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).