feat(m6): claim_lp_proceeds Merkle verification + SOL transfer

[graveyieldprotocol]

Summary

Wires the second half of GraveVault's settlement flow. claim_lp_proceeds now actually executes a claim instead of stubbing the proof + transfer:

1. Verify Merkle proof of (lp_holder, lp_balance_at_snapshot) against pool_registry.lp_snapshot_merkle_root (sealed by salvage_pool at salvage time)
2. Defensive reject: lp_balance_at_snapshot > 0 AND lp_total_supply_at_snapshot > 0
3. Compute pro-rata via u128 intermediate; conservation check claimed + amount <= total
4. SOL transfer from lp_holder_pool_vault to lp_holder via system_program::transfer (PDA-signs with its own seeds via invoke_signed)
5. Init ClaimRecord PDA (canonical double-claim defense — second claim by same (pool, holder) pair fails at the init constraint before lamports move)
6. Emit LpClaimProcessed

PR scope (Option B, code-path split)

This PR is the claim_lp_proceeds side. The matching salvage_pool execution path (Raydium V4 + Jupiter + 40/40/20 distribution) is in PR #19 (m5). The two PRs have no file overlap:

• m5 touches: cpi/ (new), instructions/salvage_pool.rs, errors.rs, constants.rs
• m6 touches: merkle.rs (new), instructions/claim_lp_proceeds.rs
• Both touch lib.rs and CHANGELOG.md in non-overlapping sections (m5 adds pub mod cpi;, m6 adds pub mod merkle;)

Whichever PR lands second will need a clean rebase; Git's three-way merge handles it.

What's in this PR

New file — programs/grave-vault/src/merkle.rs:

• compute_leaf(holder, balance) -> [u8; 32] = sha256(pubkey || balance_le_u64)
• verify_proof(root, leaf, proof) -> bool = sorted-pair walk (OZ / Uniswap convention)
• 7 host unit tests: deterministic leaf, distinct leaf on balance/pubkey change, two-leaf tree, four-leaf balanced tree, sorted-pair order invariance, empty-proof-as-leaf edge case, tampered leaf rejection

Modified — programs/grave-vault/src/instructions/claim_lp_proceeds.rs:

• Replaces m3's require!(!params.merkle_proof.is_empty(), …) stub with a real merkle::verify_proof(...) call against pool_registry.lp_snapshot_merkle_root
• Replaces m3's TODO(GraveVault m6): SOL transfer comment with a real system_program::transfer CPI signed by lp_holder_pool_vault's own seeds via invoke_signed
• Adds defensive checks for zero balance + zero total supply
• Preserves m3's pro-rata math, conservation check, ClaimRecord init, and event emission

Modified — programs/grave-vault/src/lib.rs:

• + pub mod merkle;

Modified — CHANGELOG.md:

• m6 entry with added / changed / sync-convention / unverified breakdown

Error codes

No new error codes. InvalidClaimProof (7010) and ClaimAlreadyProcessed (7011) — both already on main — cover the m6 surface. docs/error_codes.md unchanged.

Test plan

• cargo fmt --check green
• cargo clippy --all-targets -- -D warnings green
• cargo test --lib --package grave-vault merkle — 7 unit tests pass
• anchor build green
• terminology-lint green (pre-checked locally: PASS)
• CodeRabbit review (mandatory pre-merge)

Unverified (transparent)

• End-to-end localnet smoke test: salvage a Raydium V4 SOL/X pool via m5, then claim from multiple holders against the sealed root. Blocked on m5 (PR feat(m5): GraveVault salvage_pool execution path #19) landing first — this is the next step after both PRs merge.
• Real off-chain GraveScanner v2 indexer integration. The leaf encoding (sha256(pubkey || balance_le_u64)) is documented in merkle.rs — the off-chain builder MUST match it byte-for-byte. Indexer work is m9 (separate workstream).
• BPF compile via anchor build — deferred to CI per the validated parallel-track cadence.

Honest disclaimers

Same ship-now-verify-after cadence as m5. Anything CodeRabbit or CI flags will be addressed as fix-up commits on this PR. The CHANGELOG enumerates what's not yet proven.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@graveyieldprotocol has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 52 minutes and 51 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 96a0d7f0-9f26-4685-b008-86be6dd762ea

📥 Commits

Reviewing files that changed from the base of the PR and between 704ca9c and 342d8cb.

📒 Files selected for processing (6)

• .github/workflows/ci.yml
• CHANGELOG.md
• programs/grave-vault/Cargo.toml
• programs/grave-vault/src/instructions/claim_lp_proceeds.rs
• programs/grave-vault/src/lib.rs
• programs/grave-vault/src/merkle.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/m6-grave-vault-claim-merkle

---

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 and usage tips.}