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 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 / FungibleAsset	{CoinType or metadata Object}	{decimals}	{list}	{list}

Aptos dual token model:

• Legacy Coin: 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 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	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 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	{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	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 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 is type-safe at compile time (T must match), but FungibleAsset is identified by metadata Object at runtime
• If protocol accepts both Coin 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 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 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