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.