Implementation of proofs for IPC

[karlem]

Overview

This PR introduces the first working implementation of IPC Filecoin Proofs — a library and CLI tool for generating and verifying compact Merkle proofs of Filecoin L1 state and events.

It enables IPC subnets (and other verifiers) to prove facts about the L1 chain offline, using only a self-contained witness bundle. This is primarily used for top-down message verification, cross-chain bridges, and trust-minimized automation.

---

What’s included

• Storage proofs — Verify that a specific actor’s FEVM storage slot had a given value at a given tipset.
• Event proofs — Verify that an EVM log (e.g. NewTopDownMessage) was emitted by a particular actor at a specific height.
• RecordingBlockStore — Wraps the blockstore to record only the exact CIDs touched during traversal, keeping proofs minimal and deterministic.
• Two-pass event filtering — First scans receipts to find relevant indices, then records only those AMT/HAMT paths, reducing witness size.
• Shared RPC cache — Deduplicates identical blocks across multiple proofs, cutting redundant network calls and final bundle size.
• ProofBundle format — Self-contained { blocks[], proofs[] } structure that can be verified offline with no RPC dependencies.

---

How it works

1. The generator connects to Lotus RPC, traverses HAMTs and AMTs for state, receipts, and events.
2. During traversal, the RecordingBlockStore logs every block read.
3. Only blocks relevant to the proof are packaged into the ProofBundle.
4. The verifier replays the same HAMT/AMT traversals locally, verifying inclusion of storage values or events against a trusted tipset (under F3 finality).

---

Why it matters

This is the foundation for trust-minimized IPC communication — subnets can verify parent-chain events or state changes without needing a full node or RPC.
It also opens the door for bridges, auditable relayers, and off-chain verifiers that can independently confirm Filecoin L1 data integrity.

---

Next steps / planned improvements

• Add detailed serialization spec for ProofBundle (likely CAR-based).
• Add negative and integration tests (missing blocks, empty filters, invalid bundles).
• Include performance benchmarks (witness size, RPC count, verification time).
• Embed version metadata into proof bundles for forward compatibility.
• Document finality/trust-anchor configuration and handling of reorgs.

---

Notes for reviewers

The review focus should be on:

• Architecture and correctness of proof generation and recording.
• Determinism and completeness of witness capture.
• Clarity of interfaces for generating and verifying proofs.
• Readability and maintainability of the traversal logic.

Please flag anything unclear or brittle — particularly around actor ID handling, finality assumptions, or serialization boundaries.

---

In short: this PR lays the groundwork for verifiable, self-contained proofs of Filecoin L1 facts — the core building block for IPC cross-chain trust.

[Kubuxu]

You might want to switch to websockets for better efficiency if you run into some perf issues here.

[Kubuxu]

preimage would be the inputs that get hashed, so key, slotIndex, it seems like you are accepting the digest.

[Kubuxu]

The approach is very much correct. I spot-checked some edge cases I had in mind, and they seem to be covered. From high-level LGTM. I could look further into data paths (to ensure we don't trust proof inputs too much), and I will try to do that.