|
| 1 | +# NFTX Protocol V3 |
| 2 | + |
| 3 | +<img alt="NFTX Logo" src=".github/nftx-logo.jpg" /> |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +NFTX is a platform for creating liquid markets for illiquid Non-Fungible Tokens (NFTs). |
| 8 | +<br> |
| 9 | +Users deposit their NFT into an NFTX vault to fractionalize and mint a fungible ERC20 token (vToken). This vToken can be redeem back for any NFT from the vault, by paying a redeem fee in ETH. |
| 10 | +<br><br> |
| 11 | +The vTokens can then be used to earn yield by:<br> |
| 12 | + |
| 13 | +1. Depositing into InventoryStaking to earn ETH (from vault fees) + vTokens (from early withdrawal fees) |
| 14 | +2. Pairing the vTokens with ETH and providing concentrated liquidity into the NFTX AMM to earn trading fees and additional ETH (from vault fees). |
| 15 | + |
| 16 | +<hr /> |
| 17 | + |
| 18 | +## Contracts |
| 19 | + |
| 20 | +[addresses-table] |
| 21 | + |
| 22 | +## Core Contracts |
| 23 | + |
| 24 | +### 1. NFTXVaultUpgradeableV3 |
| 25 | + |
| 26 | +Allows the following 3 main operations:<br /> |
| 27 | +i. `mint`: Deposits NFTs and mints vault tokens in exchange.<br /> |
| 28 | +ii. `redeem`: Burn vault tokens to redeem NFTs from the vault in exchange.<br /> |
| 29 | +iii. `swap`: Swap an array of NFTs into a desired array of NFTs from the vault. |
| 30 | + |
| 31 | +All of the above operations require the user to pay vault fees in ETH, calculated as a % of the ~20 min TWAP of the vToken from our AMM pool (with fee tier = `FeeDistributor.rewardFeeTier()`). If the pool doesn't exist yet, then no vault fees are deducted.<br /><br /> |
| 32 | +The vault fees collected here are sent to the `NFTXFeeDistributorV3` in the same transaction to distribute to Inventory stakers and Liquidity Providers.<br /> |
| 33 | +<br /> |
| 34 | +In case of redeeming/swapping into a newly deposited NFT from a vault, an extra premium in ETH needs to be paid along with the vault fees. This premium is shared with the original depositor of the redeemed tokenId and the rest of the stakers. This premium amount goes down exponentially since being deposited into the vault and finally settling on 0.<br /> |
| 35 | +<br /> |
| 36 | +Additional features: |
| 37 | + |
| 38 | +- Flash-minting without any added fees. |
| 39 | +- Using Eligibility modules to only allow certain tokenIds into the Vault. |
| 40 | + |
| 41 | +### 2. NFTXVaultFactoryUpgradeableV3 |
| 42 | + |
| 43 | +Allows to deploy Beacon Proxies for the Vaults. |
| 44 | + |
| 45 | +### 3. NFTXFeeDistributorV3 |
| 46 | + |
| 47 | +Allows to distribute WETH (vault fees) between multiple receivers including inventory stakers and NFTX AMM liquidity providers in the `rewardFeeTier` pool. |
| 48 | + |
| 49 | +### 4. NFTXInventoryStakingV3Upgradeable |
| 50 | + |
| 51 | +Allows users to stake vTokens and mint xNFT in exchange that earns WETH and vTokens as fees. The WETH vault fees are distributed equally among all the stakers.<br /> |
| 52 | + |
| 53 | +- NFTs can also be directly staked via Inventory, which internally mints vTokens but without deducting any vault fees. As users can use this to game and avoid the mint fees, so a redeem timelock is placed on the xNFT. |
| 54 | +- There is an option to early withdraw (while still in timelock) by paying a % of your vTokens as penalty, which gets distributed among rest of the stakers. This penalty goes down linearly overtime. |
| 55 | +- Users can collect and withdraw the WETH accumulated by their position |
| 56 | +- During withdrawal, users have the option to redeem NFTs from the vault with their underlying vToken balance. No vault fees is paid if initially the xNFT position was created by depositing NFTs. |
| 57 | +- Users can combine multiple xNFT positions into one, after each of their timelocks have run out. |
| 58 | + |
| 59 | +### 5. UniswapV3FactoryUpgradeable |
| 60 | + |
| 61 | +Forked from Uniswap, and converted into an upgradeable contract. Allows to deploy NFTX AMM pools as Create2 Beacon Proxies. |
| 62 | + |
| 63 | +### 6. UniswapV3PoolUpgradeable |
| 64 | + |
| 65 | +Forked from Uniswap. Added `distributeRewards` function, to be called by the FeeDistributor, which allows to distribute the WETH vault fees to the LPs in the current tick, proportional to their share of the liquidity. <br /> |
| 66 | +If the pool is in `rewardFeeTier`, then cardinality is set during initialization of the pool so that it's able to provide TWAP for the vault fee calculations. The cost of initialization of the observations slots is forwarded & distributed to the first swappers. |
| 67 | + |
| 68 | +### 7. NonfungiblePositionManager |
| 69 | + |
| 70 | +Forked from Uniswap. Allows NFTX AMM positions to be represented as ERC721 NFTs. Allows the NFTXRouter to timelock positions from withdrawing liquidity, though more liquidity can still be added. |
| 71 | + |
| 72 | +- Vault fees accumulated as WETH show up the same way as normal LP fees. |
| 73 | + |
| 74 | +### 8. NFTXRouter |
| 75 | + |
| 76 | +Router to facilitate vault tokens minting/burning + addition/removal of concentrated liquidity, all in one transaction. <br /> |
| 77 | + |
| 78 | +- NFTs can be directly deposited into the pool via NFTXRouter, which internally mints vTokens but without deducting any vault fees. As users can use this to game and avoid the mint fees, so a redeem timelock is placed on the LP NFT. |
| 79 | +- During withdrawal, users have the option to redeem NFTs from the vault with their underlying vToken balance. No vault fees is paid if initially the position was created by depositing NFTs. |
| 80 | +- NFTs can be directly sold and bought from the pool in exchange for ETH, via the AMM. |
| 81 | + |
| 82 | +## Zaps |
| 83 | + |
| 84 | +### 1. CreateVaultZap |
| 85 | + |
| 86 | +An amalgomation of vault creation steps, merged and optimised in a single contract call. <br /> |
| 87 | +Allows to create a new Vault, mint vTokens in exchange for NFTs, deploy new NFTX AMM pool, deposit the minted vTokens and the ETH sent into the AMM pool to mint liquidity position NFT, deposit the remaining vTokens into inventory staking to mint xNFT. |
| 88 | + |
| 89 | +### 2. MarketplaceUniversalRouterZap |
| 90 | + |
| 91 | +Marketplace Zap that utilizes Uniswap's Universal Router to facilitate tokens swaps via Sushiswap and NFTX AMM. Enables deducting creator royalties via ERC2981.<br /> |
| 92 | + |
| 93 | +- `sell721`/`sell1155`: sell NFT tokenIds to ETH.<br /> |
| 94 | + `idsIn --{--mint-> [vault] -> vTokens --sell-> [UniversalRouter] --}-> ETH` |
| 95 | +- `swap721`/`swap1155`: Swap an array of NFTs into a desired array of NFTs from the vault, by paying ETH for vault fees. |
| 96 | +- `buyNFTsWithETH`: buy NFT tokenIds with ETH.<br /> |
| 97 | + `ETH --{-sell-> [UniversalRouter] -> vTokens + ETH --redeem-> [vault] --}-> idsOut` |
| 98 | +- `buyNFTsWithERC20`: buy NFT tokenIds with ERC20.<br/> |
| 99 | + `ERC20 --{-sell-> [UniversalRouter] -> ETH -> [UniversalRouter] -> vTokens + ETH --redeem-> [vault] --}-> idsOut` |
| 100 | + |
| 101 | +### 3. MigratorZap |
| 102 | + |
| 103 | +Allows the users to migrate their NFTX v2 positions to v3: |
| 104 | + |
| 105 | +- from v2 vTokens in sushiswap liquidity to v3 vTokens in NFTX AMM. |
| 106 | +- from v2 vTokens in v2 inventory staking to v3 vTokens in xNFT. |
| 107 | +- from v2 vTokens to v3 vTokens in xNFT. |
| 108 | + |
| 109 | +<hr /> |
| 110 | + |
| 111 | +## Project Setup |
| 112 | + |
| 113 | +We use [Foundry](https://book.getfoundry.sh/) for tests and [Hardhat](https://hardhat.org/docs) for contract deployments. Refer to installation instructions for foundry [here](https://github.com/foundry-rs/foundry#installation). |
| 114 | + |
| 115 | +```sh |
| 116 | +git clone https://github.com/NFTX-project/nftx-protocol-v3.git |
| 117 | +cd nftx-protocol-v3 |
| 118 | +forge install |
| 119 | +yarn install |
| 120 | +``` |
| 121 | + |
| 122 | +Copy `.env.sample` into `.env` and fill out the env variables. |
| 123 | + |
| 124 | +### Tests |
| 125 | + |
| 126 | +```sh |
| 127 | +forge test |
| 128 | +``` |
| 129 | + |
| 130 | +### Deployment |
| 131 | + |
| 132 | +1. To deploy core V3 contracts (including Uniswap V3 Fork): |
| 133 | + |
| 134 | +```sh |
| 135 | +yarn deploy:goerli --maxfee <inWei> --priorityfee <inWei> --tags NFTXV3 |
| 136 | +``` |
| 137 | + |
| 138 | +2. Deploy new Universal Router (https://github.com/NFTX-project/nftx-universal-router) with updated address for UniswapV3 Factory address. |
| 139 | +3. Deploy all Zaps: |
| 140 | + |
| 141 | +```sh |
| 142 | +yarn deploy:goerli --maxfee <inWei> --priorityfee <inWei> --tags Zaps |
| 143 | +``` |
| 144 | + |
| 145 | +4. Run the following to generate `./addresses.json` for the deployed contract addresses |
| 146 | + |
| 147 | +```sh |
| 148 | +yarn gen:addresses |
| 149 | +``` |
| 150 | + |
| 151 | +Note: Tags are defined in the deploy script at the end like: `func.tags = ["<tag>"]` |
| 152 | + |
| 153 | +### Verify Contracts |
| 154 | + |
| 155 | +`yarn verify:goerli` |
| 156 | + |
| 157 | +**Note:** For some UniswapV3 contracts there might be some error while verifying, so run this for those contracts: |
| 158 | + |
| 159 | +`yarn verify:goerli --license "GPL-2.0" --force-license --solc-input` |
| 160 | + |
| 161 | +How to verify the BeaconProxy (for Vaults): |
| 162 | +`source .env && forge verify-contract --chain-id 5 --num-of-optimizations 800 --watch --etherscan-api-key $ETHERSCAN_API_KEY --compiler-version v0.8.15+commit.e14f2714 0xffE5d77309efd6e9391Ac14D95f2035A1e138659 lib/openzeppelin-contracts/contracts/proxy/beacon/BeaconProxy.sol:BeaconProxy --constructor-args $(cast abi-encode "constructor(address,bytes)" 0x1d552A0e6c2f680872C4a88b1e7def05F1858dF0 "")` |
| 163 | + |
| 164 | +where `0xffE5d77309efd6e9391Ac14D95f2035A1e138659` = vault (proxy) address\ |
| 165 | +and `0x1d552A0e6c2f680872C4a88b1e7def05F1858dF0` = vault factory |
0 commit comments