RFC: Reference-Ordered PTB Commands — Unlocking Composable Transaction Building

[Danny-Devs]

TL;DR

In Transaction.ts, there's a TODO comment (introduced in SDK v2 Release, lines 94-96):

// TODO: Instead of making this return a concrete argument, we should ideally
// make it reference-based (so that this gets resolved at build-time), which
// allows re-ordering transactions.

I'd like to explore what this foundational change would enable.

Once transaction results are symbolic until build-time, the SDK could:

• Topologically sort commands based on data dependencies
• Enable composable transaction fragments across protocol SDKs
• Lay the groundwork for future optimization passes (dead code elimination, deduplication)

Questions:

1. What's currently blocking this change? (complexity? backwards compat? priority?)
2. Would a concrete RFC with migration path be useful?
3. Are there internal use cases at Mysten that would benefit?

Happy to contribute research, RFC drafting, or a proof-of-concept if this direction is welcome.

---

The Current State

Today, when you call:

const coin = tx.splitCoins(tx.gas, [100]);

The coin variable receives a TransactionResult with a concrete command index. Internally, its shape is:

{ $kind: 'Result', Result: 0 }  // where 0 is the command's position

The index is determined at declaration time — specifically, it's this.#data.commands.length - 1 at the moment the command is added (see Transaction.ts line 478).

This means the moment you reference that result in another command, you've implicitly committed to an execution order. The SDK processes commands largely in declaration order, with some handling for async thunks, but the fundamental ordering is fixed at declaration time.

---

The Composition Problem

Consider two protocol SDKs trying to interoperate.

(Note: These are simplified illustrative examples, not actual protocol APIs.)

Protocol A provides a swap helper:

function protocolASwap(tx: Transaction, coinIn: TransactionArgument) {
  return tx.moveCall({
    target: 'protocol_a::pool::swap',
    arguments: [coinIn]
  });
  // Returns { $kind: 'Result', Result: 0 } — if this was the first command
}

Protocol B provides a deposit helper:

function protocolBDeposit(tx: Transaction, coin: TransactionArgument) {
  return tx.moveCall({
    target: 'protocol_b::market::deposit',
    arguments: [coin]
  });
}

A developer composes them:

const tx = new Transaction();

// Step 1: Swap
const outputCoin = protocolASwap(tx, inputCoin);
// outputCoin = { $kind: 'Result', Result: 0 }

// Step 2: Deposit the swap output
protocolBDeposit(tx, outputCoin);
// This command references Result(0)

// ✅ This works!

But then they realize they need to add a borrow operation that should logically come before the swap:

const borrowedCoin = tx.moveCall({
  target: 'protocol_b::market::borrow',
  arguments: [...]
});
// borrowedCoin = { $kind: 'Result', Result: 2 }

// PROBLEM: This is command index 2, but the developer wanted it first.

The developer is stuck. The indices were baked in when each command was declared. They can't insert a command at position 0 without manually rewriting every Result reference in the transaction.

This is why composing transaction fragments from multiple protocol SDKs is fragile today — each SDK bakes in concrete indices, and combining them requires careful coordination of declaration order.

---

The Vision: Reference Ordering

What if transaction results were symbolic until build time?

(Note: The syntax below is illustrative — it shows what a reference-based API could look like, not current SDK behavior.)

const coin = tx.splitCoins(tx.gas, [100]);
// Hypothetically: coin = { $ref: Symbol('cmd-0') } — symbolic, not yet concrete

Now developers could declare commands in any order that makes sense for their code:

const tx = new Transaction();

// Declare in whatever order is natural
const outputCoin = protocolASwap(tx, inputCoin);   // symbolic reference
const receipt = protocolBDeposit(tx, outputCoin);  // symbolic, depends on outputCoin
const borrowedCoin = protocolBBorrow(tx, ...);     // symbolic, independent

// At build time:
await tx.build({ client });

What would happen at build time:

1. Dependency analysis — The SDK traces which commands consume which results:

   • deposit depends on swap (it uses outputCoin)
   • borrow has no dependency on either

2. Topological sort — Find valid execution orders that respect dependencies:

   • [borrow, swap, deposit] ✓
   • [swap, borrow, deposit] ✓
   • [swap, deposit, borrow] ✓
   • [deposit, swap, ...] ✗ (violates dependency)

3. Index assignment — Pick a valid order and assign concrete indices

4. Reference resolution — Replace all symbolic references with concrete indices

The developer never had to think about command ordering. They declared what they wanted, and the SDK figured out a valid execution sequence.

Error handling: If references create a circular dependency (A depends on B, B depends on A), the SDK would fail at build time with a clear error message.

---

What This Foundation Would Enable

Once the SDK has a dependency graph instead of a flat command list, it enters "compiler" territory. The first step (reference ordering) is the foundation; these are potential future capabilities it would unlock:

1. Composable Transaction Fragments

Protocol SDKs could provide transaction "building blocks" that compose naturally:

// Hypothetical future API:
const swapResult = protocolA.addSwap(tx, { coinIn, minOut });
const leverageResult = protocolB.addLeverage(tx, { collateral: swapResult });

// At build time: SDK resolves cross-protocol dependencies automatically

Today this is fragile because of index coordination. With reference ordering, each protocol SDK could operate independently.

2. Dead Code Elimination (Future Possibility)

If a command's result is never consumed, a future optimization pass could detect and remove it:

const routeA = tx.moveCall({ target: 'dex_a::swap', ... });
const routeB = tx.moveCall({ target: 'dex_b::swap', ... });

// Developer only uses routeB downstream
tx.transferObjects([routeB], recipient);

// Future optimization: SDK could detect routeA is unused and prune it

3. Command Deduplication (Future Possibility)

Identical commands with identical inputs could potentially be merged:

const coinA = tx.splitCoins(tx.gas, [100]);
const coinB = tx.splitCoins(tx.gas, [100]);  // Same operation

// Future optimization: SDK could detect the duplicate

4. Transaction Templates (Future Possibility)

With symbolic references, parameterized transaction templates become conceivable:

// Hypothetical future API:
const template = Transaction.createTemplate()
  .splitCoins(PARAM.gas, [PARAM.amount])
  .transferObjects([RESULT(0)], PARAM.recipient);

// Instantiate with different parameters
const tx1 = template.instantiate({ amount: 100, recipient: alice });
const tx2 = template.instantiate({ amount: 200, recipient: bob });

5. Debugging & Visualization

The dependency graph IS the execution plan. Future tooling could expose it:

// Hypothetical future API:
const plan = tx.explain();
// {
//   commands: [...],
//   dependencies: { 0: [], 1: [0], 2: [] },
//   executionOrder: [0, 2, 1]
// }

---

The Architectural Principle

Current (Fixed Ordering)	Proposed (Reference Ordering)
Commit indices at declaration time	Commit indices at build time
Indices are concrete immediately	Indices are symbolic until build
Order = declaration order	Order = any valid topological order
SDK = serializer	SDK = lightweight compiler

This pattern — delaying commitment from declaration to build time — is the same architectural move that:

• SQL query builders use (build up the query, execute later)
• React's virtual DOM uses (describe the UI, reconcile later)
• Terraform uses (declare resources, plan/apply later)

Declarative systems that defer commitment can perform analysis and optimization that imperative systems cannot.

---

Summary

PTBs are Sui's signature innovation — atomic, composable, multi-step transactions. The TODO comment in Transaction.ts identifies a foundational improvement: making transaction results reference-based rather than index-based.

This change would:

1. Immediately enable easier composition of transaction fragments across protocol SDKs
2. Lay the foundation for future optimization passes (dead code elimination, deduplication, etc.)

The first step is the foundation. Everything else builds on it.

I'm happy to contribute RFC drafting, migration path analysis, or a proof-of-concept implementation if this direction is welcome.

[hayes-mysten]

Questions:

What's currently blocking this change? (complexity? backwards compat? priority?)

Complexity and backwards compatibility are big concerns here. We try really hard to avoid breaking changes where possible, and when they are needed we try to batch them together so bigger migrations are less frequent. The Transaction interface is more sensitive to this than other parts of the SDK because transaction instances are frequently built and passed between different SDKs, and ensuring that this does not break in all kinds of weird and complicated edge cases is very complex.

This is also a much more complex issue than it might appear at a surface level, and also has security and debugging implications that need careful consideration in the design.

Would a concrete RFC with migration path be useful?

To move forward with this, we'd a very detailed understanding of the full set of changes required, and exactly how this interacts with many different parts of the system including:

• the wallet standard (and both v1/v2 json formats)
• transaction plugins (especially existing plugins that do command substitution or injection)
• transaction thunks (both sync and async)
• transaction intents
• error messages (both build time errors and simulate/execution errors that reference specific commands)
• sdk compatibility and interoperability

I am very confident this is not something an LLM would do well, and would be very hesitant to spend any significant time reviewing a mostly llm derived solution to these problems.

I think doing this well is probably multiple months of effort and iteration (first solutions to these kinds of problems always need revision or redesigns). And the complexity involved here is why it did not happen as part of the 2.0 release.

Are there internal use cases at Mysten that would benefit?

There are no real blockers on these changes, but many pain points that could be made simpler if this was handled properly (mostly similar to what's mentioned in the original issue). We have some use cases that are overly complex today, that should be made simpler:

• coin/balance intent substitution
• command substitution for swap/defi sdks
• dynamic dispatch alternatives that dynamic PTB construction based on inputs (eg permission or payment checks for future versions of kiosk/pas style apis)

[hayes-mysten]

There is probably a lot I am forgetting here, but this at least covers some of the high level pieces of what we've been considering for this.

It's not super urgent, because the existing APIs and tooling are sufficient for all known use cases, we just know that the model could be made simpler.

One other major piece of this is that if we were to re-design how transactions are represented internally we want to move to a model without mutable state where everything works through transforms and caches rather than mutating the internal state directly

[Danny-Devs]

Thanks for the response, Hayes — really appreciate the depth.

Hearing you clearly: the ref-ordering redesign is complex, touches six load-bearing surfaces, not urgent. Parking the full design.

The transforms+caches direction is really cool — it makes all three pain points collapse into the same shape. Looking forward to seeing where you take it.

Hoping to help out with the three pain points.

[Danny-Devs]

Hey Hayes — thanks again for the steer on those three pain points.

I took a swing at #1 (coin/balance intent substitution). Two questions before I open a PR:

1. Are you done iterating on CoinWithBalance for now? I saw Add tx.coin/tx.balance methods, rewrite CoinWithBalance intent resolution #963 and Prefer address balances over coins in intent resolution #1001 in late March / early April and want to make sure I'm not stepping on in-flight work.

2. Is PAS-style convergence the direction you want for intent resolvers? The shape I prototyped mirrors packages/pas/src/intents.ts.

If either is no, I can park this and pivot to #2 or #3.

[hayes-mysten]

coin and balance changes should be mostly stable now. We'll see if anything else is needed after address balances go live on mainnet.

PAS is using the current best practices for intents, but I wouldn't design around it. If we are rethinking the internals of how transactions are built, it probably makes sense to rethink how intents are resolved as part of that. The current solutions are a little awkward and have a lot of places where its easy to make subtle mistakes in re-mapping and substitution