DEV Community: Tushar Pamnani

45 Days Building on Midnight: An Honest Builder's POV

Tushar Pamnani — Sat, 11 Apr 2026 18:39:26 +0000

If you're considering building on Midnight, read this before you start.

I want to be upfront about what this article is and isn't.

It's not a tutorial. It's not a portfolio flex. It's what I actually experienced spending 45 days going full-time on Midnight - what broke me, what surprised me, what I built, and whether I'd do it again.

The short answer is yes. The longer answer is more interesting.

What "45 Days Full-Time" Actually Means

I was a final-year engineering student when I started. Full-time meant 2pm to 4-5am most nights, with weekend slots eaten by events and workshops. No structured hours, no team, no roadmap handed to me; just me, the docs, a lot of Discord messages, and a proof server running in Docker.

I studied DeFi math, ZK cryptography, and Midnight's architecture simultaneously. I built while I learned. Some contracts took a day. Some took a week of debugging a single circuit constraint. By the end of 45 days I had built roughly 15 contracts and ~10 full-stack dApps.

Here's what that actually looks like:

Escrow contract with ZK commitment schemes and state machine ordering
Linear bonding curve token with ZK-verified quadratic reserve math
pUSD v3 lending protocol (180+ tests, hit Midnight's block size limits, had to cut from 28 to 10 circuits)
Prediction market with range-based rewards (Bet in Range: submitted to hackathon)
Quadratic voting with ZK-verified sqrt weighting
ZK allowlist with depth-20 Sparse Merkle Tree and domain-separated nullifiers
LMSR prediction markets, NFT launchpad, coin flip dApp, gamified learning platform
mn-scaffold: an npm CLI for scaffolding Midnight projects from a live template registry
midnight-wallet-kit: React hooks for Lace and 1AM wallet integration, published to npm
Midnight Club: an open-source developer hub for the ecosystem

Two contributions came directly out of this period that I'm particularly glad exist. The first: when Midnight SDK v8 landed with significant breaking changes, a new WalletFacade.init pattern, mandatory encrypted private state, the signRecipe methodology replacing manual intent signing, I'd already worked through all of it while upgrading my own projects. That understanding turned into a PR to Midnight's official create-mn-app repository, upgrading the hello-world template to SDK v8. It's approved and pending merge. The second is already live: a documentation PR to the official midnight-docs repo clarifying the create-mn-app project selection flow, specifically documenting that the CLI prompts you to choose between a Contract or a Full dApp, and which templates are available for each. It's the kind of thing that seems obvious once you know it and completely opaque when you don't. Both came from the same place: hitting a wall, figuring it out, then making sure the next developer doesn't hit the same wall.

I also got selected into the Midnight Aliit, the ecosystem's selective technical fellowship program for builders who contribute through code, education, and community. The name comes from Mandalorian: aliit means "family" or "clan," which is an accurate description of what it actually feels like. Fellows are chosen based on prior contributions, demonstrated technical depth, and a track record of helping others build. It's not a badge; it comes with direct access to the teams building Midnight, the ability to feed product feedback directly upstream, and a responsibility to keep bringing new developers into the ecosystem. Getting in validated that the 45 days weren't just productive for me personally.

The Thing That Made Me Cry: Developer Experience

I'm going to say something that every Midnight developer is thinking but most won't write publicly: the DevEx is genuinely hard right now.

This isn't a complaint. It's a fact worth stating clearly for anyone evaluating whether to build here.

There's no publicly hosted proof server. Every developer who wants to build, test, or demo anything that involves ZK proofs has to run the proof server locally in Docker. This is fine for development. It becomes a serious problem the moment you want to deploy something real at zero cost, the way you'd deploy a Solana program or an EVM contract and have users interact with it immediately. On Midnight, your users need a running proof server, or you need to run one for them, which isn't free.

I built midnight-wallet-kit specifically because there was no proper documentation for Lace provider APIs. I spent hours inspecting window objects in the browser console to figure out what methods existed, what payloads they accepted, and how to make them work reliably across both wallets. There was no spec to read. I reverse-engineered it.

The Compact compiler's error messages, at least in the versions I was working with, could be cryptic. Circuit constraints that fail don't always tell you why clearly. You learn by developing an intuition for what the ZK constraint system will and won't accept, which takes time and pain.

I hit Midnight's block size limits while building pUSD v3. Had to reduce the contract from 28 circuits down to 10. The documentation on block size constraints didn't exist at the time; I found the limit by hitting it.

None of this made me want to stop. But it would make a lot of developers stop, and I've seen it happen.

The Thing That Surprised Me: The Team Actually Shows Up

I expected a new ecosystem with thin developer support. What I got was the opposite.

Every time I got seriously stuck, and I mean seriously stuck, the kind of stuck where you've been debugging for two days and you're considering starting over, someone from the Midnight team was in Discord helping me work through it. Not a bot. Not a "have you read the docs?" response. Actual engineers engaging with my specific problem.

I know "good developer support" sounds like a bare minimum. In practice, it's not. Most chains at Midnight's stage have a Discord that's 90% price talk and 10% confused newcomers. Midnight's developer channels are genuinely technical. The people building the chain are in the same channels as the people building on it.

This matters more than it sounds when you're working alone at 3am on a circuit constraint that won't compile.

The Thing I Didn't Expect: ZK Stopped Being Scary

I came into this with a genuine fear of zero-knowledge cryptography. I'd tried to implement ZK-adjacent things on other chains and made a mess every time.

Midnight changed that.

Not because Midnight made ZK easy, it didn't. But Compact forces you to engage with the actual concepts rather than letting you abstract over them. When the compiler rejects your program because you tried to move witness data to the public ledger without disclose(), you don't just fix the error and move on. You understand why it's an error. The language teaches you the mental model.

By week three I was writing blog posts explaining ZK commitment schemes and the witness-verify pattern to other developers. By week five I was implementing Sparse Merkle Trees and domain-separated nullifiers. That's not knowledge I would have picked up passively. Midnight forced it.

The DeFi math came the same way. Bonding curves required integrating a price function. LMSR prediction markets required understanding logarithmic scoring rules. pUSD required thinking about liquidation thresholds and collateral ratios under ZK constraints. I learned all of it because I had to implement it.

If you come to Midnight for the privacy primitives, you'll leave with a significantly deeper understanding of cryptography than when you arrived. That's a real return on investment that doesn't show up in any ecosystem metric.

What's Missing: The Proof Server Problem Isn't Fully Solved

Midnight does provide publicly hosted proof server endpoints for Preview, Preprod, and Mainnet. So technically, you don't have to run one locally.

But here's the thing the official docs say immediately after listing those endpoints: you should only use a proof server you control, because the proof server receives your private data; token ownership details, private state, witness inputs. Using a hosted proof server you don't control means trusting a third party with exactly the data Midnight's privacy model is designed to protect.

For development and testing: the hosted endpoints are convenient and fine. For a production dApp where privacy actually matters: you're back to running it yourself or self-hosting infrastructure. And for attracting users who aren't developers and won't run Docker, the UX friction is still real.

This isn't a criticism of Midnight's architecture. The local proof server is the right privacy model. But it creates a genuine tension: the chain's core value proposition is privacy, and the most privacy-respecting deployment requires infrastructure that most dApp users will never set up themselves. That tension doesn't have an easy answer, and I'd rather name it honestly than pretend the hosted endpoints make the problem disappear.

Should You Build on Midnight?

The honest version of my answer: it depends on your risk tolerance and your grinding capacity.

If you want a chain where you can build a polished dApp in a weekend and ship it to users immediately, Midnight is not that chain yet.

If you're willing to grind through rough DevEx for a period of time in exchange for being early to a genuinely novel privacy primitive layer, the kind of early where there's almost no competition for the problems you're solving, then Midnight is worth serious consideration.

The privacy problem in blockchain is real and unsolved. Midnight is one of the most technically interesting approaches to it. The team is building in public and engaging with developers. The ecosystem is small enough that good work gets noticed immediately, my escrow contract got into the official awesome-dapps list and onto the fireside dev hangout within 1 week of publishing.

I would not have gotten that visibility shipping my 50th Solana DEX fork.

If you're thinking about building on Midnight and want someone to walk you through the rough parts, I'm happy to help personally. I've hit most of the walls already.

What Comes Next

This retrospective is a checkpoint, not an ending. The repos stay open, the series stays up, midnight-wallet-kit is on npm, and there's more to build.

If you're starting your Midnight journey and want to skip some of the walls I hit, find me on X or GitHub. The repos are open, the series is up, and the walls are documented.

Midnight in Practice series · midnight-wallet-kit · mn-scaffold · Midnight Club

I Spent Hours in the DOM So You Don't Have To

Tushar Pamnani — Wed, 08 Apr 2026 20:57:19 +0000

Full source: github.com/tusharpamnani/midnight-wallet-kit

When I started building frontends on Midnight, I hit a wall that nobody warned me about.

The contracts were working. The proof server was running. The TypeScript SDK was integrated. And then I needed to connect a wallet.

There was no proper documentation for Lace's Midnight provider. No fixed window.ethereum-style standard to follow. Just two browser extensions injecting objects into the DOM under different keys, with different method signatures, inconsistent behavior, and no specification to read.

I spent hours inspecting window objects, console-logging provider payloads, and reverse-engineering what each wallet actually exposed before I could make a single connection work reliably. Every Midnight frontend developer hits this exact wall. Nobody should have to climb it twice.

That's why I built midnight-wallet-kit.

What the Problem Actually Looks Like

If you've built on Ethereum, you know window.ethereum. It's a standard. You call eth_requestAccounts, you get addresses, you sign. Every wallet implements the same interface.

Midnight doesn't have this yet. Lace injects under window.lace. 1AM injects under window.midnight. The methods exist but aren't documented. The payload shapes vary. And because Midnight uses ZK proofs and shielded transactions, the signing flow is more complex than EVM; you're not just signing a hash, you're signing an intent that the proof server will process.

Without a proper abstraction layer, every developer ends up writing the same fragile, bespoke integration code:

// What you end up writing without a kit
const provider = (window as any).lace?.midnight;
if (!provider) throw new Error("Lace not found?");
const accounts = await provider.enable?.();
// hope this works, documentation doesn't exist

Then you do the same thing for 1AM. Then you handle the case where neither is installed. Then you handle session persistence across page refreshes. Then you write tests that require a real browser extension to be installed. By the time you're done, you've written a wallet library, except it only works for your specific app and breaks when the extension updates.

What Midnight Wallet Kit Gives You

midnight-wallet-kit is a production-grade abstraction layer for Lace and 1AM on Midnight. Install it, register your adapters, wrap your app in a provider, and you're done.

npm install midnight-wallet-kit

Setup

import { WalletManager, InjectedWalletAdapter } from 'midnight-wallet-kit';

const manager = new WalletManager();

manager
  .register(new InjectedWalletAdapter({ name: 'Lace', providerKey: 'lace' }))
  .register(new InjectedWalletAdapter({ name: '1AM', providerKey: 'midnight' }));

import { WalletProvider } from 'midnight-wallet-kit/react';

function App({ children }) {
  return (
    <WalletProvider
      manager={manager}
      autoConnect={['1AM', 'Lace']}  // priority fallback order
      autoRestore={true}              // reconnect last-used wallet on refresh
    >
      {children}
    </WalletProvider>
  );
}

That's the entire integration. Everything below this point is application code.

The Four Hooks

`useWallet()`: connection state

const { address, isConnected, connectionState, error } = useWallet();

connectionState gives you the full lifecycle: idle → connecting → connected, with restoring, error, disconnecting, and disconnected as intermediate states. No more boolean isConnected that doesn't tell you why a connection failed.

address returns the user's Midnight unshielded address — the same mn_addr_... format used throughout the contract layer. coinPublicKey and encryptionPublicKey are also available if your dApp needs them.

`useConnect()`: connection management

const { connect, disconnect, isLoading, adapters } = useConnect();

// Connect to a specific wallet
await connect('1AM');

// Or let the kit try in priority order
// (handled automatically via WalletProvider autoConnect)

adapters gives you the list of all registered adapter names; useful for rendering a wallet selection UI without hardcoding names.

`useIntent()`: signing

const { buildAndSign, signMessage } = useIntent();

// Sign a contract intent
const result = await buildAndSign({
  contractAddress: '...',
  circuitId: 'buy',
  args: [n, maxCost]
});

// Sign an arbitrary message (login flows, proofs of ownership)
const signed = await signMessage("Login to My DApp");
// Timestamping and normalization handled automatically

buildAndSign validates intent parameters with Zod before sending anything to the wallet; you get a typed InvalidIntentError before the extension even opens, not a cryptic failure deep in the proof pipeline.

signMessage handles the multi-step probing for data-signing support across different wallet versions, adds proper prefixes, and generates unique timestamps automatically.

`useBalance()`: balance polling

const { balance, isLoading, error, refetch } = useBalance();
// balance: { tDUST: bigint; shielded: bigint } | null

Automatically polls every 15 seconds when connected. refetch() is available for manual triggers after a transaction. Uses the Midnight indexer under the hood; if the indexer query fails, you get a typed BalanceFetchError, not a silent null.

The Architecture: Why It's Built This Way

Adapters normalize the provider chaos

Every wallet integration lives in an adapter that implements MidnightWallet. The InjectedWalletAdapter handles the DOM-level provider probing, the part I spent hours figuring out manually. It exhaustively searches for working RPC methods across different provider standards and payload formats, so if Lace updates their injection key or 1AM changes their method signature, you update one adapter, not every component in your app.

Wallet modes are explicitly typed:

intent-signing: supports the full signIntent() flow, standard for DApps
tx-only: direct transaction balancing and submission only
unknown: handled defensively as a fallback

WalletManager handles the lifecycle

The WalletManager is the orchestrator. It manages adapter registration, connection state transitions, fallback chains, middleware, and session persistence.

Fallback chains are the feature I wish I'd had from day one:

await manager.connectWithFallback(['1AM', 'Lace']);

Try 1AM first. If it's not installed or the user rejects, try Lace. If both fail, throw FallbackExhaustedError. One line. No manual try-catch chains.

Session persistence via autoRestore stores the last-connected wallet name in localStorage and attempts to reconnect on page load. Users stay connected across refreshes without re-approving the extension every time.

Middleware for observability

manager.use(async (ctx, next) => {
  console.log(`Starting ${ctx.operation} on ${ctx.adapterName}`);
  await next();
  if (ctx.error) {
    analytics.track('wallet_error', { 
      operation: ctx.operation, 
      error: ctx.error.message 
    });
  }
});

Every wallet operation; connect, disconnect, signIntent, signMessage - passes through the middleware chain. The context object gives you the operation type, adapter name, intent payload, result, and any error. Useful for logging, analytics, and debugging production issues without adding instrumentation to every component.

Typed Errors: No More `catch (e: any)`

Every error from the kit is a typed class inheriting from MidnightWalletError. You can branch on error type rather than parsing message strings:

import { 
  ProviderNotFoundError,
  ConnectionRejectedError,
  FallbackExhaustedError,
  NetworkMismatchError 
} from 'midnight-wallet-kit';

try {
  await connect('Lace');
} catch (e) {
  if (e instanceof ProviderNotFoundError) {
    showInstallPrompt('lace');
  } else if (e instanceof ConnectionRejectedError) {
    showRejectedMessage();
  } else if (e instanceof NetworkMismatchError) {
    showNetworkSwitchPrompt();
  }
}

NetworkMismatchError in particular is one you'll hit in the wild, if a user switches their wallet to mainnet while your dApp is pointed at preprod, the session breaks silently without this check. The kit detects and surfaces it explicitly.

Testing Without a Browser Extension

This is the part that usually breaks dApp test suites. Testing wallet integration normally requires a real browser extension to be installed and configured, which makes CI impossible.

import { MockWalletAdapter } from 'midnight-wallet-kit/testing';

const adapter = new MockWalletAdapter({
  name: 'TestWallet',
  address: 'mn_addr1_test...',
  coinPublicKey: 'test_cpk',
  signatureOverride: '0xmocksignature',
  signDelay: 100,        // simulate realistic latency
  shouldRejectSign: false
});

manager.register(adapter);

You can simulate connection failures, signing rejections, latency, and specific return values. No browser, no extension, no environment setup; just a mock that implements the same MidnightWallet interface as the real adapters.

// Test the rejection flow
const failAdapter = new MockWalletAdapter({
  name: 'RejectingWallet',
  shouldRejectConnect: true
});

await expect(manager.connect('RejectingWallet'))
  .rejects.toThrow(ConnectionRejectedError);

SSR and Next.js

While building Midnight Club in Next.js, window.lace and window.midnight were being accessed during server-side rendering, causing window is not defined crashes that were silent in development but broke production builds.

The React hooks are SSR-safe. Provider detection (window.lace, window.midnight) only runs on the client; no window is not defined errors during Next.js server-side rendering. WalletProvider guards all DOM access behind a mounted check, so your app hydrates cleanly without injecting wallet state during SSR.

What's Next

The kit currently supports Lace and 1AM via InjectedWalletAdapter. Hardware wallet support is the natural next step as the Midnight ecosystem matures and physical signing devices become available.

If you're building on Midnight and hit something the kit doesn't handle, an edge case in the provider, a new wallet, a signing flow that doesn't fit the current API - issues and PRs are open at github.com/tusharpamnani/midnight-wallet-kit

ZK Membership Proofs on Midnight

Tushar Pamnani — Thu, 02 Apr 2026 11:54:29 +0000

Part 5 of Midnight in Practice. Part 1 | Part 2 | Part 3 | Part 4

Full source: github.com/tusharpamnani/midnight-allowlist

Every contract in this series has introduced one primitive that changes how you think about ZK development. The bonding curve introduced the witness-verify pattern. The escrow introduced commitment schemes for multi-party coordination. The QV contract introduced verification-over-computation for expensive arithmetic.

This article introduces a different class of problem: proving membership in a set without revealing which member you are.

The allowlist contract solves it using a Sparse Merkle Tree; a data structure that lets anyone prove their leaf is included in a tree of up to one million members, using only twenty hash operations inside a ZK circuit, without revealing their leaf, their position, or their secret.

By the end of this article you'll understand why Merkle trees are the standard structure for ZK membership proofs, how the circuit reconstructs a root from a private path, what nullifiers are doing cryptographically, and why the contract computes the nullifier inside the circuit rather than accepting it as a plain argument.

The Problem: Membership Without Identity

The naive approach to allowlisting is just a mapping:

export ledger allowlist: Map<Bytes<32>, Boolean>;

export circuit check(address: Bytes<32>): [] {
    assert(allowlist.member(disclose(address)), "Not allowed");
}

This works, but it's fully public. Every allowed address is visible on-chain. Whoever calls check reveals their address. For a token mint, an airdrop, or any access-gated system where the membership list itself is sensitive; a list of credentialed institutions, KYC-verified wallets, private beta testers, this model fails.

What you want is: a user proves they are in the allowlist without the chain learning which member they are.

Merkle trees make this possible.

Why Merkle Trees Work for ZK Membership

A Merkle tree is a binary tree where every leaf is a hash of some data, and every internal node is a hash of its two children. The root is a single 32-byte value that commits to the entire set.

The key property: given any leaf, you can prove it's in the tree by providing the sibling hashes along the path from leaf to root; the Merkle path. Anyone who knows the root can verify the proof by recomputing the path. Nobody learns anything about other leaves.

For this allowlist, each leaf is hash("zk-allowlist:leaf:v1" || secret). The root is stored on-chain. The Merkle path and the secret stay entirely off-chain as witnesses. The circuit recomputes the root from the path and asserts it matches the on-chain value.

The tree in this implementation has depth 20, supporting up to 2²⁰ = 1,048,576 members. That's the range of the proof: one path, twenty sibling hashes, one root check.

The Ledger: Minimal Public Surface

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

Three fields. That's the entire public surface of this contract.

merkle_root is the single commitment to the entire membership set. One 32-byte value represents up to a million members. Updating the set means updating one hash.

admin_commitment is the governance primitive; a hash of the admin's secret credential. We'll cover this in detail below, but notice the design: the admin's identity is never on-chain. Only a commitment to their secret is. Authorization happens entirely inside a ZK proof.

used_nullifiers is the replay protection set. Once a nullifier appears here, it can never be used again. The set grows with every successful verifyAndUse call and is never pruned.

Compare this to a naive allowlist that stores all member addresses: this contract reveals nothing about who is allowed. An observer sees a root, a commitment blob, and a set of 32-byte values with no meaning outside the context of a specific secret and context string.

The Witnesses: Everything Private

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

Five witnesses. Four are for the membership proof, one is for governance.

getSiblings() returns a Vector<20, Bytes<32>>: the twenty sibling hashes along the Merkle path. In the TypeScript layer, these come from tree.getMerklePath(leafIndex). They are computed locally and fed into the proof server. They never appear on-chain.

getPathIndices() returns Vector<20, Boolean>: the direction bits. At each level, false means the current node is a left child (sibling goes right), true means it's a right child (sibling goes left). This determines which side each sibling hash goes in hashLevelNode.

getContext() is the scoping mechanism for nullifiers: more on this shortly.

getAdminSecret() is used only in setRoot. The admin proves knowledge of the secret whose commitment matches admin_commitment without ever disclosing the secret itself.

The `hashLevelNode` Circuit

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

This is the building block for the entire Merkle path reconstruction. It computes one level of the tree: given the current hash and its sibling, produce the parent hash.

The is_right flag controls which side the current node occupies. If the current node is a right child, the sibling goes left; so the hash is H(domain || sibling || current). If it's a left child, the hash is H(domain || current || sibling). Getting this wrong produces the wrong root and the assertion fails.

The domain separator "zk-allowlist:node:v1" is padded to 32 bytes and prepended to every node hash. This is the same domain separation philosophy from the QV nullifier discussion, it prevents a hash computed for one purpose from being confused with a hash computed for another. A leaf hash, a node hash, and a nullifier hash all use different tags even though they all call persistentHash.

The Vector<3, Bytes<32>> type annotation tells persistentHash the exact structure of its input. This is the multi-argument pattern the QV contract couldn't use due to an earlier compiler constraint; by Compact 0.22 it works cleanly for vectors of fixed-length byte arrays.

The `verifyAndUse` Circuit, Step by Step

This is the circuit that does the actual work. Let's walk through each of its six numbered steps.

Step 1: Witness loading

const secret = getSecret();
const context = getContext();
const siblings = getSiblings();
const path_indices = getPathIndices();

All four private inputs are loaded from witnesses. From this point forward, the circuit operates on these values without them ever being disclosed unless explicitly wrapped in disclose().

Step 2: Leaf computation

const leaf = persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "zk-allowlist:leaf:v1"),
    secret
]);

The member's leaf is derived from their secret inside the circuit. The domain tag "zk-allowlist:leaf:v1" ensures a leaf hash is structurally different from a node hash even if the same secret were somehow used at both levels.

Notice what doesn't happen here: the leaf is never disclose()-d. It stays entirely within the witness data space of the proof. The chain never learns the leaf value.

Step 3: Nullifier verification

const computed_nullifier = persistentHash<Vector<3, Bytes<32>>>([
    pad(32, "zk-allowlist:nullifier:v1"),
    secret,
    context
]);
assert(computed_nullifier == nullifier, "Proof integrity error: ...");

This is the most important step to understand correctly. The nullifier parameter is provided by the caller as a public input to verifyAndUse. But the circuit doesn't trust it; it recomputes the nullifier from the private secret and context witnesses and asserts the two match.

Why does this matter? Without this check, a caller could pass any arbitrary nullifier value. They could reuse a nullifier from a different context, fabricate one entirely, or replay a proof with a different nullifier to bypass the double-use check. By recomputing the nullifier inside the circuit and binding it to the private secret and context, the contract ensures that:

The nullifier is deterministically derived from the prover's actual secret, not fabricated
The same secret in a different context produces a different nullifier, context scoping works
Nobody can use someone else's nullifier, the secret is the key

One design decision worth calling out explicitly: the nullifier is a circuit argument rather than computed purely internally with no public exposure. The circuit could derive computed_nullifier and insert it directly without ever surfacing it as a parameter, and the proof would be equally valid. But making it an explicit public argument means the TypeScript client must compute the nullifier locally before invoking the contract. This gives the client the ability to query used_nullifiers on the ledger first and abort early if the nullifier is already recorded, saving the user from generating an expensive ZK proof that would fail on-chain anyway. Proof generation takes meaningful time. Fast UI feedback before that step is worth the minor architectural exposure of making the nullifier a parameter rather than a purely internal value.

Step 4: Merkle path reconstruction

const h0  = hashLevelNode(path_indices[0],  leaf,  siblings[0]);
const h1  = hashLevelNode(path_indices[1],  h0,    siblings[1]);
// ... 18 more levels ...
const calculated_root = hashLevelNode(path_indices[19], h18, siblings[19]);

Twenty calls to hashLevelNode, each feeding the output of the previous as input. This is the full depth-20 Merkle path unrolled manually.

The reason for manual unrolling rather than a loop has two layers. The deeper one is fundamental to all ZK circuits: they must compile to a fixed-size mathematical constraint system. Any loop must have statically determinable bounds; the circuit size has to be known at key generation time. A loop over a runtime-length vector is impossible in any ZK circuit system, not just Compact.

The shallower reason is specific to Compact v0.22: the compiler could struggle with variable shadowing, loop state management, and sequential hashing bounds inside a for...in loop over vectors. Manual unrolling is bulletproof; it produces a mathematically sound constraint system without hitting compiler edge cases. It's verbose, but it compiles cleanly every time. If Compact's loop handling matures in later versions, this could be condensed. For now, twenty explicit lines is the right tradeoff.

Step 5: Root assertion

assert(calculated_root == merkle_root.read(), "Membership verification failed: ...");

The locally reconstructed root must match what's stored on-chain. This single assertion is the entire membership proof. If the prover provided the wrong secret, the wrong siblings, or the wrong path indices, calculated_root will differ from merkle_root at some level of the tree and the proof will fail to generate.

An invalid proof doesn't just fail at the assert; it fails at the proof generation stage. The proof server cannot produce a valid ZK proof for a circuit that would fail its assertions. This means an invalid membership attempt never even reaches the chain.

Step 6: Nullifier recording

assert(!used_nullifiers.member(disclose(nullifier)), "Dual-usage detected: ...");
used_nullifiers.insert(disclose(nullifier));

Two things happen here. First, the check: if this nullifier is already in used_nullifiers, the transaction fails. Second, the insert: the nullifier is disclose()-d into the public set, permanently marking it as used.

The disclose() on the nullifier is intentional and necessary. The nullifier needs to go on-chain so future proofs can check against it. But notice what it reveals: a 32-byte hash of (domain || secret || context). An observer learns that some secret with some context was used, not which secret, not which context, not which member.

The Admin Pattern: ZK Governance

export circuit setRoot(new_root: Bytes<32>): [] {
    const derived_commitment = persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "zk-allowlist:admin:v1"),
        getAdminSecret()
    ]);
    assert(derived_commitment == admin_commitment.read(), "Unauthorized: ...");
    merkle_root.write(disclose(new_root));
}

This is the same pattern as the escrow's deriveKey but applied to governance. The admin never stores their identity on-chain. admin_commitment is just hash(domain || adminSecret). Authorization is proven in ZK: the caller demonstrates they know the secret whose commitment matches the on-chain value.

The setup circuit is a one-time initialization:

export circuit setup(initial_commitment: Bytes<32>): [] {
    assert(admin_commitment.read() == pad(32, ""), "Setup failed: Administrator already configured");
    admin_commitment.write(disclose(initial_commitment));
}

The zero-bytes default check works because Compact ledger state variables are zero-initialized by the underlying Midnight ledger if they haven't been written to. Bytes<32> fields start as 32 zero bytes; no explicit initialization needed, no null or undefined state possible. pad(32, "") generates exactly those 32 zero bytes, so the assertion admin_commitment.read() == pad(32, "") is a clean "has this ever been written?" check. Once setup writes a real commitment, it can never be called again.

Notice that setup takes initial_commitment as a circuit argument, not derived from a witness. The admin computes hash(domain || adminSecret) off-chain and passes it in. The secret itself never appears in the transaction.

The Off-Chain Layer: What `allowlist-utils.ts` Actually Does

The TypeScript layer in allowlist-utils.ts handles everything the circuit can't do; stateful data management, Merkle tree construction, and local proof verification before submission.

generateProof does three things:

Finds the leaf index for the given secret in the local tree
Calls tree.getMerklePath(leafIndex) to get siblings and path indices
Verifies the path locally with tree.verifyPath() before constructing the proof object

That last step is the key one. Local verification before submission is a development-time safeguard; it catches malformed proofs before they hit the proof server, which would generate a valid ZK proof for an invalid membership claim and then have it rejected on-chain. Better to fail fast locally.

The proof object itself is structured as:

{
    proof: hex-encoded JSON of witness data,  // private inputs
    publicInputs: {
        root: string,      // current tree root
        nullifier: string  // hash(secret, context)
    },
    meta: { context, treeDepth, generatedAt, verified }
}

The witness object inside the hex-encoded proof contains secret, leaf, leafIndex, siblings, and pathIndices, all the private inputs the proof server needs. In a production deployment these would be consumed by the proof server and discarded; here they're serialized for CLI inspection and local verification.

verifyProof mirrors the circuit's logic in TypeScript: recompute the leaf, walk the path, check the root, recompute the nullifier, compare. It's the same five checks the circuit performs, run locally without a proof server. Useful for debugging and for the test suite's 17 forgery attack tests.

The Concatenation Bug the Tests Found

The test suite discovered a real vulnerability worth understanding:

hashNullifier("alice", "ctx1") === hashNullifier("alic", "ectx1")

The original implementation hashed domain || secret || context by simple concatenation. "alice" + "ctx1" and "alic" + "ectx1" both produce the string "alicectx1", identical inputs, identical hashes, identical nullifiers.

The fix was a 4-byte big-endian length prefix before the secret:

hash(domain || len(secret) || secret || context)

Now len("alice") = 5 and len("alic") = 4, the inputs are structurally distinct. The contract's persistentHash<Vector<3, Bytes<32>>> call naturally avoids this issue because it operates on fixed-length Bytes<32> values rather than variable-length strings. But the off-chain TypeScript hashing needed the explicit length prefix fix.

This is a classic lesson in hash function design: whenever you concatenate variable-length inputs, you need either fixed-length encoding, length prefixes, or a structured type system to prevent collisions across different field boundaries. The Compact circuit is immune because Bytes<32> is always exactly 32 bytes. The TypeScript layer isn't, and the test suite proved it.

What's Actually on the Chain

Being precise, as always:

Data	On-chain	Observer learns
Merkle root	Yes	The set has this root: nothing about members
Admin commitment	Yes	Someone controls this contract: not who
Nullifier	Yes (after use)	Some secret+context was used: not which
Secret	No	Nothing
Leaf hash	No	Nothing
Leaf index	No	Nothing
Merkle path	No	Nothing
Member count	No	Nothing

The root encodes the full membership set as a single hash. The nullifier set grows with usage. An observer watching the chain can count how many times the allowlist has been used but cannot learn anything about who used it or who is allowed.

The General Pattern

Strip the allowlist semantics and what remains is a reusable primitive for any ZK set membership proof on Midnight:

1. Off-chain: build a Merkle tree of commitments to private identities

leaf = hash(domain_leaf || secret)
tree.insert(leaf)
root = tree.root

2. On-chain: store only the root

export ledger merkle_root: Bytes<32>;

3. In the circuit: reconstruct the root from a private path

// 20 levels of hashLevelNode, unrolled
assert(calculated_root == merkle_root.read(), "Not a member");

4. Bind usage to a scoped nullifier computed inside the circuit

const nullifier = persistentHash([domain_nullifier, secret, context]);
assert(computed_nullifier == provided_nullifier, "Nullifier mismatch");
assert(!used_nullifiers.member(disclose(nullifier)), "Already used");
used_nullifiers.insert(disclose(nullifier));

Private airdrops, ZK KYC, anonymous credentials, private DAO membership - all of them are variations on this structure. The tree depth controls the maximum set size. The context string controls the scope of each nullifier. The domain separators ensure hash outputs from different parts of the system never collide.

What's Next

The six contracts across this series; bonding curve, state model analysis, escrow, quadratic voting, allowlist, cover the core primitive set for ZK DeFi and governance on Midnight: algorithmic markets, private state management, multi-party coordination, mathematical verification, and membership proofs.

The natural extension from the allowlist is combining it with the QV contract: members of a private allowlist get quadratic voting power, their membership proven anonymously, their vote weight proven without revealing their token allocation. That's a full private governance primitive and a meaningful next build.

Full source: github.com/tusharpamnani/midnight-allowlist

How Midnight Verifies tokens Without Computing It

Tushar Pamnani — Wed, 01 Apr 2026 05:30:00 +0000

Part 4 of building with Midnight. Part 1 | Part 2 | Part 3

Full source: https://github.com/tusharpamnani/midnight-quadratic-voting

Every article in this series has had one moment where Midnight forces you to think differently. In Part 1 it was the witness pattern; you don't compute inside the circuit, you verify. In Part 3 it was the commitment scheme; you don't share secret values, you prove knowledge of them.

This article has the same moment, and it's the clearest example yet.

Quadratic voting requires computing floor(sqrt(tokens)) for every voter. If you're thinking like a Solidity developer, your instinct is to implement a square root function and call it inside the contract. On Midnight, that instinct is wrong, and understanding why leads you directly to one of the most elegant patterns in ZK circuit design.

What Quadratic Voting Is and Why It's Hard in ZK

Standard voting gives each participant one vote regardless of their stake. Token-weighted voting gives proportional power to token holders; one token, one vote - which tends toward plutocracy. Quadratic voting is the middle ground: voting power scales as the square root of tokens committed.

weight = floor(sqrt(tokens))

The effect: doubling your tokens increases your influence by roughly 41%, not 100%. Whales can still participate but their marginal influence decreases. It's a mechanism design solution to concentration of power.

The ZK problem is this: sqrt is not a native operation in arithmetic circuits. ZK proof systems work over finite fields; addition and multiplication are cheap, but square roots require either expensive lookup tables or iterative algorithms that balloon the circuit size. For a practical on-chain implementation, neither is acceptable.

The solution isn't to compute the square root at all.

The `verifySqrt` Insight

Here's the core circuit from the contract:

circuit verifySqrt(tokens: Uint<64>, w: Uint<32>, w_sq: Uint<64>): [] {
    assert(w_sq <= tokens, "Weight too large: w^2 > tokens");
    const two_w = (w as Uint<64>) + (w as Uint<64>);
    const two_w_plus_1 = two_w + 1;
    assert(tokens - w_sq < two_w_plus_1, "Weight too small: use floor(sqrt(tokens))");
}

Three lines of arithmetic. No square root function anywhere. Let's understand exactly what this is doing.

The key mathematical insight: you don't need to compute floor(sqrt(tokens)). You only need to verify that a claimed value w satisfies the definition of floor square root.

w = floor(sqrt(tokens)) if and only if:

w² ≤ tokens < (w+1)²

Expand (w+1)²:

w² ≤ tokens < w² + 2w + 1

Rearrange the right side:

tokens - w² < 2w + 1

That's exactly what the two asserts check. The first assert checks w² ≤ tokens. The second checks tokens - w² < 2w + 1. Together they bound w to be exactly floor(sqrt(tokens)): no larger, no smaller.

The caller provides w and w_sq as witnesses, computed off-chain in TypeScript where you can use native math:

const w = Math.floor(Math.sqrt(Number(tokens)));
const w_sq = BigInt(w) * BigInt(w);

The circuit never computes a square root. It only verifies two inequalities. Both are just subtraction and comparison, cheap in any arithmetic circuit.

This is the witness pattern from Part 1 applied to a harder problem. In the bonding curve, calculateCost computed the integral off-chain and verifiedHalfProduct verified it with a multiplication check. Here, getSqrtWeight computes the square root off-chain and verifySqrt verifies it with two inequality checks. The structure is identical; the mathematical trick is different.

The Full Contract, Annotated

pragma language_version 0.22;
import CompactStandardLibrary;

// Public ledger state
export ledger committed_tokens: Map<Bytes<32>, Uint<64>>;
export ledger has_voted: Set<Bytes<32>>;
export ledger total_votes: Counter;

// Witnesses — computed off-chain, verified in-circuit
witness getVoterId(): Bytes<32>;
witness getCommittedTokens(): Uint<64>;
witness getSqrtWeight(): Uint<32>;
witness getWSquared(): Uint<64>;

Four witnesses. Notice getWSquared() exists separately from getSqrtWeight(), rather than computing w² inside the circuit (a multiplication), the caller provides it pre-computed and the circuit verifies the relationship. This is the same philosophy as the bonding curve: push arithmetic off-chain, verify the result cheaply.

circuit computeNullifier(voter_id: Bytes<32>): Bytes<32> {
    return persistentHash<Bytes<32>>(voter_id);
}

The nullifier is hash(voter_id). One voter ID maps to exactly one nullifier, deterministically, forever. This prevents double voting: once a nullifier is in has_voted, that voter ID can never vote again regardless of what proof they generate.

The comment in the source is worth quoting directly: "Current compiler signature restricts persistentHash to a single Bytes<32> argument. For now, we hash the voter_id directly." This is an honest acknowledgment of a current Compact compiler constraint. The README flags the consequence: same voter_id across different contracts produces the same nullifier, creating cross-contract linkability. The fix: hash(voter_id, contract_id), is straightforward once the compiler supports multi-argument hashing.

export circuit commit(voter_id: Bytes<32>, tokens: Uint<64>): [] {
    assert(!committed_tokens.member(disclose(voter_id)), "Already committed");
    committed_tokens.insert(disclose(voter_id), disclose(tokens));
}

This is the circuit where we need to be honest about the current privacy model.

Both voter_id and tokens are disclose()-d into the public ledger. The README lists these as private, but the compiler tells the true story: any value passed through disclose() into an export ledger field is fully visible on-chain. Right now, an observer can see which voter IDs have committed and exactly how many tokens each holds.

This is the same situation as the bonding curve balances from Part 1: public ledger, not private state. The genuinely private version would use persistentCommit to store a commitment to (voter_id, tokens, nonce) on-chain, with the actual values held in local private state. The vote circuit would then verify the commitment rather than checking the plaintext map. That's the architecture the README's privacy model describes and the next iteration of this contract should implement.

export circuit vote(): [] {
    const voter_id    = getVoterId();
    const tokens      = getCommittedTokens();
    const sqrt_weight = getSqrtWeight();
    const w_sq        = getWSquared();

    const computed_nullifier = computeNullifier(voter_id);

    // Verify the voter has a commitment
    assert(committed_tokens.member(disclose(voter_id)), "No commitment found");

    // Verify the committed amount matches the witness
    assert(committed_tokens.lookup(disclose(voter_id)) == disclose(tokens), "Token mismatch");

    // Verify the quadratic constraint in ZK
    verifySqrt(tokens, sqrt_weight, w_sq);

    // Prevent double voting
    assert(!has_voted.member(disclose(computed_nullifier)), "Already voted");

    // Record the vote
    has_voted.insert(disclose(computed_nullifier));
    total_votes.increment(disclose(sqrt_weight as Uint<16>));
}

Walk through the sequence of checks:

Membership check: the voter committed tokens in a prior transaction. Without this, anyone could vote with an arbitrary weight without having committed anything.

Token match: the tokens witness matches what's actually stored in the commitment map. This closes a subtle attack: without this check, a voter could commit 100 tokens then claim 10,000 tokens at vote time, pass the verifySqrt check with a legitimate w for 10,000, and vote with an inflated weight.

Quadratic constraint: verifySqrt runs. The circuit verifies w = floor(sqrt(tokens)) without computing a square root.

Double vote check: the nullifier hasn't been used. Combined with the deterministic nullifier derivation, this guarantees exactly one vote per committed voter ID.

State updates: nullifier recorded, total votes incremented by sqrt_weight. The global tally reflects the sum of all voters' square-root-weighted contributions.

The ordering of these checks matters. Membership before token match (can't verify a value that doesn't exist). Token match before verifySqrt (the constraint is meaningless if the token count can be faked). Double vote check before state update (record only after all validation passes).

What's Actually On-Chain

Being precise, same as the previous articles:

Data	On-chain?	Visible to observer?
Voter ID	Yes (`committed_tokens` key)	Yes
Token amount	Yes (`committed_tokens` value)	Yes
Square root weight	Yes (via `total_votes` increment)	Partially — total only
Nullifier	Yes (`has_voted`)	Yes
Individual vote weight	No	No
Whether a specific voter voted	Derivable from `has_voted`	Yes, via nullifier

The chain sees voter IDs and token amounts in the current implementation. The total_votes counter accumulates the global weighted tally but individual vote weights aren't stored separately: an observer can see the total but not decompose whose weight contributed what.

The nullifier being on-chain is intentional and necessary: it's the double-vote prevention mechanism. What it leaks is that a given voter ID has voted, derivable by anyone who knows the voter ID and can compute hash(voter_id). In the domain-separated future version, this becomes hash(voter_id, contract_id), still derivable by someone who knows the voter ID, but no longer linkable across contracts.

The Mental Model This Series Has Been Building

Step back and look at what the four contracts in this series have taught:

Bonding curve: the witness pattern. Expensive arithmetic off-chain, cheap verification in-circuit. The circuit doesn't trust the witness; it constrains it.

export ledger vs private state: the disclosure model. disclose() is a deliberate act, not a default. The compiler enforces it. Privacy is opt-out at the language level.

Escrow: multi-party coordination. Two private states, one proof. Commitment schemes bind parties to terms without revealing them. State machines enforce ordering cryptographically.

Quadratic voting: verification over computation. The circuit doesn't compute sqrt. It verifies that someone else's claimed sqrt satisfies the mathematical definition. The same pattern applies to any expensive function: compute off-chain, verify with cheaper constraints in-circuit.

That last principle is the most general. Anywhere you find yourself wanting to compute something expensive inside a ZK circuit; a square root, a logarithm, a hash of a large input - ask instead: what are the cheap constraints that a valid result must satisfy? Verify those instead.

What's Next

The natural extension of this contract, private token commitments using persistentCommit instead of plaintext export ledger maps, is exactly the bridge between this article and Part 2's commitment pattern. If you want a hands-on extension problem: refactor commit to store persistentCommit(voter_id, tokens, nonce) on-chain, move the actual values to private state, and update vote to verify the commitment before running verifySqrt. The quadratic constraint circuit stays identical, only the token retrieval and verification changes.

The allowlist contract, which uses Merkle trees, domain-separated nullifiers, and a proper off-chain membership proof system, is the next full article in this series. It takes the nullifier pattern introduced here and builds a complete private membership system around it.

Full source for this contract and the rest of the series: github.com/tusharpamnani/midnight-quadratic-voting

How Midnight Coordinates Two-Party Transfers

Tushar Pamnani — Sat, 28 Mar 2026 21:33:34 +0000

Part 3 of building with Midnight. Part 1 | Part 2

Part 2 ended with a provocation:

"The next level is understanding how private state interacts with transfers between users, which requires both parties to update their local private state atomically, coordinated by a proof that neither can fake."

That's not theoretical anymore. The midnight-escrow contract is a working implementation of exactly this problem, and it's a much richer teaching tool than any pseudocode example.

This article is a circuit-level autopsy of that contract. We're going to read the actual Compact code, understand why each line exists from a cryptographic coordination perspective, and extract the general pattern that applies to any private multi-party transfer on Midnight.

The Coordination Problem, Stated Precisely

Before touching code, let's be precise about what makes multi-party transfers hard on Midnight.

In Solidity you write:

balances[alice] -= amount;
balances[bob]   += amount;

Both writes happen in one EVM transaction. Atomicity is free because the EVM's state is a single shared namespace: one machine, one write.

In Midnight, the state model is split:

Public ledger (P)  →  every node on the network, plaintext
Private state (S)  →  user's local machine, never on-chain

Alice's private balance lives on Alice's machine. Bob's lives on Bob's. There is no shared namespace for private values. And a ZK proof can only attest to a state transition for one private state at a time.

So the question becomes: how do you make two separate private state updates, on two different machines, behave atomically?

The escrow contract answers this with three interlocking mechanisms:

A commitment scheme that binds the transfer terms cryptographically
A derived identity system that ties circuit authorization to private keys without exposing them
A state machine that enforces ordering and makes intermediate exploitation impossible

Let's walk through each.

The Ledger: What's Actually Public

export ledger buyer: Bytes<32>;
export ledger seller: Bytes<32>;
export ledger termsCommitment: Bytes<32>;
export ledger state: EscrowState;
export ledger round: Counter;

Five fields. That's the entire public surface of this contract.

Notice what's not here: no balance, no amount, no secret, no nonce. An observer watching the chain sees two 32-byte identifiers, a 32-byte blob, a state enum, and a counter.

buyer and seller are not wallet addresses: they are derived keys. We'll get to the derivation in a moment, but this is one of the most important design decisions in the contract.

termsCommitment is the cryptographic core. It's a commitment to the transfer terms: the amount and the release secret. The buyer posts it at creation; the seller must open it at release. Everything else in the protocol flows from this one field.

The Witnesses: The Private Side

export type EscrowPrivateState = {
  secretKey: Uint8Array;     // 32 bytes — identity key
  releaseSecret: Uint8Array; // 32 bytes — pre-image of the commitment
  nonce: Uint8Array;         // 32 bytes — commitment randomness
  amount: bigint;            // escrow value
};

And the corresponding Compact witness declarations:

witness secretKey(): Bytes<32>;
witness releaseSecret(): Bytes<32>;
witness nonce(): Bytes<32>;
witness escrowAmount(): Uint<64>;

These four values never touch the chain. They live in EscrowPrivateState, which the wallet SDK manages locally. At proof generation time, the witness functions feed them into the circuit, the Compact compiler sees them as private inputs to the ZK proof.

The witness implementation is deliberately simple:

export const witnesses = {
  secretKey(
    context: WitnessContext<Ledger, EscrowPrivateState>
  ): [EscrowPrivateState, Uint8Array] {
    const state = context.privateState;
    return [state, state.secretKey];
  },
  // ... same pattern for releaseSecret, nonce, escrowAmount
};

Each witness function returns a tuple of [newPrivateState, witnessValue]. In this contract, private state is read-only; the returned state is always identical to the input. This makes sense: both parties hold fixed secrets for the entire duration of the escrow. Neither needs to update their local state between circuit calls.

Identity Without Exposing Keys: `deriveKey`

circuit deriveKey(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>(
    [pad(32, "midnight:escrow:key"), sk]
  );
}

This circuit is one of the most important pieces in the contract and consistently the least explained.

The buyer and seller ledger fields hold derived public keys, not raw addresses or standard ECDSA public keys. Concretely:

derived_key = persistentHash(["midnight:escrow:key", secretKey])

Why not store a standard public key and verify a signature? You could, but you'd need signature verification logic inside the circuit, which adds constraints. The derived key approach is more elegant: secretKey is a private witness, deriveKey(sk) computes a public identifier from it inside the proof, and the circuit asserts the computed value matches what's on the ledger. The ZK proof itself is the authorization, no separate signature scheme needed.

The domain separator "midnight:escrow:key" (padded to 32 bytes) is critical. Without it, the same secretKey used in two different Midnight contracts would produce the same derived key on-chain, creating a linkage across the ecosystem. The separator namespace-isolates key derivation to this contract.

When createEscrow runs:

const sk = secretKey();   // private witness — never leaves the proof
const pk = deriveKey(sk); // computed inside the circuit
buyer = disclose(pk);     // only the derived key goes on-chain

The chain learns pk. It learns nothing about sk. But anyone who later calls a circuit with the same sk will produce the same pk, proving identity without revealing the key.

The Commitment Scheme: Binding Terms Without Revealing Them

export circuit createEscrow(
  sellerPk: Bytes<32>,
  amount: Uint<64>
): [] {
  assert(state == EscrowState.EMPTY, "Escrow already exists");

  const sk     = secretKey();
  const pk     = deriveKey(sk);
  const n      = nonce();
  const secret = releaseSecret();

  const releaseHash = persistentHash<Bytes<32>>(secret);

  const termsCommit = persistentCommit<Vector<2, Bytes<32>>>(
    [amount as Bytes<32>, releaseHash],
    n
  );

  buyer           = disclose(pk);
  seller          = disclose(sellerPk);
  termsCommitment = disclose(termsCommit);
  state           = EscrowState.FUNDED;
}

Let's trace what gets committed and why each decision was made.

Step 1: hash the release secret first

const releaseHash = persistentHash<Bytes<32>>(secret);

The commitment will contain hash(secret), not secret itself. This is a double layer of hiding: even if someone could theoretically invert persistentCommit, they'd only recover the hash, not the original pre-image.

Step 2: commit to [amount, releaseHash] with the nonce

const termsCommit = persistentCommit<Vector<2, Bytes<32>>>(
  [amount as Bytes<32>, releaseHash],
  n
);

persistentCommit is binding and hiding. The nonce n ensures two escrows with the same amount and the same secret produce different termsCommitment values on-chain, preventing correlation. Reuse the nonce and two identical commitments would appear on-chain, allowing an observer to link them.

The persistent prefix matters. The Compact docs distinguish: transientCommit outputs are suitable only for within-proof use; persistentCommit outputs are designed for storage in ledger state. Use transientCommit here and the commitment can't be reliably verified later. persistentCommit is the correct choice for anything that goes into export ledger.

Step 3: disclose only the derived values

buyer           = disclose(pk);
seller          = disclose(sellerPk);
termsCommitment = disclose(termsCommit);

Three disclose() calls. As established in Part 2, each is a deliberate declaration to the compiler: "I know this witness-derived value is going public." The compiler rejects this circuit without them. And each disclosure is intentional; the buyer's identity, the seller's identity, and the commitment all need to be on-chain for the protocol to function.

What's not disclosed: secretKey, releaseSecret, nonce, amount. The chain sees the commitment but cannot reverse it.

The Verification: How the Seller Proves Knowledge of the Secret

This is the cryptographic heart of the contract:

export circuit release(): [] {
  assert(state == EscrowState.FUNDED, "Invalid state");

  const sk = secretKey();
  const pk = deriveKey(sk);
  assert(pk == seller, "Only seller can release");

  const secret = releaseSecret();
  const n      = nonce();
  const amt    = escrowAmount();

  const secretHash = persistentHash<Bytes<32>>(secret);
  const recomputed = persistentCommit<Vector<2, Bytes<32>>>(
    [amt as Bytes<32>, secretHash],
    n
  );

  assert(
    recomputed == termsCommitment,
    "Invalid release proof"
  );

  state = EscrowState.RELEASED;
}

Two assertions. Two completely different things being verified.

Assertion 1: Identity

assert(pk == seller, "Only seller can release");

The seller proves they hold the secretKey that produced the seller field at creation. Without the correct sk, deriveKey(sk) produces the wrong hash and the assertion fails. No one else can generate a valid proof for this circuit.

Assertion 2: Knowledge of the secret

assert(recomputed == termsCommitment, "Invalid release proof");

The seller recomputes the commitment from scratch using their private releaseSecret, nonce, and escrowAmount. If any of these don't match what the buyer committed to in createEscrow, recomputed != termsCommitment and the proof fails.

This is the binding. The buyer chose (amount, releaseSecret, nonce) and committed to them. The seller must produce the exact same triple. The only way a seller could have the correct (releaseSecret, nonce) is if the buyer shared them, which is the off-chain handshake step in the protocol. The ZK proof doesn't replace that handshake. It verifies that the handshake happened correctly, without the chain ever seeing what was exchanged.

None of these values appear in the public output of the proof. The chain verifies the ZK proof, updates state to RELEASED, and that's it.

The Full Protocol Flow

Here's how the three circuits sequence for a complete transfer:

Bob (Buyer)                          Chain                        Alice (Seller)
     │                                 │                                │
     │── createEscrow(alicePk, amt) ──▶│                                │
     │   Proof asserts:                │  Ledger after:                 │
     │   - deriveKey(bobSk) == buyer   │  buyer    = H(bobSk)           │
     │   - commit([amt,H(secret)],n)   │  seller   = alicePk            │
     │                                 │  terms    = commit(...)        │
     │                                 │  state    = FUNDED             │
     │                                 │                                │
     │◀── share(nonce, secret) off-chain ─────────────────────────────▶│
     │                                 │                                │
     │                                 │◀── acceptEscrow() ─────────────│
     │                                 │    Proof: deriveKey(aliceSk)   │
     │                                 │    == seller                   │
     │                                 │                                │
     │                                 │◀── release() ──────────────────│
     │                                 │    Proof:                      │
     │                                 │    - deriveKey(aliceSk)==seller│
     │                                 │    - recomputed==termsCommit   │
     │                                 │  state = RELEASED              │

The off-chain share(nonce, secret) step is the only coordination that happens outside the chain. Bob hands Alice these two values; the CLI prints them, they copy-paste. The chain never sees this handoff. The ZK proof in release() is what cryptographically verifies Alice received the right values and used them correctly.

`acceptEscrow`: The Lightweight Identity Check

export circuit acceptEscrow(): [] {
  assert(state == EscrowState.FUNDED, "Escrow not funded");
  const sk = secretKey();
  const pk = deriveKey(sk);
  assert(pk == seller, "Only seller can accept");
}

This circuit does one thing: proves Alice is the intended seller. No state change beyond the proof itself.

Why does this exist separately from release? Two reasons.

Confirmation before commitment. Before Alice calls release, she verifies she's looking at the right escrow; the one Bob created for her specifically. acceptEscrow lets her confirm seller == deriveKey(aliceSk) before she's asked to provide releaseSecret and nonce.

Extension point. In a richer system, a swap scenario, for example - acceptEscrow might trigger a state change (FUNDED → ACCEPTED) that signals Bob to release his side of an asset exchange. Keeping it as a separate circuit preserves that hook without changing the release logic.

`refund`: The Escape Hatch

export circuit refund(): [] {
  assert(state == EscrowState.FUNDED, "Invalid state");
  const sk = secretKey();
  const pk = deriveKey(sk);
  assert(pk == buyer, "Only buyer can refund");
  state = EscrowState.REFUNDED;
}

No timeout logic. No round check. Bob can call refund at any time while the escrow is FUNDED.

This is a deliberate design choice for the current implementation, and one the repo explicitly flags as a future improvement. In production you'd gate refund on a round counter so Alice has a guaranteed window to call release. The round: Counter ledger field exists precisely for this; it just isn't wired to refund yet.

But even without the timeout, the liveness guarantee is clear: if Alice disappears, Bob isn't stuck. The state machine ensures refund and release are mutually exclusive, once either fires, state is no longer FUNDED and the other becomes impossible at the circuit level.

State Machine: Why Ordering Is a Security Property

enum EscrowState {
  EMPTY,
  FUNDED,
  RELEASED,
  REFUNDED
}

Every circuit opens with an assert on state. This isn't defensive programming, it's the atomicity guarantee.

EMPTY  ──createEscrow──▶  FUNDED  ──release──▶  RELEASED
                                  └──refund───▶  REFUNDED

Once state = EscrowState.RELEASED, the escrow is frozen. release requires FUNDED. refund requires FUNDED. createEscrow requires EMPTY. There is no path back, no double-release, no re-creation over an existing escrow.

Consider what happens without these assertions: the buyer could call createEscrow twice, overwriting termsCommitment with a different nonce mid-flight. The seller could call release twice. The state machine makes all of these impossible; not as application-layer logic, but as ZK-verified constraints inside the proof. The chain will not accept a proof that fails a circuit assertion.

This is the Midnight equivalent of reentrancy protection, enforced by the proof system, not by a mutex.

The Privacy Accounting: What Leaks and What Doesn't

Being precise about what an on-chain observer actually learns:

Information	Buyer knows	Seller knows	Chain sees	Observer learns
Transfer amount	✓	✓ (after sharing)	✗	✗
Release secret	✓	✓ (after sharing)	✗	✗
Nonce	✓	✓ (after sharing)	✗	✗
Buyer identity	✓	✓	`H(buyerSk)`	Pseudonym only
Seller identity	✓	✓	`sellerPk` as passed	Pseudonym only
That a transfer occurred	✓	✓	✓	✓
Transfer direction (who→who)	✓	✓	✓	✓

buyer and seller are on-chain; direction is visible. This is a deliberate tradeoff: escrow semantically requires knowing who holds which role. A symmetric private swap would need a different design where both parties are represented symmetrically.

The termsCommitment field is worth a specific note: it's 32 bytes on-chain, visible to everyone. But it reveals nothing about the underlying values. Two escrows with identical amounts and secrets but different nonces produce completely different commitments, the nonce is what ensures this, and it never leaves the buyer's private state.

The General Pattern: What Escrow Teaches Us

Strip the escrow semantics away and what remains is a reusable coordination primitive for any private multi-party transfer on Midnight:

1. Commit to transfer terms at initiation

termsCommitment = disclose(persistentCommit([value, hash(secret)], nonce));

2. Bind identities to private keys via derivation

const pk = deriveKey(secretKey());
assert(pk == onChainIdentity, "Auth failed");

3. Verify the commitment at completion

const recomputed = persistentCommit([value, hash(secret)], nonce);
assert(recomputed == termsCommitment, "Proof failed");

4. Enforce ordering via state machine

assert(state == ExpectedState, "Wrong state");
// ... logic ...
state = NextState;

Private DEX swaps, confidential lending, sealed-bid auctions; all of them are variations on this structure. They need to bind two parties to agreed terms, verify those terms without revealing them, and enforce who moves first. The escrow contract is the cleanest working example of how Midnight's primitives compose to solve it.

What's Next

The repo explicitly lists its open extensions: timeout-based refunds, multi-party agreements, private dispute resolution. Each is a direct extension of the patterns here. The commitment scheme generalises to more parties by including more values in the committed vector. The state machine grows more states. The identity checks stay identical, deriveKey(secretKey()) works regardless of how many participants are involved.

Part 1: Building a Bonding Curve Token on Midnight
Part 2: You're Probably Using export ledger Wrong
Full source: github.com/sevryn-labs/midnight-escrow

You're Probably Using export ledger Wrong

Tushar Pamnani — Fri, 27 Mar 2026 17:51:16 +0000

Part 2 of building with Midnight. Part 1 here.

In the first article we built a bonding curve on Midnight and were honest about something most ecosystem articles aren't: the token balances in that contract are fully public. Not because Midnight can't do better; it can, but because we used export ledger for everything and wrapped every balance update in disclose().

That's the default pattern developers reach for when coming from Solidity, and it's the wrong instinct on Midnight.

This article is specifically about that decision: what export ledger actually means at the protocol level, what private state actually means, what disclose() is doing as a compile-time mechanism, and when you should use each. By the end you'll have a clear mental model and a concrete refactor path for the bonding curve balances.

The mental model you need to drop first

Coming from Solidity, your mental model of contract state is a single flat namespace. Everything in storage is public. Privacy is something you bolt on externally; encryption, commit-reveal, ZK gadgets. The language doesn't have an opinion about it.

Midnight inverts this completely. In Compact, private information should be disclosed only as necessary, and the language requires disclosure to be explicitly declared. This makes privacy the default and disclosure an explicit exception, reducing the risk of accidental disclosure.

That sentence is doing a lot. Privacy is the default. Disclosure is an exception you have to actively declare. The compiler enforces this; it will reject your program if you try to move witness data to the public ledger without explicitly saying so.

The practical implication: every piece of state in a Midnight contract starts in one of two worlds, and moving between them requires a deliberate act.

World 1: `export ledger`: the public world

ledger declarations represent the local state of the smart contract, the state that is kept on-chain. The values in the ledger are visible and public.

When you write this:

export ledger totalSupply: Uint<64>;
export ledger balances: Map<Bytes<32>, Uint<64>>;

both fields are synchronized across every node on the network. Any observer can read them. They are as public as a Solidity mapping, no caveats.

The export keyword does two additional things beyond making the field public: it makes the field readable from the TypeScript/JavaScript side of your dApp, and it makes it part of the deployed contract's on-chain interface. You need export on any ledger field your frontend will read.

This is the right choice for state that the market needs to see. In the bonding curve, totalSupply, reserveBalance, and curveSlope are correctly export ledger. Anyone interacting with the contract needs to know the current price, and the price is a function of those three values. Hiding them would break the market.

World 2: Private state: the local world

Private state is encrypted data stored locally by users, never exposed to the network.

Private state in a Midnight contract lives on the user's machine, managed by the wallet SDK. It is never written to the chain as plaintext. The chain only ever sees a cryptographic commitment to it; a hash that proves the value exists and hasn't changed without revealing what it is.

This is the right home for per-user data. Token balances, allowances, position sizes; information that belongs to the user and that nobody else has a legitimate reason to see.

The contrast with export ledger is stark:

	`export ledger`	Private state
Where it lives	Every node on the network	User's local storage
Who can read it	Anyone	Only the owner
On-chain representation	Plaintext value	Cryptographic commitment
How it's updated	Direct ledger assignment	Via ZK proof
Solidity equivalent	`public` storage variable	No equivalent

`disclose()`: the boundary marker, not an escape hatch

This is the most misunderstood operator in Compact, and understanding it precisely matters.

A Compact program must explicitly declare its intention to disclose data that might be private before storing it in the public ledger, returning it from an exported circuit, or passing it to another contract.

disclose() is not an encryption function. It is not a privacy mechanism. It does the opposite: it is a compile-time annotation that says "I know this witness data is going public, and I am doing it on purpose."

Placing a disclose() wrapper does not cause disclosure in itself; it has no effect other than telling the compiler that it is okay to disclose the value of the wrapped expression.

Think of it as a signed waiver. You're not changing what happens at runtime, the value was going to the ledger either way. You're just telling the compiler you made a deliberate choice, not an accidental one.

Without it, the compiler rejects your program outright:

witness getBalance(): Bytes<32>;
export ledger balance: Bytes<32>;

export circuit recordBalance(): [] {
    balance = getBalance();  // compiler error
}

Exception: line 6 char 11:
  potential witness-value disclosure must be declared but is not:
    witness value potentially disclosed:
      the return value of witness getBalance at line 2 char 1
    nature of the disclosure:
      ledger operation might disclose the witness value

With it:

export circuit recordBalance(): [] {
    balance = disclose(getBalance());  // compiles fine
}

The compiler calls its enforcement mechanism the "witness protection program", it is implemented as an abstract interpreter, where the abstract values are not actual run-time values but information about witness data that will be contained within the actual run-time values. If at some point the interpreter encounters an undeclared disclosure of an abstract value containing witness data, the compiler halts and produces an appropriate error message.

One subtlety worth knowing: the disclosure tracking follows witness data through arithmetic, type conversions, and function calls. You cannot obfuscate your way past it:

circuit obfuscate(x: Field): Field {
    return x + 73;  // still witness data
}

export circuit recordBalance(): [] {
    const s = S { x: getBalance() as Field };
    const x = obfuscate(s.x);
    balance = x as Bytes<32>;  // compiler still catches this
}

Subjecting witness data to arithmetic, converting it from one representation to another, and passing it into and out of other circuits does not hide potential disclosure from the compiler.

The best practice from the docs: put the disclose() wrapper as close to the disclosure point as possible to avoid accidental disclosure if the data travels along multiple paths.

The commitment pattern: how private state actually works

If export ledger puts values on-chain as plaintext, and private state keeps them off-chain entirely, you might wonder: how does the contract verify anything about private state without seeing it?

The answer is commitments. A commitment scheme hashes arbitrary data together with a random nonce. The result can be safely placed into the ledger's state without revealing the original data. At a later point, the commitment can be "opened" by revealing the value and nonce, or a contract can simply prove (assert) that it has the correct value and nonce without ever revealing them.

The Compact standard library provides the tools for this:

circuit transientHash<T>(value: T): Field;
circuit transientCommit<T>(value: T, rand: Field): Field;
circuit persistentHash<T>(value: T): Bytes<32>;
circuit persistentCommit<T>(value: T, rand: Bytes<32>): Bytes<32>;

The transient* functions should only be used when the values are not kept in state, while persistent* outputs are suitable for storage in a contract's ledger state.

There's an important note on nonces: the nonce must not be reused. If it is, you can link the commitments with the same nonces and values. Nonce reuse breaks the privacy guarantee, two commitments with the same nonce and value are identical on-chain, letting an observer link them.

One additional thing the compiler knows: transientCommit(e) is treated as non-witness data even if e contains witness data. transientHash(e) is not: the hash output is still tracked as witness-tainted. This is because a commitment includes a random nonce that sufficiently hides the input, while a bare hash might not.

Applying this to the bonding curve

Here's the current state of the bonding curve contract:

// currently: fully public
export ledger balances: Map<Bytes<32>, Uint<64>>;
export ledger allowances: Map<Bytes<32>, Map<Bytes<32>, Uint<64>>>;

And the buy circuit updates them like this:

const caller = disclose(callerAddress());
balances.insert(caller, disclose((prevBalance + n) as Uint<64>));

Both the address and the new balance are disclose()-d; explicitly pushed public. Anyone watching the chain can see who bought and how many tokens they now hold. This is identical to what you'd get on Ethereum.

The refactor toward private balances involves three changes:

1. Store a commitment in the ledger instead of the balance

export ledger balanceCommitments: Map<Bytes<32>, Bytes<32>>;

The map key is still the user's address (which stays public, you need to look up commitments by user). The value is persistentCommit(balance, nonce), a hash of the balance and a random nonce.

2. Keep the actual balance in private state

The user's wallet holds the plaintext balance and the nonce locally. These never touch the chain.

3. In the circuit, prove the old commitment and assert the new one

export circuit buy(n: Uint<64>, maxCost: Uint<64>): [] {
    // ...existing checks...

    const caller = disclose(callerAddress());
    const prevBalance = localBalance();      // witness: read from private state
    const nonce = localNonce();              // witness: read from private state
    const newNonce = freshNonce();           // witness: generate new nonce

    // verify the existing commitment matches what's on-chain
    const oldCommit = persistentCommit(prevBalance, nonce);
    assert(balanceCommitments[caller] == oldCommit, "Balance commitment mismatch");

    // write the new commitment — balance updated, but value stays private
    const newBalance = prevBalance + n;
    balanceCommitments.insert(caller, disclose(persistentCommit(newBalance, newNonce)));
}

What goes on-chain: the new commitment. What stays private: the actual balance and nonce. The ZK proof guarantees the arithmetic was done correctly without revealing the operands.

This is the pattern PROTOCOL.md describes and the current contract code doesn't yet implement. The core curve logic, the witness-verified cost calculation, the reserve invariant, the slippage protection; stays completely unchanged. Only the balance storage layer changes.

The decision table

Here's the practical guide for any state field you're designing:

If your data...	Use...	Because...
Defines market price or global invariants	`export ledger`	Every participant needs it to interact correctly
Needs to be read by your frontend directly	`export ledger`	Private state isn't accessible from TypeScript without a proof
Is per-user and sensitive	Private state + commitment in ledger	Balance stays local; proof verifies correctness
Is a temporary computation input	Witness (no ledger at all)	Lives only for the duration of proof generation
Proves membership without revealing value	`persistentCommit` in `export ledger`	Commitment on-chain, value stays private
Is an identity/address you're intentionally publishing	`disclose()` + `export ledger`	Explicit, deliberate public disclosure

The quick heuristic: if removing this field from the chain would break another user's ability to interact with the contract, it belongs in export ledger. If it belongs only to one user and no one else needs to verify it directly, it belongs in private state.

Why the compiler enforces this

It's worth appreciating what Midnight's design actually achieves here. On Ethereum, accidentally making private data public is easy; you just expose the wrong storage variable. There's no language-level guardrail. The compiler is indifferent to privacy.

Compact's "witness protection program" makes accidental disclosure a compile error. The decision to disclose private information must rest with each Midnight dApp because disclosure requirements are inherently situation-specific. Because private information should be disclosed only as necessary, Midnight's Compact language requires disclosure to be explicitly declared.

Every disclose() in your codebase is a record of a conscious decision. You can audit your contract's privacy model by grepping for disclose(), every hit is a place where witness data crosses into the public world. If you see one you didn't intend, the fix is architectural, not cosmetic.

That's a fundamentally different relationship between language and privacy than anything in the EVM ecosystem.

What's next?

The bonding curve commitment refactor outlined above is a genuine open contribution on the repo. If you're exploring Midnight's private state primitives, that's a contained, well-tested codebase to experiment on; the test suite already covers the invariants, so you'll know immediately if your refactor breaks something.

The next level from here is understanding how private state interacts with transfers between users, which requires both parties to update their local private state atomically, coordinated by a proof that neither can fake. That's a more involved pattern and worth its own article.

Part 1: Building a Bonding Curve Token on Midnight
Full source: github.com/sevryn-labs/midnight-bonding-curve

Building a Bonding Curve Token on Midnight, With Real ZK Proofs

Tushar Pamnani — Tue, 17 Mar 2026 13:59:53 +0000

Full source: github.com/sevryn-labs/midnight-bonding-curve

If you've built DeFi on EVM chains before, you already know the shape of a bonding curve: a smart contract that prices tokens algorithmically against supply, mints on buy, burns on sell, and holds a reserve. No order book. No oracle. The math is the market maker.

What makes building one on Midnight interesting isn't that this implementation hides all your data - it doesn't, and we'll be precise about what's public and what isn't. What's interesting is the execution model: how Midnight separates off-chain computation from on-chain verification using ZK proofs, and what that unlocks as a foundation for genuinely private DeFi primitives.

We'll cover the bonding curve math, how Midnight's execution model differs from what you're used to, the ZK witness pattern that replaces what would normally just be on-chain arithmetic, and an honest account of the current privacy boundary. The full contract is in Compact (Midnight's smart contract language) and the off-chain layer is TypeScript.

The math first, briefly

We're using a linear bonding curve where the marginal price at supply s is:

P(s) = a · s

a is the slope set at deployment. Price scales linearly with supply — simple, predictable, well-understood economic properties.

Because price moves during a purchase, you can't just multiply. You integrate the curve over the range of tokens being bought:

Cost(s, n)   = (a / 2) · ((s + n)² − s²)   // buying n tokens from supply s
Refund(s, n) = (a / 2) · (s² − (s − n)²)   // selling n tokens from supply s

From this falls a reserve invariant that must hold at all times:

R(s) = (a / 2) · s²

Every buy and sell is checked against this invariant inside the circuit. Any state that violates it cannot produce a valid ZK proof; the math enforces solvency at the cryptographic level.

If you want the full derivation and economic intuition behind the curve, I wrote a deeper breakdown on my blog →

What Midnight is actually doing differently

Before diving into the contract, it's worth being precise about Midnight's execution model, because it's genuinely different from EVM or Solana and the differences shape every design decision.

On a typical chain, when you call a function the validators re-execute your computation and check the result. Everyone sees the inputs. On Midnight, you execute the circuit locally, generate a ZK proof that you did it correctly, and submit only the proof plus public outputs. Validators verify the proof in milliseconds without ever seeing your private inputs.

The state model reflects this split directly. The first diagram above shows the full ZK transaction flow. The second shows the state split as it exists in this contract. totalSupply, reserveBalance, curveSlope, and the admin fields are public export ledger variables; anyone can read them on-chain. The witnesses, callerAddress and calculateCost, are computed locally and fed into the proof generation step but never written to the chain as plaintext.

The proof server is a local Docker container. It never touches the network. It takes your inputs, runs the circuit constraints, and generates the proof. Your witness values never leave your machine.

An honest account of what's public in this contract

This is the section that most implementations gloss over, so let's be direct.

balances and allowances are defined as export ledger maps:

export ledger balances: Map<Bytes<32>, Uint<64>>;
export ledger allowances: Map<Bytes<32>, Map<Bytes<32>, Uint<64>>>;

In Compact, ledger variables represent public state synchronized across all nodes. And in the buy, sell, and transfer circuits, balances are updated using disclose():

balances.insert(caller, disclose((prevBalance + n) as Uint<64>));

disclose() explicitly adds a value to the transaction's public circuit outputs. That means updated balances and associated addresses are visible to anyone observing the blockchain. This is the same privacy model as a standard EVM token.

It's worth noting that PROTOCOL.md in the repo describes a commitment-based privacy model for balances, but the current contract code doesn't implement it yet. Consider this a working reference implementation of the bonding curve mechanics, with private balances as the natural next step once the pattern is wired in.

Midnight absolutely supports genuinely private balance maps using persistent private state and commitment types. This contract just doesn't use them yet. When someone asks "are token balances private on this contract?" — the honest answer right now is no, but the architecture of the chain makes it achievable without changing the core curve logic.

The witness pattern, where EVM and Midnight diverge most sharply

This is the part that most confuses developers coming from Solidity, and it's also the most interesting part of the architecture.

In Solidity, you'd compute the bonding curve cost directly inside the contract:

function mintCost(uint256 s, uint256 n) internal view returns (uint256) {
    return (slope * ((s + n)**2 - s**2)) / 2;
}

In Compact, you can't do arbitrary arithmetic inside the circuit for free. ZK circuits have constraints, and squaring large integers is expensive inside them. The solution is the witness pattern: compute the expensive thing off-chain in TypeScript, pass the result into the circuit, and have the circuit verify the result rather than recompute it.

The contract declares the witness as a foreign function:

witness calculateCost(
    slope: Uint<64>,
    s_old: Uint<64>,
    s_new: Uint<64>
): Uint<64>;

You implement this in TypeScript using native BigInt, no circuit constraints, full precision:

// src/math.ts
export function calculateMintCost(slope: bigint, s: bigint, n: bigint): bigint {
    const sNew = s + n;
    return (slope * (sNew * sNew - s * s)) / 2n;
}

The circuit then verifies the result rather than trusting it blindly:

circuit verifiedHalfProduct(
    slope: Uint<64>,
    s_old: Uint<64>,
    s_new: Uint<64>
): Uint<64> {
    const result = calculateCost(slope, s_old, s_new);
    const totalProduct = slope * (s_new * s_new - s_old * s_old);
    assert(
        2 * result == totalProduct || 2 * result + 1 == totalProduct,
        "Witness cost value failed verification"
    );
    return result;
}

That 2 * result + 1 branch deserves an explanation. Compact uses integer (truncating) division. When deltaSq = (s+n)² − s² is odd, dividing by 2 truncates — the remainder is lost. The circuit permits both branches because either 2·result == totalProduct (even case) or 2·result + 1 == totalProduct (odd case, truncated). Critically, both Cost(s,n) and Refund(s,n) for the same (s,n) pair truncate the same product, so mint/burn reversibility is preserved across rounding.

This is not a trust assumption, it's a constraint. A witness that provides a wrong value will fail this assertion and no valid proof can be generated.

`callerAddress()`, the `msg.sender` equivalent

The other witness in the contract is callerAddress(), declared as:

witness callerAddress(): Bytes<32>;

This is the Midnight equivalent of Solidity's msg.sender. It's implemented in witnesses.ts to read the address field out of the user's local PrivateState, the wallet's identity, resolved off-chain during proof generation.

Because it's a witness, you might wonder: can a user just lie and provide someone else's address? No. The value is bound by the ZK proof. In deployment, the circuit verifies that the provided witness is consistent with the public key that authorized the state transition; a user can only move tokens that their own proof can account for. The witness is provided by the user, but the circuit constraints make fraud cryptographically impossible to prove.

In buy, the caller address is used like this:

const caller = disclose(callerAddress());
balances.insert(caller, disclose((prevBalance + n) as Uint<64>));

The disclose() on callerAddress() is what makes the buyer's address visible on-chain, consistent with the public balance model the contract currently uses.

Walking through a buy

Here's the full buy circuit with annotations:

export circuit buy(n: Uint<64>, maxCost: Uint<64>): [] {
    // 1. Emergency halt check
    assert(!paused, "Contract is paused");

    // 2. Optional supply cap enforcement
    const s = totalSupply;
    const newSupply = s + n;
    assert(supplyCap == 0 || newSupply <= supplyCap, "Supply cap exceeded");

    // 3. Cost via verified witness (off-chain compute, on-chain verify)
    const cost = verifiedHalfProduct(curveSlope, s, newSupply);

    // 4. Slippage protection — caller set their own limit
    assert(cost <= maxCost, "Cost exceeds maxCost slippage limit");

    // 5. Mint: update supply, reserve, and caller's balance
    totalSupply = newSupply;
    reserveBalance = reserveBalance + cost;
    const caller = disclose(callerAddress());
    balances.insert(caller, disclose((prevBalance + n) as Uint<64>));
}

The sell circuit mirrors this exactly, using verifiedHalfProduct(curveSlope, newSupply, s) (arguments reversed) to compute the refund, and a minRefund guard instead of maxCost.

What you actually deploy and run

The repo structure maps cleanly to the execution model:

contracts/
  bonding_curve.compact       # Compact source → compiled to ZK circuits + TS bindings

src/
  math.ts                     # Off-chain witness implementations (pure BigInt)
  simulator.ts                # In-process state replica for testing (no proof server needed)
  cli.ts                      # Interactive buy/sell/transfer terminal
  deploy.ts                   # Deployment to Midnight Preprod
  witnesses.ts                # Witness implementations including callerAddress()
  tests/
    bonding_curve.test.ts     # 27 test sections, fuzz and invariant tests

Compilation turns bonding_curve.compact into ZK circuits, generating keys and TypeScript API bindings:

npm install
npm run compile   # compactc → zkir/ + keys/ + TS bindings
npm run build

To deploy or interact with a live contract, the proof server must be running:

npm run start-proof-server   # local Docker container, keep it alive

npm run deploy               # deploys to Midnight Preprod, prompts for wallet seed
npm run cli                  # interactive: buy, sell, transfer, inspect state

Your wallet needs tNIGHT tokens for gas. Use the Midnight preprod faucet, then the CLI prompts you through everything else.

One implementation detail worth calling out: the CLI uses Midnight Unshielded Addresses (mn_addr_...) as the canonical user identity. These Bech32m strings are decoded and SHA-256 hashed to produce a deterministic 32-byte key for the internal maps. This normalization prevents the same user from appearing as different identities depending on which address format they use.

The test suite is worth reading

The contract ships with 27 test sections. A few worth calling out:

The reserve invariant tests verify R = (a/2) · s² after every operation across interleaved multi-user sequences. The integer arithmetic tests specifically probe the odd/even deltaSq truncation behavior and confirm that mint/burn round-trips are symmetric. The randomized fuzz runs 100 random buy/sell sequences and checks the invariant after each round. The large-number stress tests push supply values to 10¹¹ to surface overflow before it surfaces in production.

If you're deploying a variant, the overflow section in the README deserves careful attention: at slope=10, the reserve overflows Uint<64> around s ≈ 1.36 × 10⁹. Choosing slope and cap values such that slope · cap² / 2 < 2⁶⁴ is a deployment-time decision, not something the circuit enforces for you.

Where to go from here

The natural next step is refactoring balances and allowances to use Midnight's persistent private state - replacing the current export ledger maps and disclose() calls with commitment-backed private storage. The core curve logic, the witness pattern, and the reserve invariant all stay exactly the same. Only the state storage layer changes. That's the version that matches what PROTOCOL.md describes, and it's a meaningful contribution to make to this repo if you're exploring Midnight's privacy primitives.

Beyond that, the patterns here - witness-verified arithmetic, ZK-enforced reserve invariants, slippage protection at the circuit level, generalize naturally. Multi-token pools, TWAP oracles, prediction markets where positions are hidden until resolution: all of these become tractable once you've internalized the witness/circuit split.

The full source, test suite, and deployment scripts are at github.com/sevryn-labs/midnight-bonding-curve.

Reference implementation, not audited, not production-ready without a full security review. See AUDIT.md in the repo before putting real value behind it.

DEV Community: Tushar Pamnani

45 Days Building on Midnight: An Honest Builder's POV

What "45 Days Full-Time" Actually Means

The Thing That Made Me Cry: Developer Experience

The Thing That Surprised Me: The Team Actually Shows Up

The Thing I Didn't Expect: ZK Stopped Being Scary

What's Missing: The Proof Server Problem Isn't Fully Solved

Should You Build on Midnight?

What Comes Next

I Spent Hours in the DOM So You Don't Have To

What the Problem Actually Looks Like

What Midnight Wallet Kit Gives You

Setup

The Four Hooks

useWallet(): connection state

useConnect(): connection management

useIntent(): signing

useBalance(): balance polling

The Architecture: Why It's Built This Way

Adapters normalize the provider chaos

WalletManager handles the lifecycle

Middleware for observability

Typed Errors: No More catch (e: any)

Testing Without a Browser Extension

SSR and Next.js

What's Next

ZK Membership Proofs on Midnight

The Problem: Membership Without Identity

Why Merkle Trees Work for ZK Membership

The Ledger: Minimal Public Surface

The Witnesses: Everything Private

The hashLevelNode Circuit

The verifyAndUse Circuit, Step by Step

The Admin Pattern: ZK Governance

The Off-Chain Layer: What allowlist-utils.ts Actually Does

The Concatenation Bug the Tests Found

What's Actually on the Chain

The General Pattern

What's Next

How Midnight Verifies tokens Without Computing It

What Quadratic Voting Is and Why It's Hard in ZK

The verifySqrt Insight

The Full Contract, Annotated

What's Actually On-Chain

The Mental Model This Series Has Been Building

What's Next

How Midnight Coordinates Two-Party Transfers

The Coordination Problem, Stated Precisely

The Ledger: What's Actually Public

The Witnesses: The Private Side

Identity Without Exposing Keys: deriveKey

The Commitment Scheme: Binding Terms Without Revealing Them

The Verification: How the Seller Proves Knowledge of the Secret

The Full Protocol Flow

acceptEscrow: The Lightweight Identity Check

refund: The Escape Hatch

State Machine: Why Ordering Is a Security Property

The Privacy Accounting: What Leaks and What Doesn't

The General Pattern: What Escrow Teaches Us

What's Next

You're Probably Using export ledger Wrong

The mental model you need to drop first

World 1: export ledger: the public world

World 2: Private state: the local world

disclose(): the boundary marker, not an escape hatch

The commitment pattern: how private state actually works

Applying this to the bonding curve

The decision table

Why the compiler enforces this

What's next?

Building a Bonding Curve Token on Midnight, With Real ZK Proofs

The math first, briefly

What Midnight is actually doing differently

An honest account of what's public in this contract

The witness pattern, where EVM and Midnight diverge most sharply

callerAddress(), the msg.sender equivalent

Walking through a buy

What you actually deploy and run

The test suite is worth reading

Where to go from here

`useWallet()`: connection state

`useConnect()`: connection management

`useIntent()`: signing

`useBalance()`: balance polling

Typed Errors: No More `catch (e: any)`

The `hashLevelNode` Circuit

The `verifyAndUse` Circuit, Step by Step

The Off-Chain Layer: What `allowlist-utils.ts` Actually Does

The `verifySqrt` Insight

Identity Without Exposing Keys: `deriveKey`

`acceptEscrow`: The Lightweight Identity Check

`refund`: The Escape Hatch

World 1: `export ledger`: the public world

`disclose()`: the boundary marker, not an escape hatch

`callerAddress()`, the `msg.sender` equivalent