token-flow-tracing

name	token-flow-tracing
description	Trigger Pattern SEP-41 token transfers, TokenClient::new, transfer/transfer_from/burn, XLM native balance - Inject Into Lifecycle, External-Env agents

TOKEN_FLOW_TRACING Skill (Soroban)

Trigger Pattern: SEP-41 transfer/transfer_from/approve/burn, TokenClient::new, XLM native balance, SAC interactions Inject Into: Lifecycle, External-Env agents Finding prefix: [TF-N] Rules referenced: R4, R5, R10, R11

For every token the protocol handles:

1. Token Entry Points

Where can tokens enter?

• deposit() / stake() functions — explicit entry via token_client.transfer_from(user, contract, amount) or token_client.transfer(user, contract_address, amount)
• Unsolicited SEP-41 transfers — anyone can call token.transfer(sender, contract_address, amount) directly; the contract has no hook to reject it
• XLM native balance — anyone can send XLM to the contract's Stellar account; the contract reads this via e.current_contract_address().balance() or a token client wrapping the XLM SAC
• Return tokens from cross-contract calls — tokens returned as output of invoke_contract (e.g., swap output, unstake return)
• Allowance-based pulls — contract holds an approved allowance; tokens pulled via transfer_from into the contract

Soroban-specific note: Unlike Solana, there are no token account PDAs. The contract address IS the recipient. Unsolicited transfers arrive directly to e.current_contract_address() and are undetectable without an explicit balance snapshot before and after calls.

2. Token State Tracking

For each entry point:

• What state variable tracks the balance? (e.g., e.storage().instance().get(&DataKey::TotalDeposited))
• Is token_client.balance(contract_address) read directly for calculations? → Donation attack vector
• Are tracked balances vs actual token_client.balance() compared anywhere?
• Can tracked balance get out of sync with actual on-chain balance?

Red flags:

• Exchange rate calculations using token_client.balance(e.current_contract_address()) directly
• No reconciliation mechanism to handle unsolicited-transfer discrepancies
• Internal accounting updated BEFORE the cross-contract token transfer executes
• Balance read at function start, transfer happens mid-function, balance read again — reentrancy window (Soroban is reentrant via invoke_contract)

3. Token Exit Points

Where can tokens leave?

• withdraw() / unstake() functions
• Fee distributions to treasury address
• Reward claim functions
• Emergency withdrawal / rescue functions
• Cross-contract invoke_contract calls that transfer tokens as part of the call
• Liquidation transfers

For each exit:

• Does the tracked balance decrease BEFORE or AFTER token_client.transfer() executes?
• Can the contract be underfunded at execution time? (funds lent to external contracts, reserved for pending withdrawals)
• Does the function re-read the live balance after transferring, creating a post-transfer snapshot inconsistency?

3b. Self-Transfer Accounting

For each transfer instruction: can the source and destination be the same address? If YES: does a self-transfer update accounting state (fees credited, rewards claimed, share ratios updated) without net token movement? Flag as FINDING. This targets accounting manipulation, distinct from input validation.

4. Token Type Separation (Multi-Token Protocols)

For protocols handling multiple token types:

• Are different SEP-41 tokens handled by different code paths?
• Can one token's function be triggered with another token's contract address?
• Is the token address validated against a stored allowlist or configured token?
• Does the protocol distinguish between:
  • XLM native (via e.current_contract_address().balance() or XLM SAC address) vs SEP-41 tokens
  • SAC-wrapped assets (Stellar classic assets bridged to Soroban) vs pure Soroban tokens
  • Base token vs LP/receipt token (underlying vs yield-bearing)
  • Tokens with different decimal precisions (XLM is 7 decimals; many SEP-41 tokens use 7 or 18)

Check: If function A handles TokenX and function B handles TokenY, can TokenX's address be passed to function B?

5. Unsolicited Transfer Analysis

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

If YES (always YES in Soroban — any SEP-41 holder can call token.transfer(self, contract_addr, amount)):

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

If the protocol claims NO:

• Why not? (Is there a TransferHook equivalent? There is none in standard SEP-41.)
• 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:

Token Type	Can Transfer To Protocol?	Changes Accounting?	Blocks Operations?	Triggers Side Effects?
XLM (native)	YES (always)	YES/NO	YES/NO	YES/NO
{sep41_token_a}	YES (always)	YES/NO	YES/NO	YES/NO
SAC-{asset}	YES (always)	YES/NO	YES/NO	YES/NO

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:

Token	Entry Points	Exit Points	Tracking Var	balance() Used Directly?	Unsolicited Possible?
[Name/Address]	deposit, cross-contract return	withdraw, claim	total_deposited	YES/NO	YES (always)

7. Cross-Token Interactions

For protocols with multiple tokens:

• Can operations on TokenA affect TokenB's accounting?
• Are there exchange rate dependencies between tokens (XLM vs SEP-41, base vs LP)?
• Can withdrawing TokenA affect availability of TokenB?
• Can XLM balance affect SEP-41 token operations (base reserve requirements)?

8. Cross-Contract Call Return Verification

For every invoke_contract call that returns tokens or modifies state:

8a. Contract Address Verification

• What contract does the call target? Is the contract address validated against a stored trusted address?
• What return value / state change is expected? Is it verified post-call?

Common mismatches:

• Wrong token address: attacker passes a fake SEP-41 contract that mints freely
• Decimal mismatch: token with 7 decimals vs token with 18 decimals — amounts differ by 10^11
• Return value ignored: invoke_contract succeeded but returned unexpected amount
• Reentrancy: callee calls back into this contract before this contract's state is updated

Check: Every TokenClient::new(&e, &token_address) — is token_address validated against the configured/expected token, or accepted from user-supplied input?

8b. Return Value / Post-Call State Validation

• Does the protocol validate contract state after invoke_contract completes?
• Can zero/max/unexpected return values cause issues?
• Is there a mismatch between expected and actual post-call state?

Soroban reentrancy note: Soroban DOES allow reentrant invoke_contract calls unless the contract explicitly guards against them. If a cross-contract call can call back into this contract before the current function completes, check for reentrancy vectors.

9. Allowance Expiry Analysis (Soroban-Specific)

Soroban SEP-41 allowances are stored in Temporary ledger storage with a TTL (expressed as a ledger number deadline, not an amount-only approval like EVM). This creates unique staleness vectors:

9a. Allowance Storage Type

• Is the allowance stored in Temporary storage? (expires automatically if TTL is not extended)
• What is the approved expiration_ledger? Is it far enough in the future?
• Who sets the expiration? Can it be set to 0 (immediate expiry)?

9b. Allowance Expiry Attack Scenarios

Scenario	Description	Impact
Expired allowance	Contract holds an approved allowance; TTL expires before it is consumed; subsequent transfer_from fails	DoS: operation reverts, user funds locked pending reapproval
Short TTL front-run	User approves with short TTL; attacker delays their own transaction until allowance expires; then calls function that relies on the allowance	Griefing: operation fails after attacker delays it
Allowance amount != i128	Approved amount stored as i64 in older code; overflow at amounts > 2^63	Accounting mismatch: partial approval silently truncated

9c. Token Side Effects (SAC-specific)

• Is this token a SAC (Stellar Asset Contract)? If YES, the Stellar issuer may have freeze/clawback rights.
• Can a SAC clawback from the contract mid-operation? (balance disappears; tracked state diverges)
• Does the protocol handle SAC freeze/clawback gracefully, or does it panic?

9d. Side Effect Token Type Analysis

Call / Event	Side Effect	Token Type Produced	Protocol Handles This Type?	Mismatch?
{cross_contract_call}	{side_effect}	{token_type_or_UNKNOWN}	YES/NO	YES/NO

RULES: Side effect type != expected → FINDING. Type UNKNOWN → CONTESTED (Rule 4). Check BOTH cross-contract calls AND unsolicited transfers.

Example Application

// RED FLAG: Direct balance usage — donatable
let rate = token_client.balance(&e.current_contract_address()) / vault.total_shares;

// BETTER: Tracked balance — but verify total_deposited is updated on ALL entry paths
let rate = vault.total_deposited / vault.total_shares;

// RED FLAG: Token address from user input — not validated
let token_client = TokenClient::new(&e, &token_address); // token_address from fn args
token_client.transfer_from(&e.current_contract_address(), &from, &to, &amount);

// BETTER: Validated against configured token
let configured_token: Address = e.storage().instance().get(&DataKey::Token).unwrap();
require!(token_address == configured_token, Error::InvalidToken);

Finding Template

**ID**: [TF-N]
**Severity**: [based on fund impact]
**Step Execution**: S1,2,3,4,5,6,7,8,9 | X(reasons) | ?(uncertain)
**Location**: src/{file}.rs:LineN
**Title**: [Token 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]

---

Step Execution Checklist (MANDATORY)

CRITICAL: Report completion status for ALL sections. Findings with incomplete sections will be flagged for depth review.

Section	Required	Completed?	Notes
1. Token Entry Points	YES	Y/X/?
2. Token State Tracking	YES	Y/X/?
3. Token Exit Points	YES	Y/X/?
4. Token Type Separation	IF multi-token	Y/X(N/A)/?
5. Unsolicited Transfer Analysis	YES	Y/X/?
5b. Unsolicited Transfer Matrix (All Types)	YES	Y/X/?	MANDATORY — never skip
6. Token Flow Checklist	YES	Y/X/?
7. Cross-Token Interactions	IF multi-token	Y/X(N/A)/?
8. Cross-Contract Call Return Verification	YES	Y/X/?	MANDATORY — never skip
9. Allowance Expiry Analysis	YES	Y/X/?	MANDATORY — Soroban-specific, never skip
9d. Side Effect Token Type	YES	Y/X/?	MANDATORY — never skip

Cross-Reference Markers

• After Section 5: IF LP/receipt tokens identified → MUST complete Sections 8-9. IF cross-contract calls return tokens → verify return state in Section 8.
• After Section 8: IF token address is user-supplied → mark CONTESTED until validated. IF reentrancy path exists → escalate to depth-state-trace.
• After Section 9: IF allowance TTL is shorter than expected operation window → FINDING (at minimum Medium). IF SAC with clawback → document clawback handling or flag missing guard.

Mandatory Forced Output

Sections 8 and 9 MUST produce tabular output even if uncertain. If UNVERIFIED: verdict cannot be REFUTED, use CONTESTED. If side effects UNKNOWN: apply adversarial default and document assumptions.