D-Stacks 74a4f927e9
RPC: include orphans into mempool entries (#2046)
* RPC: include orphans into mempool entries

* no need for + 1

* give request option to choose mempool pool(s)

* add to wallet, fix bg

* use orphanpool rpc to test for orphans

* fix fmt

* fix crash when quering orphan pool in get_mempool_entries

* pass the tests, fix fromAppMessage bug

* Update config_test.go

don't think this is needed

* needed for tests to pass

* inverse to transactionpoolfilter, cut down code to two ifs.

* fmt

* update test to true false, forgot one includetransactionpool renaming

* update and simplyfiy get_mempool_entry handler

* comment outdated

* i think we usually use make instead of var.

* Fix some leftovers of includeTransactionPool

Co-authored-by: Ori Newman <orinewman1@gmail.com>
2022-06-15 23:46:44 +03:00

48 KiB
Raw Blame History

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

Field Type Label Description
header RpcBlockHeader
transactions RpcTransaction repeated
verboseData RpcBlockVerboseData

RpcBlockHeader

Field Type Label Description
version uint32
parents RpcBlockLevelParents repeated
hashMerkleRoot string
acceptedIdMerkleRoot string
utxoCommitment string
timestamp int64
bits uint32
nonce uint64
daaScore uint64
blueWork string
pruningPoint string
blueScore uint64

RpcBlockLevelParents

Field Type Label Description
parentHashes string repeated

RpcBlockVerboseData

Field Type Label Description
hash string
difficulty double
selectedParentHash string
transactionIds string repeated
isHeaderOnly bool
blueScore uint64
childrenHashes string repeated
mergeSetBluesHashes string repeated
mergeSetRedsHashes string repeated
isChainBlock bool

RpcTransaction

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

RpcTransactionInput

Field Type Label Description
previousOutpoint RpcOutpoint
signatureScript string
sequence uint64
sigOpCount uint32
verboseData RpcTransactionInputVerboseData

RpcScriptPublicKey

Field Type Label Description
version uint32
scriptPublicKey string

RpcTransactionOutput

Field Type Label Description
amount uint64
scriptPublicKey RpcScriptPublicKey
verboseData RpcTransactionOutputVerboseData

RpcOutpoint

Field Type Label Description
transactionId string
index uint32

RpcUtxoEntry

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

RpcTransactionVerboseData

Field Type Label Description
transactionId string
hash string
mass uint64
blockHash string
blockTime uint64

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

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 RpcBlock
allowNonDAABlocks bool

SubmitBlockResponseMessage

Field Type Label Description
rejectReason SubmitBlockResponseMessage.RejectReason
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
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

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.
includeOrphanPool bool
filterTransactionPool bool

GetMempoolEntryResponseMessage

Field Type Label Description
entry MempoolEntry
error RPCError

GetMempoolEntriesRequestMessage

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

Field Type Label Description
includeOrphanPool bool
filterTransactionPool bool

GetMempoolEntriesResponseMessage

Field Type Label Description
entries MempoolEntry repeated
error RPCError

MempoolEntry

Field Type Label Description
fee uint64
transaction RpcTransaction
isOrphan bool

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
allowOrphan bool

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

Field Type Label Description
block RpcBlock
error RPCError

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

Field Type Label Description
blockHashes string repeated
blocks RpcBlock 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
pruningPointHash string
virtualDaaScore uint64
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 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

Field Type Label Description
added UtxosByAddressesEntry repeated
removed UtxosByAddressesEntry repeated

UtxosByAddressesEntry

Field Type Label Description
address string
outpoint RpcOutpoint
utxoEntry RpcUtxoEntry

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

Field Type Label Description
entries UtxosByAddressesEntry repeated
error RPCError

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

Field Type Label Description
balance uint64
error RPCError

GetBalancesByAddressesRequestMessage

Field Type Label Description
addresses string repeated

BalancesByAddressEntry

Field Type Label Description
address string
balance uint64
error RPCError

GetBalancesByAddressesResponseMessage

Field Type Label Description
entries BalancesByAddressEntry 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

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

Field Type Label Description
p2pId string
mempoolSize uint64
serverVersion string
isUtxoIndexed bool
isSynced bool
error RPCError

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

Field Type Label Description
address string
sending MempoolEntry repeated
receiving MempoolEntry repeated

GetMempoolEntriesByAddressesRequestMessage

Field Type Label Description
addresses string repeated
includeOrphanPool bool
filterTransactionPool bool

GetMempoolEntriesByAddressesResponseMessage

Field Type Label Description
entries MempoolEntryByAddress repeated
error RPCError

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)