Introduction

Now that the ADR-106 - gRPC API has been approved and merged, the next step is the implementation of the gRPC services outlined in the ADR.

This will be a master tracking issue for all the services that still need to be implemented.

Some gRPC services were fully or partially implemented as part of the ADR-101 - Data Companion Pull API effort, such as Block, BlockResults and Version service.

The remaining services don't need to be implemented all at once. The goal is to implement each individual service (and its methods) as part of a separate issue.

List of services to be implemented (and methods for each service)

• VersionService - A simple service that aims to be quite stable over time in order to be utilized by clients to establish the version of the software with which they are interacting (e.g. to pre-emptively determine compatibility).
  • GetVersion - Query the version of the software and protocols employed by the node (e.g. CometBFT, ABCI, block, P2P and application version).

• Implemented in:
  • grpc: Add base gRPC server with version service #818 (GetVersion)
• Available on:
  • v1.x (alpha)
  • v0.38.x (experimental)

• NodeService - Provides information about the node providing the gRPC interface
  • GetStatus - Query the current node status, including node info, public key, latest block hash, app hash, block height and time.
  • GetHealth - Lightweight mechanism to query the health of the node.

• TransactionService - Facilitates broadcasting and querying of transactions.
  • BroadcastAsync - Broadcast a transaction asynchronously. Does not wait for the transaction to be validated via CheckTx, nor does it wait for the transaction to be committed.
  • BroadcastSync - Broadcast a transaction, but only return once CheckTx has been called on the transaction. Does not wait for the transaction to be committed.
  • GetByHash - Fetch a transaction by way of its hash.
  • Search - Search for transactions with their results.

• ApplicationService - Provides a proxy interface through which to access the application being run by the node (via ABCI).
  • Query - Submit a query directly to the application via ABCI.

• BlockService - Provides information about blocks.
  • GetLatestHeight - Return a stream of latest block heights as new blocks are committed to the blockchain.
  • GetByHeight - Fetch the block associated with a particular height.
  • GetHeaderByHeight - Fetch the header associated with the block at a particular height.
  • Search - Search for blocks by way of block events.

• Implemented in [partially]:
  • Add gRPC block service #1142 (GetLatestHeight and GetByHeight)
• Available on:
  • v1.x (alpha)
  • v0.38.x (experimental)

• BlockResultsService - Provides information about block execution results.
  • GetBlockResults - Fetch the block results associated with a particular height.

• Implemented in:
  • Add BlockResults gRPC service #1168 (GetBlockResults)
• Available on:
  • v1.x (alpha)
  • v0.38.x (experimental)

• ConsensusService - Provides information about consensus.
  • GetParams - Fetch the consensus parameters for a particular height.
  • GetCommit: Get commit results at the given height.
  • GetValidatorSet: Get validator set at the given height.

• NetworkService - Provides information about the blockchain network.
  • GetGenesis - Fetch paginated genesis data.
  • GetPeers - Fetch information about the peers to which the node is connected.

The PruningService was not part of the ADR-106, but ADR-101. Since it is a gRPC service, it is included here for tracking purposes.

• PruningService - provides privileged access to specialized pruning functionality on the CometBFT node to help control node storage.
  • SetBlockRetainHeight - Indicates to the node that it can safely prune all block data up to the specified retain height.
  • GetBlockRetainHeight - Returns information about the retain height parameters used by the node to influence block retention/pruning.
  • SetBlockResultsRetainHeight - Indicates to the node that it can safely prune all block results data up to the specified height.
  • GetBlockResultsRetainHeight - Returns information about the retain height parameters used by the node to influence block results retention/pruning.
  • SetTxIndexerRetainHeight - Indicates to the node that it can safely prune all tx indices up to the specified retain height.
  • GetTxIndexerRetainHeight - Returns information about the retain height parameters used by the node to influence TxIndexer pruning
  • SetBlockIndexerRetainHeight - Indicates to the node that it can safely prune all block indices up to the specified retain height.
  • GetBlockIndexerRetainHeight - Returns information about the retain height parameters used by the node to influence BlockIndexer pruning

• Implemented in:
  • ADR-101: Implement gRPC PruningService #1097 (all methods)
• Available on:
  • v1.x (alpha)
  • v0.38.x (experimental)

• PrivvalService -Allows communication with a signing backend

• Tracked by:
  • privval: Implement gRPC support #476

Definition of Done (DoD)

• All services (and its methods) of the list have been implemented