Class RpcClient

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("connect", async (event) => {
    console.log("Connected to", rpc.url);
    await rpc.subscribeDaaScore();
});

rpc.addEventListener("disconnect", (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("connect", 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

constructor

Properties

encoding isConnected nodeId resolver url

Methods

addEventListener addPeer ban clearEventListener connect disconnect estimateNetworkHashesPerSecond free getBalanceByAddress getBalancesByAddresses getBlock getBlockCount getBlockDagInfo getBlockTemplate getBlocks getCoinSupply getConnectedPeerInfo getConnections getCurrentBlockColor getCurrentNetwork getDaaScoreTimestampEstimate getFeeEstimate getFeeEstimateExperimental getHeaders getInfo getMempoolEntries getMempoolEntriesByAddresses getMempoolEntry getMetrics getPeerAddresses getServerInfo getSink getSinkBlueScore getSubnetwork getSyncStatus getUtxosByAddresses getVirtualChainFromBlock ping removeAllEventListeners removeEventListener resolveFinalityConflict setNetworkId setResolver shutdown start stop submitBlock submitTransaction submitTransactionReplacement subscribeBlockAdded subscribeFinalityConflict subscribeFinalityConflictResolved subscribeNewBlockTemplate subscribePruningPointUtxoSetOverride subscribeSinkBlueScoreChanged subscribeUtxosChanged subscribeVirtualChainChanged subscribeVirtualDaaScoreChanged toJSON toString triggerAbort unban unsubscribeBlockAdded unsubscribeFinalityConflict unsubscribeFinalityConflictResolved unsubscribeNewBlockTemplate unsubscribePruningPointUtxoSetOverride unsubscribeSinkBlueScoreChanged unsubscribeUtxosChanged unsubscribeVirtualChainChanged unsubscribeVirtualDaaScoreChanged defaultPort parseUrl

Constructors

constructor

Properties

Readonly encoding

encoding: string

The current protocol encoding.

Readonly isConnected

isConnected: boolean

The current connection status of the RPC client.

Readonly nodeId

nodeId: string

Optional: Resolver node id.

Readonly resolver

resolver: Resolver

Current rpc resolver

Readonly url

url: string

The current URL of the RPC client.

Methods

addEventListener

  • addEventListener(callback): void

  • Parameters

    Returns void

  • addEventListener<M>(event, callback?): any

  • Type Parameters

    Parameters

    • event: M
    • Optional callback: ((eventData) => void)
        • (eventData): void

        • Parameters

          Returns void

    Returns any

addPeer

ban

  • ban(request): Promise<IBanResponse>

  • 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.

clearEventListener

  • clearEventListener(callback): void

  • Unregister a single event listener callback from all events.

    Parameters

    Returns void

connect

  • connect(args?): Promise<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

  • disconnect(): Promise<void>

  • Disconnect from the Kaspa RPC server.

    Returns Promise<void>

estimateNetworkHashesPerSecond

free

  • free(): void

  • Returns void

getBalanceByAddress

getBalancesByAddresses

getBlock

getBlockCount

getBlockDagInfo

  • getBlockDagInfo(request?): Promise<IGetBlockDagInfoResponse>

  • Provides information about the Directed Acyclic Graph (DAG) structure of the Kaspa BlockDAG. Returned information: Number of blocks in the DAG, number of tips in the DAG, hash of the selected parent block, difficulty of the selected parent block, selected parent block blue score, selected parent block time.

    Parameters

    Returns Promise<IGetBlockDagInfoResponse>

    See

    IGetBlockDagInfoRequest, IGetBlockDagInfoResponse

    Throws

    string on an RPC error or a server-side error.

getBlockTemplate

getBlocks

getCoinSupply

getConnectedPeerInfo

getConnections

getCurrentBlockColor

getCurrentNetwork

getDaaScoreTimestampEstimate

getFeeEstimate

getFeeEstimateExperimental

getHeaders

getInfo

getMempoolEntries

getMempoolEntriesByAddresses

getMempoolEntry

getMetrics

getPeerAddresses

getServerInfo

getSink

  • getSink(request?): Promise<IGetSinkResponse>

  • Retrieves the current sink block, which is the block with the highest cumulative difficulty in the Kaspa BlockDAG. Returned information: Sink block hash, sink block height.

    Parameters

    Returns Promise<IGetSinkResponse>

    See

    IGetSinkRequest, IGetSinkResponse

    Throws

    string on an RPC error or a server-side error.

getSinkBlueScore

getSubnetwork

getSyncStatus

getUtxosByAddresses

getVirtualChainFromBlock

ping

removeAllEventListeners

  • removeAllEventListeners(): void

  • Unregister all notification callbacks for all events.

    Returns void

removeEventListener

  • removeEventListener(event, callback?): 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

    See

    RpcClient.addEventListener

resolveFinalityConflict

setNetworkId

  • setNetworkId(network_id): void

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

    Parameters

    Returns void

setResolver

  • setResolver(resolver): void

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

    Parameters

    Returns void

shutdown

start

  • start(): Promise<void>

  • Start background RPC services (automatically started when invoking RpcClient.connect).

    Returns Promise<void>

stop

  • stop(): Promise<void>

  • Stop background RPC services (automatically stopped when invoking RpcClient.disconnect).

    Returns Promise<void>

submitBlock

submitTransaction

submitTransactionReplacement

subscribeBlockAdded

  • subscribeBlockAdded(): Promise<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>

subscribeFinalityConflict

  • subscribeFinalityConflict(): 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>

subscribeFinalityConflictResolved

  • subscribeFinalityConflictResolved(): 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>

subscribeNewBlockTemplate

  • subscribeNewBlockTemplate(): 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>

subscribePruningPointUtxoSetOverride

  • subscribePruningPointUtxoSetOverride(): 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>

subscribeSinkBlueScoreChanged

  • subscribeSinkBlueScoreChanged(): 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>

subscribeUtxosChanged

  • subscribeUtxosChanged(addresses): 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>

subscribeVirtualChainChanged

  • subscribeVirtualChainChanged(include_accepted_transaction_ids): 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>

subscribeVirtualDaaScoreChanged

  • subscribeVirtualDaaScoreChanged(): 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>

toJSON

  • toJSON(): Object
    • Return copy of self without private attributes.

    Returns Object

toString

  • toString(): string

  • Return stringified version of self.

    Returns string

triggerAbort

  • triggerAbort(): void

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

    Returns void

unban

  • unban(request): Promise<IUnbanResponse>

  • Unbans a previously banned peer, allowing it to connect to the Kaspa node again. Returned information: None.

    Parameters

    Returns Promise<IUnbanResponse>

    See

    IUnbanRequest, IUnbanResponse

    Throws

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

unsubscribeBlockAdded

  • unsubscribeBlockAdded(): Promise<void>

  • Returns Promise<void>

unsubscribeFinalityConflict

  • unsubscribeFinalityConflict(): Promise<void>

  • Returns Promise<void>

unsubscribeFinalityConflictResolved

  • unsubscribeFinalityConflictResolved(): Promise<void>

  • Returns Promise<void>

unsubscribeNewBlockTemplate

  • unsubscribeNewBlockTemplate(): Promise<void>

  • Returns Promise<void>

unsubscribePruningPointUtxoSetOverride

  • unsubscribePruningPointUtxoSetOverride(): Promise<void>

  • Returns Promise<void>

unsubscribeSinkBlueScoreChanged

  • unsubscribeSinkBlueScoreChanged(): Promise<void>

  • Returns Promise<void>

unsubscribeUtxosChanged

  • unsubscribeUtxosChanged(addresses): Promise<void>

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

    Parameters

    Returns Promise<void>

unsubscribeVirtualChainChanged

  • unsubscribeVirtualChainChanged(include_accepted_transaction_ids): 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>

unsubscribeVirtualDaaScoreChanged

  • unsubscribeVirtualDaaScoreChanged(): 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>

Static defaultPort

  • defaultPort(encoding, network): number

  • Parameters

    Returns number

Static parseUrl

  • parseUrl(url, encoding, network): string

  • 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

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc