This repo contains mStable's Meta Vaults contracts that are based on EIP-4626 vaults.
Meta Vaults combine, compose, and optimise multiple yield sources into standardised vaults and higher-order products while remaining open and interoperable.
There are 3 different types of Vault implementations:
- Basic Vault: This is the simplest building block for composable yielding Vaults. It follows the ERC-4626 standard. It can be used to either create a yield strategy or wrap an existing contract to allow for ERC-4626 compatibility
- Multi Asset Vault: This is a layer that can aggregate multiple yield sources into one. It can use any ERC-4626 compliant contracts, even if they are not using the same asset. This Vault is similar to the ERC-4626 standard but has slight modifications to handle multiple assets.
- Meta Vault: This is the top layer and is composed of either Basic Vaults, Multi Asset Vaults, other ERC-4626 compliant contracts, or any combination of them. The Meta Vault is ERC-4626 compliant and therefore offers the users the easiest path to allocate their assets or for protocols to integrate.
The Contracts follow a modular pattern. The Vaults can be enriched with additional functionality:
- Allocation Vaults: Vaults that can manage a multiple underlying Vaults via setting weights or batching.
- Cached Vaults: Adds the capability to cache some of the underlying assets in the vault. Saves gas on small deposits/withdrawals to/from an underlying platform or vault.
- Fee Vaults: Adds the capability to charge a fee, ether performance or transactional.
- Rewards: Handling rewards donated to the Vault.
Separate Modules:
- Liquidator: Can be used by a Vault to liquidate assets and swap into the underlying in order to increase share value of itself. Useful for farmining strategies.
- Swap: Contracts to swap one asset for another. Used by the liquidator.
- Managers: Contracts that add function to manage a vault - Batching transaction and is easier/cheaper to manage vault positions.
Find the official Announcement here.
The first set of mStable meta vaults are for staking 3Pool-based (3Crv) Curve Metapool liquidity provider (LP) tokens in Convex. See 3Crv Convex Vaults for more details.
The second set of mStable meta vaults are for staking FRAX based Curve Metapool liquidity provider (LP) tokens in Convex. That is, Metapools that include the FRAX+USDC (crvFRAX) LP token which is also referred to as the Frax base pool (FraxBP). See FRAX-based Convex Vaults for more details.
$ yarn
Key folders:
/contracts/z_mocks: All mocks used throughout the test suite/security: Scripts used to run static analysis tools like Slither and Securify/build: Is generate from the build processyarn compile./dist: Typescript generated JavaScript and definition files./docs: Images used in READMEs. The contract diagrams are generated by sol2uml. The process diagrams are done in PlantUML with source in the mStable-process-docs repo./tasks: Hardhat tasks that run operational reports and transactions./test: Unit tests in folders corresponding to contracts/xx. All third party protocols are mocked./test-fork: Hardhat fork tests used to test against other protocols./test-utils: Core util files used throughout the test framework/types: TS Types used throughout the suite/generated: Generated output from Typechain; strongly-typed, Ethers-flavoured contract interfaces
Tests are written with Hardhat, Ethers.js, Mocha & Typescript, using Typechain to generate typings for all contracts. Tests are executed using hardhat in hardhats evm.
$ yarn test
Solidity-coverage is used to run coverage analysis on test suite.
This produces reports that are visible in the /coverage folder, and navigatable/uploadable. Ultimately they are used as a reference that there is some sort of adequate cover, although they will not be a source of truth for a robust test framework. Reports are publicly available on coveralls.
NB: solidity-coverage runs with solc optimizer=false (see discussion)
Codebase rules are enforced through a passing GitHub Actions (workflow configs are in .github/workflows). These rules are:
- Linting of both the contracts (through Solium) and TS files (ESLint)
- Passing unit test suite
- Maintaining high unit testing coverage
- Solidity imports deconstructed as
import { xxx } from "../xxx.sol" - Solidity commented as per NatSpec format
- Internal function ordering from high > low order
The logger can be found in logger.ts and uses the debug package. Set the DEBUG environment variable to enable the log messages.
# See all mStable logs
export DEBUG=mstable*
# Just see the tx logs
export DEBUG=mstable:tx
# To see the address resolving logs
export DEBUG=mstable:addressesHardhat Tasks are used for command line interactions with the mStable contracts. The tasks can be found in the tasks folder.
To access public blockchains the NODE_URL environment variable needs to be exported with the provider url. For example
# Alchemy mainnet
export NODE_URL=https://eth-mainnet.alchemyapi.io/v2/yourApiKey
# Infura mainnet
NODE_URL=https://mainnet.infura.io/v3/yourApiKeyThe Hardhat --network option must be used to specify which chain to use. These networks are configured in hardhat.config.ts. For example mainnet, polygon_mainnet, ropsten, goerli, polygon_testnet or local.
If you are just using readonly tasks like token-balance you don't need to have a signer with Ether in it so the default Hardhat test account is ok to use. For example
yarn task token-balance --network mainnet --token MTA --owner mStableDAO
If you want to use Defender Relay you need to export the API key and secret in environment variable DEFENDER_API_KEY and DEFENDER_API_SECRET. For example
export DEFENDER_API_KEY=<your key>
export DEFENDER_API_SECRET=<your secret>
You can also a local private key with.
export PRIVATE_KEY=<your private key>
A separate Hardhat config file tasks.config.ts is used for task config. This inherits from the main Hardhat config file hardhat.config.ts. This avoids circular dependencies when the repository needs to be compiled before the Typechain artifacts have been generated. This means the --config tasks.config.ts Hardhat option needs to be used to run the mStable tasks.
Never commit mainnet private keys, mnemonics or provider URLs to the repository.
Examples of using the Hardhat tasks
# List all Hardhat tasks
yarn task
# Set the provider url
export NODE_URL=https://mainnet.infura.io/v3/yourApiKey
# To transfer 1000 MTA tokens from the signer account being used to the mStable DAO
yarn task token-transfer --network mainnet --asset MTA --recipient mStableDAO -- amount 1000The contract Natspec can be generated into a markdown file in the docs/natspec folder using the following command.
yarn docgen
The markdown for the relevant contracts can then be copied into GitBook.
Unfortunately the generated markdown will not include inherited classes. These need to be manually included for now.
- https://github.com/mstable/mStable-defender
- https://github.com/mstable/metavault-subgraph
- https://github.com/mstable/frontend
- https://github.com/mstable/mStable-data
- https://github.com/mstable/mStable-process-docs/tree/main/vaults
- https://yield.mstable.org Meta Vault user Interface
- https://docs.mstable.org User documentation
- https://developers.mstable.org Developer documentation
- https://immunefi.com/bounty/mstable/ Bug bounty
- https://mstable.org
- https://app.mstable.org
- https://staking.mstable.app
- https://github.com/mstable/mStable-contracts
| Contract | Address | Repo Version |
|---|---|---|
| CowSwapDex | 0xB305372B12Fd5d736EcB6BF903eaA844f2a23112 | v0.0.5 |
| Liquidator | 0xD298291059aed77686037aEfFCf497A321A4569e | v0.0.7 |
| Curve3CrvMetapoolCalculatorLibrary | 0x5de8865522A61FC9bf2A3ca1A7D196A42863Ea56 | v0.0.3 |
| Curve3CrvFactoryMetapoolCalculatorLibrary | 0x3206bf36B1e1764B4C40c5A51A8E237DC4cB10a9 | v0.0.3 |
| Curve3CrvCalculatorLibrary | 0x092C1b41163c85054F008A486BA72347B919aFa7 | v0.0.3 |
| mUSD Convex Vault | 0xB9B47E72819934d7A5d60Bf08cD2C78072383EBb | v0.0.3 |
| FRAX Convex Vault | 0x98c5910823C2E67d54e4e0C03de44043DbfA7ca8 | v0.0.3 |
| BUSD Convex Vault | 0x87Ed92648fAE3b3930577c92c8A247b127ED8949 | v0.0.3 |
| 3Crv Meta Vault | 0x9614a4C61E45575b56c7e0251f63DCDe797d93C5 | v0.0.6 |
| USDC 3CRV Convex Meta Vault | 0x455fB969dC06c4Aa77e7db3f0686CC05164436d2 | v0.0.3 |