Write Your Own Opcode

source-verifiedGreen This page shows how to add a custom instruction to a SwapVM router: write the instruction, register it in the router's opcode set, and build a program with ProgramBuilder. It also documents the compiler settings the dispatch mechanism depends on, the EIP-170 constraint that forces curation of the native opcode set, the taker-side TakerTraits layout and EIP-1271 signature path, and a set of verified tooling footguns that repeatedly bite integrators.

The instruction model

A SwapVM program is a flat byte string. The run loop (src/libs/VM.sol, ContextLib.runLoop) walks it two bytes at a time: the first byte is the opcode, the second is the argument length (0–255), followed by that many argument bytes.

[opcode:1][argsLen:1][args:argsLen] [opcode:1][argsLen:1][args:argsLen] ...

For each instruction the loop calls a dispatcher stored as an internal function pointer on the VM (ctx.vm.dispatch), which the router wires to _runOpcode(ctx, opcode, args).

Every instruction has exactly this signature:

function _myInstruction(Context memory ctx, bytes calldata args) internal;

The instruction receives the whole execution Context (src/libs/VM.sol) and may read and mutate it:

Reading taker-supplied arguments

Two kinds of data reach an instruction. The program args (the args parameter) are baked into the maker's strategy and are the same for every taker. Taker args are supplied per-swap by the caller (the instructionsArgs slice of TakerTraits) and are consumed front-to-back via ContextLib:

bytes calldata all   = ctx.takerArgs();          // remaining taker args
bytes calldata chunk = ctx.tryChopTakerArgs(32); // consume up to 32 bytes

Extruction._extruction is the canonical example: it forwards ctx.takerArgs() to an external contract and then tryChopTakerArgs(choppedLength) to consume exactly what that contract reports it used.

Step by step: write, register, build

1. Write the instruction contract

Create a contract under src/instructions/ exposing one or more internal functions with the instruction signature. Keep the logic deterministic — the same input must produce the same output in both quote() (static) and swap() contexts, or quote/swap consistency breaks.

// src/instructions/MyCap.sol
import { Context, ContextLib } from "../libs/VM.sol";

contract MyCap {
    using ContextLib for Context;

    error AmountOutExceedsCap(uint256 amountOut, uint256 cap);

    /// args: [cap: 32 bytes]
    function _capAmountOut1D(Context memory ctx, bytes calldata args) internal pure {
        uint256 cap = uint256(bytes32(args));
        require(ctx.swap.amountOut <= cap, AmountOutExceedsCap(ctx.swap.amountOut, cap));
    }
}

2. Register it in the opcode set

An opcode set contract (src/opcodes/Opcodes.sol for the standard router, src/opcodes/AquaOpcodes.sol for the Aqua router) inherits every instruction contract and exposes two parallel structures that must stay in lockstep:

• _runOpcode(ctx, opcode, args) — the runtime if/else dispatcher. Add your branch at the next free index.
• _opcodes() — a fixed array of internal function pointers. Add your function pointer at the same index. This array is what ProgramBuilder uses to translate a function into its opcode byte.

// in _runOpcode(...)
else if (opcode == 52) MyCap._capAmountOut1D(ctx, args);   // next free index

// in _opcodes() — append at the SAME position, and bump the array size
MyCap._capAmountOut1D

Finally, a router (src/routers/…) inherits the opcode set and overrides _dispatch to call _runOpcode. That is the whole wiring:

function _dispatch(Context memory ctx, uint256 opcode, bytes calldata args) internal override {
    _runOpcode(ctx, opcode, args);
}

3. Build a program with ProgramBuilder

ProgramBuilder (test/utils/ProgramBuilder.sol) turns instruction references into bytecode. It resolves an opcode by internal function-pointer equality against the set returned by _opcodes():

Program memory program = ProgramBuilder.init(_opcodes());

bytes memory bytecode = bytes.concat(
    program.build(_xycConcentrateGrowLiquidity2D, concentrateArgs),
    program.build(_flatFeeAmountInXD, feeArgs),
    program.build(_capAmountOut1D, abi.encodePacked(cap)),   // your new opcode
    program.build(_xycSwapXD)                                 // no args
);

findOpcode loops _opcodes() and returns the index where self.opcodes[i] == targetOpcode. If the function pointer is not in the set it reverts OpcodeNotFound at build time. That equality check is the reason the whole project is compiled through the IR pipeline (next section).

The bytecode becomes the program field of a maker order via MakerTraitsLib.build(...). The order's data is tokenA ‖ tokenB ‖ hooks… ‖ program, with tokenA < tokenB enforced.

Required solc settings

The instruction dispatch and the ProgramBuilder opcode lookup both hinge on internal function pointers being stable, comparable values (self.opcodes[i] == targetOpcode). The project only ever compiles this under the Yul/IR pipeline; do the same, or the comparison — and therefore your generated programs — cannot be trusted.

EIP-170 and curating the native set

A deployed contract may not exceed the EIP-170 bytecode limit (24,576 bytes). Every instruction the router inlines adds to that budget, so the two shipped opcode sets are deliberately different sizes:

• Opcodes (standard SwapVMRouter) registers the full set — control flow, balances, invalidators, XYC/concentrate/decay, limit, min-rate, Dutch auction, TWAP, fees, pegged, whitelist, extruction — opcodes 10–51.
• AquaOpcodes (deployed AquaSwapVMRouter) registers only a curated subset — Controls, XYCSwap, XYCConcentrate, Decay, Fee (amount-in variants), PeggedSwap, Extruction — opcodes 10–33.

TakerTraits & the taker path

The taker controls execution through TakerTraits (src/libs/TakerTraits.sol), a packed uint176 header (18-byte slice-index table + 2-byte flags) followed by variable-length slices. Build it with TakerTraitsLib.build(Args). The fields that matter to integrators:

The threshold and deadline are enforced in TakerTraitsLib.validate after the program runs: amountOut > 0 is required, the deadline is checked against block.timestamp, and the min/max (or strict) threshold is applied to the computed amount.

The EIP-1271 (smart-contract signature) path

For signature-based (non-Aqua) orders, SwapVM.swap verifies the maker with:

bytes calldata signature = takerTraits.signature(takerData);
require(order.maker.recoverOrIsValidSignature(orderHash, signature),
        BadSignature(order.maker, orderHash, signature));

recoverOrIsValidSignature (from @1inch/solidity-utils ECDSA) first attempts EOA ecrecover and, failing that, falls back to the EIP-1271 isValidSignature(bytes32,bytes) call on order.maker. So a smart-contract wallet or a programmatic maker can sign orders — the signature simply travels in the signature slice of the taker data. Aqua orders (useAquaInsteadOfSignature) skip this entirely: authority comes from having shipped liquidity into Aqua under that orderHash, and the order is hashed with a plain keccak256(abi.encode(order)) rather than the EIP-712 typed hash.

Known tooling caveats & version drift