plamentsv/token-flow-tracing

TOKEN_FLOW_TRACING Skill

Trigger Pattern: BALANCE_DEPENDENT flag (required) Inject Into: Depth-token-flow, breadth agents Purpose: Trace all token flows through Aptos Move protocols using FungibleAsset and Coin<T> models, identifying accounting desync, unsolicited deposit vectors, type confusion, and dispatchable hook side effects

For every token the protocol handles:

1. Asset Inventory

Enumerate ALL asset types the protocol handles:

| Asset | Model | Type Parameter / Metadata | Decimals | Entry Modules | Exit Modules | |-------|-------|--------------------------|----------|---------------|-------------| | {name} | Coin<T> / FungibleAsset | {CoinType or metadata Object} | {decimals} | {list} | {list} |

Aptos dual token model:

• Legacy Coin<T>: Uses CoinStore<T> resource at user address. Type parameter T identifies the coin.
• FungibleAsset (FA): Uses FungibleStore objects. Metadata object identifies the asset type.
• Paired assets: Some tokens exist as both Coin<T> and FA simultaneously (APT is the primary example). Check if protocol handles both representations correctly.
• Migration tokens: Tokens migrated from Coin to FA model may have both interfaces active.

2. Token Entry Points

Where can tokens enter the protocol?

| Entry Path | Function | Asset Model | Accounting Updated? | Access Control | |------------|----------|-------------|--------------------|--------------| | Standard deposit | {deposit_fn} | {Coin/FA} | YES/NO | {who can call} | | primary_fungible_store::deposit() | External | FA | NO (protocol unaware) | Permissionless | | coin::deposit<T>() | External | Coin<T> | NO (protocol unaware) | Permissionless (if CoinStore registered) | | Direct fungible_asset::deposit() | Via store ref | FA | NO (protocol unaware) | Requires FungibleStore reference | | move_to<T>() | Internal | Resource | {depends} | Module only | | Side-effect receipts | External call returns | {varies} | {depends} | {depends} |

Red flags:

• Protocol holds a FungibleStore whose reference is obtainable by external callers
• Protocol has registered CoinStore<T> making it a valid deposit target
• Protocol uses object::generate_signer() or object::generate_extend_ref() which could allow external deposits

3. Token Exit Points

Where can tokens leave the protocol?

| Exit Path | Function | Asset Model | Accounting Updated? | Access Control | |-----------|----------|-------------|--------------------|--------------| | Standard withdraw | {withdraw_fn} | {Coin/FA} | YES/NO | {who can call} | | primary_fungible_store::withdraw() | Via signer | FA | {depends} | Requires signer capability | | coin::withdraw<T>() | Via signer | Coin<T> | {depends} | Requires signer | | fungible_asset::withdraw() | Via store ref | FA | {depends} | Requires store &mut ref or TransferRef | | Fee distribution | {fee_fn} | {varies} | YES/NO | {access} | | Emergency withdraw | {emergency_fn} | {varies} | YES/NO | {admin} |

For each exit: does the tracked balance decrease BEFORE or AFTER the actual 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 function: can the sender and recipient be the same account/address? 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.

4. Balance Tracking Analysis

For each asset type:

| Asset | Internal Tracking Variable | On-Chain Balance Query | Can Desync? | Desync Vector | |-------|---------------------------|----------------------|-------------|---------------| | {name} | {e.g., total_deposited in resource} | fungible_asset::balance(store) or coin::balance<T>(addr) | YES/NO | {if YES: how} |

Critical question: Does the protocol use internal accounting or direct on-chain balance queries?

• Internal accounting: Protocol maintains its own total_deposited / total_assets resource -> SAFE from donation attacks IF consistently updated
• Direct balance query: Protocol reads fungible_asset::balance() or coin::balance<T>() directly -> DONATION ATTACK VECTOR -- attacker can inflate balance without protocol awareness

Red flags:

• Exchange rate calculations using fungible_asset::balance(store) directly
• No reconciliation function to handle accounting discrepancies
• Accounting variables updated BEFORE token transfer completes (not relevant in Move's linear type system, but check for resource mutation ordering)

5. Unsolicited Deposit Analysis

Can tokens be deposited to the protocol without calling its deposit function?

If YES (most cases on Aptos):

5a. Unsolicited Deposit Vectors

| Vector | Asset Model | Protocol Aware? | Impact | |--------|-------------|----------------|--------| | primary_fungible_store::deposit(protocol_addr, fa) | FA | NO | {impact} | | coin::deposit<T>(protocol_addr, coin) | Coin<T> | NO | {impact} | | Direct transfer to object-owned store | FA | NO | {impact} |

5b. Unsolicited Transfer Matrix (All Token Types) -- R11 Five Dimensions

For EVERY external token type the protocol holds, queries, or receives as side effects:

| Token Type | Can Deposit Unsolicited? | Accounting Distortion? | Share Inflation? | Threshold Manipulation? | Reward Dilution? | Fee Calculation Impact? | |------------|------------------------|----------------------|-----------------|----------------------|-----------------|----------------------| | {token_a} | YES/NO | YES/NO | YES/NO | YES/NO | YES/NO | YES/NO |

RULE: If ANY token type is unsolicited-depositable AND affects state -> analyze each consequence:

• Accounting distortion: Does tracked vs actual balance diverge?
• Share inflation: Does unsolicited deposit inflate share price (more assets per share)?
• Threshold manipulation: Can unsolicited deposits push protocol past thresholds?
• Reward dilution: Do unsolicited deposits dilute rewards for existing participants?
• Fee calculation: Do fees computed on balance include unsolicited deposits?

If NO:

• Why not? (No CoinStore registered? Store not publicly accessible? Custom deposit hooks reject?)
• Is the protection reliable? (Can it be bypassed via object manipulation?)

6. Token Type Confusion

Can the wrong asset type be used where another is expected?

| Check | Location | Status | Impact | |-------|----------|--------|--------| | FungibleAsset metadata validated on deposit? | {fn} | YES/NO | Wrong FA type accepted | | Coin<T> type parameter constrains to expected type? | {fn} | YES/NO (compile-time) | N/A for Coin (type-safe) | | Paired Coin/FA confusion? | {fn} | YES/NO | Same asset counted twice | | Metadata address hardcoded or validated? | {fn} | {which} | Spoofed metadata |

Aptos-specific type confusion vectors:

• FungibleAsset metadata is an Object address -- if not validated, attacker-created FA with fake metadata could be deposited
• Coin<T> is type-safe at compile time (T must match), but FungibleAsset is identified by metadata Object at runtime
• If protocol accepts both Coin<T> AND FungibleAsset for the same underlying token, can the same deposit be counted under both models?

7. Dispatchable Hook Impact

If any token in scope uses the Aptos FungibleAsset dispatchable hooks (DispatchFunctionStore):

| Token | Hook Type | Hook Function | Side Effect | Protocol Handles? | |-------|-----------|--------------|-------------|-------------------| | {token} | deposit | {module::fn} | {effect} | YES/NO | | {token} | withdraw | {module::fn} | {effect} | YES/NO | | {token} | derived_balance | {module::fn} | {effect} | YES/NO |

Analysis questions:

• Can deposit hooks cause reentrancy-like behavior? (hook calls back into protocol during deposit)
• Can withdraw hooks block withdrawals? (hook aborts on certain conditions)
• Can derived_balance hooks return manipulated values? (custom balance reporting)
• Does the protocol check is_dispatchable() before interacting with tokens?

8. Zero-Value Operations

What happens with zero-amount deposits/withdrawals?

| Operation | Zero Amount Behavior | Accounting Impact | Shares Issued/Burned? | |-----------|---------------------|-------------------|----------------------| | deposit(0) | {aborts/succeeds} | {state change?} | {0 shares / abort?} | | withdraw(0) | {aborts/succeeds} | {state change?} | {0 shares burned?} | | transfer(0) | {aborts/succeeds} | {state change?} | N/A |

Red flags:

• Zero-amount deposit succeeds and issues shares (division by zero in rate calculation)
• Zero-amount withdraw triggers reward claims or state updates without actual token movement
• Zero-amount operations bypass minimum balance checks

9. Cross-Token Interactions

For protocols handling multiple token types:

| Token A | Token B | Interaction | Can A Affect B? | Impact | |---------|---------|-------------|----------------|--------| | {tokenA} | {tokenB} | {rate dependency / collateral relationship / swap} | YES/NO | {impact} |

• Can operations on TokenA affect TokenB's accounting?
• Are there exchange rate dependencies between tokens?
• Can withdrawing TokenA affect availability of TokenB?
• If protocol handles both Coin<T> and FA representations of same asset, are operations on one reflected in the other?

10. Token Flow Checklist

For each token identified:

| Token | Entry Points | Exit Points | Tracking Var | Direct Balance Query Used? | Unsolicited Possible? | |-------|--------------|-------------|--------------|---------------------------|----------------------| | {name} | {list} | {list} | {var} | YES/NO | YES/NO |

Instantiation Parameters

{CONTRACTS}           -- Move modules to analyze
{ASSET_TYPES}         -- FungibleAsset metadata and Coin<T> types in scope
{ENTRY_FUNCTIONS}     -- Functions where tokens enter the protocol
{EXIT_FUNCTIONS}      -- Functions where tokens leave the protocol
{BALANCE_VARS}        -- Internal balance tracking variables
{EXTERNAL_TOKENS}     -- External token types the protocol interacts with

Finding Template

**ID**: [TF-N]
**Severity**: [based on fund impact]
**Step Execution**: checkmark1,2,3,4,5,6,7,8,9,10 | x(reasons) | ?(uncertain)
**Rules Applied**: [R1:Y, R4:Y, R10:Y, R11:Y]
**Location**: module::function:LineN
**Title**: [Asset type] can enter/exit via [path] without [expected accounting update]
**Description**: [Trace the token flow and where it diverges from expected]
**Impact**: [What breaks: exchange rates, user balances, protocol insolvency]

Output Schema

| Field | Required | Description | |-------|----------|-------------| | asset_inventory | yes | All asset types and their models | | entry_points | yes | Token entry paths with accounting status | | exit_points | yes | Token exit paths with accounting status | | balance_tracking | yes | Internal vs on-chain balance analysis | | unsolicited_vectors | yes | Unsolicited deposit analysis (R11 5 dimensions) | | type_confusion | yes | Token type validation issues | | finding | yes | CONFIRMED / REFUTED / CONTESTED | | evidence | yes | Code locations with line numbers | | step_execution | yes | Status for each step |

---

Step Execution Checklist (MANDATORY)

| Section | Required | Completed? | Notes | |---------|----------|------------|-------| | 1. Asset Inventory | YES | Y/x/? | | | 2. Token Entry Points | YES | Y/x/? | | | 3. Token Exit Points | YES | Y/x/? | | | 4. Balance Tracking Analysis | YES | Y/x/? | | | 5. Unsolicited Deposit Analysis | YES | Y/x/? | | | 5b. Unsolicited Transfer Matrix (All Types) | YES | Y/x/? | MANDATORY -- never skip (R11) | | 6. Token Type Confusion | YES | Y/x/? | | | 7. Dispatchable Hook Impact | IF dispatchable tokens | Y/x(N/A)/? | | | 8. Zero-Value Operations | YES | Y/x/? | | | 9. Cross-Token Interactions | IF multi-token | Y/x(N/A)/? | | | 10. Token Flow Checklist | YES | Y/x/? | |

Cross-Reference Markers

After Section 5 (Unsolicited Deposit Analysis):

• IF unsolicited deposits possible -> MUST complete Section 5b with ALL 5 R11 dimensions
• IF FungibleAsset with dispatchable hooks -> MUST complete Section 7

After Section 6 (Token Type Confusion):

• IF protocol handles both Coin<T> and FA for same underlying -> MUST check double-counting in Section 9
• Cross-reference with ZERO_STATE_RETURN.md for first-depositor amplification via unsolicited deposits

After Section 7 (Dispatchable Hook Impact):

• IF hooks can abort -> trace all callers for uncaught abort impact
• IF hooks have side effects -> trace through to accounting consistency