feat(evm): align BLOCKHASH opcode with Aptos consensus block_id

[nekomoto911]

Summary

Make the EVM BLOCKHASH opcode return Gravity's Aptos consensus block_id on every execution path — live pipeline, historical eth_call, debug_trace*, trace_*, eth_callBundle, mev_simBundle, flashbots_validateBuilderSubmission, and the pending-block simulation. JSON-RPC layer is untouched: eth_getBlockByNumber(n).hash continues to return the standard keccak(rlp(header)) so devp2p, stage sync, eth_feeHistory, and genesis init all remain bit-compatible with upstream reth.

The opcode-visible distribution is binary {block_id, 0x0}: a miss (block predates the upgrade point or is not yet committed) maps to B256::ZERO. The mechanism never falls back to keccak, so cross-upgrade contracts need a single "is zero?" branch — same shape as the existing "current_block - n > 256 → 0" rule baked into the opcode.

Approach

Rather than threading a per-site BlockIdOverrideDb<DB> wrapper through 17 RPC call sites (the surface area would have spanned eth-api/debug/trace/bundle/validation), this lifts BlockNumberToBlockIdReader to a supertrait of StateProvider and changes the blanket impl<T: StateProvider> EvmStateProvider for T so block_hash dispatches to block_id_by_number. Every EVM path that goes through StateProviderDatabase is covered automatically. The miss-to-zero contract is preserved by the existing one-line unwrap_or_default() in StateProviderDatabase::block_hash_ref.

Production providers query a new tables::BlockNumberToBlockId table. Writes happen in BlockViewStorage::update_canonical synchronously before make_canonical returns, so the racy in-memory window is closed for the Gravity pipeline. Test stubs alias block_id_by_number to block_hash to preserve existing test expectations.

In-memory race-window closure

The upstream-reth path (MakeCanonical engine event with async advance_persistence) used to leave a brief window where block N was canonical-in-memory but its block_id row had not landed in tables::BlockNumberToBlockId — gravity_blockIdByNumber(N) returned null and BLOCKHASH(N) returned 0x0 during that window. This is now closed:

• CanonicalInMemoryState carries a block_ids: BTreeMap<BlockNumber, B256> index with insert_block_id / block_id_by_number / remove_persisted_block_ids (range-evict on persistence) / snapshot_block_ids_for (point-snapshot for overlays). Eviction handles the u64::MAX boundary via checked_add(1).
• MakeCanonicalEvent carries block_id. The engine tree inserts the index entry before make_executed_block_canonical advances the canonical head, so any RPC observer that sees N as canonical resolves block_id_by_number(N) immediately.
• MemoryOverlayStateProviderRef gains a block_ids snapshot field and a with_block_ids builder. block_id_by_number is in-memory-first then historical; block_hash is unchanged (still keccak header hash from sealed in-memory blocks — the two trait methods deliberately diverge).
• BlockchainProvider::block_id_by_number is now two-stage: in-memory first, then consistent_provider().
• All construction sites with CanonicalInMemoryState access wire the snapshot (consistent.rs::block_state_provider_ref + state_by_hash; blockchain_provider.rs::block_state_provider + latest() validator path). StateProviderBuilder::build (upstream-reth run_inner, opt-in via GRETH_DISABLE_PIPE_EXECUTION) and ress/provider (stateless witness recorder) carry race-window doc notes; both sit outside the gravity hot path.

Additions

• tables::BlockNumberToBlockId (BlockNumber → B256)
• BlockNumberToBlockIdReader trait + impls across all StateProvider impls
• gravity_blockIdByNumber JSON-RPC method under a new gravity namespace (--http.api gravity / --ws.api gravity); "pending" returns null
• CanonicalInMemoryState::block_ids in-memory index closing the MakeCanonical → advance_persistence race window
• MemoryOverlayStateProviderRef::with_block_ids builder for race-window-safe overlays

Test plan

• cargo test -p reth-rpc --lib gravity — pending-short-circuit + concrete-dispatch
• cargo test -p reth-provider --lib block_number_to_block_id_roundtrip — table roundtrip via DatabaseProvider + ProviderFactory
• cargo test -p reth-chain-state --features test-utils --lib memory_overlay::tests — T1 (no keccak leak when snapshot empty) / T2 (in-memory snapshot overrides historical) / T3 (block_hash and block_id_by_number diverge on the same overlay)
• cargo test -p reth-chain-state --features test-utils --lib block_id — CanonicalInMemoryState insert / lookup / inclusive evict / u64::MAX boundary / snapshot / clear
• cargo test -p reth-pipe-exec-layer-ext-v2 --test gravity_blockhash_alignment_test test_blockhash_alignment_grevm — full pipeline E2E (grevm)
• cargo test -p reth-pipe-exec-layer-ext-v2 --test gravity_blockhash_alignment_test test_blockhash_alignment_disable_grevm — full pipeline E2E (no grevm)
• cargo +nightly fmt --all --check
• RUSTFLAGS=-D warnings cargo +nightly clippy --lib --tests --benches --all-features --locked

The integration test runs 20 blocks through the live PipeExecLayerApi, then asserts:

Invariant	Assertion
Table populated	BlockNumberToBlockId(n) == mock_block_id(n) for n ∈ [1, 20]
Provider	BlockchainProvider::block_id_by_number(n) == mock_block_id(n)
RPC stays keccak	eth_getBlockByNumber(n).hash != mock_block_id(n)
EVM in window	eth_call(BLOCKHASH(n)) returns mock_block_id(n) for n ∈ [1, 19]
Future block	eth_call(BLOCKHASH(21)) returns 0x0
Current block	eth_call(BLOCKHASH(20)) returns 0x0 (opcode contract)

Migration / known limits

• No backfill for blocks executed before this change. EVM BLOCKHASH(n) for those returns 0x0, never keccak — matches the existing "out-of-window → 0" behavior. Documented in the design.
• Stage-sync re-execution: operators wiping the DB and re-running stage-sync over previously-executed Gravity history must backfill BlockNumberToBlockId first; otherwise state roots will diverge from the live run. The live Gravity pipeline does not use this path.
• RpcBlockchainStateProvider (RPC-proxy mode) returns Ok(None) rather than aliasing to block_hash — preserves the {block_id, 0} invariant. Real block_id reads in proxy mode require a node that queries the table directly.
• update_canonical opens a sync RW tx on the async hot path (one ~40 byte commit per canonical block). Future optimization batches with engine-tree persistence or uses spawn_blocking.
• StateProviderBuilder::build and ress/provider do not thread the in-memory block_ids snapshot. Both are off the gravity hot path (the former requires GRETH_DISABLE_PIPE_EXECUTION=1; the latter is a stateless witness recorder); explicit race-window doc notes are in place. Closing these requires plumbing a CanonicalInMemoryState handle and is deferred.

Labels

A-rpc A-evm