From 6fe2dc18d312b83bd00346bc0639b4e4af8fbd43 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 17:40:21 +0800 Subject: [PATCH 01/13] docs: add complete public RPC reference --- AGENTS.md | 2 +- docs/AGENTS.md | 2 +- docs/SUMMARY.md | 52 +++++- docs/dev/read/overview.md | 162 ++++++++---------- docs/dev/read/realtime-api.md | 21 +-- docs/dev/read/rpc/README.md | 82 +++++++++ .../rpc/debug_getHistoryTransactionCount.md | 42 +++++ docs/dev/read/rpc/debug_getRawHeader.md | 81 +++++++++ docs/dev/read/rpc/debug_traceBlockByHash.md | 99 +++++++++++ docs/dev/read/rpc/debug_traceBlockByNumber.md | 94 ++++++++++ docs/dev/read/rpc/debug_traceTransaction.md | 91 ++++++++++ docs/dev/read/rpc/eth_accounts.md | 34 ++++ docs/dev/read/rpc/eth_blockNumber.md | 34 ++++ docs/dev/read/rpc/eth_call.md | 157 +++++++++++++++++ docs/dev/read/rpc/eth_callAfter.md | 123 ------------- docs/dev/read/rpc/eth_callMany.md | 99 +++++++++++ docs/dev/read/rpc/eth_chainId.md | 34 ++++ docs/dev/read/rpc/eth_createAccessList.md | 135 +++++++++++++++ docs/dev/read/rpc/eth_estimateGas.md | 120 +++++++++++++ docs/dev/read/rpc/eth_feeHistory.md | 86 ++++++++++ docs/dev/read/rpc/eth_gasPrice.md | 35 ++++ docs/dev/read/rpc/eth_getBalance.md | 49 ++++++ docs/dev/read/rpc/eth_getBlockByHash.md | 89 ++++++++++ docs/dev/read/rpc/eth_getBlockByNumber.md | 89 ++++++++++ docs/dev/read/rpc/eth_getBlockReceipts.md | 112 ++++++++++++ .../rpc/eth_getBlockTransactionCountByHash.md | 39 +++++ .../eth_getBlockTransactionCountByNumber.md | 39 +++++ docs/dev/read/rpc/eth_getCode.md | 48 ++++++ docs/dev/read/rpc/eth_getCodeByHash.md | 39 +++++ docs/dev/read/rpc/eth_getHeaderByHash.md | 78 +++++++++ docs/dev/read/rpc/eth_getHeaderByNumber.md | 78 +++++++++ docs/dev/read/rpc/eth_getLogs.md | 116 +++++++++++++ docs/dev/read/rpc/eth_getLogsWithCursor.md | 128 -------------- docs/dev/read/rpc/eth_getStorageAt.md | 58 +++++++ docs/dev/read/rpc/eth_getTransactionByHash.md | 98 +++++++++++ docs/dev/read/rpc/eth_getTransactionCount.md | 49 ++++++ .../dev/read/rpc/eth_getTransactionReceipt.md | 95 ++++++++++ .../rpc/eth_getUncleByBlockHashAndIndex.md | 82 +++++++++ .../rpc/eth_getUncleByBlockNumberAndIndex.md | 79 +++++++++ .../read/rpc/eth_getUncleCountByBlockHash.md | 81 +++++++++ .../rpc/eth_getUncleCountByBlockNumber.md | 79 +++++++++ docs/dev/read/rpc/eth_getWithdrawalProof.md | 35 ++++ docs/dev/read/rpc/eth_maxPriorityFeePerGas.md | 35 ++++ docs/dev/read/rpc/eth_protocolVersion.md | 76 ++++++++ docs/dev/read/rpc/eth_sendRawTransaction.md | 46 +++++ .../read/rpc/eth_sendRawTransactionSync.md | 117 +++++++++++++ docs/dev/read/rpc/eth_syncing.md | 62 +++++++ docs/dev/read/rpc/eth_unsubscribe.md | 39 +++++ docs/dev/read/rpc/mega_getBlockWitness.md | 56 ++++++ docs/dev/read/rpc/mega_getWithdrawalProof.md | 90 ++++++++++ docs/dev/read/rpc/mega_outputAtBlock.md | 110 ++++++++++++ docs/dev/read/rpc/net_listening.md | 34 ++++ docs/dev/read/rpc/net_peerCount.md | 34 ++++ docs/dev/read/rpc/net_version.md | 34 ++++ docs/dev/read/rpc/optimism_outputAtBlock.md | 34 ++++ .../read/rpc/realtime_sendRawTransaction.md | 18 +- docs/dev/read/rpc/web3_clientVersion.md | 38 ++++ lychee.toml | 2 +- 58 files changed, 3593 insertions(+), 377 deletions(-) create mode 100644 docs/dev/read/rpc/README.md create mode 100644 docs/dev/read/rpc/debug_getHistoryTransactionCount.md create mode 100644 docs/dev/read/rpc/debug_getRawHeader.md create mode 100644 docs/dev/read/rpc/debug_traceBlockByHash.md create mode 100644 docs/dev/read/rpc/debug_traceBlockByNumber.md create mode 100644 docs/dev/read/rpc/debug_traceTransaction.md create mode 100644 docs/dev/read/rpc/eth_accounts.md create mode 100644 docs/dev/read/rpc/eth_blockNumber.md create mode 100644 docs/dev/read/rpc/eth_call.md delete mode 100644 docs/dev/read/rpc/eth_callAfter.md create mode 100644 docs/dev/read/rpc/eth_callMany.md create mode 100644 docs/dev/read/rpc/eth_chainId.md create mode 100644 docs/dev/read/rpc/eth_createAccessList.md create mode 100644 docs/dev/read/rpc/eth_estimateGas.md create mode 100644 docs/dev/read/rpc/eth_feeHistory.md create mode 100644 docs/dev/read/rpc/eth_gasPrice.md create mode 100644 docs/dev/read/rpc/eth_getBalance.md create mode 100644 docs/dev/read/rpc/eth_getBlockByHash.md create mode 100644 docs/dev/read/rpc/eth_getBlockByNumber.md create mode 100644 docs/dev/read/rpc/eth_getBlockReceipts.md create mode 100644 docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md create mode 100644 docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md create mode 100644 docs/dev/read/rpc/eth_getCode.md create mode 100644 docs/dev/read/rpc/eth_getCodeByHash.md create mode 100644 docs/dev/read/rpc/eth_getHeaderByHash.md create mode 100644 docs/dev/read/rpc/eth_getHeaderByNumber.md create mode 100644 docs/dev/read/rpc/eth_getLogs.md delete mode 100644 docs/dev/read/rpc/eth_getLogsWithCursor.md create mode 100644 docs/dev/read/rpc/eth_getStorageAt.md create mode 100644 docs/dev/read/rpc/eth_getTransactionByHash.md create mode 100644 docs/dev/read/rpc/eth_getTransactionCount.md create mode 100644 docs/dev/read/rpc/eth_getTransactionReceipt.md create mode 100644 docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md create mode 100644 docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md create mode 100644 docs/dev/read/rpc/eth_getUncleCountByBlockHash.md create mode 100644 docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md create mode 100644 docs/dev/read/rpc/eth_getWithdrawalProof.md create mode 100644 docs/dev/read/rpc/eth_maxPriorityFeePerGas.md create mode 100644 docs/dev/read/rpc/eth_protocolVersion.md create mode 100644 docs/dev/read/rpc/eth_sendRawTransaction.md create mode 100644 docs/dev/read/rpc/eth_sendRawTransactionSync.md create mode 100644 docs/dev/read/rpc/eth_syncing.md create mode 100644 docs/dev/read/rpc/eth_unsubscribe.md create mode 100644 docs/dev/read/rpc/mega_getBlockWitness.md create mode 100644 docs/dev/read/rpc/mega_getWithdrawalProof.md create mode 100644 docs/dev/read/rpc/mega_outputAtBlock.md create mode 100644 docs/dev/read/rpc/net_listening.md create mode 100644 docs/dev/read/rpc/net_peerCount.md create mode 100644 docs/dev/read/rpc/net_version.md create mode 100644 docs/dev/read/rpc/optimism_outputAtBlock.md create mode 100644 docs/dev/read/rpc/web3_clientVersion.md diff --git a/AGENTS.md b/AGENTS.md index 0838fff..63b0beb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This file provides guidance to AI agents (e.g., Claude Code, Codex, Cursor, etc. MegaETH Documentation — the official documentation site for MegaETH, hosted at [docs.megaeth.com](https://docs.megaeth.com). Documentation is written in GitBook-flavored Markdown and deployed via GitBook with Git Sync. -For GitBook syntax, custom blocks, configuration, and best practices, follow the [official GitBook skill file](https://raw.githubusercontent.com/GitbookIO/public-docs/refs/heads/main/skill.md). +For GitBook syntax, custom blocks, configuration, and best practices, follow the [official GitBook `write-docs` skill](https://raw.githubusercontent.com/GitBookIO/gitbook-skills/main/skills/write-docs/SKILL.md). ## Documentation Architecture diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 4159284..b4aa3b9 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -84,7 +84,7 @@ Use these exact forms consistently. Do not alternate between variants. ## Formatting -- **GitBook Markdown**: Use GitBook-flavored Markdown with custom blocks. See `/skill.md` for full syntax reference. +- **GitBook Markdown**: Use GitBook-flavored Markdown with custom blocks. Follow the [official GitBook `write-docs` skill](https://raw.githubusercontent.com/GitBookIO/gitbook-skills/main/skills/write-docs/SKILL.md) for the full syntax reference. - **One sentence, one line**: Each sentence goes on its own line for better diffs. - **Frontmatter**: Every page must have YAML frontmatter with at least `description` for SEO. - **Headings**: Use `#` for the page title (H1), `##` for sections (H2), `###` for subsections (H3). One H1 per page. Use sentence case: "Gas forwarding rules" not "Gas Forwarding Rules." Capitalize only proper nouns (MegaETH, Ethereum, Rex4). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 8c421a3..009c955 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -25,11 +25,57 @@ - [Force Inclusion — Foundry](dev/send-tx/force-inclusion.md) - [Read from MegaETH](dev/read/overview.md) - [Realtime API](dev/read/realtime-api.md) - - RPC Reference + - [RPC Reference](dev/read/rpc/README.md) + - [debug_getHistoryTransactionCount](dev/read/rpc/debug_getHistoryTransactionCount.md) + - [debug_getRawHeader](dev/read/rpc/debug_getRawHeader.md) + - [debug_traceBlockByHash](dev/read/rpc/debug_traceBlockByHash.md) + - [debug_traceBlockByNumber](dev/read/rpc/debug_traceBlockByNumber.md) + - [debug_traceTransaction](dev/read/rpc/debug_traceTransaction.md) + - [eth_accounts](dev/read/rpc/eth_accounts.md) + - [eth_blockNumber](dev/read/rpc/eth_blockNumber.md) + - [eth_call](dev/read/rpc/eth_call.md) + - [eth_callMany](dev/read/rpc/eth_callMany.md) + - [eth_chainId](dev/read/rpc/eth_chainId.md) + - [eth_createAccessList](dev/read/rpc/eth_createAccessList.md) + - [eth_estimateGas](dev/read/rpc/eth_estimateGas.md) + - [eth_feeHistory](dev/read/rpc/eth_feeHistory.md) + - [eth_gasPrice](dev/read/rpc/eth_gasPrice.md) + - [eth_getBalance](dev/read/rpc/eth_getBalance.md) + - [eth_getBlockByHash](dev/read/rpc/eth_getBlockByHash.md) + - [eth_getBlockByNumber](dev/read/rpc/eth_getBlockByNumber.md) + - [eth_getBlockReceipts](dev/read/rpc/eth_getBlockReceipts.md) + - [eth_getBlockTransactionCountByHash](dev/read/rpc/eth_getBlockTransactionCountByHash.md) + - [eth_getBlockTransactionCountByNumber](dev/read/rpc/eth_getBlockTransactionCountByNumber.md) + - [eth_getCode](dev/read/rpc/eth_getCode.md) + - [eth_getCodeByHash](dev/read/rpc/eth_getCodeByHash.md) + - [eth_getHeaderByHash](dev/read/rpc/eth_getHeaderByHash.md) + - [eth_getHeaderByNumber](dev/read/rpc/eth_getHeaderByNumber.md) + - [eth_getLogs](dev/read/rpc/eth_getLogs.md) + - [eth_getStorageAt](dev/read/rpc/eth_getStorageAt.md) + - [eth_getTransactionByHash](dev/read/rpc/eth_getTransactionByHash.md) + - [eth_getTransactionCount](dev/read/rpc/eth_getTransactionCount.md) + - [eth_getTransactionReceipt](dev/read/rpc/eth_getTransactionReceipt.md) + - [eth_getUncleByBlockHashAndIndex](dev/read/rpc/eth_getUncleByBlockHashAndIndex.md) + - [eth_getUncleByBlockNumberAndIndex](dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md) + - [eth_getUncleCountByBlockHash](dev/read/rpc/eth_getUncleCountByBlockHash.md) + - [eth_getUncleCountByBlockNumber](dev/read/rpc/eth_getUncleCountByBlockNumber.md) + - [eth_getWithdrawalProof](dev/read/rpc/eth_getWithdrawalProof.md) + - [eth_maxPriorityFeePerGas](dev/read/rpc/eth_maxPriorityFeePerGas.md) + - [eth_protocolVersion](dev/read/rpc/eth_protocolVersion.md) + - [eth_sendRawTransaction](dev/read/rpc/eth_sendRawTransaction.md) + - [eth_sendRawTransactionSync](dev/read/rpc/eth_sendRawTransactionSync.md) - [eth_subscribe](dev/read/rpc/eth_subscribe.md) - - [eth_callAfter](dev/read/rpc/eth_callAfter.md) - - [eth_getLogsWithCursor](dev/read/rpc/eth_getLogsWithCursor.md) + - [eth_syncing](dev/read/rpc/eth_syncing.md) + - [eth_unsubscribe](dev/read/rpc/eth_unsubscribe.md) + - [mega_getBlockWitness](dev/read/rpc/mega_getBlockWitness.md) + - [mega_getWithdrawalProof](dev/read/rpc/mega_getWithdrawalProof.md) + - [mega_outputAtBlock](dev/read/rpc/mega_outputAtBlock.md) + - [net_listening](dev/read/rpc/net_listening.md) + - [net_peerCount](dev/read/rpc/net_peerCount.md) + - [net_version](dev/read/rpc/net_version.md) + - [optimism_outputAtBlock](dev/read/rpc/optimism_outputAtBlock.md) - [realtime_sendRawTransaction](dev/read/rpc/realtime_sendRawTransaction.md) + - [web3_clientVersion](dev/read/rpc/web3_clientVersion.md) - [Error Codes](dev/read/rpc/error-codes.md) - [Transaction Execution](dev/execution/overview.md) - [Gas Model](dev/execution/gas-model.md) diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 067a5b1..2c99041 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -14,100 +14,82 @@ If the read API still operated on one-second EVM blocks, applications would wait The Realtime API closes this gap: it queries against the most recent mini-block so that balances, receipts, logs, and state changes are visible within milliseconds of execution — not seconds. Standard methods like `eth_getBalance`, `eth_call`, and `eth_getTransactionReceipt` already reflect mini-block state automatically when called with `latest` or `pending`. -On top of that, MegaETH introduces four extension methods for even lower-latency workflows: +On top of that, MegaETH exposes two public extension paths for lower-latency workflows: - [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) — submit a transaction and get the receipt back in one call, no polling - [`eth_subscribe`](rpc/eth_subscribe.md) — stream logs, state changes, mini-blocks, and block headers over WebSocket as they happen -- [`eth_callAfter`](rpc/eth_callAfter.md) — simulate a transaction after a prior one confirms (nonce-gated) -- [`eth_getLogsWithCursor`](rpc/eth_getLogsWithCursor.md) — paginated log queries for large result sets For use-case-oriented guidance (which method to use for what), see the [Realtime API](realtime-api.md) page. ## Available Methods {% hint style="info" %} -The table below reflects the **public MegaETH RPC endpoint**. -Methods marked "Managed only" are unavailable on the public endpoint but supported by managed RPC providers such as [Alchemy](https://www.alchemy.com/). -See [Debugging Transactions](../send-tx/debugging.md) for usage of debug methods, and [Tooling](../tooling.md#rpc-providers) for provider options. +The table below reflects the public MegaETH Mainnet endpoint as verified on July 24, 2026. +"Unavailable" includes methods recognized by the gateway but disabled or unimplemented upstream. +Managed providers may expose additional methods. {% endhint %} -| Method | Availability | Additional Restrictions | -| ----------------------------------------- | -------------- | ----------------------------------------------------------------- | -| `debug_getRawBlock` | Managed only | | -| `debug_getRawHeader` | Available | | -| `debug_getRawReceipts` | Managed only | | -| `debug_getRawTransaction` | Managed only | | -| `debug_replayBlock` | Managed only | | -| `debug_traceBlock` | Managed only | | -| `debug_traceBlockByHash` | Available | | -| `debug_traceBlockByNumber` | Available | | -| `debug_traceCall` | Available | | -| `debug_traceCallMany` | Managed only | | -| `debug_traceTransaction` | Available | | -| `eth_accounts` | Available | | -| `eth_blockNumber` | Available | | -| `eth_call` | Available | Compute gas limited to 60,000,000. | -| `eth_callAfter` | Available | Compute gas limited to 60,000,000. Timeout limited to 60 seconds. | -| `eth_callMany` | Available | Compute gas limited to 60,000,000 per call. | -| `eth_chainId` | Available | | -| `eth_createAccessList` | Available | Compute gas limited to 60,000,000. | -| `eth_estimateGas` | Available | Compute gas limited to 60,000,000. | -| `eth_feeHistory` | Available | Block range limited to 256. | -| `eth_gasPrice` | Available | | -| `eth_getBalance` | Available | | -| `eth_getBlockByHash` | Available | | -| `eth_getBlockByNumber` | Available | | -| `eth_getBlockReceipts` | Available | | -| `eth_getBlockTransactionCountByHash` | Available | | -| `eth_getBlockTransactionCountByNumber` | Available | | -| `eth_getCode` | Available | | -| `eth_getFilterChanges` | Unavailable | | -| `eth_getFilterLogs` | Unavailable | | -| `eth_getHeaderByNumber` | Available | | -| `eth_getLogs` | Available | | -| `eth_getLogsWithCursor` | Managed only | | -| `eth_getStorageAt` | Available | | -| `eth_getTransactionByBlockHashAndIndex` | Available | | -| `eth_getTransactionByBlockNumberAndIndex` | Available | | -| `eth_getTransactionByHash` | Available | | -| `eth_getTransactionCount` | Available | | -| `eth_getTransactionReceipt` | Available | | -| `eth_getUncleByBlockHashAndIndex` | Available | | -| `eth_getUncleByBlockNumberAndIndex` | Available | | -| `eth_getUncleCountByBlockHash` | Available | | -| `eth_getUncleCountByBlockNumber` | Available | | -| `eth_maxPriorityFeePerGas` | Available | | -| `eth_mining` | Available | | -| `eth_newBlockFilter` | Available | | -| `eth_newFilter` | Available | | -| `eth_newPendingTransactionFilter` | Available | | -| `eth_protocolVersion` | Available | | -| `eth_sendRawTransaction` | Available | | -| `eth_sendTransaction` | Unavailable | Use `eth_sendRawTransaction` with a signed transaction. | -| `eth_sign` | Unavailable | Sign client-side. | -| `eth_signTransaction` | Unavailable | Sign client-side. | -| `eth_signTypedData` | Unavailable | Sign client-side. | -| `eth_subscribe` | WebSocket only | | -| `eth_syncing` | Available | | -| `eth_uninstallFilter` | Available | | -| `eth_unsubscribe` | WebSocket only | | -| `net_listening` | Available | | -| `net_peerCount` | Available | | -| `net_version` | Available | | -| `realtime_sendRawTransaction` | Available | | -| `trace_block` | Available | | -| `trace_call` | Available | | -| `trace_callMany` | Managed only | | -| `trace_get` | Managed only | | -| `trace_rawTransaction` | Managed only | | -| `trace_replayBlockTransactions` | Managed only | | -| `trace_replayTransaction` | Managed only | | -| `trace_transaction` | Available | | -| `txpool_content` | Unavailable | | -| `txpool_contentFrom` | Unavailable | | -| `txpool_inspect` | Unavailable | | -| `txpool_status` | Unavailable | | -| `web3_clientVersion` | Available | | +| Method | Availability | Additional restrictions or behavior | +| ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | +| `debug_getHistoryTransactionCount` | Available | MegaETH-specific. | +| `debug_getRawHeader` | Available | | +| `debug_traceBlockByHash` | Available | Large responses are streamed. | +| `debug_traceBlockByNumber` | Available | Large responses are streamed. | +| `debug_traceCall` | Unavailable | The public endpoint returns `-32601`. | +| `debug_traceTransaction` | Available | Large responses are streamed. | +| `eth_accounts` | Available | Returns an empty array because the gateway does not manage user keys. | +| `eth_blockNumber` | Available | | +| `eth_call` | Available | Compute gas limited to 60,000,000. | +| `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | +| `eth_chainId` | Available | | +| `eth_createAccessList` | Available | Compute gas limited to 60,000,000. | +| `eth_estimateGas` | Available | Compute gas limited to 60,000,000. | +| `eth_feeHistory` | Available | Block range limited to 256. | +| `eth_gasPrice` | Available | | +| `eth_getBalance` | Available | | +| `eth_getBlockByHash` | Available | | +| `eth_getBlockByNumber` | Available | | +| `eth_getBlockReceipts` | Available | | +| `eth_getBlockTransactionCountByHash` | Available | | +| `eth_getBlockTransactionCountByNumber` | Available | | +| `eth_getCode` | Available | | +| `eth_getCodeByHash` | Available | MegaETH-specific. | +| `eth_getHeaderByHash` | Available | MegaETH-specific. | +| `eth_getHeaderByNumber` | Available | MegaETH-specific. | +| `eth_getLogs` | Available | | +| `eth_getLogsWithCursor` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getStorageAt` | Available | | +| `eth_getTransactionByBlockHashAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByBlockNumberAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByHash` | Available | | +| `eth_getTransactionCount` | Available | | +| `eth_getTransactionReceipt` | Available | | +| `eth_getUncleByBlockHashAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleByBlockNumberAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockHash` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockNumber` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | +| `eth_maxPriorityFeePerGas` | Available | | +| `eth_mining` | Unavailable | The node reports the method as unimplemented. | +| `eth_protocolVersion` | Available | Legacy compatibility method. | +| `eth_sendRawTransaction` | Available | | +| `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | +| `eth_subscribe` | WebSocket only | Supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`. | +| `eth_syncing` | Available | | +| `eth_unsubscribe` | WebSocket only | | +| `mega_getBlockWitness` | Available | MegaETH-specific. | +| `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | +| `mega_outputAtBlock` | Available | OP Stack output-root method. | +| `net_listening` | Available | | +| `net_peerCount` | Available | | +| `net_version` | Available | | +| `optimism_outputAtBlock` | Available | Alias of `mega_outputAtBlock`. | +| `realtime_sendRawTransaction` | Available | MegaETH-specific synchronous receipt method. | +| `trace_block` | Unavailable | The public endpoint returns `-32601`. | +| `trace_call` | Unavailable | The public endpoint returns `-32601`. | +| `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | +| `web3_clientVersion` | Available | | ## Rate Limiting @@ -133,15 +115,9 @@ A request whose body exceeds the applicable limit is rejected with HTTP `413` an ## Response Caching -The public RPC gateway may serve a small set of read methods from a server-side cache inside the gateway itself, rather than forwarding every request to a node: - -- `eth_getBlockByNumber` -- `eth_getBlockReceipts` -- `eth_getHeaderByNumber` -- `web3_clientVersion` - -Only requests for **immutable data** are eligible: an explicit historical block number, a block hash, or the `earliest` tag. -Requests using the `latest`, `pending`, `safe`, or `finalized` tags always go to a node, so cached responses are never stale — the realtime behavior described above is unaffected. +The public RPC gateway may serve read methods from an internal server-side cache rather than forwarding every request to a node. +Eligibility and lifetime are method-specific: immutable block numbers and hashes can use longer-lived entries, while methods that follow the chain head either use a short-lived cache or bypass it. +Do not assume that two different methods or block tags have the same cache policy. Two headers on the response are relevant: @@ -152,7 +128,7 @@ Two headers on the response are relevant: Use it to understand where a response came from; it has no effect on correctness. Sending `Cache-Control: no-store` or `no-cache` as a _request_ header does not bypass the internal cache — request cache directives address intermediary caches, not the origin's own caching. -Because only immutable data is cached, there is never a reason to bypass it. +The gateway does not provide a request option that bypasses its internal cache. ## Related Pages diff --git a/docs/dev/read/realtime-api.md b/docs/dev/read/realtime-api.md index f666c5d..3e2d32c 100644 --- a/docs/dev/read/realtime-api.md +++ b/docs/dev/read/realtime-api.md @@ -22,8 +22,6 @@ Additional functionality will be added based on feedback. | ------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- | | [`eth_subscribe`](rpc/eth_subscribe.md) | Stream logs, state changes, mini-blocks, and block headers over WebSocket | [Full reference](rpc/eth_subscribe.md) | | [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) | Submit a transaction and get the receipt back in one call — no polling | [Full reference](rpc/realtime_sendRawTransaction.md) | -| [`eth_callAfter`](rpc/eth_callAfter.md) | Run `eth_call` after a prior transaction confirms (nonce-gated) | [Full reference](rpc/eth_callAfter.md) | -| [`eth_getLogsWithCursor`](rpc/eth_getLogsWithCursor.md) | Paginated log queries for large result sets | [Full reference](rpc/eth_getLogsWithCursor.md) | The following standard Ethereum methods also return real-time results on MegaETH — they query against the latest mini-block automatically when called with `latest` or `pending`: @@ -47,7 +45,8 @@ The following standard Ethereum methods also return real-time results on MegaETH **Problem:** Your dapp submits a transaction and needs the receipt immediately — polling `eth_getTransactionReceipt` adds latency and complexity. **Solution:** Use [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md). -It submits the transaction and blocks until the receipt is available (up to 10 seconds), returning it in a single round-trip. +It submits the transaction and waits for the receipt in a single round-trip. +The node's default wait is 5 seconds; an explicit timeout is capped at 3 seconds by the public gateway. Drop-in replacement for `eth_sendRawTransaction`. ### Streaming events for a live UI @@ -72,22 +71,6 @@ Each notification includes the updated balance, nonce, and any storage slots tha **Solution:** Subscribe to [`miniBlocks`](rpc/eth_subscribe.md#miniblocks). Each notification contains the full set of transactions and receipts for that mini-block. -### Chaining dependent transactions - -**Problem:** You send an approval transaction and then need to simulate the follow-up swap — but `eth_call` might execute before the approval confirms. - -**Solution:** Use [`eth_callAfter`](rpc/eth_callAfter.md). -It waits for the sender's nonce to reach a target value (indicating the prior transaction has confirmed), then executes the call. -This avoids race conditions between approval and swap simulation. - -### Querying large log ranges - -**Problem:** `eth_getLogs` fails or times out when the block range is too large. - -**Solution:** Use [`eth_getLogsWithCursor`](rpc/eth_getLogsWithCursor.md). -When the server hits its resource limit, it returns a partial result with a cursor. -Pass the cursor in the next request to continue from where you left off. - ## How It Works On standard EVM chains, query methods reflect state as of the most recent EVM block (produced every ~1 second on MegaETH, longer on other chains). diff --git a/docs/dev/read/rpc/README.md b/docs/dev/read/rpc/README.md new file mode 100644 index 0000000..cae7162 --- /dev/null +++ b/docs/dev/read/rpc/README.md @@ -0,0 +1,82 @@ +--- +description: "Complete reference for the 50 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." +--- + +# RPC Reference + +The public MegaETH gateway exposes 48 HTTP methods and two WebSocket subscription methods. +This reference is based on the gateway registry, node implementation, and public Mainnet behavior verified on July 24, 2026. + +Use the [availability table](../overview.md#available-methods) for recognized methods that are disabled on the public endpoint and for methods offered only by managed providers. +See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. + +## State and simulation + +- [`eth_accounts`](./eth_accounts.md) +- [`eth_call`](./eth_call.md) +- [`eth_callMany`](./eth_callMany.md) +- [`eth_createAccessList`](./eth_createAccessList.md) +- [`eth_estimateGas`](./eth_estimateGas.md) +- [`eth_getBalance`](./eth_getBalance.md) +- [`eth_getCode`](./eth_getCode.md) +- [`eth_getCodeByHash`](./eth_getCodeByHash.md) +- [`eth_getStorageAt`](./eth_getStorageAt.md) +- [`eth_getTransactionCount`](./eth_getTransactionCount.md) + +## Blocks, transactions, and receipts + +- [`eth_blockNumber`](./eth_blockNumber.md) +- [`eth_getBlockByHash`](./eth_getBlockByHash.md) +- [`eth_getBlockByNumber`](./eth_getBlockByNumber.md) +- [`eth_getBlockReceipts`](./eth_getBlockReceipts.md) +- [`eth_getBlockTransactionCountByHash`](./eth_getBlockTransactionCountByHash.md) +- [`eth_getBlockTransactionCountByNumber`](./eth_getBlockTransactionCountByNumber.md) +- [`eth_getHeaderByHash`](./eth_getHeaderByHash.md) +- [`eth_getHeaderByNumber`](./eth_getHeaderByNumber.md) +- [`eth_getTransactionByHash`](./eth_getTransactionByHash.md) +- [`eth_getTransactionReceipt`](./eth_getTransactionReceipt.md) +- [`eth_getUncleByBlockHashAndIndex`](./eth_getUncleByBlockHashAndIndex.md) +- [`eth_getUncleByBlockNumberAndIndex`](./eth_getUncleByBlockNumberAndIndex.md) +- [`eth_getUncleCountByBlockHash`](./eth_getUncleCountByBlockHash.md) +- [`eth_getUncleCountByBlockNumber`](./eth_getUncleCountByBlockNumber.md) +- [`eth_syncing`](./eth_syncing.md) + +## Logs and subscriptions + +- [`eth_getLogs`](./eth_getLogs.md) +- [`eth_subscribe`](./eth_subscribe.md) — WebSocket only +- [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only + +## Fees and transaction submission + +- [`eth_feeHistory`](./eth_feeHistory.md) +- [`eth_gasPrice`](./eth_gasPrice.md) +- [`eth_maxPriorityFeePerGas`](./eth_maxPriorityFeePerGas.md) +- [`eth_sendRawTransaction`](./eth_sendRawTransaction.md) +- [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) +- [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) + +## Debug methods + +- [`debug_getHistoryTransactionCount`](./debug_getHistoryTransactionCount.md) +- [`debug_getRawHeader`](./debug_getRawHeader.md) +- [`debug_traceBlockByHash`](./debug_traceBlockByHash.md) +- [`debug_traceBlockByNumber`](./debug_traceBlockByNumber.md) +- [`debug_traceTransaction`](./debug_traceTransaction.md) + +## MegaETH and OP Stack methods + +- [`eth_getWithdrawalProof`](./eth_getWithdrawalProof.md) +- [`mega_getBlockWitness`](./mega_getBlockWitness.md) +- [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md) +- [`mega_outputAtBlock`](./mega_outputAtBlock.md) +- [`optimism_outputAtBlock`](./optimism_outputAtBlock.md) + +## Network and client information + +- [`eth_chainId`](./eth_chainId.md) +- [`eth_protocolVersion`](./eth_protocolVersion.md) +- [`net_listening`](./net_listening.md) +- [`net_peerCount`](./net_peerCount.md) +- [`net_version`](./net_version.md) +- [`web3_clientVersion`](./web3_clientVersion.md) diff --git a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md new file mode 100644 index 0000000..c879f6a --- /dev/null +++ b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md @@ -0,0 +1,42 @@ +--- +description: "debug_getHistoryTransactionCount JSON-RPC reference for MegaETH." +--- + +# debug_getHistoryTransactionCount + +Returns the chain-wide cumulative transaction count up to and including a given block. + +## Parameters + +**`block`** string **REQUIRED** + +Hex block number or tag (`earliest`, `latest`, `safe`, `finalized`). +`pending` is not supported. + +## Returns + +**`result`** Quantity + +Cumulative transaction count across all blocks up to the selected block. +Consecutive blocks with no transactions return the same value. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------- | --------------- | +| `-32001` | Block selector cannot be resolved or unsupported tag such as `pending` was used | Fix the request | +| `-32602` | Invalid parameter shape | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"debug_getHistoryTransactionCount","params":["0x12a05f"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 1, "result": "0x12cbab" } // 1,231,787 total transactions through block 1,220,703 +``` diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/read/rpc/debug_getRawHeader.md new file mode 100644 index 0000000..d979a18 --- /dev/null +++ b/docs/dev/read/rpc/debug_getRawHeader.md @@ -0,0 +1,81 @@ +--- +description: "Returns the RLP-encoded header for a MegaETH block." +--- + +# debug_getRawHeader + +## Summary + +Returns a block header encoded with Recursive Length Prefix (RLP). +The public MegaETH endpoint supports this standard debug method. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------- | ----------------------- | -------- | ------------------------------------------------------------------------ | +| `0` | `block` | `QUANTITY` or block tag | Yes | Block number or `latest`, `safe`, `finalized`, `earliest`, or `pending`. | + +## Result + +The result is a `DATA` value containing the RLP-encoded header. +Decode the bytes as an Ethereum block header rather than treating them as a JSON block object. + +## MegaETH Behavior + +### Ethereum Standard + +The method returns the canonical RLP representation of the selected block header. + +### MegaETH Node Behavior + +MegaETH exposes the method through its debug namespace and accepts a block number or tag. +The encoded header includes the fields used by the selected MegaETH hardfork. + +### MegaETH Public Gateway + +The public gateway forwards this method through its compute pool and may cache immutable block selections. +Support and a successful historical lookup were observed on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Method | Invalid params | The block selector is missing or malformed. | +| `-32000` | Method | Server error | The block is unavailable or cannot be encoded. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_getRawHeader", + "params": ["0x1"] +} +``` + +The RLP value is abbreviated below. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf9026ba09425ed45fa0843e257166258f69bced9ef9eb2d0bb23c6b5a901fba3…" +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs, `src/debug/getters.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/getters.yaml) +- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/read/rpc/debug_traceBlockByHash.md new file mode 100644 index 0000000..ba24420 --- /dev/null +++ b/docs/dev/read/rpc/debug_traceBlockByHash.md @@ -0,0 +1,99 @@ +--- +description: "Replays every transaction in a MegaETH block selected by hash and returns execution traces." +--- + +# debug_traceBlockByHash + +## Summary + +Replays a block selected by hash and returns one execution trace per transaction. +The public MegaETH endpoint supports this standard debug method. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------------- | ---------------- | ------------------------- | ----------------------------------------------------------------------------- | +| `0` | `blockHash` | `DATA`, 32 bytes | Yes | Hash of the block to replay. | +| `1` | `traceConfig` | object | Yes on the public gateway | Tracer selection and tracer-specific options. Use `{}` for the opcode tracer. | + +Common `traceConfig` fields include `tracer`, `tracerConfig`, and `timeout`. +For example, set `tracer` to `"callTracer"` for a nested call frame instead of opcode-level `structLogs`. + +## Result + +The result is an array ordered by transaction index. +Each entry contains `txHash` and either `result` or `error`; the shape of `result` depends on the selected tracer. + +## MegaETH Behavior + +### Ethereum Standard + +The method replays all transactions in the selected block against its parent state. +The genesis block cannot be replayed because it has no parent state. + +### MegaETH Node Behavior + +MegaETH uses the standard geth-compatible tracer options and returns a trace paired with each transaction hash. +System transactions may therefore appear in block traces. + +### MegaETH Public Gateway + +The public gateway streams trace responses because they can be large. +It requires two positional parameters and was observed to support `callTracer` on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ------------------------------------------------------------------------ | +| `-32602` | Method | Invalid params | Either positional parameter is missing or malformed. | +| `-32000` | Method | Server error | The block is unknown, its parent state is unavailable, or tracing fails. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_traceBlockByHash", + "params": [ + "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d", + { "tracer": "callTracer" } + ] +} +``` + +The nested call frame is abbreviated below. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "txHash": "0xecc262f36652019b75f4cb7315ff19f430fc92efd5a8048948400407d55fd904", + "result": { + "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", + "to": "0x4200000000000000000000000000000000000015", + "gasUsed": "0xb9d56c", + "type": "CALL" + } + } + ] +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) +- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) +- Gateway: [mega-rpc streaming trace processor](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/processors/debug-trace-processor.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/read/rpc/debug_traceBlockByNumber.md new file mode 100644 index 0000000..c624b05 --- /dev/null +++ b/docs/dev/read/rpc/debug_traceBlockByNumber.md @@ -0,0 +1,94 @@ +--- +description: "Replays every transaction in a MegaETH block selected by number and returns execution traces." +--- + +# debug_traceBlockByNumber + +## Summary + +Replays a block selected by number or tag and returns one execution trace per transaction. +The public MegaETH endpoint supports this standard debug method. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------------- | ----------------------- | ------------------------- | ----------------------------------------------------------------------------- | +| `0` | `block` | `QUANTITY` or block tag | Yes | Block number or `latest`, `safe`, `finalized`, `earliest`, or `pending`. | +| `1` | `traceConfig` | object | Yes on the public gateway | Tracer selection and tracer-specific options. Use `{}` for the opcode tracer. | + +Common `traceConfig` fields include `tracer`, `tracerConfig`, and `timeout`. + +## Result + +The result is an array ordered by transaction index. +Each entry contains `txHash` and either `result` or `error`; the shape of `result` depends on the selected tracer. + +## MegaETH Behavior + +### Ethereum Standard + +The method replays all transactions in the selected block against its parent state. +The genesis block cannot be replayed because it has no parent state. + +### MegaETH Node Behavior + +MegaETH uses geth-compatible tracer options and includes system transactions in the block trace when present. + +### MegaETH Public Gateway + +The public gateway streams trace responses and requires two positional parameters. +Support and a successful `callTracer` response were observed on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ----------------------------------------------------------------------------- | +| `-32602` | Method | Invalid params | Either positional parameter is missing or malformed. | +| `-32000` | Method | Server error | The block or parent state is unavailable, a timeout occurs, or tracing fails. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_traceBlockByNumber", + "params": ["0x1", { "tracer": "callTracer" }] +} +``` + +The nested call frame is abbreviated below. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "txHash": "0xecc262f36652019b75f4cb7315ff19f430fc92efd5a8048948400407d55fd904", + "result": { + "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", + "to": "0x4200000000000000000000000000000000000015", + "gasUsed": "0xb9d56c", + "type": "CALL" + } + } + ] +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) +- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) +- Gateway: [mega-rpc streaming trace processor](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/processors/debug-trace-processor.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/read/rpc/debug_traceTransaction.md new file mode 100644 index 0000000..0ccf6a5 --- /dev/null +++ b/docs/dev/read/rpc/debug_traceTransaction.md @@ -0,0 +1,91 @@ +--- +description: "Replays a MegaETH transaction and returns its execution trace." +--- + +# debug_traceTransaction + +## Summary + +Replays a transaction in its original block context and returns an execution trace. +The public MegaETH endpoint supports this standard debug method. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ----------------- | ---------------- | ------------------------- | ----------------------------------------------------------------------------- | +| `0` | `transactionHash` | `DATA`, 32 bytes | Yes | Hash of a mined transaction. | +| `1` | `traceConfig` | object | Yes on the public gateway | Tracer selection and tracer-specific options. Use `{}` for the opcode tracer. | + +## Result + +The result shape depends on the tracer. +With no named tracer, the result contains opcode-level `structLogs`; with `callTracer`, it is a nested call frame. + +## MegaETH Behavior + +### Ethereum Standard + +The method reconstructs the transaction's pre-execution state, replays the transaction, and returns the selected trace format. + +### MegaETH Node Behavior + +MegaETH provides geth-compatible opcode and named tracers. +Tracing a system transaction may expose MegaETH system-contract calls. + +### MegaETH Public Gateway + +The public gateway streams this method's response and requires both positional parameters. +Support and a successful `callTracer` response were observed on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------------------------------------------- | +| `-32602` | Method | Invalid params | The hash or trace configuration is missing or malformed. | +| `-32000` | Method | Server error | The transaction or required history is unavailable, a timeout occurs, or tracing fails. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_traceTransaction", + "params": [ + "0xecc262f36652019b75f4cb7315ff19f430fc92efd5a8048948400407d55fd904", + { "tracer": "callTracer" } + ] +} +``` + +The nested call frame is abbreviated below. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", + "to": "0x4200000000000000000000000000000000000015", + "gas": "0x5f5e100", + "gasUsed": "0xb9d56c", + "type": "CALL" + } +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) +- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_accounts.md b/docs/dev/read/rpc/eth_accounts.md new file mode 100644 index 0000000..f3896a1 --- /dev/null +++ b/docs/dev/read/rpc/eth_accounts.md @@ -0,0 +1,34 @@ +--- +description: "eth_accounts JSON-RPC reference for MegaETH." +--- + +# eth_accounts + +Returns a list of addresses controlled by the RPC node. + +## Parameters + +None. + +## Returns + +**`result`** Address[] + +Accounts controlled by the RPC node; always empty on public endpoints. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":41,"method":"eth_accounts","params":[]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 41, "result": [] } +``` diff --git a/docs/dev/read/rpc/eth_blockNumber.md b/docs/dev/read/rpc/eth_blockNumber.md new file mode 100644 index 0000000..f78c593 --- /dev/null +++ b/docs/dev/read/rpc/eth_blockNumber.md @@ -0,0 +1,34 @@ +--- +description: "eth_blockNumber JSON-RPC reference for MegaETH." +--- + +# eth_blockNumber + +Returns the latest block number. + +## Parameters + +None. + +## Returns + +**`result`** Quantity + +Current head block number; advances with each new block. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":21,"method":"eth_blockNumber","params":[]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 21, "result": "0xaeb3d6" } // block 11,449,302 +``` diff --git a/docs/dev/read/rpc/eth_call.md b/docs/dev/read/rpc/eth_call.md new file mode 100644 index 0000000..cdd9f6c --- /dev/null +++ b/docs/dev/read/rpc/eth_call.md @@ -0,0 +1,157 @@ +--- +description: "eth_call JSON-RPC reference for MegaETH." +--- + +# eth_call + +Simulates a transaction against a given block's state and returns the result without creating an on-chain transaction. + +## Parameters + +**`transaction`** object **REQUIRED** + +Transaction to simulate. + +- **`from`** Address + + Caller; set explicitly when `msg.sender` matters. + +- **`to`** Address + + Target; `null` for contract-creation simulation. + +- **`value`** Quantity + + Wei value sent. + +- **`input`** Data + + Calldata; `data` is also accepted but `input` is preferred. + If both are present they must be identical. + +- **`gas`** Quantity + + Gas cap. + +- **`gasPrice`** Quantity + + Legacy gas price; do not combine with EIP-1559 fields. + +- **`maxFeePerGas`** Quantity + + EIP-1559 max fee. + +- **`maxPriorityFeePerGas`** Quantity + + EIP-1559 priority fee. + +- **`nonce`** Quantity + + Caller nonce override. + +- **`accessList`** array + + EIP-2930 access list; each entry: `{ "address": Address, "storageKeys": [Bytes32] }`. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +--- + +**`stateOverride`** object + +Per-address state overrides for this simulation. + +Object keyed by address. Each value: + +- **`balance`** Quantity + + Override the account balance. + +- **`nonce`** Quantity + + Override the account nonce. + +- **`code`** Data + + Override the account bytecode. + +- **`state`** object + + Replace full storage (slot → value); mutually exclusive with `stateDiff`. + +- **`stateDiff`** object + + Patch individual storage slots; mutually exclusive with `state`. + +- **`movePrecompileToAddress`** Address + + Move a precompile to the specified address before `code` is applied. + +--- + +**`blockOverrides`** object + +Block environment overrides for this simulation. + +- **`number`** Quantity + + Override `block.number`. + +- **`time`** Quantity + + Override `block.timestamp`. + +- **`gasLimit`** Quantity + + Override `block.gasLimit`. + +- **`feeRecipient`** Address + + Override `block.coinbase`. + +- **`prevRandao`** Quantity + + Override randomness. + +- **`baseFeePerGas`** Quantity + + Override `block.baseFee`. + +- **`blobBaseFee`** Quantity + + Override blob base fee. + +## Returns + +**`result`** Data + +Raw return bytes. +Calls to non-contract addresses return `0x`. +Reverts surface as JSON-RPC errors, not as a normal result. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------------------------------------- | ------------------------------------------------- | +| `-32602` | Malformed call object, block selector, or override object | Fix the request | +| `3` | Simulated execution reverted | Decode `error.data` and fix call conditions | +| `-32000` | Simulation failed or hit an execution limit | Inspect `error.message`; adjust gas or call shape | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":46,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000004","input":"0x11223344"},"latest"]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 46, "result": "0x11223344" } +``` diff --git a/docs/dev/read/rpc/eth_callAfter.md b/docs/dev/read/rpc/eth_callAfter.md deleted file mode 100644 index 56e5a52..0000000 --- a/docs/dev/read/rpc/eth_callAfter.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -description: eth_callAfter — execute eth_call after waiting for an account's nonce to reach a target value. ---- - -# eth_callAfter - -Executes `eth_call` after waiting for an account's nonce to reach a target value. -Useful for simulating a transaction that depends on prior transactions completing — for example, checking the result of a swap after a preceding approval has been confirmed. - -## Parameters - -Pass `params` as `[request, condition, stateOverride, blockOverrides]`. Only `request` and `condition` are required. - -### `request` - -Describes the simulated transaction. - -| Field | Type | Required | Notes | -| ---------------------- | ----------------- | -------- | ------------------------------------------------------------------------- | -| `to` | `Data` (20 bytes) | Yes | Target contract address | -| `from` | `Data` (20 bytes) | No | Sender address. Set explicitly when `msg.sender` matters | -| `input` | `Data` | No | Calldata. MegaETH also accepts `data`, but prefer `input` for portability | -| `value` | `Quantity` | No | Wei to send with the call | -| `gas` | `Quantity` | No | Gas limit for the simulation | -| `gasPrice` | `Quantity` | No | Legacy gas price. Cannot be combined with EIP-1559 fee fields | -| `maxFeePerGas` | `Quantity` | No | EIP-1559 max fee. Cannot be combined with `gasPrice` | -| `maxPriorityFeePerGas` | `Quantity` | No | EIP-1559 priority fee. Cannot be combined with `gasPrice` | - -### `condition` - -| Field | Type | Required | Notes | -| --------- | ----------------- | -------- | ------------------------------------------------------------ | -| `account` | `Data` (20 bytes) | Yes | Account address whose nonce to monitor | -| `nonce` | `Quantity` | Yes | Target nonce value to wait for | -| `timeout` | `Number` | No | Max wait time in milliseconds. Default: `3000`. Max: `60000` | - -### `stateOverride` - -Optional. Temporary account-level overrides applied only for this simulation. Keyed by address. - -| Field | Type | Notes | -| ----------- | ---------- | ------------------------------------------------------------------------------ | -| `balance` | `Quantity` | Override the account balance | -| `nonce` | `Quantity` | Override the account nonce | -| `code` | `Data` | Override the account bytecode | -| `state` | `Object` | Replace the entire storage (slot → value). Cannot be combined with `stateDiff` | -| `stateDiff` | `Object` | Patch individual storage slots. Cannot be combined with `state` | - -### `blockOverrides` - -Optional. Temporary block-environment overrides applied only for this simulation. - -| Field | Type | Notes | -| --------------- | ----------------- | -------------------------- | -| `number` | `Quantity` | Override `block.number` | -| `time` | `Quantity` | Override `block.timestamp` | -| `gasLimit` | `Quantity` | Override `block.gasLimit` | -| `feeRecipient` | `Data` (20 bytes) | Override `block.coinbase` | -| `baseFeePerGas` | `Quantity` | Override `block.baseFee` | - -## Returns - -| Field | Type | Notes | -| -------- | ------ | ------------------------------------------------------- | -| `result` | `Data` | Return data from the executed call — same as `eth_call` | - -## Errors - -| Code | Cause | Fix | -| -------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| `-32000` | `Timeout: timeout waiting for nonce condition` — nonce did not reach the target within the timeout | Increase `timeout`, or verify the prior transaction was submitted | -| `-32000` | `InternalError` — internal processing error | Retry the request | - -See also [Error reference](error-codes.md). - -## Example - -Execute `eth_call` after waiting for account nonce to reach 5: - -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -X POST -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_callAfter", - "params": [ - { - "from": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266", - "to": "0x1234567890abcdef1234567890abcdef12345678", - "data": "0x70a08231000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266" - }, - { - "account": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266", - "nonce": "0x5", - "timeout": 30000 - } - ] - }' -``` - -Successful response: - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000" -} -``` - -Timeout response: - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "error": { - "code": -32000, - "message": "Timeout: timeout waiting for nonce condition" - } -} -``` diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/read/rpc/eth_callMany.md new file mode 100644 index 0000000..ced152e --- /dev/null +++ b/docs/dev/read/rpc/eth_callMany.md @@ -0,0 +1,99 @@ +--- +description: "Executes ordered bundles of read-only calls against a selected MegaETH state." +--- + +# eth_callMany + +## Summary + +Executes one or more ordered bundles of read-only calls and returns a result for every call. +The public MegaETH gateway adds validation, compute limits, and an optional timeout to the node method. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ---------------- | ---------------- | -------- | ------------------------------------------------------------------ | +| `0` | `bundles` | array | Yes | One to 100 bundle objects, with at most 100 transactions in total. | +| `1` | `stateContext` | object | Yes | State against which the bundles execute. | +| `2` | `stateOverrides` | object or `null` | No | Temporary account-state overrides. | +| `3` | `timeoutMs` | integer | No | Gateway timeout from 1 to 25,000 milliseconds; defaults to 5,000. | + +Each bundle requires a non-empty `transactions` array and may include a `blockOverride` object. +Each transaction uses the standard `eth_call` transaction-call fields. +`stateContext.blockNumber` is required and accepts a block number, block tag, or EIP-1898-style block reference. +`stateContext.transactionIndex` may be `-1` or a non-negative integer. + +## Result + +The result is an array of bundle results. +Each bundle result is an array containing one object per transaction; a successful call object contains a `value` field with the returned `DATA`. + +## MegaETH Behavior + +### Ethereum Standard + +`eth_callMany` is not part of the core Ethereum JSON-RPC API, although compatible implementations use it for ordered multi-call simulation. + +### MegaETH Node Behavior + +The MegaETH node executes bundles in order against a shared evolving simulation state and returns a nested result array. + +### MegaETH Public Gateway + +The gateway accepts two to four positional parameters, limits requests to 100 bundles and 100 total transactions, and limits each call to 60,000,000 compute gas. +It applies a 5-second default timeout and accepts an explicit timeout up to 25 seconds. +These limits were verified in gateway source and a successful call was observed on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | +| `-32602` | Method | Invalid params | Required objects are missing, fields are malformed, or bundle, transaction, or timeout limits are exceeded. | +| `-32000` | Method | Server error | A simulation cannot execute or its timeout expires. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the 1.5 MiB public endpoint body limit. | + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_callMany", + "params": [ + [ + { + "transactions": [ + { + "to": "0x0000000000000000000000000000000000000000", + "data": "0x" + } + ] + } + ], + { "blockNumber": "latest" } + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [[{ "value": "0x" }]] +} +``` + +## Sources + +- Node: [mega-reth `eth_callMany` implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc call-many adapter](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/services/call-many/mega-call-many-adapter.ts) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_chainId.md b/docs/dev/read/rpc/eth_chainId.md new file mode 100644 index 0000000..fa2d58e --- /dev/null +++ b/docs/dev/read/rpc/eth_chainId.md @@ -0,0 +1,34 @@ +--- +description: "eth_chainId JSON-RPC reference for MegaETH." +--- + +# eth_chainId + +Returns the chain ID of the connected network. + +## Parameters + +None. + +## Returns + +**`result`** Quantity + +The chain ID for the connected network. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":31,"method":"eth_chainId","params":[]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 31, "result": "0x10e6" } // 4326 (Mainnet) +``` diff --git a/docs/dev/read/rpc/eth_createAccessList.md b/docs/dev/read/rpc/eth_createAccessList.md new file mode 100644 index 0000000..74ae109 --- /dev/null +++ b/docs/dev/read/rpc/eth_createAccessList.md @@ -0,0 +1,135 @@ +--- +description: "eth_createAccessList JSON-RPC reference for MegaETH." +--- + +# eth_createAccessList + +Generates an access list for a transaction. + +## Parameters + +**`transaction`** object **REQUIRED** + +Transaction to simulate. + +- **`from`** Address + + Caller. + +- **`to`** Address + + Target; `null` for contract-creation simulation. + +- **`value`** Quantity + + Wei value sent. + +- **`input`** Data + + Calldata; prefer over `data`. + +- **`gas`** Quantity + + Gas cap. + +- **`gasPrice`** Quantity + + Legacy gas price; do not combine with EIP-1559 fields. + +- **`maxFeePerGas`** Quantity + + EIP-1559 max fee. + +- **`maxPriorityFeePerGas`** Quantity + + EIP-1559 priority fee. + +- **`nonce`** Quantity + + Caller nonce override. + +- **`accessList`** array + + EIP-2930 access list; each entry: `{ "address": Address, "storageKeys": [Bytes32] }`. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +--- + +**`stateOverride`** object + +Per-address state overrides for this simulation. + +Object keyed by address. Each value: + +- **`balance`** Quantity + + Override the account balance. + +- **`nonce`** Quantity + + Override the account nonce. + +- **`code`** Data + + Override the account bytecode. + +- **`state`** object + + Replace full storage (slot → value); mutually exclusive with `stateDiff`. + +- **`stateDiff`** object + + Patch individual storage slots; mutually exclusive with `state`. + +- **`movePrecompileToAddress`** Address + + Move a precompile to the specified address before `code` is applied. + +## Returns + +- **`accessList`** array + + Generated EIP-2930 access list; each entry: `{ "address": Address, "storageKeys": [Bytes32] }`. + +- **`gasUsed`** Quantity + + Gas with the generated access list applied. + +- **`error`** string + + Execution error when the call reverts; may coexist with `accessList` and `gasUsed`. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------- | -------------------------------------- | +| `-32602` | Malformed transaction object or block selector | Fix the request | +| `-32000` | Pre-execution check failed (e.g. intrinsic gas too low) | Raise or remove the gas cap | +| `-32003` | Sender cannot cover gas and value in the selected state | Fund the sender or lower the value/fee | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":7,"method":"eth_createAccessList","params":[{"to":"0x1111111111111111111111111111111111111111","input":"0x"},"latest"]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 7, + "result": { + "accessList": [], + "gasUsed": "0xea60" + } +} +``` diff --git a/docs/dev/read/rpc/eth_estimateGas.md b/docs/dev/read/rpc/eth_estimateGas.md new file mode 100644 index 0000000..2e740bb --- /dev/null +++ b/docs/dev/read/rpc/eth_estimateGas.md @@ -0,0 +1,120 @@ +--- +description: "eth_estimateGas JSON-RPC reference for MegaETH." +--- + +# eth_estimateGas + +Estimates the gas required to execute a transaction. + +## Parameters + +**`transaction`** object **REQUIRED** + +Transaction to simulate. + +- **`from`** Address + + Caller. + +- **`to`** Address + + Target; `null` for contract-creation simulation. + +- **`value`** Quantity + + Wei value sent. + +- **`input`** Data + + Calldata; prefer over `data`. + +- **`gas`** Quantity + + Gas cap. + +- **`gasPrice`** Quantity + + Legacy gas price; do not combine with EIP-1559 fields. + +- **`maxFeePerGas`** Quantity + + EIP-1559 max fee. + +- **`maxPriorityFeePerGas`** Quantity + + EIP-1559 priority fee. + +- **`nonce`** Quantity + + Caller nonce override. + +- **`accessList`** array + + EIP-2930 access list; each entry: `{ "address": Address, "storageKeys": [Bytes32] }`. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +--- + +**`stateOverride`** object + +Per-address state overrides for this simulation. + +Object keyed by address. Each value: + +- **`balance`** Quantity + + Override the account balance. + +- **`nonce`** Quantity + + Override the account nonce. + +- **`code`** Data + + Override the account bytecode. + +- **`state`** object + + Replace full storage (slot → value); mutually exclusive with `stateDiff`. + +- **`stateDiff`** object + + Patch individual storage slots; mutually exclusive with `state`. + +- **`movePrecompileToAddress`** Address + + Move a precompile to the specified address before `code` is applied. + +## Returns + +**`result`** Quantity + +Estimated execution gas. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| `-32602` | Malformed transaction fields, fee model, or block selector | Fix the request | +| `-32000` | Estimation failed, hit a provider-side execution limit, or used a rejected explicit gas cap | Inspect `error.message` and adjust gas or call shape | +| `3` | Simulated execution reverted | Decode `error.data` and fix the call conditions | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":57,"method":"eth_estimateGas","params":[{"to":"0x0000000000000000000000000000000000000000","value":"0x0"},"latest"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 57, "result": "0xea60" } // 60,000 gas +``` diff --git a/docs/dev/read/rpc/eth_feeHistory.md b/docs/dev/read/rpc/eth_feeHistory.md new file mode 100644 index 0000000..6bf891e --- /dev/null +++ b/docs/dev/read/rpc/eth_feeHistory.md @@ -0,0 +1,86 @@ +--- +description: "eth_feeHistory JSON-RPC reference for MegaETH." +--- + +# eth_feeHistory + +Returns historical gas fee data for a range of blocks. + +## Parameters + +**`blockCount`** Quantity **REQUIRED** + +Number of blocks (`1`–`256`). + +--- + +**`newestBlock`** string **REQUIRED** + +Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. + +--- + +**`rewardPercentiles`** number[] + +Monotonically increasing values from `0` to `100`; omit to exclude `reward` from the result. + +## Returns + +- **`oldestBlock`** Quantity + + First block in the returned range. + +- **`baseFeePerGas`** Quantity[] + + Base fee per block; length is `blockCount + 1`. + +- **`gasUsedRatio`** number[] + + Gas utilization ratio per block. + +- **`reward`** Quantity[][] + + Percentile reward values; present only when `rewardPercentiles` was provided. + +- **`baseFeePerBlobGas`** Quantity[] + + Blob base fee per block when available. + +- **`blobGasUsedRatio`** number[] + + Blob gas utilization ratio per block when available. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------------------------------------------- | ------------------- | +| `-32602` | Invalid request shape or `blockCount` outside the allowed range | Fix the request | +| `-32000` | `blockCount` exceeds the endpoint limit | Reduce `blockCount` | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":66,"method":"eth_feeHistory","params":["0x2","latest",[25,75]]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 66, + "result": { + "oldestBlock": "0xfffff", + "baseFeePerGas": ["0xf4240", "0xf4240", "0xf4240"], + "gasUsedRatio": [0.1, 0.1], + "reward": [ + ["0x0", "0x0"], + ["0x0", "0x0"] + ], + "baseFeePerBlobGas": ["0x1", "0x1", "0x1"], + "blobGasUsedRatio": [0, 0] + } +} +``` diff --git a/docs/dev/read/rpc/eth_gasPrice.md b/docs/dev/read/rpc/eth_gasPrice.md new file mode 100644 index 0000000..a43bd41 --- /dev/null +++ b/docs/dev/read/rpc/eth_gasPrice.md @@ -0,0 +1,35 @@ +--- +description: "eth_gasPrice JSON-RPC reference for MegaETH." +--- + +# eth_gasPrice + +Returns the current gas price in wei. +Under MegaETH's current fee policy, this method returns `0xf4240` (1,000,000 wei = 0.001 gwei). + +## Parameters + +None. + +## Returns + +**`result`** Quantity + +Gas price in wei. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 1, "result": "0xf4240" } // 1,000,000 wei +``` diff --git a/docs/dev/read/rpc/eth_getBalance.md b/docs/dev/read/rpc/eth_getBalance.md new file mode 100644 index 0000000..c4086d8 --- /dev/null +++ b/docs/dev/read/rpc/eth_getBalance.md @@ -0,0 +1,49 @@ +--- +description: "eth_getBalance JSON-RPC reference for MegaETH." +--- + +# eth_getBalance + +Returns the ETH balance of an account in wei at a given block. + +## Parameters + +**`address`** Address **REQUIRED** + +Target account or contract address. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +## Returns + +**`result`** Quantity + +Balance in wei. +The method returns `0x0` for unknown accounts and zero-balance accounts alike. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------- | ----------------------------------------------------- | +| `-32602` | Malformed address or block selector | Fix the request | +| `-32001` | Block selector cannot be resolved | Verify the block number or hash | +| `4444` | Requested historical state is not available | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 1, "result": "0xe7bc7211178" } // 15,924,784,599,416 wei +``` diff --git a/docs/dev/read/rpc/eth_getBlockByHash.md b/docs/dev/read/rpc/eth_getBlockByHash.md new file mode 100644 index 0000000..1f1097f --- /dev/null +++ b/docs/dev/read/rpc/eth_getBlockByHash.md @@ -0,0 +1,89 @@ +--- +description: "eth_getBlockByHash JSON-RPC reference for MegaETH." +--- + +# eth_getBlockByHash + +Returns a block by its hash. + +## Parameters + +**`blockHash`** Hash32 **REQUIRED** + +Target block hash. + +--- + +**`fullTransactions`** boolean **REQUIRED** + +`false` returns transaction hashes; `true` returns full transaction objects. + +## Returns + +`Block | null` — `null` when the hash is well-formed but does not match any block. + +- **`number`** Quantity + + Block number. + +- **`hash`** Hash32 + + Block hash. + +- **`parentHash`** Hash32 + + Parent block hash. + +- **`timestamp`** Quantity + + Block timestamp. + +- **`miner`** Address + + Fee recipient / coinbase. + +- **`gasLimit`** Quantity + + Block gas limit. + +- **`gasUsed`** Quantity + + Gas consumed by the block. + +- **`transactions`** Hash32[] | Transaction[] + + Hashes when `fullTransactions = false`; full objects when `true`. + +Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. + +## Errors + +| Code | Cause | Fix | +| -------- | -------------------------------------------------------------- | ----------------------------------------------------- | +| `-32602` | Block hash is malformed or `fullTransactions` is not a boolean | Fix the request | +| `4444` | Requested historical block is not available on this endpoint | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":74,"method":"eth_getBlockByHash","params":["0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1",false]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 74, + "result": { + "hash": "0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1", + "number": "0x100000", + "timestamp": "0x692225d3", + "transactions": [ + "0x243d39c7f6cd74a9a081a6fe4bdfce37ac6136b9454691aeeb9ed77998450cbc" + ] + } +} +``` diff --git a/docs/dev/read/rpc/eth_getBlockByNumber.md b/docs/dev/read/rpc/eth_getBlockByNumber.md new file mode 100644 index 0000000..706b689 --- /dev/null +++ b/docs/dev/read/rpc/eth_getBlockByNumber.md @@ -0,0 +1,89 @@ +--- +description: "eth_getBlockByNumber JSON-RPC reference for MegaETH." +--- + +# eth_getBlockByNumber + +Returns a block by number or tag. + +## Parameters + +**`block`** string **REQUIRED** + +Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. + +--- + +**`fullTransactions`** boolean **REQUIRED** + +`false` returns transaction hashes; `true` returns full transaction objects. + +## Returns + +`Block | null` — `null` when the requested block does not exist or is not yet available. + +- **`number`** Quantity + + Block number. + +- **`hash`** Hash32 + + Block hash. + +- **`parentHash`** Hash32 + + Parent block hash. + +- **`timestamp`** Quantity + + Block timestamp. + +- **`miner`** Address + + Fee recipient / coinbase. + +- **`gasLimit`** Quantity + + Block gas limit. + +- **`gasUsed`** Quantity + + Gas consumed by the block. + +- **`transactions`** Hash32[] | Transaction[] + + Hashes when `fullTransactions = false`; full objects when `true`. + +Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------------------------------------------- | ----------------------------------------------------- | +| `-32602` | Malformed block selector or `fullTransactions` is not a boolean | Fix the request | +| `4444` | Requested historical block is not available on this endpoint | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":81,"method":"eth_getBlockByNumber","params":["0x100000",false]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 81, + "result": { + "hash": "0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1", + "number": "0x100000", + "timestamp": "0x692225d3", + "transactions": [ + "0x243d39c7f6cd74a9a081a6fe4bdfce37ac6136b9454691aeeb9ed77998450cbc" + ] + } +} +``` diff --git a/docs/dev/read/rpc/eth_getBlockReceipts.md b/docs/dev/read/rpc/eth_getBlockReceipts.md new file mode 100644 index 0000000..8b20333 --- /dev/null +++ b/docs/dev/read/rpc/eth_getBlockReceipts.md @@ -0,0 +1,112 @@ +--- +description: "eth_getBlockReceipts JSON-RPC reference for MegaETH." +--- + +# eth_getBlockReceipts + +Returns all transaction receipts for a block. + +## Parameters + +**`block`** string | object **REQUIRED** + +Block number, tag (`earliest`, `latest`, `safe`, `finalized`, `pending`), block hash, or `{"blockHash":"0x…"}` selector object. + +## Returns + +`Receipt[] | null` — receipts for every transaction in the block. +The method returns `null` when the block is not found. +It returns `[]` when the block exists but contains no transactions. + +Each array element contains: + +- **`transactionHash`** Hash32 + + Transaction hash. + +- **`status`** Quantity + + `0x1` success; `0x0` failure. + +- **`blockHash`** Hash32 + + Containing block hash. + +- **`blockNumber`** Quantity + + Containing block number. + +- **`from`** Address + + Sender. + +- **`to`** Address | null + + Recipient; `null` for contract creation. + +- **`gasUsed`** Quantity + + Gas consumed by this transaction. + +- **`effectiveGasPrice`** Quantity + + Effective gas price. + +- **`contractAddress`** Address | null + + Created contract address when applicable. + +- **`logs`** Log[] + + Emitted log entries. + +Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). + +## Errors + +| Code | Cause | Fix | +| -------- | -------------------------------------------------- | ----------------------------------------------------- | +| `-32602` | Malformed or unsupported block selector | Fix the request | +| `4444` | Historical block data unavailable on this endpoint | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":16,"method":"eth_getBlockReceipts","params":[{"blockHash":"0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d"}]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 16, + "result": [ + { + "type": "0x7e", + "status": "0x1", + "cumulativeGasUsed": "0xb9d56c", + "logs": [], + "depositNonce": "0x0", + "depositReceiptVersion": "0x1", + "transactionHash": "0xecc262f36652019b75f4cb7315ff19f430fc92efd5a8048948400407d55fd904", + "transactionIndex": "0x0", + "blockHash": "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d", + "blockNumber": "0x1", + "gasUsed": "0xb9d56c", // 12,178,796 + "effectiveGasPrice": "0x0", // 0 — deposit transaction + "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", + "to": "0x4200000000000000000000000000000000000015", + "contractAddress": null, + "l1GasPrice": "0x22ba611d", // 582,639,901 wei + "l1GasUsed": "0x6e7", // 1,767 + "l1Fee": "0x0", + "l1BaseFeeScalar": "0x558", // 1,368 + "l1BlobBaseFee": "0x7", // 7 + "l1BlobBaseFeeScalar": "0xc5fc5", // 810,949 + }, + ], +} +``` diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md new file mode 100644 index 0000000..4bec80d --- /dev/null +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md @@ -0,0 +1,39 @@ +--- +description: "eth_getBlockTransactionCountByHash JSON-RPC reference for MegaETH." +--- + +# eth_getBlockTransactionCountByHash + +Returns the number of transactions in the block matching the given hash. + +## Parameters + +**`blockHash`** Hash32 **REQUIRED** + +Target block hash. + +## Returns + +**`result`** Quantity | null + +Transaction count; `null` when the block is not found. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------- | --------------- | +| `-32602` | Block hash missing or malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":3,"method":"eth_getBlockTransactionCountByHash","params":["0xa97b8563203de36f0c8430709734438fbf7f2444b6de9f307853fc46b230de3e"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 3, "result": "0x18" } // 24 transactions +``` diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md new file mode 100644 index 0000000..d79e853 --- /dev/null +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md @@ -0,0 +1,39 @@ +--- +description: "eth_getBlockTransactionCountByNumber JSON-RPC reference for MegaETH." +--- + +# eth_getBlockTransactionCountByNumber + +Returns the number of transactions in a block identified by block number or tag. + +## Parameters + +**`block`** string **REQUIRED** + +Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. + +## Returns + +**`result`** Quantity | null + +Transaction count; `null` when the block is not found. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------- | --------------- | +| `-32602` | Block selector is malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":4,"method":"eth_getBlockTransactionCountByNumber","params":["0xb11362"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 4, "result": "0x17" } // 23 transactions (block 11,604,834) +``` diff --git a/docs/dev/read/rpc/eth_getCode.md b/docs/dev/read/rpc/eth_getCode.md new file mode 100644 index 0000000..c274c48 --- /dev/null +++ b/docs/dev/read/rpc/eth_getCode.md @@ -0,0 +1,48 @@ +--- +description: "eth_getCode JSON-RPC reference for MegaETH." +--- + +# eth_getCode + +Returns the runtime bytecode stored at an address at a given block. + +## Parameters + +**`address`** Address **REQUIRED** + +Target account or contract address. + +--- + +**`block`** string + +Hex block number, block hash, or tag (`latest`, `safe`, `finalized`, …). +The default is `"latest"`. + +## Returns + +**`result`** Data + +Runtime bytecode (not creation bytecode) at the address; `0x` when no code is deployed. + +## Errors + +| Code | Cause | Fix | +| -------- | ----------------------------------------- | ----------------------------------------------------- | +| `-32602` | Malformed address or block selector | Fix the request | +| `-32001` | Block selector cannot be resolved | Verify the block number or hash | +| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":2,"method":"eth_getCode","params":["0x4200000000000000000000000000000000000011","latest"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 2, "result": "0x6080604052…" } // bytecode truncated +``` diff --git a/docs/dev/read/rpc/eth_getCodeByHash.md b/docs/dev/read/rpc/eth_getCodeByHash.md new file mode 100644 index 0000000..f97ef16 --- /dev/null +++ b/docs/dev/read/rpc/eth_getCodeByHash.md @@ -0,0 +1,39 @@ +--- +description: "eth_getCodeByHash JSON-RPC reference for MegaETH." +--- + +# eth_getCodeByHash + +Returns runtime bytecode for a given code hash. + +## Parameters + +**`codeHash`** Hash32 **REQUIRED** + +Target runtime code hash. + +## Returns + +**`result`** Data + +Runtime bytecode; `0x` when no bytecode is stored for that hash. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------------- | --------------- | +| `-32602` | Code hash is missing or malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":43,"method":"eth_getCodeByHash","params":["0xfa8c9db6c6cab7108dea276f4cd09d575674eb0852c0fa3187e59e98ef977998"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 43, "result": "0x6080604052…" } // bytecode truncated +``` diff --git a/docs/dev/read/rpc/eth_getHeaderByHash.md b/docs/dev/read/rpc/eth_getHeaderByHash.md new file mode 100644 index 0000000..acaf2f1 --- /dev/null +++ b/docs/dev/read/rpc/eth_getHeaderByHash.md @@ -0,0 +1,78 @@ +--- +description: "eth_getHeaderByHash JSON-RPC reference for MegaETH." +--- + +# eth_getHeaderByHash + +Returns a block header by its hash. + +## Parameters + +**`blockHash`** Hash32 **REQUIRED** + +Target block hash. + +## Returns + +`Header | null` — `null` when the hash does not match any known block. + +- **`number`** Quantity + + Block number. + +- **`hash`** Hash32 + + Block hash. + +- **`parentHash`** Hash32 + + Parent block hash. + +- **`timestamp`** Quantity + + Block timestamp. + +- **`miner`** Address + + Fee recipient / coinbase. + +- **`gasLimit`** Quantity + + Block gas limit. + +- **`gasUsed`** Quantity + + Gas consumed. + +Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. + +## Errors + +| Code | Cause | Fix | +| -------- | ---------------------------------- | --------------- | +| `-32602` | Block hash is missing or malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":26,"method":"eth_getHeaderByHash","params":["0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0"]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 26, + "result": { + "hash": "0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0", + "parentHash": "0x6b6b52368c21dcdba7348fa37edae3e945013627a83a96b64d55217696899d30", + "stateRoot": "0xf328fa2752aea1c211a73067d17c25d09a416b4b6a7785441f39bcc930028717", + "number": "0xb10f64", // 11,603,812 + "timestamp": "0x69c33537", // 1,774,400,823 + "baseFeePerGas": "0xf4240", // 1,000,000 wei + }, +} +``` diff --git a/docs/dev/read/rpc/eth_getHeaderByNumber.md b/docs/dev/read/rpc/eth_getHeaderByNumber.md new file mode 100644 index 0000000..35abdf4 --- /dev/null +++ b/docs/dev/read/rpc/eth_getHeaderByNumber.md @@ -0,0 +1,78 @@ +--- +description: "eth_getHeaderByNumber JSON-RPC reference for MegaETH." +--- + +# eth_getHeaderByNumber + +Returns a header-only view of a block by number or block tag. + +## Parameters + +**`block`** string **REQUIRED** + +Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. + +## Returns + +`Header | null` — `null` when the block is not found. + +- **`number`** Quantity + + Block number. + +- **`hash`** Hash32 + + Block hash. + +- **`parentHash`** Hash32 + + Parent block hash. + +- **`timestamp`** Quantity + + Block timestamp. + +- **`miner`** Address + + Fee recipient / coinbase. + +- **`gasLimit`** Quantity + + Block gas limit. + +- **`gasUsed`** Quantity + + Gas consumed. + +Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. + +## Errors + +| Code | Cause | Fix | +| -------- | -------------------------------------------------------------- | --------------- | +| `-32602` | Malformed selector, decimal string, or unsupported object form | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":27,"method":"eth_getHeaderByNumber","params":["0xb11048"]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 27, + "result": { + "hash": "0x235d80b5e91125a1a1d6da6776c6a9ee087d1818c494f71736b09bed61b1411e", + "parentHash": "0x6fc0412abfba89bbfab17b2d8bd36cb1c214c1d53ed213fa8958439d0c4f9c18", + "stateRoot": "0x301d7b77a74893451bd76e5d1672aaaa493cd78c06d59e885218d48917a35c03", + "number": "0xb11048", // 11,604,040 + "timestamp": "0x69c3361b", // 1,774,401,051 + "baseFeePerGas": "0xf4240", // 1,000,000 wei + }, +} +``` diff --git a/docs/dev/read/rpc/eth_getLogs.md b/docs/dev/read/rpc/eth_getLogs.md new file mode 100644 index 0000000..6c751c8 --- /dev/null +++ b/docs/dev/read/rpc/eth_getLogs.md @@ -0,0 +1,116 @@ +--- +description: "eth_getLogs JSON-RPC reference for MegaETH." +--- + +# eth_getLogs + +Returns event logs emitted by smart contracts, filtered by block range, contract address, and/or topics. + +## Parameters + +**`filter`** object **REQUIRED** + +Log filter. + +- **`fromBlock`** string + + Inclusive start as a hex block number or tag. + The default is `latest`. + +- **`toBlock`** string + + Inclusive end as a hex block number or tag. + The default is `latest`. + +- **`blockHash`** Hash32 + + Single-block mode; mutually exclusive with `fromBlock`/`toBlock`. + +- **`address`** Address | Address[] + + Filter by emitting address(es). + +- **`topics`** array + + Positional topic filter where positions are AND and values within a position are OR. + Use `null` for wildcards. + +## Returns + +`Log[]` — array of matching log entries. + +- **`address`** Address + + Emitting contract. + +- **`topics`** Hash32[] + + Indexed topics. + +- **`data`** Data + + Unindexed payload. + +- **`blockNumber`** Quantity | null + + Containing block number. + +- **`transactionHash`** Hash32 | null + + Containing transaction hash. + +- **`transactionIndex`** Quantity | null + + Transaction position in block. + +- **`logIndex`** Quantity | null + + Log position in block. + +- **`removed`** boolean + + `true` if removed during reorg. + +- **`blockTimestamp`** Quantity + + Block timestamp. + +## Errors + +| Code | Cause | Fix | +| -------- | ---------------------------------------------------------------------- | ---------------------------- | +| `-32602` | Filter is malformed or combines `blockHash` with `fromBlock`/`toBlock` | Fix the filter | +| `-32001` | Provided `blockHash` cannot be resolved | Verify the block hash | +| `-32000` | Query range is too large for the endpoint | Narrow the range or paginate | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":110,"method":"eth_getLogs","params":[{"fromBlock":"0xb120c6","toBlock":"0xb120c6","address":"0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6","topics":["0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815","0x00000000000000000000000000000000000000000000000000000000000000d8"]}]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 110, + "result": [ + { + "address": "0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6", + "topics": [ + "0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815", + "0x00000000000000000000000000000000000000000000000000000000000000d8", // 216 + ], + "data": "0x0000000000000000000954150000002f000000000000d6d800000000006ec9a2", + "blockNumber": "0xb120c6", // 11,608,262 + "blockTimestamp": "0x69c34699", + "transactionHash": "0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6", + "logIndex": "0x24", // 36 + "removed": false, + }, + ], +} +``` diff --git a/docs/dev/read/rpc/eth_getLogsWithCursor.md b/docs/dev/read/rpc/eth_getLogsWithCursor.md deleted file mode 100644 index 1066298..0000000 --- a/docs/dev/read/rpc/eth_getLogsWithCursor.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -description: eth_getLogsWithCursor — paginated log queries using a cursor for incremental retrieval of large datasets. ---- - -# eth_getLogsWithCursor - -Returns event logs with cursor-based pagination. -Accepts the same filter parameters as `eth_getLogs`, with an additional optional `cursor`. -When a query exceeds server-side resource limits, the server returns a partial result and a cursor marking where it left off. - -## Parameters - -Pass a single filter object as `params[0]`. - -| Field | Type | Required | Notes | -| ----------- | ------------------ | -------- | ---------------------------------------------------------------------- | -| `fromBlock` | `BlockTag` | No | Start of range (inclusive) | -| `toBlock` | `BlockTag` | No | End of range (inclusive) | -| `blockHash` | `Data` (32 bytes) | No | Single block to query. Cannot be combined with `fromBlock` / `toBlock` | -| `address` | `Data` \| `Data[]` | No | Contract address(es) to match | -| `topics` | `Data[]` | No | Position-sensitive topic filter. Use `null` as a wildcard | -| `cursor` | `String` | No | Opaque cursor from a previous response. Omit for the initial request | - -## Returns - -| Field | Type | Notes | -| -------- | -------- | ------------------------------------------------------------------- | -| `logs` | `Log[]` | Matching log objects (same schema as `eth_getLogs`) | -| `cursor` | `String` | Present when more results remain. Absent when the query is complete | - -The cursor is derived from the block number and log index of the last log in the batch, but clients should treat it as an opaque string. - -## Errors - -| Code | Cause | Fix | -| -------- | ---------------------------------------------------------------------- | ------------------------------------- | -| `-32602` | Malformed filter, or `blockHash` combined with `fromBlock` / `toBlock` | Fix the filter | -| `-32000` | Query too large for the endpoint | Narrow the filter or reduce the range | - -See also [Error reference](error-codes.md). - -## Example - -### Initial request - -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -X POST -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_getLogsWithCursor", - "params": [{ - "fromBlock": "0x100", - "toBlock": "0x200", - "address": "0x1234567890abcdef1234567890abcdef12345678", - "topics": ["0xddf252ad..."] - }] - }' -``` - -Partial response (has cursor — more results remain): - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "logs": [ - { - "address": "0x1234567890abcdef1234567890abcdef12345678", - "blockNumber": "0x101", - "logIndex": "0x0", - "topics": ["0xddf252ad..."], - "data": "0x...", - "transactionHash": "0x...", - "transactionIndex": "0x0", - "blockHash": "0x...", - "removed": false - } - ], - "cursor": "0x0000010100000000" - } -} -``` - -Continuation request — pass the `cursor` from the previous response to resume: - -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -X POST -H "Content-Type: application/json" \ - -d '{ - "jsonrpc": "2.0", - "id": 2, - "method": "eth_getLogsWithCursor", - "params": [{ - "fromBlock": "0x100", - "toBlock": "0x200", - "address": "0x1234567890abcdef1234567890abcdef12345678", - "topics": ["0xddf252ad..."], - "cursor": "0x0000010100000000" - }] - }' -``` - -Complete response (no cursor — all results retrieved): - -```json -{ - "jsonrpc": "2.0", - "id": 2, - "result": { - "logs": [ - { - "address": "0x1234567890abcdef1234567890abcdef12345678", - "blockNumber": "0x102", - "logIndex": "0x3", - "topics": ["0xddf252ad..."], - "data": "0x...", - "transactionHash": "0x...", - "transactionIndex": "0x2", - "blockHash": "0x...", - "removed": false - } - ] - } -} -``` diff --git a/docs/dev/read/rpc/eth_getStorageAt.md b/docs/dev/read/rpc/eth_getStorageAt.md new file mode 100644 index 0000000..d3c9574 --- /dev/null +++ b/docs/dev/read/rpc/eth_getStorageAt.md @@ -0,0 +1,58 @@ +--- +description: "eth_getStorageAt JSON-RPC reference for MegaETH." +--- + +# eth_getStorageAt + +Returns the 32-byte value stored at a given contract storage slot at a specified block. + +## Parameters + +**`address`** Address **REQUIRED** + +Contract address. + +--- + +**`slot`** string **REQUIRED** + +Hex storage slot; use a 32-byte zero-padded value for portability. + +--- + +**`block`** string + +Hex block number, block hash, or tag (`latest`, `safe`, `finalized`, …). +The default is `"latest"`. + +## Returns + +**`result`** Bytes32 + +Raw 32-byte storage word; a zero value can mean an empty slot, a non-existent account, or an explicitly stored zero. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------ | ----------------------------------------------------- | +| `-32602` | Address, slot encoding, or block selector is malformed | Fix the request | +| `-32001` | Block selector cannot be resolved | Verify the block number or hash | +| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":63,"method":"eth_getStorageAt","params":["0x4200000000000000000000000000000000000011","0x0000000000000000000000000000000000000000000000000000000000000000","0xb11048"]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 63, + "result": "0x000000000000000000000000000000000000000000000001bce8287cf283cc16", +} // raw 32-byte word at slot 0, block 11,604,040 +``` diff --git a/docs/dev/read/rpc/eth_getTransactionByHash.md b/docs/dev/read/rpc/eth_getTransactionByHash.md new file mode 100644 index 0000000..c056280 --- /dev/null +++ b/docs/dev/read/rpc/eth_getTransactionByHash.md @@ -0,0 +1,98 @@ +--- +description: "eth_getTransactionByHash JSON-RPC reference for MegaETH." +--- + +# eth_getTransactionByHash + +Returns a transaction by its hash. + +## Parameters + +**`transactionHash`** Hash32 **REQUIRED** + +Target transaction hash. + +## Returns + +`Transaction | null` — `null` when the transaction cannot be found. + +- **`hash`** Hash32 + + Transaction hash. + +- **`type`** Quantity + + Transaction type identifier. + +- **`from`** Address + + Sender. + +- **`to`** Address | null + + Recipient; `null` for contract creation. + +- **`value`** Quantity + + Transfer value in wei. + +- **`nonce`** Quantity + + Sender nonce. + +- **`gas`** Quantity + + Gas limit. + +- **`input`** Data + + Calldata. + +- **`blockHash`** Hash32 | null + + `null` for pending transactions. + +- **`blockNumber`** Quantity | null + + `null` for pending transactions. + +- **`transactionIndex`** Quantity | null + + `null` for pending transactions. + +Additional fields vary by transaction type (`gasPrice`, `maxFeePerGas`, `accessList`, `chainId`, `v`, `r`, `s`, etc.). + +## Errors + +| Code | Cause | Fix | +| -------- | ---------------------------------------- | --------------- | +| `-32602` | Transaction hash is missing or malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":79,"method":"eth_getTransactionByHash","params":["0x89f0ccba20d5bbbe1cb6b44fb8d1f9a9e14b620a0b947a3de81cff684462f60c"]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 79, + "result": { + "type": "0x0", + "hash": "0x89f0ccba20d5bbbe1cb6b44fb8d1f9a9e14b620a0b947a3de81cff684462f60c", + "from": "0xa887dcb9d5f39ef79272801d05abdf707cfbbd1d", + "to": "0x6342000000000000000000000000000000000001", + "nonce": "0x597ac57", + "gas": "0x3d5720", + "value": "0x0", + "blockHash": "0xf773491fd24617452b30c3ed626bf440b5846b9c818ec7d8d7f71c9a02993c8b", + "blockNumber": "0xb120c6", + "transactionIndex": "0x1" + } +} +``` diff --git a/docs/dev/read/rpc/eth_getTransactionCount.md b/docs/dev/read/rpc/eth_getTransactionCount.md new file mode 100644 index 0000000..0480a4e --- /dev/null +++ b/docs/dev/read/rpc/eth_getTransactionCount.md @@ -0,0 +1,49 @@ +--- +description: "eth_getTransactionCount JSON-RPC reference for MegaETH." +--- + +# eth_getTransactionCount + +Returns the number of transactions sent from an address at a given block. + +## Parameters + +**`address`** Address **REQUIRED** + +Target account address. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +## Returns + +**`result`** Quantity + +Transaction count at the requested block. +The method returns `0x0` for both unknown accounts and accounts with zero transactions. + +## Errors + +| Code | Cause | Fix | +| -------- | ----------------------------------------- | ----------------------------------------------------- | +| `-32602` | Malformed address or block selector | Fix the request | +| `-32001` | Block selector cannot be resolved | Verify the block number or hash | +| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":91,"method":"eth_getTransactionCount","params":["0xa344fb2d117501ee379d2ea9c0c016959ad94f1e","0xb120c6"]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 91, "result": "0xfa8c" } // 64,140 transactions (block 11,608,262) +``` diff --git a/docs/dev/read/rpc/eth_getTransactionReceipt.md b/docs/dev/read/rpc/eth_getTransactionReceipt.md new file mode 100644 index 0000000..29f9ebc --- /dev/null +++ b/docs/dev/read/rpc/eth_getTransactionReceipt.md @@ -0,0 +1,95 @@ +--- +description: "eth_getTransactionReceipt JSON-RPC reference for MegaETH." +--- + +# eth_getTransactionReceipt + +Returns a transaction receipt by hash. + +## Parameters + +**`transactionHash`** Hash32 **REQUIRED** + +Hash of the target transaction. + +## Returns + +`Receipt | null` — `null` when the transaction is unknown or not yet mined. + +- **`transactionHash`** Hash32 + + Transaction hash. + +- **`status`** Quantity + + `0x1` success; `0x0` failure. + +- **`blockHash`** Hash32 + + Containing block hash. + +- **`blockNumber`** Quantity + + Containing block number. + +- **`from`** Address + + Sender. + +- **`to`** Address | null + + Recipient; `null` for contract creation. + +- **`gasUsed`** Quantity + + Gas consumed by this transaction. + +- **`effectiveGasPrice`** Quantity + + Effective gas price. + +- **`contractAddress`** Address | null + + Created contract address when applicable. + +- **`logs`** Log[] + + Emitted log entries. + +Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). + +## Errors + +| Code | Cause | Fix | +| -------- | ---------------------------------------- | --------------- | +| `-32602` | Transaction hash is missing or malformed | Fix the request | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":120,"method":"eth_getTransactionReceipt","params":["0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6"]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 120, + "result": { + "type": "0x2", + "status": "0x1", + "transactionHash": "0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6", + "blockHash": "0xf773491fd24617452b30c3ed626bf440b5846b9c818ec7d8d7f71c9a02993c8b", + "blockNumber": "0xb120c6", + "gasUsed": "0x215ec", + "effectiveGasPrice": "0xf4241", + "from": "0xa344fb2d117501ee379d2ea9c0c016959ad94f1e", + "to": "0x5e3ae52eba0f9740364bd5dd39738e1336086a8b", + "contractAddress": null, + "l1Fee": "0x4ab5901" + } +} +``` diff --git a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md new file mode 100644 index 0000000..f96728b --- /dev/null +++ b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md @@ -0,0 +1,82 @@ +--- +description: "Returns an uncle block by parent block hash and uncle index." +--- + +# eth_getUncleByBlockHashAndIndex + +## Summary + +Returns an uncle block selected by its parent block hash and index. +MegaETH blocks do not contain proof-of-work uncles, so the method returns `null` for valid MegaETH blocks. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ----------- | ---------------- | -------- | ------------------------------------------------ | +| `0` | `blockHash` | `DATA`, 32 bytes | Yes | Hash of the block whose uncle list is inspected. | +| `1` | `index` | `QUANTITY` | Yes | Zero-based uncle index. | + +## Result + +The result is a block object or `null` when no uncle exists at the selected index. +On MegaETH, `null` is expected and does not mean that the parent block itself is missing. + +## MegaETH Behavior + +### Ethereum Standard + +The method returns the uncle header at the selected index as a block object without transactions. + +### MegaETH Node Behavior + +MegaETH inherits the compatibility method, but its proof-of-stake L2 blocks do not contain proof-of-work uncles. + +### MegaETH Public Gateway + +The gateway may cache immutable hash selections. +A lookup at index zero for a valid Mainnet block returned `null` on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Method | Invalid params | The block hash or index is missing or malformed. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific errors were observed for a canonical lookup. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: null + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getUncleByBlockHashAndIndex", + "params": [ + "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d", + "0x0" + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": null +} +``` + +## Sources + +- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md new file mode 100644 index 0000000..0b8faa2 --- /dev/null +++ b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md @@ -0,0 +1,79 @@ +--- +description: "Returns an uncle block by parent block number and uncle index." +--- + +# eth_getUncleByBlockNumberAndIndex + +## Summary + +Returns an uncle block selected by its parent block number or tag and index. +MegaETH blocks do not contain proof-of-work uncles, so the method returns `null` for valid MegaETH blocks. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------- | ----------------------- | -------- | ------------------------------------------------------------------------ | +| `0` | `block` | `QUANTITY` or block tag | Yes | Block number or `latest`, `safe`, `finalized`, `earliest`, or `pending`. | +| `1` | `index` | `QUANTITY` | Yes | Zero-based uncle index. | + +## Result + +The result is a block object or `null` when no uncle exists at the selected index. +On MegaETH, `null` is expected and does not mean that the parent block itself is missing. + +## MegaETH Behavior + +### Ethereum Standard + +The method returns the uncle header at the selected index as a block object without transactions. + +### MegaETH Node Behavior + +MegaETH inherits the compatibility method, but its proof-of-stake L2 blocks do not contain proof-of-work uncles. + +### MegaETH Public Gateway + +The gateway may cache immutable selections and treats head tags as dynamic. +A lookup at index zero for the `latest` block returned `null` on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ---------------------------------------------------- | +| `-32602` | Method | Invalid params | The block selector or index is missing or malformed. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific errors were observed for a canonical lookup. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: null + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getUncleByBlockNumberAndIndex", + "params": ["latest", "0x0"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": null +} +``` + +## Sources + +- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md new file mode 100644 index 0000000..e8af343 --- /dev/null +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md @@ -0,0 +1,81 @@ +--- +description: "Returns the number of uncle blocks referenced by a MegaETH block selected by hash." +--- + +# eth_getUncleCountByBlockHash + +## Summary + +Returns the number of uncle blocks referenced by a block selected by hash. +MegaETH does not produce proof-of-work uncles, so valid MegaETH blocks return zero. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ----------- | ---------------- | -------- | ----------------------------- | +| `0` | `blockHash` | `DATA`, 32 bytes | Yes | Hash of the block to inspect. | + +## Result + +The result is a hexadecimal `QUANTITY` containing the uncle count. +For a valid MegaETH block this is zero. + +## MegaETH Behavior + +### Ethereum Standard + +The method returns the number of uncles referenced by the selected block. + +### MegaETH Node Behavior + +MegaETH inherits the compatibility method, but its proof-of-stake L2 blocks do not contain proof-of-work uncles. + +### MegaETH Public Gateway + +The gateway may cache the count for a block hash. +A valid Mainnet block returned an uncle count of zero on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Method | Invalid params | The block hash is missing or malformed. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific errors were observed for a valid block. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getUncleCountByBlockHash", + "params": [ + "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d" + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0" +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockHash.mdx) +- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md new file mode 100644 index 0000000..eb247a9 --- /dev/null +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md @@ -0,0 +1,79 @@ +--- +description: "Returns the number of uncle blocks referenced by a MegaETH block selected by number." +--- + +# eth_getUncleCountByBlockNumber + +## Summary + +Returns the number of uncle blocks referenced by a block selected by number or tag. +MegaETH does not produce proof-of-work uncles, so valid MegaETH blocks return zero. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------- | ----------------------- | -------- | ------------------------------------------------------------------------ | +| `0` | `block` | `QUANTITY` or block tag | Yes | Block number or `latest`, `safe`, `finalized`, `earliest`, or `pending`. | + +## Result + +The result is a hexadecimal `QUANTITY` containing the uncle count. +For a valid MegaETH block this is zero. + +## MegaETH Behavior + +### Ethereum Standard + +The method returns the number of uncles referenced by the selected block. + +### MegaETH Node Behavior + +MegaETH inherits the compatibility method, but its proof-of-stake L2 blocks do not contain proof-of-work uncles. + +### MegaETH Public Gateway + +The gateway may cache immutable selections and treats head tags as dynamic. +The `latest` block returned an uncle count of zero on July 24, 2026. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Method | Invalid params | The block selector is missing or malformed. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific errors were observed for a valid block. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getUncleCountByBlockNumber", + "params": ["latest"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0" +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockNumber.mdx) +- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/read/rpc/eth_getWithdrawalProof.md new file mode 100644 index 0000000..ad13a94 --- /dev/null +++ b/docs/dev/read/rpc/eth_getWithdrawalProof.md @@ -0,0 +1,35 @@ +--- +description: "Returns a withdrawal-storage proof for MegaETH's L2-to-L1 message passer contract." +--- + +# eth_getWithdrawalProof + +Returns the same proof as [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md). +The gateway routes both method names to the same node implementation. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------------- | ------------------- | -------- | ------------------------------------------------------------------ | +| `0` | `address` | `Address` | Yes | Must be `0x4200000000000000000000000000000000000016`. | +| `1` | `storageKeys` | `Bytes32[]` | Yes | Withdrawal-message storage keys to prove; an empty array is valid. | +| `2` | `block` | block number or tag | Yes | State against which to build the proof. | + +## Returns + +An EIP-1186-style account proof containing `accountProof`, `balance`, `codeHash`, `nonce`, `storageHash`, and one `storageProof` entry per requested key. + +## Errors + +The parameters, errors, and response fields are identical to [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md#errors). + +## Example + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getWithdrawalProof", + "params": ["0x4200000000000000000000000000000000000016", [], "latest"] +} +``` diff --git a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md new file mode 100644 index 0000000..5b6d3aa --- /dev/null +++ b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md @@ -0,0 +1,35 @@ +--- +description: "eth_maxPriorityFeePerGas JSON-RPC reference for MegaETH." +--- + +# eth_maxPriorityFeePerGas + +Returns the recommended priority fee per gas in wei. +MegaETH returns `0x0` because priority fees are not needed under the current fee policy. + +## Parameters + +None. + +## Returns + +**`result`** Quantity + +Always `0x0`. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_maxPriorityFeePerGas","params":[]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x0" } +``` diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/read/rpc/eth_protocolVersion.md new file mode 100644 index 0000000..2b00467 --- /dev/null +++ b/docs/dev/read/rpc/eth_protocolVersion.md @@ -0,0 +1,76 @@ +--- +description: "Returns the Ethereum protocol version reported by the MegaETH RPC node." +--- + +# eth_protocolVersion + +## Summary + +Returns the Ethereum protocol version reported by the connected node. +The public MegaETH endpoint supports this legacy compatibility method. + +## Parameters + +None. + +## Result + +The result is a hexadecimal `QUANTITY`. +Do not confuse this compatibility value with the MegaETH chain ID or network ID. + +## MegaETH Behavior + +### Ethereum Standard + +The legacy method reports an Ethereum wire-protocol version and takes no parameters. + +### MegaETH Node Behavior + +MegaETH exposes the inherited compatibility method through the `eth` namespace. + +### MegaETH Public Gateway + +The gateway treats this response as immutable and may cache it. +The value shown in the example was observed on July 24, 2026, but callers should not use it for chain selection; use [`eth_chainId`](./eth_chainId.md) instead. + +## Errors + +The `| Scope |` column distinguishes request failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Request | Invalid params | Unexpected parameters are supplied. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific errors were observed. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_protocolVersion", + "params": [] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x5" +} +``` + +## Sources + +- Node: [mega-reth Ethereum RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) +- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_sendRawTransaction.md b/docs/dev/read/rpc/eth_sendRawTransaction.md new file mode 100644 index 0000000..69471c6 --- /dev/null +++ b/docs/dev/read/rpc/eth_sendRawTransaction.md @@ -0,0 +1,46 @@ +--- +description: "eth_sendRawTransaction JSON-RPC reference for MegaETH." +--- + +# eth_sendRawTransaction + +Submits a signed transaction to the network and returns its transaction hash. + +## Parameters + +**`rawTx`** Data **REQUIRED** + +Signed, RLP-encoded transaction bytes. +Supported envelope types are legacy, EIP-2930 (`0x01`), EIP-1559 (`0x02`), EIP-4844 (`0x03`), and EIP-7702 (`0x04`). + +## Returns + +**`result`** Data + +32-byte transaction hash. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | +| `-32602` | Parameter missing, hex malformed, or bytes cannot be decoded as a signed transaction | Fix the transaction | +| `-32000` | Pool or gateway rule violation | Fix the field identified in `error.message` | +| `-32003` | Insufficient sender funds, pool at capacity, or unsupported transaction type | Fund the sender or wait for pool capacity | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_sendRawTransaction","params":["0xf86c808405763d658261a894aa000000000000000000000000000000000000000a8255448718e5bb3abd109fa0c8e3b4a0087357bd49d80a0ac24daf0c91191e71086c1e355fc62cfab2218873a074f4636f740fa4d1697b6e736e5982b700be2c8b63031a24fa531ae4814b3af8"]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x66734e85ef096167acb887cf445946a1ed57b90b66ffe38af87e11294febbfa9" +} +``` diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/read/rpc/eth_sendRawTransactionSync.md new file mode 100644 index 0000000..ab27f33 --- /dev/null +++ b/docs/dev/read/rpc/eth_sendRawTransactionSync.md @@ -0,0 +1,117 @@ +--- +description: "eth_sendRawTransactionSync JSON-RPC reference for MegaETH." +--- + +# eth_sendRawTransactionSync + +Submits a signed transaction and returns a receipt once the transaction is included in a block. + +## Parameters + +**`data`** Data **REQUIRED** + +Signed raw transaction bytes. + +--- + +**`timeoutMs`** number + +Client wait budget in milliseconds. +When omitted, the node uses its 5-second default; the public gateway caps explicit values at `3000` (3 s). + +## Returns + +- **`transactionHash`** Hash32 + + Transaction hash. + +- **`status`** Quantity + + `0x1` success; `0x0` failure (the transaction reverted but was included on-chain). + +- **`blockHash`** Hash32 + + Containing block hash. + +- **`blockNumber`** Quantity + + Containing block number. + +- **`from`** Address + + Sender. + +- **`to`** Address | null + + Recipient; `null` for contract creation. + +- **`gasUsed`** Quantity + + Gas consumed by this transaction. + +- **`effectiveGasPrice`** Quantity + + Effective gas price. + +- **`contractAddress`** Address | null + + Created contract address when applicable. + +- **`logs`** Log[] + + Emitted log entries. + +Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| `-32602` | Raw transaction is malformed, undecodable, or `timeoutMs` is invalid | Fix the request | +| `-32000` | Receipt not available before the wait window expired, or the node rejected the transaction | Treat as inconclusive — the transaction may still land; inspect the error message | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{ + "jsonrpc": "2.0", + "id": 91, + "method": "eth_sendRawTransactionSync", + "params": [ + "0xf86480830f424082ea6094cc4b43ab7230cc5913801a746c1834aa06c4e7e780808231b2a0b8126d2c41a6c7dbd0a9e219233497057bb391e7ee1d628370f9c1456f82b054a06663fde9daa2fae784c3dac1c9a5a973d538e3a12ec9c0e4d3cee9c70ba2b239", + 3000 + ] + }' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 91, + "result": { + "type": "0x0", + "status": "0x1", + "transactionHash": "0x8d3b1e22e7a9026c8658b5d922293d59e4de7c3382bb832d6890e6ab23ad7ec7", + "transactionIndex": "0x5", + "blockHash": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", + "blockNumber": "0xe7133c", // 15,143,740 + "from": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", + "to": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", + "gasUsed": "0xea60", // 60,000 + "effectiveGasPrice": "0xf4240", // 1,000,000 wei + "cumulativeGasUsed": "0x143043", + "contractAddress": null, + "logs": [], + "l1GasPrice": "0x3216", + "l1GasUsed": "0x640", + "l1Fee": "0x6da0", + "l1BaseFeeScalar": "0x558", + "l1BlobBaseFee": "0x1", + "l1BlobBaseFeeScalar": "0x0", + }, +} +``` diff --git a/docs/dev/read/rpc/eth_syncing.md b/docs/dev/read/rpc/eth_syncing.md new file mode 100644 index 0000000..18b88b5 --- /dev/null +++ b/docs/dev/read/rpc/eth_syncing.md @@ -0,0 +1,62 @@ +--- +description: "eth_syncing JSON-RPC reference for MegaETH." +--- + +# eth_syncing + +Returns whether the node is currently syncing. + +## Parameters + +None. + +## Returns + +`false` when the node is fully synced. When syncing, a `SyncProgress` object: + +- **`startingBlock`** Quantity + + Sync start point. + +- **`currentBlock`** Quantity + + Current progress. + +- **`highestBlock`** Quantity + + Target block. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_syncing","params":[]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": false +} +``` + +When syncing: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "startingBlock": "0x0", + "currentBlock": "0xaeb3d0", + "highestBlock": "0xaeb3d6" + } +} +``` diff --git a/docs/dev/read/rpc/eth_unsubscribe.md b/docs/dev/read/rpc/eth_unsubscribe.md new file mode 100644 index 0000000..fc370a2 --- /dev/null +++ b/docs/dev/read/rpc/eth_unsubscribe.md @@ -0,0 +1,39 @@ +--- +description: "eth_unsubscribe JSON-RPC reference for MegaETH." +--- + +# eth_unsubscribe + +Cancels an existing subscription so that no further events are sent. + +## Parameters + +**`subscriptionId`** Data **REQUIRED** + +Subscription ID returned by `eth_subscribe`. + +## Returns + +**`result`** boolean + +`true` if the subscription was found and cancelled; `false` if the ID was not active. + +## Errors + +| Code | Cause | Fix | +| -------- | -------------------------------------------------- | -------------------------------------------------------- | +| `-32602` | Subscription ID parameter is missing | Provide the subscription ID returned by `eth_subscribe` | +| `-32600` | Subscription was created by a different connection | Cancel from the connection that created the subscription | + +See also [Error reference](error-codes.md). + +## Example + +```bash +wscat -c wss://mainnet.megaeth.com/ws +> {"jsonrpc":"2.0","id":1,"method":"eth_unsubscribe","params":["0xaec58cfc2dc41f873fc37d6c871230c1"]} +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": true } +``` diff --git a/docs/dev/read/rpc/mega_getBlockWitness.md b/docs/dev/read/rpc/mega_getBlockWitness.md new file mode 100644 index 0000000..8ce9b2a --- /dev/null +++ b/docs/dev/read/rpc/mega_getBlockWitness.md @@ -0,0 +1,56 @@ +--- +description: "mega_getBlockWitness JSON-RPC reference for MegaETH." +--- + +# mega_getBlockWitness + +Returns the execution witness for a block. + +## Parameters + +**`keys`** object **REQUIRED** + +Block lookup key. + +- **`blockNumber`** Quantity **REQUIRED** + + Target block number. + +- **`blockHash`** Hash32 + + Block hash for the same block number. + Always include it when available so the lookup is pinned to a specific fork. + +{% hint style="warning" %} +A `blockNumber`-only lookup returns the first stored witness at that height and is not reorg-safe. +Use `blockNumber` together with `blockHash` for production verification. +{% endhint %} + +## Returns + +**`result`** string + +`v0:` followed by a base64-encoded zstd-compressed witness blob. + +## Errors + +| Code | Cause | Fix | +| -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| `-32602` | `blockNumber` missing, invalid hex value, or invalid hash field combination | Fix the request | +| `-32603` | No witness exists for the requested keys, or the witness service failed | Inspect the message; `Witness not found` is an expected availability miss | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"mega_getBlockWitness","params":[{"blockNumber":"0x7fd","blockHash":"0x262206173864c1e597ab9fcf2f718f95f942907207f4fed97dda66d272c5d4a6"}]}' +``` + +```jsonc +{ "jsonrpc": "2.0", "id": 1, "result": "v0:KLUv/QBgzVUAZJwh…" } // base64-encoded zstd blob, truncated +``` + +For decoding details and network coverage, see [Get block witness](../../../node/witness.md). diff --git a/docs/dev/read/rpc/mega_getWithdrawalProof.md b/docs/dev/read/rpc/mega_getWithdrawalProof.md new file mode 100644 index 0000000..8fe776d --- /dev/null +++ b/docs/dev/read/rpc/mega_getWithdrawalProof.md @@ -0,0 +1,90 @@ +--- +description: "mega_getWithdrawalProof JSON-RPC reference for MegaETH." +--- + +# mega_getWithdrawalProof + +Returns a Merkle proof for the L2ToL1MessagePasser contract at a given block. + +## Parameters + +**`address`** Address **REQUIRED** + +The contract address to prove. +For withdrawal verification, use the L2-to-L1 message passer address `0x4200000000000000000000000000000000000016`. + +--- + +**`storageKeys`** Bytes32[] **REQUIRED** + +Storage keys to prove; empty array is valid. + +--- + +**`block`** string **REQUIRED ON THE PUBLIC GATEWAY** + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The node defaults an omitted value to `latest`, but the public endpoint requires all three positional parameters. + +## Returns + +- **`address`** Address + + Proved address. + +- **`accountProof`** Data[] + + Account trie proof nodes. + +- **`balance`** Quantity + + Account balance. + +- **`codeHash`** Hash32 + + Account code hash. + +- **`nonce`** Quantity + + Account nonce. + +- **`storageHash`** Hash32 + + Storage trie root. + +- **`storageProof`** object[] + + Per-key storage proofs; each entry has `key` (`Bytes32`), `value` (`Bytes32`), `proof` (`Data[]`). + +## Errors + +| Code | Cause | Fix | +| -------- | ----------------------------------------------------------------------------------- | -------------------------- | +| `-32602` | A storage key is not a valid 32-byte hex string, or required parameters are missing | Fix the request | +| `-32000` | The requested block cannot be resolved | Verify the block reference | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"mega_getWithdrawalProof","params":["0x4200000000000000000000000000000000000016",[],"latest"]}' +``` + +```jsonc +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "address": "0x4200000000000000000000000000000000000016", + "balance": "0x0", + "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + "nonce": "0x0", + "storageHash": "0xddd6dcaf75eeb81fb4701c2a39b3132bd60bf9602e2fcbe5852f5d07e14c8084", + "accountProof": [], + "storageProof": [], + }, +} +``` diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/read/rpc/mega_outputAtBlock.md new file mode 100644 index 0000000..d3bbe62 --- /dev/null +++ b/docs/dev/read/rpc/mega_outputAtBlock.md @@ -0,0 +1,110 @@ +--- +description: "mega_outputAtBlock JSON-RPC reference for MegaETH." +--- + +# mega_outputAtBlock + +Returns the output root at a given block. + +## Parameters + +**`blockNumber`** Quantity **REQUIRED** + +Concrete hex block number; block tags such as `latest` are not accepted. + +## Returns + +- **`version`** Hash32 + + Output version. + +- **`outputRoot`** Hash32 + + Output commitment. + +- **`blockRef`** object + + Block reference; see fields below. + + - **`hash`** Hash32 + + Block hash. + + - **`number`** number + + Block number (JSON number). + + - **`parentHash`** Hash32 + + Parent block hash. + + - **`timestamp`** number + + Block timestamp (JSON number). + + - **`l1origin`** object + + L1 origin with `hash` and `number`. + + - **`sequenceNumber`** number + + Sequence number. + +- **`withdrawalStorageRoot`** Hash32 + + Withdrawal storage root. + +- **`stateRoot`** Hash32 + + State root. + +- **`syncStatus`** object + + Backend sync-status snapshot. + +## Errors + +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `-32602` | Missing block number, wrong parameter count, or block tag instead of hex block number | Fix the request parameters | +| `-32603` | Backend cannot produce output data for the requested block | Retry transient failures; inspect the error message for details | + +See also [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":301,"method":"mega_outputAtBlock","params":["0x100"]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 301, + "result": { + "version": "0x0000000000000000000000000000000000000000000000000000000000000000", + "outputRoot": "0xe41251ac90623f6a303572f9abea7d48a259fdb5812d36fdc3102abc69a62f97", + "blockRef": { + "hash": "0x716a59d9fa50a9c225cbd4319bde1f1eccb9e8c3cacee8d7bda0dec17e1d9b34", + "number": 256, + "parentHash": "0xa1b2c3d4e5f60718293a4b5c6d7e8f9001122334455667788990aabbccddeeff", + "timestamp": 1762797267, + "l1origin": { + "hash": "0x0011223344556677889900aabbccddeeff0011223344556677889900aabbccdd", + "number": 21000000 + }, + "sequenceNumber": 0 + }, + "syncStatus": { + "current_l1": { "hash": "0xaabb…", "number": 24732192 }, + "unsafe_l2": { "hash": "0x8899…", "number": 11615881 }, + "safe_l2": { "hash": "0x8899…", "number": 11615881 }, + "finalized_l2": { "hash": "0x7788…", "number": 11615800 } + }, + "withdrawalStorageRoot": "0x8ed4baae3a927be3dea54996b4d5899f8c01e7594bf50b17dc1e741388ce3d12", + "stateRoot": "0xf5e1d1c08df99fabc86c73c2f88f137f63a880e9776315964f0c8ac77ae86305" + } +} +``` diff --git a/docs/dev/read/rpc/net_listening.md b/docs/dev/read/rpc/net_listening.md new file mode 100644 index 0000000..8f295f9 --- /dev/null +++ b/docs/dev/read/rpc/net_listening.md @@ -0,0 +1,34 @@ +--- +description: "net_listening JSON-RPC reference for MegaETH." +--- + +# net_listening + +Returns whether the node is listening for connections. + +## Parameters + +None. + +## Returns + +**`result`** boolean + +Always `true`. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"net_listening","params":[]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": true } +``` diff --git a/docs/dev/read/rpc/net_peerCount.md b/docs/dev/read/rpc/net_peerCount.md new file mode 100644 index 0000000..15b9824 --- /dev/null +++ b/docs/dev/read/rpc/net_peerCount.md @@ -0,0 +1,34 @@ +--- +description: "net_peerCount JSON-RPC reference for MegaETH." +--- + +# net_peerCount + +Returns the number of peers currently connected to the node. + +## Parameters + +None. + +## Returns + +**`result`** Quantity + +Number of connected peers. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"net_peerCount","params":[]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "0x4" } +``` diff --git a/docs/dev/read/rpc/net_version.md b/docs/dev/read/rpc/net_version.md new file mode 100644 index 0000000..03e320f --- /dev/null +++ b/docs/dev/read/rpc/net_version.md @@ -0,0 +1,34 @@ +--- +description: "net_version JSON-RPC reference for MegaETH." +--- + +# net_version + +Returns the current network ID. + +## Parameters + +None. + +## Returns + +**`result`** string + +Network ID as a decimal integer string. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"net_version","params":[]}' +``` + +```json +{ "jsonrpc": "2.0", "id": 1, "result": "4326" } +``` diff --git a/docs/dev/read/rpc/optimism_outputAtBlock.md b/docs/dev/read/rpc/optimism_outputAtBlock.md new file mode 100644 index 0000000..23f48ee --- /dev/null +++ b/docs/dev/read/rpc/optimism_outputAtBlock.md @@ -0,0 +1,34 @@ +--- +description: "Returns the OP Stack output-root data for a MegaETH block." +--- + +# optimism_outputAtBlock + +Returns the same output-root data as [`mega_outputAtBlock`](./mega_outputAtBlock.md). +The two names are aliases on MegaETH. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ------------- | ---------- | -------- | --------------------------------------------------------------- | +| `0` | `blockNumber` | `QUANTITY` | Yes | Concrete hexadecimal block number; block tags are not accepted. | + +## Returns + +An output object containing `version`, `outputRoot`, `blockRef`, `withdrawalStorageRoot`, `stateRoot`, and `syncStatus`. +See [`mega_outputAtBlock`](./mega_outputAtBlock.md#returns) for every field. + +## Errors + +The validation and backend errors are identical to [`mega_outputAtBlock`](./mega_outputAtBlock.md#errors). + +## Example + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "optimism_outputAtBlock", + "params": ["0x100"] +} +``` diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md index 2ef86dd..2dec8de 100644 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/read/rpc/realtime_sendRawTransaction.md @@ -6,13 +6,15 @@ description: realtime_sendRawTransaction — submit a transaction and receive th Submits a signed transaction and returns the receipt directly once the transaction is executed — no polling required. This is a drop-in replacement for `eth_sendRawTransaction` that eliminates the need to poll `eth_getTransactionReceipt`. -The method times out after 10 seconds if the transaction has not been executed. +When no timeout is supplied, the node uses its 5-second default wait. +The public gateway accepts an optional timeout but caps it at 3,000 milliseconds. ## Parameters -| Position | Type | Required | Notes | -| -------- | ------ | -------- | ------------------------------ | -| `0` | `Data` | Yes | Hex-encoded signed transaction | +| Position | Type | Required | Notes | +| -------- | -------- | -------- | ------------------------------------------------------------- | +| `0` | `Data` | Yes | Hex-encoded signed transaction | +| `1` | `number` | No | Wait timeout in milliseconds; capped at `3000` by the gateway | ## Returns @@ -31,9 +33,9 @@ A transaction receipt object on success: ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------------------------------------------------- | ------------------------------------------------ | -| `-32000` | `realtime transaction expired` — transaction not executed within 10 seconds | Fall back to polling `eth_getTransactionReceipt` | +| Code | Cause | Fix | +| -------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `-32000` | `realtime transaction expired` — receipt not available before the wait expired | The transaction may still land; poll `eth_getTransactionReceipt` | See also [Error reference](error-codes.md). @@ -42,7 +44,7 @@ See also [Error reference](error-codes.md). ```bash curl -sS https://mainnet.megaeth.com/rpc \ -X POST -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":1,"method":"realtime_sendRawTransaction","params":["0x"]}' + -d '{"jsonrpc":"2.0","id":1,"method":"realtime_sendRawTransaction","params":["0x",3000]}' ``` Successful response: diff --git a/docs/dev/read/rpc/web3_clientVersion.md b/docs/dev/read/rpc/web3_clientVersion.md new file mode 100644 index 0000000..863f27d --- /dev/null +++ b/docs/dev/read/rpc/web3_clientVersion.md @@ -0,0 +1,38 @@ +--- +description: "web3_clientVersion JSON-RPC reference for MegaETH." +--- + +# web3_clientVersion + +Returns the current client version string. + +## Parameters + +None. + +## Returns + +**`result`** string + +Client name, version, and build target. + +## Errors + +Standard JSON-RPC errors only. +See [Error reference](error-codes.md). + +## Example + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]}' +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "mega-reth/v2.0.17-97ab2f0@mnet-sgp-rpc-2" +} +``` diff --git a/lychee.toml b/lychee.toml index 3cfc41e..f1fc459 100644 --- a/lychee.toml +++ b/lychee.toml @@ -9,7 +9,7 @@ offline = true root_dir = "docs" # Check anchor fragments (#section-name) -include_fragments = "full" +include_fragments = true # Skip these URL patterns (regex) exclude = [ From b363af0a45198e13727f1a920d984dcd4607ce87 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 17:43:51 +0800 Subject: [PATCH 02/13] ci: pin lychee config version --- .mise.toml | 2 +- lychee.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.mise.toml b/.mise.toml index 52027c9..e8a0ff0 100644 --- a/.mise.toml +++ b/.mise.toml @@ -1,5 +1,5 @@ [tools] -lychee = "latest" +lychee = "0.24.2" "npm:markdownlint-cli2" = "latest" # Pinned: prettier >= 3.9.0 mangles GitBook template tags ({% tab %}/{% endtab %}) # into markdown table rows, breaking page rendering. Re-evaluate before bumping. diff --git a/lychee.toml b/lychee.toml index f1fc459..3cfc41e 100644 --- a/lychee.toml +++ b/lychee.toml @@ -9,7 +9,7 @@ offline = true root_dir = "docs" # Check anchor fragments (#section-name) -include_fragments = true +include_fragments = "full" # Skip these URL patterns (regex) exclude = [ From 34b4a74094dfa4be27f7b6a0567f10263311718c Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 18:18:47 +0800 Subject: [PATCH 03/13] docs: address RPC reference review feedback --- docs/SUMMARY.md | 1 + docs/dev/read/overview.md | 6 ++ docs/dev/read/rpc/README.md | 7 +- docs/dev/read/rpc/debug_getRawHeader.md | 4 +- docs/dev/read/rpc/debug_traceBlockByHash.md | 4 +- docs/dev/read/rpc/debug_traceBlockByNumber.md | 4 +- docs/dev/read/rpc/debug_traceTransaction.md | 4 +- docs/dev/read/rpc/eth_callMany.md | 5 +- .../rpc/eth_getUncleByBlockHashAndIndex.md | 4 +- .../rpc/eth_getUncleByBlockNumberAndIndex.md | 4 +- .../read/rpc/eth_getUncleCountByBlockHash.md | 4 +- .../rpc/eth_getUncleCountByBlockNumber.md | 4 +- docs/dev/read/rpc/eth_getWithdrawalProof.md | 10 +-- docs/dev/read/rpc/eth_protocolVersion.md | 4 +- .../read/rpc/eth_sendRawTransactionSync.md | 3 + docs/dev/read/rpc/eth_uninstallFilter.md | 79 +++++++++++++++++++ docs/dev/read/rpc/mega_outputAtBlock.md | 34 +++++--- .../read/rpc/realtime_sendRawTransaction.md | 5 ++ docs/dev/send-tx/debugging.md | 8 +- 19 files changed, 151 insertions(+), 43 deletions(-) create mode 100644 docs/dev/read/rpc/eth_uninstallFilter.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 009c955..9993466 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -66,6 +66,7 @@ - [eth_sendRawTransactionSync](dev/read/rpc/eth_sendRawTransactionSync.md) - [eth_subscribe](dev/read/rpc/eth_subscribe.md) - [eth_syncing](dev/read/rpc/eth_syncing.md) + - [eth_uninstallFilter](dev/read/rpc/eth_uninstallFilter.md) - [eth_unsubscribe](dev/read/rpc/eth_unsubscribe.md) - [mega_getBlockWitness](dev/read/rpc/mega_getBlockWitness.md) - [mega_getWithdrawalProof](dev/read/rpc/mega_getWithdrawalProof.md) diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 2c99041..1a67754 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -55,6 +55,8 @@ Managed providers may expose additional methods. | `eth_getBlockTransactionCountByNumber` | Available | | | `eth_getCode` | Available | | | `eth_getCodeByHash` | Available | MegaETH-specific. | +| `eth_getFilterChanges` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getFilterLogs` | Unavailable | The public endpoint returns `-32601`. | | `eth_getHeaderByHash` | Available | MegaETH-specific. | | `eth_getHeaderByNumber` | Available | MegaETH-specific. | | `eth_getLogs` | Available | | @@ -72,11 +74,15 @@ Managed providers may expose additional methods. | `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | | `eth_maxPriorityFeePerGas` | Available | | | `eth_mining` | Unavailable | The node reports the method as unimplemented. | +| `eth_newBlockFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newPendingTransactionFilter` | Unavailable | The public endpoint returns `-32601`. | | `eth_protocolVersion` | Available | Legacy compatibility method. | | `eth_sendRawTransaction` | Available | | | `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | | `eth_subscribe` | WebSocket only | Supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`. | | `eth_syncing` | Available | | +| `eth_uninstallFilter` | Available | Returns `false` when the filter ID does not exist. | | `eth_unsubscribe` | WebSocket only | | | `mega_getBlockWitness` | Available | MegaETH-specific. | | `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | diff --git a/docs/dev/read/rpc/README.md b/docs/dev/read/rpc/README.md index cae7162..b71c9b4 100644 --- a/docs/dev/read/rpc/README.md +++ b/docs/dev/read/rpc/README.md @@ -1,13 +1,13 @@ --- -description: "Complete reference for the 50 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." +description: "Complete reference for the 51 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." --- # RPC Reference -The public MegaETH gateway exposes 48 HTTP methods and two WebSocket subscription methods. +The public MegaETH gateway exposes 49 HTTP methods and two WebSocket subscription methods. This reference is based on the gateway registry, node implementation, and public Mainnet behavior verified on July 24, 2026. -Use the [availability table](../overview.md#available-methods) for recognized methods that are disabled on the public endpoint and for methods offered only by managed providers. +Use the [availability table](../overview.md#available-methods) for methods that are disabled or unsupported on the public endpoint. See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. ## State and simulation @@ -45,6 +45,7 @@ See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. - [`eth_getLogs`](./eth_getLogs.md) - [`eth_subscribe`](./eth_subscribe.md) — WebSocket only +- [`eth_uninstallFilter`](./eth_uninstallFilter.md) - [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only ## Fees and transaction submission diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/read/rpc/debug_getRawHeader.md index d979a18..1b3eb51 100644 --- a/docs/dev/read/rpc/debug_getRawHeader.md +++ b/docs/dev/read/rpc/debug_getRawHeader.md @@ -76,6 +76,6 @@ The RLP value is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/getters.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/getters.yaml) -- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/read/rpc/debug_traceBlockByHash.md index ba24420..507a1ed 100644 --- a/docs/dev/read/rpc/debug_traceBlockByHash.md +++ b/docs/dev/read/rpc/debug_traceBlockByHash.md @@ -94,6 +94,6 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) -- Gateway: [mega-rpc streaming trace processor](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/processors/debug-trace-processor.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/processors/debug-trace-processor.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/read/rpc/debug_traceBlockByNumber.md index c624b05..4db6cc1 100644 --- a/docs/dev/read/rpc/debug_traceBlockByNumber.md +++ b/docs/dev/read/rpc/debug_traceBlockByNumber.md @@ -89,6 +89,6 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) -- Gateway: [mega-rpc streaming trace processor](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/processors/debug-trace-processor.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/processors/debug-trace-processor.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/read/rpc/debug_traceTransaction.md index 0ccf6a5..fc36e62 100644 --- a/docs/dev/read/rpc/debug_traceTransaction.md +++ b/docs/dev/read/rpc/debug_traceTransaction.md @@ -86,6 +86,6 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Node: [mega-reth debug RPC API](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-api/src/debug.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/read/rpc/eth_callMany.md index ced152e..84de9b9 100644 --- a/docs/dev/read/rpc/eth_callMany.md +++ b/docs/dev/read/rpc/eth_callMany.md @@ -93,7 +93,6 @@ Outcome: success ## Sources -- Node: [mega-reth `eth_callMany` implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc call-many adapter](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/services/call-many/mega-call-many-adapter.ts) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/services/call-many/mega-call-many-adapter.ts` and `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md index f96728b..ccc8a03 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md @@ -77,6 +77,6 @@ Outcome: null ## Sources -- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md index 0b8faa2..6b9eaa7 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md @@ -74,6 +74,6 @@ Outcome: null ## Sources -- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md index e8af343..39422e5 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md @@ -76,6 +76,6 @@ Outcome: success ## Sources - Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockHash.mdx) -- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md index eb247a9..5d20ccc 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md @@ -74,6 +74,6 @@ Outcome: success ## Sources - Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockNumber.mdx) -- Node: [mega-reth block-query RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/read/rpc/eth_getWithdrawalProof.md index ad13a94..b48b9b3 100644 --- a/docs/dev/read/rpc/eth_getWithdrawalProof.md +++ b/docs/dev/read/rpc/eth_getWithdrawalProof.md @@ -9,11 +9,11 @@ The gateway routes both method names to the same node implementation. ## Parameters -| Position | Name | Type | Required | Description | -| -------- | ------------- | ------------------- | -------- | ------------------------------------------------------------------ | -| `0` | `address` | `Address` | Yes | Must be `0x4200000000000000000000000000000000000016`. | -| `1` | `storageKeys` | `Bytes32[]` | Yes | Withdrawal-message storage keys to prove; an empty array is valid. | -| `2` | `block` | block number or tag | Yes | State against which to build the proof. | +| Position | Name | Type | Required | Description | +| -------- | ------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `0` | `address` | `Address` | Yes | Contract address to prove; use `0x4200000000000000000000000000000000000016` for withdrawal verification. | +| `1` | `storageKeys` | `Bytes32[]` | Yes | Withdrawal-message storage keys to prove; an empty array is valid. | +| `2` | `block` | block number or tag | Yes | State against which to build the proof. | ## Returns diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/read/rpc/eth_protocolVersion.md index 2b00467..a6a2044 100644 --- a/docs/dev/read/rpc/eth_protocolVersion.md +++ b/docs/dev/read/rpc/eth_protocolVersion.md @@ -71,6 +71,6 @@ Outcome: success ## Sources -- Node: [mega-reth Ethereum RPC implementation](https://github.com/megaeth-labs/mega-reth/blob/0264d0821a8fe14ac6c7f710e9452edef7407b3f/crates/rpc/rpc-eth-api/src/core.rs) -- Gateway: [mega-rpc method registry](https://github.com/megaeth-labs/mega-rpc/blob/06aa35aa95d569c227cc25d2aa12834eb0458aa0/workers/src/spec/methods.ts) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) +- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/read/rpc/eth_sendRawTransactionSync.md index ab27f33..d55fd50 100644 --- a/docs/dev/read/rpc/eth_sendRawTransactionSync.md +++ b/docs/dev/read/rpc/eth_sendRawTransactionSync.md @@ -5,6 +5,7 @@ description: "eth_sendRawTransactionSync JSON-RPC reference for MegaETH." # eth_sendRawTransactionSync Submits a signed transaction and returns a receipt once the transaction is included in a block. +The public gateway routes this method and [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) through the same synchronous submission handler, with the same parameters and receipt result. ## Parameters @@ -32,6 +33,8 @@ When omitted, the node uses its 5-second default; the public gateway caps explic - **`blockHash`** Hash32 Containing block hash. + A receipt produced from a streaming mini-block can temporarily contain the all-`ff` placeholder hash until the enclosing EVM block is committed. + Refetch the receipt with `eth_getTransactionReceipt` after block sealing when a canonical block hash is required. - **`blockNumber`** Quantity diff --git a/docs/dev/read/rpc/eth_uninstallFilter.md b/docs/dev/read/rpc/eth_uninstallFilter.md new file mode 100644 index 0000000..43a641c --- /dev/null +++ b/docs/dev/read/rpc/eth_uninstallFilter.md @@ -0,0 +1,79 @@ +--- +description: "Removes an Ethereum log or block filter by ID." +--- + +# eth_uninstallFilter + +## Summary + +Removes a filter and releases the node resources associated with it. +The public MegaETH endpoint accepts this standard method even though filter-creation and filter-polling methods are not publicly supported. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | ---------- | ---------- | -------- | ------------------------------------------------ | +| `0` | `filterId` | `QUANTITY` | Yes | Identifier returned by a filter-creation method. | + +## Result + +Returns `true` when the filter existed and was removed. +Returns `false` when the filter ID was unknown or had already expired. +`false` does not mean that `eth_uninstallFilter` itself is unavailable. + +## MegaETH Behavior + +### Ethereum Standard + +Clients should uninstall a filter when it is no longer needed so the node can release its resources. + +### MegaETH Node Behavior + +MegaETH inherits the standard filter-removal handler and returns a boolean indicating whether a filter was removed. + +### MegaETH Public Gateway + +The method returned `false` for an unknown filter ID on July 24, 2026. +The public endpoint returned method-not-found errors for `eth_newFilter`, `eth_newBlockFilter`, `eth_newPendingTransactionFilter`, `eth_getFilterChanges`, and `eth_getFilterLogs` on the same date, so public clients normally use [`eth_subscribe`](./eth_subscribe.md) instead of filter polling. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | --------------------------------------------------- | +| `-32602` | Method | Invalid params | The filter ID is missing or malformed. | +| `-32099` | Transport/policy | Payload too large | The request exceeds the public endpoint body limit. | + +No method-specific error was observed for a canonical request. + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: false + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_uninstallFilter", + "params": ["0x1"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": false +} +``` + +## Sources + +- Spec: [Ethereum Execution APIs, `src/eth/filter.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/eth/filter.yaml) +- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc/src/eth/filter.rs` (internal repository) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/read/rpc/mega_outputAtBlock.md index d3bbe62..1ec4191 100644 --- a/docs/dev/read/rpc/mega_outputAtBlock.md +++ b/docs/dev/read/rpc/mega_outputAtBlock.md @@ -79,32 +79,46 @@ curl -sS https://mainnet.megaeth.com/rpc \ --data '{"jsonrpc":"2.0","id":301,"method":"mega_outputAtBlock","params":["0x100"]}' ``` +The response below is illustrative; hashes and sync-status values are synthetic. + ```json { "jsonrpc": "2.0", "id": 301, "result": { "version": "0x0000000000000000000000000000000000000000000000000000000000000000", - "outputRoot": "0xe41251ac90623f6a303572f9abea7d48a259fdb5812d36fdc3102abc69a62f97", + "outputRoot": "0x0000000000000000000000000000000000000000000000000000000000000001", "blockRef": { - "hash": "0x716a59d9fa50a9c225cbd4319bde1f1eccb9e8c3cacee8d7bda0dec17e1d9b34", + "hash": "0x0000000000000000000000000000000000000000000000000000000000000002", "number": 256, - "parentHash": "0xa1b2c3d4e5f60718293a4b5c6d7e8f9001122334455667788990aabbccddeeff", + "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000003", "timestamp": 1762797267, "l1origin": { - "hash": "0x0011223344556677889900aabbccddeeff0011223344556677889900aabbccdd", + "hash": "0x0000000000000000000000000000000000000000000000000000000000000004", "number": 21000000 }, "sequenceNumber": 0 }, "syncStatus": { - "current_l1": { "hash": "0xaabb…", "number": 24732192 }, - "unsafe_l2": { "hash": "0x8899…", "number": 11615881 }, - "safe_l2": { "hash": "0x8899…", "number": 11615881 }, - "finalized_l2": { "hash": "0x7788…", "number": 11615800 } + "current_l1": { + "hash": "0x0000000000000000000000000000000000000000000000000000000000000011", + "number": 24732192 + }, + "unsafe_l2": { + "hash": "0x0000000000000000000000000000000000000000000000000000000000000012", + "number": 11615881 + }, + "safe_l2": { + "hash": "0x0000000000000000000000000000000000000000000000000000000000000013", + "number": 11615881 + }, + "finalized_l2": { + "hash": "0x0000000000000000000000000000000000000000000000000000000000000014", + "number": 11615800 + } }, - "withdrawalStorageRoot": "0x8ed4baae3a927be3dea54996b4d5899f8c01e7594bf50b17dc1e741388ce3d12", - "stateRoot": "0xf5e1d1c08df99fabc86c73c2f88f137f63a880e9776315964f0c8ac77ae86305" + "withdrawalStorageRoot": "0x0000000000000000000000000000000000000000000000000000000000000005", + "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000006" } } ``` diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md index 2dec8de..ae5486a 100644 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/read/rpc/realtime_sendRawTransaction.md @@ -8,6 +8,7 @@ Submits a signed transaction and returns the receipt directly once the transacti This is a drop-in replacement for `eth_sendRawTransaction` that eliminates the need to poll `eth_getTransactionReceipt`. When no timeout is supplied, the node uses its 5-second default wait. The public gateway accepts an optional timeout but caps it at 3,000 milliseconds. +The gateway routes this method and [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) through the same synchronous submission handler, so their parameters and receipt behavior are equivalent. ## Parameters @@ -23,6 +24,7 @@ A transaction receipt object on success: | Field | Type | Notes | | ----------------- | ----------------- | ------------------------------------------------ | | `transactionHash` | `Data` (32 bytes) | Hash of the submitted transaction | +| `blockHash` | `Data` (32 bytes) | Block containing the transaction | | `blockNumber` | `Quantity` | Block containing the transaction | | `from` | `Data` (20 bytes) | Sender address | | `to` | `Data` (20 bytes) | Recipient address (`null` for contract creation) | @@ -31,6 +33,9 @@ A transaction receipt object on success: | `logs` | `Log[]` | Event logs emitted during execution | | `contractAddress` | `Data` (20 bytes) | Deployed contract address, or `null` | +For receipts produced from a streaming mini-block, `blockHash` can temporarily be the all-`ff` placeholder until the enclosing EVM block is committed. +Refetch the receipt with `eth_getTransactionReceipt` after block sealing when a canonical block hash is required. + ## Errors | Code | Cause | Fix | diff --git a/docs/dev/send-tx/debugging.md b/docs/dev/send-tx/debugging.md index 3c9d519..f19a353 100644 --- a/docs/dev/send-tx/debugging.md +++ b/docs/dev/send-tx/debugging.md @@ -11,13 +11,13 @@ MegaETH provides two ways to debug transactions: ## Debug RPC Methods -Standard Ethereum debug methods are available on the public MegaETH RPC endpoint (`https://mainnet.megaeth.com/rpc`) and through managed RPC providers such as [Alchemy](https://www.alchemy.com/). +The public MegaETH RPC endpoint supports tracing mined transactions and blocks. +It does not support `debug_traceCall`; use `mega-evme` for local call simulation or check whether a managed RPC provider exposes that method. The following methods are supported: -- **`debug_traceTransaction`** — trace an already-mined transaction by hash -- **`debug_traceCall`** — simulate and trace a call without broadcasting -- **`debug_traceBlockByNumber`** / **`debug_traceBlockByHash`** — trace all transactions in a block +- **[`debug_traceTransaction`](../read/rpc/debug_traceTransaction.md)** — trace an already-mined transaction by hash +- **[`debug_traceBlockByNumber`](../read/rpc/debug_traceBlockByNumber.md)** / **[`debug_traceBlockByHash`](../read/rpc/debug_traceBlockByHash.md)** — trace all transactions in a block ### Supported Tracers From c645a25d0d249b5b61d999f8992a770630577ab8 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 18:37:29 +0800 Subject: [PATCH 04/13] docs: reconcile realtime transaction guidance --- docs/dev/send-tx/debugging.md | 2 +- docs/dev/send-tx/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/send-tx/debugging.md b/docs/dev/send-tx/debugging.md index f19a353..2a885c0 100644 --- a/docs/dev/send-tx/debugging.md +++ b/docs/dev/send-tx/debugging.md @@ -12,7 +12,7 @@ MegaETH provides two ways to debug transactions: ## Debug RPC Methods The public MegaETH RPC endpoint supports tracing mined transactions and blocks. -It does not support `debug_traceCall`; use `mega-evme` for local call simulation or check whether a managed RPC provider exposes that method. +It does not support `debug_traceCall`; use [`mega-evme`](#simulating-a-new-transaction) for local call simulation or check whether a managed RPC provider exposes that method. The following methods are supported: diff --git a/docs/dev/send-tx/overview.md b/docs/dev/send-tx/overview.md index 42df71b..a6bfa24 100644 --- a/docs/dev/send-tx/overview.md +++ b/docs/dev/send-tx/overview.md @@ -119,7 +119,7 @@ curl -s https://mainnet.megaeth.com/rpc \ ``` Returns the full transaction receipt directly. -Times out after 10 seconds if the transaction has not been executed. +The node waits up to 5 seconds by default; the public gateway caps an explicit timeout at 3,000 milliseconds and returns `-32000 realtime transaction expired` if the deadline elapses first. See [`realtime_sendRawTransaction`](../read/rpc/realtime_sendRawTransaction.md) for the full reference. {% endtab %} {% endtabs %} From 048439366279d13ea6ba16a1ca859dbd7b43298e Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 18:55:28 +0800 Subject: [PATCH 05/13] docs: reconcile RPC reference with current main --- .gitbook.yaml | 4 ++++ docs/dev/read/overview.md | 3 +-- docs/dev/read/rpc/error-codes.md | 20 +++++++++++--------- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/.gitbook.yaml b/.gitbook.yaml index 23dad3a..fff1fc7 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -3,3 +3,7 @@ root: ./docs/ structure: readme: README.md summary: SUMMARY.md + +redirects: + dev/read/rpc/eth_callAfter: dev/read/overview.md#available-methods + dev/read/rpc/eth_getLogsWithCursor: dev/read/overview.md#available-methods diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 89a3227..7b2d474 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -105,7 +105,7 @@ Each method belongs to one of four categories, and each category has its own req | Category | Limit (per 10 s) | Methods | | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | | Instant | 2,000 | `eth_chainId`, `eth_blockNumber`, `net_version`, `eth_accounts`, `web3_clientVersion`, `eth_getBalance`, `eth_getStorageAt` | -| Simple | 500 | Block/transaction queries, `eth_callAfter`, and all other read methods not listed in another category | +| Simple | 500 | Block/transaction queries and all other read methods not listed in another category | | Compute | 200 | `eth_call`, `eth_callMany`, `eth_estimateGas`, `eth_createAccessList`, `debug_trace*`, `trace_*` | | IO-heavy | 200 | `eth_getLogs`, `eth_getBlockReceipts` | @@ -114,7 +114,6 @@ Additional notes: - Transaction submission methods (`eth_sendRawTransaction`, `realtime_sendRawTransaction`) are not subject to these read rate limits. - Cache hits still consume the method's per-category budget. - `eth_callMany` consumes one Compute-category request per inner transaction, not one per HTTP request. -- `eth_callAfter` uses the Simple-category budget even though it shares `eth_call`'s 60,000,000 compute-gas cap. - A rate-limited request is rejected with HTTP `429` and RPC error `-32005` (`Rate limit exceeded`) — see [Error Codes](rpc/error-codes.md). Reduce request frequency, or use batching or WebSocket subscriptions to lower the request count. ## Request Body Limits diff --git a/docs/dev/read/rpc/error-codes.md b/docs/dev/read/rpc/error-codes.md index a384036..f2f4249 100644 --- a/docs/dev/read/rpc/error-codes.md +++ b/docs/dev/read/rpc/error-codes.md @@ -4,15 +4,17 @@ description: MegaETH JSON-RPC error codes — HTTP status codes, RPC error codes # Error Codes -| HTTP Error Code | RPC Error Code | Error Message | Explanation | Mitigation | -| --------------- | -------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| 400 | -32700 | `parse error` | The request body contains invalid JSON. | Check the request format and ensure valid JSON syntax. | -| 413 | -32099 | `payload too large` | The request body exceeds the size limit for the method being called. | Stay within the body-size limit for the method class. See [Request Body Limits](../overview.md#request-body-limits). | -| 403 | -32601 | `rpc method is not whitelisted` | The requested RPC method is not allowed by the proxy configuration. | Use only whitelisted RPC methods. Contact MegaETH if you need access to additional methods. | -| 400 | -32019 | `block is out of range` | The requested block number is out of range. | Check the block number and ensure it's within the valid range. | -| 500 | -32020 | `backend response too large` | The backend response is too large. | Reduce the scope of the request or contact MegaETH for assistance. | -| 429 | -32005 | `Rate limit exceeded` | The request exceeds the rate limit for its method category. | Reduce request frequency, or use batching or WebSocket subscriptions. See [Rate Limiting](../overview.md#rate-limiting). | -| 200 | -32000 | `permanent error forwarding request context deadline exceeded` | The API proxy cannot connect to the backend RPC server. | Pause for a while and retry. Notify MegaETH if the error persists. | +| HTTP Error Code | RPC Error Code | Error Message | Explanation | Mitigation | +| --------------- | -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| 400 | -32700 | `parse error` | The request body contains invalid JSON. | Check the request format and ensure valid JSON syntax. | +| 413 | -32099 | `payload too large` | The request body exceeds the size limit for the method being called. | Stay within the body-size limit for the method class. See [Request Body Limits](../overview.md#request-body-limits). | +| 403 | -32601 | `rpc method is not whitelisted` | The requested RPC method is not allowed by the proxy configuration. | Use only whitelisted RPC methods. Contact MegaETH if you need access to additional methods. | +| 200 | -32001 | `Resource not found` | The requested block, header, or other resource could not be resolved. | Verify the block number or hash and retry. | +| 200 | 4444 | `pruned history unavailable` | The node no longer retains the requested historical state or data. | Use a newer block or an endpoint with the required historical-state retention. | +| 400 | -32019 | `block is out of range` | The requested block number is out of range. | Check the block number and ensure it's within the valid range. | +| 500 | -32020 | `backend response too large` | The backend response is too large. | Reduce the scope of the request or contact MegaETH for assistance. | +| 429 | -32005 | `Rate limit exceeded` | The request exceeds the rate limit for its method category. | Reduce request frequency, or use batching or WebSocket subscriptions. See [Rate Limiting](../overview.md#rate-limiting). | +| 200 | -32000 | `permanent error forwarding request context deadline exceeded` | The API proxy cannot connect to the backend RPC server. | Pause for a while and retry. Notify MegaETH if the error persists. | Older references to `-32021` or `-32022` refer to the previous rate-limit codes. The public gateway now returns `-32005` for rate-limited requests. From 4fef1d8ba6bae218d3b89bc4dd3abf89bdca01ee Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Fri, 24 Jul 2026 19:14:26 +0800 Subject: [PATCH 06/13] docs: complete public RPC policy guidance --- docs/dev/read/overview.md | 12 ++++++------ docs/dev/read/rpc/debug_getRawHeader.md | 2 -- docs/dev/read/rpc/debug_traceBlockByHash.md | 2 -- docs/dev/read/rpc/debug_traceBlockByNumber.md | 2 -- docs/dev/read/rpc/debug_traceTransaction.md | 2 -- docs/dev/read/rpc/eth_callMany.md | 2 -- docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md | 2 -- .../read/rpc/eth_getUncleByBlockNumberAndIndex.md | 2 -- docs/dev/read/rpc/eth_getUncleCountByBlockHash.md | 2 -- docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md | 2 -- docs/dev/read/rpc/eth_protocolVersion.md | 2 -- docs/dev/read/rpc/eth_uninstallFilter.md | 1 - 12 files changed, 6 insertions(+), 27 deletions(-) diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 7b2d474..834ea5b 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -111,7 +111,7 @@ Each method belongs to one of four categories, and each category has its own req Additional notes: -- Transaction submission methods (`eth_sendRawTransaction`, `realtime_sendRawTransaction`) are not subject to these read rate limits. +- Transaction submission methods (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) are not subject to these read rate limits. - Cache hits still consume the method's per-category budget. - `eth_callMany` consumes one Compute-category request per inner transaction, not one per HTTP request. - A rate-limited request is rejected with HTTP `429` and RPC error `-32005` (`Rate limit exceeded`) — see [Error Codes](rpc/error-codes.md). Reduce request frequency, or use batching or WebSocket subscriptions to lower the request count. @@ -120,11 +120,11 @@ Additional notes: The public RPC endpoint caps the size of the request body, and the cap depends on the method being called: -| Method class | Maximum body size | -| --------------------------------------------------------------------------------------------------- | ----------------- | -| Transaction submission (`eth_sendRawTransaction`, `realtime_sendRawTransaction`) | 2.5 MiB | -| Large reads and simulations (`eth_call`, `eth_callMany`, `eth_createAccessList`, `eth_estimateGas`) | 1.5 MiB | -| All other methods | 128 KiB | +| Method class | Maximum body size | +| -------------------------------------------------------------------------------------------------------------- | ----------------- | +| Transaction submission (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) | 2.5 MiB | +| Large reads and simulations (`eth_call`, `eth_callMany`, `eth_createAccessList`, `eth_estimateGas`) | 1.5 MiB | +| All other methods | 128 KiB | The higher limits for simulation methods let you estimate gas for or simulate large contract deployments, whose initcode can exceed the 128 KiB default. A request whose body exceeds the applicable limit is rejected with HTTP `413` and RPC error `-32099` (`payload too large`) — see [Error Codes](rpc/error-codes.md). diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/read/rpc/debug_getRawHeader.md index 1b3eb51..d0db656 100644 --- a/docs/dev/read/rpc/debug_getRawHeader.md +++ b/docs/dev/read/rpc/debug_getRawHeader.md @@ -76,6 +76,4 @@ The RLP value is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/getters.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/getters.yaml) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/read/rpc/debug_traceBlockByHash.md index 507a1ed..2b143de 100644 --- a/docs/dev/read/rpc/debug_traceBlockByHash.md +++ b/docs/dev/read/rpc/debug_traceBlockByHash.md @@ -94,6 +94,4 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/processors/debug-trace-processor.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/read/rpc/debug_traceBlockByNumber.md index 4db6cc1..64c2020 100644 --- a/docs/dev/read/rpc/debug_traceBlockByNumber.md +++ b/docs/dev/read/rpc/debug_traceBlockByNumber.md @@ -89,6 +89,4 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/processors/debug-trace-processor.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/read/rpc/debug_traceTransaction.md index fc36e62..e0d6ad9 100644 --- a/docs/dev/read/rpc/debug_traceTransaction.md +++ b/docs/dev/read/rpc/debug_traceTransaction.md @@ -86,6 +86,4 @@ The nested call frame is abbreviated below. ## Sources - Spec: [Ethereum Execution APIs, `src/debug/trace.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/debug/trace.yaml) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-api/src/debug.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/read/rpc/eth_callMany.md index 84de9b9..b8df01f 100644 --- a/docs/dev/read/rpc/eth_callMany.md +++ b/docs/dev/read/rpc/eth_callMany.md @@ -93,6 +93,4 @@ Outcome: success ## Sources -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/services/call-many/mega-call-many-adapter.ts` and `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md index ccc8a03..a775f96 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md @@ -77,6 +77,4 @@ Outcome: null ## Sources -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md index 6b9eaa7..734d6cf 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md @@ -74,6 +74,4 @@ Outcome: null ## Sources -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md index 39422e5..9cd2885 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md @@ -76,6 +76,4 @@ Outcome: success ## Sources - Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockHash.mdx) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md index 5d20ccc..4b46e14 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md @@ -74,6 +74,4 @@ Outcome: success ## Sources - Spec: [Ethereum Execution APIs method reference](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/docs-api/api/methods/eth_getUncleCountByBlockNumber.mdx) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/read/rpc/eth_protocolVersion.md index a6a2044..34cf9cb 100644 --- a/docs/dev/read/rpc/eth_protocolVersion.md +++ b/docs/dev/read/rpc/eth_protocolVersion.md @@ -71,6 +71,4 @@ Outcome: success ## Sources -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc-eth-api/src/core.rs` (internal repository) -- Code: `mega-rpc@06aa35aa95d569c227cc25d2aa12834eb0458aa0`, `workers/src/spec/methods.ts` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_uninstallFilter.md b/docs/dev/read/rpc/eth_uninstallFilter.md index 43a641c..c5bc8ff 100644 --- a/docs/dev/read/rpc/eth_uninstallFilter.md +++ b/docs/dev/read/rpc/eth_uninstallFilter.md @@ -75,5 +75,4 @@ Outcome: false ## Sources - Spec: [Ethereum Execution APIs, `src/eth/filter.yaml`](https://github.com/ethereum/execution-apis/blob/50d1e5e0b6f5a5046e45421e5c84497ab6e55e6c/src/eth/filter.yaml) -- Code: `mega-reth@0264d0821a8fe14ac6c7f710e9452edef7407b3f`, `crates/rpc/rpc/src/eth/filter.rs` (internal repository) - Probe: MegaETH Mainnet public endpoint, July 24, 2026 From ac991ad1af004db2255d0affb6df999552ac8e06 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 16:06:31 +0800 Subject: [PATCH 07/13] docs: document MegaETH RPC behavior --- docs/dev/execution/system-contracts.md | 2 +- docs/dev/faq.md | 11 +- docs/dev/read/overview.md | 4 +- .../rpc/debug_getHistoryTransactionCount.md | 70 +++++-- docs/dev/read/rpc/eth_accounts.md | 66 ++++++- docs/dev/read/rpc/eth_blockNumber.md | 68 ++++++- docs/dev/read/rpc/eth_call.md | 78 ++++++-- docs/dev/read/rpc/eth_chainId.md | 68 ++++++- docs/dev/read/rpc/eth_createAccessList.md | 71 +++++-- docs/dev/read/rpc/eth_estimateGas.md | 81 ++++++-- docs/dev/read/rpc/eth_feeHistory.md | 61 ++++-- docs/dev/read/rpc/eth_gasPrice.md | 68 ++++++- docs/dev/read/rpc/eth_getBalance.md | 74 +++++-- docs/dev/read/rpc/eth_getBlockByHash.md | 65 +++++-- docs/dev/read/rpc/eth_getBlockByNumber.md | 87 +++++++-- docs/dev/read/rpc/eth_getBlockReceipts.md | 88 ++++++--- .../rpc/eth_getBlockTransactionCountByHash.md | 70 +++++-- .../eth_getBlockTransactionCountByNumber.md | 68 +++++-- docs/dev/read/rpc/eth_getCode.md | 72 +++++-- docs/dev/read/rpc/eth_getCodeByHash.md | 71 +++++-- docs/dev/read/rpc/eth_getHeaderByHash.md | 72 +++++-- docs/dev/read/rpc/eth_getHeaderByNumber.md | 70 +++++-- docs/dev/read/rpc/eth_getLogs.md | 88 +++++++-- docs/dev/read/rpc/eth_getStorageAt.md | 74 +++++-- docs/dev/read/rpc/eth_getTransactionByHash.md | 62 +++++- docs/dev/read/rpc/eth_getTransactionCount.md | 74 +++++-- .../dev/read/rpc/eth_getTransactionReceipt.md | 64 ++++-- docs/dev/read/rpc/eth_getWithdrawalProof.md | 64 +++++- docs/dev/read/rpc/eth_maxPriorityFeePerGas.md | 70 +++++-- docs/dev/read/rpc/eth_sendRawTransaction.md | 67 +++++-- .../read/rpc/eth_sendRawTransactionSync.md | 92 ++++++--- docs/dev/read/rpc/eth_subscribe.md | 184 +++++++----------- docs/dev/read/rpc/eth_syncing.md | 64 ++++-- docs/dev/read/rpc/eth_unsubscribe.md | 65 +++++-- docs/dev/read/rpc/mega_getBlockWitness.md | 87 +++++++-- docs/dev/read/rpc/mega_getWithdrawalProof.md | 68 +++++-- docs/dev/read/rpc/mega_outputAtBlock.md | 109 +++++++---- docs/dev/read/rpc/net_listening.md | 66 ++++++- docs/dev/read/rpc/net_peerCount.md | 66 ++++++- docs/dev/read/rpc/net_version.md | 66 ++++++- docs/dev/read/rpc/optimism_outputAtBlock.md | 80 +++++++- .../read/rpc/realtime_sendRawTransaction.md | 56 ++++-- docs/dev/read/rpc/web3_clientVersion.md | 60 +++++- docs/dev/send-tx/gas-estimation.md | 12 +- docs/dev/send-tx/overview.md | 5 +- 45 files changed, 2380 insertions(+), 648 deletions(-) diff --git a/docs/dev/execution/system-contracts.md b/docs/dev/execution/system-contracts.md index 5b3225b..5e2266a 100644 --- a/docs/dev/execution/system-contracts.md +++ b/docs/dev/execution/system-contracts.md @@ -142,7 +142,7 @@ Code deposit costs 10,000 storage gas per byte on MegaETH. A 24 KB contract costs roughly 240M storage gas. If `gasLimitOverride` is too low for this cost, the inner deployment will fail (out of gas) but the outer call still succeeds — check `errorData` and `deployedAddress`, and note the outer call is still charged the gas the failed attempt consumed. Simulate the transaction with [`mega-evme`](../send-tx/debugging.md#simulating-a-new-transaction) to find the required gas — it has no gas cap and fully implements MegaETH's gas model. -Alternatively, use `eth_estimateGas` on a MegaETH endpoint (subject to the [RPC compute gas cap](../send-tx/gas-estimation.md#the-rpc-compute-gas-cap)). +Alternatively, use `eth_estimateGas` on a MegaETH endpoint (subject to the [public RPC simulation limits](../send-tx/gas-estimation.md#public-rpc-simulation-limits)). {% endhint %} {% hint style="info" %} diff --git a/docs/dev/faq.md b/docs/dev/faq.md index 3952310..16857f7 100644 --- a/docs/dev/faq.md +++ b/docs/dev/faq.md @@ -46,12 +46,15 @@ See the [Contract Limits specification](https://docs.megaeth.com/spec/megaevm/co ## Transaction Lifecycle & Txpool -### What is the gas limit of `eth_call` / `eth_estimateGas`? +### What limits apply to `eth_call` and `eth_estimateGas`? -60,000,000 compute gas on the public RPC endpoint. +The public gateway adds a 60,000,000 compute-gas limit to `eth_call`. +It preserves the caller's total `gas` field, so this is a compute limit rather than a replacement total-gas limit. -Note that this limit is _different_ from the protocol per-transaction gas limit of 10,000,000,000. -It applies only to RPC simulation calls. +`eth_estimateGas` instead uses the node's CPU-limited estimator; the gateway's source default is 500,000,000 nanoseconds (0.5 seconds). +It does not add the same 60M compute-gas override. + +These RPC simulation limits are _different_ from the protocol per-transaction gas limit of 10,000,000,000. Managed RPC providers may allow higher limits. ### What is the maximum number of transactions I can have in the txpool? diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 834ea5b..098440f 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -43,8 +43,8 @@ Managed providers may expose additional methods. | `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | | `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | | `eth_chainId` | Available | | -| `eth_createAccessList` | Available | Compute gas limited to 60,000,000. | -| `eth_estimateGas` | Available | Compute gas limited to 60,000,000. | +| `eth_createAccessList` | Available | Routed to the compute pool; no separate 60M compute override is added. | +| `eth_estimateGas` | Available | Uses an internal CPU-time limit; the source default is 0.5 seconds. | | `eth_feeHistory` | Available | Block range limited to 256. | | `eth_gasPrice` | Available | | | `eth_getBalance` | Available | | diff --git a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md index c879f6a..9946852 100644 --- a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md +++ b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md @@ -4,8 +4,12 @@ description: "debug_getHistoryTransactionCount JSON-RPC reference for MegaETH." # debug_getHistoryTransactionCount +## Summary + Returns the chain-wide cumulative transaction count up to and including a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`block`** string **REQUIRED** @@ -13,30 +17,70 @@ Returns the chain-wide cumulative transaction count up to and including a given Hex block number or tag (`earliest`, `latest`, `safe`, `finalized`). `pending` is not supported. -## Returns +## Result **`result`** Quantity Cumulative transaction count across all blocks up to the selected block. Consecutive blocks with no transactions return the same value. +## MegaETH Behavior + +### Ethereum Standard + +`debug_getHistoryTransactionCount` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH debug extension. + +### MegaETH Node Behavior + +MegaETH adds this diagnostic method. It resolves the selected block and returns the cumulative transaction count through that block; `pending` is not a supported selector. + +### MegaETH Public Gateway + +The public gateway exposes the method in the simple read tier and caches resolved results as immutable data for 30 minutes. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------- | --------------- | -| `-32001` | Block selector cannot be resolved or unsupported tag such as `pending` was used | Fix the request | -| `-32602` | Invalid parameter shape | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------------------------- | +| `-32001` | Method | Resource not found | Block selector cannot be resolved or unsupported tag such as `pending` was used | +| `-32602` | Request | Invalid params | Invalid parameter shape | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"debug_getHistoryTransactionCount","params":["0x12a05f"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_getHistoryTransactionCount", + "params": ["0x12a05f"] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 1, "result": "0x12cbab" } // 1,231,787 total transactions through block 1,220,703 +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x12cbab" +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/debug.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_accounts.md b/docs/dev/read/rpc/eth_accounts.md index f3896a1..04b53a9 100644 --- a/docs/dev/read/rpc/eth_accounts.md +++ b/docs/dev/read/rpc/eth_accounts.md @@ -4,31 +4,79 @@ description: "eth_accounts JSON-RPC reference for MegaETH." # eth_accounts +## Summary + Returns a list of addresses controlled by the RPC node. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** Address[] Accounts controlled by the RPC node; always empty on public endpoints. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +A self-hosted node can report accounts only when its RPC environment manages keys. The execution client itself does not imply that the public service controls user accounts. + +### MegaETH Public Gateway + +The gateway does not query a signer or node. It synthesizes an empty array, so an empty result means only that the public endpoint does not manage user keys. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":41,"method":"eth_accounts","params":[]}' +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 41, + "method": "eth_accounts", + "params": [] +} ``` ```json -{ "jsonrpc": "2.0", "id": 41, "result": [] } +{ + "jsonrpc": "2.0", + "id": 41, + "result": [] +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/client.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/hardcoded-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026 diff --git a/docs/dev/read/rpc/eth_blockNumber.md b/docs/dev/read/rpc/eth_blockNumber.md index f78c593..f35fc4c 100644 --- a/docs/dev/read/rpc/eth_blockNumber.md +++ b/docs/dev/read/rpc/eth_blockNumber.md @@ -4,31 +4,79 @@ description: "eth_blockNumber JSON-RPC reference for MegaETH." # eth_blockNumber +## Summary + Returns the latest block number. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** Quantity Current head block number; advances with each new block. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns the current canonical EVM block height. Mini-blocks produced within the current EVM block do not each increment this number. + +### MegaETH Public Gateway + +The gateway uses the instant read tier and may cache the head number for 1 second. Applications that need mini-block cadence should use WebSocket subscriptions instead. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":21,"method":"eth_blockNumber","params":[]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 21, + "method": "eth_blockNumber", + "params": [] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 21, "result": "0xaeb3d6" } // block 11,449,302 +```json +{ + "jsonrpc": "2.0", + "id": 21, + "result": "0xaeb3d6" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/client.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_call.md b/docs/dev/read/rpc/eth_call.md index cdd9f6c..846049e 100644 --- a/docs/dev/read/rpc/eth_call.md +++ b/docs/dev/read/rpc/eth_call.md @@ -4,8 +4,12 @@ description: "eth_call JSON-RPC reference for MegaETH." # eth_call +## Summary + Simulates a transaction against a given block's state and returns the result without creating an on-chain transaction. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`transaction`** object **REQUIRED** @@ -126,7 +130,7 @@ Block environment overrides for this simulation. Override blob base fee. -## Returns +## Result **`result`** Data @@ -134,24 +138,72 @@ Raw return bytes. Calls to non-contract addresses return `0x`. Reverts surface as JSON-RPC errors, not as a normal result. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node simulates the call against the selected state without persisting changes. MegaETH's execution model applies its multidimensional execution limits in addition to the gas field. + +### MegaETH Public Gateway + +The gateway routes the request to the compute pool, rewrites it to `mega_callWithBlock`, buffers the rewritten response, and does not cache it. +It preserves the caller's `gas` field and separately supplies an internal compute-gas limit of 60,000,000; the internal limit caps compute gas without replacing the total gas budget. +The public endpoint permits a 1.5 MiB single-request body. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------------------------------- | ------------------------------------------------- | -| `-32602` | Malformed call object, block selector, or override object | Fix the request | -| `3` | Simulated execution reverted | Decode `error.data` and fix call conditions | -| `-32000` | Simulation failed or hit an execution limit | Inspect `error.message`; adjust gas or call shape | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Malformed call object, block selector, or override object | +| `3` | Method | Execution reverted | Simulated execution reverted | +| `-32000` | Method | Server error | Simulation failed or hit an execution limit | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples -See also [Error reference](error-codes.md). +Endpoint: `https://mainnet.megaeth.com/rpc` -## Example +Capture date: July 24, 2026 -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":46,"method":"eth_call","params":[{"to":"0x0000000000000000000000000000000000000004","input":"0x11223344"},"latest"]}' +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 46, + "method": "eth_call", + "params": [ + { + "to": "0x0000000000000000000000000000000000000004", + "input": "0x11223344" + }, + "latest" + ] +} ``` ```json -{ "jsonrpc": "2.0", "id": 46, "result": "0x11223344" } +{ + "jsonrpc": "2.0", + "id": 46, + "result": "0x11223344" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/execute.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/api.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/mega-call-with-block-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_chainId.md b/docs/dev/read/rpc/eth_chainId.md index fa2d58e..29fe78c 100644 --- a/docs/dev/read/rpc/eth_chainId.md +++ b/docs/dev/read/rpc/eth_chainId.md @@ -4,31 +4,79 @@ description: "eth_chainId JSON-RPC reference for MegaETH." # eth_chainId +## Summary + Returns the chain ID of the connected network. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** Quantity The chain ID for the connected network. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node derives this value from its chain specification. MegaETH Mainnet uses chain ID 4326; callers should read the value rather than hardcode it across environments. + +### MegaETH Public Gateway + +The gateway uses the instant read tier and caches the immutable result for 30 minutes. MegaETH Mainnet returned chain ID 4326 in the captured example. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":31,"method":"eth_chainId","params":[]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 31, + "method": "eth_chainId", + "params": [] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 31, "result": "0x10e6" } // 4326 (Mainnet) +```json +{ + "jsonrpc": "2.0", + "id": 31, + "result": "0x10e6" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/client.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_createAccessList.md b/docs/dev/read/rpc/eth_createAccessList.md index 74ae109..ac25989 100644 --- a/docs/dev/read/rpc/eth_createAccessList.md +++ b/docs/dev/read/rpc/eth_createAccessList.md @@ -4,8 +4,12 @@ description: "eth_createAccessList JSON-RPC reference for MegaETH." # eth_createAccessList +## Summary + Generates an access list for a transaction. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`transaction`** object **REQUIRED** @@ -91,7 +95,7 @@ Object keyed by address. Each value: Move a precompile to the specified address before `code` is applied. -## Returns +## Result - **`accessList`** array @@ -105,22 +109,58 @@ Object keyed by address. Each value: Execution error when the call reverts; may coexist with `accessList` and `gasUsed`. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node executes the call in access-list collection mode and returns both the accessed addresses and storage keys and the resulting gas usage. + +### MegaETH Public Gateway + +The gateway routes the method to the compute pool without response caching and permits a 1.5 MiB single-request body. +Unlike `eth_call`, gateway source does not add the separate 60,000,000 compute-gas override to this method. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------- | -------------------------------------- | -| `-32602` | Malformed transaction object or block selector | Fix the request | -| `-32000` | Pre-execution check failed (e.g. intrinsic gas too low) | Raise or remove the gas cap | -| `-32003` | Sender cannot cover gas and value in the selected state | Fund the sender or lower the value/fee | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------- | ------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Malformed transaction object or block selector | +| `-32000` | Method | Server error | Pre-execution check failed (e.g. intrinsic gas too low) | +| `-32003` | Method | Transaction rejected | Sender cannot cover gas and value in the selected state | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":7,"method":"eth_createAccessList","params":[{"to":"0x1111111111111111111111111111111111111111","input":"0x"},"latest"]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 7, + "method": "eth_createAccessList", + "params": [ + { + "to": "0x1111111111111111111111111111111111111111", + "input": "0x" + }, + "latest" + ] +} ``` ```json @@ -133,3 +173,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/execute.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/api.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_estimateGas.md b/docs/dev/read/rpc/eth_estimateGas.md index 2e740bb..5e1877f 100644 --- a/docs/dev/read/rpc/eth_estimateGas.md +++ b/docs/dev/read/rpc/eth_estimateGas.md @@ -4,8 +4,12 @@ description: "eth_estimateGas JSON-RPC reference for MegaETH." # eth_estimateGas +## Summary + Estimates the gas required to execute a transaction. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`transaction`** object **REQUIRED** @@ -91,30 +95,79 @@ Object keyed by address. Each value: Move a precompile to the specified address before `code` is applied. -## Returns +## Result **`result`** Quantity Estimated execution gas. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +MegaETH's estimator uses a 60,000-gas intrinsic floor for a basic transfer and supports state overrides. The node also exposes a CPU-limited variant used by the public gateway. + +### MegaETH Public Gateway + +The gateway routes the request to the compute pool and rewrites it to the node's `eth_estimateGasWithCpuLimit` method. +It does not cache the result and supplies an internal CPU-time limit whose source default is 500,000,000 nanoseconds (0.5 seconds). +This is distinct from `eth_call`'s 60,000,000 compute-gas limit. +The public endpoint permits a 1.5 MiB single-request body. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| `-32602` | Malformed transaction fields, fee model, or block selector | Fix the request | -| `-32000` | Estimation failed, hit a provider-side execution limit, or used a rejected explicit gas cap | Inspect `error.message` and adjust gas or call shape | -| `3` | Simulated execution reverted | Decode `error.data` and fix the call conditions | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed transaction fields, fee model, or block selector | +| `-32000` | Method | Server error | Estimation failed, hit a provider-side execution limit, or used a rejected explicit gas cap | +| `3` | Method | Execution reverted | Simulated execution reverted | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":57,"method":"eth_estimateGas","params":[{"to":"0x0000000000000000000000000000000000000000","value":"0x0"},"latest"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 57, + "method": "eth_estimateGas", + "params": [ + { + "to": "0x0000000000000000000000000000000000000000", + "value": "0x0" + }, + "latest" + ] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 57, "result": "0xea60" } // 60,000 gas +```json +{ + "jsonrpc": "2.0", + "id": 57, + "result": "0xea60" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/execute.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/replace.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_feeHistory.md b/docs/dev/read/rpc/eth_feeHistory.md index 6bf891e..c9b3a45 100644 --- a/docs/dev/read/rpc/eth_feeHistory.md +++ b/docs/dev/read/rpc/eth_feeHistory.md @@ -4,8 +4,12 @@ description: "eth_feeHistory JSON-RPC reference for MegaETH." # eth_feeHistory +## Summary + Returns historical gas fee data for a range of blocks. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`blockCount`** Quantity **REQUIRED** @@ -24,7 +28,7 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Monotonically increasing values from `0` to `100`; omit to exclude `reward` from the result. -## Returns +## Result - **`oldestBlock`** Quantity @@ -50,21 +54,49 @@ Monotonically increasing values from `0` to `100`; omit to exclude `reward` from Blob gas utilization ratio per block when available. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node implements the standard fee-history shape. The public gateway does not forward this method to the node, so node-derived fee history must not be inferred from public results. + +### MegaETH Public Gateway + +The gateway synthesizes this response locally instead of querying a node. It accepts 1 to 256 blocks and currently fills the response with a 1,000,000-wei base fee, 0.1 gas-used ratio, 1-wei blob base fee, zero blob utilization, and zero rewards. Treat these as gateway policy values, not measured historical blocks. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------------------------------------- | ------------------- | -| `-32602` | Invalid request shape or `blockCount` outside the allowed range | Fix the request | -| `-32000` | `blockCount` exceeds the endpoint limit | Reduce `blockCount` | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | --------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Invalid request shape or `blockCount` outside the allowed range | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":66,"method":"eth_feeHistory","params":["0x2","latest",[25,75]]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 66, + "method": "eth_feeHistory", + "params": ["0x2", "latest", [25, 75]] +} ``` ```json @@ -84,3 +116,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/fee_market.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/fee-history-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026 diff --git a/docs/dev/read/rpc/eth_gasPrice.md b/docs/dev/read/rpc/eth_gasPrice.md index a43bd41..b33bf99 100644 --- a/docs/dev/read/rpc/eth_gasPrice.md +++ b/docs/dev/read/rpc/eth_gasPrice.md @@ -4,32 +4,80 @@ description: "eth_gasPrice JSON-RPC reference for MegaETH." # eth_gasPrice +## Summary + Returns the current gas price in wei. Under MegaETH's current fee policy, this method returns `0xf4240` (1,000,000 wei = 0.001 gwei). +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** Quantity Gas price in wei. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node's gas oracle reflects the active MegaETH fee policy. On Mainnet the observed value was 1,000,000 wei, or 0.001 gwei. + +### MegaETH Public Gateway + +The gateway uses the simple read path and may cache the head-dependent result for 1 second. The captured Mainnet value was 1,000,000 wei, or 0.001 gwei. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_gasPrice", + "params": [] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 1, "result": "0xf4240" } // 1,000,000 wei +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf4240" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/fee_market.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getBalance.md b/docs/dev/read/rpc/eth_getBalance.md index c4086d8..0ee7b42 100644 --- a/docs/dev/read/rpc/eth_getBalance.md +++ b/docs/dev/read/rpc/eth_getBalance.md @@ -4,8 +4,12 @@ description: "eth_getBalance JSON-RPC reference for MegaETH." # eth_getBalance +## Summary + Returns the ETH balance of an account in wei at a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`address`** Address **REQUIRED** @@ -19,31 +23,71 @@ Target account or contract address. Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). The default is `"latest"`. -## Returns +## Result **`result`** Quantity Balance in wei. -The method returns `0x0` for unknown accounts and zero-balance accounts alike. +The method returns a zero quantity for unknown accounts and zero-balance accounts alike. + +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node reads the account balance from the selected state. `latest` and `pending` can include state already visible through MegaETH's real-time mini-block pipeline. + +### MegaETH Public Gateway + +For `latest` or `pending`, the gateway rewrites the request to `mega_getAccountInfo`, treats `pending` as `latest`, and compares rollback-aware cached metadata with the upstream result. It can return cached data when the upstream fails; historical selectors bypass this account cache. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------- | ----------------------------------------------------- | -| `-32602` | Malformed address or block selector | Fix the request | -| `-32001` | Block selector cannot be resolved | Verify the block number or hash | -| `4444` | Requested historical state is not available | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | ------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Malformed address or block selector | +| `-32001` | Method | Resource not found | Block selector cannot be resolved | +| `4444` | Method | Pruned history unavailable | Requested historical state is not available | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}' +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getBalance", + "params": ["0x0000000000000000000000000000000000000000", "pending"] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 1, "result": "0xe7bc7211178" } // 15,924,784,599,416 wei +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x7b0ecf3e28d5" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/state.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/account-query-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026 diff --git a/docs/dev/read/rpc/eth_getBlockByHash.md b/docs/dev/read/rpc/eth_getBlockByHash.md index 1f1097f..e2145c0 100644 --- a/docs/dev/read/rpc/eth_getBlockByHash.md +++ b/docs/dev/read/rpc/eth_getBlockByHash.md @@ -4,8 +4,12 @@ description: "eth_getBlockByHash JSON-RPC reference for MegaETH." # eth_getBlockByHash +## Summary + Returns a block by its hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`blockHash`** Hash32 **REQUIRED** @@ -18,7 +22,7 @@ Target block hash. `false` returns transaction hashes; `true` returns full transaction objects. -## Returns +## Result `Block | null` — `null` when the hash is well-formed but does not match any block. @@ -56,21 +60,53 @@ Target block hash. Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns the canonical block matching the hash, or `null` if the hash is unknown. It honors the `fullTransactions` response-shape flag. + +### MegaETH Public Gateway + +The gateway streams and caches successful block responses for 30 minutes, using a hash-to-number mapping to deduplicate entries. A `null` lookup is not cached. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | -------------------------------------------------------------- | ----------------------------------------------------- | -| `-32602` | Block hash is malformed or `fullTransactions` is not a boolean | Fix the request | -| `4444` | Requested historical block is not available on this endpoint | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | -------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Block hash is malformed or `fullTransactions` is not a boolean | +| `4444` | Method | Pruned history unavailable | Requested historical block is not available on this endpoint | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":74,"method":"eth_getBlockByHash","params":["0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1",false]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 74, + "method": "eth_getBlockByHash", + "params": [ + "0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1", + false + ] +} ``` ```json @@ -87,3 +123,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/block.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/get-block-by-hash-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getBlockByNumber.md b/docs/dev/read/rpc/eth_getBlockByNumber.md index 706b689..648169c 100644 --- a/docs/dev/read/rpc/eth_getBlockByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockByNumber.md @@ -4,8 +4,12 @@ description: "eth_getBlockByNumber JSON-RPC reference for MegaETH." # eth_getBlockByNumber +## Summary + Returns a block by number or tag. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`block`** string **REQUIRED** @@ -18,7 +22,7 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. `false` returns transaction hashes; `true` returns full transaction objects. -## Returns +## Result `Block | null` — `null` when the requested block does not exist or is not yet available. @@ -56,21 +60,50 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node resolves a block number or tag and honors the `fullTransactions` response-shape flag. A missing block is represented by `null`. + +### MegaETH Public Gateway + +The gateway returns `null` immediately for `pending`. Other responses are streamed and cached; head-following tags use short-lived entries while fixed blocks are treated as immutable. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------------------------------------- | ----------------------------------------------------- | -| `-32602` | Malformed block selector or `fullTransactions` is not a boolean | Fix the request | -| `4444` | Requested historical block is not available on this endpoint | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | --------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed block selector or `fullTransactions` is not a boolean | +| `4444` | Method | Pruned history unavailable | Requested historical block is not available on this endpoint | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":81,"method":"eth_getBlockByNumber","params":["0x100000",false]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 81, + "method": "eth_getBlockByNumber", + "params": ["0x100000", false] +} ``` ```json @@ -87,3 +120,35 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +Pending-block edge case: + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: null + +```json +{ + "jsonrpc": "2.0", + "id": 82, + "method": "eth_getBlockByNumber", + "params": ["pending", false] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 82, + "result": null +} +``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/block.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/simple-cache-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24 and July 27, 2026 diff --git a/docs/dev/read/rpc/eth_getBlockReceipts.md b/docs/dev/read/rpc/eth_getBlockReceipts.md index 8b20333..a661be2 100644 --- a/docs/dev/read/rpc/eth_getBlockReceipts.md +++ b/docs/dev/read/rpc/eth_getBlockReceipts.md @@ -4,15 +4,19 @@ description: "eth_getBlockReceipts JSON-RPC reference for MegaETH." # eth_getBlockReceipts +## Summary + Returns all transaction receipts for a block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`block`** string | object **REQUIRED** Block number, tag (`earliest`, `latest`, `safe`, `finalized`, `pending`), block hash, or `{"blockHash":"0x…"}` selector object. -## Returns +## Result `Receipt[] | null` — receipts for every transaction in the block. The method returns `null` when the block is not found. @@ -26,7 +30,7 @@ Each array element contains: - **`status`** Quantity - `0x1` success; `0x0` failure. + A nonzero status indicates success; zero indicates that execution reverted. - **`blockHash`** Hash32 @@ -62,24 +66,57 @@ Each array element contains: Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns all receipts for the selected block. The response can be large because MegaETH blocks can contain many transactions. + +### MegaETH Public Gateway + +The gateway returns `null` immediately for `pending`, streams large responses, and caches successful results for up to 30 minutes. The method is in the IO-heavy read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | -------------------------------------------------- | ----------------------------------------------------- | -| `-32602` | Malformed or unsupported block selector | Fix the request | -| `4444` | Historical block data unavailable on this endpoint | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | ------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed or unsupported block selector | +| `4444` | Method | Pruned history unavailable | Historical block data unavailable on this endpoint | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's IO-heavy read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":16,"method":"eth_getBlockReceipts","params":[{"blockHash":"0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d"}]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 16, + "method": "eth_getBlockReceipts", + "params": [ + { + "blockHash": "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d" + } + ] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 16, @@ -95,18 +132,25 @@ curl -sS https://mainnet.megaeth.com/rpc \ "transactionIndex": "0x0", "blockHash": "0x57804c21b747137075b29ce153b4f559345a3624273660c87e81bd57e7cbbc3d", "blockNumber": "0x1", - "gasUsed": "0xb9d56c", // 12,178,796 - "effectiveGasPrice": "0x0", // 0 — deposit transaction + "gasUsed": "0xb9d56c", + "effectiveGasPrice": "0x0", "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", "to": "0x4200000000000000000000000000000000000015", "contractAddress": null, - "l1GasPrice": "0x22ba611d", // 582,639,901 wei - "l1GasUsed": "0x6e7", // 1,767 + "l1GasPrice": "0x22ba611d", + "l1GasUsed": "0x6e7", "l1Fee": "0x0", - "l1BaseFeeScalar": "0x558", // 1,368 - "l1BlobBaseFee": "0x7", // 7 - "l1BlobBaseFeeScalar": "0xc5fc5", // 810,949 - }, - ], + "l1BaseFeeScalar": "0x558", + "l1BlobBaseFee": "0x7", + "l1BlobBaseFeeScalar": "0xc5fc5" + } + ] } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/block.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/simple-cache-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md index 4bec80d..3b9cc43 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md @@ -4,36 +4,82 @@ description: "eth_getBlockTransactionCountByHash JSON-RPC reference for MegaETH. # eth_getBlockTransactionCountByHash +## Summary + Returns the number of transactions in the block matching the given hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`blockHash`** Hash32 **REQUIRED** Target block hash. -## Returns +## Result **`result`** Quantity | null Transaction count; `null` when the block is not found. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node looks up the block and returns its transaction count. An unknown block produces `null`. + +### MegaETH Public Gateway + +The gateway caches successful hash-based lookups for 30 minutes in the simple read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------- | --------------- | -| `-32602` | Block hash missing or malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Block hash missing or malformed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":3,"method":"eth_getBlockTransactionCountByHash","params":["0xa97b8563203de36f0c8430709734438fbf7f2444b6de9f307853fc46b230de3e"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "eth_getBlockTransactionCountByHash", + "params": [ + "0xa97b8563203de36f0c8430709734438fbf7f2444b6de9f307853fc46b230de3e" + ] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 3, "result": "0x18" } // 24 transactions +```json +{ + "jsonrpc": "2.0", + "id": 3, + "result": "0x18" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/block.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md index d79e853..691d1e9 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md @@ -4,36 +4,80 @@ description: "eth_getBlockTransactionCountByNumber JSON-RPC reference for MegaET # eth_getBlockTransactionCountByNumber +## Summary + Returns the number of transactions in a block identified by block number or tag. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`block`** string **REQUIRED** Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. -## Returns +## Result **`result`** Quantity | null Transaction count; `null` when the block is not found. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node resolves the number or tag and returns the block's transaction count. An unknown block produces `null`. + +### MegaETH Public Gateway + +The gateway caches successful fixed-block lookups for 30 minutes in the simple read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------- | --------------- | -| `-32602` | Block selector is malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Block selector is malformed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":4,"method":"eth_getBlockTransactionCountByNumber","params":["0xb11362"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "eth_getBlockTransactionCountByNumber", + "params": ["0xb11362"] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 4, "result": "0x17" } // 23 transactions (block 11,604,834) +```json +{ + "jsonrpc": "2.0", + "id": 4, + "result": "0x17" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/block.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getCode.md b/docs/dev/read/rpc/eth_getCode.md index c274c48..6b55cca 100644 --- a/docs/dev/read/rpc/eth_getCode.md +++ b/docs/dev/read/rpc/eth_getCode.md @@ -4,8 +4,12 @@ description: "eth_getCode JSON-RPC reference for MegaETH." # eth_getCode +## Summary + Returns the runtime bytecode stored at an address at a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`address`** Address **REQUIRED** @@ -19,30 +23,70 @@ Target account or contract address. Hex block number, block hash, or tag (`latest`, `safe`, `finalized`, …). The default is `"latest"`. -## Returns +## Result **`result`** Data Runtime bytecode (not creation bytecode) at the address; `0x` when no code is deployed. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns runtime bytecode from the selected state. A missing account and an account with no code are both represented by empty bytecode. + +### MegaETH Public Gateway + +The gateway streams bytecode responses and caches successful fixed-state lookups for up to 30 minutes. The exact cache key follows the address and block selector. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ----------------------------------------- | ----------------------------------------------------- | -| `-32602` | Malformed address or block selector | Fix the request | -| `-32001` | Block selector cannot be resolved | Verify the block number or hash | -| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed address or block selector | +| `-32001` | Method | Resource not found | Block selector cannot be resolved | +| `4444` | Method | Pruned history unavailable | Requested historical state is unavailable | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":2,"method":"eth_getCode","params":["0x4200000000000000000000000000000000000011","latest"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "eth_getCode", + "params": ["0x4200000000000000000000000000000000000011", "latest"] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 2, "result": "0x6080604052…" } // bytecode truncated +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": "0x6080604052\u2026" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/state.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getCodeByHash.md b/docs/dev/read/rpc/eth_getCodeByHash.md index f97ef16..d201e85 100644 --- a/docs/dev/read/rpc/eth_getCodeByHash.md +++ b/docs/dev/read/rpc/eth_getCodeByHash.md @@ -4,36 +4,83 @@ description: "eth_getCodeByHash JSON-RPC reference for MegaETH." # eth_getCodeByHash +## Summary + Returns runtime bytecode for a given code hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`codeHash`** Hash32 **REQUIRED** Target runtime code hash. -## Returns +## Result **`result`** Data Runtime bytecode; `0x` when no bytecode is stored for that hash. +## MegaETH Behavior + +### Ethereum Standard + +`eth_getCodeByHash` is not part of the core Ethereum execution JSON-RPC API. It is an implementation-specific extension. + +### MegaETH Node Behavior + +MegaETH adds a direct code-hash lookup that returns the stored runtime bytecode. An unknown code hash produces empty bytecode rather than an account lookup. + +### MegaETH Public Gateway + +The public gateway exposes this MegaETH extension and caches successful immutable lookups for 30 minutes. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------- | --------------- | -| `-32602` | Code hash is missing or malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":43,"method":"eth_getCodeByHash","params":["0xfa8c9db6c6cab7108dea276f4cd09d575674eb0852c0fa3187e59e98ef977998"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 43, + "method": "eth_getCodeByHash", + "params": [ + "0xfa8c9db6c6cab7108dea276f4cd09d575674eb0852c0fa3187e59e98ef977998" + ] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 43, "result": "0x6080604052…" } // bytecode truncated +```json +{ + "jsonrpc": "2.0", + "id": 43, + "result": "0x6080604052\u2026" +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/ext.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getHeaderByHash.md b/docs/dev/read/rpc/eth_getHeaderByHash.md index acaf2f1..9ce3910 100644 --- a/docs/dev/read/rpc/eth_getHeaderByHash.md +++ b/docs/dev/read/rpc/eth_getHeaderByHash.md @@ -4,15 +4,19 @@ description: "eth_getHeaderByHash JSON-RPC reference for MegaETH." # eth_getHeaderByHash +## Summary + Returns a block header by its hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`blockHash`** Hash32 **REQUIRED** Target block hash. -## Returns +## Result `Header | null` — `null` when the hash does not match any known block. @@ -46,23 +50,54 @@ Target block hash. Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. +## MegaETH Behavior + +### Ethereum Standard + +`eth_getHeaderByHash` is not part of the core Ethereum execution JSON-RPC API. It is an implementation-specific extension. + +### MegaETH Node Behavior + +MegaETH exposes a header-only lookup. It returns `null` when the hash is unknown and avoids serializing the block body. + +### MegaETH Public Gateway + +The gateway streams successful responses, caches them for 30 minutes, and records a hash-to-number mapping. A `null` result is deliberately not cached. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ---------------------------------- | --------------- | -| `-32602` | Block hash is missing or malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Block hash is missing or malformed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":26,"method":"eth_getHeaderByHash","params":["0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0"]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 26, + "method": "eth_getHeaderByHash", + "params": [ + "0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0" + ] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 26, @@ -70,9 +105,16 @@ curl -sS https://mainnet.megaeth.com/rpc \ "hash": "0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0", "parentHash": "0x6b6b52368c21dcdba7348fa37edae3e945013627a83a96b64d55217696899d30", "stateRoot": "0xf328fa2752aea1c211a73067d17c25d09a416b4b6a7785441f39bcc930028717", - "number": "0xb10f64", // 11,603,812 - "timestamp": "0x69c33537", // 1,774,400,823 - "baseFeePerGas": "0xf4240", // 1,000,000 wei - }, + "number": "0xb10f64", + "timestamp": "0x69c33537", + "baseFeePerGas": "0xf4240" + } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/ext.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/get-header-by-hash-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getHeaderByNumber.md b/docs/dev/read/rpc/eth_getHeaderByNumber.md index 35abdf4..b230d89 100644 --- a/docs/dev/read/rpc/eth_getHeaderByNumber.md +++ b/docs/dev/read/rpc/eth_getHeaderByNumber.md @@ -4,15 +4,19 @@ description: "eth_getHeaderByNumber JSON-RPC reference for MegaETH." # eth_getHeaderByNumber +## Summary + Returns a header-only view of a block by number or block tag. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`block`** string **REQUIRED** Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. -## Returns +## Result `Header | null` — `null` when the block is not found. @@ -46,23 +50,52 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. +## MegaETH Behavior + +### Ethereum Standard + +`eth_getHeaderByNumber` is not part of the core Ethereum execution JSON-RPC API. It is an implementation-specific extension. + +### MegaETH Node Behavior + +MegaETH exposes a header-only lookup by number or tag. It returns `null` when the block cannot be resolved. + +### MegaETH Public Gateway + +The gateway returns `null` immediately for `pending`; other header responses are streamed and cached, with fixed blocks treated as immutable. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | -------------------------------------------------------------- | --------------- | -| `-32602` | Malformed selector, decimal string, or unsupported object form | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | -------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed selector, decimal string, or unsupported object form | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":27,"method":"eth_getHeaderByNumber","params":["0xb11048"]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 27, + "method": "eth_getHeaderByNumber", + "params": ["0xb11048"] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 27, @@ -70,9 +103,16 @@ curl -sS https://mainnet.megaeth.com/rpc \ "hash": "0x235d80b5e91125a1a1d6da6776c6a9ee087d1818c494f71736b09bed61b1411e", "parentHash": "0x6fc0412abfba89bbfab17b2d8bd36cb1c214c1d53ed213fa8958439d0c4f9c18", "stateRoot": "0x301d7b77a74893451bd76e5d1672aaaa493cd78c06d59e885218d48917a35c03", - "number": "0xb11048", // 11,604,040 - "timestamp": "0x69c3361b", // 1,774,401,051 - "baseFeePerGas": "0xf4240", // 1,000,000 wei - }, + "number": "0xb11048", + "timestamp": "0x69c3361b", + "baseFeePerGas": "0xf4240" + } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/ext.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/simple-cache-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getLogs.md b/docs/dev/read/rpc/eth_getLogs.md index 6c751c8..bfde0ac 100644 --- a/docs/dev/read/rpc/eth_getLogs.md +++ b/docs/dev/read/rpc/eth_getLogs.md @@ -4,8 +4,12 @@ description: "eth_getLogs JSON-RPC reference for MegaETH." # eth_getLogs +## Summary + Returns event logs emitted by smart contracts, filtered by block range, contract address, and/or topics. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`filter`** object **REQUIRED** @@ -35,7 +39,7 @@ Log filter. Positional topic filter where positions are AND and values within a position are OR. Use `null` for wildcards. -## Returns +## Result `Log[]` — array of matching log entries. @@ -75,25 +79,64 @@ Log filter. Block timestamp. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node applies the standard address/topic filter and enforces canonical block-selector encoding. Backend retention can still affect historical ranges. + +### MegaETH Public Gateway + +The gateway places the method in the IO-heavy tier, routes older explicit ranges to its ClickHouse-backed log service when configured, streams the response, and caches only cache-safe filters. There is no gateway block-range cap, but backend row, time, or memory limits can still make very large queries incomplete or fail. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ---------------------------------------------------------------------- | ---------------------------- | -| `-32602` | Filter is malformed or combines `blockHash` with `fromBlock`/`toBlock` | Fix the filter | -| `-32001` | Provided `blockHash` cannot be resolved | Verify the block hash | -| `-32000` | Query range is too large for the endpoint | Narrow the range or paginate | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ---------------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Filter is malformed or combines `blockHash` with `fromBlock`/`toBlock` | +| `-32001` | Method | Resource not found | Provided `blockHash` cannot be resolved | +| `-32000` | Method | Server error | Query range is too large for the endpoint | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's IO-heavy read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":110,"method":"eth_getLogs","params":[{"fromBlock":"0xb120c6","toBlock":"0xb120c6","address":"0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6","topics":["0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815","0x00000000000000000000000000000000000000000000000000000000000000d8"]}]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 110, + "method": "eth_getLogs", + "params": [ + { + "fromBlock": "0xb120c6", + "toBlock": "0xb120c6", + "address": "0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6", + "topics": [ + "0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815", + "0x00000000000000000000000000000000000000000000000000000000000000d8" + ] + } + ] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 110, @@ -102,15 +145,22 @@ curl -sS https://mainnet.megaeth.com/rpc \ "address": "0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6", "topics": [ "0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815", - "0x00000000000000000000000000000000000000000000000000000000000000d8", // 216 + "0x00000000000000000000000000000000000000000000000000000000000000d8" ], "data": "0x0000000000000000000954150000002f000000000000d6d800000000006ec9a2", - "blockNumber": "0xb120c6", // 11,608,262 + "blockNumber": "0xb120c6", "blockTimestamp": "0x69c34699", "transactionHash": "0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6", - "logIndex": "0x24", // 36 - "removed": false, - }, - ], + "logIndex": "0x24", + "removed": false + } + ] } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/filter.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/filter.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/eth-logs-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getStorageAt.md b/docs/dev/read/rpc/eth_getStorageAt.md index d3c9574..2a04703 100644 --- a/docs/dev/read/rpc/eth_getStorageAt.md +++ b/docs/dev/read/rpc/eth_getStorageAt.md @@ -4,8 +4,12 @@ description: "eth_getStorageAt JSON-RPC reference for MegaETH." # eth_getStorageAt +## Summary + Returns the 32-byte value stored at a given contract storage slot at a specified block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`address`** Address **REQUIRED** @@ -25,34 +29,74 @@ Hex storage slot; use a 32-byte zero-padded value for portability. Hex block number, block hash, or tag (`latest`, `safe`, `finalized`, …). The default is `"latest"`. -## Returns +## Result **`result`** Bytes32 Raw 32-byte storage word; a zero value can mean an empty slot, a non-existent account, or an explicitly stored zero. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node reads a 32-byte storage word from the selected state. A zero word does not distinguish absent storage from an explicitly stored zero. + +### MegaETH Public Gateway + +The gateway exposes the method in the instant read tier and does not cache the response. Historical-state retention errors from the selected backend remain visible to callers. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------ | ----------------------------------------------------- | -| `-32602` | Address, slot encoding, or block selector is malformed | Fix the request | -| `-32001` | Block selector cannot be resolved | Verify the block number or hash | -| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | ------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Address, slot encoding, or block selector is malformed | +| `-32001` | Method | Resource not found | Block selector cannot be resolved | +| `4444` | Method | Pruned history unavailable | Requested historical state is unavailable | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":63,"method":"eth_getStorageAt","params":["0x4200000000000000000000000000000000000011","0x0000000000000000000000000000000000000000000000000000000000000000","0xb11048"]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 63, + "method": "eth_getStorageAt", + "params": [ + "0x4200000000000000000000000000000000000011", + "0x0000000000000000000000000000000000000000000000000000000000000000", + "0xb11048" + ] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 63, - "result": "0x000000000000000000000000000000000000000000000001bce8287cf283cc16", -} // raw 32-byte word at slot 0, block 11,604,040 + "result": "0x000000000000000000000000000000000000000000000001bce8287cf283cc16" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/state.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getTransactionByHash.md b/docs/dev/read/rpc/eth_getTransactionByHash.md index c056280..eb406de 100644 --- a/docs/dev/read/rpc/eth_getTransactionByHash.md +++ b/docs/dev/read/rpc/eth_getTransactionByHash.md @@ -4,15 +4,19 @@ description: "eth_getTransactionByHash JSON-RPC reference for MegaETH." # eth_getTransactionByHash +## Summary + Returns a transaction by its hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`transactionHash`** Hash32 **REQUIRED** Target transaction hash. -## Returns +## Result `Transaction | null` — `null` when the transaction cannot be found. @@ -62,20 +66,51 @@ Target transaction hash. Additional fields vary by transaction type (`gasPrice`, `maxFeePerGas`, `accessList`, `chainId`, `v`, `r`, `s`, etc.). +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns a transaction known to canonical storage or the live transaction view; an unknown hash produces `null`. + +### MegaETH Public Gateway + +The gateway caches included transactions for 30 minutes. A `null` result is not cached, so a later request can observe a transaction that has since become available. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ---------------------------------------- | --------------- | -| `-32602` | Transaction hash is missing or malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Transaction hash is missing or malformed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":79,"method":"eth_getTransactionByHash","params":["0x89f0ccba20d5bbbe1cb6b44fb8d1f9a9e14b620a0b947a3de81cff684462f60c"]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 79, + "method": "eth_getTransactionByHash", + "params": [ + "0x89f0ccba20d5bbbe1cb6b44fb8d1f9a9e14b620a0b947a3de81cff684462f60c" + ] +} ``` ```json @@ -96,3 +131,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/transaction.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/get-tx-by-hash-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getTransactionCount.md b/docs/dev/read/rpc/eth_getTransactionCount.md index 0480a4e..cb09a25 100644 --- a/docs/dev/read/rpc/eth_getTransactionCount.md +++ b/docs/dev/read/rpc/eth_getTransactionCount.md @@ -4,8 +4,12 @@ description: "eth_getTransactionCount JSON-RPC reference for MegaETH." # eth_getTransactionCount +## Summary + Returns the number of transactions sent from an address at a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`address`** Address **REQUIRED** @@ -19,31 +23,71 @@ Target account address. Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). The default is `"latest"`. -## Returns +## Result **`result`** Quantity Transaction count at the requested block. -The method returns `0x0` for both unknown accounts and accounts with zero transactions. +The method returns a zero quantity for both unknown accounts and accounts with zero transactions. + +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns the account nonce at the selected state. Unknown accounts and accounts that have not sent transactions both produce a zero quantity. + +### MegaETH Public Gateway + +For `latest` or `pending`, the gateway rewrites to `mega_getAccountInfo`, treats `pending` as `latest`, and can return a fresh cached nonce immediately. Historical selectors bypass the account cache; a nonce read in the same outer batch as submissions need not include those submissions. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. ## Errors -| Code | Cause | Fix | -| -------- | ----------------------------------------- | ----------------------------------------------------- | -| `-32602` | Malformed address or block selector | Fix the request | -| `-32001` | Block selector cannot be resolved | Verify the block number or hash | -| `4444` | Requested historical state is unavailable | Verify historical-state availability for the endpoint | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Malformed address or block selector | +| `-32001` | Method | Resource not found | Block selector cannot be resolved | +| `4444` | Method | Pruned history unavailable | Requested historical state is unavailable | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":91,"method":"eth_getTransactionCount","params":["0xa344fb2d117501ee379d2ea9c0c016959ad94f1e","0xb120c6"]}' +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 91, + "method": "eth_getTransactionCount", + "params": ["0xa344fb2d117501ee379d2ea9c0c016959ad94f1e", "0xb120c6"] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 91, "result": "0xfa8c" } // 64,140 transactions (block 11,608,262) +```json +{ + "jsonrpc": "2.0", + "id": 91, + "result": "0xfa8c" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/state.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/account-query-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getTransactionReceipt.md b/docs/dev/read/rpc/eth_getTransactionReceipt.md index 29f9ebc..68c205c 100644 --- a/docs/dev/read/rpc/eth_getTransactionReceipt.md +++ b/docs/dev/read/rpc/eth_getTransactionReceipt.md @@ -4,15 +4,19 @@ description: "eth_getTransactionReceipt JSON-RPC reference for MegaETH." # eth_getTransactionReceipt +## Summary + Returns a transaction receipt by hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`transactionHash`** Hash32 **REQUIRED** Hash of the target transaction. -## Returns +## Result `Receipt | null` — `null` when the transaction is unknown or not yet mined. @@ -22,7 +26,7 @@ Hash of the target transaction. - **`status`** Quantity - `0x1` success; `0x0` failure. + A nonzero status indicates success; zero indicates that execution reverted. - **`blockHash`** Hash32 @@ -58,20 +62,51 @@ Hash of the target transaction. Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns `null` until a receipt is visible. Receipts produced from a real-time mini-block may temporarily use the all-`ff` block-hash placeholder until the EVM block seals. + +### MegaETH Public Gateway + +The gateway first checks its receipt cache, forwards misses upstream, and caches non-null receipts for 30 minutes. A `null` result is not cached. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ---------------------------------------- | --------------- | -| `-32602` | Transaction hash is missing or malformed | Fix the request | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32602` | Request | Invalid params | Transaction hash is missing or malformed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":120,"method":"eth_getTransactionReceipt","params":["0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6"]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 120, + "method": "eth_getTransactionReceipt", + "params": [ + "0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6" + ] +} ``` ```json @@ -93,3 +128,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ } } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/transaction.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/tx-receipt-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/read/rpc/eth_getWithdrawalProof.md index b48b9b3..40c7af7 100644 --- a/docs/dev/read/rpc/eth_getWithdrawalProof.md +++ b/docs/dev/read/rpc/eth_getWithdrawalProof.md @@ -4,9 +4,13 @@ description: "Returns a withdrawal-storage proof for MegaETH's L2-to-L1 message # eth_getWithdrawalProof +## Summary + Returns the same proof as [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md). The gateway routes both method names to the same node implementation. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters | Position | Name | Type | Required | Description | @@ -15,15 +19,46 @@ The gateway routes both method names to the same node implementation. | `1` | `storageKeys` | `Bytes32[]` | Yes | Withdrawal-message storage keys to prove; an empty array is valid. | | `2` | `block` | block number or tag | Yes | State against which to build the proof. | -## Returns +## Result An EIP-1186-style account proof containing `accountProof`, `balance`, `codeHash`, `nonce`, `storageHash`, and one `storageProof` entry per requested key. +## MegaETH Behavior + +### Ethereum Standard + +`eth_getWithdrawalProof` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH compatibility extension for the withdrawal-proof API. + +### MegaETH Node Behavior + +MegaETH implements this OP Stack withdrawal-proof extension for the L2-to-L1 message passer. It returns an EIP-1186-style account and storage proof. + +### MegaETH Public Gateway + +The public gateway exposes this method and caches successful proofs for 30 minutes. All three positional parameters are required at the gateway. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. + ## Errors -The parameters, errors, and response fields are identical to [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md#errors). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -## Example +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success ```json { @@ -33,3 +68,26 @@ The parameters, errors, and response fields are identical to [`mega_getWithdrawa "params": ["0x4200000000000000000000000000000000000016", [], "latest"] } ``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "address": "0x4200000000000000000000000000000000000016", + "accountProof": [], + "balance": "0x0", + "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + "nonce": "0x0", + "storageHash": "0x891f4462376be7ecac17a67a0ee5be7bc0c35979c182e5f7f19ebb2b1e320cc3", + "storageProof": [] + } +} +``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/ext.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026 diff --git a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md index 5b6d3aa..e2e2af2 100644 --- a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md +++ b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md @@ -4,32 +4,80 @@ description: "eth_maxPriorityFeePerGas JSON-RPC reference for MegaETH." # eth_maxPriorityFeePerGas +## Summary + Returns the recommended priority fee per gas in wei. -MegaETH returns `0x0` because priority fees are not needed under the current fee policy. +MegaETH returns a zero-wei priority fee because priority fees are not needed under the current fee policy. + +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. ## Parameters None. -## Returns +## Result **`result`** Quantity -Always `0x0`. +Always a zero-wei quantity. + +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node fee policy does not require a priority fee, but the public result is synthesized by the gateway rather than used as evidence of a node query. + +### MegaETH Public Gateway + +The gateway synthesizes a zero-wei priority fee without calling a node. This is a current MegaETH fee-policy response, not a market estimate. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"eth_maxPriorityFeePerGas","params":[]}' +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_maxPriorityFeePerGas", + "params": [] +} ``` ```json -{ "jsonrpc": "2.0", "id": 1, "result": "0x0" } +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0" +} ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/fee_market.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc-eth-api/src/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/hardcoded-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026 diff --git a/docs/dev/read/rpc/eth_sendRawTransaction.md b/docs/dev/read/rpc/eth_sendRawTransaction.md index 69471c6..acbab0c 100644 --- a/docs/dev/read/rpc/eth_sendRawTransaction.md +++ b/docs/dev/read/rpc/eth_sendRawTransaction.md @@ -4,37 +4,71 @@ description: "eth_sendRawTransaction JSON-RPC reference for MegaETH." # eth_sendRawTransaction +## Summary + Submits a signed transaction to the network and returns its transaction hash. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`rawTx`** Data **REQUIRED** Signed, RLP-encoded transaction bytes. -Supported envelope types are legacy, EIP-2930 (`0x01`), EIP-1559 (`0x02`), EIP-4844 (`0x03`), and EIP-7702 (`0x04`). +Supported envelope types are legacy, EIP-2930, EIP-1559, EIP-4844, and EIP-7702. -## Returns +## Result **`result`** Data 32-byte transaction hash. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node decodes and validates the signed transaction before admitting it to the transaction pool. Successful submission returns the transaction hash, not an inclusion receipt. + +### MegaETH Public Gateway + +The gateway validates chain ID, signature, intrinsic gas, fee floor, nonce, balance, and policy checks before forwarding. The method is exempt from read-rate limits and accepts request bodies up to 2.5 MiB. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | -| `-32602` | Parameter missing, hex malformed, or bytes cannot be decoded as a signed transaction | Fix the transaction | -| `-32000` | Pool or gateway rule violation | Fix the field identified in `error.message` | -| `-32003` | Insufficient sender funds, pool at capacity, or unsupported transaction type | Fund the sender or wait for pool capacity | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | -------------------- | ------------------------------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Parameter missing, hex malformed, or bytes cannot be decoded as a signed transaction | +| `-32000` | Method | Server error | Pool or gateway rule violation | +| `-32003` | Method | Transaction rejected | Insufficient sender funds, pool at capacity, or unsupported transaction type | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"eth_sendRawTransaction","params":["0xf86c808405763d658261a894aa000000000000000000000000000000000000000a8255448718e5bb3abd109fa0c8e3b4a0087357bd49d80a0ac24daf0c91191e71086c1e355fc62cfab2218873a074f4636f740fa4d1697b6e736e5982b700be2c8b63031a24fa531ae4814b3af8"]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_sendRawTransaction", + "params": [ + "0xf86c808405763d658261a894aa000000000000000000000000000000000000000a8255448718e5bb3abd109fa0c8e3b4a0087357bd49d80a0ac24daf0c91191e71086c1e355fc62cfab2218873a074f4636f740fa4d1697b6e736e5982b700be2c8b63031a24fa531ae4814b3af8" + ] +} ``` ```json @@ -44,3 +78,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ "result": "0x66734e85ef096167acb887cf445946a1ed57b90b66ffe38af87e11294febbfa9" } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/submit.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/api.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/sequencer-guard/single-tx.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/read/rpc/eth_sendRawTransactionSync.md index d55fd50..6a52cd6 100644 --- a/docs/dev/read/rpc/eth_sendRawTransactionSync.md +++ b/docs/dev/read/rpc/eth_sendRawTransactionSync.md @@ -4,9 +4,13 @@ description: "eth_sendRawTransactionSync JSON-RPC reference for MegaETH." # eth_sendRawTransactionSync +## Summary + Submits a signed transaction and returns a receipt once the transaction is included in a block. The public gateway routes this method and [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) through the same synchronous submission handler, with the same parameters and receipt result. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`data`** Data **REQUIRED** @@ -20,7 +24,7 @@ Signed raw transaction bytes. Client wait budget in milliseconds. When omitted, the node uses its 5-second default; the public gateway caps explicit values at `3000` (3 s). -## Returns +## Result - **`transactionHash`** Hash32 @@ -28,7 +32,7 @@ When omitted, the node uses its 5-second default; the public gateway caps explic - **`status`** Quantity - `0x1` success; `0x0` failure (the transaction reverted but was included on-chain). + A nonzero status indicates success; zero means the transaction reverted but was included on-chain. - **`blockHash`** Hash32 @@ -66,32 +70,55 @@ When omitted, the node uses its 5-second default; the public gateway caps explic Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). +## MegaETH Behavior + +### Ethereum Standard + +`eth_sendRawTransactionSync` is not part of the core Ethereum execution JSON-RPC API. It is a compatibility extension exposed by the MegaETH public gateway. + +### MegaETH Node Behavior + +The current MegaETH node does not register this `eth_*` alias. Its native synchronous submission method is `realtime_sendRawTransaction`; the node waits up to 5 seconds by default for a real-time receipt. + +### MegaETH Public Gateway + +The gateway exposes this compatibility name and routes it and `realtime_sendRawTransaction` through the same handler. Both are rewritten to the node's `realtime_sendRawTransactionWithSender` method after gateway-side validation. The gateway caps explicit waits at 3,000 milliseconds and accepts request bodies up to 2.5 MiB. An expiry is inconclusive: the transaction may still land. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | -| `-32602` | Raw transaction is malformed, undecodable, or `timeoutMs` is invalid | Fix the request | -| `-32000` | Receipt not available before the wait window expired, or the node rejected the transaction | Treat as inconclusive — the transaction may still land; inspect the error message | - -See also [Error reference](error-codes.md). - -## Example - -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{ - "jsonrpc": "2.0", - "id": 91, - "method": "eth_sendRawTransactionSync", - "params": [ - "0xf86480830f424082ea6094cc4b43ab7230cc5913801a746c1834aa06c4e7e780808231b2a0b8126d2c41a6c7dbd0a9e219233497057bb391e7ee1d628370f9c1456f82b054a06663fde9daa2fae784c3dac1c9a5a973d538e3a12ec9c0e4d3cee9c70ba2b239", - 3000 - ] - }' +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------ | +| `-32602` | Request | Invalid params | Raw transaction is malformed, undecodable, or `timeoutMs` is invalid | +| `-32000` | Method | Server error | Receipt not available before the wait window expired, or the node rejected the transaction | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 91, + "method": "eth_sendRawTransactionSync", + "params": [ + "0xf86480830f424082ea6094cc4b43ab7230cc5913801a746c1834aa06c4e7e780808231b2a0b8126d2c41a6c7dbd0a9e219233497057bb391e7ee1d628370f9c1456f82b054a06663fde9daa2fae784c3dac1c9a5a973d538e3a12ec9c0e4d3cee9c70ba2b239", + 3000 + ] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 91, @@ -101,11 +128,11 @@ curl -sS https://mainnet.megaeth.com/rpc \ "transactionHash": "0x8d3b1e22e7a9026c8658b5d922293d59e4de7c3382bb832d6890e6ab23ad7ec7", "transactionIndex": "0x5", "blockHash": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", - "blockNumber": "0xe7133c", // 15,143,740 + "blockNumber": "0xe7133c", "from": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", "to": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", - "gasUsed": "0xea60", // 60,000 - "effectiveGasPrice": "0xf4240", // 1,000,000 wei + "gasUsed": "0xea60", + "effectiveGasPrice": "0xf4240", "cumulativeGasUsed": "0x143043", "contractAddress": null, "logs": [], @@ -114,7 +141,14 @@ curl -sS https://mainnet.megaeth.com/rpc \ "l1Fee": "0x6da0", "l1BaseFeeScalar": "0x558", "l1BlobBaseFee": "0x1", - "l1BlobBaseFeeScalar": "0x0", - }, + "l1BlobBaseFeeScalar": "0x0" + } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/realtime.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/sequencer-guard/single-tx.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_subscribe.md b/docs/dev/read/rpc/eth_subscribe.md index 3574602..4f7deb9 100644 --- a/docs/dev/read/rpc/eth_subscribe.md +++ b/docs/dev/read/rpc/eth_subscribe.md @@ -4,143 +4,97 @@ description: eth_subscribe — WebSocket subscriptions for real-time logs, state # eth_subscribe -Creates a WebSocket subscription that streams data as mini-blocks are produced. -This is the lowest-latency way to receive transaction results — logs, state changes, and block contents arrive within ~10ms of execution. +## Summary -Call `eth_unsubscribe` with the subscription ID when a subscription is no longer needed. +Creates a WebSocket subscription and returns a subscription ID. +MegaETH supports standard log and head subscriptions plus `stateChanges` and `miniBlocks` for real-time mini-block data. -{% hint style="info" %} -WebSocket connections require periodic client activity to remain open. -Send `eth_chainId` at least once every 30 seconds to keep the connection alive. -Idle connections may be closed by the server. -{% endhint %} +The public method is WebSocket-only. Use [`eth_unsubscribe`](./eth_unsubscribe.md) on the same connection when the subscription is no longer needed. -## Subscription Types +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | -------------- | --------------- | -------- | ------------------------------------------------------------------ | +| `0` | `subscription` | string | Yes | One of `logs`, `stateChanges`, `miniBlocks`, or `newHeads`. | +| `1` | `options` | object or array | Depends | Filter options for `logs`, or an address array for `stateChanges`. | ### `logs` -Streams event logs as transactions are packaged into mini-blocks. -Set both `fromBlock` and `toBlock` to `"pending"` for real-time delivery. +The optional filter object accepts: -**Parameters:** +| Field | Type | Required | Description | +| ----------- | -------------------- | -------- | --------------------------------------------------------------------- | +| `fromBlock` | block tag | No | Set to `pending` with `toBlock` for real-time mini-block logs. | +| `toBlock` | block tag | No | Set to `pending` with `fromBlock` for real-time mini-block logs. | +| `address` | address or address[] | No | Emitting contract address or addresses. | +| `topics` | array | No | Position-sensitive topic filter; nested arrays express OR conditions. | -| Field | Type | Required | Notes | -| ----------- | ------------------ | -------- | ------------------------------------- | -| `fromBlock` | `BlockTag` | No | Set to `"pending"` for real-time logs | -| `toBlock` | `BlockTag` | No | Set to `"pending"` for real-time logs | -| `address` | `Data` \| `Data[]` | No | Contract address(es) to filter | -| `topics` | `Data[]` | No | Position-sensitive topic filter | +### `stateChanges` -**Example:** +The second parameter is a required array of account addresses to monitor. -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": [ - "logs", - { - "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", - "topics": [ - "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902" - ], - "fromBlock": "pending", - "toBlock": "pending" - } - ] -} -``` +### `miniBlocks` -Each notification uses the same schema as `eth_getLogs`. +No second parameter is required. -### `stateChanges` +### `newHeads` -Streams account state changes as transactions are packaged into mini-blocks. -Takes a list of account addresses to monitor. +No second parameter is required. -**Parameters:** +## Result -| Position | Type | Required | Notes | -| -------- | -------- | -------- | ------------------------------------ | -| `0` | `Data[]` | Yes | List of account addresses to monitor | +The initial response contains a connection-scoped subscription ID as `DATA`. +Subsequent notifications use `eth_subscription` and include that ID plus a `result` payload. -**Example:** +Payloads depend on the subscription type: -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["stateChanges", ["0x2ef038991d64c72646d4f06ba78d93f4f1654e3f"]] -} -``` +- `logs` uses the same log object schema as [`eth_getLogs`](./eth_getLogs.md). +- `stateChanges` returns an account address, numeric nonce, balance quantity, and changed storage slots. +- `miniBlocks` returns the EVM block number and timestamp, mini-block index and global height, microsecond timestamp, gas used, transactions, receipts, roots, and the sequencer signature when available. +- `newHeads` returns a block header and includes MegaETH's additional `miniBlockCount` field. -**Notification schema:** +Notifications are not replayed automatically after a connection closes. Reconnect and create a new subscription when continuity is required. -| Field | Type | Notes | -| --------- | ----------------- | ------------------------------------ | -| `address` | `Data` (20 bytes) | Account address | -| `nonce` | `Number` | Latest nonce | -| `balance` | `Quantity` | Latest balance | -| `storage` | `Object` | Changed storage slots (slot → value) | +## MegaETH Behavior -**Example notification:** +### Ethereum Standard -```json -{ - "address": "0x2ef038991d64c72646d4f06ba78d93f4f1654e3f", - "nonce": 1, - "balance": "0x16345785d8a0000", - "storage": { - "0xb6318d15e99499c465cc5e3d630975bf37b5641a8beb2614b018219310f4ea12": "0x68836e425f5", - "0xbf0f571b7368c19b53ab5ef0ff767ed8e0aef55a462778a6119b7871b017ce8f": "0x71094412456b0" - } -} -``` +Ethereum WebSocket providers commonly implement `eth_subscribe` for `logs` and `newHeads`, although subscriptions are transport extensions rather than HTTP execution-API methods. +Subscription IDs and delivery are scoped to the WebSocket connection. -### `miniBlocks` +### MegaETH Node Behavior -Streams mini-blocks as they are produced by the sequencer. +MegaETH adds `stateChanges` and `miniBlocks`. +These expose state and receipt data as mini-blocks are produced, while `newHeads` follows sealed EVM blocks and adds `miniBlockCount`. +For real-time log delivery, both log-range tags should be `pending`. -**Parameters:** None. +### MegaETH Public Gateway -**Example:** +The public gateway accepts this method only over `wss://mainnet.megaeth.com/ws`. +It supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`, tracks ownership per connection, and requires periodic client activity; sending a lightweight request such as `eth_chainId` at least every 30 seconds prevents idle closure. -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["miniBlocks"] -} -``` +This behavior and a successful `newHeads` subscription were observed on July 24, 2026. +Connection policy and operational timeouts may change. -**Notification schema:** - -| Field | Type | Notes | -| ---------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `block_number` | `Quantity` | EVM block number that this mini-block belongs to | -| `block_timestamp` | `Quantity` | EVM block timestamp | -| `index` | `Quantity` | Index of this mini-block within the EVM block | -| `mini_block_number` | `Quantity` | Global mini-block height | -| `mini_block_timestamp` | `Quantity` | Creation timestamp (Unix microseconds) | -| `gas_used` | `Quantity` | Gas consumed in this mini-block | -| `transactions` | `Transaction[]` | Transactions (same schema as `eth_getTransactionByHash`) | -| `receipts` | `Receipt[]` | Receipts (same schema as `eth_getTransactionReceipt`) | -| `transaction_root` | `Hash` | Merkle (MPT) root of `transactions` | -| `receipt_root` | `Hash` | Merkle (MPT) root of `receipts` | -| `signature` | `Object` | Sequencer's ECDSA signature over the header hash, as `r`, `s`, and `yParity` fields. Absent for pre-Rex5 mini-blocks. See [Sequencer signatures](../../../mini-block.md#sequencer-signatures) | +## Errors -### `newHeads` +The `| Scope |` column distinguishes method failures from gateway policy errors. -Streams EVM block headers as they are sealed. -Standard Ethereum subscription — works the same as on other EVM chains. -On MegaETH, headers include an additional `miniBlockCount` field. +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------------------- | --------------------------------------------------------------------- | +| `-32602` | Method | Invalid params | The subscription type or its filter/options are malformed. | +| `-32000` | Transport/policy | WebSocket connection required | The method is sent over HTTP instead of a WebSocket connection. | +| `-32601` | Transport/policy | Method not found | The requested subscription type is not enabled by the public gateway. | -**Parameters:** None. +See also [Error Codes](./error-codes.md). -**Example:** +## Examples + +Endpoint: `wss://mainnet.megaeth.com/ws` (WebSocket) + +Capture date: July 24, 2026 + +Outcome: success ```json { @@ -151,11 +105,17 @@ On MegaETH, headers include an additional `miniBlockCount` field. } ``` -## Errors +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xaec58cfc2dc41f873fc37d6c871230c1" +} +``` -| Code | Cause | Fix | -| -------- | ------------------------------------------------- | ---------------------------------- | -| `-32602` | Invalid subscription type or malformed parameters | Fix the request | -| `-32000` | WebSocket connection required | Use a WebSocket endpoint, not HTTP | +## Sources -See also [Error reference](error-codes.md). +- Spec: EIP-1474 for JSON-RPC framing; subscriptions are a WebSocket transport extension. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/pubsub.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/rpc-gateway/websocket-session.ts` +- Probe: MegaETH Mainnet public WebSocket endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_syncing.md b/docs/dev/read/rpc/eth_syncing.md index 18b88b5..80729c2 100644 --- a/docs/dev/read/rpc/eth_syncing.md +++ b/docs/dev/read/rpc/eth_syncing.md @@ -4,13 +4,17 @@ description: "eth_syncing JSON-RPC reference for MegaETH." # eth_syncing +## Summary + Returns whether the node is currently syncing. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result `false` when the node is fully synced. When syncing, a `SyncProgress` object: @@ -26,37 +30,63 @@ None. Target block. +## MegaETH Behavior + +### Ethereum Standard + +The canonical Ethereum method uses the parameter and result contract documented above, including the stated `null`, `false`, or zero-value semantics where applicable. + +### MegaETH Node Behavior + +The node returns `false` when caught up and a progress object while synchronizing. This reports node synchronization, not L1 finality. + +### MegaETH Public Gateway + +The gateway forwards this dynamic status without response caching in the simple read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"eth_syncing","params":[]}' -``` +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success ```json { "jsonrpc": "2.0", "id": 1, - "result": false + "method": "eth_syncing", + "params": [] } ``` -When syncing: - ```json { "jsonrpc": "2.0", "id": 1, - "result": { - "startingBlock": "0x0", - "currentBlock": "0xaeb3d0", - "highestBlock": "0xaeb3d6" - } + "result": false } ``` + +## Sources + +- Spec: `git@github.com:ethereum/execution-apis.git @ d24f58b56dcd16ab0f0c70ec609bcc1c42750b51: src/eth/client.yaml` +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc/src/eth/core.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/eth_unsubscribe.md b/docs/dev/read/rpc/eth_unsubscribe.md index fc370a2..8593f01 100644 --- a/docs/dev/read/rpc/eth_unsubscribe.md +++ b/docs/dev/read/rpc/eth_unsubscribe.md @@ -4,36 +4,79 @@ description: "eth_unsubscribe JSON-RPC reference for MegaETH." # eth_unsubscribe +## Summary + Cancels an existing subscription so that no further events are sent. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`subscriptionId`** Data **REQUIRED** Subscription ID returned by `eth_subscribe`. -## Returns +## Result **`result`** boolean `true` if the subscription was found and cancelled; `false` if the ID was not active. +## MegaETH Behavior + +### Ethereum Standard + +`eth_unsubscribe` is part of the commonly implemented Ethereum WebSocket subscription API, but it is not specified by the core execution JSON-RPC API. + +### MegaETH Node Behavior + +The node cancels a subscription in the WebSocket session that created it. Subscription IDs are connection-scoped. + +### MegaETH Public Gateway + +The public method is WebSocket-only. The gateway keeps subscription ownership per connection and rejects attempts to cancel a subscription from another session. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | -------------------------------------------------- | -------------------------------------------------------- | -| `-32602` | Subscription ID parameter is missing | Provide the subscription ID returned by `eth_subscribe` | -| `-32600` | Subscription was created by a different connection | Cancel from the connection that created the subscription | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ------- | --------------- | -------------------------------------------------- | +| `-32602` | Request | Invalid params | Subscription ID parameter is missing | +| `-32600` | Request | Invalid request | Subscription was created by a different connection | + +See also [Error Codes](./error-codes.md). + +## Examples -See also [Error reference](error-codes.md). +Endpoint: `wss://mainnet.megaeth.com/ws` (WebSocket) -## Example +Capture date: July 24, 2026 -```bash -wscat -c wss://mainnet.megaeth.com/ws -> {"jsonrpc":"2.0","id":1,"method":"eth_unsubscribe","params":["0xaec58cfc2dc41f873fc37d6c871230c1"]} +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_unsubscribe", + "params": ["0xaec58cfc2dc41f873fc37d6c871230c1"] +} ``` ```json -{ "jsonrpc": "2.0", "id": 1, "result": true } +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/api.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/rpc-gateway/websocket-session.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/mega_getBlockWitness.md b/docs/dev/read/rpc/mega_getBlockWitness.md index 8ce9b2a..d55af68 100644 --- a/docs/dev/read/rpc/mega_getBlockWitness.md +++ b/docs/dev/read/rpc/mega_getBlockWitness.md @@ -4,8 +4,12 @@ description: "mega_getBlockWitness JSON-RPC reference for MegaETH." # mega_getBlockWitness +## Summary + Returns the execution witness for a block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`keys`** object **REQUIRED** @@ -21,36 +25,89 @@ Block lookup key. Block hash for the same block number. Always include it when available so the lookup is pinned to a specific fork. +- **`parentHash`** Hash32 + + Parent block hash for an OP payload lookup. + Must be supplied together with `attributesHash` and cannot be combined with `blockHash`. + +- **`attributesHash`** Hash32 + + Payload-attributes hash for an OP payload lookup. + Must be supplied together with `parentHash` and cannot be combined with `blockHash`. + {% hint style="warning" %} A `blockNumber`-only lookup returns the first stored witness at that height and is not reorg-safe. -Use `blockNumber` together with `blockHash` for production verification. +Use `blockNumber` together with `blockHash`, or the paired `parentHash` and `attributesHash`, for production verification. {% endhint %} -## Returns +## Result **`result`** string `v0:` followed by a base64-encoded zstd-compressed witness blob. +## MegaETH Behavior + +### Ethereum Standard + +`mega_getBlockWitness` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH extension. + +### MegaETH Node Behavior + +MegaETH returns a `v0:`-prefixed, base64-encoded zstd witness. Requests can select by block hash, or by the paired parent and payload-attributes hashes. + +### MegaETH Public Gateway + +The gateway does not cache witness responses. In an outer batch, if any witness request uses a block number below 7,385,897, at most four `mega_getBlockWitness` requests are allowed. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| `-32602` | `blockNumber` missing, invalid hex value, or invalid hash field combination | Fix the request | -| `-32603` | No witness exists for the requested keys, or the witness service failed | Inspect the message; `Witness not found` is an expected availability miss | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | --------------------------------------------------------------------------- | +| `-32602` | Request | Invalid params | `blockNumber` missing, invalid hex value, or invalid hash field combination | +| `-32603` | Method | Internal error | No witness exists for the requested keys, or the witness service failed | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error reference](error-codes.md). +See also [Error Codes](./error-codes.md). -## Example +## Examples -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"mega_getBlockWitness","params":[{"blockNumber":"0x7fd","blockHash":"0x262206173864c1e597ab9fcf2f718f95f942907207f4fed97dda66d272c5d4a6"}]}' +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "mega_getBlockWitness", + "params": [ + { + "blockNumber": "0x7fd", + "blockHash": "0x262206173864c1e597ab9fcf2f718f95f942907207f4fed97dda66d272c5d4a6" + } + ] +} ``` -```jsonc -{ "jsonrpc": "2.0", "id": 1, "result": "v0:KLUv/QBgzVUAZJwh…" } // base64-encoded zstd blob, truncated +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "v0:KLUv/QBgzVUAZJwh\u2026" +} ``` -For decoding details and network coverage, see [Get block witness](../../../node/witness.md). +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/witness.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/services/batch/batch-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/mega_getWithdrawalProof.md b/docs/dev/read/rpc/mega_getWithdrawalProof.md index 8fe776d..f8e2571 100644 --- a/docs/dev/read/rpc/mega_getWithdrawalProof.md +++ b/docs/dev/read/rpc/mega_getWithdrawalProof.md @@ -4,8 +4,12 @@ description: "mega_getWithdrawalProof JSON-RPC reference for MegaETH." # mega_getWithdrawalProof +## Summary + Returns a Merkle proof for the L2ToL1MessagePasser contract at a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`address`** Address **REQUIRED** @@ -26,7 +30,7 @@ Storage keys to prove; empty array is valid. Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). The node defaults an omitted value to `latest`, but the public endpoint requires all three positional parameters. -## Returns +## Result - **`address`** Address @@ -56,24 +60,53 @@ The node defaults an omitted value to `latest`, but the public endpoint requires Per-key storage proofs; each entry has `key` (`Bytes32`), `value` (`Bytes32`), `proof` (`Data[]`). +## MegaETH Behavior + +### Ethereum Standard + +`mega_getWithdrawalProof` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH extension for OP Stack withdrawal proofs. + +### MegaETH Node Behavior + +The current MegaETH node registers the withdrawal-proof implementation as `eth_getWithdrawalProof`; it does not register this `mega_*` alias. + +### MegaETH Public Gateway + +The gateway rewrites this alias to `eth_getWithdrawalProof` and caches successful proofs for 30 minutes. Callers receive the same result shape under either name. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ----------------------------------------------------------------------------------- | -------------------------- | -| `-32602` | A storage key is not a valid 32-byte hex string, or required parameters are missing | Fix the request | -| `-32000` | The requested block cannot be resolved | Verify the block reference | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------------------------------- | +| `-32602` | Request | Invalid params | A storage key is not a valid 32-byte hex string, or required parameters are missing | +| `-32000` | Method | Server error | The requested block cannot be resolved | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"mega_getWithdrawalProof","params":["0x4200000000000000000000000000000000000016",[],"latest"]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "mega_getWithdrawalProof", + "params": ["0x4200000000000000000000000000000000000016", [], "latest"] +} ``` -```jsonc +```json { "jsonrpc": "2.0", "id": 1, @@ -84,7 +117,14 @@ curl -sS https://mainnet.megaeth.com/rpc \ "nonce": "0x0", "storageHash": "0xddd6dcaf75eeb81fb4701c2a39b3132bd60bf9602e2fcbe5852f5d07e14c8084", "accountProof": [], - "storageProof": [], - }, + "storageProof": [] + } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/eth/ext.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/read/rpc/mega_outputAtBlock.md index 1ec4191..8ff159a 100644 --- a/docs/dev/read/rpc/mega_outputAtBlock.md +++ b/docs/dev/read/rpc/mega_outputAtBlock.md @@ -4,19 +4,23 @@ description: "mega_outputAtBlock JSON-RPC reference for MegaETH." # mega_outputAtBlock +## Summary + Returns the output root at a given block. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters **`blockNumber`** Quantity **REQUIRED** Concrete hex block number; block tags such as `latest` are not accepted. -## Returns +## Result -- **`version`** Hash32 +- **`version`** Hash32, optional - Output version. + Output version. Fresh upstream responses can include it, while the gateway's cached projection currently omits it. - **`outputRoot`** Hash32 @@ -62,63 +66,86 @@ Concrete hex block number; block tags such as `latest` are not accepted. Backend sync-status snapshot. +## MegaETH Behavior + +### Ethereum Standard + +`mega_outputAtBlock` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH extension. + +### MegaETH Node Behavior + +The current MegaETH execution node's related native method is `mega_optimismOutputAtBlock`, which forwards a concrete block number to the OP node's `optimism_outputAtBlock` endpoint. The public `mega_outputAtBlock` spelling is a gateway-facing compatibility name. + +### MegaETH Public Gateway + +The gateway rewrites this method to `optimism_outputAtBlock` and routes it to the OP-node pool. It caches stable output data for 30 minutes but refreshes the embedded synchronization status on a 1-second cadence. +Its cached projection omits the upstream `version` field, so callers must tolerate `version` being present on a fresh response and absent on a cache hit. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -| `-32602` | Missing block number, wrong parameter count, or block tag instead of hex block number | Fix the request parameters | -| `-32603` | Backend cannot produce output data for the requested block | Retry transient failures; inspect the error message for details | +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------------------------------- | +| `-32602` | Request | Invalid params | Missing block number, wrong parameter count, or block tag instead of hex block number | +| `-32603` | Method | Internal error | Backend cannot produce output data for the requested block | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -See also [Error reference](error-codes.md). +## Examples -## Example +Endpoint: `https://mainnet.megaeth.com/rpc` -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":301,"method":"mega_outputAtBlock","params":["0x100"]}' +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "mega_outputAtBlock", + "params": ["0x154de48"] +} ``` -The response below is illustrative; hashes and sync-status values are synthetic. +The captured response below is abridged; `syncStatus` contains additional L1 and L2 progress fields. ```json { "jsonrpc": "2.0", - "id": 301, + "id": 1, "result": { - "version": "0x0000000000000000000000000000000000000000000000000000000000000000", - "outputRoot": "0x0000000000000000000000000000000000000000000000000000000000000001", + "outputRoot": "0xf90851c88ec4adfe04b03f33beab99bbabbd73fc474ab7b3a8fa109a3913f047", "blockRef": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000002", - "number": 256, - "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000003", - "timestamp": 1762797267, + "hash": "0xce5344be15fecbe70574c97e57626f79a0816e8ebfc37a53ad535e82dd2def56", + "number": 22339144, + "parentHash": "0x85f2e75f7be8967a319af7de35275ad257150f80ae243b97f07b45332d3476a1", + "timestamp": 1785136155, "l1origin": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000004", - "number": 21000000 + "hash": "0xf79fbbd55e49baaff2f61e027b424b1b5b1ef7cd58bd7d664eb39947352b2f73", + "number": 25622475 }, - "sequenceNumber": 0 + "sequenceNumber": 137 }, "syncStatus": { - "current_l1": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000011", - "number": 24732192 - }, - "unsafe_l2": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000012", - "number": 11615881 - }, - "safe_l2": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000013", - "number": 11615881 - }, - "finalized_l2": { - "hash": "0x0000000000000000000000000000000000000000000000000000000000000014", - "number": 11615800 + "head_l1": { + "number": 25622556 } }, - "withdrawalStorageRoot": "0x0000000000000000000000000000000000000000000000000000000000000005", - "stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000006" + "withdrawalStorageRoot": "0x891f4462376be7ecac17a67a0ee5be7bc0c35979c182e5f7f19ebb2b1e320cc3", + "stateRoot": "0x686f5150a2aec8f1b5ae15108288530860fa4157a9f39c71e55b0fa24783d506" } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/mega.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/op-output-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026; response abridged to stable top-level fields diff --git a/docs/dev/read/rpc/net_listening.md b/docs/dev/read/rpc/net_listening.md index 8f295f9..1dd005c 100644 --- a/docs/dev/read/rpc/net_listening.md +++ b/docs/dev/read/rpc/net_listening.md @@ -4,31 +4,79 @@ description: "net_listening JSON-RPC reference for MegaETH." # net_listening +## Summary + Returns whether the node is listening for connections. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** boolean Always `true`. +## MegaETH Behavior + +### Ethereum Standard + +`net_listening` is a legacy Ethereum client/network compatibility method rather than a current execution-API method. Implementations commonly expose it with the result shape above. + +### MegaETH Node Behavior + +The inherited network method reports whether the node's peer-to-peer service is listening. + +### MegaETH Public Gateway + +The gateway forwards this dynamic value without response caching in the simple read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"net_listening","params":[]}' +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "net_listening", + "params": [] +} ``` ```json -{ "jsonrpc": "2.0", "id": 1, "result": true } +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc/src/net.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/net_peerCount.md b/docs/dev/read/rpc/net_peerCount.md index 15b9824..85c11b5 100644 --- a/docs/dev/read/rpc/net_peerCount.md +++ b/docs/dev/read/rpc/net_peerCount.md @@ -4,31 +4,79 @@ description: "net_peerCount JSON-RPC reference for MegaETH." # net_peerCount +## Summary + Returns the number of peers currently connected to the node. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** Quantity Number of connected peers. +## MegaETH Behavior + +### Ethereum Standard + +`net_peerCount` is a legacy Ethereum client/network compatibility method rather than a current execution-API method. Implementations commonly expose it with the result shape above. + +### MegaETH Node Behavior + +The inherited network method reports the node's current peer count; the value is inherently transient. + +### MegaETH Public Gateway + +The gateway forwards this dynamic value without response caching in the simple read tier. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"net_peerCount","params":[]}' +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "net_peerCount", + "params": [] +} ``` ```json -{ "jsonrpc": "2.0", "id": 1, "result": "0x4" } +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x4" +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc/src/net.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/net_version.md b/docs/dev/read/rpc/net_version.md index 03e320f..9456ca8 100644 --- a/docs/dev/read/rpc/net_version.md +++ b/docs/dev/read/rpc/net_version.md @@ -4,31 +4,79 @@ description: "net_version JSON-RPC reference for MegaETH." # net_version +## Summary + Returns the current network ID. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** string Network ID as a decimal integer string. +## MegaETH Behavior + +### Ethereum Standard + +`net_version` is a legacy Ethereum client/network compatibility method rather than a current execution-API method. Implementations commonly expose it with the result shape above. + +### MegaETH Node Behavior + +The node reports its configured network identifier as a decimal string. On MegaETH this normally matches the chain ID, but callers should use `eth_chainId` for transaction signing. + +### MegaETH Public Gateway + +The gateway exposes the method in the instant read tier and caches the immutable network ID for 30 minutes. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. -## Example +No method-specific errors were observed. -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"net_version","params":[]}' +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "net_version", + "params": [] +} ``` ```json -{ "jsonrpc": "2.0", "id": 1, "result": "4326" } +{ + "jsonrpc": "2.0", + "id": 1, + "result": "4326" +} ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc/src/net.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/optimism_outputAtBlock.md b/docs/dev/read/rpc/optimism_outputAtBlock.md index 23f48ee..bdf79f4 100644 --- a/docs/dev/read/rpc/optimism_outputAtBlock.md +++ b/docs/dev/read/rpc/optimism_outputAtBlock.md @@ -4,31 +4,99 @@ description: "Returns the OP Stack output-root data for a MegaETH block." # optimism_outputAtBlock +## Summary + Returns the same output-root data as [`mega_outputAtBlock`](./mega_outputAtBlock.md). The two names are aliases on MegaETH. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters | Position | Name | Type | Required | Description | | -------- | ------------- | ---------- | -------- | --------------------------------------------------------------- | | `0` | `blockNumber` | `QUANTITY` | Yes | Concrete hexadecimal block number; block tags are not accepted. | -## Returns +## Result + +An output object containing `outputRoot`, `blockRef`, `withdrawalStorageRoot`, `stateRoot`, and `syncStatus`. +The upstream `version` field can be present on a fresh response but is omitted by the gateway's cached projection. +See [`mega_outputAtBlock`](./mega_outputAtBlock.md#result) for every field. + +## MegaETH Behavior + +### Ethereum Standard + +`optimism_outputAtBlock` is not part of the core Ethereum execution JSON-RPC API. It is an OP Stack extension. + +### MegaETH Node Behavior -An output object containing `version`, `outputRoot`, `blockRef`, `withdrawalStorageRoot`, `stateRoot`, and `syncStatus`. -See [`mega_outputAtBlock`](./mega_outputAtBlock.md#returns) for every field. +This is the OP node's native output-root method. The related MegaETH execution-node method is `mega_optimismOutputAtBlock`, which forwards to it. + +### MegaETH Public Gateway + +The gateway accepts this name and `mega_outputAtBlock`, routes both to the OP-node pool as `optimism_outputAtBlock`, and applies the same split cache policy for output data and synchronization status. +Because the cached projection omits `version`, callers must not require that field even though it can appear on a fresh response. + +This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. ## Errors -The validation and backend errors are identical to [`mega_outputAtBlock`](./mega_outputAtBlock.md#errors). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ----------------------------------------------------------- | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | + +See also [Error Codes](./error-codes.md). -## Example +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success ```json { "jsonrpc": "2.0", "id": 1, "method": "optimism_outputAtBlock", - "params": ["0x100"] + "params": ["0x154de48"] } ``` + +The captured response below is abridged; `syncStatus` contains additional L1 and L2 progress fields. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "version": "0x0000000000000000000000000000000000000000000000000000000000000000", + "outputRoot": "0xf90851c88ec4adfe04b03f33beab99bbabbd73fc474ab7b3a8fa109a3913f047", + "blockRef": { + "hash": "0xce5344be15fecbe70574c97e57626f79a0816e8ebfc37a53ad535e82dd2def56", + "number": 22339144 + }, + "withdrawalStorageRoot": "0x891f4462376be7ecac17a67a0ee5be7bc0c35979c182e5f7f19ebb2b1e320cc3", + "stateRoot": "0x686f5150a2aec8f1b5ae15108288530860fa4157a9f39c71e55b0fa24783d506", + "syncStatus": { + "head_l1": { + "number": 25622556 + } + } + } +} +``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/mega.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/processors/op-output-processor.ts` +- Probe: MegaETH Mainnet public endpoint, July 27, 2026; response abridged to stable top-level fields diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md index ae5486a..4f1416e 100644 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/read/rpc/realtime_sendRawTransaction.md @@ -4,12 +4,16 @@ description: realtime_sendRawTransaction — submit a transaction and receive th # realtime_sendRawTransaction +## Summary + Submits a signed transaction and returns the receipt directly once the transaction is executed — no polling required. This is a drop-in replacement for `eth_sendRawTransaction` that eliminates the need to poll `eth_getTransactionReceipt`. When no timeout is supplied, the node uses its 5-second default wait. The public gateway accepts an optional timeout but caps it at 3,000 milliseconds. The gateway routes this method and [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) through the same synchronous submission handler, so their parameters and receipt behavior are equivalent. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters | Position | Type | Required | Notes | @@ -17,7 +21,7 @@ The gateway routes this method and [`eth_sendRawTransactionSync`](./eth_sendRawT | `0` | `Data` | Yes | Hex-encoded signed transaction | | `1` | `number` | No | Wait timeout in milliseconds; capped at `3000` by the gateway | -## Returns +## Result A transaction receipt object on success: @@ -29,30 +33,47 @@ A transaction receipt object on success: | `from` | `Data` (20 bytes) | Sender address | | `to` | `Data` (20 bytes) | Recipient address (`null` for contract creation) | | `gasUsed` | `Quantity` | Gas consumed by the transaction | -| `status` | `Quantity` | `0x1` for success, `0x0` for revert | +| `status` | `Quantity` | Nonzero for success; zero for revert | | `logs` | `Log[]` | Event logs emitted during execution | | `contractAddress` | `Data` (20 bytes) | Deployed contract address, or `null` | For receipts produced from a streaming mini-block, `blockHash` can temporarily be the all-`ff` placeholder until the enclosing EVM block is committed. Refetch the receipt with `eth_getTransactionReceipt` after block sealing when a canonical block hash is required. +## MegaETH Behavior + +### Ethereum Standard + +`realtime_sendRawTransaction` is not part of the core Ethereum execution JSON-RPC API. It is a MegaETH extension. + +### MegaETH Node Behavior + +MegaETH adds this synchronous submission method. It returns a real-time receipt and uses the same node implementation as `eth_sendRawTransactionSync`. + +### MegaETH Public Gateway + +The gateway routes this name and `eth_sendRawTransactionSync` through the same synchronous handler. After gateway-side validation, both names are rewritten to the node's `realtime_sendRawTransactionWithSender` method. The gateway caps explicit waits at 3,000 milliseconds and accepts request bodies up to 2.5 MiB. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -| Code | Cause | Fix | -| -------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -| `-32000` | `realtime transaction expired` — receipt not available before the wait expired | The transaction may still land; poll `eth_getTransactionReceipt` | +The `| Scope |` column distinguishes method failures from gateway policy errors. -See also [Error reference](error-codes.md). +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ----------------- | ------------------------------------------------------------------------------ | +| `-32000` | Method | Server error | `realtime transaction expired` — receipt not available before the wait expired | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -X POST -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","id":1,"method":"realtime_sendRawTransaction","params":["0x",3000]}' -``` +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` -Successful response: +Capture date: July 24, 2026 + +Outcome: success ```json { @@ -71,8 +92,6 @@ Successful response: } ``` -Timeout response: - ```json { "jsonrpc": "2.0", @@ -83,3 +102,10 @@ Timeout response: } } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/realtime.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/sequencer-guard/single-tx.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/read/rpc/web3_clientVersion.md b/docs/dev/read/rpc/web3_clientVersion.md index 863f27d..7433f45 100644 --- a/docs/dev/read/rpc/web3_clientVersion.md +++ b/docs/dev/read/rpc/web3_clientVersion.md @@ -4,29 +4,66 @@ description: "web3_clientVersion JSON-RPC reference for MegaETH." # web3_clientVersion +## Summary + Returns the current client version string. +The public MegaETH endpoint supports this method. The standard, node, and gateway layers below identify behavior that differs from a generic Ethereum endpoint. + ## Parameters None. -## Returns +## Result **`result`** string Client name, version, and build target. +## MegaETH Behavior + +### Ethereum Standard + +`web3_clientVersion` is a legacy Ethereum client/network compatibility method rather than a current execution-API method. Implementations commonly expose it with the result shape above. + +### MegaETH Node Behavior + +The node constructs a client/build identifier. The exact string is operational metadata and can change between deployments. + +### MegaETH Public Gateway + +The gateway uses the instant read tier and caches the version string for 30 minutes. Callers must not parse the deployment suffix as a stable API. + +This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. + ## Errors -Standard JSON-RPC errors only. -See [Error reference](error-codes.md). +The `| Scope |` column distinguishes method failures from gateway policy errors. + +No method-specific errors were observed. + +| Code | Scope | Message | When it happens | +| -------- | ---------------- | ------------------- | ------------------------------------------------------------ | +| `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | +| `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -## Example +See also [Error Codes](./error-codes.md). -```bash -curl -sS https://mainnet.megaeth.com/rpc \ - -H 'content-type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]}' +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "web3_clientVersion", + "params": [] +} ``` ```json @@ -36,3 +73,10 @@ curl -sS https://mainnet.megaeth.com/rpc \ "result": "mega-reth/v2.0.17-97ab2f0@mnet-sgp-rpc-2" } ``` + +## Sources + +- Spec: EIP-1474 for JSON-RPC framing and error conventions; this method is an extension or legacy compatibility method. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/rpc/rpc/src/web3.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/spec/methods.ts` +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/send-tx/gas-estimation.md b/docs/dev/send-tx/gas-estimation.md index 11938e7..9ff5e7f 100644 --- a/docs/dev/send-tx/gas-estimation.md +++ b/docs/dev/send-tx/gas-estimation.md @@ -59,20 +59,20 @@ cast estimate 0xContractAddress \ Any Ethereum SDK (ethers.js, viem, alloy, web3.py, etc.) works the same way — just point it at a MegaETH RPC endpoint and call `estimateGas` as usual. -### The RPC Compute Gas Cap +### Public RPC Simulation Limits -`eth_estimateGas` (and `eth_call`) enforce a compute gas limit of **60,000,000** on the public RPC endpoint. -This is separate from the protocol per-transaction gas limit of 10,000,000,000. +The public gateway adds a **60,000,000 compute-gas limit** to `eth_call` while preserving the caller's total `gas` field. +`eth_estimateGas` uses a different protection: the gateway calls the node's CPU-limited estimator with a source-default budget of **500,000,000 nanoseconds (0.5 seconds)**. +It does not add the same 60M compute-gas override to gas estimation. -If your transaction requires more than 60M compute gas to simulate, the RPC call will fail. +An `eth_call` that exceeds its compute limit or an estimation that exceeds its CPU-time budget can fail even when the transaction's protocol gas limit would be valid. There are two workarounds: 1. **Set a manual gas limit.** Use the `--gas-limit` flag (see [Toolchain Configuration](#toolchain-configuration) below) to skip estimation entirely and submit the transaction with a known gas value. You can determine the right value by simulating the transaction locally with [`mega-evme`](debugging.md#using-mega-evme), which has no gas cap and fully implements MegaETH's gas model. 2. **Use a managed RPC provider with a higher cap.** - Managed RPC providers typically allow much more gas for `eth_call` and `eth_estimateGas` than the public endpoint. - For reference, standard Ethereum node software (geth, reth) defaults to 50M, and providers like Alchemy support up to 550M. + Managed RPC providers may use different compute and CPU-time policies for `eth_call` and `eth_estimateGas`. See the [RPC Providers](../tooling.md#rpc-providers) table for providers that support MegaETH. ### Request Body Size for Large Deployments diff --git a/docs/dev/send-tx/overview.md b/docs/dev/send-tx/overview.md index a6bfa24..0f14b83 100644 --- a/docs/dev/send-tx/overview.md +++ b/docs/dev/send-tx/overview.md @@ -46,8 +46,9 @@ curl -s https://mainnet.megaeth.com/rpc \ {% endtabs %} {% hint style="warning" %} -The public RPC caps `eth_estimateGas` at **60M compute gas**. -If your transaction needs more (e.g., deploying a large contract), either set a manual gas limit or use a [managed RPC provider](../tooling.md#rpc-providers) with a higher cap. +The public RPC runs `eth_estimateGas` through a CPU-limited estimator whose source-default budget is **0.5 seconds**. +Long-running estimates can fail even when the transaction's protocol gas limit would be valid. +If this affects a large deployment, either set a manual gas limit or use a [managed RPC provider](../tooling.md#rpc-providers) with a different estimation policy. You can determine the exact gas needed by simulating locally with [`mega-evme`](debugging.md#simulating-a-new-transaction). {% endhint %} From 4af32115c7a318171456f8eafa523012f90aa538 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 16:17:31 +0800 Subject: [PATCH 08/13] docs: remove RPC evidence boilerplate --- docs/dev/read/rpc/debug_getHistoryTransactionCount.md | 2 -- docs/dev/read/rpc/debug_getRawHeader.md | 1 - docs/dev/read/rpc/debug_traceBlockByHash.md | 2 +- docs/dev/read/rpc/debug_traceBlockByNumber.md | 1 - docs/dev/read/rpc/debug_traceTransaction.md | 1 - docs/dev/read/rpc/eth_accounts.md | 2 -- docs/dev/read/rpc/eth_blockNumber.md | 2 -- docs/dev/read/rpc/eth_call.md | 2 -- docs/dev/read/rpc/eth_callMany.md | 1 - docs/dev/read/rpc/eth_chainId.md | 2 -- docs/dev/read/rpc/eth_createAccessList.md | 2 -- docs/dev/read/rpc/eth_estimateGas.md | 2 -- docs/dev/read/rpc/eth_feeHistory.md | 2 -- docs/dev/read/rpc/eth_gasPrice.md | 2 -- docs/dev/read/rpc/eth_getBalance.md | 2 -- docs/dev/read/rpc/eth_getBlockByHash.md | 2 -- docs/dev/read/rpc/eth_getBlockByNumber.md | 2 -- docs/dev/read/rpc/eth_getBlockReceipts.md | 2 -- docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md | 2 -- docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md | 2 -- docs/dev/read/rpc/eth_getCode.md | 2 -- docs/dev/read/rpc/eth_getCodeByHash.md | 2 -- docs/dev/read/rpc/eth_getHeaderByHash.md | 2 -- docs/dev/read/rpc/eth_getHeaderByNumber.md | 2 -- docs/dev/read/rpc/eth_getLogs.md | 2 -- docs/dev/read/rpc/eth_getStorageAt.md | 2 -- docs/dev/read/rpc/eth_getTransactionByHash.md | 2 -- docs/dev/read/rpc/eth_getTransactionCount.md | 2 -- docs/dev/read/rpc/eth_getTransactionReceipt.md | 2 -- docs/dev/read/rpc/eth_getWithdrawalProof.md | 2 -- docs/dev/read/rpc/eth_maxPriorityFeePerGas.md | 2 -- docs/dev/read/rpc/eth_protocolVersion.md | 2 +- docs/dev/read/rpc/eth_sendRawTransaction.md | 2 -- docs/dev/read/rpc/eth_sendRawTransactionSync.md | 2 -- docs/dev/read/rpc/eth_subscribe.md | 3 --- docs/dev/read/rpc/eth_syncing.md | 2 -- docs/dev/read/rpc/eth_unsubscribe.md | 2 -- docs/dev/read/rpc/mega_getBlockWitness.md | 2 -- docs/dev/read/rpc/mega_getWithdrawalProof.md | 2 -- docs/dev/read/rpc/mega_outputAtBlock.md | 2 -- docs/dev/read/rpc/net_listening.md | 2 -- docs/dev/read/rpc/net_peerCount.md | 2 -- docs/dev/read/rpc/net_version.md | 2 -- docs/dev/read/rpc/optimism_outputAtBlock.md | 2 -- docs/dev/read/rpc/realtime_sendRawTransaction.md | 2 -- docs/dev/read/rpc/web3_clientVersion.md | 2 -- 46 files changed, 2 insertions(+), 87 deletions(-) diff --git a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md index 9946852..3856ab8 100644 --- a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md +++ b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md @@ -38,8 +38,6 @@ MegaETH adds this diagnostic method. It resolves the selected block and returns The public gateway exposes the method in the simple read tier and caches resolved results as immutable data for 30 minutes. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/read/rpc/debug_getRawHeader.md index d0db656..9feac68 100644 --- a/docs/dev/read/rpc/debug_getRawHeader.md +++ b/docs/dev/read/rpc/debug_getRawHeader.md @@ -34,7 +34,6 @@ The encoded header includes the fields used by the selected MegaETH hardfork. ### MegaETH Public Gateway The public gateway forwards this method through its compute pool and may cache immutable block selections. -Support and a successful historical lookup were observed on July 24, 2026. ## Errors diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/read/rpc/debug_traceBlockByHash.md index 2b143de..372d889 100644 --- a/docs/dev/read/rpc/debug_traceBlockByHash.md +++ b/docs/dev/read/rpc/debug_traceBlockByHash.md @@ -39,7 +39,7 @@ System transactions may therefore appear in block traces. ### MegaETH Public Gateway The public gateway streams trace responses because they can be large. -It requires two positional parameters and was observed to support `callTracer` on July 24, 2026. +It requires two positional parameters and supports `callTracer`. ## Errors diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/read/rpc/debug_traceBlockByNumber.md index 64c2020..6bb0fc1 100644 --- a/docs/dev/read/rpc/debug_traceBlockByNumber.md +++ b/docs/dev/read/rpc/debug_traceBlockByNumber.md @@ -37,7 +37,6 @@ MegaETH uses geth-compatible tracer options and includes system transactions in ### MegaETH Public Gateway The public gateway streams trace responses and requires two positional parameters. -Support and a successful `callTracer` response were observed on July 24, 2026. ## Errors diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/read/rpc/debug_traceTransaction.md index e0d6ad9..c07e293 100644 --- a/docs/dev/read/rpc/debug_traceTransaction.md +++ b/docs/dev/read/rpc/debug_traceTransaction.md @@ -35,7 +35,6 @@ Tracing a system transaction may expose MegaETH system-contract calls. ### MegaETH Public Gateway The public gateway streams this method's response and requires both positional parameters. -Support and a successful `callTracer` response were observed on July 24, 2026. ## Errors diff --git a/docs/dev/read/rpc/eth_accounts.md b/docs/dev/read/rpc/eth_accounts.md index 04b53a9..9b0efef 100644 --- a/docs/dev/read/rpc/eth_accounts.md +++ b/docs/dev/read/rpc/eth_accounts.md @@ -34,8 +34,6 @@ A self-hosted node can report accounts only when its RPC environment manages key The gateway does not query a signer or node. It synthesizes an empty array, so an empty result means only that the public endpoint does not manage user keys. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_blockNumber.md b/docs/dev/read/rpc/eth_blockNumber.md index f35fc4c..a528038 100644 --- a/docs/dev/read/rpc/eth_blockNumber.md +++ b/docs/dev/read/rpc/eth_blockNumber.md @@ -34,8 +34,6 @@ The node returns the current canonical EVM block height. Mini-blocks produced wi The gateway uses the instant read tier and may cache the head number for 1 second. Applications that need mini-block cadence should use WebSocket subscriptions instead. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_call.md b/docs/dev/read/rpc/eth_call.md index 846049e..d34faa8 100644 --- a/docs/dev/read/rpc/eth_call.md +++ b/docs/dev/read/rpc/eth_call.md @@ -154,8 +154,6 @@ The gateway routes the request to the compute pool, rewrites it to `mega_callWit It preserves the caller's `gas` field and separately supplies an internal compute-gas limit of 60,000,000; the internal limit caps compute gas without replacing the total gas budget. The public endpoint permits a 1.5 MiB single-request body. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/read/rpc/eth_callMany.md index b8df01f..74ae144 100644 --- a/docs/dev/read/rpc/eth_callMany.md +++ b/docs/dev/read/rpc/eth_callMany.md @@ -42,7 +42,6 @@ The MegaETH node executes bundles in order against a shared evolving simulation The gateway accepts two to four positional parameters, limits requests to 100 bundles and 100 total transactions, and limits each call to 60,000,000 compute gas. It applies a 5-second default timeout and accepts an explicit timeout up to 25 seconds. -These limits were verified in gateway source and a successful call was observed on July 24, 2026. ## Errors diff --git a/docs/dev/read/rpc/eth_chainId.md b/docs/dev/read/rpc/eth_chainId.md index 29fe78c..dea6a81 100644 --- a/docs/dev/read/rpc/eth_chainId.md +++ b/docs/dev/read/rpc/eth_chainId.md @@ -34,8 +34,6 @@ The node derives this value from its chain specification. MegaETH Mainnet uses c The gateway uses the instant read tier and caches the immutable result for 30 minutes. MegaETH Mainnet returned chain ID 4326 in the captured example. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_createAccessList.md b/docs/dev/read/rpc/eth_createAccessList.md index ac25989..06de2bf 100644 --- a/docs/dev/read/rpc/eth_createAccessList.md +++ b/docs/dev/read/rpc/eth_createAccessList.md @@ -124,8 +124,6 @@ The node executes the call in access-list collection mode and returns both the a The gateway routes the method to the compute pool without response caching and permits a 1.5 MiB single-request body. Unlike `eth_call`, gateway source does not add the separate 60,000,000 compute-gas override to this method. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_estimateGas.md b/docs/dev/read/rpc/eth_estimateGas.md index 5e1877f..ccd628b 100644 --- a/docs/dev/read/rpc/eth_estimateGas.md +++ b/docs/dev/read/rpc/eth_estimateGas.md @@ -118,8 +118,6 @@ It does not cache the result and supplies an internal CPU-time limit whose sourc This is distinct from `eth_call`'s 60,000,000 compute-gas limit. The public endpoint permits a 1.5 MiB single-request body. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_feeHistory.md b/docs/dev/read/rpc/eth_feeHistory.md index c9b3a45..6298ffc 100644 --- a/docs/dev/read/rpc/eth_feeHistory.md +++ b/docs/dev/read/rpc/eth_feeHistory.md @@ -68,8 +68,6 @@ The node implements the standard fee-history shape. The public gateway does not The gateway synthesizes this response locally instead of querying a node. It accepts 1 to 256 blocks and currently fills the response with a 1,000,000-wei base fee, 0.1 gas-used ratio, 1-wei blob base fee, zero blob utilization, and zero rewards. Treat these as gateway policy values, not measured historical blocks. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_gasPrice.md b/docs/dev/read/rpc/eth_gasPrice.md index b33bf99..90dc371 100644 --- a/docs/dev/read/rpc/eth_gasPrice.md +++ b/docs/dev/read/rpc/eth_gasPrice.md @@ -35,8 +35,6 @@ The node's gas oracle reflects the active MegaETH fee policy. On Mainnet the obs The gateway uses the simple read path and may cache the head-dependent result for 1 second. The captured Mainnet value was 1,000,000 wei, or 0.001 gwei. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBalance.md b/docs/dev/read/rpc/eth_getBalance.md index 0ee7b42..92c2e66 100644 --- a/docs/dev/read/rpc/eth_getBalance.md +++ b/docs/dev/read/rpc/eth_getBalance.md @@ -44,8 +44,6 @@ The node reads the account balance from the selected state. `latest` and `pendin For `latest` or `pending`, the gateway rewrites the request to `mega_getAccountInfo`, treats `pending` as `latest`, and compares rollback-aware cached metadata with the upstream result. It can return cached data when the upstream fails; historical selectors bypass this account cache. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBlockByHash.md b/docs/dev/read/rpc/eth_getBlockByHash.md index e2145c0..e699de2 100644 --- a/docs/dev/read/rpc/eth_getBlockByHash.md +++ b/docs/dev/read/rpc/eth_getBlockByHash.md @@ -74,8 +74,6 @@ The node returns the canonical block matching the hash, or `null` if the hash is The gateway streams and caches successful block responses for 30 minutes, using a hash-to-number mapping to deduplicate entries. A `null` lookup is not cached. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBlockByNumber.md b/docs/dev/read/rpc/eth_getBlockByNumber.md index 648169c..30d2a63 100644 --- a/docs/dev/read/rpc/eth_getBlockByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockByNumber.md @@ -74,8 +74,6 @@ The node resolves a block number or tag and honors the `fullTransactions` respon The gateway returns `null` immediately for `pending`. Other responses are streamed and cached; head-following tags use short-lived entries while fixed blocks are treated as immutable. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBlockReceipts.md b/docs/dev/read/rpc/eth_getBlockReceipts.md index a661be2..ceb33e0 100644 --- a/docs/dev/read/rpc/eth_getBlockReceipts.md +++ b/docs/dev/read/rpc/eth_getBlockReceipts.md @@ -80,8 +80,6 @@ The node returns all receipts for the selected block. The response can be large The gateway returns `null` immediately for `pending`, streams large responses, and caches successful results for up to 30 minutes. The method is in the IO-heavy read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md index 3b9cc43..39ddbad 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md @@ -36,8 +36,6 @@ The node looks up the block and returns its transaction count. An unknown block The gateway caches successful hash-based lookups for 30 minutes in the simple read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md index 691d1e9..8930a57 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md @@ -36,8 +36,6 @@ The node resolves the number or tag and returns the block's transaction count. A The gateway caches successful fixed-block lookups for 30 minutes in the simple read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getCode.md b/docs/dev/read/rpc/eth_getCode.md index 6b55cca..a74d758 100644 --- a/docs/dev/read/rpc/eth_getCode.md +++ b/docs/dev/read/rpc/eth_getCode.md @@ -43,8 +43,6 @@ The node returns runtime bytecode from the selected state. A missing account and The gateway streams bytecode responses and caches successful fixed-state lookups for up to 30 minutes. The exact cache key follows the address and block selector. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getCodeByHash.md b/docs/dev/read/rpc/eth_getCodeByHash.md index d201e85..b5baad8 100644 --- a/docs/dev/read/rpc/eth_getCodeByHash.md +++ b/docs/dev/read/rpc/eth_getCodeByHash.md @@ -36,8 +36,6 @@ MegaETH adds a direct code-hash lookup that returns the stored runtime bytecode. The public gateway exposes this MegaETH extension and caches successful immutable lookups for 30 minutes. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getHeaderByHash.md b/docs/dev/read/rpc/eth_getHeaderByHash.md index 9ce3910..652d88d 100644 --- a/docs/dev/read/rpc/eth_getHeaderByHash.md +++ b/docs/dev/read/rpc/eth_getHeaderByHash.md @@ -64,8 +64,6 @@ MegaETH exposes a header-only lookup. It returns `null` when the hash is unknown The gateway streams successful responses, caches them for 30 minutes, and records a hash-to-number mapping. A `null` result is deliberately not cached. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getHeaderByNumber.md b/docs/dev/read/rpc/eth_getHeaderByNumber.md index b230d89..296e366 100644 --- a/docs/dev/read/rpc/eth_getHeaderByNumber.md +++ b/docs/dev/read/rpc/eth_getHeaderByNumber.md @@ -64,8 +64,6 @@ MegaETH exposes a header-only lookup by number or tag. It returns `null` when th The gateway returns `null` immediately for `pending`; other header responses are streamed and cached, with fixed blocks treated as immutable. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getLogs.md b/docs/dev/read/rpc/eth_getLogs.md index bfde0ac..b06dfcb 100644 --- a/docs/dev/read/rpc/eth_getLogs.md +++ b/docs/dev/read/rpc/eth_getLogs.md @@ -93,8 +93,6 @@ The node applies the standard address/topic filter and enforces canonical block- The gateway places the method in the IO-heavy tier, routes older explicit ranges to its ClickHouse-backed log service when configured, streams the response, and caches only cache-safe filters. There is no gateway block-range cap, but backend row, time, or memory limits can still make very large queries incomplete or fail. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getStorageAt.md b/docs/dev/read/rpc/eth_getStorageAt.md index 2a04703..21e4bfe 100644 --- a/docs/dev/read/rpc/eth_getStorageAt.md +++ b/docs/dev/read/rpc/eth_getStorageAt.md @@ -49,8 +49,6 @@ The node reads a 32-byte storage word from the selected state. A zero word does The gateway exposes the method in the instant read tier and does not cache the response. Historical-state retention errors from the selected backend remain visible to callers. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getTransactionByHash.md b/docs/dev/read/rpc/eth_getTransactionByHash.md index eb406de..ff5ad4a 100644 --- a/docs/dev/read/rpc/eth_getTransactionByHash.md +++ b/docs/dev/read/rpc/eth_getTransactionByHash.md @@ -80,8 +80,6 @@ The node returns a transaction known to canonical storage or the live transactio The gateway caches included transactions for 30 minutes. A `null` result is not cached, so a later request can observe a transaction that has since become available. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getTransactionCount.md b/docs/dev/read/rpc/eth_getTransactionCount.md index cb09a25..f71508a 100644 --- a/docs/dev/read/rpc/eth_getTransactionCount.md +++ b/docs/dev/read/rpc/eth_getTransactionCount.md @@ -44,8 +44,6 @@ The node returns the account nonce at the selected state. Unknown accounts and a For `latest` or `pending`, the gateway rewrites to `mega_getAccountInfo`, treats `pending` as `latest`, and can return a fresh cached nonce immediately. Historical selectors bypass the account cache; a nonce read in the same outer batch as submissions need not include those submissions. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getTransactionReceipt.md b/docs/dev/read/rpc/eth_getTransactionReceipt.md index 68c205c..b6e139f 100644 --- a/docs/dev/read/rpc/eth_getTransactionReceipt.md +++ b/docs/dev/read/rpc/eth_getTransactionReceipt.md @@ -76,8 +76,6 @@ The node returns `null` until a receipt is visible. Receipts produced from a rea The gateway first checks its receipt cache, forwards misses upstream, and caches non-null receipts for 30 minutes. A `null` result is not cached. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/read/rpc/eth_getWithdrawalProof.md index 40c7af7..aee3c9e 100644 --- a/docs/dev/read/rpc/eth_getWithdrawalProof.md +++ b/docs/dev/read/rpc/eth_getWithdrawalProof.md @@ -37,8 +37,6 @@ MegaETH implements this OP Stack withdrawal-proof extension for the L2-to-L1 mes The public gateway exposes this method and caches successful proofs for 30 minutes. All three positional parameters are required at the gateway. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md index e2e2af2..148452d 100644 --- a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md +++ b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md @@ -35,8 +35,6 @@ The node fee policy does not require a priority fee, but the public result is sy The gateway synthesizes a zero-wei priority fee without calling a node. This is a current MegaETH fee-policy response, not a market estimate. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/read/rpc/eth_protocolVersion.md index 34cf9cb..cdf462d 100644 --- a/docs/dev/read/rpc/eth_protocolVersion.md +++ b/docs/dev/read/rpc/eth_protocolVersion.md @@ -31,7 +31,7 @@ MegaETH exposes the inherited compatibility method through the `eth` namespace. ### MegaETH Public Gateway The gateway treats this response as immutable and may cache it. -The value shown in the example was observed on July 24, 2026, but callers should not use it for chain selection; use [`eth_chainId`](./eth_chainId.md) instead. +Callers should not use this value for chain selection; use [`eth_chainId`](./eth_chainId.md) instead. ## Errors diff --git a/docs/dev/read/rpc/eth_sendRawTransaction.md b/docs/dev/read/rpc/eth_sendRawTransaction.md index acbab0c..54fe5e3 100644 --- a/docs/dev/read/rpc/eth_sendRawTransaction.md +++ b/docs/dev/read/rpc/eth_sendRawTransaction.md @@ -37,8 +37,6 @@ The node decodes and validates the signed transaction before admitting it to the The gateway validates chain ID, signature, intrinsic gas, fee floor, nonce, balance, and policy checks before forwarding. The method is exempt from read-rate limits and accepts request bodies up to 2.5 MiB. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/read/rpc/eth_sendRawTransactionSync.md index 6a52cd6..68efab5 100644 --- a/docs/dev/read/rpc/eth_sendRawTransactionSync.md +++ b/docs/dev/read/rpc/eth_sendRawTransactionSync.md @@ -84,8 +84,6 @@ The current MegaETH node does not register this `eth_*` alias. Its native synchr The gateway exposes this compatibility name and routes it and `realtime_sendRawTransaction` through the same handler. Both are rewritten to the node's `realtime_sendRawTransactionWithSender` method after gateway-side validation. The gateway caps explicit waits at 3,000 milliseconds and accepts request bodies up to 2.5 MiB. An expiry is inconclusive: the transaction may still land. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_subscribe.md b/docs/dev/read/rpc/eth_subscribe.md index 4f7deb9..be0dc0f 100644 --- a/docs/dev/read/rpc/eth_subscribe.md +++ b/docs/dev/read/rpc/eth_subscribe.md @@ -73,9 +73,6 @@ For real-time log delivery, both log-range tags should be `pending`. The public gateway accepts this method only over `wss://mainnet.megaeth.com/ws`. It supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`, tracks ownership per connection, and requires periodic client activity; sending a lightweight request such as `eth_chainId` at least every 30 seconds prevents idle closure. -This behavior and a successful `newHeads` subscription were observed on July 24, 2026. -Connection policy and operational timeouts may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_syncing.md b/docs/dev/read/rpc/eth_syncing.md index 80729c2..0722587 100644 --- a/docs/dev/read/rpc/eth_syncing.md +++ b/docs/dev/read/rpc/eth_syncing.md @@ -44,8 +44,6 @@ The node returns `false` when caught up and a progress object while synchronizin The gateway forwards this dynamic status without response caching in the simple read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/eth_unsubscribe.md b/docs/dev/read/rpc/eth_unsubscribe.md index 8593f01..872de45 100644 --- a/docs/dev/read/rpc/eth_unsubscribe.md +++ b/docs/dev/read/rpc/eth_unsubscribe.md @@ -36,8 +36,6 @@ The node cancels a subscription in the WebSocket session that created it. Subscr The public method is WebSocket-only. The gateway keeps subscription ownership per connection and rejects attempts to cancel a subscription from another session. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/mega_getBlockWitness.md b/docs/dev/read/rpc/mega_getBlockWitness.md index d55af68..ba88ebb 100644 --- a/docs/dev/read/rpc/mega_getBlockWitness.md +++ b/docs/dev/read/rpc/mega_getBlockWitness.md @@ -60,8 +60,6 @@ MegaETH returns a `v0:`-prefixed, base64-encoded zstd witness. Requests can sele The gateway does not cache witness responses. In an outer batch, if any witness request uses a block number below 7,385,897, at most four `mega_getBlockWitness` requests are allowed. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/mega_getWithdrawalProof.md b/docs/dev/read/rpc/mega_getWithdrawalProof.md index f8e2571..96f8a9c 100644 --- a/docs/dev/read/rpc/mega_getWithdrawalProof.md +++ b/docs/dev/read/rpc/mega_getWithdrawalProof.md @@ -74,8 +74,6 @@ The current MegaETH node registers the withdrawal-proof implementation as `eth_g The gateway rewrites this alias to `eth_getWithdrawalProof` and caches successful proofs for 30 minutes. Callers receive the same result shape under either name. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/read/rpc/mega_outputAtBlock.md index 8ff159a..80b799b 100644 --- a/docs/dev/read/rpc/mega_outputAtBlock.md +++ b/docs/dev/read/rpc/mega_outputAtBlock.md @@ -81,8 +81,6 @@ The current MegaETH execution node's related native method is `mega_optimismOutp The gateway rewrites this method to `optimism_outputAtBlock` and routes it to the OP-node pool. It caches stable output data for 30 minutes but refreshes the embedded synchronization status on a 1-second cadence. Its cached projection omits the upstream `version` field, so callers must tolerate `version` being present on a fresh response and absent on a cache hit. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/net_listening.md b/docs/dev/read/rpc/net_listening.md index 1dd005c..3027da0 100644 --- a/docs/dev/read/rpc/net_listening.md +++ b/docs/dev/read/rpc/net_listening.md @@ -34,8 +34,6 @@ The inherited network method reports whether the node's peer-to-peer service is The gateway forwards this dynamic value without response caching in the simple read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/net_peerCount.md b/docs/dev/read/rpc/net_peerCount.md index 85c11b5..cf3047d 100644 --- a/docs/dev/read/rpc/net_peerCount.md +++ b/docs/dev/read/rpc/net_peerCount.md @@ -34,8 +34,6 @@ The inherited network method reports the node's current peer count; the value is The gateway forwards this dynamic value without response caching in the simple read tier. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/net_version.md b/docs/dev/read/rpc/net_version.md index 9456ca8..42d1d8f 100644 --- a/docs/dev/read/rpc/net_version.md +++ b/docs/dev/read/rpc/net_version.md @@ -34,8 +34,6 @@ The node reports its configured network identifier as a decimal string. On MegaE The gateway exposes the method in the instant read tier and caches the immutable network ID for 30 minutes. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/optimism_outputAtBlock.md b/docs/dev/read/rpc/optimism_outputAtBlock.md index bdf79f4..7606a0b 100644 --- a/docs/dev/read/rpc/optimism_outputAtBlock.md +++ b/docs/dev/read/rpc/optimism_outputAtBlock.md @@ -38,8 +38,6 @@ This is the OP node's native output-root method. The related MegaETH execution-n The gateway accepts this name and `mega_outputAtBlock`, routes both to the OP-node pool as `optimism_outputAtBlock`, and applies the same split cache policy for output data and synchronization status. Because the cached projection omits `version`, callers must not require that field even though it can appear on a fresh response. -This public behavior was confirmed from gateway source and the example was observed on July 27, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md index 4f1416e..d899171 100644 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/read/rpc/realtime_sendRawTransaction.md @@ -54,8 +54,6 @@ MegaETH adds this synchronous submission method. It returns a real-time receipt The gateway routes this name and `eth_sendRawTransactionSync` through the same synchronous handler. After gateway-side validation, both names are rewritten to the node's `realtime_sendRawTransactionWithSender` method. The gateway caps explicit waits at 3,000 milliseconds and accepts request bodies up to 2.5 MiB. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. diff --git a/docs/dev/read/rpc/web3_clientVersion.md b/docs/dev/read/rpc/web3_clientVersion.md index 7433f45..ac73327 100644 --- a/docs/dev/read/rpc/web3_clientVersion.md +++ b/docs/dev/read/rpc/web3_clientVersion.md @@ -34,8 +34,6 @@ The node constructs a client/build identifier. The exact string is operational m The gateway uses the instant read tier and caches the version string for 30 minutes. Callers must not parse the deployment suffix as a stable API. -This public behavior was confirmed from gateway source and the example was observed on July 24, 2026. Gateway policy and operational values may change. - ## Errors The `| Scope |` column distinguishes method failures from gateway policy errors. From 78f47e8b3a2f17baad4af677305b8bba1db570b2 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 16:22:23 +0800 Subject: [PATCH 09/13] docs: rename RPC comparison section --- docs/dev/read/rpc/debug_getHistoryTransactionCount.md | 2 +- docs/dev/read/rpc/debug_getRawHeader.md | 2 +- docs/dev/read/rpc/debug_traceBlockByHash.md | 2 +- docs/dev/read/rpc/debug_traceBlockByNumber.md | 2 +- docs/dev/read/rpc/debug_traceTransaction.md | 2 +- docs/dev/read/rpc/eth_accounts.md | 2 +- docs/dev/read/rpc/eth_blockNumber.md | 2 +- docs/dev/read/rpc/eth_call.md | 2 +- docs/dev/read/rpc/eth_callMany.md | 2 +- docs/dev/read/rpc/eth_chainId.md | 2 +- docs/dev/read/rpc/eth_createAccessList.md | 2 +- docs/dev/read/rpc/eth_estimateGas.md | 2 +- docs/dev/read/rpc/eth_feeHistory.md | 2 +- docs/dev/read/rpc/eth_gasPrice.md | 2 +- docs/dev/read/rpc/eth_getBalance.md | 2 +- docs/dev/read/rpc/eth_getBlockByHash.md | 2 +- docs/dev/read/rpc/eth_getBlockByNumber.md | 2 +- docs/dev/read/rpc/eth_getBlockReceipts.md | 2 +- docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md | 2 +- docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md | 2 +- docs/dev/read/rpc/eth_getCode.md | 2 +- docs/dev/read/rpc/eth_getCodeByHash.md | 2 +- docs/dev/read/rpc/eth_getHeaderByHash.md | 2 +- docs/dev/read/rpc/eth_getHeaderByNumber.md | 2 +- docs/dev/read/rpc/eth_getLogs.md | 2 +- docs/dev/read/rpc/eth_getStorageAt.md | 2 +- docs/dev/read/rpc/eth_getTransactionByHash.md | 2 +- docs/dev/read/rpc/eth_getTransactionCount.md | 2 +- docs/dev/read/rpc/eth_getTransactionReceipt.md | 2 +- docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md | 2 +- docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md | 2 +- docs/dev/read/rpc/eth_getUncleCountByBlockHash.md | 2 +- docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md | 2 +- docs/dev/read/rpc/eth_getWithdrawalProof.md | 2 +- docs/dev/read/rpc/eth_maxPriorityFeePerGas.md | 2 +- docs/dev/read/rpc/eth_protocolVersion.md | 2 +- docs/dev/read/rpc/eth_sendRawTransaction.md | 2 +- docs/dev/read/rpc/eth_sendRawTransactionSync.md | 2 +- docs/dev/read/rpc/eth_subscribe.md | 2 +- docs/dev/read/rpc/eth_syncing.md | 2 +- docs/dev/read/rpc/eth_uninstallFilter.md | 2 +- docs/dev/read/rpc/eth_unsubscribe.md | 2 +- docs/dev/read/rpc/mega_getBlockWitness.md | 2 +- docs/dev/read/rpc/mega_getWithdrawalProof.md | 2 +- docs/dev/read/rpc/mega_outputAtBlock.md | 2 +- docs/dev/read/rpc/net_listening.md | 2 +- docs/dev/read/rpc/net_peerCount.md | 2 +- docs/dev/read/rpc/net_version.md | 2 +- docs/dev/read/rpc/optimism_outputAtBlock.md | 2 +- docs/dev/read/rpc/realtime_sendRawTransaction.md | 2 +- docs/dev/read/rpc/web3_clientVersion.md | 2 +- 51 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md index 3856ab8..f25abbd 100644 --- a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md +++ b/docs/dev/read/rpc/debug_getHistoryTransactionCount.md @@ -24,7 +24,7 @@ Hex block number or tag (`earliest`, `latest`, `safe`, `finalized`). Cumulative transaction count across all blocks up to the selected block. Consecutive blocks with no transactions return the same value. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/read/rpc/debug_getRawHeader.md index 9feac68..d51a46d 100644 --- a/docs/dev/read/rpc/debug_getRawHeader.md +++ b/docs/dev/read/rpc/debug_getRawHeader.md @@ -20,7 +20,7 @@ The public MegaETH endpoint supports this standard debug method. The result is a `DATA` value containing the RLP-encoded header. Decode the bytes as an Ethereum block header rather than treating them as a JSON block object. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/read/rpc/debug_traceBlockByHash.md index 372d889..44ba3b0 100644 --- a/docs/dev/read/rpc/debug_traceBlockByHash.md +++ b/docs/dev/read/rpc/debug_traceBlockByHash.md @@ -24,7 +24,7 @@ For example, set `tracer` to `"callTracer"` for a nested call frame instead of o The result is an array ordered by transaction index. Each entry contains `txHash` and either `result` or `error`; the shape of `result` depends on the selected tracer. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/read/rpc/debug_traceBlockByNumber.md index 6bb0fc1..6cee7f7 100644 --- a/docs/dev/read/rpc/debug_traceBlockByNumber.md +++ b/docs/dev/read/rpc/debug_traceBlockByNumber.md @@ -23,7 +23,7 @@ Common `traceConfig` fields include `tracer`, `tracerConfig`, and `timeout`. The result is an array ordered by transaction index. Each entry contains `txHash` and either `result` or `error`; the shape of `result` depends on the selected tracer. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/read/rpc/debug_traceTransaction.md index c07e293..4d2ff51 100644 --- a/docs/dev/read/rpc/debug_traceTransaction.md +++ b/docs/dev/read/rpc/debug_traceTransaction.md @@ -21,7 +21,7 @@ The public MegaETH endpoint supports this standard debug method. The result shape depends on the tracer. With no named tracer, the result contains opcode-level `structLogs`; with `callTracer`, it is a nested call frame. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_accounts.md b/docs/dev/read/rpc/eth_accounts.md index 9b0efef..39bc370 100644 --- a/docs/dev/read/rpc/eth_accounts.md +++ b/docs/dev/read/rpc/eth_accounts.md @@ -20,7 +20,7 @@ None. Accounts controlled by the RPC node; always empty on public endpoints. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_blockNumber.md b/docs/dev/read/rpc/eth_blockNumber.md index a528038..701deb2 100644 --- a/docs/dev/read/rpc/eth_blockNumber.md +++ b/docs/dev/read/rpc/eth_blockNumber.md @@ -20,7 +20,7 @@ None. Current head block number; advances with each new block. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_call.md b/docs/dev/read/rpc/eth_call.md index d34faa8..582de26 100644 --- a/docs/dev/read/rpc/eth_call.md +++ b/docs/dev/read/rpc/eth_call.md @@ -138,7 +138,7 @@ Raw return bytes. Calls to non-contract addresses return `0x`. Reverts surface as JSON-RPC errors, not as a normal result. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/read/rpc/eth_callMany.md index 74ae144..c2d5d19 100644 --- a/docs/dev/read/rpc/eth_callMany.md +++ b/docs/dev/read/rpc/eth_callMany.md @@ -28,7 +28,7 @@ Each transaction uses the standard `eth_call` transaction-call fields. The result is an array of bundle results. Each bundle result is an array containing one object per transaction; a successful call object contains a `value` field with the returned `DATA`. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_chainId.md b/docs/dev/read/rpc/eth_chainId.md index dea6a81..38bf7b1 100644 --- a/docs/dev/read/rpc/eth_chainId.md +++ b/docs/dev/read/rpc/eth_chainId.md @@ -20,7 +20,7 @@ None. The chain ID for the connected network. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_createAccessList.md b/docs/dev/read/rpc/eth_createAccessList.md index 06de2bf..d622b61 100644 --- a/docs/dev/read/rpc/eth_createAccessList.md +++ b/docs/dev/read/rpc/eth_createAccessList.md @@ -109,7 +109,7 @@ Object keyed by address. Each value: Execution error when the call reverts; may coexist with `accessList` and `gasUsed`. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_estimateGas.md b/docs/dev/read/rpc/eth_estimateGas.md index ccd628b..c822beb 100644 --- a/docs/dev/read/rpc/eth_estimateGas.md +++ b/docs/dev/read/rpc/eth_estimateGas.md @@ -101,7 +101,7 @@ Object keyed by address. Each value: Estimated execution gas. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_feeHistory.md b/docs/dev/read/rpc/eth_feeHistory.md index 6298ffc..3657aaa 100644 --- a/docs/dev/read/rpc/eth_feeHistory.md +++ b/docs/dev/read/rpc/eth_feeHistory.md @@ -54,7 +54,7 @@ Monotonically increasing values from `0` to `100`; omit to exclude `reward` from Blob gas utilization ratio per block when available. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_gasPrice.md b/docs/dev/read/rpc/eth_gasPrice.md index 90dc371..654ed50 100644 --- a/docs/dev/read/rpc/eth_gasPrice.md +++ b/docs/dev/read/rpc/eth_gasPrice.md @@ -21,7 +21,7 @@ None. Gas price in wei. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBalance.md b/docs/dev/read/rpc/eth_getBalance.md index 92c2e66..79b8d5b 100644 --- a/docs/dev/read/rpc/eth_getBalance.md +++ b/docs/dev/read/rpc/eth_getBalance.md @@ -30,7 +30,7 @@ The default is `"latest"`. Balance in wei. The method returns a zero quantity for unknown accounts and zero-balance accounts alike. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBlockByHash.md b/docs/dev/read/rpc/eth_getBlockByHash.md index e699de2..6c156e8 100644 --- a/docs/dev/read/rpc/eth_getBlockByHash.md +++ b/docs/dev/read/rpc/eth_getBlockByHash.md @@ -60,7 +60,7 @@ Target block hash. Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBlockByNumber.md b/docs/dev/read/rpc/eth_getBlockByNumber.md index 30d2a63..1cad89c 100644 --- a/docs/dev/read/rpc/eth_getBlockByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockByNumber.md @@ -60,7 +60,7 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Additional standard fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBlockReceipts.md b/docs/dev/read/rpc/eth_getBlockReceipts.md index ceb33e0..e0c92db 100644 --- a/docs/dev/read/rpc/eth_getBlockReceipts.md +++ b/docs/dev/read/rpc/eth_getBlockReceipts.md @@ -66,7 +66,7 @@ Each array element contains: Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md index 39ddbad..cc7f287 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md @@ -22,7 +22,7 @@ Target block hash. Transaction count; `null` when the block is not found. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md index 8930a57..91c393f 100644 --- a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md +++ b/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md @@ -22,7 +22,7 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Transaction count; `null` when the block is not found. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getCode.md b/docs/dev/read/rpc/eth_getCode.md index a74d758..69ccb08 100644 --- a/docs/dev/read/rpc/eth_getCode.md +++ b/docs/dev/read/rpc/eth_getCode.md @@ -29,7 +29,7 @@ The default is `"latest"`. Runtime bytecode (not creation bytecode) at the address; `0x` when no code is deployed. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getCodeByHash.md b/docs/dev/read/rpc/eth_getCodeByHash.md index b5baad8..f262ce9 100644 --- a/docs/dev/read/rpc/eth_getCodeByHash.md +++ b/docs/dev/read/rpc/eth_getCodeByHash.md @@ -22,7 +22,7 @@ Target runtime code hash. Runtime bytecode; `0x` when no bytecode is stored for that hash. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getHeaderByHash.md b/docs/dev/read/rpc/eth_getHeaderByHash.md index 652d88d..0c60336 100644 --- a/docs/dev/read/rpc/eth_getHeaderByHash.md +++ b/docs/dev/read/rpc/eth_getHeaderByHash.md @@ -50,7 +50,7 @@ Target block hash. Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getHeaderByNumber.md b/docs/dev/read/rpc/eth_getHeaderByNumber.md index 296e366..7861cf5 100644 --- a/docs/dev/read/rpc/eth_getHeaderByNumber.md +++ b/docs/dev/read/rpc/eth_getHeaderByNumber.md @@ -50,7 +50,7 @@ Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. Additional standard header fields (`stateRoot`, `logsBloom`, `transactionsRoot`, `receiptsRoot`, `baseFeePerGas`, …) are also included. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getLogs.md b/docs/dev/read/rpc/eth_getLogs.md index b06dfcb..1c11eba 100644 --- a/docs/dev/read/rpc/eth_getLogs.md +++ b/docs/dev/read/rpc/eth_getLogs.md @@ -79,7 +79,7 @@ Log filter. Block timestamp. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getStorageAt.md b/docs/dev/read/rpc/eth_getStorageAt.md index 21e4bfe..e7b0dea 100644 --- a/docs/dev/read/rpc/eth_getStorageAt.md +++ b/docs/dev/read/rpc/eth_getStorageAt.md @@ -35,7 +35,7 @@ The default is `"latest"`. Raw 32-byte storage word; a zero value can mean an empty slot, a non-existent account, or an explicitly stored zero. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getTransactionByHash.md b/docs/dev/read/rpc/eth_getTransactionByHash.md index ff5ad4a..af06655 100644 --- a/docs/dev/read/rpc/eth_getTransactionByHash.md +++ b/docs/dev/read/rpc/eth_getTransactionByHash.md @@ -66,7 +66,7 @@ Target transaction hash. Additional fields vary by transaction type (`gasPrice`, `maxFeePerGas`, `accessList`, `chainId`, `v`, `r`, `s`, etc.). -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getTransactionCount.md b/docs/dev/read/rpc/eth_getTransactionCount.md index f71508a..dc9e8f7 100644 --- a/docs/dev/read/rpc/eth_getTransactionCount.md +++ b/docs/dev/read/rpc/eth_getTransactionCount.md @@ -30,7 +30,7 @@ The default is `"latest"`. Transaction count at the requested block. The method returns a zero quantity for both unknown accounts and accounts with zero transactions. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getTransactionReceipt.md b/docs/dev/read/rpc/eth_getTransactionReceipt.md index b6e139f..0c54cf4 100644 --- a/docs/dev/read/rpc/eth_getTransactionReceipt.md +++ b/docs/dev/read/rpc/eth_getTransactionReceipt.md @@ -62,7 +62,7 @@ Hash of the target transaction. Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md index a775f96..9461fa9 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md @@ -21,7 +21,7 @@ MegaETH blocks do not contain proof-of-work uncles, so the method returns `null` The result is a block object or `null` when no uncle exists at the selected index. On MegaETH, `null` is expected and does not mean that the parent block itself is missing. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md index 734d6cf..d4d5bd9 100644 --- a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md +++ b/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md @@ -21,7 +21,7 @@ MegaETH blocks do not contain proof-of-work uncles, so the method returns `null` The result is a block object or `null` when no uncle exists at the selected index. On MegaETH, `null` is expected and does not mean that the parent block itself is missing. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md index 9cd2885..f8a22ae 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md @@ -20,7 +20,7 @@ MegaETH does not produce proof-of-work uncles, so valid MegaETH blocks return ze The result is a hexadecimal `QUANTITY` containing the uncle count. For a valid MegaETH block this is zero. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md index 4b46e14..ef17958 100644 --- a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md +++ b/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md @@ -20,7 +20,7 @@ MegaETH does not produce proof-of-work uncles, so valid MegaETH blocks return ze The result is a hexadecimal `QUANTITY` containing the uncle count. For a valid MegaETH block this is zero. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/read/rpc/eth_getWithdrawalProof.md index aee3c9e..6691ca4 100644 --- a/docs/dev/read/rpc/eth_getWithdrawalProof.md +++ b/docs/dev/read/rpc/eth_getWithdrawalProof.md @@ -23,7 +23,7 @@ The public MegaETH endpoint supports this method. The standard, node, and gatewa An EIP-1186-style account proof containing `accountProof`, `balance`, `codeHash`, `nonce`, `storageHash`, and one `storageProof` entry per requested key. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md index 148452d..2689519 100644 --- a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md +++ b/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md @@ -21,7 +21,7 @@ None. Always a zero-wei quantity. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/read/rpc/eth_protocolVersion.md index cdf462d..0eba374 100644 --- a/docs/dev/read/rpc/eth_protocolVersion.md +++ b/docs/dev/read/rpc/eth_protocolVersion.md @@ -18,7 +18,7 @@ None. The result is a hexadecimal `QUANTITY`. Do not confuse this compatibility value with the MegaETH chain ID or network ID. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_sendRawTransaction.md b/docs/dev/read/rpc/eth_sendRawTransaction.md index 54fe5e3..e2719d7 100644 --- a/docs/dev/read/rpc/eth_sendRawTransaction.md +++ b/docs/dev/read/rpc/eth_sendRawTransaction.md @@ -23,7 +23,7 @@ Supported envelope types are legacy, EIP-2930, EIP-1559, EIP-4844, and EIP-7702. 32-byte transaction hash. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/read/rpc/eth_sendRawTransactionSync.md index 68efab5..b298fd1 100644 --- a/docs/dev/read/rpc/eth_sendRawTransactionSync.md +++ b/docs/dev/read/rpc/eth_sendRawTransactionSync.md @@ -70,7 +70,7 @@ When omitted, the node uses its 5-second default; the public gateway caps explic Additional fields include `cumulativeGasUsed`, `logsBloom`, `type`, and L1 fee fields (`l1Fee`, `l1GasPrice`, `l1GasUsed`, etc.). -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_subscribe.md b/docs/dev/read/rpc/eth_subscribe.md index be0dc0f..fee6b76 100644 --- a/docs/dev/read/rpc/eth_subscribe.md +++ b/docs/dev/read/rpc/eth_subscribe.md @@ -55,7 +55,7 @@ Payloads depend on the subscription type: Notifications are not replayed automatically after a connection closes. Reconnect and create a new subscription when continuity is required. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_syncing.md b/docs/dev/read/rpc/eth_syncing.md index 0722587..19e701e 100644 --- a/docs/dev/read/rpc/eth_syncing.md +++ b/docs/dev/read/rpc/eth_syncing.md @@ -30,7 +30,7 @@ None. Target block. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_uninstallFilter.md b/docs/dev/read/rpc/eth_uninstallFilter.md index c5bc8ff..3c37c29 100644 --- a/docs/dev/read/rpc/eth_uninstallFilter.md +++ b/docs/dev/read/rpc/eth_uninstallFilter.md @@ -21,7 +21,7 @@ Returns `true` when the filter existed and was removed. Returns `false` when the filter ID was unknown or had already expired. `false` does not mean that `eth_uninstallFilter` itself is unavailable. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/eth_unsubscribe.md b/docs/dev/read/rpc/eth_unsubscribe.md index 872de45..e76dda6 100644 --- a/docs/dev/read/rpc/eth_unsubscribe.md +++ b/docs/dev/read/rpc/eth_unsubscribe.md @@ -22,7 +22,7 @@ Subscription ID returned by `eth_subscribe`. `true` if the subscription was found and cancelled; `false` if the ID was not active. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/mega_getBlockWitness.md b/docs/dev/read/rpc/mega_getBlockWitness.md index ba88ebb..5877331 100644 --- a/docs/dev/read/rpc/mega_getBlockWitness.md +++ b/docs/dev/read/rpc/mega_getBlockWitness.md @@ -46,7 +46,7 @@ Use `blockNumber` together with `blockHash`, or the paired `parentHash` and `att `v0:` followed by a base64-encoded zstd-compressed witness blob. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/mega_getWithdrawalProof.md b/docs/dev/read/rpc/mega_getWithdrawalProof.md index 96f8a9c..d6c2def 100644 --- a/docs/dev/read/rpc/mega_getWithdrawalProof.md +++ b/docs/dev/read/rpc/mega_getWithdrawalProof.md @@ -60,7 +60,7 @@ The node defaults an omitted value to `latest`, but the public endpoint requires Per-key storage proofs; each entry has `key` (`Bytes32`), `value` (`Bytes32`), `proof` (`Data[]`). -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/read/rpc/mega_outputAtBlock.md index 80b799b..5dad1c8 100644 --- a/docs/dev/read/rpc/mega_outputAtBlock.md +++ b/docs/dev/read/rpc/mega_outputAtBlock.md @@ -66,7 +66,7 @@ Concrete hex block number; block tags such as `latest` are not accepted. Backend sync-status snapshot. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/net_listening.md b/docs/dev/read/rpc/net_listening.md index 3027da0..4bb27c2 100644 --- a/docs/dev/read/rpc/net_listening.md +++ b/docs/dev/read/rpc/net_listening.md @@ -20,7 +20,7 @@ None. Always `true`. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/net_peerCount.md b/docs/dev/read/rpc/net_peerCount.md index cf3047d..b5ed6f8 100644 --- a/docs/dev/read/rpc/net_peerCount.md +++ b/docs/dev/read/rpc/net_peerCount.md @@ -20,7 +20,7 @@ None. Number of connected peers. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/net_version.md b/docs/dev/read/rpc/net_version.md index 42d1d8f..e4f03b2 100644 --- a/docs/dev/read/rpc/net_version.md +++ b/docs/dev/read/rpc/net_version.md @@ -20,7 +20,7 @@ None. Network ID as a decimal integer string. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/optimism_outputAtBlock.md b/docs/dev/read/rpc/optimism_outputAtBlock.md index 7606a0b..f48f08c 100644 --- a/docs/dev/read/rpc/optimism_outputAtBlock.md +++ b/docs/dev/read/rpc/optimism_outputAtBlock.md @@ -23,7 +23,7 @@ An output object containing `outputRoot`, `blockRef`, `withdrawalStorageRoot`, ` The upstream `version` field can be present on a fresh response but is omitted by the gateway's cached projection. See [`mega_outputAtBlock`](./mega_outputAtBlock.md#result) for every field. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md index d899171..4dc2971 100644 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/read/rpc/realtime_sendRawTransaction.md @@ -40,7 +40,7 @@ A transaction receipt object on success: For receipts produced from a streaming mini-block, `blockHash` can temporarily be the all-`ff` placeholder until the enclosing EVM block is committed. Refetch the receipt with `eth_getTransactionReceipt` after block sealing when a canonical block hash is required. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard diff --git a/docs/dev/read/rpc/web3_clientVersion.md b/docs/dev/read/rpc/web3_clientVersion.md index ac73327..090f22b 100644 --- a/docs/dev/read/rpc/web3_clientVersion.md +++ b/docs/dev/read/rpc/web3_clientVersion.md @@ -20,7 +20,7 @@ None. Client name, version, and build target. -## MegaETH Behavior +## Comparison with Ethereum Standard JSON-RPC ### Ethereum Standard From 012a9d5784cb23a4a128be0a69afb5a3de423622 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 16:45:36 +0800 Subject: [PATCH 10/13] docs: promote RPC reference section --- .gitbook.yaml | 57 ++++- docs/AGENTS.md | 2 +- docs/SUMMARY.md | 106 ++++----- docs/dev/AGENTS.md | 4 +- docs/dev/overview.md | 2 +- docs/dev/payments.md | 2 +- docs/dev/read/overview.md | 149 +------------ docs/dev/read/realtime-api.md | 18 +- docs/dev/read/rpc/README.md | 83 ------- docs/dev/rpc/README.md | 207 ++++++++++++++++++ .../rpc/debug_getHistoryTransactionCount.md | 0 docs/dev/{read => }/rpc/debug_getRawHeader.md | 0 .../{read => }/rpc/debug_traceBlockByHash.md | 0 .../rpc/debug_traceBlockByNumber.md | 0 .../{read => }/rpc/debug_traceTransaction.md | 0 docs/dev/{read => }/rpc/error-codes.md | 24 +- docs/dev/{read => }/rpc/eth_accounts.md | 0 docs/dev/{read => }/rpc/eth_blockNumber.md | 0 docs/dev/{read => }/rpc/eth_call.md | 0 docs/dev/{read => }/rpc/eth_callMany.md | 0 docs/dev/{read => }/rpc/eth_chainId.md | 0 .../{read => }/rpc/eth_createAccessList.md | 0 docs/dev/{read => }/rpc/eth_estimateGas.md | 0 docs/dev/{read => }/rpc/eth_feeHistory.md | 0 docs/dev/{read => }/rpc/eth_gasPrice.md | 0 docs/dev/{read => }/rpc/eth_getBalance.md | 0 docs/dev/{read => }/rpc/eth_getBlockByHash.md | 0 .../{read => }/rpc/eth_getBlockByNumber.md | 0 .../{read => }/rpc/eth_getBlockReceipts.md | 0 .../rpc/eth_getBlockTransactionCountByHash.md | 0 .../eth_getBlockTransactionCountByNumber.md | 0 docs/dev/{read => }/rpc/eth_getCode.md | 0 docs/dev/{read => }/rpc/eth_getCodeByHash.md | 0 .../dev/{read => }/rpc/eth_getHeaderByHash.md | 0 .../{read => }/rpc/eth_getHeaderByNumber.md | 0 docs/dev/{read => }/rpc/eth_getLogs.md | 0 docs/dev/{read => }/rpc/eth_getStorageAt.md | 0 .../rpc/eth_getTransactionByHash.md | 0 .../{read => }/rpc/eth_getTransactionCount.md | 0 .../rpc/eth_getTransactionReceipt.md | 0 .../rpc/eth_getUncleByBlockHashAndIndex.md | 0 .../rpc/eth_getUncleByBlockNumberAndIndex.md | 0 .../rpc/eth_getUncleCountByBlockHash.md | 0 .../rpc/eth_getUncleCountByBlockNumber.md | 0 .../{read => }/rpc/eth_getWithdrawalProof.md | 0 .../rpc/eth_maxPriorityFeePerGas.md | 0 .../dev/{read => }/rpc/eth_protocolVersion.md | 0 .../{read => }/rpc/eth_sendRawTransaction.md | 0 .../rpc/eth_sendRawTransactionSync.md | 0 docs/dev/{read => }/rpc/eth_subscribe.md | 0 docs/dev/{read => }/rpc/eth_syncing.md | 0 .../dev/{read => }/rpc/eth_uninstallFilter.md | 0 docs/dev/{read => }/rpc/eth_unsubscribe.md | 0 .../{read => }/rpc/mega_getBlockWitness.md | 0 .../{read => }/rpc/mega_getWithdrawalProof.md | 0 docs/dev/{read => }/rpc/mega_outputAtBlock.md | 0 docs/dev/{read => }/rpc/net_listening.md | 0 docs/dev/{read => }/rpc/net_peerCount.md | 0 docs/dev/{read => }/rpc/net_version.md | 0 .../{read => }/rpc/optimism_outputAtBlock.md | 0 .../rpc/realtime_sendRawTransaction.md | 0 docs/dev/{read => }/rpc/web3_clientVersion.md | 0 docs/dev/send-tx/debugging.md | 6 +- docs/dev/send-tx/gas-estimation.md | 4 +- docs/dev/send-tx/overview.md | 2 +- docs/mini-block.md | 6 +- 66 files changed, 352 insertions(+), 320 deletions(-) delete mode 100644 docs/dev/read/rpc/README.md create mode 100644 docs/dev/rpc/README.md rename docs/dev/{read => }/rpc/debug_getHistoryTransactionCount.md (100%) rename docs/dev/{read => }/rpc/debug_getRawHeader.md (100%) rename docs/dev/{read => }/rpc/debug_traceBlockByHash.md (100%) rename docs/dev/{read => }/rpc/debug_traceBlockByNumber.md (100%) rename docs/dev/{read => }/rpc/debug_traceTransaction.md (100%) rename docs/dev/{read => }/rpc/error-codes.md (83%) rename docs/dev/{read => }/rpc/eth_accounts.md (100%) rename docs/dev/{read => }/rpc/eth_blockNumber.md (100%) rename docs/dev/{read => }/rpc/eth_call.md (100%) rename docs/dev/{read => }/rpc/eth_callMany.md (100%) rename docs/dev/{read => }/rpc/eth_chainId.md (100%) rename docs/dev/{read => }/rpc/eth_createAccessList.md (100%) rename docs/dev/{read => }/rpc/eth_estimateGas.md (100%) rename docs/dev/{read => }/rpc/eth_feeHistory.md (100%) rename docs/dev/{read => }/rpc/eth_gasPrice.md (100%) rename docs/dev/{read => }/rpc/eth_getBalance.md (100%) rename docs/dev/{read => }/rpc/eth_getBlockByHash.md (100%) rename docs/dev/{read => }/rpc/eth_getBlockByNumber.md (100%) rename docs/dev/{read => }/rpc/eth_getBlockReceipts.md (100%) rename docs/dev/{read => }/rpc/eth_getBlockTransactionCountByHash.md (100%) rename docs/dev/{read => }/rpc/eth_getBlockTransactionCountByNumber.md (100%) rename docs/dev/{read => }/rpc/eth_getCode.md (100%) rename docs/dev/{read => }/rpc/eth_getCodeByHash.md (100%) rename docs/dev/{read => }/rpc/eth_getHeaderByHash.md (100%) rename docs/dev/{read => }/rpc/eth_getHeaderByNumber.md (100%) rename docs/dev/{read => }/rpc/eth_getLogs.md (100%) rename docs/dev/{read => }/rpc/eth_getStorageAt.md (100%) rename docs/dev/{read => }/rpc/eth_getTransactionByHash.md (100%) rename docs/dev/{read => }/rpc/eth_getTransactionCount.md (100%) rename docs/dev/{read => }/rpc/eth_getTransactionReceipt.md (100%) rename docs/dev/{read => }/rpc/eth_getUncleByBlockHashAndIndex.md (100%) rename docs/dev/{read => }/rpc/eth_getUncleByBlockNumberAndIndex.md (100%) rename docs/dev/{read => }/rpc/eth_getUncleCountByBlockHash.md (100%) rename docs/dev/{read => }/rpc/eth_getUncleCountByBlockNumber.md (100%) rename docs/dev/{read => }/rpc/eth_getWithdrawalProof.md (100%) rename docs/dev/{read => }/rpc/eth_maxPriorityFeePerGas.md (100%) rename docs/dev/{read => }/rpc/eth_protocolVersion.md (100%) rename docs/dev/{read => }/rpc/eth_sendRawTransaction.md (100%) rename docs/dev/{read => }/rpc/eth_sendRawTransactionSync.md (100%) rename docs/dev/{read => }/rpc/eth_subscribe.md (100%) rename docs/dev/{read => }/rpc/eth_syncing.md (100%) rename docs/dev/{read => }/rpc/eth_uninstallFilter.md (100%) rename docs/dev/{read => }/rpc/eth_unsubscribe.md (100%) rename docs/dev/{read => }/rpc/mega_getBlockWitness.md (100%) rename docs/dev/{read => }/rpc/mega_getWithdrawalProof.md (100%) rename docs/dev/{read => }/rpc/mega_outputAtBlock.md (100%) rename docs/dev/{read => }/rpc/net_listening.md (100%) rename docs/dev/{read => }/rpc/net_peerCount.md (100%) rename docs/dev/{read => }/rpc/net_version.md (100%) rename docs/dev/{read => }/rpc/optimism_outputAtBlock.md (100%) rename docs/dev/{read => }/rpc/realtime_sendRawTransaction.md (100%) rename docs/dev/{read => }/rpc/web3_clientVersion.md (100%) diff --git a/.gitbook.yaml b/.gitbook.yaml index fff1fc7..3ddc55a 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -5,5 +5,58 @@ structure: summary: SUMMARY.md redirects: - dev/read/rpc/eth_callAfter: dev/read/overview.md#available-methods - dev/read/rpc/eth_getLogsWithCursor: dev/read/overview.md#available-methods + dev/read/rpc: dev/rpc/README.md + dev/read/rpc/debug_getHistoryTransactionCount: dev/rpc/debug_getHistoryTransactionCount.md + dev/read/rpc/debug_getRawHeader: dev/rpc/debug_getRawHeader.md + dev/read/rpc/debug_traceBlockByHash: dev/rpc/debug_traceBlockByHash.md + dev/read/rpc/debug_traceBlockByNumber: dev/rpc/debug_traceBlockByNumber.md + dev/read/rpc/debug_traceTransaction: dev/rpc/debug_traceTransaction.md + dev/read/rpc/error-codes: dev/rpc/error-codes.md + dev/read/rpc/eth_accounts: dev/rpc/eth_accounts.md + dev/read/rpc/eth_blockNumber: dev/rpc/eth_blockNumber.md + dev/read/rpc/eth_call: dev/rpc/eth_call.md + dev/read/rpc/eth_callAfter: dev/rpc/README.md#available-methods + dev/read/rpc/eth_callMany: dev/rpc/eth_callMany.md + dev/read/rpc/eth_chainId: dev/rpc/eth_chainId.md + dev/read/rpc/eth_createAccessList: dev/rpc/eth_createAccessList.md + dev/read/rpc/eth_estimateGas: dev/rpc/eth_estimateGas.md + dev/read/rpc/eth_feeHistory: dev/rpc/eth_feeHistory.md + dev/read/rpc/eth_gasPrice: dev/rpc/eth_gasPrice.md + dev/read/rpc/eth_getBalance: dev/rpc/eth_getBalance.md + dev/read/rpc/eth_getBlockByHash: dev/rpc/eth_getBlockByHash.md + dev/read/rpc/eth_getBlockByNumber: dev/rpc/eth_getBlockByNumber.md + dev/read/rpc/eth_getBlockReceipts: dev/rpc/eth_getBlockReceipts.md + dev/read/rpc/eth_getBlockTransactionCountByHash: dev/rpc/eth_getBlockTransactionCountByHash.md + dev/read/rpc/eth_getBlockTransactionCountByNumber: dev/rpc/eth_getBlockTransactionCountByNumber.md + dev/read/rpc/eth_getCode: dev/rpc/eth_getCode.md + dev/read/rpc/eth_getCodeByHash: dev/rpc/eth_getCodeByHash.md + dev/read/rpc/eth_getHeaderByHash: dev/rpc/eth_getHeaderByHash.md + dev/read/rpc/eth_getHeaderByNumber: dev/rpc/eth_getHeaderByNumber.md + dev/read/rpc/eth_getLogs: dev/rpc/eth_getLogs.md + dev/read/rpc/eth_getLogsWithCursor: dev/rpc/README.md#available-methods + dev/read/rpc/eth_getStorageAt: dev/rpc/eth_getStorageAt.md + dev/read/rpc/eth_getTransactionByHash: dev/rpc/eth_getTransactionByHash.md + dev/read/rpc/eth_getTransactionCount: dev/rpc/eth_getTransactionCount.md + dev/read/rpc/eth_getTransactionReceipt: dev/rpc/eth_getTransactionReceipt.md + dev/read/rpc/eth_getUncleByBlockHashAndIndex: dev/rpc/eth_getUncleByBlockHashAndIndex.md + dev/read/rpc/eth_getUncleByBlockNumberAndIndex: dev/rpc/eth_getUncleByBlockNumberAndIndex.md + dev/read/rpc/eth_getUncleCountByBlockHash: dev/rpc/eth_getUncleCountByBlockHash.md + dev/read/rpc/eth_getUncleCountByBlockNumber: dev/rpc/eth_getUncleCountByBlockNumber.md + dev/read/rpc/eth_getWithdrawalProof: dev/rpc/eth_getWithdrawalProof.md + dev/read/rpc/eth_maxPriorityFeePerGas: dev/rpc/eth_maxPriorityFeePerGas.md + dev/read/rpc/eth_protocolVersion: dev/rpc/eth_protocolVersion.md + dev/read/rpc/eth_sendRawTransaction: dev/rpc/eth_sendRawTransaction.md + dev/read/rpc/eth_sendRawTransactionSync: dev/rpc/eth_sendRawTransactionSync.md + dev/read/rpc/eth_subscribe: dev/rpc/eth_subscribe.md + dev/read/rpc/eth_syncing: dev/rpc/eth_syncing.md + dev/read/rpc/eth_uninstallFilter: dev/rpc/eth_uninstallFilter.md + dev/read/rpc/eth_unsubscribe: dev/rpc/eth_unsubscribe.md + dev/read/rpc/mega_getBlockWitness: dev/rpc/mega_getBlockWitness.md + dev/read/rpc/mega_getWithdrawalProof: dev/rpc/mega_getWithdrawalProof.md + dev/read/rpc/mega_outputAtBlock: dev/rpc/mega_outputAtBlock.md + dev/read/rpc/net_listening: dev/rpc/net_listening.md + dev/read/rpc/net_peerCount: dev/rpc/net_peerCount.md + dev/read/rpc/net_version: dev/rpc/net_version.md + dev/read/rpc/optimism_outputAtBlock: dev/rpc/optimism_outputAtBlock.md + dev/read/rpc/realtime_sendRawTransaction: dev/rpc/realtime_sendRawTransaction.md + dev/read/rpc/web3_clientVersion: dev/rpc/web3_clientVersion.md diff --git a/docs/AGENTS.md b/docs/AGENTS.md index b4aa3b9..14daac8 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -94,7 +94,7 @@ Use these exact forms consistently. Do not alternate between variants. ### Within the same layer -Use relative paths: `[Gas Model](gas-model.md)` or `[RPC Methods](../read/overview.md)`. +Use relative paths: `[Gas Model](gas-model.md)` or `[RPC Methods](../rpc/README.md)`. ### Between layers diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 9993466..d3952f5 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -25,59 +25,59 @@ - [Force Inclusion — Foundry](dev/send-tx/force-inclusion.md) - [Read from MegaETH](dev/read/overview.md) - [Realtime API](dev/read/realtime-api.md) - - [RPC Reference](dev/read/rpc/README.md) - - [debug_getHistoryTransactionCount](dev/read/rpc/debug_getHistoryTransactionCount.md) - - [debug_getRawHeader](dev/read/rpc/debug_getRawHeader.md) - - [debug_traceBlockByHash](dev/read/rpc/debug_traceBlockByHash.md) - - [debug_traceBlockByNumber](dev/read/rpc/debug_traceBlockByNumber.md) - - [debug_traceTransaction](dev/read/rpc/debug_traceTransaction.md) - - [eth_accounts](dev/read/rpc/eth_accounts.md) - - [eth_blockNumber](dev/read/rpc/eth_blockNumber.md) - - [eth_call](dev/read/rpc/eth_call.md) - - [eth_callMany](dev/read/rpc/eth_callMany.md) - - [eth_chainId](dev/read/rpc/eth_chainId.md) - - [eth_createAccessList](dev/read/rpc/eth_createAccessList.md) - - [eth_estimateGas](dev/read/rpc/eth_estimateGas.md) - - [eth_feeHistory](dev/read/rpc/eth_feeHistory.md) - - [eth_gasPrice](dev/read/rpc/eth_gasPrice.md) - - [eth_getBalance](dev/read/rpc/eth_getBalance.md) - - [eth_getBlockByHash](dev/read/rpc/eth_getBlockByHash.md) - - [eth_getBlockByNumber](dev/read/rpc/eth_getBlockByNumber.md) - - [eth_getBlockReceipts](dev/read/rpc/eth_getBlockReceipts.md) - - [eth_getBlockTransactionCountByHash](dev/read/rpc/eth_getBlockTransactionCountByHash.md) - - [eth_getBlockTransactionCountByNumber](dev/read/rpc/eth_getBlockTransactionCountByNumber.md) - - [eth_getCode](dev/read/rpc/eth_getCode.md) - - [eth_getCodeByHash](dev/read/rpc/eth_getCodeByHash.md) - - [eth_getHeaderByHash](dev/read/rpc/eth_getHeaderByHash.md) - - [eth_getHeaderByNumber](dev/read/rpc/eth_getHeaderByNumber.md) - - [eth_getLogs](dev/read/rpc/eth_getLogs.md) - - [eth_getStorageAt](dev/read/rpc/eth_getStorageAt.md) - - [eth_getTransactionByHash](dev/read/rpc/eth_getTransactionByHash.md) - - [eth_getTransactionCount](dev/read/rpc/eth_getTransactionCount.md) - - [eth_getTransactionReceipt](dev/read/rpc/eth_getTransactionReceipt.md) - - [eth_getUncleByBlockHashAndIndex](dev/read/rpc/eth_getUncleByBlockHashAndIndex.md) - - [eth_getUncleByBlockNumberAndIndex](dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md) - - [eth_getUncleCountByBlockHash](dev/read/rpc/eth_getUncleCountByBlockHash.md) - - [eth_getUncleCountByBlockNumber](dev/read/rpc/eth_getUncleCountByBlockNumber.md) - - [eth_getWithdrawalProof](dev/read/rpc/eth_getWithdrawalProof.md) - - [eth_maxPriorityFeePerGas](dev/read/rpc/eth_maxPriorityFeePerGas.md) - - [eth_protocolVersion](dev/read/rpc/eth_protocolVersion.md) - - [eth_sendRawTransaction](dev/read/rpc/eth_sendRawTransaction.md) - - [eth_sendRawTransactionSync](dev/read/rpc/eth_sendRawTransactionSync.md) - - [eth_subscribe](dev/read/rpc/eth_subscribe.md) - - [eth_syncing](dev/read/rpc/eth_syncing.md) - - [eth_uninstallFilter](dev/read/rpc/eth_uninstallFilter.md) - - [eth_unsubscribe](dev/read/rpc/eth_unsubscribe.md) - - [mega_getBlockWitness](dev/read/rpc/mega_getBlockWitness.md) - - [mega_getWithdrawalProof](dev/read/rpc/mega_getWithdrawalProof.md) - - [mega_outputAtBlock](dev/read/rpc/mega_outputAtBlock.md) - - [net_listening](dev/read/rpc/net_listening.md) - - [net_peerCount](dev/read/rpc/net_peerCount.md) - - [net_version](dev/read/rpc/net_version.md) - - [optimism_outputAtBlock](dev/read/rpc/optimism_outputAtBlock.md) - - [realtime_sendRawTransaction](dev/read/rpc/realtime_sendRawTransaction.md) - - [web3_clientVersion](dev/read/rpc/web3_clientVersion.md) - - [Error Codes](dev/read/rpc/error-codes.md) +- [RPC Reference](dev/rpc/README.md) + - [debug_getHistoryTransactionCount](dev/rpc/debug_getHistoryTransactionCount.md) + - [debug_getRawHeader](dev/rpc/debug_getRawHeader.md) + - [debug_traceBlockByHash](dev/rpc/debug_traceBlockByHash.md) + - [debug_traceBlockByNumber](dev/rpc/debug_traceBlockByNumber.md) + - [debug_traceTransaction](dev/rpc/debug_traceTransaction.md) + - [eth_accounts](dev/rpc/eth_accounts.md) + - [eth_blockNumber](dev/rpc/eth_blockNumber.md) + - [eth_call](dev/rpc/eth_call.md) + - [eth_callMany](dev/rpc/eth_callMany.md) + - [eth_chainId](dev/rpc/eth_chainId.md) + - [eth_createAccessList](dev/rpc/eth_createAccessList.md) + - [eth_estimateGas](dev/rpc/eth_estimateGas.md) + - [eth_feeHistory](dev/rpc/eth_feeHistory.md) + - [eth_gasPrice](dev/rpc/eth_gasPrice.md) + - [eth_getBalance](dev/rpc/eth_getBalance.md) + - [eth_getBlockByHash](dev/rpc/eth_getBlockByHash.md) + - [eth_getBlockByNumber](dev/rpc/eth_getBlockByNumber.md) + - [eth_getBlockReceipts](dev/rpc/eth_getBlockReceipts.md) + - [eth_getBlockTransactionCountByHash](dev/rpc/eth_getBlockTransactionCountByHash.md) + - [eth_getBlockTransactionCountByNumber](dev/rpc/eth_getBlockTransactionCountByNumber.md) + - [eth_getCode](dev/rpc/eth_getCode.md) + - [eth_getCodeByHash](dev/rpc/eth_getCodeByHash.md) + - [eth_getHeaderByHash](dev/rpc/eth_getHeaderByHash.md) + - [eth_getHeaderByNumber](dev/rpc/eth_getHeaderByNumber.md) + - [eth_getLogs](dev/rpc/eth_getLogs.md) + - [eth_getStorageAt](dev/rpc/eth_getStorageAt.md) + - [eth_getTransactionByHash](dev/rpc/eth_getTransactionByHash.md) + - [eth_getTransactionCount](dev/rpc/eth_getTransactionCount.md) + - [eth_getTransactionReceipt](dev/rpc/eth_getTransactionReceipt.md) + - [eth_getUncleByBlockHashAndIndex](dev/rpc/eth_getUncleByBlockHashAndIndex.md) + - [eth_getUncleByBlockNumberAndIndex](dev/rpc/eth_getUncleByBlockNumberAndIndex.md) + - [eth_getUncleCountByBlockHash](dev/rpc/eth_getUncleCountByBlockHash.md) + - [eth_getUncleCountByBlockNumber](dev/rpc/eth_getUncleCountByBlockNumber.md) + - [eth_getWithdrawalProof](dev/rpc/eth_getWithdrawalProof.md) + - [eth_maxPriorityFeePerGas](dev/rpc/eth_maxPriorityFeePerGas.md) + - [eth_protocolVersion](dev/rpc/eth_protocolVersion.md) + - [eth_sendRawTransaction](dev/rpc/eth_sendRawTransaction.md) + - [eth_sendRawTransactionSync](dev/rpc/eth_sendRawTransactionSync.md) + - [eth_subscribe](dev/rpc/eth_subscribe.md) + - [eth_syncing](dev/rpc/eth_syncing.md) + - [eth_uninstallFilter](dev/rpc/eth_uninstallFilter.md) + - [eth_unsubscribe](dev/rpc/eth_unsubscribe.md) + - [mega_getBlockWitness](dev/rpc/mega_getBlockWitness.md) + - [mega_getWithdrawalProof](dev/rpc/mega_getWithdrawalProof.md) + - [mega_outputAtBlock](dev/rpc/mega_outputAtBlock.md) + - [net_listening](dev/rpc/net_listening.md) + - [net_peerCount](dev/rpc/net_peerCount.md) + - [net_version](dev/rpc/net_version.md) + - [optimism_outputAtBlock](dev/rpc/optimism_outputAtBlock.md) + - [realtime_sendRawTransaction](dev/rpc/realtime_sendRawTransaction.md) + - [web3_clientVersion](dev/rpc/web3_clientVersion.md) + - [Error Codes](dev/rpc/error-codes.md) - [Transaction Execution](dev/execution/overview.md) - [Gas Model](dev/execution/gas-model.md) - [Resource Limits](dev/execution/resource-limits.md) diff --git a/docs/dev/AGENTS.md b/docs/dev/AGENTS.md index c1cd41d..bfcb505 100644 --- a/docs/dev/AGENTS.md +++ b/docs/dev/AGENTS.md @@ -156,8 +156,8 @@ Fold MegaETH-specific notes **inline** where they are relevant: Use a three-column table: `| Code | Cause | Fix |`. - **Cause** and **Fix** should be terse — sentence fragments, not full prose. -- Omit generic rate-limit errors (`-32005`) — those are covered by the [Error reference](read/rpc/error-codes.md). -- End with: `See also [Error reference](read/rpc/error-codes.md).` +- Omit generic rate-limit errors (`-32005`) — those are covered by the [Error reference](rpc/error-codes.md). +- End with: `See also [Error reference](rpc/error-codes.md).` ### Hex-encoded quantities diff --git a/docs/dev/overview.md b/docs/dev/overview.md index d7df4f5..6699fe7 100644 --- a/docs/dev/overview.md +++ b/docs/dev/overview.md @@ -68,6 +68,6 @@ See [Contracts & Tokens](send-tx/contracts.md#l1-contracts-ethereum) for all L1 - [EVM Differences](execution/overview.md) — what's different from Ethereum - [Gas Model](execution/gas-model.md) — how MegaETH's dual gas model works - [System Contracts](execution/system-contracts.md) — oracle, timestamp, and other system contracts -- [RPC Reference](read/overview.md) — JSON-RPC methods and error codes +- [RPC Reference](rpc/README.md) — JSON-RPC methods and error codes - [Realtime API](read/realtime-api.md) — WebSocket and real-time RPC extensions - [Onchain Payments](payments.md) — charge for APIs, content, or metered services onchain diff --git a/docs/dev/payments.md b/docs/dev/payments.md index ead6ebd..dcd3523 100644 --- a/docs/dev/payments.md +++ b/docs/dev/payments.md @@ -337,7 +337,7 @@ The repository also includes the escrow contract (`contract/`) and protocol sche - **Token.** The demo uses a testnet USD-style ERC-20 (USDm) as the payment asset across all five flows. - **Escrow.** The session flows use a `TempoStreamChannel`-style escrow deployed on MegaETH; the gasless variant adds Permit2 / EIP-3009 funding entry points so a relayer can fund on the payer's behalf. -- **Fast settlement.** Server-side settlement (gasless charge, channel `close`, relayed funding) is submitted via MegaETH's realtime transaction RPC, which returns a receipt synchronously instead of requiring a separate poll. See [`realtime_sendRawTransaction`](read/rpc/realtime_sendRawTransaction.md) and the [Realtime API](read/realtime-api.md). +- **Fast settlement.** Server-side settlement (gasless charge, channel `close`, relayed funding) is submitted via MegaETH's realtime transaction RPC, which returns a receipt synchronously instead of requiring a separate poll. See [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) and the [Realtime API](read/realtime-api.md). - **Gas.** Sponsored flows require a funded server key to pay gas. Estimate gas with `eth_estimateGas` against a MegaETH endpoint rather than computing it manually — see [Gas Estimation](send-tx/gas-estimation.md). ## Further reading diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 098440f..8356d1d 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -1,152 +1,7 @@ --- -description: How to query state and data from MegaETH — JSON-RPC methods, rate limiting, subscriptions, and real-time queries. +description: Entry point to the MegaETH JSON-RPC reference. --- # Read from MegaETH -## Realtime API - -Standard Ethereum JSON-RPC was designed for chains with multi-second block times. -On those chains, a one-second delay between execution and queryability is normal — you poll `eth_getTransactionReceipt`, wait for the next block, and eventually get your result. - -MegaETH produces [mini-blocks](../../mini-block.md) every ~10 milliseconds. -If the read API still operated on one-second EVM blocks, applications would wait 100× longer than necessary to see their results. -The Realtime API closes this gap: it queries against the most recent mini-block so that balances, receipts, logs, and state changes are visible within milliseconds of execution — not seconds. - -Standard methods like `eth_getBalance`, `eth_call`, and `eth_getTransactionReceipt` already reflect mini-block state automatically when called with `latest` or `pending`. -On top of that, MegaETH exposes two public extension paths for lower-latency workflows: - -- [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) — submit a transaction and get the receipt back in one call, no polling -- [`eth_subscribe`](rpc/eth_subscribe.md) — stream logs, state changes, mini-blocks, and block headers over WebSocket as they happen - -For use-case-oriented guidance (which method to use for what), see the [Realtime API](realtime-api.md) page. - -## Available Methods - -{% hint style="info" %} -The table below reflects the public MegaETH Mainnet endpoint as verified on July 24, 2026. -"Unavailable" includes methods recognized by the gateway but disabled or unimplemented upstream. -Managed providers may expose additional methods. -{% endhint %} - -| Method | Availability | Additional restrictions or behavior | -| ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | -| `debug_getHistoryTransactionCount` | Available | MegaETH-specific. | -| `debug_getRawHeader` | Available | | -| `debug_traceBlockByHash` | Available | Large responses are streamed. | -| `debug_traceBlockByNumber` | Available | Large responses are streamed. | -| `debug_traceCall` | Unavailable | The public endpoint returns `-32601`. | -| `debug_traceTransaction` | Available | Large responses are streamed. | -| `eth_accounts` | Available | Returns an empty array because the gateway does not manage user keys. | -| `eth_blockNumber` | Available | | -| `eth_call` | Available | Compute gas limited to 60,000,000. | -| `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | -| `eth_chainId` | Available | | -| `eth_createAccessList` | Available | Routed to the compute pool; no separate 60M compute override is added. | -| `eth_estimateGas` | Available | Uses an internal CPU-time limit; the source default is 0.5 seconds. | -| `eth_feeHistory` | Available | Block range limited to 256. | -| `eth_gasPrice` | Available | | -| `eth_getBalance` | Available | | -| `eth_getBlockByHash` | Available | | -| `eth_getBlockByNumber` | Available | | -| `eth_getBlockReceipts` | Available | | -| `eth_getBlockTransactionCountByHash` | Available | | -| `eth_getBlockTransactionCountByNumber` | Available | | -| `eth_getCode` | Available | | -| `eth_getCodeByHash` | Available | MegaETH-specific. | -| `eth_getFilterChanges` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getFilterLogs` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getHeaderByHash` | Available | MegaETH-specific. | -| `eth_getHeaderByNumber` | Available | MegaETH-specific. | -| `eth_getLogs` | Available | | -| `eth_getLogsWithCursor` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getStorageAt` | Available | | -| `eth_getTransactionByBlockHashAndIndex` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getTransactionByBlockNumberAndIndex` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getTransactionByHash` | Available | | -| `eth_getTransactionCount` | Available | | -| `eth_getTransactionReceipt` | Available | | -| `eth_getUncleByBlockHashAndIndex` | Available | Returns `null` for valid MegaETH blocks. | -| `eth_getUncleByBlockNumberAndIndex` | Available | Returns `null` for valid MegaETH blocks. | -| `eth_getUncleCountByBlockHash` | Available | Returns `0x0` for valid MegaETH blocks. | -| `eth_getUncleCountByBlockNumber` | Available | Returns `0x0` for valid MegaETH blocks. | -| `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | -| `eth_maxPriorityFeePerGas` | Available | | -| `eth_mining` | Unavailable | The node reports the method as unimplemented. | -| `eth_newBlockFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_newFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_newPendingTransactionFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_protocolVersion` | Available | Legacy compatibility method. | -| `eth_sendRawTransaction` | Available | | -| `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | -| `eth_subscribe` | WebSocket only | Supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`. | -| `eth_syncing` | Available | | -| `eth_uninstallFilter` | Available | Returns `false` when the filter ID does not exist. | -| `eth_unsubscribe` | WebSocket only | | -| `mega_getBlockWitness` | Available | MegaETH-specific. | -| `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | -| `mega_outputAtBlock` | Available | OP Stack output-root method. | -| `net_listening` | Available | | -| `net_peerCount` | Available | | -| `net_version` | Available | | -| `optimism_outputAtBlock` | Available | Alias of `mega_outputAtBlock`. | -| `realtime_sendRawTransaction` | Available | MegaETH-specific synchronous receipt method. | -| `trace_block` | Unavailable | The public endpoint returns `-32601`. | -| `trace_call` | Unavailable | The public endpoint returns `-32601`. | -| `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | -| `web3_clientVersion` | Available | | - -## Rate Limiting - -Read methods on the public RPC endpoint are rate-limited **per IP address** in **fixed 10-second windows**. -Each method belongs to one of four categories, and each category has its own request budget: - -| Category | Limit (per 10 s) | Methods | -| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | -| Instant | 2,000 | `eth_chainId`, `eth_blockNumber`, `net_version`, `eth_accounts`, `web3_clientVersion`, `eth_getBalance`, `eth_getStorageAt` | -| Simple | 500 | Block/transaction queries and all other read methods not listed in another category | -| Compute | 200 | `eth_call`, `eth_callMany`, `eth_estimateGas`, `eth_createAccessList`, `debug_trace*`, `trace_*` | -| IO-heavy | 200 | `eth_getLogs`, `eth_getBlockReceipts` | - -Additional notes: - -- Transaction submission methods (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) are not subject to these read rate limits. -- Cache hits still consume the method's per-category budget. -- `eth_callMany` consumes one Compute-category request per inner transaction, not one per HTTP request. -- A rate-limited request is rejected with HTTP `429` and RPC error `-32005` (`Rate limit exceeded`) — see [Error Codes](rpc/error-codes.md). Reduce request frequency, or use batching or WebSocket subscriptions to lower the request count. - -## Request Body Limits - -The public RPC endpoint caps the size of the request body, and the cap depends on the method being called: - -| Method class | Maximum body size | -| -------------------------------------------------------------------------------------------------------------- | ----------------- | -| Transaction submission (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) | 2.5 MiB | -| Large reads and simulations (`eth_call`, `eth_callMany`, `eth_createAccessList`, `eth_estimateGas`) | 1.5 MiB | -| All other methods | 128 KiB | - -The higher limits for simulation methods let you estimate gas for or simulate large contract deployments, whose initcode can exceed the 128 KiB default. -A request whose body exceeds the applicable limit is rejected with HTTP `413` and RPC error `-32099` (`payload too large`) — see [Error Codes](rpc/error-codes.md). - -## Response Caching - -The public RPC gateway may serve read methods from an internal server-side cache rather than forwarding every request to a node. -Eligibility and lifetime are method-specific: immutable block numbers and hashes can use longer-lived entries, while methods that follow the chain head either use a short-lived cache or bypass it. -Do not assume that two different methods or block tags have the same cache policy. - -Two headers on the response are relevant: - -- **`Cache-Control: no-store`** — every public response carries this header. - It is a directive to caches _downstream_ of the gateway (browsers, proxies, CDNs): do not store this response. - It does not mean the gateway itself computed the response from scratch — the gateway's internal cache is part of the origin, not a downstream cache, so serving from it does not conflict with `no-store`. -- **`X-Workers-Cache-Status`** — reports whether the gateway's internal cache was hit (`HIT`, `MISS`, or other [Cloudflare cache statuses](https://developers.cloudflare.com/cache/concepts/cache-responses/)). - Use it to understand where a response came from; it has no effect on correctness. - -Sending `Cache-Control: no-store` or `no-cache` as a _request_ header does not bypass the internal cache — request cache directives address intermediary caches, not the origin's own caching. -The gateway does not provide a request option that bypasses its internal cache. - -## Related Pages - -- [Realtime API](realtime-api.md) — use-case guide for streaming data and instant receipts -- [Error Codes](rpc/error-codes.md) — HTTP and RPC error codes with mitigations +See the [RPC Reference](../rpc/README.md) for supported methods, availability, rate limits, request limits, caching, and error codes. diff --git a/docs/dev/read/realtime-api.md b/docs/dev/read/realtime-api.md index 3e2d32c..94f8830 100644 --- a/docs/dev/read/realtime-api.md +++ b/docs/dev/read/realtime-api.md @@ -18,10 +18,10 @@ Additional functionality will be added based on feedback. ## Available Methods -| Method | What it does | Reference | -| ------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------- | -| [`eth_subscribe`](rpc/eth_subscribe.md) | Stream logs, state changes, mini-blocks, and block headers over WebSocket | [Full reference](rpc/eth_subscribe.md) | -| [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) | Submit a transaction and get the receipt back in one call — no polling | [Full reference](rpc/realtime_sendRawTransaction.md) | +| Method | What it does | Reference | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- | +| [`eth_subscribe`](../rpc/eth_subscribe.md) | Stream logs, state changes, mini-blocks, and block headers over WebSocket | [Full reference](../rpc/eth_subscribe.md) | +| [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md) | Submit a transaction and get the receipt back in one call — no polling | [Full reference](../rpc/realtime_sendRawTransaction.md) | The following standard Ethereum methods also return real-time results on MegaETH — they query against the latest mini-block automatically when called with `latest` or `pending`: @@ -44,7 +44,7 @@ The following standard Ethereum methods also return real-time results on MegaETH **Problem:** Your dapp submits a transaction and needs the receipt immediately — polling `eth_getTransactionReceipt` adds latency and complexity. -**Solution:** Use [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md). +**Solution:** Use [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md). It submits the transaction and waits for the receipt in a single round-trip. The node's default wait is 5 seconds; an explicit timeout is capped at 3 seconds by the public gateway. Drop-in replacement for `eth_sendRawTransaction`. @@ -53,7 +53,7 @@ Drop-in replacement for `eth_sendRawTransaction`. **Problem:** Your frontend needs to update in real time as swaps, transfers, or game actions happen on-chain. -**Solution:** Subscribe to [`logs`](rpc/eth_subscribe.md#logs) over WebSocket with `fromBlock` and `toBlock` set to `"pending"`. +**Solution:** Subscribe to [`logs`](../rpc/eth_subscribe.md#logs) over WebSocket with `fromBlock` and `toBlock` set to `"pending"`. Logs arrive within ~10ms of execution — fast enough for live trading dashboards, game UIs, and notification systems. Filter by contract address and topics to receive only the events you care about. @@ -61,14 +61,14 @@ Filter by contract address and topics to receive only the events you care about. **Problem:** You need to track balance or storage changes for specific accounts in real time (e.g., a liquidation bot watching collateral ratios). -**Solution:** Subscribe to [`stateChanges`](rpc/eth_subscribe.md#statechanges) with the account addresses you want to monitor. +**Solution:** Subscribe to [`stateChanges`](../rpc/eth_subscribe.md#statechanges) with the account addresses you want to monitor. Each notification includes the updated balance, nonce, and any storage slots that changed. ### Building a block explorer or indexer **Problem:** You need every transaction and receipt as soon as it's executed, not when the next EVM block is sealed. -**Solution:** Subscribe to [`miniBlocks`](rpc/eth_subscribe.md#miniblocks). +**Solution:** Subscribe to [`miniBlocks`](../rpc/eth_subscribe.md#miniblocks). Each notification contains the full set of transactions and receipts for that mini-block. ## How It Works @@ -94,4 +94,4 @@ At T+100ms, she sends 1 ETH to Bob — the transaction is packaged into a mini-b ## Related Pages - [Mini-Blocks](../../mini-block.md) — understanding the two block types -- [RPC Reference](overview.md) — full method availability table and rate limiting +- [RPC Reference](../rpc/README.md) — full method availability table and rate limiting diff --git a/docs/dev/read/rpc/README.md b/docs/dev/read/rpc/README.md deleted file mode 100644 index b71c9b4..0000000 --- a/docs/dev/read/rpc/README.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: "Complete reference for the 51 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." ---- - -# RPC Reference - -The public MegaETH gateway exposes 49 HTTP methods and two WebSocket subscription methods. -This reference is based on the gateway registry, node implementation, and public Mainnet behavior verified on July 24, 2026. - -Use the [availability table](../overview.md#available-methods) for methods that are disabled or unsupported on the public endpoint. -See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. - -## State and simulation - -- [`eth_accounts`](./eth_accounts.md) -- [`eth_call`](./eth_call.md) -- [`eth_callMany`](./eth_callMany.md) -- [`eth_createAccessList`](./eth_createAccessList.md) -- [`eth_estimateGas`](./eth_estimateGas.md) -- [`eth_getBalance`](./eth_getBalance.md) -- [`eth_getCode`](./eth_getCode.md) -- [`eth_getCodeByHash`](./eth_getCodeByHash.md) -- [`eth_getStorageAt`](./eth_getStorageAt.md) -- [`eth_getTransactionCount`](./eth_getTransactionCount.md) - -## Blocks, transactions, and receipts - -- [`eth_blockNumber`](./eth_blockNumber.md) -- [`eth_getBlockByHash`](./eth_getBlockByHash.md) -- [`eth_getBlockByNumber`](./eth_getBlockByNumber.md) -- [`eth_getBlockReceipts`](./eth_getBlockReceipts.md) -- [`eth_getBlockTransactionCountByHash`](./eth_getBlockTransactionCountByHash.md) -- [`eth_getBlockTransactionCountByNumber`](./eth_getBlockTransactionCountByNumber.md) -- [`eth_getHeaderByHash`](./eth_getHeaderByHash.md) -- [`eth_getHeaderByNumber`](./eth_getHeaderByNumber.md) -- [`eth_getTransactionByHash`](./eth_getTransactionByHash.md) -- [`eth_getTransactionReceipt`](./eth_getTransactionReceipt.md) -- [`eth_getUncleByBlockHashAndIndex`](./eth_getUncleByBlockHashAndIndex.md) -- [`eth_getUncleByBlockNumberAndIndex`](./eth_getUncleByBlockNumberAndIndex.md) -- [`eth_getUncleCountByBlockHash`](./eth_getUncleCountByBlockHash.md) -- [`eth_getUncleCountByBlockNumber`](./eth_getUncleCountByBlockNumber.md) -- [`eth_syncing`](./eth_syncing.md) - -## Logs and subscriptions - -- [`eth_getLogs`](./eth_getLogs.md) -- [`eth_subscribe`](./eth_subscribe.md) — WebSocket only -- [`eth_uninstallFilter`](./eth_uninstallFilter.md) -- [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only - -## Fees and transaction submission - -- [`eth_feeHistory`](./eth_feeHistory.md) -- [`eth_gasPrice`](./eth_gasPrice.md) -- [`eth_maxPriorityFeePerGas`](./eth_maxPriorityFeePerGas.md) -- [`eth_sendRawTransaction`](./eth_sendRawTransaction.md) -- [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) -- [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) - -## Debug methods - -- [`debug_getHistoryTransactionCount`](./debug_getHistoryTransactionCount.md) -- [`debug_getRawHeader`](./debug_getRawHeader.md) -- [`debug_traceBlockByHash`](./debug_traceBlockByHash.md) -- [`debug_traceBlockByNumber`](./debug_traceBlockByNumber.md) -- [`debug_traceTransaction`](./debug_traceTransaction.md) - -## MegaETH and OP Stack methods - -- [`eth_getWithdrawalProof`](./eth_getWithdrawalProof.md) -- [`mega_getBlockWitness`](./mega_getBlockWitness.md) -- [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md) -- [`mega_outputAtBlock`](./mega_outputAtBlock.md) -- [`optimism_outputAtBlock`](./optimism_outputAtBlock.md) - -## Network and client information - -- [`eth_chainId`](./eth_chainId.md) -- [`eth_protocolVersion`](./eth_protocolVersion.md) -- [`net_listening`](./net_listening.md) -- [`net_peerCount`](./net_peerCount.md) -- [`net_version`](./net_version.md) -- [`web3_clientVersion`](./web3_clientVersion.md) diff --git a/docs/dev/rpc/README.md b/docs/dev/rpc/README.md new file mode 100644 index 0000000..96f486c --- /dev/null +++ b/docs/dev/rpc/README.md @@ -0,0 +1,207 @@ +--- +description: "Complete reference for the 51 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." +--- + +# RPC Reference + +The public MegaETH gateway exposes 49 HTTP methods and two WebSocket subscription methods. +See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. + +## Available Methods + +{% hint style="info" %} +The table below reflects the public MegaETH Mainnet endpoint. +"Unavailable" includes methods recognized by the gateway but disabled or unimplemented upstream. +Managed providers may expose additional methods. +{% endhint %} + +| Method | Availability | Additional restrictions or behavior | +| ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | +| `debug_getHistoryTransactionCount` | Available | MegaETH-specific. | +| `debug_getRawHeader` | Available | | +| `debug_traceBlockByHash` | Available | Large responses are streamed. | +| `debug_traceBlockByNumber` | Available | Large responses are streamed. | +| `debug_traceCall` | Unavailable | The public endpoint returns `-32601`. | +| `debug_traceTransaction` | Available | Large responses are streamed. | +| `eth_accounts` | Available | Returns an empty array because the gateway does not manage user keys. | +| `eth_blockNumber` | Available | | +| `eth_call` | Available | Compute gas limited to 60,000,000. | +| `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | +| `eth_chainId` | Available | | +| `eth_createAccessList` | Available | Routed to the compute pool; no separate 60M compute override is added. | +| `eth_estimateGas` | Available | Uses an internal CPU-time limit; the source default is 0.5 seconds. | +| `eth_feeHistory` | Available | Block range limited to 256. | +| `eth_gasPrice` | Available | | +| `eth_getBalance` | Available | | +| `eth_getBlockByHash` | Available | | +| `eth_getBlockByNumber` | Available | | +| `eth_getBlockReceipts` | Available | | +| `eth_getBlockTransactionCountByHash` | Available | | +| `eth_getBlockTransactionCountByNumber` | Available | | +| `eth_getCode` | Available | | +| `eth_getCodeByHash` | Available | MegaETH-specific. | +| `eth_getFilterChanges` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getFilterLogs` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getHeaderByHash` | Available | MegaETH-specific. | +| `eth_getHeaderByNumber` | Available | MegaETH-specific. | +| `eth_getLogs` | Available | | +| `eth_getLogsWithCursor` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getStorageAt` | Available | | +| `eth_getTransactionByBlockHashAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByBlockNumberAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByHash` | Available | | +| `eth_getTransactionCount` | Available | | +| `eth_getTransactionReceipt` | Available | | +| `eth_getUncleByBlockHashAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleByBlockNumberAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockHash` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockNumber` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | +| `eth_maxPriorityFeePerGas` | Available | | +| `eth_mining` | Unavailable | The node reports the method as unimplemented. | +| `eth_newBlockFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newPendingTransactionFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_protocolVersion` | Available | Legacy compatibility method. | +| `eth_sendRawTransaction` | Available | | +| `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | +| `eth_subscribe` | WebSocket only | Supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`. | +| `eth_syncing` | Available | | +| `eth_uninstallFilter` | Available | Returns `false` when the filter ID does not exist. | +| `eth_unsubscribe` | WebSocket only | | +| `mega_getBlockWitness` | Available | MegaETH-specific. | +| `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | +| `mega_outputAtBlock` | Available | OP Stack output-root method. | +| `net_listening` | Available | | +| `net_peerCount` | Available | | +| `net_version` | Available | | +| `optimism_outputAtBlock` | Available | Alias of `mega_outputAtBlock`. | +| `realtime_sendRawTransaction` | Available | MegaETH-specific synchronous receipt method. | +| `trace_block` | Unavailable | The public endpoint returns `-32601`. | +| `trace_call` | Unavailable | The public endpoint returns `-32601`. | +| `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | +| `web3_clientVersion` | Available | | + +## Rate Limiting + +Read methods on the public RPC endpoint are rate-limited **per IP address** in **fixed 10-second windows**. +Each method belongs to one of four categories, and each category has its own request budget: + +| Category | Limit (per 10 s) | Methods | +| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | +| Instant | 2,000 | `eth_chainId`, `eth_blockNumber`, `net_version`, `eth_accounts`, `web3_clientVersion`, `eth_getBalance`, `eth_getStorageAt` | +| Simple | 500 | Block/transaction queries and all other read methods not listed in another category | +| Compute | 200 | `eth_call`, `eth_callMany`, `eth_estimateGas`, `eth_createAccessList`, `debug_trace*`, `trace_*` | +| IO-heavy | 200 | `eth_getLogs`, `eth_getBlockReceipts` | + +Additional notes: + +- Transaction submission methods (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) are not subject to these read rate limits. +- Cache hits still consume the method's per-category budget. +- `eth_callMany` consumes one Compute-category request per inner transaction, not one per HTTP request. +- A rate-limited request is rejected with HTTP `429` and RPC error `-32005` (`Rate limit exceeded`) — see [Error Codes](./error-codes.md). Reduce request frequency, or use batching or WebSocket subscriptions to lower the request count. + +## Request Body Limits + +The public RPC endpoint caps the size of the request body, and the cap depends on the method being called: + +| Method class | Maximum body size | +| -------------------------------------------------------------------------------------------------------------- | ----------------- | +| Transaction submission (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) | 2.5 MiB | +| Large reads and simulations (`eth_call`, `eth_callMany`, `eth_createAccessList`, `eth_estimateGas`) | 1.5 MiB | +| All other methods | 128 KiB | + +The higher limits for simulation methods let you estimate gas for or simulate large contract deployments, whose initcode can exceed the 128 KiB default. +A request whose body exceeds the applicable limit is rejected with HTTP `413` and RPC error `-32099` (`payload too large`) — see [Error Codes](./error-codes.md). + +## Response Caching + +The public RPC gateway may serve read methods from an internal server-side cache rather than forwarding every request to a node. +Eligibility and lifetime are method-specific: immutable block numbers and hashes can use longer-lived entries, while methods that follow the chain head either use a short-lived cache or bypass it. +Do not assume that two different methods or block tags have the same cache policy. + +Two headers on the response are relevant: + +- **`Cache-Control: no-store`** — every public response carries this header. + It is a directive to caches _downstream_ of the gateway (browsers, proxies, CDNs): do not store this response. + It does not mean the gateway itself computed the response from scratch — the gateway's internal cache is part of the origin, not a downstream cache, so serving from it does not conflict with `no-store`. +- **`X-Workers-Cache-Status`** — reports whether the gateway's internal cache was hit (`HIT`, `MISS`, or other [Cloudflare cache statuses](https://developers.cloudflare.com/cache/concepts/cache-responses/)). + Use it to understand where a response came from; it has no effect on correctness. + +Sending `Cache-Control: no-store` or `no-cache` as a _request_ header does not bypass the internal cache — request cache directives address intermediary caches, not the origin's own caching. +The gateway does not provide a request option that bypasses its internal cache. + +## Method Reference + +## State and simulation + +- [`eth_accounts`](./eth_accounts.md) +- [`eth_call`](./eth_call.md) +- [`eth_callMany`](./eth_callMany.md) +- [`eth_createAccessList`](./eth_createAccessList.md) +- [`eth_estimateGas`](./eth_estimateGas.md) +- [`eth_getBalance`](./eth_getBalance.md) +- [`eth_getCode`](./eth_getCode.md) +- [`eth_getCodeByHash`](./eth_getCodeByHash.md) +- [`eth_getStorageAt`](./eth_getStorageAt.md) +- [`eth_getTransactionCount`](./eth_getTransactionCount.md) + +## Blocks, transactions, and receipts + +- [`eth_blockNumber`](./eth_blockNumber.md) +- [`eth_getBlockByHash`](./eth_getBlockByHash.md) +- [`eth_getBlockByNumber`](./eth_getBlockByNumber.md) +- [`eth_getBlockReceipts`](./eth_getBlockReceipts.md) +- [`eth_getBlockTransactionCountByHash`](./eth_getBlockTransactionCountByHash.md) +- [`eth_getBlockTransactionCountByNumber`](./eth_getBlockTransactionCountByNumber.md) +- [`eth_getHeaderByHash`](./eth_getHeaderByHash.md) +- [`eth_getHeaderByNumber`](./eth_getHeaderByNumber.md) +- [`eth_getTransactionByHash`](./eth_getTransactionByHash.md) +- [`eth_getTransactionReceipt`](./eth_getTransactionReceipt.md) +- [`eth_getUncleByBlockHashAndIndex`](./eth_getUncleByBlockHashAndIndex.md) +- [`eth_getUncleByBlockNumberAndIndex`](./eth_getUncleByBlockNumberAndIndex.md) +- [`eth_getUncleCountByBlockHash`](./eth_getUncleCountByBlockHash.md) +- [`eth_getUncleCountByBlockNumber`](./eth_getUncleCountByBlockNumber.md) +- [`eth_syncing`](./eth_syncing.md) + +## Logs and subscriptions + +- [`eth_getLogs`](./eth_getLogs.md) +- [`eth_subscribe`](./eth_subscribe.md) — WebSocket only +- [`eth_uninstallFilter`](./eth_uninstallFilter.md) +- [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only + +## Fees and transaction submission + +- [`eth_feeHistory`](./eth_feeHistory.md) +- [`eth_gasPrice`](./eth_gasPrice.md) +- [`eth_maxPriorityFeePerGas`](./eth_maxPriorityFeePerGas.md) +- [`eth_sendRawTransaction`](./eth_sendRawTransaction.md) +- [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) +- [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) + +## Debug methods + +- [`debug_getHistoryTransactionCount`](./debug_getHistoryTransactionCount.md) +- [`debug_getRawHeader`](./debug_getRawHeader.md) +- [`debug_traceBlockByHash`](./debug_traceBlockByHash.md) +- [`debug_traceBlockByNumber`](./debug_traceBlockByNumber.md) +- [`debug_traceTransaction`](./debug_traceTransaction.md) + +## MegaETH and OP Stack methods + +- [`eth_getWithdrawalProof`](./eth_getWithdrawalProof.md) +- [`mega_getBlockWitness`](./mega_getBlockWitness.md) +- [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md) +- [`mega_outputAtBlock`](./mega_outputAtBlock.md) +- [`optimism_outputAtBlock`](./optimism_outputAtBlock.md) + +## Network and client information + +- [`eth_chainId`](./eth_chainId.md) +- [`eth_protocolVersion`](./eth_protocolVersion.md) +- [`net_listening`](./net_listening.md) +- [`net_peerCount`](./net_peerCount.md) +- [`net_version`](./net_version.md) +- [`web3_clientVersion`](./web3_clientVersion.md) diff --git a/docs/dev/read/rpc/debug_getHistoryTransactionCount.md b/docs/dev/rpc/debug_getHistoryTransactionCount.md similarity index 100% rename from docs/dev/read/rpc/debug_getHistoryTransactionCount.md rename to docs/dev/rpc/debug_getHistoryTransactionCount.md diff --git a/docs/dev/read/rpc/debug_getRawHeader.md b/docs/dev/rpc/debug_getRawHeader.md similarity index 100% rename from docs/dev/read/rpc/debug_getRawHeader.md rename to docs/dev/rpc/debug_getRawHeader.md diff --git a/docs/dev/read/rpc/debug_traceBlockByHash.md b/docs/dev/rpc/debug_traceBlockByHash.md similarity index 100% rename from docs/dev/read/rpc/debug_traceBlockByHash.md rename to docs/dev/rpc/debug_traceBlockByHash.md diff --git a/docs/dev/read/rpc/debug_traceBlockByNumber.md b/docs/dev/rpc/debug_traceBlockByNumber.md similarity index 100% rename from docs/dev/read/rpc/debug_traceBlockByNumber.md rename to docs/dev/rpc/debug_traceBlockByNumber.md diff --git a/docs/dev/read/rpc/debug_traceTransaction.md b/docs/dev/rpc/debug_traceTransaction.md similarity index 100% rename from docs/dev/read/rpc/debug_traceTransaction.md rename to docs/dev/rpc/debug_traceTransaction.md diff --git a/docs/dev/read/rpc/error-codes.md b/docs/dev/rpc/error-codes.md similarity index 83% rename from docs/dev/read/rpc/error-codes.md rename to docs/dev/rpc/error-codes.md index f2f4249..be86226 100644 --- a/docs/dev/read/rpc/error-codes.md +++ b/docs/dev/rpc/error-codes.md @@ -4,21 +4,21 @@ description: MegaETH JSON-RPC error codes — HTTP status codes, RPC error codes # Error Codes -| HTTP Error Code | RPC Error Code | Error Message | Explanation | Mitigation | -| --------------- | -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| 400 | -32700 | `parse error` | The request body contains invalid JSON. | Check the request format and ensure valid JSON syntax. | -| 413 | -32099 | `payload too large` | The request body exceeds the size limit for the method being called. | Stay within the body-size limit for the method class. See [Request Body Limits](../overview.md#request-body-limits). | -| 403 | -32601 | `rpc method is not whitelisted` | The requested RPC method is not allowed by the proxy configuration. | Use only whitelisted RPC methods. Contact MegaETH if you need access to additional methods. | -| 200 | -32001 | `Resource not found` | The requested block, header, or other resource could not be resolved. | Verify the block number or hash and retry. | -| 200 | 4444 | `pruned history unavailable` | The node no longer retains the requested historical state or data. | Use a newer block or an endpoint with the required historical-state retention. | -| 400 | -32019 | `block is out of range` | The requested block number is out of range. | Check the block number and ensure it's within the valid range. | -| 500 | -32020 | `backend response too large` | The backend response is too large. | Reduce the scope of the request or contact MegaETH for assistance. | -| 429 | -32005 | `Rate limit exceeded` | The request exceeds the rate limit for its method category. | Reduce request frequency, or use batching or WebSocket subscriptions. See [Rate Limiting](../overview.md#rate-limiting). | -| 200 | -32000 | `permanent error forwarding request context deadline exceeded` | The API proxy cannot connect to the backend RPC server. | Pause for a while and retry. Notify MegaETH if the error persists. | +| HTTP Error Code | RPC Error Code | Error Message | Explanation | Mitigation | +| --------------- | -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| 400 | -32700 | `parse error` | The request body contains invalid JSON. | Check the request format and ensure valid JSON syntax. | +| 413 | -32099 | `payload too large` | The request body exceeds the size limit for the method being called. | Stay within the body-size limit for the method class. See [Request Body Limits](./README.md#request-body-limits). | +| 403 | -32601 | `rpc method is not whitelisted` | The requested RPC method is not allowed by the proxy configuration. | Use only whitelisted RPC methods. Contact MegaETH if you need access to additional methods. | +| 200 | -32001 | `Resource not found` | The requested block, header, or other resource could not be resolved. | Verify the block number or hash and retry. | +| 200 | 4444 | `pruned history unavailable` | The node no longer retains the requested historical state or data. | Use a newer block or an endpoint with the required historical-state retention. | +| 400 | -32019 | `block is out of range` | The requested block number is out of range. | Check the block number and ensure it's within the valid range. | +| 500 | -32020 | `backend response too large` | The backend response is too large. | Reduce the scope of the request or contact MegaETH for assistance. | +| 429 | -32005 | `Rate limit exceeded` | The request exceeds the rate limit for its method category. | Reduce request frequency, or use batching or WebSocket subscriptions. See [Rate Limiting](./README.md#rate-limiting). | +| 200 | -32000 | `permanent error forwarding request context deadline exceeded` | The API proxy cannot connect to the backend RPC server. | Pause for a while and retry. Notify MegaETH if the error persists. | Older references to `-32021` or `-32022` refer to the previous rate-limit codes. The public gateway now returns `-32005` for rate-limited requests. ## Related Pages -- [RPC Reference](../overview.md) — full method availability table +- [RPC Reference](./README.md) — full method availability table diff --git a/docs/dev/read/rpc/eth_accounts.md b/docs/dev/rpc/eth_accounts.md similarity index 100% rename from docs/dev/read/rpc/eth_accounts.md rename to docs/dev/rpc/eth_accounts.md diff --git a/docs/dev/read/rpc/eth_blockNumber.md b/docs/dev/rpc/eth_blockNumber.md similarity index 100% rename from docs/dev/read/rpc/eth_blockNumber.md rename to docs/dev/rpc/eth_blockNumber.md diff --git a/docs/dev/read/rpc/eth_call.md b/docs/dev/rpc/eth_call.md similarity index 100% rename from docs/dev/read/rpc/eth_call.md rename to docs/dev/rpc/eth_call.md diff --git a/docs/dev/read/rpc/eth_callMany.md b/docs/dev/rpc/eth_callMany.md similarity index 100% rename from docs/dev/read/rpc/eth_callMany.md rename to docs/dev/rpc/eth_callMany.md diff --git a/docs/dev/read/rpc/eth_chainId.md b/docs/dev/rpc/eth_chainId.md similarity index 100% rename from docs/dev/read/rpc/eth_chainId.md rename to docs/dev/rpc/eth_chainId.md diff --git a/docs/dev/read/rpc/eth_createAccessList.md b/docs/dev/rpc/eth_createAccessList.md similarity index 100% rename from docs/dev/read/rpc/eth_createAccessList.md rename to docs/dev/rpc/eth_createAccessList.md diff --git a/docs/dev/read/rpc/eth_estimateGas.md b/docs/dev/rpc/eth_estimateGas.md similarity index 100% rename from docs/dev/read/rpc/eth_estimateGas.md rename to docs/dev/rpc/eth_estimateGas.md diff --git a/docs/dev/read/rpc/eth_feeHistory.md b/docs/dev/rpc/eth_feeHistory.md similarity index 100% rename from docs/dev/read/rpc/eth_feeHistory.md rename to docs/dev/rpc/eth_feeHistory.md diff --git a/docs/dev/read/rpc/eth_gasPrice.md b/docs/dev/rpc/eth_gasPrice.md similarity index 100% rename from docs/dev/read/rpc/eth_gasPrice.md rename to docs/dev/rpc/eth_gasPrice.md diff --git a/docs/dev/read/rpc/eth_getBalance.md b/docs/dev/rpc/eth_getBalance.md similarity index 100% rename from docs/dev/read/rpc/eth_getBalance.md rename to docs/dev/rpc/eth_getBalance.md diff --git a/docs/dev/read/rpc/eth_getBlockByHash.md b/docs/dev/rpc/eth_getBlockByHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getBlockByHash.md rename to docs/dev/rpc/eth_getBlockByHash.md diff --git a/docs/dev/read/rpc/eth_getBlockByNumber.md b/docs/dev/rpc/eth_getBlockByNumber.md similarity index 100% rename from docs/dev/read/rpc/eth_getBlockByNumber.md rename to docs/dev/rpc/eth_getBlockByNumber.md diff --git a/docs/dev/read/rpc/eth_getBlockReceipts.md b/docs/dev/rpc/eth_getBlockReceipts.md similarity index 100% rename from docs/dev/read/rpc/eth_getBlockReceipts.md rename to docs/dev/rpc/eth_getBlockReceipts.md diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/rpc/eth_getBlockTransactionCountByHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getBlockTransactionCountByHash.md rename to docs/dev/rpc/eth_getBlockTransactionCountByHash.md diff --git a/docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/rpc/eth_getBlockTransactionCountByNumber.md similarity index 100% rename from docs/dev/read/rpc/eth_getBlockTransactionCountByNumber.md rename to docs/dev/rpc/eth_getBlockTransactionCountByNumber.md diff --git a/docs/dev/read/rpc/eth_getCode.md b/docs/dev/rpc/eth_getCode.md similarity index 100% rename from docs/dev/read/rpc/eth_getCode.md rename to docs/dev/rpc/eth_getCode.md diff --git a/docs/dev/read/rpc/eth_getCodeByHash.md b/docs/dev/rpc/eth_getCodeByHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getCodeByHash.md rename to docs/dev/rpc/eth_getCodeByHash.md diff --git a/docs/dev/read/rpc/eth_getHeaderByHash.md b/docs/dev/rpc/eth_getHeaderByHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getHeaderByHash.md rename to docs/dev/rpc/eth_getHeaderByHash.md diff --git a/docs/dev/read/rpc/eth_getHeaderByNumber.md b/docs/dev/rpc/eth_getHeaderByNumber.md similarity index 100% rename from docs/dev/read/rpc/eth_getHeaderByNumber.md rename to docs/dev/rpc/eth_getHeaderByNumber.md diff --git a/docs/dev/read/rpc/eth_getLogs.md b/docs/dev/rpc/eth_getLogs.md similarity index 100% rename from docs/dev/read/rpc/eth_getLogs.md rename to docs/dev/rpc/eth_getLogs.md diff --git a/docs/dev/read/rpc/eth_getStorageAt.md b/docs/dev/rpc/eth_getStorageAt.md similarity index 100% rename from docs/dev/read/rpc/eth_getStorageAt.md rename to docs/dev/rpc/eth_getStorageAt.md diff --git a/docs/dev/read/rpc/eth_getTransactionByHash.md b/docs/dev/rpc/eth_getTransactionByHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getTransactionByHash.md rename to docs/dev/rpc/eth_getTransactionByHash.md diff --git a/docs/dev/read/rpc/eth_getTransactionCount.md b/docs/dev/rpc/eth_getTransactionCount.md similarity index 100% rename from docs/dev/read/rpc/eth_getTransactionCount.md rename to docs/dev/rpc/eth_getTransactionCount.md diff --git a/docs/dev/read/rpc/eth_getTransactionReceipt.md b/docs/dev/rpc/eth_getTransactionReceipt.md similarity index 100% rename from docs/dev/read/rpc/eth_getTransactionReceipt.md rename to docs/dev/rpc/eth_getTransactionReceipt.md diff --git a/docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/rpc/eth_getUncleByBlockHashAndIndex.md similarity index 100% rename from docs/dev/read/rpc/eth_getUncleByBlockHashAndIndex.md rename to docs/dev/rpc/eth_getUncleByBlockHashAndIndex.md diff --git a/docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/rpc/eth_getUncleByBlockNumberAndIndex.md similarity index 100% rename from docs/dev/read/rpc/eth_getUncleByBlockNumberAndIndex.md rename to docs/dev/rpc/eth_getUncleByBlockNumberAndIndex.md diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/rpc/eth_getUncleCountByBlockHash.md similarity index 100% rename from docs/dev/read/rpc/eth_getUncleCountByBlockHash.md rename to docs/dev/rpc/eth_getUncleCountByBlockHash.md diff --git a/docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/rpc/eth_getUncleCountByBlockNumber.md similarity index 100% rename from docs/dev/read/rpc/eth_getUncleCountByBlockNumber.md rename to docs/dev/rpc/eth_getUncleCountByBlockNumber.md diff --git a/docs/dev/read/rpc/eth_getWithdrawalProof.md b/docs/dev/rpc/eth_getWithdrawalProof.md similarity index 100% rename from docs/dev/read/rpc/eth_getWithdrawalProof.md rename to docs/dev/rpc/eth_getWithdrawalProof.md diff --git a/docs/dev/read/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/rpc/eth_maxPriorityFeePerGas.md similarity index 100% rename from docs/dev/read/rpc/eth_maxPriorityFeePerGas.md rename to docs/dev/rpc/eth_maxPriorityFeePerGas.md diff --git a/docs/dev/read/rpc/eth_protocolVersion.md b/docs/dev/rpc/eth_protocolVersion.md similarity index 100% rename from docs/dev/read/rpc/eth_protocolVersion.md rename to docs/dev/rpc/eth_protocolVersion.md diff --git a/docs/dev/read/rpc/eth_sendRawTransaction.md b/docs/dev/rpc/eth_sendRawTransaction.md similarity index 100% rename from docs/dev/read/rpc/eth_sendRawTransaction.md rename to docs/dev/rpc/eth_sendRawTransaction.md diff --git a/docs/dev/read/rpc/eth_sendRawTransactionSync.md b/docs/dev/rpc/eth_sendRawTransactionSync.md similarity index 100% rename from docs/dev/read/rpc/eth_sendRawTransactionSync.md rename to docs/dev/rpc/eth_sendRawTransactionSync.md diff --git a/docs/dev/read/rpc/eth_subscribe.md b/docs/dev/rpc/eth_subscribe.md similarity index 100% rename from docs/dev/read/rpc/eth_subscribe.md rename to docs/dev/rpc/eth_subscribe.md diff --git a/docs/dev/read/rpc/eth_syncing.md b/docs/dev/rpc/eth_syncing.md similarity index 100% rename from docs/dev/read/rpc/eth_syncing.md rename to docs/dev/rpc/eth_syncing.md diff --git a/docs/dev/read/rpc/eth_uninstallFilter.md b/docs/dev/rpc/eth_uninstallFilter.md similarity index 100% rename from docs/dev/read/rpc/eth_uninstallFilter.md rename to docs/dev/rpc/eth_uninstallFilter.md diff --git a/docs/dev/read/rpc/eth_unsubscribe.md b/docs/dev/rpc/eth_unsubscribe.md similarity index 100% rename from docs/dev/read/rpc/eth_unsubscribe.md rename to docs/dev/rpc/eth_unsubscribe.md diff --git a/docs/dev/read/rpc/mega_getBlockWitness.md b/docs/dev/rpc/mega_getBlockWitness.md similarity index 100% rename from docs/dev/read/rpc/mega_getBlockWitness.md rename to docs/dev/rpc/mega_getBlockWitness.md diff --git a/docs/dev/read/rpc/mega_getWithdrawalProof.md b/docs/dev/rpc/mega_getWithdrawalProof.md similarity index 100% rename from docs/dev/read/rpc/mega_getWithdrawalProof.md rename to docs/dev/rpc/mega_getWithdrawalProof.md diff --git a/docs/dev/read/rpc/mega_outputAtBlock.md b/docs/dev/rpc/mega_outputAtBlock.md similarity index 100% rename from docs/dev/read/rpc/mega_outputAtBlock.md rename to docs/dev/rpc/mega_outputAtBlock.md diff --git a/docs/dev/read/rpc/net_listening.md b/docs/dev/rpc/net_listening.md similarity index 100% rename from docs/dev/read/rpc/net_listening.md rename to docs/dev/rpc/net_listening.md diff --git a/docs/dev/read/rpc/net_peerCount.md b/docs/dev/rpc/net_peerCount.md similarity index 100% rename from docs/dev/read/rpc/net_peerCount.md rename to docs/dev/rpc/net_peerCount.md diff --git a/docs/dev/read/rpc/net_version.md b/docs/dev/rpc/net_version.md similarity index 100% rename from docs/dev/read/rpc/net_version.md rename to docs/dev/rpc/net_version.md diff --git a/docs/dev/read/rpc/optimism_outputAtBlock.md b/docs/dev/rpc/optimism_outputAtBlock.md similarity index 100% rename from docs/dev/read/rpc/optimism_outputAtBlock.md rename to docs/dev/rpc/optimism_outputAtBlock.md diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/rpc/realtime_sendRawTransaction.md similarity index 100% rename from docs/dev/read/rpc/realtime_sendRawTransaction.md rename to docs/dev/rpc/realtime_sendRawTransaction.md diff --git a/docs/dev/read/rpc/web3_clientVersion.md b/docs/dev/rpc/web3_clientVersion.md similarity index 100% rename from docs/dev/read/rpc/web3_clientVersion.md rename to docs/dev/rpc/web3_clientVersion.md diff --git a/docs/dev/send-tx/debugging.md b/docs/dev/send-tx/debugging.md index 2a885c0..38129a1 100644 --- a/docs/dev/send-tx/debugging.md +++ b/docs/dev/send-tx/debugging.md @@ -16,8 +16,8 @@ It does not support `debug_traceCall`; use [`mega-evme`](#simulating-a-new-trans The following methods are supported: -- **[`debug_traceTransaction`](../read/rpc/debug_traceTransaction.md)** — trace an already-mined transaction by hash -- **[`debug_traceBlockByNumber`](../read/rpc/debug_traceBlockByNumber.md)** / **[`debug_traceBlockByHash`](../read/rpc/debug_traceBlockByHash.md)** — trace all transactions in a block +- **[`debug_traceTransaction`](../rpc/debug_traceTransaction.md)** — trace an already-mined transaction by hash +- **[`debug_traceBlockByNumber`](../rpc/debug_traceBlockByNumber.md)** / **[`debug_traceBlockByHash`](../rpc/debug_traceBlockByHash.md)** — trace all transactions in a block ### Supported Tracers @@ -205,7 +205,7 @@ See [Volatile Data Access](../execution/volatile-data.md) for the full list of t - [Gas Estimation](gas-estimation.md) — estimate gas correctly and avoid common errors - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding - [Gas Model](../execution/gas-model.md) — how compute gas and storage gas work -- [RPC Reference](../read/overview.md) — method availability and restrictions +- [RPC Reference](../rpc/README.md) — method availability and restrictions - [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas - [Gas Detention (spec)](https://docs.megaeth.com/spec/megaevm/gas-detention) — compute gas cap triggered by volatile data access - [mega-evme](https://docs.megaeth.com/mega-evme) — full command reference, configuration, and cookbook diff --git a/docs/dev/send-tx/gas-estimation.md b/docs/dev/send-tx/gas-estimation.md index 9ff5e7f..c614a46 100644 --- a/docs/dev/send-tx/gas-estimation.md +++ b/docs/dev/send-tx/gas-estimation.md @@ -80,7 +80,7 @@ There are two workarounds: Estimating gas for a large contract deployment sends the full initcode in the request body. To accommodate this, the public RPC endpoint allows `eth_call`, `eth_callMany`, `eth_createAccessList`, and `eth_estimateGas` bodies up to **1.5 MiB** — well above the 128 KiB limit applied to ordinary read methods. A request that exceeds this limit is rejected with HTTP `413` / `-32099` (`payload too large`). -See [Request Body Limits](../read/overview.md#request-body-limits) for the full breakdown. +See [Request Body Limits](../rpc/README.md#request-body-limits) for the full breakdown. ## Toolchain Configuration @@ -151,7 +151,7 @@ If you need to debug which dimension caused a failure, see [Debugging Transactio - [Gas Model](../execution/gas-model.md) — how compute gas, storage gas, and the bucket multiplier work - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding -- [RPC Reference](../read/overview.md) — method availability and restrictions +- [RPC Reference](../rpc/README.md) — method availability and restrictions - [Developer FAQ](../faq.md) — `eth_estimateGas` gas cap, block gas limit - [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas - [Resource Limits (spec)](https://docs.megaeth.com/spec/megaevm/resource-limits) — per-transaction and per-block limit enforcement diff --git a/docs/dev/send-tx/overview.md b/docs/dev/send-tx/overview.md index 0f14b83..22fd806 100644 --- a/docs/dev/send-tx/overview.md +++ b/docs/dev/send-tx/overview.md @@ -121,7 +121,7 @@ curl -s https://mainnet.megaeth.com/rpc \ Returns the full transaction receipt directly. The node waits up to 5 seconds by default; the public gateway caps an explicit timeout at 3,000 milliseconds and returns `-32000 realtime transaction expired` if the deadline elapses first. -See [`realtime_sendRawTransaction`](../read/rpc/realtime_sendRawTransaction.md) for the full reference. +See [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md) for the full reference. {% endtab %} {% endtabs %} diff --git a/docs/mini-block.md b/docs/mini-block.md index 1e02fb8..dbf01d8 100644 --- a/docs/mini-block.md +++ b/docs/mini-block.md @@ -79,7 +79,7 @@ A signed mini-block is a binding commitment: if the sequencer ever sealed an EVM The signing key is registered onchain in the [SequencerRegistry](https://docs.megaeth.com/spec/system-contracts/sequencer-registry) system contract at `0x6342000000000000000000000000000000000006`, introduced in Rex5. The key can be rotated by scheduling a change in the registry; rotations take effect at an EVM block boundary, and the full change history remains queryable onchain. -The signature is a standard secp256k1 ECDSA signature over `keccak256(rlp(header))`, where the header is the following eight fields of the [`miniBlocks` subscription payload](dev/read/rpc/eth_subscribe.md#miniblocks), RLP-encoded in this order: +The signature is a standard secp256k1 ECDSA signature over `keccak256(rlp(header))`, where the header is the following eight fields of the [`miniBlocks` subscription payload](dev/rpc/eth_subscribe.md#miniblocks), RLP-encoded in this order: | # | Payload field | Type | | --- | ---------------------- | ------------ | @@ -104,7 +104,7 @@ Mini-blocks produced before Rex5 are unsigned — the `signature` field is absen To verify a mini-block, rebuild the header hash, recover the signer from the signature, and compare it against the sequencer key registered onchain. -The example below uses [viem](https://viem.sh) and takes a notification payload `mb` exactly as delivered by the [`miniBlocks` subscription](dev/read/rpc/eth_subscribe.md#miniblocks). +The example below uses [viem](https://viem.sh) and takes a notification payload `mb` exactly as delivered by the [`miniBlocks` subscription](dev/rpc/eth_subscribe.md#miniblocks). ```typescript import { @@ -195,6 +195,6 @@ Each notification delivers the mini-block's transactions, receipts, and state ch - [Architecture](architecture.md) — how transactions flow through the MegaETH network - [Realtime API](dev/read/realtime-api.md) — subscribe to mini-blocks and get execution results with minimum latency -- [eth_subscribe](dev/read/rpc/eth_subscribe.md) — full reference of the `miniBlocks` subscription payload +- [eth_subscribe](dev/rpc/eth_subscribe.md) — full reference of the `miniBlocks` subscription payload - [High-Precision Timestamp](dev/execution/system-contracts.md#high-precision-timestamp) — microsecond timestamps available within mini-blocks - [SequencerRegistry (spec)](https://docs.megaeth.com/spec/system-contracts/sequencer-registry) — onchain registry of the sequencer signing key From f157be6584a1929b89a2df4e406aba7b4289755f Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 17:32:46 +0800 Subject: [PATCH 11/13] docs: complete JSON-RPC documentation --- .gitbook.yaml | 108 ++++---- docs/SUMMARY.md | 111 +++++---- docs/dev/faq.md | 2 + docs/dev/overview.md | 2 +- docs/dev/payments.md | 2 +- docs/dev/read/overview.md | 2 +- docs/dev/read/realtime-api.md | 19 +- docs/dev/rpc/README.md | 211 +--------------- docs/dev/rpc/error-codes.md | 128 ++++++++-- docs/dev/rpc/eth_subscribe.md | 118 --------- docs/dev/rpc/json-rpc-basics.md | 117 +++++++++ docs/dev/rpc/operations-and-limits.md | 104 ++++++++ docs/dev/rpc/quickstart.md | 64 +++++ docs/dev/rpc/reference/README.md | 158 ++++++++++++ .../debug_getHistoryTransactionCount.md | 2 +- .../rpc/{ => reference}/debug_getRawHeader.md | 0 .../{ => reference}/debug_traceBlockByHash.md | 0 .../debug_traceBlockByNumber.md | 0 .../{ => reference}/debug_traceTransaction.md | 0 docs/dev/rpc/{ => reference}/eth_accounts.md | 2 +- .../rpc/{ => reference}/eth_blockNumber.md | 2 +- docs/dev/rpc/{ => reference}/eth_call.md | 2 +- docs/dev/rpc/{ => reference}/eth_callMany.md | 0 docs/dev/rpc/{ => reference}/eth_chainId.md | 2 +- .../{ => reference}/eth_createAccessList.md | 2 +- .../rpc/{ => reference}/eth_estimateGas.md | 2 +- .../dev/rpc/{ => reference}/eth_feeHistory.md | 2 +- docs/dev/rpc/{ => reference}/eth_gasPrice.md | 2 +- .../dev/rpc/{ => reference}/eth_getBalance.md | 2 +- .../rpc/{ => reference}/eth_getBlockByHash.md | 2 +- .../{ => reference}/eth_getBlockByNumber.md | 2 +- .../{ => reference}/eth_getBlockReceipts.md | 2 +- .../eth_getBlockTransactionCountByHash.md | 2 +- .../eth_getBlockTransactionCountByNumber.md | 2 +- docs/dev/rpc/{ => reference}/eth_getCode.md | 2 +- .../rpc/{ => reference}/eth_getCodeByHash.md | 2 +- .../{ => reference}/eth_getHeaderByHash.md | 2 +- .../{ => reference}/eth_getHeaderByNumber.md | 2 +- docs/dev/rpc/{ => reference}/eth_getLogs.md | 2 +- .../rpc/{ => reference}/eth_getStorageAt.md | 2 +- .../eth_getTransactionByHash.md | 2 +- .../eth_getTransactionCount.md | 2 +- .../eth_getTransactionReceipt.md | 2 +- .../eth_getUncleByBlockHashAndIndex.md | 0 .../eth_getUncleByBlockNumberAndIndex.md | 0 .../eth_getUncleCountByBlockHash.md | 0 .../eth_getUncleCountByBlockNumber.md | 0 .../{ => reference}/eth_getWithdrawalProof.md | 2 +- .../eth_maxPriorityFeePerGas.md | 2 +- .../{ => reference}/eth_protocolVersion.md | 0 .../{ => reference}/eth_sendRawTransaction.md | 2 +- .../eth_sendRawTransactionSync.md | 2 +- docs/dev/rpc/reference/eth_subscribe.md | 235 ++++++++++++++++++ docs/dev/rpc/{ => reference}/eth_syncing.md | 2 +- .../{ => reference}/eth_uninstallFilter.md | 0 .../rpc/{ => reference}/eth_unsubscribe.md | 2 +- .../{ => reference}/mega_getBlockWitness.md | 2 +- .../mega_getWithdrawalProof.md | 2 +- .../rpc/{ => reference}/mega_outputAtBlock.md | 2 +- docs/dev/rpc/{ => reference}/net_listening.md | 2 +- docs/dev/rpc/{ => reference}/net_peerCount.md | 2 +- docs/dev/rpc/{ => reference}/net_version.md | 2 +- .../{ => reference}/optimism_outputAtBlock.md | 2 +- .../realtime_sendRawTransaction.md | 2 +- .../rpc/{ => reference}/web3_clientVersion.md | 2 +- docs/dev/rpc/types.md | 100 ++++++++ docs/dev/send-tx/debugging.md | 6 +- docs/dev/send-tx/gas-estimation.md | 4 +- docs/dev/send-tx/overview.md | 2 +- docs/mini-block.md | 6 +- 70 files changed, 1076 insertions(+), 501 deletions(-) delete mode 100644 docs/dev/rpc/eth_subscribe.md create mode 100644 docs/dev/rpc/json-rpc-basics.md create mode 100644 docs/dev/rpc/operations-and-limits.md create mode 100644 docs/dev/rpc/quickstart.md create mode 100644 docs/dev/rpc/reference/README.md rename docs/dev/rpc/{ => reference}/debug_getHistoryTransactionCount.md (98%) rename docs/dev/rpc/{ => reference}/debug_getRawHeader.md (100%) rename docs/dev/rpc/{ => reference}/debug_traceBlockByHash.md (100%) rename docs/dev/rpc/{ => reference}/debug_traceBlockByNumber.md (100%) rename docs/dev/rpc/{ => reference}/debug_traceTransaction.md (100%) rename docs/dev/rpc/{ => reference}/eth_accounts.md (98%) rename docs/dev/rpc/{ => reference}/eth_blockNumber.md (98%) rename docs/dev/rpc/{ => reference}/eth_call.md (99%) rename docs/dev/rpc/{ => reference}/eth_callMany.md (100%) rename docs/dev/rpc/{ => reference}/eth_chainId.md (98%) rename docs/dev/rpc/{ => reference}/eth_createAccessList.md (99%) rename docs/dev/rpc/{ => reference}/eth_estimateGas.md (99%) rename docs/dev/rpc/{ => reference}/eth_feeHistory.md (98%) rename docs/dev/rpc/{ => reference}/eth_gasPrice.md (98%) rename docs/dev/rpc/{ => reference}/eth_getBalance.md (98%) rename docs/dev/rpc/{ => reference}/eth_getBlockByHash.md (98%) rename docs/dev/rpc/{ => reference}/eth_getBlockByNumber.md (98%) rename docs/dev/rpc/{ => reference}/eth_getBlockReceipts.md (99%) rename docs/dev/rpc/{ => reference}/eth_getBlockTransactionCountByHash.md (98%) rename docs/dev/rpc/{ => reference}/eth_getBlockTransactionCountByNumber.md (98%) rename docs/dev/rpc/{ => reference}/eth_getCode.md (98%) rename docs/dev/rpc/{ => reference}/eth_getCodeByHash.md (98%) rename docs/dev/rpc/{ => reference}/eth_getHeaderByHash.md (98%) rename docs/dev/rpc/{ => reference}/eth_getHeaderByNumber.md (98%) rename docs/dev/rpc/{ => reference}/eth_getLogs.md (99%) rename docs/dev/rpc/{ => reference}/eth_getStorageAt.md (98%) rename docs/dev/rpc/{ => reference}/eth_getTransactionByHash.md (98%) rename docs/dev/rpc/{ => reference}/eth_getTransactionCount.md (98%) rename docs/dev/rpc/{ => reference}/eth_getTransactionReceipt.md (98%) rename docs/dev/rpc/{ => reference}/eth_getUncleByBlockHashAndIndex.md (100%) rename docs/dev/rpc/{ => reference}/eth_getUncleByBlockNumberAndIndex.md (100%) rename docs/dev/rpc/{ => reference}/eth_getUncleCountByBlockHash.md (100%) rename docs/dev/rpc/{ => reference}/eth_getUncleCountByBlockNumber.md (100%) rename docs/dev/rpc/{ => reference}/eth_getWithdrawalProof.md (98%) rename docs/dev/rpc/{ => reference}/eth_maxPriorityFeePerGas.md (98%) rename docs/dev/rpc/{ => reference}/eth_protocolVersion.md (100%) rename docs/dev/rpc/{ => reference}/eth_sendRawTransaction.md (98%) rename docs/dev/rpc/{ => reference}/eth_sendRawTransactionSync.md (99%) create mode 100644 docs/dev/rpc/reference/eth_subscribe.md rename docs/dev/rpc/{ => reference}/eth_syncing.md (98%) rename docs/dev/rpc/{ => reference}/eth_uninstallFilter.md (100%) rename docs/dev/rpc/{ => reference}/eth_unsubscribe.md (98%) rename docs/dev/rpc/{ => reference}/mega_getBlockWitness.md (98%) rename docs/dev/rpc/{ => reference}/mega_getWithdrawalProof.md (98%) rename docs/dev/rpc/{ => reference}/mega_outputAtBlock.md (99%) rename docs/dev/rpc/{ => reference}/net_listening.md (98%) rename docs/dev/rpc/{ => reference}/net_peerCount.md (98%) rename docs/dev/rpc/{ => reference}/net_version.md (98%) rename docs/dev/rpc/{ => reference}/optimism_outputAtBlock.md (98%) rename docs/dev/rpc/{ => reference}/realtime_sendRawTransaction.md (99%) rename docs/dev/rpc/{ => reference}/web3_clientVersion.md (98%) create mode 100644 docs/dev/rpc/types.md diff --git a/.gitbook.yaml b/.gitbook.yaml index 3ddc55a..b415578 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -5,58 +5,58 @@ structure: summary: SUMMARY.md redirects: - dev/read/rpc: dev/rpc/README.md - dev/read/rpc/debug_getHistoryTransactionCount: dev/rpc/debug_getHistoryTransactionCount.md - dev/read/rpc/debug_getRawHeader: dev/rpc/debug_getRawHeader.md - dev/read/rpc/debug_traceBlockByHash: dev/rpc/debug_traceBlockByHash.md - dev/read/rpc/debug_traceBlockByNumber: dev/rpc/debug_traceBlockByNumber.md - dev/read/rpc/debug_traceTransaction: dev/rpc/debug_traceTransaction.md + dev/read/rpc: dev/rpc/reference/README.md + dev/read/rpc/debug_getHistoryTransactionCount: dev/rpc/reference/debug_getHistoryTransactionCount.md + dev/read/rpc/debug_getRawHeader: dev/rpc/reference/debug_getRawHeader.md + dev/read/rpc/debug_traceBlockByHash: dev/rpc/reference/debug_traceBlockByHash.md + dev/read/rpc/debug_traceBlockByNumber: dev/rpc/reference/debug_traceBlockByNumber.md + dev/read/rpc/debug_traceTransaction: dev/rpc/reference/debug_traceTransaction.md dev/read/rpc/error-codes: dev/rpc/error-codes.md - dev/read/rpc/eth_accounts: dev/rpc/eth_accounts.md - dev/read/rpc/eth_blockNumber: dev/rpc/eth_blockNumber.md - dev/read/rpc/eth_call: dev/rpc/eth_call.md - dev/read/rpc/eth_callAfter: dev/rpc/README.md#available-methods - dev/read/rpc/eth_callMany: dev/rpc/eth_callMany.md - dev/read/rpc/eth_chainId: dev/rpc/eth_chainId.md - dev/read/rpc/eth_createAccessList: dev/rpc/eth_createAccessList.md - dev/read/rpc/eth_estimateGas: dev/rpc/eth_estimateGas.md - dev/read/rpc/eth_feeHistory: dev/rpc/eth_feeHistory.md - dev/read/rpc/eth_gasPrice: dev/rpc/eth_gasPrice.md - dev/read/rpc/eth_getBalance: dev/rpc/eth_getBalance.md - dev/read/rpc/eth_getBlockByHash: dev/rpc/eth_getBlockByHash.md - dev/read/rpc/eth_getBlockByNumber: dev/rpc/eth_getBlockByNumber.md - dev/read/rpc/eth_getBlockReceipts: dev/rpc/eth_getBlockReceipts.md - dev/read/rpc/eth_getBlockTransactionCountByHash: dev/rpc/eth_getBlockTransactionCountByHash.md - dev/read/rpc/eth_getBlockTransactionCountByNumber: dev/rpc/eth_getBlockTransactionCountByNumber.md - dev/read/rpc/eth_getCode: dev/rpc/eth_getCode.md - dev/read/rpc/eth_getCodeByHash: dev/rpc/eth_getCodeByHash.md - dev/read/rpc/eth_getHeaderByHash: dev/rpc/eth_getHeaderByHash.md - dev/read/rpc/eth_getHeaderByNumber: dev/rpc/eth_getHeaderByNumber.md - dev/read/rpc/eth_getLogs: dev/rpc/eth_getLogs.md - dev/read/rpc/eth_getLogsWithCursor: dev/rpc/README.md#available-methods - dev/read/rpc/eth_getStorageAt: dev/rpc/eth_getStorageAt.md - dev/read/rpc/eth_getTransactionByHash: dev/rpc/eth_getTransactionByHash.md - dev/read/rpc/eth_getTransactionCount: dev/rpc/eth_getTransactionCount.md - dev/read/rpc/eth_getTransactionReceipt: dev/rpc/eth_getTransactionReceipt.md - dev/read/rpc/eth_getUncleByBlockHashAndIndex: dev/rpc/eth_getUncleByBlockHashAndIndex.md - dev/read/rpc/eth_getUncleByBlockNumberAndIndex: dev/rpc/eth_getUncleByBlockNumberAndIndex.md - dev/read/rpc/eth_getUncleCountByBlockHash: dev/rpc/eth_getUncleCountByBlockHash.md - dev/read/rpc/eth_getUncleCountByBlockNumber: dev/rpc/eth_getUncleCountByBlockNumber.md - dev/read/rpc/eth_getWithdrawalProof: dev/rpc/eth_getWithdrawalProof.md - dev/read/rpc/eth_maxPriorityFeePerGas: dev/rpc/eth_maxPriorityFeePerGas.md - dev/read/rpc/eth_protocolVersion: dev/rpc/eth_protocolVersion.md - dev/read/rpc/eth_sendRawTransaction: dev/rpc/eth_sendRawTransaction.md - dev/read/rpc/eth_sendRawTransactionSync: dev/rpc/eth_sendRawTransactionSync.md - dev/read/rpc/eth_subscribe: dev/rpc/eth_subscribe.md - dev/read/rpc/eth_syncing: dev/rpc/eth_syncing.md - dev/read/rpc/eth_uninstallFilter: dev/rpc/eth_uninstallFilter.md - dev/read/rpc/eth_unsubscribe: dev/rpc/eth_unsubscribe.md - dev/read/rpc/mega_getBlockWitness: dev/rpc/mega_getBlockWitness.md - dev/read/rpc/mega_getWithdrawalProof: dev/rpc/mega_getWithdrawalProof.md - dev/read/rpc/mega_outputAtBlock: dev/rpc/mega_outputAtBlock.md - dev/read/rpc/net_listening: dev/rpc/net_listening.md - dev/read/rpc/net_peerCount: dev/rpc/net_peerCount.md - dev/read/rpc/net_version: dev/rpc/net_version.md - dev/read/rpc/optimism_outputAtBlock: dev/rpc/optimism_outputAtBlock.md - dev/read/rpc/realtime_sendRawTransaction: dev/rpc/realtime_sendRawTransaction.md - dev/read/rpc/web3_clientVersion: dev/rpc/web3_clientVersion.md + dev/read/rpc/eth_accounts: dev/rpc/reference/eth_accounts.md + dev/read/rpc/eth_blockNumber: dev/rpc/reference/eth_blockNumber.md + dev/read/rpc/eth_call: dev/rpc/reference/eth_call.md + dev/read/rpc/eth_callAfter: dev/rpc/reference/README.md#available-methods + dev/read/rpc/eth_callMany: dev/rpc/reference/eth_callMany.md + dev/read/rpc/eth_chainId: dev/rpc/reference/eth_chainId.md + dev/read/rpc/eth_createAccessList: dev/rpc/reference/eth_createAccessList.md + dev/read/rpc/eth_estimateGas: dev/rpc/reference/eth_estimateGas.md + dev/read/rpc/eth_feeHistory: dev/rpc/reference/eth_feeHistory.md + dev/read/rpc/eth_gasPrice: dev/rpc/reference/eth_gasPrice.md + dev/read/rpc/eth_getBalance: dev/rpc/reference/eth_getBalance.md + dev/read/rpc/eth_getBlockByHash: dev/rpc/reference/eth_getBlockByHash.md + dev/read/rpc/eth_getBlockByNumber: dev/rpc/reference/eth_getBlockByNumber.md + dev/read/rpc/eth_getBlockReceipts: dev/rpc/reference/eth_getBlockReceipts.md + dev/read/rpc/eth_getBlockTransactionCountByHash: dev/rpc/reference/eth_getBlockTransactionCountByHash.md + dev/read/rpc/eth_getBlockTransactionCountByNumber: dev/rpc/reference/eth_getBlockTransactionCountByNumber.md + dev/read/rpc/eth_getCode: dev/rpc/reference/eth_getCode.md + dev/read/rpc/eth_getCodeByHash: dev/rpc/reference/eth_getCodeByHash.md + dev/read/rpc/eth_getHeaderByHash: dev/rpc/reference/eth_getHeaderByHash.md + dev/read/rpc/eth_getHeaderByNumber: dev/rpc/reference/eth_getHeaderByNumber.md + dev/read/rpc/eth_getLogs: dev/rpc/reference/eth_getLogs.md + dev/read/rpc/eth_getLogsWithCursor: dev/rpc/reference/README.md#available-methods + dev/read/rpc/eth_getStorageAt: dev/rpc/reference/eth_getStorageAt.md + dev/read/rpc/eth_getTransactionByHash: dev/rpc/reference/eth_getTransactionByHash.md + dev/read/rpc/eth_getTransactionCount: dev/rpc/reference/eth_getTransactionCount.md + dev/read/rpc/eth_getTransactionReceipt: dev/rpc/reference/eth_getTransactionReceipt.md + dev/read/rpc/eth_getUncleByBlockHashAndIndex: dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md + dev/read/rpc/eth_getUncleByBlockNumberAndIndex: dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md + dev/read/rpc/eth_getUncleCountByBlockHash: dev/rpc/reference/eth_getUncleCountByBlockHash.md + dev/read/rpc/eth_getUncleCountByBlockNumber: dev/rpc/reference/eth_getUncleCountByBlockNumber.md + dev/read/rpc/eth_getWithdrawalProof: dev/rpc/reference/eth_getWithdrawalProof.md + dev/read/rpc/eth_maxPriorityFeePerGas: dev/rpc/reference/eth_maxPriorityFeePerGas.md + dev/read/rpc/eth_protocolVersion: dev/rpc/reference/eth_protocolVersion.md + dev/read/rpc/eth_sendRawTransaction: dev/rpc/reference/eth_sendRawTransaction.md + dev/read/rpc/eth_sendRawTransactionSync: dev/rpc/reference/eth_sendRawTransactionSync.md + dev/read/rpc/eth_subscribe: dev/rpc/reference/eth_subscribe.md + dev/read/rpc/eth_syncing: dev/rpc/reference/eth_syncing.md + dev/read/rpc/eth_uninstallFilter: dev/rpc/reference/eth_uninstallFilter.md + dev/read/rpc/eth_unsubscribe: dev/rpc/reference/eth_unsubscribe.md + dev/read/rpc/mega_getBlockWitness: dev/rpc/reference/mega_getBlockWitness.md + dev/read/rpc/mega_getWithdrawalProof: dev/rpc/reference/mega_getWithdrawalProof.md + dev/read/rpc/mega_outputAtBlock: dev/rpc/reference/mega_outputAtBlock.md + dev/read/rpc/net_listening: dev/rpc/reference/net_listening.md + dev/read/rpc/net_peerCount: dev/rpc/reference/net_peerCount.md + dev/read/rpc/net_version: dev/rpc/reference/net_version.md + dev/read/rpc/optimism_outputAtBlock: dev/rpc/reference/optimism_outputAtBlock.md + dev/read/rpc/realtime_sendRawTransaction: dev/rpc/reference/realtime_sendRawTransaction.md + dev/read/rpc/web3_clientVersion: dev/rpc/reference/web3_clientVersion.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index d3952f5..4db0bb2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -25,59 +25,6 @@ - [Force Inclusion — Foundry](dev/send-tx/force-inclusion.md) - [Read from MegaETH](dev/read/overview.md) - [Realtime API](dev/read/realtime-api.md) -- [RPC Reference](dev/rpc/README.md) - - [debug_getHistoryTransactionCount](dev/rpc/debug_getHistoryTransactionCount.md) - - [debug_getRawHeader](dev/rpc/debug_getRawHeader.md) - - [debug_traceBlockByHash](dev/rpc/debug_traceBlockByHash.md) - - [debug_traceBlockByNumber](dev/rpc/debug_traceBlockByNumber.md) - - [debug_traceTransaction](dev/rpc/debug_traceTransaction.md) - - [eth_accounts](dev/rpc/eth_accounts.md) - - [eth_blockNumber](dev/rpc/eth_blockNumber.md) - - [eth_call](dev/rpc/eth_call.md) - - [eth_callMany](dev/rpc/eth_callMany.md) - - [eth_chainId](dev/rpc/eth_chainId.md) - - [eth_createAccessList](dev/rpc/eth_createAccessList.md) - - [eth_estimateGas](dev/rpc/eth_estimateGas.md) - - [eth_feeHistory](dev/rpc/eth_feeHistory.md) - - [eth_gasPrice](dev/rpc/eth_gasPrice.md) - - [eth_getBalance](dev/rpc/eth_getBalance.md) - - [eth_getBlockByHash](dev/rpc/eth_getBlockByHash.md) - - [eth_getBlockByNumber](dev/rpc/eth_getBlockByNumber.md) - - [eth_getBlockReceipts](dev/rpc/eth_getBlockReceipts.md) - - [eth_getBlockTransactionCountByHash](dev/rpc/eth_getBlockTransactionCountByHash.md) - - [eth_getBlockTransactionCountByNumber](dev/rpc/eth_getBlockTransactionCountByNumber.md) - - [eth_getCode](dev/rpc/eth_getCode.md) - - [eth_getCodeByHash](dev/rpc/eth_getCodeByHash.md) - - [eth_getHeaderByHash](dev/rpc/eth_getHeaderByHash.md) - - [eth_getHeaderByNumber](dev/rpc/eth_getHeaderByNumber.md) - - [eth_getLogs](dev/rpc/eth_getLogs.md) - - [eth_getStorageAt](dev/rpc/eth_getStorageAt.md) - - [eth_getTransactionByHash](dev/rpc/eth_getTransactionByHash.md) - - [eth_getTransactionCount](dev/rpc/eth_getTransactionCount.md) - - [eth_getTransactionReceipt](dev/rpc/eth_getTransactionReceipt.md) - - [eth_getUncleByBlockHashAndIndex](dev/rpc/eth_getUncleByBlockHashAndIndex.md) - - [eth_getUncleByBlockNumberAndIndex](dev/rpc/eth_getUncleByBlockNumberAndIndex.md) - - [eth_getUncleCountByBlockHash](dev/rpc/eth_getUncleCountByBlockHash.md) - - [eth_getUncleCountByBlockNumber](dev/rpc/eth_getUncleCountByBlockNumber.md) - - [eth_getWithdrawalProof](dev/rpc/eth_getWithdrawalProof.md) - - [eth_maxPriorityFeePerGas](dev/rpc/eth_maxPriorityFeePerGas.md) - - [eth_protocolVersion](dev/rpc/eth_protocolVersion.md) - - [eth_sendRawTransaction](dev/rpc/eth_sendRawTransaction.md) - - [eth_sendRawTransactionSync](dev/rpc/eth_sendRawTransactionSync.md) - - [eth_subscribe](dev/rpc/eth_subscribe.md) - - [eth_syncing](dev/rpc/eth_syncing.md) - - [eth_uninstallFilter](dev/rpc/eth_uninstallFilter.md) - - [eth_unsubscribe](dev/rpc/eth_unsubscribe.md) - - [mega_getBlockWitness](dev/rpc/mega_getBlockWitness.md) - - [mega_getWithdrawalProof](dev/rpc/mega_getWithdrawalProof.md) - - [mega_outputAtBlock](dev/rpc/mega_outputAtBlock.md) - - [net_listening](dev/rpc/net_listening.md) - - [net_peerCount](dev/rpc/net_peerCount.md) - - [net_version](dev/rpc/net_version.md) - - [optimism_outputAtBlock](dev/rpc/optimism_outputAtBlock.md) - - [realtime_sendRawTransaction](dev/rpc/realtime_sendRawTransaction.md) - - [web3_clientVersion](dev/rpc/web3_clientVersion.md) - - [Error Codes](dev/rpc/error-codes.md) - [Transaction Execution](dev/execution/overview.md) - [Gas Model](dev/execution/gas-model.md) - [Resource Limits](dev/execution/resource-limits.md) @@ -87,6 +34,64 @@ - [Tooling & Infrastructure](dev/tooling.md) - [Verifiable Randomness (VRF)](dev/vrf.md) - [Onchain Payments](dev/payments.md) +- [JSON-RPC](dev/rpc/README.md) + - [Quickstart](dev/rpc/quickstart.md) + - [JSON-RPC basics](dev/rpc/json-rpc-basics.md) + - [Type reference](dev/rpc/types.md) + - [Error reference](dev/rpc/error-codes.md) + - [Operations and limits](dev/rpc/operations-and-limits.md) + - [RPC Reference](dev/rpc/reference/README.md) + - [debug_getHistoryTransactionCount](dev/rpc/reference/debug_getHistoryTransactionCount.md) + - [debug_getRawHeader](dev/rpc/reference/debug_getRawHeader.md) + - [debug_traceBlockByHash](dev/rpc/reference/debug_traceBlockByHash.md) + - [debug_traceBlockByNumber](dev/rpc/reference/debug_traceBlockByNumber.md) + - [debug_traceTransaction](dev/rpc/reference/debug_traceTransaction.md) + - [eth_accounts](dev/rpc/reference/eth_accounts.md) + - [eth_blockNumber](dev/rpc/reference/eth_blockNumber.md) + - [eth_call](dev/rpc/reference/eth_call.md) + - [eth_callMany](dev/rpc/reference/eth_callMany.md) + - [eth_chainId](dev/rpc/reference/eth_chainId.md) + - [eth_createAccessList](dev/rpc/reference/eth_createAccessList.md) + - [eth_estimateGas](dev/rpc/reference/eth_estimateGas.md) + - [eth_feeHistory](dev/rpc/reference/eth_feeHistory.md) + - [eth_gasPrice](dev/rpc/reference/eth_gasPrice.md) + - [eth_getBalance](dev/rpc/reference/eth_getBalance.md) + - [eth_getBlockByHash](dev/rpc/reference/eth_getBlockByHash.md) + - [eth_getBlockByNumber](dev/rpc/reference/eth_getBlockByNumber.md) + - [eth_getBlockReceipts](dev/rpc/reference/eth_getBlockReceipts.md) + - [eth_getBlockTransactionCountByHash](dev/rpc/reference/eth_getBlockTransactionCountByHash.md) + - [eth_getBlockTransactionCountByNumber](dev/rpc/reference/eth_getBlockTransactionCountByNumber.md) + - [eth_getCode](dev/rpc/reference/eth_getCode.md) + - [eth_getCodeByHash](dev/rpc/reference/eth_getCodeByHash.md) + - [eth_getHeaderByHash](dev/rpc/reference/eth_getHeaderByHash.md) + - [eth_getHeaderByNumber](dev/rpc/reference/eth_getHeaderByNumber.md) + - [eth_getLogs](dev/rpc/reference/eth_getLogs.md) + - [eth_getStorageAt](dev/rpc/reference/eth_getStorageAt.md) + - [eth_getTransactionByHash](dev/rpc/reference/eth_getTransactionByHash.md) + - [eth_getTransactionCount](dev/rpc/reference/eth_getTransactionCount.md) + - [eth_getTransactionReceipt](dev/rpc/reference/eth_getTransactionReceipt.md) + - [eth_getUncleByBlockHashAndIndex](dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md) + - [eth_getUncleByBlockNumberAndIndex](dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md) + - [eth_getUncleCountByBlockHash](dev/rpc/reference/eth_getUncleCountByBlockHash.md) + - [eth_getUncleCountByBlockNumber](dev/rpc/reference/eth_getUncleCountByBlockNumber.md) + - [eth_getWithdrawalProof](dev/rpc/reference/eth_getWithdrawalProof.md) + - [eth_maxPriorityFeePerGas](dev/rpc/reference/eth_maxPriorityFeePerGas.md) + - [eth_protocolVersion](dev/rpc/reference/eth_protocolVersion.md) + - [eth_sendRawTransaction](dev/rpc/reference/eth_sendRawTransaction.md) + - [eth_sendRawTransactionSync](dev/rpc/reference/eth_sendRawTransactionSync.md) + - [eth_subscribe](dev/rpc/reference/eth_subscribe.md) + - [eth_syncing](dev/rpc/reference/eth_syncing.md) + - [eth_uninstallFilter](dev/rpc/reference/eth_uninstallFilter.md) + - [eth_unsubscribe](dev/rpc/reference/eth_unsubscribe.md) + - [mega_getBlockWitness](dev/rpc/reference/mega_getBlockWitness.md) + - [mega_getWithdrawalProof](dev/rpc/reference/mega_getWithdrawalProof.md) + - [mega_outputAtBlock](dev/rpc/reference/mega_outputAtBlock.md) + - [net_listening](dev/rpc/reference/net_listening.md) + - [net_peerCount](dev/rpc/reference/net_peerCount.md) + - [net_version](dev/rpc/reference/net_version.md) + - [optimism_outputAtBlock](dev/rpc/reference/optimism_outputAtBlock.md) + - [realtime_sendRawTransaction](dev/rpc/reference/realtime_sendRawTransaction.md) + - [web3_clientVersion](dev/rpc/reference/web3_clientVersion.md) - [Developer FAQ](dev/faq.md) ## Node Operation diff --git a/docs/dev/faq.md b/docs/dev/faq.md index 16857f7..1f55909 100644 --- a/docs/dev/faq.md +++ b/docs/dev/faq.md @@ -162,11 +162,13 @@ The public WebSocket endpoint supports the following methods: - `eth_subscribe` - `eth_unsubscribe` - `eth_sendRawTransaction` +- `eth_sendRawTransactionSync` - `realtime_sendRawTransaction` - `eth_chainId` WebSocket connections are rate-limited to 5 messages per second per connection. Send `eth_chainId` at least once every 30 seconds to keep the connection alive — idle connections may be closed by the server. +See [Operations and limits](rpc/operations-and-limits.md#websocket-limits) for connection, subscription, filter, and message-size limits. ### Can I set up my own RPC node? diff --git a/docs/dev/overview.md b/docs/dev/overview.md index 6699fe7..284ad2a 100644 --- a/docs/dev/overview.md +++ b/docs/dev/overview.md @@ -68,6 +68,6 @@ See [Contracts & Tokens](send-tx/contracts.md#l1-contracts-ethereum) for all L1 - [EVM Differences](execution/overview.md) — what's different from Ethereum - [Gas Model](execution/gas-model.md) — how MegaETH's dual gas model works - [System Contracts](execution/system-contracts.md) — oracle, timestamp, and other system contracts -- [RPC Reference](rpc/README.md) — JSON-RPC methods and error codes +- [JSON-RPC](rpc/README.md) — protocol guidance, limits, errors, and RPC methods - [Realtime API](read/realtime-api.md) — WebSocket and real-time RPC extensions - [Onchain Payments](payments.md) — charge for APIs, content, or metered services onchain diff --git a/docs/dev/payments.md b/docs/dev/payments.md index dcd3523..d91d2d2 100644 --- a/docs/dev/payments.md +++ b/docs/dev/payments.md @@ -337,7 +337,7 @@ The repository also includes the escrow contract (`contract/`) and protocol sche - **Token.** The demo uses a testnet USD-style ERC-20 (USDm) as the payment asset across all five flows. - **Escrow.** The session flows use a `TempoStreamChannel`-style escrow deployed on MegaETH; the gasless variant adds Permit2 / EIP-3009 funding entry points so a relayer can fund on the payer's behalf. -- **Fast settlement.** Server-side settlement (gasless charge, channel `close`, relayed funding) is submitted via MegaETH's realtime transaction RPC, which returns a receipt synchronously instead of requiring a separate poll. See [`realtime_sendRawTransaction`](rpc/realtime_sendRawTransaction.md) and the [Realtime API](read/realtime-api.md). +- **Fast settlement.** Server-side settlement (gasless charge, channel `close`, relayed funding) is submitted via MegaETH's realtime transaction RPC, which returns a receipt synchronously instead of requiring a separate poll. See [`realtime_sendRawTransaction`](rpc/reference/realtime_sendRawTransaction.md) and the [Realtime API](read/realtime-api.md). - **Gas.** Sponsored flows require a funded server key to pay gas. Estimate gas with `eth_estimateGas` against a MegaETH endpoint rather than computing it manually — see [Gas Estimation](send-tx/gas-estimation.md). ## Further reading diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index 8356d1d..d9b5eff 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -4,4 +4,4 @@ description: Entry point to the MegaETH JSON-RPC reference. # Read from MegaETH -See the [RPC Reference](../rpc/README.md) for supported methods, availability, rate limits, request limits, caching, and error codes. +See [JSON-RPC](../rpc/README.md) for shared guidance and the complete RPC method reference. diff --git a/docs/dev/read/realtime-api.md b/docs/dev/read/realtime-api.md index 94f8830..153eade 100644 --- a/docs/dev/read/realtime-api.md +++ b/docs/dev/read/realtime-api.md @@ -18,10 +18,10 @@ Additional functionality will be added based on feedback. ## Available Methods -| Method | What it does | Reference | -| ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- | -| [`eth_subscribe`](../rpc/eth_subscribe.md) | Stream logs, state changes, mini-blocks, and block headers over WebSocket | [Full reference](../rpc/eth_subscribe.md) | -| [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md) | Submit a transaction and get the receipt back in one call — no polling | [Full reference](../rpc/realtime_sendRawTransaction.md) | +| Method | What it does | Reference | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | +| [`eth_subscribe`](../rpc/reference/eth_subscribe.md) | Stream headers, logs, pending transactions, sync status, mini-blocks, and state changes over WebSocket | [Full reference](../rpc/reference/eth_subscribe.md) | +| [`realtime_sendRawTransaction`](../rpc/reference/realtime_sendRawTransaction.md) | Submit a transaction and get the receipt back in one call — no polling | [Full reference](../rpc/reference/realtime_sendRawTransaction.md) | The following standard Ethereum methods also return real-time results on MegaETH — they query against the latest mini-block automatically when called with `latest` or `pending`: @@ -44,7 +44,7 @@ The following standard Ethereum methods also return real-time results on MegaETH **Problem:** Your dapp submits a transaction and needs the receipt immediately — polling `eth_getTransactionReceipt` adds latency and complexity. -**Solution:** Use [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md). +**Solution:** Use [`realtime_sendRawTransaction`](../rpc/reference/realtime_sendRawTransaction.md). It submits the transaction and waits for the receipt in a single round-trip. The node's default wait is 5 seconds; an explicit timeout is capped at 3 seconds by the public gateway. Drop-in replacement for `eth_sendRawTransaction`. @@ -53,7 +53,7 @@ Drop-in replacement for `eth_sendRawTransaction`. **Problem:** Your frontend needs to update in real time as swaps, transfers, or game actions happen on-chain. -**Solution:** Subscribe to [`logs`](../rpc/eth_subscribe.md#logs) over WebSocket with `fromBlock` and `toBlock` set to `"pending"`. +**Solution:** Subscribe to [`logs`](../rpc/reference/eth_subscribe.md#logs) over WebSocket with `fromBlock` and `toBlock` set to `"pending"`. Logs arrive within ~10ms of execution — fast enough for live trading dashboards, game UIs, and notification systems. Filter by contract address and topics to receive only the events you care about. @@ -61,14 +61,14 @@ Filter by contract address and topics to receive only the events you care about. **Problem:** You need to track balance or storage changes for specific accounts in real time (e.g., a liquidation bot watching collateral ratios). -**Solution:** Subscribe to [`stateChanges`](../rpc/eth_subscribe.md#statechanges) with the account addresses you want to monitor. +**Solution:** Subscribe to [`stateChanges`](../rpc/reference/eth_subscribe.md#statechanges) with the account addresses you want to monitor. Each notification includes the updated balance, nonce, and any storage slots that changed. ### Building a block explorer or indexer **Problem:** You need every transaction and receipt as soon as it's executed, not when the next EVM block is sealed. -**Solution:** Subscribe to [`miniBlocks`](../rpc/eth_subscribe.md#miniblocks). +**Solution:** Subscribe to [`miniBlocks`](../rpc/reference/eth_subscribe.md#miniblocks). Each notification contains the full set of transactions and receipts for that mini-block. ## How It Works @@ -94,4 +94,5 @@ At T+100ms, she sends 1 ETH to Bob — the transaction is packaged into a mini-b ## Related Pages - [Mini-Blocks](../../mini-block.md) — understanding the two block types -- [RPC Reference](../rpc/README.md) — full method availability table and rate limiting +- [RPC Reference](../rpc/reference/README.md) — full method availability and method documentation +- [Operations and limits](../rpc/operations-and-limits.md) — public gateway limits and caching behavior diff --git a/docs/dev/rpc/README.md b/docs/dev/rpc/README.md index 96f486c..ed80c22 100644 --- a/docs/dev/rpc/README.md +++ b/docs/dev/rpc/README.md @@ -1,207 +1,20 @@ --- -description: "Complete reference for the 51 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." +description: MegaETH JSON-RPC endpoints, shared protocol conventions, operational limits, and method reference. --- -# RPC Reference +# JSON-RPC -The public MegaETH gateway exposes 49 HTTP methods and two WebSocket subscription methods. -See [Error Codes](./error-codes.md) for shared JSON-RPC and gateway errors. +MegaETH exposes Ethereum-compatible JSON-RPC over HTTP and WebSocket, with additional methods and real-time behavior. +Start with the shared guides below, then use the RPC Reference for individual method contracts. -## Available Methods +## Get started -{% hint style="info" %} -The table below reflects the public MegaETH Mainnet endpoint. -"Unavailable" includes methods recognized by the gateway but disabled or unimplemented upstream. -Managed providers may expose additional methods. -{% endhint %} +- [Quickstart](./quickstart.md) — make a read-only request and verify the connected network. +- [JSON-RPC basics](./json-rpc-basics.md) — request envelopes, notifications, batches, and response handling. +- [Type reference](./types.md) — hexadecimal quantities, byte strings, addresses, hashes, and selectors. +- [Error reference](./error-codes.md) — standard, Ethereum, MegaETH, and public-gateway errors. +- [Operations and limits](./operations-and-limits.md) — rate limits, payload caps, caching, and WebSocket limits. -| Method | Availability | Additional restrictions or behavior | -| ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | -| `debug_getHistoryTransactionCount` | Available | MegaETH-specific. | -| `debug_getRawHeader` | Available | | -| `debug_traceBlockByHash` | Available | Large responses are streamed. | -| `debug_traceBlockByNumber` | Available | Large responses are streamed. | -| `debug_traceCall` | Unavailable | The public endpoint returns `-32601`. | -| `debug_traceTransaction` | Available | Large responses are streamed. | -| `eth_accounts` | Available | Returns an empty array because the gateway does not manage user keys. | -| `eth_blockNumber` | Available | | -| `eth_call` | Available | Compute gas limited to 60,000,000. | -| `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | -| `eth_chainId` | Available | | -| `eth_createAccessList` | Available | Routed to the compute pool; no separate 60M compute override is added. | -| `eth_estimateGas` | Available | Uses an internal CPU-time limit; the source default is 0.5 seconds. | -| `eth_feeHistory` | Available | Block range limited to 256. | -| `eth_gasPrice` | Available | | -| `eth_getBalance` | Available | | -| `eth_getBlockByHash` | Available | | -| `eth_getBlockByNumber` | Available | | -| `eth_getBlockReceipts` | Available | | -| `eth_getBlockTransactionCountByHash` | Available | | -| `eth_getBlockTransactionCountByNumber` | Available | | -| `eth_getCode` | Available | | -| `eth_getCodeByHash` | Available | MegaETH-specific. | -| `eth_getFilterChanges` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getFilterLogs` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getHeaderByHash` | Available | MegaETH-specific. | -| `eth_getHeaderByNumber` | Available | MegaETH-specific. | -| `eth_getLogs` | Available | | -| `eth_getLogsWithCursor` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getStorageAt` | Available | | -| `eth_getTransactionByBlockHashAndIndex` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getTransactionByBlockNumberAndIndex` | Unavailable | The public endpoint returns `-32601`. | -| `eth_getTransactionByHash` | Available | | -| `eth_getTransactionCount` | Available | | -| `eth_getTransactionReceipt` | Available | | -| `eth_getUncleByBlockHashAndIndex` | Available | Returns `null` for valid MegaETH blocks. | -| `eth_getUncleByBlockNumberAndIndex` | Available | Returns `null` for valid MegaETH blocks. | -| `eth_getUncleCountByBlockHash` | Available | Returns `0x0` for valid MegaETH blocks. | -| `eth_getUncleCountByBlockNumber` | Available | Returns `0x0` for valid MegaETH blocks. | -| `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | -| `eth_maxPriorityFeePerGas` | Available | | -| `eth_mining` | Unavailable | The node reports the method as unimplemented. | -| `eth_newBlockFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_newFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_newPendingTransactionFilter` | Unavailable | The public endpoint returns `-32601`. | -| `eth_protocolVersion` | Available | Legacy compatibility method. | -| `eth_sendRawTransaction` | Available | | -| `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | -| `eth_subscribe` | WebSocket only | Supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`. | -| `eth_syncing` | Available | | -| `eth_uninstallFilter` | Available | Returns `false` when the filter ID does not exist. | -| `eth_unsubscribe` | WebSocket only | | -| `mega_getBlockWitness` | Available | MegaETH-specific. | -| `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | -| `mega_outputAtBlock` | Available | OP Stack output-root method. | -| `net_listening` | Available | | -| `net_peerCount` | Available | | -| `net_version` | Available | | -| `optimism_outputAtBlock` | Available | Alias of `mega_outputAtBlock`. | -| `realtime_sendRawTransaction` | Available | MegaETH-specific synchronous receipt method. | -| `trace_block` | Unavailable | The public endpoint returns `-32601`. | -| `trace_call` | Unavailable | The public endpoint returns `-32601`. | -| `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | -| `web3_clientVersion` | Available | | +## RPC Reference -## Rate Limiting - -Read methods on the public RPC endpoint are rate-limited **per IP address** in **fixed 10-second windows**. -Each method belongs to one of four categories, and each category has its own request budget: - -| Category | Limit (per 10 s) | Methods | -| -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | -| Instant | 2,000 | `eth_chainId`, `eth_blockNumber`, `net_version`, `eth_accounts`, `web3_clientVersion`, `eth_getBalance`, `eth_getStorageAt` | -| Simple | 500 | Block/transaction queries and all other read methods not listed in another category | -| Compute | 200 | `eth_call`, `eth_callMany`, `eth_estimateGas`, `eth_createAccessList`, `debug_trace*`, `trace_*` | -| IO-heavy | 200 | `eth_getLogs`, `eth_getBlockReceipts` | - -Additional notes: - -- Transaction submission methods (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) are not subject to these read rate limits. -- Cache hits still consume the method's per-category budget. -- `eth_callMany` consumes one Compute-category request per inner transaction, not one per HTTP request. -- A rate-limited request is rejected with HTTP `429` and RPC error `-32005` (`Rate limit exceeded`) — see [Error Codes](./error-codes.md). Reduce request frequency, or use batching or WebSocket subscriptions to lower the request count. - -## Request Body Limits - -The public RPC endpoint caps the size of the request body, and the cap depends on the method being called: - -| Method class | Maximum body size | -| -------------------------------------------------------------------------------------------------------------- | ----------------- | -| Transaction submission (`eth_sendRawTransaction`, `eth_sendRawTransactionSync`, `realtime_sendRawTransaction`) | 2.5 MiB | -| Large reads and simulations (`eth_call`, `eth_callMany`, `eth_createAccessList`, `eth_estimateGas`) | 1.5 MiB | -| All other methods | 128 KiB | - -The higher limits for simulation methods let you estimate gas for or simulate large contract deployments, whose initcode can exceed the 128 KiB default. -A request whose body exceeds the applicable limit is rejected with HTTP `413` and RPC error `-32099` (`payload too large`) — see [Error Codes](./error-codes.md). - -## Response Caching - -The public RPC gateway may serve read methods from an internal server-side cache rather than forwarding every request to a node. -Eligibility and lifetime are method-specific: immutable block numbers and hashes can use longer-lived entries, while methods that follow the chain head either use a short-lived cache or bypass it. -Do not assume that two different methods or block tags have the same cache policy. - -Two headers on the response are relevant: - -- **`Cache-Control: no-store`** — every public response carries this header. - It is a directive to caches _downstream_ of the gateway (browsers, proxies, CDNs): do not store this response. - It does not mean the gateway itself computed the response from scratch — the gateway's internal cache is part of the origin, not a downstream cache, so serving from it does not conflict with `no-store`. -- **`X-Workers-Cache-Status`** — reports whether the gateway's internal cache was hit (`HIT`, `MISS`, or other [Cloudflare cache statuses](https://developers.cloudflare.com/cache/concepts/cache-responses/)). - Use it to understand where a response came from; it has no effect on correctness. - -Sending `Cache-Control: no-store` or `no-cache` as a _request_ header does not bypass the internal cache — request cache directives address intermediary caches, not the origin's own caching. -The gateway does not provide a request option that bypasses its internal cache. - -## Method Reference - -## State and simulation - -- [`eth_accounts`](./eth_accounts.md) -- [`eth_call`](./eth_call.md) -- [`eth_callMany`](./eth_callMany.md) -- [`eth_createAccessList`](./eth_createAccessList.md) -- [`eth_estimateGas`](./eth_estimateGas.md) -- [`eth_getBalance`](./eth_getBalance.md) -- [`eth_getCode`](./eth_getCode.md) -- [`eth_getCodeByHash`](./eth_getCodeByHash.md) -- [`eth_getStorageAt`](./eth_getStorageAt.md) -- [`eth_getTransactionCount`](./eth_getTransactionCount.md) - -## Blocks, transactions, and receipts - -- [`eth_blockNumber`](./eth_blockNumber.md) -- [`eth_getBlockByHash`](./eth_getBlockByHash.md) -- [`eth_getBlockByNumber`](./eth_getBlockByNumber.md) -- [`eth_getBlockReceipts`](./eth_getBlockReceipts.md) -- [`eth_getBlockTransactionCountByHash`](./eth_getBlockTransactionCountByHash.md) -- [`eth_getBlockTransactionCountByNumber`](./eth_getBlockTransactionCountByNumber.md) -- [`eth_getHeaderByHash`](./eth_getHeaderByHash.md) -- [`eth_getHeaderByNumber`](./eth_getHeaderByNumber.md) -- [`eth_getTransactionByHash`](./eth_getTransactionByHash.md) -- [`eth_getTransactionReceipt`](./eth_getTransactionReceipt.md) -- [`eth_getUncleByBlockHashAndIndex`](./eth_getUncleByBlockHashAndIndex.md) -- [`eth_getUncleByBlockNumberAndIndex`](./eth_getUncleByBlockNumberAndIndex.md) -- [`eth_getUncleCountByBlockHash`](./eth_getUncleCountByBlockHash.md) -- [`eth_getUncleCountByBlockNumber`](./eth_getUncleCountByBlockNumber.md) -- [`eth_syncing`](./eth_syncing.md) - -## Logs and subscriptions - -- [`eth_getLogs`](./eth_getLogs.md) -- [`eth_subscribe`](./eth_subscribe.md) — WebSocket only -- [`eth_uninstallFilter`](./eth_uninstallFilter.md) -- [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only - -## Fees and transaction submission - -- [`eth_feeHistory`](./eth_feeHistory.md) -- [`eth_gasPrice`](./eth_gasPrice.md) -- [`eth_maxPriorityFeePerGas`](./eth_maxPriorityFeePerGas.md) -- [`eth_sendRawTransaction`](./eth_sendRawTransaction.md) -- [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) -- [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) - -## Debug methods - -- [`debug_getHistoryTransactionCount`](./debug_getHistoryTransactionCount.md) -- [`debug_getRawHeader`](./debug_getRawHeader.md) -- [`debug_traceBlockByHash`](./debug_traceBlockByHash.md) -- [`debug_traceBlockByNumber`](./debug_traceBlockByNumber.md) -- [`debug_traceTransaction`](./debug_traceTransaction.md) - -## MegaETH and OP Stack methods - -- [`eth_getWithdrawalProof`](./eth_getWithdrawalProof.md) -- [`mega_getBlockWitness`](./mega_getBlockWitness.md) -- [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md) -- [`mega_outputAtBlock`](./mega_outputAtBlock.md) -- [`optimism_outputAtBlock`](./optimism_outputAtBlock.md) - -## Network and client information - -- [`eth_chainId`](./eth_chainId.md) -- [`eth_protocolVersion`](./eth_protocolVersion.md) -- [`net_listening`](./net_listening.md) -- [`net_peerCount`](./net_peerCount.md) -- [`net_version`](./net_version.md) -- [`web3_clientVersion`](./web3_clientVersion.md) +Use the [RPC Reference](./reference/README.md) for method availability and individual request, response, error, and example documentation. diff --git a/docs/dev/rpc/error-codes.md b/docs/dev/rpc/error-codes.md index be86226..e062809 100644 --- a/docs/dev/rpc/error-codes.md +++ b/docs/dev/rpc/error-codes.md @@ -1,24 +1,118 @@ --- -description: MegaETH JSON-RPC error codes — HTTP status codes, RPC error codes, explanations, and mitigations. +description: Standard JSON-RPC, Ethereum, MegaETH, and public-gateway errors with retry guidance. --- -# Error Codes +# Error reference -| HTTP Error Code | RPC Error Code | Error Message | Explanation | Mitigation | -| --------------- | -------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| 400 | -32700 | `parse error` | The request body contains invalid JSON. | Check the request format and ensure valid JSON syntax. | -| 413 | -32099 | `payload too large` | The request body exceeds the size limit for the method being called. | Stay within the body-size limit for the method class. See [Request Body Limits](./README.md#request-body-limits). | -| 403 | -32601 | `rpc method is not whitelisted` | The requested RPC method is not allowed by the proxy configuration. | Use only whitelisted RPC methods. Contact MegaETH if you need access to additional methods. | -| 200 | -32001 | `Resource not found` | The requested block, header, or other resource could not be resolved. | Verify the block number or hash and retry. | -| 200 | 4444 | `pruned history unavailable` | The node no longer retains the requested historical state or data. | Use a newer block or an endpoint with the required historical-state retention. | -| 400 | -32019 | `block is out of range` | The requested block number is out of range. | Check the block number and ensure it's within the valid range. | -| 500 | -32020 | `backend response too large` | The backend response is too large. | Reduce the scope of the request or contact MegaETH for assistance. | -| 429 | -32005 | `Rate limit exceeded` | The request exceeds the rate limit for its method category. | Reduce request frequency, or use batching or WebSocket subscriptions. See [Rate Limiting](./README.md#rate-limiting). | -| 200 | -32000 | `permanent error forwarding request context deadline exceeded` | The API proxy cannot connect to the backend RPC server. | Pause for a while and retry. Notify MegaETH if the error persists. | +HTTP status and JSON-RPC status describe different layers. +An HTTP `200` response can contain either a JSON-RPC `result` or a JSON-RPC `error`. -Older references to `-32021` or `-32022` refer to the previous rate-limit codes. -The public gateway now returns `-32005` for rate-limited requests. +## Error surfaces -## Related Pages +| Surface | Shape | Meaning | +| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Transport failure | No valid JSON-RPC body | The HTTP, routing, connectivity, or gateway layer failed. | +| JSON-RPC error | Top-level `error` object | The request envelope, method, parameters, or server execution failed. | +| Method-defined error | A successful `result` contains an error field | The JSON-RPC call succeeded, but the method reports an execution outcome inside its result. | +| Empty success | `result` is `null`, `"0x0"`, or `[]` | The method succeeded and returned its documented empty value. | -- [RPC Reference](./README.md) — full method availability table +Check the method page before treating an empty success as a failure. +See [JSON-RPC basics](./json-rpc-basics.md#error-response) for the complete error envelope. + +## Standard JSON-RPC errors + +| Code | Name | Meaning | Retry | +| -------- | ---------------- | ------------------------------------------------------------------------------ | ----- | +| `-32700` | Parse error | The request body is not valid JSON. | No | +| `-32600` | Invalid Request | The JSON-RPC envelope is invalid. | No | +| `-32601` | Method not found | The method is unknown, disabled, or unavailable on this endpoint or transport. | No | +| `-32602` | Invalid params | The parameters do not satisfy the method contract. | No | +| `-32603` | Internal error | The server failed while processing a valid request. | Maybe | + +Malformed JSON and unknown methods on the public HTTP endpoint return a JSON-RPC error body with HTTP `200`. +Client logic should therefore inspect `error.code` instead of inferring success from the HTTP status. + +## Ethereum server errors + +EIP-1474 assigns the following server-error codes: + +| Code | Meaning | Typical action | +| -------- | ---------------------------------------------- | -------------------------------------------------------------- | +| `-32000` | Invalid input or a general server-side failure | Inspect the message and method context before retrying. | +| `-32001` | Resource not found | Verify the block, transaction, or other selector. | +| `-32002` | Resource unavailable | Retry later if the requested resource should become available. | +| `-32003` | Transaction rejected | Correct the transaction or its fees before retrying. | +| `-32004` | Method not supported | Use a supported method or endpoint. | +| `-32005` | Limit exceeded | Reduce load or request scope, then retry with backoff. | +| `-32006` | JSON-RPC version not supported | Send JSON-RPC `"2.0"`. | + +Providers can reuse `-32000` for several failures. +Use both the numeric code and message for diagnostics, but avoid matching only on message text. + +## MegaETH and gateway errors + +| Code | Meaning | Typical cause | Action | +| -------- | -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `3` | Execution reverted | `eth_call` or `eth_estimateGas` reached an EVM revert. | Inspect and decode `error.data`, then change the call inputs or state context. | +| `4444` | Pruned history unavailable | The serving node does not retain the requested historical state. | Use a newer block or an endpoint with the required history. | +| `-32005` | Limit exceeded | A public rate limit, WebSocket subscription cap, or server-capacity limit was reached. | Reduce concurrency or scope and retry with exponential backoff and jitter. | +| `-32099` | Payload too large | The HTTP request body exceeds the applicable gateway limit. | Reduce the body or batch size. | + +See [Operations and limits](./operations-and-limits.md) for the public gateway thresholds. + +### Execution revert example + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": 3, + "message": "execution reverted", + "data": "0x08c379a0..." + } +} +``` + +The first four bytes of `error.data` identify the revert payload format. +Decode the payload when possible before retrying. + +### Historical state unavailable + +Code `4444` applies to historical state that the node has pruned or never retained. +It commonly affects state reads such as `eth_getBalance`, `eth_getCode`, `eth_getStorageAt`, and `eth_getTransactionCount` at an old block. + +Keep the request and selector unchanged while testing another endpoint. +Do not retry the same endpoint repeatedly because retention is not a transient condition. + +## HTTP status handling + +| HTTP status | Meaning at the transport layer | Client action | +| -------------- | ------------------------------------- | ---------------------------------------------------------------- | +| `200` | The HTTP exchange completed. | Inspect the JSON-RPC body for `result` or `error`. | +| `413` | The request body is too large. | Handle JSON-RPC `-32099` when present and reduce the payload. | +| `429` | The gateway rate-limited the request. | Handle JSON-RPC `-32005` when present and retry with backoff. | +| `500` or `503` | The gateway or upstream failed. | Retry sparingly after checking request size and endpoint health. | + +Do not hardcode a one-to-one mapping between every JSON-RPC code and an HTTP status. + +## What to record + +Capture these fields before retrying or escalating a failure: + +- endpoint and transport +- method name +- block or resource selector +- HTTP status +- JSON-RPC code, message, and data +- request ID +- retry count and delay + +Never log private keys or unsigned transaction secrets. +Redact raw signed transactions unless the transaction is already public and your logging policy allows them. + +## Sources + +- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) +- [EIP-1474: Remote procedure call specification](https://eips.ethereum.org/EIPS/eip-1474) +- `mega-reth`: `crates/rpc/rpc-eth-types/src/error/mod.rs` diff --git a/docs/dev/rpc/eth_subscribe.md b/docs/dev/rpc/eth_subscribe.md deleted file mode 100644 index fee6b76..0000000 --- a/docs/dev/rpc/eth_subscribe.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -description: eth_subscribe — WebSocket subscriptions for real-time logs, state changes, mini-blocks, and block headers on MegaETH. ---- - -# eth_subscribe - -## Summary - -Creates a WebSocket subscription and returns a subscription ID. -MegaETH supports standard log and head subscriptions plus `stateChanges` and `miniBlocks` for real-time mini-block data. - -The public method is WebSocket-only. Use [`eth_unsubscribe`](./eth_unsubscribe.md) on the same connection when the subscription is no longer needed. - -## Parameters - -| Position | Name | Type | Required | Description | -| -------- | -------------- | --------------- | -------- | ------------------------------------------------------------------ | -| `0` | `subscription` | string | Yes | One of `logs`, `stateChanges`, `miniBlocks`, or `newHeads`. | -| `1` | `options` | object or array | Depends | Filter options for `logs`, or an address array for `stateChanges`. | - -### `logs` - -The optional filter object accepts: - -| Field | Type | Required | Description | -| ----------- | -------------------- | -------- | --------------------------------------------------------------------- | -| `fromBlock` | block tag | No | Set to `pending` with `toBlock` for real-time mini-block logs. | -| `toBlock` | block tag | No | Set to `pending` with `fromBlock` for real-time mini-block logs. | -| `address` | address or address[] | No | Emitting contract address or addresses. | -| `topics` | array | No | Position-sensitive topic filter; nested arrays express OR conditions. | - -### `stateChanges` - -The second parameter is a required array of account addresses to monitor. - -### `miniBlocks` - -No second parameter is required. - -### `newHeads` - -No second parameter is required. - -## Result - -The initial response contains a connection-scoped subscription ID as `DATA`. -Subsequent notifications use `eth_subscription` and include that ID plus a `result` payload. - -Payloads depend on the subscription type: - -- `logs` uses the same log object schema as [`eth_getLogs`](./eth_getLogs.md). -- `stateChanges` returns an account address, numeric nonce, balance quantity, and changed storage slots. -- `miniBlocks` returns the EVM block number and timestamp, mini-block index and global height, microsecond timestamp, gas used, transactions, receipts, roots, and the sequencer signature when available. -- `newHeads` returns a block header and includes MegaETH's additional `miniBlockCount` field. - -Notifications are not replayed automatically after a connection closes. Reconnect and create a new subscription when continuity is required. - -## Comparison with Ethereum Standard JSON-RPC - -### Ethereum Standard - -Ethereum WebSocket providers commonly implement `eth_subscribe` for `logs` and `newHeads`, although subscriptions are transport extensions rather than HTTP execution-API methods. -Subscription IDs and delivery are scoped to the WebSocket connection. - -### MegaETH Node Behavior - -MegaETH adds `stateChanges` and `miniBlocks`. -These expose state and receipt data as mini-blocks are produced, while `newHeads` follows sealed EVM blocks and adds `miniBlockCount`. -For real-time log delivery, both log-range tags should be `pending`. - -### MegaETH Public Gateway - -The public gateway accepts this method only over `wss://mainnet.megaeth.com/ws`. -It supports `logs`, `stateChanges`, `miniBlocks`, and `newHeads`, tracks ownership per connection, and requires periodic client activity; sending a lightweight request such as `eth_chainId` at least every 30 seconds prevents idle closure. - -## Errors - -The `| Scope |` column distinguishes method failures from gateway policy errors. - -| Code | Scope | Message | When it happens | -| -------- | ---------------- | ----------------------------- | --------------------------------------------------------------------- | -| `-32602` | Method | Invalid params | The subscription type or its filter/options are malformed. | -| `-32000` | Transport/policy | WebSocket connection required | The method is sent over HTTP instead of a WebSocket connection. | -| `-32601` | Transport/policy | Method not found | The requested subscription type is not enabled by the public gateway. | - -See also [Error Codes](./error-codes.md). - -## Examples - -Endpoint: `wss://mainnet.megaeth.com/ws` (WebSocket) - -Capture date: July 24, 2026 - -Outcome: success - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["newHeads"] -} -``` - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0xaec58cfc2dc41f873fc37d6c871230c1" -} -``` - -## Sources - -- Spec: EIP-1474 for JSON-RPC framing; subscriptions are a WebSocket transport extension. -- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/pubsub.rs` -- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/rpc-gateway/websocket-session.ts` -- Probe: MegaETH Mainnet public WebSocket endpoint, July 24, 2026 diff --git a/docs/dev/rpc/json-rpc-basics.md b/docs/dev/rpc/json-rpc-basics.md new file mode 100644 index 0000000..e7f205a --- /dev/null +++ b/docs/dev/rpc/json-rpc-basics.md @@ -0,0 +1,117 @@ +--- +description: Shared JSON-RPC 2.0 request, notification, batch, success, and error conventions used by MegaETH. +--- + +# JSON-RPC basics + +MegaETH uses JSON-RPC 2.0 for HTTP requests and WebSocket messages. +Method pages define the parameter order, result shape, and method-specific behavior. + +## Request envelope + +| Field | JSON type | Required | Rule | +| --------- | ---------------- | ----------------------------- | ----------------------------------------------------- | +| `jsonrpc` | string | Yes | Must be `"2.0"`. | +| `id` | string or number | Unless sending a notification | Correlates the response with the request. | +| `method` | string | Yes | Names the RPC method. | +| `params` | array or object | Method-defined | Method pages in this reference use positional arrays. | + +Use a unique string or number for `id` when you expect a response. +JSON-RPC permits a `null` request ID, but clients should avoid it because a response may also use `null` when the request ID cannot be determined. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_chainId", + "params": [] +} +``` + +## Notifications + +A notification omits `id`. +The server does not return a response, including when the notification is invalid. + +```json +{ + "jsonrpc": "2.0", + "method": "eth_blockNumber", + "params": [] +} +``` + +Use notifications only when your application intentionally does not need a result or error. + +## Batch requests + +A batch is a JSON array containing request or notification objects. +The public gateway accepts at most 100 items in one batch. + +```json +[ + { + "jsonrpc": "2.0", + "id": "block", + "method": "eth_blockNumber", + "params": [] + }, + { + "jsonrpc": "2.0", + "id": "chain", + "method": "eth_chainId", + "params": [] + } +] +``` + +Batch responses may arrive in a different order from their requests. +Match each response by `id`, and remember that notification items do not produce response items. +See [Operations and limits](./operations-and-limits.md#http-request-and-response-limits) for batch accounting and body-size limits. + +## Success response + +A successful response contains `result` and does not contain `error`. +The result type is defined by the method. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x10e6" +} +``` + +Values such as `null`, `"0x0"`, and `[]` can be successful results when documented by the method. + +## Error response + +A failed call contains `error` and does not contain `result`. + +| Field | JSON type | Required | Description | +| --------------- | ------------------------- | -------- | ------------------------------- | +| `jsonrpc` | string | Yes | Always `"2.0"`. | +| `id` | string, number, or `null` | Yes | Usually matches the request ID. | +| `error.code` | number | Yes | Machine-readable error code. | +| `error.message` | string | Yes | Human-readable summary. | +| `error.data` | any | No | Additional structured details. | + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32602, + "message": "Invalid params" + } +} +``` + +HTTP `200` only means the HTTP exchange completed. +Always inspect the JSON-RPC body for `result` or `error`. +See [Error reference](./error-codes.md) for standard, Ethereum, gateway, and MegaETH-specific codes. + +## Sources + +- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) +- [EIP-1474: Remote procedure call specification](https://eips.ethereum.org/EIPS/eip-1474) diff --git a/docs/dev/rpc/operations-and-limits.md b/docs/dev/rpc/operations-and-limits.md new file mode 100644 index 0000000..13741a4 --- /dev/null +++ b/docs/dev/rpc/operations-and-limits.md @@ -0,0 +1,104 @@ +--- +description: Public MegaETH JSON-RPC rate limits, payload limits, method caps, caching behavior, and WebSocket limits. +--- + +# Operations and limits + +This page describes limits applied by the public MegaETH gateway. +Method pages define the underlying request and response contracts. + +## HTTP request and response limits + +| Limit | Value | +| -------------------------------------- | ------------ | +| Default request body | 128 KiB | +| Transaction-submission request body | 2.5 MiB | +| Simulation and large-read request body | 1.5 MiB | +| Batch size | 100 requests | +| Batch subrequest budget | 950 | +| Response size | 50 MiB | + +The 2.5 MiB body limit applies to `eth_sendRawTransaction`, `eth_sendRawTransactionSync`, and `realtime_sendRawTransaction`. +The 1.5 MiB body limit applies to `eth_call`, `eth_callMany`, `eth_createAccessList`, and `eth_estimateGas`. +A body that exceeds its limit is rejected with HTTP `413` and JSON-RPC code `-32099`. + +The batch subrequest budget counts expanded work rather than only top-level batch items. +For example, the calls inside `eth_callMany` contribute to that budget. + +## Method-specific limits + +| Method | Public gateway behavior | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `eth_call` | Compute gas is capped at 60,000,000. | +| `eth_callMany` | At most 100 bundles and 100 total calls, 60,000,000 compute gas per call, and a 25-second timeout. | +| `eth_estimateGas` | The node applies a CPU-time limit whose current default is 0.5 seconds. | +| `eth_feeHistory` | `blockCount` is capped at 256. | +| `eth_getLogs` | The public indexed path does not impose a gateway block-range cap, but backend row, execution-time, memory, and response-size limits still apply. | + +Use bounded ranges and pagination for log scans and historical backfills. +Do not assume that removing a block-range cap makes an unbounded query safe. + +## Read rate limits + +Read requests are limited per client IP in fixed 10-second windows. + +| Category | Requests per 10 seconds | Typical methods | +| -------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| Instant | 2,000 | `eth_chainId`, `eth_blockNumber`, `net_version`, `eth_accounts`, `web3_clientVersion`, `eth_getBalance`, `eth_getStorageAt` | +| Simple | 500 | Basic block and transaction reads not assigned to another category | +| Compute | 200 | `eth_call`, `eth_callMany`, `eth_estimateGas`, `eth_createAccessList`, and debug trace methods | +| IO-heavy | 200 | `eth_getLogs` and `eth_getBlockReceipts` | + +Transaction-submission methods are exempt from these read limits. +`eth_callMany` is charged by its inner calls rather than as one unit. +A rate-limited request returns HTTP `429` with JSON-RPC code `-32005`. + +Use exponential backoff with jitter for retryable throttling. +Reduce concurrency and query size before increasing retry frequency. + +## Gateway caching + +The public gateway caches eligible read methods internally. +Immutable block numbers and hashes can use longer-lived entries, while head-following reads use shorter policies or bypass the cache. + +Rate-limit accounting differs by request shape: + +- A single read is rate-limited before cache lookup, so a cache hit consumes its category budget. +- A read batch checks the cache first and charges only cache misses against the read-rate budget. + +Every public response includes `Cache-Control: no-store` for downstream caches. +This header does not disable the gateway's internal cache. +`X-Workers-Cache-Status` indicates whether that internal cache returned the response. + +The gateway does not expose a request header or parameter that bypasses its internal cache. + +## WebSocket limits + +| Limit | Value | +| ---------------------------------- | ------------------------------------ | +| Connections per IP | 5 | +| Subscriptions per connection | 5 | +| Client message rate | 5 messages per second per connection | +| Idle timeout | 60 seconds | +| Maximum message size | 64 KiB | +| Addresses in a `logs` filter | 20 | +| Topic positions in a `logs` filter | 4 | + +Use `wss://mainnet.megaeth.com/ws` for Mainnet and `wss://carrot.megaeth.com/ws` for Testnet. +Send a lightweight request such as `eth_chainId` at least every 30 seconds to prevent idle disconnection. +Reconnect, recreate subscriptions, and reconcile any missed data after a disconnect because notifications are not replayed automatically. + +The public WebSocket endpoint accepts: + +- `eth_subscribe` +- `eth_unsubscribe` +- `eth_sendRawTransaction` +- `eth_sendRawTransactionSync` +- `realtime_sendRawTransaction` +- `eth_chainId` + +## Related pages + +- [Error reference](./error-codes.md) +- [`eth_subscribe`](./reference/eth_subscribe.md) +- [`eth_getLogs`](./reference/eth_getLogs.md) diff --git a/docs/dev/rpc/quickstart.md b/docs/dev/rpc/quickstart.md new file mode 100644 index 0000000..df4aa4c --- /dev/null +++ b/docs/dev/rpc/quickstart.md @@ -0,0 +1,64 @@ +--- +description: Make your first read-only MegaETH JSON-RPC requests and verify the connected network. +--- + +# Quickstart + +Use these read-only requests to confirm connectivity and learn the basic response shape. +The public HTTP endpoint accepts JSON-RPC `POST` requests without an API key. + +## Endpoints + +| Network | HTTP | WebSocket | +| ------- | --------------------------------- | ------------------------------ | +| Mainnet | `https://mainnet.megaeth.com/rpc` | `wss://mainnet.megaeth.com/ws` | +| Testnet | `https://carrot.megaeth.com/rpc` | `wss://carrot.megaeth.com/ws` | + +Use HTTP for standard requests and WebSocket for [`eth_subscribe`](./reference/eth_subscribe.md) and [`eth_unsubscribe`](./reference/eth_unsubscribe.md). + +## Check the latest block + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' +``` + +A successful response contains a hexadecimal block number: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x..." +} +``` + +## Verify the network + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":2,"method":"eth_chainId","params":[]}' +``` + +MegaETH Mainnet returns `0x10e6` (4326), and MegaETH Testnet returns `0x18c7` (6343). + +## Read account state + +Replace the zero address with the account you want to query. + +```bash +curl -sS https://mainnet.megaeth.com/rpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":3,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}' +``` + +The result is a hexadecimal [`Quantity`](./types.md#quantity) denominated in wei. + +## Next steps + +- Use [JSON-RPC basics](./json-rpc-basics.md) for envelopes, notifications, and batches. +- Use [Operations and limits](./operations-and-limits.md) before sending large batches or historical queries. +- Use [Error reference](./error-codes.md) to distinguish transport failures from JSON-RPC errors. +- Browse the [RPC Reference](./reference/README.md) for request and response schemas. diff --git a/docs/dev/rpc/reference/README.md b/docs/dev/rpc/reference/README.md new file mode 100644 index 0000000..b98f782 --- /dev/null +++ b/docs/dev/rpc/reference/README.md @@ -0,0 +1,158 @@ +--- +description: "Complete reference for the 51 JSON-RPC methods available through MegaETH's public HTTP and WebSocket endpoints." +--- + +# RPC Reference + +This reference documents the JSON-RPC methods available through the public MegaETH HTTP and WebSocket endpoints. +Use [JSON-RPC](../README.md) for request framing, shared wire types, errors, and gateway limits. + +## Available Methods + +{% hint style="info" %} +The table below reflects the public MegaETH Mainnet endpoint. +"Unavailable" includes methods recognized by the gateway but disabled or unimplemented upstream. +Managed providers may expose additional methods. +{% endhint %} + +| Method | Availability | Additional restrictions or behavior | +| ----------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- | +| `debug_getHistoryTransactionCount` | Available | MegaETH-specific. | +| `debug_getRawHeader` | Available | | +| `debug_traceBlockByHash` | Available | Large responses are streamed. | +| `debug_traceBlockByNumber` | Available | Large responses are streamed. | +| `debug_traceCall` | Unavailable | The public endpoint returns `-32601`. | +| `debug_traceTransaction` | Available | Large responses are streamed. | +| `eth_accounts` | Available | Returns an empty array because the gateway does not manage user keys. | +| `eth_blockNumber` | Available | | +| `eth_call` | Available | Compute gas limited to 60,000,000. | +| `eth_callAfter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_callMany` | Available | 100 bundles and 100 total calls; 60,000,000 compute gas per call; timeout capped at 25 seconds. | +| `eth_chainId` | Available | | +| `eth_createAccessList` | Available | Routed to the compute pool; no separate 60M compute override is added. | +| `eth_estimateGas` | Available | Uses an internal CPU-time limit; the source default is 0.5 seconds. | +| `eth_feeHistory` | Available | Block range limited to 256. | +| `eth_gasPrice` | Available | | +| `eth_getBalance` | Available | | +| `eth_getBlockByHash` | Available | | +| `eth_getBlockByNumber` | Available | | +| `eth_getBlockReceipts` | Available | | +| `eth_getBlockTransactionCountByHash` | Available | | +| `eth_getBlockTransactionCountByNumber` | Available | | +| `eth_getCode` | Available | | +| `eth_getCodeByHash` | Available | MegaETH-specific. | +| `eth_getFilterChanges` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getFilterLogs` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getHeaderByHash` | Available | MegaETH-specific. | +| `eth_getHeaderByNumber` | Available | MegaETH-specific. | +| `eth_getLogs` | Available | | +| `eth_getLogsWithCursor` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getStorageAt` | Available | | +| `eth_getTransactionByBlockHashAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByBlockNumberAndIndex` | Unavailable | The public endpoint returns `-32601`. | +| `eth_getTransactionByHash` | Available | | +| `eth_getTransactionCount` | Available | | +| `eth_getTransactionReceipt` | Available | | +| `eth_getUncleByBlockHashAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleByBlockNumberAndIndex` | Available | Returns `null` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockHash` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getUncleCountByBlockNumber` | Available | Returns `0x0` for valid MegaETH blocks. | +| `eth_getWithdrawalProof` | Available | OP Stack withdrawal proof method. | +| `eth_maxPriorityFeePerGas` | Available | | +| `eth_mining` | Unavailable | The node reports the method as unimplemented. | +| `eth_newBlockFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_newPendingTransactionFilter` | Unavailable | The public endpoint returns `-32601`. | +| `eth_protocolVersion` | Available | Legacy compatibility method. | +| `eth_sendRawTransaction` | Available | | +| `eth_sendRawTransactionSync` | Available | MegaETH-specific synchronous receipt method. | +| `eth_subscribe` | WebSocket only | Supports six subscription types; see the method page. | +| `eth_syncing` | Available | | +| `eth_uninstallFilter` | Available | Returns `false` when the filter ID does not exist. | +| `eth_unsubscribe` | WebSocket only | | +| `mega_getBlockWitness` | Available | MegaETH-specific. | +| `mega_getWithdrawalProof` | Available | Alias routed to `eth_getWithdrawalProof`. | +| `mega_outputAtBlock` | Available | OP Stack output-root method. | +| `net_listening` | Available | | +| `net_peerCount` | Available | | +| `net_version` | Available | | +| `optimism_outputAtBlock` | Available | Alias of `mega_outputAtBlock`. | +| `realtime_sendRawTransaction` | Available | MegaETH-specific synchronous receipt method. | +| `trace_block` | Unavailable | The public endpoint returns `-32601`. | +| `trace_call` | Unavailable | The public endpoint returns `-32601`. | +| `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | +| `web3_clientVersion` | Available | | + +## Method Reference + +## State and simulation + +- [`eth_accounts`](./eth_accounts.md) +- [`eth_call`](./eth_call.md) +- [`eth_callMany`](./eth_callMany.md) +- [`eth_createAccessList`](./eth_createAccessList.md) +- [`eth_estimateGas`](./eth_estimateGas.md) +- [`eth_getBalance`](./eth_getBalance.md) +- [`eth_getCode`](./eth_getCode.md) +- [`eth_getCodeByHash`](./eth_getCodeByHash.md) +- [`eth_getStorageAt`](./eth_getStorageAt.md) +- [`eth_getTransactionCount`](./eth_getTransactionCount.md) + +## Blocks, transactions, and receipts + +- [`eth_blockNumber`](./eth_blockNumber.md) +- [`eth_getBlockByHash`](./eth_getBlockByHash.md) +- [`eth_getBlockByNumber`](./eth_getBlockByNumber.md) +- [`eth_getBlockReceipts`](./eth_getBlockReceipts.md) +- [`eth_getBlockTransactionCountByHash`](./eth_getBlockTransactionCountByHash.md) +- [`eth_getBlockTransactionCountByNumber`](./eth_getBlockTransactionCountByNumber.md) +- [`eth_getHeaderByHash`](./eth_getHeaderByHash.md) +- [`eth_getHeaderByNumber`](./eth_getHeaderByNumber.md) +- [`eth_getTransactionByHash`](./eth_getTransactionByHash.md) +- [`eth_getTransactionReceipt`](./eth_getTransactionReceipt.md) +- [`eth_getUncleByBlockHashAndIndex`](./eth_getUncleByBlockHashAndIndex.md) +- [`eth_getUncleByBlockNumberAndIndex`](./eth_getUncleByBlockNumberAndIndex.md) +- [`eth_getUncleCountByBlockHash`](./eth_getUncleCountByBlockHash.md) +- [`eth_getUncleCountByBlockNumber`](./eth_getUncleCountByBlockNumber.md) +- [`eth_syncing`](./eth_syncing.md) + +## Logs and subscriptions + +- [`eth_getLogs`](./eth_getLogs.md) +- [`eth_subscribe`](./eth_subscribe.md) — WebSocket only +- [`eth_uninstallFilter`](./eth_uninstallFilter.md) +- [`eth_unsubscribe`](./eth_unsubscribe.md) — WebSocket only + +## Fees and transaction submission + +- [`eth_feeHistory`](./eth_feeHistory.md) +- [`eth_gasPrice`](./eth_gasPrice.md) +- [`eth_maxPriorityFeePerGas`](./eth_maxPriorityFeePerGas.md) +- [`eth_sendRawTransaction`](./eth_sendRawTransaction.md) +- [`eth_sendRawTransactionSync`](./eth_sendRawTransactionSync.md) +- [`realtime_sendRawTransaction`](./realtime_sendRawTransaction.md) + +## Debug methods + +- [`debug_getHistoryTransactionCount`](./debug_getHistoryTransactionCount.md) +- [`debug_getRawHeader`](./debug_getRawHeader.md) +- [`debug_traceBlockByHash`](./debug_traceBlockByHash.md) +- [`debug_traceBlockByNumber`](./debug_traceBlockByNumber.md) +- [`debug_traceTransaction`](./debug_traceTransaction.md) + +## MegaETH and OP Stack methods + +- [`eth_getWithdrawalProof`](./eth_getWithdrawalProof.md) +- [`mega_getBlockWitness`](./mega_getBlockWitness.md) +- [`mega_getWithdrawalProof`](./mega_getWithdrawalProof.md) +- [`mega_outputAtBlock`](./mega_outputAtBlock.md) +- [`optimism_outputAtBlock`](./optimism_outputAtBlock.md) + +## Network and client information + +- [`eth_chainId`](./eth_chainId.md) +- [`eth_protocolVersion`](./eth_protocolVersion.md) +- [`net_listening`](./net_listening.md) +- [`net_peerCount`](./net_peerCount.md) +- [`net_version`](./net_version.md) +- [`web3_clientVersion`](./web3_clientVersion.md) diff --git a/docs/dev/rpc/debug_getHistoryTransactionCount.md b/docs/dev/rpc/reference/debug_getHistoryTransactionCount.md similarity index 98% rename from docs/dev/rpc/debug_getHistoryTransactionCount.md rename to docs/dev/rpc/reference/debug_getHistoryTransactionCount.md index f25abbd..bc706c5 100644 --- a/docs/dev/rpc/debug_getHistoryTransactionCount.md +++ b/docs/dev/rpc/reference/debug_getHistoryTransactionCount.md @@ -49,7 +49,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/debug_getRawHeader.md b/docs/dev/rpc/reference/debug_getRawHeader.md similarity index 100% rename from docs/dev/rpc/debug_getRawHeader.md rename to docs/dev/rpc/reference/debug_getRawHeader.md diff --git a/docs/dev/rpc/debug_traceBlockByHash.md b/docs/dev/rpc/reference/debug_traceBlockByHash.md similarity index 100% rename from docs/dev/rpc/debug_traceBlockByHash.md rename to docs/dev/rpc/reference/debug_traceBlockByHash.md diff --git a/docs/dev/rpc/debug_traceBlockByNumber.md b/docs/dev/rpc/reference/debug_traceBlockByNumber.md similarity index 100% rename from docs/dev/rpc/debug_traceBlockByNumber.md rename to docs/dev/rpc/reference/debug_traceBlockByNumber.md diff --git a/docs/dev/rpc/debug_traceTransaction.md b/docs/dev/rpc/reference/debug_traceTransaction.md similarity index 100% rename from docs/dev/rpc/debug_traceTransaction.md rename to docs/dev/rpc/reference/debug_traceTransaction.md diff --git a/docs/dev/rpc/eth_accounts.md b/docs/dev/rpc/reference/eth_accounts.md similarity index 98% rename from docs/dev/rpc/eth_accounts.md rename to docs/dev/rpc/reference/eth_accounts.md index 39bc370..58acf2b 100644 --- a/docs/dev/rpc/eth_accounts.md +++ b/docs/dev/rpc/reference/eth_accounts.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_blockNumber.md b/docs/dev/rpc/reference/eth_blockNumber.md similarity index 98% rename from docs/dev/rpc/eth_blockNumber.md rename to docs/dev/rpc/reference/eth_blockNumber.md index 701deb2..9c7b9bf 100644 --- a/docs/dev/rpc/eth_blockNumber.md +++ b/docs/dev/rpc/reference/eth_blockNumber.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_call.md b/docs/dev/rpc/reference/eth_call.md similarity index 99% rename from docs/dev/rpc/eth_call.md rename to docs/dev/rpc/reference/eth_call.md index 582de26..b579575 100644 --- a/docs/dev/rpc/eth_call.md +++ b/docs/dev/rpc/reference/eth_call.md @@ -166,7 +166,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_callMany.md b/docs/dev/rpc/reference/eth_callMany.md similarity index 100% rename from docs/dev/rpc/eth_callMany.md rename to docs/dev/rpc/reference/eth_callMany.md diff --git a/docs/dev/rpc/eth_chainId.md b/docs/dev/rpc/reference/eth_chainId.md similarity index 98% rename from docs/dev/rpc/eth_chainId.md rename to docs/dev/rpc/reference/eth_chainId.md index 38bf7b1..ba7530a 100644 --- a/docs/dev/rpc/eth_chainId.md +++ b/docs/dev/rpc/reference/eth_chainId.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_createAccessList.md b/docs/dev/rpc/reference/eth_createAccessList.md similarity index 99% rename from docs/dev/rpc/eth_createAccessList.md rename to docs/dev/rpc/reference/eth_createAccessList.md index d622b61..9216f36 100644 --- a/docs/dev/rpc/eth_createAccessList.md +++ b/docs/dev/rpc/reference/eth_createAccessList.md @@ -136,7 +136,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_estimateGas.md b/docs/dev/rpc/reference/eth_estimateGas.md similarity index 99% rename from docs/dev/rpc/eth_estimateGas.md rename to docs/dev/rpc/reference/eth_estimateGas.md index c822beb..905b373 100644 --- a/docs/dev/rpc/eth_estimateGas.md +++ b/docs/dev/rpc/reference/eth_estimateGas.md @@ -130,7 +130,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's compute read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 1.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_feeHistory.md b/docs/dev/rpc/reference/eth_feeHistory.md similarity index 98% rename from docs/dev/rpc/eth_feeHistory.md rename to docs/dev/rpc/reference/eth_feeHistory.md index 3657aaa..9cd7edd 100644 --- a/docs/dev/rpc/eth_feeHistory.md +++ b/docs/dev/rpc/reference/eth_feeHistory.md @@ -78,7 +78,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_gasPrice.md b/docs/dev/rpc/reference/eth_gasPrice.md similarity index 98% rename from docs/dev/rpc/eth_gasPrice.md rename to docs/dev/rpc/reference/eth_gasPrice.md index 654ed50..90c0336 100644 --- a/docs/dev/rpc/eth_gasPrice.md +++ b/docs/dev/rpc/reference/eth_gasPrice.md @@ -46,7 +46,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBalance.md b/docs/dev/rpc/reference/eth_getBalance.md similarity index 98% rename from docs/dev/rpc/eth_getBalance.md rename to docs/dev/rpc/reference/eth_getBalance.md index 79b8d5b..aeb0fdd 100644 --- a/docs/dev/rpc/eth_getBalance.md +++ b/docs/dev/rpc/reference/eth_getBalance.md @@ -56,7 +56,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBlockByHash.md b/docs/dev/rpc/reference/eth_getBlockByHash.md similarity index 98% rename from docs/dev/rpc/eth_getBlockByHash.md rename to docs/dev/rpc/reference/eth_getBlockByHash.md index 6c156e8..8eae2a7 100644 --- a/docs/dev/rpc/eth_getBlockByHash.md +++ b/docs/dev/rpc/reference/eth_getBlockByHash.md @@ -85,7 +85,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBlockByNumber.md b/docs/dev/rpc/reference/eth_getBlockByNumber.md similarity index 98% rename from docs/dev/rpc/eth_getBlockByNumber.md rename to docs/dev/rpc/reference/eth_getBlockByNumber.md index 1cad89c..47c417e 100644 --- a/docs/dev/rpc/eth_getBlockByNumber.md +++ b/docs/dev/rpc/reference/eth_getBlockByNumber.md @@ -85,7 +85,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBlockReceipts.md b/docs/dev/rpc/reference/eth_getBlockReceipts.md similarity index 99% rename from docs/dev/rpc/eth_getBlockReceipts.md rename to docs/dev/rpc/reference/eth_getBlockReceipts.md index e0c92db..860a146 100644 --- a/docs/dev/rpc/eth_getBlockReceipts.md +++ b/docs/dev/rpc/reference/eth_getBlockReceipts.md @@ -91,7 +91,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's IO-heavy read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBlockTransactionCountByHash.md b/docs/dev/rpc/reference/eth_getBlockTransactionCountByHash.md similarity index 98% rename from docs/dev/rpc/eth_getBlockTransactionCountByHash.md rename to docs/dev/rpc/reference/eth_getBlockTransactionCountByHash.md index cc7f287..da271d6 100644 --- a/docs/dev/rpc/eth_getBlockTransactionCountByHash.md +++ b/docs/dev/rpc/reference/eth_getBlockTransactionCountByHash.md @@ -46,7 +46,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getBlockTransactionCountByNumber.md b/docs/dev/rpc/reference/eth_getBlockTransactionCountByNumber.md similarity index 98% rename from docs/dev/rpc/eth_getBlockTransactionCountByNumber.md rename to docs/dev/rpc/reference/eth_getBlockTransactionCountByNumber.md index 91c393f..c0240c2 100644 --- a/docs/dev/rpc/eth_getBlockTransactionCountByNumber.md +++ b/docs/dev/rpc/reference/eth_getBlockTransactionCountByNumber.md @@ -46,7 +46,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getCode.md b/docs/dev/rpc/reference/eth_getCode.md similarity index 98% rename from docs/dev/rpc/eth_getCode.md rename to docs/dev/rpc/reference/eth_getCode.md index 69ccb08..240e5fd 100644 --- a/docs/dev/rpc/eth_getCode.md +++ b/docs/dev/rpc/reference/eth_getCode.md @@ -55,7 +55,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getCodeByHash.md b/docs/dev/rpc/reference/eth_getCodeByHash.md similarity index 98% rename from docs/dev/rpc/eth_getCodeByHash.md rename to docs/dev/rpc/reference/eth_getCodeByHash.md index f262ce9..5f77db0 100644 --- a/docs/dev/rpc/eth_getCodeByHash.md +++ b/docs/dev/rpc/reference/eth_getCodeByHash.md @@ -47,7 +47,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getHeaderByHash.md b/docs/dev/rpc/reference/eth_getHeaderByHash.md similarity index 98% rename from docs/dev/rpc/eth_getHeaderByHash.md rename to docs/dev/rpc/reference/eth_getHeaderByHash.md index 0c60336..ef10d4f 100644 --- a/docs/dev/rpc/eth_getHeaderByHash.md +++ b/docs/dev/rpc/reference/eth_getHeaderByHash.md @@ -74,7 +74,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getHeaderByNumber.md b/docs/dev/rpc/reference/eth_getHeaderByNumber.md similarity index 98% rename from docs/dev/rpc/eth_getHeaderByNumber.md rename to docs/dev/rpc/reference/eth_getHeaderByNumber.md index 7861cf5..0d408ff 100644 --- a/docs/dev/rpc/eth_getHeaderByNumber.md +++ b/docs/dev/rpc/reference/eth_getHeaderByNumber.md @@ -74,7 +74,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getLogs.md b/docs/dev/rpc/reference/eth_getLogs.md similarity index 99% rename from docs/dev/rpc/eth_getLogs.md rename to docs/dev/rpc/reference/eth_getLogs.md index 1c11eba..728b8c6 100644 --- a/docs/dev/rpc/eth_getLogs.md +++ b/docs/dev/rpc/reference/eth_getLogs.md @@ -105,7 +105,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's IO-heavy read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getStorageAt.md b/docs/dev/rpc/reference/eth_getStorageAt.md similarity index 98% rename from docs/dev/rpc/eth_getStorageAt.md rename to docs/dev/rpc/reference/eth_getStorageAt.md index e7b0dea..5c939ca 100644 --- a/docs/dev/rpc/eth_getStorageAt.md +++ b/docs/dev/rpc/reference/eth_getStorageAt.md @@ -61,7 +61,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getTransactionByHash.md b/docs/dev/rpc/reference/eth_getTransactionByHash.md similarity index 98% rename from docs/dev/rpc/eth_getTransactionByHash.md rename to docs/dev/rpc/reference/eth_getTransactionByHash.md index af06655..28db8f7 100644 --- a/docs/dev/rpc/eth_getTransactionByHash.md +++ b/docs/dev/rpc/reference/eth_getTransactionByHash.md @@ -90,7 +90,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getTransactionCount.md b/docs/dev/rpc/reference/eth_getTransactionCount.md similarity index 98% rename from docs/dev/rpc/eth_getTransactionCount.md rename to docs/dev/rpc/reference/eth_getTransactionCount.md index dc9e8f7..8ad31b7 100644 --- a/docs/dev/rpc/eth_getTransactionCount.md +++ b/docs/dev/rpc/reference/eth_getTransactionCount.md @@ -56,7 +56,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getTransactionReceipt.md b/docs/dev/rpc/reference/eth_getTransactionReceipt.md similarity index 98% rename from docs/dev/rpc/eth_getTransactionReceipt.md rename to docs/dev/rpc/reference/eth_getTransactionReceipt.md index 0c54cf4..8c2fee1 100644 --- a/docs/dev/rpc/eth_getTransactionReceipt.md +++ b/docs/dev/rpc/reference/eth_getTransactionReceipt.md @@ -86,7 +86,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_getUncleByBlockHashAndIndex.md b/docs/dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md similarity index 100% rename from docs/dev/rpc/eth_getUncleByBlockHashAndIndex.md rename to docs/dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md diff --git a/docs/dev/rpc/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md similarity index 100% rename from docs/dev/rpc/eth_getUncleByBlockNumberAndIndex.md rename to docs/dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md diff --git a/docs/dev/rpc/eth_getUncleCountByBlockHash.md b/docs/dev/rpc/reference/eth_getUncleCountByBlockHash.md similarity index 100% rename from docs/dev/rpc/eth_getUncleCountByBlockHash.md rename to docs/dev/rpc/reference/eth_getUncleCountByBlockHash.md diff --git a/docs/dev/rpc/eth_getUncleCountByBlockNumber.md b/docs/dev/rpc/reference/eth_getUncleCountByBlockNumber.md similarity index 100% rename from docs/dev/rpc/eth_getUncleCountByBlockNumber.md rename to docs/dev/rpc/reference/eth_getUncleCountByBlockNumber.md diff --git a/docs/dev/rpc/eth_getWithdrawalProof.md b/docs/dev/rpc/reference/eth_getWithdrawalProof.md similarity index 98% rename from docs/dev/rpc/eth_getWithdrawalProof.md rename to docs/dev/rpc/reference/eth_getWithdrawalProof.md index 6691ca4..b815826 100644 --- a/docs/dev/rpc/eth_getWithdrawalProof.md +++ b/docs/dev/rpc/reference/eth_getWithdrawalProof.md @@ -48,7 +48,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_maxPriorityFeePerGas.md b/docs/dev/rpc/reference/eth_maxPriorityFeePerGas.md similarity index 98% rename from docs/dev/rpc/eth_maxPriorityFeePerGas.md rename to docs/dev/rpc/reference/eth_maxPriorityFeePerGas.md index 2689519..888fe8f 100644 --- a/docs/dev/rpc/eth_maxPriorityFeePerGas.md +++ b/docs/dev/rpc/reference/eth_maxPriorityFeePerGas.md @@ -46,7 +46,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_protocolVersion.md b/docs/dev/rpc/reference/eth_protocolVersion.md similarity index 100% rename from docs/dev/rpc/eth_protocolVersion.md rename to docs/dev/rpc/reference/eth_protocolVersion.md diff --git a/docs/dev/rpc/eth_sendRawTransaction.md b/docs/dev/rpc/reference/eth_sendRawTransaction.md similarity index 98% rename from docs/dev/rpc/eth_sendRawTransaction.md rename to docs/dev/rpc/reference/eth_sendRawTransaction.md index e2719d7..78ee997 100644 --- a/docs/dev/rpc/eth_sendRawTransaction.md +++ b/docs/dev/rpc/reference/eth_sendRawTransaction.md @@ -48,7 +48,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32003` | Method | Transaction rejected | Insufficient sender funds, pool at capacity, or unsupported transaction type | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_sendRawTransactionSync.md b/docs/dev/rpc/reference/eth_sendRawTransactionSync.md similarity index 99% rename from docs/dev/rpc/eth_sendRawTransactionSync.md rename to docs/dev/rpc/reference/eth_sendRawTransactionSync.md index b298fd1..29d5926 100644 --- a/docs/dev/rpc/eth_sendRawTransactionSync.md +++ b/docs/dev/rpc/reference/eth_sendRawTransactionSync.md @@ -94,7 +94,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32000` | Method | Server error | Receipt not available before the wait window expired, or the node rejected the transaction | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/reference/eth_subscribe.md b/docs/dev/rpc/reference/eth_subscribe.md new file mode 100644 index 0000000..fcfc322 --- /dev/null +++ b/docs/dev/rpc/reference/eth_subscribe.md @@ -0,0 +1,235 @@ +--- +description: eth_subscribe — WebSocket subscriptions for block headers, logs, pending transactions, sync status, mini-blocks, and state changes. +--- + +# eth_subscribe + +## Summary + +Creates a WebSocket subscription and returns a connection-scoped subscription ID. +MegaETH supports four common Ethereum subscription types and adds `miniBlocks` and `stateChanges`. + +Use [`eth_unsubscribe`](./eth_unsubscribe.md) on the same connection when the subscription is no longer needed. +Notifications are not replayed after a connection closes, so reconnecting clients must recreate subscriptions and reconcile missed data. + +## Parameters + +| Position | Name | Type | Required | Description | +| -------- | -------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | +| `0` | `subscription` | string | Yes | One of `newHeads`, `logs`, `newPendingTransactions`, `syncing`, `miniBlocks`, or `stateChanges`. | +| `1` | `options` | object, boolean, or `Address[]` | No | Shape depends on the subscription type. | + +### `newHeads` + +No options are accepted. +Notifications are emitted for sealed EVM block headers. + +### `logs` + +The optional filter object accepts: + +| Field | Type | Required | Description | +| ----------- | ------------------------ | -------- | ----------------------------------------------------------------------- | +| `fromBlock` | block number or tag | No | Set to `pending` or `latest` to receive mini-block log updates. | +| `toBlock` | block number or tag | No | Upper bound for the filter. | +| `blockHash` | `Hash32` | No | Selects one block and cannot be combined with `fromBlock` or `toBlock`. | +| `address` | `Address` or `Address[]` | No | Matches emitting contracts. | +| `topics` | array | No | Position-sensitive topic filter with OR arrays at individual positions. | + +The public gateway accepts at most 20 addresses and four topic positions in one log subscription. +For real-time mini-block logs, set both `fromBlock` and `toBlock` to `pending`. + +### `newPendingTransactions` + +The optional second parameter is a boolean. +Omit it or pass `false` to receive transaction hashes, or pass `true` to receive full transaction objects. + +### `syncing` + +No options are accepted. +Notifications report changes in node synchronization status. + +### `miniBlocks` + +No options are accepted. +Notifications contain transactions and receipts as each mini-block is produced. + +### `stateChanges` + +The optional second parameter is an array of account addresses. +Omitting the array or passing an empty array subscribes to all changed accounts. +The node defaults to a maximum of 256 addresses in one subscription. + +## Result + +The initial response returns a subscription ID as `Data`. +Later messages use the `eth_subscription` notification envelope: + +```json +{ + "jsonrpc": "2.0", + "method": "eth_subscription", + "params": { + "subscription": "0x...", + "result": {} + } +} +``` + +The `result` shape depends on the subscription type. + +### `newHeads` result + +The result contains the standard Ethereum block-header fields documented by [`eth_getBlockByNumber`](./eth_getBlockByNumber.md). +When block metadata is available, MegaETH also includes: + +| Field | Type | Description | +| ----------------- | ---------- | ---------------------------------------------- | +| `txOffset` | `Quantity` | Transaction offset recorded for the block. | +| `miniBlockOffset` | `Quantity` | Global offset of the block's first mini-block. | +| `miniBlockCount` | `Quantity` | Number of mini-blocks in the EVM block. | +| `signature` | `Data` | Sequencer signature recorded for the block. | + +### `logs` result + +The result uses the log object documented by [`eth_getLogs`](./eth_getLogs.md). +Mini-block log notifications can contain streaming placeholders until the enclosing EVM block is sealed. + +### `newPendingTransactions` result + +The result is a transaction `Hash32` by default. +When the second parameter is `true`, the result is the full transaction object documented by [`eth_getTransactionByHash`](./eth_getTransactionByHash.md). + +### `syncing` result + +The result is `false` when the node is not syncing. +While syncing, it is the progress object documented by [`eth_syncing`](./eth_syncing.md). + +### `miniBlocks` result + +Mini-block payloads use `snake_case` field names. + +| Field | Type | Description | +| ---------------------- | ---------- | ---------------------------------------------------------------------------------- | +| `block_number` | `Quantity` | Number of the enclosing EVM block. | +| `block_timestamp` | `Quantity` | Unix timestamp of the enclosing EVM block in seconds. | +| `index` | `Quantity` | Mini-block index within the EVM block. | +| `mini_block_number` | `Quantity` | Global mini-block number. | +| `mini_block_timestamp` | `Quantity` | Mini-block Unix timestamp in microseconds. | +| `gas_used` | `Quantity` | Gas consumed by the mini-block. | +| `transactions` | object[] | Included transaction objects. | +| `receipts` | object[] | Corresponding transaction receipts. | +| `transaction_root` | `Hash32` | Transaction trie root for the mini-block. | +| `receipt_root` | `Hash32` | Receipt trie root for the mini-block. | +| `signature` | `Data` | Sequencer signature, omitted for mini-blocks produced before the signing hardfork. | + +### `stateChanges` result + +Each notification describes one changed account. + +| Field | Type | Description | +| --------- | ---------- | ------------------------------------------------ | +| `address` | `Address` | Changed account. | +| `nonce` | `Quantity` | Current account nonce. | +| `balance` | `Quantity` | Current account balance. | +| `storage` | object | Changed storage slots as `{ key: value }` pairs. | + +`storage` contains only slots changed in that mini-block. +An empty object means that the account's nonce or balance changed without a storage change. + +## Comparison with Ethereum Standard JSON-RPC + +### Ethereum Standard + +`eth_subscribe` is a WebSocket transport extension rather than an HTTP Execution API method. +Ethereum clients commonly support `newHeads`, `logs`, `newPendingTransactions`, and `syncing`, with subscription IDs scoped to one connection. + +### MegaETH Node Behavior + +MegaETH adds `miniBlocks` and `stateChanges` for updates at mini-block granularity. +It enriches `newHeads` with transaction-offset, mini-block, and sequencer-signature metadata. +Setting a log subscription's `fromBlock` to `pending` or `latest` selects the mini-block event stream. + +### MegaETH Public Gateway + +Use `wss://mainnet.megaeth.com/ws` for Mainnet or `wss://carrot.megaeth.com/ws` for Testnet. +The public gateway allows all six subscription types and limits each connection to five active subscriptions. +Send `eth_chainId` at least every 30 seconds to keep an otherwise idle connection active. +See [Operations and limits](../operations-and-limits.md#websocket-limits) for the remaining WebSocket limits. + +## Errors + +| Code | Scope | When it happens | Action | +| -------- | ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | +| `-32602` | Method | The subscription type or options are invalid, or a `stateChanges` address list exceeds the node limit. | Correct the type, option shape, filter, or address count. | +| `-32005` | Gateway or server | The connection subscription cap or server capacity is exhausted. | Unsubscribe from unused streams or reconnect with fewer subscriptions. | + +Calling `eth_subscribe` over HTTP does not create a subscription. +Use a WebSocket connection and inspect the returned JSON-RPC error if a client sends the method to the wrong transport. + +See also [Error reference](../error-codes.md). + +## Examples + +Connect to the Mainnet WebSocket endpoint and subscribe to block headers: + +```bash +wscat -c wss://mainnet.megaeth.com/ws +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_subscribe", + "params": ["newHeads"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xaec58cfc2dc41f873fc37d6c871230c1" +} +``` + +Subscribe to pending transaction hashes: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "eth_subscribe", + "params": ["newPendingTransactions"] +} +``` + +Subscribe to all state changes: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "eth_subscribe", + "params": ["stateChanges"] +} +``` + +Filter state changes by account: + +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "eth_subscribe", + "params": ["stateChanges", ["0xaa000000000000000000000000000000000000aa"]] +} +``` + +## Sources + +- Spec: [EIP-1474](https://eips.ethereum.org/EIPS/eip-1474) for JSON-RPC framing. +- Code: `git@github.com:megaeth-labs/mega-reth.git @ ab60376631228edab3a6df180f295280bad26e93: crates/megaeth/rpc/src/pubsub.rs` +- Code: `git@github.com:megaeth-labs/mega-rpc.git @ 06aa35aa95d569c227cc25d2aa12834eb0458aa0: workers/src/rpc-gateway/websocket/constants.ts` +- Probe: MegaETH Mainnet public WebSocket endpoint, July 27, 2026. diff --git a/docs/dev/rpc/eth_syncing.md b/docs/dev/rpc/reference/eth_syncing.md similarity index 98% rename from docs/dev/rpc/eth_syncing.md rename to docs/dev/rpc/reference/eth_syncing.md index 19e701e..268381e 100644 --- a/docs/dev/rpc/eth_syncing.md +++ b/docs/dev/rpc/reference/eth_syncing.md @@ -55,7 +55,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/eth_uninstallFilter.md b/docs/dev/rpc/reference/eth_uninstallFilter.md similarity index 100% rename from docs/dev/rpc/eth_uninstallFilter.md rename to docs/dev/rpc/reference/eth_uninstallFilter.md diff --git a/docs/dev/rpc/eth_unsubscribe.md b/docs/dev/rpc/reference/eth_unsubscribe.md similarity index 98% rename from docs/dev/rpc/eth_unsubscribe.md rename to docs/dev/rpc/reference/eth_unsubscribe.md index e76dda6..133e049 100644 --- a/docs/dev/rpc/eth_unsubscribe.md +++ b/docs/dev/rpc/reference/eth_unsubscribe.md @@ -45,7 +45,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32602` | Request | Invalid params | Subscription ID parameter is missing | | `-32600` | Request | Invalid request | Subscription was created by a different connection | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/mega_getBlockWitness.md b/docs/dev/rpc/reference/mega_getBlockWitness.md similarity index 98% rename from docs/dev/rpc/mega_getBlockWitness.md rename to docs/dev/rpc/reference/mega_getBlockWitness.md index 5877331..6657c34 100644 --- a/docs/dev/rpc/mega_getBlockWitness.md +++ b/docs/dev/rpc/reference/mega_getBlockWitness.md @@ -71,7 +71,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/mega_getWithdrawalProof.md b/docs/dev/rpc/reference/mega_getWithdrawalProof.md similarity index 98% rename from docs/dev/rpc/mega_getWithdrawalProof.md rename to docs/dev/rpc/reference/mega_getWithdrawalProof.md index d6c2def..119914e 100644 --- a/docs/dev/rpc/mega_getWithdrawalProof.md +++ b/docs/dev/rpc/reference/mega_getWithdrawalProof.md @@ -85,7 +85,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/mega_outputAtBlock.md b/docs/dev/rpc/reference/mega_outputAtBlock.md similarity index 99% rename from docs/dev/rpc/mega_outputAtBlock.md rename to docs/dev/rpc/reference/mega_outputAtBlock.md index 5dad1c8..28f4dfa 100644 --- a/docs/dev/rpc/mega_outputAtBlock.md +++ b/docs/dev/rpc/reference/mega_outputAtBlock.md @@ -92,7 +92,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/net_listening.md b/docs/dev/rpc/reference/net_listening.md similarity index 98% rename from docs/dev/rpc/net_listening.md rename to docs/dev/rpc/reference/net_listening.md index 4bb27c2..c3b45ce 100644 --- a/docs/dev/rpc/net_listening.md +++ b/docs/dev/rpc/reference/net_listening.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/net_peerCount.md b/docs/dev/rpc/reference/net_peerCount.md similarity index 98% rename from docs/dev/rpc/net_peerCount.md rename to docs/dev/rpc/reference/net_peerCount.md index b5ed6f8..56d5de9 100644 --- a/docs/dev/rpc/net_peerCount.md +++ b/docs/dev/rpc/reference/net_peerCount.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/net_version.md b/docs/dev/rpc/reference/net_version.md similarity index 98% rename from docs/dev/rpc/net_version.md rename to docs/dev/rpc/reference/net_version.md index e4f03b2..bdd84de 100644 --- a/docs/dev/rpc/net_version.md +++ b/docs/dev/rpc/reference/net_version.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/optimism_outputAtBlock.md b/docs/dev/rpc/reference/optimism_outputAtBlock.md similarity index 98% rename from docs/dev/rpc/optimism_outputAtBlock.md rename to docs/dev/rpc/reference/optimism_outputAtBlock.md index f48f08c..2d85b7b 100644 --- a/docs/dev/rpc/optimism_outputAtBlock.md +++ b/docs/dev/rpc/reference/optimism_outputAtBlock.md @@ -49,7 +49,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's simple read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/realtime_sendRawTransaction.md b/docs/dev/rpc/reference/realtime_sendRawTransaction.md similarity index 99% rename from docs/dev/rpc/realtime_sendRawTransaction.md rename to docs/dev/rpc/reference/realtime_sendRawTransaction.md index 4dc2971..bb625d4 100644 --- a/docs/dev/rpc/realtime_sendRawTransaction.md +++ b/docs/dev/rpc/reference/realtime_sendRawTransaction.md @@ -63,7 +63,7 @@ The `| Scope |` column distinguishes method failures from gateway policy errors. | `-32000` | Method | Server error | `realtime transaction expired` — receipt not available before the wait expired | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 2.5 MiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/web3_clientVersion.md b/docs/dev/rpc/reference/web3_clientVersion.md similarity index 98% rename from docs/dev/rpc/web3_clientVersion.md rename to docs/dev/rpc/reference/web3_clientVersion.md index 090f22b..3745c69 100644 --- a/docs/dev/rpc/web3_clientVersion.md +++ b/docs/dev/rpc/reference/web3_clientVersion.md @@ -45,7 +45,7 @@ No method-specific errors were observed. | `-32005` | Transport/policy | Rate limit exceeded | The caller exceeds the public gateway's instant read budget. | | `-32099` | Transport/policy | Payload too large | The request body exceeds the 128 KiB public endpoint limit. | -See also [Error Codes](./error-codes.md). +See also [Error Codes](../error-codes.md). ## Examples diff --git a/docs/dev/rpc/types.md b/docs/dev/rpc/types.md new file mode 100644 index 0000000..1837404 --- /dev/null +++ b/docs/dev/rpc/types.md @@ -0,0 +1,100 @@ +--- +description: Hexadecimal quantities, byte strings, addresses, hashes, block selectors, and transaction call objects used by MegaETH JSON-RPC. +--- + +# Type reference + +This page defines wire types shared by MegaETH JSON-RPC methods. +Method pages remain self-contained and specify the types accepted in each position. + +## Core wire types + +### `Quantity` + +A `Quantity` is a non-negative integer encoded as a `0x`-prefixed hexadecimal string. +It uses the shortest representation, so leading zeroes are not allowed except in `0x0`. + +| Valid | Invalid | +| -------- | ------- | +| `0x0` | `0` | +| `0x1` | `0x01` | +| `0x5208` | `21000` | + +### `Data` + +`Data` is an arbitrary byte sequence encoded as a `0x`-prefixed hexadecimal string. +It contains exactly two hexadecimal digits per byte and may be empty. + +| Valid | Invalid | +| ------------ | ---------- | +| `0x` | `0` | +| `0x12` | `0x1` | +| `0xdeadbeef` | `deadbeef` | + +### `Address` + +An `Address` is a 20-byte value encoded as `0x` followed by 40 hexadecimal digits. +The wire format accepts upper- or lowercase hexadecimal digits. + +Example: `0x0000000000000000000000000000000000000000`. + +### `Hash32` + +A `Hash32` is a 32-byte hash encoded as `0x` followed by 64 hexadecimal digits. +Block hashes, transaction hashes, and trie roots use this representation. + +### `Bytes32` + +`Bytes32` has the same wire width as `Hash32` but represents a fixed-width value rather than necessarily a hash. +Storage keys and proof values commonly use this representation. + +## Block selectors + +Methods that read block or state data may accept a block number encoded as `Quantity` or one of these tags: + +| Tag | Meaning on MegaETH | +| ----------- | ------------------------------------------------------------ | +| `earliest` | The genesis block. | +| `latest` | The latest streaming state, including committed mini-blocks. | +| `pending` | The latest streaming state. | +| `safe` | The latest safe EVM block known to the node. | +| `finalized` | The latest finalized EVM block known to the node. | + +Some methods also accept an EIP-1898 block selector object containing `blockHash` or `blockNumber`. +Check the method page before using the object form because support is method-specific. + +## Transaction call object + +Simulation methods such as [`eth_call`](./reference/eth_call.md), [`eth_estimateGas`](./reference/eth_estimateGas.md), and [`eth_createAccessList`](./reference/eth_createAccessList.md) accept a transaction call object. +Common fields include: + +| Field | Type | Description | +| ---------------------- | ------------------- | ------------------------------------------- | +| `from` | `Address` | Simulated sender. | +| `to` | `Address` or `null` | Recipient, or `null` for contract creation. | +| `gas` | `Quantity` | Gas limit supplied to the simulation. | +| `gasPrice` | `Quantity` | Legacy gas price. | +| `maxFeePerGas` | `Quantity` | EIP-1559 maximum fee. | +| `maxPriorityFeePerGas` | `Quantity` | EIP-1559 priority fee. | +| `value` | `Quantity` | Value transferred in wei. | +| `input` or `data` | `Data` | Calldata or contract creation bytecode. | +| `nonce` | `Quantity` | Sender nonce when the method supports it. | +| `accessList` | array | EIP-2930 access list. | + +Do not combine `gasPrice` with EIP-1559 fee fields. +Use the relevant method page for accepted fields and defaults. + +## Common validation mistakes + +| Mistake | Wrong | Correct | +| ------------------------ | ------------------------------ | ---------------------- | +| Decimal quantity | `21000` | `"0x5208"` | +| Leading zeroes | `"0x0001"` | `"0x1"` | +| Odd-length data | `"0x123"` | `"0x0123"` | +| Short address | `"0x1234"` | A full 20-byte address | +| Mixed log selector modes | `blockHash` with `fromBlock` | Use one selector mode | +| Mixed fee models | `gasPrice` with `maxFeePerGas` | Use one fee model | + +## Source + +- [EIP-1474: Value encoding](https://eips.ethereum.org/EIPS/eip-1474#value-encoding) diff --git a/docs/dev/send-tx/debugging.md b/docs/dev/send-tx/debugging.md index 38129a1..79a52f8 100644 --- a/docs/dev/send-tx/debugging.md +++ b/docs/dev/send-tx/debugging.md @@ -16,8 +16,8 @@ It does not support `debug_traceCall`; use [`mega-evme`](#simulating-a-new-trans The following methods are supported: -- **[`debug_traceTransaction`](../rpc/debug_traceTransaction.md)** — trace an already-mined transaction by hash -- **[`debug_traceBlockByNumber`](../rpc/debug_traceBlockByNumber.md)** / **[`debug_traceBlockByHash`](../rpc/debug_traceBlockByHash.md)** — trace all transactions in a block +- **[`debug_traceTransaction`](../rpc/reference/debug_traceTransaction.md)** — trace an already-mined transaction by hash +- **[`debug_traceBlockByNumber`](../rpc/reference/debug_traceBlockByNumber.md)** / **[`debug_traceBlockByHash`](../rpc/reference/debug_traceBlockByHash.md)** — trace all transactions in a block ### Supported Tracers @@ -205,7 +205,7 @@ See [Volatile Data Access](../execution/volatile-data.md) for the full list of t - [Gas Estimation](gas-estimation.md) — estimate gas correctly and avoid common errors - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding - [Gas Model](../execution/gas-model.md) — how compute gas and storage gas work -- [RPC Reference](../rpc/README.md) — method availability and restrictions +- [RPC Reference](../rpc/reference/README.md) — method availability and restrictions - [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas - [Gas Detention (spec)](https://docs.megaeth.com/spec/megaevm/gas-detention) — compute gas cap triggered by volatile data access - [mega-evme](https://docs.megaeth.com/mega-evme) — full command reference, configuration, and cookbook diff --git a/docs/dev/send-tx/gas-estimation.md b/docs/dev/send-tx/gas-estimation.md index c614a46..41b1270 100644 --- a/docs/dev/send-tx/gas-estimation.md +++ b/docs/dev/send-tx/gas-estimation.md @@ -80,7 +80,7 @@ There are two workarounds: Estimating gas for a large contract deployment sends the full initcode in the request body. To accommodate this, the public RPC endpoint allows `eth_call`, `eth_callMany`, `eth_createAccessList`, and `eth_estimateGas` bodies up to **1.5 MiB** — well above the 128 KiB limit applied to ordinary read methods. A request that exceeds this limit is rejected with HTTP `413` / `-32099` (`payload too large`). -See [Request Body Limits](../rpc/README.md#request-body-limits) for the full breakdown. +See [HTTP request and response limits](../rpc/operations-and-limits.md#http-request-and-response-limits) for the full breakdown. ## Toolchain Configuration @@ -151,7 +151,7 @@ If you need to debug which dimension caused a failure, see [Debugging Transactio - [Gas Model](../execution/gas-model.md) — how compute gas, storage gas, and the bucket multiplier work - [EVM Differences](../execution/overview.md) — volatile data caps, SSTORE refund changes, 98/100 forwarding -- [RPC Reference](../rpc/README.md) — method availability and restrictions +- [RPC Reference](../rpc/reference/README.md) — method availability and restrictions - [Developer FAQ](../faq.md) — `eth_estimateGas` gas cap, block gas limit - [Dual Gas Model (spec)](https://docs.megaeth.com/spec/megaevm/dual-gas-model) — formal specification of compute gas and storage gas - [Resource Limits (spec)](https://docs.megaeth.com/spec/megaevm/resource-limits) — per-transaction and per-block limit enforcement diff --git a/docs/dev/send-tx/overview.md b/docs/dev/send-tx/overview.md index 22fd806..d99a508 100644 --- a/docs/dev/send-tx/overview.md +++ b/docs/dev/send-tx/overview.md @@ -121,7 +121,7 @@ curl -s https://mainnet.megaeth.com/rpc \ Returns the full transaction receipt directly. The node waits up to 5 seconds by default; the public gateway caps an explicit timeout at 3,000 milliseconds and returns `-32000 realtime transaction expired` if the deadline elapses first. -See [`realtime_sendRawTransaction`](../rpc/realtime_sendRawTransaction.md) for the full reference. +See [`realtime_sendRawTransaction`](../rpc/reference/realtime_sendRawTransaction.md) for the full reference. {% endtab %} {% endtabs %} diff --git a/docs/mini-block.md b/docs/mini-block.md index dbf01d8..43c370b 100644 --- a/docs/mini-block.md +++ b/docs/mini-block.md @@ -79,7 +79,7 @@ A signed mini-block is a binding commitment: if the sequencer ever sealed an EVM The signing key is registered onchain in the [SequencerRegistry](https://docs.megaeth.com/spec/system-contracts/sequencer-registry) system contract at `0x6342000000000000000000000000000000000006`, introduced in Rex5. The key can be rotated by scheduling a change in the registry; rotations take effect at an EVM block boundary, and the full change history remains queryable onchain. -The signature is a standard secp256k1 ECDSA signature over `keccak256(rlp(header))`, where the header is the following eight fields of the [`miniBlocks` subscription payload](dev/rpc/eth_subscribe.md#miniblocks), RLP-encoded in this order: +The signature is a standard secp256k1 ECDSA signature over `keccak256(rlp(header))`, where the header is the following eight fields of the [`miniBlocks` subscription payload](dev/rpc/reference/eth_subscribe.md#miniblocks), RLP-encoded in this order: | # | Payload field | Type | | --- | ---------------------- | ------------ | @@ -104,7 +104,7 @@ Mini-blocks produced before Rex5 are unsigned — the `signature` field is absen To verify a mini-block, rebuild the header hash, recover the signer from the signature, and compare it against the sequencer key registered onchain. -The example below uses [viem](https://viem.sh) and takes a notification payload `mb` exactly as delivered by the [`miniBlocks` subscription](dev/rpc/eth_subscribe.md#miniblocks). +The example below uses [viem](https://viem.sh) and takes a notification payload `mb` exactly as delivered by the [`miniBlocks` subscription](dev/rpc/reference/eth_subscribe.md#miniblocks). ```typescript import { @@ -195,6 +195,6 @@ Each notification delivers the mini-block's transactions, receipts, and state ch - [Architecture](architecture.md) — how transactions flow through the MegaETH network - [Realtime API](dev/read/realtime-api.md) — subscribe to mini-blocks and get execution results with minimum latency -- [eth_subscribe](dev/rpc/eth_subscribe.md) — full reference of the `miniBlocks` subscription payload +- [eth_subscribe](dev/rpc/reference/eth_subscribe.md) — full reference of the `miniBlocks` subscription payload - [High-Precision Timestamp](dev/execution/system-contracts.md#high-precision-timestamp) — microsecond timestamps available within mini-blocks - [SequencerRegistry (spec)](https://docs.megaeth.com/spec/system-contracts/sequencer-registry) — onchain registry of the sequencer signing key From 826b183cbb303de051185113c9aa2cc4d5e33ee7 Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Mon, 27 Jul 2026 18:08:37 +0800 Subject: [PATCH 12/13] docs: expand read overview --- docs/dev/read/overview.md | 68 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/docs/dev/read/overview.md b/docs/dev/read/overview.md index d9b5eff..4525cb5 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -1,7 +1,71 @@ --- -description: Entry point to the MegaETH JSON-RPC reference. +description: How to read current state, historical data, transactions, logs, and real-time updates from MegaETH. --- # Read from MegaETH -See [JSON-RPC](../rpc/README.md) for shared guidance and the complete RPC method reference. +MegaETH supports standard Ethereum JSON-RPC reads for accounts, contracts, blocks, transactions, receipts, and logs. +Existing Ethereum libraries work without a MegaETH-specific read API. + +The main difference is freshness. +Requests using `latest` or `pending` read from MegaETH's streaming state, which advances as mini-blocks are produced. +You can therefore read state updated within milliseconds without waiting for the next EVM block. + +## Choose a read pattern + +| Pattern | Use it for | Starting point | +| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------- | +| HTTP JSON-RPC | One-time reads, contract calls, simulations, and historical queries | [JSON-RPC](../rpc/README.md) | +| WebSocket subscriptions | Push-based logs, pending transactions, block headers, mini-blocks, and state changes | [Realtime API](realtime-api.md) | +| Concrete block selectors | Reproducible reads against a specific EVM block | [Type reference](../rpc/types.md#block-selectors) | + +Use HTTP for request-and-response workflows. +Use WebSocket subscriptions when your application needs updates as they happen or wants to avoid polling. + +## State freshness and block tags + +| Selector | Data source | Behavior | +| ------------------------ | -------------------------- | -------------------------------------------------------------------- | +| `latest` | Streaming state | Includes state committed by the latest mini-block. | +| `pending` | Streaming state | Uses the same real-time state view as `latest`. | +| `safe` | EVM block state | Reads the latest block considered safe. | +| `finalized` | EVM block state | Reads the latest finalized block. | +| Hexadecimal block number | Historical EVM block state | Repeats the state view for that block when retained by the endpoint. | + +No additional flag or header is required for real-time reads. +Pass `latest` or `pending` to methods that accept a block selector. + +Historical availability depends on the serving endpoint's retention. +If an old state query returns code `4444`, see the [Error reference](../rpc/error-codes.md#historical-state-unavailable). + +## Public gateway behavior + +The public MegaETH endpoint applies operational policies in addition to each method's JSON-RPC contract. +Account for these policies when choosing query size, concurrency, and retry behavior. + +| Behavior | What to expect | Details | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| Rate limiting | Read methods use per-IP tiers with fixed 10-second windows. A limited request returns HTTP `429` with JSON-RPC code `-32005`. | [Read rate limits](../rpc/operations-and-limits.md#read-rate-limits) | +| Request and response limits | The default request-body limit is 128 KiB, large reads and simulations allow up to 1.5 MiB, batches contain at most 100 requests, and responses are limited to 50 MiB. | [HTTP request and response limits](../rpc/operations-and-limits.md#http-request-and-response-limits) | +| Method-specific limits | Expensive methods such as `eth_call`, `eth_callMany`, `eth_feeHistory`, and `eth_getLogs` have additional execution or result constraints. | [Method-specific limits](../rpc/operations-and-limits.md#method-specific-limits) | +| Gateway caching | Eligible reads may be served from the gateway's internal cache. Cache policy depends on the method and selector, and `Cache-Control: no-store` only controls downstream caches. | [Gateway caching](../rpc/operations-and-limits.md#gateway-caching) | + +Use bounded ranges and pagination for large log or historical queries. +Retry `-32005` failures with exponential backoff and jitter instead of immediate repetition. +Inspect `X-Workers-Cache-Status` when you need to determine whether an eligible response came from the gateway cache. + +## Common tasks + +- Read an account balance with [`eth_getBalance`](../rpc/reference/eth_getBalance.md). +- Read contract storage with [`eth_getStorageAt`](../rpc/reference/eth_getStorageAt.md). +- Execute a read-only contract call with [`eth_call`](../rpc/reference/eth_call.md). +- Look up a transaction or receipt with [`eth_getTransactionByHash`](../rpc/reference/eth_getTransactionByHash.md) and [`eth_getTransactionReceipt`](../rpc/reference/eth_getTransactionReceipt.md). +- Query emitted events with [`eth_getLogs`](../rpc/reference/eth_getLogs.md). +- Stream real-time updates with [`eth_subscribe`](../rpc/reference/eth_subscribe.md). + +## Next steps + +- [JSON-RPC](../rpc/README.md) explains request framing, shared types, errors, and public gateway limits. +- [RPC Reference](../rpc/reference/README.md) lists method availability and the complete method documentation. +- [Realtime API](realtime-api.md) explains mini-block-level reads and WebSocket subscriptions. +- [Operations and limits](../rpc/operations-and-limits.md) documents rate limits, request limits, caching, and WebSocket limits. From 2774be275c4e01bb89041b6e4b6eb2661139987f Mon Sep 17 00:00:00 2001 From: William Aaron Cheung Date: Tue, 28 Jul 2026 09:52:24 +0800 Subject: [PATCH 13/13] docs: address RPC review feedback --- docs/dev/rpc/operations-and-limits.md | 18 ++++++++++--- docs/dev/rpc/reference/README.md | 2 -- .../reference/eth_getTransactionReceipt.md | 2 ++ .../reference/realtime_sendRawTransaction.md | 25 ++++++++++++++----- 4 files changed, 36 insertions(+), 11 deletions(-) diff --git a/docs/dev/rpc/operations-and-limits.md b/docs/dev/rpc/operations-and-limits.md index 13741a4..2675eb9 100644 --- a/docs/dev/rpc/operations-and-limits.md +++ b/docs/dev/rpc/operations-and-limits.md @@ -58,8 +58,20 @@ Reduce concurrency and query size before increasing retry frequency. ## Gateway caching -The public gateway caches eligible read methods internally. -Immutable block numbers and hashes can use longer-lived entries, while head-following reads use shorter policies or bypass the cache. +The public gateway has several internal caches. +Their eligibility and lifetime depend on the method and selector: immutable block numbers and hashes can use longer-lived entries, while head-following reads use shorter policies or bypass a cache layer. +See each method's reference page for its method-specific behavior. + +The gateway's Workers read-cache layer is limited to: + +- `eth_getBlockByNumber` +- `eth_getBlockReceipts` +- `eth_getHeaderByNumber` +- `web3_clientVersion` + +For the block-selecting methods in this layer, only an explicit historical block number, a block hash, or `earliest` is eligible. +The `latest`, `pending`, `safe`, and `finalized` tags bypass this layer. +Other gateway cache layers can still apply method-specific short-lived policies to head-following reads. Rate-limit accounting differs by request shape: @@ -68,7 +80,7 @@ Rate-limit accounting differs by request shape: Every public response includes `Cache-Control: no-store` for downstream caches. This header does not disable the gateway's internal cache. -`X-Workers-Cache-Status` indicates whether that internal cache returned the response. +For methods eligible for the Workers read-cache layer, `X-Workers-Cache-Status` indicates whether that layer returned the response. The gateway does not expose a request header or parameter that bypasses its internal cache. diff --git a/docs/dev/rpc/reference/README.md b/docs/dev/rpc/reference/README.md index b98f782..62af76c 100644 --- a/docs/dev/rpc/reference/README.md +++ b/docs/dev/rpc/reference/README.md @@ -83,8 +83,6 @@ Managed providers may expose additional methods. | `trace_transaction` | Unavailable | The public endpoint returns `-32601`. | | `web3_clientVersion` | Available | | -## Method Reference - ## State and simulation - [`eth_accounts`](./eth_accounts.md) diff --git a/docs/dev/rpc/reference/eth_getTransactionReceipt.md b/docs/dev/rpc/reference/eth_getTransactionReceipt.md index 8c2fee1..4fca92e 100644 --- a/docs/dev/rpc/reference/eth_getTransactionReceipt.md +++ b/docs/dev/rpc/reference/eth_getTransactionReceipt.md @@ -96,6 +96,8 @@ Capture date: July 24, 2026 Outcome: success +The captured response below is abridged. Receipts also include the other fields documented in [Result](#result), including `transactionIndex`, `cumulativeGasUsed`, `logs`, and `logsBloom`. + ```json { "jsonrpc": "2.0", diff --git a/docs/dev/rpc/reference/realtime_sendRawTransaction.md b/docs/dev/rpc/reference/realtime_sendRawTransaction.md index bb625d4..130d77e 100644 --- a/docs/dev/rpc/reference/realtime_sendRawTransaction.md +++ b/docs/dev/rpc/reference/realtime_sendRawTransaction.md @@ -73,19 +73,32 @@ Capture date: July 24, 2026 Outcome: success +The gateway routes this method and `eth_sendRawTransactionSync` through the same handler, so their successful receipt responses have the same structure: + ```json { "jsonrpc": "2.0", "id": 1, "result": { - "transactionHash": "0xf98a6b5de84ee59666d0ff3d8c361f308c3a22fc0bb94466810777d60a3ed7a7", - "blockNumber": "0x10", - "from": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266", - "to": "0xa7b8c275b3dde39e69a5c0ffd9f34f974364941a", - "gasUsed": "0x5208", + "type": "0x0", "status": "0x1", + "transactionHash": "0x8d3b1e22e7a9026c8658b5d922293d59e4de7c3382bb832d6890e6ab23ad7ec7", + "transactionIndex": "0x5", + "blockHash": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", + "blockNumber": "0xe7133c", + "from": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", + "to": "0xcc4b43ab7230cc5913801a746c1834aa06c4e7e7", + "gasUsed": "0xea60", + "effectiveGasPrice": "0xf4240", + "cumulativeGasUsed": "0x143043", + "contractAddress": null, "logs": [], - "contractAddress": null + "l1GasPrice": "0x3216", + "l1GasUsed": "0x640", + "l1Fee": "0x6da0", + "l1BaseFeeScalar": "0x558", + "l1BlobBaseFee": "0x1", + "l1BlobBaseFeeScalar": "0x0" } } ```