@middlemarch/erc721r

ERC721r

An ERC721 base contract that mints tokens in a pseudo-random order. Because the token is revealed in the same transaction as the mint itself, this contract creates a fun but not fully secure experience.

This contract is for entertainment purposes only!

People using Flashbots will be able to predict what they will get and decide not to go through with the mint if they don't like it. There might also be other exploits I am not aware of because the "instant reveal" mint style is impossible to securely randomize.

If randomness is an important part of your app, you should strongly consider moving to a commit-reveal scheme where the user pays in a different transaction from the one in which they learn what NFT they got. Unfortunately this costs more gas and is less fun, so weigh this against the benefit of increased security.

If you want to learn more, this MouseDev thread is a good place to start.

Usage

yarn add @middlemarch/erc721r or npm install @middlemarch/erc721r

import {ERC721r} from "@middlemarch/erc721r/contracts/ERC721r.sol";

contract FashionHatPunks is ERC721r {
    // 10_000 is the collection's maxSupply
    constructor() ERC721r("Fashion Hat Punks", "HATPUNK", 10_000) {}
    
    // You must implement tokenURI
    function tokenURI(uint tokenId) public view override returns (string memory) {
        return "some uri";
    }
    
    function mint(uint quantity) external {
        // ERC721r exposes a public numberMinted(address) that you can optionally use
        // to, e.g., enforce limits instead of using a separate mapping(address => uint)
        // which is more expensive
        require(numberMinted(msg.sender) + quantity <= 10, "Limit 10 per address");
        
        // You do *not* need to do this. ERC721r handles it.
        // require(totalSupply() + quantity <= maxSupply())
        
        _mintRandom(msg.sender, quantity);
    }
}

ERC721r exposes public maxSupply(), totalSupply() and remainingSupply() functions automatically.

It inherits from Solady's ERC721 so you also get _getExtraData(), _setExtraData(), _getAux(), and _setAux(). However you should be aware that the auxes are used internally by ERC721R, so you should not use them in your own contract. Instead, use _setExtraAddressData() and _getExtraAddressData().

There is also the function _mintAtIndex(address to, uint index) which allows you to mint non-randomly, but it will only behave as you expect if you:

1. Use it before minting randomly
2. Mint non-random tokens in decreasing order of id. E.g., if you want to mint id 200 to one person and id 100 to another person, you should mint id 200 first (because 200 > 100).

Notes

• ERC721r assumes the first id is 0
• Max balance is type(uint32).max
• Contracts cannot mint

Implementation notes

ERC721r uses the modern version of the Fisher–Yates shuffle which stores the list of available tokens and the list of minted tokens in one data structure to save gas.

Credits

This contract was extracted from Fashion Hat Punks, where it was first used. The core logic and code was copied from CryptoPhunksV2. The repository structure was copied from ERC721A. You can read about its inspiration in this Medium article.

License

Copyright (c) 2022 Tom Lehman. ERC721R is released under the MIT License.