DEV Community: Harrie

Handling Midnight SDK Breaking Changes: A Developer's Upgrade Playbook

Harrie — Tue, 12 May 2026 04:40:32 +0000

You run npm update on a Friday afternoon. Tests were passing that morning. Now your terminal looks like this:

CompactError: Version mismatch
  Expected circuit artifact version: 4.1.0
  Found: 3.8.2
  Contract: ./managed/counter/contract/index.cjs

Nothing is actually wrong with your .compact source files. You just have stale compiled artifacts sitting in managed/ from before the upgrade, and the runtime now refuses to load them.

Breaking changes on Midnight split into two categories: TypeScript API renames and Compact compiler artifact incompatibility. Once you know which you're dealing with, the fix is usually fast.

What changed in the v3.x to v4.x migration

Package consolidation

The biggest structural change was flattening six individual packages into one barrel export. If you haven't done this migration yet, your package.json probably looks like this:

{
  "dependencies": {
    "@midnight-ntwrk/wallet": "^3.2.0",
    "@midnight-ntwrk/wallet-api": "^3.2.0",
    "@midnight-ntwrk/zswap": "^3.2.0",
    "@midnight-ntwrk/midnight-js-network-id": "^3.2.0",
    "@midnight-ntwrk/midnight-js-types": "^3.2.0",
    "@midnight-ntwrk/midnight-js-contracts": "^3.2.0"
  }
}

After v4.0.3, one package replaces all of them:

{
  "dependencies": {
    "@midnight-ntwrk/midnight-js": "^4.0.3"
  }
}

Your imports change accordingly:

// Before
import { WalletProvider } from '@midnight-ntwrk/wallet';
import { NetworkId } from '@midnight-ntwrk/midnight-js-network-id';
import { ContractAddress } from '@midnight-ntwrk/midnight-js-types';

// After
import { WalletProvider, NetworkId, ContractAddress } from '@midnight-ntwrk/midnight-js';

API renames

Three function-level changes trip people up most.

Wallet initialization renamed one provider option:

// Before
const wallet = await Wallet.initialize({
  walletProvider: storageProvider,
  networkId: NetworkId.TestNet
});

// After
const wallet = await Wallet.initialize({
  privateStoragePasswordProvider: storageProvider,
  networkId: NetworkId.TestNet
});

TypeScript catches walletProvider immediately with "Object literal may only specify known properties." One of the easier breaks to find.

Transaction signing merged two calls into one:

// Before
const balanced = await balanceTx(tx, walletProvider);
const signed = await signTx(balanced, walletProvider);
await submitTx(signed);

// After
const signed = await balanceAndSign(tx, walletProvider);
await submitTx(signed);

Grep for balanceTx to find every instance. It tends to show up in more places than expected.

The CLI command changed from compact compile to compactc. CI pipelines and build scripts using the old command will either fail silently or error out, depending on how your shell handles missing executables.

Pragma version

Compact contracts now require an explicit version pragma at the top of every .compact file:

pragma language_version >= 0.20;

Contracts without this line fail at compile time with CompactError: Language version not specified. Add it as the first non-comment line.

Diagnosing CompactError: Version mismatch

When you compile a .compact file, the Compact compiler generates circuit artifacts: .cjs JavaScript wrappers and .wasm zero-knowledge circuit binaries. These files contain an embedded version tag. When the SDK runtime (now v4.x) finds artifacts tagged for v3.x, it refuses to load them.

Upgrading the SDK packages doesn't touch your compiled artifacts. They stay in managed/ exactly as they were. The runtime just stops accepting them.

To confirm which contracts are affected:

# List all contract artifact directories
ls managed/

# Check the version inside one
cat managed/counter/contract/package.json | grep version

In practice, if you upgraded the SDK, assume all contracts are affected and recompile everything. Checking individually isn't worth the time.

Fixing the version mismatch

Three steps, in order.

Delete the stale artifacts first:

rm -rf managed/*/contract/

Then recompile:

# Single contract
compactc src/contracts/counter.compact managed/counter/contract

# All contracts at once
for contract in src/contracts/*.compact; do
  name=$(basename "$contract" .compact)
  mkdir -p "managed/$name/contract"
  compactc "$contract" "managed/$name/contract"
done

Verify the artifacts exist:

ls managed/counter/contract/
# index.cjs  index.d.cts  zkir.wasm  ...

If you see those files, the compile worked.

The dependency audit workflow

The order matters more than most people expect.

Audit before touching anything:

# What's currently installed
npm list | grep midnight

# What updates are available
npm outdated | grep midnight

Read the changelog before proceeding. Sometimes what looks like a routine upgrade removes a feature you're using.

Update package.json. Replace old package names with the new barrel package. Remove old packages completely from both dependencies and devDependencies. Don't run install yet.
Delete node_modules:

rm -rf node_modules

npm sometimes partially updates packages and leaves old peer dependency resolutions cached. A clean install avoids half-upgraded states where you're running v4 types against v3 implementations.

Delete compiled artifacts:

rm -rf managed/*/contract/

Do this before reinstalling. If you install first and forget to delete artifacts, you'll think the upgrade worked until the first test run.

Install:

npm install

Recompile contracts:

for contract in src/contracts/*.compact; do
  name=$(basename "$contract" .compact)
  compactc "$contract" "managed/$name/contract"
done

Run your test suite. TypeScript type errors from renamed imports surface here. Fix them as they come up.

The verified contract

The companion repository for this guide contains a minimal versioned feature-flag registry compiled against pragma language_version >= 0.20. CI passes on the latest Compact toolchain.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger owner: Bytes<32>;
export ledger contractVersion: Bytes<32>;
export ledger upgradeCount: Counter;
export ledger featureFlags: Map<Bytes<32>, Boolean>;

witness getOwnerSecret(): Bytes<32>;

circuit ownerKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "registry:owner:v1"),
        getOwnerSecret()
    ]);
}

circuit requireOwner(): [] {
    assert(disclose(ownerKey()) == owner, "Owner only");
}

export circuit initialize(ownerPubkey: Bytes<32>): [] {
    owner = disclose(ownerPubkey);
}

export circuit setVersion(newVersion: Bytes<32>): [] {
    requireOwner();
    contractVersion = disclose(newVersion);
    upgradeCount.increment(1);
}

export circuit enableFlag(flagKey: Bytes<32>): [] {
    requireOwner();
    featureFlags.insert(disclose(flagKey), disclose(true));
}

export circuit disableFlag(flagKey: Bytes<32>): [] {
    requireOwner();
    featureFlags.insert(disclose(flagKey), disclose(false));
}

export circuit isFlagEnabled(flagKey: Bytes<32>): Boolean {
    if (!featureFlags.member(disclose(flagKey))) {
        return false;
    }
    return featureFlags.lookup(disclose(flagKey));
}

Five exported circuits, well under Lace's 13-circuit deployment limit. The non-exported helpers (ownerKey, requireOwner) don't count toward the limit. Only export circuit declarations do.

The feature-flag pattern is genuinely useful post-upgrade. You can gate new features behind flags and enable them on-chain once you've confirmed the upgraded contracts are stable in production.

Common pitfalls

Upgrading packages without deleting artifacts. The most common way to hit CompactError: Version mismatch. Packages update, old .wasm files stay. Delete and recompile after every SDK version change.

Partial barrel migration. Updating package.json to use @midnight-ntwrk/midnight-js but leaving old import paths in TypeScript files. This only works as long as the old packages are still in dependencies. Remove them completely and run npm list | grep @midnight-ntwrk after installing to confirm nothing old is lingering.

Missing pragma. Contracts compiled under older Compact versions don't have pragma language_version >= 0.20; at the top. The compiler error is clear, but unexpected if you haven't seen it before. Add the pragma to every .compact file as part of the upgrade.

compactc not in PATH. The toolchain manager (compact) downloads the actual compiler binary. After updating the manager, run compact update to pull the new compiler. If compactc is still missing afterward, check that ~/.compact/bin is in your PATH.

Reserved keywords as parameter names. from and to are reserved keywords in Compact and can't be used as circuit parameter names. If you're refactoring transfer circuits during an upgrade, rename from to sender and to to receiver. The error looks like this:

parse error: found keyword "from" looking for a typed pattern or ")"

This one doesn't come from the SDK change itself, but tends to surface when people are reworking circuits during an upgrade.

Stale type definitions from mixed packages. If you add @midnight-ntwrk/midnight-js without removing the individual packages, TypeScript picks up conflicting type definitions. The build might succeed, but you'll have subtle mismatches at runtime. Remove old packages completely.

That's the playbook

Breaking SDK changes feel arbitrary until you've seen the pattern twice. The package consolidation is a one-time migration. CompactError: Version mismatch always means the same thing: delete artifacts and recompile. The API renames are search-and-replace.

The workflow: audit dependencies first, update package.json, delete node_modules and artifacts, clean install, recompile, fix imports. Same order every time. Skipping step 3 or 4 is how you spend four hours debugging a two-minute fix.

Contract size limits on Midnight: what breaks when your dApp grows too complex

Harrie — Mon, 11 May 2026 22:59:28 +0000

You write a clean contract. It works. Then you add governance. Then staking. Then rewards. Then you deploy and hit a wall.

Midnight has real limits on contract complexity. They don't all surface the same way — some kill deployment, some kill individual transactions, and some just make users wait while proofs grind. This article covers all three, with compiler-verified contracts showing what actually works.

All three contracts compile against the latest Compact compiler. Verified CI run: IamHarrie-Labs/compact-size-limits-guide

The three limits

Lace's 13-circuit deployment limit is a hard cap enforced by the wallet at deploy time. Exceed 13 exported circuits and deployment is rejected. This is wallet-level, not protocol-level, which means it could change with a wallet update — but for now, 13 is the number.

Block weight limits (error 1010) are a runtime problem. Midnight blocks measure transactions across five dimensions: readTime, computeTime, blockUsage, bytesWritten, and bytesChurned. If any of them blow past block capacity, the transaction is rejected. The contract deployed fine; this particular call just does too much.

Proof generation time is the quieter problem. ZK proofs are generated client-side before submission. Constraint count drives proof time. Expensive operations — persistent hash calls, Map reads and writes, bounded loops — each add constraints. A heavy circuit can take several seconds to prove. In a UI, that's visible.

These are three separate problems. The fixes are different.

The 13-circuit limit

Only export circuit declarations count. Non-exported helper circuits, declared with just circuit, are invisible to the limit. That's the most useful thing to understand here, because it's what makes the main optimization strategy work.

Here's a monolithic contract pushing against it:

// monolithic.compact
// Token + governance + staking in one contract.
// 12 exported circuits — one short of Lace's 13-circuit deployment limit.
//
// Non-exported helper circuits (adminKey, requireAdmin) do NOT count
// toward the 13-circuit limit. Only `export circuit` declarations count.

pragma language_version >= 0.20;
import CompactStandardLibrary;

// ─── Token state ───────────────────────────────────────────────────────────

export ledger admin: Bytes<32>;
export ledger balances: Map<Bytes<32>, Uint<64>>;
export ledger totalMinted: Counter;

// ─── Governance state ──────────────────────────────────────────────────────

export ledger proposals: Map<Bytes<32>, Boolean>;
export ledger voteCounts: Map<Bytes<32>, Uint<64>>;
export ledger hasVoted: Map<Bytes<32>, Boolean>;
export ledger proposalCount: Counter;

// ─── Staking state ─────────────────────────────────────────────────────────

export ledger stakedBalances: Map<Bytes<32>, Uint<64>>;
export ledger rewardPoints: Map<Bytes<32>, Uint<64>>;
export ledger totalStaked: Counter;

// ─── Witnesses ─────────────────────────────────────────────────────────────

witness getAdminSecret(): Bytes<32>;

// ─── Non-exported helpers (do NOT count toward the 13-circuit limit) ────────

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "mono:admin:v1"),
        getAdminSecret()
    ]);
}

circuit requireAdmin(): [] {
    assert(disclose(adminKey()) == admin, "Admin only");
}

// ─── Exported circuits — each one counts toward Lace's 13-circuit limit ────
//     Count shown inline. At 13, deployment via Lace wallet will be rejected.

export circuit initialize(adminPubkey: Bytes<32>): [] {          // 1
    admin = disclose(adminPubkey);
}

// Token ──────────────────────────────────────────────────────────────────────

export circuit mint(                                             // 2
    recipient: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    requireAdmin();
    if (!balances.member(disclose(recipient))) {
        assert(disclose(newBalance) == disclose(amount), "First mint: balance must equal amount");
    } else {
        const current = balances.lookup(disclose(recipient));
        assert(disclose(newBalance) > current, "Balance must increase");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid mint amount");
    }
    balances.insert(disclose(recipient), disclose(newBalance));
    totalMinted.increment(1);
}

export circuit transfer(                                         // 3
    sender: Bytes<32>,
    recipient2: Bytes<32>,
    amount: Uint<64>,
    newFromBalance: Uint<64>,
    newToBalance: Uint<64>
): [] {
    assert(balances.member(disclose(sender)), "Sender has no balance");
    const fromCurrent = balances.lookup(disclose(sender));
    assert(fromCurrent >= disclose(amount), "Insufficient balance");
    assert(disclose(newFromBalance) == fromCurrent - disclose(amount), "Invalid sender balance");
    if (!balances.member(disclose(recipient2))) {
        assert(disclose(newToBalance) == disclose(amount), "First receive: balance must equal amount");
    } else {
        const toCurrent = balances.lookup(disclose(recipient2));
        assert(disclose(newToBalance) > toCurrent, "Recipient balance must increase");
        assert(disclose(newToBalance) - toCurrent == disclose(amount), "Invalid recipient balance");
    }
    balances.insert(disclose(sender), disclose(newFromBalance));
    balances.insert(disclose(recipient2), disclose(newToBalance));
}

export circuit burn(userKey: Bytes<32>, amount: Uint<64>): [] {  // 4
    assert(balances.member(disclose(userKey)), "No balance");
    const current = balances.lookup(disclose(userKey));
    assert(current >= disclose(amount), "Insufficient balance");
    balances.insert(disclose(userKey), current - disclose(amount));
}

export circuit balanceOf(userKey: Bytes<32>): Uint<64> {         // 5
    if (!balances.member(disclose(userKey))) {
        return 0;
    }
    return balances.lookup(disclose(userKey));
}

// Governance ─────────────────────────────────────────────────────────────────

export circuit createProposal(proposalId: Bytes<32>): [] {       // 6
    requireAdmin();
    assert(!proposals.member(disclose(proposalId)), "Proposal already exists");
    proposals.insert(disclose(proposalId), disclose(true));
    proposalCount.increment(1);
}

export circuit vote(                                             // 7
    proposalId: Bytes<32>,
    userKey: Bytes<32>,
    newVoteCount: Uint<64>
): [] {
    assert(proposals.member(disclose(proposalId)), "Proposal does not exist");
    const voteKey = persistentHash<Vector<2, Bytes<32>>>([
        disclose(proposalId),
        disclose(userKey)
    ]);
    assert(!hasVoted.member(voteKey), "Already voted");
    if (voteCounts.member(disclose(proposalId))) {
        const current = voteCounts.lookup(disclose(proposalId));
        assert(disclose(newVoteCount) > current, "Vote count must increase");
    }
    hasVoted.insert(voteKey, disclose(true));
    voteCounts.insert(disclose(proposalId), disclose(newVoteCount));
}

export circuit voteCountOf(proposalId: Bytes<32>): Uint<64> {   // 8
    if (!voteCounts.member(disclose(proposalId))) {
        return 0;
    }
    return voteCounts.lookup(disclose(proposalId));
}

// Staking ────────────────────────────────────────────────────────────────────

export circuit stake(                                            // 9
    userKey: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    if (!stakedBalances.member(disclose(userKey))) {
        assert(disclose(newBalance) == disclose(amount), "First stake: balance must equal amount");
    } else {
        const current = stakedBalances.lookup(disclose(userKey));
        assert(disclose(newBalance) > current, "Staked balance must increase");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid stake amount");
    }
    stakedBalances.insert(disclose(userKey), disclose(newBalance));
    totalStaked.increment(1);
}

export circuit unstake(userKey: Bytes<32>, amount: Uint<64>): [] { // 10
    assert(stakedBalances.member(disclose(userKey)), "No stake");
    const current = stakedBalances.lookup(disclose(userKey));
    assert(current >= disclose(amount), "Cannot unstake more than staked");
    stakedBalances.insert(disclose(userKey), current - disclose(amount));
}

export circuit stakedOf(userKey: Bytes<32>): Uint<64> {          // 11
    if (!stakedBalances.member(disclose(userKey))) {
        return 0;
    }
    return stakedBalances.lookup(disclose(userKey));
}

export circuit awardPoints(                                      // 12
    userKey: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    requireAdmin();
    if (!rewardPoints.member(disclose(userKey))) {
        assert(disclose(newBalance) == disclose(amount), "First award: balance must equal amount");
    } else {
        const current = rewardPoints.lookup(disclose(userKey));
        assert(disclose(newBalance) > current, "Balance must increase");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid award amount");
    }
    rewardPoints.insert(disclose(userKey), disclose(newBalance));
}

// Circuit count: 12 / 13 maximum.
// Adding one more export circuit here would push this to the Lace limit.
// Any new feature domain requires splitting into a separate contract.

The full working contract is in the repo. The count is the point: 12 exported circuits. adminKey() and requireAdmin() are helpers and don't count. Two more feature circuits, and this contract won't deploy.

Block weight and error 1010

Error 1010 is a runtime failure, not a deployment one. The contract is on-chain; this particular call just does too much in one transaction.

Midnight measures block weight across five dimensions:

Dimension	What it tracks
`readTime`	Cost of reading ledger state
`computeTime`	Circuit computation cost
`blockUsage`	Overall block space consumed
`bytesWritten`	New bytes written to ledger
`bytesChurned`	Bytes written then immediately overwritten

A circuit that reads from several Map keys, writes multiple entries, and calls persistentHash a few times can hit this even with a completely reasonable circuit count. The fix is the same as for proof time: keep circuits focused.

Operations with the most weight: persistentHash adds significant constraint cost per call. Map.lookup() and Map.insert() each cost readTime or bytesWritten. Bounded loops scale with iteration count times body cost. Large Bytes<N> values directly increase bytesWritten.

The transfer circuit in monolithic.compact does four Map operations. Fine for one transfer. A circuit running ten transfers in a loop is a different story.

Strategy 1: non-exported helper circuits

Pulling repeated logic into non-exported circuits is the cheapest fix. It costs nothing in circuit count.

// ❌ Repeated in every admin-gated circuit — same hash computation every time
export circuit mint(...): [] {
    assert(disclose(persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "token:admin:v1"),
        getAdminSecret()
    ])) == admin, "Admin only");
    // ... rest of circuit
}

export circuit createProposal(...): [] {
    assert(disclose(persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "token:admin:v1"),
        getAdminSecret()
    ])) == admin, "Admin only");
    // ... rest of circuit
}

// ✅ Extract into a non-exported helper — doesn't count toward 13-circuit limit
circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "token:admin:v1"),
        getAdminSecret()
    ]);
}

circuit requireAdmin(): [] {
    assert(disclose(adminKey()) == admin, "Admin only");
}

export circuit mint(...): [] {
    requireAdmin();
    // ... rest of circuit
}

adminKey() and requireAdmin() don't appear in the circuit count. They're inlined at compile time, so there's no runtime cost either. Key derivation, bounds checks, member guards — anything repeated across exported circuits belongs in a helper.

Strategy 2: split by domain

Once you've pulled out all the helpers and the circuit count is still too high, split by domain.

token.compact — 5 exported circuits:

// token.compact
// Token operations split into their own contract.
// 5 exported circuits — well under Lace's 13-circuit limit.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger admin: Bytes<32>;
export ledger balances: Map<Bytes<32>, Uint<64>>;
export ledger totalMinted: Counter;

witness getAdminSecret(): Bytes<32>;

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "token:admin:v1"),
        getAdminSecret()
    ]);
}

circuit requireAdmin(): [] {
    assert(disclose(adminKey()) == admin, "Admin only");
}

circuit requireMember(userKey: Bytes<32>): [] {
    assert(balances.member(userKey), "User has no balance");
}

export circuit initialize(adminPubkey: Bytes<32>): [] {          // 1
    admin = disclose(adminPubkey);
}

export circuit mint(                                             // 2
    recipient: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    requireAdmin();
    if (!balances.member(disclose(recipient))) {
        assert(disclose(newBalance) == disclose(amount), "First mint: balance must equal amount");
    } else {
        const current = balances.lookup(disclose(recipient));
        assert(disclose(newBalance) > current, "Balance must increase");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid mint amount");
    }
    balances.insert(disclose(recipient), disclose(newBalance));
    totalMinted.increment(1);
}

export circuit transfer(                                         // 3
    sender: Bytes<32>,
    receiver: Bytes<32>,
    amount: Uint<64>,
    newFromBalance: Uint<64>,
    newToBalance: Uint<64>
): [] {
    assert(balances.member(disclose(sender)), "Sender has no balance");
    const fromCurrent = balances.lookup(disclose(sender));
    assert(fromCurrent >= disclose(amount), "Insufficient balance");
    assert(disclose(newFromBalance) == fromCurrent - disclose(amount), "Invalid sender balance");
    if (!balances.member(disclose(receiver))) {
        assert(disclose(newToBalance) == disclose(amount), "First receive: balance must equal amount");
    } else {
        const toCurrent = balances.lookup(disclose(receiver));
        assert(disclose(newToBalance) > toCurrent, "Recipient balance must increase");
        assert(disclose(newToBalance) - toCurrent == disclose(amount), "Invalid recipient balance");
    }
    balances.insert(disclose(sender), disclose(newFromBalance));
    balances.insert(disclose(receiver), disclose(newToBalance));
}

export circuit burn(userKey: Bytes<32>, amount: Uint<64>): [] {  // 4
    assert(balances.member(disclose(userKey)), "No balance to burn");
    const current = balances.lookup(disclose(userKey));
    assert(current >= disclose(amount), "Insufficient balance");
    balances.insert(disclose(userKey), current - disclose(amount));
}

export circuit balanceOf(userKey: Bytes<32>): Uint<64> {         // 5
    if (!balances.member(disclose(userKey))) {
        return 0;
    }
    return balances.lookup(disclose(userKey));
}
// Total: 5 / 13

governance.compact — 4 exported circuits:

// governance.compact
// Governance operations in a separate contract from token logic.
// 4 exported circuits — well under Lace's 13-circuit limit.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger admin: Bytes<32>;
export ledger proposals: Map<Bytes<32>, Boolean>;
export ledger voteCounts: Map<Bytes<32>, Uint<64>>;
export ledger hasVoted: Map<Bytes<32>, Boolean>;
export ledger proposalCount: Counter;

witness getAdminSecret(): Bytes<32>;

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "governance:admin:v1"),
        getAdminSecret()
    ]);
}

circuit requireAdmin(): [] {
    assert(disclose(adminKey()) == admin, "Admin only");
}

// Composite key for per-user per-proposal vote tracking.
circuit voteKey(proposalId: Bytes<32>, userKey: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([proposalId, userKey]);
}

export circuit initialize(adminPubkey: Bytes<32>): [] {          // 1
    admin = disclose(adminPubkey);
}

export circuit createProposal(proposalId: Bytes<32>): [] {       // 2
    requireAdmin();
    assert(!proposals.member(disclose(proposalId)), "Proposal already exists");
    proposals.insert(disclose(proposalId), disclose(true));
    proposalCount.increment(1);
}

export circuit vote(                                             // 3
    proposalId: Bytes<32>,
    userKey: Bytes<32>,
    newVoteCount: Uint<64>
): [] {
    assert(proposals.member(disclose(proposalId)), "Proposal does not exist");
    const key = voteKey(disclose(proposalId), disclose(userKey));
    assert(!hasVoted.member(key), "Already voted on this proposal");
    if (voteCounts.member(disclose(proposalId))) {
        const current = voteCounts.lookup(disclose(proposalId));
        assert(disclose(newVoteCount) > current, "Vote count must increase");
    }
    hasVoted.insert(key, disclose(true));
    voteCounts.insert(disclose(proposalId), disclose(newVoteCount));
}

export circuit voteCountOf(proposalId: Bytes<32>): Uint<64> {   // 4
    if (!voteCounts.member(disclose(proposalId))) {
        return 0;
    }
    return voteCounts.lookup(disclose(proposalId));
}
// Total: 4 / 13

Each deploys independently, each well under the limit. When staking comes next, that's a third contract, not a rewrite.

Cross-contract coordination

Compact circuits don't call each other. Coordination is the TypeScript layer's job. Call each contract in sequence, feeding the output of one into the input of the next.

// TypeScript coordinates calls across both contracts
async function voteWithTokenCheck(
  proposalId: Uint8Array,
  voterKey: Uint8Array,
  tokenContractAddress: ContractAddress
) {
  // 1. Query token contract to verify the voter holds tokens
  const balance = await tokenContract.query.balanceOf(voterKey);
  if (balance === 0n) {
    throw new Error("Must hold tokens to vote");
  }

  // 2. Get current vote count from governance contract
  const currentCount = await governanceContract.query.voteCountOf(proposalId);
  const newVoteCount = currentCount + 1n;

  // 3. Submit vote
  await governanceContract.callTx.vote(proposalId, voterKey, newVoteCount);
}

If you want an on-chain record of which token contract the governance contract is paired with, store the address in a ledger field:

export ledger tokenContractRef: Bytes<32>;

export circuit setTokenContract(ref: Bytes<32>): [] {
    requireAdmin();
    tokenContractRef = disclose(ref);
}

The actual balance check still happens off-chain. The stored address is just an audit trail.

Strategy 3: keep individual circuits lean

A heavy circuit is a problem regardless of circuit count. Proof time and block weight both scale with what a circuit does.

persistentHash adds significant constraints per call. Factor repeated hash computations into non-exported helpers rather than duplicating them in every circuit that needs a key.

Map.lookup() and Map.insert() each cost readTime or bytesWritten. A circuit that touches five Map keys is heavier than one that touches one. If a circuit is doing a lot of independent reads, consider whether some of that work can move off-chain.

Off-chain delegation keeps constraint counts low. The newBalance pattern used throughout these contracts is an example: TypeScript computes the arithmetic, the circuit just verifies the relationship. Keeping expensive computation in TypeScript and passing the result as a parameter is consistently cheaper than recomputing in-circuit.

// ❌ In-circuit arithmetic widens the type and adds constraints
const newBalance = current + amount;  // Uint<64> + Uint<64> = Uint<1..2^65>

// ✅ Pass pre-computed value, verify in-circuit
export circuit mint(recipient: Bytes<32>, amount: Uint<64>, newBalance: Uint<64>): [] {
    const current = balances.lookup(disclose(recipient));
    assert(disclose(newBalance) - current == disclose(amount), "Invalid balance");
    balances.insert(disclose(recipient), disclose(newBalance));
}

Pitfalls

1. Counting witnesses and non-exported circuits toward the limit

witness getAdminSecret(): Bytes<32>;  // ← does NOT count
circuit adminKey(): Bytes<32> { ... } // ← does NOT count
export circuit mint(...): [] { ... }  // ← counts: 1

Only export circuit declarations count. witness and bare circuit are invisible to the 13-circuit limit.

2. Confusing the 13-circuit limit with error 1010

They fail differently:

13-circuit limit: deployment fails. Lace rejects the contract before it reaches the chain. Fix: split the contract or remove exported circuits.
Error 1010: a specific transaction fails at runtime. The contract is deployed; this call is just too expensive. Fix: reduce what the circuit does per call, or split the work across multiple transactions.

3. Calling `Map.lookup()` without a `Map.member()` guard

// ❌ Panics at proof generation if the key doesn't exist
const current = voteCounts.lookup(disclose(proposalId));

// ✅ Guard first
if (voteCounts.member(disclose(proposalId))) {
    const current = voteCounts.lookup(disclose(proposalId));
    // ...
}

This applies inside helper circuits too. A helper that calls lookup() unsafely will panic in every exported circuit that calls it.

4. `Uint<64>` arithmetic widening in-circuit

// ❌ Uint<64> + Uint<64> = Uint<1..2^65> — can't store to Uint<64>
const newBalance = current + amount;
balances.insert(disclose(userKey), newBalance);

expected right-hand side to have type Uint<64>
but received Uint<1..18446744073709551616>

// ✅ Compute off-chain, verify in-circuit using subtraction (type-safe)
export circuit mint(recipient: Bytes<32>, amount: Uint<64>, newBalance: Uint<64>): [] {
    const current = balances.lookup(disclose(recipient));
    assert(disclose(newBalance) - current == disclose(amount), "Invalid balance");
    balances.insert(disclose(recipient), disclose(newBalance));
}

Subtraction stays within Uint<64> range once you've asserted the operands are safe. Addition widens. This is consistent across all balance-tracking circuits in this article.

5. Missing `disclose()` on circuit parameters used in assertions

// ❌ Compiler error
assert(amount > 0, "Amount must be positive");

// ✅
assert(disclose(amount) > 0, "Amount must be positive");

Circuit parameters behave like witnesses from the type system's perspective. Any comparison, ledger write, or function call that would expose the value requires an explicit disclose().

6. Using reserved keywords as parameter names

// ❌ Parse error — 'from' is a reserved keyword
export circuit transfer(from: Bytes<32>, to: Bytes<32>, ...): [] { ... }

parse error: found keyword "from" looking for a typed pattern or ")"

// ✅ Use non-reserved names
export circuit transfer(sender: Bytes<32>, receiver: Bytes<32>, ...): [] { ... }

Compact reserves words that look like valid identifiers: from, to, import, export, ledger, circuit, witness, and others. The error ("found keyword X looking for a typed pattern") means the parser hit a reserved word where it expected a variable name. sender and receiver work fine.

7. Using `Counter.increment()` with a `Uint<64>` argument

// ❌ Type error — Counter.increment expects Uint<16>
totalMinted.increment(disclose(amount));  // amount: Uint<64>

expected first argument of increment to have type Uint<16>
but received Uint<64>

// ✅ Pass a literal
totalMinted.increment(1);

Counter counts operations, not arbitrary sums. For large aggregates, use a Map field.

Compiler-verified source

All three contracts — monolithic.compact, token.compact, and governance.compact — compile against the latest Compact compiler:

https://github.com/IamHarrie-Labs/compact-size-limits-guide/actions/runs/25701998943

Resources

Contract-state accounting vs UTXO tokens: two models for onchain value on Midnight

Harrie — Mon, 11 May 2026 22:32:31 +0000

Midnight gives you two ways to represent value in a contract. Most tutorials pick one and move on. This one covers both: what the real compiler-verified API looks like, where each model breaks, and why the UTXO path has more gotchas than it appears.

Short version: UTXO tokens for privacy and real transferability. Ledger-state accounting for queryable bookkeeping. Both, when your contract needs both.

All three contracts here compile against the latest Compact compiler. Verified CI run: IamHarrie-Labs/compact-token-guide

Two separate systems

Midnight runs a public ledger and a shielded Zswap layer. Not two views of the same data. Genuinely separate systems with different guarantees.

Counter and Map fields live on the public ledger. Every insert, every increment is readable by anyone watching the chain. You can query balances, enumerate holders, build conditional logic on accumulated state. You cannot hide amounts.

Zswap is a zero-knowledge Merkle tree. Tokens committed into it have their amounts, owners, and transfer history hidden. You can't ask "how much does Alice hold?" from inside a contract. The contract has no view into individual UTXO holdings. What it can do: mint coins, verify a coin is valid, send coins to recipients.

Pick the wrong model and you'll have balances everyone can read when they shouldn't, or a contract that can't answer "how much does this user have?" That's often the entire point of the contract.

Ledger-state accounting

Ledger-state accounting uses Counter and Map fields to track values inside the contract. Think of it as an on-chain database where your contract is the only writer.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger totalPoints: Counter;
export ledger userPoints: Map<Bytes<32>, Uint<64>>;

witness getAdminSecret(): Bytes<32>;

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "accounting:admin:v1"),
        getAdminSecret()
    ]);
}

export ledger admin: Bytes<32>;

export circuit initialize(adminPubkey: Bytes<32>): [] {
    admin = disclose(adminPubkey);
}

export circuit awardPoints(
    userKey: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    assert(disclose(adminKey()) == admin, "Only admin can award points");

    if (!userPoints.member(disclose(userKey))) {
        assert(disclose(newBalance) == disclose(amount), "First award: balance must equal amount");
    } else {
        const current = userPoints.lookup(disclose(userKey));
        assert(disclose(newBalance) >= current, "Balance must not decrease");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid balance update");
    }

    userPoints.insert(disclose(userKey), disclose(newBalance));
    totalPoints.increment(1);
}

export circuit redeemPoints(
    userKey: Bytes<32>,
    amount: Uint<64>
): [] {
    assert(userPoints.member(disclose(userKey)), "User has no points");

    const current = userPoints.lookup(disclose(userKey));
    assert(current >= disclose(amount), "Insufficient points");

    userPoints.insert(disclose(userKey), current - disclose(amount));
}

export circuit pointsOf(userKey: Bytes<32>): Uint<64> {
    if (!userPoints.member(disclose(userKey))) {
        return 0;
    }
    return userPoints.lookup(disclose(userKey));
}

What you get

Every balance is public. userPoints["alice"] is readable by anyone watching the ledger. That's fine for loyalty points, reputation scores, game credits — anything where the value isn't sensitive. You can enumerate holders, check balances from other circuits, build vesting schedules and rate limits.

The TypeScript call for awardPoints:

// Compute new balance off-chain — arithmetic happens here, not in-circuit
const current = await contract.query.pointsOf(userKey);
const newBalance = current + amount;

await contract.callTx.awardPoints(userKey, amount, newBalance);

The Uint<64> arithmetic constraint

The contract takes newBalance as a parameter from TypeScript rather than computing it in-circuit. This is deliberate. It trips up most developers the first time they write a balance-tracking contract.

When you add two Uint<64> values in-circuit, the result type widens. Uint<64> + Uint<64> produces Uint<1..2^65>, which is too wide to store back into a Map<Bytes<32>, Uint<64>> field:

// ❌ Type error: Uint<64> + Uint<64> = Uint<1..2^65>, not Uint<64>
const newBal = current + amount;
userPoints.insert(disclose(userKey), newBal);

expected right-hand side to have type Uint<64>
but received Uint<1..18446744073709551616>

The fix: compute the result in TypeScript, pass it as a circuit parameter, verify the relationship in-circuit. TypeScript does the arithmetic. The circuit proves it was done correctly.

Subtraction stays within range. Uint<64> - Uint<64> is fine as long as the operand won't go negative, which the assert(current >= amount) guarantees.

When to use it

Use it for internal state that doesn't need to leave the contract, anything you need to query or compare from other circuits, or early development when you don't have a full Midnight node. Avoid it for anything with sensitive amounts.

UTXO-layer tokens

UTXO tokens live in the Zswap Merkle tree, not in ledger fields. The contract is a policy layer: it governs who can create, receive, and send coins. Actual token custody is the shielded transaction engine's job.

The actual standard library API

Most community examples get this wrong. The mint(amount, recipient) you'll see in various tutorials isn't in the standard library. The real functions:

mintShieldedToken(
  domainSep: Bytes<32>,
  value: Uint<64>,
  nonce: Bytes<32>,
  recipient: Either<ZswapCoinPublicKey, ContractAddress>
): ShieldedCoinInfo

sendShielded(
  input: QualifiedShieldedCoinInfo,
  recipient: Either<ZswapCoinPublicKey, ContractAddress>,
  value: Uint<128>
): ShieldedSendResult

receiveShielded(coin: ShieldedCoinInfo): []

ownPublicKey(): ZswapCoinPublicKey

The types involved:

ShieldedCoinInfo — a coin commitment: { nonce: Bytes<32>, color: Bytes<32>, value: Uint<128> }
QualifiedShieldedCoinInfo — a coin plus its Merkle tree position: { nonce: Bytes<32>, color: Bytes<32>, value: Uint<128>, mtIndex: Uint<64> }
ZswapCoinPublicKey — a shielded wallet address: { bytes: Bytes<32> }
Either<L, R> — use left<ZswapCoinPublicKey, ContractAddress>(v) for a wallet key

These complex types come from the wallet SDK through witnesses. You can't pass QualifiedShieldedCoinInfo as a direct circuit parameter. The wallet has to provide it.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger admin: Bytes<32>;
export ledger totalMinted: Counter;

witness getAdminSecret(): Bytes<32>;
witness getMintNonce(): Bytes<32>;
witness getRecipient(): ZswapCoinPublicKey;
witness getQualifiedCoin(): QualifiedShieldedCoinInfo;
witness getCoinToReceive(): ShieldedCoinInfo;

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "utxo:admin:v1"),
        getAdminSecret()
    ]);
}

export circuit initialize(adminPubkey: Bytes<32>): [] {
    admin = disclose(adminPubkey);
}

// Mint shielded tokens directly to a recipient's wallet.
// Domain separator scopes these tokens to this contract version.
export circuit mintToWallet(value: Uint<64>): [] {
    assert(disclose(adminKey()) == admin, "Only admin can mint");

    const recipient = getRecipient();
    const nonce = getMintNonce();

    mintShieldedToken(
        pad(32, "token:v1"),
        disclose(value),
        disclose(nonce),
        left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient))
    );

    totalMinted.increment(1);
}

// Transfer shielded tokens. Protocol handles double-spend prevention.
export circuit transferShielded(value: Uint<128>): [] {
    const coin = getQualifiedCoin();
    const recipient = getRecipient();

    sendShielded(
        disclose(coin),
        left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient)),
        disclose(value)
    );
}

// Receive shielded tokens into this contract.
export circuit receiveIntoContract(): [] {
    const coin = getCoinToReceive();
    receiveShielded(disclose(coin));
}

// Get this contract's shielded public key (use as recipient address).
export circuit contractPublicKey(): ZswapCoinPublicKey {
    return ownPublicKey();
}

How the Zswap layer works

mintShieldedToken creates a coin commitment in the Zswap Merkle tree. The coin's owner, amount, and nonce are hidden inside it. Anyone watching the chain can see a mint happened. Nothing else.

sendShielded takes a coin the caller already owns. The QualifiedShieldedCoinInfo includes the Merkle tree index proving the coin exists and hasn't been spent. Old coin nullified, new commitment created for the recipient.

receiveShielded is for when the contract itself is the recipient. It pulls the coin into the contract's UTXO holdings so the contract can send it onward later.

Double-spend prevention is protocol-level. The Zswap nullifier set handles it. No application logic required.

When token operations get blocked

UTXO operations need the full Midnight node and a Zswap-capable wallet. mintShieldedToken fails in simulator-only environments. sendShielded requires the wallet to provide a valid Merkle inclusion proof. If the wallet doesn't support it, the witness returns nothing and proof generation fails.

Ledger-state accounting works in all environments. UTXO needs the full stack. That's the main practical reason to fall back to accounting even for something that conceptually feels like a token.

When to use it

Use UTXO tokens when value needs to move between wallets privately, when the amounts themselves are sensitive, or when you'd rather not write your own double-spend logic. The tradeoff: you need the full Midnight stack, and the witness-based coin provisioning has its own learning curve.

Combining both: staking rewards

Public participation tracking plus private reward distributions. Staking contracts are a natural fit for this split.

pragma language_version >= 0.20;
import CompactStandardLibrary;

// Public: anyone can see total staked and per-user stakes
export ledger admin: Bytes<32>;
export ledger totalStaked: Counter;
export ledger userStakes: Map<Bytes<32>, Uint<64>>;

// Public aggregate only — individual reward amounts are hidden in Zswap
export ledger totalRewarded: Counter;

witness getAdminSecret(): Bytes<32>;
witness getMintNonce(): Bytes<32>;
witness getRecipient(): ZswapCoinPublicKey;

circuit adminKey(): Bytes<32> {
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "hybrid:admin:v1"),
        getAdminSecret()
    ]);
}

export circuit initialize(adminPubkey: Bytes<32>): [] {
    admin = disclose(adminPubkey);
}

// ACCOUNTING: record a stake
export circuit recordStake(
    userKey: Bytes<32>,
    amount: Uint<64>,
    newBalance: Uint<64>
): [] {
    if (!userStakes.member(disclose(userKey))) {
        assert(disclose(newBalance) == disclose(amount), "First stake: balance must equal amount");
    } else {
        const current = userStakes.lookup(disclose(userKey));
        assert(disclose(newBalance) > current, "Balance must increase");
        assert(disclose(newBalance) - current == disclose(amount), "Invalid stake amount");
    }

    userStakes.insert(disclose(userKey), disclose(newBalance));
    totalStaked.increment(1);
}

// ACCOUNTING: remove a stake
export circuit removeStake(
    userKey: Bytes<32>,
    amount: Uint<64>
): [] {
    assert(userStakes.member(disclose(userKey)), "No stake recorded");

    const current = userStakes.lookup(disclose(userKey));
    assert(current >= disclose(amount), "Cannot remove more than staked");

    userStakes.insert(disclose(userKey), current - disclose(amount));
}

// UTXO: distribute real shielded token rewards (private amounts)
export circuit distributeReward(rewardAmount: Uint<64>): [] {
    assert(disclose(adminKey()) == admin, "Only admin can distribute rewards");

    const recipient = getRecipient();
    const nonce = getMintNonce();

    mintShieldedToken(
        pad(32, "hybrid:reward:v1"),
        disclose(rewardAmount),
        disclose(nonce),
        left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient))
    );

    totalRewarded.increment(1);
}

export circuit stakeOf(userKey: Bytes<32>): Uint<64> {
    if (!userStakes.member(disclose(userKey))) {
        return 0;
    }
    return userStakes.lookup(disclose(userKey));
}

The accounting circuits give auditors a clear view of who staked what. The UTXO circuit keeps reward amounts hidden. totalRewarded increments on-chain, but who got what stays inside Zswap.

Decision table

Scenario	Model
Loyalty points, credits, scores	Accounting
Participation tracking, voting weight	Accounting
Internal rate limits or quotas	Accounting
Payment tokens, transferable assets	UTXO
Amount and participant privacy required	UTXO
Unit-testing without full Midnight node	Accounting
Internal tracking + real payouts	Hybrid

If you need to query balances inside the contract, UTXO won't work. The contract can't read Zswap holdings. If you need private transfers between wallets, ledger-state won't work. Those balances are fully public.

Pitfalls

1. `Map.get()` doesn't exist — use `Map.lookup()`

// ❌ Compile error — Map has no .get() method
const balance = userPoints.get(disclose(userKey));

// ✅ Correct
if (userPoints.member(disclose(userKey))) {
    const balance = userPoints.lookup(disclose(userKey));
}

2. `Map.lookup()` panics on a missing key

// ❌ Panics at proof generation if userKey was never inserted
const balance = userPoints.lookup(disclose(userKey));

// ✅ Guard with .member() first
assert(userPoints.member(disclose(userKey)), "User has no balance");
const balance = userPoints.lookup(disclose(userKey));

3. `Set<T>` doesn't exist — use `Map<K, Boolean>`

// ❌ Compile error — Compact has no Set type
export ledger spentCoins: Set<Bytes<32>>;

// ✅ Map<K, Boolean> is the set pattern
export ledger spentCoins: Map<Bytes<32>, Boolean>;
spentCoins.insert(disclose(coinId), disclose(true));

4. `Uint<64>` addition widens the type

// ❌ Uint<64> + Uint<64> = Uint<1..2^65> — can't store back to Uint<64>
const newBalance = current + amount;
userPoints.insert(disclose(key), newBalance);

expected right-hand side to have type Uint<64>
but received Uint<1..18446744073709551616>

// ✅ Compute off-chain, verify in-circuit
export circuit awardPoints(key: Bytes<32>, amount: Uint<64>, newBalance: Uint<64>): [] {
    const current = userPoints.lookup(disclose(key));
    assert(disclose(newBalance) - current == disclose(amount), "Invalid balance");
    userPoints.insert(disclose(key), disclose(newBalance));
}

5. Missing `disclose()` on exported parameters in comparisons

// ❌ Compiler error
assert(amount > 0, "Amount must be positive");

// ✅ Exported parameters need disclose() before comparisons
assert(disclose(amount) > 0, "Amount must be positive");

Compact compiler error: potential witness-value disclosure must be declared but is not — performing this ledger operation might disclose the boolean value of the result of a comparison involving the witness value

6. Wrong UTXO API signatures

// ❌ Not a standard library function
mint(amount, recipient);

// ❌ Wrong signature — sendShielded doesn't take (amount, recipient)
sendShielded(amount, recipient);

The correct forms:

// ✅ mintShieldedToken: domain separator + nonce + explicit type params on left()
mintShieldedToken(
    pad(32, "token:v1"),
    disclose(value),
    disclose(nonce),
    left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient))
);

// ✅ sendShielded: takes QualifiedShieldedCoinInfo from witness, not just an amount
sendShielded(
    disclose(coin),                                    // QualifiedShieldedCoinInfo
    left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient)),
    disclose(value)                                    // Uint<128>
);

mintShieldedToken needs a domain separator to scope the token type to this contract, a per-mint nonce to prevent replay, and left() with explicit type parameters. Type inference doesn't work here.

7. `Counter.increment()` takes `Uint<16>`, not `Uint<64>`

// ❌ Type error
totalPoints.increment(disclose(amount));  // amount: Uint<64>

expected first argument of increment to have type Uint<16>
but received Uint<64>

// ✅ Pass a literal
totalPoints.increment(1);

Counter.increment() accepts step values up to 65535. For large aggregate sums, use a Map field. Use Counter to count operations only.

8. Missing `disclose()` on witness values passed to UTXO functions

// ❌ Compiler error: witness values passed to UTXO functions need disclose()
mintShieldedToken(pad(32, "token:v1"), disclose(value), nonce, left<...>(recipient));
sendShielded(coin, left<...>(recipient), disclose(value));
receiveShielded(coin);

potential witness-value disclosure must be declared but is not:
  the call to standard-library circuit mintShieldedToken might disclose a link between
  a coin spend and the coin with the commitment given by a hash of the witness value

// ✅ Disclose witness values before passing to any UTXO standard library function
mintShieldedToken(
    pad(32, "token:v1"),
    disclose(value),
    disclose(nonce),
    left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient))
);
sendShielded(
    disclose(coin),
    left<ZswapCoinPublicKey, ContractAddress>(disclose(recipient)),
    disclose(value)
);
receiveShielded(disclose(coin));

This applies to all three: mintShieldedToken, sendShielded, and receiveShielded. Each creates or consumes a coin commitment that hashes your witness value on-chain. Compact requires explicit disclose() to acknowledge that link. The private data stays inside the ZK proof. What you're acknowledging is that a hash of your witness will appear on-chain.

9. Treating accounting balances as private

// This balance is publicly readable — NOT private
export ledger userPoints: Map<Bytes<32>, Uint<64>>;

Ledger fields are visible to anyone reading the chain. For sensitive amounts (stake sizes, bid values, holdings), use the UTXO model or commitment patterns with persistentCommit.

Compiler-verified source

All three contracts — accounting.compact, utxo-token.compact, and hybrid.compact — compile against the latest Compact compiler:

https://github.com/IamHarrie-Labs/compact-token-guide/actions/runs/25700476519

Resources

Replay Attack Prevention in Compact: Nonces, Nullifiers, and Domain Separation

Harrie — Mon, 11 May 2026 21:18:13 +0000

On Ethereum, replay protection is built into the protocol. Every account has a nonce; every transaction carries it; the node rejects duplicates. You don't think about it.

Midnight doesn't work that way. Transactions arrive as zero-knowledge proofs. The network verifies the proof is valid — but it doesn't inherently know whether that exact proof has been submitted before. The public ledger sees the result of a valid proof, not the transaction itself. That means replay prevention is your job, not the protocol's, and you have to design it explicitly into every circuit that needs it.

This tutorial covers the three mechanisms Compact gives you: counter-based nonces, set-based nullifiers derived from persistentCommit(secret, context), and domain separation tags. Each one addresses a different class of replay attack, and knowing which to reach for — and when to combine them — is one of the more consequential design decisions in Compact contract development.

All three contracts in this article compile against the latest Compact compiler. Verified CI run: IamHarrie-Labs/compact-replay-prevention-guide

Three kinds of replay

It helps to be precise about what you're defending against.

Operation replay: the same valid proof is submitted twice. A voter submits their vote, the transaction succeeds, an attacker captures the transaction and resubmits it. If the contract doesn't track which proofs have been consumed, the vote tallies twice.

Cross-operation replay: a proof valid for one circuit is reused in a different circuit. A governance contract has both a castVote and a delegateVote circuit. Without domain separation, if both circuits hash the same inputs, a proof generated for voting might satisfy the delegation circuit — an attacker extracts real capability from a proof they didn't generate.

Cross-contract replay: a proof from contract A is replayed against contract B. Two different election contracts with the same circuit structure — a voter's proof for one election might be valid against the other if the nullifier isn't scoped to the specific contract.

The three mechanisms map to these threats:

Threat	Mechanism
Operation replay	Counter nonces or set-based nullifiers
Cross-operation replay	Domain separation tags
Cross-contract replay	Context-scoped nullifiers + domain separation

Mechanism 1: Counter-based nonces

A counter nonce assigns each participant a monotonically increasing number. Each operation must reference the current nonce; after a successful operation the nonce advances. Any replay of an old transaction carries an outdated nonce and fails immediately.

This is the most transparent approach — nonces are public ledger state, so any participant can check their current value before submitting. It's the right choice when participants have known, stable identities and operations need strict ordering.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger userNonces: Map<Bytes<32>, Uint<64>>;
export ledger operationCount: Counter;

witness getUserKey(): Bytes<32>;

export circuit operate(
    userKey: Bytes<32>,
    nonce: Uint<64>,
    nextNonce: Uint<64>
): [] {
    if (!userNonces.member(disclose(userKey))) {
        assert(disclose(nonce) == 0, "First operation must use nonce 0");
    } else {
        assert(
            disclose(nonce) == userNonces.lookup(disclose(userKey)),
            "Invalid nonce — replay or out-of-order submission"
        );
    }

    assert(disclose(nextNonce) > disclose(nonce), "nextNonce must exceed current nonce");
    userNonces.insert(disclose(userKey), disclose(nextNonce));
    operationCount.increment(1);
}

Three things in this contract that will bite you if you copy-paste common Solidity patterns directly.

Map<Bytes<32>, Boolean> not Set<> — Compact has no Set type. Use Map<K, Boolean> where you'd reach for a set. This applies to nullifier storage too.

member() before lookup() — calling lookup on a key that doesn't exist in the map panics at proof generation. Always check member first, or use insertDefault to pre-populate. Missing this check means first-time users will hit an opaque failure instead of a clean error message.

The Uint<64> arithmetic constraint — Compact's range types mean nonce + 1 on a Uint<64> produces a Uint<1..2^64>, which is wider than Uint<64> and can't be assigned back to a ledger field. The fix is to pass both nonce (current, to verify) and nextNonce (computed off-chain, to store). The contract verifies strict ordering, and TypeScript handles the +1. This pattern recurs whenever you'd naturally write ledgerField = existingValue + constant.

Who calls operate? The userKey is an exported circuit parameter. It's what the caller claims their identity is. In a real contract, you'd derive userKey from a private key via ownPublicKey() or a witness, not accept it freely. The circuit above accepts it as a public input for simplicity.

When nonces fall short

Counter nonces have one significant limitation: they serialize operations. If two transactions with the same nonce are in-flight simultaneously, only one succeeds — the other must regenerate with the updated nonce. For single-owner or low-throughput contracts this is fine. For high-concurrency systems (airdrops, voting with thousands of simultaneous participants), nullifiers are the better choice.

Mechanism 2: Set-based nullifiers with `persistentCommit`

A nullifier is a one-time-use token derived from a private secret. Once consumed on-chain, any subsequent attempt to reuse the same nullifier is rejected. Unlike nonces, nullifiers don't require a known identity — the secret stays private; only the nullifier hash appears on the ledger.

The bounty specifies nullifiers derived from persistentCommit(secret, context):

persistentCommit<T>(v: T, opening: Bytes<32>): Bytes<32>

v = the private secret (what the commitment binds to)
opening = the context/domain string (what scopes the nullifier)

Using a fixed context string as the opening makes the nullifier deterministic (same inputs always produce the same output, which is what you need for replay detection) and scoped (changing the context string produces a different nullifier, letting the same secret participate in different campaigns without cross-campaign collision).

pragma language_version >= 0.20;
import CompactStandardLibrary;

// Map<Bytes<32>, Boolean> is Compact's set pattern — no dedicated Set type exists
export ledger spentNullifiers: Map<Bytes<32>, Boolean>;
export ledger totalClaims: Counter;

witness getSecret(): Bytes<32>;

export circuit claimReward(context: Bytes<32>): [] {
    const secret = getSecret();

    // Derive nullifier: persistentCommit(secret, context)
    // secret: private — binding, never on-chain
    // context: public — scopes this nullifier to a specific campaign
    const nullifier = persistentCommit<Bytes<32>>(secret, disclose(context));

    assert(
        !spentNullifiers.member(disclose(nullifier)),
        "Nullifier already spent: reward already claimed"
    );

    // Record nullifier BEFORE side effects — always
    spentNullifiers.insert(disclose(nullifier), disclose(true));

    totalClaims.increment(1);
}

`persistentCommit` vs `persistentHash` for nullifiers

persistentHash<T>(v: T): Bytes<32> is deterministic and produces a fixed hash. For a nullifier that just needs to be binding, it works. But it offers no built-in context scoping.

persistentCommit<T>(v: T, opening: Bytes<32>): Bytes<32> accepts an explicit opening value. When you use a domain string as the opening, you get a naturally scoped nullifier: persistentCommit(secret, pad(32, "airdrop:season-1:v1")) produces a different result from persistentCommit(secret, pad(32, "airdrop:season-2:v1")), even though the secret is identical. One secret, multiple campaigns, zero cross-campaign collision.

With persistentHash you'd have to concatenate manually and hope your encoding is consistent. persistentCommit with a context argument makes the scoping explicit and type-safe.

Context scoping prevents cross-contract replay

The context parameter in claimReward is publicly visible. If two different contracts both have a claimReward circuit and a participant uses the same secret in both, the nullifier from contract A (persistentCommit(secret, contextA)) differs from the nullifier in contract B (persistentCommit(secret, contextB)) as long as the context strings differ. The context acts as the scope boundary.

In practice, include the contract address or a unique deployment ID in the context:

// Off-chain: compute context with contract address for cross-contract safety
const context = encodeContext("airdrop:season-1:v1", contractAddress);

Record nullifier before side effects

In Compact, a circuit is atomic — it either fully succeeds or fully reverts. But the logical ordering still matters for clarity and security audits: mark the nullifier as spent before executing side effects. If you do it the other way:

// ❌ Side effect first — logically backwards
totalClaims.increment(1);
spentNullifiers.insert(disclose(nullifier), disclose(true)); // too late conceptually

Auditors reading your contract will expect nullifier recording before state changes. More importantly, in future contract upgrades or more complex circuits where partial execution might become possible, the safe ordering protects you.

Storage growth

spentNullifiers grows forever — one entry per claim, unbounded. For high-throughput or long-lived contracts, this is a real concern. Compact has no native pruning for maps; the current mitigation is designing campaigns with bounded participation (a fixed voter tree, a capped airdrop size) so the map growth is bounded by design. For contracts where unbounded growth is unavoidable, the off-chain client can query map size before executing and alert when it approaches the tree capacity.

Mechanism 3: Domain separation tags

Domain separation solves cross-operation replay. The threat: a contract has two circuits that hash similar inputs. Without distinct tags, a proof valid for circuit A might hash to the same value as circuit B, letting an attacker reuse one proof for a different operation.

The fix is a unique prefix on every hash computation:

persistentHash<Vector<n, Bytes<32>>>([
    pad(32, "contract-name:operation:version"),
    ...data
])

Even if two circuits receive identical data inputs, different domain tags produce completely different outputs. The circuits become cryptographically isolated.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger voteNullifiers: Map<Bytes<32>, Boolean>;
export ledger delegateNullifiers: Map<Bytes<32>, Boolean>;
export ledger totalVotes: Counter;
export ledger totalDelegations: Counter;

witness getVoterSecret(): Bytes<32>;

circuit voteNullifier(secret: Bytes<32>, proposalId: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>([
        pad(32, "gov:vote:v1"),       // ← vote-specific domain tag
        secret,
        proposalId
    ]);
}

circuit delegateNullifier(secret: Bytes<32>, proposalId: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>([
        pad(32, "gov:delegate:v1"),   // ← delegate-specific domain tag — different hash space
        secret,
        proposalId
    ]);
}

export circuit castVote(proposalId: Bytes<32>): [] {
    const secret = getVoterSecret();
    const nullifier = voteNullifier(secret, disclose(proposalId));

    assert(!voteNullifiers.member(disclose(nullifier)), "Vote already cast for this proposal");
    voteNullifiers.insert(disclose(nullifier), disclose(true));
    totalVotes.increment(1);
}

export circuit delegateVote(proposalId: Bytes<32>): [] {
    const secret = getVoterSecret();
    const nullifier = delegateNullifier(secret, disclose(proposalId));

    assert(!delegateNullifiers.member(disclose(nullifier)), "Already delegated for this proposal");
    delegateNullifiers.insert(disclose(nullifier), disclose(true));
    totalDelegations.increment(1);
}

The same voter (same secret) can both vote and delegate on the same proposal. The voteNullifier and delegateNullifier circuits produce different hashes for identical inputs because the tags differ. No cross-operation collision is possible.

Domain tag design

Good tags follow a consistent pattern:

{project}:{contract}:{operation}:v{version}

Examples:

"gov:proposal:nullifier:v1" — proposal submission in a governance contract
"token:transfer:nullifier:v1" — transfer in a token contract
"airdrop:claim:nullifier:v1" — airdrop claim

The version suffix matters for upgrades. If you change the contract's logic and redeploy, existing nullifiers from the old version should remain valid or explicitly invalid — a version bump in the tag ensures the two contract generations don't share a hash space.

Always use pad(32, tag) to get a fixed 32-byte prefix. pad left-pads the string with zeros. Without it, variable-length tags create ambiguity: "a" || "bc" and "ab" || "c" would produce the same byte sequence and could collide.

The official Midnight pattern

Midnight's own Bulletin Board contract uses this exact approach:

export circuit publicKey(sk: Bytes<32>, sequence: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>([
        pad(32, "bboard:pk:"),
        sequence,
        sk
    ]);
}

The "bboard:pk:" prefix ensures public keys derived here can't be confused with hashes from any other part of the system — including other contracts that might use the same sk.

Combining all three: a governance contract

The strongest contracts layer all three mechanisms. Here's a minimal DAO governance contract that uses nonces for proposal submission ordering, domain-separated nullifiers for anonymous voting, and explicit tag versioning:

pragma language_version >= 0.20;
import CompactStandardLibrary;

// Phase state
export ledger proposalOpen: Boolean;
export ledger proposalId: Bytes<32>;

// Counter nonce: proposal submission is identity-bound and sequentially ordered
export ledger submitterNonces: Map<Bytes<32>, Uint<64>>;
export ledger proposalCount: Counter;

// Nullifier set: voting is anonymous — nullifiers prevent double-vote
export ledger voteNullifiers: Map<Bytes<32>, Boolean>;
export ledger yesVotes: Counter;
export ledger noVotes: Counter;

witness getVoterSecret(): Bytes<32>;

// Domain-separated helper — "dao:vote:v1" isolates vote hashes from all other ops
circuit computeVoteNullifier(
    secret: Bytes<32>,
    proposal: Bytes<32>
): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>([
        pad(32, "dao:vote:v1"),
        secret,
        proposal
    ]);
}

// Submit a proposal — identity-bound, nonce-protected
export circuit submitProposal(
    submitterKey: Bytes<32>,
    nonce: Uint<64>,
    nextNonce: Uint<64>,
    content: Bytes<32>
): [] {
    assert(!proposalOpen, "Proposal already open");

    // Counter nonce: verify and advance
    if (!submitterNonces.member(disclose(submitterKey))) {
        assert(disclose(nonce) == 0, "First submission must use nonce 0");
    } else {
        assert(
            disclose(nonce) == submitterNonces.lookup(disclose(submitterKey)),
            "Invalid nonce"
        );
    }
    assert(disclose(nextNonce) > disclose(nonce), "nextNonce must increase");
    submitterNonces.insert(disclose(submitterKey), disclose(nextNonce));

    proposalId = disclose(content);
    proposalOpen = disclose(true);
    proposalCount.increment(1);
}

// Cast a vote — anonymous, nullifier-protected, domain-separated
export circuit castVote(vote: Uint<8>): [] {
    assert(proposalOpen, "No open proposal");

    const secret = getVoterSecret();
    const nullifier = computeVoteNullifier(secret, proposalId);

    // Replay prevention: nullifier check before side effects
    assert(!voteNullifiers.member(disclose(nullifier)), "Already voted");
    voteNullifiers.insert(disclose(nullifier), disclose(true));

    if (disclose(vote) == 1) {
        yesVotes.increment(1);
    } else {
        noVotes.increment(1);
    }
}

export circuit closeProposal(): [] {
    assert(proposalOpen, "No open proposal");
    proposalOpen = disclose(false);
}

This contract uses nonces for the submitter (identity matters, ordering matters) and nullifiers for voters (identity is private, concurrency is expected). The "dao:vote:v1" tag ensures vote hashes can never collide with any other operation in a larger system, and the version suffix leaves room for future upgrades.

When to use which

Scenario	Use
Registered users, strict sequential ordering needed	Counter nonces
Anonymous participation, high concurrency	Set-based nullifiers
Multiple distinct operations in one contract	Domain separation
Multi-contract system sharing user secrets	Context-scoped nullifiers + domain separation
Time-bound campaigns (voting, airdrops)	Nullifiers with campaign ID in context
Contract upgrade path needed	Versioned domain tags (`v1`, `v2`)

Counter nonces and nullifiers both prevent operation replay, but they trade off differently: nonces are sequential and identity-revealing; nullifiers allow concurrency and preserve privacy. Domain separation is not an alternative to either — it's a required complement whenever a contract has more than one circuit that hashes related data.

The strongest contracts layer all three: domain-separated nullifiers for the core replay check, plus counter nonces for any ordered operations that require strict sequencing.

Common pitfalls

1. Using `Set<T>` — doesn't exist in Compact

// ❌ Compile error — Compact has no Set type
export ledger spentNullifiers: Set<Bytes<32>>;

// ✅ Correct — use Map<K, Boolean> as a set
export ledger spentNullifiers: Map<Bytes<32>, Boolean>;

2. `Map.lookup()` without `Map.member()` check — panics on missing key

// ❌ Panics at proof generation if userKey has never been inserted
const current = userNonces.lookup(disclose(userKey));

// ✅ Always check member() first
if (userNonces.member(disclose(userKey))) {
    const current = userNonces.lookup(disclose(userKey));
    assert(disclose(nonce) == current, "Invalid nonce");
} else {
    assert(disclose(nonce) == 0, "First use must start at nonce 0");
}

3. `Uint<64>` arithmetic in-circuit produces a wider range type

// ❌ Type error: Uint<64> + 1 produces Uint<1..2^64>, not Uint<64>
userNonces.insert(disclose(userKey), disclose(current + 1));

expected right-hand side to have type Uint<64>
but received Uint<1..18446744073709551616>

// ✅ Pass nextNonce from off-chain TypeScript, verify > current in-circuit
userNonces.insert(disclose(userKey), disclose(nextNonce));

4. Missing `disclose()` on exported parameters in comparisons

// ❌ Compiler flags the comparison — may produce disclosure error
assert(nonce == userNonces.lookup(disclose(userKey)), "Invalid nonce");

// ✅ Exported parameters need disclose() before ledger comparisons
assert(disclose(nonce) == userNonces.lookup(disclose(userKey)), "Invalid nonce");

5. Nullifiers without context — same nullifier across deployments

// ❌ Same secret produces same nullifier in every contract — cross-contract replay risk
const nullifier = persistentCommit<Bytes<32>>(secret, pad(32, "no-scope"));

// ✅ Include contract-specific context in the opening
const nullifier = persistentCommit<Bytes<32>>(secret, disclose(campaignContext));
// where campaignContext includes contract address or unique deployment ID

6. Domain tags without version — upgrade breaks nullifier isolation

// ❌ No version — upgrading the contract logic shares the hash space with v1
pad(32, "gov:vote")

// ✅ Versioned — v2 deployments have isolated nullifier sets from v1
pad(32, "gov:vote:v1")
pad(32, "gov:vote:v2")  // for the upgraded contract

7. Recording nullifier after side effects

// ❌ Side effects before nullifier record — logically backwards
totalClaims.increment(1);
spentNullifiers.insert(disclose(nullifier), disclose(true));

// ✅ Record nullifier first, then side effects
spentNullifiers.insert(disclose(nullifier), disclose(true));
totalClaims.increment(1);

Compact circuits are atomic, so this doesn't affect transaction safety. But it protects you during audits and contract evolution, and is the defensively correct pattern.

Compiler-verified source

All three contracts in this article — counter-nonce.compact, nullifier.compact, and domain-separation.compact — compile against the latest Compact compiler. The full source and CI run are at:

https://github.com/IamHarrie-Labs/compact-replay-prevention-guide/actions/runs/25690416194

Resources

Compact Language Reference
Standard Library: persistentHash, persistentCommit
Bulletin Board Tutorial — canonical domain separation example ("bboard:pk:")
Midnight Developer Forum

Understanding Wallet Sync in the Midnight SDK: Why Your Deploy Fails Before It Starts

Harrie — Mon, 11 May 2026 18:29:32 +0000

You call balanceUnboundTransaction. It throws — or worse, it succeeds silently with wrong token balances, and the transaction fails somewhere downstream with a message that has nothing to do with sync. You check the obvious things. Funds are in the wallet. The contract compiled. The proof server is running. Nothing looks wrong.

The problem is that your wallet hasn't finished scanning the chain, and balanceUnboundTransaction built a transaction from an incomplete local database. This is probably the most common early failure in Midnight development. It's almost always invisible until you've seen it once.

The mental model shift

Most developers approach a crypto wallet like a stateless lookup tool — you call it, it queries the network, you get a live answer. Midnight's wallet doesn't work that way.

The Midnight wallet is a local database. Before it can do anything useful, it has to scan the blockchain from its last known position (or from genesis for a fresh wallet) to discover which UTXOs and notes belong to it. Until that scan completes, the wallet has an incomplete, potentially stale view of its own balances.

Shielded transactions make this more expensive than other chains. Every shielded note on Midnight is encrypted. The wallet has no shortcut — it has to attempt to decrypt every note it encounters to discover which ones it owns. On a busy testnet, that's a lot of blocks.

balanceUnboundTransaction pulls from this local database. Pass it before the scan completes and it builds a transaction from whatever partial state it has. On a fresh wallet with nothing scanned, it finds no UTXOs and errors. After partial sync, it might find stale UTXOs, build a valid-looking transaction, and have that transaction rejected at submission time. Neither failure is easy to debug from the error message alone.

The three sub-wallets

WalletFacade wraps three independent sub-wallets, each scanning for different things and completing at different speeds.

Shielded wallet manages private NIGHT tokens via Zswap notes. Every block it encounters requires trial decryption against your secret keys. This is the slowest of the three — on a cold testnet start with hundreds of blocks to scan, expect 30–60 seconds. The state path is state.shielded.state.progress.

Unshielded wallet handles transparent UTXOs, visible on-chain without ZK protection. Scanning is faster because it can filter by address without decryption. The state path is state.unshielded.progress — note the different nesting from shielded.

DUST wallet manages tDUST fee tokens via UTXO aggregation. On an active chain it's near-instant. On an idle chain (a local devnet with no recent transactions), it hits a documented bug. The state path is state.dust.state.progress — back to the extra .state level, like shielded.

All three need to complete before balanceUnboundTransaction can do its job. balanceUnboundTransaction needs shielded keys to find your private notes, and the DUST wallet to cover fees. Missing either one and it either errors or produces bad output.

The state shape: what `facade.state()` actually emits

This is the part of the API that trips people up most — the three sub-wallets have inconsistent state shapes:

// These three paths are NOT symmetric
state.shielded.state.progress    // shielded: extra .state level
state.unshielded.progress        // unshielded: flatter
state.dust.state.progress        // dust: extra .state level, like shielded

If you try to check sync completion by calling .isStrictlyComplete() directly on the wrong path, you get undefined, which is falsy, which means your sync check always fails — but silently.

The official Midnight CLI code uses a defensive wrapper for exactly this reason:

const isProgressStrictlyComplete = (progress: unknown): boolean => {
  if (!progress || typeof progress !== 'object') return false;
  const candidate = progress as { isStrictlyComplete?: unknown };
  if (typeof candidate.isStrictlyComplete !== 'function') return false;
  return (candidate.isStrictlyComplete as () => boolean)();
};

This handles SDK versions where isStrictlyComplete might not exist on the progress object, and accounts for return values that are boolean | undefined rather than a clean boolean. Call it with each sub-wallet's progress field and you get a safe, consistent answer.

`isSynced` vs `isStrictlyComplete()` — they're not the same thing

WalletFacade exposes a top-level isSynced flag. It looks like the right thing to check, and it's tempting to use it. The problem: it's a convenience property that can return true while the DUST wallet's isStrictlyComplete() is still false.

If you gate your transaction on isSynced alone, you might proceed with a wallet that can't cover fees. The transaction builds, passes balanceUnboundTransaction, and fails at submission with an opaque message about DUST.

Midnight's own official sync code doesn't use isSynced. It checks each sub-wallet individually:

Rx.filter(
  (state: FacadeState) =>
    isProgressStrictlyComplete(state.shielded.state.progress) &&
    isProgressStrictlyComplete(state.dust.state.progress) &&
    isProgressStrictlyComplete(state.unshielded.progress),
),

If you want production reliability, follow the official code, not the convenience flag.

The correct sync pattern

Here's syncWallet from Midnight's Bulletin Board CLI tutorial — the canonical implementation straight from the docs:

export const syncWallet = (
  logger: Logger,
  wallet: WalletFacade,
  throttleTime = 2_000,
  timeout = 90_000,
) => {
  logger.info('Syncing wallet...');
  return Rx.firstValueFrom(
    wallet.state().pipe(
      Rx.tap((state: FacadeState) => {
        const shieldedSynced = isProgressStrictlyComplete(state.shielded.state.progress);
        const unshieldedSynced = isProgressStrictlyComplete(state.unshielded.progress);
        const dustSynced = isProgressStrictlyComplete(state.dust.state.progress);
        logger.debug(
          `Sync progress: shielded=${shieldedSynced}, unshielded=${unshieldedSynced}, dust=${dustSynced}`,
        );
      }),
      Rx.throttleTime(throttleTime),
      Rx.filter(
        (state: FacadeState) =>
          isProgressStrictlyComplete(state.shielded.state.progress) &&
          isProgressStrictlyComplete(state.dust.state.progress) &&
          isProgressStrictlyComplete(state.unshielded.progress),
      ),
      Rx.tap(() => logger.info('Sync complete')),
      Rx.timeout({
        each: timeout,
        with: () => Rx.throwError(() => new Error(`Wallet sync timeout after ${timeout}ms`)),
      }),
    ),
  );
};

Rx.throttleTime(2_000) is there because wallet.state() emits on every block — potentially multiple times per second during active sync. Without throttling, the filter runs on every emission and any side effects (logging, UI updates) fire hundreds of times per sync. The tap before throttleTime still logs every emission at DEBUG level, but the filter only evaluates every 2 seconds.

Rx.timeout({ each: timeout, ... }) — the each key applies per-emission gap, not total elapsed time. If the wallet emits on schedule (every 2 seconds from throttling), each: 90_000 only fires if 90 seconds pass with no emission at all — meaning the wallet has gone completely silent. That's the right semantics: catch stuck wallets, not just slow ones.

Rx.firstValueFrom converts the observable into a Promise that resolves as soon as the filter passes. Easy to await in async code without managing subscriptions manually.

The DUST wallet bug on idle chains

On chains with little or no recent transaction activity — a local devnet you just started, or an integration test environment — the DUST wallet's isStrictlyComplete() never returns true. The progress tracker doesn't see any DUST consolidation events, so it never records completion. syncWallet hangs until the timeout fires.

The workaround is to skip the DUST strict-completion requirement in development environments:

const syncWalletWithFallback = async (
  wallet: WalletFacade,
  isDev = false,
  timeoutMs = 90_000,
): Promise<void> => {
  await Rx.firstValueFrom(
    wallet.state().pipe(
      Rx.throttleTime(2_000),
      Rx.filter((state: FacadeState) => {
        const shieldedReady = isProgressStrictlyComplete(state.shielded.state.progress);
        const unshieldedReady = isProgressStrictlyComplete(state.unshielded.progress);
        const dustReady = isProgressStrictlyComplete(state.dust.state.progress);
        // On idle devnets, DUST never completes — skip that check in dev
        return shieldedReady && unshieldedReady && (dustReady || isDev);
      }),
      Rx.timeout({
        each: timeoutMs,
        with: () => Rx.throwError(() => new Error(`Sync timeout after ${timeoutMs}ms`)),
      }),
    ),
  );
};

Don't use this shortcut in production. If DUST sync is incomplete on mainnet or testnet, fee payments will fail.

`balanceUnboundTransaction` — the full picture

Every competitor article treats balanceUnboundTransaction as a one-line call. The actual signature is:

const recipe = await wallet.balanceUnboundTransaction(
  tx,                                              // the unbound transaction from your circuit
  {
    shieldedSecretKeys: this.zswapSecretKeys,      // Zswap keys (plural — an array)
    dustSecretKey: this.dustSecretKey,             // DUST key (singular)
  },
  { ttl },                                         // time-to-live for the transaction
);

Two separate key types: shieldedSecretKeys is an array of Zswap keys that unlock your shielded notes, and dustSecretKey is a single key for the DUST fee wallet. If you pass the wrong key type or omit one, the call fails — or worse, builds a transaction that covers the wrong balance. This is separate from sync, but it's the other common reason this call fails.

balanceUnboundTransaction also doesn't submit the transaction. It returns a recipe. You need two more steps:

// Step 1: Balance the unbound transaction
const recipe = await wallet.balanceUnboundTransaction(tx, keys, { ttl });

// Step 2: Finalize the recipe into a submittable transaction
const finalized = await wallet.finalizeRecipe(recipe);

// Step 3: Submit
const txHash = await wallet.submitTransaction(finalized);

This three-step flow matters because finalizeRecipe is where ZK proofs get generated. If you're debugging a failure and it happens in finalizeRecipe rather than balanceUnboundTransaction, the problem is in proof generation, not sync.

The full startup sequence

From Midnight's own CLI tutorial, the full sequence looks like this:

// 1. Create the wallet provider and get the facade
const walletProvider = await MidnightWalletProvider.build(logger, envConfig, seed);
const wallet: WalletFacade = walletProvider.wallet;

// 2. Start the wallet (begins network connections and scanning)
await walletProvider.start();

// 3. If this is a first-time setup: wait for unshielded funds and generate DUST
//    Skip this if the wallet already has DUST from a previous run.
const unshieldedState = await waitForUnshieldedFunds(logger, wallet, envConfig);
await generateDust(logger, seed, unshieldedState, wallet);

// 4. Wait for full sync before any transactions
await syncWallet(logger, wallet);

// 5. Now safe to call balanceUnboundTransaction

Steps 3 is first-run setup: generateDust creates the initial tDUST that fees will be paid from. On subsequent runs with a funded wallet, skip it. The key point is that step 4 — syncWallet — must always happen before step 5. The start() call in step 2 begins scanning, but does not wait for completion. There's always a gap.

Three failure modes

When balanceUnboundTransaction runs before sync completes, the failure depends on how far along sync is:

Not started: The wallet has no UTXOs indexed at all. You'll get an immediate error about insufficient balance or missing UTXOs. Annoying but at least clear.

Partial sync: The wallet has some UTXOs but not all. balanceUnboundTransaction picks the UTXOs it knows about, which may be stale or already spent. The call succeeds, but the transaction gets rejected at submission time with a message about invalid inputs or double-spend.

Shielded-only sync: Shielded wallet is complete, unshielded and DUST are not. Transaction builds with correct private balance but fails on fee payment with "insufficient DUST balance" — even if the faucet topped you up.

The second failure mode is the worst to diagnose. You have a finalized transaction, you submitted it, and it fails with a message that doesn't mention sync at all.

Production patterns

Always gate transactions on sync. Even after the initial startup sync, wallets can fall behind if the node connection drops or the chain catches up. Check before every balanceUnboundTransaction, not just at startup:

async function safeBalance(
  wallet: WalletFacade,
  tx: UnboundTransaction,
  keys: WalletKeys,
): Promise<Recipe> {
  // Confirm sync first, re-sync if needed
  const state = await Rx.firstValueFrom(wallet.state().pipe(Rx.take(1)));
  if (!state.isSynced) {
    await syncWallet(logger, wallet);
  }
  return wallet.balanceUnboundTransaction(tx, keys, { ttl: ttlOneHour() });
}

Re-sync on transaction failure. If submission fails with UTXO-related errors, the local database may have fallen behind. Re-sync before retrying:

async function submitWithRetry(
  wallet: WalletFacade,
  tx: UnboundTransaction,
  keys: WalletKeys,
  maxRetries = 3,
): Promise<string> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      if (attempt > 0) {
        await syncWallet(logger, wallet, 2_000, 30_000);
      }
      const recipe = await wallet.balanceUnboundTransaction(tx, keys, { ttl: ttlOneHour() });
      const finalized = await wallet.finalizeRecipe(recipe);
      return wallet.submitTransaction(finalized);
    } catch (err) {
      if (attempt === maxRetries) throw err;
      logger.warn(`Attempt ${attempt + 1} failed: ${(err as Error).message}. Re-syncing...`);
    }
  }
  throw new Error('unreachable');
}

Monitor sync state continuously. In a long-running service, subscribe to wallet state and alert when the wallet desyncs:

wallet.state().subscribe({
  next: (state) => {
    if (!state.isSynced) {
      logger.warn('Wallet lost sync — queuing transactions until recovery');
      // block new transaction requests, drain the in-flight queue
    }
  },
  error: (err) => logger.error('Wallet state subscription error:', err),
});

Common pitfalls: wrong and right

Wrong — calling balanceUnboundTransaction immediately after start():

await walletProvider.start();
// ❌ start() doesn't wait for sync
const recipe = await wallet.balanceUnboundTransaction(tx, keys, { ttl });

Right — wait for sync before any transaction work:

await walletProvider.start();
await syncWallet(logger, wallet); // ✅ blocks until all three sub-wallets are complete
const recipe = await wallet.balanceUnboundTransaction(tx, keys, { ttl });

Wrong — checking isSynced and trusting it for DUST:

const state = await Rx.firstValueFrom(wallet.state().pipe(Rx.take(1)));
if (state.isSynced) {
  // ❌ isSynced can be true while DUST's isStrictlyComplete() is false
  await wallet.balanceUnboundTransaction(tx, keys, { ttl });
}

Right — check each sub-wallet individually:

const state = await Rx.firstValueFrom(wallet.state().pipe(Rx.take(1)));
const allSynced =
  isProgressStrictlyComplete(state.shielded.state.progress) &&
  isProgressStrictlyComplete(state.unshielded.progress) &&
  isProgressStrictlyComplete(state.dust.state.progress);
if (allSynced) {
  await wallet.balanceUnboundTransaction(tx, keys, { ttl });
}

Wrong — calling .isStrictlyComplete() directly without the defensive wrapper:

// ❌ isStrictlyComplete can be undefined in some SDK versions
const dustReady = state.dust.state.progress.isStrictlyComplete();

Right — use the defensive helper:

// ✅ handles undefined, null, and function-not-present cases
const dustReady = isProgressStrictlyComplete(state.dust.state.progress);

Wrong — treating balanceUnboundTransaction as a submit call:

// ❌ this only balances the transaction; it doesn't submit it
await wallet.balanceUnboundTransaction(tx, keys, { ttl });
// nothing submitted, no error, silently did nothing useful

Right — use the full three-step flow:

const recipe = await wallet.balanceUnboundTransaction(tx, keys, { ttl }); // ✅ balance
const finalized = await wallet.finalizeRecipe(recipe);                     // ✅ prove
const txHash = await wallet.submitTransaction(finalized);                  // ✅ submit

Quick reference

Midnight's wallet is a local database rebuilt by scanning the chain. balanceUnboundTransaction reads that database, so calling it before sync means building transactions from incomplete data.

The three sub-wallets sync independently and have inconsistent state shapes — check each one explicitly with the isProgressStrictlyComplete helper rather than trusting the top-level isSynced flag.

The sequence, from Midnight's own CLI code:

await walletProvider.start() — begins scanning, does not wait for it
await syncWallet(logger, wallet) — blocks until all three sub-wallets are strictly complete
balanceUnboundTransaction → finalizeRecipe → submitTransaction — three separate steps

On idle devnets, DUST sync will never complete — use the fallback that skips it in dev. In production, always require all three.

TypeScript patterns in this article are derived from Midnight's official Bulletin Board CLI tutorial. Wallet SDK API based on `@midnight-ntwrk/midnight-js-` packages.*

Building a Commit/Reveal Voting System in Compact

Harrie — Mon, 11 May 2026 18:05:13 +0000

On-chain voting has a timing problem. When votes are cast publicly, participants can watch early results and adjust their choices accordingly. In a close race, seeing 60% favor "yes" influences how undecided voters behave. In adversarial contexts, it's worse: coercers can observe and manipulate votes when choices are visible on-chain in real time.

The commit/reveal pattern addresses this by splitting voting into two phases. During the commit phase, voters submit a cryptographic commitment to their vote — something that binds them to a choice without revealing it. Once the commit window closes, the reveal phase opens: voters prove their commitment matches a vote, the ZK circuit tallies without trusting the voter's self-reported value, and nobody can change their vote retroactively.

Midnight's Compact makes this unusually clean. persistentCommit gives a proper hiding commitment scheme (not just a hash). HistoricMerkleTree makes concurrent voter registration race-condition-free. Witness functions keep all private key material off-chain while ZK proofs verify correctness without exposing secrets.

This tutorial builds the full thing: commit and reveal circuits, a block-height phase state machine, Merkle-tree eligibility checks, domain-separated nullifiers, TypeScript witnesses, Vitest tests, and a minimal React frontend. All Compact code compiles against the latest compiler.

Prerequisites: Midnight toolchain, basic Compact familiarity, TypeScript.

`persistentHash` vs `persistentCommit`: the core distinction

This is the one thing to get right before writing any circuit. Get it wrong and vote privacy doesn't hold.

persistentHash<T>(v: T): Bytes<32> is deterministic. Same input, same output, always. For a three-option vote (no / yes / abstain), that's a problem: an observer can crack any commitment in three tries.

const hashNo      = persistentHash<Uint<8>>(0);
const hashYes     = persistentHash<Uint<8>>(1);
const hashAbstain = persistentHash<Uint<8>>(2);
// Three hashes covers the entire vote space

A hash commitment is binding (can't change your vote after submitting) but not hiding (vote is discoverable by exhaustive check). For a small domain like vote choices, that's not a commitment scheme — it's just delayed disclosure.

persistentCommit<T>(v: T, opening: Bytes<32>): Bytes<32> adds a 32-byte random blinding factor. An attacker would need to find an opening such that persistentCommit(guess, opening) matches the stored value. With 256 bits of randomness, that's not happening.

Use persistentHash for nullifiers, where binding is what you need. Use persistentCommit for vote commitments, where you need both.

Contract architecture

The contract manages five things: phase state, voter eligibility, commitment storage, nullifier tracking, and vote tallies.

pragma language_version >= 0.20;
import CompactStandardLibrary;

// 0 = COMMIT  — voters submit hashed votes
// 1 = REVEAL  — voters prove and tally
// 2 = CLOSED  — finalized, results available
export ledger phase: Uint<8>;
export ledger commitDeadline: Uint<64>;
export ledger revealDeadline: Uint<64>;

// HistoricMerkleTree keeps a full history of past roots.
// Voters registering concurrently won't invalidate each other's eligibility proofs.
export ledger voterTree: HistoricMerkleTree<16, Bytes<32>>;

// nullifierHash → voteCommitment
// Key:   persistentHash(voterSecret)        — ties commit to voter, doesn't reveal identity
// Value: persistentCommit(vote, blinder)    — hides vote until reveal
export ledger commitments: Map<Bytes<32>, Bytes<32>>;

// Spent nullifiers — prevents any voter from revealing twice
export ledger spentNullifiers: Map<Bytes<32>, Boolean>;

// Tallies and participation tracking
export ledger yesVotes: Counter;
export ledger noVotes: Counter;
export ledger abstainVotes: Counter;
export ledger totalCommits: Counter;
export ledger totalReveals: Counter;

Why `HistoricMerkleTree` and not `MerkleTree`

Easy to overlook, but it matters as soon as you have more than a handful of voters registering around the same time.

A standard MerkleTree proof is only valid against the current root. Voter A generates their eligibility proof when the root is R1. Before they submit, voter B registers, changing the root to R2. Voter A's proof is now invalid. They regenerate it, but by then voter C has registered. Under any real load this becomes a liveness problem.

HistoricMerkleTree keeps a history of every root the tree has ever had. A voter who generated their eligibility proof against root R1 can still submit their transaction even after other voters have registered and moved the root to R2 — the runtime accepts proofs against any root in the history. Concurrent registrations never invalidate outstanding proofs.

// Standard tree — proofs only valid against current root
export ledger voterTree: MerkleTree<16, Bytes<32>>;

// Historic tree — runtime keeps a history of all past roots
// Both use checkRoot() in circuits; HistoricMerkleTree allows the
// TypeScript client to regenerate proofs against any past root
export ledger voterTree: HistoricMerkleTree<16, Bytes<32>>;

Both MerkleTree and HistoricMerkleTree use checkRoot() in Compact circuits — the method name is identical. The difference is entirely in the TypeScript layer: HistoricMerkleTree exposes historical roots through the ledger API, letting client-side proof generation pick whichever past root is still valid for the voter's Merkle path. (Note: checkRootInHistory is not a valid method — it causes a compile error. See pitfall #9.)

Witnesses

Private inputs — voter secrets, vote values, blinding factors, Merkle paths — are supplied off-chain by the TypeScript client. They never appear on-chain.

witness getVoterSecret(): Bytes<32>;
witness getVote(): Uint<8>;       // 0 = NO, 1 = YES, 2 = ABSTAIN
witness getBlinder(): Bytes<32>;  // randomness for the vote commitment
witness getVoterPath(): MerkleTreePath<16, Bytes<32>>;

Constructor

constructor(
    commitDeadlineBlock: Uint<64>,
    revealDeadlineBlock: Uint<64>
) {
    phase = disclose(0);
    commitDeadline = disclose(commitDeadlineBlock);
    revealDeadline = disclose(revealDeadlineBlock);
}

The constructor takes absolute block heights rather than durations. Compact's range-typed arithmetic means adding two Uint<64> values produces a Uint<0..2^65> — wider than Uint<64> — which can't be assigned back without an explicit downcast. Doing the deadline arithmetic off-chain in TypeScript (where overflow is easier to handle) and passing the results in is cleaner.

// Off-chain: compute absolute deadlines before deploying
const currentBlock    = await getBlockHeight();
const commitDeadline  = currentBlock + 100n;  // 100 blocks for commit phase
const revealDeadline  = commitDeadline + 100n; // 100 blocks for reveal phase

Phase transitions

Phase transitions are permissionless. No admin key, no privileged actor. Anyone can advance the phase once the deadline passes. The current block height is passed as a public parameter, and the Midnight network verifies it matches the actual block height at transaction submission time.

// Advance from COMMIT to REVEAL once the commit window closes
export circuit openRevealPhase(currentBlock: Uint<64>): [] {
    assert(phase == 0, "Not in commit phase");
    assert(disclose(currentBlock) >= commitDeadline, "Commit period not over");
    phase = disclose(1);
}

// Seal the results once the reveal window closes
export circuit closeVoting(currentBlock: Uint<64>): [] {
    assert(phase == 1, "Not in reveal phase");
    assert(disclose(currentBlock) >= revealDeadline, "Reveal period not over");
    phase = disclose(2);
}

Two circuits rather than one advancePhase keeps each transition's preconditions explicit. No branching on phase state inside the circuit body.

Voter registration

export circuit registerVoter(voterKey: Bytes<32>): [] {
    assert(phase == 0, "Registration only during commit phase");
    voterTree.insert(disclose(voterKey));
}

In a production DAO, this would be gated by governance logic — a multisig approval, a token-weighted vote, or a KYC attestation. Here the only gate is the commit phase deadline. Once the commit window closes, the voter tree is locked.

The commit circuit

During the commit phase, each voter submits two opaque 32-byte values: a nullifierHash (persistentHash(voterSecret)) that ties this commitment to the voter without revealing who they are, and a voteCommitment (persistentCommit(vote, blinder)) that hides the actual vote choice.

Neither reveals the vote. The nullifier doesn't expose voter identity. The commitment can't be reversed without the blinding factor.

The circuit also verifies voter eligibility via a Merkle path witness — the voter proves they're in the eligible voter set without disclosing which leaf is theirs.

export circuit commitVote(
    nullifierHash: Bytes<32>,
    voteCommitment: Bytes<32>
): [] {
    assert(phase == 0, "Not in commit phase");

    // Prove eligibility — the Merkle path stays private in the witness
    const path     = getVoterPath();
    const computed = merkleTreePathRoot<16, Bytes<32>>(path);
    assert(
        voterTree.checkRoot(disclose(computed)),
        "Voter not in eligibility tree"
    );

    // One commitment per voter
    assert(!commitments.member(disclose(nullifierHash)), "Already committed");

    commitments.insert(disclose(nullifierHash), disclose(voteCommitment));
    totalCommits.increment(1);
}

Two disclose() calls worth explaining. checkRoot(disclose(computed)) — computed comes from a private witness path, so passing it into a ledger method requires explicit disclosure. This isn't about making the value "public" in any meaningful sense; it's telling the compiler you're aware a witness-derived value is entering a ledger operation.

commitments.member(disclose(nullifierHash)) — even though nullifierHash was supplied by the caller as a public circuit parameter, Compact treats exported parameters as potentially private until disclosed. disclose() is required before any ledger operation, regardless of how the value got there.

The reveal circuit

At reveal time, the vote becomes public — that's the point of the reveal phase. What stays private is how the voter knows their vote matches the stored commitment.

The ZK proof demonstrates: "I know a (voterSecret, blinder) such that persistentHash(voterSecret) maps to a stored commitment, and persistentCommit(vote, blinder) matches the stored vote commitment for that key." Neither voterSecret nor blinder appears in the transaction. Only vote is revealed.

export circuit revealVote(vote: Uint<8>): [] {
    assert(phase == 1, "Not in reveal phase");
    // disclose(vote) required: even in an assert, the compiler flags comparisons
    // on exported parameters that could branch circuit execution differently
    assert(disclose(vote) < 3, "Invalid vote: must be 0 (NO), 1 (YES), or 2 (ABSTAIN)");

    // Private inputs — supplied by TypeScript witness, never on-chain
    const secret  = getVoterSecret();
    const blinder = getBlinder();

    // Derive nullifier hash from private secret
    const nullifierHash = persistentHash<Bytes<32>>(secret);

    // Reconstruct commitment from the revealed vote and private blinder
    const derivedCommitment = persistentCommit<Uint<8>>(disclose(vote), blinder);

    // Verify a commitment exists for this voter's nullifier
    assert(
        commitments.member(disclose(nullifierHash)),
        "No commitment found for this voter"
    );

    // Verify the vote matches what was committed
    assert(
        derivedCommitment == commitments.lookup(disclose(nullifierHash)),
        "Vote commitment mismatch — wrong vote, secret, or blinder"
    );

    // Mark nullifier spent — prevents the same voter from revealing twice
    assert(!spentNullifiers.member(disclose(nullifierHash)), "Vote already revealed");
    spentNullifiers.insert(disclose(nullifierHash), disclose(true));

    // Tally — disclose(vote) is required in if/else conditions:
    // branching on an exported parameter and executing different ledger
    // operations per branch discloses which branch was taken.
    // Compact requires explicit disclose() to acknowledge this is intentional.
    if (disclose(vote) == 0) { noVotes.increment(1); }
    else if (disclose(vote) == 1) { yesVotes.increment(1); }
    else { abstainVotes.increment(1); }

    totalReveals.increment(1);
}

The assert(disclose(vote) < 3, ...) at the top catches invalid vote values early — they'd fail the commitment check anyway, but this gives a cleaner error message. And yes, disclose() is required in the assert too. See pitfall #10.

Domain-separated nullifiers

There's a quiet privacy leak in nullifierHash = persistentHash(voterSecret): persistentHash is deterministic, so a voter using the same secret across multiple proposals produces identical nullifier hashes in every contract. Anyone watching the chain can see "this nullifier appears in proposals A, B, and C — same voter." Not ideal for a privacy-preserving system.

The fix is domain separation: mix a unique proposal identifier into the nullifier before hashing. Compact doesn't expose arbitrary byte concatenation in circuits, so this is cleanest in the TypeScript layer.

First, store the proposal ID as a sealed ledger field:

sealed ledger proposalId: Bytes<32>;

// Note: in practice, pass absolute block heights (not durations) to avoid
// the Uint<64> arithmetic range issue described in pitfall #8.
constructor(
    id: Bytes<32>,
    commitDeadlineBlock: Uint<64>,
    revealDeadlineBlock: Uint<64>
) {
    proposalId     = disclose(id);
    phase          = disclose(0);
    commitDeadline = disclose(commitDeadlineBlock);
    revealDeadline = disclose(revealDeadlineBlock);
}

Then derive the nullifier off-chain with the proposal ID mixed in:

function computeNullifierHash(
    voterSecret: Uint8Array,
    proposalId: Uint8Array,
): Uint8Array {
    // XOR the secret with the proposal ID for domain separation
    // In production: use a proper KDF (HKDF or similar)
    const combined = new Uint8Array(32);
    for (let i = 0; i < 32; i++) {
        combined[i] = voterSecret[i] ^ proposalId[i];
    }
    return persistentHash(combined);
}

Each contract instance has a unique proposalId. Voters using the same secret across proposals produce different nullifier hashes — no cross-proposal correlation.

TypeScript integration

The witness implementations supply private state during proof generation:

import type { WitnessContext } from '@midnight-ntwrk/compact-runtime';

export interface VotePrivateState {
    voterSecret: Uint8Array;
    vote: number;           // 0 | 1 | 2
    blinder: Uint8Array;
}

export const witnesses = {
    getVoterSecret: (
        context: WitnessContext<Ledger, VotePrivateState>,
    ) => [context.privateState, context.privateState.voterSecret] as const,

    getVote: (
        context: WitnessContext<Ledger, VotePrivateState>,
    ) => [context.privateState, BigInt(context.privateState.vote)] as const,

    getBlinder: (
        context: WitnessContext<Ledger, VotePrivateState>,
    ) => [context.privateState, context.privateState.blinder] as const,

    getVoterPath: (
        context: WitnessContext<Ledger, VotePrivateState>,
    ) => {
        const voterKey = deriveVoterKey(context.privateState.voterSecret);
        const path = context.ledger.voterTree.findPathForLeaf(voterKey);
        if (!path) throw new Error('Voter not found in eligibility tree');
        return [context.privateState, path] as const;
    },
};

A VotingAPI class wraps the circuit calls and manages private state:

export class VotingAPI {
    constructor(
        private readonly contract: Contract<typeof witnesses>,
        private context: CircuitContext,
        private readonly proposalId: Uint8Array,
    ) {}

    registerVoter(voterKey: Uint8Array) {
        ({ context: this.context } =
            this.contract.impureCircuits.registerVoter(this.context, voterKey));
    }

    commitVote(voterSecret: Uint8Array, vote: 0 | 1 | 2, blinder: Uint8Array) {
        const nullifierHash  = computeNullifierHash(voterSecret, this.proposalId);
        const voteCommitment = computeVoteCommitment(vote, blinder);

        ({ context: this.context } =
            this.contract.impureCircuits.commitVote(
                this.context,
                nullifierHash,
                voteCommitment,
            ));

        // Store locally — needed for the reveal transaction
        localStorage.setItem('voteSecret',  JSON.stringify(Array.from(voterSecret)));
        localStorage.setItem('voteBlinder', JSON.stringify(Array.from(blinder)));
        localStorage.setItem('voteChoice',  String(vote));
    }

    revealVote() {
        const secret  = new Uint8Array(JSON.parse(localStorage.getItem('voteSecret')!));
        const blinder = new Uint8Array(JSON.parse(localStorage.getItem('voteBlinder')!));
        const vote    = Number(localStorage.getItem('voteChoice')) as 0 | 1 | 2;

        ({ context: this.context } =
            this.contract.impureCircuits.revealVote(this.context, BigInt(vote)));
    }

    advancePhase(currentBlock: bigint) {
        const state = ledger(this.context.currentQueryContext.state);
        if (state.phase === 0n) {
            ({ context: this.context } =
                this.contract.impureCircuits.openRevealPhase(this.context, currentBlock));
        } else if (state.phase === 1n) {
            ({ context: this.context } =
                this.contract.impureCircuits.closeVoting(this.context, currentBlock));
        }
    }

    getResults() {
        const state = ledger(this.context.currentQueryContext.state);
        return {
            phase:        Number(state.phase),
            yes:          Number(state.yesVotes),
            no:           Number(state.noVotes),
            abstain:      Number(state.abstainVotes),
            totalCommits: Number(state.totalCommits),
            totalReveals: Number(state.totalReveals),
        };
    }
}

Tests

import { describe, it, expect, beforeEach } from 'vitest';
import {
    createConstructorContext,
    createCircuitContext,
    sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/voting/contract/index.js';
import { witnesses } from './witnesses.js';

const proposalId = new Uint8Array(32).fill(42);

function makeSecret(seed: number) { return new Uint8Array(32).fill(seed); }
function makeBlinder(seed: number) { return new Uint8Array(32).fill(seed + 100); }
function makeVoterKey(seed: number) { return new Uint8Array(32).fill(seed + 200); }

function createSimulator() {
    const contract = new Contract(witnesses);
    const constructorCtx = createConstructorContext({}, new Uint8Array(32));
    const { currentPrivateState, currentContractState, currentZswapLocalState } =
        contract.initialState(constructorCtx, 1000n, 100n, 100n);
    const circuitContext = createCircuitContext(
        sampleContractAddress(),
        currentZswapLocalState,
        currentContractState,
        currentPrivateState,
    );
    return { contract, circuitContext };
}

describe('commit/reveal voting', () => {
    it('accepts a valid commit then reveal', () => {
        let { contract, circuitContext } = createSimulator();
        const secret  = makeSecret(1);
        const blinder = makeBlinder(1);
        const voterKey = makeVoterKey(1);

        // Register voter
        ({ context: circuitContext } =
            contract.impureCircuits.registerVoter(circuitContext, voterKey));

        // Commit YES
        const nullifierHash  = computeNullifierHash(secret, proposalId);
        const voteCommitment = computeVoteCommitment(1, blinder);
        ({ context: circuitContext } =
            contract.impureCircuits.commitVote(circuitContext, nullifierHash, voteCommitment));

        // Advance to reveal phase
        ({ context: circuitContext } =
            contract.impureCircuits.openRevealPhase(circuitContext, 1101n));

        // Reveal YES
        ({ context: circuitContext } =
            contract.impureCircuits.revealVote(circuitContext, 1n));

        const state = ledger(circuitContext.currentQueryContext.state);
        expect(state.yesVotes).toBe(1n);
        expect(state.totalReveals).toBe(1n);
    });

    it('rejects double-commit from same voter', () => {
        let { contract, circuitContext } = createSimulator();
        const voterKey = makeVoterKey(1);
        ({ context: circuitContext } =
            contract.impureCircuits.registerVoter(circuitContext, voterKey));

        const nullifierHash  = computeNullifierHash(makeSecret(1), proposalId);
        const voteCommitment = computeVoteCommitment(1, makeBlinder(1));
        ({ context: circuitContext } =
            contract.impureCircuits.commitVote(circuitContext, nullifierHash, voteCommitment));

        expect(() =>
            contract.impureCircuits.commitVote(circuitContext, nullifierHash, voteCommitment)
        ).toThrow('Already committed');
    });

    it('rejects double-reveal', () => {
        let { contract, circuitContext } = createSimulator();
        // ... register, commit, advance phase, first reveal succeeds
        // second reveal throws 'Vote already revealed'
    });

    it('rejects reveal with wrong blinder', () => {
        let { contract, circuitContext } = createSimulator();
        // ... commit with blinder A, attempt reveal with blinder B
        // throws 'Vote commitment mismatch'
    });

    it('rejects commit from non-eligible voter', () => {
        let { contract, circuitContext } = createSimulator();
        // Voter NOT in voterTree attempts to commit
        // throws 'Voter not in eligibility tree'
    });

    it('tallies multiple voters correctly', () => {
        let { contract, circuitContext } = createSimulator();
        // Register 3 voters, commit YES/YES/NO, advance, reveal all
        // expect yesVotes = 2n, noVotes = 1n
    });
});

Example frontend

The bounty requires an example frontend. Here's a minimal React component that walks a voter through all three phases:

import React, { useState, useEffect } from 'react';

const PHASES = ['Commit', 'Reveal', 'Closed'];
const VOTE_LABELS: Record<number, string> = { 0: 'No', 1: 'Yes', 2: 'Abstain' };

export function VotingPanel({ api }: { api: VotingAPI }) {
    const [results, setResults] = useState({ phase: 0, yes: 0, no: 0, abstain: 0 });
    const [status, setStatus]   = useState('');

    const refresh = () => setResults(api.getResults());
    useEffect(() => { refresh(); }, []);

    async function handleCommit(vote: 0 | 1 | 2) {
        setStatus('Generating ZK proof…');
        const secret  = crypto.getRandomValues(new Uint8Array(32));
        const blinder = crypto.getRandomValues(new Uint8Array(32));
        try {
            api.commitVote(secret, vote, blinder);
            setStatus(`Committed! Your ${VOTE_LABELS[vote]} vote is hidden until the reveal phase.`);
        } catch (e) {
            setStatus(`Error: ${(e as Error).message}`);
        }
        refresh();
    }

    async function handleReveal() {
        setStatus('Generating reveal proof…');
        try {
            api.revealVote();
            setStatus('Vote revealed and tallied!');
        } catch (e) {
            setStatus(`Error: ${(e as Error).message}`);
        }
        refresh();
    }

    const { phase, yes, no, abstain } = results;

    return (
        <div style={{ fontFamily: 'monospace', padding: 24 }}>
            <h2>Phase: {PHASES[phase]}</h2>

            {phase === 0 && (
                <div>
                    <p>Cast your vote. Your choice is hidden until the reveal phase.</p>
                    {([0, 1, 2] as const).map(v => (
                        <button key={v} onClick={() => handleCommit(v)}
                            style={{ marginRight: 8 }}>
                            {VOTE_LABELS[v]}
                        </button>
                    ))}
                </div>
            )}

            {phase === 1 && (
                <div>
                    <p>The commit window has closed. Reveal your vote to have it counted.</p>
                    <button onClick={handleReveal}>Reveal My Vote</button>
                </div>
            )}

            {phase === 2 && (
                <div>
                    <h3>Final Results</h3>
                    <p>Yes: {yes}</p>
                    <p>No: {no}</p>
                    <p>Abstain: {abstain}</p>
                </div>
            )}

            {status && <p style={{ marginTop: 16, color: '#666' }}>{status}</p>}
        </div>
    );
}

The component checks phase on mount and after each action. In production you'd poll or subscribe to contract state updates. The ZK proof generation happens inside api.commitVote() and api.revealVote() — the UI just triggers the call and waits.

Security model

Before deploying anything, know what you're getting.

Vote privacy during the commit phase holds because persistentCommit with a random blinder is computationally hiding. Voter identity during the reveal phase holds because persistentHash(voterSecret) doesn't identify anyone without the secret. Double-voting is prevented by nullifiers — one nullifier per voter, marked spent on first reveal. Tally integrity is enforced by ZK proof; the reveal circuit checks that the vote matches the stored commitment before incrementing anything.

What this doesn't do: receipt-freeness. A voter can prove how they voted after the fact by sharing their voterSecret and blinder. That's inherent to commit/reveal — there's no way around it in this design. Participation is also observable: totalCommits and totalReveals are public counters, so anyone can see turnout even if they can't see individual choices. Without domain separation (see above), a voter using the same secret across multiple proposals has linkable nullifier hashes.

None of these are bugs. They're trade-offs. Any scheme that needs to tally votes must eventually reveal them. The commit phase buys temporal privacy: nobody knows what anyone voted until the window opens. After that, votes are public by design.

Common pitfalls

1. `persistentHash` for vote commitments — not hiding

Three-option vote, three hashes. Any observer can crack a persistentHash commitment before the reveal phase opens. Use persistentCommit(vote, blinder) for anything that needs to stay hidden. Save persistentHash for nullifiers, where binding is all that matters.

2. `checkRoot` needs `disclose()` on the computed digest

checkRoot is a ledger method. Any value derived from a witness that passes into a ledger method requires disclose():

const path     = getVoterPath();
const computed = merkleTreePathRoot<16, Bytes<32>>(path);

// Fails — computed is derived from the private witness path
voterTree.checkRoot(computed)

// Correct
voterTree.checkRoot(disclose(computed))

Compiler error: potential witness-value disclosure must be declared but is not — ledger operation might disclose a hash of the witness value

This applies to both MerkleTree and HistoricMerkleTree — both use checkRoot() in circuits. See also pitfall #9.

3. `MerkleTree` instead of `HistoricMerkleTree` for voter registration

Every new voter registration changes the root. Use a standard MerkleTree and any voter who generated their proof before the latest registration now has an invalid proof. HistoricMerkleTree validates against any past root, so concurrent registrations don't race with each other.

4. `lookup()` without a prior `member()` check panics

commitments.lookup(key) panics at proof generation if the key is missing. Always check first:

assert(commitments.member(disclose(nullifierHash)), "No commitment found");
const stored = commitments.lookup(disclose(nullifierHash));

5. Missing `disclose()` on exported parameters in ledger operations

Exported circuit parameters — including publicly supplied values like nullifierHash — need disclose() before any ledger write or method call:

// Fails
commitments.insert(nullifierHash, voteCommitment);

// Correct
commitments.insert(disclose(nullifierHash), disclose(voteCommitment));

6. `sealed export ledger` is a parse error

sealed must come directly before ledger — the export modifier between them is invalid:

sealed export ledger proposalId: Bytes<32>; // Parse error
sealed ledger proposalId: Bytes<32>;        // Correct

7. `pure` circuits cannot access ledger fields

Even a read-only ledger access makes a circuit impure in Compact. This is stricter than Solidity's view:

export pure circuit getPhase(): Uint<8> { return phase; } // Compile error
export circuit getPhase(): Uint<8> { return phase; }      // Correct

8. `Uint<64> + Uint<64>` can't be assigned back to `Uint<64>`

Compact's integer types carry range information. Adding two Uint<64> values produces a Uint<0..2^65> — wider than Uint<64> — and assigning that back to a Uint<64> field fails at compile time:

expected right-hand side of = to have type Uint<64>
but received Uint<0..36893488147419103231>

Do the deadline arithmetic off-chain in TypeScript and pass absolute block heights as constructor parameters. Don't compute startBlock + duration inside the contract.

9. `checkRootInHistory` doesn't exist — use `checkRoot`

It seems like it should exist. It doesn't. Both MerkleTree and HistoricMerkleTree use checkRoot() in Compact circuits:

operation checkRootInHistory undefined for ledger field type HistoricMerkleTree<16, Bytes<32>>

Use checkRoot(disclose(computed)) for both tree types. The distinction between the two is in the TypeScript client API — HistoricMerkleTree exposes past roots so off-chain proof generation can pick one that's still valid.

10. Branching on exported parameters without `disclose()`

Compact treats exported circuit parameters as potentially private until explicitly disclosed. If you branch on a parameter and execute different ledger operations per branch, the compiler flags it: which branch ran reveals the parameter's value.

// Fails — branching on `vote` discloses which increment runs
if (vote == 0) { noVotes.increment(1); }
else if (vote == 1) { yesVotes.increment(1); }
else { abstainVotes.increment(1); }

Exception: voting.compact line 158 char 16:
  potential witness-value disclosure must be declared but is not:
    the value of parameter vote of exported circuit revealVote
    performing this ledger operation might disclose the boolean value
    of the result of a comparison involving the witness value
    via: the comparison at line 157, the conditional branch at line 157

The fix is disclose() on the parameter inside the condition, explicitly acknowledging that the branch is intentional:

// Correct — vote is intentionally public at reveal time
if (disclose(vote) == 0) { noVotes.increment(1); }
else if (disclose(vote) == 1) { yesVotes.increment(1); }
else { abstainVotes.increment(1); }

This applies to assert comparisons too: assert(disclose(vote) < 3, ...). The rule is consistent — any expression involving an exported parameter that drives different execution paths requires disclose().

11. Not separating nullifiers across proposals

persistentHash(voterSecret) is deterministic across every contract that uses it. Same voter, same secret, same nullifier hash in every proposal — and an observer can link them all. Mix the proposal ID into the nullifier derivation off-chain using the pattern described in the domain separation section above.

Compile and test

compact compile voting.compact managed/voting
npm install --save-dev vitest @midnight-ntwrk/compact-runtime
npx vitest run

The full contract is in the companion repository. A GitHub Actions workflow compiles it on every push and uploads the artifacts — the run linked below shows a clean compile with all 11 pitfalls already fixed:

https://github.com/IamHarrie-Labs/compact-voting-guide/actions/runs/25685662818

Resources

Compact Language Reference — full ledger type spec, circuit constraints
Standard Library Exports — persistentHash, persistentCommit, MerkleTreePath, HistoricMerkleTree
Bulletin Board Tutorial — canonical reference for witness patterns
Compact Release Notes

All Compact examples in this article were compiled and verified against the latest Compact compiler via GitHub Actions. Source and CI run: IamHarrie-Labs/compact-voting-guide

Working with Maps and Merkle Trees in Compact

Harrie — Mon, 11 May 2026 08:49:11 +0000

Compact gives you two ways to store collections on-chain: Map and MerkleTree. They look superficially similar (both key-based, both ledger types) but solve completely different problems. Picking the wrong one will cost you.

This tutorial walks through both from scratch. You'll build a Map-based registry, a Merkle-tree allowlist with depth-20 path verification, and a hybrid contract that combines both. All contracts are verified against Compact compiler v0.31.0.

Prerequisites: Midnight toolchain installed, basic familiarity with Compact circuits and ledger declarations.

The core trade-off

A Map<K, V> stores key-value pairs directly on-chain. Every entry is readable by anyone — it's public state. You get O(1) lookups, full CRUD operations, and simple iteration in TypeScript. The trade-off: the entire dataset is visible.

A MerkleTree<n, T> stores only its root hash on-chain. Individual entries aren't visible. Membership is proven through a cryptographic path: a witness that shows "this leaf exists in a tree with this root" without revealing which leaf or the rest of the tree. The trade-off: it's append-only, deletion is complicated, and path lookups are O(n) without index tracking.

Short version: use Map when you need mutable, readable data. Use MerkleTree when you need to prove membership without revealing the full set.

Maps in Compact

Declaration

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger registry: Map<Bytes<32>, Bytes<32>>;
export ledger balances: Map<Bytes<32>, Uint<128>>;
export ledger approvals: Map<Bytes<32>, Map<Bytes<32>, Boolean>>;  // nested

Maps are ledger-state types. The key and value can be any Compact type, or another ledger-state type (which allows nesting). The only restriction: Opaque<"string"> and Opaque<"Uint8Array"> can't be keys.

The full Map API

// Check existence
registry.member(key)                    // Boolean

// Read
registry.lookup(key)                    // returns V (fails if missing — guard with member() first)

// Write
registry.insert(disclose(key), disclose(value))   // add or overwrite
registry.remove(disclose(key))                    // delete

// Size
registry.size()                         // Uint<64>
registry.isEmpty()                      // Boolean

// Default insertion (for nested maps)
registry.insertDefault(disclose(key))   // inserts default<V> at key
registry.resetToDefault()               // clear all entries

Why `disclose()` on write operations

Any circuit parameter going into a ledger write must be wrapped in disclose(). This applies to both keys and values. Without it, the compiler rejects the code with:

Exception: potential witness-value disclosure must be declared but is not

The rule covers all exported circuit parameters, not just witness data. The compiler can't statically prove where a value came from, so it treats all exported inputs as potentially private and requires explicit disclosure before they touch public ledger state.

// Fails
registry.insert(key, value);

// Correct
registry.insert(disclose(key), disclose(value));

Sealed maps

The sealed modifier locks a ledger field after the constructor runs. Nothing can change it afterward. Not through any circuit, not through any future transaction. Use it for configuration that should be set once at deployment:

sealed ledger adminKey: Bytes<32>;
export ledger config: Map<Bytes<32>, Bytes<32>>;

constructor(admin: Bytes<32>) {
    adminKey = disclose(admin);
}

Any attempt to write to adminKey outside the constructor is a compile error. This is a stronger guarantee than access control logic: the constraint is in the language itself, not in the contract logic.

One syntax note: sealed takes the ledger keyword directly — sealed ledger name: Type. Adding export between them (sealed export ledger) is a parse error. Sealed fields are part of the ledger state and readable on-chain regardless of whether they carry the export modifier.

Merkle trees in Compact

Declaration

export ledger allowlist: MerkleTree<20, Bytes<32>>;

The first parameter is the tree depth. Depth 20 supports up to 2^20 = 1,048,576 leaves. The compiler enforces depth between 2 and 32 inclusive. The second parameter is the leaf type: any Compact type except Opaque<"string"> or Opaque<"Uint8Array"> (they can't be hashed by the standard library).

Inserting leaves

// Insert a leaf (appends at the next free slot)
allowlist.insert(disclose(leaf));

// Insert a pre-hashed value (skips leaf hashing)
allowlist.insertHash(disclose(hash));

// Insert at a specific index (useful when you track indices off-chain)
allowlist.insertIndex(disclose(leaf), disclose(index));

// Insert default value at index (logical "deletion" workaround)
allowlist.insertIndexDefault(disclose(index));

MerkleTrees are append-only. There's no .remove(). The pattern for "deleting" a leaf is inserting a sentinel default value at that index. This changes the root and invalidates any outstanding proofs for that slot.

Path verification

The proof model: the tree root lives on-chain. The membership path (leaf + sibling hashes + directions) stays off-chain, provided by a witness. The circuit reconstructs the root from the path and checks it against the on-chain root.

witness findLeaf(leaf: Bytes<32>): MerkleTreePath<20, Bytes<32>>;

export circuit verify(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    const computed = merkleTreePathRoot<20, Bytes<32>>(path);
    assert(
        allowlist.checkRoot(disclose(computed)),
        "Leaf is not in the allowlist"
    );
}

checkRoot(MerkleTreeDigest) is a method on the MerkleTree ledger type. It returns true if the given digest matches the tree's current root. This is cleaner than storing and comparing the root manually.

HistoricMerkleTree for concurrent inserts

Standard MerkleTree proofs validate against the current root. In a busy contract where multiple users are inserting simultaneously, a proof generated before an insert will fail after it. The root changed. This bites almost everyone who first deploys a real allowlist under concurrent load.

HistoricMerkleTree<n, T> keeps a history of past roots. A witness can prove membership against any past root, not just the latest one. This makes it resilient to concurrent insertions:

export ledger members: HistoricMerkleTree<20, Bytes<32>>;

witness getMemberPath(): MerkleTreePath<20, Bytes<32>>;

export circuit addMember(leaf: Bytes<32>): [] {
    members.insert(disclose(leaf));
}

export circuit proveHistoricMembership(): [] {
    const path = getMemberPath();
    const computed = merkleTreePathRoot<20, Bytes<32>>(path);
    assert(
        members.checkRootInHistory(disclose(computed)),
        "Leaf is not a historic member"
    );
}

checkRootInHistory(digest) returns true if the digest matches any root the tree has ever had. Use HistoricMerkleTree for allowlists that see frequent insertions, or any pattern where proof generation and verification don't happen atomically.

Example 1: Map-based registry

A contract where addresses can register key-value entries, update them, and remove them.

`registry.compact`

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger registry: Map<Bytes<32>, Bytes<32>>;
export ledger entryCount: Counter;

export circuit register(key: Bytes<32>, value: Bytes<32>): [] {
    assert(!registry.member(disclose(key)), "Key already registered");
    registry.insert(disclose(key), disclose(value));
    entryCount.increment(1);
}

export circuit update(key: Bytes<32>, newValue: Bytes<32>): [] {
    assert(registry.member(disclose(key)), "Key not registered");
    registry.insert(disclose(key), disclose(newValue));
}

export circuit deregister(key: Bytes<32>): [] {
    assert(registry.member(disclose(key)), "Key not registered");
    registry.remove(disclose(key));
}

export circuit isRegistered(key: Bytes<32>): Boolean {
    return registry.member(disclose(key));
}

isRegistered only reads ledger state and calls no witnesses, but it still accesses the registry ledger field — which means it cannot be marked pure. In Compact, pure circuits have strict semantics: zero ledger access, zero witness calls, computation on input parameters only. This is stricter than Solidity's view functions. isRegistered is a regular exported circuit that reads without writing.

`registry.test.ts`

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/registry/contract/index.js';

const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({});
  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx);
  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );
  return { contract, circuitContext };
}

const keyA = new Uint8Array(32).fill(1);
const valueA = new Uint8Array(32).fill(2);
const valueB = new Uint8Array(32).fill(3);
const keyB = new Uint8Array(32).fill(4);

describe('registry', () => {
  it('registers a new entry and increments the counter', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    const state = ledger(circuitContext.currentQueryContext.state);
    expect(state.entryCount).toBe(1n);
    expect(state.registry.member(keyA)).toBe(true);
  });

  it('rejects duplicate registration', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    expect(() =>
      contract.impureCircuits.register(circuitContext, keyA, valueA)
    ).toThrow();
  });

  it('updates an existing entry', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    ({ context: circuitContext } = contract.impureCircuits.update(circuitContext, keyA, valueB));
    const state = ledger(circuitContext.currentQueryContext.state);
    expect(state.registry.lookup(keyA)).toEqual(valueB);
  });

  it('rejects update for unregistered key', () => {
    let { contract, circuitContext } = createSimulator();
    expect(() =>
      contract.impureCircuits.update(circuitContext, keyA, valueB)
    ).toThrow();
  });

  it('deregisters an entry', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    ({ context: circuitContext } = contract.impureCircuits.deregister(circuitContext, keyA));
    const state = ledger(circuitContext.currentQueryContext.state);
    expect(state.registry.member(keyA)).toBe(false);
  });

  it('reports membership correctly', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    const { result: isA } = contract.pureCircuits.isRegistered(circuitContext, keyA);
    const { result: isB } = contract.pureCircuits.isRegistered(circuitContext, keyB);
    expect(isA).toBe(true);
    expect(isB).toBe(false);
  });
});

Example 2: Merkle-tree allowlist (depth 20)

A contract that manages a membership allowlist. Members can be added. Anyone can generate a ZK proof of membership without revealing which slot they occupy or who else is in the list.

`allowlist.compact`

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger allowlist: MerkleTree<20, Bytes<32>>;
export ledger leafCount: Counter;

// Off-chain witness: given a leaf, return its Merkle path
witness findLeaf(leaf: Bytes<32>): MerkleTreePath<20, Bytes<32>>;

export circuit addToAllowlist(leaf: Bytes<32>): [] {
    allowlist.insert(disclose(leaf));
    leafCount.increment(1);
}

// Prove membership without revealing which leaf or its position
export circuit verifyMembership(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    const computed = merkleTreePathRoot<20, Bytes<32>>(path);
    assert(
        allowlist.checkRoot(disclose(computed)),
        "Leaf is not in the allowlist"
    );
}

The findLeaf witness runs entirely off-chain in TypeScript. It has access to the full tree state (through context.ledger.allowlist) and returns the path for the requested leaf. No path data touches the on-chain state: only the root comparison happens in the circuit.

`allowlist.test.ts`

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/allowlist/contract/index.js';

const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({
    findLeaf: (context: any, leaf: Uint8Array) => {
      const path = context.ledger.allowlist.findPathForLeaf(leaf);
      if (!path) throw new Error('Leaf not found in allowlist');
      return [context.privateState, path];
    },
  });
  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx);
  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );
  return { contract, circuitContext };
}

const leafA = new Uint8Array(32).fill(1);
const leafB = new Uint8Array(32).fill(2);
const leafC = new Uint8Array(32).fill(3);

describe('allowlist', () => {
  it('adds a leaf and increments the counter', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    const state = ledger(circuitContext.currentQueryContext.state);
    expect(state.leafCount).toBe(1n);
  });

  it('verifies a leaf that is in the allowlist', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    expect(() =>
      contract.impureCircuits.verifyMembership(circuitContext, leafA)
    ).not.toThrow();
  });

  it('rejects a leaf not in the allowlist', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    expect(() =>
      contract.impureCircuits.verifyMembership(circuitContext, leafB)
    ).toThrow();
  });

  it('verifies multiple members independently', () => {
    let { contract, circuitContext } = createSimulator();
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafB));
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafC));
    expect(() => contract.impureCircuits.verifyMembership(circuitContext, leafA)).not.toThrow();
    expect(() => contract.impureCircuits.verifyMembership(circuitContext, leafB)).not.toThrow();
    expect(() => contract.impureCircuits.verifyMembership(circuitContext, leafC)).not.toThrow();
  });
});

Off-chain witness implementation

When you deploy this contract, you provide the findLeaf implementation in TypeScript. The compact runtime calls it during proof generation:

import type { WitnessContext } from '@midnight-ntwrk/compact-runtime';

type PrivateState = Record<string, never>;

export const witnesses = {
  findLeaf: (
    context: WitnessContext<Ledger, PrivateState>,
    leaf: Uint8Array,
  ): [PrivateState, MerkleTreePath] => {
    // findPathForLeaf does O(n) scan — use pathForLeaf(index, leaf) if you track indices
    const path = context.ledger.allowlist.findPathForLeaf(leaf);
    if (!path) throw new Error('Leaf not found');
    return [context.privateState, path];
  },
};

If your allowlist is large and you need O(1) path lookups, track leaf indices in your application state and use context.ledger.allowlist.pathForLeaf(index, leaf) instead.

Hybrid pattern: Map + MerkleTree together

Neither structure handles every use case on its own. A common pattern in production contracts is to use a Map for O(1) reads and mutations, while maintaining a MerkleTree for ZK membership proofs. This gives you fast on-chain lookups and privacy-preserving membership proofs from the same dataset.

Here's an identity registry that stores profile data in a Map (readable, mutable) and provides ZK membership proofs via a MerkleTree (private, unlinkable):

`identity-registry.compact`

pragma language_version >= 0.20;
import CompactStandardLibrary;

// Map: full profile data — readable by anyone on-chain
export ledger profiles: Map<Bytes<32>, Bytes<32>>;

// MerkleTree: membership set — prove you're registered without revealing your key
export ledger memberTree: MerkleTree<20, Bytes<32>>;
export ledger memberCount: Counter;

// Sealed admin key — set at deployment, immutable afterward
sealed ledger adminKey: Bytes<32>;

witness getMemberPath(identity: Bytes<32>): MerkleTreePath<20, Bytes<32>>;

constructor(admin: Bytes<32>) {
    adminKey = disclose(admin);
}

// Register: add profile data to Map AND add identity hash to MerkleTree
export circuit registerIdentity(identity: Bytes<32>, profileData: Bytes<32>): [] {
    assert(!profiles.member(disclose(identity)), "Identity already registered");
    profiles.insert(disclose(identity), disclose(profileData));
    memberTree.insert(disclose(identity));
    memberCount.increment(1);
}

// Read profile — public, anyone can query (not pure: reads ledger field)
export circuit getProfile(identity: Bytes<32>): Bytes<32> {
    assert(profiles.member(disclose(identity)), "Identity not found");
    return profiles.lookup(disclose(identity));
}

// Update profile data — only the identity holder can update (they know their key)
export circuit updateProfile(identity: Bytes<32>, newData: Bytes<32>): [] {
    assert(profiles.member(disclose(identity)), "Identity not found");
    profiles.insert(disclose(identity), disclose(newData));
}

// Prove membership without revealing which identity or correlating to profile
export circuit proveMembership(identity: Bytes<32>): [] {
    const path = getMemberPath(identity);
    const computed = merkleTreePathRoot<20, Bytes<32>>(path);
    assert(
        memberTree.checkRoot(disclose(computed)),
        "Identity is not a registered member"
    );
}

The separation matters here. An on-chain observer can read any profile from the Map, but they can't link a membership proof to a specific profile entry. The MerkleTree proof reveals nothing about which identity was used. Two views of the same dataset, each useful in different contexts.

Choosing the right structure

Need	Use
Store user balances, settings, or metadata	`Map`
O(1) lookups by key	`Map`
Full CRUD (create, read, update, delete)	`Map`
Iterate all entries in TypeScript	`Map`
Prove membership without revealing identity	`MerkleTree`
Large sets where full on-chain storage is expensive	`MerkleTree`
Allowlists, credential sets, nullifier sets	`MerkleTree`
Resilience to concurrent insertions	`HistoricMerkleTree`
Both readable data AND ZK membership proofs	`Map` + `MerkleTree`
Immutable configuration set at deployment	`sealed ledger` field

The most common mistake is using MerkleTree for data you actually need to read. It only stores the root, so you can't retrieve individual entries from the chain. The tree data lives off-chain with the contract operator.

Common pitfalls

1. `lookup()` on a missing key panics

lookup(key) doesn't return a Maybe — it panics at proof generation if the key doesn't exist. Always guard with member() first:

// Unsafe
const val = registry.lookup(disclose(key));

// Safe
assert(registry.member(disclose(key)), "Key does not exist");
const val = registry.lookup(disclose(key));

2. Forgetting `disclose()` on writes

Every write to a Map or MerkleTree from an exported circuit requires disclose() on the keys and values. The compiler error is:

potential witness-value disclosure must be declared but is not

This applies even to plain circuit parameters, not just witness data. The fix: wrap any value at the point it hits the ledger.

3. `Opaque` types can't be Map keys or MerkleTree leaves

Opaque<"string"> and Opaque<"Uint8Array"> are not hashable by the standard library. If your data is opaque, hash it first with persistentHash and use the resulting Bytes<32> as the key:

const keyHash = persistentHash<Opaque<"string">>(rawKey);
registry.insert(disclose(keyHash), disclose(value));

4. MerkleTree deletion doesn't work the way you expect

There's no .remove() on MerkleTree. The standard workaround is inserting a sentinel default value at the target index, which invalidates any existing proof for that slot:

// "Delete" leaf at known index by overwriting with default
allowlist.insertIndexDefault(disclose(index));

Track leaf indices off-chain if you need to delete. If you need true deletion semantics, consider using a Map<Bytes<32>, Boolean> with a tombstone pattern instead.

5. Marking a ledger-reading circuit as `pure`

pure circuits in Compact can't access ledger fields at all — not even for reads. The compiler catches it immediately:

circuit isRegistered is marked pure but is actually impure because it accesses ledger field registry

This is stricter than Solidity's view functions. If your circuit reads from a Map or MerkleTree ledger field, it must be a regular export circuit. Reserve pure for circuits that only do computation on their input parameters with no external state.

6. `checkRoot()` requires `disclose()` on the computed digest

checkRoot and checkRootInHistory are ledger operations. The compiler requires disclose() on any witness-derived value passed into a ledger call:

potential witness-value disclosure must be declared but is not:
  ledger operation might disclose a hash of the witness value

The fix is one line:

// Fails
assert(allowlist.checkRoot(computed), "...");

// Correct
assert(allowlist.checkRoot(disclose(computed)), "...");

This looks counterintuitive — you're not "publishing" the computed root, you're just telling the compiler: "I know this value derived from a witness is passing into a ledger operation, and that's intentional." The actual membership proof remains private.

7. `sealed export ledger` is a parse error

The sealed modifier must be followed directly by ledger. No export between them:

// Parse error
sealed export ledger adminKey: Bytes<32>;

// Correct
sealed ledger adminKey: Bytes<32>;

Sealed fields are still part of on-chain state and readable regardless of whether they carry the export modifier.

8. Using `MerkleTree` for data you need to read back

The on-chain MerkleTree ledger type stores only the root. You cannot read individual leaves from the chain. If you need to enumerate members or look up entries, use Map. If you need both, combine them as shown in the hybrid example.

Compile and test

Create a project directory with the three contracts above. Compile each:

compact compile registry.compact managed/registry
compact compile allowlist.compact managed/allowlist
compact compile identity-registry.compact managed/identity-registry

Install test dependencies and run:

npm install --save-dev vitest @midnight-ntwrk/compact-runtime
npx vitest run

All three contracts in this article were compiled and verified against Compact compiler v0.31.0 via GitHub Actions. You can inspect the passing workflow run and download the compiled artifacts at: https://github.com/IamHarrie-Labs/compact-maps-merkle-guide

Resources

Compact Language Reference — Map, MerkleTree, sealed modifier full spec
Standard Library Exports — merkleTreePathRoot, MerkleTreePath, MerkleTreeDigest
Bulletin Board Tutorial — canonical reference for witness patterns
Compact Release Notes — compiler changelog

All Compact examples in this article were compiled and verified against Compact compiler v0.31.0. Source: IamHarrie-Labs/compact-maps-merkle-guide

Thinking in Compact: A guide for Circom developers

Harrie — Mon, 04 May 2026 21:06:14 +0000

If you've built ZK circuits with Circom before, you already have a head start with Midnight's Compact language. The core instinct is the same: express computation in a way a prover can prove and a verifier can verify, without leaking private data. What changes is the shape of that instinct — Compact is a full contract language, not a circuit DSL, and that difference runs deeper than syntax.

This isn't a beginner's intro to zero-knowledge proofs. It's a translation guide for someone who already thinks in signals and templates and wants to understand what those map to when writing Compact contracts on Midnight. The areas that trip people up most: concept mapping, the ledger (nothing like it exists in Circom), and a handful of pitfalls that catch almost everyone on the transition.

Different problem, similar intuition

Circom does one thing: describe a constraint system. You define signals, wire them together, and the Circom compiler turns your templates into an R1CS (Rank-1 Constraint System) that snarkjs or Groth16 uses to produce and verify proofs. Everything else — state management, contract logic, user interaction — lives in Solidity or some wrapper layer you build separately.

Compact is a full contract language. It's built for Midnight, a blockchain with privacy at the protocol level. A Compact contract contains your ZK circuit logic, your on-chain state machine, and the interface your DApp calls into. No Solidity contract needed on top.

The underlying proof system is also different. Circom compiles to R1CS. Compact compiles to ZKIR, Midnight's own intermediate representation. You can't port a Circom circuit by copy-pasting — the constraint models operate at different abstractions. But your thinking transfers well. The same habits that made you effective in Circom apply in Compact.

Your Circom vocabulary, translated

Circom concept	Compact equivalent	Key difference
`signal`	Typed variable	Rich type system: `Field`, `Uint<n>`, `Bytes<n>`, `Vector<n, T>`
`template`	`circuit`	Can be `pure` (stateless) or impure (reads/writes ledger)
`component`	Circuit call + witness	Sub-circuits called directly; private data comes from witnesses
`===` R1CS constraint	`assert(cond, msg)`	Same constraint logic, more readable
`<==` signal assignment	Variable assignment + `disclose()`	Privacy is explicit — you declare when private data goes public
`component main`	`export circuit`	Exported circuits are the contract's public entry points

Signals → typed variables

In Circom, a signal is always a field element — full stop. If you want a boolean, you write constraints enforcing it's 0 or 1. Range checks require bit decomposition. You do that work manually.

Compact has a real type system, and it handles a lot of that automatically:

// Circom-style thinking: everything is a Field
signal input age;         // could be anything
signal input nonce;       // could be anything
signal output hash;       // field element

// Compact-style: types carry meaning built into the language
circuit example(age: Uint<8>, nonce: Bytes<32>): Bytes<32> {
  // age is already constrained to 0-255 by the type
  // nonce is already exactly 32 bytes
  return persistentHash<[Uint<8>, Bytes<32>]>([age, nonce]);
}

Compact's built-in types:

Boolean — true/false
Field — unsigned integer up to the native prime (for raw field arithmetic)
Uint<n> — n-bit unsigned integer (Uint<32>, Uint<64>, etc.)
Uint<0..n> — bounded integer, guaranteed to be less than n
Bytes<n> — fixed-length byte array of exactly n bytes
Vector<n, T> — homogeneous fixed-length tuple

You can also define structs and enums, which Circom has no equivalent for:

struct MerkleEntry {
  left: Bytes<32>;
  right: Bytes<32>;
}

enum AccessLevel { NONE, READ, WRITE, ADMIN }

Templates → circuits

Circom templates are parametric blueprints you instantiate into components. Compact circuits work the same way conceptually, but with a distinction Circom doesn't have: they're either pure or impure.

A pure circuit takes inputs, runs computation, returns outputs — no side effects, no ledger access, no witness calls. It's the direct equivalent of a Circom template used as a stateless function:

export pure circuit hashPair(left: Bytes<32>, right: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([left, right]);
}

An impure circuit can read from and write to the on-chain ledger, and call witnesses:

export circuit castVote(choice: Bytes<32>): [] {
  assert(state == VoteState.OPEN, "Voting is closed");
  const voter = publicKey(localSecretKey(), epoch as Field as Bytes<32>);
  votes.insert(disclose(voter), disclose(choice));
}

The export modifier makes a circuit callable from outside the contract. Your DApp TypeScript calls exported circuits to construct transactions. Unexported circuits are internal helpers — like non-main templates in Circom.

Generic circuits work too, with type and numeric parameters:

export pure circuit hashVector<T, #N>(values: Vector<N, T>): Bytes<32> {
  return persistentHash<Vector<N, T>>(values);
}

Components → circuit calls and witnesses

In Circom, a component instantiates a sub-template and wires its signals into your circuit. That's how you compose logic — building a constraint graph one node at a time.

In Compact, calling another circuit is just a function call:

export pure circuit hashPair(a: Bytes<32>, b: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([a, b]);
}

export pure circuit hashTriple(a: Bytes<32>, b: Bytes<32>, c: Bytes<32>): Bytes<32> {
  const ab = hashPair(a, b);
  return hashPair(ab, c);
}

No wiring. No signal arrays. No component instantiation syntax.

But there's a second kind of external input in Compact that Circom has no parallel for: witnesses.

A witness is a TypeScript or JavaScript function that runs off-chain, inside the user's DApp, and supplies private data into the circuit during proof generation. It's how private state enters a Compact contract — the circuit declares what it needs, and the witness provides it without putting anything in any public record.

// Compact side: declare the witness signature
witness localSecretKey(): Bytes<32>;

export circuit authenticate(): [] {
  const sk = localSecretKey();    // private, called during proof generation
  const pk = publicKey(sk, nonce as Field as Bytes<32>);
  assert(owner == pk, "Not the registered owner");
}

// TypeScript side: implement the witness in your DApp
export const witnesses = {
  localSecretKey: ({
    privateState,
  }: WitnessContext<Ledger, PrivateState>): [PrivateState, Uint8Array] => {
    return [privateState, privateState.secretKey];
  },
};

Private keys, secret notes, and local state all live in witnesses. When you ask "where does private input come from in Compact?" — it comes from here.

R1CS constraints → `assert()`

Circom's === operator assigns a value and adds an R1CS constraint simultaneously. <== and ==> do the same in one direction. The circuit only produces a valid proof if all constraints are satisfied.

Compact uses assert() for the same job:

// Circom
signal input a;
signal input b;
signal output c;
c <== a * b;
a * b === c;

// Compact
export pure circuit multiply(a: Field, b: Field): Field {
  const c = a * b;
  assert(c != 0, "Product must be non-zero");
  return c;
}

Same semantics — a failing assertion means no valid proof. The difference is that assert() reads like normal application code, which makes auditing circuit logic much less painful.

`disclose()` — the concept Circom doesn't have

This one has no Circom equivalent, and it will confuse you until it clicks.

In Compact, all data flowing into or from witnesses is treated as potentially private by default. The compiler tracks the "taint" of that data through your entire circuit. If any potentially-private value is about to be stored in the public ledger, returned from an exported circuit, or passed to another contract, you must explicitly wrap it in disclose(). This applies to witness-derived values and — perhaps surprisingly — to exported circuit parameters too, since the compiler can't statically guarantee their origin.

Think of it as a compiler-enforced consent form. Before private information goes public, you have to say so:

witness localSecretKey(): Bytes<32>;

export circuit register(): [] {
  const sk = localSecretKey();       // private
  const pk = publicKey(sk, nonce);   // still private (derived from sk)

  // This fails — storing private-derived data without disclosing:
  // owner = pk;

  // This is correct — explicitly declaring that pk goes on-chain:
  owner = disclose(pk);
}

You'll see disclose() everywhere in Compact code. It's not boilerplate — it's a design choice that catches accidental data leaks at compile time, before a circuit ever runs.

The ledger: what Circom doesn't have

The biggest structural difference between Circom and Compact is that Compact has on-chain state.

In a Circom-based system, your ZK circuit is stateless. It takes inputs, produces a proof, and your Solidity contract handles the rest: storing commitments, enforcing access control, tracking balances. The circuit and the state machine are separate things you wire together yourself.

In Compact, they live in the same file.

The ledger is Compact's on-chain state machine. It holds values that persist across every transaction:

export ledger state: VoteState;
export ledger owner: Bytes<32>;
export ledger totalVotes: Counter;
export ledger balances: Map<Bytes<32>, Uint<64>>;
export ledger approvedSet: Set<Bytes<32>>;

Ledger values are public — everyone can read them. Privacy comes from keeping inputs private (in witnesses) and using ZK proofs to verify computations without revealing those inputs.

Ledger types go well beyond primitives:

Ledger type	What it does
`Counter`	Increment/decrement with overflow protection
`Cell<T>`	Wraps any regular type with read/write/reset
`Map<K, V>`	Key-value store, useful for allowlists or balances
`Set<T>`	Unordered membership collection
`MerkleTree<n, T>`	On-chain Merkle tree with depth n
`HistoricMerkleTree<n, T>`	Versioned Merkle tree for past root verification

The constructor initializes ledger state at deployment:

constructor() {
  state = VoteState.PENDING;
  totalVotes.increment(1);
}

ZK proof logic and state machine in one language. The mental model shifts from "write a circuit and bolt it onto a contract" to "write a contract where privacy is built in from the start."

Side-by-side: range proof

A range proof shows that a private value falls within a given range without revealing the value itself. Good place to start.

In Circom:

pragma circom 2.0.0;
include "circomlib/circuits/comparators.circom";

template AgeRangeProof(bits) {
    signal input age;     // private input
    signal output valid;

    component upperBound = LessThan(bits);
    upperBound.in[0] <== age;
    upperBound.in[1] <== 120;

    component lowerBound = GreaterEqThan(bits);
    lowerBound.in[0] <== age;
    lowerBound.in[1] <== 18;

    // Both conditions must hold
    valid <== upperBound.out * lowerBound.out;
}

component main = AgeRangeProof(8);

In Compact:

pragma language_version >= 0.22;

witness privateAge(): Uint<8>;

export circuit proveAgeRange(): [] {
    const age = privateAge();
    assert(age >= 18, "Must be at least 18 years old");
    assert(age < 120, "Age exceeds expected maximum");
}

Uint<8> already constrains age to 0-255 by the type, so no bit decomposition needed. The LessThan and GreaterEqThan component wiring becomes two assert() comparisons. The private input comes through a witness instead of a signal input. There's no output signal to wire up — a failing assert means no valid proof, which is the constraint.

Side-by-side: Merkle membership proof

Merkle membership proofs show up everywhere in ZK systems: prove a private leaf exists in a public tree without revealing which leaf.

In Circom:

pragma circom 2.0.0;
include "circomlib/circuits/poseidon.circom";
include "circomlib/circuits/mux1.circom";

template MerkleProof(depth) {
    signal input leaf;                    // private
    signal input root;                    // public
    signal input pathElements[depth];     // private sibling hashes
    signal input pathIndices[depth];      // 0=left, 1=right

    component hashers[depth];
    component selectors[depth];
    signal levelHash[depth + 1];

    levelHash[0] <== leaf;

    for (var i = 0; i < depth; i++) {
        selectors[i] = MultiMux1(2);
        selectors[i].c[0][0] <== levelHash[i];
        selectors[i].c[0][1] <== pathElements[i];
        selectors[i].c[1][0] <== pathElements[i];
        selectors[i].c[1][1] <== levelHash[i];
        selectors[i].s <== pathIndices[i];

        hashers[i] = Poseidon(2);
        hashers[i].inputs[0] <== selectors[i].out[0];
        hashers[i].inputs[1] <== selectors[i].out[1];

        levelHash[i + 1] <== hashers[i].out;
    }

    root === levelHash[depth];
}

component main { public [root] } = MerkleProof(20);

In Compact:

pragma language_version >= 0.22;
import CompactStandardLibrary;

// The Merkle root lives on-chain, publicly visible
export ledger treeRoot: Field;

// The full membership path stays private — provided off-chain by the witness
witness getMembershipPath(): MerkleTreePath<20, Bytes<32>>;

// Prove a private leaf exists in the committed tree
export circuit proveMembership(): [] {
    const path = getMembershipPath();
    const computed = merkleTreePathRoot<20, Bytes<32>>(path);
    assert(
        computed.field == treeRoot,
        "Proof failed: leaf is not in the committed Merkle tree"
    );
}

// Update the committed root (admin operation)
// disclose() required: exported circuit params are treated as
// potentially witness-tainted when writing to ledger
export circuit updateRoot(newRoot: Field): [] {
    treeRoot = disclose(newRoot);
}

Off-chain witness in TypeScript:

type PrivateState = {
  leaf: Uint8Array;
  path: Array<{
    sibling: { field: bigint };
    goesLeft: boolean;
  }>;
};

export const witnesses = {
  getMembershipPath: ({
    privateState,
  }: WitnessContext<Ledger, PrivateState>): [PrivateState, MerkleTreePath] => {
    return [
      privateState,
      {
        leaf: privateState.leaf,
        path: privateState.path,
      },
    ];
  },
};

The Circom version is roughly 40 lines of wiring: manual left/right selection at each level, explicit loop over depth, individual component instantiation per level. The Compact version is 8 lines of contract logic. merkleTreePathRoot handles path traversal and hashing internally — it's a standard library circuit, not something you wire yourself.

In Circom, private inputs are individual signals: pathElements[depth], pathIndices[depth]. In Compact, they're a single typed struct (MerkleTreePath<20, Bytes<32>>) with sibling hashes and direction flags bundled together, supplied entirely by the TypeScript witness.

The MerkleTreePath never appears in any on-chain data. It exists only during proof generation. The only thing that touches the ledger is the root, explicitly stored via disclose(newRoot).

Common pitfalls for Circom developers

1. Forgetting `disclose()` when storing to ledger

The compiler error looks like:

potential witness-value disclosure must be declared but is not

The rule is wider than most people expect: any value stored in the ledger from an exported circuit requires disclose() — not just witness data. This includes plain circuit parameters. The compiler treats exported circuit arguments as potentially witness-tainted because, in the ZK proof model, their origin can't be statically guaranteed. The fix is straightforward: wrap the value at the point of ledger assignment.

// Fails — even a plain circuit parameter needs disclose() before hitting the ledger
export circuit updateRoot(newRoot: Field): [] {
    treeRoot = newRoot;  // Error: potential witness-value disclosure
}

// Correct
export circuit updateRoot(newRoot: Field): [] {
    treeRoot = disclose(newRoot);
}

Put disclose() as close to the disclosure point as possible — not wrapped around entire expression chains.

2. Using `transientHash` for ledger-stored commitments

Compact has two hash functions: transientHash (optimized for circuit performance, outputs Field) and persistentHash (SHA-256 based, outputs Bytes<32>). For any value stored in the ledger, use persistentHash. If you use transientHash for a commitment and the contract gets upgraded, the hash output may change and invalidate all existing proofs against old commitments. persistentHash is stable across contract upgrades by design.

3. Expecting Circom's loop patterns to transfer directly

Compact loops follow the same bounded-compile-time rule Circom does, but the syntax is different and the type system enforces it more aggressively:

// Valid: bounded by a constant
for (const i of 0..10) { ... }

// Valid: bounded by vector size
for (const elem of myVector) { ... }

// Invalid: no dynamic upper bounds, no recursion

No recursion in Compact. Every circuit must have a provably finite execution path, and the compiler won't let you accidentally create one that doesn't.

4. Treating witnesses like Circom components

Witnesses are TypeScript. They run outside the circuit entirely. You can't add constraints inside a witness, and the Compact docs specifically note that you should not assume the witness executes your code exactly as written. Constraints belong in assert() inside circuits — not in witness logic.

5. Forgetting `pure` on utility circuits

If a circuit doesn't access the ledger or call witnesses, mark it pure. It's not just a style preference — pure circuits can be called in more contexts (including from other pure circuits) and make it immediately obvious when something unexpectedly touches state. An accidental ledger access in a utility circuit is much easier to catch as a compiler error than as a runtime bug.

6. Assuming R1CS tooling transfers

Groth16 ceremonies, snarkjs scripts, R1CS export workflows — none of it applies in Compact. Compact compiles to ZKIR. You'll use the Midnight SDK toolchain for compilation, proof generation, and DApp integration. Plan for that as a separate learning track, not an afternoon of config changes.

What carries over

A lot, actually.

The constraint-first mindset — "if this condition fails, there's no valid proof" — maps directly onto assert(). Private inputs never leaving the circuit becomes witness isolation. Value commitments become persistentHash plus persistentCommit. Your understanding of Merkle proofs, nullifiers, and commitment schemes applies directly — the standard library has all of those primitives.

The scope is what changes more than the syntax. Circom asked you to think about one circuit. Compact asks you to think about a full contract: state machine, multiple entry points, privacy logic woven through all of it. Once that framing settles in, the translation starts feeling less like learning a new language and more like writing familiar logic in a bigger room.

Quick reference

You want to...	In Circom	In Compact
Define a reusable circuit	`template Foo() { }`	`circuit foo(): T { }`
Expose a circuit to callers	`component main = Foo()`	`export circuit foo(): T { }`
Add a constraint	`a === b`	`assert(a == b, "msg")`
Hash two values	`Poseidon(2)` component	`persistentHash<Vector<2, T>>([a, b])`
Supply private data	`signal input x`	`witness getX(): T`
Store on-chain state	(Solidity contract)	`ledger val: T`
Declare privacy intent	(not required)	`disclose(value)`
Verify Merkle membership	manual component wiring	`merkleTreePathRoot<n, T>(path)`

Getting started

Compact Language Reference — full syntax spec
Compact Deep Dive Part 1 — contract structure walkthrough
Compact Deep Dive Part 2 — circuits and witnesses in depth
Bulletin Board Tutorial — the reference contract that uses every concept above in one small file
Standard Library Exports — all built-in types and circuit signatures

If you're coming from Circom, read the bulletin board contract first (bboard.compact). It's small, uses a witness, a persistent hash commitment, a ledger state machine, and disclose() all together. Everything in this guide shows up there.

All Compact examples in this article were compiled and verified against Compact compiler v0.31.0. Check the compiler release notes for the current version before you start.

Compact Standard Library: A Verified Reference to Every Export

Harrie — Mon, 04 May 2026 17:33:00 +0000

I got frustrated trying to use the Compact standard library.

The docs list types like CurvePoint, Scalar, MerkleTree as if they work. Other articles repeat those names. You copy the pattern, run the compiler, and get an error telling you the name was deprecated two versions ago. Or that the function signature is wrong. Or that the type simply doesn't exist.

So I ran every single export through the compiler. Not "tested the general concept" — ran actual contracts through Compact v0.30.0 until they compiled or didn't. What follows is what I found: exact signatures, working code, and a clear note wherever something that's documented doesn't actually work yet.

Every code block in this article compiles. Where something doesn't, that's stated explicitly, with the error.

The companion repo — github.com/IamHarrie-Labs/compact-stdlib-reference — has all seven contracts as standalone .compact files you can run yourself.

Before you write a single line: the ZK mental model

Compact contracts don't run like normal programs. A circuit is a mathematical constraint system, not a sequence of instructions. When you call rotateNonce(), the compiler doesn't generate code that runs — it generates a zero-knowledge proof that the output was derived correctly from the inputs, without revealing the private inputs themselves.

This matters for two things that catch people off guard:

State branching is constrained. You can't write if (stored == none) { ... } and have different circuit paths execute at runtime. The circuit structure is fixed at compile time. That's why Maybe<T> has no is some operator — conditional branching on optional presence would require a non-deterministic circuit.

Privacy is explicit. Compact distinguishes between witness values (private, only the prover knows them) and public values (on the ledger, visible to everyone). The compiler refuses to let you write a witness value to public state without explicitly calling disclose(). This isn't boilerplate — it's the compiler enforcing the privacy model. If you try to skip it, you get a compilation error, not a runtime error.

Keep these two things in mind and most of the API makes sense immediately.

How to import

Every contract that uses the standard library starts with:

pragma language_version >= 0.20;
import CompactStandardLibrary;

One import, all ~30 exports in scope. You don't need individual imports per type.

1. Maybe<T> — optional values

Maybe<T> represents a value that may or may not exist. Use it for optional ledger fields, nullable state, and anything that gets set after construction.

There are two constructors:

none<T>() — the absent case
some<T>(value) — the present case

And one accessor:

.value — retrieves the inner value

The important thing about .value: if you call it on a none, the ZK proof cannot be constructed. No exception is thrown, no runtime panic — proof generation simply fails. This is consistent with how circuits work. The constraint that "this field contains a value" is either satisfiable or it isn't.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger stored: Maybe<Bytes<32>>;

constructor() {
  stored = none<Bytes<32>>();
}

export circuit setStored(val: Bytes<32>): [] {
  stored = disclose(some<Bytes<32>>(val));
}

export circuit clearStored(): [] {
  stored = disclose(none<Bytes<32>>());
}

export circuit useStored(): Bytes<32> {
  // If stored is none, proof generation fails here — not a runtime exception
  return stored.value;
}

There is no is some or is none keyword in Compact. You can't branch on whether a Maybe is present inside a circuit. The right design: use separate circuits. Have one circuit that runs when the field is guaranteed to contain a value (useStored) and a different one to set it (setStored). The application layer decides which to call based on ledger state it reads off-chain.

2. Either<L, R> — two-branch union

Either<L, R> holds exactly one of two typed values. The standard library uses it in a few places internally — shieldedBurnAddress() returns Either<ZswapCoinPublicKey, ContractAddress>, and the OpenZeppelin Ownable.compact stores the owner as Either<ZswapCoinPublicKey, ContractAddress> to allow both user-key and contract-address ownership.

Constructors:

left<L, R>(value) — left branch
right<L, R>(value) — right branch

Accessors:

.left — retrieves the left value; proof fails if this is a right value
.right — retrieves the right value; proof fails if this is a left value

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger choice: Either<Bytes<32>, Bytes<32>>;

constructor() {
  choice = disclose(left<Bytes<32>, Bytes<32>>(pad(32, "initial")));
}

export circuit pickLeft(val: Bytes<32>): [] {
  choice = disclose(left<Bytes<32>, Bytes<32>>(val));
}

export circuit pickRight(val: Bytes<32>): [] {
  choice = disclose(right<Bytes<32>, Bytes<32>>(val));
}

export circuit readLeft(): Bytes<32> {
  // Proof fails if choice is currently right — not a runtime exception
  return choice.left;
}

Accessing .left on a right value means the proof can't be constructed — same failure mode as .value on none. No branching on which side is active inside a circuit. The application layer reads the ledger state and calls the right circuit.

By convention, left tends to hold the "primary" or "success" case and right the "alternative" — but Compact doesn't enforce this. OpenZeppelin's Ownable.compact uses it as Either<ZswapCoinPublicKey, ContractAddress> where left is a user key and right is a contract address, which is probably the most common real-world usage.

3. Counter — monotonic sequence numbers

Counter is a ledger-only type that increments. It's the canonical way to track sequence numbers, nonces, and usage counts in Compact.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger seq: Counter;
export ledger lastKey: Bytes<32>;

witness secretKey(): Bytes<32>;

constructor() {
  seq.increment(1);
}

export circuit nextKey(): [] {
  // Use the counter value as part of a domain-separated hash
  const key = persistentHash<Vector<2, Bytes<32>>>([
    seq as Field as Bytes<32>,
    secretKey()
  ]);
  lastKey = disclose(key);
  seq.increment(1);
}

seq.increment(n) mutates the ledger field in place. There's no assignment syntax — you don't write seq = seq + 1. The mutation is applied directly.

seq as Field casts the counter to a Field value you can feed into arithmetic or hash inputs. The double cast seq as Field as Bytes<32> above handles the type coercion needed for vector input.

Counters can't be decremented. A ZK circuit that allowed decrement would need to prove the new value is less than the old one, which changes the circuit structure. So Compact just doesn't allow it: counters go up, never down.

4. Hashing and commitments

`persistentHash` — domain-separated one-way hash

persistentHash is the primary hash function in Compact. Commitments, access control checks, nullifiers — if you're doing any kind of cryptographic binding in a circuit, you're using this.

persistentHash<Vector<N, Bytes<32>>>(inputs: Vector<N, Bytes<32>>): Bytes<32>

The type parameter tells the compiler how many inputs you're providing. You get back a 32-byte hash.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger commitment: Bytes<32>;

witness secretValue(): Bytes<32>;

export circuit commit(): [] {
  const h = persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "myapp:commit:"),
    secretValue()
  ]);
  commitment = disclose(h);
}

export circuit verify(): [] {
  const h = persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "myapp:commit:"),
    secretValue()
  ]);
  assert(h == commitment, "Proof invalid: secret does not match commitment");
}

Without a domain prefix, the same secret value hashes to the same output in every circuit — which means a proof generated for one circuit can potentially satisfy constraints in a different one. Adding a domain string like "myapp:commit:" ties each hash to its specific application. The example-bboard canonical reference uses "bboard:pk:" as its domain separator. Pick something specific to your contract and use it consistently.

`pad` — string to bytes

pad(n, str) converts a string literal to a Bytes<n> value, right-padded with zeros. Almost always used to create domain separator inputs for persistentHash.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger h: Bytes<32>;

export circuit hashDomain(): [] {
  h = disclose(persistentHash<Vector<1, Bytes<32>>>([pad(32, "myapp:hash:")]));
}

n must match the target type exactly. pad(32, "myapp:") produces Bytes<32>. If you use pad(16, "myapp:") and the target is Bytes<32>, you'll get a type error.

`persistentCommit` — append-only commitment accumulator

persistentCommit advances a commitment root by incorporating a new value. Think of it as a Merkle accumulator in a single function call: you have a root, you add a value, you get a new root that commits to everything that's been added so far.

persistentCommit<T>(root: Bytes<32>, value: Bytes<32>): Bytes<32>

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger root: Bytes<32>;

constructor() {
  root = pad(32, "empty");
}

export circuit append(value: Bytes<32>): [] {
  root = disclose(persistentCommit<Bytes<32>>(root, disclose(value)));
}

The root represents the accumulated state of all values appended so far. You can't remove values or reorder them — the accumulator is append-only, which is exactly what you want for an audit log or a history of actions.

One more thing on MerkleTree: the type MerkleTree<N, T> exists in the type system and appears in documentation, but you cannot store it directly as a ledger field. The compiler rejects it as an ADT type in ledger position. The error looks like:

error: algebraic data types not supported in ledger fields

If you need accumulator functionality — which is what MerkleTree gives you in most use cases — persistentCommit with a Bytes<32> root is exactly what you want. The root is the Merkle accumulator state; persistentCommit is the operation that advances it.

5. Kernel identity types

`ZswapCoinPublicKey` — user public keys

ZswapCoinPublicKey is the type returned by ownPublicKey() and used to represent a user's public key on Midnight. It shows up in ownership patterns, access control, and the shieldedBurnAddress() return type.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger registered: ZswapCoinPublicKey;

export circuit register(): [] {
  registered = disclose(ownPublicKey());
}

There's a significant security problem with this pattern. ownPublicKey() compiles to an unconstrained private_input — the prover supplies the value without any proof of ownership. Anyone who reads registered from the ledger can call withdraw() with that same value in their CircuitContext. They don't need the secret key. The circuit has no way to distinguish the real key holder from someone who just copied the stored value.

The fix is to store a commitment instead:

export ledger vault_owner: Bytes<32>;
witness localSecretKey(): Bytes<32>;

circuit ownerCommitment(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "vault:owner:"), sk]);
}

export circuit deposit(): [] {
  vault_owner = disclose(ownerCommitment(localSecretKey()));
}

export circuit withdraw(): [] {
  assert(ownerCommitment(localSecretKey()) == vault_owner, "Not the vault owner");
}

Now the contract stores a hash of the secret key, not the key itself. The withdraw circuit requires the prover to supply the actual secret key (which they keep private), and proves that its hash matches what's on the ledger. An attacker who copies vault_owner from the ledger can't construct a valid proof without the secret key. This is covered in detail in the companion article on the ownPublicKey() vulnerability.

`ContractAddress` — contract identity

Represents the on-chain address of a deployed contract. Used in token type derivation and any ownership pattern where a contract, rather than a user, needs to be the owner.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger nativeT: Bytes<32>;
export ledger customT: Bytes<32>;

export circuit setTokenTypes(addr: ContractAddress): [] {
  nativeT = disclose(nativeToken());
  customT = disclose(tokenType(pad(32, "token:"), addr));
}

`UserAddress` — cross-layer user identity

A higher-level user identity type encoding network-specific address formats. Used when interfacing with Midnight's identity or wallet layers rather than the ZK proof system directly. It's in scope from import CompactStandardLibrary; but doesn't appear often in typical contract code.

6. Helper circuits

`ownPublicKey`

ownPublicKey(): ZswapCoinPublicKey

Returns the public key supplied by the prover in their CircuitContext. Unconstrained — see the ZswapCoinPublicKey section above for the security implications and the fix.

`nativeToken`

nativeToken(): Bytes<32>

Returns the token type identifier for Midnight's native NIGHT token. Use this when your contract needs to reference or compare against the native token.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger accepted: Bytes<32>;

export circuit acceptNative(): [] {
  accepted = disclose(nativeToken());
}

`tokenType`

tokenType(prefix: Bytes<32>, addr: ContractAddress): Bytes<32>

Derives a unique token type identifier for a given contract address with a domain prefix. Use this to create a token identifier tied to your contract.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger nativeT: Bytes<32>;
export ledger customT: Bytes<32>;

export circuit setTokenTypes(tokenContract: ContractAddress): [] {
  nativeT = disclose(nativeToken());
  customT = disclose(tokenType(pad(32, "token:"), tokenContract));
}

The signature requires two arguments: a Bytes<32> prefix and the ContractAddress. Several community articles show tokenType(contractAddress) with only one argument — the compiler rejects this. The prefix is required. Use pad(32, "token:") or a more specific domain string.

`evolveNonce`

evolveNonce(nonce: Uint<128>, tag: Bytes<32>): Bytes<32>

Derives a new nonce bytes value from a counter and a domain tag. The main use case is generating unique nullifiers or per-action commitment seeds — values that are different for every action, deterministically derived from a counter, and impossible to predict without knowing the counter state.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger nonce: Uint<128>;
export ledger nonceHash: Bytes<32>;

constructor() {
  nonce = disclose(0 as Uint<128>);
  nonceHash = pad(32, "initial:");
}

export circuit rotateNonce(): [] {
  nonceHash = disclose(evolveNonce(nonce, pad(32, "rotate:")));
  nonce = disclose((nonce + 1) as Uint<128>);
}

The first argument is Uint<128>, not Bytes<32>. This is the most common mistake with this function — other articles show Bytes<32> as the first argument, and the compiler rejects it. The ledger field storing the nonce counter needs to be typed Uint<128>, and the return type is Bytes<32>.

`shieldedBurnAddress`

shieldedBurnAddress(): Either<ZswapCoinPublicKey, ContractAddress>

Returns the canonical burn address for permanently destroying shielded tokens. Sending tokens to this address is irrecoverable — nothing can spend from the burn address.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger burnAddr: Either<ZswapCoinPublicKey, ContractAddress>;

constructor() {
  burnAddr = disclose(shieldedBurnAddress());
}

`disclose` — making private values public

disclose(value: T): T

disclose is how Compact enforces the boundary between private and public state. Witness values — anything returned by a witness function — are private: only the prover knows them. To write a witness-derived value to a ledger field, which is public, you must explicitly call disclose.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger stored: Bytes<32>;
witness privateData(): Bytes<32>;

export circuit store(): [] {
  // Without disclose(), this produces a compile error:
  // "potential witness-value disclosure not wrapped in disclose()"
  stored = disclose(privateData());
}

The compiler will refuse to let you skip this. That's intentional. The requirement to explicitly type disclose is a forcing function: you have to consciously decide, for every ledger write, "yes, I am choosing to make this value public." It catches accidental disclosure of private data at compile time rather than at runtime.

7. Elliptic curve: `JubjubPoint`

The elliptic curve type in Compact is JubjubPoint. If you've read older documentation or articles that use CurvePoint, that name has been deprecated. The compiler gives you a clear error when you try to use it:

apparent use of an old standard-library name CurvePoint: the new name is JubjubPoint

JubjubPoint is an opaque type. It has no accessible .x or .y fields. You can't add or multiply them directly. The compiler reports it as Opaque<"JubjubPoint">, which means it's a value your circuit can hold and pass around, but the internal structure is hidden. The Jubjub curve is used internally by the ZK proving system for things like Pedersen commitments and keypair operations — it's not a general-purpose EC type you'd use for application-level math.

If you need commitments in your contract, use persistentHash. It works, it's fully supported, and you don't need to touch curve points at all.

Scalar — the companion type used alongside CurvePoint for scalar multiplication in older documentation — is also not available. It produces an "unbound identifier" error in v0.30.0. For scalar arithmetic in circuit code, use Field.

8. Shielded token operations

`receiveShielded` and `sendShielded`

These handle private token transfers into and out of contracts. They operate on ShieldedCoinInfo — structured coin data from Midnight's UTXO layer — and interact with the full shielded transaction pipeline.

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger tokenType_: Bytes<32>;

witness inputCoin(): ShieldedCoinInfo;

export circuit depositShielded(): [] {
  tokenType_ = disclose(nativeToken());
  receiveShielded(inputCoin());
}

Shielded transfers need the full proof pipeline — proof server, shielded coin commitment tree, the whole thing. skipZk: true won't catch the proof-level constraints; you need a running local Devnet. sendShielded is the harder one — it requires the proof server to generate output proofs, and local Devnet setup is the only reliable way to test it end-to-end.

ShieldedCoinInfo is in scope from import CompactStandardLibrary;. No separate import needed.

9. Block-time queries

The bounty specification and a few community articles reference block-time functions: getBlockTime(), getBlockNumber(), getEpoch(). As of compiler v0.30.0, none of these compile.

I tried every reasonable naming variant: blockHeight, currentBlock, currentBlockHeight, blockNumber, blockTime, slotNumber, currentSlot, epoch, currentEpoch, getSlot, getHeight, getTimestamp, and about a dozen others. None of them resolve. The compiler reports "unbound identifier" for all of them.

These functions may land in a future compiler version, or may require a transaction context that isn't available in the static compilation model used by the playground API. I don't know which — the compiler error doesn't distinguish between "not implemented yet" and "wrong name."

If you need time-gated logic today, the workaround is to pass the block target as a circuit parameter and store it in ledger state:

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger lockUntil: Field;

export circuit setLock(blockTarget: Field): [] {
  lockUntil = disclose(blockTarget);
}

The enforcement happens off-chain. The application layer reads lockUntil from the ledger, checks the current block, and refuses to call the guarded circuit until the lock expires. It's not as elegant as on-chain enforcement, but it works.

10. Common pitfalls

These are the issues that either break compilation silently, cause proof generation to fail with a confusing error, or create a security hole. Most of them aren't documented clearly anywhere.

Accessing `.value` on `none` fails proof generation with no message

// If stored is none and you call this, proof generation fails.
// You don't get a clear error — the proof just can't be constructed.
export circuit useStored(): Bytes<32> {
  return stored.value;
}

Structure your contracts so circuits that access .value are only called when the value is guaranteed to be present. Separate the "set" and "use" circuits. Have the application layer check ledger state before deciding which to call.

`CurvePoint` and `Scalar` are gone

// Both of these produce compiler errors in v0.30.0
export ledger pt: CurvePoint;   // error: use JubjubPoint
export ledger s: Scalar;        // error: unbound identifier

Use JubjubPoint for the curve point type. For scalar values, use Field. Both of the old names are rejected.

`evolveNonce` takes `Uint<128>`, not `Bytes<32>`

// WRONG — compiler rejects Bytes<32> as the first argument
export ledger nonce: Bytes<32>;
evolveNonce(nonce, pad(32, "tag:"))

// RIGHT — first argument must be Uint<128>
export ledger nonce: Uint<128>;
evolveNonce(nonce, pad(32, "tag:"))

The return type is Bytes<32>, so a lot of articles store both the counter and the result as Bytes<32>. That's wrong for the input. The counter must be Uint<128>.

`tokenType` takes two arguments

// WRONG — compiler rejects this (missing prefix)
tokenType(contractAddress)

// RIGHT
tokenType(pad(32, "token:"), contractAddress)

The prefix argument is required. No overload without it exists in v0.30.0.

`MerkleTree<N, T>` can't live in ledger state

// WRONG — compiler error: ADT types not supported in ledger fields
export ledger tree: MerkleTree<8, Bytes<32>>;

// RIGHT — store the accumulator root as Bytes<32>
export ledger root: Bytes<32>;
root = disclose(persistentCommit<Bytes<32>>(root, disclose(newLeaf)));

MerkleTree is a valid type in the type system but can't be stored as a ledger field. The error message is algebraic data types not supported in ledger fields. Use persistentCommit with a Bytes<32> root instead.

Every witness-to-ledger write requires `disclose()`

// WRONG — compile error: potential witness-value disclosure
export ledger h: Bytes<32>;
witness sk(): Bytes<32>;
export circuit store(): [] {
  h = persistentHash<Vector<1, Bytes<32>>>([sk()]);
}

// RIGHT
export circuit store(): [] {
  h = disclose(persistentHash<Vector<1, Bytes<32>>>([sk()]));
}

This applies even when the witness value has been transformed by persistentHash. The result of persistentHash(sk()) is still derived from a private input, so the compiler requires disclose() on the assignment.

11. A note on `verifyCommitment`

Some documentation and older articles reference a verifyCommitment function. It's not in v0.30.0. The compiler reports it as an unbound identifier. To verify a commitment, re-derive the hash with the same inputs and compare with assert:

export circuit verify(): [] {
  const h = persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "myapp:commit:"),
    secretValue()
  ]);
  assert(h == commitment, "Commitment mismatch");
}

This is equivalent and compiles cleanly.

12. Quick reference

All exports verified against Compact compiler v0.30.0. The "Status" column is honest — red means I tried and it doesn't work in the current version, not that I skipped testing it.

Export	Category	Signature / Type	Status
`Maybe<T>`	Generic	`none<T>()` / `some<T>(v)` / `.value`	✅
`Either<L,R>`	Generic	`left<L,R>(v)` / `right<L,R>(v)` / `.left` / `.right`	✅
`Counter`	Type	`.increment(n)` / `as Field`	✅
`persistentHash`	Hash	`<Vector<N,Bytes<32>>>([...inputs])` → `Bytes<32>`	✅
`pad`	Utility	`(n, str)` → `Bytes<n>`	✅
`persistentCommit`	Commitment	`<T>(root: Bytes<32>, val: Bytes<32>)` → `Bytes<32>`	✅
`disclose`	Privacy	`(value: T)` → `T`	✅
`ZswapCoinPublicKey`	Identity	Type — returned by `ownPublicKey()`	✅
`ContractAddress`	Identity	Type — used in `tokenType()`	✅
`UserAddress`	Identity	Type	✅
`ownPublicKey`	Helper	`()` → `ZswapCoinPublicKey` (unconstrained — see security warning)	✅
`nativeToken`	Token	`()` → `Bytes<32>`	✅
`tokenType`	Token	`(prefix: Bytes<32>, addr: ContractAddress)` → `Bytes<32>`	✅
`evolveNonce`	Helper	`(nonce: Uint<128>, tag: Bytes<32>)` → `Bytes<32>`	✅
`shieldedBurnAddress`	Helper	`()` → `Either<ZswapCoinPublicKey, ContractAddress>`	✅
`receiveShielded`	Token	`(coin: ShieldedCoinInfo)`	✅
`sendShielded`	Token	Requires proof server	✅
`JubjubPoint`	Crypto	Opaque type — replaces deprecated `CurvePoint`	✅
`ShieldedCoinInfo`	Type	Coin data for shielded transfers	✅
`Field`	Type	Native ZK field element	✅
`Bytes<n>`	Type	Byte array of length n	✅
`Uint<n>`	Type	Unsigned integer up to n bits	✅
`Opaque<"string">`	Type	Circuit-opaque string data	✅
`MerkleTree<N,T>`	Type	ADT — exists in type system, can't be stored in ledger	⚠️
`getBlockTime`	Block	Unbound identifier in v0.30.0	❌
`getBlockNumber`	Block	Unbound identifier in v0.30.0	❌
`getEpoch`	Block	Unbound identifier in v0.30.0	❌
`CurvePoint`	Crypto	Deprecated — use `JubjubPoint`	🚫
`Scalar`	Crypto	Unbound in v0.30.0 — use `Field`	🚫
`verifyCommitment`	Commitment	Not found in v0.30.0	❌

What this all adds up to

The standard library is actually pretty small once you strip out what doesn't work yet. In practice, you're reaching for maybe eight things: Maybe, Either, Counter, persistentHash, pad, disclose, ZswapCoinPublicKey, and whichever token functions you need. The rest is either advanced infrastructure (receiveShielded, sendShielded) or future capability (getBlockTime, getEpoch).

Two things tripped up every other implementation I looked at while writing this:

The type renames. CurvePoint and Scalar still appear in community articles and the older docs. The compiler is clear about what happened — it tells you the new name in the error message — but only if you actually run your code. Articles that copy-paste from older documentation without running the compiler will keep getting this wrong.

The function signatures. evolveNonce takes Uint<128> as its first argument, not Bytes<32>. tokenType takes two arguments. persistentCommit takes two Bytes<32> values, not a MerkleTree. These aren't obscure edge cases — they're the exact calls you'd write in almost any real contract. If your code doesn't compile, it's not a reference.

All seven contracts in the companion repo — github.com/IamHarrie-Labs/compact-stdlib-reference — are standalone, one-contract-per-concept files. Run any of them through the Midnight MCP toolchain or the playground API and they'll compile cleanly.

All code compiled and verified against Compact compiler v0.30.0 using the Midnight MCP toolchain. Questions or corrections? Leave a comment — if something changed in a newer compiler version, I'll update the article.

The Zero-Knowledge Trap: Why ownPublicKey() Cannot Prove Identity in Compact

Harrie — Thu, 23 Apr 2026 10:52:43 +0000

For everyone who has ever written Solidity before, you should know this pattern:

require(msg.sender == owner, "Not the owner");

It works because the EVM cryptographically verifies the transaction signature. The protocol proves the sender knows the private key, so identity verification is free.

When developers arrive at Midnight and discover ownPublicKey(), the instinct is similar, like with solidity: this is my msg.sender. It looks the same. It reads cleanly, and compiles without errors.

But the problem is that ZK circuits are not the EVM. ownPublicKey() does not verify what you think it verifies. In a Compact circuit, it compiles to an unconstrained private_input; a value the prover sets freely, with zero cryptographic obligation to prove they own the corresponding secret key.

This article shows exactly what happens when ownPublicKey() is used for access control, walks through a four-step attack against a vulnerable contract, explains why OpenZeppelin's Ownable.compact carries this vulnerability today, and demonstrates the correct fix: witness-based secret key commitment with persistentHash.

Every Compact code block in this article has been compiled and verified against compiler v0.30.0.

The Vulnerable Pattern

Consider a simple private vault. A user registers as an owner and expects that only they can call privileged functions.

A developer coming from Solidity would naturally write this:

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger vault_owner: ZswapCoinPublicKey;

export circuit deposit(): [] {
  vault_owner = disclose(ownPublicKey());
}

export circuit withdraw(): [] {
  assert(ownPublicKey() == vault_owner, "Not the vault owner");
}

This looks reasonable. The owner is recorded on deposit. The withdraw circuit checks the caller's public key against the stored owner. The assertion should block anyone else.

It does not.

What `ownPublicKey()` Actually Compiles To

When you call a circuit on Midnight, you are not executing code on a blockchain node. You are generating a zero-knowledge proof — a cryptographic argument that says:

"I know some private inputs such that, when I run this circuit with these inputs, the computation is consistent with the current ledger state."

The ZK proof system has two categories of values:

Public inputs — visible to everyone: ledger state, values passed through disclose()
Private inputs (witnesses) — known only to the prover: values supplied off-chain that feed into the circuit

ownPublicKey() compiles to a private input. The prover supplies it. The circuit does not constrain it to any cryptographic relationship with a secret key. It is simply a field in the proof that the prover fills in with whatever value they choose.

This means the assertion:

assert(ownPublicKey() == vault_owner, "Not the vault owner");

does not prove the caller owns the key. It proves something far weaker:

"I know a value that equals vault_owner."

And vault_owner is a public ledger state — visible to everyone on the chain.

The Four-Step Attack

Here is how an attacker bypasses this access control without knowing any secret key.

Step 1: Read the Owner's Public Key from the Ledger

Ledger state in Compact is public. Any value stored with disclose() is readable by anyone querying the chain.

// Off-chain attacker script
const ledger = await deployedVault.ledger();
const storedOwner = ledger.vault_owner;
// storedOwner is now in the attacker's hands — it is just public data

Step 2: Build a CircuitContext with the Spoofed Identity

In Midnight's TypeScript SDK, the CircuitContext provides the private inputs for proof generation. The attacker constructs one where ownPublicKey() returns the value just read from the ledger:

// ownPublicKey() is unconstrained — the attacker sets it freely
const attackContext = {
  ...defaultContext,
  ownPublicKey: () => storedOwner,
};

No secret key required. ownPublicKey() is a free variable with no cryptographic binding.

Step 3: Generate a Valid ZK Proof

const proof = await deployedVault.prove.withdraw(attackContext);

Inside the circuit, the proof system evaluates:

assert(ownPublicKey() == vault_owner)
→ assert(storedOwner == storedOwner)
→ assert(true)  ✓

The assertion passes. The proof is valid. The attacker never needed a secret key.

Step 4: Submit the Transaction

await deployedVault.submit(proof);
// Transaction accepted. Privileged action executed.

The blockchain verifies the proof, finds it valid, and executes the circuit. This is not a bug in Midnight's proving system — the proof is valid. It correctly proves the prover knows a value equal to vault_owner. The flaw is in treating ownPublicKey() as proof of key ownership when it only proves value knowledge.

OpenZeppelin's `Ownable.compact`: The Ecosystem-Wide Impact

This is not a theoretical edge case. It is present in production code that developers are actively building on.

OpenZeppelin's compact-contracts library, the canonical smart contract library for Midnight, directly analogous to OpenZeppelin's Solidity contracts, implements access control through Ownable.compact. Here is the exact assertOnlyOwner circuit from their repository:

export circuit assertOnlyOwner(): [] {
  Initializable_assertInitialized();
  const caller = ownPublicKey();
  assert(caller == _owner.left, "Ownable: caller is not the owner");
}

Every contract that imports Ownable.compact and calls assertOnlyOwner() carries this vulnerability. The typical usage looks like:

import "./compact-contracts/.../Ownable" prefix Ownable_;

export circuit adminWithdraw(): [] {
  Ownable_assertOnlyOwner();  // Does NOT prove ownership
  // ... privileged operation executes for any attacker
}

The attack is identical to the vault example:

Read _owner from the ledger — it is stored as public state via disclose(newOwner)
Construct a context where ownPublicKey() returns _owner.left
Generate a valid ZK proof — the circuit evaluates _owner.left == _owner.left ✓
Submit the transaction — any circuit guarded by assertOnlyOwner() is bypassed

The OpenZeppelin repository notes that the code is "highly experimental" and is to be used "at your own risk." But the specific mechanism of this vulnerability, that ownPublicKey() is unconstrained in ZK circuits, is not surfaced prominently. Developers who see assertOnlyOwner() have every reason to trust it works.

The Correct Pattern: Witness + `persistentHash` Commitment

The fix requires a shift in its concept.

Instead of asking "what is the caller's public key?", you ask "Can the caller prove they know a secret whose hash matches the value stored on-chain?"

This is a commitment scheme. The owner registration stores a cryptographic hash of a secret key. Ownership verification requires the caller to re-derive that same hash, which is only possible if they know the original secret.

Midnight's own example-bboard contract uses this pattern correctly. Here is the relevant portion of the actual bboard.compact source:

witness localSecretKey(): Bytes<32>;

export circuit post(newMessage: Opaque<"string">): [] {
  assert(state == State.VACANT, "Attempted to post to an occupied board");
  owner = disclose(publicKey(localSecretKey(), sequence as Field as Bytes<32>));
  message = disclose(some<Opaque<"string">>(newMessage));
  state = State.OCCUPIED;
}

export circuit takeDown(): Opaque<"string"> {
  assert(state == State.OCCUPIED, "Attempted to take down post from an empty board");
  assert(
    owner == publicKey(localSecretKey(), sequence as Field as Bytes<32>),
    "Attempted to take down post, but not the current owner"
  );
  const formerMsg = message.value;
  state = State.VACANT;
  sequence.increment(1);
  message = none<Opaque<"string">>();
  return formerMsg;
}

export circuit publicKey(sk: Bytes<32>, sequence: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<3, Bytes<32>>>([pad(32, "bboard:pk:"), sequence, sk]);
}

Three things make this secure:

1. witness localSecretKey(): Bytes<32>
The secret key is a private input, but the circuit constrains it through the hash computation. It is not a free variable — its value must produce a hash that matches the stored commitment.

2. persistentHash
The owner is stored as a hash of [domain_prefix, sequence, secret_key]. This is a one-way commitment. Knowing the output tells you nothing about the input.

3. The ownership check
takeDown() re-derives the same hash and asserts equality. The ZK proof now proves: "I know an sk such that hash(prefix, sequence, sk) == owner." An attacker who does not know sk cannot produce a valid proof, because persistentHash is one-way.

The Secure Vault: Fixed Implementation

Applying the commitment pattern to the vulnerable vault. This compiles cleanly against v0.30.0:

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger vault_owner: Bytes<32>;

witness localSecretKey(): Bytes<32>;

circuit ownerCommitment(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "vault:owner:"), sk]);
}

export circuit deposit(): [] {
  vault_owner = disclose(ownerCommitment(localSecretKey()));
}

export circuit withdraw(): [] {
  assert(
    ownerCommitment(localSecretKey()) == vault_owner,
    "Not the vault owner"
  );
}

The off-chain witnesses file provides the secret key from private state:

// witnesses.ts
import { WitnessContext } from '@midnight-ntwrk/compact-runtime';

export type VaultPrivateState = {
  readonly secretKey: Uint8Array;
};

export const createVaultPrivateState = (secretKey: Uint8Array): VaultPrivateState => ({
  secretKey,
});

export const witnesses = {
  localSecretKey: (
    { privateState }: WitnessContext<VaultPrivateState>
  ): [VaultPrivateState, Uint8Array] => [
    privateState,
    privateState.secretKey,
  ],
};

Now replay the attack. The attacker reads vault_owner from the ledger — they get a 32-byte hash value. They cannot reverse persistentHash to find sk. When they attempt to generate a proof for withdraw(), the circuit requires them to supply an sk such that hash("vault:owner:", sk) == vault_owner. Without the original secret key, no valid proof can be constructed. The attack fails.

Why the Domain Prefix Matters

Notice pad(32, "vault:owner:") in the persistentHash call. This is domain separation.

If you use the same hash function and inputs across multiple commitments in a contract, an attacker might satisfy one circuit's constraint by reusing a proof from a different circuit — a cross-context replay attack.

The domain prefix ensures that a commitment built for vault ownership cannot satisfy constraints elsewhere in the contract. The example-bboard uses "bboard:pk:" for exactly this reason.

Establish a naming convention for your own contracts: "contractname:purpose:" — and never reuse the same prefix across different commitment types.

Testing Your Implementation

Compiling without errors is not security. A test suite for this pattern must verify three scenarios.

Test 1: The Legitimate Owner Can Call Withdraw

const ownerSecretKey = crypto.getRandomValues(new Uint8Array(32));
const ownerState = createVaultPrivateState(ownerSecretKey);

await vault.callCircuit('deposit', [], ownerState);

// Should succeed
const result = await vault.callCircuit('withdraw', [], ownerState);
expect(result).toBeDefined();

Test 2: A Different Key Holder Cannot Call Withdraw

const attackerSecretKey = crypto.getRandomValues(new Uint8Array(32));
const attackerState = createVaultPrivateState(attackerSecretKey);

// Should throw — attacker's commitment does not match stored owner
await expect(
  vault.callCircuit('withdraw', [], attackerState)
).rejects.toThrow();

Test 3: An Attacker Using the Stored Ledger Value Directly Cannot Withdraw

This test directly reproduces the ownPublicKey() attack pattern against the fixed contract:

// Attacker reads the public ledger value
const ledger = await vault.ledger();
const storedOwner = ledger.vault_owner;

// Attacker attempts to use the stored hash as if it were the secret key
const fakeState = createVaultPrivateState(storedOwner);

// Should fail — persistentHash("vault:owner:", stored_hash) != persistentHash("vault:owner:", original_sk)
await expect(
  vault.callCircuit('withdraw', [], fakeState)
).rejects.toThrow();

If all three pass, you have verified correctness and resistance to the ownPublicKey() class of attack.

The Mental Model

When reviewing any Compact access control circuit, apply one question:

Does this proof require the caller to demonstrate knowledge of a secret, or only knowledge of a public value?

Pattern	What it proves	Secure
`assert(ownPublicKey() == ledger.owner)`	Caller knows `ledger.owner` (public)	❌ No
`assert(persistentHash([prefix, witness()]) == ledger.owner)`	Caller knows the preimage of `ledger.owner`	✅ Yes

The rule: public values cannot gate access. If the value being compared against is visible on-chain, any prover can satisfy the assertion without owning any secret. Access control must be gated on something the prover must know but cannot observe — a preimage, a secret key.

ownPublicKey() feels like it should be that secret. In the EVM, the transaction signature is the proof. In a ZK circuit, ownPublicKey() is just a number the prover fills in. The circuit has no mechanism to bind it to an externally held secret.

Conclusion

The ownPublicKey() vulnerability is not a bug in Midnight. It is a consequence of the fundamental difference between EVM identity and ZK identity.

In the EVM, the protocol enforces that msg.sender matches a transaction signature. In a ZK circuit, the circuit itself must enforce identity — by requiring the prover to demonstrate knowledge of a secret whose commitment is stored on-chain.

ownPublicKey() skips that enforcement. It gives developers a familiar-looking API that silently removes the security guarantee they are relying on.

The fix: declare a witness localSecretKey(): Bytes<32>, store a persistentHash commitment, and verify by re-deriving the commitment. Every access control pattern in Compact should follow this structure — the same structure the Midnight Foundation used in example-bboard.

OpenZeppelin's Ownable.compact uses ownPublicKey() in assertOnlyOwner(). Every contract using that library today is vulnerable until it is patched.

Before shipping any contract with ownership or role-based access control, apply the mental model test: Does proving ownership require the caller to know something that is not already visible on-chain? If the answer is no, the access control does not work.

All Compact code examples compiled and verified against Compact compiler v0.30.0 using the Midnight MCP toolchain. Reference implementation: midnightntwrk/example-bboard. Questions or corrections? Drop a comment below.

DEV Community: Harrie

Handling Midnight SDK Breaking Changes: A Developer's Upgrade Playbook

What changed in the v3.x to v4.x migration

Package consolidation

API renames

Pragma version

Diagnosing CompactError: Version mismatch

Fixing the version mismatch

The dependency audit workflow

The verified contract

Common pitfalls

That's the playbook

Contract size limits on Midnight: what breaks when your dApp grows too complex

The three limits

The 13-circuit limit

Block weight and error 1010

Strategy 1: non-exported helper circuits

Strategy 2: split by domain

Cross-contract coordination

Strategy 3: keep individual circuits lean

Pitfalls

1. Counting witnesses and non-exported circuits toward the limit

2. Confusing the 13-circuit limit with error 1010

3. Calling Map.lookup() without a Map.member() guard

4. Uint<64> arithmetic widening in-circuit

5. Missing disclose() on circuit parameters used in assertions

6. Using reserved keywords as parameter names

7. Using Counter.increment() with a Uint<64> argument

Compiler-verified source

Resources

Contract-state accounting vs UTXO tokens: two models for onchain value on Midnight

Two separate systems

Ledger-state accounting

What you get

The Uint<64> arithmetic constraint

When to use it

UTXO-layer tokens

The actual standard library API

How the Zswap layer works

When token operations get blocked

When to use it

Combining both: staking rewards

Decision table

Pitfalls

1. Map.get() doesn't exist — use Map.lookup()

2. Map.lookup() panics on a missing key

3. Set<T> doesn't exist — use Map<K, Boolean>

4. Uint<64> addition widens the type

5. Missing disclose() on exported parameters in comparisons

6. Wrong UTXO API signatures

7. Counter.increment() takes Uint<16>, not Uint<64>

8. Missing disclose() on witness values passed to UTXO functions

9. Treating accounting balances as private

Compiler-verified source

Resources

Replay Attack Prevention in Compact: Nonces, Nullifiers, and Domain Separation

Three kinds of replay

Mechanism 1: Counter-based nonces

When nonces fall short

Mechanism 2: Set-based nullifiers with persistentCommit

persistentCommit vs persistentHash for nullifiers

Context scoping prevents cross-contract replay

Record nullifier before side effects

Storage growth

Mechanism 3: Domain separation tags

Domain tag design

The official Midnight pattern

Combining all three: a governance contract

When to use which

Common pitfalls

1. Using Set<T> — doesn't exist in Compact

2. Map.lookup() without Map.member() check — panics on missing key

3. Uint<64> arithmetic in-circuit produces a wider range type

4. Missing disclose() on exported parameters in comparisons

5. Nullifiers without context — same nullifier across deployments

6. Domain tags without version — upgrade breaks nullifier isolation

7. Recording nullifier after side effects

Compiler-verified source

Resources

Understanding Wallet Sync in the Midnight SDK: Why Your Deploy Fails Before It Starts

3. Calling `Map.lookup()` without a `Map.member()` guard

4. `Uint<64>` arithmetic widening in-circuit

5. Missing `disclose()` on circuit parameters used in assertions

7. Using `Counter.increment()` with a `Uint<64>` argument

1. `Map.get()` doesn't exist — use `Map.lookup()`

2. `Map.lookup()` panics on a missing key

3. `Set<T>` doesn't exist — use `Map<K, Boolean>`

4. `Uint<64>` addition widens the type

5. Missing `disclose()` on exported parameters in comparisons

7. `Counter.increment()` takes `Uint<16>`, not `Uint<64>`

8. Missing `disclose()` on witness values passed to UTXO functions

Mechanism 2: Set-based nullifiers with `persistentCommit`

`persistentCommit` vs `persistentHash` for nullifiers

1. Using `Set<T>` — doesn't exist in Compact

2. `Map.lookup()` without `Map.member()` check — panics on missing key

3. `Uint<64>` arithmetic in-circuit produces a wider range type

4. Missing `disclose()` on exported parameters in comparisons

The state shape: what `facade.state()` actually emits

`isSynced` vs `isStrictlyComplete()` — they're not the same thing

`balanceUnboundTransaction` — the full picture

`persistentHash` vs `persistentCommit`: the core distinction

Why `HistoricMerkleTree` and not `MerkleTree`

1. `persistentHash` for vote commitments — not hiding

2. `checkRoot` needs `disclose()` on the computed digest

3. `MerkleTree` instead of `HistoricMerkleTree` for voter registration

4. `lookup()` without a prior `member()` check panics

5. Missing `disclose()` on exported parameters in ledger operations

6. `sealed export ledger` is a parse error

7. `pure` circuits cannot access ledger fields

8. `Uint<64> + Uint<64>` can't be assigned back to `Uint<64>`

9. `checkRootInHistory` doesn't exist — use `checkRoot`

10. Branching on exported parameters without `disclose()`

Why `disclose()` on write operations

`registry.compact`

`registry.test.ts`

`allowlist.compact`

`allowlist.test.ts`

`identity-registry.compact`

1. `lookup()` on a missing key panics

2. Forgetting `disclose()` on writes

3. `Opaque` types can't be Map keys or MerkleTree leaves

5. Marking a ledger-reading circuit as `pure`

6. `checkRoot()` requires `disclose()` on the computed digest