Create a new RPC client with optional Encoding and a url
.
Optional
config: IRpcConfigIRpcConfig interface for more details.
Readonly
encodingThe current protocol encoding.
Readonly
isThe current connection status of the RPC client.
Readonly
nodeOptional: Resolver node id.
Readonly
providerOptional: public node provider name.
Readonly
providerOptional: public node provider URL.
Readonly
resolverCurrent rpc resolver
Readonly
urlThe current URL of the RPC client.
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();
Optional
callback: RpcEventCallbackAdds a peer to the Kaspa node's list of known peers. Returned information: None.
IAddPeerRequest, IAddPeerResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Bans a peer from connecting to the Kaspa node for a specified duration. Returned information: None.
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Unregister a single event listener callback from all events.
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.
Optional
args: IConnectOptionsIConnectOptions interface for more details.
Estimates the network's current hash rate in hashes per second. Returned information: Estimated network hashes per second.
IEstimateNetworkHashesPerSecondRequest, IEstimateNetworkHashesPerSecondResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves the balance of a specific address in the Kaspa BlockDAG. Returned information: Balance of the address.
IGetBalanceByAddressRequest, IGetBalanceByAddressResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves balances for multiple addresses in the Kaspa BlockDAG. Returned information: Balances of the addresses.
IGetBalancesByAddressesRequest, IGetBalancesByAddressesResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves a specific block from the Kaspa BlockDAG. Returned information: Block information.
IGetBlockRequest, IGetBlockResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves the current number of blocks in the Kaspa BlockDAG. This is not a block count, not a "block height" and can not be used for transaction validation. Returned information: Current block count.
Optional
request: IGetBlockCountRequestIGetBlockCountRequest, IGetBlockCountResponse
string
on an RPC error or a server-side error.
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.
Optional
request: IGetBlockDagInfoRequestIGetBlockDagInfoRequest, IGetBlockDagInfoResponse
string
on an RPC error or a server-side error.
Generates a new block template for mining. Returned information: Block template information.
IGetBlockTemplateRequest, IGetBlockTemplateResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves multiple blocks from the Kaspa BlockDAG. Returned information: List of block information.
IGetBlocksRequest, IGetBlocksResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Returns the total current coin supply of Kaspa network. Returned information: Total coin supply.
Optional
request: IGetCoinSupplyRequestIGetCoinSupplyRequest, IGetCoinSupplyResponse
string
on an RPC error or a server-side error.
Retrieves information about the peers connected to the Kaspa node. Returned information: Peer ID, IP address and port, connection status, protocol version.
Optional
request: IGetConnectedPeerInfoRequestIGetConnectedPeerInfoRequest, IGetConnectedPeerInfoResponse
string
on an RPC error or a server-side error.
Retrieves the current network configuration. Returned information: Current network configuration.
IGetCurrentNetworkRequest, IGetCurrentNetworkResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves the estimated DAA (Difficulty Adjustment Algorithm) score timestamp estimate. Returned information: DAA score timestamp estimate.
IGetDaaScoreTimestampEstimateRequest, IGetDaaScoreTimestampEstimateResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves block headers from the Kaspa BlockDAG. Returned information: List of block headers.
IGetHeadersRequest, IGetHeadersResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves general information about the Kaspa node. Returned information: Version of the Kaspa node, protocol version, network identifier. This call is primarily used by gRPC clients. For wRPC clients, use RpcClient.getServerInfo.
Optional
request: IGetInfoRequestRetrieves mempool entries from the Kaspa node's mempool. Returned information: List of mempool entries.
IGetMempoolEntriesRequest, IGetMempoolEntriesResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves mempool entries associated with specific addresses. Returned information: List of mempool entries.
IGetMempoolEntriesByAddressesRequest, IGetMempoolEntriesByAddressesResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves a specific mempool entry by transaction ID. Returned information: Mempool entry information.
IGetMempoolEntryRequest, IGetMempoolEntryResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves various metrics and statistics related to the performance and status of the Kaspa node. Returned information: Memory usage, CPU usage, network activity.
Optional
request: IGetMetricsRequestProvides a list of addresses of known peers in the Kaspa network that the node can potentially connect to. Returned information: List of peer addresses.
Optional
request: IGetPeerAddressesRequestIGetPeerAddressesRequest, IGetPeerAddressesResponse
string
on an RPC error or a server-side error.
Retrieves information about the Kaspa server. Returned information: Version of the Kaspa server, protocol version, network identifier.
Optional
request: IGetServerInfoRequestIGetServerInfoRequest, IGetServerInfoResponse
string
on an RPC error or a server-side error.
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.
Optional
request: IGetSinkRequestReturns the blue score of the current sink block, indicating the total amount of work that has been done on the main chain leading up to that block. Returned information: Blue score of the sink block.
Optional
request: IGetSinkBlueScoreRequestIGetSinkBlueScoreRequest, IGetSinkBlueScoreResponse
string
on an RPC error or a server-side error.
Retrieves information about a subnetwork in the Kaspa BlockDAG. Returned information: Subnetwork information.
IGetSubnetworkRequest, IGetSubnetworkResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Obtains basic information about the synchronization status of the Kaspa node. Returned information: Syncing status.
Optional
request: IGetSyncStatusRequestIGetSyncStatusRequest, IGetSyncStatusResponse
string
on an RPC error or a server-side error.
Retrieves unspent transaction outputs (UTXOs) associated with specific addresses. Returned information: List of UTXOs.
IGetUtxosByAddressesRequest, IGetUtxosByAddressesResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Retrieves the virtual chain corresponding to a specified block hash. Returned information: Virtual chain information.
IGetVirtualChainFromBlockRequest, IGetVirtualChainFromBlockResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Tests the connection and responsiveness of a Kaspa node. Returned information: None.
Optional
request: IPingRequestUnregister 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.
Optional
callback: RpcEventCallbackResolves a finality conflict in the Kaspa BlockDAG. Returned information: None.
IResolveFinalityConflictRequest, IResolveFinalityConflictResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Set the resolver for the RPC client. This setting will take effect on the next connection.
Set the network id for the RPC client. This setting will take effect on the next connection.
Gracefully shuts down the Kaspa node. Returned information: None.
Optional
request: IShutdownRequestSubmits a block to the Kaspa network. Returned information: None.
ISubmitBlockRequest, ISubmitBlockResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Submits a transaction to the Kaspa network. Returned information: None.
ISubmitTransactionRequest, ISubmitTransactionResponse
string
on an RPC error, a server-side error or when supplying incorrect arguments.
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.
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.
Unbans a previously banned peer, allowing it to connect to the Kaspa node again. Returned information: None.
string
on an RPC error, a server-side error or when supplying incorrect arguments.
Unsubscribe from UTXOs changed notification event for a specific set of addresses.
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.
Static
defaultStatic
parseConstructs an WebSocket RPC URL given the partial URL or an IP, RPC encoding and a network type.
url
- Partial URL or an IP addressencoding
- RPC encodingnetwork_type
- Network typeGenerated using TypeDoc
Kaspa RPC client uses (wRPC) interface to connect directly with Kaspa Node. wRPC supports two types of encodings:
borsh
(binary, default) andjson
.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
Connecting to a Kaspa Node directly
Example usage
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:
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.