Neptune Cash JS

Neptune Cash JS is a community-made wrapper for neptune-core JSON RPC API requests. Currently, it supports first 20 implemented API methods in both Neptune Cash and Neptune Privacy. Licensed under Apache-2.0.

Important

To see README.md or source code of your version please checkout to the right tag. The npm packages already contain the right data.

How to use it?

I assume, that you have already used libraries like ethers or viem and know how JSON-RPC works. Also, I hope you are a little bit familiar with neptune-core.

First of all, install the library using:

npm install neptune-cash

Next, create a client object:

import {NeptuneClient} from "neptune-cash"

const neptune = new NeptuneClient()

Note, that you aren't connect with the server immediately. The connection happens every time when you invoke methods.

The constructor takes two parameters:

1. hostName - host name of the RPC server, default localhost
2. port - port of the RPC server, default 9797 (notice that the default port for the XNT is 9897)

To create your own server check Configuring RPC server. If you don't like to, you can use mine - hostName: 217.160.149.196 with default port 🙂

Methods

The NeptuneClient class provides two kinds of async methods:

1. with safe prefix - they return error (if occurred) as a field of an object:

   { success: true, data: T } | { success: false, error: JSONRPCErrorType | RequestErrorType }

   In this case I was inspired by zod. See src/types/internal.ts for more details.

2. without safe prefix - these methods can throw instance of class extending Error if error occurred.

Error classes

The library provides following classes for error handling (no other errors can be thrown):

1. RequestError - extends Error - responsible for network errors, e.g. invalid port or no internet connection.
2. JSONRPCError - extends Error, responsible for errors from RPC responses. Also parent class for two following:
   • MethodNotFoundError - thrown when your server doesn't support a given method.
   • InvalidParamsError - thrown when params you provided to method are invalid. Types of method arguments aren't perfect so this error can occur often.

Configuring RPC server

Neptune Cash

1. Download neptune-core 0.5.0 from here.

2. Sync your node with the network:

   neptune-core --peer <address>

   To get currently working peers you can search the internet or ask someone on the Neptune Cash Telegram. You can use many --peer with other addresses.

3. Run the server:

   neptune-core --listen-rpc --peer <address> --rpc-modules "chain,node,archival"

   This command will start the server with all modules (and methods) supported by the library.

Neptune Privacy (XNT)

1. Download xnt-core 0.1.0 from here.

2. Sync your node with the network:

   xnt-core --peer <address>

   To get currently working peers you can search the internet or ask someone on the Neptune Privacy Telegram. You can use many --peer with other addresses.

3. Run the server:

   xnt-core --listen-rpc --peer <address> --rpc-modules "chain,node,archival"

   This command will start the server with all modules (and methods) supported by the library.

Using my RPC

• Neptune Cash

  const neptune = new NeptuneClient("217.160.149.196", DEFAULT_NEPTUNE_CASH_PORT);

• Neptune Privacy (XNT)

  const neptune = new NeptuneClient("217.160.149.196", DEFAULT_XNT_PORT);

Remember to provide the right imports!

Specification

• neptune-core 0.5.0 modules: chain, node, archival
• xnt-core 0.1.0 modules: chain, node, archival

Some of the newer features may not work.

Tech stack

The whole library is based on the ofetch. Also, I've used ts-node as a dev dependency.

Contact

If you have any questions/suggestions feel free to message me on Telegram, or Discord: @comradecobweb. You can also open an issue!

Useful resources

API Docs
Kaffin's PR
message.rs
https.rs
ops.rs
XNT source code