Skip to main content
Version: v3.7

gRPC

Erigon provides gRPC APIs that allow users to access blockchain data and services directly through protocol buffer interfaces. These APIs offer high-performance, strongly-typed access to Erigon's internal services and are particularly useful for applications requiring efficient data access or integration with other gRPC-based systems.

The gRPC server can be explicitly enabled using the --grpc flag when running the standalone rpcdaemon binary. This flag is not available on the main erigon binary — internal gRPC services for components like TxPool, Downloader, and Sentry start automatically on the --private.api.addr endpoint and do not require any additional flag.

Performance Considerations​

  • gRPC APIs provide better performance than JSON-RPC for high-throughput applications
  • Direct database access via the key-value (KV) interface offers the fastest data retrieval
  • Shared memory access (when running locally) provides optimal performance

Data Format and Buckets​

Database bucket names and their formats are documented in db/kv/tables.go. Understanding these structures is essential for effective use of the KV interface.

Network Access​

  • gRPC services can be accessed over the network when properly configured
  • TLS encryption is recommended for production deployments
  • Rate limiting can be configured via the --private.api.ratelimit flag

Integration Libraries​

Erigon provides Go, Rust, and C++ implementations of the RoKV (read-only key-value) interface for easy integration with applications.

Availability​

  • gRPC services are available when enabled with the --grpc flag on the standalone rpcdaemon binary
  • The default listening address is configurable via --grpc.addr and --grpc.port
  • Services require the main Erigon node to be running and accessible

For more information, visit the Erigon Interfaces GitHub repository.

KV (Key-Value) Interface​

The KV interface provides low-level database access methods for reading blockchain data directly from Erigon's MDBX database.

Interface Definition

The KV interface is defined in the remote protobuf specification and provides methods for:

  • Opening read-only transactions
  • Reading data by key ranges
  • Iterating over database buckets
  • Accessing historical state data

Example Usage

# Connect to gRPC endpoint
grpcurl -plaintext localhost:9090 remote.KV/Version

Available Methods

MethodDescription
VersionReturns the KV service API version
TxOpens a read-only transaction for data access
StateChangesStreams state changes for a block range
SnapshotsReturns information about available snapshots

ETHBACKEND Interface​

The ETHBACKEND interface provides access to Ethereum-specific backend services including block data, transaction information, and network status.

Available Services

ServiceDescription
EtherbaseReturns the coinbase address
NetVersionReturns the network ID
NetPeerCountReturns the number of connected peers
ProtocolVersionReturns the Ethereum protocol version
ClientVersionReturns the client version string
SubscribeSubscribes to blockchain events
NodeInfoReturns node information
PeersReturns information about connected peers
AddPeerAdds a peer to the node
PendingBlockReturns the pending block

TxPool Interface​

The TxPool interface provides access to transaction pool operations and status information.

Available Methods

MethodDescription
VersionReturns the TxPool service version
FindUnknownHashesFinds unknown transaction hashes
GetTransactionsRetrieves transactions from the pool
AllReturns all transactions in the pool
PendingAddAdds transactions to the pending pool
PendingRemoveRemoves transactions from the pending pool
OnAddSubscribes to transaction addition events
MiningReturns mining-related transaction data
NonceFromAddressGets the next nonce for an address

Downloader Interface​

The Downloader interface provides access to snapshot downloading and torrent management functionality.

Available Methods

MethodDescription
AddAdds files to the download queue
DeleteRemoves files from the download queue
CompletedChecks if downloads are completed
SetLogPrefixSets logging prefix for Downloader

Configuration and Security​

TLS Configuration​

Erigon supports TLS encryption for gRPC connections using certificate files:

./build/bin/rpcdaemon --grpc --tls.cert=/path/to/cert.pem --tls.key=/path/to/key.pem --tls.cacert=/path/to/ca.pem

Health Checks​

gRPC health checks can be enabled to monitor service availability:

./build/bin/rpcdaemon --grpc --grpc.healthcheck

Connection Examples​

Go Client Example

conn, err := grpc.Dial("localhost:9090", grpc.WithInsecure())
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := remote.NewKVClient(conn)
// Use client for database operations

Direct Database Access

The gRPC interface allows reading Erigon's database while the node is running, sharing the same OS-level PageCache for optimal performance.

Last updated on