ptb-composability

name	ptb-composability
description	Trigger Pattern PTB flag (always for Sui -- Programmable Transaction Blocks are the Sui transaction model) - Inject Into Breadth agents, depth-external, depth-state-trace

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:

#	Function	Module	Visibility	Returns Value?	Takes Shared Obj?	Composable in PTB?	Notes
1	{func}	{mod}	public / entry / public(package)	YES / NO	YES / NO	YES / NO	{context}

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:

#	Function	Assumes Single-Call?	What Assumption?	Breakable via PTB?	Impact
1	{func}	YES/NO	{describe assumption}	YES/NO	{impact}

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:

#	Function	Input Objects	Output Objects	Can Output Be Routed To?	Can Be Called Multiple Times?
1	{func}	{owned/shared/immutable}	{Coin / Object / HotPotato}	{any function accepting this type}	YES/NO

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?

Function Pair	Shared State	Deposit-Action-Withdraw Possible?	Defense?
{deposit, claim}	{pool balance}	YES/NO	{cooldown? same-epoch check? minimum lock?}

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

Shared Object	Invariant	Commands That Mutate It	Sequence-Dependent?	Exploitable?
{obj}	{invariant description}	{cmd1, cmd2, cmd3}	YES/NO	{if YES, describe exploit}

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

#	Hot Potato Type	Created By	Consumed By	Abilities	Bypass Possible?
1	{Receipt}	{borrow()}	{repay()}	NONE (confirmed)	{analysis}

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?

Wrap Operation	Unwrap Operation	What's Inside	Check Bypassed?
{wrap_func}	{unwrap_func}	{object with restrictions}	{describe bypass or NONE}

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.

Attack Vector	Description	Check
Many-small-operations	1000+ tiny operations to circumvent aggregate limits	Do aggregate limits track across PTB commands?
Object creation spam	PTB creates many objects (up to 1024 per PTB)	Unbounded object creation paths?
Gas exhaustion griefing	Craft PTB that consumes max gas on revert	Gas charged on abort -- attacker pays

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)

Step	Required	Completed?	Notes
1. Entry Point Inventory	YES		All public/entry functions classified
1b. Single-Call Assumption Audit	YES		HIGH PRIORITY -- every public function checked
2. Multi-Step Composition Analysis	YES		All return values checked
2b. Value Interception Pattern	YES		Value-returning functions modeled
3. Flash Loan via PTB	YES		Deposit-action-withdraw patterns
4. Shared Object Mutation Ordering	YES		HIGH PRIORITY -- oracle, balance, state toggle
4d. Shared Object Reorder Sensitivity	YES		Invariant + multi-command sequences
5. Hot Potato Enforcement	IF hot potatoes exist		Zero-ability verified
6. Object Wrapping/Unwrapping	IF wrap/unwrap functions exist		Transfer restriction bypass
7. Gas Budget Manipulation	IF aggregate limits exist

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