Purpose and Scope
This document describes the JSON-RPC API architecture of StableNet, including available API namespaces, service implementations, and the backend abstraction layer that connects API services to core blockchain components.The API system provides external access to node functionality via HTTP, WebSocket, and IPC transports. For information on event filtering and subscriptions, refer to Event Filtering and Subscriptions.
API Architecture Overview
The StableNet RPC API follows a layered architecture in which API service implementations depend on aBackend interface.This design enables access to core blockchain functionality without tight coupling to the Ethereum backend.
API Namespace Structure
StableNet organizes its APIs into multiple namespaces, each with a clearly defined responsibility and purpose.Namespaces are registered via
internal/ethapi.GetAPIs, eth.Ethereum.APIs(), node-level apis(), and the consensus engine (WBFT) APIs(), and are exposed externally through the RPC handler.
API Namespace Mapping
| Namespace | Service Implementation | Purpose |
|---|---|---|
eth | EthereumAPI, BlockChainAPI, TransactionAPI, EthereumAccountAPI, DownloaderAPI | Core protocol, blocks, transactions, synchronization |
txpool | TxPoolAPI | Transaction pool inspection |
personal | PersonalAccountAPI | Password-based account management and fee-delegated signing |
debug | DebugAPI (ethapi·eth·node) | Debugging and diagnostics |
admin | AdminAPI (node·eth) | Node and peer management |
miner | MinerAPI | Block production control |
net | NetAPI | Network information |
web3 | web3API | Web3 utilities |
istanbul | WBFT API | WBFT consensus validators, signers, and status |
eth Namespace
Theeth namespace provides core Ethereum protocol functionality and is composed of multiple API service classes.
EthereumAPI Service
EthereumAPI handles network state and fee-related queries.
| Method | Description |
|---|---|
GasPrice() | Returns gas price for legacy transactions |
MaxPriorityFeePerGas() | Returns priority fee for EIP-1559 transactions |
FeeHistory() | Returns historical fee data |
Syncing() | Returns node synchronization status |
MaxPriorityFeePerGas does not use a gas price oracle and instead returns the gas tip value enforced by the GovValidator contract.
BlockChainAPI Service
BlockChainAPI provides interfaces for querying blockchain state and data.
| Method | Description | RPC Method |
|---|---|---|
ChainId() | Returns chain ID | eth_chainId |
BlockNumber() | Returns current block number | eth_blockNumber |
GetBalance() | Queries account balance | eth_getBalance |
GetCode() | Queries contract code | eth_getCode |
GetStorageAt() | Queries a storage slot | eth_getStorageAt |
GetProof() | Returns Merkle proof | eth_getProof |
GetBlockByNumber() | Fetch block by number | eth_getBlockByNumber |
GetBlockByHash() | Fetch block by hash | eth_getBlockByHash |
GetTransactionByHash() | Fetch transaction | eth_getTransactionByHash |
GetTransactionReceipt() | Fetch transaction receipt | eth_getTransactionReceipt |
TransactionAPI Service
TransactionAPI is responsible for transaction creation, signing, and submission.
| Method | Description | RPC Method |
|---|---|---|
SendTransaction() | Signs and submits a transaction | eth_sendTransaction |
SendRawTransaction() | Submits a signed transaction | eth_sendRawTransaction |
SignTransaction() | Signs a transaction only | eth_signTransaction |
FillTransaction() | Fills default transaction fields | eth_fillTransaction |
EstimateGas() | Estimates gas usage | eth_estimateGas |
Call() | Executes a call without state changes | eth_call |
txpool Namespace
TxPoolAPI provides read-only access to transaction pool state.
| Method | Description | RPC Method |
|---|---|---|
Content() | Lists all transactions in the pool | txpool_content |
ContentFrom() | Lists transactions for a specific address | txpool_contentFrom |
Status() | Returns pending/queued counts | txpool_status |
Inspect() | Human-readable summary | txpool_inspect |
- pending: Eligible for inclusion in the next block
- queued: Waiting due to nonce gaps or insufficient balance
personal Namespace
PersonalAccountAPI provides password-based account management.For security reasons, it is typically disabled on external RPC endpoints.
| Method | Description | RPC Method |
|---|---|---|
NewAccount() | Create a new account | personal_newAccount |
ListAccounts() | List accounts | personal_listAccounts |
UnlockAccount() | Unlock an account | personal_unlockAccount |
LockAccount() | Lock an account | personal_lockAccount |
SendTransaction() | Password-based transaction sending | personal_sendTransaction |
SignTransaction() | Password-based signing | personal_signTransaction |
Sign() | Sign arbitrary data | personal_sign |
ImportRawKey() | Import a private key | personal_importRawKey |
debug Namespace
DebugAPI provides advanced functionality for development and operational diagnostics.
Major Feature Categories
Transaction and Block TracingTraceTransaction()TraceBlock()TraceBlockByNumber()TraceBlockByHash()TraceCall()
DumpBlock()AccountRange()StorageRangeAt()
DbGet()DbAncient()ChaindbProperty()ChaindbCompact()
CpuProfile()BlockProfile()MemStats()GcStats()
web3 Namespace
web3API provides basic Web3 utility functions.
| Method | Description | RPC Method |
|---|---|---|
ClientVersion() | Returns client version | web3_clientVersion |
Sha3() | Computes Keccak-256 hash | web3_sha3 |
istanbul Namespace
Exposed only when WBFT consensus is enabled.| Method | Description | RPC Method |
|---|---|---|
NodeAddress() | Returns signer node address | istanbul_nodeAddress |
GetCommitSignersFromBlock() | Returns proposer and commit signers | istanbul_getCommitSignersFromBlock |
GetCommitSignersFromBlockByHash() | Query by block hash | istanbul_getCommitSignersFromBlockByHash |
GetValidators() | Returns validator list | istanbul_getValidators |
GetValidatorsAtHash() | Validators at a given hash | istanbul_getValidatorsAtHash |
Status() | Round and sealer statistics | istanbul_status |
StableNet Fee Delegation Extensions
For fee-delegated transactions, StableNet provides the following extended APIs in thepersonal and eth namespaces.
| RPC Method | Description |
|---|---|
personal_signRawFeeDelegateTransaction | Authenticates the fee payer using a password and appends a fee-payer signature to an already signed transaction, returning RLP-encoded bytes. |
eth_signRawFeeDelegateTransaction | Performs the same fee-delegation signing using an already unlocked fee-payer account. |
eth_sendRawTransaction, and gas costs are paid by the fee payer.
API Test Infrastructure
The codebase includes the following test infrastructure:- Unit tests based on a mock backend
- Genesis- and key-based integration tests
- RPC serialization and response validation tests