Forem: Michael Stivala

How to Create an Off-chain NFT Whitelist

Michael Stivala — Wed, 10 Aug 2022 17:03:00 +0000

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,
}

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();

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]})

💡 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;
}

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))
        )
    );
}

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;
    // ...
}

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)
    // ...
}

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!

How I optimized gas costs by 75%

Michael Stivala — Tue, 09 Aug 2022 14:20:48 +0000

On the Ethereum blockchain, each transaction costs an amount of money in “gas fees”. As developers, our goal is to keep transaction costs as low as possible.

In this article I’ll discuss how to configure hardhat to report gas costs, and how to configure Solidity’s built-in optimizer to reduce gas costs.

I’ll be optimizing a sample NFT project from my upcoming book “A developer’s guide to launching an NFT collection”.

Gas Reporter

Before we turn on the optimizer, let’s start by measuring our current gas costs to give us a benchmark to compare against. We’ll need to first install and configure the hardhat-gas-reporter plugin.

The hardhat-gas-reporter plugin overrides hardhat’s npx hardhat test command and tracks the average gas price of every function that is called within your tests.

You may have guessed it — having automated tests for your project is required to use the gas reporter!

Install the plugin by running npm install hardhat-gas-reporter.

In your hardhat config file import the plugin at the top of the file by adding require("hardhat-gas-reporter")

Add the following block to the settings exported from that file:

gasReporter: {
  outputFile: "gas-report.txt",
  enabled: process.env.REPORT_GAS !== undefined,
  currency: "USD",
  noColors: true,
  coinmarketcap: process.env.COIN_MARKETCAP_API_KEY || "",
  token: "ETH"
}

In order for the gas reporter to give us the monetary cost of each transaction, we’ll need a CoinMarketCap API key, which can be acquired for free from their website.

Go ahead and add the following lines to your .env file:

REPORT_GAS=true
COIN_MARKETCAP_API_KEY=[YOUR-API-KEY]

Let’s run our tests again via npx hardhat test. The gas reporter plugin will take over and will log the gas used in every function call and will output the results to the gas-report-txt file.

This report is really useful in estimating how much your contract will cost to deploy to production, and how much each transaction will cost once deployed.

It also gives us a benchmark that we can use to measure our gas optimization efforts!

Solidity Optimizer

Let’s configure the solidity compiler to optimize our code for us by adjusting the solidity line in our hardhat configuration in hardhat.config.js:

solidity: {
    version: "0.8.9",
    settings: {
        optimizer: {
            // Toggles whether the optimizer is on or off. 
            // It's good to keep it off for development 
            // and turn on for when getting ready to launch.
            enabled: true,
            // The number of runs specifies roughly how often 
            // the deployed code will be executed across the 
            // life-time of the contract.
            runs: 300,
        }
    },
}

Apart from turning the optimizer on, the only configuration option we have is the runs parameter.

From the solidity documentation:

The number of runs specifies roughly how often each opcode of the deployed code will be executed across the life-time of the contract. This means it is a trade-off parameter between code size (deploy cost) and code execution cost (cost after deployment).

200 or 300 runs is a sensible default, but I encourage you to experiment with different values to see how it effects deployment and transaction costs, and pick the most appropriate value for your project.

Here’s the same report again, but with the optimizer turned on. Notice the reduction in gas prices:

What’s next?

Follow me on twitter for more blockchain-related tips and tricks, and to keep in the loop about my upcoming book launch: “A developer’s guide to launching an NFT collection”.