[DEV-290] NFTFair Docs Update

docs/nftfair/contracts/summary.md

@@ -6,13 +6,16 @@ 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.
 
+*- 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
@@ -21,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)
+| `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) |

docs/nftfair/contracts/vault/base.md

@@ -4,32 +4,39 @@ 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;
 }
 ```
 
 | 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,51 +105,82 @@ 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)
 ```
 
 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)
 ```
 
 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)
 ```
 
 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.

docs/nftfair/contracts/vault/templates/minter.md

@@ -0,0 +1,84 @@
+# 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.
+- 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 a Minter vault.
+
+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 accommodate 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)` |

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:

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
   - AnyDAO:
     - Introduction: ./anydao/introduction.md
     - Design: ./anydao/design.md