Repository navigation
docs: classify JSON-RPC behavior changes as application-facing breaking changes #270
Description
Summary
BREAKING_CHANGES.md currently categorizes breaking changes primarily in terms of node-operator concerns such as CLI flags, configuration defaults, and serialized/log output.
However, some node configuration changes also alter externally observable JSON-RPC behavior for applications.
A concrete example is the v0.7.2 reduction of the default RPC gas cap from 50,000,000 to 30,000,000.
After upgrading a node with otherwise unchanged configuration, an application can observe previously successful eth_call or eth_estimateGas requests begin failing.
This is therefore not only a node-operator configuration change. It is also an application compatibility change.
Current Behavior
The v0.7.2 breaking-change entry documents:
- old
--rpc.gascapdefault:50000000 - new
--rpc.gascapdefault:30000000
and explains that calls requiring more than 30M gas will now fail.
However, the breaking-change taxonomy does not provide a distinct category for changes to externally visible JSON-RPC behavior.
As a result, dApp developers, SDK maintainers, infrastructure providers, and RPC consumers may not realize that a node upgrade can change application behavior even when the JSON-RPC API itself has not changed.
Expected Behavior
Application-facing RPC compatibility changes should be explicitly classified in BREAKING_CHANGES.md.
For example:
[RPC] -- JSON-RPC semantics, limits, defaults, or externally observable behavior changed.
The v0.7.2 entry could then be represented as both:
[Config] default --rpc.gascap changed from 50M to 30M.
[RPC] eth_call and eth_estimateGas requests requiring >30M gas may now fail.
Why This Matters
RPC behavior is effectively part of Arc’s developer-facing interface.
Changes to:
- gas caps
- request limits
- transaction validation
- WebSocket subscription limits
- simulation behavior
- error responses
can break applications even though no Solidity contract or JSON-RPC method signature changed.
Treating these solely as operator configuration changes makes it harder for application developers to determine whether an Arc upgrade can affect their software.
Suggested Fix
Add an application-facing breaking-change category to BREAKING_CHANGES.md, for example:
[RPC]-- JSON-RPC semantics, limits, defaults, validation, or error behavior changed.
Consider also adding:
[App]-- externally observable behavior changed in a way that may require dApp or SDK changes.
Then annotate applicable historical entries, especially the v0.7.x RPC changes.
Activity
osr21 commentedon Aug 17, 2026
I went through the current
BREAKING_CHANGES.mdagainst this proposal, and the gap you're describing is real and concrete — the doc's own v0.7.x entries already prove the point.The taxonomy is operator-only today. The three flags defined at the top are
[CLI](flag added/renamed/removed),[Config](default/env/manifest value), and[Format](log/metric/serialized output). All three frame the change by what the operator edits, never by what an external caller observes. Reinforcing that, entries are split into### For Node Operatorsand### For Validators— there is no application-developer audience at all. So an app/SDK maintainer scanning the file has no flag to grep for and no section that's addressed to them.Your gascap example is not isolated — several v0.7.x entries are app-facing but filed as
[Config]/[CLI]for operators:--rpc.gascap50M → 30M.eth_call/eth_estimateGasabove 30M now fail. (Your example; filed[Config].)[CLI].)--arc.rpc.max-batch-entriesdefaults to 100; oversized batches are rejected with JSON-RPC-32600before any per-entry handler runs. Any SDK/tooling batching >100 calls sees a hard error. (Filed[Config].)--rpc.max-subscriptions-per-connection1024 → 32. A WS client opening >32 subscriptions per socket now fails. (Filed[Config].)That's four externally-observable RPC behavior changes across two releases, none of which are discoverable as app-facing under the current flags. This is strong evidence for the
[RPC]category rather than a one-off.One refinement on the proposal. I'd land
[RPC]and skip[App]for now.[RPC]is crisply defined (JSON-RPC semantics, limits, defaults, validation, error responses) and covers every example above.[App]as "externally observable behavior changed" is broad enough to overlap[RPC]and[Format](log/serialized output is arguably app-observable too), which risks ambiguous double-tagging. If a distinct non-RPC app-facing class shows up later, add it then with a sharp boundary.On dual-tagging + audience: the doc already supports a change appearing in both audience sections ("rare"), so annotating an entry as both
[Config](operator restores old default) and[RPC](caller-visible effect) fits the existing structure. It would also help to either add a short### For Application Developerssubsection or explicitly note that[RPC]-tagged entries are relevant to dApp/SDK/RPC-provider consumers, since the current two-audience split gives them nowhere to look.Concretely, the v0.7.2 gascap entry becomes:
Happy to open a PR that (1) adds the
[RPC]flag definition to the header, (2) retro-annotates the four v0.7.x entries above, and (3) adds a one-line note pointing application developers at[RPC]entries — if a maintainer confirms they'd take it.kutluhaneth46 commentedon Aug 31, 2026
PR: https://github.com/circlefin/arc-node/pull/NEW
Made with Cursor
kutluhaneth46 commentedon Aug 31, 2026
PR: #297
kutluhaneth46 commentedon Sep 10, 2026
@huklaa Heads-up — this is already covered by open PR #297. Happy to collaborate there if you have review notes; no need for a parallel PR.
kutluhaneth46 commentedon Sep 28, 2026
@ZhiyuCircle requesting assignment — linked PR is already open, CI-green, and mergeable. Per CONTRIBUTING the only remaining gate is assignment; happy to rebase or adjust scope once assigned.