V2
Overview
The Odos Router is designed as a safety wrapper around contract operations, which helps facilitate effective token swaps in the world of decentralized finance (DeFi). The Router safeguards user approvals, making sure tokens are only moved from the user in the right amount when the user is performing a swap. The goal is that the user receives at least the minimum amount they were expecting. The router can handle different kinds of swaps, as well as various approval mechanisms. Also, the router is responsible for collecting and holding revenue, which comes from positive slippage and/or fees, from the swap activities.
Key Features
Single and Multi-input/output Swapping
The main operations of the router are swap functions that aid users in exchanging tokens. The router can handle multi-input and multi-output swaps efficiently through its _swapMulti function, and single to single swaps via the _swap function. These two functions also have different methods for collecting revenue. The _swap function collects any positive slippage, which is the surplus between the quoted and actual output when the actual output is higher. Meanwhile, the _swapMulti function charges a flat fee on all swaps, but doesn’t collect any positive slippage.
Both _swap and _swapMulti have various externally callable functions. For accessing the user’s ERC20 tokens, both methods allow for standard approvals made directly to the router, as well as the use of Uniswap’s Permit2 contract. Both methods also have a compact version that reduces the amount of calldata needed to describe the swap.
Compact Swaps
The compact swap function variants aim to use as little calldata as possible, removing padding and compressing the data needed to define a swap path without compromising on complexity and accessible liquidity. This leads to gas savings across the board on all chains, but the savings are particularly large for optimistic rollups that post their calldata to Mainnet Ethereum like Arbitrum, Optimism, and Base. On these rollups, gas costs for swapping will be well over 50% cheaper than V1 in many cases, depending on network conditions and details of the swap. Compact swaps are enabled by default, but swaps encoded via the native solidity ABI are still available as well by setting the “compact” flag to false in the API.
Max Balance Swapping
Router V2 also allows the user to specify that their entire balance at the time of the swap to be used by passing in a 0 as the input amount. This is particularly useful for rebasing tokens whose balance can change slightly between the time of the path computation and the time of transaction execution. Typically these will be tokens that accumulate yield via rebasing, like Aave wrapped tokens and Overnight Finance wrapped stablecoins.
Referrals
The router has a feature for referral codes to keep track of usage. Optionally, an extra fee can be charged in conjunction with this referral code. New referral codes can be registered freely with the registerReferralCode function. Once registered, the referral code information cannot be changed - if a change is needed, a new referral code will need to be registered.
When executing a swap, a referral code can be used by passing it into the swap function. The swap will then charge the referral fee (if applicable) on the output(s) of the swap and send 80% of the fee to the specified beneficiary instantly, holding back the other 20% of the additional fee as router revenue.
For more information on how to use referral codes, check out our referral code documentation.
Owner Controls
The router collects and holds revenue generated from swap fees through positive slippage and swap fees. These funds are held in the router to avoid extra gas fees during the user’s swap for additional transfers. The router provides several owner protected functions to manage this revenue. The owner can also use certain functions to access the collected revenue, for instance, to transfer out revenue in a single denomination (like USDC) despite it originally being collected in many denominations.
Revenue Streams
The router generates income through three methods:
Normal Swaps: Revenue is generated from positive slippage, which is the difference between the quoted amount and the actual amount received when the latter is higher. Negative slippage is not revenue for the router.
SwapMulti: Instead of positive slippage, a fixed fee is deducted from the output tokens for transactions using the SwapMulti function. (Refer to the specific section for fee details.)
Referral Fees: When swaps include a partner’s referral code, an added fee is charged. Of this fee, 20% is kept by the router as its earnings, while the remaining 80% is paid to the referring partner.
Positive Slippage
In single token swaps, the router collects revenue through a process called positive slippage. Positive slippage occurs when the router executes a swap that is better than initially predicted. This can happen due to fluctuations in the market between the time an order is placed and when it’s fulfilled.
The router ensures the returned token amount falls within a range between the minimum amount outputMin to a projected amount outputQuote. If the final trade is more favorable than initially anticipated, demonstrating positive slippage, the router retains the additional amount as its revenue.
No / Non-fee Referral
When using the router without a referral code or with a referral code that does not charge an extra fee.
| Function | Owner Take |
|---|---|
| Swap | Positive Slippage |
| SwapMulti | 0.01% of Output |
Referral Fee
When using the router with a referral code that charges an extra fee.
| Function | Owner Take | Referrer Take |
|---|---|---|
| Swap | Positive Slippage + 20% of fee | 80% of fee |
| SwapMulti | 0.01% of Output + 20% of fee | 80% of fee |
Audit
Router V2 was audited by Zellic in June 2023. A link to the report can be found in the Zellic Publications GitHub Repository.
Deployments
Each of these addresses can be retrieved from the Odos API using the /info/router/v2/{chain_id} endpoint. More information about our API can be found here.
Mainnets
Ethereum
Arbitrum
Optimism
Base
Polygon PoS
Avalanche
BNB
Fantom
zkSync Era
Mode
ModeABI
This is retrievable from our API using the /info/contract-info/v2 endpoint. More information about our API can be found here.
| |
Events
Swap
Emitted when a swap between two tokens has been performed successfully using the swap or swapCompact functions.
Parameters:
sender: Address of swap userinputAmount: Amount of input tokeninputToken: Address of input tokenamountOut: Amount of output tokenoutputToken: Address of output tokenslippage: A signedint256indicating the slippage for the swapreferralCode: Referral code if one is passed in
SwapMulti
Emitted when a multi-token swap has been performed successfully using the swapMulti, swapMultiCompact, or swapRouterFunds functions.
Parameters:
sender: The address of the user who initiated the swap operation. This could be an individual user or a contract.amountsIn: An array containing the amounts of the input tokens that were used in the swap. The order of amounts corresponds to the order of the tokens in thetokensInparameter.tokensIn: An array containing the addresses of the input tokens that were used in the swap.amountsOut: An array containing the amounts of the output tokens that were received from the swap. The order of amounts corresponds to the order of the tokens in thetokensOutparameter.tokensOut: An array containing the addresses of the output tokens that were received from the swap.referralCode: The referral code that was used for the swap operation. This might affect the fee structure or benefit a particular referrer. If no referral code was used, this parameter could be 0 or an empty string.
OwnershipTransferred
Emitted when the owner of the router is transferred from one address to another.
Parameters:
previousOwner: Address of the previous ownernewOwner: Address of the new owner