NFT Blind Box Implementation Plan

The uniqueness of NFTs primarily comes from the fact that each token has a tokenID in the smart contract that represents it, allowing for the setting of attributes for the token through the tokenID, which are described as metadata json. As shown in the code below:

mapping(uint256 => string) private _tokenURIs;

The key of _tokenURIs is the tokenID, and the value is the address of the metadata json file.

The metadata json file stores information such as the image resource address of the NFT. To achieve the essence of blind boxes, a default metadata json file address can be set for all blind boxes before they are opened, or no address can be set, and the specific file address can be returned when the blind box is opened.

function tokenURI(uint256 tokenId) public view override returns (string memory) {
  // Default file address
  if (!canOpen) return unrevealURI;
  // Specific file address
  return _tokenURIs[tokenId];
}

Solution 1: Direct Setting#

Before opening the blind boxes, the project team first prepares the metadata json files corresponding to each tokenID. The file names are ${tokenID}.json, and then these files are placed in a folder and stored in ipfs. The files can be accessed via ipfs://{folder's CID}/${tokenID}.json.

At the same time, the baseURL ( ipfs://{folder's CID}/) of the files is saved in the smart contract. When opening the blind boxes, the address can be concatenated directly to achieve the purpose of opening the blind boxes.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.15;

import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/contracts/utils/Counters.sol";
import "@openzeppelin/contracts/utils/Strings.sol";

contract GameItem is ERC721URIStorage {
  using Counters for Counters.Counter;
  
  // Incremental tokenId
  Counters.Counter private _tokenIds;
  
  // Whether blind boxes can be opened
  bool public canOpen = false;

  constructor() ERC721("GameItem", "ITM") {}

  function tokenURI(uint256 tokenId) public view override returns (string memory) {
    // Check if blind boxes can be opened
    require(canOpen, 'can not open now');
    // Ensure it has been minted
    require(_exists(tokenId), 'token not minted');

    string memory baseURI = _baseURI();
    if (bytes(baseURI).length > 0) {
        // Concatenate json file address
        string memory path = string.concat(baseURI, Strings.toString(tokenId));
        return string.concat(path, '.json');
    } else {
        return '';
    }
  }
}

Although this method requires low gas, there is a significant problem: how to prove that the images after the project team opens the boxes are determined before sale. For example, if the project team sells 10 blind boxes, the images of these 10 blind boxes should be determined before the boxes are opened. However, the current solution cannot ensure this; after the blind boxes are sold and not opened, the project team can freely swap or change the content of the files. For instance, they could swap the contents of box 3 and box 5, while the corresponding tokenURI remains unchanged.

Another issue is that the attribute correspondence of the nft is artificially fabricated and not truly random.

Solution 2: Random Number + Shuffling Algorithm#

When the project team has prepared the configuration files for the nft and uploaded them to ipfs, they can solve the randomness issue by randomly selecting non-repeating files from the file pool when opening the blind boxes. For example, when a user opens box 1, the randomly corresponding configuration file address could be ipfs://{folder's CID}/5.json. This can somewhat solve the randomness issue of solution one.

Next is the setting of baseURI. Due to the uniqueness of ipfs, the CID of the folder is determined by its internal files; once the internal files are modified, the CID of the folder will inevitably change. Therefore, to prevent modification of file content, the baseURI needs to be set when deploying the smart contract, and it should be unmodifiable.

There are two issues to address for solution two:

How to obtain random numbers - chainlink
How to draw files without repetition - shuffling algorithm

Random Number#

Use the chainlink service to obtain random numbers: create a subscription at https://vrf.chain.link/ to get a subscription ID. Recharge link tokens in this subscription (each time a random number is obtained, LINK tokens are consumed), and finally bind the contract address.

If your project uses the hardhat framework, you need to install the chainlink contract library.

$ yarn add @chainlink/contracts

Example of obtaining random numbers:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol";
import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol";

contract RoboNFT is VRFConsumerBaseV2 {
  // Coordinator
  VRFCoordinatorV2Interface COORDINATOR;

  struct ChainlinkParams {
    // Subscription ID
    uint64 subId;
    // Gas channel to use
    // Different networks' gas channels: https://docs.chain.link/docs/vrf-contracts/#configurations
    bytes32 keyHash;
    // Gas limit for callback, value depends on the number of random numbers to be obtained
    // Obtaining one random number requires 20000 wei
    uint32 gasLimit;
    // Number of confirmations for request - set to 3
    uint16 requestConfirms;
    // Number of random numbers obtained per request
    uint32 numWords;
  }
  ChainlinkParams public chainlinkParams;

  // Array to store returned random numbers
  uint256[] public randomNums;

  // _vrfCoordinator is the coordinator address, see different network addresses at https://docs.chain.link/docs/vrf-contracts/#configurations
  constructor(
    ChainlinkParams memory _chainlinkParams,
    address _vrfCoordinator
  ) VRFConsumerBaseV2(_vrfCoordinator) {
    // Create coordinator contract instance
    COORDINATOR = VRFCoordinatorV2Interface(_vrfCoordinator);
    // Initialize chainlink parameters
    chainlinkParams = _chainlinkParams;
  }

  // Request random numbers (wallet must have sufficient LINK tokens)
  function requestRandomWords() external {
    // Request random numbers through the coordinator and return the request ID
    uint requestId  = COORDINATOR.requestRandomWords(
      chainlinkParams.keyHash,
      chainlinkParams.subId,
      chainlinkParams.requestConfirms,
      chainlinkParams.gasLimit,
      chainlinkParams.numWords
    );
  }

  // Chainlink callback, passing in request ID and random numbers
  function fulfillRandomWords(
    uint256 requestId,
    uint256[] memory randomWords
  ) internal override {
  	// Obtained random numbers
    randomNums = randomWords;
  }
}

Shuffling Algorithm#

The shuffling algorithm scatters the original array, allowing each number in the original array to appear with equal probability in each position of the shuffled array. In the context of nft blind boxes, it means drawing files from the file list without repetition with equal probability.

The shuffling algorithm can be implemented in the following ways:

Fisher-Yates Shuffle#

Randomly generate an index random from the length of the original array
Remove the random element from the original array; the random element is the selected element
Repeat until shuffling is complete

Since the time complexity of this algorithm is $ O(n^2) $, and it requires frequent deletion of elements, this method is not suitable.

Knuth-Durstenfeld Shuffle#

The basic idea of this algorithm is similar to Fisher-Yates. Each time, a random element is taken from the unprocessed data, and that element is swapped with the last element of the array, meaning that the tail of the array contains the elements that have already been processed.

The algorithm process is as follows:

Randomly generate an index random from the length n of the original array
Swap the random element from the original array with the last element, meaning the tail of the array contains the processed elements
Repeat generating random numbers in the length of n-1 and swap with the second-to-last element

Although the time complexity of this algorithm has been reduced to $O(n)$, it still requires frequent swapping of array elements, resulting in additional gas costs.

To avoid frequent swapping of array elements, a mapping can be used to store pointers.

mapping(uint => uint) public referIdMap;

Assuming there is the following file list:

When opening box 1, a random number between [1-8] is generated, say 4. At this point, referIdMap[4] does not point to anything, so the file corresponding to box 1 is 4, and referIdMap[4] = 8 is set.

When opening box 2, a random number between [1-7] is generated, say 4. At this point, referIdMap[4] = 8, so the file corresponding to box 2 is 8, and referIdMap[4] = 7 is set.

When opening box 3, a random number between [1-6] is generated, say 3. At this point, referIdMap[3] does not point to anything, so the file corresponding to box 3 is 3, and referIdMap[3] = 6 is set.

This process continues until all blind boxes are opened.

Blind Box Implementation#

// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
pragma solidity ^0.8.7;

import '@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol';
import '@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol';
import '@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol';
import '@openzeppelin/contracts/utils/Counters.sol';
import '@openzeppelin/contracts/access/Ownable.sol';
import '@openzeppelin/contracts/utils/cryptography/ECDSA.sol';
import '@openzeppelin/contracts/utils/cryptography/MerkleProof.sol';

contract RoboNFT is ERC721URIStorage, VRFConsumerBaseV2, Ownable {
  using Counters for Counters.Counter;
  // Incremental tokenId
  Counters.Counter private _tokenIds;

  // Coordinator - used to request random numbers
  VRFCoordinatorV2Interface COORDINATOR;
  struct ChainlinkParams {
    bytes32 keyHash;
    uint64 subId;
    uint32 gasLimit;
    uint16 requestConfirms;
    uint32 numWords;
  }
  ChainlinkParams public chainlinkParams;

  string public baseURI; // The ipfs address of the folder containing all nft attribute files, in the form of ipfs://{CID}/
  string public constant unrevealURI = 'ipfs://xxxxxx'; // The default metadata json address for the blind box

  // Internal nft information
  struct TokenInfo {
    bool requested; // Whether a random number has been requested
    uint fileId; // File id, e.g., if box 10 corresponds to fileId 4, the returned address is baseURI + '4.json'
  }
  mapping(uint => TokenInfo) private tokenInfoMap; // tokenId => TokenInfo
  mapping(uint => uint) public vrfTokenIdMap; // requestId => tokenId
  mapping(uint => uint) public referIdMap; // Store whether files in the file pool have been used

  uint price = 0.01 ether; // mint price
  bool public allowReveal = false; // Whether blind boxes can be opened
  uint public totalBoxes; // Total number of blind boxes
  uint perMaxMintCount = 5; // Maximum number of mints per address
  uint public revealedCount; // Number of opened blind boxes

  // _vrfCoordinator is the coordinator address, see different network addresses at https://docs.chain.link/docs/vrf-contracts/#configurations
  constructor(
    string memory _name,
    string memory _symbol,
    ChainlinkParams memory _chainlinkParams,
    address _vrfCoordinator,
    uint _totalBoxes,
    string memory _baseURI
  ) ERC721(_name, _symbol) VRFConsumerBaseV2(_vrfCoordinator) {
    // Create coordinator contract instance
    COORDINATOR = VRFCoordinatorV2Interface(_vrfCoordinator);
    // Initialize chainlink parameters
    chainlinkParams = _chainlinkParams;
    // Set total number
    totalBoxes = _totalBoxes;
    // Set baseURI
    baseURI = _baseURI;
    // tokenId starts from 1
    _tokenIds.increment();
  }

  function setAllowReveal(bool _allowReveal) external onlyOwner {
    allowReveal = _allowReveal;
  }

  function withdraw(address payable _to) external payable onlyOwner {
    (bool success, ) = _to.call{value: address(this).balance}('');
    require(success);
  }

  // mint function
  // _expireTime mint end time
  function mint() external payable {
    // Balance + current mint quantity <= maximum quantity allowed per address
    require(balanceOf(msg.sender) + 1 <= perMaxMintCount, 'Mint number exceeds');
    // Ensure payment is not less than price
    require(msg.value >= price, 'require 0.01 ether');

    uint tokenId = _tokenIds.current();
    _safeMint(msg.sender, tokenId);
    _tokenIds.increment();
  }

  // Request to open the blind box
  function requestReveal(uint _tokenId) external {
    require(allowReveal, 'you can not open the box now'); // Ensure blind boxes can currently be opened
    require(ownerOf(_tokenId) == msg.sender, 'the nft does not belong to you'); // Ensure the nft to be opened belongs to msg.sender
    require(!tokenInfoMap[_tokenId].requested, 'the nft has requested random number'); // Ensure _tokenId has not requested a random number

    // Request random number (wallet must have sufficient LINK tokens)
    uint requestId = COORDINATOR.requestRandomWords(
      chainlinkParams.keyHash,
      chainlinkParams.subId,
      chainlinkParams.requestConfirms,
      chainlinkParams.gasLimit,
      chainlinkParams.numWords
    );
    tokenInfoMap[_tokenId].requested = true;

    // Store the tokenId corresponding to the requestId
    vrfTokenIdMap[requestId] = _tokenId;
  }

  // Chainlink callback, passing in request ID and random numbers
  function fulfillRandomWords(
    uint requestId,
    uint[] memory randomWords
  ) internal override {
    // Get tokenId
    uint tokenId = vrfTokenIdMap[requestId];
    // Random number
    uint random = randomWords[0];

    TokenInfo memory tokenInfo = tokenInfoMap[tokenId];

    // tokenId has requested a random number and has not set the blind box ID
    if (tokenInfo.requested && tokenInfo.fileId == 0) {
      uint remainCount = totalBoxes - revealedCount;
      // Randomly take one from the remaining file pool (generate a random number between 1 and remainCount)
      uint index = random % remainCount + 1;

      // Check if the randomly obtained index has been used
      uint referId = referIdMap[index];

      if (referId > 0) {
        // Previously randomly obtained index
        // 1. Set the fileId corresponding to tokenId as referId
        // 2. Set referIdMap[index] to the last unused element 
        tokenInfo.fileId = referId;
        referIdMap[index] = remainCount;
      } else {
        // Not previously randomly obtained index
        // 1. Set the fileId corresponding to tokenId as index
        // 2. Set referIdMap[index] to the last unused element
        tokenInfo.fileId = index;
        referIdMap[index] = remainCount;
      }
      // Number of opened blind boxes + 1
      revealedCount++;
    }
  }

  function tokenURI(uint _tokenId) public view virtual override returns(string memory) {
    require(_exists(_tokenId), 'token not exist');
    if (!allowReveal) return unrevealURI;

    uint fileId = tokenInfoMap[_tokenId].fileId;
    // Blind box not opened
    if (fileId == 0) return unrevealURI;

    return string(abi.encodePacked(baseURI, Strings.toString(fileId), '.json'));
  }
}