feat: add tree fee claim instruction

Author: ananas-block

.specify/memory/constitution.md

@@ -11,7 +11,8 @@
 
 ### II. Security-First
 
-- All account validation MUST use `light-account-checks` (`check_owner`, `check_signer`, `check_mut`, `check_discriminator`, `check_pda_seeds`).
+- All account validation MUST use `light-account-checks` (`check_owner`, `check_signer`, `check_mut`, `check_discriminator`, `check_pda_seeds`) or Anchor's `AccountLoader` (which checks owner + discriminator).
+- When an instruction dispatches on runtime-determined account types: use `*_from_account_info` (light-account-checks) for V2 batched accounts and `AccountLoader::try_from` (Anchor) for V1 accounts. If Anchor lifetime constraints prevent `AccountLoader`, an explicit owner check + discriminator match is acceptable but MUST be documented with the reason.
 - All arithmetic in on-chain programs MUST use checked math (`checked_add`, `checked_sub`, `checked_mul`) or equivalent safe operations.
 - Merkle tree integrity: all state transitions MUST be verified by ZK proofs before any compressed account mutation.
 - No upgradeable program authority without explicit constitution amendment.
@@ -26,6 +27,7 @@
 - MUST NOT run `cargo test` at the monorepo root.
 - Assert pattern: single `assert_eq` against a fully constructed expected struct (borsh-deserialized actual vs hand-built expected).
 - Tests that depend on `light-test-utils` MUST live in `program-tests/` or `sdk-tests/`, never in `program-libs/` or `programs/`.
+- When writing tests, MUST use the `/rust-test` skill for conventions: assertion patterns, assert functions per instruction, property tests with proptest, failing tests for every error variant, and Solana program testing with light-program-test.
 
 ### IV. Spec-First
 
@@ -45,6 +47,7 @@
 - **Instruction Dispatch**: Anchor `#[program]` for `account-compression` / `registry`; manual 8-byte discriminator dispatch for pinocchio programs (`system`).
 - **Fluent CPI Builder**: `LightCpiInstruction` trait with `.new_cpi()` -> `.with_light_account()` -> `.invoke()` chaining.
 - **Account Validation**: `check_owner`, `check_signer`, `check_mut`, `check_discriminator`, `check_pda_seeds` from `light-account-checks`.
+- **Authority Checks**: MUST use `check_signer_is_registered_or_authority` or its `manual_*` variant via `GroupAccess` trait. Custom auth functions that mirror this logic MUST document the equivalence and the reason for not using the canonical function (e.g., Anchor lifetime constraints in dynamic dispatch).
 
 ### VII. Zero-Copy
 
@@ -101,4 +104,4 @@ Examples: `jorrit/feat-compressible-mint`, `jorrit/fix-macro-deps`, `jorrit/chor
 - Amendments require: (1) written proposal, (2) explicit approval, (3) updated version below.
 - All code reviews MUST verify compliance with these principles.
 
-**Version**: 1.0.0 | **Ratified**: 2026-03-20 | **Last Amended**: 2026-03-20
+**Version**: 1.1.0 | **Ratified**: 2026-03-20 | **Last Amended**: 2026-03-21

CLAUDE.md

@@ -287,3 +287,10 @@ CompressAndClose: [96, 94, 135, 18, 121, 42, 213, 117]
 - Building instructions manually without Anchor's `InstructionData` trait
 - Creating SDK functions that don't depend on Anchor crate
 - Verifying instruction data in tests or validators
+
+## Active Technologies
+- Rust (Solana BPF target), Anchor framework for account-compression and registry programs + anchor-lang, light-batched-merkle-tree, light-merkle-tree-metadata, light-account-checks, light-compressed-accoun (001-tree-fee-distribution)
+- Solana on-chain accounts (tree/queue accounts owned by account-compression, PDA owned by registry) (001-tree-fee-distribution)
+
+## Recent Changes
+- 001-tree-fee-distribution: Added Rust (Solana BPF target), Anchor framework for account-compression and registry programs + anchor-lang, light-batched-merkle-tree, light-merkle-tree-metadata, light-account-checks, light-compressed-accoun

Cargo.lock

@@ -1,5 +1,45 @@
 use crate::errors::MerkleTreeMetadataError;
 
+/// Cap on lamports reimbursed to a forester per tree operation.
+pub const FORESTER_REIMBURSEMENT_CAP: u64 = 5000;
+
+/// Hardcoded rent exemption based on Solana's rent formula at deployment time.
+/// Formula: `(data_len + ACCOUNT_STORAGE_OVERHEAD) * LAMPORTS_PER_BYTE_YEAR * EXEMPTION_THRESHOLD`
+/// = `(data_len + 128) * 3480 * 2`
+///
+/// Hardcoded rather than queried via Sysvar because Solana's rent rate may
+/// change after trees are initialized, and existing trees must retain correct reserves.
+pub fn hardcoded_rent_exemption(data_len: u64) -> Option<u64> {
+    const LAMPORTS_PER_BYTE: u64 = 6960; // 3480 * 2
+    const ACCOUNT_STORAGE_OVERHEAD: u64 = 128;
+    data_len
+        .checked_add(ACCOUNT_STORAGE_OVERHEAD)?
+        .checked_mul(LAMPORTS_PER_BYTE)
+}
+
+/// Computes excess lamports claimable from a tree/queue account.
+///
+/// Formula: `account_lamports - rent_exemption - rollover_fee * (capacity - next_index + 1)`
+///
+/// The first leaf (index 0) does not pay a rollover fee, so:
+/// - paid fees = `next_index - 1`
+/// - remaining unfunded = `capacity - next_index + 1`
+///
+/// Returns `None` if there is no excess (underflow in any step).
+pub fn compute_claimable_excess(
+    account_lamports: u64,
+    rent_exemption: u64,
+    rollover_fee: u64,
+    capacity: u64,
+    next_index: u64,
+) -> Option<u64> {
+    let remaining = capacity.checked_sub(next_index)?.checked_add(1)?;
+    let reserved_rollover = rollover_fee.checked_mul(remaining)?;
+    account_lamports
+        .checked_sub(rent_exemption)?
+        .checked_sub(reserved_rollover)
+}
+
 pub fn compute_rollover_fee(
     rollover_threshold: u64,
     tree_height: u32,
@@ -87,3 +127,131 @@ fn test_address_tree_compute_rollover_fee() {
     );
     assert!(lifetime_lamports > (merkle_tree_lamports + queue_lamports));
 }
+
+#[test]
+fn test_hardcoded_rent_exemption() {
+    // 8-byte discriminator account: (8 + 128) * 6960 = 946_560
+    assert_eq!(hardcoded_rent_exemption(8), Some(946_560));
+    // 0-byte account: (0 + 128) * 6960 = 890_880
+    assert_eq!(hardcoded_rent_exemption(0), Some(890_880));
+    // Large account
+    let large = 10_000_000u64;
+    assert_eq!(
+        hardcoded_rent_exemption(large),
+        Some((large + 128) * 6960)
+    );
+    // Overflow: u64::MAX
+    assert_eq!(hardcoded_rent_exemption(u64::MAX), None);
+}
+
+#[test]
+fn test_compute_claimable_excess_normal() {
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = 500u64;
+    // remaining = 1000 - 500 + 1 = 501
+    // reserved = 100 * 501 = 50_100
+    // excess = lamports - rent - reserved
+    let lamports = rent + 50_100 + 5_000;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        Some(5_000)
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_zero() {
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = 500u64;
+    let remaining = capacity - next_index + 1;
+    let lamports = rent + rollover_fee * remaining;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        Some(0)
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_negative_underflow() {
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = 500u64;
+    // Lamports less than rent alone
+    let lamports = rent - 1;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        None
+    );
+    // Lamports between rent and rent + reserved
+    let remaining = capacity - next_index + 1;
+    let lamports = rent + rollover_fee * remaining - 1;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        None
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_next_index_zero() {
+    // First leaf at index 0 does not pay rollover fee.
+    // remaining = capacity - 0 + 1 = capacity + 1
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = 0u64;
+    let remaining = capacity + 1; // 1001
+    let lamports = rent + rollover_fee * remaining + 42;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        Some(42)
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_next_index_at_capacity() {
+    // Tree is full: next_index == capacity
+    // remaining = capacity - capacity + 1 = 1
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = capacity;
+    let remaining = 1; // one slot reserved
+    let lamports = rent + rollover_fee * remaining + 99;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        Some(99)
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_next_index_exceeds_capacity() {
+    // Edge case: next_index > capacity should return None (checked_sub underflow)
+    let rent = 1_000_000u64;
+    let rollover_fee = 100u64;
+    let capacity = 1000u64;
+    let next_index = 1001u64;
+    let lamports = rent + 999_999;
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        None
+    );
+}
+
+#[test]
+fn test_compute_claimable_excess_zero_rollover_fee() {
+    // Accounts with rollover_fee == 0 (e.g. V1 nullifier queues)
+    let rent = 1_000_000u64;
+    let rollover_fee = 0u64;
+    let capacity = 1000u64;
+    let next_index = 500u64;
+    let lamports = rent + 7777;
+    // reserved = 0 * 501 = 0
+    assert_eq!(
+        compute_claimable_excess(lamports, rent, rollover_fee, capacity, next_index),
+        Some(7777)
+    );
+}

program-libs/merkle-tree-metadata/src/fee.rs

@@ -43,4 +43,5 @@ light-compressible = { workspace = true }
 light-token-client = { workspace = true }
 light-token-interface = { workspace = true }
 light-zero-copy = { workspace = true }
+light-merkle-tree-metadata = { workspace = true }
 borsh = { workspace = true }