docs: add complete public RPC reference

.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

.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.

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
 

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
 

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

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
 

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" %}

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?
 

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

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