feat(proofs): add bounded historical proof history

[panos-xyz]

Important

This is a stacked PR on top of #141. PR #141 owns the canonical-cursor
reference-index runtime; this PR should be reviewed only for bounded historical
proof storage and RPC changes. After #141 merges, this PR can be retargeted to
its target branch.

Summary

• add an opt-in, forward-only historical MPT proof index backed by a separate MDBX database
• serve bounded historical eth_getProof requests on both normal and authenticated RPC
• add explicit proofs init, proofs prune, and proofs unwind operator commands
• keep proof history independent from the always-on reference-index runtime

The versioned-trie implementation is adapted from Base commit
b2673bbd927cb34d7cfad4d448bfbd5bd30eae88 under MIT; Morph owns the integration,
MDBX backend, lifecycle, RPC policy, and tests.

Behavior

• proof history is disabled by default and enabled with --proofs-history
• the default retention window is 1,296,000 blocks; the Reth historical-state overlay remains disabled
• proofs init anchors the proof database at the current canonical tip; there is no backward backfill, schema migration, or automatic data deletion
• chain ID, genesis hash, and schema metadata are validated fail-closed; incomplete metadata or proof data without identity requires manual deletion
• the proof ExEx consumes precomputed trie updates on the fast path, supports canonical commit/reorg/revert notifications, and fails the node on unrecoverable proof-history errors
• startup refuses automatic pruning gaps above 1,000 blocks; operators must run proofs prune explicitly
• eth_getProof accepts only the inclusive durable window, checks the latest stored canonical hash, and limits each request to 1,024 storage keys
• window validation and proof cursors share one request-scoped MDBX read transaction so concurrent pruning cannot change the state generation mid-request
• debug_proofsSyncStatus reports earliest/latest bounds from one MDBX snapshot
• the derived database defaults to <chain-datadir>/historical-proofs; cold snapshots remain whole-data-directory copies

CLI

morph-reth proofs init --chain <chain> --datadir <path>
morph-reth node --chain <chain> --datadir <path> --proofs-history
morph-reth proofs prune --chain <chain> --datadir <path>
morph-reth proofs unwind --chain <chain> --datadir <path> --target <block>

Optional node settings:

• --proofs-history.storage-path <PATH>
• --proofs-history.window <BLOCKS>
• --proofs-history.verification-interval <BLOCKS>

Validation

• cargo fmt --all -- --check
• cargo test --workspace --no-fail-fast
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• strict missing-docs build for morph-proofs and morph-proofs-exex
• proof storage: 139 unit tests plus identity integration and doctest
• proof ExEx: 38 tests, including reorg/revert/error propagation
• request-snapshot and concurrent-prune regression tests
• real-node coexistence E2E: proof ExEx and canonical reference-index runtime advance together; normal/auth historical eth_getProof match
• existing reference-index node/RPC E2E: 4/4

Scope

This PR does not add a reference-index disable flag, reference-index status RPC,
snapshot format, compatibility migration, or benchmark harness. Live long-running
network sync, Hive/geth datasets, and performance benchmarks remain separate validation work.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3d4c3f9a-4be8-401e-937c-292f5c41fe8e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/reth-main-history-proof

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}