kaspad/infrastructure/network/netadapter/server/grpcserver/protowire/rpc.md

Protocol Documentation

Table of Contents

• rpc.proto

  • RPCError
  • GetCurrentNetworkRequestMessage
  • GetCurrentNetworkResponseMessage
  • SubmitBlockRequestMessage
  • SubmitBlockResponseMessage
  • GetBlockTemplateRequestMessage
  • GetBlockTemplateResponseMessage
  • NotifyBlockAddedRequestMessage
  • NotifyBlockAddedResponseMessage
  • BlockAddedNotificationMessage
  • GetPeerAddressesRequestMessage
  • GetPeerAddressesResponseMessage
  • GetPeerAddressesKnownAddressMessage
  • GetSelectedTipHashRequestMessage
  • GetSelectedTipHashResponseMessage
  • GetMempoolEntryRequestMessage
  • GetMempoolEntryResponseMessage
  • GetMempoolEntriesRequestMessage
  • GetMempoolEntriesResponseMessage
  • MempoolEntry
  • GetConnectedPeerInfoRequestMessage
  • GetConnectedPeerInfoResponseMessage
  • GetConnectedPeerInfoMessage
  • AddPeerRequestMessage
  • AddPeerResponseMessage
  • SubmitTransactionRequestMessage
  • SubmitTransactionResponseMessage
  • NotifyVirtualSelectedParentChainChangedRequestMessage
  • NotifyVirtualSelectedParentChainChangedResponseMessage
  • VirtualSelectedParentChainChangedNotificationMessage
  • ChainBlock
  • AcceptedBlock
  • GetBlockRequestMessage
  • GetBlockResponseMessage
  • BlockVerboseData
  • TransactionVerboseData
  • TransactionVerboseInput
  • ScriptSig
  • TransactionVerboseOutput
  • ScriptPublicKeyResult
  • GetSubnetworkRequestMessage
  • GetSubnetworkResponseMessage
  • GetVirtualSelectedParentChainFromBlockRequestMessage
  • GetVirtualSelectedParentChainFromBlockResponseMessage
  • GetBlocksRequestMessage
  • GetBlocksResponseMessage
  • GetBlockCountRequestMessage
  • GetBlockCountResponseMessage
  • GetBlockDagInfoRequestMessage
  • GetBlockDagInfoResponseMessage
  • ResolveFinalityConflictRequestMessage
  • ResolveFinalityConflictResponseMessage
  • NotifyFinalityConflictsRequestMessage
  • NotifyFinalityConflictsResponseMessage
  • FinalityConflictNotificationMessage
  • FinalityConflictResolvedNotificationMessage
  • ShutDownRequestMessage
  • ShutDownResponseMessage
  • GetHeadersRequestMessage
  • GetHeadersResponseMessage
  • NotifyUtxosChangedRequestMessage
  • NotifyUtxosChangedResponseMessage
  • UtxosChangedNotificationMessage
  • UtxosByAddressesEntry
  • RpcTransaction
  • RpcTransactionInput
  • RpcScriptPublicKey
  • RpcTransactionOutput
  • RpcOutpoint
  • RpcUtxoEntry
  • GetUtxosByAddressesRequestMessage
  • GetUtxosByAddressesResponseMessage
  • GetVirtualSelectedParentBlueScoreRequestMessage
  • GetVirtualSelectedParentBlueScoreResponseMessage
  • NotifyVirtualSelectedParentBlueScoreChangedRequestMessage
  • NotifyVirtualSelectedParentBlueScoreChangedResponseMessage
  • VirtualSelectedParentBlueScoreChangedNotificationMessage

• Scalar Value Types

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

GetCurrentNetworkRequestMessage

GetCurrentNetworkRequestMessage requests the network kaspad is currently running against.

Possible networks are: Mainnet, Testnet, Simnet, Devnet

GetCurrentNetworkResponseMessage

Field	Type	Label	Description
currentNetwork	string
error	RPCError

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	BlockMessage

SubmitBlockResponseMessage

Field	Type	Label	Description
error	RPCError

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

GetBlockTemplateResponseMessage

Field	Type	Label	Description
blockMessage	BlockMessage
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	BlockMessage

GetPeerAddressesRequestMessage

GetPeerAddressesRequestMessage requests the list of known kaspad addresses in the current network. (mainnet, testnet, etc.)

GetPeerAddressesResponseMessage

Field	Type	Label	Description
addresses	GetPeerAddressesKnownAddressMessage	repeated
bannedAddresses	GetPeerAddressesKnownAddressMessage	repeated
error	RPCError

GetPeerAddressesKnownAddressMessage

Field	Type	Label	Description
Addr	string

GetSelectedTipHashRequestMessage

GetSelectedTipHashRequestMessage requests the hash of the current virtual's selected parent.

GetSelectedTipHashResponseMessage

Field	Type	Label	Description
selectedTipHash	string
error	RPCError

GetMempoolEntryRequestMessage

GetMempoolEntryRequestMessage requests information about a specific transaction in the mempool.

Field	Type	Label	Description
txId	string		The transaction's TransactionID.

GetMempoolEntryResponseMessage

Field	Type	Label	Description
entry	MempoolEntry
error	RPCError

GetMempoolEntriesRequestMessage

GetMempoolEntriesRequestMessage requests information about all the transactions currently in the mempool.

GetMempoolEntriesResponseMessage

Field	Type	Label	Description
entries	MempoolEntry	repeated
error	RPCError

MempoolEntry

Field	Type	Label	Description
fee	uint64
transactionVerboseData	TransactionVerboseData

GetConnectedPeerInfoRequestMessage

GetConnectedPeerInfoRequestMessage requests information about all the p2p peers currently connected to this kaspad.

GetConnectedPeerInfoResponseMessage

Field	Type	Label	Description
infos	GetConnectedPeerInfoMessage	repeated
error	RPCError

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

Field	Type	Label	Description
transaction	RpcTransaction

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

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
addedChainBlocks	ChainBlock	repeated	The chain blocks that were added, in low-to-high order

ChainBlock

Field	Type	Label	Description
hash	string
acceptedBlocks	AcceptedBlock	repeated

AcceptedBlock

Field	Type	Label	Description
hash	string
acceptedTransactionIds	string	repeated

GetBlockRequestMessage

GetBlockRequestMessage requests information about a specific block

Field	Type	Label	Description
hash	string		The hash of the requested block
subnetworkId	string
includeTransactionVerboseData	bool		Whether to include transaction data in the response

GetBlockResponseMessage

Field	Type	Label	Description
blockHash	string
blockVerboseData	BlockVerboseData
error	RPCError

BlockVerboseData

Field	Type	Label	Description
hash	string
version	uint32
versionHex	string
hashMerkleRoot	string
acceptedIDMerkleRoot	string
utxoCommitment	string
transactionVerboseData	TransactionVerboseData	repeated
time	int64
nonce	uint64
bits	string
difficulty	double
parentHashes	string	repeated
selectedParentHash	string
transactionIDs	string	repeated
isHeaderOnly	bool
blueScore	uint64

TransactionVerboseData

Field	Type	Label	Description
txId	string
hash	string
size	uint64
version	uint32
lockTime	uint64
subnetworkId	string
gas	uint64
payloadHash	string
payload	string
transactionVerboseInputs	TransactionVerboseInput	repeated
transactionVerboseOutputs	TransactionVerboseOutput	repeated
blockHash	string
time	uint64
blockTime	uint64

TransactionVerboseInput

Field	Type	Label	Description
txId	string
outputIndex	uint32
scriptSig	ScriptSig
sequence	uint64

ScriptSig

Field	Type	Label	Description
asm	string
hex	string

TransactionVerboseOutput

Field	Type	Label	Description
value	uint64
index	uint32
scriptPublicKey	ScriptPublicKeyResult

ScriptPublicKeyResult

Field	Type	Label	Description
asm	string
hex	string
type	string
address	string

GetSubnetworkRequestMessage

GetSubnetworkRequestMessage requests information about a specific subnetwork

Currently unimplemented

Field	Type	Label	Description
subnetworkId	string

GetSubnetworkResponseMessage

Field	Type	Label	Description
gasLimit	uint64
error	RPCError

GetVirtualSelectedParentChainFromBlockRequestMessage

GetVirtualSelectedParentChainFromBlockRequestMessage requests the virtual selected parent chain from some startHash to this kaspad's current virtual

Field	Type	Label	Description
startHash	string

GetVirtualSelectedParentChainFromBlockResponseMessage

Field	Type	Label	Description
removedChainBlockHashes	string	repeated	The chain blocks that were removed, in high-to-low order
addedChainBlocks	ChainBlock	repeated	The chain blocks that were added, in low-to-high order
error	RPCError

GetBlocksRequestMessage

GetBlocksRequestMessage requests blocks between a certain block lowHash up to this kaspad's current virtual.

Field	Type	Label	Description
lowHash	string
includeBlockHexes	bool
includeBlockVerboseData	bool
includeTransactionVerboseData	bool

GetBlocksResponseMessage

Field	Type	Label	Description
blockHashes	string	repeated
blockHexes	string	repeated
blockVerboseData	BlockVerboseData	repeated
error	RPCError

GetBlockCountRequestMessage

GetBlockCountRequestMessage requests the current number of blocks in this kaspad. Note that this number may decrease as pruning occurs.

GetBlockCountResponseMessage

Field	Type	Label	Description
blockCount	uint64
headerCount	uint64
error	RPCError

GetBlockDagInfoRequestMessage

GetBlockDagInfoRequestMessage requests general information about the current state of this kaspad's DAG.

GetBlockDagInfoResponseMessage

Field	Type	Label	Description
networkName	string
blockCount	uint64
headerCount	uint64
tipHashes	string	repeated
difficulty	double
pastMedianTime	int64
virtualParentHashes	string	repeated
error	RPCError

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

GetHeadersRequestMessage requests headers between the given startHash and the current virtual, up to the given limit.

Field	Type	Label	Description
startHash	string
limit	uint64
isAscending	bool

GetHeadersResponseMessage

Field	Type	Label	Description
headers	string	repeated
error	RPCError

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

NotifyUtxosChangedResponseMessage

Field	Type	Label	Description
error	RPCError

UtxosChangedNotificationMessage

UtxosChangedNotificationMessage is sent whenever the UTXO index had been updated.

See: NotifyUtxosChangedRequestMessage

Field	Type	Label	Description
added	UtxosByAddressesEntry	repeated
removed	UtxosByAddressesEntry	repeated

UtxosByAddressesEntry

Field	Type	Label	Description
address	string
outpoint	RpcOutpoint
utxoEntry	RpcUtxoEntry

RpcTransaction

Field	Type	Label	Description
version	uint32
inputs	RpcTransactionInput	repeated
outputs	RpcTransactionOutput	repeated
lockTime	uint64
subnetworkId	string
gas	uint64
payloadHash	string
payload	string

RpcTransactionInput

Field	Type	Label	Description
previousOutpoint	RpcOutpoint
signatureScript	string
sequence	uint64

RpcScriptPublicKey

Field	Type	Label	Description
version	uint32
scriptPublicKey	string

RpcTransactionOutput

Field	Type	Label	Description
amount	uint64
scriptPublicKey	RpcScriptPublicKey

RpcOutpoint

Field	Type	Label	Description
transactionId	string
index	uint32

RpcUtxoEntry

Field	Type	Label	Description
amount	uint64
scriptPublicKey	RpcScriptPublicKey
blockBlueScore	uint64
isCoinbase	bool

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

Field	Type	Label	Description
entries	UtxosByAddressesEntry	repeated
error	RPCError

GetVirtualSelectedParentBlueScoreRequestMessage

GetVirtualSelectedParentBlueScoreRequestMessage requests the blue score of the current selected parent of the virtual block.

GetVirtualSelectedParentBlueScoreResponseMessage

Field	Type	Label	Description
blueScore	uint64
error	RPCError

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

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)