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;
  string extraData = 2;
}

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;
  bool includeOrphanPool = 2;
  bool filterTransactionPool = 3;
}

message GetMempoolEntryResponseMessage{
  MempoolEntry entry = 1;

  RPCError error = 1000;
}

// GetMempoolEntriesRequestMessage requests information about all the transactions
// currently in the mempool.
message GetMempoolEntriesRequestMessage{
        bool includeOrphanPool = 1;
        bool filterTransactionPool = 2;
}

message GetMempoolEntriesResponseMessage{
  repeated MempoolEntry entries = 1;

  RPCError error = 1000;
}

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

// 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{
  bool includeAcceptedTransactionIds = 1;
}

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;

  // Will be filled only if `includeAcceptedTransactionIds = true` in the notify request.
  repeated AcceptedTransactionIds acceptedTransactionIds = 2;
}

// 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;
  bool includeAcceptedTransactionIds = 2;
}

message AcceptedTransactionIds{
  string acceptingBlockHash = 1;
  repeated string acceptedTransactionIds = 2;
}

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;

  // The transactions accepted by each block in addedChainBlockHashes.
  // Will be filled only if `includeAcceptedTransactionIds = true` in the request.
  repeated AcceptedTransactionIds acceptedTransactionIds = 2;

  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; // Leave empty to get all updates
}

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;
  bool isUtxoIndexed = 4;
  bool isSynced = 5;
  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 {
}

message MempoolEntryByAddress{
  string address = 1;
  repeated MempoolEntry sending = 2;
  repeated MempoolEntry receiving = 3;
}

message GetMempoolEntriesByAddressesRequestMessage{
  repeated string addresses = 1;
  bool includeOrphanPool = 2;
  bool filterTransactionPool = 3;
}

message  GetMempoolEntriesByAddressesResponseMessage{
  repeated MempoolEntryByAddress entries = 1;

  RPCError error = 1000;
}

message GetCoinSupplyRequestMessage{
}

message GetCoinSupplyResponseMessage{
        uint64 maxSompi = 1; // note: this is a hard coded maxSupply, actual maxSupply is expected to deviate by upto -5%, but cannot be measured exactly.
        uint64 circulatingSompi = 2;

        RPCError error = 1000;
}

message PingRequestMessage{
}

message PingResponseMessage { RPCError error = 1000; }

message ProcessMetrics {
  uint64 residentSetSize = 1;
  uint64 virtualMemorySize = 2;
  uint32 coreNum = 3;
  float cpuUsage = 4;
  uint32 fdNum = 5;
  uint64 diskIoReadBytes = 6;
  uint64 diskIoWriteBytes = 7;
  float diskIoReadPerSec = 8;
  float diskIoWritePerSec = 9;
}

message ConnectionMetrics {
  uint32 borshLiveConnections = 31;
  uint64 borshConnectionAttempts = 32;
  uint64 borshHandshakeFailures = 33;

  uint32 jsonLiveConnections = 41;
  uint64 jsonConnectionAttempts = 42;
  uint64 jsonHandshakeFailures = 43;

  uint32 activePeers = 51;
}

message BandwidthMetrics {
  uint64 borshBytesTx = 61;
  uint64 borshBytesRx = 62;
  uint64 jsonBytesTx = 63;
  uint64 jsonBytesRx = 64;
  uint64 grpcP2pBytesTx = 65;
  uint64 grpcP2pBytesRx = 66;
  uint64 grpcUserBytesTx = 67;
  uint64 grpcUserBytesRx = 68;
}

message ConsensusMetrics {
  uint64 blocksSubmitted = 1;
  uint64 headerCounts = 2;
  uint64 depCounts = 3;
  uint64 bodyCounts = 4;
  uint64 txsCounts = 5;
  uint64 chainBlockCounts = 6;
  uint64 massCounts = 7;

  uint64 blockCount = 11;
  uint64 headerCount = 12;
  uint64 mempoolSize = 13;
  uint32 tipHashesCount = 14;
  double difficulty = 15;
  uint64 pastMedianTime = 16;
  uint32 virtualParentHashesCount = 17;
  uint64 virtualDaaScore = 18;
}

message StorageMetrics { uint64 storageSizeBytes = 1; }

message GetConnectionsRequestMessage { bool includeProfileData = 1; }

message ConnectionsProfileData {
  double cpuUsage = 1;
  uint64 memoryUsage = 2;
}

message GetConnectionsResponseMessage {
  uint32 clients = 1;
  uint32 peers = 2;
  ConnectionsProfileData profileData = 3;
  RPCError error = 1000;
}

message GetSystemInfoRequestMessage {}

message GetSystemInfoResponseMessage {
  string version = 1;
  string systemId = 2;
  string gitHash = 3;
  uint32 coreNum = 4;
  uint64 totalMemory = 5;
  uint32 fdLimit = 6;
  RPCError error = 1000;
}

message GetMetricsRequestMessage {
  bool processMetrics = 1;
  bool connectionMetrics = 2;
  bool bandwidthMetrics = 3;
  bool consensusMetrics = 4;
  bool storageMetrics = 5;
  bool customMetrics = 6;
}

message GetMetricsResponseMessage {
  uint64 serverTime = 1;
  ProcessMetrics processMetrics = 11;
  ConnectionMetrics connectionMetrics = 12;
  BandwidthMetrics bandwidthMetrics = 13;
  ConsensusMetrics consensusMetrics = 14;
  StorageMetrics storageMetrics = 15;
  RPCError error = 1000;
}

message GetServerInfoRequestMessage {}

message GetServerInfoResponseMessage {
  uint32 rpcApiVersion = 1;
  uint32 rpcApiRevision = 2;
  string serverVersion = 3;
  string networkId = 4;
  bool hasUtxoIndex = 5;
  bool isSynced = 6;
  uint64 virtualDaaScore = 7;
  RPCError error = 1000;
}

message GetSyncStatusRequestMessage {}

message GetSyncStatusResponseMessage {
  bool isSynced = 1;
  RPCError error = 1000;
}

message GetDaaScoreTimestampEstimateRequestMessage {
  repeated uint64 daaScores = 1;
}

message GetDaaScoreTimestampEstimateResponseMessage{
  repeated uint64 timestamps = 1;
  RPCError error = 1000;
}

message RpcFeerateBucket {
  // Fee/mass of a transaction in `sompi/gram` units
  double feerate = 1;
  double estimatedSeconds = 2;
}

// Data required for making fee estimates.
//
// Feerate values represent fee/mass of a transaction in `sompi/gram` units.
// Given a feerate value recommendation, calculate the required fee by
// taking the transaction mass and multiplying it by feerate: `fee = feerate *
// mass(tx)`
message RpcFeeEstimate {
  // Top-priority feerate bucket. Provides an estimation of the feerate required
  // for sub-second DAG inclusion.
  RpcFeerateBucket priority_bucket = 1;

  // A vector of *normal* priority feerate values. The first value of this
  // vector is guaranteed to exist and provide an estimation for sub-*minute*
  // DAG inclusion. All other values will have shorter estimation times than all
  // `lowBuckets` values. Therefor by chaining `[priority] | normal | low` and
  // interpolating between them, one can compose a complete feerate function on
  // the client side. The API makes an effort to sample enough "interesting"
  // points on the feerate-to-time curve, so that the interpolation is
  // meaningful.
  repeated RpcFeerateBucket normalBuckets = 2;

  // A vector of *low* priority feerate values. The first value of this vector
  // is guaranteed to exist and provide an estimation for sub-*hour* DAG
  // inclusion.
  repeated RpcFeerateBucket lowBuckets = 3;
}

message RpcFeeEstimateVerboseExperimentalData {
  uint64 mempoolReadyTransactionsCount = 1;
  uint64 mempoolReadyTransactionsTotalMass = 2;
  uint64 networkMassPerSecond = 3;

  double nextBlockTemplateFeerateMin = 11;
  double nextBlockTemplateFeerateMedian = 12;
  double nextBlockTemplateFeerateMax = 13;
}

message GetFeeEstimateRequestMessage {}

message GetFeeEstimateResponseMessage {
  RpcFeeEstimate estimate = 1;
  RPCError error = 1000;
}

message GetFeeEstimateExperimentalRequestMessage { bool verbose = 1; }

message GetFeeEstimateExperimentalResponseMessage {
  RpcFeeEstimate estimate = 1;
  RpcFeeEstimateVerboseExperimentalData verbose = 2;

  RPCError error = 1000;
}

message GetCurrentBlockColorRequestMessage { string hash = 1; }

message GetCurrentBlockColorResponseMessage {
  bool blue = 1;

  RPCError error = 1000;
}

// SubmitTransactionReplacementRequestMessage submits a transaction to the
// mempool, applying a mandatory Replace by Fee policy
message SubmitTransactionReplacementRequestMessage {
  RpcTransaction transaction = 1;
}

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

  // The previous transaction replaced in the mempool by the newly submitted one
  RpcTransaction replacedTransaction = 2;

  RPCError error = 1000;
}