kaspad/infrastructure/network/netadapter/server/grpcserver/protowire/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.
//
syntax = "proto3";
package protowire;

option go_package = "github.com/kaspanet/kaspad/protowire";

// RPCError represents a generic non-internal error.
//
// Receivers of any ResponseMessage are expected to check whether its error field is not null.
message RPCError{
  string message = 1;
}

message RpcBlock {
  RpcBlockHeader header = 1;
  repeated RpcTransaction transactions = 2;
  RpcBlockVerboseData verboseData = 3;
}

message RpcBlockHeader {
  uint32 version = 1;
  repeated RpcBlockLevelParents parents = 12;
  string hashMerkleRoot = 3;
  string acceptedIdMerkleRoot = 4;
  string utxoCommitment = 5;
  int64 timestamp = 6;
  uint32 bits = 7;
  uint64 nonce = 8;
  uint64 daaScore = 9;
  string blueWork = 10;
  string pruningPoint = 14;
  uint64 blueScore = 13;
}

message RpcBlockLevelParents {
  repeated string parentHashes = 1;
}

message RpcBlockVerboseData{
  string hash = 1;
  double difficulty = 11;
  string selectedParentHash = 13;
  repeated string transactionIds = 14;
  bool isHeaderOnly = 15;
  uint64 blueScore = 16;
  repeated string childrenHashes = 17;
  repeated string mergeSetBluesHashes = 18;
  repeated string mergeSetRedsHashes = 19;
  bool isChainBlock = 20;
}

message RpcTransaction {
  uint32 version = 1;
  repeated RpcTransactionInput inputs = 2;
  repeated RpcTransactionOutput outputs = 3;
  uint64 lockTime = 4;
  string subnetworkId = 5;
  uint64 gas = 6;
  string payload = 8;
  RpcTransactionVerboseData verboseData = 9;
}

message RpcTransactionInput {
  RpcOutpoint previousOutpoint = 1;
  string signatureScript = 2;
  uint64 sequence = 3;
  uint32 sigOpCount = 5;
  RpcTransactionInputVerboseData verboseData = 4;
}

message RpcScriptPublicKey {
  uint32 version = 1;
  string scriptPublicKey = 2;
}

message RpcTransactionOutput {
  uint64 amount = 1;
  RpcScriptPublicKey scriptPublicKey = 2;
  RpcTransactionOutputVerboseData verboseData = 3;
}

message RpcOutpoint {
  string transactionId = 1;
  uint32 index = 2;
}

message RpcUtxoEntry {
  uint64 amount = 1;
  RpcScriptPublicKey scriptPublicKey = 2;
  uint64 blockDaaScore = 3;
  bool isCoinbase = 4;
}

message RpcTransactionVerboseData{
  string transactionId = 1;
  string hash = 2;
  uint64 mass = 4;
  string blockHash = 12;
  uint64 blockTime = 14;
}

message RpcTransactionInputVerboseData{
}

message RpcTransactionOutputVerboseData{
  string scriptPublicKeyType = 5;
  string scriptPublicKeyAddress = 6;
}

// GetCurrentNetworkRequestMessage requests the network kaspad is currently running against.
//
// Possible networks are: Mainnet, Testnet, Simnet, Devnet
message GetCurrentNetworkRequestMessage{
}

message GetCurrentNetworkResponseMessage{
  string currentNetwork = 1;
  RPCError error = 1000;
}

// SubmitBlockRequestMessage requests to submit a block into the DAG.
// Blocks are generally expected to have been generated using the getBlockTemplate call.
//
// See: GetBlockTemplateRequestMessage
message SubmitBlockRequestMessage{
  RpcBlock block = 2;
  bool allowNonDAABlocks = 3;
}

message SubmitBlockResponseMessage{
  enum RejectReason {
    NONE = 0;
    BLOCK_INVALID = 1;
    IS_IN_IBD = 2;
  }
  RejectReason rejectReason = 1;
  RPCError error = 1000;
}

// GetBlockTemplateRequestMessage requests a current block template.
// Callers are expected to solve the block template and submit it using the submitBlock call
//
// See: SubmitBlockRequestMessage
message GetBlockTemplateRequestMessage{
  // Which kaspa address should the coinbase block reward transaction pay into
  string payAddress = 1;
}

message GetBlockTemplateResponseMessage{
  RpcBlock block = 3;

  // 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.
  bool isSynced = 2;

  RPCError error = 1000;
}

// NotifyBlockAddedRequestMessage registers this connection for blockAdded notifications.
//
// See: BlockAddedNotificationMessage
message NotifyBlockAddedRequestMessage{
}

message NotifyBlockAddedResponseMessage{
  RPCError error = 1000;
}

// BlockAddedNotificationMessage is sent whenever a blocks has been added (NOT accepted)
// into the DAG.
//
// See: NotifyBlockAddedRequestMessage
message BlockAddedNotificationMessage{
  RpcBlock block = 3;
}

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

message GetPeerAddressesResponseMessage{
  repeated GetPeerAddressesKnownAddressMessage addresses = 1;
  repeated GetPeerAddressesKnownAddressMessage bannedAddresses = 2;
  RPCError error = 1000;
}

message GetPeerAddressesKnownAddressMessage {
  string Addr = 1;
}

// GetSelectedTipHashRequestMessage requests the hash of the current virtual's
// selected parent.
message GetSelectedTipHashRequestMessage{
}

message GetSelectedTipHashResponseMessage{
  string selectedTipHash = 1;
  RPCError error = 1000;
}

// GetMempoolEntryRequestMessage requests information about a specific transaction
// in the mempool.
message GetMempoolEntryRequestMessage{
  // The transaction's TransactionID.
  string txId = 1;
}

message GetMempoolEntryResponseMessage{
  MempoolEntry entry = 1;

  RPCError error = 1000;
}

// GetMempoolEntriesRequestMessage requests information about all the transactions
// currently in the mempool.
message GetMempoolEntriesRequestMessage{
}

message GetMempoolEntriesResponseMessage{
  repeated MempoolEntry entries = 1;

  RPCError error = 1000;
}

message MempoolEntry{
  uint64 fee = 1;
  RpcTransaction transaction = 3;
}

// GetConnectedPeerInfoRequestMessage requests information about all the p2p peers
// currently connected to this kaspad.
message GetConnectedPeerInfoRequestMessage{
}

message GetConnectedPeerInfoResponseMessage{
  repeated GetConnectedPeerInfoMessage infos = 1;
  RPCError error = 1000;
}

message GetConnectedPeerInfoMessage{
  string id = 1;
  string address = 2;

  // How long did the last ping/pong exchange take
  int64 lastPingDuration = 3;

  // Whether this kaspad initiated the connection
  bool isOutbound = 6;
  int64 timeOffset = 7;
  string userAgent = 8;

  // The protocol version that this peer claims to support
  uint32 advertisedProtocolVersion = 9;

  // The timestamp of when this peer connected to this kaspad
  int64 timeConnected = 10;

  // Whether this peer is the IBD peer (if IBD is running)
  bool isIbdPeer = 11;
}

// AddPeerRequestMessage adds a peer to kaspad's outgoing connection list.
// This will, in most cases, result in kaspad connecting to said peer.
message AddPeerRequestMessage{
  string address = 1;

  // Whether to keep attempting to connect to this peer after disconnection
  bool isPermanent = 2;
}

message AddPeerResponseMessage{
  RPCError error = 1000;
}

// SubmitTransactionRequestMessage submits a transaction to the mempool
message SubmitTransactionRequestMessage{
  RpcTransaction transaction = 1;
  bool allowOrphan = 2;
}

message SubmitTransactionResponseMessage{
  // The transaction ID of the submitted transaction
  string transactionId = 1;

  RPCError error = 1000;
}

// NotifyVirtualSelectedParentChainChangedRequestMessage registers this connection for virtualSelectedParentChainChanged notifications.
//
// See: VirtualSelectedParentChainChangedNotificationMessage
message NotifyVirtualSelectedParentChainChangedRequestMessage{
}

message NotifyVirtualSelectedParentChainChangedResponseMessage{
  RPCError error = 1000;
}

// VirtualSelectedParentChainChangedNotificationMessage is sent whenever the DAG's selected parent
// chain had changed.
//
// See: NotifyVirtualSelectedParentChainChangedRequestMessage
message VirtualSelectedParentChainChangedNotificationMessage{
  // The chain blocks that were removed, in high-to-low order
  repeated string removedChainBlockHashes = 1;

  // The chain blocks that were added, in low-to-high order
  repeated string addedChainBlockHashes = 3;
}

// GetBlockRequestMessage requests information about a specific block
message GetBlockRequestMessage{
  // The hash of the requested block
  string hash = 1;

  // Whether to include transaction data in the response
  bool includeTransactions = 3;
}

message GetBlockResponseMessage{
  RpcBlock block = 3;
  RPCError error = 1000;
}

// GetSubnetworkRequestMessage requests information about a specific subnetwork
//
// Currently unimplemented
message GetSubnetworkRequestMessage{
  string subnetworkId = 1;
}

message GetSubnetworkResponseMessage{
  uint64 gasLimit = 1;
  RPCError error = 1000;
}

// GetVirtualSelectedParentChainFromBlockRequestMessage requests the virtual selected
// parent chain from some startHash to this kaspad's current virtual
message GetVirtualSelectedParentChainFromBlockRequestMessage{
  string startHash = 1;
}

message GetVirtualSelectedParentChainFromBlockResponseMessage{
  // The chain blocks that were removed, in high-to-low order
  repeated string removedChainBlockHashes = 1;

  // The chain blocks that were added, in low-to-high order
  repeated string addedChainBlockHashes = 3;

  RPCError error = 1000;
}

// GetBlocksRequestMessage requests blocks between a certain block lowHash up to this
// kaspad's current virtual.
message GetBlocksRequestMessage{
  string lowHash = 1;
  bool includeBlocks = 2;
  bool includeTransactions = 3;
}

message GetBlocksResponseMessage{
  repeated string blockHashes = 4;
  repeated RpcBlock blocks = 3;
  RPCError error = 1000;
}

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

message GetBlockCountResponseMessage{
  uint64 blockCount = 1;
  uint64 headerCount = 2;
  RPCError error = 1000;
}

// GetBlockDagInfoRequestMessage requests general information about the current state
// of this kaspad's DAG.
message GetBlockDagInfoRequestMessage{
}

message GetBlockDagInfoResponseMessage{
  string networkName = 1;
  uint64 blockCount = 2;
  uint64 headerCount = 3;
  repeated string tipHashes = 4;
  double difficulty = 5;
  int64 pastMedianTime = 6;
  repeated string virtualParentHashes = 7;
  string pruningPointHash = 8;
  uint64 virtualDaaScore = 9;
  RPCError error = 1000;
}

message ResolveFinalityConflictRequestMessage{
  string finalityBlockHash = 1;
}

message ResolveFinalityConflictResponseMessage{
  RPCError error = 1000;
}

message NotifyFinalityConflictsRequestMessage{
}

message NotifyFinalityConflictsResponseMessage{
  RPCError error = 1000;
}

message FinalityConflictNotificationMessage{
  string violatingBlockHash = 1;
}

message FinalityConflictResolvedNotificationMessage{
  string finalityBlockHash = 1;
}

// ShutDownRequestMessage shuts down this kaspad.
message ShutDownRequestMessage{
}

message ShutDownResponseMessage{
  RPCError error = 1000;
}

// GetHeadersRequestMessage requests headers between the given startHash and the
// current virtual, up to the given limit.
message GetHeadersRequestMessage{
  string startHash = 1;
  uint64 limit = 2;
  bool isAscending = 3;
}

message GetHeadersResponseMessage{
  repeated string headers = 1;
  RPCError error = 1000;
}

// 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
message NotifyUtxosChangedRequestMessage {
  repeated string addresses = 1;
}

message NotifyUtxosChangedResponseMessage {
  RPCError error = 1000;
}

// UtxosChangedNotificationMessage is sent whenever the UTXO index had been updated.
//
// See: NotifyUtxosChangedRequestMessage
message UtxosChangedNotificationMessage {
  repeated UtxosByAddressesEntry added = 1;
  repeated UtxosByAddressesEntry removed = 2;
}

message UtxosByAddressesEntry {
  string address = 1;
  RpcOutpoint outpoint = 2;
  RpcUtxoEntry utxoEntry = 3;
}

// 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
message StopNotifyingUtxosChangedRequestMessage {
  repeated string addresses = 1;
}

message StopNotifyingUtxosChangedResponseMessage {
  RPCError error = 1000;
}

// GetUtxosByAddressesRequestMessage requests all current UTXOs for the given kaspad addresses
//
// This call is only available when this kaspad was started with `--utxoindex`
message GetUtxosByAddressesRequestMessage {
  repeated string addresses = 1;
}

message GetUtxosByAddressesResponseMessage {
  repeated UtxosByAddressesEntry entries = 1;

  RPCError error = 1000;
}

// GetBalanceByAddressRequest returns the total balance in unspent transactions towards a given address
// 
// This call is only available when this kaspad was started with `--utxoindex`
message GetBalanceByAddressRequestMessage {
  string address = 1;
}

message GetBalanceByAddressResponseMessage {
  uint64 balance = 1;

  RPCError error = 1000;
}

message GetBalancesByAddressesRequestMessage {
  repeated string addresses = 1;
}

message BalancesByAddressEntry{
  string address = 1;
  uint64 balance = 2;

  RPCError error = 1000;
}

message GetBalancesByAddressesResponseMessage {
  repeated BalancesByAddressEntry entries = 1;

  RPCError error = 1000;
}

// GetVirtualSelectedParentBlueScoreRequestMessage requests the blue score of the current selected parent
// of the virtual block.
message GetVirtualSelectedParentBlueScoreRequestMessage {
}

message GetVirtualSelectedParentBlueScoreResponseMessage {
  uint64 blueScore = 1;

  RPCError error = 1000;
}

// NotifyVirtualSelectedParentBlueScoreChangedRequestMessage registers this connection for
// virtualSelectedParentBlueScoreChanged notifications.
//
// See: VirtualSelectedParentBlueScoreChangedNotificationMessage
message NotifyVirtualSelectedParentBlueScoreChangedRequestMessage {
}

message NotifyVirtualSelectedParentBlueScoreChangedResponseMessage {
  RPCError error = 1000;
}

// VirtualSelectedParentBlueScoreChangedNotificationMessage is sent whenever the blue score
// of the virtual's selected parent changes.
//
// See NotifyVirtualSelectedParentBlueScoreChangedRequestMessage
message VirtualSelectedParentBlueScoreChangedNotificationMessage {
  uint64 virtualSelectedParentBlueScore = 1;
}

// NotifyVirtualDaaScoreChangedRequestMessage registers this connection for
// virtualDaaScoreChanged notifications.
//
// See: VirtualDaaScoreChangedNotificationMessage
message NotifyVirtualDaaScoreChangedRequestMessage {
}

message NotifyVirtualDaaScoreChangedResponseMessage {
  RPCError error = 1000;
}

// VirtualDaaScoreChangedNotificationMessage is sent whenever the DAA score
// of the virtual changes.
//
// See NotifyVirtualDaaScoreChangedRequestMessage
message VirtualDaaScoreChangedNotificationMessage {
  uint64 virtualDaaScore = 1;
}

// 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
message NotifyPruningPointUTXOSetOverrideRequestMessage {
}


message NotifyPruningPointUTXOSetOverrideResponseMessage {
  RPCError error = 1000;
}

// PruningPointUTXOSetOverrideNotificationMessage is sent whenever the UTXO index
// resets due to pruning point change via IBD.
//
// See NotifyPruningPointUTXOSetOverrideRequestMessage
message PruningPointUTXOSetOverrideNotificationMessage {
}

// 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
message StopNotifyingPruningPointUTXOSetOverrideRequestMessage {
}

message StopNotifyingPruningPointUTXOSetOverrideResponseMessage {
  RPCError error = 1000;
}

// BanRequestMessage bans the given ip.
message BanRequestMessage{
  string ip = 1;
}

message BanResponseMessage{
  RPCError error = 1000;
}

// UnbanRequestMessage unbans the given ip.
message UnbanRequestMessage{
  string ip = 1;
}

message UnbanResponseMessage{
  RPCError error = 1000;
}

// GetInfoRequestMessage returns info about the node.
message GetInfoRequestMessage{
}

message GetInfoResponseMessage{
  string p2pId = 1;
  uint64 mempoolSize = 2;
  string serverVersion = 3;
  RPCError error = 1000;
}

message EstimateNetworkHashesPerSecondRequestMessage{
  uint32 windowSize = 1;
  string startHash = 2;
}

message EstimateNetworkHashesPerSecondResponseMessage{
  uint64 networkHashesPerSecond = 1;
  RPCError error = 1000;
}

// NotifyNewBlockTemplateRequestMessage registers this connection for
// NewBlockTemplate notifications.
//
// See: NewBlockTemplateNotificationMessage
message NotifyNewBlockTemplateRequestMessage {
}

message NotifyNewBlockTemplateResponseMessage {
  RPCError error = 1000;
}

// NewBlockTemplateNotificationMessage is sent whenever a new updated block template is
// available for miners.
//
// See NotifyNewBlockTemplateRequestMessage
message NewBlockTemplateNotificationMessage {
}