This contract is part of Orbs Liquidity Nexus protocol. It is a thin wrapper over Sushi LP token and represents liquidity added to the Sushi ETH/USDC pair.
The purpose of Liquidity Nexus is to allow single-sided ETH-only farming on SushiSwap. In regular Sushi LP, users add liquidity of both USDC and ETH in equal values. Nexus LP allows users to add liquidity in ETH only, without needing any USDC.
So where does the USDC come from? USDC is sourced separately from Orbs Liquidity Nexus and originates from CeFi. This large pool of USDC is deployed in advance and is waiting in the contract until ETH is added. Once ETH is added by users, it is paired with part of the available USDC to generate regular Sushi LP. When liquidity is removed by a user, the Sushi LP is burned, the USDC is returned to the pool and the ETH is returned to the user.
- Run
npm installto install all the dependencies. - Sign up on Alchemy. We recommend using Alchemy over Infura to allow for a reproducible Mainnet fork testing environment as well as efficiency due to caching.
- Create a file
.config.json:
{
"alchemyKey": "<your-alchemy-key>"
}
The contract is thoroughly tested using Hardhat on a Mainnet fork. There are over 25 tests in this suite and even more economic simulation tests in a dedicated repo. Run the test suite with:
npm run build
npm run test
This contract is designed to be tightly integrated with a DeFi vault such as harvest.finance / yearn.finance / autofarm.network / acryptos.com
The result is an ETH-only DeFi vault where DeFi participants deposit ETH and earn ETH with considerably higher APY than normal. We have a proof of concept demonstration of such an integration as a harvest.finance vault available here. This demonstration was not deployed and harvest was used because of their existing Sushi ETH/USDC vaults which are useful for APY comparisons.
The contracts mints new Nexus LP tokens (the contract is an ERC20) for all liquidity added by users and burns these tokens when liquidity is removed. Nexus LP tokens are transferred to users adding liquidity. The contract is a wrapper around Sushi LP. The Sushi LP tokens are not transferred to users and are kept by this contract until users decide to remove their liquidity.
Since this contract holds a significant amount of Sushi LP tokens, to maximize yield over this Sushi LP, the contract deposits all Sushi LP immediately in Sushi MasterChef and accumulates SUSHI rewards. SUSHI rewards belong to the governance role which can claim them at any time.
-
governance- The party that receives SUSHI rewards accumulated from all Sushi LP generated by this contract. Only this role can executeclaimRewardsto receive the SUSHI andcompoundProfitsto take any ETH generated from selling the rewards (selling must occur outside this contract) and distribute the profits to all liquidity providers. Normally, the governance would be a DeFi vault such as harvest.finance / yearn.finance / autofarm.network / acryptos.com that is tightly integrated with this contract and manages all profits. -
owner- The deployer of the contract which is also the capital provider for the USDC pool waiting in the contract. Only this role can deposit USDC and withdraw available USDC. This role can also pause and unpause new liquidity additions by users and salvage unrelated tokens that were sent to the contract by accident. It's important to note that the owner cannot upgrade or migrate the code. The owner also cannot touch any of the ETH deposited by users or the Sushi LP that were generated from it.
The contract is immutable to protect users. It cannot be upgraded or migrated. All future migrations must be completely manual. Meaning a new separate contract will be deployed and users will have to choose to remove their liquidity from this contract and add their liquidity manually to the new one.
The owner can handle emergencies, but in a way that fully protects users and their liquidity.
-
pause/unpause - The owner can pause adding new liquidity by users. Even when paused, existing liquidity providers can still remove their liquidity, so they are always protected.
-
salvage - The owner can salvage unrelated tokens that were sent to the contract by accident. These tokens cannot be ETH / USDC / SUSHI or Sushi LP, so users are always protected.
-
emergency exit - Since the owner is the capital provider of all USDC, in an emergency the owner can retrieve their USDC. If this happens, all Sushi LP are burned so the USDC can be retrieved. All ETH generated from this remains safe in the contract until users remove liquidity since ETH belongs to users, and their liquidity is always protected from the owner.
-
disable oracle price protection - The contract safeguards the ETH price of the Sushi ETH/USDC pair against manipulation by comparing it to an external ETH price oracle (Chainlink or Compound). The owner can disable this protection in an emergency where these oracles stop functioning.
This contract is marked in yellow, its users are on the left, contracts it relies on are on the right:
- The contract accepts USDC from the owner (the capital provider) and holds the USDC capital until can be matched with ETH.
- The owner is not able to withdraw their occupied USDC other than emergency.
- The contract accepts ETH (or WETH) from users that call
addLiquidity.- Pairs this new ETH with available USDC and generates Sushi LP. If there's not enough available USDC, the transaction will revert.
- Auto stakes the resulting Sushi LP into Sushi MasterChef.
- Mints Nexus LP for the user (these shares may grow in value due to profits compounded by governance).
- Users can withdraw at any time by calling
removeLiquidity, no entry or exit fees.
- The contract allows governance to claim SUSHI rewards occumulated in MasterChef.
- If governance sells the SUSHI rewards, it must be done outside this contract.
- Governance can deposit back profits as ETH by calling
compoundProfits. - Any compounded profits are distributed per-share for all Nexus LP holders.
- Governance can decide on the cut of the profits to give to the owner (capital provider that deposited original USDC).
- Once a user removes liquidity, the contract burns the relevant Sushi LP to free ETH and USDC.
- Resulting ETH/USDC are rebalanced according to the defined rebalancing strategy.
- The goal is to maximize resulting yield for the ETH provider, while protecting the USDC provider's initial deposit.
- It is up to the governance to decide on the right distribution of rewards between USDC and ETH providers.
Sushi MasterChef only distributes 1/3 of SUSHI rewards immediately. The rest of the rewards (2/3) are locked for 6 months and must be claimed manually from Sushi's Merkle distributor. This manual action can be done by any third-party at any time. The resulting SUSHI will be transferred by Sushi's Merkle distributor to this contract. After this happens, only governance can claim the SUSHI by calling claimRewards.
Since there are two different parties supplying the ETH and USDC, the fees and impermanent loss must be divided between them. There are multiple rebalancing strategies implemented in this contract. In general, the goal is to give the ETH suppliers more of the rewards in exachange for taking more of the IL risk. The USDC is sourced from CeFi providers via Orbs Liquidity Nexus and their general expectations are to limit exposure to crypto volatility and receive lower APY. Read more about the rebalancing strategies in the Orbs Liquidity Nexus Medium posts below. You can also see how IL is divided (ignoring swap fees) in each strategy here.
Fair and exploit-safe implementation of the rebalancing strategies requires non-fungibility. This means two users who deposited the same amount of ETH at different times (when ETH price was different) will be rebalanced differently so each of them has their own IL depending on the amount of USDC they were paired with from the available USDC pool. Ideally, Nexus LP would have been implemented as an NFT but this would limit compatibility with existing vault projects. Nexus LP is therefore a fungible regular ERC20 that can be transferred. Soft non-fungibility is implemented by remembering the minter's address and only allowing this original minter to burn the amount that they minted.
In other words, only the original address that executed addLiquidity can execute removeLiquidity. This behavior provides seamless compatibility with DeFi vaults that can hold the Nexus LP tokens until their users choose to exit.
Since IL is divided between two parties (ETH provider and USDC provider), we must protect against IL manipulation by depositors. Different ETH depositors cannot manipulate each other, but they can manipulate the USDC provider. Manipulation requires the ETH depositor to cause an artificial drastic change in the ETH price of Sushi ETH/USDC pair by means such as flash loans. To prevent this, the contract validates the ETH price in Sushi ETH/USDC pair by comparing it to an external ETH price oracle Chainlink. If the difference in price is extreme, the transaction is reverted.
Orbs Liquidity Nexus is a project by Orbs blockchain team that introduces CeFi sourced liquidity to popular DeFi projects like harvest. Here are some Medium posts that explain in more detail:
- Introducing Orbs Liquidity Nexus - Liquidity as a Service
- Single Sided-Farming on Any DEX Via Orbs Liquidity Nexus - Part 1
- Single Sided-Farming on Any DEX Via Orbs Liquidity Nexus - Part 2
- Single Sided-Farming on Any DEX Via Orbs Liquidity Nexus - Part 3
- Orbs Integrates With Chainlink to Secure Single-Sided Farming From Flash Loan Attacks