From b14cb5a32851b80cb43f586529c867558eeb348e Mon Sep 17 00:00:00 2001 From: Preston Ong Date: Fri, 25 Mar 2022 15:25:49 +0800 Subject: [PATCH 1/5] additional networks --- docs/nftfair/introduction.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/nftfair/introduction.md b/docs/nftfair/introduction.md index fc3ea573..88206619 100644 --- a/docs/nftfair/introduction.md +++ b/docs/nftfair/introduction.md @@ -8,6 +8,12 @@ This platform is compatible with most EVM networks. We currently support the hos - BSC +We plan to deploy this platform on the following networks in the near future: + +- Polygon PoS +- Moonbeam +- Ethereum + We are working hard to expand the list of supported networks. If your intended launch network is not included in our supported list, please submit a proposal [here](https://docs.google.com/forms/d/e/1FAIpQLScU36yLYWuiL3gXVvy7NwvnY-t4JD0u6XUvhTeaogCzQDzQpw/viewform) or reach out to us at [nftfair@ata.network](mailto:nftfair@ata.network). ## Fairdrop Templates: From a04afd051d3ae1be69aaae21e702503babdf9dc1 Mon Sep 17 00:00:00 2001 From: Preston Ong Date: Thu, 5 May 2022 12:23:22 +0800 Subject: [PATCH 2/5] updated vault base docs --- docs/nftfair/contracts/vault/base.md | 67 ++++++++++++++++++++++------ 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/nftfair/contracts/vault/base.md b/docs/nftfair/contracts/vault/base.md index eb01851a..2c7e7bf0 100644 --- a/docs/nftfair/contracts/vault/base.md +++ b/docs/nftfair/contracts/vault/base.md @@ -4,12 +4,15 @@ NFTFair Vaults are responsible for fairly distributing NFTs, a.k.a. Fairdrop, th The `NFTVaultBase` contract provides the essential features to receive and organize NFTs by assigning categories. A category must be created **prior** to receiving any NFTs. The vault may reject any incoming NFTs, if a category is not created for that particular NFT contract. -The structure of the Category is the following: +The structure of a Category strictly complies with the format below: ```solidity struct CategoryInfo { + enum TokenType; address nft; EnumerableSet.UintSet ids; + mapping (uint256 => uint256) id_value; EnumerableSet.UintSet claimable_ids; + mapping (uint256 => uint256) claimable_id_values; uint256 purchaseLimit; uint256 price; } @@ -17,19 +20,23 @@ struct CategoryInfo { | Parameter | Description | | --- | --- | +| TokenType | `ERC721` or `ERC1155` | | NFT | The address of the NFT contract. This address **cannot** be modified after initialization| -| ids | A list of token IDs that the vault has received. IDs are appended when the `onERC721Received` hook is called | +| ids | A recorded list of token IDs that belong to the category. IDs are appended when the `onERC*Received` hook is called | +| id_values | The mapping of a tokenIDs to the total quantity of ERC1155 tokens in the category | | claimable ids | A list of token IDs that are available to claim. A subset of the `ids` list. | +| claimable_id_values | The mapping of a tokenIDs to the available quantity of ERC1155 tokens to be claimed | | Purchase Limit | The maximum amount of NFTs that a user is eligible to claim from the category | | Price | Amount to be paid in `paymentToken` to purchase an NFT | -## `createCategory()` +### `createCategory()` ```solidity function createCategory( address _nft, uint256 _max, - uint256 _price + uint256 _price, + TokenType _tokenType ) ``` @@ -40,8 +47,9 @@ Initializes a category. | NFT | `address` | The NFT contract address. **CANNOT BE CHANGED AFTER INITIALIZATION** | | Max | `uint256` | The maximum amount of NFTs that a user is eligible to claim from the category | | Price | `uint256` | Amount to be paid in `paymentToken` to purchase an NFT | +| TokenType | `TokenType` | `ERC721` or `ERC1155` | -## `updateCategory` +### `updateCategory` ```solidity function updateCategory( @@ -59,7 +67,7 @@ Updates the properties of a specified category, **except for the NFT address**. | Max | `uint256` | The maximum amount of NFTs that a user is eligible to claim from the category | | Price | `uint256` | Amount to be paid in `paymentToken` to purchase an NFT | -## `configurePayment` +### `configurePayment` ```solidity function configurePayment(address _newToken, uint256[] memory _prices) @@ -72,7 +80,7 @@ This function allows changing the payment token and/or updates prices across all | Token | `address` | The ERC20 token address | | Prices | `uint256[]` | The length of the array must either be 0 or the total number of categories. This transaction reverts otherwise. | -## `revenuePayout` +### `revenuePayout` ```solidity function revenuePayout(address _beneficiary, address _token) @@ -85,7 +93,7 @@ The Vault owner calls this function to withdraw revenue out of the vault. | Beneficiary | `address` | The recipient address | | Token | `address` | The ERC20 token address | -## `recover` +### `recover` ```solidity function recover(uint256[] memory _categoryArr, address _recipient) @@ -97,7 +105,7 @@ The owner can invoke this method to withdraw remaining NFTs from one or more spe | Categories | `uint256[]` | One or more categories | | Recipient | `address` | The recipient address | -## `claimed` +### `claimed` ```solidity function claimed(address _user, uint256 _category) public view override returns (uint256[] memory) @@ -105,7 +113,7 @@ function claimed(address _user, uint256 _category) public view override returns Returns a list of token IDs that has been claimed by the `_user` from a specified `_category` -## `getClaimableIds` +### `getClaimableIds` ```solidity function getClaimableIds(uint256 _category) public view override returns (uint256[] memory) @@ -113,28 +121,28 @@ function getClaimableIds(uint256 _category) public view override returns (uint25 Returns a list of available token IDs from a specified `_category`. -## `getCategoryPrice` +### `getCategoryPrice` ```solidity function getCategoryPrice(uint256 _category) external view override returns (uint256) ``` Returns the amount of `paymentToken` required to purchase a single NFT from the specified `_category`. Call the `paymentToken()` method to get the ERC20 address of the payment token. -## `getCategoryNft` +### `getCategoryNft` ```solidity function getCategoryNft(uint256 _category) external view override returns (address) ``` Returns the address of the NFT contract from the specified `_category`. -## `getCategoryNftIds` +### `getCategoryNftIds` ```solidity function getCategoryNftIds(uint256 _category) external view returns (uint256[] memory) ``` Returns the list of token IDs that has been added into this category. This list excludes token IDs that had been recovered by the owner. -## `claimableCount` +### `claimableCount` ```solidity function claimableCount(uint256 _category) external view returns (uint256) @@ -142,6 +150,37 @@ function claimableCount(uint256 _category) external view returns (uint256) Return the number of available token IDs from a specified `_category`. +ERC1155: This method returns the total token amount to claim, spanned across all token IDs that are available. For example, if the vault contains 1 of token ID: 1 and 2 of token ID: 2, this method returns 3, since there are three tokens available to claim. + +--- +## ERC 1155 Compatibility + +This section describes the methods that are only valid for `categpry.tokenType == ERC1155`. + +### `claimedCount` + +```solidity +function claimedCount(address _user, uint256 _category) public view returns (uint256) +``` + +Returns the total number of NFTs that have been claimed by the _user from a specified _category + +### `getClaimableCountByIds` + +```solidity +function getClaimableCountByIds(uint256 _category, uint256[] calldata tokenIds) public view returns (uint256[] memory) +``` + +Returns an array of ERC1155 balance that are available to claim from a specified _category, with respect to the provided _tokenIds. + +### `getCategoryNftCountByIds` + +```solidity +function getCategoryNftCountByIds(uint256 _category, uint256[] memory _tokenIds) public view returns (uint256[] memory) +``` + +Returns an array of ERC1155 total balance recorded in a given _category, with respect to the provided _tokenIds. + --- This base contract can be extended to implement the `claim()` function. `claim()` functions are implemented differently by their templates. \ No newline at end of file From 56f086f3148c1893c7f286fd862d0f1c0c4bebb6 Mon Sep 17 00:00:00 2001 From: Preston Ong Date: Thu, 5 May 2022 13:11:37 +0800 Subject: [PATCH 3/5] added minter vault docs --- docs/nftfair/contracts/summary.md | 3 +- .../contracts/vault/templates/minter.md | 81 +++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 docs/nftfair/contracts/vault/templates/minter.md diff --git a/docs/nftfair/contracts/summary.md b/docs/nftfair/contracts/summary.md index b1bbd65d..3b5a7804 100644 --- a/docs/nftfair/contracts/summary.md +++ b/docs/nftfair/contracts/summary.md @@ -6,10 +6,11 @@ This documentation outlines the contract specification of the platform. The cont - `NFTFairTreasury` - The central contract that collects sales revenues generated from vaults, and other protocol-related payment. - `NFTFairVaultBase` - The base Vault contract that implements essential features of a vault, can be extended with additional implementations that are tailored to a specific template. -Currently, the platform supports the two templates: +Currently, the platform supports the following templates: - FIFO - Mystery Boxes +- Minter Vault We plan to add more templates in the future. diff --git a/docs/nftfair/contracts/vault/templates/minter.md b/docs/nftfair/contracts/vault/templates/minter.md new file mode 100644 index 00000000..dc525855 --- /dev/null +++ b/docs/nftfair/contracts/vault/templates/minter.md @@ -0,0 +1,81 @@ +# Minter Vault + +This vault extends the `NFTFairVaultBase` contract. However, there are several notable characteristics that set itself apart from the currently existing templates. Such differences are: +- The contract no longer holds pre-minted tokens, and will not accept any inbound token transfers. Calling the `onERC721Received` hook will cause a transaction to revert. +- The `ids` property of the Category object stores a list of token IDs that has been minted by the Vault. +- The `claimable_ids` property of the category object stores a list of pre-configured IDs that will be minted from the specified category. + +--- + +## Workflow + +The workflow to host a Fairdrop using this template does not deviate too far from the current workflow, except that it no longer requires the step of transferring tokens to the vault. + +The following briefly shows the steps of setting up a Fairdrop using this template: + +1. Deploy the Minter vault via the console. + +2. Deploy a contract that inherits either the `IERC721Mintable` or `IERC1155Mintable` interface + +3. Grant `MINTER_ROLE` permission to the Minter vault contract. + +4. Create one or more categories as usual. + +5. The vault is now ready to mint and distribute tokens. + +--- + +## Methods + +### Overloaded Methods + +The following functions inherited from the `NFTFairVaultBase` have been overloaded to suit the use case for this template. + +#### `getCategoryNftIds` + +```solidity +function getCategoryNftIds(uint256 _category) public view override returns (uint256[] memory) +``` + +Returns the list of all NFT IDs belonging to the specified `_category`. This implementation is slightly different from `NFTFairVaultBase` because the `category.ids` list only contains the list of IDs that were minted by users. The function concatenates the `category.ids` and `category.claimable_ids` lists to make a list of all IDs. + +#### `recover` + +```solidity +function recover(uint256[] memory _categoryArr, address _recipient) +``` + +This function results in the transaction to immediately revert, since, it is no longer necessary for the vault to recover any tokens. + +#### `onERC**Received` + +Same as `recover`. + +--- +### Set Category ID + +```solidity +function setCategoryIds(uint256 _category, uint256[] memory _ids, uint256[] memory _amounts) external +``` + +Use this method to assign token IDs to a category. This method must be invoked prior minting of tokens. + +| Parameter | Type | Description | +| --- | --- | --- | +| Category | `uint256` | The integer representation of a category | +| IDs | `uint256[]` | An array of token IDs to be added into the category | +| Amounts | `uint256[]` | The amount of corresponding `_ids` to be added into the category. Pass an empty array for ERC721 tokens | + +### Claim + +```solidity +function claim(uint256 _category, uint256 _deadline, bytes calldata _sig) external onlyConveyor +``` + +Mints and distributes a token to the user. The token ID is not revealed until the transaction is final. + +| Parameter | Type | Description | +| --- | --- | --- | +| Category | `uint256` | The integer representation of a category | +| Deadline | `uint256` | Transaction reverts at `block.timestamp > deadline` | +| Sig | `bytes` | The user's EIP712 message to authorize the Treasury for collecting the payment. You may pass `0x` if `paymentToken == address(0)` | diff --git a/mkdocs.yml b/mkdocs.yml index 3e348982..e1c320a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - Vault Templates: - FIFO Vault: ./nftfair/contracts/vault/templates/fifo.md - Mystery Boxes Vault: ./nftfair/contracts/vault/templates/mysteryboxes.md + - Minter Vault: ./nftfair/contracts/vault/templates/minter.md theme: From 3af13ba5d4a1f3fbb7746acec93ae5a4d611d710 Mon Sep 17 00:00:00 2001 From: Preston Ong Date: Thu, 5 May 2022 13:18:47 +0800 Subject: [PATCH 4/5] fixed formatting --- docs/nftfair/contracts/vault/templates/minter.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/nftfair/contracts/vault/templates/minter.md b/docs/nftfair/contracts/vault/templates/minter.md index dc525855..e7c04dbb 100644 --- a/docs/nftfair/contracts/vault/templates/minter.md +++ b/docs/nftfair/contracts/vault/templates/minter.md @@ -1,6 +1,7 @@ # Minter Vault This vault extends the `NFTFairVaultBase` contract. However, there are several notable characteristics that set itself apart from the currently existing templates. Such differences are: + - The contract no longer holds pre-minted tokens, and will not accept any inbound token transfers. Calling the `onERC721Received` hook will cause a transaction to revert. - The `ids` property of the Category object stores a list of token IDs that has been minted by the Vault. - The `claimable_ids` property of the category object stores a list of pre-configured IDs that will be minted from the specified category. @@ -13,7 +14,7 @@ The workflow to host a Fairdrop using this template does not deviate too far fro The following briefly shows the steps of setting up a Fairdrop using this template: -1. Deploy the Minter vault via the console. +1. Deploy a Minter vault. 2. Deploy a contract that inherits either the `IERC721Mintable` or `IERC1155Mintable` interface @@ -29,7 +30,7 @@ The following briefly shows the steps of setting up a Fairdrop using this templa ### Overloaded Methods -The following functions inherited from the `NFTFairVaultBase` have been overloaded to suit the use case for this template. +The following functions inherited from the `NFTFairVaultBase` have been overloaded to accommodate the use case for this template. #### `getCategoryNftIds` From 2650fcec1c945ecdb958ff341bcf01282806d17c Mon Sep 17 00:00:00 2001 From: Preston Ong Date: Thu, 12 May 2022 13:27:46 +0800 Subject: [PATCH 5/5] added polygon addresses and minter deprecation notice --- docs/nftfair/contracts/summary.md | 18 ++++++++++++++---- .../contracts/vault/templates/minter.md | 2 ++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/nftfair/contracts/summary.md b/docs/nftfair/contracts/summary.md index 3b5a7804..cd98a311 100644 --- a/docs/nftfair/contracts/summary.md +++ b/docs/nftfair/contracts/summary.md @@ -10,10 +10,12 @@ Currently, the platform supports the following templates: - FIFO - Mystery Boxes -- Minter Vault +- Minter Vault* We plan to add more templates in the future. +*- The Minter vault is currently operating as it's own independent template at the moment. We planned to build the minting functionaiity on top of the existing templates in the short future. Keep an eye for an update. + --- # Addresses @@ -22,6 +24,14 @@ We plan to add more templates in the future. | Contract | Address | | --- | --- | -| `NFTFairFactory` | [0x67F7e0C322a067C70e1eE99873Fe4163f4A02edD](https://bscscan.com/address/0x67f7e0c322a067c70e1ee99873fe4163f4a02edd) | -| `NFTFairProxy` | [0x062154774E1726246c75A4e8f05EDC675d8B39a1](https://bscscan.com/address/0x062154774E1726246c75A4e8f05EDC675d8B39a1) | -| `NFTFairTreasury` | [0x39c805A56EeF49BcD7C6c14d5dcf6e7f0daf63A4](https://bscscan.com/address/0x39c805A56EeF49BcD7C6c14d5dcf6e7f0daf63A4) \ No newline at end of file +| `NFTFairFactory (Implementation)` | [0x67F7e0C322a067C70e1eE99873Fe4163f4A02edD](https://bscscan.com/address/0x67f7e0c322a067c70e1ee99873fe4163f4a02edd) | +| `NFTFairFactory (Proxy)` | [0x062154774E1726246c75A4e8f05EDC675d8B39a1](https://bscscan.com/address/0x062154774E1726246c75A4e8f05EDC675d8B39a1) | +| `NFTFairTreasury` | [0x39c805A56EeF49BcD7C6c14d5dcf6e7f0daf63A4](https://bscscan.com/address/0x39c805A56EeF49BcD7C6c14d5dcf6e7f0daf63A4) | + +## Polygon PoS + +| Contract | Address | +| --- | --- | +| `NFTFairFactory (Implementation)` | [0xA97B472406b65e57D58E735D78E80e5586c1b526](https://polygonscan.com/address/0xa97b472406b65e57d58e735d78e80e5586c1b526) | +| `NFTFairFactory (Proxy)` | [0x062154774E1726246c75A4e8f05EDC675d8B39a1](https://polygonscan.com/address/0x062154774E1726246c75A4e8f05EDC675d8B39a1) | +| `NFTFairTreasury` | [0x514397BA31975E39c90475425bC8F3F26b313ed7](https://polygonscan.com/address/0x514397ba31975e39c90475425bc8f3f26b313ed7) | \ No newline at end of file diff --git a/docs/nftfair/contracts/vault/templates/minter.md b/docs/nftfair/contracts/vault/templates/minter.md index e7c04dbb..fa48f37c 100644 --- a/docs/nftfair/contracts/vault/templates/minter.md +++ b/docs/nftfair/contracts/vault/templates/minter.md @@ -1,5 +1,7 @@ # Minter Vault +:warning: **Note:** This template will be deprecated soon. We planned on adding the minting function on top of the existing FIFO and mystery box templates. At that point, this template will be removed from the Factory. + This vault extends the `NFTFairVaultBase` contract. However, there are several notable characteristics that set itself apart from the currently existing templates. Such differences are: - The contract no longer holds pre-minted tokens, and will not accept any inbound token transfers. Calling the `onERC721Received` hook will cause a transaction to revert.