Smart contracts overview
Blueshift protocol consists of three main parts: Core + Periphery and Farming. These parts work independently, but altogether make up a single Blueshift dapp.
Figure 1. Core and Periphery protocol`s parts high-level architecture
Governance router is a smart contract that contains the address of protocol governor. Governor is a (multisig) wallet (or a smart contract in the future) that is allowed to make some state-changing operations in other protocol contracts that are restricted to common users. In future some decentralized governance logic would be implemented in this smart contract. In addition this contract also contains addresses of Portfolio, Oracle and LPT Minter factories (see below) of the protocol, so all the contracts need only to know the address of the governance router to get addresses of other heading contracts.
Portfolio factory is a singleton factory that deploys Portfolios (described below) for the protocol (using create2 pattern). This smart contract also contains addresses of all the deployed Portfolios. To deploy a portfolio you should pass Oracle, LPT Minter and Reserve factory pre-deployed contracts (see below) addresses. Only protocol governor can deploy new Portfolios using the factory.
LPT Minter factory is a singleton factory that deploys LPT Minters (described below) for protocol (using create2 pattern). This smart contract also contains addresses of all the deployed LPT Minters. Only protocol governor can deploy new LPT Minters using the factory.
Oracle factory is a singleton factory that deploys Oracles (described below) for the protocol (using create2 pattern). This smart contract also contains addresses of all the deployed Oracles. Only protocol governor can deploy new Oracles using the factory.
Portfolio is a smart contract that supervises work of its own Oracle and LPT Minter and performs high-level calculations for swaps and liquidity deposit and withdraw operations (low-level calculations are performed in Oracle). Portfolio also has its own Reserve factory smart contract that provides Liquidity reserves contracts (described below). High-level calculations consist of:
- managing Oracles calculations on liquidity prices and amounts;
- calculations on Liquidity Provider Tokens (LPT) price and minting/burning amounts in return to liquidity amount deposited/withdrawn.
The protocol can have as much portfolios as needed, but each portfolio should have its own Oracle, LPT Minter and Reserve factory, and as many liquidity reserves as the number of various tokens Portfolio holds.
Liquidity reserve factory (Reserve factory) is not as much a singleton factory as Oracle and LPT Minter factories are. There is a dedicated Reserve factory for each Portfolio. Reserve factory deploys Liquidity reserves for Portfolio (using create2 pattern) and contains their addresses. Only Portfolio can deploy new Reserves using the factory.
Liquidity reserve (Reserve, Pool) is a smart contract aimed at holding token liquidity on its address and transfer tokens as Portfolio tells Reserve. Each Portfolio has its own reserve for each token. Even if the same token is deposited to different portfolios, tokens would be stored on different Reserve`s addresses.
Additional logic could be implemented in the future, but at the moment Reserves are used only as token vaults. Liquidity reserves should not be messed up with virtual reserves that Oracle uses during swap calculations.
LPT Minter implements IERC20 and IERC721 interfaces. This contract is not as much minter as the token itself. LPT stands for Liquidity Provider Token and as its title says, it is a token that one receives for providing liquidity to Portfolio in return to the tokens provided. LP Tokens could then be staked in Blueshift Farms to earn some BLUES tokens or returned to Portfolio to get provided liquidity back. It's not necessary to return liquidity in tokens provided as Portfolio allows to get the token(-s) you want from those which are deposited to Portfolio in return to one's LP Tokens. As LPT is a ERC20 token, one could freely do any operations with it (transfer to other wallets for example).
Oracle is a smart contract used for all the low-level calculations on assets’ prices and amounts. This smart contract stores internal protocol prices and locked amounts of all the Portfolio tokens. Oracle's calculations consist of:
- swap exchange amounts calculations;
- new token prices (after swap, deposit and withdraw) calculations;
- exponential moving average (EMA) of token prices calculations;
- token amounts balances during deposit and withdraw operations (protocol has additional fees for portfolio disbalancing).
Oracle is the only contract that has all the information on Portfolio assets.
Portfolio registry is a standalone contract that contains and returns information about all the registered Portfolios of the protocol, their addresses, names, list of tokens, addresses of LPT Minters and Oracles. Newly added portfolios are registered manually by and only by the protocol governor.
Portfolio manager is also a standalone contract that contains information about Portfolio tokens` weights distribution (desired distribution). Also this contract is used by the governor to manage portfolios: change token weights, add or remove tokens from a portfolio, etc.
External oracle is another standalone contract used at the moment for the only purpose - checking signed prices from external sources (another DEXes) to use them when a portfolio performs arbitrage swaps. External prices are received from the verified off-chain signer (Blueshift back-end).
Router is a standalone utility contract that helps users interact with the portfolios (e.g. performing swaps, chain swaps, deposit, etc.). Router has a lot of utility logic that performs actions with tokens and portfolios. For example, to perform a swap, one should just call one method of the Router with a list of parameters and the contract itself will transfer tokens to Portfolio, call all the necessary methods and return output tokens to whom they should be returned in a single transaction.
Arbitrage router is a standalone utility contract that helps arbitrageurs to perform arbitrage swaps. Arbitrage router only exists to transfer tokens from arbitrageur to portfolio and call portfolio`s arbitrage swap method in the same transaction.
Figure 2. Farming part high-level architecture
All the protocol state changing operations with farming contracts are allowed only for owner, wallet with the specified address (decentralized governance in the future).
Minter is a smart contract the main purpose of which is to mint BLUES tokens for users that stake LPT and BLUES tokens in Farms and Stakings respectively. Minter also contains logic for minting rates and minted tokens distribution between all the Blueshift Farms and Stakings.
Farming factory is a singleton factory that deploys Farmings (described below) for the protocol (using create2 pattern) and registers them in Minter (only those Farmings which are registered in Minter are tracked by the protocol). Only the protocol owner can deploy new Farmings using the factory.
Staking factory is a singleton factory that deploys Stakings (described below) for the protocol (using create2 pattern) and registers them in Minter (only those Stakings which are registered in Minter are tracked by the protocol). Only the protocol owner can deploy new Stakings using the factory.
Earning is an abstract smart contract that contains the common part of Farmings and Stakings logic. Logic from this contract performs all the calculations on token`s staking/unstaking and reward distribution among all the users according to their shares in total deposited liquidity.
Farming (Farm) is a smart contract that used for staking Portfolio`s LPT. Each portfolio could have its own farm for giving users an ability to receive BLUES tokens for providing LPT (for holding their assets on the protocol and not withdrawing them).
Farms are added manually by the protocol owner as new Portfolio is added. As they are added manually, not every portfolio may have its own Farm (but usually they do). Farm contract inherits Earning contract and extends it with some internal logic specific for Farms only and not for Stakings.
Staking (Manual staking, Manual yield pool) is another smart contract that inherits Earning contract. Staking works much like a farm and the only difference is that Staking is used to stake BLUES tokens to earn more BLUES tokens. So, although there is an ability to add as much Stakings as one wants using Factory, there is no need having more than one. Staking is also called Manual yield pool as user can manually compound his BLUES earnings to Staking. Compounding is what staking can do, but Farming can`t. Compounding is just collecting earnings in BLUES and depositing them back to the pool in one transaction.
Auto-staking (Auto yield pool) is a smart contract that is not actually a staking, but a staking client. It acts like a broker, takes your BLUES and stakes them to the Manual staking. But Auto-staking is called “auto” as users do not have to compound their earnings manually. Earnings of all the users are compounded automatically when someone sends a compounding transaction. The sender of the transaction receives a part of the reward compounded and the rest of the reward is distributed among all stakers according to their shares in the total Auto pool`s deposit.