plamentsv/trident-api-reference

Skill: Trident API Reference (v0.12.0)

Type: Reference document (prevents method signature hallucination) Trigger: trident_available: true in build_status.md Loaded by: Invariant fuzz generator (Phase 4b), security-verifier Template 6 (Phase 5) Version: Trident v0.12.0 (Ackee Blockchain Security) Important: Check trident --version before using. If version differs, warn and proceed with caution.

CLI Commands

# Initialize scaffolding (creates trident-tests/ from program IDL)
trident init

# Run fuzz campaign (v0.11+ uses built-in TridentSVM - no honggfuzz/AFL needed)
# Run from the trident-tests/ directory
cd trident-tests && trident fuzz run fuzz_0

# Run with a specific seed for reproducibility
trident fuzz run fuzz_0 12345

# Enable detailed transaction logging
TRIDENT_LOG=1 trident fuzz run fuzz_0

# Build without running (useful for CI or pre-checks)
trident fuzz run fuzz_0 --skip-build

Platform support: Trident v0.11+ works on Linux, macOS (including Apple Silicon), and Windows. Earlier versions (<=0.10) required honggfuzz (Linux-only).

Project Structure

trident-tests/
  fuzz_tests/
    fuzz_0/
      fuzz_instructions.rs    # Handler definitions (auto-generated, customize)
      test_fuzz.rs             # Entry point (auto-generated)
  .fuzz-artifacts/             # Crash/violation files written here (v0.11+)
  Trident.toml                 # Configuration (iterations, coverage, regression)

Key Types and Traits

FuzzInstruction Enum

// Auto-generated from IDL. Each variant = one program instruction.
// Customize: add bounds to parameters, constrain account selection.
#[derive(Arbitrary, DisplayIx, FuzzTestExecutor, FuzzDeserialize)]
pub enum FuzzInstruction {
    InstructionName(InstructionNameData),
    // ...
}

Instruction Data Structs

#[derive(Arbitrary, Debug)]
pub struct InstructionNameData {
    // Fields mirror the instruction's arguments
    pub amount: u64,
    pub authority: AccountId,  // AccountId = index into AccountsStorage
    // ...
}

AccountsStorage

// Manages test accounts. Use AccountId (u8) to reference accounts.
// Trident creates/reuses accounts automatically.

// Read account state:
let account = fuzz_accounts.token_account.storage().get(&account_id);

// Custom account setup (e.g., mock oracle):
fn set_account_custom(
    &mut self,
    account_id: AccountId,
    data: &[u8],
    owner: &Pubkey,
) -> Pubkey;

Invariant Hooks

impl FuzzInstruction {
    // Called after EACH instruction execution
    fn check_invariant(&self, pre_state: &Snapshot, post_state: &Snapshot) {
        // Assert protocol invariants here
        // Panic = violation found = crash file generated
        assert!(
            post_state.total_supply == post_state.sum_balances(),
            "Supply invariant violated"
        );
    }
}

Snapshot Pattern

// Capture state before instruction for comparison
struct Snapshot {
    total_supply: u64,
    vault_balance: u64,
    // Add fields for each invariant
}

impl Snapshot {
    fn capture(accounts: &AccountsStorage) -> Self {
        // Read relevant account states
    }
}

Common Pitfalls

1. Check .fuzz-artifacts/ for violations: Trident v0.11+ writes crash/violation files to .fuzz-artifacts/ (not fuzzing/fuzz_0/ like older versions). Always check this directory even if stdout shows no errors.
2. AccountId reuse: Multiple instruction fields using the same AccountId type will be assigned the same account. Use distinct account pools for distinct roles.
3. Silent reverts: If handler setup fails (wrong PDA, missing prerequisite), the instruction silently reverts. Check success rate -- if all calls revert, the campaign is trivial.