# Ethereum-compatible methods

AEREDIUM implements the standard Ethereum JSON-RPC. Behavior matches go-ethereum / reth where the spec is well-defined. AEREDIUM-specific differences are called out where relevant.

## Block

| Method                                      | Description                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| `eth_blockNumber`                           | Latest committed block number                                                 |
| `eth_getBlockByNumber(tag, fullTx)`         | Block by number or tag (`latest`, `finalized`, `safe`, `earliest`, `pending`) |
| `eth_getBlockByHash(hash, fullTx)`          | Block by hash                                                                 |
| `eth_getBlockTransactionCountByNumber(tag)` | Transaction count in a block                                                  |
| `eth_getBlockTransactionCountByHash(hash)`  | Transaction count in a block                                                  |
| `eth_getUncleCountByBlockNumber(tag)`       | Always returns `0x0` (no uncles on AEREDIUM)                                  |
| `eth_getUncleCountByBlockHash(hash)`        | Always returns `0x0`                                                          |

> AEREDIUM has 1-block finality, so `latest`, `finalized`, and `safe` always return the same block.

## Transaction

| Method                                              | Description                                                |
| --------------------------------------------------- | ---------------------------------------------------------- |
| `eth_sendRawTransaction(rawTx)`                     | Submit a signed transaction. Returns the transaction hash. |
| `eth_getTransactionByHash(hash)`                    | Transaction by hash                                        |
| `eth_getTransactionByBlockHashAndIndex(hash, idx)`  |                                                            |
| `eth_getTransactionByBlockNumberAndIndex(tag, idx)` |                                                            |
| `eth_getTransactionReceipt(hash)`                   | Receipt with status, logs, gas used, effective gas price   |
| `eth_getTransactionCount(addr, tag)`                | Account nonce                                              |

Receipts include the standard EVM fields plus `effectiveGasPrice`, `cumulativeGasUsed`, `logsBloom`, and `type` (0 = legacy, 2 = EIP-1559).

## Account & state

| Method                              | Description           |
| ----------------------------------- | --------------------- |
| `eth_getBalance(addr, tag)`         | Balance in wei        |
| `eth_getCode(addr, tag)`            | Contract bytecode     |
| `eth_getStorageAt(addr, slot, tag)` | Raw storage slot      |
| `eth_getProof(addr, slots, tag)`    | EIP-1186 Merkle proof |

## Execution

| Method                                       | Description                                                                   |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| `eth_call(callObject, tag, [stateOverride])` | Execute a call without sending a tx. Supports state overrides for simulation. |
| `eth_estimateGas(callObject, [tag])`         | Estimate gas required                                                         |
| `eth_createAccessList(callObject, tag)`      | EIP-2930 access list generation                                               |

## Gas & fees

| Method                                                 | Description                                              |
| ------------------------------------------------------ | -------------------------------------------------------- |
| `eth_gasPrice`                                         | Suggested legacy gas price                               |
| `eth_maxPriorityFeePerGas`                             | Suggested priority fee                                   |
| `eth_feeHistory(blockCount, newestBlock, percentiles)` | Historical base fees and percentile-bucket priority fees |

## Filters & logs

| Method                            | Description                            |
| --------------------------------- | -------------------------------------- |
| `eth_newFilter(filter)`           | Create a log filter, returns filter ID |
| `eth_newBlockFilter`              | Filter for new block hashes            |
| `eth_newPendingTransactionFilter` | Filter for new pending tx hashes       |
| `eth_uninstallFilter(id)`         | Remove a filter                        |
| `eth_getFilterChanges(id)`        | Drain new entries since the last poll  |
| `eth_getFilterLogs(id)`           | All logs matching the filter           |
| `eth_getLogs(filter)`             | Direct log query                       |

`eth_getLogs` queries spanning more than 10,000 blocks are rejected with `-32602`. Paginate by block range.

## Network status

| Method               | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `eth_chainId`        | `0x3e8` (1000)                                                                   |
| `eth_syncing`        | `false` if up to date, otherwise `{ startingBlock, currentBlock, highestBlock }` |
| `net_version`        | `"1000"`                                                                         |
| `net_listening`      | `true`                                                                           |
| `net_peerCount`      | Number of validator peers                                                        |
| `web3_clientVersion` | Identifier string, e.g. `"aeredium-api-gateway/v1.x.x"`                          |
| `web3_sha3(data)`    | Keccak-256 hash                                                                  |

## Debug & tracing

These methods are heavier and rate-limited more aggressively.

| Method                                       | Description                                          |
| -------------------------------------------- | ---------------------------------------------------- |
| `debug_traceTransaction(hash, [config])`     | Trace a transaction. Default tracer is `callTracer`. |
| `debug_traceCall(callObject, tag, [config])` | Trace an `eth_call`-style execution                  |
| `debug_traceBlockByNumber(tag, [config])`    | Trace every transaction in a block                   |
| `debug_traceBlockByHash(hash, [config])`     | Same, by block hash                                  |

Supported tracer types: `callTracer`, `prestateTracer`, `4byteTracer`, `structLog` (the default).

## Subscriptions (WebSocket only)

See [WebSocket subscriptions](/developer.aeredium.io/json-rpc-api/websocket.md).

## Methods we do **not** support

* `eth_sendTransaction` — the gateway never holds keys. Sign locally, send raw bytes via `eth_sendRawTransaction`.
* `eth_sign`, `eth_signTransaction`, `personal_*` — same reason.
* `eth_coinbase`, `eth_mining`, `eth_hashrate` — no proof-of-work on AEREDIUM.
* `eth_accounts` — returns `[]`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aeredium.gitbook.io/developer.aeredium.io/json-rpc-api/ethereum.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.