docs: clarify RPC behavior and validate rustdoc

[ayaanoncrypto]

Closes #271
Closes #270
Closes #257
Closes #235

Summary

This pull request groups four focused documentation and CI improvements:

• Explain that the JSON-RPC gas cap limits eth_call and eth_estimateGas simulations and is distinct from the protocol transaction gas limit.
• • Add an [RPC] breaking-change category for application-facing JSON-RPC behavior changes.
• • Update Docker Compose image examples from v0.6.0 to v0.7.3.
• • Add a CI job that runs workspace rustdoc with warnings treated as errors.
    The separate eth_blockNumber clarification is tracked in docs: node verification guide incorrectly describes eth_blockNumber as returning the next block height #272 and is implemented by PR docs: clarify eth_blockNumber verification #274.

Validation

git diff --check passed. Rust formatting and rustdoc execution were unavailable locally because Cargo is not installed in the sandbox.

[osr21]

Reviewed the full diff against the five issues this closes (#235, #257, #270, #271, #272). Three of the five are cleanly resolved; two have gaps worth fixing before merge, and there's one CI ordering problem that will break the build.

Verified good:

• docs: docker-compose.yml comment examples still reference v0.6.0 #235 (docker-compose examples on v0.6.0) — bumped to v0.7.3. ✅
• docs: explicitly distinguish RPC gas cap from protocol transaction gas limits #271 (gas cap vs protocol limit) — the new line "The RPC gas cap limits gas available to eth_call and eth_estimateGas simulations. It is an RPC execution limit, not the protocol maximum gas limit…" is exactly the distinction requested. ✅
• docs: classify JSON-RPC behavior changes as application-facing breaking changes #270 (add [RPC] category) — the flag is defined in the header and the gascap entry is dual-tagged [Config][RPC]. ✅ (but incomplete — see below)

Gaps:

1. The new rust-doc CI job will fail on its first run — this is the blocker. Issue #257 (which this PR closes) states in its own title that "31 rustdoc diagnostics have accumulated." This PR adds the enforcement (cargo doc --workspace --no-deps --all-features --locked with RUSTDOCFLAGS: -D warnings) but does not fix those 31 diagnostics. With -D warnings, the job turns every one of those into an error, so the check goes red immediately and blocks this PR and every subsequent one. The enforcement and the cleanup have to land together: either fix the 31 rustdoc warnings in this PR (or a predecessor), or land the job first without -D warnings (report-only), clean up, then flip to -D warnings. As-is, #257 isn't actually closed — the diagnostics still exist, they're just now fatal. (I can't run cargo doc here — no Rust toolchain in my sandbox — so I'm taking the count from #257's own claim; the ordering problem holds for any non-zero count.)

2. #272 — the prose is fixed but the printf bug in the same two lines is not. The diff correctly changes "next block height" → "latest block number known to the node", but keeps printf "%0d":

It is not the next block height. You can use `printf "%0d"` to translate it into decimal.

%0d is not a valid hex→decimal conversion — %d doesn't parse a 0x-prefixed string and 0 alone isn't a valid flag/width, so printf "%0d" 0x64 does not yield 100. The correct form is:

printf "%d\n" 0x64   # -> 100

Since this PR closes #272 and edits these exact two lines, it's the natural place to fix the snippet too.

3. #270 is only partially addressed. The [RPC] flag is defined and applied to the gascap entry, but the other externally-observable RPC changes already in BREAKING_CHANGES.md are left tagged operator-only:

• v0.7.2 pre-EIP-155 rejection (currently [CLI]) — clients submitting legacy unprotected txs break; that's app-facing → should be [CLI][RPC].
• v0.7.2 batch cap (--arc.rpc.max-batch-entries, currently [Config]) — oversized batches now rejected with -32600; app-facing → [Config][RPC].
• v0.7.1 subscription cap (--rpc.max-subscriptions-per-connection 1024→32, currently [Config]) — WS clients opening >32 subs break; app-facing → [Config][RPC].

Closing #270 while only tagging one of the four known app-facing entries leaves the taxonomy half-applied. Either annotate these three here, or scope #270 to "introduce the category" and track the retro-annotation separately.

Minor (CI supply-chain consistency): actions/checkout is pinned to a commit SHA (df4cb1c… # v6.0.3), but actions-rust-lang/setup-rust-toolchain@v1 in the same new job uses a floating major tag. For consistency with the pinned checkout, pin setup-rust-toolchain to a SHA as well.

Net: #235/#271 are done; #270/#272 need small follow-through in this same PR; and the rust-doc job needs the pre-existing warnings resolved (or a report-only first step) or CI breaks the moment this lands. Happy to help with the rustdoc cleanup or the BREAKING_CHANGES.md annotations if useful.

[osr21]

Thanks for the quick turnaround — the follow-up commit (573ce38) resolves three of the four items:

• docs: node verification guide incorrectly describes eth_blockNumber as returning the next block height #272 printf bug fixed ✅ — printf "%0d" → printf "%d\n" 0x64. That's correct: bash printf %d parses the 0x-prefixed operand as hex, so printf "%d\n" 0x64 → 100. Both the wording and the snippet are now right.
• docs: classify JSON-RPC behavior changes as application-facing breaking changes #270 fully applied ✅ — the three remaining app-facing entries are now dual-tagged: pre-EIP-155 rejection → [CLI][RPC], batch cap → [Config][RPC], and the EL RPC connection-defaults entry (which carries the --rpc.max-subscriptions-per-connection 1024→32 change) → [Config][RPC]. The taxonomy is now consistently applied across all four externally-observable changes.
• Action pinning fixed ✅ — actions-rust-lang/setup-rust-toolchain is now pinned to 0267444…# v1 across all six jobs, matching the SHA-pinned actions/checkout.

Still outstanding — and it's the merge blocker: the rust-doc job (#257). This commit doesn't touch it. The job still runs cargo doc … with RUSTDOCFLAGS: -D warnings, and the 31 pre-existing rustdoc diagnostics that #257 names haven't been fixed, so the check will fail on its first run and block the merge. This needs one of:

1. fix the 31 rustdoc warnings in this PR (then -D warnings passes and docs: cargo doc is not run in CI; 31 rustdoc diagnostics have accumulated #257 is genuinely closed), or
2. land the job report-only first (drop -D warnings), clean up the diagnostics in a follow-up, then flip enforcement on.

Once CI is green on the rust-doc job this looks good to me. (Still can't run cargo doc locally — no Rust toolchain in my sandbox — so I'm going off #257's stated count; the ordering constraint holds for any non-zero number.)

[osr21]

Re: dee374b ("docs: deduplicate block number clarification") — I see what you did here, and the dedup mechanic is right, but there's one loose end that will bite on merge.

What this commit does: it reverts #273's copy of the eth_blockNumber doc fix back to the original text, so this file now matches main exactly (blob 93f04f9). Net effect: #273 no longer touches docs/running-an-arc-node.md, which cleanly avoids the conflict with #274 and lets #274 own the #272 fix. Good — that's exactly the deduplication.

The problem: the reverted text is the buggy original — "next block height" and printf "%0d", the two things #272 reported. That's harmless only because it now equals main… but #273's description still says Closes #272. So if #273 merges, GitHub auto-closes #272 while shipping the un-fixed (buggy) text, and the real fix would then live only in #274. If #274 hasn't merged yet at that point, #272 is closed with the bug still live in main.

Two things to fix before this merges:

1. Remove #272 from docs: clarify RPC behavior and validate rustdoc #273's closing list — leave it as Closes #235, #257, #270, #271. docs: clarify RPC behavior and validate rustdoc #273 no longer fixes docs: node verification guide incorrectly describes eth_blockNumber as returning the next block height #272, so it shouldn't close it.
2. Land docs: clarify eth_blockNumber verification #274 to actually fix docs: node verification guide incorrectly describes eth_blockNumber as returning the next block height #272. docs: clarify eth_blockNumber verification #274 (head 2e6a4e9) still carries the correct text ("latest block number known to the node" + printf "%d\n" <hex>) and is independent of the rust-doc/docs: cargo doc is not run in CI; 31 rustdoc diagnostics have accumulated #257 CI work still blocking docs: clarify RPC behavior and validate rustdoc #273 — so it can go in first and close docs: node verification guide incorrectly describes eth_blockNumber as returning the next block height #272 on its own.

After that the split is clean: #274 → #272; #273 → #235/#257/#270/#271 (still pending the rust-doc job resolving those 31 rustdoc diagnostics so -D warnings passes).

[ayaanoncrypto]

Thanks for the detailed review. The requested documentation, RPC taxonomy, and action-pinning follow-ups are complete. PR #274 now owns the #272 documentation fix, and #273 no longer changes that file or closes #272.

The remaining blocker is the rust-doc job. Cargo is unavailable in this sandbox, so I cannot claim the existing rustdoc diagnostics are resolved or verify the -D warnings job locally. I am leaving that CI and maintainer decision visible rather than weakening the enforcement without confirmation.

[osr21]

The ownership split is correct, but there are two integration facts worth adding to this status.

What is confirmed

• PR docs: clarify RPC behavior and validate rustdoc #273 no longer changes docs/running-an-arc-node.md and no longer claims Closes #272.
• PR docs: clarify eth_blockNumber verification #274 is still the sole owner of the eth_blockNumber wording and printf "%d\n" <hex> fix, but it is still open and maintainer-blocked — it has not landed yet.
• PR docs: clarify RPC behavior and validate rustdoc #273 still adds RUSTDOCFLAGS: -D warnings without including the rustdoc source fixes, so the rust-doc job cannot be expected to pass against the base branch as it stands.

Important overlap with #258

PR #258 is also still open. Its head contains the actual rustdoc fixes for the 31 diagnostics and adds a rust-docs job that runs the same workspace documentation command with -D warnings.

That means #273 is not only waiting on a maintainer decision about the diagnostics — it overlaps #258 in .github/workflows/ci.yml and duplicates the same enforcement. The two jobs are named differently (rust-docs in #258 versus rust-doc here), but they run the same check. If #258 lands first, #273 will need to be rebased and its duplicate job reconciled; if #273 lands first, its new job will remain red until #258's source fixes arrive, and #258 will then add a second job. The cleanest ownership is to keep the diagnostics and one enforcement job together, while preserving the SHA-pinned action version used here if that workflow change is retained.

Current merge state

GitHub currently reports #273 as mergeable: false, mergeable_state: dirty. I reproduced the conflict by merging the current main into dee374b: the only conflict is deployments/docker-compose.yml, where this PR's concrete 0.7.3 examples conflict with main's $ARC_VERSION examples. The conflict is documentation-only, but it must be resolved before the PR can merge.

So the latest comment is right not to claim the -D warnings job is green, but the remaining work is broader than the rustdoc warning count: #258/#273 need coordination, #273 needs a rebase/conflict resolution, and #274 still has to land independently for #272 to be truly closed.

Disclosure: I'm an external community contributor, not affiliated with Circle, with no write access to this repository. Advisory review only, not an approval.