Testing Guide

Testing Guide

Unit · Integration · Fuzz · Formal Verification · Load · Chaos · CI/CD · Module-Aware

Complete testing methodology for all five on-chain programs deployed by Groovy Company, Inc. across the three production modules — Equities (Module 1), Real Estate (Module 2), and CORECM — Carbon Ore, Rare Earth, and Critical Minerals (Module 3). This guide defines test strategy, coverage targets, execution procedures, fixture data, and CI/CD pipeline configuration. Required reading for contributors, auditors verifying test coverage, and the QA team executing pre-deployment validation.

The same test apparatus exercises all three modules. Module-specific test scenarios (Module 2 NAV-deviation enforcement, Module 3 federal-action freeze coordination) sit alongside cross-module scenarios (custody, holding period across Reg D / Reg S / Reg CF, OFAC, AML).

---

Table of Contents

1. Testing Strategy
2. Environment Setup
3. Unit Tests
4. Integration Tests
5. Fuzz Testing
6. Formal Verification (Certora)
7. Load Testing
8. Chaos Testing
9. Test Fixtures and Data
10. Coverage Requirements
11. CI/CD Pipeline
12. Pre-Deployment Checklist
13. Troubleshooting

---

1. Testing Strategy

1.1 Testing Pyramid

                    ┌──────────┐
                    │  Formal  │  Certora Prover — 6 invariants
                    │  Verify  │  Mathematical proof, not sampling
                    ├──────────┤  E.4 covers module-aware extensions
                  ┌─┤   Load   ├─┐  600 TPS sustained
                  │ │  & Chaos │ │  Oracle failure injection (all 7)
                  │ ├──────────┤ │
                ┌─┤ │  Fuzz    │ ├─┐  100,000+ random inputs
                │ │ │  Testing │ │ │  Hook + CPMM + NAV + Classification
                │ │ ├──────────┤ │ │
              ┌─┤ │ │Integration│ │ ├─┐  42 controls end-to-end
              │ │ │ │  Tests   │ │ │ │  Full lifecycle per module
              │ │ │ ├──────────┤ │ │ │
            ┌─┤ │ │ │  Unit    │ │ │ ├─┐  Per-control
            │ │ │ │ │  Tests   │ │ │ │ │  Per-function
            └─┴─┴─┴─┴──────────┴─┴─┴─┴─┘
              HIGH VOLUME ──────── LOW VOLUME
              FAST ──────────────── SLOW

1.2 Coverage Targets

Test Type	Tool	Coverage Target	Run Time	Frequency
Unit	cargo test	100% control logic; 100% module-aware extensions	<60 seconds	Every commit
Integration	anchor test	All 42 controls E2E across Module 1, 2, and 3	<5 minutes	Every PR
Fuzz	cargo fuzz	Transfer Hook, CPMM, NAV oracle, Classification oracle	100,000+ runs	Weekly + pre-release
Formal verification	Certora Prover	6 invariants — E.4 covers module-aware extensions	~30 minutes	Pre-release
Load	Custom generator	600 TPS sustained across all modules	~15 minutes	Pre-release
Chaos	Failure injection	All fail-safe paths across 7 oracle categories	~30 minutes	Monthly + pre-release

1.3 What Gets Tested Where

Component	Unit	Integration	Fuzz	Formal	Load	Chaos	Module Scope
Transfer Hook (42 controls)	Each control individually	Full 42-control execution per module	Random inputs	E.1, E.2, E.4, E.6	600 TPS with hooks	Oracle failure	All modules
CPMM arithmetic	calculate_output_amount	Buy/sell/fee flows	u128 overflow	E.5 (fee accuracy)	Concurrent swaps	—	All modules
Global Pool	Deposit function	Fee routing across modules	Extraction attempts	E.3 (non-extract)	Fee accumulation	—	All modules
Custody Oracle	Signature verification	Attestation flow	Malformed payloads	E.1, E.2	Per-block update	Relay killed	All modules
Circuit Breakers	Trigger/reset logic	Price impact + volume halt + NAV deviation + Classification stale	Boundary values	E.6 (correctness)	Sustained load	TWAP stale	All modules + M2 + M3
Holding Period	Timer logic across Reg D / Reg S / Reg CF	Lock/unlock lifecycle per regime	Timestamp edge cases	—	—	—	All modules
Governance	Proposal/vote/execute	Timelock enforcement; module-specific param adjustments	—	—	—	—	All modules
NAV Oracle	Signature verification + deviation math	Module 2 NAV-deviation lifecycle	Malformed appraisal payloads	E.4 (covered)	NAV updates per cycle	Relay killed; deviation injection	Module 2
Classification Oracle	Federal-action state transitions	Module 3 federal-action freeze E2E	Malformed federal-action payloads	E.4 (covered)	Federal-action storms	Relay killed; federal-action injection	Module 3

---

2. Environment Setup

2.1 Test Dependencies

# Core
rustup update stable
cargo install cargo-tarpaulin    # Coverage
cargo install cargo-fuzz         # Fuzz testing
cargo install cargo-nextest      # Fast test runner

# Anchor
anchor --version  # Must be 0.30+

# Node.js (integration tests)
yarn install

# Solana test validator
solana-test-validator --version

2.2 Local Test Validator

# Start with Token-2022 support
solana-test-validator \
  --bpf-program TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
    target/deploy/spl_token_2022.so \
  --reset \
  --quiet

# Verify
solana cluster-version

2.3 Test Configuration

# Anchor.toml
[test]
startup_wait = 5000

[test.validator]
url = "http://localhost:8899"

[[test.validator.clone]]
address = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"

[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

---

3. Unit Tests

3.1 Running Unit Tests

# All programs
cargo test --workspace

# Specific program
cargo test -p transfer-hook
cargo test -p amm
cargo test -p liquidity-pool
cargo test -p governance
cargo test -p oracle-aggregator

# Module-specific test modules
cargo test -p transfer-hook nav_deviation        # Module 2 extensions
cargo test -p transfer-hook federal_action       # Module 3 extensions
cargo test -p oracle-aggregator nav_oracle       # Module 2 oracle
cargo test -p oracle-aggregator classification_oracle  # Module 3 oracle

# Verbose output (shows print statements)
cargo test --workspace -- --nocapture

# Fast runner (parallel execution)
cargo nextest run --workspace

3.2 Transfer Hook Unit Tests

Each of the 42 controls has dedicated unit tests covering pass, fail, and boundary conditions. Module-aware extensions (Module 2 CB-21 NAV-deviation; Module 3 REG-42 federal-action) have additional dedicated test modules.

Test Pattern (Wallet Limit, Cross-Module)

// tests/unit/transfer_hook/test_wallet_limit.rs

#[cfg(test)]
mod tests {
    use super::*;
    use crate::state::SecurityConfig;

    fn default_config() -> SecurityConfig {
        SecurityConfig {
            max_wallet_percent: 499, // 4.99%
            ..SecurityConfig::default()
        }
    }

    #[test]
    fn test_wallet_limit_under_threshold() {
        // Wallet holds 4.00% → transfer of 0.50% → total 4.50% → PASS
        let config = default_config();
        let current_balance = 40_000_000;   // 4.00% of 1B supply
        let transfer_amount = 5_000_000;    // 0.50%
        let total_supply = 1_000_000_000;

        let result = check_wallet_limit(
            current_balance,
            transfer_amount,
            total_supply,
            config.max_wallet_percent,
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_wallet_limit_at_exact_threshold() {
        // Wallet holds 0% → transfer of exactly 4.99% → PASS (≤ 4.99%)
        let config = default_config();
        let current_balance = 0;
        let transfer_amount = 49_900_000;   // 4.99% of 1B
        let total_supply = 1_000_000_000;

        let result = check_wallet_limit(
            current_balance,
            transfer_amount,
            total_supply,
            config.max_wallet_percent,
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_wallet_limit_exceeds_threshold() {
        // Wallet holds 0% → transfer of 5.00% → FAIL (> 4.99%)
        let config = default_config();
        let current_balance = 0;
        let transfer_amount = 50_000_000;   // 5.00% of 1B
        let total_supply = 1_000_000_000;

        let result = check_wallet_limit(
            current_balance,
            transfer_amount,
            total_supply,
            config.max_wallet_percent,
        );
        assert!(result.is_err());
        assert_eq!(
            result.unwrap_err(),
            TransferHookError::WalletLimitExceeded.into()
        );
    }

    #[test]
    fn test_wallet_limit_module_2_higher_cap() {
        // Module 2 mints may be issuer-configured up to 9.99%
        let mut config = default_config();
        config.max_wallet_percent = 999; // 9.99%

        let current_balance = 0;
        let transfer_amount = 99_000_000;   // 9.90% — within Module 2 cap
        let total_supply = 1_000_000_000;

        let result = check_wallet_limit(
            current_balance,
            transfer_amount,
            total_supply,
            config.max_wallet_percent,
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_wallet_limit_max_u64() {
        // Edge case: maximum u64 values → no overflow
        let config = default_config();
        let result = check_wallet_limit(
            u64::MAX / 2,
            u64::MAX / 2,
            u64::MAX,
            config.max_wallet_percent,
        );
        // Should not panic — u128 intermediate arithmetic
        assert!(result.is_ok() || result.is_err());
    }
}

Module 2 — NAV-Deviation Unit Tests

// tests/unit/transfer_hook/test_nav_deviation.rs

#[cfg(test)]
mod nav_deviation_tests {
    use super::*;

    fn module_2_config() -> SecurityConfig {
        SecurityConfig {
            module: ModuleId::RealEstate,
            max_wallet_percent: 999,                    // M2 may use 9.99%
            nav_deviation_max_bps: Some(2200),          // 22% default
            nav_reappraisal_max_age_secs: Some(7_776_000), // 90 days
            nav_circuit_breaker_enabled: Some(true),
            ..SecurityConfig::default()
        }
    }

    #[test]
    fn test_nav_deviation_within_tolerance() {
        // On-chain price 105, NAV 100 → +5% (500 bps) → within 22%
        let config = module_2_config();
        let on_chain_price_usd = 10_500_000_000u128;
        let appraised_nav_usd  = 10_000_000_000u128;
        let result = check_nav_deviation(on_chain_price_usd, appraised_nav_usd, &config);
        assert!(result.is_ok());
    }

    #[test]
    fn test_nav_deviation_exact_threshold() {
        // 22% above NAV — exactly at threshold → PASS (≤)
        let config = module_2_config();
        let appraised_nav_usd  = 10_000_000_000u128;
        let on_chain_price_usd = 12_200_000_000u128; // +22.00%
        let result = check_nav_deviation(on_chain_price_usd, appraised_nav_usd, &config);
        assert!(result.is_ok());
    }

    #[test]
    fn test_nav_deviation_exceeds_threshold() {
        // 23% above NAV — exceeds 22% → FAIL
        let config = module_2_config();
        let appraised_nav_usd  = 10_000_000_000u128;
        let on_chain_price_usd = 12_300_000_000u128; // +23.00%
        let result = check_nav_deviation(on_chain_price_usd, appraised_nav_usd, &config);
        assert!(result.is_err());
        assert_eq!(
            result.unwrap_err(),
            TransferHookError::PriceImpactExceeded.into()
        );
    }

    #[test]
    fn test_nav_deviation_negative_within_tolerance() {
        // 15% below NAV — within tolerance
        let config = module_2_config();
        let appraised_nav_usd  = 10_000_000_000u128;
        let on_chain_price_usd =  8_500_000_000u128; // -15%
        let result = check_nav_deviation(on_chain_price_usd, appraised_nav_usd, &config);
        assert!(result.is_ok());
    }

    #[test]
    fn test_nav_stale_pauses_mint() {
        let config = module_2_config();
        let last_appraisal_ts = 1_700_000_000;
        let now = last_appraisal_ts + 7_776_001; // exceeds 90-day threshold by 1s
        let result = check_nav_freshness(last_appraisal_ts, now, &config);
        assert!(result.is_err());
    }

    #[test]
    fn test_module_1_skips_nav_check() {
        // Module 1 mint — no NAV oracle → check returns Ok unconditionally
        let config = SecurityConfig {
            module: ModuleId::Equities,
            ..SecurityConfig::default()
        };
        let result = check_nav_deviation(0, 0, &config);
        assert!(result.is_ok());
    }
}

Module 3 — Federal-Action Freeze Unit Tests

// tests/unit/transfer_hook/test_federal_action.rs

#[cfg(test)]
mod federal_action_tests {
    use super::*;

    fn module_3_config() -> SecurityConfig {
        SecurityConfig {
            module: ModuleId::Corecm,
            classification_max_age_secs: Some(86_400), // 24h
            federal_action_freeze_enabled: Some(true),
            ..SecurityConfig::default()
        }
    }

    #[test]
    fn test_federal_action_inactive_passes() {
        let config = module_3_config();
        let oracle_state = ClassificationOracleState {
            federal_action_active: false,
            ..ClassificationOracleState::default()
        };
        let result = enforce_federal_action_freeze(&oracle_state, &config);
        assert!(result.is_ok());
    }

    #[test]
    fn test_federal_action_active_blocks() {
        let config = module_3_config();
        let oracle_state = ClassificationOracleState {
            federal_action_active: true,
            active_action_refs: vec!["EO-14118".to_string()],
            ..ClassificationOracleState::default()
        };
        let result = enforce_federal_action_freeze(&oracle_state, &config);
        assert!(result.is_err());
        assert_eq!(
            result.unwrap_err(),
            TransferHookError::RegulatoryOverride.into()
        );
    }

    #[test]
    fn test_classification_stale_flagged_not_blocked() {
        // Classification stale beyond threshold — flagged but transfer continues
        let config = module_3_config();
        let last_refresh_ts = 1_700_000_000;
        let now = last_refresh_ts + 86_401;  // 1s past 24h
        let result = check_classification_freshness(last_refresh_ts, now, &config);
        assert!(result.is_ok());        // Allowed
        assert!(result.unwrap().flagged_for_review);
    }

    #[test]
    fn test_module_1_skips_federal_action_check() {
        // Module 1 mint — no Classification oracle → check returns Ok
        let config = SecurityConfig {
            module: ModuleId::Equities,
            ..SecurityConfig::default()
        };
        let result = enforce_federal_action_freeze(
            &ClassificationOracleState::default(),
            &config,
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_federal_action_freeze_can_be_disabled_per_mint() {
        let mut config = module_3_config();
        config.federal_action_freeze_enabled = Some(false);

        let oracle_state = ClassificationOracleState {
            federal_action_active: true,
            ..ClassificationOracleState::default()
        };
        // With per-mint toggle disabled, Control 42 must be invoked manually
        let result = enforce_federal_action_freeze(&oracle_state, &config);
        assert!(result.is_ok());
    }
}

Control Test Matrix (Module-Aware)

Control	Pass Test	Fail Test	Boundary Test	Module-Aware Variant
CV-01 (Custody)	Supply = balance	Supply > balance	Supply = balance + 1	Asset class per module
CV-02 (Oracle fresh)	Slot age = 0	Slot age = 5	Slot age = 1	All modules
SC-30 (OFAC sender)	Wallet not on SDN	Wallet on SDN	—	All modules
IV-09 (AML)	Score = 25	Score = 75	Score = 30, 31, 70, 71	Module 3 enhanced KYC depth
PL-16 (Wallet limit)	4.50% post (M1/M3)	5.01% post (M1/M3)	4.99% exactly	Module 2 cap up to 9.99%
CB-20 (Price halt)	8% move in 5 min	12% move in 5 min	10.0% exactly	All modules
CB-21 (Price impact)	1.5% impact	3.0% impact	2.0% exactly	Module 2: NAV deviation also checked
HP-24 (Holding period)	Reg D 7 mo elapsed	Reg D 5 mo elapsed	Reg D 6 mo exactly	Reg D / Reg S / Reg CF variants
REG-42 (Reg freeze)	Not paused	Paused by authority	—	Module 3: federal-action variant

3.3 CPMM Arithmetic Unit Tests

#[cfg(test)]
mod cpmm_tests {
    use super::*;

    #[test]
    fn test_basic_swap() {
        // 10 SOL into pool with 100 SOL / 1M tokens, 5% fee
        let result = calculate_output_amount(
            10_000_000_000,      // 10 SOL (lamports)
            100_000_000_000,     // 100 SOL reserve
            1_000_000_000_000,   // 1M tokens (9 decimals)
            500,                 // 5% fee
        ).unwrap();

        // Expected: ~86,758 tokens (after fee)
        assert!(result.output_amount > 86_000_000_000);
        assert!(result.output_amount < 87_000_000_000);

        // Fee should be 5% of input
        let expected_fee = 10_000_000_000 * 500 / 10_000;
        assert_eq!(result.fee_amount, expected_fee);
    }

    #[test]
    fn test_k_invariant_preserved() {
        let reserve_sol   = 100_000_000_000u64;
        let reserve_token = 1_000_000_000_000u64;
        let k_before = reserve_sol as u128 * reserve_token as u128;

        let result = calculate_output_amount(
            10_000_000_000,
            reserve_sol,
            reserve_token,
            500,
        ).unwrap();

        let new_sol   = reserve_sol + 10_000_000_000 - result.fee_amount;
        let new_token = reserve_token - result.output_amount;
        let k_after   = new_sol as u128 * new_token as u128;

        // k should only increase (fees add to pool) — invariant holds for
        // Module 1, Module 2, and Module 3 mints uniformly
        assert!(k_after >= k_before);
    }

    #[test]
    fn test_fee_distribution_sums_to_total() {
        // 0.44 + 2.00 + 1.50 + 1.06 = 5.00% — must be exact across all modules
        let pool_bps     = 44u16;
        let issuer_bps   = 200u16;
        let staking_bps  = 150u16;
        let protocol_bps = 106u16;
        let total_bps    = 500u16;
        assert_eq!(pool_bps + issuer_bps + staking_bps + protocol_bps, total_bps);
    }

    #[test]
    fn test_u128_no_overflow() {
        // Max u64 reserves — must not overflow
        let result = calculate_output_amount(
            u64::MAX / 100,
            u64::MAX / 2,
            u64::MAX / 2,
            500,
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_fee_accuracy_within_1_lamport() {
        // Certora invariant E.5: |actual_fee - expected_fee| ≤ 1
        for amount in [1, 100, 10_000, 1_000_000, u64::MAX / 1000] {
            let result = calculate_output_amount(
                amount,
                100_000_000_000,
                1_000_000_000_000,
                500,
            );
            if let Ok(r) = result {
                let expected_fee = (amount as u128 * 500 / 10_000) as u64;
                let diff = if r.fee_amount > expected_fee {
                    r.fee_amount - expected_fee
                } else {
                    expected_fee - r.fee_amount
                };
                assert!(diff <= 1, "Fee accuracy > 1 lamport for amount {}", amount);
            }
        }
    }
}

3.4 Holding Period Unit Tests — Reg D / Reg S / Reg CF

#[cfg(test)]
mod holding_period_tests {
    use super::*;

    // Holding-period constants — immutable program constants
    const REG_D_HOLDING_SECS:  i64 = 15_778_800;  // 6 months
    const REG_S_HOLDING_SECS:  i64 = 31_536_000;  // 12 months
    const REG_CF_HOLDING_SECS: i64 = 31_536_000;  // 12 months

    #[test]
    fn test_reg_d_locked_within_6_months() {
        let account = HoldingPeriodAccount {
            jurisdiction: Jurisdiction::US,
            regime: HoldingRegime::RegD,
            purchase_timestamp: 1_700_000_000,
            holding_period_secs: REG_D_HOLDING_SECS,
            is_locked: true,
            ..Default::default()
        };

        // 5 months later — still locked under Reg D
        let clock = mock_clock(1_700_000_000 + 13_000_000);
        let result = enforce_holding_period(&account, &clock);
        assert_eq!(result.unwrap_err(), TransferHookError::TokensLocked.into());
    }

    #[test]
    fn test_reg_d_unlocked_after_6_months() {
        let account = HoldingPeriodAccount {
            jurisdiction: Jurisdiction::US,
            regime: HoldingRegime::RegD,
            purchase_timestamp: 1_700_000_000,
            holding_period_secs: REG_D_HOLDING_SECS,
            is_locked: true,
            ..Default::default()
        };

        // 7 months later — unlocked under Reg D
        let clock = mock_clock(1_700_000_000 + 18_000_000);
        let result = enforce_holding_period(&account, &clock);
        assert!(result.is_ok());
    }

    #[test]
    fn test_reg_d_exact_6_month_boundary() {
        let account = HoldingPeriodAccount {
            jurisdiction: Jurisdiction::US,
            regime: HoldingRegime::RegD,
            purchase_timestamp: 1_700_000_000,
            holding_period_secs: REG_D_HOLDING_SECS,
            is_locked: true,
            ..Default::default()
        };

        // Exactly 6 months — should PASS (≥ threshold)
        let clock = mock_clock(1_700_000_000 + REG_D_HOLDING_SECS);
        let result = enforce_holding_period(&account, &clock);
        assert!(result.is_ok());

        // 1 second before — should FAIL
        let clock = mock_clock(1_700_000_000 + REG_D_HOLDING_SECS - 1);
        let result = enforce_holding_period(&account, &clock);
        assert!(result.is_err());
    }

    #[test]
    fn test_reg_s_12_month_holding() {
        let account = HoldingPeriodAccount {
            jurisdiction: Jurisdiction::NonUS,
            regime: HoldingRegime::RegS,
            purchase_timestamp: 1_700_000_000,
            holding_period_secs: REG_S_HOLDING_SECS,
            is_locked: true,
            ..Default::default()
        };

        // 11 months — locked under Reg S
        let clock = mock_clock(1_700_000_000 + 29_000_000);
        assert!(enforce_holding_period(&account, &clock).is_err());

        // 13 months — unlocked under Reg S
        let clock = mock_clock(1_700_000_000 + 34_000_000);
        assert!(enforce_holding_period(&account, &clock).is_ok());
    }

    #[test]
    fn test_reg_cf_12_month_holding() {
        let account = HoldingPeriodAccount {
            jurisdiction: Jurisdiction::RegCF,
            regime: HoldingRegime::RegCF,
            purchase_timestamp: 1_700_000_000,
            holding_period_secs: REG_CF_HOLDING_SECS,
            is_locked: true,
            ..Default::default()
        };

        // 11 months — locked under Reg CF
        let clock = mock_clock(1_700_000_000 + 29_000_000);
        assert!(enforce_holding_period(&account, &clock).is_err());

        // 13 months — unlocked under Reg CF
        let clock = mock_clock(1_700_000_000 + 34_000_000);
        assert!(enforce_holding_period(&account, &clock).is_ok());
    }

    #[test]
    fn test_already_unlocked() {
        let account = HoldingPeriodAccount {
            is_locked: false,
            ..Default::default()
        };
        // Already unlocked — always passes regardless of regime
        let clock = mock_clock(0);
        assert!(enforce_holding_period(&account, &clock).is_ok());
    }
}

---

4. Integration Tests

4.1 Running Integration Tests

# All integration tests (starts local validator)
anchor test

# Specific test file
anchor test -- --grep "transfer hook"
anchor test -- --grep "circuit breaker"
anchor test -- --grep "full lifecycle"
anchor test -- --grep "module 2"
anchor test -- --grep "module 3"

# Skip local validator (if already running)
anchor test --skip-local-validator

4.2 Full Lifecycle Test — Module 1 (Equities)

The most important integration test for Module 1 — verifies the complete ST22 token lifecycle from mint to secondary trade.

// tests/e2e/full-lifecycle-module1.ts

describe('ST22 Full Lifecycle — Module 1 Equities', () => {
  let mint:           PublicKey;
  let issuerWallet:   Keypair;
  let investorRegD:   Keypair;
  let investorRegS:   Keypair;
  let investorRegCF:  Keypair;

  before(async () => {
    issuerWallet  = Keypair.generate();
    investorRegD  = Keypair.generate();
    investorRegS  = Keypair.generate();
    investorRegCF = Keypair.generate();
    await airdrop(issuerWallet.publicKey, 100);
    await airdrop(investorRegD.publicKey, 100);
    await airdrop(investorRegS.publicKey, 100);
    await airdrop(investorRegCF.publicKey, 100);
  });

  it('Step 1: Creates Module 1 ST22 mint with Transfer Hook', async () => {
    mint = await createST22Mint({
      authority:   issuerWallet,
      hookProgram: transferHookProgramId,
      decimals:    9,
      module:      'equities',
    });

    const mintInfo = await getMint(connection, mint, 'confirmed', TOKEN_2022_PROGRAM_ID);
    const hookExt  = getTransferHook(mintInfo);
    expect(hookExt.programId.toBase58()).to.equal(transferHookProgramId.toBase58());
  });

  it('Step 2: Initializes SecurityConfig for Module 1', async () => {
    await program.methods
      .initializeSecurityConfig({
        module:                  { equities: {} },
        maxWalletPercent:        499,
        circuitBreakerThreshold: 3000,
        circuitBreakerCooldown:  new BN(86400),
        priceImpactMaxBps:       200,
        twapWindowSecs:          1800,
        holdingPeriodEnabled:    true,
      })
      .accounts({ mint, authority: issuerWallet.publicKey })
      .signers([issuerWallet])
      .rpc();

    const config = await program.account.securityConfig.fetch(securityConfigPda);
    expect(config.maxWalletPercent).to.equal(499);
    expect(config.module).to.deep.equal({ equities: {} });
    expect(config.holdingPeriodConfig.enabled).to.be.true;
  });

  it('Step 3: Initializes CustodyOracle (cross-module)', async () => {
    await oracleProgram.methods
      .initializeCustodyOracle(empirePublicKey)
      .accounts({ mint, authority: issuerWallet.publicKey })
      .signers([issuerWallet])
      .rpc();

    const oracle = await oracleProgram.account.custodyOracle.fetch(custodyOraclePda);
    expect(oracle.empirePubkey.toBase58()).to.equal(empirePublicKey.toBase58());
  });

  it('Step 4: Mints ST22 tokens (1:1 with Empire custody)', async () => {
    await updateCustodyOracle(mint, { custodiedBalance: 1_000_000_000, tokenSupply: 0 });
    await mintTo(connection, issuerWallet, mint, issuerTokenAccount,
                 issuerWallet, 1_000_000_000);
    await updateCustodyOracle(mint, {
      custodiedBalance: 1_000_000_000, tokenSupply: 1_000_000_000,
    });

    const oracle = await oracleProgram.account.custodyOracle.fetch(custodyOraclePda);
    expect(oracle.custodiedBalance.toNumber()).to.equal(oracle.tokenSupply.toNumber());
  });

  it('Step 5: Creates HoldingPeriodAccount for Reg D investor', async () => {
    await program.methods
      .initializeHoldingPeriod({ regime: { regD: {} }, jurisdiction: { us: {} } })
      .accounts({
        mint,
        beneficiary: investorRegD.publicKey,
        authority:   empireAuthority.publicKey,
      })
      .signers([empireAuthority])
      .rpc();

    const holding = await program.account.holdingPeriodAccount.fetch(holdingPdaRegD);
    expect(holding.regime).to.deep.equal({ regD: {} });
    expect(holding.holdingPeriodSecs.toNumber()).to.equal(15_778_800);
    expect(holding.isLocked).to.be.true;
  });

  it('Step 5b: Creates HoldingPeriodAccount for Reg S investor', async () => {
    await program.methods
      .initializeHoldingPeriod({ regime: { regS: {} }, jurisdiction: { nonUs: {} } })
      .accounts({
        mint,
        beneficiary: investorRegS.publicKey,
        authority:   empireAuthority.publicKey,
      })
      .signers([empireAuthority])
      .rpc();

    const holding = await program.account.holdingPeriodAccount.fetch(holdingPdaRegS);
    expect(holding.holdingPeriodSecs.toNumber()).to.equal(31_536_000);
  });

  it('Step 5c: Creates HoldingPeriodAccount for Reg CF investor', async () => {
    await program.methods
      .initializeHoldingPeriod({ regime: { regCf: {} }, jurisdiction: { regCf: {} } })
      .accounts({
        mint,
        beneficiary: investorRegCF.publicKey,
        authority:   empireAuthority.publicKey,
      })
      .signers([empireAuthority])
      .rpc();

    const holding = await program.account.holdingPeriodAccount.fetch(holdingPdaRegCF);
    expect(holding.regime).to.deep.equal({ regCf: {} });
    expect(holding.holdingPeriodSecs.toNumber()).to.equal(31_536_000);
  });

  it('Step 6: Transfers tokens to Reg D investor (hook executes)', async () => {
    const tx = await transferChecked(
      connection, issuerWallet, issuerTokenAccount,
      mint, investorRegDTokenAccount, issuerWallet, 50_000_000,
      9, [], undefined, TOKEN_2022_PROGRAM_ID,
    );
    expect(tx).to.be.a('string');
  });

  it('Step 7: Reg D investor cannot sell during holding period', async () => {
    try {
      await transferChecked(
        connection, investorRegD, investorRegDTokenAccount,
        mint, someOtherAccount, investorRegD, 10_000_000,
        9, [], undefined, TOKEN_2022_PROGRAM_ID,
      );
      expect.fail('Should have thrown TokensLocked');
    } catch (error) {
      expect(error.message).to.include('6024');
    }
  });

  it('Step 8: After Reg D 6-month holding period, investor can sell', async () => {
    await advanceClock(15_778_800 + 1);
    const tx = await transferChecked(
      connection, investorRegD, investorRegDTokenAccount,
      mint, someOtherAccount, investorRegD, 10_000_000,
      9, [], undefined, TOKEN_2022_PROGRAM_ID,
    );
    expect(tx).to.be.a('string');
  });

  it('Step 9: Wallet limit enforced (4.99%) on Module 1', async () => {
    const fivePercent = 50_000_000;
    try {
      await transferChecked(
        connection, issuerWallet, issuerTokenAccount,
        mint, freshWalletAccount, issuerWallet, fivePercent,
        9, [], undefined, TOKEN_2022_PROGRAM_ID,
      );
      expect.fail('Should have thrown WalletLimitExceeded');
    } catch (error) {
      expect(error.message).to.include('6020');
    }
  });

  it('Step 10: Custody discrepancy halts all transfers', async () => {
    await updateCustodyOracle(mint, {
      custodiedBalance: 999_999_999,
      tokenSupply:      1_000_000_000,
    });
    try {
      await transferChecked(
        connection, issuerWallet, issuerTokenAccount,
        mint, investorRegDTokenAccount, issuerWallet, 1,
        9, [], undefined, TOKEN_2022_PROGRAM_ID,
      );
      expect.fail('Should have thrown CustodyDiscrepancy');
    } catch (error) {
      expect(error.message).to.include('6001');
    }
  });
});

4.3 Module 2 — Real Estate Lifecycle Test

// tests/e2e/full-lifecycle-module2.ts

describe('ST22 Full Lifecycle — Module 2 Real Estate', () => {
  let mint:         PublicKey;
  let saeIssuer:    Keypair;       // Single-Asset Entity holding underlying property
  let appraiser:    Keypair;       // Authorized licensed appraiser

  it('Initializes Module 2 SecurityConfig with NAV bounds', async () => {
    await program.methods
      .initializeSecurityConfig({
        module:                   { realEstate: {} },
        maxWalletPercent:         999,                      // Up to 9.99% for M2
        circuitBreakerThreshold:  3000,
        circuitBreakerCooldown:   new BN(86400),
        priceImpactMaxBps:        200,
        twapWindowSecs:           1800,
        holdingPeriodEnabled:     true,
        navDeviationMaxBps:       2200,                     // 22% default
        navReappraisalMaxAgeSecs: new BN(7_776_000),        // 90 days
        navCircuitBreakerEnabled: true,
      })
      .accounts({ mint, authority: saeIssuer.publicKey })
      .signers([saeIssuer])
      .rpc();
  });

  it('Initializes NAVOracle with first appraisal', async () => {
    await oracleProgram.methods
      .initializeNavOracle({
        appraisedNavUsd:      new BN(10_000_000_000),    // $10,000 per token
        appraiserId:          'APP-2026-001',
        appraisalTimestamp:   new BN(Date.now() / 1000),
      })
      .accounts({ mint, appraiserAuthority: appraiser.publicKey })
      .signers([appraiser])
      .rpc();
  });

  it('Allows trade within NAV deviation tolerance', async () => {
    // Pool price equivalent to NAV ± 5% — within 22% tolerance
    const tx = await executeSwap(mint, /* small */ 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });

  it('Pauses mint when NAV deviation exceeds tolerance', async () => {
    // Force pool price 25% above NAV
    await forcePoolPrice(mint, /* +25% */);
    try {
      await executeSwap(mint, 1_000_000, 'buy');
      expect.fail('Should have thrown PriceImpactExceeded (NAV variant)');
    } catch (error) {
      expect(error.message).to.include('6021');
    }
  });

  it('Pauses mint when NAV oracle is stale', async () => {
    await advanceClock(7_776_001);   // 90 days + 1 second
    try {
      await executeSwap(mint, 1_000_000, 'buy');
      expect.fail('Should have thrown PriceImpactExceeded (NAV stale)');
    } catch (error) {
      expect(error.message).to.include('6021');
    }
  });

  it('Resumes trading after fresh appraisal', async () => {
    await oracleProgram.methods
      .updateNavOracle({
        appraisedNavUsd:    new BN(11_000_000_000),
        appraiserId:        'APP-2026-001',
        appraisalTimestamp: new BN(Date.now() / 1000),
      })
      .accounts({ mint, appraiserAuthority: appraiser.publicKey })
      .signers([appraiser])
      .rpc();

    // Trading resumes
    const tx = await executeSwap(mint, 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });
});

4.4 Module 3 — CORECM Federal-Action Lifecycle Test

// tests/e2e/full-lifecycle-module3.ts

describe('ST22 Full Lifecycle — Module 3 CORECM', () => {
  let mint:                PublicKey;
  let baeIssuer:           Keypair;     // Basin-Asset Entity
  let classificationRelay: Keypair;     // Authorized Classification relay

  it('Initializes Module 3 SecurityConfig with classification bounds', async () => {
    await program.methods
      .initializeSecurityConfig({
        module:                     { corecm: {} },
        maxWalletPercent:           499,
        circuitBreakerThreshold:    3000,
        circuitBreakerCooldown:     new BN(86400),
        priceImpactMaxBps:          200,
        twapWindowSecs:             1800,
        holdingPeriodEnabled:       true,
        classificationMaxAgeSecs:   new BN(86_400),       // 24h
        federalActionFreezeEnabled: true,
      })
      .accounts({ mint, authority: baeIssuer.publicKey })
      .signers([baeIssuer])
      .rpc();
  });

  it('Initializes ClassificationOracle with USGS / DOE status', async () => {
    await oracleProgram.methods
      .initializeClassificationOracle({
        usgsCriticalStatus:    'critical_mineral_rare_earth',
        doeMaterialsStatus:    'high_priority',
        section232Applicable:  false,
        dpaTitleIIIApplicable: false,
        federalActionActive:   false,
        activeActionRefs:      [],
      })
      .accounts({ mint, classificationRelay: classificationRelay.publicKey })
      .signers([classificationRelay])
      .rpc();
  });

  it('Allows trade when no federal action is active', async () => {
    const tx = await executeSwap(mint, 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });

  it('Federal-action detection triggers Control 42 freeze', async () => {
    // Inject federal-action event (simulating Federal Register monitoring)
    await oracleProgram.methods
      .updateClassificationOracle({
        federalActionActive: true,
        activeActionRefs:    ['EO-14118'],
      })
      .accounts({ mint, classificationRelay: classificationRelay.publicKey })
      .signers([classificationRelay])
      .rpc();

    // Pre-flight rejects the trade with Error 6042 federal-action variant
    try {
      await executeSwap(mint, 1_000_000, 'buy');
      expect.fail('Should have thrown RegulatoryOverride');
    } catch (error) {
      expect(error.message).to.include('6042');
    }
  });

  it('Other Module 3 mints not subject to the action remain tradeable', async () => {
    // Different mint — different basin reference — federal action does not apply
    const otherMint = await createModule3Mint();
    const tx = await executeSwap(otherMint, 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });

  it('Trading resumes after federal action lifted', async () => {
    await oracleProgram.methods
      .updateClassificationOracle({
        federalActionActive: false,
        activeActionRefs:    [],
      })
      .accounts({ mint, classificationRelay: classificationRelay.publicKey })
      .signers([classificationRelay])
      .rpc();

    const tx = await executeSwap(mint, 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });
});

4.5 Circuit Breaker Integration Tests (Cross-Module)

// tests/e2e/circuit-breaker.ts

describe('Circuit Breaker', () => {
  it('blocks trade exceeding 2% price impact (any module)', async () => {
    const largeAmount = 31_000_000; // 3.1% of reserve
    try {
      await executeSwap(mint, largeAmount, 'buy');
      expect.fail('Should have thrown PriceImpactExceeded');
    } catch (error) {
      expect(error.message).to.include('6021');
    }
  });

  it('allows trade within 2% price impact', async () => {
    const safeAmount = 19_000_000;
    const tx = await executeSwap(mint, safeAmount, 'buy');
    expect(tx).to.be.a('string');
  });

  it('triggers 15-min halt on >10% move in 5 minutes', async () => {
    for (let i = 0; i < 5; i++) {
      await executeSwap(mint, 20_000_000, 'sell');
    }
    try {
      await executeSwap(mint, 1_000_000, 'sell');
      expect.fail('Should have triggered circuit breaker');
    } catch (error) {
      expect(error.message).to.include('6005');
    }
  });

  it('resumes after 15-minute cooldown', async () => {
    await advanceClock(901);
    const tx = await executeSwap(mint, 1_000_000, 'buy');
    expect(tx).to.be.a('string');
  });
});

4.6 Key Integration Test Scenarios

Scenario	File	Controls Tested	Expected Outcome	Module
Module 1 happy path: full lifecycle	e2e/full-lifecycle-module1.ts	All 42	Mint → transfer → hold → trade	M1
Module 2 happy path: NAV lifecycle	e2e/full-lifecycle-module2.ts	All 42 + NAV ext	Mint → NAV init → trade → reappraisal	M2
Module 3 happy path: federal-action lifecycle	e2e/full-lifecycle-module3.ts	All 42 + federal-action ext	Mint → classification init → freeze → resume	M3
Custody discrepancy halt	e2e/full-lifecycle-module1.ts	CV-01 to CV-06	Error 6001, all transfers halt	All
OFAC sender blocked	transfer-hook.ts	SC-30 to SC-32	Error 6003	All
AML high risk rejected	transfer-hook.ts	IV-09	Error 6006	All
Wallet limit M1 enforced (4.99%)	transfer-hook.ts	PL-16	Error 6020 at 5.00%	M1
Wallet limit M2 enforced (9.99%)	transfer-hook.ts	PL-16	Error 6020 at 10.00%	M2
Price impact blocked	e2e/circuit-breaker.ts	CB-21	Error 6021 at >2%	All
Volume halt triggered	e2e/circuit-breaker.ts	CB-23	Error 6037 at >30% daily	All
NAV deviation circuit breaker	e2e/full-lifecycle-module2.ts	CB-21 NAV variant	Error 6021 (NAV)	M2
NAV stale pause	e2e/full-lifecycle-module2.ts	CB-21 NAV stale	Error 6021 (stale)	M2
Federal-action freeze	e2e/full-lifecycle-module3.ts	REG-42 federal variant	Error 6042 (federal)	M3
Holding period: Reg D locked	transfer-hook.ts	HP-24	Error 6024 within 6 months	All
Holding period: Reg D unlocked	transfer-hook.ts	HP-24	Success after 6 months	All
Holding period: Reg S 12mo	transfer-hook.ts	HP-24	Error 6024 within 12 months	All
Holding period: Reg CF 12mo	transfer-hook.ts	HP-24	Error 6024 within 12 months	All
Regulatory freeze (cross-module)	governance.ts	REG-42	Error 6042, transfers halt	All
Fee distribution accuracy	amm.ts	—	5% total, 0.44% to Global Pool	All
LP burn verification	liquidity-pool.ts	—	LP supply = 0, no withdrawal possible	All
Global Pool only grows	liquidity-pool.ts	—	Balance increases with every trade	All
Governance timelock	governance.ts	RK-41	Proposal blocked before 48h	All

---

5. Fuzz Testing

5.1 Setup

cd programs/transfer-hook
cargo fuzz init  # First time only

5.2 Transfer Hook Fuzz Target

// fuzz/fuzz_targets/transfer_hook_fuzz.rs

#![no_main]
use libfuzzer_sys::fuzz_target;
use transfer_hook::utils::validation::*;
use transfer_hook::state::*;

fuzz_target!(|data: &[u8]| {
    if data.len() < 32 { return; }

    let amount  = u64::from_le_bytes(data[ 0.. 8].try_into().unwrap_or([0; 8]));
    let balance = u64::from_le_bytes(data[ 8..16].try_into().unwrap_or([0; 8]));
    let supply  = u64::from_le_bytes(data[16..24].try_into().unwrap_or([0; 8]));
    let max_pct = u16::from_le_bytes(data[24..26].try_into().unwrap_or([0; 2]));

    // Must not panic — should return Ok or Err
    let _ = check_wallet_limit(balance, amount, supply, max_pct);
});

5.3 CPMM Arithmetic Fuzz Target

// fuzz/fuzz_targets/cpmm_fuzz.rs

#![no_main]
use libfuzzer_sys::fuzz_target;
use amm::utils::math::*;

fuzz_target!(|data: &[u8]| {
    if data.len() < 26 { return; }

    let input       = u64::from_le_bytes(data[ 0.. 8].try_into().unwrap_or([0; 8]));
    let reserve_in  = u64::from_le_bytes(data[ 8..16].try_into().unwrap_or([0; 8]));
    let reserve_out = u64::from_le_bytes(data[16..24].try_into().unwrap_or([0; 8]));
    let fee_bps     = u16::from_le_bytes(data[24..26].try_into().unwrap_or([0; 2]));

    let result = calculate_output_amount(input, reserve_in, reserve_out, fee_bps);

    if let Ok(r) = result {
        // Invariant: output < reserve_out
        assert!(r.output_amount < reserve_out || reserve_out == 0);
        // Invariant: fee ≤ input
        assert!(r.fee_amount <= input);
        // Invariant: k only grows
        if reserve_in > 0 && reserve_out > 0 && input > 0 {
            let k_before = reserve_in as u128 * reserve_out as u128;
            let new_in   = reserve_in as u128 + input as u128 - r.fee_amount as u128;
            let new_out  = reserve_out as u128 - r.output_amount as u128;
            let k_after  = new_in * new_out;
            assert!(k_after >= k_before);
        }
    }
});

5.4 NAV Deviation Fuzz Target (Module 2)

// fuzz/fuzz_targets/nav_deviation_fuzz.rs

#![no_main]
use libfuzzer_sys::fuzz_target;
use transfer_hook::utils::nav::*;

fuzz_target!(|data: &[u8]| {
    if data.len() < 34 { return; }

    let on_chain_price = u128::from_le_bytes(data[ 0..16].try_into().unwrap_or([0; 16]));
    let appraised_nav  = u128::from_le_bytes(data[16..32].try_into().unwrap_or([0; 16]));
    let max_dev_bps    = u16::from_le_bytes (data[32..34].try_into().unwrap_or([0; 2]));

    // Must not panic for any input combination
    let _ = compute_nav_deviation_bps(on_chain_price, appraised_nav, max_dev_bps);
});

5.5 Classification Oracle Fuzz Target (Module 3)

// fuzz/fuzz_targets/classification_fuzz.rs

#![no_main]
use libfuzzer_sys::fuzz_target;
use oracle_aggregator::classification::*;

fuzz_target!(|data: &[u8]| {
    if data.len() < 17 { return; }

    let last_refresh_ts = i64::from_le_bytes(data[0.. 8].try_into().unwrap_or([0; 8]));
    let now             = i64::from_le_bytes(data[8..16].try_into().unwrap_or([0; 8]));
    let federal_active  = data[16] & 1 == 1;

    // Must not panic; freshness check must always return Ok or flagged Ok
    let _ = check_classification_freshness(last_refresh_ts, now, federal_active);
});

5.6 Running Fuzz Tests

# Transfer Hook fuzz — 100,000 runs
cd programs/transfer-hook
cargo fuzz run transfer_hook_fuzz -- -max_len=1024 -runs=100000

# CPMM fuzz — 100,000 runs
cd programs/amm
cargo fuzz run cpmm_fuzz -- -max_len=512 -runs=100000

# Module 2 — NAV deviation fuzz
cd programs/transfer-hook
cargo fuzz run nav_deviation_fuzz -- -max_len=1024 -runs=100000

# Module 3 — Classification fuzz
cd programs/oracle-aggregator
cargo fuzz run classification_fuzz -- -max_len=1024 -runs=100000

# Extended fuzz (pre-release) — 1,000,000 runs
cargo fuzz run transfer_hook_fuzz -- -max_len=1024 -runs=1000000

# Reproduce a crash
cargo fuzz run transfer_hook_fuzz artifacts/transfer_hook_fuzz/crash-abc123

5.7 Fuzz Coverage Targets

Target	Input Space	Runs (Weekly)	Runs (Pre-Release)	Module Scope
check_wallet_limit	u64 × 3 + u16	100,000	1,000,000	All
calculate_output_amount	u64 × 3 + u16	100,000	1,000,000	All
enforce_holding_period	i64 × 3 + bool + regime	100,000	1,000,000	All (Reg D / Reg S / Reg CF)
verify_custody_oracle	u64 × 4 + bool × 2	50,000	500,000	All
check_price_impact	u64 × 3 + u16	50,000	500,000	All
compute_nav_deviation_bps	u128 × 2 + u16	50,000	500,000	Module 2
check_classification_freshness	i64 × 2 + bool	50,000	500,000	Module 3

---

6. Formal Verification (Certora)

6.1 Six Invariants

ID	Property	Spec File	Program	Module Coverage
E.1	No unauthorized minting	no_unauthorized_minting.spec	transfer_hook	All modules
E.2	Custody ratio maintained	custody_ratio.spec	transfer_hook	All modules
E.3	Global Pool non-extractable	pool_non_extractability.spec	liquidity_pool	All modules — single shared pool
E.4	Transfer Hook completeness	hook_completeness.spec	transfer_hook	All modules — verifies module-aware extensions cannot be removed
E.5	Fee accuracy (≤ 1 lamport)	fee_accuracy.spec	amm	All modules
E.6	Circuit breaker correctness	circuit_breaker.spec	transfer_hook	All modules; covers Module 2 NAV-deviation variant

E.4 covers the module-aware extensions explicitly — any program upgrade that would remove the Module 2 NAV-deviation enforcement or the Module 3 federal-action freeze coordination fails E.4 verification. There are no separate per-module invariants.

6.2 Running Certora

# All specs
cd specs
for spec in *.spec; do
  echo "Running: $spec"
  certoraRun "$spec" --solana
  echo "Result: $?"
done

# Individual spec
certoraRun no_unauthorized_minting.spec --solana
certoraRun pool_non_extractability.spec --solana
certoraRun hook_completeness.spec --solana

6.3 Verification Requirement

All 6 invariants must PASS before any deployment (devnet or mainnet). A FAIL on any invariant is a release blocker — no exceptions. This applies regardless of whether the deployment includes only Module 1 mints, only Module 2 mints, only Module 3 mints, or any combination — the same six invariants protect every module.

---

7. Load Testing

7.1 Target

600 TPS sustained with full 42-control Transfer Hook verification on every transaction. The target applies to combined load across modules; module-specific load tests verify each module independently.

7.2 Load Generator

# Cross-module sustained load
npx ts-node scripts/load-test.ts \
  --rpc          http://localhost:8899 \
  --target-tps   600 \
  --duration-secs 900 \
  --module-mix   "M1:60,M2:25,M3:15"

# Module 2 only — NAV updates concurrent with trading
npx ts-node scripts/load-test-module-2.ts \
  --rpc           http://localhost:8899 \
  --target-tps    200 \
  --nav-updates   "every:60"

# Module 3 only — federal-action storm scenario
npx ts-node scripts/load-test-module-3.ts \
  --rpc                         http://localhost:8899 \
  --target-tps                  100 \
  --federal-action-injections    5

7.3 Metrics Collected

Metric	Target	Alert	Module Scope
Sustained TPS	≥ 600	< 500	All modules combined
p50 latency	< 500 ms	> 800 ms	All
p99 latency	< 2000 ms	> 5000 ms	All
Error rate	< 0.1%	> 1%	All
CU per swap (M1)	< 800,000	> 1,000,000	M1
CU per swap (M2)	< 820,000	> 1,000,000	M2
CU per swap (M3)	< 830,000	> 1,000,000	M3
Custody oracle update latency	< 200 ms	> 500 ms	All
NAV oracle update latency	< 1 s	> 5 s	M2
Classification oracle federal-action SLA	< 60 min	> 60 min	M3

---

8. Chaos Testing

8.1 Failure Injection Scenarios

Test	Injection Method	Expected Behavior	Module Scope
Kill custody relay	pm2 stop custody-relay	Transfers halt after 1 slot. Error 6002.	All
Empire API 500	Mock error response	Relay retries 3x, then stale. Halt.	All
Inject custody discrepancy	Write custodied_balance ≠ supply	Error 6001. P0 alert.	All
Kill OFAC indexer	pm2 stop ofac-indexer	Cache <24h. Halt >48h.	All
Both AML providers timeout	Network partition	Cache <6h. New wallets blocked.	All
Pyth feed stale	Mock stale data	Breaker disabled >5 min. P2.	All
RPC primary down	Block Helius endpoint	Failover to Triton. P2.	All
Kill NAV relay	pm2 stop nav-relay	Affected M2 mints pause when staleness exceeded	M2
NAV deviation injection	Inject NAV value triggering deviation	Affected mint paused. Error 6021. P1.	M2
Kill Classification relay	pm2 stop classification-relay	M3 mints enter enhanced review on staleness. P2.	M3
Federal-action injection	Inject federal-action event	P0 incident. Control 42 freeze within 60 min.	M3

8.2 Running Chaos Tests

./scripts/chaos/run-all.sh                          # All scenarios
./scripts/chaos/kill-custody-relay.sh               # Cross-module
./scripts/chaos/kill-nav-relay.sh                   # Module 2
./scripts/chaos/inject-nav-deviation.sh             # Module 2
./scripts/chaos/kill-classification-relay.sh        # Module 3
./scripts/chaos/inject-federal-action.sh            # Module 3
./scripts/chaos/verify-recovery.sh                  # Confirm recovery

---

9. Test Fixtures and Data

9.1 Standard Test Accounts

// tests/fixtures/accounts.ts

export const TEST_FIXTURES = {
  // Module 1 — Equities
  m1Mint:             Keypair.generate(),
  m1Issuer:           Keypair.generate(),

  // Module 2 — Real Estate (Single-Asset Entity)
  m2Mint:             Keypair.generate(),
  m2SaeIssuer:        Keypair.generate(),
  m2Appraiser:        Keypair.generate(),

  // Module 3 — CORECM (Basin-Asset Entity)
  m3Mint:             Keypair.generate(),
  m3BaeIssuer:        Keypair.generate(),
  m3ClassificationRelay: Keypair.generate(),

  // Cross-module investor wallets
  investorRegD:       Keypair.generate(),
  investorRegS:       Keypair.generate(),
  investorRegCF:      Keypair.generate(),
  sanctionedWallet:   Keypair.generate(),
  highRiskWallet:     Keypair.generate(),

  // Oracle keys
  empireKeypair:      Keypair.generate(),
  custodyRelayKeypair: Keypair.generate(),

  // Pool defaults
  initialSol:    100_000_000_000,        // 100 SOL
  initialTokens:   1_000_000_000_000,    // 1M tokens (9 decimals)
  totalSupply: 1_000_000_000_000_000,    // 1B tokens
};

9.2 SecurityConfig Fixtures (Per Module)

export const DEFAULT_M1_CONFIG = {
  module:                  { equities: {} },
  maxWalletPercent:        499,                   // 4.99%
  circuitBreakerThreshold: 3000,                  // 30%
  circuitBreakerCooldown:  86400,                 // 24h
  priceImpactMaxBps:       200,                   // 2%
  twapWindowSecs:          1800,                  // 30 min
  holdingPeriodEnabled:    true,
};

export const DEFAULT_M2_CONFIG = {
  module:                   { realEstate: {} },
  maxWalletPercent:         999,                  // 9.99% — M2 may use higher cap
  circuitBreakerThreshold:  3000,
  circuitBreakerCooldown:   86400,
  priceImpactMaxBps:        200,
  twapWindowSecs:           1800,
  holdingPeriodEnabled:     true,
  navDeviationMaxBps:       2200,                 // 22% default
  navReappraisalMaxAgeSecs: 7_776_000,            // 90 days
  navCircuitBreakerEnabled: true,
};

export const DEFAULT_M3_CONFIG = {
  module:                     { corecm: {} },
  maxWalletPercent:           499,
  circuitBreakerThreshold:    3000,
  circuitBreakerCooldown:     86400,
  priceImpactMaxBps:          200,
  twapWindowSecs:             1800,
  holdingPeriodEnabled:       true,
  classificationMaxAgeSecs:   86_400,             // 24h
  federalActionFreezeEnabled: true,
};

---

10. Coverage Requirements

10.1 Generating Coverage

cargo tarpaulin --workspace --out Html --output-dir coverage/
open coverage/tarpaulin-report.html

10.2 Minimum Coverage

Module	Target	Blocker?
Transfer Hook control logic (all 42)	100%	Yes — release blocker
Module 2 NAV-deviation extension	100%	Yes — release blocker
Module 3 federal-action freeze extension	100%	Yes — release blocker
CPMM arithmetic	100%	Yes — release blocker
Error code paths	100%	Yes — release blocker
Cross-module oracle verification	95%+	Yes — release blocker
Module 2 NAV oracle verification	95%+	Yes — release blocker
Module 3 Classification oracle verification	95%+	Yes — release blocker
Governance proposal logic (incl. module-specific param adjustments)	90%+	No
SDK TypeScript	80%+	No

---

11. CI/CD Pipeline

11.1 GitHub Actions Workflow

# .github/workflows/test.yml
name: RWA Tokens Tests
on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo test --workspace
      - run: cargo tarpaulin --workspace --fail-under 95

  integration-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: coral-xyz/anchor-action@v0.30
      - run: anchor build
      - run: anchor test
      # Module-specific E2E suites — must all pass
      - run: anchor test -- --grep "Module 1"
      - run: anchor test -- --grep "Module 2"
      - run: anchor test -- --grep "Module 3"

  fuzz-tests:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@nightly
      - run: cargo install cargo-fuzz
      - run: |
          cd programs/transfer-hook
          cargo fuzz run transfer_hook_fuzz -- -runs=100000
          cargo fuzz run nav_deviation_fuzz -- -runs=100000
          cd ../amm
          cargo fuzz run cpmm_fuzz -- -runs=100000
          cd ../oracle-aggregator
          cargo fuzz run classification_fuzz -- -runs=100000

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with: { components: clippy, rustfmt }
      - run: cargo fmt --all -- --check
      - run: cargo clippy --workspace -- -D warnings

11.2 PR Merge Gates

Gate	Required	Blocking?
Unit tests pass	Yes	Yes
Integration tests pass — all three modules	Yes	Yes
Coverage ≥ 95%	Yes	Yes
cargo fmt clean	Yes	Yes
cargo clippy zero warnings	Yes	Yes
Code review (1+ approver)	Yes	Yes
Fuzz tests (main branch only)	Main only	Yes for release
Certora (pre-release only)	Release only	Yes for release

---

12. Pre-Deployment Checklist

UNIT TESTS
[ ] cargo test --workspace — ALL PASS
[ ] cargo tarpaulin — coverage ≥ 95%
[ ] cargo clippy — zero warnings
[ ] cargo fmt — clean
[ ] Module 2 NAV-deviation tests — ALL PASS
[ ] Module 3 federal-action tests — ALL PASS
[ ] Reg D / Reg S / Reg CF holding-period tests — ALL PASS

INTEGRATION TESTS
[ ] anchor test — ALL PASS
[ ] Module 1 full lifecycle E2E — PASS
[ ] Module 2 full lifecycle E2E (NAV) — PASS
[ ] Module 3 full lifecycle E2E (federal-action) — PASS
[ ] Circuit breaker E2E — PASS
[ ] All 42 controls individually tested — PASS
[ ] Module-aware extensions individually tested — PASS

FUZZ TESTS
[ ] transfer_hook_fuzz — 100,000+ runs, zero crashes
[ ] cpmm_fuzz — 100,000+ runs, zero crashes
[ ] nav_deviation_fuzz (M2) — 100,000+ runs, zero crashes
[ ] classification_fuzz (M3) — 100,000+ runs, zero crashes

FORMAL VERIFICATION
[ ] E.1 No unauthorized minting — PASS
[ ] E.2 Custody ratio — PASS
[ ] E.3 Pool non-extractability — PASS
[ ] E.4 Hook completeness (incl. module-aware extensions) — PASS
[ ] E.5 Fee accuracy — PASS
[ ] E.6 Circuit breaker (incl. NAV variant) — PASS

LOAD TEST
[ ] 600 TPS sustained 15 min — PASS (mixed module load)
[ ] p99 latency < 2000ms — PASS
[ ] Error rate < 0.1% — PASS
[ ] M2 NAV update concurrent load — PASS
[ ] M3 federal-action storm scenario — PASS

CHAOS TEST
[ ] Custody relay failure — fail-safe works
[ ] OFAC indexer failure — cache fallback works
[ ] AML provider failure — cache fallback works
[ ] RPC failover — automatic
[ ] M2 NAV relay failure — affected mint pauses
[ ] M2 NAV deviation injection — affected mint paused
[ ] M3 Classification relay failure — enhanced review activates
[ ] M3 Federal-action injection — Control 42 freeze within 60 min

BUILD
[ ] Build hash matches audited source
[ ] IDL matches program (incl. module-aware fields)

---

13. Troubleshooting

Issue	Cause	Fix
anchor test timeout	Validator slow to start	Increase startup_wait in Anchor.toml
cargo test linker errors	Missing system deps	sudo apt install libudev-dev pkg-config libssl-dev
Fuzz target won't compile	Nightly required	rustup default nightly for fuzz directory
Coverage below threshold	Untested error paths	Add explicit error-path unit tests
Integration test: AccountNotFound	PDAs not initialized	Check test setup initializes all required accounts including module-specific PDAs (NAVOracle for M2, ClassificationOracle for M3)
Module 2 test: NAV deviation not triggering	Pool price helper not reaching threshold	Use forcePoolPrice helper to set deterministic deviation
Module 3 test: federal-action freeze not applying	Classification oracle not initialized before federal-action injection	Initialize ClassificationOracle with federalActionFreezeEnabled: true before injecting
Reg CF test: jurisdiction not recognized	Older Anchor IDL cached	anchor build to regenerate IDL with Jurisdiction::RegCF variant
Load test: TransactionExpired	Localnet too slow	Use devnet for load tests, or increase validator slots

---

Related Documentation

• Smart Contract Reference — Program instructions, error codes, module-aware program behavior.
• Deployment Guide — Pre-deployment checklist references this guide; module-specific oracle initialization.
• Security Model — Formal verification invariants; module-specific threat surfaces.
• Oracle Integration Guide — Custody, OFAC, AML, TWAP, EDGAR (M1), NAV (M2), Classification (M3) relay architecture and chaos test scenarios.
• Transfer Hook Reference — Standalone reference for the 42 controls including module-aware extensions.
• Incident Response Playbook — P0 through P3 runbooks; Module 3 federal-action freeze runbook.

---

RWA Tokens · Testing Guide · Groovy Company, Inc.