diff --git a/.gitbook.yaml b/.gitbook.yaml index 23dad3a..b415578 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -3,3 +3,60 @@ root: ./docs/ structure: readme: README.md summary: SUMMARY.md + +redirects: + 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/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/.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/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..14daac8 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). @@ -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 8c421a3..4db0bb2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -25,12 +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 - - [eth_subscribe](dev/read/rpc/eth_subscribe.md) - - [eth_callAfter](dev/read/rpc/eth_callAfter.md) - - [eth_getLogsWithCursor](dev/read/rpc/eth_getLogsWithCursor.md) - - [realtime_sendRawTransaction](dev/read/rpc/realtime_sendRawTransaction.md) - - [Error Codes](dev/read/rpc/error-codes.md) - [Transaction Execution](dev/execution/overview.md) - [Gas Model](dev/execution/gas-model.md) - [Resource Limits](dev/execution/resource-limits.md) @@ -40,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/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/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..1f55909 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? @@ -159,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 d7df4f5..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](read/overview.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 ead6ebd..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`](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/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 6a48866..4525cb5 100644 --- a/docs/dev/read/overview.md +++ b/docs/dev/read/overview.md @@ -1,171 +1,71 @@ --- -description: How to query state and data from MegaETH — JSON-RPC methods, rate limiting, subscriptions, and real-time queries. +description: How to read current state, historical data, transactions, logs, and real-time updates from MegaETH. --- # 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 introduces four extension methods for even 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. -{% 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 | | - -## 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, `eth_callAfter`, 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`, `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 - -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 | - -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 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. - -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. -Because only immutable data is cached, there is never a reason to bypass it. - -## 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 +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. diff --git a/docs/dev/read/realtime-api.md b/docs/dev/read/realtime-api.md index f666c5d..153eade 100644 --- a/docs/dev/read/realtime-api.md +++ b/docs/dev/read/realtime-api.md @@ -18,12 +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) | -| [`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) | +| 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`: @@ -46,15 +44,16 @@ 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. +**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`. ### Streaming events for a live UI **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. @@ -62,32 +61,16 @@ 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. -### 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). @@ -111,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](overview.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/read/rpc/error-codes.md b/docs/dev/read/rpc/error-codes.md deleted file mode 100644 index a384036..0000000 --- a/docs/dev/read/rpc/error-codes.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: MegaETH JSON-RPC error codes — HTTP status codes, RPC error codes, explanations, and mitigations. ---- - -# 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. | - -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 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_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_subscribe.md b/docs/dev/read/rpc/eth_subscribe.md deleted file mode 100644 index 3574602..0000000 --- a/docs/dev/read/rpc/eth_subscribe.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -description: eth_subscribe — WebSocket subscriptions for real-time logs, state changes, mini-blocks, and block headers on MegaETH. ---- - -# 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. - -Call `eth_unsubscribe` with the subscription ID when a subscription is no longer needed. - -{% 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 %} - -## Subscription Types - -### `logs` - -Streams event logs as transactions are packaged into mini-blocks. -Set both `fromBlock` and `toBlock` to `"pending"` for real-time delivery. - -**Parameters:** - -| 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 | - -**Example:** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": [ - "logs", - { - "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", - "topics": [ - "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902" - ], - "fromBlock": "pending", - "toBlock": "pending" - } - ] -} -``` - -Each notification uses the same schema as `eth_getLogs`. - -### `stateChanges` - -Streams account state changes as transactions are packaged into mini-blocks. -Takes a list of account addresses to monitor. - -**Parameters:** - -| Position | Type | Required | Notes | -| -------- | -------- | -------- | ------------------------------------ | -| `0` | `Data[]` | Yes | List of account addresses to monitor | - -**Example:** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["stateChanges", ["0x2ef038991d64c72646d4f06ba78d93f4f1654e3f"]] -} -``` - -**Notification schema:** - -| Field | Type | Notes | -| --------- | ----------------- | ------------------------------------ | -| `address` | `Data` (20 bytes) | Account address | -| `nonce` | `Number` | Latest nonce | -| `balance` | `Quantity` | Latest balance | -| `storage` | `Object` | Changed storage slots (slot → value) | - -**Example notification:** - -```json -{ - "address": "0x2ef038991d64c72646d4f06ba78d93f4f1654e3f", - "nonce": 1, - "balance": "0x16345785d8a0000", - "storage": { - "0xb6318d15e99499c465cc5e3d630975bf37b5641a8beb2614b018219310f4ea12": "0x68836e425f5", - "0xbf0f571b7368c19b53ab5ef0ff767ed8e0aef55a462778a6119b7871b017ce8f": "0x71094412456b0" - } -} -``` - -### `miniBlocks` - -Streams mini-blocks as they are produced by the sequencer. - -**Parameters:** None. - -**Example:** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["miniBlocks"] -} -``` - -**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) | - -### `newHeads` - -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. - -**Parameters:** None. - -**Example:** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "eth_subscribe", - "params": ["newHeads"] -} -``` - -## Errors - -| Code | Cause | Fix | -| -------- | ------------------------------------------------- | ---------------------------------- | -| `-32602` | Invalid subscription type or malformed parameters | Fix the request | -| `-32000` | WebSocket connection required | Use a WebSocket endpoint, not HTTP | - -See also [Error reference](error-codes.md). diff --git a/docs/dev/read/rpc/realtime_sendRawTransaction.md b/docs/dev/read/rpc/realtime_sendRawTransaction.md deleted file mode 100644 index 2ef86dd..0000000 --- a/docs/dev/read/rpc/realtime_sendRawTransaction.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: realtime_sendRawTransaction — submit a transaction and receive the receipt in a single call without polling. ---- - -# realtime_sendRawTransaction - -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. - -## Parameters - -| Position | Type | Required | Notes | -| -------- | ------ | -------- | ------------------------------ | -| `0` | `Data` | Yes | Hex-encoded signed transaction | - -## Returns - -A transaction receipt object on success: - -| Field | Type | Notes | -| ----------------- | ----------------- | ------------------------------------------------ | -| `transactionHash` | `Data` (32 bytes) | Hash of the submitted transaction | -| `blockNumber` | `Quantity` | Block containing the transaction | -| `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 | -| `logs` | `Log[]` | Event logs emitted during execution | -| `contractAddress` | `Data` (20 bytes) | Deployed contract address, or `null` | - -## Errors - -| Code | Cause | Fix | -| -------- | --------------------------------------------------------------------------- | ------------------------------------------------ | -| `-32000` | `realtime transaction expired` — transaction not executed within 10 seconds | Fall back to polling `eth_getTransactionReceipt` | - -See also [Error reference](error-codes.md). - -## Example - -```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"]}' -``` - -Successful response: - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "transactionHash": "0xf98a6b5de84ee59666d0ff3d8c361f308c3a22fc0bb94466810777d60a3ed7a7", - "blockNumber": "0x10", - "from": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266", - "to": "0xa7b8c275b3dde39e69a5c0ffd9f34f974364941a", - "gasUsed": "0x5208", - "status": "0x1", - "logs": [], - "contractAddress": null - } -} -``` - -Timeout response: - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "error": { - "code": -32000, - "message": "realtime transaction expired" - } -} -``` diff --git a/docs/dev/rpc/README.md b/docs/dev/rpc/README.md new file mode 100644 index 0000000..ed80c22 --- /dev/null +++ b/docs/dev/rpc/README.md @@ -0,0 +1,20 @@ +--- +description: MegaETH JSON-RPC endpoints, shared protocol conventions, operational limits, and method reference. +--- + +# JSON-RPC + +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. + +## Get started + +- [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. + +## RPC Reference + +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 new file mode 100644 index 0000000..e062809 --- /dev/null +++ b/docs/dev/rpc/error-codes.md @@ -0,0 +1,118 @@ +--- +description: Standard JSON-RPC, Ethereum, MegaETH, and public-gateway errors with retry guidance. +--- + +# Error reference + +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`. + +## Error surfaces + +| 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. | + +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/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..2675eb9 --- /dev/null +++ b/docs/dev/rpc/operations-and-limits.md @@ -0,0 +1,116 @@ +--- +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 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: + +- 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. +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. + +## 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..62af76c --- /dev/null +++ b/docs/dev/rpc/reference/README.md @@ -0,0 +1,156 @@ +--- +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 | | + +## 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/reference/debug_getHistoryTransactionCount.md b/docs/dev/rpc/reference/debug_getHistoryTransactionCount.md new file mode 100644 index 0000000..bc706c5 --- /dev/null +++ b/docs/dev/rpc/reference/debug_getHistoryTransactionCount.md @@ -0,0 +1,84 @@ +--- +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** + +Hex block number or tag (`earliest`, `latest`, `safe`, `finalized`). +`pending` is not supported. + +## Result + +**`result`** Quantity + +Cumulative transaction count across all blocks up to the selected block. +Consecutive blocks with no transactions return the same value. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "debug_getHistoryTransactionCount", + "params": ["0x12a05f"] +} +``` + +```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/rpc/reference/debug_getRawHeader.md b/docs/dev/rpc/reference/debug_getRawHeader.md new file mode 100644 index 0000000..d51a46d --- /dev/null +++ b/docs/dev/rpc/reference/debug_getRawHeader.md @@ -0,0 +1,78 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/debug_traceBlockByHash.md b/docs/dev/rpc/reference/debug_traceBlockByHash.md new file mode 100644 index 0000000..44ba3b0 --- /dev/null +++ b/docs/dev/rpc/reference/debug_traceBlockByHash.md @@ -0,0 +1,97 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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 supports `callTracer`. + +## 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/debug_traceBlockByNumber.md b/docs/dev/rpc/reference/debug_traceBlockByNumber.md new file mode 100644 index 0000000..6cee7f7 --- /dev/null +++ b/docs/dev/rpc/reference/debug_traceBlockByNumber.md @@ -0,0 +1,91 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/debug_traceTransaction.md b/docs/dev/rpc/reference/debug_traceTransaction.md new file mode 100644 index 0000000..4d2ff51 --- /dev/null +++ b/docs/dev/rpc/reference/debug_traceTransaction.md @@ -0,0 +1,88 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_accounts.md b/docs/dev/rpc/reference/eth_accounts.md new file mode 100644 index 0000000..58acf2b --- /dev/null +++ b/docs/dev/rpc/reference/eth_accounts.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** Address[] + +Accounts controlled by the RPC node; always empty on public endpoints. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 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": [] +} +``` + +## 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/rpc/reference/eth_blockNumber.md b/docs/dev/rpc/reference/eth_blockNumber.md new file mode 100644 index 0000000..9c7b9bf --- /dev/null +++ b/docs/dev/rpc/reference/eth_blockNumber.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** Quantity + +Current head block number; advances with each new block. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 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": 21, + "method": "eth_blockNumber", + "params": [] +} +``` + +```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/rpc/reference/eth_call.md b/docs/dev/rpc/reference/eth_call.md new file mode 100644 index 0000000..b579575 --- /dev/null +++ b/docs/dev/rpc/reference/eth_call.md @@ -0,0 +1,207 @@ +--- +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** + +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. + +## Result + +**`result`** Data + +Raw return bytes. +Calls to non-contract addresses return `0x`. +Reverts surface as JSON-RPC errors, not as a normal result. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +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" +} +``` + +## 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/rpc/reference/eth_callMany.md b/docs/dev/rpc/reference/eth_callMany.md new file mode 100644 index 0000000..c2d5d19 --- /dev/null +++ b/docs/dev/rpc/reference/eth_callMany.md @@ -0,0 +1,95 @@ +--- +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`. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 + +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_chainId.md b/docs/dev/rpc/reference/eth_chainId.md new file mode 100644 index 0000000..ba7530a --- /dev/null +++ b/docs/dev/rpc/reference/eth_chainId.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** Quantity + +The chain ID for the connected network. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 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": 31, + "method": "eth_chainId", + "params": [] +} +``` + +```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/rpc/reference/eth_createAccessList.md b/docs/dev/rpc/reference/eth_createAccessList.md new file mode 100644 index 0000000..9216f36 --- /dev/null +++ b/docs/dev/rpc/reference/eth_createAccessList.md @@ -0,0 +1,180 @@ +--- +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** + +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. + +## Result + +- **`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`. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +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 +{ + "jsonrpc": "2.0", + "id": 7, + "result": { + "accessList": [], + "gasUsed": "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/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/rpc/reference/eth_estimateGas.md b/docs/dev/rpc/reference/eth_estimateGas.md new file mode 100644 index 0000000..905b373 --- /dev/null +++ b/docs/dev/rpc/reference/eth_estimateGas.md @@ -0,0 +1,171 @@ +--- +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** + +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. + +## Result + +**`result`** Quantity + +Estimated execution gas. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 57, + "method": "eth_estimateGas", + "params": [ + { + "to": "0x0000000000000000000000000000000000000000", + "value": "0x0" + }, + "latest" + ] +} +``` + +```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/rpc/reference/eth_feeHistory.md b/docs/dev/rpc/reference/eth_feeHistory.md new file mode 100644 index 0000000..9cd7edd --- /dev/null +++ b/docs/dev/rpc/reference/eth_feeHistory.md @@ -0,0 +1,123 @@ +--- +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** + +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. + +## Result + +- **`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +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 +{ + "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] + } +} +``` + +## 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/rpc/reference/eth_gasPrice.md b/docs/dev/rpc/reference/eth_gasPrice.md new file mode 100644 index 0000000..90c0336 --- /dev/null +++ b/docs/dev/rpc/reference/eth_gasPrice.md @@ -0,0 +1,81 @@ +--- +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. + +## Result + +**`result`** Quantity + +Gas price in wei. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_gasPrice", + "params": [] +} +``` + +```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/rpc/reference/eth_getBalance.md b/docs/dev/rpc/reference/eth_getBalance.md new file mode 100644 index 0000000..aeb0fdd --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBalance.md @@ -0,0 +1,91 @@ +--- +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** + +Target account or contract address. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +## Result + +**`result`** Quantity + +Balance in wei. +The method returns a zero quantity for unknown accounts and zero-balance accounts alike. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getBalance", + "params": ["0x0000000000000000000000000000000000000000", "pending"] +} +``` + +```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/rpc/reference/eth_getBlockByHash.md b/docs/dev/rpc/reference/eth_getBlockByHash.md new file mode 100644 index 0000000..8eae2a7 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBlockByHash.md @@ -0,0 +1,130 @@ +--- +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** + +Target block hash. + +--- + +**`fullTransactions`** boolean **REQUIRED** + +`false` returns transaction hashes; `true` returns full transaction objects. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +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 +{ + "jsonrpc": "2.0", + "id": 74, + "result": { + "hash": "0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1", + "number": "0x100000", + "timestamp": "0x692225d3", + "transactions": [ + "0x243d39c7f6cd74a9a081a6fe4bdfce37ac6136b9454691aeeb9ed77998450cbc" + ] + } +} +``` + +## 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/rpc/reference/eth_getBlockByNumber.md b/docs/dev/rpc/reference/eth_getBlockByNumber.md new file mode 100644 index 0000000..47c417e --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBlockByNumber.md @@ -0,0 +1,152 @@ +--- +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** + +Hex block number or tag: `latest`, `safe`, `finalized`, `earliest`, `pending`. + +--- + +**`fullTransactions`** boolean **REQUIRED** + +`false` returns transaction hashes; `true` returns full transaction objects. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +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": 81, + "method": "eth_getBlockByNumber", + "params": ["0x100000", false] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 81, + "result": { + "hash": "0xe0b5b2b8222c00dcbe9f359fc917a9190127bd1b958e11b6caa2035dd03952f1", + "number": "0x100000", + "timestamp": "0x692225d3", + "transactions": [ + "0x243d39c7f6cd74a9a081a6fe4bdfce37ac6136b9454691aeeb9ed77998450cbc" + ] + } +} +``` + +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/rpc/reference/eth_getBlockReceipts.md b/docs/dev/rpc/reference/eth_getBlockReceipts.md new file mode 100644 index 0000000..860a146 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBlockReceipts.md @@ -0,0 +1,154 @@ +--- +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. + +## Result + +`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 + + A nonzero status indicates success; zero indicates that execution reverted. + +- **`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.). + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +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" + } + ] +} +``` + +```json +{ + "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", + "effectiveGasPrice": "0x0", + "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001", + "to": "0x4200000000000000000000000000000000000015", + "contractAddress": null, + "l1GasPrice": "0x22ba611d", + "l1GasUsed": "0x6e7", + "l1Fee": "0x0", + "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/rpc/reference/eth_getBlockTransactionCountByHash.md b/docs/dev/rpc/reference/eth_getBlockTransactionCountByHash.md new file mode 100644 index 0000000..da271d6 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBlockTransactionCountByHash.md @@ -0,0 +1,83 @@ +--- +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. + +## Result + +**`result`** Quantity | null + +Transaction count; `null` when the block is not found. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "eth_getBlockTransactionCountByHash", + "params": [ + "0xa97b8563203de36f0c8430709734438fbf7f2444b6de9f307853fc46b230de3e" + ] +} +``` + +```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/rpc/reference/eth_getBlockTransactionCountByNumber.md b/docs/dev/rpc/reference/eth_getBlockTransactionCountByNumber.md new file mode 100644 index 0000000..c0240c2 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getBlockTransactionCountByNumber.md @@ -0,0 +1,81 @@ +--- +description: "eth_getBlockTransactionCountByNumber JSON-RPC reference for MegaETH." +--- + +# 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`. + +## Result + +**`result`** Quantity | null + +Transaction count; `null` when the block is not found. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 4, + "method": "eth_getBlockTransactionCountByNumber", + "params": ["0xb11362"] +} +``` + +```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/rpc/reference/eth_getCode.md b/docs/dev/rpc/reference/eth_getCode.md new file mode 100644 index 0000000..240e5fd --- /dev/null +++ b/docs/dev/rpc/reference/eth_getCode.md @@ -0,0 +1,90 @@ +--- +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** + +Target account or contract address. + +--- + +**`block`** string + +Hex block number, block hash, or tag (`latest`, `safe`, `finalized`, …). +The default is `"latest"`. + +## Result + +**`result`** Data + +Runtime bytecode (not creation bytecode) at the address; `0x` when no code is deployed. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "eth_getCode", + "params": ["0x4200000000000000000000000000000000000011", "latest"] +} +``` + +```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/rpc/reference/eth_getCodeByHash.md b/docs/dev/rpc/reference/eth_getCodeByHash.md new file mode 100644 index 0000000..5f77db0 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getCodeByHash.md @@ -0,0 +1,84 @@ +--- +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. + +## Result + +**`result`** Data + +Runtime bytecode; `0x` when no bytecode is stored for that hash. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 43, + "method": "eth_getCodeByHash", + "params": [ + "0xfa8c9db6c6cab7108dea276f4cd09d575674eb0852c0fa3187e59e98ef977998" + ] +} +``` + +```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/rpc/reference/eth_getHeaderByHash.md b/docs/dev/rpc/reference/eth_getHeaderByHash.md new file mode 100644 index 0000000..ef10d4f --- /dev/null +++ b/docs/dev/rpc/reference/eth_getHeaderByHash.md @@ -0,0 +1,118 @@ +--- +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. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +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": 26, + "method": "eth_getHeaderByHash", + "params": [ + "0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0" + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 26, + "result": { + "hash": "0x6f3fcff78eefe9591d2ad590b8a78738b8ad80d9646eccd302618cd9198b73e0", + "parentHash": "0x6b6b52368c21dcdba7348fa37edae3e945013627a83a96b64d55217696899d30", + "stateRoot": "0xf328fa2752aea1c211a73067d17c25d09a416b4b6a7785441f39bcc930028717", + "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/rpc/reference/eth_getHeaderByNumber.md b/docs/dev/rpc/reference/eth_getHeaderByNumber.md new file mode 100644 index 0000000..0d408ff --- /dev/null +++ b/docs/dev/rpc/reference/eth_getHeaderByNumber.md @@ -0,0 +1,116 @@ +--- +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`. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +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": 27, + "method": "eth_getHeaderByNumber", + "params": ["0xb11048"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 27, + "result": { + "hash": "0x235d80b5e91125a1a1d6da6776c6a9ee087d1818c494f71736b09bed61b1411e", + "parentHash": "0x6fc0412abfba89bbfab17b2d8bd36cb1c214c1d53ed213fa8958439d0c4f9c18", + "stateRoot": "0x301d7b77a74893451bd76e5d1672aaaa493cd78c06d59e885218d48917a35c03", + "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/rpc/reference/eth_getLogs.md b/docs/dev/rpc/reference/eth_getLogs.md new file mode 100644 index 0000000..728b8c6 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getLogs.md @@ -0,0 +1,164 @@ +--- +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** + +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. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +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" + ] + } + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 110, + "result": [ + { + "address": "0xf818c8da51f9a712cfbcddd44d0c445fa1a104e6", + "topics": [ + "0x994d1f10d7d73f3765b557bce9826b2fafd1bad3862fa6192211b39a12183815", + "0x00000000000000000000000000000000000000000000000000000000000000d8" + ], + "data": "0x0000000000000000000954150000002f000000000000d6d800000000006ec9a2", + "blockNumber": "0xb120c6", + "blockTimestamp": "0x69c34699", + "transactionHash": "0xf3473347041eb4ccc045ee58e6c79c80d98ee4aa783d49e49c69d0a0e50d8ed6", + "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/rpc/reference/eth_getStorageAt.md b/docs/dev/rpc/reference/eth_getStorageAt.md new file mode 100644 index 0000000..5c939ca --- /dev/null +++ b/docs/dev/rpc/reference/eth_getStorageAt.md @@ -0,0 +1,100 @@ +--- +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** + +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"`. + +## 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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +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": 63, + "method": "eth_getStorageAt", + "params": [ + "0x4200000000000000000000000000000000000011", + "0x0000000000000000000000000000000000000000000000000000000000000000", + "0xb11048" + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 63, + "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/rpc/reference/eth_getTransactionByHash.md b/docs/dev/rpc/reference/eth_getTransactionByHash.md new file mode 100644 index 0000000..28db8f7 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getTransactionByHash.md @@ -0,0 +1,138 @@ +--- +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. + +## Result + +`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.). + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +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 +{ + "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" + } +} +``` + +## 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/rpc/reference/eth_getTransactionCount.md b/docs/dev/rpc/reference/eth_getTransactionCount.md new file mode 100644 index 0000000..8ad31b7 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getTransactionCount.md @@ -0,0 +1,91 @@ +--- +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** + +Target account address. + +--- + +**`block`** string + +Hex block number or tag (`latest`, `safe`, `finalized`, `earliest`, `pending`). +The default is `"latest"`. + +## Result + +**`result`** Quantity + +Transaction count at the requested block. +The method returns a zero quantity for both unknown accounts and accounts with zero transactions. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 91, + "method": "eth_getTransactionCount", + "params": ["0xa344fb2d117501ee379d2ea9c0c016959ad94f1e", "0xb120c6"] +} +``` + +```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/rpc/reference/eth_getTransactionReceipt.md b/docs/dev/rpc/reference/eth_getTransactionReceipt.md new file mode 100644 index 0000000..4fca92e --- /dev/null +++ b/docs/dev/rpc/reference/eth_getTransactionReceipt.md @@ -0,0 +1,137 @@ +--- +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. + +## Result + +`Receipt | null` — `null` when the transaction is unknown or not yet mined. + +- **`transactionHash`** Hash32 + + Transaction hash. + +- **`status`** Quantity + + A nonzero status indicates success; zero indicates that execution reverted. + +- **`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.). + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 Codes](../error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +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", + "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" + } +} +``` + +## 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/rpc/reference/eth_getUncleByBlockHashAndIndex.md b/docs/dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md new file mode 100644 index 0000000..9461fa9 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getUncleByBlockHashAndIndex.md @@ -0,0 +1,80 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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 + +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md b/docs/dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md new file mode 100644 index 0000000..d4d5bd9 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getUncleByBlockNumberAndIndex.md @@ -0,0 +1,77 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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 + +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_getUncleCountByBlockHash.md b/docs/dev/rpc/reference/eth_getUncleCountByBlockHash.md new file mode 100644 index 0000000..f8a22ae --- /dev/null +++ b/docs/dev/rpc/reference/eth_getUncleCountByBlockHash.md @@ -0,0 +1,79 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_getUncleCountByBlockNumber.md b/docs/dev/rpc/reference/eth_getUncleCountByBlockNumber.md new file mode 100644 index 0000000..ef17958 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getUncleCountByBlockNumber.md @@ -0,0 +1,77 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_getWithdrawalProof.md b/docs/dev/rpc/reference/eth_getWithdrawalProof.md new file mode 100644 index 0000000..b815826 --- /dev/null +++ b/docs/dev/rpc/reference/eth_getWithdrawalProof.md @@ -0,0 +1,91 @@ +--- +description: "Returns a withdrawal-storage proof for MegaETH's L2-to-L1 message passer contract." +--- + +# 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 | +| -------- | ------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `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. | + +## Result + +An EIP-1186-style account proof containing `accountProof`, `balance`, `codeHash`, `nonce`, `storageHash`, and one `storageProof` entry per requested key. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_getWithdrawalProof", + "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/rpc/reference/eth_maxPriorityFeePerGas.md b/docs/dev/rpc/reference/eth_maxPriorityFeePerGas.md new file mode 100644 index 0000000..888fe8f --- /dev/null +++ b/docs/dev/rpc/reference/eth_maxPriorityFeePerGas.md @@ -0,0 +1,81 @@ +--- +description: "eth_maxPriorityFeePerGas JSON-RPC reference for MegaETH." +--- + +# eth_maxPriorityFeePerGas + +## Summary + +Returns the recommended priority fee per gas in wei. +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. + +## Result + +**`result`** Quantity + +Always a zero-wei quantity. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## 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" +} +``` + +## 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/rpc/reference/eth_protocolVersion.md b/docs/dev/rpc/reference/eth_protocolVersion.md new file mode 100644 index 0000000..0eba374 --- /dev/null +++ b/docs/dev/rpc/reference/eth_protocolVersion.md @@ -0,0 +1,74 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. +Callers should not use this value 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 + +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_sendRawTransaction.md b/docs/dev/rpc/reference/eth_sendRawTransaction.md new file mode 100644 index 0000000..78ee997 --- /dev/null +++ b/docs/dev/rpc/reference/eth_sendRawTransaction.md @@ -0,0 +1,85 @@ +--- +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, EIP-1559, EIP-4844, and EIP-7702. + +## Result + +**`result`** Data + +32-byte transaction hash. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 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": "eth_sendRawTransaction", + "params": [ + "0xf86c808405763d658261a894aa000000000000000000000000000000000000000a8255448718e5bb3abd109fa0c8e3b4a0087357bd49d80a0ac24daf0c91191e71086c1e355fc62cfab2218873a074f4636f740fa4d1697b6e736e5982b700be2c8b63031a24fa531ae4814b3af8" + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "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/rpc/reference/eth_sendRawTransactionSync.md b/docs/dev/rpc/reference/eth_sendRawTransactionSync.md new file mode 100644 index 0000000..29d5926 --- /dev/null +++ b/docs/dev/rpc/reference/eth_sendRawTransactionSync.md @@ -0,0 +1,152 @@ +--- +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** + +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). + +## Result + +- **`transactionHash`** Hash32 + + Transaction hash. + +- **`status`** Quantity + + A nonzero status indicates success; zero means the transaction reverted but was included on-chain. + +- **`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 + + 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.). + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 91, + "result": { + "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": [], + "l1GasPrice": "0x3216", + "l1GasUsed": "0x640", + "l1Fee": "0x6da0", + "l1BaseFeeScalar": "0x558", + "l1BlobBaseFee": "0x1", + "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/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/reference/eth_syncing.md b/docs/dev/rpc/reference/eth_syncing.md new file mode 100644 index 0000000..268381e --- /dev/null +++ b/docs/dev/rpc/reference/eth_syncing.md @@ -0,0 +1,90 @@ +--- +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. + +## Result + +`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_syncing", + "params": [] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "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/rpc/reference/eth_uninstallFilter.md b/docs/dev/rpc/reference/eth_uninstallFilter.md new file mode 100644 index 0000000..3c37c29 --- /dev/null +++ b/docs/dev/rpc/reference/eth_uninstallFilter.md @@ -0,0 +1,78 @@ +--- +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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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) +- Probe: MegaETH Mainnet public endpoint, July 24, 2026 diff --git a/docs/dev/rpc/reference/eth_unsubscribe.md b/docs/dev/rpc/reference/eth_unsubscribe.md new file mode 100644 index 0000000..133e049 --- /dev/null +++ b/docs/dev/rpc/reference/eth_unsubscribe.md @@ -0,0 +1,80 @@ +--- +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`. + +## Result + +**`result`** boolean + +`true` if the subscription was found and cancelled; `false` if the ID was not active. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 + +Endpoint: `wss://mainnet.megaeth.com/ws` (WebSocket) + +Capture date: July 24, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_unsubscribe", + "params": ["0xaec58cfc2dc41f873fc37d6c871230c1"] +} +``` + +```json +{ + "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/rpc/reference/mega_getBlockWitness.md b/docs/dev/rpc/reference/mega_getBlockWitness.md new file mode 100644 index 0000000..6657c34 --- /dev/null +++ b/docs/dev/rpc/reference/mega_getBlockWitness.md @@ -0,0 +1,111 @@ +--- +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** + +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. + +- **`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`, or the paired `parentHash` and `attributesHash`, for production verification. +{% endhint %} + +## Result + +**`result`** string + +`v0:` followed by a base64-encoded zstd-compressed witness blob. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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 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": "mega_getBlockWitness", + "params": [ + { + "blockNumber": "0x7fd", + "blockHash": "0x262206173864c1e597ab9fcf2f718f95f942907207f4fed97dda66d272c5d4a6" + } + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "v0:KLUv/QBgzVUAZJwh\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/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/rpc/reference/mega_getWithdrawalProof.md b/docs/dev/rpc/reference/mega_getWithdrawalProof.md new file mode 100644 index 0000000..119914e --- /dev/null +++ b/docs/dev/rpc/reference/mega_getWithdrawalProof.md @@ -0,0 +1,128 @@ +--- +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** + +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. + +## Result + +- **`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[]`). + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +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": "mega_getWithdrawalProof", + "params": ["0x4200000000000000000000000000000000000016", [], "latest"] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "address": "0x4200000000000000000000000000000000000016", + "balance": "0x0", + "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + "nonce": "0x0", + "storageHash": "0xddd6dcaf75eeb81fb4701c2a39b3132bd60bf9602e2fcbe5852f5d07e14c8084", + "accountProof": [], + "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/rpc/reference/mega_outputAtBlock.md b/docs/dev/rpc/reference/mega_outputAtBlock.md new file mode 100644 index 0000000..28f4dfa --- /dev/null +++ b/docs/dev/rpc/reference/mega_outputAtBlock.md @@ -0,0 +1,149 @@ +--- +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. + +## Result + +- **`version`** Hash32, optional + + Output version. Fresh upstream responses can include it, while the gateway's cached projection currently omits it. + +- **`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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "mega_outputAtBlock", + "params": ["0x154de48"] +} +``` + +The captured response below is abridged; `syncStatus` contains additional L1 and L2 progress fields. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "outputRoot": "0xf90851c88ec4adfe04b03f33beab99bbabbd73fc474ab7b3a8fa109a3913f047", + "blockRef": { + "hash": "0xce5344be15fecbe70574c97e57626f79a0816e8ebfc37a53ad535e82dd2def56", + "number": 22339144, + "parentHash": "0x85f2e75f7be8967a319af7de35275ad257150f80ae243b97f07b45332d3476a1", + "timestamp": 1785136155, + "l1origin": { + "hash": "0xf79fbbd55e49baaff2f61e027b424b1b5b1ef7cd58bd7d664eb39947352b2f73", + "number": 25622475 + }, + "sequenceNumber": 137 + }, + "syncStatus": { + "head_l1": { + "number": 25622556 + } + }, + "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/rpc/reference/net_listening.md b/docs/dev/rpc/reference/net_listening.md new file mode 100644 index 0000000..c3b45ce --- /dev/null +++ b/docs/dev/rpc/reference/net_listening.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** boolean + +Always `true`. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## 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 +} +``` + +## 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/rpc/reference/net_peerCount.md b/docs/dev/rpc/reference/net_peerCount.md new file mode 100644 index 0000000..56d5de9 --- /dev/null +++ b/docs/dev/rpc/reference/net_peerCount.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** Quantity + +Number of connected peers. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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). + +## 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" +} +``` + +## 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/rpc/reference/net_version.md b/docs/dev/rpc/reference/net_version.md new file mode 100644 index 0000000..bdd84de --- /dev/null +++ b/docs/dev/rpc/reference/net_version.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** string + +Network ID as a decimal integer string. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 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" +} +``` + +## 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/rpc/reference/optimism_outputAtBlock.md b/docs/dev/rpc/reference/optimism_outputAtBlock.md new file mode 100644 index 0000000..2d85b7b --- /dev/null +++ b/docs/dev/rpc/reference/optimism_outputAtBlock.md @@ -0,0 +1,100 @@ +--- +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. | + +## 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. + +## Comparison with Ethereum Standard JSON-RPC + +### Ethereum Standard + +`optimism_outputAtBlock` is not part of the core Ethereum execution JSON-RPC API. It is an OP Stack extension. + +### MegaETH Node Behavior + +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. + +## 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). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +Capture date: July 27, 2026 + +Outcome: success + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "optimism_outputAtBlock", + "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/rpc/reference/realtime_sendRawTransaction.md b/docs/dev/rpc/reference/realtime_sendRawTransaction.md new file mode 100644 index 0000000..130d77e --- /dev/null +++ b/docs/dev/rpc/reference/realtime_sendRawTransaction.md @@ -0,0 +1,122 @@ +--- +description: realtime_sendRawTransaction — submit a transaction and receive the receipt in a single call without polling. +--- + +# 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 | +| -------- | -------- | -------- | ------------------------------------------------------------- | +| `0` | `Data` | Yes | Hex-encoded signed transaction | +| `1` | `number` | No | Wait timeout in milliseconds; capped at `3000` by the gateway | + +## Result + +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) | +| `gasUsed` | `Quantity` | Gas consumed by the transaction | +| `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. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## Errors + +The `| Scope |` column distinguishes method failures from gateway policy errors. + +| 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. | + +See also [Error Codes](../error-codes.md). + +## Examples + +Endpoint: `https://mainnet.megaeth.com/rpc` + +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": { + "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": [], + "l1GasPrice": "0x3216", + "l1GasUsed": "0x640", + "l1Fee": "0x6da0", + "l1BaseFeeScalar": "0x558", + "l1BlobBaseFee": "0x1", + "l1BlobBaseFeeScalar": "0x0" + } +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32000, + "message": "realtime transaction expired" + } +} +``` + +## 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/rpc/reference/web3_clientVersion.md b/docs/dev/rpc/reference/web3_clientVersion.md new file mode 100644 index 0000000..3745c69 --- /dev/null +++ b/docs/dev/rpc/reference/web3_clientVersion.md @@ -0,0 +1,80 @@ +--- +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. + +## Result + +**`result`** string + +Client name, version, and build target. + +## Comparison with Ethereum Standard JSON-RPC + +### 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. + +## 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 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": "web3_clientVersion", + "params": [] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "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/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 3c9d519..79a52f8 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`](#simulating-a-new-transaction) 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`](../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](../read/overview.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 11938e7..41b1270 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 @@ -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 [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](../read/overview.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 42df71b..d99a508 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 %} @@ -119,8 +120,8 @@ 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. -See [`realtime_sendRawTransaction`](../read/rpc/realtime_sendRawTransaction.md) for the full reference. +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/reference/realtime_sendRawTransaction.md) for the full reference. {% endtab %} {% endtabs %} diff --git a/docs/mini-block.md b/docs/mini-block.md index 1e02fb8..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/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/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/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/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/read/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