ptb-composability

Skill: PTB_COMPOSABILITY (Sui)

Trigger Pattern: PTB flag (always for Sui -- Programmable Transaction Blocks are the Sui transaction model) Inject Into: Breadth agents, depth-external, depth-state-trace Finding prefix: [PTB-N] Rules referenced: R4, R5, R8, R10, R15

Programmable Transaction Blocks (PTBs) are Sui's transaction composition primitive. A single PTB can contain up to 1024 commands, each calling a different function, with return values routed between commands. This enables atomic multi-step sequences that are fundamentally different from EVM's single-entry-point model. Every public function is a potential PTB command -- there is no "internal only" visibility equivalent to Solidity's internal.

STEP PRIORITY: Steps 1 (Single-Call Assumption Audit) and 4 (Atomic Read-Modify-Write) are where HIGH/CRITICAL severity findings most commonly hide. Do NOT rush these steps. If constrained, skip conditional sections (6, 7) before skipping 1, 3, or 4.

---

1. Entry Point Inventory

For EVERY public and entry function in the protocol, classify composability:

Sui visibility semantics:

• entry functions: callable from PTB but return values CANNOT be used by subsequent commands (consumed or discarded within the command). Objects can only be transferred, not returned.
• public functions: fully composable -- return values pass between commands. This is the primary composability surface.
• public(package): callable only by other modules in the same package. NOT callable from PTB. Safe from external composition.
• fun (private): Not callable from outside the module. Safe.

Key observation: Any function that is public (not entry, not public(package)) is fully composable. Its return values can be routed to ANY other function in the same PTB.

1b. Single-Call Assumption Audit

For EVERY public and entry function, check whether its security model implicitly assumes it is the ONLY function called in the transaction:

Common single-call assumptions that PTBs break:

• Post-call state check: Function reads state, performs action, then a SEPARATE function checks the result. Attacker inserts commands between action and check.
• Balance snapshot: Function reads a balance at start, assumes balance changed only due to its work. Another PTB command could have changed the balance.
• One-operation-per-transaction: Protocol assumes a user can only deposit OR withdraw in a single transaction. PTB allows deposit + borrow + withdraw atomically.
• Temporal separation: Protocol assumes time must pass between action A and action B (cooldown). If both functions are callable, PTB executes them in the same transaction with zero time delta.
• Reentrancy-like patterns: Function A updates state partially, function B reads partial state. PTBs naturally enable "call A then call B" -- state IS updated between commands.

Key question for each function: "If an attacker calls this function as command N in a PTB, and can execute arbitrary commands 1..N-1 before it and N+1..1024 after it, what can go wrong?"

---

2. Multi-Step Composition Analysis

For each public function that returns objects:

Return value routing checks:

• Coin routing: If function A returns Coin<T>, can it be routed to function C (external) instead of intended function B?
• Coin splitting: PTB has native SplitCoins command. Returned Coin<T> can be split. Does protocol assume full amount passed?
• Coin merging: PTB has native MergeCoins command. Can attacker merge extra coins to inflate amounts?
• Mutable reference routing: &mut Object references are borrowed for a command and released after. Same object can be passed to multiple commands sequentially. Does command N assume the object wasn't modified by command N-1?
• Recipient mismatch: If function returns a value-bearing object, the final TransferObjects command determines the recipient.

2b. Value Interception Pattern

Model this specific attack for each function returning value:

1. Attacker calls protocol_function_A() -> returns Coin<USDC> (intended for pool)
2. Attacker routes Coin<USDC> to their own address via TransferObjects
3. Protocol expects the Coin was consumed by the next step but it was intercepted

Check: Does the protocol rely on PTB command ordering to ensure returned values reach the right destination? If YES -> the user controls the ordering, not the protocol.

---

3. Flash Loan via PTB

Without explicit flash loan protocols, PTBs enable flash-loan-like patterns:

1. [Command 1] Split large Coin<SUI> from attacker's balance
2. [Command 2] Deposit into protocol (inflates TVL/balance)
3. [Command 3] Trigger reward distribution (calculated on inflated balance)
4. [Command 4] Withdraw from protocol
5. [Command 5] Join coins back (net zero capital, captured rewards)

Can protocol state be manipulated between PTB commands?

Hot potato flash loan pattern:

1. borrow(pool, amount) -> (Coin<T>, FlashReceipt)     // Creates hot potato
2. [attacker does arbitrary operations with Coin<T>]
3. repay(pool, coin, receipt)                            // Consumes hot potato

Checks for hot potato flash loans:

• Does repay() verify returned amount >= borrowed amount + fee?
• Can attacker call OTHER protocol functions between borrow and repay that benefit from temporarily inflated balance?
• Is FlashReceipt type-parameterized to prevent cross-pool receipt reuse?
• Verify hot potato struct has NO abilities (no key, store, drop, copy)

---

4. Shared Object Mutation Ordering

Within a PTB touching shared objects:

4a. Oracle Manipulation Within PTB

1. [Command 1] Call DEX swap to move on-chain price
2. [Command 2] Call protocol function that reads manipulated price
3. [Command 3] Reverse DEX swap to restore price
4. Net effect: Protocol acted on manipulated price, attacker profited

Check: Does protocol read spot prices (manipulable) or TWAP/oracle prices (resistant)?

4b. Balance Manipulation Within PTB

1. [Command 1] Deposit large amount (inflate balance/shares)
2. [Command 2] Trigger reward distribution (on inflated balance)
3. [Command 3] Withdraw deposited amount
4. Net effect: Captured rewards with zero time commitment

4c. State Toggling Within PTB

1. [Command 1] Set state to value A (e.g., via AdminCap function)
2. [Command 2] Perform action requiring state A
3. [Command 3] Reset state back to original value B
4. Net effect: Privileged action performed, state appears unchanged

Check: Possible if attacker controls an AdminCap? (Rule 6: semi-trusted role analysis)

4d. Shared Object Reorder Sensitivity

Check for each shared object: Write down the invariant. Can a sequence of 2-3 valid individual operations (each maintaining the invariant) produce a combined state that violates the invariant?

---

5. Hot Potato Enforcement

For each zero-ability struct (hot potato):

Checks:

• Verify struct has NO abilities. If it has drop -> NOT a hot potato.
• Is the consuming function the ONLY function accepting this type?
• Can multiple hot potatoes be created in a single PTB? Does consumption order matter?
• Does consuming function validate the hot potato matches the creating context?
• Can attacker cause consumption precondition to fail AFTER hot potato created? (entire PTB aborts -- griefing vector)
• Can a wrapper with store ability store the hot potato? (bypass via external module -- check for public generic wrappers)

---

6. Object Wrapping/Unwrapping in PTB

Can objects be wrapped, manipulated, and unwrapped within a single PTB to bypass checks?

Pattern: Object has transfer restrictions (key only, no store). Attacker wraps it inside a store-capable struct, transfers the wrapper, then unwraps on the other side. If wrap and unwrap are both public functions -> transfer restriction bypassed within a single PTB.

---

7. Gas Budget Manipulation

PTB gas budget is shared across all commands.

Typically lower severity: Sui's gas model charges the sender, so resource attacks are self-penalizing. Focus on aggregate limit bypass.

---

Output Schema

## Finding [PTB-N]: Title

**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: check1,2,3,4,5,6,7 | skip(reason) | uncertain
**Rules Applied**: [R4:___, R5:___, R8:___, R10:___, R15:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: sources/{module}.move:LineN

**PTB Attack Type**: SINGLE_CALL_ASSUMPTION / RETURN_VALUE_ROUTING / FLASH_LOAN_VIA_PTB / ATOMIC_MANIPULATION / HOT_POTATO_BYPASS / WRAP_UNWRAP_BYPASS / AGGREGATE_LIMIT
**Attack Sequence**:
1. [Command 1]: {what attacker does}
2. [Command 2]: {what attacker does}
3. [Command N]: {what attacker does}
**Net Effect**: {what the attacker gained}

**Description**: What is wrong
**Impact**: What can happen (fund loss, unfair value capture, invariant violation)
**Evidence**: Code showing vulnerability + PTB command sequence

---

Step Execution Checklist (MANDATORY)

Cross-Reference Markers

After Step 1b: If single-call assumption found on fund-critical function -> immediate HIGH finding.

After Step 3: Cross-reference with SHARE_ALLOCATION_FAIRNESS for deposit-action-withdraw reward capture.

After Step 4a: Cross-reference with ORACLE_ANALYSIS if on-chain DEX prices are used.

After Step 5: Cross-reference with ABILITY_ANALYSIS Section 5 (Hot Potato Enforcement).

If any step skipped, document valid reason (N/A, no hot potatoes, no external calls, no aggregate limits).