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;
  bool txIndexed = 15; //whether the transaction is stored in the txindex database, regardless if kaspad is run with the `--txindex` flag, or not. 
  string acceptingBlockHash = 16; // Kaspad must be started with the `--txindex` flag, for parameter to display. 
  uint32 confirmations = 17;  // Kaspad must be started with the `--txindex` flag for parameter to display.
}

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 isTxIndexed = 5;
  bool isArchival = 6;
  bool isSynced = 7;

  RPCError error = 1000;
}


//Kaspad most be started with the `--txindex` flag for this Request to work.
message GetAcceptingBlockHashOfTxRequestMessage {
        string txID = 1;    
}

 //the accepting block is defined as the virtual chain block that first knows about the transaction. This block may change, or be ommitted and resubmitted, during virtual changes at the tip of the blockDAG   
message GetAcceptingBlockHashOfTxResponseMessage {
        string hash = 1; //the accepting block is defined as the virtual chain block that first knows about the transaction. This block may change, or be ommitted and resubmitted, during virtual changes at the tip of the blockDAG   
        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 RpcTxIDConfirmationsPair {
        string txID = 1;
        int64 confirmations = 2;   
}

message RpcTxIDBlockHashPair {
        string txID = 1;
        string Hash = 2;   
}

message RpcTxIDBlockPair {
        string txID = 1;
        RpcBlock block = 2;   
}

// Kaspad must be started with the `--txindex` flag for this Request to work.
message GetAcceptingBlockHashesOfTxsRequestMessage{
        repeated string txIDs = 1;
}
message GetAcceptingBlockHashesOfTxsResponseMessage{
        repeated RpcTxIDBlockHashPair txIDBlockHashPairs = 1;
        
        RPCError error = 1000;
}

// Kaspad must be started with the `--txindex` flag for this Request to work.
message GetTxsRequestMessage{
        repeated string txIDs = 1;
}

message GetTxsResponseMessage{
        repeated RpcTransaction transactions = 1;


        RPCError error = 1000;
}


// Kaspad must be started with the `--txindex` flag for this Request to work.
message GetTxsConfirmationsRequestMessage{
        repeated string txIDs = 1;
}

message GetTxsConfirmationsResponseMessage{
        repeated RpcTxIDConfirmationsPair txIDConfirmationsPairs = 1; 

        RPCError error = 1000;
}

// NotifyTxsConfirmationChangedRequstMessage is a listener that registers confirmations from supplied TxIDs
// Kaspad must be started with the `--txindex` flag for this Request to work.
message NotifyTxsConfirmationChangedRequestMessage{
        repeated string TxIDs = 1; //initial TxIds to listen for when regestering for notifications

        uint32 requiredConfirmations = 2; // number of confirmations until a transaction is considered confirmed
        bool includePending = 3; // weather to notify confirmation changes during pre-Confirmed states
               
}

message NotifyTxsConfirmationChangedResponseMessage{
   
        RPCError error = 1000;
}

// TxsConfirmationChangedNotificationMessage is the notification about txs pertaining to specified TxIDs
message TxsConfirmationChangedNotificationMessage{
        uint32 requiredConfirmations = 1; //the required confirmations set when notification was sent
        repeated RpcTxIDConfirmationsPair pending = 2; // RpcTxIDConfirmationsPairs which have entered the virtual chain but not passed the required confirmations
        repeated RpcTxIDConfirmationsPair confirmed = 3; // RpcTxIDConfirmationsPairs which have entered the virtual chain and passed the required confirmations
        repeated string unconfirmedTxIds = 4; // TxIds which were not confirmed within the required confirmations.

        RPCError error = 1000;
}

// ModifyNotifyingTxsConfirmationChangedRequestMessage modfies the params of a registered `NotifyTxsConfirmationChangedRequstMessage`
// must be registered to NotifyTxsConfirmationChangedRequstMessage for this command to work
message ModifyNotifyingTxsConfirmationChangedRequestMessage{
        repeated string addTxIDs = 1; //add txIds to the notification stream
        repeated string removeTxIDs = 2; //remove txIds to the notification stream
        uint32 requiredConfirmations = 3;
        bool includePending = 4;
}

message ModifyNotifyingTxsConfirmationChangedResponseMessage{
        RPCError error = 1000;
}

message TxEntryByAddress{
        string address = 1;
        string txId = 2;
        uint32 confirmations = 3;
      }

message TxEntriesByAddresses{
        repeated TxEntryByAddress sent = 1; 
        repeated TxEntryByAddress received = 2;
      }

// NotifyAddressesTxsChangedRequestMessage Listens for Txs pertaining to specified addresses according to the params specified
message NotifyAddressesTxsRequestMessage{
        repeated string addresses = 1; //initial addresses to listen for Tx changes when regestering for notifications
        uint32 requiredConfirmations = 2;  // number of confirmations until a transaction is considered confirmed
        bool includePending = 3; //whether to notify confirmation changes during pre-Confirmed states
        bool includeSending = 4; //whether to listen on addresses sending txs
        bool includeReceiving = 5; //whether to listen on addresses reciving txs
}

message NotifyAddressesTxsResponseMessage{
        RPCError error = 1000;
}

// ModifyNotifyAddressesTxsParamsRequestMessage modifies the params used for a regesitered `NotifyAddressesTxsRequest`
// Must be registered to NotifyAddressTxChangedRequestMessage for this command to work
message ModifyNotifyingAddressesTxsRequestMessage{
        repeated string AddAddresses = 1;  //add addresses to the notification stream
        repeated string RemoveAddresses = 2; //remove addresses to the notification stream
        uint32 requiredConfirmations = 3;
        bool includePending = 4;
        bool includeSending = 5;
        bool includeReceiving = 6;
}

message ModifyNotifyingAddressesTxsResponseMessage{

        RPCError error = 1000;
}

// AddressesTxsNotificationMessage is the notification about txs pertaining to specified addresses
message AddressesTxsNotificationMessage{
        uint32 requiredConfirmations = 1; //the required confirmations set when notification was sent
        TxEntriesByAddresses pending = 2; // TxEntriesByAddresses which have entered the blockdag but not passed the required confirmations
        TxEntriesByAddresses confirmed = 3; // TxEntriesByAddresses which have entered the blockdag and passed the required confirmations
        TxEntriesByAddresses unconfirmed = 4; // TxEntriesByAddresses which have been pending, but removed via a reorg within the number of required confirmations.
}