Protocol Documentation
Table of Contents
Top
rpc.proto
RPC-related types. Request messages, response messages, and dependant types.
Clients are expected to build RequestMessages and wrap them in KaspadMessage. (see messages.proto)
Having received a RequestMessage, (wrapped in a KaspadMessage) the RPC server will respond with a
ResponseMessage (likewise wrapped in a KaspadMessage) respective to the original RequestMessage.
IMPORTANT: This API is a work in progress and is subject to break between versions.
RPCError
RPCError represents a generic non-internal error.
Receivers of any ResponseMessage are expected to check whether its error field is not null.
Field |
Type |
Label |
Description |
message |
string |
|
|
RpcBlock
RpcBlockLevelParents
Field |
Type |
Label |
Description |
parentHashes |
string |
repeated |
|
RpcBlockVerboseData
RpcTransaction
RpcTransactionInput
RpcScriptPublicKey
Field |
Type |
Label |
Description |
version |
uint32 |
|
|
scriptPublicKey |
string |
|
|
RpcTransactionOutput
RpcOutpoint
Field |
Type |
Label |
Description |
transactionId |
string |
|
|
index |
uint32 |
|
|
RpcUtxoEntry
RpcTransactionVerboseData
RpcTransactionInputVerboseData
RpcTransactionOutputVerboseData
Field |
Type |
Label |
Description |
scriptPublicKeyType |
string |
|
|
scriptPublicKeyAddress |
string |
|
|
GetCurrentNetworkRequestMessage
GetCurrentNetworkRequestMessage requests the network kaspad is currently running against.
Possible networks are: Mainnet, Testnet, Simnet, Devnet
GetCurrentNetworkResponseMessage
SubmitBlockRequestMessage
SubmitBlockRequestMessage requests to submit a block into the DAG.
Blocks are generally expected to have been generated using the getBlockTemplate call.
See: GetBlockTemplateRequestMessage
Field |
Type |
Label |
Description |
block |
RpcBlock |
|
|
allowNonDAABlocks |
bool |
|
|
SubmitBlockResponseMessage
GetBlockTemplateRequestMessage
GetBlockTemplateRequestMessage requests a current block template.
Callers are expected to solve the block template and submit it using the submitBlock call
See: SubmitBlockRequestMessage
Field |
Type |
Label |
Description |
payAddress |
string |
|
Which kaspa address should the coinbase block reward transaction pay into |
extraData |
string |
|
|
GetBlockTemplateResponseMessage
Field |
Type |
Label |
Description |
block |
RpcBlock |
|
|
isSynced |
bool |
|
Whether kaspad thinks that it's synced. Callers are discouraged (but not forbidden) from solving blocks when kaspad is not synced. That is because when kaspad isn't in sync with the rest of the network there's a high chance the block will never be accepted, thus the solving effort would have been wasted. |
error |
RPCError |
|
|
NotifyBlockAddedRequestMessage
NotifyBlockAddedRequestMessage registers this connection for blockAdded notifications.
See: BlockAddedNotificationMessage
NotifyBlockAddedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
BlockAddedNotificationMessage
BlockAddedNotificationMessage is sent whenever a blocks has been added (NOT accepted)
into the DAG.
See: NotifyBlockAddedRequestMessage
Field |
Type |
Label |
Description |
block |
RpcBlock |
|
|
GetPeerAddressesRequestMessage
GetPeerAddressesRequestMessage requests the list of known kaspad addresses in the
current network. (mainnet, testnet, etc.)
GetPeerAddressesResponseMessage
GetPeerAddressesKnownAddressMessage
Field |
Type |
Label |
Description |
Addr |
string |
|
|
GetSelectedTipHashRequestMessage
GetSelectedTipHashRequestMessage requests the hash of the current virtual's
selected parent.
GetSelectedTipHashResponseMessage
GetMempoolEntryRequestMessage
GetMempoolEntryRequestMessage requests information about a specific transaction
in the mempool.
Field |
Type |
Label |
Description |
txId |
string |
|
The transaction's TransactionID. |
includeOrphanPool |
bool |
|
|
filterTransactionPool |
bool |
|
|
GetMempoolEntryResponseMessage
GetMempoolEntriesRequestMessage
GetMempoolEntriesRequestMessage requests information about all the transactions
currently in the mempool.
Field |
Type |
Label |
Description |
includeOrphanPool |
bool |
|
|
filterTransactionPool |
bool |
|
|
GetMempoolEntriesResponseMessage
MempoolEntry
GetConnectedPeerInfoRequestMessage
GetConnectedPeerInfoRequestMessage requests information about all the p2p peers
currently connected to this kaspad.
GetConnectedPeerInfoResponseMessage
GetConnectedPeerInfoMessage
Field |
Type |
Label |
Description |
id |
string |
|
|
address |
string |
|
|
lastPingDuration |
int64 |
|
How long did the last ping/pong exchange take |
isOutbound |
bool |
|
Whether this kaspad initiated the connection |
timeOffset |
int64 |
|
|
userAgent |
string |
|
|
advertisedProtocolVersion |
uint32 |
|
The protocol version that this peer claims to support |
timeConnected |
int64 |
|
The timestamp of when this peer connected to this kaspad |
isIbdPeer |
bool |
|
Whether this peer is the IBD peer (if IBD is running) |
AddPeerRequestMessage
AddPeerRequestMessage adds a peer to kaspad's outgoing connection list.
This will, in most cases, result in kaspad connecting to said peer.
Field |
Type |
Label |
Description |
address |
string |
|
|
isPermanent |
bool |
|
Whether to keep attempting to connect to this peer after disconnection |
AddPeerResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
SubmitTransactionRequestMessage
SubmitTransactionRequestMessage submits a transaction to the mempool
SubmitTransactionResponseMessage
Field |
Type |
Label |
Description |
transactionId |
string |
|
The transaction ID of the submitted transaction |
error |
RPCError |
|
|
NotifyVirtualSelectedParentChainChangedRequestMessage
NotifyVirtualSelectedParentChainChangedRequestMessage registers this connection for virtualSelectedParentChainChanged notifications.
See: VirtualSelectedParentChainChangedNotificationMessage
Field |
Type |
Label |
Description |
includeAcceptedTransactionIds |
bool |
|
|
NotifyVirtualSelectedParentChainChangedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
VirtualSelectedParentChainChangedNotificationMessage
VirtualSelectedParentChainChangedNotificationMessage is sent whenever the DAG's selected parent
chain had changed.
See: NotifyVirtualSelectedParentChainChangedRequestMessage
Field |
Type |
Label |
Description |
removedChainBlockHashes |
string |
repeated |
The chain blocks that were removed, in high-to-low order |
addedChainBlockHashes |
string |
repeated |
The chain blocks that were added, in low-to-high order |
acceptedTransactionIds |
AcceptedTransactionIds |
repeated |
Will be filled only if includeAcceptedTransactionIds = true in the notify request. |
GetBlockRequestMessage
GetBlockRequestMessage requests information about a specific block
Field |
Type |
Label |
Description |
hash |
string |
|
The hash of the requested block |
includeTransactions |
bool |
|
Whether to include transaction data in the response |
GetBlockResponseMessage
GetSubnetworkRequestMessage
GetSubnetworkRequestMessage requests information about a specific subnetwork
Currently unimplemented
Field |
Type |
Label |
Description |
subnetworkId |
string |
|
|
GetSubnetworkResponseMessage
GetVirtualSelectedParentChainFromBlockRequestMessage
GetVirtualSelectedParentChainFromBlockRequestMessage requests the virtual selected
parent chain from some startHash to this kaspad's current virtual
Field |
Type |
Label |
Description |
startHash |
string |
|
|
includeAcceptedTransactionIds |
bool |
|
|
AcceptedTransactionIds
Field |
Type |
Label |
Description |
acceptingBlockHash |
string |
|
|
acceptedTransactionIds |
string |
repeated |
|
GetVirtualSelectedParentChainFromBlockResponseMessage
Field |
Type |
Label |
Description |
removedChainBlockHashes |
string |
repeated |
The chain blocks that were removed, in high-to-low order |
addedChainBlockHashes |
string |
repeated |
The chain blocks that were added, in low-to-high order |
acceptedTransactionIds |
AcceptedTransactionIds |
repeated |
The transactions accepted by each block in addedChainBlockHashes. Will be filled only if includeAcceptedTransactionIds = true in the request. |
error |
RPCError |
|
|
GetBlocksRequestMessage
GetBlocksRequestMessage requests blocks between a certain block lowHash up to this
kaspad's current virtual.
Field |
Type |
Label |
Description |
lowHash |
string |
|
|
includeBlocks |
bool |
|
|
includeTransactions |
bool |
|
|
GetBlocksResponseMessage
GetBlockCountRequestMessage
GetBlockCountRequestMessage requests the current number of blocks in this kaspad.
Note that this number may decrease as pruning occurs.
GetBlockCountResponseMessage
GetBlockDagInfoRequestMessage
GetBlockDagInfoRequestMessage requests general information about the current state
of this kaspad's DAG.
GetBlockDagInfoResponseMessage
ResolveFinalityConflictRequestMessage
Field |
Type |
Label |
Description |
finalityBlockHash |
string |
|
|
ResolveFinalityConflictResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
NotifyFinalityConflictsRequestMessage
NotifyFinalityConflictsResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
FinalityConflictNotificationMessage
Field |
Type |
Label |
Description |
violatingBlockHash |
string |
|
|
FinalityConflictResolvedNotificationMessage
Field |
Type |
Label |
Description |
finalityBlockHash |
string |
|
|
ShutDownRequestMessage
ShutDownRequestMessage shuts down this kaspad.
ShutDownResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
GetHeadersRequestMessage requests headers between the given startHash and the
current virtual, up to the given limit.
NotifyUtxosChangedRequestMessage
NotifyUtxosChangedRequestMessage registers this connection for utxoChanged notifications
for the given addresses.
This call is only available when this kaspad was started with --utxoindex
See: UtxosChangedNotificationMessage
Field |
Type |
Label |
Description |
addresses |
string |
repeated |
Leave empty to get all updates |
NotifyUtxosChangedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
UtxosChangedNotificationMessage
UtxosChangedNotificationMessage is sent whenever the UTXO index had been updated.
See: NotifyUtxosChangedRequestMessage
UtxosByAddressesEntry
StopNotifyingUtxosChangedRequestMessage
StopNotifyingUtxosChangedRequestMessage unregisters this connection for utxoChanged notifications
for the given addresses.
This call is only available when this kaspad was started with --utxoindex
See: UtxosChangedNotificationMessage
Field |
Type |
Label |
Description |
addresses |
string |
repeated |
|
StopNotifyingUtxosChangedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
GetUtxosByAddressesRequestMessage
GetUtxosByAddressesRequestMessage requests all current UTXOs for the given kaspad addresses
This call is only available when this kaspad was started with --utxoindex
Field |
Type |
Label |
Description |
addresses |
string |
repeated |
|
GetUtxosByAddressesResponseMessage
GetBalanceByAddressRequestMessage
GetBalanceByAddressRequest returns the total balance in unspent transactions towards a given address
This call is only available when this kaspad was started with --utxoindex
Field |
Type |
Label |
Description |
address |
string |
|
|
GetBalanceByAddressResponseMessage
GetBalancesByAddressesRequestMessage
Field |
Type |
Label |
Description |
addresses |
string |
repeated |
|
BalancesByAddressEntry
GetBalancesByAddressesResponseMessage
GetVirtualSelectedParentBlueScoreRequestMessage
GetVirtualSelectedParentBlueScoreRequestMessage requests the blue score of the current selected parent
of the virtual block.
GetVirtualSelectedParentBlueScoreResponseMessage
NotifyVirtualSelectedParentBlueScoreChangedRequestMessage
NotifyVirtualSelectedParentBlueScoreChangedRequestMessage registers this connection for
virtualSelectedParentBlueScoreChanged notifications.
See: VirtualSelectedParentBlueScoreChangedNotificationMessage
NotifyVirtualSelectedParentBlueScoreChangedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
VirtualSelectedParentBlueScoreChangedNotificationMessage
VirtualSelectedParentBlueScoreChangedNotificationMessage is sent whenever the blue score
of the virtual's selected parent changes.
See NotifyVirtualSelectedParentBlueScoreChangedRequestMessage
Field |
Type |
Label |
Description |
virtualSelectedParentBlueScore |
uint64 |
|
|
NotifyVirtualDaaScoreChangedRequestMessage
NotifyVirtualDaaScoreChangedRequestMessage registers this connection for
virtualDaaScoreChanged notifications.
See: VirtualDaaScoreChangedNotificationMessage
NotifyVirtualDaaScoreChangedResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
VirtualDaaScoreChangedNotificationMessage
VirtualDaaScoreChangedNotificationMessage is sent whenever the DAA score
of the virtual changes.
See NotifyVirtualDaaScoreChangedRequestMessage
Field |
Type |
Label |
Description |
virtualDaaScore |
uint64 |
|
|
NotifyPruningPointUTXOSetOverrideRequestMessage
NotifyPruningPointUTXOSetOverrideRequestMessage registers this connection for
pruning point UTXO set override notifications.
This call is only available when this kaspad was started with --utxoindex
See: NotifyPruningPointUTXOSetOverrideResponseMessage
NotifyPruningPointUTXOSetOverrideResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
PruningPointUTXOSetOverrideNotificationMessage
PruningPointUTXOSetOverrideNotificationMessage is sent whenever the UTXO index
resets due to pruning point change via IBD.
See NotifyPruningPointUTXOSetOverrideRequestMessage
StopNotifyingPruningPointUTXOSetOverrideRequestMessage
StopNotifyingPruningPointUTXOSetOverrideRequestMessage unregisters this connection for
pruning point UTXO set override notifications.
This call is only available when this kaspad was started with --utxoindex
See: PruningPointUTXOSetOverrideNotificationMessage
StopNotifyingPruningPointUTXOSetOverrideResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
BanRequestMessage
BanRequestMessage bans the given ip.
Field |
Type |
Label |
Description |
ip |
string |
|
|
BanResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
UnbanRequestMessage
UnbanRequestMessage unbans the given ip.
Field |
Type |
Label |
Description |
ip |
string |
|
|
UnbanResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
GetInfoRequestMessage
GetInfoRequestMessage returns info about the node.
GetInfoResponseMessage
EstimateNetworkHashesPerSecondRequestMessage
Field |
Type |
Label |
Description |
windowSize |
uint32 |
|
|
startHash |
string |
|
|
EstimateNetworkHashesPerSecondResponseMessage
Field |
Type |
Label |
Description |
networkHashesPerSecond |
uint64 |
|
|
error |
RPCError |
|
|
NotifyNewBlockTemplateRequestMessage
NotifyNewBlockTemplateRequestMessage registers this connection for
NewBlockTemplate notifications.
See: NewBlockTemplateNotificationMessage
NotifyNewBlockTemplateResponseMessage
Field |
Type |
Label |
Description |
error |
RPCError |
|
|
NewBlockTemplateNotificationMessage
NewBlockTemplateNotificationMessage is sent whenever a new updated block template is
available for miners.
See NotifyNewBlockTemplateRequestMessage
MempoolEntryByAddress
GetMempoolEntriesByAddressesRequestMessage
Field |
Type |
Label |
Description |
addresses |
string |
repeated |
|
includeOrphanPool |
bool |
|
|
filterTransactionPool |
bool |
|
|
GetMempoolEntriesByAddressesResponseMessage
GetCoinSupplyRequestMessage
GetCoinSupplyResponseMessage
Field |
Type |
Label |
Description |
maxSompi |
uint64 |
|
note: this is a hard coded maxSupply, actual maxSupply is expected to deviate by upto -5%, but cannot be measured exactly. |
circulatingSompi |
uint64 |
|
|
error |
RPCError |
|
|
SubmitBlockResponseMessage.RejectReason
Name |
Number |
Description |
NONE |
0 |
|
BLOCK_INVALID |
1 |
|
IS_IN_IBD |
2 |
|
Scalar Value Types
.proto Type |
Notes |
C++ |
Java |
Python |
Go |
C# |
PHP |
Ruby |
double |
|
double |
double |
float |
float64 |
double |
float |
Float |
float |
|
float |
float |
float |
float32 |
float |
float |
Float |
int32 |
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. |
int32 |
int |
int |
int32 |
int |
integer |
Bignum or Fixnum (as required) |
int64 |
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. |
int64 |
long |
int/long |
int64 |
long |
integer/string |
Bignum |
uint32 |
Uses variable-length encoding. |
uint32 |
int |
int/long |
uint32 |
uint |
integer |
Bignum or Fixnum (as required) |
uint64 |
Uses variable-length encoding. |
uint64 |
long |
int/long |
uint64 |
ulong |
integer/string |
Bignum or Fixnum (as required) |
sint32 |
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. |
int32 |
int |
int |
int32 |
int |
integer |
Bignum or Fixnum (as required) |
sint64 |
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. |
int64 |
long |
int/long |
int64 |
long |
integer/string |
Bignum |
fixed32 |
Always four bytes. More efficient than uint32 if values are often greater than 2^28. |
uint32 |
int |
int |
uint32 |
uint |
integer |
Bignum or Fixnum (as required) |
fixed64 |
Always eight bytes. More efficient than uint64 if values are often greater than 2^56. |
uint64 |
long |
int/long |
uint64 |
ulong |
integer/string |
Bignum |
sfixed32 |
Always four bytes. |
int32 |
int |
int |
int32 |
int |
integer |
Bignum or Fixnum (as required) |
sfixed64 |
Always eight bytes. |
int64 |
long |
int/long |
int64 |
long |
integer/string |
Bignum |
bool |
|
bool |
boolean |
boolean |
bool |
bool |
boolean |
TrueClass/FalseClass |
string |
A string must always contain UTF-8 encoded or 7-bit ASCII text. |
string |
String |
str/unicode |
string |
string |
string |
String (UTF-8) |
bytes |
May contain any arbitrary sequence of bytes. |
string |
ByteString |
str |
[]byte |
ByteString |
string |
String (ASCII-8BIT) |