Across: ABI Encoding for Crosschain Intent Orders

The Ten-Field Order Layout

AcrossOrderData contains token addresses, integer amounts, destination details and optional message bytes in a fixed sequence of ten fields. Its order matters even where neighboring fields share a type. Swapping two uint256 values can leave syntactically valid bytes while changing the transfer that the contract reads. These fields appear in the following order:

• inputToken uses address, followed by inputAmount as uint256.
• outputToken uses address, followed by outputAmount as uint256.
• destinationChainId uses uint256, followed by recipient as bytes32.
• exclusiveRelayer uses address, followed by depositNonce as uint256.
• exclusivityPeriod uses uint32, followed by message as bytes.

Which Encoding Matches the Settler’s Decoder?

The ten-field implementation expects one ABI-encoded AcrossOrderData tuple, matching abi.decode(order.orderData, (AcrossOrderData)) in the origin settler. Its component types are (address,uint256,address,uint256,uint256,bytes32,address,uint256,uint32,bytes). Because message is dynamic, the struct itself is dynamic. Encoding that struct as one argument introduces an outer offset to its content. A flat list of the ten members has a different top-level layout, even with identical values.

In Solidity, abi.encode(orderDataStruct) supplies the required struct wrapping. A client-side encoder needs one tuple parameter containing the same ordered components. An encoding that drops inputToken, inputAmount or depositNonce cannot reproduce this struct. The origin settler needs those fields alongside the destination instructions. Decoding with a different local schema does not establish compatibility with the contract’s decoder.

Type Hash and Function Calldata

OnchainCrossChainOrder wraps a uint32 fillDeadline, a bytes32 orderDataType and a bytes orderData payload for the struct-based open() interface. Its canonical function signature is open((uint32,bytes32,bytes)). Passing three separate top-level arguments describes a different function signature. The distinction changes the function selector, so the outer call requires the ABI of the selected deployment.

The type hash identifies the declared order-data format. Changing a transfer amount preserves that identifier. Changing the canonical type declaration changes its hash, including changes to member names or their types.

Function calldata adds another encoding layer around the order. A contract-call encoder supplies the function selector and outer arguments. The orderData field holds the inner encoded struct without another open() selector. Keep the type identifier, order payload and complete transaction calldata distinct; each has a different role in the call.

Integer Amounts and Token Units

Each token amount reaches the encoder as an integer in its own token units, so decimal display amounts need token-specific conversion. If a token uses d decimal places, a display amount A corresponds to A × 10^d base units, provided that the result is an exact integer. Each token has its own scale; ERC-20 makes its decimals() method optional. An encoder cannot infer that scale from an address or ticker. Keep inputAmount tied to the origin token and outputAmount tied to the destination token. Subtracting their raw integers has no economic meaning when their token units differ.

Recipient Padding and Address Conversion

Recipient data occupies the bytes32 field, while token identifiers and the exclusive relayer use address fields in this settlement format. An Ethereum Virtual Machine (EVM) address contains 20 bytes. Its wider recipient representation places 12 zero bytes before the address, leaving the address in the lower 20 bytes. The settler’s checked address conversion rejects a recipient with nonzero data in its upper 12 bytes. Left-padding preserves the account value; right-padding the address moves its bytes into different positions.

Open full-size image

A field’s width does not establish destination compatibility. This settler converts the wider recipient back into an EVM address for its deposit call. Arbitrary 32-byte account identifiers therefore do not become usable recipients simply because they fit inside bytes32.

Dynamic Message Offsets and Padding

Dynamic message bytes use an offset in the ABI head and a length word in the tail, followed by the actual contents. Inside this tuple, nine static fields and the message offset occupy ten words. The message offset measures from the start of the tuple’s content, independently of the surrounding function calldata. Treating it as an offset from the function selector points to the wrong location.

Standard ABI encoding stores dynamic bytes as a length word followed by contents padded to a multiple of 32 bytes. The length counts the actual contents, excluding padding. Trailing padding does not become part of the decoded message.

Packed encoding changes that structure by omitting normal padding and dynamic length information. Use standard ABI encoding for this order-data decoder. Message contents also have their own destination semantics. On the V3 contract-recipient callback path, a nonempty message requires the receiver to implement handleV3AcrossMessage(). If that callback fails, the fill reverts. Correct ABI wrapping alone does not establish that the receiver accepts its contents.

Fill Deadlines and Exclusivity Values

fillDeadline gives an absolute Unix timestamp in seconds, while the exclusivity field supplies a separate parameter governing exclusive fill rights. The outer order’s uint32 type constrains representation. The paired SpokePool also limits how far into the future a deposit can set its deadline through fillDeadlineBuffer. A deadline beyond the current origin-chain timestamp plus that buffer makes the deposit revert, even if it fits the integer type.

The SpokePool’s exclusivity conversion distinguishes zero, relative durations and absolute timestamps. Zero requests no exclusivity. Positive values at or below MAX_EXCLUSIVITY_PERIOD_SECONDS add the supplied seconds to the deposit timestamp. Larger values specify an absolute deadline. A positive exclusivity parameter requires a nonzero exclusive relayer; the deposit reverts if that relayer is zero. Preserve that relationship when constructing the tuple; the name exclusivityPeriod alone does not describe every accepted parameter interpretation.

Open full-size image

Nonce Choice and Deposit Identity

depositNonce selects how this origin settler obtains a deposit identifier, while the ABI represents either choice with the same integer type. Zero selects depositV3() and the SpokePool’s sequential counter. A nonzero value selects unsafeDeposit() and an identifier derived from the settler, depositor and nonce. Reusing those inputs repeats the deposit identifier. If the resulting relay hash matches one that the destination SpokePool has already marked as filled, another fill reverts. A sequential identifier can change between a view call and mining if other deposits advance the counter. The emitted deposit record identifies the actual deposit. This nonce differs from the wallet’s transaction nonce and the gasless order’s authorization nonce.

Decoded Fields and Resolved Orders

A call to resolve() expands an encoded onchain order into the outputs and fill instructions that the settlement interface exposes. In this implementation, maxSpent describes the output that the filler supplies to the transfer recipient. minReceived records the input token and amount on the origin chain, naming exclusiveRelayer as recipient. That entry describes filler-side settlement. Read each output’s token, amount, recipient and chain together. The name minReceived does not identify the end user’s destination amount.

A view result does not move funds or reserve a fill. The configured destination settler and other chain state still govern execution.

Open full-size image

Local round-trip decoding checks the serialized fields. Origin-call simulation additionally exercises the selected function with its caller and execution state, including token spending permissions. Resolution alone does not test the token transfer that open() performs. A successful origin receipt containing Open establishes order opening. A matching destination fill establishes completion separately.