devLap

Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

typescript dev.to

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)
Enter fullscreen mode Exit fullscreen mode

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>>;
Enter fullscreen mode Exit fullscreen mode

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>;
Enter fullscreen mode Exit fullscreen mode

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
    ]);
  }
}
Enter fullscreen mode Exit fullscreen mode

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)
}
Enter fullscreen mode Exit fullscreen mode

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));
}
Enter fullscreen mode Exit fullscreen mode

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;
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Step 2: Add Members Off-Chain 

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

Step 3: Push Root On-Chain 

compact call setRoot --arg new_root=$ROOT --witness admin_secret=$ADMIN_SECRET
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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);
  });
});
Enter fullscreen mode Exit fullscreen mode

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.

Source: dev.to

arrow_back Back to Tutorials