feat(grave-vault): m3 salvage_pool pre-flight + cert freshness gates

[graveyieldprotocol]

Summary

Lands milestone 3 of the canonical 10-step GraveYield build sequence: GraveVault salvage_pool pre-flight + PoolRegistry. The instruction now opens with all the right gates wired; AMM remove_liquidity (m5), Jupiter swap (m6), and 40/40/20 distribution (m7) remain honest-stubbed below the pre-flight section.

Resolves Seth's Telegram lock from 2026-05-10:

• MIN_CERT_TTL_SECONDS = 600 (10 min)
• Doc patch deferred — code first, docs document what the code actually does.

Changes

Scanner (cert_ttl_seconds migration to governance-configurable + floor)

• programs/grave-scanner/src/state/protocol_config.rs — added cert_ttl_seconds: i64 field. _reserved stays at 64 bytes; INIT_SPACE grows by 8 bytes (pre-mainnet, no migration concern).
• programs/grave-scanner/src/constants.rs — added MIN_CERT_TTL_SECONDS: i64 = 600 (hardcoded floor; raising requires program upgrade) and DEFAULT_CERT_TTL_SECONDS: i64 = 3600. Old ELIGIBILITY_CERT_TTL_SECONDS const kept as #[deprecated] alias for backwards-compatible test fixtures.
• programs/grave-scanner/src/errors.rs — added error 6019 CertTtlBelowMinimum.
• programs/grave-scanner/src/instructions/initialize.rs — InitializeParams.cert_ttl_seconds: i64 field with default-handling (0 → DEFAULT_CERT_TTL_SECONDS) and floor validation.
• programs/grave-scanner/src/instructions/update_protocol_config.rs — UpdateProtocolConfigParams.cert_ttl_seconds: Option<i64> with floor validation. Reverts CertTtlBelowMinimum for any value < 600s.
• programs/grave-scanner/src/instructions/evaluate_pool_phase2.rs — reads cfg.cert_ttl_seconds instead of the hardcoded const when stamping cert.expires_at.

Vault (salvage_pool full pre-flight)

• programs/grave-vault/src/instructions/salvage_pool.rs — flagship change. Five gates wired:
  1. !cfg.emergency_paused → ProtocolPaused (existing).
  2. !cert.is_expired(now) → EligibilityCertExpired (NEW). TTL window comes from Scanner ProtocolConfig, floored at 600s.
  3. cert.criteria_bitmap == 0x3F → InvalidEligibilityCert (NEW). All six derelict-pool criteria must have passed at Phase 2.
  4. cert.amm_program_id == params.amm_program_id AND cert.pool_address == params.pool_address → InvalidEligibilityCert (NEW). Defense in depth against forged seed match.
  5. pool.key() == params.pool_address → PreflightFailed (existing).
  • eligibility_cert migrated UncheckedAccount → Account<'info, EligibilityCert>. Anchor now handles 8-byte discriminator + owner-program (grave_scanner::ID) automatically; manual ownership require! removed as redundant.
  • lp_holder_pool_vault migrated UncheckedAccount → SystemAccount<'info> with init_if_needed + space = 0. First salvage of a pool creates the system-owned 0-data PDA; subsequent salvages of the same pool blocked upstream by pool_registry init constraint, so the init_if_needed footgun does not apply.
  • Inline TODOs name m4–m7 deliverables and explicitly capture min_quote_output_lamports to keep the unused-variable lint quiet through m6.
• programs/grave-vault/src/instructions/claim_lp_proceeds.rs — lp_holder_pool_vault aligned to SystemAccount<'info> for type consistency with salvage_pool.
• programs/grave-vault/Cargo.toml — added init-if-needed feature to anchor-lang dependency.
• CHANGELOG.md — created with v1.0.6 entry naming each change + honest-stub status.

Verification status

• All 10 files written and committed atomically (commit 35afe30).
• Cross-program type binding: Account<'info, EligibilityCert> works because grave-scanner = { features = ["cpi"] } and #[account] macro generates a stable Owner impl that resolves to grave_scanner::ID regardless of consuming crate.
• cargo check / cargo clippy -D warnings not yet run. Pending Seth's ship-now-vs-verify-first call. v1.0.7 will be the post-verification patch with any compile fixes named in CHANGELOG (per established cadence).
• No localnet tests in this PR. m3 test plan (8 cases — happy path → AmmAdapterUnimplemented revert; pause; missing cert; stale cert; double salvage; cert criteria mismatch; cert pool mismatch; pool address mismatch) is a follow-up PR once Anchor.toml localnet validator setup lands.

Honest-stub status (m4–m7 still pending)

• AMM remove_liquidity Raydium V4: wired in v1.0.5 background work; not yet integration-tested against seeded localnet pool (OpenBook seed harness is v1.1).
• AMM adapters Raydium CLMM / Orca / PumpSwap: revert AmmAdapterUnimplemented.
• Locker release adapters UNCX / PinkSale / Team Finance: revert LockerAdapterUnimplemented.
• Jupiter v6 swap CPI: not wired; m6 deliverable.
• 40/40/20 distribution math: not wired; m7 deliverable. SalvageReceipt distribution fields are zeroed at init.
• LP-holder Merkle proof verification in claim_lp_proceeds: returns InvalidClaimProof until m6.

Pre-mainnet checklist additions

• Re-deploy ProtocolConfig PDAs on devnet — adding cert_ttl_seconds changes INIT_SPACE. Existing config accounts will fail realloc unless rotated through a fresh initialize. (No-op on the canonical pre-mainnet deploy path since no live config exists.)
• Replace placeholder program IDs in both crates' declare_id! and Anchor.toml via anchor keys list && anchor keys sync before any audit submission.

Test plan

• Pull this branch and run cargo check from repo root (Rust 1.85, Solana 2.0.21, Anchor 0.31.1).
• Run cargo clippy --all-targets -- -D warnings.
• Run pnpm -r typecheck to verify SDK types still resolve against the new IDL.
• CI workflow: terminology-lint.sh should pass (no rescue / RescueReceipt introduced — all canonical v4.0 terms).
• (Followup PR) Localnet test suite for the 8 m3 revert cases.

Summary by CodeRabbit

Release Notes

• New Features

  • Certificate Time-To-Live (TTL) is now governance-configurable with enforced minimum duration
  • Added certificate freshness validation and enhanced protocol state checks during pool salvage operations
  • Improved account type safety for LP holder vault operations

• Chores

  • Updated v1.0.6 changelog documenting milestone-3 implementation
  • Enhanced Anchor framework dependency configuration for vault initialization

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR implements governance-configurable certificate TTL validation with minimum enforcement and strengthens GraveVault account type safety by migrating from unchecked accounts to typed PDAs, adding pre-flight gating logic for protocol pause, certificate freshness, criteria enforcement, and parameter binding verification in salvage_pool.

Changes

TTL Configuration and Account Type Strengthening

Layer / File(s)	Summary
TTL Constants and Error Definitions programs/grave-scanner/src/constants.rs, programs/grave-scanner/src/errors.rs	Introduces DEFAULT_CERT_TTL_SECONDS (3600s), MIN_CERT_TTL_SECONDS (600s), deprecated alias for backward compatibility, and CertTtlBelowMinimum error variant.
ProtocolConfig State Schema programs/grave-scanner/src/state/protocol_config.rs	Adds cert_ttl_seconds: i64 field documenting governance update constraints and phase-2 usage.
Initialize TTL Validation programs/grave-scanner/src/instructions/initialize.rs	InitializeParams gains cert_ttl_seconds; handler defaults to DEFAULT_CERT_TTL_SECONDS, validates minimum floor, and stores in config.
Update TTL Validation programs/grave-scanner/src/instructions/update_protocol_config.rs	UpdateProtocolConfigParams adds optional cert_ttl_seconds; handler validates and updates config with minimum floor enforcement.
Phase-2 Certificate Issuance programs/grave-scanner/src/instructions/evaluate_pool_phase2.rs	Uses governance-configurable cfg.cert_ttl_seconds instead of fixed constant to stamp cert.expires_at with overflow checking.
Account Type Wiring programs/grave-vault/Cargo.toml, programs/grave-vault/src/instructions/salvage_pool.rs, programs/grave-vault/src/instructions/claim_lp_proceeds.rs	Enables init-if-needed feature; defines ALL_CRITERIA_MASK constant; wires eligibility_cert as typed Account<EligibilityCert> PDA; migrates lp_holder_pool_vault from UncheckedAccount to SystemAccount with init_if_needed in both instructions.
Salvage Pool Pre-flight Gating programs/grave-vault/src/instructions/salvage_pool.rs	Adds sequential validation gates: protocol pause check, certificate freshness via is_expired, criteria bitmap enforcement against ALL_CRITERIA_MASK, and binding verification of amm_program_id and pool_address. Moves Clock::get() earlier, adds pool address consistency check, and explicitly captures min_quote_output_lamports for future steps.
Documentation CHANGELOG.md	Documents v1.0.6 release with milestone-3 scope, added/changed items, verification status, audit-pending stubs, and pre-mainnet deployment checklist including ProtocolConfig PDA redeployment necessity.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The PR introduces coordinated changes across TTL configuration and account type safety with clear validation logic and pre-flight gating, but requires careful review of the handler's gating sequence and state schema impact on serialization size.

Possibly related PRs

• graveyieldprotocol/protocol#10: Prior PR making overlapping changes to grave-scanner (evaluate_pool_phase2, ProtocolConfig state, and error definitions) that this PR builds upon or extends.

Poem

🐰 With TTL floors and account types now strong,
The vaults shall gating-check all day long!
Freshness confirmed, criteria aligned bright—
Salvage pools now guard with pre-flight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: implementing milestone 3 salvage_pool pre-flight gates and certificate freshness validation, which aligns with the primary changes across grave-scanner and grave-vault.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/grave-vault-m3-salvage-pool-preflight

---

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

[coderabbitai]

🧹 Nitpick comments (1)

programs/grave-vault/src/instructions/salvage_pool.rs (1)

29-35: ⚡ Quick win

Consider adding a test assertion to verify mask synchronization.

The intentional duplication is reasonable for compile-time safety, but without an automated check, the two constants could silently drift during refactoring. A simple test assertion would catch this:

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn all_criteria_mask_matches_scanner() {
        assert_eq!(
            ALL_CRITERIA_MASK,
            grave_scanner::criteria::ALL_CRITERIA_MASK,
            "ALL_CRITERIA_MASK drifted from grave_scanner"
        );
    }
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@programs/grave-vault/src/instructions/salvage_pool.rs` around lines 29 - 35,
Add a unit test that asserts the local ALL_CRITERIA_MASK equals
grave_scanner::criteria::ALL_CRITERIA_MASK to prevent drift; create a
#[cfg(test)] mod tests with a #[test] fn (e.g.
all_criteria_mask_matches_scanner) that calls assert_eq!(ALL_CRITERIA_MASK,
grave_scanner::criteria::ALL_CRITERIA_MASK, "...") so CI fails if the two
constants diverge.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@programs/grave-vault/src/instructions/salvage_pool.rs`:
- Around line 29-35: Add a unit test that asserts the local ALL_CRITERIA_MASK
equals grave_scanner::criteria::ALL_CRITERIA_MASK to prevent drift; create a
#[cfg(test)] mod tests with a #[test] fn (e.g.
all_criteria_mask_matches_scanner) that calls assert_eq!(ALL_CRITERIA_MASK,
grave_scanner::criteria::ALL_CRITERIA_MASK, "...") so CI fails if the two
constants diverge.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9db1dbe3-f121-4414-aa2a-cc48198856ac

📥 Commits

Reviewing files that changed from the base of the PR and between 4a4aa6c and 35afe30.

📒 Files selected for processing (10)

• CHANGELOG.md
• programs/grave-scanner/src/constants.rs
• programs/grave-scanner/src/errors.rs
• programs/grave-scanner/src/instructions/evaluate_pool_phase2.rs
• programs/grave-scanner/src/instructions/initialize.rs
• programs/grave-scanner/src/instructions/update_protocol_config.rs
• programs/grave-scanner/src/state/protocol_config.rs
• programs/grave-vault/Cargo.toml
• programs/grave-vault/src/instructions/claim_lp_proceeds.rs
• programs/grave-vault/src/instructions/salvage_pool.rs

[graveyieldprotocol]

Superseded by #15.

The rebased version against current main (post-m4, post-Solana 3.x toolchain bump) is now open at #15 and is fully verified locally:

• cargo fmt + clippy: clean on Rust 1.91.1 + Anchor 0.32.1
• 20/20 tests pass
• cargo-build-sbf --tools-version v1.54: BPF compile succeeds in 51s

Migration delta vs this PR: Anchor 0.32 rejects init/init_if_needed on SystemAccount (per the 0.32.0 release notes — lang: Add custom error when using init on SystemAccount). PR #15 replaces the lp_holder_pool_vault: SystemAccount<'info> + init_if_needed pattern with UncheckedAccount<'info> + a manual system_program::create_account CPI in the handler. Net behaviour is identical — system-owned, space=0, rent-exempt PDA created on first salvage of each pool — but compatible with the new Anchor major.

Closing this PR as not-planned. Original design is preserved 1:1 in #15.

[graveyieldprotocol]

Superseded by #15, which has now merged to main as 4cdd1a9d.

#15 contains this PR's full diff plus the Anchor 0.32 migration delta required by the toolchain bump in #14 (replacing init_if_needed on SystemAccount with a manual system_program::create_account CPI). The intent and on-chain semantics are preserved 1:1.

Please close this PR as not planned.