Token Flow Tracing

TOKEN_FLOW_TRACING Skill (Solana)

Trigger Pattern: SPL token CPI transfers, token_account.amount, invoke/invoke_signed, Transfer/TransferChecked Inject Into: Lifecycle, External-Env agents

For every token the protocol handles:

1. Token Entry Points

Where can tokens enter?

• deposit() / stake() instructions - standard entry points via CPI to Token Program
• Unsolicited SPL transfers - anyone can transfer SPL tokens to any known token account address
• SOL lamport donations - anyone can transfer lamports to any account (system_program::transfer or direct)
• CPI return tokens - tokens sent back as part of external CPI (e.g., unstake returns tokens, swap output)
• PDA-owned token accounts - tokens arriving at program-derived token accounts

2. Token State Tracking

For each entry point:

• What state variable tracks the balance? (e.g., vault.total_value, pool.total_deposited)
• Is token_account.amount read directly for calculations? -> Donation attack vector
• Are tracked balances vs actual token_account.amount compared anywhere?
• Can tracked balance get out of sync with actual token account balance?

Red flags:

• Exchange rate calculations using token_account.amount directly
• No reconciliation mechanism to handle discrepancies
• Internal accounting updated BEFORE CPI transfer completes
• PDA token accounts readable by anyone - balance is public state

3. Token Exit Points

Where can tokens leave?

• withdraw() / unstake() instructions
• Fee distributions to treasury/authority accounts
• Reward claim instructions
• Emergency withdrawal / rescue instructions
• CPI transfers to external adaptors or strategy programs
• Liquidation transfers

For each exit: does the tracked balance decrease BEFORE or AFTER the CPI transfer? For each transfer call: can the source account be underfunded at execution time? (funds deployed externally, locked, or lent out → transfer reverts)

3b. Self-Transfer Accounting

For each transfer instruction: can the source and destination token accounts belong to the same owner/authority, or be the same account? If YES: does a self-transfer update accounting state (fees credited, rewards claimed, snapshots updated, share ratios changed) without net token movement? Flag as FINDING. Note: this check targets accounting manipulation from self-transfers, distinct from the account key uniqueness validation in ACCOUNT_VALIDATION.md's Self-Transfer Risk column.

4. Token Type Separation (Multi-Token Protocols)

For protocols handling multiple token types:

• Are different SPL tokens handled by different code paths?
• Can one token type's instruction be triggered with another token's accounts?
• Are account constraints (mint, authority) properly validated per token type?
• Does the protocol distinguish between:
  • SOL (native lamports) vs SPL tokens (token accounts)
  • Base SPL vs Token-2022 tokens (different program IDs)
  • Base token vs LP/receipt token (underlying vs yield-bearing)
  • Staking receipt tokens (validator stake, LP shares, delegation receipts)

Check: If instruction A handles MintX and instruction B handles MintY, can MintX accounts be passed to instruction B's logic?

5. Unsolicited Transfer Analysis

Can tokens be sent to the protocol's token accounts without calling deposit()?

If YES (almost always YES on Solana):

• Does this break accounting? (tracked balance != actual token_account.amount)
• Does this inflate exchange rates? (more assets per share)
• Does this enable first-depositor attack amplification?
• Are there reconciliation instructions to sync state?
• Can an attacker front-run deposits with unsolicited transfers?

If NO:

• Why not? (Token-2022 TransferHook rejecting? PDA authority required for receives?)
• Is the protection reliable? (can it be bypassed?)

5b. Unsolicited Transfer Matrix (All Token Types)

For EVERY token type the protocol holds, queries, or receives - including SOL lamports:

RULE: If ANY transferable token affects state -> analyze: accounting divergence, rent impact, operation blocking, side effect chains.

6. Token Flow Checklist

For each token identified:

7. Cross-Token Interactions

For protocols with multiple tokens:

• Can operations on TokenA affect TokenB's accounting?
• Are there exchange rate dependencies between tokens (SOL vs SPL, base vs LP)?
• Can withdrawing TokenA affect availability of TokenB?
• Can SOL lamport balance affect SPL token operations (rent exemption)?

8. CPI Return Type Verification

For every CPI call that returns tokens or modifies accounts: