Interacting with the Clipper Exchange contracts
There are several different external functions for interacting with the Clipper exchange onchain, depending on your use case. In all of these functions, Signature is a struct defined by:
Avoiding Transaction Errors with the Clipper API
Clipper is designed to be used sequentially, so that it trades only one active and outstanding signed quote at a time. Once you execute a swap with Clipper all of your existing quotes from before that swap are "dirty" and may no longer be honored onchain.
If you try to sign multiple quotes, or use the same signed quote multiple times, the transactions are highly likely to revert on the blockchain, costing you gas. To avoid this, always call for fresh quotes after you transact with Clipper.
Swapping Tokens for Tokens
function swap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;
function transmitAndSwap(address inputToken, address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;
Observe that the signed quote has all of these values to use, except for auxiliaryData which can be set to any string and is used for identification purposes in the event logs.
The difference between swap and transmitAndSwap is that transmitAndSwap starts by transferring inputAmount of the inputToken from msg.sender to the exchange, while swap assumes that the appropriate amount of the input token has already been transmitted. Which function you should use depends on if and how you are connecting the Clipper swap to other operations.
See the complete example here
Handling Native Currency
On each chain a native currency has special privileges and abilities and is often not ERC20 compatible. For instance, MATIC is the native currency on Polygon. Unlike the Clipper implementation on Ethereum mainnet, Clipper's RFQ architecture only uses ERC20 tokens, meaning that these native currencies must be wrapped before exchange with Clipper, and that Clipper can only return the wrapped version of these assets from the exchange.
However, for convenience, we provide two sets of functions for handling native currency in a direct fashion. For these swaps, you must get a signature for a transaction to or from the wrapped version of the native currency, as this is what will actually be exchanged.
For swaps of tokens to native currency (example: DAI to MATIC on Polygon), use:
function sellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;
function transmitAndSellTokenForEth(address inputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external;
As with token-to-token swaps, the difference between these functions is that the first assumes that at least inputAmount of inputToken has already been sent, while the second pulls that input token directly from msg.sender. Observe further that:
The outputToken argument is not present (since it will be native currency)
These functions refer to the native currency as Eth regardless of chain
For swaps of native currency to tokens (example: MATIC to USDC on Polygon), use:
function sellEthForToken(address outputToken, uint256 inputAmount, uint256 outputAmount, uint256 goodUntil, address destinationAddress, Signature calldata theSignature, bytes calldata auxiliaryData) external payable;
This function can operate either by attaching the native currency to the call as msg.value or by transferring that native currency to the exchange contract prior to the function call.
Reduced calldata API
On L2s like Optimism, Clipper's exchange contracts include two special functions that operate with reduced calldata in order to lower transaction costs. These functions are:
function packedTransmitAndSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;
function packedSwap(uint256 packedInput, uint256 packedOutput, uint256 packedGoodUntil, bytes32 auxData, bytes32 r, bytes32 vs) external payable;
Similar to the other Clipper functions, use packedTransmitAndSwap to transmit the token from msg.sender and use packedSwap if tokens have already been transmitted.
Handling Native Currency in the L2 API
Indicate native currency (e.g., ETH on Optimism) should be the input or output by setting the contract address to address(0).
Packed Format Values
The packed format is a way of compressing an integer amount and a contract address into a single uint256 value. The packed format puts the address as the (first, lowest order) 160 bits (= 40 hex values = 20 bytes) and the amount as the (second, highest order) 96 bits (= 24 hex values = 12 bytes). To created a packed value, leftshift the integer amount by 160 bits and add it to the binary representation of the contract address. The four packed arguments into this function, and the values they encode, are:
packedInput: input amount and contract address
auxData - this is a bytes32 value that is a packed representation of an identifying string, and the destination_address (lowest order bytes). The identifying string is emitted as part of Swapped event and allows us to attribute trade sourced correctly.
packedOutput: output amount and contract address
packedGoodUntil: Simply use the good_until value received from the server - it is already a packed representation of state.
Short Signatures
These functions use the EIP 2098 "short signature" representation for the signature returned from the Clipper Exchange server. Source code to convert from the v, r, s signature value to the r, vs short signature is available on the EIP.
Intermediate Contract Whitelisting
Clipper limits the number of signed quotes per day for each destination_address. If you make use of an intermediate or routing contract, please let us know the address you intend to use for that and we can whitelist the address to remove its daily signing limits.
Last updated