feat(sparse): add membership proof generation

[dicethedev]

🗒️ Description / Motivation

• Adds sparse Merkle membership proof support for Phase 3.
• Enables callers to prove that a specific 256-bit key maps to a specific value without revealing the rest of the tree.
• Introduces a compact proof format that stores empty siblings as None and reconstructs them from the empty-hash cache during verification.

What Changed

• Added SparseMerkleProof<D> with:
  • key: [u8; 32]
  • siblings: Vec<Option<D>>
  • leaf: Option<D>
• Added generate_membership_proof(key) to SparseMerkleTree.
• Added stateless SparseMerkleTree::<H>::verify(expected_root, leaf_data, proof).
• Added serde dependency to merkle-variants so sparse proofs implement Serializable.
• Added tests for valid proofs, wrong values, tampered siblings, non-membership proof shape, and serialization round-trip.
• Fixed strict Clippy lint issues from make lint.

Correctness / Behavior Guarantees

• Proofs for inserted keys include the stored leaf hash.
• Proofs always contain 256 sibling entries.
• Empty sibling subtrees are represented as None.
• Verification reconstructs omitted siblings using the canonical empty-hash cache.
• Verification fails if the provided value does not match the proof leaf.
• Verification fails if any non-empty sibling is tampered with.
• Proofs for missing keys return leaf: None, setting up the next non-membership proof phase.

Tests Added / Run

• Added tests covering:
  • Inserted-key proof verification
  • Wrong-value verification failure
  • Tampered-sibling verification failure
  • Missing-key proof with leaf: None
  • SparseMerkleProof serialization round-trip

Related Issues / PRs

• Closes Phase 3 - Sparse Merkle Tree (Membership proof generation and ProofVerifier) #30
• Related to Phase 3 - Sparse Merkle Tree (Implement key-addressed insert() and remove() with path traversal) #29
• Related to Phase 3 - Sparse Merkle Tree (Non-membership proof generation and verification) #31

✅ Verification Checklist

• Ran make fmt — clean
• Ran make lint (clippy with -D warnings) — clean
• Ran make test — all passing

[Copilot]

Pull request overview

Adds sparse Merkle membership proof support to merkle-variants to enable proving that a 256-bit key maps to a specific value (by value preimage), using a compact proof format that omits empty siblings.

Changes:

• Introduces SparseMerkleProof<D> (key + 256 sibling hashes as Option<D> + optional leaf hash) with serde support.
• Adds SparseMerkleTree::generate_membership_proof(key) and a stateless SparseMerkleTree::<H>::verify(expected_root, leaf_data, proof) verifier.
• Adds tests for proof generation/verification failure cases and serialization round-trip.

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

File	Description
merkle-variants/src/sparse.rs	Adds proof type, proof generation, stateless verification, and new tests.
merkle-variants/Cargo.toml	Adds serde dependency so sparse proofs can be serialized.
Cargo.lock	Updates lockfile to include serde for merkle-variants.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.