Token Flow Tracing

TOKEN_FLOW_TRACING Skill (Sui)

Trigger Pattern: BALANCE_DEPENDENT flag (required) Inject Into: Depth-token-flow, breadth agents Purpose: Trace all Coin<T> and Balance<T> flows through Sui Move protocols to identify accounting desync, unsolicited deposit vectors, type confusion, and token lifecycle issues

For every token the protocol handles:

1. Asset Inventory

Enumerate ALL Coin<T> and Balance<T> types the protocol handles:

Sui-specific representations:

• Coin<T>: Owned object with id: UID and balance: Balance<T>. Has key + store abilities -- freely transferable to any address via transfer::public_transfer. This is the primary unsolicited transfer vector on Sui.
• Balance<T>: Value type with store ability only (no key). Stored inside other objects. Cannot exist as a standalone on-chain object. Must live inside a struct with key.
• TreasuryCap<T>: Capability to mint/burn. Must be tracked.
• Dynamic fields storing Balance<T>: Hidden balance storage -- check dynamic_field::add/borrow/remove.

2. Token Entry Points

Where can tokens enter the protocol?

Sui-specific entry analysis:

• coin::into_balance(coin) converts Coin<T> to Balance<T> -- does the protocol track this conversion?
• coin::split(&mut coin, amount, ctx) creates a new Coin<T> -- does the protocol validate the split amount?
• Can users pass zero-value coins? (coin::zero<T>(ctx))

3. Token Exit Points

Where can tokens leave the protocol?

For each exit: does the tracked balance decrease BEFORE or AFTER the actual balance extraction? For each transfer/withdrawal: can the source be underfunded at execution time? (funds deployed externally, locked, or lent out → transfer aborts) Check for:

• balance::split before state update -> can the function abort between split and update?
• State update before balance::split -> can state be inconsistent if split aborts?

3b. Self-Transfer Accounting

For each transfer function: can the sender and recipient be the same address/object? 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 and Desync Analysis

For each token in the protocol:

Red flags:

• Exchange rate calculations using balance::value() directly instead of tracked internal variable
• No reconciliation mechanism between tracked and actual balance
• Accounting variables updated in a different function than the balance transfer
• balance::join(&mut pool.balance, deposit_balance) without incrementing tracked counter

Sui-specific desync vectors:

• balance::join into a shared object's Balance<T> without updating the tracking variable
• Dynamic field operations that add/remove Balance<T> without pool-level accounting
• Multiple shared objects holding the same token type with aggregate accounting errors

5. Unsolicited Deposit Analysis

Can tokens be added to the protocol's balance without going through deposit logic?

Sui object model considerations:

• Owned objects: Only the owner can access. Sending Coin<T> via transfer::public_transfer to a shared object's address creates a NEW owned object at that address -- it does NOT add to the shared object's Balance<T>. The protocol would need to explicitly receive and merge it.
• Shared objects: Anyone can call functions on shared objects, but cannot directly modify their Balance<T> fields without going through the module's public API.
• However: If the module exposes a public function that accepts Coin<T> and calls balance::join without proper accounting, this IS a donation vector.

5b. Unsolicited Transfer Matrix (All Token Types)

For EVERY external token type the protocol holds, queries, or receives as side effects -- not just the protocol's primary token:

RULE: If ANY token type can enter the protocol's balance AND affects state -> analyze each consequence:

• Accounting impact: Does tracked vs actual balance diverge?
• Iteration impact: Does the protocol iterate over sources of this token? (gas DoS vector via object count)
• Operation blocking: Does non-zero balance of this token prevent admin operations?
• Side effect chain: Does receiving this token trigger further side effects?