Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

Last month, I was tasked with building an allowlist system for a Midnight dApp. The requirement seemed simple: let authorized users access a feature without revealing who they are. In the clear-text world, you'd just check if (user in allowedList). But on a privacy platform, that if statement leaks everything.

This tutorial walks through building a complete anonymous membership proof system — from the Compact contract on-chain to the TypeScript tooling that generates Merkle proofs locally. We'll cover sparse Merkle trees, depth-20 path verification, nullifier-based replay prevention, and admin root management.

Why Merkle Trees for Allowlists?

Traditional allowlists publish every member's address on-chain. That's fine for transparency, but terrible for privacy. A Merkle tree solves this differently:

• Off-chain: The admin maintains a list of member secrets
• On-chain: Only a single 32-byte hash (the Merkle root) is stored
• Proof: A member proves they know a secret that hashes to a leaf in the tree, without revealing which leaf

                    Root (on-chain)
                   /    \
                 H01    H23
                /  \    /  \
               H0  H1  H2  H3
              / \  / \ / \ / \
             L0 L1 L2 L3 ...  (2^20 leaves)

To prove you're L1, you provide H0, H23, and the path indices. The verifier recomputes the root and checks it matches the on-chain value. Your secret (L1's preimage) stays private.

The Compact Contract

The contract manages three pieces of state:

export ledger merkle_root: Bytes<32>;
export ledger admin_commitment: Bytes<32>;
export ledger used_nullifiers: Set<Bytes<32>>;

Witnesses (Secret Inputs)

These are the prover-side inputs that never appear on-chain:

witness getSecret(): Bytes<32>;
witness getContext(): Bytes<32>;
witness getSiblings(): Vector<20, Bytes<32>>;
witness getPathIndices(): Vector<20, Boolean>;
witness getAdminSecret(): Bytes<32>;

Recomputing the Merkle Path

circuit hashLevelNode(is_right: Boolean, current: Bytes<32>, sibling: Bytes<32>): Bytes<32> {
  if (is_right) {
    return persistentHash<Vector<3, Bytes<32>>>([
      pad(32, "zk-allowlist:node:v1"),
      sibling,
      current
    ]);
  } else {
    return persistentHash<Vector<3, Bytes<32>>>([
      pad(32, "zk-allowlist:node:v1"),
      current,
      sibling
    ]);
  }
}

Checking Membership

circuit isMember(): (Bytes<32>, Bytes<32>) {
  let secret = getSecret();
  let context = getContext();
  let leaf = poseidonHash(secret);
  let computed_root = leaf;
  let siblings = getSiblings();
  let indices = getPathIndices();

  for (i in 0..20) {
    computed_root = hashLevelNode(indices[i], computed_root, siblings[i]);
  }

  assert(computed_root == merkle_root.read(), "Invalid membership proof");

  let nullifier = persistentHash<Vector<2, Bytes<32>>>([secret, context]);
  assert(not used_nullifiers.contains(nullifier), "Nullifier already used");

  (computed_root, nullifier)
}

Admin Root Management

export circuit setRoot(new_root: Bytes<32>): [] {
  let admin_secret = getAdminSecret();
  let commitment = poseidonHash(admin_secret);
  assert(commitment == admin_commitment.read(), "Not authorized");
  merkle_root.write(disclose(new_root));
}

The TypeScript Tooling

Sparse Merkle Tree Implementation

export class MerkleTree {
  readonly depth: number;
  private leaves: HashHex[] = [];
  private layers: Map<number, Map<number, HashHex>> = new Map();
  private zeroHashes: HashHex[];

  constructor(depth: number = 20) {
    this.depth = depth;
    this.zeroHashes = computeZeroHashes(depth);
    for (let i = 0; i <= depth; i++) {
      this.layers.set(i, new Map());
    }
  }

  insertLeaf(leafHash: HashHex): number {
    const leafIndex = this.leaves.length;
    this.leaves.push(leafHash);
    this.setNode(0, leafIndex, leafHash);

    let currentIndex = leafIndex;
    for (let level = 0; level < this.depth; level++) {
      const parentIndex = Math.floor(currentIndex / 2);
      const leftChild = this.getNode(level, parentIndex * 2);
      const rightChild = this.getNode(level, parentIndex * 2 + 1);
      const parentHash = hashNode(leftChild, rightChild);
      this.setNode(level + 1, parentIndex, parentHash);
      currentIndex = parentIndex;
    }
    return leafIndex;
  }
}

The Complete Flow

Step 1: Admin Sets Up the Contract

ADMIN_SECRET=$(openssl rand -hex 32)
ADMIN_COMMITMENT=$(echo -n $ADMIN_SECRET | poseidon-hash)
compact deploy --ledger admin_commitment=$ADMIN_COMMITMENT

Step 2: Add Members Off-Chain

midnight-allowlist add-member --secret "alice-secret-123"
ROOT=$(midnight-allowlist get-root)

Step 3: Push Root On-Chain

compact call setRoot --arg new_root=$ROOT --witness admin_secret=$ADMIN_SECRET

Step 4: Member Generates and Submits Proof

PROOF=$(midnight-allowlist generate-proof --secret "alice-secret-123" --context "voting-round-1")
compact call proveMembership --proof $PROOF

Edge Cases and Gotchas

1. Zero Hash Collisions

The sparse tree uses pre-computed zero hashes. Make sure your computeZeroHashes function matches exactly what the Compact contract expects.

2. Context Binding

The nullifier is hash(secret || context). Use distinct contexts for different operations:

const VOTE_CONTEXT = "governance-vote-q2-2026";
const AIRDROP_CONTEXT = "token-airdrop-genesis";

3. Tree Capacity Planning

A depth-20 tree supports ~1M members. Each additional level doubles capacity but increases proof generation time linearly.

Testing

describe('ZK Allowlist', () => {
  it('should verify valid membership proof', async () => {
    const tree = new MerkleTree(20);
    tree.insertLeaf(hashLeaf('alice-secret'));
    const proof = tree.generateMerkleProof(0);
    expect(verifyProof(tree.root, proof, hashLeaf('alice-secret'))).toBe(true);
  });
});

What's Next?

This system handles the core membership proof flow. Production deployments should consider batch root updates, Merkle tree snapshots, circuit optimization, and frontend integration.

The complete source code is available in the companion repository linked in the PR.

---

This tutorial is part of the Midnight Network bounty program. For more developer resources, visit docs.midnight.network.