plamentsv / fungible-asset-security

Skill: FUNGIBLEASSETSECURITY

Trigger: FA_STANDARD flag detected (protocol uses FungibleAsset standard)
Used by: Breadth agents, depth-token-flow
Covers: FungibleAsset metadata validation, zero-value exploitation, store ownership, dispatchable hooks, Ref safety, Coin-to-FA migration

Purpose

Audit FungibleAsset standard usage for Aptos-specific vulnerabilities. The FA standard introduces object-based token management with capabilities (MintRef, BurnRef, TransferRef, FreezeRef) and optional dispatchable hooks. Incorrect usage creates counterfeit token acceptance, forced transfers, reentrancy, and accounting mismatches.

Methodology

STEP 1: Metadata Validation Audit

For EVERY function that accepts a FungibleAsset parameter or reads from a FungibleStore:

How metadata validation works:

// CORRECT: validates the asset is the expected type
let metadata = fungible_asset::metadata(&fa);
assert!(metadata == expected_metadata, ERROR_WRONG_ASSET);

// VULNERABLE: no validation - accepts ANY FungibleAsset
public fun deposit(fa: FungibleAsset) {
    // Attacker can pass a worthless FA created from their own metadata
    fungible_asset::deposit(store, fa);
}

MANDATORY SEARCH: Grep all .move files for:

1. FungibleAsset in function signatures (parameters)
2. For each hit: trace whether fungible_asset::metadata(&fa) is called and compared
3. Functions that ONLY use fungible_asset::amount(&fa) without metadata check -> FLAG

Severity: Accepting unvalidated FungibleAsset = accepting counterfeit tokens. If the function credits the user or modifies protocol state based on the FA amount -> HIGH/CRITICAL.

STEP 2: Zero-Value Exploitation

Analyze zero-value FungibleAsset paths:

Check for each:

1. Can fungible_asset::zero(metadata) be used to trigger code paths that modify state? (e.g., register a user, set a flag, emit an event)
2. Does fungible_asset::destroy_zero(fa) clean up properly, or does it leave dangling state?

3. Can zero-value deposits/withdrawals:

   • Register a new FungibleStore where one shouldn't exist?
   • Trigger reward distribution checkpoints?
   • Bypass minimum deposit requirements (checked after or before deposit)?
   • Create entries in tracking data structures (SmartTable, vector)?
4. Does amount == 0 get explicitly checked and rejected at entry points?

Pattern: Zero-value operations often bypass amount > 0 checks that were assumed but never written, allowing state modifications without economic cost.

STEP 3: Store Creation and Ownership Analysis

Audit FungibleStore creation, ownership chains, and access control:

3a. Store Creation Inventory

CRITICAL: primary_fungible_store::ensure_primary_store_exists(addr, metadata) is permissionless. An attacker can create a primary store for ANY address for ANY metadata. If the protocol assumes a store's existence means the user has interacted with the protocol -> FINDING.

3b. Transitive Ownership

Check: If Object A owns Object B which owns a FungibleStore, the owner of Object A can withdraw from B's store through the ownership chain. Trace all object ownership hierarchies for unintended fund access paths.

3c. Store Address Confusion

Pattern: Protocol calculates expected store address but user can supply a different store address. If the function doesn't verify the store belongs to the expected object/address -> FINDING.

STEP 4: Dispatchable Hook Analysis

If the protocol uses dispatchable FungibleAsset (custom withdraw, deposit, or derived_balance hooks):

4a. Hook Inventory

4b. Reentrancy via Hooks

For each registered hook:

1. Does the hook call back into the registering module's public functions?
2. Does the hook call into any other module that reads/writes shared state?
3. Is #[module_lock] applied to the registering module? (prevents indirect reentrancy but NOT direct)
4. What state has been modified BEFORE the hook executes? Can the hook see inconsistent state?

Reentrancy sequence:

Module::transfer() {
    1. Read balance (CHECK)
    2. Deduct from source store → triggers withdraw hook (INTERACTION before EFFECT completion)
    3. Withdraw hook reenters Module::another_function()
    4. another_function() sees partially-updated state
    // ...
}

4c. Deposit Hook Blocking

Can a deposit hook unconditionally revert to prevent deposits into a specific store?

• If YES: can this be used to DoS the protocol? (e.g., prevent liquidations, block reward distribution)
• Who controls the hook? (protocol, user, external party)

4d. Derived Balance Manipulation

If derived_balance hook is registered:

1. Does the protocol call fungible_asset::balance(store) expecting the real balance?
2. balance() calls derived_balance hook if registered - the returned value may differ from actual stored amount
3. Can the hook return inflated values to trick the protocol? (e.g., appear to have more collateral)
4. Can the hook return deflated values? (e.g., trigger incorrect liquidation)

STEP 5: Ref Safety Analysis

Audit the lifecycle and access control of FungibleAsset capability references:

5a. Ref Inventory

MANDATORY CHECK for each Ref:

1. Is the Ref stored in a resource with key only? (safe - not extractable)
2. Is the Ref stored in a struct with store ability? (dangerous - can be moved out)
3. Is the Ref stored in an Object? Who owns the Object? Can ownership be transferred?
4. Are there public functions that return the Ref or pass it to external code?

5b. TransferRef Bypass Analysis

TransferRef allows transfers that bypass freeze status:

1. Is there a TransferRef for the protocol's main token?
2. Can TransferRef be used to force-transfer tokens FROM users? (fungible_asset::transfer_with_ref(ref, from_store, to_store, amount))
3. Who holds the TransferRef? Is this documented as a trust assumption?
4. Can TransferRef bypass any protocol-level transfer restrictions (not just freeze)?

5c. Ref Destruction Audit

STEP 6: Coin-to-FA Migration Accounting

If the protocol handles both Coin<T> and FungibleAsset:

Pattern: When a protocol accepts both Coin<T> and FungibleAsset for the same underlying token, internal accounting that tracks only one representation can be exploited by depositing in one form and withdrawing in the other.

Key Questions (Must Answer All)

1. Metadata validation: Does every FA-accepting function verify the asset type?
2. Zero-value: Are zero-amount operations explicitly guarded?
3. Store creation: Can permissionless store creation be exploited?
4. Hooks: If dispatchable, can hooks reenter, block, or manipulate balances?
5. Refs: Where are MintRef/BurnRef/TransferRef/FreezeRef stored, and who can access them?
6. Coin-FA parity: If both types supported, is accounting consistent?

Common False Positives

1. Framework-enforced metadata: Some framework functions internally validate metadata - verify before flagging
2. Primary store determinism: Primary store addresses are deterministic (primary_fungible_store_address(owner, metadata)) - "unexpected address" may be intentional
3. Intentional TransferRef usage: Protocol may document that TransferRef is needed for authorized transfers (e.g., liquidation)
4. Zero-value guards in framework: Some framework functions (e.g., deposit) may already reject zero amounts internally - verify

Output Schema

## Finding [FA-N]: Title

**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: ✓1,2,3,4,5,6 | ✗N(reason) | ?N(uncertain)
**Rules Applied**: [R1:✓/✗, R4:✓/✗, R10:✓/✗, R11:✓/✗]
**Severity**: Critical/High/Medium/Low/Info
**Location**: module_name.move:LineN

**FA Component**: {metadata/store/hook/ref/accounting}
**Attack Vector**: {counterfeit deposit / reentrancy via hook / forced transfer via TransferRef / ...}

**Description**: What's wrong
**Impact**: What can happen (fund theft, accounting mismatch, DoS)
**Evidence**: Code snippets showing the vulnerability
**Recommendation**: How to fix

### Precondition Analysis (if PARTIAL/REFUTED)
**Missing Precondition**: [What blocks exploitation]
**Precondition Type**: STATE / ACCESS / TIMING / EXTERNAL / BALANCE

### Postcondition Analysis (if CONFIRMED/PARTIAL)
**Postconditions Created**: [What conditions this creates]
**Postcondition Types**: [List applicable types]
**Who Benefits**: [Who can use these]

Step Execution Checklist (MANDATORY)

If any step skipped, document valid reason (N/A, no dispatchable hooks, no Coin support, no TransferRef).