Belong.net

Install Node.js, npm, yarn

• Download the LTS (Long Term Support) version for your operating system from Node.js official website.

• Install this version.

• Verify node.js installation:

$ node -v

Example output:

$ v16.x.x or higher

• Verify npm installation:

$ npm -v

Example output:

$ v16.x.x or higher

• Install yarn:

$ npm install --global yarn

• Verify installation:

$ yarn -v

HardHat Usage

Check HardHat guide.

Foundry Usage

Check Foundry guide.

Project Overview

The protocol allows users to create their own NFT collection, whose tokens represent invitations to the corresponding hub (community). All the collections are deployed via the Factory contract. Users must specify the name, the symbol, contractURI, paying token address, mint price, whitelist mint price, max collection size and the flag which shows if NFTs of the collection will be transferable or not. The name, symbol, contractURI and other parameters (such a royalties size and its receiver) need to be moderated on the backend, so BE’s signature will be needed for the collection deployment. Factory will be deployed via proxy.

Proxy deploymet

Proxy deployment consists of 4 steps:

• deployment of Implementation contract
• deployment of Proxy contract
• deployment of ProxyAdmin contract (the smart contract which will manage all of the proxies deployed from the wallet, it has Ownable modifier, and the Ownership can be transferred)
• then ProxyAdmin address will be stored in config file in the repo, and further deployment of upgrading proxies or deploying new projects will be held by it

Initialization:

• connecting Implementation to Proxy through ProxyAdmin
• initialization of Proxy usign delegate call

1. Functional Requirements

1.1. Roles

Belong NFT project has several roles:

1. The owner: Controls the platform commission, can configure Factory contract.
2. Creator: Collection creator can set the mint prices and the paying token of his/her collection. He/she will receive funds from primary sales and some fraction of royalties from secondary sales
3. Platform address: Receives the royalties from the secondary sales and commissions from primary sales
4. Signer: The platform’s BE which moderates the data and gives its approval if requirements are met
5. User: Can create his/her own collection (with signer’s approval), mint tokens in his own or other collections (with signer’s approval)

1.2. Features

Belong NFT project has the following features:

• Create a new collection. (Everyone with signer’s approval)
• Get the information about the deployed collections. (Everyone)
• Mint token from any collection. (Everyone with signer’s approval)
• Send funds from primary and secondary sales to platform’s and creators' wallets (Everyone)
• Set paying token (Collection owner)
• Set mint price (Collection owner)
• Set platform commission (The owner)
• Set platform address in the Factory contract (The owner)
• Set signer address in the Factory contract (The owner)

1.3 Use Cases

At the beginning, three smart contracts are deployed at the network:

• ReceiverFactory (creates nfts of royalties receivers)
• Factory (creates nfts of NFT collections)

Collection creation

1. Creator specifies the settings of his collection (name, symbol, contractURI with royalty information, mint price, whitelisted mint price, paying token, royalties and “transferable” flag) on the front-end
2. Creator deploys the RoyaltiesReceiver contract with deployReceiver() function of ReceiverFactory contract. BE (which is subscribed to the ReceiverFactory's events) checks it it was deployed.
3. The BE checks if name, symbol and royalties size comply with the rules
4. BE creates contractURI JSON file and uploads it to some hosting (the fee_recipient field must be equal to the RoyaltiesReceiver address)
5. BE signs the collection data
6. Now the creator can call produce() function on Factory contract. A new nft collection will be deployed.

Additional case - Referral System:

• Any user can create his own referral code.

1. This code can be shared to creator.
2. Creator can use this code during the collection creation.
3. Now the referral code creator are attached to this collection.
4. The referral code creator will receive the percentage of the comission from mint tokens.

Mint token from the collection

1. If some other user wants to mint a new token in this collection, his/her account will have to be validated by the BE
2. BE generates tokenURI for the new token
3. If the account meets all the requirements and tokenURI is successfully generated, the BE signs the data for mint. Also, if the user is in the whitelist, BE can specify it with whitelisted flag
4. The user calls the mint functions of the NFT contract

If a mint price is greater than zero, the contract will handle payments in either Native currency or ERC20 tokens. For every primary sale, a portion of the payment is immediately sent to the platform as a commission, while the remainder is transferred to the creator. If referral code shared to the creator, and this code was used, then some percentage from platform commissions will be transfered to the referral code creator.

• The factory owner can set or change the platform commission.
• The collection creator can modify the paying token and adjust the mint prices for both regular and whitelisted users.

At deployment, NFTs can be marked as non-transferable, which means that no token in the collection can be transferred or sold. This transferability setting is immutable and cannot be changed later.

For secondary sales (e.g., through a marketplace), a corresponding RoyaltiesReceiver contract ensures royalties are properly distributed between the creator and the platform.

In batch minting operations, the contract supports both static and dynamic pricing.

• For static price minting, the price for each NFT is determined based on the user's whitelist status.
• For dynamic price minting, each NFT can have its own custom price.

The contract validates signatures to ensure authorized minting and handles payments by checking the expected mint price and paying token. If the price changes or an incorrect token is used, the mint will fail. Royalties and platform commissions are calculated and distributed accordingly.

2. Technical Requirements

2.1. Architecture Overview

• StaticPrice

  

• DynamicPrice

  

• ReferralSystem

  

• RoyaltiesReceiverFlow

  

2.2. Contracts

This section contains detailed information (their purpose, assets, functions, and events) about the contracts used in the project.

2.2.1. NFT

• NFT contract

Implements the minting and transfer functionality for NFTs, including transfer validation and royalty management.

• BaseERC721 contract

A base contract for ERC721 tokens that supports royalties, transfer validation, and metadata management.

• CreatorToken contract

Contract that enables the use of a transfer validator to validate token transfers.

• AutoValidatorTransferApprove contract

Base contract mix-in that provides functionality to automatically approve a 721-C transfer validator implementation for transfers.

2.2.2. NFTFactory

• NFTFactory contract

A factory contract to create new NFT instances with specific parameters.

• ReferralSystem contract

Provides referral system functionality, including creating referral codes, setting users, and managing referral percentages.

2.2.4. RoyaltiesReceiver

A contract for managing and releasing royalty payments in both native Ether and ERC20 tokens.

In our case, the receivers will be a creator and the platform address. The sum of both shares must be equal to 10000. Because of that the specified creator royalties and platform fees must be converted to shares with the next formulas:

platform_shares = 10000/(x/p + 1) creator_shares = 10000 - platform_shares

where x - creators’s BPs (input on FE) p - platform fee BPs (default is 100)

2.2.5. ReceiverFactory

A factory contract for creating instances of the RoyaltiesReceiver contract.

2.3. Intefaces

This section contains detailed information (their purpose and functions) about the interfaces used in the project.

2.3.1. ICreatorToken Interface

Interface for managing transfer validators for tokens

2.3.2. ITransferValidator721 Interface

Interface for validating NFT transfers for ERC721 tokens

3. Additional Explanations

3.1. Platform Comission and Royalties

For every NFT contract deployed feeReceiver and feeNumerator parameters are used during its construction. These parameters do not affect the internal logic in any significant way and only used to apply with ERC2981 standart

Whether ERC2981 is enforced and used or not is entirely up to third parties (NFT marketplaces)

Considering mint fees - a different logic is used: Each time a mint() function is called on any NFT contract - given NFT contract receives two parameters from Factory contract These parameters are: platformCommission and platformAddress Based on these parameters mint fees are enforced

Smart Contract

Conditions under which Treasury is created

1. mintPrice=0&Royalties=0 => Create Contract (feeReciever='address user wallet')
2. mintPrice=0.01&Royalties=0(+2% platform fee) => Create fee reciever
3. mintPrice=0.01&Royalties=1(+2% platform fee) => Create fee reciever
4. mintPrice=0&Royalties=1(+2% platform fee) => Create fee reciever