Skip to main content
An operator is any wallet that calls swap for a different user: a relayer, an execution desk, or a smart account module. The user’s tokens move, so the user must authorize the operator first, in one of two ways.

Choose an authorization

Both only authorize the operator. The user’s ERC-20 approval to the capital provider’s delegate is still what lets the tokens move.

Before you start

  • Bounded legs. Build and bound each leg as in Swap on-chain. The user authorizes those bounds.
  • The user’s approval. The user approves the delegate of each leg’s stablecoinDelegateID for the input token, as in step 4 of Swap on-chain.
  • An operator wallet with ETH for network fees. The user, the operator, and the receiver must all be off the protocol blacklist.
  • One SDK client for each party. The examples use mlAsUser, whose wallet client signs as the user, and mlAsOperator, whose wallet client signs as the operator. Swap on-chain shows how to create a client.

Use a standing allowance

Use a standing allowance when the same operator swaps for the user repeatedly, and the output always returns to the user.
1

The user grants the allowance

The allowance belongs to one operator and one input asset ID. amount is added to what remains.
2

The operator swaps

The operator sends the leg with no permit. The receiver must be the user.
Each delegated leg spends its resolved input from the allowance, so an exact-out leg spends what it actually cost, not its maximum. An allowance of 2n ** 256n - 1n is unlimited and never decreases. To reduce an allowance, call adjustSwapInputAllowance with increase: false. Read the remainder with mlAsUser.swap.getSwapInputAllowance(user, operator, assetInID).

Use a signed permit

Use a permit when the user signs each swap, when the output goes to another wallet, or when the user should not send a transaction.
1

The operator prepares the legs

Build the bounded legs, choose the receiver, and set a deadline a few minutes ahead, in Unix seconds.
2

The user signs

signSwapApproval reads the user’s current nonce and signs the SwapBatchApproval message with the user’s wallet.
3

The operator simulates and submits

The operator sends the same user, receiver, legs, and permit, in the same order. Any change invalidates the signature.
The signature binds the user, the operator, the receiver, every field of every leg in order, the nonce, the deadline, the chain, and the MultiliquidSwap address. Only the operator it names can submit it. A permit cannot be used for a direct swap: if the operator is the user, the contract rejects it. A successful swap consumes the permit’s nonce. If the transaction reverts, the nonce is not consumed, so the operator can retry the same permit before its deadline.

Ordered and unordered nonces

By default a permit uses the user’s ordered nonce, nonces(user), which rises by one with each permit used. A user with several permits outstanding must sign them with consecutive nonces, and they must settle in that order. Any permit signed with a nonce that has already been used fails. An unordered permit instead uses any nonce the user has not used, so independent permits can settle in any order. Choose a random 256-bit nonce and pass unordered: true:
The user can cancel an unordered permit before it settles, even while the contract is paused:

Smart accounts and external signers

The contract accepts:
  • Externally owned accounts: a 65-byte ECDSA signature, or a 64-byte compact EIP-2098 signature.
  • EIP-7702 delegated accounts: the account key’s ECDSA signature, with an ERC-1271 check as a fallback.
  • Smart contract accounts: ERC-1271. isValidSignature must return 0x1626ba7e for the EIP-712 digest.
For a contract account, a multisig, or a custody platform, build the typed data without signing it, and have the signer sign it:
The typed data uses the domain { name: "MultiliquidSwap", version: "2", chainId, verifyingContract } with the MultiliquidSwap address as the verifying contract. MultiliquidSwap lists every type.

When something goes wrong

Swap errors such as a missed bound or an inadmissible receiver are the same as in Swap on-chain.

Next steps

MultiliquidSwap reference

The swap function, permit types, nonces, and events.

Auto-sweep

How a capital provider authorizes the contract to run legs for its own vault.