This document contain links to private repositories that might not be publicly available
ySwaps is used to abstract the token trading logic from the strategies harvest method, which means strategies can focus on farming tokens and don't have to handle tokens trading logic and paths. The "swappers" smart contracts allows trading optimizations and new paths to be added since the code is not hardcoded in strategies.
sms: Strategists multisig
tokenIn: Token we have and we want to trade/swap
toeknOut: Token we want to obtain on the swap
hopToken: Token we use as a middle step between tokenIn and tokenOut
tf: Trade Factory
- Trade Factory
- Solvers Scripts
- Dexes Libraries
- Execute Script
- Extra Toolings
- Keep3r Jobs
Contracts in charge of making the swaps (uniswap, balancer, sushiswap, solidly and more). We can separated them in two types:
Uniswap, balancer, sushiswap, etc. These are straighforward contracts that will make a simple swap on these dexes (
token A to
token B). It is also worth to mention that these swappers take care of few extra stuff like:
approval needed to make the swap,
transfering final tokens to strategy if needed.
This contract will receive a bundle of transactions that are required to aquire the wanted token/tokens. This is used in specific cases where trade can not be made in a normal exchange due to liquidity issues, dex not having that token or route, needing extra steps to aquire the token such as depositing or withdrawing, and more. It is important to mention that this swapper does NOT take care of things like approvals, or transfers (important difference with
Single swapper example: We have
tokenOut and we know that we can go straight to sushiswap that has enought liquidity to make the trade with good conditions.
Multicall example: We have a
tokenIn and we want a
tokenOut. But theres no path on any dex to do the trade directly, so we need to split the swap in two steps:
- Step 1:
- Step 2:
For this example we are gonna assume that we will need to use two different dexes for each step. Since we are gonna split the trade in two different transactions and the main objective is to use TWO DIFFERENT dexes, this is where we use the
Multicall Swapper.Everything that requires more than just a single swap tx, will use multicall dexes.
Swapper Contracts (version 0.2.0)
- MultiCallOptimizedSwapper: 0x711d1D8E8B2b468c92c202127A2BBFEFC14bf105
- ZRX 0xE32dd1F66365289b7fe14e503CBB336cD5D13F09
- AsyncBancor 0xf13b8F103690FD74B5F137eC3CF679a9D1B4BA95
- AsyncSushiswap 0x408Ec47533aEF482DC8fA568c36EC0De00593f44
- AsyncUniswapV2 0xA780b6A733D06dFf526A84c4258616b75279C763
- OneInchAggregator 0x934D1c4ba7DF902d6cd0803882876e3C999cb406
- ZRX: 0x0a94017DF3f8981Da97D79c28b103bAbDa0D67C7
- MultiCallOptimizedSwapper: 0x590B3e12Ded77dE66CBF45050cD07a65d1F51dDD
- AsyncSolidly: 0x2cb391afd5180a31d01bE95Bd61A757594C9295a
- AsyncSpiritswap: 0x8d2aFF696F14b287a6E759F4bfFB6f08E92DFD20
- AsyncSpookyswap: 0x86ee473C2eE7eB97Ee0276bE43427a6CF0cC6348
- SyncSpiritswap: 0x923D22FE66C77E2fea215050F088AE26186F96aE
- SyncSpookyswap: 0xcD00a47D9fB36B0B37D589E20fE4fB7e2D9d9e8A
This contract has the
enabled tradesthat each strategy can make. Enabled trades are just a list of possible swaps that a strategy can make. So it only contains three variables:
tokenOut. We have these enabled trades to know which swaps can/should be made with each strategy.
This contract is also in changer of verifying the trades. To do that it will use the different
executemethods in it and call the
swapper contractsthat needs to use. Remember that
swappersare the contracts responsible to making the actual swap.
When we execute the swap its important to point out that this takes care of:
transfering tokenIn from strat to swapper,
make final the check if the amount received > minAmountOut.
Trade Factory Contracts (version 0.2.0)
- TradeFactory: 0x7BAF843e06095f68F4990Ca50161C2C4E4e01ec6
- TradeFactory: 0xD3f89C21719Ec5961a3E6B0f9bBf9F9b4180E9e9
Scripts in charge of providing the swap transaction that will be used and sent to
Trade Factory contract.
Custom solvers: There are custom solvers for specific cases/strategies that will need to make multiple transactions for a specific swap. Each of these scripts aims to an specific strategy and trade that needs to be made. Some examples (
ThreePoolCrvMulticall.ts). This is for specific strategies's trades that will need to swap tokens that can not be swaped/resolved on a single dex swap. The tx provided by this solver is gonna be used with the
Dexes solvers: this script is used for situations where the trade can be resolved with a normal swap on an exchange and does NOT require multiple tx to ensure the trade is possible. Different to
Custom Solvers, this can be used in a generic way for different strategies/swaps. This script checks with every DeX and chooses the best one to make the trade. The tx provided by this solver is gonna be used with the
Multicall Dexes solvers: This solver is gonna split the trade in different steps using the
hopTokensprovided by us. Each step of the swap will loop between every dexes library and will take the best dex for each step of the trade. This solver generally will be using the
MulticallSwappersince we are doing 2 steps or tx for the swap. But it is also possible to use the
SingleSwapperbecause if both steps of the trade are using the same Dex, we should merge them into one for gas efficiency. We will be transformir
1 txso we can use the
There is one dex library per dex (uniswap, bancor, ...). They are in charge of getting the trade information of each Dex and returning all the data needed on the
NOTE: The libraries contemplate the hopTokens too.
This is where everything starts. Here we will grab all the enabled trades, loop and use logic to determinate if:
1) Should the trade by executed?
2) If so, what solver should we use?
3) Once we have the solver response, execute the swap transaction provided by the solver.
Execute pending trades: What exactly happens?
1.1. Identify "pending trades"
1.2. Determinate which solver to use.
1.3. Solver determinates best Dex and returns the swap tx
1.3. Execute swap tx provided by the solver.
Call the execute in Trade Factory
2.1. Contract validates the data and that trade in configuration is valid.
2.2 Moves the funds directly from the strategy to the swapper.
swapper.swap()to execute the trade.
2.4 Check that amount received by strategy > minAmountOut provided by us.
Swapper executes the trade
3.1. Validates some data.
3.2. Executes the trade
3.3. Send funds directly to the strategy.
- Gas service: provides the correct params for gas options for each network
- Price service: we use providers as CoinGecko API to normilize the
tokenOutAmountin USD so we can verify that we are not getting a bad price from the Dex we ended up using.
Add new strategy
STRATEGYrole on Trade factory contract. From yMech.
enable tradeson Trade factory contract. From strategy.
enable tradeon ySwap repo config (
3.1 To add it to the config we also need to know what solver we are going to use. It would be
Dexes.tswhich is a generic solver or it would have its own
3.2 In case of need a
Custom Solver, we need to code it.
- Once added to config, we are ready to execute the script to swap available trades.
- Revoke role from MS.
- Remove from network config file.
- OPTIONAL: remove custom solver if it has one.
Previous knowledge about how
Keeper Network works is needed.
Add strategy fantom keeper harvest job
- Go straight to ftmscan harvest job and add the strategy manually by a yMech.
- Add strategy to v2-ftm-strategies.ts config with
B) (safest way to have everything added)
- Review and merge pr from strategists to add new strategies.
- On packages/strategies-keep3r Execute script:
npx hardhat run scripts/jobs/detached/01-v2-harvest-ftm-detached-job-add-strategies.ts --network fantom
- On config file strategies-keep3r/utils/v2-ftm-strategies.ts change once again strategies property added to true
- Push changes.
Remove strategy fantom keeper harvest job
- Go to ftmscan
Harvest Job SCand remove the strategy manually using method
removeStrategies. Call with a mechanic.
- Remove strategy from