feat: add snapshot Merkle inclusion proof verifier (#463)

[morelucks]

Summary

Closes #463

Adds verify_snapshot_inclusion — a pure, stateless Merkle inclusion proof helper that lets off-chain holders prove their leaf was included in a finalized snapshot without storing the full holder set on-chain.

---

What changed

src/lib.rs — single new public function verify_snapshot_inclusion

---

Design

Leaf encoding

Identical to finalize_snapshot (same hash function, same serialisation):

leaf_hash = SHA-256( index_xdr || holder_xdr || shares_bps_xdr )

Each field is XDR-serialised with .to_xdr(&env). This guarantees that any leaf produced by the existing finalization pass is directly provable — no separate encoding step.

Sorted-pair Merkle tree

Internal nodes:

parent = SHA-256( min(a, b) || max(a, b) )

Sorting the pair lexicographically before hashing makes the tree position-independent: the proof array carries only sibling hashes, no left/right flags. Off-chain tooling must build proofs with the same sorted-pair rule.

Verification algorithm

1. Hash the supplied raw leaf bytes with SHA-256 → current
2. For each sibling in proof: sort pair, concatenate, SHA-256 → new current
3. current == entry.content_hash → true, otherwise false

---

Security properties

Property	Detail
Finalization guard	Returns false for unfinalized snapshots (untrusted content_hash)
Missing snapshot	Returns false — no error leaked (prevents enumeration)
Fixed-width proof elements	Vec<BytesN<32>> — no length-extension attack surface
Collision resistance	Forging a valid proof requires breaking SHA-256
Same hash function as finalize_snapshot	env.crypto().sha256() throughout

---

Leaf encoding reference (for off-chain implementors)

// index: slot position (u32), holder: Address, share_bps: u32
let mut raw = Bytes::new(&env);
raw.append(&index.to_xdr(&env));
raw.append(&holder.to_xdr(&env));
raw.append(&share_bps.to_xdr(&env));
let leaf_hash = env.crypto().sha256(&raw).to_bytes(); // BytesN<32>

Pass raw (the pre-hash bytes) as the leaf argument to verify_snapshot_inclusion.

[drips-wave]

@morelucks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits