Skip to main content

​
Purpose and Scope

This document describes the RPC (Remote Procedure Call) server architecture and API layer of go-stablenet. It covers RPC endpoint configuration, available API namespaces, the backend abstraction layer, event filtering and subscriptions, and transaction submission mechanisms. The RPC layer provides an external interface for interacting with blockchain nodes via JSON-RPC over HTTP, WebSocket, or IPC transports. For information on P2P networking and protocol handlers, refer to Networking. For details on node initialization and lifecycle management, refer to Node Initialization and Lifecycle.

​
RPC Server Configuration

The node supports three RPC transport mechanisms: HTTP, WebSocket (WS), and Inter-Process Communication (IPC). Each transport can be independently enabled and configured via command-line flags or configuration files.

​
Transport Configuration

TransportEnable FlagAddress FlagPort FlagDefault Port
HTTP--http--http.addr--http.port8545
WebSocket--ws--ws.addr--ws.port8546
IPC(enabled by default)--ipcpathN/Agstable.ipc
Key Configuration Flags:
  • --http.api: Comma-separated list of API namespaces exposed over HTTP (e.g., “eth,net,web3”)
  • --ws.api: API namespaces for the WebSocket interface
  • --http.corsdomain: CORS domains for HTTP requests
  • --ws.origins: Allowed origins for WebSocket connections
  • --http.vhosts: Virtual hostnames allowed by the HTTP server
  • --ipcdisable: Disable the IPC-RPC server
Security and Limits:
  • --rpc.gascap: Gas cap for eth_call and eth_estimateGas (default: 50,000,000)
  • --rpc.evmtimeout: Execution timeout for eth_call (default: 5 seconds)
  • --rpc.txfeecap: Transaction fee cap in ether (default: 0, no cap)
  • --rpc.batch-request-limit: Maximum number of requests in a batch
  • --rpc.batch-response-max-size: Maximum response size in bytes for batch responses
  • --allow-insecure-unlock: Allow account unlocking over HTTP (disabled by default for security reasons)

​
RPC Server Initialization Flow

During node initialization, the RPC server follows these steps: parsing transport configuration, determining API namespaces, creating the Backend instance, initializing the RPC server, binding transport-specific listeners, and registering APIs.

​
Core API Namespaces

​
eth Namespace

The eth namespace provides the primary interface for blockchain state queries, transaction submission, and gas estimation.
MethodDescription
eth_chainIdReturns the chain ID
eth_blockNumberReturns the current block number
eth_getBalanceRetrieves account balance
eth_getStorageAtRetrieves a storage slot value
eth_getCodeRetrieves contract code
eth_getTransactionCountRetrieves account nonce
eth_callExecutes an EVM call without state changes
eth_estimateGasEstimates gas for a transaction
eth_sendRawTransactionSubmits a signed transaction
eth_gasPriceReturns a suggested legacy gas price
eth_maxPriorityFeePerGasReturns the EIP-1559 priority fee
eth_feeHistoryReturns fee history

​
txpool Namespace

The txpool namespace provides diagnostic APIs for inspecting the internal state of the transaction pool.

​
admin Namespace

The admin namespace provides node management functions, including peer management and RPC server control. This namespace should never be exposed on public RPC endpoints.

​
debug Namespace

The debug namespace provides advanced debugging features such as transaction tracing, state dumps, chain rewinding, and database diagnostics.

​
personal Namespace

The personal namespace provides local account-based signing functionality and is disabled by default for security reasons.

​
miner Namespace

The miner namespace provides block production, sealing control, and gas policy configuration functions.

​
net Namespace

The net namespace provides basic network information such as the network ID and peer connectivity status.

​
web3 Namespace

The web3 namespace provides auxiliary utility APIs such as client version (web3_clientVersion) and SHA3 hashing (web3_sha3).

​
istanbul Namespace

The istanbul namespace exposes RPCs from the Anzeon/WBFT consensus engine, providing consensus-related queries such as validators, block signers, and round statistics.

​
Event System and Filtering

The RPC filter system provides new block, log, and pending transaction events via polling-based filters or WebSocket-based subscriptions.

​
Log Filter Criteria Structure

type FilterCriteria struct {
    BlockHash *common.Hash
    FromBlock *big.Int
    ToBlock   *big.Int
    Addresses []common.Address
    Topics    [][]common.Hash
}

​
Summary

The go-stablenet RPC and API layer provides multi-transport support, a comprehensive set of namespaces, an efficient event system, flexible transaction submission mechanisms, and strong security controls. It maintains compatibility with the standard Ethereum JSON-RPC while integrating StableNet-specific features.