/ability-analysis

name: "ability-analysis"
description: "Trigger Pattern Always (Aptos Move) - foundational security check - Inject Into Breadth agents, depth agents"

ABILITY_ANALYSIS Skill

> **Trigger Pattern**: Always (Aptos Move) --- foundational security check > **Inject Into**: Breadth agents, depth agents

For every struct defined in the audited modules:

**STEP PRIORITY**: Steps 2 (Copy Ability Audit) and 6 (Ability Combination Analysis) are where HIGH/CRITICAL severity findings most commonly hide. Do NOT rush these steps. If constrained, skip conditional sections (7) before skipping 2 or 6.

1. Struct Ability Inventory

Enumerate ALL structs defined in the audited modules:

| Struct | Module | Abilities | Represents Value? | Represents Obligation? | Is Resource? | Security Assessment | |--------|--------|-----------|-------------------|----------------------|-------------|---------------------| | {name} | {module} | copy, drop, store, key | YES/NO | YES/NO | YES/NO | {assessment} |

**Classification guide**:

• **Value-bearing**: Coins, LP tokens, shares, receipts, vouchers, NFTs --- anything that represents transferable economic value or a claim to value
• **Obligation-bearing**: Hot potatoes, flash loan receipts, callback obligations, lock receipts --- anything that MUST be consumed before transaction ends
• **Resource**: Singleton state containers, registries, configuration stores --- things that should exist at most once per address/globally
• **Data**: Purely informational structs with no security-sensitive lifecycle (events, parameters, intermediate computation results)

**For each struct**: What abilities does it NEED vs what abilities does it HAVE? Excess abilities are the attack surface.

2. Copy Ability Audit

For each struct with the `copy` ability:

2a. Value Duplication Check

| Struct | Has `copy`? | Represents Value? | Duplication Exploitable? | Severity | |--------|-------------|-------------------|-------------------------|----------| | {name} | YES/NO | YES/NO | YES/NO --- {reason} | {H/M/L/N/A} |

**CRITICAL**: `copy` on a value-bearing type means the value can be duplicated at zero cost. This is the Move equivalent of a double-spend.

**Check for each `copy` struct**: 1. Can this struct be copied and then used multiple times? (e.g., copied receipt redeemed twice) 2. Does the module rely on move semantics to enforce single-use? If yes, `copy` breaks that assumption. 3. Is `copy` needed for legitimate operations? (e.g., snapshot reads, event emission) --- if not, it should be removed. 4. Trace all functions that accept this struct as a parameter: do they consume (move) or borrow (&) it? If they consume, copy lets callers retain the original.

**MANDATORY GREP**: Search all `.move` files for `has copy` and `copy,` in struct definitions. For each hit: (1) classify the struct, (2) if value-bearing, mark as FINDING.

2b. Copy-Then-Use Trace

For each `copy` struct identified as potentially dangerous:

1. Caller obtains instance I of struct S
2. Caller copies: I_copy = copy I
3. Caller uses I in function F1 (consumed/moved)
4. Caller uses I_copy in function F2 (consumed/moved)
5. Impact: {double-spend, double-claim, double-vote, obligation bypass}

Tag: `[TRACE:copy S → use1 in F1 → use2 in F2 → impact: {X}]`

3. Drop Ability Audit

For each struct with the `drop` ability:

3a. Obligation Bypass Check

| Struct | Has `drop`? | Represents Obligation? | Drop Bypasses Cleanup? | Severity | |--------|-------------|----------------------|----------------------|----------| | {name} | YES/NO | YES/NO | YES/NO --- {reason} | {H/M/L/N/A} |

**CRITICAL**: `drop` on an obligation-bearing struct means the obligation can be silently discarded. This is the Move equivalent of skipping a required finally-block.

**Hot potato pattern check**: The hot potato pattern relies on structs having NO `drop` ability, forcing the caller to pass them to a consuming function. If `drop` is present, the pattern is broken.

**Check for each `drop` struct**: 1. Is this struct a receipt or proof that must be returned to a specific function? (flash loan receipt, lock receipt, callback proof) 2. Does any function create this struct with the expectation that a corresponding "finalize" function will consume it? 3. What state changes happen in the finalize function? If the struct is dropped instead, those state changes never occur. 4. Does dropping this struct leave the protocol in an inconsistent state? (borrowed funds not returned, locks not released, counters not decremented)

3b. Drop-Instead-of-Consume Trace

For each obligation struct:

1. Function F_create creates struct S (e.g., flash_loan returns receipt)
2. EXPECTED: Caller passes S to F_consume (e.g., repay(receipt))
3. ACTUAL (if drop): Caller drops S, F_consume never called
4. Impact: {funds not returned, lock not released, state inconsistent}

Tag: `[TRACE:drop obligation S → F_consume skipped → impact: {X}]`

4. Store Ability Audit

For each struct with the `store` ability:

4a. Module Control Escape Check

| Struct | Has `store`? | Can Escape Module? | Invariant Break If Escaped? | Severity | |--------|-------------|-------------------|---------------------------|----------| | {name} | YES/NO | YES --- via {mechanism} / NO | YES/NO --- {which invariant} | {H/M/L/N/A} |

**Check for each `store` struct**: 1. `store` allows the struct to be placed inside other structs, into `Table`/`SmartTable`, or moved to global storage via a wrapping resource. Can an attacker store this struct in their own resource, bypassing module-controlled access? 2. Does the module rely on controlling where instances of this struct live? If instances escape to user-controlled storage, can they be replayed, hoarded, or used out of context? 3. For structs with `store` but without `key`: can they be wrapped in a user-defined `key` struct to achieve unauthorized global storage? 4. If the struct contains mutable references to share