/token-flow-tracing

name: "token-flow-tracing"
description: "Trigger Pattern BALANCE_DEPENDENT flag (required) - Inject Into Depth-token-flow, breadth agents"

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 tra