API Services and Namespaces

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 a Backend 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

The eth 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

In StableNet with Anzeon enabled, 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

Transactions are classified into two states:

• 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 Tracing

• TraceTransaction()
• TraceBlock()
• TraceBlockByNumber()
• TraceBlockByHash()
• TraceCall()

State Inspection

• DumpBlock()
• AccountRange()
• StorageRangeAt()

Database Management

• DbGet()
• DbAncient()
• ChaindbProperty()
• ChaindbCompact()

Profiling

• 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 the personal 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.

The resulting signed transaction is submitted via 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