Blockchain & Smart Contracts

Merkle Tree Allowlists for NFT Mints: Contract, Proofs and Tests

How a Merkle tree lets a contract check an allowlist of thousands of addresses with one 32-byte root. Includes a tested Solidity contract, OpenZeppelin proof generation in TypeScript and the double-hash leaf detail that trips people up.

By Rajib Roy Published 5 min read

Suppose you want 3,000 people to be able to mint your NFT before the public sale. The obvious way is to store every address in a mapping inside the contract. That means 3,000 storage writes at deployment, which costs real money and may not even fit in a block. There is a much cheaper trick: store a single 32-byte fingerprint of the whole list, and make each person prove that they are in it. The fingerprint is a Merkle root, and the proof is a short list of hashes.

In this post I'll explain how that works in plain terms, build the contract and the TypeScript side with OpenZeppelin's libraries, and test the failure cases that matter: wrong person, wrong proof and double claims.

How a Merkle tree works

Take the allowlist and hash each address. Pair the hashes up and hash each pair, getting half as many. Repeat until one hash remains: the root. Change any address in the list and the root changes.

To prove that one address is in the tree, you don't need the whole list. You need the hashes of the "siblings" along the path from your leaf to the root, about log2(n) of them, so around 12 hashes for 3,000 addresses. The contract recomputes the path from your leaf and the siblings, and checks that it ends at the stored root. If it does, your address was in the list when the root was made. The contract never needs to know the other addresses.

That is the reason this pattern is so popular for allowlists and airdrops: deployment stores one value, and each claimer pays for a small amount of hashing, not for storing the list.

The contract

AllowlistMint.sol

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

import {MerkleProof} from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";

contract AllowlistMint {
    bytes32 public immutable merkleRoot;
    mapping(address => bool) public claimed;
    uint256 public totalClaims;

    error NotOnAllowlist();
    error AlreadyClaimed();

    event Claimed(address indexed account);

    constructor(bytes32 root) {
        merkleRoot = root;
    }

    function claim(bytes32[] calldata proof) external {
        if (claimed[msg.sender]) revert AlreadyClaimed();

        // Must match how @openzeppelin/merkle-tree builds leaves: a DOUBLE keccak of the ABI-encoded values.
        bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(msg.sender))));
        if (!MerkleProof.verify(proof, merkleRoot, leaf)) revert NotOnAllowlist();

        claimed[msg.sender] = true;
        totalClaims++;
        emit Claimed(msg.sender); // a real contract would mint here
    }
}

Three things to notice.

  • The root is immutable. It's set once in the constructor. If you need to change the list, deploy a new contract, or add an owner-only setRoot with care and a good reason.
  • The leaf is double-hashed. The contract computes keccak256(bytes.concat(keccak256(abi.encode(msg.sender)))). That format must match exactly what the off-chain tool produces. OpenZeppelin's merkle-tree library documents that its leaves are double-hashed, to prevent second preimage attacks. In such an attack, an attacker presents an internal node of the tree as if it were a leaf. Hashing leaves twice makes an internal node never look like a valid leaf.
  • The leaf includes msg.sender. The proof is only valid for the caller's own address. Someone who sees another person's proof in a transaction can't reuse it, because their own address would produce a different leaf.

The claimed mapping makes claims one-time. A real contract would mint (or check a per-address allowance) inside claim; I emit an event to keep the example focused.

Building the tree off-chain

OpenZeppelin's @openzeppelin/merkle-tree package builds a "standard tree" from an array of values and a list of their Solidity types. Each leaf is a tuple. For a plain address list, each leaf is a one-element tuple. The tests below create the tree, deploy the contract with its root, and look up proofs:

AllowlistMint.ts

import { expect } from "chai";
import { network } from "hardhat";
import { StandardMerkleTree } from "@openzeppelin/merkle-tree";

const { ethers } = await network.create();

describe("AllowlistMint", function () {
  async function setup() {
    const [deployer, a, b, c, outsider] = await ethers.getSigners();
    const allowlist = [a.address, b.address, c.address];
    // Each leaf is a one-element tuple: [address]. The tree is built OFF-chain; only the root goes on-chain.
    const tree = StandardMerkleTree.of(allowlist.map((x) => [x]), ["address"]);
    const mint = await ethers.deployContract("AllowlistMint", [tree.root]);
    const proofFor = (addr: string) => {
      for (const [i, v] of tree.entries()) if (v[0] === addr) return tree.getProof(i);
      throw new Error("not in tree");
    };
    return { mint, tree, proofFor, a, b, outsider };
  }

  it("lets an allowlisted address claim once", async function () {
    const { mint, proofFor, a } = await setup();
    await expect(mint.connect(a).claim(proofFor(a.address))).to.emit(mint, "Claimed").withArgs(a.address);
    await expect(mint.connect(a).claim(proofFor(a.address))).to.be.revertedWithCustomError(mint, "AlreadyClaimed");
  });

  it("rejects an address that is not in the tree, even with someone else's proof", async function () {
    const { mint, proofFor, a, outsider } = await setup();
    await expect(mint.connect(outsider).claim(proofFor(a.address))).to.be.revertedWithCustomError(mint, "NotOnAllowlist");
  });

  it("proof for b does not work for a", async function () {
    const { mint, proofFor, a, b } = await setup();
    await expect(mint.connect(a).claim(proofFor(b.address))).to.be.revertedWithCustomError(mint, "NotOnAllowlist");
  });

  it("the tree verifies its own proofs off-chain", async function () {
    const { tree } = await setup();
    tree.validate();
  });
});

The tree is built outside the blockchain; only tree.root goes into the constructor. You publish the full list or proofs (for example as a JSON file) so that users and your front end can fetch the proof for an address. The list of allowlisted addresses is therefore usually public. If you need privacy, a Merkle tree is the wrong tool.

What the tests prove

  1. Happy path and double claim. An allowlisted account claims with its proof and the contract emits Claimed. A second attempt reverts with AlreadyClaimed.
  2. Outsider with someone else's proof. An address not in the list tries to use a valid proof from an address that is. It reverts with NotOnAllowlist. This is the test for the "proof theft" worry.
  3. Cross-user proofs. A proof made for B doesn't work for A, even though both are on the list.
  4. Off-chain validation. tree.validate() checks that the library's tree is internally consistent. It's cheap, so run it in your build step before you publish a root.

Notice that most of the value is in the negative tests. Anyone can write a test where the right person succeeds. The bugs hide in what should fail.

Mistakes that break allowlists

  • Hashing mismatch. If the contract hashes abi.encodePacked(addr) and your JavaScript uses abi.encode, every proof fails. Use the same leaf format on both sides, which is why the contract above mirrors the library's documented format.
  • Case and checksum errors. Addresses in a spreadsheet may be lowercase, checksummed or have stray spaces. Normalise them before building the tree, and watch for duplicates.
  • Forgetting a claim record. Without claimed, one valid proof can be used many times.
  • Leaking the wrong list. A Merkle root proves membership; it doesn't hide the list. Don't use it for secret lists.
  • Using the tree for amounts without including them. If different people get different quantities, the amount must be part of the leaf ([address, amount]), or someone can claim more than intended.
  • Frozen mistakes. With an immutable root, a wrong address in the list can't be fixed. Check the final list, then check it again, on a testnet.
  • Gas for the claimer. Proof verification is cheap, but the claim still costs gas. Tell people that, so a free allowlist spot doesn't surprise them with a fee.

Using it with a front end

Your site needs a way to look up the proof for the connected wallet. The simplest approach is to publish a static JSON file that maps each address to its proof, or generate the proof in an API route from the tree. Then the claim button sends claim(proof). The React mint button post shows the wallet and error-handling flow; swap its mint() call for claim(proof).

Short checklist

  • One root on-chain, leaf format identical on both sides.
  • Normalised, de-duplicated addresses before building the tree.
  • Leaf includes everything the claim depends on (address, amount).
  • One-time claim record.
  • Negative tests: wrong caller, wrong proof, double claim.
  • A rehearsal on a testnet with the final list before you publish the root.
Build with me

Running an allowlist or airdrop?

I build and test claim contracts and the tooling around them. If you want yours reviewed before launch, get in touch.

See services Get in touch

What I ran this against

  • Hardhat 3.22.0 (Mocha + ethers template), @openzeppelin/contracts 5.6.1, ethers 6.17.0, solc 0.8.34, Node.js 24.22.1, run on 17 November 2026 on Hardhat's in-process simulated network. plus @openzeppelin/merkle-tree 1.0.8. Four tests pass: an allowlisted address claims once and a second claim reverts, an outsider cannot use someone else's proof, a proof for one address does not work for another, and the tree validates its own proofs.
  • Nothing was deployed to a testnet or mainnet, and the contracts are teaching examples that have not been audited. The contract only records a claim; it does not mint, charge or limit anything else.

Sources checked