> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/rpc-and-apis/8.2-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