@iqprotocol/solidity-contracts-nft NPM

IQ Protocol NFT

Docs

Contract documentation

Setup

Clone repository
Run yarn

Compilation

yarn compile

Testing

yarn test

Generate docs

pip install -r requirements.txt
yarn hardhato docgen
mkdocs serve

Deployment

The deployment process is automated via hardhat tasks, which can be found under tasks/deployment directory. Process of registration the full dataset required for testing is exampled below.

Parameters

All deployment tasks have following optional parameters: 1. unsafe defines way of deployment (by default: false) 2. ignore-cache defines usage of deployment cache (by default: true) 3. is-serial-deployment defines usage of how many deployments would be (by default: false) 3. clear-cache defines pre-deployment cache cleaning (by default: false)

Networks

Currently the following networks are supported:

Polygon Mumbai Testnet (mumbaiTestnet)
BSC Testnet (bscTestnet)
Polygon
BSC Mainnet

Creating environemnt

Create a .env file that resembles the .env.example file in the current directory.

# .env.example parameters FAQ

### Ethereum Private Key
DEPLOYMENT_PRIVATE_KEY=0xabc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1
### For PRC calls project is using Ankr: https://www.ankr.com/
ANKR_PROJECT_KEY=basdkjbaskdbaksdbaksdbakjsbdaksdkabsdkasbdkjabsdkjabdkjabsdkabks
### PolygonScan API Key: https://docs.polygonscan.com/getting-started/viewing-api-usage-statistics
ETHERSCAN_API_KEY_POLYGON=NAKJDNASNDASNDAJNEQOWNEIOQWASDLASD
### BscScan API Key: https://docs.bscscan.com/getting-started/viewing-api-usage-statistics
ETHERSCAN_API_KEY_BSC=NASFDNAOISDNQOWINEOIQWNASNDKJANSDA

Flow 1 - using custom Hardhat Runtime Environemnt tasks

Deploy ERC20 contract

yarn hardhat deploy:test:mock:erc20 --network [network name] --name [erc20 name] --symbol [erc20 symbol] --decimals [erc20 decimals] --total-supply [erc20 total supply]

Example:

yarn hardhat deploy:test:mock:erc20 --network bscTestnet --name BscCoin --symbol BCC --decimals 18 --total-supply 1000000000000 --ignore-cache false --is-serial-deployment true

Deploy ACL contract

yarn hardhat deploy:acl --network [network name]

Example:

yarn hardhat deploy:acl --network bscTestnet --ignore-cache false --is-serial-deployment true

Initial deployment

yarn hardhat deploy:initial-deployment --network [network name] --acl [address] --base-token [address] --protocol-external-fees-collector [address]

Example:

yarn hardhat deploy:initial-deployment --network bscTestnet --acl 0x0000000000000000000000000000000000000000 --base-token 0x0000000000000000000000000000000000000000 --protocol-external-fees-collector 0x0000000000000000000000000000000000000000 --ignore-cache false

Upgrades

Beware: Upgrading smart contracts requires extra caution, as this can lead to data loss and break the protocol.

Some protocol contracts are upgradeable. This allows extending functionality and fixing the security issues. The upgradeability process can be automated via hardhat tasks. You can find some examples of upgrade tasks under tasks/upgrades directory. In order to reduce the risks, the protocol relies on OZ Upgrades Plugin for deploying and upgrading contracts.

List of upgradeable contracts

accounting/distributors/ERC20RewardDistributor.sol
accounting/TokenQuote.sol
acl/ACL.sol
asset/AssetClassRegistry.sol
listing/listing-configurator/ListingConfiguratorPresetFactory.sol
listing/listing-configurator/ListingConfiguratorRegistry.sol
listing/listing-strategies/fixed-rate/FixedRateListingController.sol
listing/listing-strategies/fixed-rate-with-reward/FixedRateWithRewardListingController.sol
listing/listing-manager/ListingManager.sol
listing/listing-strategy-registry/ListingStrategyRegistry.sol
listing/listing-terms-registry/ListingTermsRegistry.sol
metahub/core/Metahub.sol
renting/renting-manager/RentingManager.sol
tax/tax-strategies/fixed-rate/FixedRateTaxController.sol
tax/tax-strategies/fixed-rate-with-reward/FixedRateWithRewardTaxController.sol
tax/tax-strategy-registry/TaxStrategyRegistry.sol
tax/tax-terms-registry/TaxTermsRegistry.sol
universe/universe-registry/UniverseRegistry.sol
warper/preset-factory/WarperPresetFactory.sol
warper/warper-manager/WarperManager.sol

Tasks

Many of the protocol maintenance routines are automated using hardhat tasks. Find the list of available commands by running:

hardhat --help

Toolkit

In order to simplify different workflows with smart contracts, which can be found under tasks/toolkit directory.

data-checks: Tasks for post-deployment checking.
data-model-dump: Tasks for generating data model changes cache.
data-registration: Tasks for registering connections between different controller contracts and registries during deployment.
datagen: Tasks for generating dummy data for showcase purposes.
deployment-cache: Tasks for interacting with contracts deployment data caching mechanisms.

Data Checks (`./tasks/toolkit/data-checks`)

In order to simplify post deployment checks contracts set and automate process of data validation in a chain agnostic and extendable way there is a set of tasks, which can be found under tasks/toolkit/data-checks directory.

Check that all required data was registered and contract registered filled with correct data

yarn hardhat toolkit:checks:all --network [network name]

Check that certain contract entity was registered

yarn hardhat toolkit:checks:check-registered-entity --network [network name] --contract-name [name of the contract] --contract-registry [address of metahub] --contract-key [unique contract entity key] --expected-contract-address [address of contract]

Check contract registry that all contracts were registered using deployment-cache data from ./active-deployment/[networkName]

yarn hardhat toolkit:checks:check-registry --network [network name]

Check that ERC721 Configurable Preset was registered

yarn hardhat toolkit:checks:check-registered-erc721-configurable-preset --network [network name] --warper-preset-factory [address] --erc721-configurable-preset [address]

Check that ERC721 Asset Class was registered

yarn hardhat toolkit:checks:check-registered-erc721-asset-class --network [network name] --asset-class-registry [address]

Check that FixedRate listing controller was registered

yarn hardhat toolkit:checks:check-registered-fixed-rate-listing-controller --network [network name] --listing-strategy-registry [address] --fixed-rate-listing-controller [address]

Check that FixedRateWithReward listing controller was registered

yarn hardhat toolkit:checks:check-registered-fixed-rate-listing-controller --network [network name] --listing-strategy-registry [address] --fixed-rate-with-reward-listing-controller [address]

Check that FixedRate tax controller was registered

yarn hardhat toolkit:checks:check-registered-fixed-rate-tax-controller --network [network name] --tax-strategy-registry [address] --fixed-rate-tax-controller [address]

Check that FixedRateWithReward tax controller was registered

yarn hardhat toolkit:checks:check-registered-fixed-rate-with-reward-tax-controller --network [network name] --tax-strategy-registry [address] --fixed-rate-with-reward-tax-controller [address]

Check that GeneralGuildPreset was registered

yarn hardhat toolkit:checks:check-registered-guild-preset --network [network name] --listing-configurator-preset-factory [address] --general-guild-preset [address]

Data Model Dump (`./tasks/toolkit/data-model-dump`)

In order to make smart contract structs, events, functions and other structure dependent changeable parts more visible for overview and comparison with previous versions, there is a set of tasks, which can be found under tasks/toolkit/.

Tasks are developed using @solidity-parser/parser @solidity-parser/parser library, that gives an opportunity to parse and interact with Solidity AST Nodes.

Create fresh dump of smart contracts using contract files from ./contracts/ and their artifacts from ./artifacts/contracts

yarn hardhat toolkit:dump:create

Compare two different versions of dumps or version from dump and actual contracts from ./contracts/

# 'version1' is option, 'version2' is required

yarn hardhat toolkit:dump:compare --version1 ['latest' by default] --version2 ['undefined' by default]

Example of 'version*' field variations

latest: contracts from ./contracts/ directory would be taken.
x.x.x: contracts from ./data-model-dump/latest or ./data-model-dump/history would be taked.
undefined: would lead to an error.

Datagen (`./tasks/toolkit/datagen`)

In order to simplify testing on testnet/mainnet networks there is set of tasks, which can be found under tasks/toolkit/datagen directory.

Detailed flow (Multiple steps)

Define protocol tax terms

yarn hardhat toolkit:datagen:register-protocol-terms --network [network name] --metahub [address]

This will set protocol tax terms to default values 25% for listing fees and 50% for tournament reward fees.

Or setup custom fee:

yarn hardhat toolkit:datagen:register-protocol-terms --network [network name] --metahub [address] --base-tax-rate 10 --reward-tax-rate 15

Where --base-tax-rate and --reward-tax-rate parameters are percentage and has maximum value of 100.

Deploy mock of Universe Token

yarn hardhat toolkit:deploy:test:mock:erc721 --network [network name] --name UniverseName --symbol UNIS

Setup Universe and Warper

yarn hardhat toolkit:datagen:setup-universe-and-warper --network [network name] --metahub [address] --universe-token [address] --base-token [address] --universe-name UniverseName

This will set universe tax terms to default values 25% for listing fees and 50% for tournament reward fees and other parameters for default values. More details can be found in tasks/datagen/setup-universe-and-warper.ts file.

Or setup custom parameters (if you already have a warper):

yarn hardhat datagen:setup-universe-and-warper --network [network name] --metahub [address] --universe-token [address] --base-token [address] --universe-name UniverseName --existing-warper-address [address] --base-tax-rate 20 --reward-tax-rate 40 --payment-tokens ["0x0000000000000000000000000000000000000000"] --warper-name WarperName --warper-preset-id 0x0000000000000000000000000000000000000000 --warper-init-data 0x0000000000000000000000000000000000000000 --warper-paused false

Mint tokens

yarn hardhat datagen:mint-tokens --network [network name] --metahub [address] --universe-token [address] --nft-collection-size 2

Creating listing

yarn hardhat datagen:list --network [network name] --metahub [address] --universe-token [address] --universe-id 1 --token-id 1

Or setup custom parameters:

yarn hardhat datagen:list --network [network name] --metahub [address] --universe-token [address] --universe-id 1 --token-id 1 --base-fee 100 --reward-fee 25 --max-lock-period 36000 --immediate-payout false --configurator [address]

Creating renting

l [network name] --metahub [address] --listing-id 1 --listing-terms-id 1 --warper [addresss] --payment-token [addresss]

Or setup custom parameters:

yarn hardhat datagen:rent --network [network name] --metahub [address] --listing-id 1 --listing-terms-id 1 --warper [addresss] --payment-token [addresss] --rental-period 36000

Simple flow (2 steps)

Deploy mock of Universe Token

yarn hardhat deploy:test:mock:erc721 --network [network name] --name UniverseName --symbol UNIS

Deploy mock of Universe Token

yarn hardhat datagen:initialize --network [network name] --metahub [address] --base-token [address] --universe-token [address]

Testing purposes (for testnet deployments)

A payment token: yarn hardhat --network [network name] deploy:mock:ERC20 --name USDC --symbol USDC
An NFT collection: yarn hardhat --network [network name] deploy:mock:ERC721-internal-tests --name TEST --symbol TT

Publish to NPM

manually update the version in package.json
yarn build
yarn run publish

Manual contract verification

Every time the deployment command is executed, a new set of deployment artifacts is created under deployments/<network>. The deployments/<network>/solcInputs directory will contain a new Standard JSON-input file which can be used for contract verification.
Verifying Metahub requires extra care. It uses dynamically linked libraries, but those do not get attached to the deployment artifact. It means that you need to edit this JSON field manually and add the deployed library addresses:

...
  "settings": {
    "optimizer": {
      "enabled": true,
      "runs": 200
    },
    "outputSelection": {
      "*": {
        "*": [
          "storageLayout",
          "abi",
          "evm.bytecode",
          "evm.deployedBytecode",
          "evm.methodIdentifiers",
          "metadata",
          "devdoc",
          "userdoc",
          "evm.gasEstimates"
        ],
        "": [
          "ast"
        ]
      }
    },
    "metadata": {
      "useLiteralContent": true
    },
    // This is the part you need to add manually
    "libraries": {
      "contracts/renting/Rentings.sol": {
        // The addresses get logged to the terminal when deploying the Metahub contract.
        "Rentings": "0xF6188F991962dBcEF5621312515BeEE566989Df0"
      },
      "contracts/listing/Listings.sol": {
        "Listings": "0xd0bdF81Aca69FC6B28de655c0464451f25A0cdfA"
      },
      "contracts/asset/Assets.sol": {
        "Assets": "0x4778CE9b59c5E9e287Ed50f4671c98F4b7557A72"
      },
      "contracts/warper/Warpers.sol": {
        "Warpers": "0x529Bd1D28bECeC204a817D2dE6530638A8AEda72"
      },
      "contracts/accounting/Accounts.sol": {
        "Accounts": "0xD40925d61751BDFab9ff4b163a3793177EbDc0AA"
      }
    }
  }
...