Why Develop Autopilot?

Providing liquidity in DeFi, particularly to correlated trading pairs such as ETH LSTs/LRTs and stablecoins on decentralized exchanges (DEXs), or to lending markets like AAVE, Fluid, and Morpho, can be an extremely efficient onchain way to earn additional yield on one's assets. Despite this, it comes with many complexities to achieve that efficiency. Tokemak's Autopilot was developed to address the many challenges liquidity providers (LPs) face when optimizing for best performance. No protocol currently offers fully autonomous, transparent and sophisticated rebalance solution focused solely on liquidity provision. This dedicated approach offers great value not only to LPs, but also to a wide range of other ecosystem participants, making LP accessible.

The Status Quo for LPs

Liquidity providers (LPs) face a highly complex decision-making process when seeking to optimally rebalance their LP positions. It requires an LP to account for a complex set of factors, including but not limited to:

• variance of yields and their composition;

• different fee and reward systems;

• offsetting various costs such as gas, slippage, and trading fees;

• different AMM models.

Differentiating between AMM models warrants highlighting, as its complexity is an often neglected core challenge of manual liquidity provision. Additional factors complicating the process include the significant amount of time LPs must spend researching opportunities and interacting with multiple protocols, making the process time-consuming and cumbersome. Even without considering these problems, the high costs of rebalancing and compounding often lead to underperformance and can prevent LPs from participating altogether.

Introducing a New Way to LP

Autopilot, a novel LP Aggregator, unlocks a new way to LP through Autopools. Users deposit assets into an Autopool, each representing a set of potential deployment destinations for the Autopilot.

From there, Autopilot takes over, autonomously monitoring the underlying pools and leveraging its powerful logic to rebalance – thus abstracting the complexity associated with rebalancing, compounding, and staking of LP tokens away from the user. The Autopool receipt tokens (e.g., autoETH) are yield-bearing and can be seamlessly integrated across DeFi.

Effortless Access to LP Optimization

The user experience is simple:

1. LP chooses an Autopool, deposit any asset via a simple, gas-optimized transaction and gets back the yield-bearing receipt token (e.g. autoETH)

   1. Autopilot monitors the underlying destinations and rebalances

   2. Autopilot auto-compounds rewards back into the Autopool

2. LP uses Dashboard to keep track of the Autopool's performance and other metrics

Providing liquidity to a set of destinations becomes as simple as swapping tokens or making a simple deposit.

"What DEX aggregators did for traders, Autopilot is doing for LPs."

Learn more about using Autopilot in the App Guide.

Design Goals

The purpose of Autopilot is to continuously rebalance assets from the Autopool into destinations with the best risk-return profiles, aiming to outperform any individual destination within the Autopool over the long term. Earnings are auto-compounded back into the Autopool and subsequently rebalanced. To achieve this, Autopilot does not merely chase the highest advertised yield but instead processes a comprehensive set of data, applies sophisticated logic, and adheres to safety constraints. This section will provide an accessible overview of the system's general architecture and essential features.

Components & Logic

This section provides a simplified overview of the components, their functions within the Autopilot system, and a summary of the rebalance logic to help users achieve a basic understanding of the Autopilot system.

Read more

Asset Flow Example

To understand the general architecture and functioning of the system, it helps to consider a simplified flow of assets within the system

Read more

This section provides a simplified overview of the components, their functions within the Autopilot system, and a summary of the rebalance logic to help users achieve a basic understanding of the Autopilot system.

For a comprehensive breakdown of the system, its components, and functionality, please refer to the Developer docs.

System Components

Autopilot, when viewed as a system and not as a product or concept, is comprised of multiple components that as a whole fulfill the purpose of continuously rebalancing assets from an Autopool into the destinations with the best risk/return profile.

Rebalance Logic

This explanation will highlight a few of the components and steps necessary to arrive at a valid rebalance solution.

The Data

Autopilot does not simply chase the highest yield, but processes a comprehensive set of data in order to attain long-term rather than short-term outperformance. The Stats System is collecting, storing and processing this data, for example:

• APR and it's different components:

  • ETH Staking Yield: ETH yield generated by Consensus and Execution Layer rewards

  • Fee APR: Yield generated from swap fees

  • Incentive APR: Additional rewards paid to liquidity providers

• Price return:

  • Exchange rate vs underlying ETH backing

• Rebalancing costs:

  • Gas fees

  • Slippage

  • Trading fees

The above factors are weighted in order to account for e.g. likelihood of APR stability. More detail on the different yield types and APR weights can be found here.

Solution and Constraints

Based on the data made available by the Stats System, the Solver proposes rebalance solutions to interchangeably convert assets and LP tokens, as well as LP token into other LP tokens. The rebalance solutions are proposed to the Strategy backing the Autopool. The Strategy verifies on-chain the validity of the proposal and adherence to immutable constraints, also by use of the Stats System's data. Among the strategy’s key features we have the following:

• Composite Return Metric - The Composite Return Metric is a score associated with destinations for liquidity within Autopools. This metric breaks down APRs into separate parts. As such, Autopilot has the flexibility of overweighting/underweighting different components for further optimization. A valid rebalance needs to observe an increase of this metric.

• Adaptive Rebalance Offset Period - The adaptive rebalance constraint is a gatekeeping condition for rebalances, which states that the expected return associated with a rebalance needs to be recouped over a given period. It is worth noting that this is a self-learning mechanism with a variable cost offset period that adapts to different market environments based on the observed yield volatility.

Lastly, the Strategy has a multitude of additional immutable constraints, such as the total slippage (i.e. total difference in the value of the in and out LP tokens), as well as lookback tests that validate an increase in net asset value (NAV) over time. Once fully validated by the Strategy, the rebalance proposal is executed.

To understand the general architecture and functioning of the system, it helps to consider a simplified flow of assets within the system:

1. Deposit – User deposits assets into Autopool. After this action, the Autopool has idle assets and the user gets the respective receipt token in return;

2. Rebalance – After a certain threshold of assets are deposited into the Autopool the Strategy backing it starts to accept proposals from the Solver. Once a proposal satisfies the constraints imposed by the Strategy, the assets in the Autopool are sent to the Solver which will then return LP tokens to the Autopool;

3. Auto-compounding – On a periodic basis, rewards from destinations are claimed and collected via a keeper process. These tokens are then converted into the Autopool base asset;

4. Debt Reporting – Each Autopool goes through a debt reporting where the system re-values the LP tokens held by that Autopool. During that process, any available auto-compounded rewards are claimed and come into the Autopool as idle funds;

5. Restart – With sufficient idle assets in the Autopool, another rebalance can occur.

In other words, users deposit assets into Autopools, the stats contracts provide on-chain information about the market, and the solver proposes rebalances to the strategy. To be accepted, the proposed rebalance must meet the strategy's constraints. The above outline focused on idle → LP rebalances but the rebalance step can occur for LP → LP rebalances as well. So long as the proposal results in a higher potential return (and satisfies other constraints) it can be executed.

Enter the Autopool

Users gain access to Autopilot by depositing into an Autopool, which use the highly composable ERC-4626 standard and can be configured with a set of destinations (pools/DEXs and lending markets for some Autopools) to which assets may be deployed to. Assets deposited into an Autopool are not subject to any lock ups or cooldown periods, meaning that users can withdraw their funds at any time. The architecture was designed to be modular, allowing for plug-and-play integration of new assets and destinations. As a result, the system can adapt to the market swiftly by launching Autopools which include e.g. a new pairings, or cater to specific ecosystems.

Composable Receipt Tokens: LATs

LPs depositing into an Autopool receive reward bearing receipt tokens, or Liquid Auto Tokens (LATs), which are composable across DeFi. Examples of common DeFi integrations include utilizing LATs as collateral, integrating LATs into yield marketplaces to trade liquidity rates, and leverage LATs.

Introduction

The sTOKE system is Tokemak's staking mechanism that enables active ecosystem participation. By staking TOKE, users receive credits that they can allocate to different Autopools. This allocation provides access to both reward streams and, when available, additional incentives specific to each Autopool.

Staking Mechanism

Staking TOKE for sTOKE

Users can stake TOKE tokens for durations between 4 and 16 weeks, during which their TOKE converts to sTOKE and generates credits that can be allocated to Autopools. The staking duration directly affects the boost multiplier - longer staking periods result in higher credit generation. This system balances rewards for protocol commitment while accommodating various user preferences.

Autopool Reward Streaming

Allocating Credits to Autopools

Default Allocation

Once your TOKE is staked, your credits will by default be evenly allocated to the available Autopools. The default allocation will be applied to any newly staked TOKE.

Personalized Allocation

You have complete flexibility in how you want to allocate your available credits across Autopools:

• You can allocate to multiple Autopools simultaneously.

• Allocation can be modified at any time without unstaking:

  • Adjust your allocations across Autopools at any time

  • Monitor and optimize your credit allocation based on performance

Your allocation of credits can be adjusted at any time, but reward calculations for the updated allocation take effect following the next snapshot. Note: when allocations are changed pre-snapshot, users will continue to earn rewards based on their previous allocation until the new snapshot goes live.

The distribution of credits is snapshotted weekly, with each snapshot determining reward distribution for the following week. This means rewards are backward-looking and are earned based on the voting snapshot at the beginning of each week.

For users looking to allocate voting credits to Autopools on different chains, TOKE is required to be present on the specific chain. A seamless bridging solution is available to transfer your TOKE across networks, located in the Staking (or sTOKE) section of the UI.

Read more about Staking TOKE in the App Guide here.

Rewards

sTOKE holders who allocate their credits to Autopools earn rewards from multiple sources:

• Rewards generated by the specific Autopools

• Additional benefits from protocol-owned asset deployment

These are used to purchase TOKE to be distributed to the TOKE stakers.

The reward structure is designed to align user incentives with the protocol's long-term success, encouraging active participation in the ecosystem's growth.

Learn how to claim your rewards here.

Ecosystem Specific Autopools

Autopools are in essence customizable networks of automated liquidity, tokenized and made composable by their respective LAT. This allows for a new way to combine utility with distribution. For instance, an Autopool tailored for the XYZ DEX, featuring a custom selection of pools (e.g., correlated ETH pairs), which then distributes branded LAT tokens (e.g., xyzETH) to LPs. Once set up, the user experience is simple: provide ETH, receive xyzETH, and the underlying liquidity remains optimally deployed, while remaining within the DEX ecosystem. This approach creates passive yield opportunities for users, which retain all underlying liquidity within a single ecosystem, thus promoting sticky liquidity and broadening the addressable market.

The Future of Autopools

A natural next step is to enable the permissionless creation of Autopools. This feature will allow users to express individual risk preferences and allows different participants, such as risk managers, to contribute specialized skills. The architecture of Autopilot also allows to develop solutions for other problem sets requiring optimization, such as e.g. point systems.

This guide contains all the information necessary to interact with all aspects of the Tokemak protocol.

Autopools

Learn how to provide liquidity with Autopools and take advantage of Autopilot optimization.

Read more

Staking TOKE

This section provides instructions on how to stake TOKE as sTOKE and earn rewards.

Read more

TOKE/ETH LP

This section will provide information on liquidity provision to TOKE/ETH liquidity pools on Curve and SushiSwap.

Read more

A list of available Autopools can be found in the "Autopools" section on tokemak.xyz. Select an Autopool in order to see detailed information and data associated with the specific Autopool, such as historical performance, underlying pools and assets etc. From here you are also able to interact with the pool:

Deposit and Withdraw

Learn how to deposit into the Autopool and earnmore pool shares.

Read more

Stake and Unstake

Stake your LAT receipt token for additional incentives.

Read more

Claim Incentives

Claim TOKE incentives and lock them for more autoETH pool shares.

Read more

View Positions

Use the dashboard to track your portfolio and manage your Autopool positions and TOKE locks.

Read more

Depositing into an Autopool

Browse to the "Autopools" section to select an Autopool and view additional details by clicking on it. Once you are ready, use the dialog box to deposit into the Autopool:

1. If your wallet is not connected to tokemak.xyz, or you need to connect to a different network for this Autopool, the main button of the dialog will prompt you to do so by clicking it.

1. Select the asset and amount you wish to deposit. You can deposit any asset, which will subsequently be swapped into the base asset of the Autopool (e.g. , ETH). You can select a specific slippage tolerance for the swap and deposit by clicking the cog icon.

2. Setting the "Auto-Stake" toggle to "on" will add the transactions to stake the LAT receipt token to the deposit transaction. If left in the "off" position, you will receive the receipt tokens into your wallet. These can always be staked at a later point.

3. Click "Deposit" in order to start the deposit process. Note that the first deposit of an asset will require an additional approval transaction.

Withdrawing from the Autopool

Autopool deposits are not subject to lock-ups or cool-down periods, meaning you can withdraw your assets at any time. You can start the process by either clicking "Manage" in the Autopools of the "Portfolio" section, or by selecting the Autopool from the list in the "Autopools" section.

1. Select the "Withdraw" tab of the dialog.

2. Select the amount you wish to to withdraw and the asset you want to receive. You can withdraw as any asset; the system will make the swap for you. You can select a specific slippage tolerance for the withdrawal and swap by clicking the cog icon.

3. Click "Withdraw" to start the withdrawal process.

Staking Autopool LATs

In case you have unstaked LATs that you wish to stake, navigate to the respective Autopool. If you are unsure about the Autopool or the status of your positions, you can browse your "Portfolio" section and check the Staking Status:

• Staked: All the LATs associated with this Autopool position have been staked.

• Partially Staked: LATs associated with this positon have partially been staked.

• Unstaked: No LATs associated with this Autopool position have been staked.

Click on "Manage" and you will be taken to the Autopool where you can use the dialog to stake your LATs.

1. Select the "Stake" tab in the dialog.

2. Enter the amount you wish to stake and click "Stake." Note that the first staking transaction will require an additional approval transaction.

3. Confirm the transaction(s) in your wallet.

Unstaking Autopool LATs?

In order to withdraw from the Autopool or otherwise utilize your LAT tokens, you will need to unstake them. Either navigate to the Autopool via the 'Autopools' section or select it from your Portfolio view.

1. Select the "Unstake" tab in the dialog.

2. Enter the amount you wish to unstake and click "Unstake."

3. Confirm the transaction(s) in your wallet.

What Are Incentives and How Are They Calculated?

Autopool LPs who stake their LAT receipt tokens currently receive additional TOKE rewards, allocated every two weeks. A defined amount of TOKE is distributed pro rata among LPs, based on the total percentage of the total staked LAT they represent. The incentives split across the three Autopools currently open for deposits as follows:

• 50% to autoETH

• 30% to balETH

• 20% to autoLRT

The amount of rewards and the split across the different pools is subject to change.

How Do I Claim and Manage My Incentives?

Navigate to your Portfolio and locate the "Autopools" section. Under "Rewards," click "Claim" to initiate the claim process. During this process, you can choose either to compound your TOKE incentives to earn autoETH or to claim liquid TOKE directly to your wallet.

Compound Claim

Compound Claim will lock your claimed TOKE for four weeks, earning additional autoETH receipt tokens. These tokens are the same as the LP receipt tokens you receive for depositing into the autoETH Autopool. You can learn more about TOKE locking here.

Basic Claim

Basic Claim allows you to claim liquid TOKE directly to your wallet. Liquid TOKE can, for example, be used to provide liquidity to the TOKE/ETH pools on SushiSwap or Curve. Learn more about TOKE/ETH LP here.

Where can I see my Autopool Positions?

All your positions can be found in the "Portfolio" section.

Total Autopools Balance

This is your total balance across all your Autopool positions.

Autopool Allocations

Here you can see the allocation to DEXs and assets across all Autopools you have deposited into.

Autopools

Here you can track and manage your individual positions.

• Total Autopools Balance: Total balance across all Autopools.

• Total Returns: Total cumulative return across all Autopools.

• Average Daily Returns: Average return across all Autopools. High daily Composite Return Metric, 7-day moving average, 30-day moving average depending on Autopool age.

• Average APR: Average APR across all Autopools. High daily Composite Return Metric, 7-day moving average, 30-day moving average depending on Autopool age.

• Rewards: Current balance of additional earned rewards.

• TVL: Total Value Locked of the Autopool.

• Deposited: Cumulative deposits made into the Autopool.

• Returns: Total cumulative return earned in the Autopool.

• APR: APR of the Autopool. High daily Composite Return Metric, 7-day moving average, 30-day moving average depending on Autopool age.

Staking Statuses

You can see your stake status under the portfolio on the autopool section.

• Staked. Your amount of LAT's stake is the same as the total amount of your position.

• Partially Staked. Your amount of LAT's stake is no the total amount of your position.

• Unstaked. You do not have staked tokens.

How Do I Manage My Autopool Positions?

In your Portfolio, click on the 'Manage' button to go to the specific Autopool page, where you can manage your Autopool position:

• Deposit / Withdrawal

• Stake / Unstake

Staking Fundamentals

Staking TOKE (sTOKE)

• Choose a staking duration of 1-4 months (4 to 16 weeks)

• Credits are generated based on amount of TOKE staked as well as lock duration (boost multiplier)

• Longer staking durations provide more credits through higher boost multipliers

• Adding TOKE to existing stakes restarts the staking period for your entire balance

• Stakes auto-renew for the same duration unless unstaking is initiated

• Unstaking must be initiated during the final week of your staking period

• If unstaking has been initiated, TOKE becomes available for withdrawal once the period ends

• Initiating the unstaking does not affect the rewards earned during the final week of the staking period.

Autopool Streams

• Allocate credits to activate Autopool Streams and earn rewards

• Allocate to multiple Autopools simultaneously

• Adjust allocations at any time without unstaking - this doesn't affect your staking period

• Make sure you are staking on the correct chain for your target Autopool (e.g., TOKE on Base is required to allocate credits to the baseETH Autopool)

Stake TOKE and Allocate Credits

Learn how to stake TOKE and allocating your credits.

Read more

Unstake and Withdraw

Learn how to unstake and withdrawing your TOKE

Read more

Claim

Learn how to claim your revenue streams TOKE rewards.

Read more

View Positions

You can see your staking positions on the Portfolio or under each of the Revenue Markets.

Read more

In order to allocate credits and activate Reward Streams, you need to stake TOKE as sTOKE using the Staking Panel:

Staking TOKE as sTOKE

1. Visit the Staking page

2. Select a Network/chain (eg. Ethereum)

3. Click Manage on the Staking Lateral Panel

4. Enter the amount of TOKE you wish to stake

5. Choose a staking interval

6. Review your boost multiplier based on the selected duration

7. Proceed with the staking transaction

When adding more TOKE to an existing stake, the entire staked balance will restart its lock period with the newly selected duration. This means your total staked amount (existing + new) will begin a fresh lock period. The minimum staking period for the added TOKE is the currently selected staking duration.

Allocating Your Credits

1. Visit the Staking page

2. Select a Network (e.g. Ethereum)

3. Click "Manage" on the Allocation Panel

4. Use the plus symbol (+) to add or the minus symbol (-) to change the allocation, or you can enter allocation percentages that total 100%

5. When allocation ready, click “Save"

You can change your allocation of credits at any time – the changes go into effect with the next snapshot. Snapshots are taken once a week.

Unstake and Withdraw

To withdraw your TOKE, you need to initiate the unstaking during the unstaking window (final week of your staking period). Once your staking period ends, your TOKE then becomes available for withdrawal.

Submit Withdrawal Request

1. Visit the Staking page during the final week of your staking period

   1. Open the Staking Panel and select the Unstake tab

   2. Enter the amount of sTOKE you wish to unstake

   3. You continue to earn rewards while the unstaking is in process

2. Complete Withdrawal

   1. Once your staking period ends, your TOKE becomes available

   2. Return to the Staking Panel and select the Withdraw tab

   3. Claim your available TOKE

Your staked TOKE (sTOKE) positions can be viewed in your dashboard in the Portfolio tab of the app.

From there, you can manage your sTOKE credit allocations (per network) by clicking on the manage button.

Rewards are claimable once a week from the Manage button within the Portfolio tab (in the Staking section).

Note: the first batch of staked TOKE rewards will become available Dec. 26th, 2024 - from there, rewards will be claimable weekly.

Providing liquidity to a TOKE/ETH liquidity pool means depositing both TOKE and ETH into the pool to facilitate trading between them on a decentralized exchange (DEX). In return, you earn a share of the trading fees and may receive additional incentives. Liquidity pools are available on SushiSwap and Curve v2. While liquidity is provided outside of tokemak.xyz, you can find links to the pools and basic info on these LP positions under the TOKE/ETH LP tab.e

Claim autoETH Rewards

To claim your autoETH, you can go to the "Staking" section.

I cannot connect to the platform

• Network Selection:

  • Ensure you select the correct network (Ethereum Mainnet). You can usually switch networks in the settings option of your wallet provider.

• Using Ledger (Natively or with MetaMask):

  • Unlock your Ledger device and select the Ethereum app.

  • Make sure the 'Contract Data' setting is enabled in the Ethereum app settings.

• Using Coinbase:

  • Use the scan QR option to connect.

  • To access directly from the Coinbase wallet, open the browser within the app and go to app.aave.com.

• Using WalletConnect:

  • Use the scan QR code option to connect.

• Using Rabby:

  • Use the scan QR code option to connect.

Enable contract data on Ledger

Make sure to select the Ethereum app and enable contract data. To enable contract data:

• Connect and unlock your Ledger device.

• Open the Ethereum application.

• Press the right button to navigate to Settings.

• Then press both buttons to validate.

• In the Contract data settings, press both buttons to allow contract data in transactions.

• The device displays Allowed.

I cannot send transactions

Make sure you have enough ETH in your wallet to interact with the platform. You must have ETH in your wallet for the transaction costs-- without it you won't be able to interact. Depending on the network status, the cost of the transactions may vary. At least 0.05 ETH may be required to interact properly.

I do not find my position

If you used the Tokemak protocol in the past you will not find your positions on the current V2, you will need to visit he Tokemak V1 protocol. You can find an interface to interact with V1 version of the Tokemak protocol here.

The site does not load

The following steps may solve your problems:

• If you are using Brave browser, switch to another browser to see if the issues are coming from the browser. If it is related to Brave browser some helpful actions are:

  • Clearing cache data and cookies for the site

  • Hard refresh with control + F5 (or cmd + r)

  • Disable brave wallet (or the wallet not being used as default, for example metamask, dapper, etc.)or other extensions that might be interfering with proper connection with the wallet

  • If the site still won't load after taking the steps above, you will have to use the platform in another browser.

• Make sure your internet connection is working and stable

• Restart the browser and try to connect again

• Try to hard refresh the site with control + F5

• Check if there are any updates for your browser or wallet provider. If so, update it to the latest version.

My transaction is stuck pending confirmation

In this situation make sure to not keep sending transactions, as every new transaction will be stuck pending the oldest transaction to be confirmed. You can get rid of the stuck transaction by speeding it up or cancelling it. Depending on the wallet you are using, you may have that option natively. For example, metamask or trust wallet have both the options to cancel or speed up transactions.

At its simplest, this contract system is a set of a sub-systems that all revolve around, and reference each other through, a system registry. There are only a handful of user interactions that are mostly surfaced through a multicall router. Additionally, we have a few permissioned keeper-like processes that handle other parts of the system. Here we’ll run through general functionality and then dive deeper into each contract/system

The purpose of Autopilot is to continuously rebalance Autopool assets into the Destinations with the best return/risk profile. Earnings are auto-compounded for the users, reinvested into the Autopool, and then rebalanced out to begin earning. We’ll give an overview of how things work by looking at how the assets flow through the system.

Step 1: Users deposit assets

Users must deposit assets into an Autopool for there to be assets to deploy. If this is a contract-to-contract interaction, this can happen directly in an Autopool. If this is a user interaction, through our UI, this will happen through our Router. The end-result is that the Autopool has idle assets sitting in it and the external party has Autopool shares in their wallet.

Step 2: Rebalance

Once a sufficient number of assets are deposited, the Autopool, or more importantly the Strategy backing the Autopool, will begin to accept rebalance proposals from our Solver. When a proposal satisfies the constraints of the Strategy:

• The Autopools underlying asset, WETH in this case, will be sent to the Solver specified in the proposal

• The Solver will take those underlying assets and turn them into the LP tokens for the Destination specified in the proposal. This can involve swaps, liquidity provisioning, or w/e other means the Solver has to procure the LP tokens.

• The Solver will send those LP tokens back to the Autopool

• Once validating everything looks good with the Strategy, the Autopool deposit those LP tokens into the corresponding DestinationVault for that Destination.

• The DestinationVault will do what it needs to with the LP tokens depending on the type of Destination it is. If its just a pool Destination then the LP tokens can stay there. If its a Curve+Convex Destination, then the DestinationVault will stake the tokens into Convex.

• The DestinationVault mints the Autopool 1:1 shares of itself to represent the deposit

• Each DestinationVault has its own Rewarder where its shares are virtually staked on the Autopools behalf.

At the end of the rebalance, the Autopool has less of its base asset, and some number of DestinationVault shares representing a claim on some LP tokens.

Step 3: Auto-Compounding

On a periodic basis, rewards from the Destinations will claimed and collected via a permissioned keeper process. This is most-likely, though not restricted to, incentive tokens through say Convex or Aura, for example.

These tokens all go to a central LiquidationRow contract where they can be liquidated to the base asset in bulk at a later time.

When that liquidation occurs, assets are sent back proportionately to the DestinationVaults that contributed to their balance. These assets are held in the DestinationVaults Rewarder where the Autopools earn them over a short period of time.

Step 4: Debt Reporting

At least every 24 hours, each Autopool goes through a debt reporting where we re-value the LP tokens held by that Autopool. During that process, any available auto-compounded rewards are claimed and come into the Autopool as idle funds.

Step 5: Rinse and Repeat

With sufficient idle assets in the Autopool, another rebalance can occur. There is no requirement that funds earned from a Destination must go back to that Destination.

The above outline focused on idle → LP rebalances but the rebalance step can occur for LP → LP rebalances as well. So long as the proposal results in a higher potential return (and satisfies other constraints) it can be executed.

The contracts were designed with a couple concepts in mind:

• It is possible that Tokemak could run multiple, separate, instances of this system on the same chain and the majority of contracts would not be safe to share between the two.

• Misconfigurations are a potential source of bugs and this is a highly configurable system. Any validations that can be performed during registration and setup, should.

To assist in enforcing these points, the system revolves around a SystemRegistry contract (src/SystemRegistry.sol), and most contracts inherit from a SystemComponent (src/SystemComponent.sol) contract that requires a reference to a SystemRegistry. These allow us to tie the various contracts together and provide a lookup point for the various contracts to talk to one another.

With the exception of the SystemRegistry contract which uses an “onlyOwner” setup for security (which will be granted to a multisig and eventually a Governor contract), all other contracts follow a RBAC security system.

AccessController

src/security/AccessController.sol

This is largely an OZ AccessControlEnumerable contract with the setup functions exposed, however, instead of each contract managing their own permissions, they all reference this one through the SecurityBase contract.

Given the sensitive nature of this contract, it is one of the contracts that can never be changed or upgraded in the system.

SystemSecurity

src/security/SystemSecurity.sol

This contract allows us to coordinate operations across all Autopools in the system. This coordination falls into two areas:

1. Pausing

2. NAV operation coordination

Pausing

Via the usage of this contract, we are able to pause all Autopool operations in the system. Autopools can still be paused locally or one-by-one, but this gives us a way pause all of them in one go.

NAV Operation Coordination

Operations in an Autopool can be broken down into ones that can see nav/share go down, and ones that can’t. To ensure proper calculations, operations that SHOULD NOT see a nav/share decrease can never be executed within the context of those that can.

Operations that can see a decrease in nav/share:

• Debt reporting - updateDebtReporting()

• Rebalances - flashRebalance()

Operations that shouldn’t:

• User balance management - deposit() / mint() / redeem() / withdraw()

This restrictions applies cross-Autopool as well. An updateDebtReporting() call in one Autopool for example, blocks deposit() in all Autopools during its execution.

Pausable

src/security/Pausable.sol

A near duplicate of the OZ contract by the same name. However, this one incorporates our SystemSecurity contract to support our global-pause behavior. It is used only by our Autopools.

The Stats System is responsible for making all required signals (e.g., staking yield, fee yield, incentive yield, etc) available on-chain. These signals are read by the Strategy to determine if a rebalance is in the best interest of its Autopool. A Calculator is responsible for storing, augmenting, and cleaning data required to provide one of those signals. Let’s take an example Destination and see how it’s stats are built:

Curve osETH/rETH + Convex Staking

Stat calculators depend on each other to build the full picture of a Destination, with only the top-most calculator being referenced directly by the DestinationVault. In this case, the top-most calculator is the ConvexCalculator. This calculator is an example of an Incentive calculator. LP tokens staked into Convex automatically earn CRV and CVX. This pool is also configured with SWISE and RPL tokens as extra rewards. And so, some annualized amount of CRV, CVX, SWISE, and RPL will be reported to the Strategy where it will calculate what the yield of those tokens are.

As a dependency, the ConvexCalculator takes a reference to a calculator responsible for providing stats about the DEX pool itself, a CurveV1PoolNoRebasingStatsCalculator (V1 calculators work for both Stableswap and Cryptoswap pools). This calculator provides the trading fee yield for the pool.

The last piece(s) are the stats about the LST tokens themselves, osETH and rETH. These calculators, OsethLSTCalculator and RethLSTCalculator, were provided to the CurveV1PoolNoRebasingStatsCalculator as dependencies when it was created. These calculators provide stats such as the base yield and price-to-book value.

With all of these calculators each providing their own data to the overall picture, a Strategy can get an accurate reading of a Destinations return.

Types of Calculators

• Incentive - Responsible for tracking the return of the incentives available when staking in Convex/Aura/Maverick/etc.

• DEX - Responsible for tracking the trading fee yield of a given DEX pool

• LST - Responsible for tracking the base yield and backing of an LST

Keeping Data Up-to-Date

A keeper network is used to periodically snapshot new data. Each calculator type defines the frequency and conditions under which a snapshot should be taken. Importantly, each calculator only stores the required information to provide its stats. If it needs to provide stats from another calculator, those are read at the time of the request to ensure that data is consistent.

Architecture

The purpose of Autopilot is to continuously rebalance Autopool assets into the destinations with the best return/risk profile. However, the best risk/return profile is somewhat subjective, as such, each Autopool has an assigned Strategy that is responsible for determining if a given rebalance (e.g., swap Pool A LP units for Pool B LP units) meets its requirements. For the LST vaults, there are a number of criteria that are considered in deciding if a rebalance is favorable, including:

• Total Slippage - the absolute difference in the value of the in and out LP tokens. Priced using safe price oracles (previously audited).

• Increase in expected return metric between the assets being swapped. Expected return is composed of (1) LST base yield, (2) DEX fee return, (3) incentive APR. Expected return metric is calculated as follows:

Composite Return Metric = W_Base * Base Return + W_Fee * Fee Return 
										+ W_Incentive * Incentive Return + W_Price * Price Return
										

Where,
			0 <= W_Base, W_Fee, W_Incentive, W_Price <= 1.0

Default Values
			W_Base = 1.0
			W_Fee = 1.0
			W_Incentive = 1.0                            
			W_Price (Discount: Price Return > 0) (Entering destination) = 0.75
			W_Price (Discount: Price Return > 0) (Exiting destination) = 0.0  
			W_Price (Premium: Price Return < 0) = 1.0
		

• Swap Loss Offset Period - how long it takes for the incremental expected return to offset the immediate loss (swap cost). The Autopool will utilize an adaptive offset period that determines how strict or loose the offset period is. The LMP rebalance transactions (a.k.a pool/destination swaps) will occur only if the following condition is met:

where,

• is the annualized gain in ETH expected to be earned as a result of this rebalance transaction.

and

• are the new and old composite APRs for the destination involved in the swap/rebalance transaction.

• is defined as period in days allowed for this rebalance transaction to recoup or recover the slippage loss. Default value is 28. At the minimum value of 7 days, approximately 525 bps of incremental APR will be needed to offset a swap cost of 10 bps. Similarly, a value of 60 days allows ~ 60 bps of incremental APR at 10 bps of swap cost.

• is the loss in value in ETH units as a result of this transaction primarily driven by slippage, token swap fees, gas used to execute the rebalance operations.

Additional Rebalance Gatekeeping Features

a. Adaptive Swap Loss Offset Period

Swap loss offset period determines how loose or strict the constraint to allowing a pool swap is. A large value relaxes the constraint and will allow many swap transactions to go through. In comparison, a value such as 7 days will require a large hurdle to be met before a destination pool swap transaction is allowed.

If the value of swap loss offset period is fixed at a high value, the Autopool system could exhibit increased turnover and experience increased swapping cost. The following describes the mechanism to adapt the swap loss offset period and tighten or loosen the pool swapping constraint should conditions warrant.

At every pool swap-out transaction, we determine the time elapsed since the last time we added to this pool. A pool swap-out transaction is a non trivial swap out i.e. swaps from WETH reserves (base asset of the Autopool) are not included. Let this time be $t$. Next, we define a constraint violation event as a pool swap out transaction where $t$ ≤ swap_cost_offset_period.

After 5 or greater constraint violation swaps within 10 swaps, the swap loss offset period is decreased by x (tighten step size) days until it reaches the minimum allowed value of 7.

After no swaps transactions occur for the period of y (constraint relax period) days, the swap loss offset period is increased by z (relax step size) day until it reaches the maximum allowed value of 60 days.

b. 30-60-90 NAV Test (LookBack Test)

This is a test conducted on the NAV (per unit or token) of the Autopool. Swapping costs should be carefully monitored to provide positive value to the Autopool. The 30 followed by 60, 90 day test is meant to allow enough time for the Autopool to earn back the swap costs. Should a lot of swaps have recently occurred (i.e. frequent swaps is not a feature of the system but just happen to occur in clusters some times), looking back in the past far enough should result a positive NAV delta i.e. NAV per token should have increased over time. A variant of this test is a 30-60 NAV test.

The following steps are conducted in this test.

1. Aligned with some time reference (i.e. 30th of every month), record the NAV of the Autopool.

   1. Calculate the delta with the NAV recorded 30 days in the past.

   2. Calculate the delta with the NAV recorded 60 days in the past

   3. Repeat with NAV recorded 90 days in the past.

2. If all of the three delta values are negative, pause pool swaps until

   1. the NAV reaches the highest NAV recorded (of the 3 values - 30, 60, 90 days in the past)

   2. 90 days have lapsed since the test was conducted

3. After the pause, set the value of $swap\_cost\_offset\_period$ at the minimum value $swap\_cost\_offset\period{min}$

References:

1. verifyRebalance Interface

2. verifyRebalance is called here by Autopool on rebalance to ensure it is a favorable rebalance.

Call Flow to the Strategy

Rebalance

During Debt Reporting

At least every 24 hours, each Destination configured on the Autopool has its cached price information updated. This has the potential to lower the nav/share of the Autopool right at that moment. When the Autopool sees a profit during debt reporting, that profit is locked up for a period time, say 24 hours. This means any nav/share increase unlocks over that same time period. At the end of a call to debt reporting, AutopoolStrategy.navUpdate() is called.

The valuation of tokens is core to the operation of this system. All token valuations are performed through the RootPriceOracle and different approaches for pricing are used depending on the type of token (native or LP) and the intended usage of the price:

Types of Prices

“Safe” Prices

These are prices that are calculated/queried from off-chain sources. This includes sources such as Chainlink, Redstone, and Tellor. These are exposed through three calls on the RootPriceOracle: getPriceInEth(), getPriceInQuote(), and one of the return values of getRangePriceLP()

These are mainly used for operations where we aren’t executing with the price at that moment. This can include pricing debt in the Autopools, calculating statistics, etc.

Spot Prices

These are prices that are calculated/queried from primarily on-chain sources. These are always in reference to a specific pool that want to know the spot price of the tokens from. To calculate these values, a small amount of token is trial swapped through a pool to determine its execution price and then any fees are factored back in.

For requests that don’t have the requested quote token as one of the tokens in the pools, “safe” prices are used to complete the steps in the conversion.

These prices are exposed through getSpotPriceInEth() and one of the return values of getRangePriceLP() .

Spot prices are checked against some tolerance when used within the system to ensure they are safe to use. The spot price of the token must be within some bps of the safe price. These are used during rebalance execution to measure impact on pools we are operating against as well as one of the ends of the getRangePriceLP() call.

Floor & Ceiling LP Prices

These prices are exclusively used in the Autopools when debt reporting has gone stale. While this should never actually be an occurrence, should a pool enter this state, debt that is stale will be re-valued using this method of pricing. This will take the worst price (depending on the operation that could be the highest or the lowest) between the safe and spot prices of all the tokens that constitute the LP token, and value all the reserves that back that LP back at that single price. This is to ensure that any potential manipulation that could be occurring cannot negatively impact the Autopool.

Architecture

The system-at-large will only ever interact with the RootPriceOracle. All specific implementations related to the method of pricing an asset are hidden behind here:

The majority of functions on the RootPriceOracle are not view functions even though they are performing “view” type operations. This is due to methods used for pricing. Since we use swaps to calculate prices, and we can’t count on every DEX to have a view operation to perform this, we have to keep the interface as payable.

Safe Price Call Flow

The following is an example call flow for resolving a complex price. We will assume that the requested price is for the $ABC token in ETH. $ABC token has an $ABC/USD feed through Redstone:

LP Price Call Flow

The following is an example call flow for resolving the safe and spot price of an LP token. We will assume this is a Curve pool:

When there is a withdraw from an Autopool, a couple things can happen. If there are enough assets to cover the withdrawal sitting idle in the Autopool, then all of the assets come from there. However, if there is not, then we must pull from the market. Just retrieving the LP positions doesn’t help the user, we must provide them back their funds in the base asset of the Autopool. This is where the SwapRouter comes in.

The SwapRouter contains routes for all the tokens that make up the constituents of any LP token we support, back to the base asset of the Autopool. This is a list that will be kept up to date by the team to ensure users receive the best execution when exiting the pools.

Example Routes

The routes can be simple or complex. We can use the same pools we are in as Destinations or completely different pools should there be better execution.

Simple Example for TokenA → TokenD:

• Swap TokenA → TokenD in Balancer TokenA/TokenD Pool

Complex Example for TokenA → TokenD

• Swap TokenA → TokenB in Curve TokenA/TokenB Pool

• Swap TokenB → TokenC in Uni V3 TokenB/TokenC Pool

• Swap TokenC → TokenD in Balancer TokenC/TokenD Pool

Swap Adapters

The chaining of operations all happen at the SwapRouter level. The only thing an adapter needs to be able to do is to swap between two tokens and validate that a given configuration is supported in the specified pool. They are only callable by the Currently we support:

• Balancer Pools

• Curve StableSwap Pools

• Curve CryptoSwap Pools

• UniV3 Pools

Getting information generically about a given Curve pool can be a tricky task given the slight variations between their different types of pools. This is a task we need to perform in many different areas of the app and so this contract was built to assist in that.

Luckily, Curve provides a meta registry themselves that can perform this lookup. However, at the time of writing this, there is a type of pool that is not supported by their registry and that is their Stable-NG type pools. To get around this, the CurveResolver has a fallback method where it attempts to figure out the information based on the successful execution of various functions.

This approach currently works for the types of pools we are interested in supporting. Should new types of pools be introduced in the future, the approaches outlined may need to be re-evaluated.

This contract is an interface to be able push data or events to other chains. It is exposed to the rest of the system as a generic interface but currently relies entirely on Chainlinks CCIP. It is designed to support a couple core features:

• Fan-out messaging. Given a sender and message type, send the provided data to one or many destination chains

• Retries. The last message of a given sender+type can be re-sent to a destination. This serves a few purposes

  • Should CCIP ever be down and messages unable to be sent, we should be able to get the data off that we need when it comes back online

  • Our contract could be out of funds when the send is attempted. We need processes that send the message to continue without reverting, but we want to be able to send that message eventually

  • Seeding information when standing up the destination chain. Some messages have large delays between them being sent. This can make standing up dependent contracts on the destination difficult and time consuming. Being able to re-send the last message ensures we have the information we need as soon as we can.

Usage

Current usage is restricted to just the LST calculators through the LSTCalculatorBase. The stats related to LSTs are specific to their native chain.

accToke gives users the ability to stake their TOKE and earn rewards in WETH. This contract is largely based on https://docs.oeth.com/governance/ogv-staking.

Differences to call out

• Rewards can accrue in the contract for a user and don’t actual claiming

• Rewards are queued instead of being on an emissions schedule. Rewards will not be added in large amounts to ensure there can’t being meaningful gaming of, and spikes in, accRewardPerShaer

Interactions

Generally accToke sits on the outside of the platform. It doesn’t have a integration into the Autopilot router. The exception to this is within the AutopoolMainRewarder. We optionally have the ability to configure that if TOKE is the token being rewarded, it can be staked for a period of time into AccToke upon claim.

The Autopilot Router is the main entry for users in the system. This is a multicall-type contract where the exposed functions are designed to be chained together to perform various operations. This can include but is not limited to:

• Depositing into an Autopool and staking the tokens into a rewarder:

  • deposit(autoPool, router, amount, min)

  • approve(autoPool, rewarder, max)

  • stakeVaultToken(autoPool, max)

• Migrating from one Autopool to another

  • withdrawVaultToken(autoPool, rewarder, amount, true)

  • selfPermit(autoPool, amount,….)

  • redeem(autoPool, router, amount, min)

  • approve(weth, autoPool2, max)

  • depositBalance(autoPool2, router, min)

  • stakeVaultToken(autoPool2, max)

The router also has the ability to swap tokens utilizing one of the AsyncSwappers configured in our system. Whether or not a swap can be utilized depends on the type of operation being performed. If we are able to know the exact number of input tokens upfront then it can be performed. Otherwise, we cannot.

Router should hold no balance

Given the flexibility of the Router it is possible to leave funds in the contract should the order of operations be incorrect. Those funds can then be withdrawn by anyone. This is expected. The Router will be integrated into our front-end and only specific flows will be supported ensuring that all token balances are sent back to the user when appropriate.

Liquidation in Autopilot refers to the process of auto-compounding rewards from our various asset deployments. For efficiency reasons, LiquidationRow attempts to batch as much of the claiming and swapping process as possible. This is broken up into two processes:

Claiming

Each DestinationVault is required to implement a collectRewards() function which will claim and transfer any reward tokens back to the liquidator. The exact details of how a claim happen are not of a concern to the liquidator, it is only worried about being told how much of some token it has received. Call flow:

Liquidation

Both the process of claiming and liquidation can be gas intensive given how many DestinationVaults and reward tokens we may need to process in the system. Both of these processes are designed to be able to work on a subset of either the DestinationVaults or the tokens to combat this. The goal is batch as match of the work as possible for efficiency, though. So, during liquidation the balance of tokens across many DestinationVaults are compiled, swapped as a single operation, and the proceeds distributed back to the DestinationVaults according to the share they contributed. Call flow:

Fees

This process is one that is permissioned and run by Tokemak. To support the gas and fees required to perform this a fee can optionally be enabled against any liquidated funds.

Destination Vaults act as our proxy to the greater DeFi ecosystem. Their goal is to provide a common interface for us to deposit/withdraw LP tokens and earn yield. Each type of Destination has its own unique concrete DestinationVault implementation. Currently we support:

• Balancer Pools

• Balancer Pools with LP staked into Aura

• Curve Pools with LP staked into Convex

• Maverick Boosted Positions

Core Functionality

Depositing and Withdrawing LP Tokens

Autopool’s will be the main actors interacting with a Destination Vault. Primarily this will come in the form of deposit and withdrawing LP tokens. The actions taken after a deposit aren’t much of a concern to the Autopool and can vary depending on the specific type of Destination. If this is a just a “Balancer Pool” type of Destination then the LP tokens will stay in the Destination Vault. If this is a Destination that say stakes into Aura, then that operation will happen upon deposit.

Withdrawing can come in two forms: as the LP units, or as the base asset. The LP unit can be withdrawn as part of a rebalance. During a user withdraw where we have to pull from the market, the LP units burned and the resulting tokens will be swapped into the base asset. All base assets in the system will be WETH at this time. Additional validations will be required to support additional base assets.

Collecting Rewards

Depending on the type of Destination Vault, rewards may be due to us for holding or staking the LP units. The implementation of this can be hard coded to return nothing, or to interact with an external protocol. Resulting claimed tokens are sent to the caller of collectRewards().

Marketplace Rewards

These functions are intentionally left empty at this time.

1271 Support

DestinationVaults have very simple 1271 support. The exact usage of this is unknown at this time. However, much of the current and coming narrative around points and other various off-chain crediting systems present a unique problem for us when it comes to claiming these rewards. It is our hope that protocols will support this interface when it comes to claiming or at least we can prove ownership of transferrability of these rewards via this interface.

Architecture

Autopools will be the main jumping off point for end-user interactions with the system (though technically this is the Router, these are the tokens the user will get back). Users will deposit and withdraw the base asset from here. Vaults are ERC 4626 + Permit compatible.

An Autopool is actually a pair of contracts. These contracts are:

• The pool itself

• A Convex-like, block height+rate style, Rewarder

The purpose of an Autopool is to represent a set of destinations that deposited assets may be deployed. It acts almost as an index. If an Autopool points to 5 destinations then your assets may be deployed to one or all of those destinations depending on how much those destinations are currently earning.

Base Asset

An Autopool should track it’s “base asset”. This is the asset that will be deposited and withdrawn from the pool. Any auto-compounding that happens will be in terms of the base asset, as well. However, it is expected that the Autopools associated Rewarder can emit any token(s).

Tracked Tokens

Autopools support being able to recover tokens that are erroneously sent to it. However, we would not want the ability to be able to transfer out any tokens that are core to operation of the Autopool. This would include the base asset and any DestinationVault shares that it currently holds. Tokens that should not be transferred are called “tracked”.

Debt Reporting

At least every 24 hours, or whenever valuations deviate by a certain threshold, the value of the DestinationVault tokens that are held by the Autopool are re-valued. Deposits and withdraws from the Autopool are based on these cached values. Should this debt reporting result in an increase in value, shares will be minted to the Autopool to offset the increase. This is to ensure there isn’t a sharp increase in the nav/share of Autopool. Auto-compounded rewards are also incorporated during this time.

Fees

Two types of fees can be taken by the Autopool and they are taken during Debt Reporting.

• Periodic Fee - This is a set fee annualized fee that is taken each Debt Reporting

• Streaming Fee - This fee is taken on profit earned by the Autopool. Optionally, this fee can only be taken when profit exceeds previous values (the high watermark).

  • Should the high watermark be enabled and not be broken for a period of 60 days, it will start to decay until we are able to take fees again

Any locked profit will be burned to offset the dilution incurred by any minted fee shares

Valuation

An Autopool tracks three valuations for any LP units it holds via a Destination Vault. These are the safe, spot, and mid point price of the LP tokens (see https://docs.tokemak.xyz/developer-docs/contracts-overview/autopool-eth-contracts-overview/autopilot-contracts-and-systems/pricing). These values are used for different purposes in the life cycle of assets in the Autopool:

• Higher of safe and spot: Used during deposit to value the assets held by the Autopool

• Lower of safe and spot: Used during withdraw to value the assets held by the Autopool

• Mid point: Used for general reporting and fee calculations

To value shares for general purposes the standard ERC4626 convertToAssets(uint256) should be used.

Max Withdraw Value

Using different valuations depending on the operation means that to find the maximum amount of assets one would receive during a redeem() call we need something more than the standard convertToAssets(uint256). For this, we have an extension to the standard function:

uint256 sharesToRedeem = 10e18;

// Begin by getting the total assets of Autopool valued for your intended operation
uint256 totalAssets = autopool.totalAssets(2); // 0 - General, 1 - Deposit, 2 - Withdraw

// Get the total supply of Autopool
uint256 totalSupply = autopool.totalSupply();

// Use the calculated total assets to do the conversion
uint256 maxReturnedAssets = autopool.convertToAssets(sharesToRedeem, totalAssets, totalSupply, 0); // 0 - Round down

Max Deposit Value

Calculating the shares you'd receive on a deposit follows very closely to the previous example

uint256 assetsToDeposit = 10e18;

// Begin by getting the total assets of Autopool valued for your intended operation
uint256 totalAssets = autopool.totalAssets(1); // 0 - General, 1 - Deposit, 2 - Withdraw

// Get the total supply of Autopool
uint256 totalSupply = autopool.totalSupply();

// Use the calculated total assets to do the conversion
uint256 maxReturnedShares = autopool.convertToShares(assetsToDeposit, totalAssets, totalSupply, 0); // 0 - Round down

Estimating Withdraw Value

Above we went through how the Autopool values the tokens it holds and how to calculate a max return value. However, there is another aspect to a redeem() call that can affect the assets returned to the user. An Autopool holds a certain percentage of assets in idle to cover small withdraws. However, if an attempted withdraw needs more assets than sit in idle, the Autopool will start the redemption process by going to the market first. This entails removing liquidity from one or more destinations, and swapping out of non-WETH assets. These swaps can result in slippage and fee's taken in the liquidity pool being swapped through. The Autopool will also ensure that any recent price positive movements in the LP tokens being liquidated are captured. All of this is considered slippage that is passed on to the user performing the redeem().

To retrieve an accurate estimation of assets that would be returned one can use the previewRedeem() call. However, it should be noted that this call deviates from the ERC4626 spec in that it is a nonpayable function instead of a view function. No state changes are made as a result of the call, but to provide the estimate state changes are necessary which are later reverted. This should not be called on-chain.

Due to this possible slippage, it is important to note that any call to redeem() should be checked that an expected amount of assets were received and to revert if not.

Rebalancing

Assets can be rebalanced between destinations according the rules of the Autopools configured strategy. Autopools support the ERC3156 flash loan interface and can grant our Solver access to funds to be able convert them into a more desirable Destinations LP token.

Architecture

GIven that the creation of Autopools may vary widely depending on the type of Autopool being created (future looking), Autopools and their corresponding Factory are a 1:1 relationship. This differs from other factory+register+template relationships in our system:

• Autopilot - Name of the overall system

• Autopool - A 4626 vault that users deposit assets into

• AutoPoolETH - A specific implementation of an AutoPool denominated in ETH/WETH

• Destination - An external contract, or set of contracts, that we LP/stake user funds into

  • Examples

    • A Balancer pool

    • A Balancer pool with LP staked into Aura

    • A Curve pool with LP staked into Convex

• DestinationVault - A contract that sits in front of a Destination in our system. These act has a proxy and give us a common interface to that Destination to perform our operations.

• Solver - Contract that can turn assets into LP tokens, LP tokens into other LP tokens, or LP tokens into assets

• Strategy - A contract that determines whether a Rebalance is in the best interest of an Autopool

• Rebalance - The deployment of:

  • Idle funds to a Destination

  • Funds from one Destination to another Destination

  • Funds from one Destination back to Idle

• Liquidation - The process of taking rewards and auto-compounding them into WETH

Bug Bounty

Our current bug bounty program can be found on Remedy: https://r.xyz/bug-bounty/programs/tokemak

Audits

Hexens

autoUSD Audit - March 2025

Read more

Autopilot Full System Audit - May 2024

Read more

Autopilot Full System Follow Up - July 2024

Read more

Certora

LMPStrategy Security Assessment & Formal Verification Report - Jan/March 2024

Read more

Hats Finance - Autopilot

Crowd Competition Smart Contract Audit, February - March 2024

Read more

Halborn - Autopilot

Autopilot (Autopools) Contracts - Preliminary Smart Contract Audit - Sept 2023

Read more

Halborn - Autopilot

Autopilot Pricing Contracts - Formal Verification Report - Sept 2023

Read more

Sherlock - Autopilot

Autopilot Contracts - Crowd Competition - Sept 2023

Read more

Halborn - accTOKE

accTOKE Contract - Nov 2022

Read more

Autopools allow you to deposit and withdraw in the same asset, the base asset,and to do so on-demand. This means when your withdrawal is large enough to require pulling assets from the underlying LP markets you may incur slippage from swapping back into the Autopool's base asset.

By default, the Autopilot system is configured to be able to swap out of these assets all on-chain with no additional work or information needed. However the quality of trade-execution back into the base asset is limited by the liquidity present in the configured routes that are on-chain. We'll outline here how to provide your own routes to optimize withdrawal execution and to set limit slippage controls.

Determining Swap Amounts

The first step in providing your own routes is to make a rough estimate as to the tokens and amounts that the Autopool will attempt to swap out of. For a TL;DR version, we have provided a package that will give this information for an Autopool and share amount: https://www.npmjs.com/package/@tokemak/autopilot-swap-route-calc If you're able to use the package then you can skip the following section. However for those that wish to calculate these tokens manually, read on.

Calculating Manually

If you wish to calculate these values on your own, you should inspect the logic that is performed during the redeem()operation on the Autopool: https://github.com/Tokemak/v2-core-pub/blob/main/src/vault/AutopoolETH.sol#L357 Some parts to highlight:

• One cannot receive more than assets than the shares valued using withdrawal pricing

• If there are enough assets in idle to cover the value of the shares, no swaps are needed

• The destinations used to pull assets are picked from the withdrawal queue on the Autopool: `getWithdrawalQueue()`

Handling Swaps During Redemption

As with calculating the amounts to swap, we have an interface to get optimal swap executions as well. This is via an API that under the hood utilizes DEX aggregators such as 0x and Bebop. To call:

POST: https://dynamic-swap-routes.tokemaklabs.xyz

{
    "chainId": 1,
    "systemName": "gen3",
    "slippageBps": 10,
    "tokensToLiquidate": [{
        "token": "0x....",
        "amount": "100000000000000000",
        "buyToken": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
    }]
}

Where the tokensToLiquidate is the output from the package @tokemak/autopilot-swap-route-calc package above. systemNamestays "gen3".

The resultsfrom the API output is what will be later passed into our Router for execution:

{ 
    "success": true, 
    "results": [ { 
        "fromToken": "0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0", 
        "toToken": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", 
        "target": "0x39dd8eff184B860eE7FFe3676eB5102e29a57329", 
        "data": "0x..." 
    } ] 
}

Custom Swap Handling

It's possible to use your own contracts as well during the swapping and redemption process instead our API and swapper contracts. To illustrate what would need to be done lets look at the execution flow.

During the redeem()process, our swapper contracts are engaged 0..n times based on the amount of shares being redeemed and the Destinations/markets we need to pull from to satisfy. For example:

• User is redeeming 100 Autopool shares worth 102 ETH (idle only has 5 ETH so it can't cover)

• The Autopool has 50 ETH worth of assets deployed to the first Destination in the withdrawal queue and 200 ETH worth of assets deployed to the second Destination in the withdrawal queue.

• The first Destination is a wstETH/WETH and the second a pxETH/rETH

• Lets assume all assets are priced at 1 ETH. We would expect our swapper contracts to be engaged 3 times:

  • Swap 25 wstETH into WETH

    • This swaps to WETH because the asset() on the Autopool is WETH

    • Since the second token in this Destination is already WETH, it is skipped for swapping

  • Swap 26 pxETH into WETH

  • Swap 26 rETH into WETH

• We exhausted the 50 ETH worth of assets from the first Destination and then moved to the second to get the remainder

Using the output from our API as an example you'd construct an array of the fromToken,toToken,target,data for each of three tokens above, wstETH, pxETH, and rETH:

• targetis the contract you want us to call

• datais the call data you'd want us to use to call your target

• Before your function is called the assets to be swapped will be transferred to the target

• Before the execution of the function ends, the contract should transfer the new assets back to the msg.sender.

Constructing the Final Transaction

Redemption with custom swap routes is only possible through our Autopilot Router multicall contract (see Contract Addresses). There are multiple ways to construct the call but ultimately you are attempting give the Router access to your tokens (through approvals, sending, or having the Router pull them) and calling redeemWithRoutes()

Links