fungible-asset-security

name	fungible-asset-security
description	Trigger FA_STANDARD flag detected (protocol uses FungibleAsset standard) - Used by Breadth agents, depth-token-flow

Skill: FUNGIBLE_ASSET_SECURITY

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:

#	Function	Accepts FA/Reads Store	Validates Metadata?	Expected Metadata	Bypass Possible?
1	{func}	FungibleAsset param	YES/NO	{expected_metadata_obj}	YES/NO

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:

#	Zero-Value Source	Code Path Triggered	State Modified?	Cleanup Correct?
1	fungible_asset::zero(metadata)	{trace what happens}	YES/NO	YES/NO
2	Withdrawal of 0 amount	{trace}	YES/NO	YES/NO

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

Store Type	Created By	Creation Permissionless?	Owner	Can Attacker Create?
Primary store	primary_fungible_store::ensure_primary_store_exists()	YES - anyone can create for any address	Address owner	YES (for any address)
Custom store	fungible_asset::create_store() on ConstructorRef	Only during object construction	Object owner	Depends on who can construct

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

Object A	Owns Object B	B Has FungibleStore	A Can Withdraw from B?
{object}	{child_object}	YES/NO	YES - via object ownership chain

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

Function	Expects Store At	Actually Reads From	Match?
{func}	Protocol-controlled store	User-supplied address	VERIFY

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

Hook Type	Registered?	Implementation Module	Can Reenter?	Can Revert?	Can Manipulate?
withdraw	YES/NO	{module::func}	ANALYZE	ANALYZE	ANALYZE
deposit	YES/NO	{module::func}	ANALYZE	ANALYZE	ANALYZE
derived_balance	YES/NO	{module::func}	ANALYZE	N/A	ANALYZE

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

Ref Type	Stored Where	Who Has Access	Can Be Extracted?	Impact If Leaked
MintRef	{object/resource}	{module/address}	YES/NO	Infinite token minting
BurnRef	{object/resource}	{module/address}	YES/NO	Destroy any user's tokens
TransferRef	{object/resource}	{module/address}	YES/NO	Bypass freeze, forced transfers
FreezeRef	{object/resource}	{module/address}	YES/NO	Freeze any user's store

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

Ref Type	Can Be Destroyed?	Destruction Function	Consequences of Destruction
MintRef	NO (no destroy function)	N/A	Permanent minting capability
BurnRef	YES (burn_ref::destroy)	{if exists}	Cannot burn tokens anymore
TransferRef	{check}	{if exists}	Cannot force-transfer anymore

STEP 6: Coin-to-FA Migration Accounting

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

#	Check	Status	Impact
1	Are Coin and FA treated equivalently in balance accounting?	YES/NO	{if NO: describe discrepancy}
2	Does total_supply track both representations?	YES/NO	{if NO: supply tracking broken}
3	Can user deposit as Coin, then withdraw as FA (or vice versa), exploiting accounting difference?	YES/NO	{describe path}
4	Are there functions that only accept Coin but credit FA internally (or vice versa)?	YES/NO	{conversion correct?}
5	If protocol converts Coin to FA: does coin::coin_to_fungible_asset() preserve exact amount?	VERIFY	{check for fees or rounding}

Pattern: When a protocol accepts both Coin 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)

Step	Required	Completed?	Notes
1. Metadata Validation Audit	YES	✓/✗/?	Every FA-accepting function checked
2. Zero-Value Exploitation	YES	✓/✗/?
3. Store Creation and Ownership	YES	✓/✗/?	Primary store permissionless creation checked
3b. Transitive Ownership	YES	✓/✗/?	Object ownership chains traced
4. Dispatchable Hook Analysis	IF dispatchable FA used	✓/✗(N/A)/?
4b. Reentrancy via Hooks	IF hooks registered	✓/✗(N/A)/?
4c. Deposit Hook Blocking	IF deposit hook registered	✓/✗(N/A)/?
4d. Derived Balance Manipulation	IF derived_balance hook	✓/✗(N/A)/?
5. Ref Safety Analysis	YES	✓/✗/?	All 4 Ref types located and access traced
5b. TransferRef Bypass	IF TransferRef exists	✓/✗(N/A)/?
6. Coin-to-FA Migration Accounting	IF both Coin and FA supported	✓/✗(N/A)/?

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