Correct canonical witness lookup and null handling for v2.2.1

[0xBreadguy]

Summary

The witness guide and RPC reference describe number-only requests as returning the first stored witness and tell clients to treat missing witnesses as errors. In mega-reth v2.2.1, number-only requests resolve the local canonical hash, return only a matching witness, and return result: null if the canonical hash or matching witness is unavailable.

• Replace first-row/unsafe lookup guidance with canonical resolution and retry-after-catch-up behavior.
• Document nullable results and reserve -32603 for internal failures; remove the missing-witness error-message matching advice.
• Explain that explicit hash/payload selectors are unchanged and pin identity without guaranteeing continued canonicality.
• Make the operator decoding example stop on null and RPC errors before decoding.

Addresses F-001. Verified against megaeth-labs/dist-docs#55, megaeth-labs/mega-reth#2026, and the executable handler in v2.2.1/crates/megaeth/rpc/src/witness.rs. The handler's old selection-priority comment still mentions the fallback, but its implementation and regression test explicitly remove it. Missing-witness null is an existing response contract; the release change removes the unknown-canonical first-row fallback.

Validation

• Repository-wide Markdown lint and Prettier 3.8.5 pass.
• JSON examples parse; local file links and GitBook blocks validate.
• Bash example passes syntax validation; its jq guard accepts available results and rejects null/error responses without emitting a payload.
• git diff --check passes.
• No live witness requests issued; behavior verified against the release-tagged source. Repository CI passes, including link checks and PR review pipeline tests.

[0xBreadguy]

Did this as part of the latest security advisory (p0).

The callout was verified and then I had this PR submitted by my agent (using Astra).

Did it to be helpful, but need the team to validate. If this just creates noise I'll confine PRs to my own working sections (e.g. tokenlist)

[flyq]

Heads-up before merging: mega_getBlockWitness does not behave the same on the public RPC and on mega-reth yet.

mega-reth (v2.2.1) returns result: null when no witness is available. The public endpoint https://mainnet.megaeth.com/rpc is served by the mega-rpc gateway, which currently returns a -32603 Witness not found error for the same case. So the null behavior this PR documents is correct for mega-reth but not yet for the public endpoint.

megaeth-labs/mega-rpc#509 aligns the gateway with mega-reth: null for a missing witness, and -32603 only for real server-side failures. Let's hold this PR until #509 is merged and deployed, so the docs match both.