docs: classify JSON-RPC behavior changes as application-facing breaking changes

[mssystem1]

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.gascap default: 50000000
• new --rpc.gascap default: 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.

[osr21]

I went through the current BREAKING_CHANGES.md against 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 Operators and ### 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:

• v0.7.2 gas cap — --rpc.gascap 50M → 30M. eth_call/eth_estimateGas above 30M now fail. (Your example; filed [Config].)
• v0.7.2 pre-EIP-155 rejection — replay-unprotected txs are now rejected over RPC by default with "only replay-protected (EIP-155) transactions allowed over RPC". A client that was submitting legacy unprotected txs breaks with no contract or method-signature change. (Filed [CLI].)
• v0.7.2 batch cap — --arc.rpc.max-batch-entries defaults to 100; oversized batches are rejected with JSON-RPC -32600 before any per-entry handler runs. Any SDK/tooling batching >100 calls sees a hard error. (Filed [Config].)
• v0.7.1 subscription cap — --rpc.max-subscriptions-per-connection 1024 → 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 Developers subsection 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:

• [Config][RPC] arc-node-execution: JSON-RPC gas cap default lowered.
  • [Config] --rpc.gascap default 50000000 → 30000000; pass --rpc.gascap 50000000 to restore.
  • [RPC] eth_call/eth_estimateGas requiring >30M gas now fail with a gas-cap error even against an unchanged JSON-RPC API.

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.