Encoding Reference

This page gives the exact packed bit and byte layouts used by the on-chain SwapVM and Aqua contracts, so an off-chain decoder can reconstruct every field without guessing. Every offset below is taken directly from the source symbols cited under each section. Bit positions are counted from the least-significant bit (bit 0) of the underlying uint256; byte offsets are counted from the start of the byte string and are big-endian, matching Solidity's abi.encodePacked layout.

MakerTraits — packed uint256 header

Source: swap-vm/src/libs/MakerTraits.sol, type MakerTraits is uint256 and library MakerTraitsLib. The value is assembled in MakerTraitsLib.build; the constants below are the literal bit-flag definitions.

| Bit(s) | Width | Field | Source constant / expression | | ------- | ----- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------ | ------------- | | 255 | 1 | shouldUnwrapWeth | SHOULD_UNWRAP_BIT_FLAG = 1 << 255 | | 254 | 1 | useAquaInsteadOfSignature | USE_AQUA_INSTEAD_OF_SIGNATURE_BIT_FLAG = 1 << 254 | | 253 | 1 | allowZeroAmountIn | ALLOW_ZERO_AMOUNT_IN = 1 << 253 | | 252 | 1 | hasPreTransferInHook | HAS_PRE_TRANSFER_IN_HOOK_BIT_FLAG = 1 << 252 | | 251 | 1 | hasPostTransferInHook | HAS_POST_TRANSFER_IN_HOOK_BIT_FLAG = 1 << 251 | | 250 | 1 | hasPreTransferOutHook | HAS_PRE_TRANSFER_OUT_HOOK_BIT_FLAG = 1 << 250 | | 249 | 1 | hasPostTransferOutHook | HAS_POST_TRANSFER_OUT_HOOK_BIT_FLAG = 1 << 249 | | 248 | 1 | preTransferInHookHasTarget | PRE_TRANSFER_IN_HOOK_HAS_TARGET = 1 << 248 | | 247 | 1 | postTransferInHookHasTarget | POST_TRANSFER_IN_HOOK_HAS_TARGET = 1 << 247 | | 246 | 1 | preTransferOutHookHasTarget | PRE_TRANSFER_OUT_HOOK_HAS_TARGET = 1 << 246 | | 245 | 1 | postTransferOutHookHasTarget | POST_TRANSFER_OUT_HOOK_HAS_TARGET = 1 << 245 | | 244–224 | 21 | reserved (written as zero) | gap between flag bits and index block | | 223–208 | 16 | index3 — end of PostTransferOutHook slice = program start offset | orderDataIndexes << ORDER_DATA_SLICES_INDEXES_BIT_OFFSET where ORDER_DATA_SLICES_INDEXES_BIT_OFFSET = 160; four uint16 packed as (index0<<0) | (index1<<16) | (index2<<32) | (index3<<48) | | 207–192 | 16 | index2 — end of PreTransferOutHook slice | | | 191–176 | 16 | index1 — end of PostTransferInHook slice | | | 175–160 | 16 | index0 — end of PreTransferInHook slice | | | 159–0 | 160 | receiver address (if zero, defaults to maker) | uint160(args.receiver) |

The four packed indexes are read back by _getOffset(traits, sliceNumber):

         
         

           Solidity
         
 
         
         

           
           

             
1
2
           
 
           
           
bitShift = sliceNumber << ORDER_DATA_SLICES_INDEX_BIT_SIZE_SHL;   // sliceNumber * 16
offset   = (traits >> 160 >> bitShift) & type(uint16).max;      // ORDER_DATA_SLICES_INDEX_BIT_MASK
         
       

Order.data byte layout (the bytes referenced by MakerTraits)

The data field of ISwapVM.Order is built with bytes.concat / abi.encodePacked in MakerTraitsLib.build. It is a packed (non-ABI) byte string. The enum OrderDataSlices { PreTransferInHook, PostTransferInHook, PreTransferOutHook, PostTransferOutHook, Program } names the slices. In the deployed v1.0.1 layout there is no token prefix — the token pair is passed to quote/swap as explicit tokenIn/tokenOut arguments, not stored in data — and the four packed index0..index3 values in MakerTraits mark the slice boundaries:

Confirmed by MakerTraitsLib._getDataSlice: the PreTransferInHook slice starts at 0, and the Program slice stops at data.length. All intermediate boundaries are the packed indexes above. (The unreleased main branch prepends a tokenA || tokenB pair and shifts every slice by 40 bytes, but that revision is not tagged or deployed — build against the layout above.)

TakerTraits — packed header + slice table

Source: swap-vm/src/libs/TakerTraits.sol, type TakerTraits is uint256 and library TakerTraitsLib. Unlike MakerTraits, the taker value is a 22-byte (176-bit) header that is prepended to a packed tail. parse reads it as TakerTraits.wrap(uint176(bytes22(data.slice(0, 22, ...)))) and the tail is data.slice(22).

Header composition (as emitted by build)

build does abi.encodePacked(slicesIndexes /*uint160*/, flags /*uint16*/, ...tail...). So on the wire the first 20 bytes are the ten packed slice indexes and the next 2 bytes are the flag word:

Header as a uint176 (how the getters read it)

TAKER_DATA_SLICES_INDEXES_BIT_OFFSET = 16, so _getOffset(traits, n) = (traits >> 16 >> (n*16)) & type(uint16).max. The flag word sits in the low 16 bits.

Flag word (low 16 bits)

Tail slice table

Offsets are relative to the tail (the bytes after the 22-byte header). The enum TakerDataSlices ordering drives _getStartOffset/_getStopOffset: slice s starts at index[s-1] (or 0 for the first) and stops at index[s] (or dataLength for the last).

The strategy shape emitted in Shipped.strategy

Source: aqua/src/interfaces/IAqua.sol (event Shipped(address maker, address app, bytes32 strategyHash, bytes strategy)) and aqua/src/Aqua.sol (ship computes strategyHash = keccak256(strategy) and emits Shipped). For a SwapVM strategy, strategy is abi.encode(order) where order is ISwapVM.Order — confirmed by swap-vm/test/base/AquaStrategyBuilders.sol (bytes memory strategy = abi.encode(order);) and by SwapVM.hash, which for Aqua orders returns keccak256(abi.encode(order)) (so strategyHash == orderHash).

ISwapVM.Order (from swap-vm/src/interfaces/ISwapVM.sol):

         
         

           Solidity
         
 
         
         

           
           

             
1
2
3
4
5
           
 
           
           
struct Order {
    address    maker;    // liquidity provider
    MakerTraits traits;  // uint256, packed header above
    bytes      data;     // hooks... || program  (no token prefix at v1.0.1)
}
         
       

Because it is standard abi.encode of a (address, uint256, bytes) tuple, the outer byte layout of Shipped.strategy is:

A decoder therefore:

1. Reads maker from the low 20 bytes of [0x00:0x20].

2. Reads traits from [0x20:0x40] and decodes the MakerTraits bit map (above) — in particular index3 at bits 223–208, which is the program start offset within data.

3. Reads len = data.length from [0x60:0x80] and takes data = strategy[0x80 : 0x80 + len].

4. Within data (no token prefix at v1.0.1): the SwapVM program bytecode tail = data[index3 : len]; with no hooks index3 = 0, so the program is all of data. The token pair is not in data — it is supplied as the tokenIn/tokenOut arguments to quote/swap.

rawBalances packing (Balance struct)

Source: aqua/src/libs/Balance.sol (struct Balance { uint248 amount; uint8 tokensCount; } and BalanceLib.load/store) and aqua/src/Aqua.sol (_balances mapping and _DOCKED). Each balance occupies exactly one 32-byte storage slot.

The pack/unpack is done in assembly:

// store
packed = or(amount, shl(248, tokensCount));   // amount in low 248 bits, count in top byte
// load
amount      = packed & 0x00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;
tokensCount = shr(248, packed);

The external view rawBalances(maker, app, strategyHash, token) returns (uint248 balance, uint8 tokensCount) as two separate ABI words; the single-slot packing above is the storage form, not the return form.

tokensCount sentinel values and _DOCKED

uint8 private constant _DOCKED = 0xff; (source: aqua/src/Aqua.sol). The tokensCount byte doubles as a lifecycle marker:

The maximum token count is _DOCKED - 1 = 254: ship reverts with MaxNumberOfTokensExceeded(tokensCount, _DOCKED - 1) if tokensCount == _DOCKED. safeBalances and push both treat a token as usable only when tokensCount > 0 && tokensCount != _DOCKED; dock stores (0, _DOCKED) for every token in the strategy.

Source files

• swap-vm/src/libs/MakerTraits.sol — MakerTraits, MakerTraitsLib (flag constants, build, _getOffset, OrderDataSlices)

• swap-vm/src/libs/TakerTraits.sol — TakerTraits, TakerTraitsLib (flag constants, build, parse, TakerDataSlices, _getStartOffset/_getStopOffset)

• swap-vm/src/interfaces/ISwapVM.sol — ISwapVM.Order

• swap-vm/src/SwapVM.sol — hash() (keccak256(abi.encode(order)) for Aqua orders), ORDER_TYPEHASH

• swap-vm/test/base/AquaStrategyBuilders.sol — abi.encode(order) shipped as the strategy

• aqua/src/interfaces/IAqua.sol — Shipped event, rawBalances

• aqua/src/Aqua.sol — ship/dock/push/safeBalances, _DOCKED

• aqua/src/libs/Balance.sol — Balance struct, BalanceLib.load/store

TakerTraits bridge — SDK wrapper → Solidity flag → bit

The two canonical TakerTraits implementations are the on-chain library TakerTraitsLib (swap-vm/src/libs/TakerTraits.sol) and the off-chain wrapper class TakerTraits in @1inch/swap-vm-sdk (typescript/swap-vm/src/swap-vm/taker-traits.ts). They encode the same 22-byte header — uint176 = 20-byte slicesIndexes (ten uint16) followed by a uint16 flag word — but name the flags differently and, critically, store the flag constants in two different forms. This section is the exact field-by-field bridge so a value round-trips losslessly between them.

Flag word bridge (low 16 bits of the header)

All seven flags live in the low uint16 of the uint176 header. The SDK exposes each as a public readonly boolean property on the TakerTraits instance (there are no getter methods on the SDK side); Solidity exposes each via a library getter that masks the packed value.

Header slice fields (SDK constructor field → Solidity slice)

The non-flag header fields set the ten packed slicesIndexes that delimit the tail. Each SDK constructor field maps one-to-one to a TakerTraitsLib.Args field and to one TakerDataSlices entry. The SDK omits a slice (contributes zero length, leaving the boundary equal to the previous index) under the same emptiness rule the Solidity build uses.