DEV Community

Cover image for How to Create an Off-chain NFT Whitelist
Michael Stivala
Michael Stivala

Posted on

How to Create an Off-chain NFT Whitelist

First, let’s define what NFT whitelisting is: it’s the process of getting a crypto wallet address pre-approved for minting.

It’s a common approach to prevent so called “gas wars”, where people raise the price of gas that they’re willing to pay to mint an NFT so that their transactions are picked up first, and can be a useful marketing tool where people are added to the whitelist after taking certain actions (for e.g.: in exchange for signing up to an email newsletter).

This article will walk you through the steps involved in implementing this type of system using smart contracts on the Ethereum blockchain.

While there are multiple valid approaches, we’ll be using a coupon system where wallet addresses are signed off-chain in a way that the smart contract can verify that it comes from a trusted source.

By the end of this article you’ll be able to:

  • Add “whitelisting” functionality to your smart contract that will allow pre-approved wallets to mint a single NFT.
  • Architect a web solution that integrates with your smart contract’s whitelist.

How will it work?

Generation

Each coupon will be a simple javascript object containing a wallet address that is signed off-chain using a private key that’s only known to us.

Retrieval

Our coupons will live in a simple JSON file and will be exposed via a simple API.

Consumption

The resulting coupon signature can be used when calling our smart contract to prove that the data being received was generated by us.


Let’s build it

Generation

Let’s start by generating our coupons. We’ll use public-key cryptography to encrypt a wallet address inside our “coupon”.

The script below exposes a createCoupon function that accepts an address and privateKey and will return a coupon.

const { ethers } = require(ethers);

async function createCoupon(address, privateKey) {
    // We’ll leverage the ethers library to create a new wallet
    // that we’ll use to sign the coupon with the private key.
    const signer = new ethers.Wallet(privateKey);

    // We need to encode the wallet address in a way that
    // can be signed and later recovered from the smart contract.
    // Hashing the address using the SHA-256 hashing algorithm
    // is a good way to do this.
    const message = ethers.utils.solidityKeccak256(
        [address],
        [address]
    );

    // Now we can sign the message using the private key.
    const signature = await   signer.signMessage(ethers.utils.arrayify(message));

    // The signature can be expanded into it’s underlying components
    // which we can pass directly into the smart contract.
    // If we didn’t split the signature here — we’d have to do it
    // in the smart contract, which is a bit of a hassle.
    let { r, s, v } = ethers.utils.splitSignature(signature);
    return {r,s,v}
}

module.exports = {
    createCoupon,
}
Enter fullscreen mode Exit fullscreen mode

We’ll need a key-pair to work with — the same one used to deploy your contract will work, but if you still need to generate one you can quickly create a new wallet with Metamask and export the private key from there.

Here’s a small node.js script that will generate our coupons:

const { createCoupon } = require("./coupons");
const fs = require('fs');
require("dotenv").config();

// Insert private key corresponding to _couponSigner
const privateKey = process.env.PRIVATE_KEY;

// Populate with addresses to whitelist
let addresses = [
    // ..
];

const main = async () => {
    let output = [];
    console.log('Generating...');
    for (let i = 0; i < addresses.length; i++) {
        let signature = await createCoupon(addresses[i], 0, privateKey);
        output.push({
            wallet: mint[i],
            r: signature.r,
            s: signature.s,
            v: signature.v
        })
    }

// Save the generated coupons to a coupons.json file
let data = JSON.stringify(output);
    fs.writeFileSync('coupons.json', data);
    console.log('Done.');
    console.log('Check the coupons.json file.');
};

const runMain = async () => {
    try {
        await main();
        process.exit(0);
    } catch (error) {
        console.log(error);
        process.exit(1);
    }
};
runMain();
Enter fullscreen mode Exit fullscreen mode

First make sure that you populate your .env file with the private key of the wallet that will be used for signing. Then, populate the addresses array in the script with a list of wallet addresses.

Run node generateCoupons.js to generate and save your coupons to a coupons.json file. Done!

Retrieval

Since each coupon is only valid for a single wallet address, there is no risk if the coupons are exposed. However, for the sake of keeping the whitelist private, it’s still a good idea to hide it behind an API endpoint that responds to a wallet address and returns the corresponding coupon if found.

While writing an API to serve these coupons is beyond the scope of this article, I can show you how easy it would be to use the below code to find and return the right coupon:

// retrieve the wallet from the query wallet
const wallet = req.query.wallet

// Find a coupon for the passed wallet address
const c = coupons.filter(coupon => coupon.wallet.toLowerCase() === wallet.toLowerCase())
if (0 == c.length) {
    return res.status(200).json({
        coupon: null, 
        message: 'Coupon not found'
    })
}

return res.status(200).json({coupon: c[0]})
Enter fullscreen mode Exit fullscreen mode

💡 The Next.js framework is an excellent choice to build this API and the remaining front-end minting website.

Consumption

In our smart contract, let’s start by defining a struct to represent our coupon.

struct Coupon {
    bytes32 r;
    bytes32 s;
    uint8 v;
}
Enter fullscreen mode Exit fullscreen mode

You might notice that this already looks like the coupon we generated with Javascript.

In our smart contract, we need to do a couple of things to verify that the coupon is valid.

  • Create the same message digest (containing the wallet address) that we created in our Javascript code.
  • Use that message digest to recover the signer of our coupon. Ensure that the recovered signer is in fact, us.

In Solidity, we can achieve this by writing two internal functions:

// Recover the original signer by using the message digest and
// the passed in coupon, to then confirm that the original
// signer is in fact the _couponSigner set on this contract.
function _isVerifiedCoupon(bytes32 digest, Coupon memory coupon)
    internal
    view
    returns (bool)
{
    address signer = ecrecover(digest, coupon.v, coupon.r, coupon.s);
    require(signer != address(0), "ECDSA: invalid signature");
    return signer == _couponSigner;
}

// Create the same message digest that we know the coupon created
// in our JavaScript code has created.
function _createMessageDigest(address _address)
    internal
    pure
    returns (bytes32)
{
    return keccak256(
        abi.encodePacked(
            "\x19Ethereum Signed Message:\n32",
             keccak256(abi.encodePacked(_address))
        )
    );
}
Enter fullscreen mode Exit fullscreen mode

Then we can update our minting function to use our new coupon system:

function mint(Coupon memory coupon)
    external
    payable
{
    require(
        _isVerifiedCoupon(_createMessageDigest(msg.sender), coupon),
        "Coupon is not valid."
    );

    // require that each wallet can only mint one token
    require(
        !_mintedAddresses[msg.sender],
        "Wallet has already minted."
    );

    // Keep track of the fact that this wallet has minted a token
    _mintedAddresses[msg.sender] = true;
    // ...
}
Enter fullscreen mode Exit fullscreen mode

And there we have it! It’s important to keep track of the wallets that have minted in order to prevent coupons from being reused.

On the minting website we need to pass our coupon when calling the mint function:

async function fetchCoupon(wallet) {
    const res = await fetch(`/api/coupons?wallet=${wallet}`)
    return await res.json()
}

async function mint(wallet) {
    const coupon = await fetchCoupon(wallet)
    let tx = await contract.mint(coupon)
    // ...
}
Enter fullscreen mode Exit fullscreen mode

Conclusion

You’ve learnt a simple, secure and effective method to implement an NFT whitelist.

This article is a specially re-written extract from my upcoming book launch: “A developer’s guide to launching an NFT collection”.

Follow me on twitter for more blockchain-related tips and tricks, and to keep in the loop about the book!

Top comments (2)

Collapse
 
sloan profile image
Sloan the DEV Moderator

This looks like a great article! 🙌

In fact, the topic of your post would also work really well in the Meta Punk Community too!

Metapunk Web3 Community 🦙

We’re a community where blockchain builders and makers, web3 devs, and nft creators can connect, learn and share 🦙

favicon metapunk.to

Meta Punk is a really cool international NFT and web3 community where artists, web3 developers, and traders can connect, learn, and share exciting discoveries and ideas. 🦙

Would you consider posting this article there too? Because Meta Punk is built on the same platform as DEV (Forem) you can fairly easily copy the Markdown and post it there as well.

Really hope that you'll share this awesome post with the community there and consider browsing the other Forem communities out there!

Collapse
 
michaelstivala profile image
Michael Stivala

Hey Sloan, good idea - I've reposted it in the Meta Punk Community :)