ERC1155Base

Overview

The ERC1155Base smart contract implements the ERC1155 multi-token standard, complemented by the ERC2981 royalty standard for optimized royalty handling. This base preset contract facilitates the minting of tokens directly to any address and enables the sale of these tokens on a marketplace such as Ninfa's OnChainMarketplace, potentially minting directly to the marketplace's address without requiring a separate transaction.

ERC1155Base serves as a robust foundation for building a versatile ERC-1155 token system. It integrates multiple important features and extensions, providing a comprehensive solution for projects requiring a high degree of customization and utility.

View on GitHub

Usage

import "@ninfa-labs/src/token/ERC1155/presets/ERC1155Base.sol";

All contracts can be imported as libraries. However, not all functions may be overridable or callable internally by child implementations for efficiency reasons. Therefore, it may be best to clone the contracts repository in cases where modifying the base implementation itself is required.

For these reasons, the virtual function modifier has been added only where strictly necessary, specifically on all internal extensions' functions and in the initialize() function for ERC1155Base, as overriding it is most likely needed by most child contracts.

Here is how to import the contract and inherit from it:

contract MyToken is ERC1155Base {
    
    /// @dev OPTIONAL override initialize() in order to override or extend setup logic
    function initialize(bytes memory _data) public override(ERC1155Base) {
        // logic can be extended or overridden in this function
        // super.initialize(_data);
    }

    constructor(address factory_) ERC1155Base(factory_) { }
}

See ERC1155LazyMint for an example of a preset contract inheriting from ERC1155Base.

Extensions

ERC1155Base inherits from multiple contracts to provide a wide range of functionalities:

• AccessControl: Manages roles and permissions.

• ERC1155Burnable: Allows tokens to be burnt, removing them permanently.

• ERC1155Royalty: Implements ERC-2981 to handle royalty information for secondary sales.

• ERC1155Metadata_URI: Manages token metadata.

• ERC1155Supply: Tracks tokens on-chain to provide a list of tokens per type and total supply.

When deploying or extending ERC1155Base, you initialize it with the address of a factory contract which is used for creating new instances.

Minting Tokens

The ERC1155Base smart contract implements the ERC1155 multi-token standard and enhances it with additional features such as royalty handling through the ERC2981 standard, metadata management, and on-chain supply tracking. This setup facilitates a flexible and robust environment for creating a variety of token types—from fungible to non-fungible tokens (NFTs).

Mint Function:

solidityCopy codefunction mint(address _to, uint256 _value, bytes calldata _data) external onlyRole(MINTER_ROLE)

• _to: Recipient of the newly minted tokens.

• _value: Quantity of each token type to mint.

• _data: Encoded data that typically includes token URI, royalty recipients, and royalty basis points.

Data Handling by Extensions

When a mint operation is initiated, the _data passed to the mint function is intricately handled by various extensions of the ERC1155Base contract, each tailored to address specific aspects of the token's properties and functionalities:

ERC1155Metadata_URI:

Token URI Management: This extension decodes the first part of _data to extract the token URI, which is essential for identifying and retrieving the token's metadata. The URI is converted from an IPFS hash to a bytes32 format using the getBytes32FromIpfsHash function, which handles the conversion process by decoding from base58, removing specific bytes, and then re-encoding in order to fit its value in 32 bytes neatly and hence requiring half the gas to write the URI to storage.

This is how to generate the token URI using JavaScript:

const getBytes32FromIpfsHash = hash => {
     let bytes = bs58.decode(hash);
     bytes = bytes.slice(2, bytes.length);
     let hexString = web3.utils.bytesToHex(bytes);
     return web3.utils.hexToNumber(hexString);
 };

Refer to the {ERC1155Metadata_URI-uri} implementation to see how the token URI is decoded in Solidity.

ERC1155Royalty:

• Royalty Configuration: Further processing of _data extracts information about royalty recipients and the royalty percentage (basis points). This setup is critical for ensuring that the creators or designated parties receive royalties from secondary sales. The royalty information is stored and managed to comply with the ERC2981 standard, which is widely supported by NFT marketplaces.

ERC1155Supply:

• Supply Management: This extension does not directly process _data but updates the supply tracking as new tokens are minted. It ensures that the total supply of each token type is accurately recorded and available for on-chain queries, supporting functionalities like showing how many tokens exist for each type.

Managing Royalties

ERC1155Base supports both default and token-specific royalties:

Setting Default Royalty:

function setDefaultRoyalty(address _receiver, uint96 _feeNumerator) external onlyRole(DEFAULT_ADMIN_ROLE)

• _receiver: Address to receive royalty payments.

• _feeNumerator: Royalty percentage, represented in basis points.

Setting Token-Specific Royalty:

function setTokenRoyalty(uint256 _tokenId, address _receiver, uint96 _feeNumerator) external onlyRole(DEFAULT_ADMIN_ROLE)

• _tokenId: Specific token ID for which to set the royalty.

• _receiver, _feeNumerator: Same as default royalty.

Token Metadata Management

Metadata URI can be set and updated, providing flexibility in how token information is presented and stored.

Setting Base URI:

function setBaseURI(string calldata baseURI_) external onlyRole(DEFAULT_ADMIN_ROLE)

• baseURI_: The base URL that will prepend token IDs to generate the full token URI.

Burning Tokens

Tokens can be burnt to reduce supply or remove tokens from circulation, which is handled by the ERC1155Burnable extension.

Burn Function:

function _burn(uint256 _tokenId, uint256 _value) internal override

• _tokenId: ID of the token to burn.

• _value: Quantity of tokens to burn.

Initialization and Role Management

During deployment or through specific factory patterns, the contract is initialized to set up roles and permissions, ensuring that only authorized users can perform certain actions.

Initialization:

function initialize(bytes memory _data) public virtual

• _data: Encoded initialization parameters including the deployer's address, default royalty information, token symbol, and name.

Additional Functionalities

• Role-Based Access Control: Through AccessControl, different roles such as minter, curator, or admin can be managed.

• Token Existence Check: Function to verify if a specific token ID exists.

• ERC-165 Support: To ensure the contract's interfaces are discoverable and compliant with the standard.

Conclusion

By utilizing ERC1155Base, developers can deploy a customizable, feature-rich ERC-1155 token contract suited for various use cases including gaming, virtual items, or any other digital assets requiring flexible ownership and royalty management. This guide should serve as a foundational resource for effectively deploying and managing a multi-token project using the ERC1155Base smart contract.