From 6ec3745ddb026786d9e3c715e4137b2d75b13226 Mon Sep 17 00:00:00 2001 From: airdropzamani Date: Mon, 31 Aug 2026 15:54:27 +0300 Subject: [PATCH 1/2] docs: classify JSON-RPC breaking changes for application developers Add an [RPC] flag and For Application Developers sections in BREAKING_CHANGES.md, clarifying that --rpc.gascap is a node-local simulation limit distinct from protocol gas limits. Fixes #270 and #271. Co-authored-by: Cursor --- BREAKING_CHANGES.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index 81f831c..8354d76 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -7,8 +7,9 @@ Each bullet is prefixed with a flag identifying the kind of breaking change: - `[CLI]` -- CLI flag added, renamed, removed, or made required. - `[Config]` -- default value, environment variable, or manifest field change. - `[Format]` -- log, metric label, or serialized output format change that breaks parsers. +- `[RPC]` -- JSON-RPC semantics, limits, defaults, validation, or error behavior changed for application callers. -Entries are split by audience. A change appears under `### For Validators` when validator-mode operation must change; otherwise it appears under `### For Node Operators`. A change requiring both audiences to act appears in both sections (rare). +Entries are split by audience. A change appears under `### For Validators` when validator-mode operation must change; under `### For Application Developers` when dApps, SDKs, wallets, or other JSON-RPC consumers may observe different behavior after a node upgrade (even when the method signatures are unchanged); otherwise it appears under `### For Node Operators`. A change requiring multiple audiences to act appears in each relevant section. Compare and release-notes links resolve once the corresponding tag is published at [`circlefin/arc-node`](https://github.com/circlefin/arc-node). @@ -37,6 +38,13 @@ Compare and release-notes links resolve once the corresponding tag is published - **[Config] Execution-layer pruning presets now inject a 128-block pruning interval.** - `node --full` and `node --minimal` previously injected `5000`. Set `--prune.block-interval=5000` explicitly to retain that schedule. +### For Application Developers + +- **[RPC] JSON-RPC error text on insufficient-balance `eth_call` / `eth_estimateGas` changed with the reth 2.2 / revm 38 upgrade.** + - Value exceeds balance: the error previously read `insufficient funds for gas * price + value`; it now reflects revm 38's `OutOfFunds` variant. + - Simple (EOA-to-EOA) transfer with insufficient balance: the surfaced error shifted from `Missing or invalid parameters` to `gas required exceeds allowance`. + - Tooling that matches JSON-RPC error text on these paths (ethers, viem, wagmi, wallets, etc.) must update its patterns. This is an RPC error-surface change, not a protocol consensus change. + ## [v0.7.3] **Changes:** [v0.7.2...v0.7.3](https://github.com/circlefin/arc-node/compare/v0.7.2...v0.7.3) -- [release notes](https://github.com/circlefin/arc-node/releases/tag/v0.7.3) @@ -51,7 +59,7 @@ No breaking changes in this release. ### For Node Operators -- **[Config] `arc-node-execution`: JSON-RPC gas cap default lowered.** +- **[Config] `arc-node-execution`: JSON-RPC gas cap default lowered.** Also affects application callers; see `### For Application Developers` below. - Old (`v0.7.1`): `--rpc.gascap` default `50000000` (Reth stock default). - New (`v0.7.2`): `--rpc.gascap` default `30000000`. - `eth_call` and `eth_estimateGas` requests that need more than 30M gas now fail with a gas-cap error. Pass `--rpc.gascap 50000000` (or higher) to restore the previous budget. Operators who never set the flag and do not rely on calls above 30M gas are unaffected. @@ -71,6 +79,21 @@ No breaking changes in this release. - New (`v0.7.2`): default `true`. On a payload-builder panic, all pending transactions are added to the list and removed from the mempool; resubmit them after investigating the panic. - Opt out with `--invalid-tx-list-enable=false`. +### For Application Developers + +- **[RPC] `arc-node-execution`: JSON-RPC gas cap default lowered.** + - Old (`v0.7.1`): `--rpc.gascap` default `50000000` (Reth stock default). + - New (`v0.7.2`): `--rpc.gascap` default `30000000`. + - `--rpc.gascap` limits gas available to applicable JSON-RPC simulation paths (`eth_call`, `eth_estimateGas`). Reaching this limit does **not** necessarily mean the corresponding transaction exceeds Arc's protocol-level transaction or block gas limits — it may mean the node-local RPC simulation budget was exhausted first. + - `eth_call` and `eth_estimateGas` requests that need more than 30M gas now fail (typically surfacing an out-of-gas style error). This is not the same as an on-chain execution revert or a protocol gas-limit rejection. + - Application developers should not treat gas-estimation failures after a node upgrade as proof that a transaction is impossible on-chain. Retry against a node with a higher cap, or ask the operator to raise `--rpc.gascap`. + +- **[RPC] `arc-node-execution`: replay-unprotected (pre-EIP-155) transactions are rejected over JSON-RPC by default.** + - Applications submitting legacy unprotected transactions over RPC now receive `"only replay-protected (EIP-155) transactions allowed over RPC"` unless the operator enables `--arc.rpc.allow-unprotected-txs`. + +- **[RPC] `arc-node-execution`: JSON-RPC batch requests are capped.** + - Batches larger than `--arc.rpc.max-batch-entries` (default `100`) are rejected with JSON-RPC error `-32600` before any per-entry handler runs. + ## [v0.7.1] **Changes:** [v0.7.0...v0.7.1](https://github.com/circlefin/arc-node/compare/v0.7.0...v0.7.1) -- [release notes](https://github.com/circlefin/arc-node/releases/tag/v0.7.1) From 9cf3f0487005798e6c1596b3d2c59e53d0c81cb6 Mon Sep 17 00:00:00 2001 From: airdropzamani Date: Tue, 1 Sep 2026 01:05:00 +0300 Subject: [PATCH 2/2] docs: drop v0.8.0 app section; clarify gascap allowance errors Address review on #297: scope application-facing notes to v0.7.2 (v0.8.0 error-text matrix is tracked in #291) and document the gas required exceeds allowance string collision. Co-authored-by: Cursor --- BREAKING_CHANGES.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index 8354d76..c3680b5 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -38,13 +38,6 @@ Compare and release-notes links resolve once the corresponding tag is published - **[Config] Execution-layer pruning presets now inject a 128-block pruning interval.** - `node --full` and `node --minimal` previously injected `5000`. Set `--prune.block-interval=5000` explicitly to retain that schedule. -### For Application Developers - -- **[RPC] JSON-RPC error text on insufficient-balance `eth_call` / `eth_estimateGas` changed with the reth 2.2 / revm 38 upgrade.** - - Value exceeds balance: the error previously read `insufficient funds for gas * price + value`; it now reflects revm 38's `OutOfFunds` variant. - - Simple (EOA-to-EOA) transfer with insufficient balance: the surfaced error shifted from `Missing or invalid parameters` to `gas required exceeds allowance`. - - Tooling that matches JSON-RPC error text on these paths (ethers, viem, wagmi, wallets, etc.) must update its patterns. This is an RPC error-surface change, not a protocol consensus change. - ## [v0.7.3] **Changes:** [v0.7.2...v0.7.3](https://github.com/circlefin/arc-node/compare/v0.7.2...v0.7.3) -- [release notes](https://github.com/circlefin/arc-node/releases/tag/v0.7.3) @@ -85,8 +78,8 @@ No breaking changes in this release. - Old (`v0.7.1`): `--rpc.gascap` default `50000000` (Reth stock default). - New (`v0.7.2`): `--rpc.gascap` default `30000000`. - `--rpc.gascap` limits gas available to applicable JSON-RPC simulation paths (`eth_call`, `eth_estimateGas`). Reaching this limit does **not** necessarily mean the corresponding transaction exceeds Arc's protocol-level transaction or block gas limits — it may mean the node-local RPC simulation budget was exhausted first. - - `eth_call` and `eth_estimateGas` requests that need more than 30M gas now fail (typically surfacing an out-of-gas style error). This is not the same as an on-chain execution revert or a protocol gas-limit rejection. - - Application developers should not treat gas-estimation failures after a node upgrade as proof that a transaction is impossible on-chain. Retry against a node with a higher cap, or ask the operator to raise `--rpc.gascap`. + - `eth_call` and `eth_estimateGas` requests that need more than 30M gas now fail. The failure often surfaces as `gas required exceeds allowance ()` or an out-of-gas style error — the same allowance string is also used when the sender's balance-derived gas budget is exhausted, so compare the parenthesized `` against the node's configured `--rpc.gascap` to tell a cap rejection from a balance rejection. This is not the same as an on-chain execution revert or a protocol gas-limit rejection. + - Application developers should not treat gas-estimation failures after a node upgrade as proof that a transaction is impossible on-chain. Retry against a node with a higher cap, or ask the operator to raise `--rpc.gascap`. Public RPC endpoints may apply a lower effective cap than the repo default. - **[RPC] `arc-node-execution`: replay-unprotected (pre-EIP-155) transactions are rejected over JSON-RPC by default.** - Applications submitting legacy unprotected transactions over RPC now receive `"only replay-protected (EIP-155) transactions allowed over RPC"` unless the operator enables `--arc.rpc.allow-unprotected-txs`.