👾 Welcome to Mellow Protocol

Hello legends! 💪

🧐 We look forward to you dissecting our code and helping us improve the security! Feel free to ask any small or big questions, and ask for guidance or clarifications.

❗️ Please pay attention to the docs and shoot any questions you have on Discord - we’ll be online to respond 💬 .

Contest Details

• $45,000 USDC main award pot
• $5,000 gas optimization award pot
• Join C4 Discord to register
• Submit findings using the C4 form
• Read our guidelines for more details
• Starts December 2, 2021 00:00 UTC
• Ends December 8, 2021 23:59 UTC

Useful links 🧐

Protocol documentation – the most complete information about the contracts

Contract API – gitbook docs generated from contracts

Vaults design article – protocol design overview (Medium)

Twitter | Discord | Website

Contest Scope 🎓

The following contracts are in scope:

Invariants that should uphold at all times ✅

1. Strategy (approved ERC721 person) should not be able to pull the funds anywhere outside of the vault system
2. Liquidity provider shall be able to withdraw funds at all times
3. No one should be able to withdraw smth with zero investment (i.e. no arbitrage / exploits is possible).
4. No one can block withdrawing or claim funds which doesn't not belong to him
5. Governance cannot withdraw liquidity provider funds (with the exception of tokens which are not managed by the Vault)
6. Governance cannot block liquidity provider funds for withdrawing
7. Bad actor on governance side cannot permanently lock protocol / pools / etc
8. VaultTokens are sorted by address in any vault

Contact us 📲

Feel free to ping us:

We're happy to answer any questions and discuss every suggestion.

Protocol overview 🔮

We're buliding permissionless vaults ecosystem for trustless automatic DeFi strategies. The protocol is designed for implementing multi-token cross-protocol liquidity rebalancing.

The Vault contracts hold the tokens and rebalance them both inside other protocols and between them. Strategy contracts interact with Vault contracts definig the rebalancing parameters.

Liquidity provider

Users pick a strategy that fits their needs and allocate their assets into a vault to earn yield. When the assets are deposited, users get composable LP tokens (ERC-20).

Strategies

Strategies are smart-contracts that implement the models to provide effective liquidity allocation. Different market events can trigger the strategies to initiate rebalance.

Vaults

Vaults allocate multiple ERC-20 tokens into other DeFi protocols and rebalance the liquidity in accordance with Strategies inside and between the protocols.

A typical vault and strategy setup would be made by using Mellow Permissioless Vaults deployVault function. As a result, the following set of smart contracts (called Vault System) would be established for every strategy and token pair:

Protocol architecture 🛠

There are two types of contracts on the diagram:

1. Protocol contracts (pink color) — these are the protocol contracts that are deployed in one instance;
2. Vault contracts (purple color) — these are the contracts deployed by users (vault owners/strategists) by using protocol contracts. Essentially everyone can create a set of Vault contracts.

We can logically separate contracts into Vault Groups. Each Vault Group is a set of contracts that allows managing and creating a vault of a specific Vault Kind. Vault Governance is a contract that can:

1. Deploy a new vault via a VaultGovernance#deployVault method
2. Manage governance params for specific vaults

Upon Vault creation, the Vault Registry contract mints a new ERC-721 token that represents that Vault.

Contracts overview 📟

AaveVault

Vault that interfaces Aave protocol in the integration layer. See details.

AaveVaultFactory

Helper contract for AaveVaultGovernance that can create new Aave Vaults. See details.

AaveVaultGovernance

Governance that manages all Aave Vaults params and can deploy a new Aave Vault. See details.

YearnVault

Vault that interfaces Yearn protocol in the integration layer. See details.

YearnVaultFactory

Helper contract for YearnVaultGovernance that can create new Yearn Vaults. See details.

YearnVaultGovernance

Governance that manages all Yearn Vaults params and can deploy a new Yearn Vault. See details.

UniV3Vault

Vault that interfaces UniV3 protocol in the integration layer. See details.

UniV3VaultFactory

Helper contract for UniV3VaultGovernance that can create new UniV3 Vaults. See details.

UniV3VaultGovernance

Governance that manages all UniV3 Vaults params and can deploy a new UniV3 Vault. See details.

ERC20Vault

Vault that stores ERC20 tokens. See details.

ERC20VaultFactory

Helper contract for ERC20VaultGovernance that can create new ERC20 Vaults. See details.

ERC20VaultGovernance

Governance that manages all ERC20 Vaults params and can deploy a new ERC20 Vault. See details.

GatewayVault

Vault that combines several integration layer Vaults into one Vault. See details.

GatewayVaultFactory

Helper contract for GatewayVaultGovernance that can create new Gateway Vaults. See details.

GatewayVaultGovernance

Governance that manages all Gateway Vaults params and can deploy a new Gateway Vault. See details.

LpIssuer

Contract that mints and burns LP tokens in exchange for ERC20 liquidity. See details.

LpIssuerFactory

Helper contract for LpIssuerGovernance that can create new Lp Issuers. See details.

LpIssuerGovernance

Governance that manages all LpIssuers params and can deploy a new LpIssuer. See details.

Vault

Abstract contract that has logic common for every Vault. See details.

VaultGovernance

Internal contract for managing different params. See details.

ProtocolGovernance

Governance that manages all params common for Mellow Permissionless Vaults protocol. See details.

DefaultAccessControl

This is a default access control with 2 roles - ADMIN and ADMIN_DELEGATE. See details.

CommonLibrary

Common shared utilities

ChiefTrader

Main contract that allows trading of ERC20 tokens on different Dexes. See details.

UniV3Trader

Contract that can execute ERC20 swaps on Uniswap V3. See details.

Trader

Base contract for every trader contract (a contract that can execute ERC20 swaps). See details.

External calls made by our contracts:

• Aave
  • LendingPool: deposit, withdraw, getReserveData
  • aTokens: balanceOf
• Uniswap
  • Router: exactInput, exactOutput
  • NonfungiblePositionManager: increaseLiquidity, decreaseLiquidity, collect, positions
• Yearn
  • Yearn Vault Registry: latestVault
  • yTokens: deposit, withdraw, balanceOf

How we protect the protocol 🔐

VaultRegistry mints a unique ERC721 NFT for each Vault. Access control is based on that NFTs:

1. Nft Owner can freely push and pull liquidity from the vault
2. Nft approved person can push, but pull only to other vaults which are in the same Vault System
3. ERC-721 ApprovedForAll cannot do anything (i.e. irrelevant to access control)

Additionally Protocol Governance admin can perform certain tasks on protocol management and emergency shutdown:

1. Disable / migrate strategies (by changing approve rights for Nfts in VaultRegistry)
2. Set strategy and protocol params on VaultGovernance level, incl setting deposit limits to 0
3. Reclaiming tokens that are sent by mistake on vaults

Only tokens whitelisted by Protocol Governance can be used for creating new Vaults.

Setup, tests, etc. 🪄

See Contracts README.md

Run unit tests

Required env variables (could be addred to .env file):

MAINNET_RPC=<ethereum rpc endpoint>
KOVAN_RPC=<ethereum rpc endpoint>

MAINNET_RPC should be able to serve acrhive node api. E.g. Alchemy can do that.

yarn
yarn coverage

Tests coverage report

open coverage/index.html

Deploy

Required env variables (could be added to .env file):

MAINNET_RPC=<ethereum rpc endpoint>
KOVAN_RPC=<ethereum rpc endpoint>
MAINNET_DEPLOYER_PK=0x.... # for mainnet deploy
KOVAN_DEPLOYER_PK=0x.... # for kovan deploy

yarn
yarn deploy:hardhat
# or yarn deploy:kovan
# or yarn deploy:mainnet

Check contract size

yarn
yarn size

Good luck and may the Force be with you!✨