docs: node verification guide incorrectly describes `eth_blockNumber` as returning the next block height

[mssystem1]

Summary

The Running an Arc Node documentation incorrectly states that the result returned by eth_blockNumber represents the next block height.

eth_blockNumber returns the number of the latest block known to the node.

Calling the returned value the "next block height" introduces an off-by-one semantic error in the node-operation documentation.

Affected Documentation

File:

docs/running-an-arc-node.md

Section:

Verify operation

Current Documentation

The guide instructs operators to call:

curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}'

It then states that:

The result field represents the next block height, in hexadecimal.

This is inaccurate.

Actual Behavior

For a chain whose latest block is block N:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xN"
}

represents block N, not block N + 1.

In other words:

eth_blockNumber = latest/current block number

not:

eth_blockNumber = next block height

Why This Matters

This wording can create off-by-one mistakes in:

• node sync checks;
• operational scripts;
• monitoring;
• block indexing;
• troubleshooting;
• documentation copied into third-party tooling.

For example, if the RPC returns:

0x64

the node's reported latest block number is:

100

The documentation currently implies this is the height of the next block to be produced.

Expected Documentation

The paragraph should instead say something similar to:

The `result` field contains the latest block number known to the execution
layer, encoded as a hexadecimal quantity. The value should increase as the
node follows the chain.

Suggested Fix

Replace:

The result field represents the next block height, in hexadecimal

with:

The result field represents the latest block number known to the node,
encoded in hexadecimal.

Optional Improvement

The verification section could also provide a deterministic conversion example:

BLOCK_HEX=$(curl -s -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  | jq -r '.result')

printf "%d\n" "$BLOCK_HEX"

This makes it clearer that the value is the current latest block number.

Impact

Documentation / developer experience.

Severity:

Low

The node itself behaves correctly; the issue is the documented interpretation
of a standard RPC response.

Environment

Repository:

circlefin/arc-node

File:

docs/running-an-arc-node.md

RPC method:

eth_blockNumber

[osr21]

Confirmed against docs/running-an-arc-node.md — the "Verify operation" section does contain this line verbatim:

The result field represents the next block height, in hexadecimal

That is inaccurate for the reason you give: eth_blockNumber returns the number of the latest block known to the node, not the next block to be produced. Your 0x64 → 100 example is exactly right, and the "next block height" phrasing introduces a real off-by-one for anyone scripting sync/monitoring checks against it. Your suggested replacement ("latest block number known to the node, encoded in hexadecimal") is the correct wording.

Two additional things I noticed in the same spot, worth folding into the same fix:

1. The printf example directly below the line is also buggy. The doc says:

   (you can use printf "%0d" to translate it into decimal)

   %0d is not a valid conversion for hex→decimal here on two counts: (a) %d doesn't parse a 0x-prefixed hex string — you need %x-style input handling, and (b) 0 alone is not a valid flag/width. In practice printf "%0d" 0x64 does not yield 100. The reliable one-liner is:

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

   which is essentially the deterministic conversion example you proposed in "Optional Improvement" (printf "%d\n" "$BLOCK_HEX"). So fixing the prose and fixing the printf snippet are the same edit — I'd do both together.

2. The second verification section is already correct — keep them consistent. The Docker "Verify" section further down describes the same call as "The result field should increase over time as the node catches up with the network" with no "next block height" claim. So the fix is really just bringing the first (bare-metal) "Verify operation" section in line with the wording the Docker section already uses.

Suggested concrete edit to the "Verify operation" paragraph:

The produced output is in JSON format. The result field contains the latest block number known to the execution layer, encoded as a hexadecimal quantity (use printf "%d\n" <hex> to convert to decimal). It should increase over time as the node follows the chain. If it remains 0x0, check the logs of the consensus layer for errors.

Low severity as you noted — node behavior is correct, this is purely the documented interpretation — but it's a clean, unambiguous fix. Happy to open the PR against docs/running-an-arc-node.md if a maintainer wants it.