Feat/fuzz testing escrow [EXO-5]

[sebatustra]

Summary

• Migrate escrow fuzz tests from honggfuzz to Trident v0.12.0 — stateful, SVM-integrated harnesses with no external binary required
• fuzz_escrow — tests the core lifecycle: deposit, release (50% valid / 50% garbage proof), and double-spend replay. Verifies that valid SMT proofs succeed, garbage proofs are rejected without touching balances, and replayed releases are permanently rejected
• fuzz_reset_smt — tests the SMT reset lifecycle across multiple tree generations. Verifies that nonces from previous generations are rejected after a reset, and that balances are never affected by a reset
• Shared helpers extracted into shared.rs to avoid duplication between harnesses
• README documents how to run the harnesses and debug with program logs

Test plan

• Build the program: cargo build-sbf (from repo root)
• Run core lifecycle harness: cd contra-escrow-program/tests/trident-tests && cargo run --bin fuzz_escrow
• Run SMT reset harness: cargo run --bin fuzz_reset_smt
• Debug a specific iteration: TRIDENT_FUZZ_DEBUG=0000000000000000 ./target/debug/fuzz_escrow 2>&1 | head -200

Coverage Report

Component	Lines Hit	Lines Total	Coverage	Artifact
Core	7,103	8,411	84.4%	rust-unit-coverage-reports
Indexer	12,130	14,212	85.4%	rust-unit-coverage-reports
Gateway	952	1,076	88.5%	rust-unit-coverage-reports
Auth	541	596	90.8%	rust-unit-coverage-reports
Withdraw Program	118	230	51.3%	unit-coverage-reports
Escrow Program	1,170	1,951	60.0%	unit-coverage-reports
E2E Integration	7,909	11,473	68.9%	e2e-coverage-reports
Total	29,923	37,949	78.9%

Last updated: 2026-04-15 17:36:37 UTC by E2E Integration

[linear]

EXO-5 Fuzz Testing for the Escrow on-chain Program

[greptile-apps]

Greptile Summary

Adds two honggfuzz harnesses (fuzz_escrow and fuzz_reset_smt) that stress-test the escrow program's deposit/release/double-spend lifecycle and SMT reset lifecycle, sharing setup helpers via a contra_escrow_fuzz lib crate. Dependency version pins intentionally mirror the integration-tests pattern for LiteSVM compatibility.

• The final balance invariant in fuzz_reset_smt only asserts the instance ATA; the symmetric user-balance check present in fuzz_escrow is absent, leaving a gap that would miss bugs where tokens are silently credited to the user without a corresponding escrow debit.

Confidence Score: 5/5

Safe to merge — no P0 or P1 issues found; all remaining findings are P2 style improvements

The only substantive gap (missing user-balance check in fuzz_reset_smt's final invariant) is a test-coverage improvement rather than a defect in the program under test. All other findings are code-quality suggestions. P2-only findings default to 5/5 per the scoring guidance.

contra-escrow-program/tests/fuzz/src/bin/fuzz_reset_smt.rs — missing user balance assertion in final invariant

Important Files Changed

Filename	Overview
contra-escrow-program/tests/fuzz/src/lib.rs	Shared helpers (FuzzContext, setup_fuzz_context, build_release_ix, clamp_*) are well-structured; minor issue with FuzzContext carrying fields unused by one harness
contra-escrow-program/tests/fuzz/src/bin/fuzz_escrow.rs	Solid harness covering deposit/release/double-spend with correct per-op and final balance invariants on both instance and user sides
contra-escrow-program/tests/fuzz/src/bin/fuzz_reset_smt.rs	SMT reset harness is mostly correct but final invariant only verifies instance balance, leaving user-side conservation unchecked
contra-escrow-program/tests/fuzz/Cargo.toml	Pinned spl-token/spl-associated-token-account versions intentionally match the integration-tests LiteSVM-compatible pins (commented in integration-tests Cargo.toml)
contra-escrow-program/tests/fuzz/README.md	Comprehensive README covering prerequisites, run commands, crash replay steps, and 5 operational gotchas

Sequence Diagram

sequenceDiagram
    participant F as Fuzzer
    participant H as Harness
    participant L as LiteSVM
    participant P as Escrow Program

    F->>H: raw bytes (arbitrary input)
    H->>H: deserialize FuzzInput (Vec<Op>)
    H->>L: setup_fuzz_context() — fresh instance
    loop for each Op (max 32)
        H->>L: warp_to_slot (unique blockhash)
        alt Deposit
            H->>P: DepositFunds ix
            P-->>L: transfer user→escrow ATA
            H->>H: assert per-op balance shift
        else Release (valid proof)
            H->>H: generate exclusion proof from local SMT
            H->>P: ReleaseFunds ix (1.2 M CU budget)
            P-->>L: verify SMT proof, transfer escrow→user, update root
            H->>H: update local SMT mirror
            H->>H: assert per-op balances
        else Release (invalid/garbage proof)
            H->>P: ReleaseFunds ix (garbage proof)
            P-->>L: reject tx
            H->>H: assert balances unchanged
        else DoubleSpend (fuzz_escrow only)
            H->>P: replay previous ReleaseFunds verbatim
            P-->>L: reject (nonce already in SMT root)
            H->>H: assert balances unchanged
        else ResetSmtRoot (fuzz_reset_smt only)
            H->>P: ResetSmtRoot ix
            P-->>L: advance tree index, clear root
            H->>H: increment local tree_index, reset local SMT
        else ReleaseStaleNonce (fuzz_reset_smt only)
            H->>P: ReleaseFunds ix with prev-gen nonce
            P-->>L: reject (nonce outside current tree range)
            H->>H: assert balances unchanged
        end
    end
    H->>H: final invariant: instance == deposited − released

Loading

_{Reviews (1): Last reviewed commit: "fuzz testing implemented with honggfuzz" | Re-trigger Greptile}