Kaspa RPC client uses (wRPC) interface to connect directly with Kaspa Node. wRPC supports two types of encodings: borsh (binary, default) and json.

There are two ways to connect: Directly to any Kaspa Node or to a community-maintained public node infrastructure using the Resolver class.

Connecting to a public node using a resolver

let rpc = new RpcClient({
resolver : new Resolver(),
networkId : "mainnet",
});

await rpc.connect();

Connecting to a Kaspa Node directly

let rpc = new RpcClient({
// if port is not provided it will default
// to the default port for the networkId
url : "127.0.0.1",
networkId : "mainnet",
});

Example usage


// Create a new RPC client with a URL
let rpc = new RpcClient({ url : "wss://<node-wrpc-address>" });

// Create a new RPC client with a resolver
// (networkId is required when using a resolver)
let rpc = new RpcClient({
resolver : new Resolver(),
networkId : "mainnet",
});

rpc.addEventListener("open", async (event) => {
console.log("Connected to", rpc.url);
await rpc.subscribeDaaScore();
});

rpc.addEventListener("close", (event) => {
console.log("Disconnected from", rpc.url);
});

try {
await rpc.connect();
} catch(err) {
console.log("Error connecting:", err);
}

You can register event listeners to receive notifications from the RPC client using RpcClient.addEventListener and RpcClient.removeEventListener functions.

IMPORTANT: If RPC is disconnected, upon reconnection you do not need to re-register event listeners, but your have to re-subscribe for Kaspa node notifications:

rpc.addEventListener("open", async (event) => {
console.log("Connected to", rpc.url);
// re-subscribe each time we connect
await rpc.subscribeDaaScore();
// ... perform wallet address subscriptions
});

If using NodeJS, it is important that RpcClient.disconnect is called before the process exits to ensure that the WebSocket connection is properly closed. Failure to do this will prevent the process from exiting.

Constructors

Properties

encoding: string

The current protocol encoding.

isConnected: boolean

The current connection status of the RPC client.

nodeId: string

Optional: Resolver node id.

providerName: string

Optional: public node provider name.

providerUrl: string

Optional: public node provider URL.

resolver: Resolver

Current rpc resolver

url: string

The current URL of the RPC client.

Methods

  • Register an event listener callback.

    Registers a callback function to be executed when a specific event occurs. The callback function will receive an RpcEvent object with the event type and data.

    RPC Subscriptions vs Event Listeners

    Subscriptions are used to receive notifications from the RPC client. Event listeners are client-side application registrations that are triggered when notifications are received.

    If node is disconnected, upon reconnection you do not need to re-register event listeners, however, you have to re-subscribe for Kaspa node notifications. As such, it is recommended to register event listeners when the RPC open event is received.

    rpc.addEventListener("open", async (event) => {
    console.log("Connected to", rpc.url);
    await rpc.subscribeDaaScore();
    // ... perform wallet address subscriptions
    });

    Multiple events and listeners

    addEventListener can be used to register multiple event listeners for the same event as well as the same event listener for multiple events.

    // Registering a single event listener for multiple events:
    rpc.addEventListener(["open", "close"], (event) => {
    console.log(event);
    });

    // Registering event listener for all events:
    rpc.addEventListener("*", (event) => {
    console.log(event);
    });
    // or without supplying the event type
    rpc.addEventListener((event) => {
    console.log(event);
    });

    // Registering multiple event listeners for the same event:
    rpc.addEventListener("open", (event) => { // first listener
    console.log(event);
    });
    rpc.addEventListener("open", (event) => { // second listener
    console.log(event);
    });

    Use of context objects

    You can also register an event with a context object. When the event is triggered, the handleEvent method of the context object will be called while this value will be set to the context object.

    // Registering events with a context object:

    const context = {
    someProperty: "someValue",
    handleEvent: (event) => {
    // the following will log "someValue"
    console.log(this.someProperty);
    console.log(event);
    }
    };
    rpc.addEventListener(["open","close"], context);

    General use examples

    In TypeScript you can use RpcEventType enum (such as RpcEventType.Open) or string (such as "open") to register event listeners. In JavaScript you can only use string.

    // Example usage (TypeScript):

    rpc.addEventListener(RpcEventType.Open, (event) => {
    console.log("Connected to", rpc.url);
    });

    rpc.addEventListener(RpcEventType.VirtualDaaScoreChanged, (event) => {
    console.log(event.type,event.data);
    });
    await rpc.subscribeDaaScore();

    rpc.addEventListener(RpcEventType.BlockAdded, (event) => {
    console.log(event.type,event.data);
    });
    await rpc.subscribeBlockAdded();

    // Example usage (JavaScript):

    rpc.addEventListener("virtual-daa-score-changed", (event) => {
    console.log(event.type,event.data);
    });

    await rpc.subscribeDaaScore();
    rpc.addEventListener("block-added", (event) => {
    console.log(event.type,event.data);
    });
    await rpc.subscribeBlockAdded();

    Parameters

    Returns void

    See

  • Bans a peer from connecting to the Kaspa node for a specified duration. Returned information: None.

    Parameters

    Returns Promise<IBanResponse>

    See

    IBanRequest, IBanResponse

    Throws

    string on an RPC error, a server-side error or when supplying incorrect arguments.

  • Unregister a single event listener callback from all events.

    Parameters

    Returns void

  • Connect to the Kaspa RPC server. This function starts a background task that connects and reconnects to the server if the connection is terminated. Use disconnect() to terminate the connection.

    Parameters

    Returns Promise<void>

    See

    IConnectOptions interface for more details.

  • Disconnect from the Kaspa RPC server.

    Returns Promise<void>

  • Returns void

  • Unregister all notification callbacks for all events.

    Returns void

  • Unregister an event listener. This function will remove the callback for the specified event. If the callback is not supplied, all callbacks will be removed for the specified event.

    Parameters

    Returns void

  • Set the resolver for the RPC client. This setting will take effect on the next connection.

    Parameters

    Returns void

  • Set the network id for the RPC client. This setting will take effect on the next connection.

    Parameters

    Returns void

  • Manage subscription for a block added notification event. Block added notification event is produced when a new block is added to the Kaspa BlockDAG.

    Returns Promise<void>

  • Manage subscription for a finality conflict notification event. Finality conflict notification event is produced when a finality conflict occurs in the Kaspa BlockDAG.

    Returns Promise<void>

  • Manage subscription for a finality conflict resolved notification event. Finality conflict resolved notification event is produced when a finality conflict in the Kaspa BlockDAG is resolved.

    Returns Promise<void>

  • Manage subscription for a new block template notification event. New block template notification event is produced when a new block template is generated for mining in the Kaspa BlockDAG.

    Returns Promise<void>

  • Manage subscription for a pruning point UTXO set override notification event. Pruning point UTXO set override notification event is produced when the UTXO set override for the pruning point changes in the Kaspa BlockDAG.

    Returns Promise<void>

  • Manage subscription for a sink blue score changed notification event. Sink blue score changed notification event is produced when the blue score of the sink block changes in the Kaspa BlockDAG.

    Returns Promise<void>

  • Subscribe for a UTXOs changed notification event. UTXOs changed notification event is produced when the set of unspent transaction outputs (UTXOs) changes in the Kaspa BlockDAG. The event notification will be scoped to the provided list of addresses.

    Parameters

    Returns Promise<void>

  • Manage subscription for a virtual chain changed notification event. Virtual chain changed notification event is produced when the virtual chain changes in the Kaspa BlockDAG.

    Parameters

    • include_accepted_transaction_ids: boolean

    Returns Promise<void>

  • Manage subscription for a virtual DAA score changed notification event. Virtual DAA score changed notification event is produced when the virtual Difficulty Adjustment Algorithm (DAA) score changes in the Kaspa BlockDAG.

    Returns Promise<void>

    • Return copy of self without private attributes.

    Returns Object

  • Return stringified version of self.

    Returns string

  • Triggers a disconnection on the underlying WebSocket. This is intended for debug purposes only. Can be used to test application reconnection logic.

    Returns void

  • Returns Promise<void>

  • Returns Promise<void>

  • Returns Promise<void>

  • Returns Promise<void>

  • Returns Promise<void>

  • Returns Promise<void>

  • Unsubscribe from UTXOs changed notification event for a specific set of addresses.

    Parameters

    Returns Promise<void>

  • Manage subscription for a virtual chain changed notification event. Virtual chain changed notification event is produced when the virtual chain changes in the Kaspa BlockDAG.

    Parameters

    • include_accepted_transaction_ids: boolean

    Returns Promise<void>

  • Manage subscription for a virtual DAA score changed notification event. Virtual DAA score changed notification event is produced when the virtual Difficulty Adjustment Algorithm (DAA) score changes in the Kaspa BlockDAG.

    Returns Promise<void>

  • Constructs an WebSocket RPC URL given the partial URL or an IP, RPC encoding and a network type.

    Arguments

    • url - Partial URL or an IP address
    • encoding - RPC encoding
    • network_type - Network type

    Parameters

    Returns string

Generated using TypeDoc