Forem: Midnight Aliit Fellowship

I Built a Midnight dApp Like an ETH Dev. Here's Everything I Got Wrong.

Tushar Pamnani — Thu, 07 May 2026 09:51:16 +0000

A brutally honest post-mortem on migrating from a server-managed wallet to the 1AM browser extension on the Midnight Network.

The Decision That Cost Me Two Days

I want to be specific about the moment I made the mistake, because it's a very recognizable moment.

Contracts written. Deployed on preprod. ZK proofs generating correctly through the CLI. I was looking at green checkmarks across the board and thinking: frontend time. The hard part was done.

That's the exact mental state where bad architectural decisions happen. You're riding the momentum of something working, and the last thing you want is to slow down and think carefully about something that feels like plumbing.

So I didn't. I looked at Midnight's SDK, saw a server-side wallet pattern that worked perfectly in Node.js, and made a decision I immediately told myself I'd "clean up later":

For simplicity, I'll just use a single server-side wallet for all transactions.

I've been writing software long enough to know that "clean up later" is a specific kind of lie developers tell themselves. But I told it anyway.

Later arrived. It cost me two days. Here's the full damage report.

What "Server Wallet" Actually Meant

Here's the thing about this mistake: it's completely understandable. If you come from Ethereum, you've probably written backend scripts that interact with contracts using a private key stored in a .env file. Hardhat tasks, deployment scripts, admin functions, server-side signing is normal. Expected, even.

Midnight has an equivalent pattern that works perfectly in Node.js environments. It goes something like this:

import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
import { NodeZkConfigProvider } from '@midnight-ntwrk/midnight-js-node-zk-config-provider';
import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client-proof-provider';
import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';

const zkConfigProvider = new NodeZkConfigProvider(zkConfigPath);
const proofProvider = httpClientProofProvider('http://127.0.0.1:6300', zkConfigProvider);
const wallet = await WalletFacade(/* ... */);

This is great for scripts. For CLI tools. For testing. It reads ZK artifacts from the filesystem, talks to a local proof server on port 6300, and persists private state using LevelDB.

What it is not is a browser-compatible architecture.

But I didn't think about that. I was in "get it working" mode. I stuffed this into my Next.js backend, created a server action that would sign and submit every transaction with my wallet, and called it done.

This worked. Demos looked fine. The contract calls went through. Nobody watching the demo could tell anything was architecturally broken.

That's the insidious part. The mistake is invisible until you try to ship to real users, and by that point, you've built an entire frontend on top of it.

Why It's Wrong (Beyond the Obvious "Users Can't Sign")

The most glaring problem is one everyone will call out immediately: users aren't signing their own transactions. That's not a dApp. That's a centralized backend with a ZK circuit in the middle. You've recreated a custodial wallet and called it Web3.

But there are deeper, more practical problems.

Problem 1: levelPrivateStateProvider doesn't exist in browsers.

LevelDB is a Node.js library. The moment you try to bundle this in a Next.js client component, you get a wall of webpack errors about missing native modules. You can't polyfill your way out of this.

Problem 2: NodeZkConfigProvider reads from the filesystem.

fs.readFileSync. In a browser. You know where this goes. The ZK artifacts (.verifier files and .bzkir files) need to be fetched over HTTP, not read from disk, but NodeZkConfigProvider doesn't know how to do that.

Problem 3: You're depending on a local proof server.

The httpClientProofProvider calls http://127.0.0.1:6300. That's a proof server that needs to be running locally. Your users don't have one. Your Vercel deployment definitely doesn't. And even if you ran it remotely, you'd immediately hit CORS hell trying to call it from the browser.

Problem 4: You hold all the keys.

Every transaction goes through your server wallet. Your seed phrase. Your keys. If your server goes down, the dApp breaks. If you rotate keys, every active session breaks. You've become the single point of failure for a supposedly trustless application.

I knew all of this, in theory. I just thought I'd "clean it up later."

Later arrived.

The Migration: What Actually Has to Change

The 1AM wallet is a browser extension for Midnight, think MetaMask but for ZK-native transactions. It injects a window.midnight['1am'] object and handles proof generation, transaction balancing, and signing internally.

To migrate, I had to rip out four things and replace them all.

1. ZK Config Provider

Before: NodeZkConfigProvider reading from filesystem.

After: FetchZkConfigProvider loading artifacts over HTTP.

const baseUrl = new URL('/contract/collection', window.location.origin).toString();
const zkConfigProvider = new FetchZkConfigProvider(baseUrl, window.fetch.bind(window));

This expects your compiled artifacts to be served statically. The provider constructs URLs like:

{baseUrl}/keys/{circuitId}.verifier
{baseUrl}/zkir/{circuitId}.bzkir

So I had to compile my contracts and drop the output into public/contract/collection/. Then verify they were actually accessible:

curl http://localhost:3000/contract/collection/keys/mint.verifier

If that returns HTML, you've got a path problem. If it returns binary data, you're good.

The gotcha I hit: I had my artifacts in the right directory but wrong structure. The provider expects keys/ and zkir/ subdirectories with specific naming. My files were dumped flat into the folder. This gave me a cryptic Failed to fetch ZK config for circuit 'mint' error that took me two hours to trace back to a missing subdirectory.

Two hours. For a missing folder. The error message gave no indication that the problem was directory structure, it just said fetch failed. This is a category of debugging that ages you.

2. Proof Provider

Before: httpClientProofProvider pointing to a local proof server.

After: The wallet's own proving capability.

const api = await wallet1AM.connect(networkId);
const provingProvider = await api.getProvingProvider(zkConfigProvider);

const proofProvider = {
  async proveTx(unprovenTx: any, _config: any) {
    const { CostModel } = await import('@midnight-ntwrk/ledger-v8');
    return unprovenTx.prove(provingProvider, CostModel.initialCostModel());
  },
};

The 1AM extension bundles its own ZK prover. You don't need a proof server running anywhere. This is the cleanest part of the migration, once you have a connected wallet API, proof generation just works.

The dynamic import on CostModel is necessary. The ledger-v8 package ships a WASM module that Next.js tries to bundle at build time, and it fails. Dynamic import() defers it to runtime in the browser where WebAssembly is available. You'll still see warnings in your build logs about async/await not being supported in the target environment, those are non-blocking, but they're loud and they'll worry you the first time you see them.

I spent an embarrassing stretch of time trying to silence those warnings before accepting they were cosmetic. The build was fine. The app ran fine. I was just pattern-matching on red text in terminals. Move on faster than I did.

3. Private State Provider

Before: levelPrivateStateProvider with LevelDB persistence.

After: An in-memory map with contract address scoping.

function createPrivateStateProvider() {
  let contractAddressScope = '';
  const stateStore = new Map<string, any>();

  return {
    setContractAddress(address: string) {
      contractAddressScope = address;
    },
    async set(privateStateId: string, state: any) {
      stateStore.set(`${contractAddressScope}:${privateStateId}`, state);
    },
    async get(privateStateId: string) {
      return stateStore.get(`${contractAddressScope}:${privateStateId}`) ?? null;
    },
    // signing key methods...
  };
}

The scoping by contract address is not optional. If you deploy multiple contracts in the same session without scoping, private state bleeds between them. I deployed two collection contracts during testing and couldn't figure out why the second one was behaving like the first, private state was resolving to the wrong contract's data. This one took longer to diagnose than I'd like to admit, because "state leaking between contracts" isn't where your brain goes first when a minting flow misbehaves.

The honest trade-off: this is ephemeral. Page reload wipes it. For production you'd want IndexedDB or syncing with the wallet's own private state store. That's a future problem. Right now, scoped in-memory state is correct enough to ship and test against real users.

4. Transaction Balancing and Submission

This is the most finicky part and where most of the debugging time went.

Before: WalletFacade.balanceTx() returned a Transaction object directly.

After: api.balanceUnsealedTransaction() returns a hex string. You have to deserialize it yourself.

const walletProvider: WalletProvider = {
  balanceTx: async (tx: any) => {
    const txHex = toHex(tx.serialize());
    const balanced = await api.balanceUnsealedTransaction(txHex);

    // The wallet returns { tx: "hexstring" } — you must deserialize
    const { Transaction } = await import('@midnight-ntwrk/ledger-v8');
    const bytes = new Uint8Array(
      balanced.tx.match(/.{2}/g).map((b: string) => parseInt(b, 16))
    );
    return Transaction.deserialize('signature', 'proof', 'binding', bytes);
  },
  getCoinPublicKey: () => shieldedAddress.shieldedCoinPublicKey,
  getEncryptionPublicKey: () => shieldedAddress.shieldedEncryptionPublicKey,
};

The error I got before adding the deserialization step was Error: balanceUnsealedTransaction returned invalid result. Not "type mismatch," not "expected Transaction object, received string." Just "invalid result." I stared at that error for longer than I should have before realizing the wallet was returning hex and I was passing it somewhere that expected a typed object.

Good error messages would have made this a 5-minute fix. It was not a 5-minute fix.

For submission:

const midnightProvider: MidnightProvider = {
  submitTx: async (tx: any) => {
    const txHex = toHex(tx.serialize());
    const result = await api.submitTransaction(txHex);

    // Handle multiple possible return shapes across wallet versions
    return (typeof result === 'string' 
      ? result 
      : result?.transactionId || result?.id) || '';
  },
};

The defensive extraction on transactionId || id exists because different versions of the 1AM extension return different shapes. You'll only discover which one you have when your transaction ID comes back as undefined in production.

The Race Condition Nobody Warns You About

Browser extensions load asynchronously. Your app boots, checks window.midnight['1am'], finds nothing, and reports "wallet not found", even though the extension is installed and working.

You need to poll:

const DETECT_TIMEOUT_MS = 6000;
const DETECT_INTERVAL_MS = 300;

const startedAt = Date.now();
const intervalId = setInterval(() => {
  const wallet = (window as any).midnight?.['1am'];

  if (wallet) {
    clearInterval(intervalId);
    // proceed with connection
    return;
  }

  if (Date.now() - startedAt >= DETECT_TIMEOUT_MS) {
    clearInterval(intervalId);
    // show "install wallet" message
  }
}, DETECT_INTERVAL_MS);

Six seconds is generous but reasonable. The extension usually loads within one or two. If it's not there after six, the user genuinely doesn't have it installed.

Also support Lace wallet as a fallback, window.midnight.mnLace, and consider a seed phrase input mode for CLI users and recovery scenarios. Real users will be less technical than you. Having multiple connection paths matters.

The Full Diff: What the Architecture Actually Looks Like Now

The server wallet model had everything in a single Node.js process. One wallet, one proof server, one private state database. Simple to reason about, impossible to scale to real users.

The browser wallet model distributes responsibility correctly:

User's Browser
├── 1AM Extension
│   ├── User's private keys (never leaves extension)
│   ├── Built-in ZK prover
│   └── Transaction signing
│
└── Your Next.js App
    ├── FetchZkConfigProvider (loads artifacts from /public)
    ├── In-memory PrivateStateProvider (scoped per contract)
    └── WalletProvider / MidnightProvider (delegates to extension)

The app never touches private keys. The user signs everything. The proof server is gone. The LevelDB dependency is gone. CORS is gone.

What I'd Tell Myself If I Could Go Back

Don't prototype with server wallets. The migration cost is real. Every abstraction you build around the server wallet pattern has to be unwound. If I'd started with the 1AM integration from day one, even just stubbed out, the final code would have been cleaner and I'd have caught the ZK artifact path issues during initial development rather than during migration.

Read the provider interfaces, not the implementations. The SDK exports clean interfaces for WalletProvider, MidnightProvider, ProofProvider. If I'd read those first instead of copying the working server-side implementations, I'd have understood earlier that these are swappable, and that swapping them is the whole point.

Browser-first is table stakes. You know this from Ethereum. MetaMask was non-negotiable in 2019. Apply the same instinct to Midnight immediately, don't let the novelty of ZK circuits make you forget the basics.

Scope your private state by contract address on day one. The fix is a single string prefix. The debugging session when you skip it is not.

The Honest Part Nobody Writes

Here's the thing I kept thinking about while doing this migration:

The error messages in Midnight's SDK are often terrible. Not "could be better", genuinely unhelpful in ways that send you in the wrong direction. balanceUnsealedTransaction returned invalid result tells you nothing about what was actually invalid. Failed to fetch ZK config for circuit 'mint' gives you zero signal about whether the problem is the URL, the directory structure, the file format, or something else entirely.

This is a real cost. Not a dealbreaker, but a real cost, and one that compounds. Every cryptic error is an hour of debugging that a better message would have made five minutes. When you're building alone at 3 AM and you've been staring at the same error for three hours, "invalid result" starts to feel personal.

I'm writing this down because the Midnight team is actively building, they read what builders publish, and error message quality is a low-effort, high-leverage improvement. The underlying architecture is sound. The ZK primitives are genuinely interesting. But right now, the gap between "this works in CLI" and "this works in a user-facing browser app" is navigated almost entirely by developer pain, and it doesn't have to be.

If this post exists in the Midnight documentation six months from now as a reference for the migration path, that's a good outcome. The patterns above are correct. The architecture works. The error messages that led me to those patterns were not helpful, and I'd rather name that honestly than wrap this up with a cheerful "but overall it was worth it!"

It was worth it. The honest version of that statement includes everything above.

Tushar Pamnani — building at Sevryn Labs. Find me on X or GitHub. Writing about Midnight at dev.to/tusharpamnani.

If you're starting your Midnight journey and want to skip some of these walls, reach out. The repos are open.

Mathematically Prohibiting 'Cheating' in On-Chain RPS: A Midnight ZK dApp Case Study

Haruki Kondo — Sun, 03 May 2026 23:31:12 +0000

Introduction

Implementing Rock-Paper-Scissors (RPS) on-chain is surprisingly tricky.

The moment you choose "Rock" and send a transaction, your opponent can read your move from the public ledger. The game is over before it even starts.

I tried implementing a commit-reveal pattern manually, but managing salts, preventing front-running, and ensuring fair judging logic... it quickly became a rabbit hole.

That's when I turned to Midnight. I built a full-stack RPS dApp where "cheating" (looking at the opponent's move before playing) is mathematically impossible!

In this article, I'll share the ZK circuit design using Midnight's smart contract language, Compact, and the hurdles I faced during development.

Note
What ZK protects: The ZK proof ensures "confidentiality of the move during the commit phase" (fairness). After the reveal, both moves are recorded on the public ledger.

Here is what the dApp looks like:

What You'll Learn

Designing the "Hidden" vs. "Visible" split in Midnight.
Mastering the commit-reveal pattern with the Compact language.
Frontend UX strategies for handling ZK proof generation time (the 10-second hurdle).
Robust provider configuration with the Midnight JS SDK.

Repository

You can find the full source code here:

mashharuki / midnight-rps-sample-app

Midnight RPS sample dApp

midnight-rps-sample-app

Midnight RPS sample dApp

Overview

midnight-rps-sample-app is a sample Rock-Paper-Scissors dApp project built on Midnight, a privacy-focused blockchain.

Key Features

Fair Gameplay via Zero-Knowledge Proofs (ZK Proofs)
The app utilizes a "commit/reveal" scheme powered by Compact smart contracts. Players commit to their move (Rock, Paper, or Scissors) by submitting a hashed value. Once all players have committed, the moves are revealed. This ensures a tamper-proof gaming experience where "sniping" or reacting to an opponent's move is impossible.
Powered by the Midnight Blockchain
Contracts are deployed on the Midnight PreProd testnet, with all transactions recorded on-chain.
Full-Stack Architecture

Package Role

pkgs/contract Smart contracts written in the Compact language

pkgs/cli CLI tools for contract deployment and interaction

pkgs/app Frontend UI built with React + Vite
Lace Wallet Integration
Connects with Lace Wallet via the @midnight-ntwrk/dapp-connector-api for secure signing and transaction processing.

Package	Role
`pkgs/contract`	Smart contracts written in the Compact language
`pkgs/cli`	CLI tools for contract deployment and interaction
`pkgs/app`	Frontend UI built with React + Vite

Game Flow

Commit Phase — Each player commits their move…

View on GitHub

Quick Start

Here are the steps to get the app running locally.

To be honest, it takes about 15-20 minutes including ZK circuit compilation and the initial Docker image pull. Get your coffee ready!

Environment

Tested with the following:

Docker version 27.4.0
compact 0.2.0
bun 1.3.13
node 23.3.0

Install Lace Wallet to your browser

If you have not yet installed Lace Wallet, you must go to below page & need to install Lace Wallet

Lace | The light wallet platform to explore Web3

Discover the new light wallet platform from Input Output Global. Manage digital assets, and access NFTs, DApps, and DeFi services. Start your Web3 journey.

lace.io

Next, you need to create wallet account of Midnight

Please switch to PreProd Network

0. Clone the Repository

git clone https://github.com/mashharuki/midnight-rps-sample-app.git

1. Install Dependencies

bun install

2. Compile and Build Contracts

# Generate ZK circuit assets (This takes the most time)
bun contract compact  

# Build CLI and Frontend
bun cli build
bun app build

The bun contract compact step is where the Compact compiler generates the ZK proving and verification keys.

3. Start the Proof Server (Initial Pull: ~3 mins)

We need to run the server that handles ZK proof generation via Docker.

Without this server, you won't be able to deploy contracts or send commit/reveal transactions.

Version 8.0.3 is verified with Compact 0.2.0.
Ensure your SDK and Proof Server versions match, or proof generation will fail.

docker run -d -p 127.0.0.1:6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server

4. Deploy Contract to PreProd Network

If you don't have testnet NIGHT Token, you can get some token from below site.

https://faucet.preprod.midnight.network/

bun cli preprod-pts

If you deploy successfull, contract address shows like below.

[19:24:25.997] INFO (40223): Deploying RPS contract...
  ⠇ Deploying RPS contract[19:24:51.416] INFO (40223): Deployed RPS contract at: 23149945fed06aa010cc3e48e9f5df91625567300fae4e09371bb788d07a6bd8
  ✓ Deploying RPS contract
  Contract deployed at: 23149945fed06aa010cc3e48e9f5df91625567300fae4e09371bb788d07a6bd8

The Essence of Midnight Architecture: "Localizing" Information

Developing with Midnight requires a different mindset compared to Solidity.

As mentioned in my previous articles, Midnight has two types of states:

Public State: Visible to everyone (on-chain ledger).
Private State: Visible only to you (local storage).

The Compact ZK circuits act as the bridge between these two.

App Architecture

Code Deep Dive: Mathematically Preventing Cheating

1. Security Core: Domain Separation

When deriving a public key from a secret key, Midnight recommends using domain separation:

pure circuit derive_pk(sk: Bytes<32>): Bytes<32> {
  // Domain separation with a fixed string "rps:pk:v1"
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "rps:pk:v1"), sk]);
}

If you use the secret key as-is, using the same key in another app would result in the same public key, risking data leakage. By adding a prefix like "app name + version", we ensure that the public keys derived from the same secret key are unique to each app.

2. The Commit-Reveal Circuits

Commit Phase (Declaring a move while keeping it hidden)

export circuit commit(): [] {
  assert(!game_over,                 "Game is already over");
  assert(state == GameState.waiting, "Not in waiting state");

  const sk         = local_secret_key(); // witness: private input
  const pk         = derive_pk(sk);
  const my_move    = get_my_move();
  const my_salt    = get_my_salt();
  const commitment = make_commit(my_move, my_salt);
  store_move_and_salt(my_move, my_salt); // ⭐ Save move and salt to private state

  if (!p1_joined) {
    p1_key    = disclose(pk);
    p1_commit = disclose(commitment);
    p1_joined = true;
  } else {
    assert(!p2_joined, "Both players already committed");
    p2_key    = disclose(pk);
    p2_commit = disclose(commitment);
    p2_joined = true;
    state     = GameState.committed; // Transition to 'committed' when both joined
  }
}

Pay close attention to store_move_and_salt.

This is a witness function that saves the selected move and salt to the browser's IndexedDB (private state). To prove that the move revealed later is the same one committed earlier, this step is absolutely necessary.

The use of disclose() is also critical. It allows developers to explicitly control which results of private computations are written to the public ledger.

Game State Transitions

The coordination between commit and reveal phases is managed by these states:

3. Reveal Phase: Where ZK Proofs Shine

If the commit is the "declaration," the reveal is the "proof."

This is where Midnight's ZK stack really pays off.

export circuit reveal(): [] {
  assert(!game_over,                   "Game is already over");
  assert(state == GameState.committed, "Not in committed state");

  const sk      = local_secret_key();
  const pk      = derive_pk(sk);
  const my_move = get_my_move();   // Restore from private state
  const my_salt = get_my_salt();   // Restore from private state
  const computed = make_commit(my_move, my_salt);

  const is_p1 = disclose(p1_key == pk);
  const is_p2 = disclose(p2_key == pk);
  assert(is_p1 || is_p2, "Caller is not a registered player");

  if (is_p1) {
    assert(!p1_revealed, "Player 1 already revealed");
    assert(disclose(computed == p1_commit), "Commitment mismatch for P1");
    p1_move     = disclose(my_move); // Move is written to ledger only now
    p1_revealed = true;
  }
  if (is_p2) {
    assert(!p2_revealed, "Player 2 already revealed");
    assert(disclose(computed == p2_commit), "Commitment mismatch for P2");
    p2_move     = disclose(my_move);
    p2_revealed = true;
  }

  if (disclose(p1_revealed && p2_revealed)) {
    result    = who_wins(p1_move, p2_move); // Judge winner
    game_over = true;
    state     = GameState.finished;
  }
}

The line assert(disclose(computed == p1_commit), "Commitment mismatch for P1") is the heart of the logic:

my_move and my_salt exist only in your local private state.
make_commit(my_move, my_salt) is re-calculated, and the ZK circuit verifies it matches the p1_commit recorded on-chain during the commit phase.
You mathematically prove that "this move is the one I committed to" without revealing the move itself until the proof is valid.

Once the reveal is successful, p1_move and p2_move are finally written on-chain, and who_wins() determines the outcome.

During the commit phase, your move is hidden by ZK and remains unknown to the opponent until it is revealed. This is the mechanism that "mathematically prohibits cheating."

Overcoming the ZK dApp UX Hurdle

The biggest challenge during implementation was handling the "ZK proof generation time."

Filling the 10-Second Silence

In Midnight, before sending a transaction, you must generate a proof on your machine (or the Proof Server). This takes about 5-10 seconds.

UX improvements are essential to prevent users from thinking the app has frozen:

Optimistic UI Updates: Switch the UI state to "Generating Proof..." as soon as the process starts to communicate clearly what is happening.
Persistent Providers: Use levelPrivateStateProvider to ensure that even if the user reloads the browser during proof generation, the generated data and chosen moves are not lost.

// Example levelPrivateStateProvider configuration
privateStateProvider: levelPrivateStateProvider({ 
  accountId, 
  namespace: "rpsPrivateState", // Separate namespace for each game
  privateStoragePasswordProvider: () => storagePassword // Secure storage
}),

Sequence: From Commit to Game End

Let's recap the full flow:

Remaining Challenges

There's still a lot to learn by building with Midnight and Compact. Here are some issues I'm still working on:

1. The Abandonment Problem (Griefing Attack)

If Player 1 commits and Player 2 never joins, the contract stays locked. I need to implement a timeout/cancel mechanism in a future update.

2. Version Management of Build Assets

ZK circuit assets (proving keys) generated by bun contract compact can become invalid with even minor updates to the Compact version or compiler.

I actually ran into this during development. If you're building a similar app, double-check your library and Proof Server versions!

Solving these two will open up even more possibilities for ZK dApps on Midnight.

Conclusion

Implementing this "fair" RPS app taught me three key lessons:

Verify Versions: Proof generation can fail due to mismatched Proof Server versions.
Don't Forget store_move_and_salt: Saving private state is mandatory for the reveal phase.
UX is Priority #1: Designing a UI that handles the unique "waiting time" of ZK is critical.

Next, I'm planning to tackle multi-round support and timeout handling!

If you're interested in Midnight's privacy tech, check out the repository and my other technical blogs!

Thanks for reading!

Follow me on X!

x.com

References

Your Data Isn't Private. You Just Haven't Put It On-Chain Yet

Tushar Pamnani — Sun, 03 May 2026 13:41:20 +0000

There's a dangerous assumption most developers bring into Compact:

"It's a privacy-first chain. My data is private unless I explicitly expose it."

This is backwards. And it's where the serious mistakes happen.

The actual model

Compact doesn't give you automatic privacy. It gives you a hard boundary between two worlds, and a compiler that enforces it.

World	Where	Who sees it
Public	On-chain, every network node	Everyone
Private	Your local machine	Only you

The boundary between them is explicit. You cross it deliberately, with a specific annotation, or you don't cross it at all. The compiler guarantees this. You cannot accidentally move private data into public state, it's a compile error, not a runtime surprise.

But here's what trips people up: the guarantee goes one direction. The compiler stops private data from leaking into public state. It does not prevent you from intentionally putting sensitive data on-chain by slapping it in export ledger and calling it a day. That's your problem to reason about.

`export ledger` means public. Completely.

This is the rule that doesn't have exceptions:

export ledger balance: Uint<64>;
export ledger owner: Bytes<32>;
export ledger totalSupply: Counter;

Every field you declare with export ledger is stored on every network node in plaintext. Your dApp can read it. So can every other dApp, every indexer, every curious person running a node. There's no visibility modifier that makes it "semi-public" or "only readable by the contract." It's public.

Most developers understand this in the abstract. Where it breaks down in practice is with per-user data. The classic mistake: storing individual user balances in export ledger. That's a privacy violation, not a compiler error, not a proof failure, just a design error that quietly exposes data you probably meant to protect.

The heuristic: If removing a ledger field would break another user's ability to interact with the contract, it belongs on-chain. If only one user cares about the value, it almost certainly shouldn't be.

Where private data actually lives

Private data comes in through witnesses, callback functions declared in Compact, implemented in your TypeScript dApp, and executed locally on the user's device:

witness getBalance(): Uint<64>;
witness secretKey(): Bytes<32>;
witness userNonce(): Field;

When a circuit calls a witness, the value it returns never touches the chain. Not even as an encrypted blob. The chain sees a ZK proof that the circuit ran correctly given some private inputs. The inputs themselves stay local.

This is what makes Compact's privacy model different from Solidity's private keyword. In Solidity, private is a visibility modifier, the data is still on-chain, just not directly accessible from other contracts. In Compact, witness data is structurally off-chain. It can't go on-chain, because there's no mechanism to put it there. The proof proves the computation; the input stays local.

`disclose()` is not what you think it is

At some point you'll need to move something from private to public, store a commitment, record a result, update global state. That's what disclose() is for.

export circuit record(): [] {
  balance = disclose(getBalance());
}

Here's what disclose() is not:

It's not encryption. The value is not transformed.
It's not a runtime operation. There's no cost.
It's not a permission check. It doesn't verify you're allowed to do this.

It's a compile-time annotation. You're telling the compiler: "I know this value is private, and I am intentionally making it public." The compiler records the declaration and permits the data flow. Without it, witness data trying to reach the ledger is a compile error.

The implication: everything after disclose() is public. The value you disclose will be visible on-chain as plaintext. Disclose it only if that's what you actually want.

The compiler tracks the boundary, everywhere.

What makes this model powerful is that the compiler doesn't just check assignment statements. It tracks witness data through every operation: arithmetic, type conversions, struct construction, helper circuits.

circuit obfuscate(x: Field): Field {
  return x + 73;
}

export circuit record(): [] {
  const s = getBalance() as Field;
  const x = obfuscate(s);
  balance = x as Bytes<32>;  // compiler error
}

Passing witness data through x + 73 doesn't make it non-private. The compiler knows the output depends on the private input, so it's still tainted. You need disclose() at the boundary, not buried in the middle of the computation.

This also means comparison results count:

// compiler error: result reveals information about witness data
export circuit balanceExceeds(n: Uint<64>): Boolean {
  return getBalance() > n;
}

// correct: explicitly declared
export circuit balanceExceeds(n: Uint<64>): Boolean {
  return disclose(getBalance()) > n;
}

Even a boolean that's derived from private data is a disclosure. The compiler catches it.

When you need to prove something about private data without revealing it

This is where the commitment pattern comes in. It solves a specific problem: you need to demonstrate that a private value exists and hasn't changed, without putting the value on-chain.

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

export circuit commitBalance(value: Uint<64>): [] {
  const nonce = freshNonce();
  const commitment = persistentCommit<Uint<64>>(value, nonce);
  balanceCommitments.insert(
    disclose(callerAddress()),
    disclose(commitment)
  );
}

What goes on-chain: the commitment (a hash with a random nonce). What stays local: the actual balance. A later circuit can prove the balance meets some condition — exceeds a threshold, is non-negative, without revealing the number. The commitment on-chain proves the private value was committed to and hasn't changed.

The nonce is critical. Two commitments with the same nonce and same value are identical on-chain — anyone watching can correlate them. Always use a fresh nonce.

The design shift this requires

Once this model clicks, you stop designing contracts around functions and start designing them around data residency.

Before: "What should this circuit do?"

After: "Where does this data live? What needs to be provable publicly? What must never leave the user's device?"

These questions affect everything downstream: what goes in export ledger, what stays in witnesses, where commitments make sense, which circuits need disclose() and which don't. Get the data residency wrong at the design stage and you'll either have a privacy leak or a system that can't verify what it needs to verify.

Most bugs in Compact contracts aren't logic errors. They're boundary errors, data ending up in the wrong world, or a contract that can't prove what it needs to because the private data that would make the proof possible was never accessible in the right form.

The one question to ask before writing any ledger field

If this value were visible to every person on the internet, would that be a problem?

If yes: it belongs in witnesses, not in export ledger. Use the commitment pattern if you need public provability without public visibility.

If no: export ledger is the right place.

Ledger State and Explicit Disclosure chapters cover this in full

The Compact Book walks through the commitment pattern with working examples, the full disclose() rules including the standard library exceptions (transientCommit is a special case), and how the compiler error traces tell you exactly where a boundary violation occurred.

→ Compact Book

Post #4 covers witnesses in depth, specifically why witness results are untrusted inputs, and what "the proof proves correct logic, not sensible inputs" means for how you write validation. That one has teeth.

Compact vs Solidity: Limitations and Advantages

Neeraj Choubisa — Sat, 02 May 2026 08:49:51 +0000

Compact vs Solidity: Limitations and Advantages

The emergence of privacy focused blockchain systems has introduced a new way of writing smart contracts. Compact is one such language designed for Midnight, a network that prioritizes confidential computation using zero knowledge proofs. Developers who are familiar with Solidity will notice that Compact is not just a new syntax but a fundamentally different model of building applications.

This article explains the core limitations of Compact when compared to Solidity, and more importantly, the advantages that make it a powerful choice for a new class of applications.

Understanding the Core Difference

Solidity operates in a fully transparent environment where every transaction, state change, and computation is visible on chain. This transparency enables composability and interoperability across decentralized applications.

Compact is built around a different principle. It enables computation on private data where the correctness of execution is proven without revealing the underlying inputs. Instead of relying entirely on on chain execution, Compact uses off chain computation combined with verifiable proofs.

This shift changes how developers design systems.

Limitations of Compact Compared to Solidity

Lack of On Chain Contract Deployment

In Solidity, contracts can deploy other contracts dynamically. This capability enables factory patterns and permissionless systems where users can create new contracts directly from existing ones.

Compact does not support deploying contracts from within a contract. All deployments must be handled off chain through scripts or backend services. This limitation directly affects architectures such as token launchpads and factory based protocols.

Reduced Composability

One of the biggest strengths of Solidity is composability. Contracts can interact with each other freely, forming complex systems like decentralized exchanges, lending protocols, and aggregators.

Compact restricts this level of interaction. Since execution is tied to proof generation and deterministic circuits, arbitrary contract calls are limited. This makes it harder to build interconnected systems in the same way as traditional DeFi.

Constraints on Dynamic Logic

Solidity allows flexible execution patterns including dynamic loops, runtime conditions, and complex state transitions.

Compact requires logic to be deterministic and efficient for proof generation. Large or unpredictable computations increase proving cost and complexity. Developers must carefully design circuits to remain efficient.

Higher Learning Curve

Writing Solidity contracts is primarily about understanding blockchain state and execution.

Compact introduces additional layers such as circuit design, proof efficiency, and privacy preserving logic. Developers must think about how data flows through proofs rather than just how it executes on chain.

Immature Tooling Ecosystem

Solidity benefits from a mature ecosystem including frameworks, testing tools, debugging environments, and extensive documentation.

Compact is still evolving. Tooling, libraries, and community support are comparatively limited, which can slow down development.

Different Approach to Identity and Permissions

In Solidity, concepts like msg.sender provide a straightforward way to handle identity and permissions.

Compact handles identity in a privacy preserving manner, which introduces additional complexity in designing access control mechanisms.

Advantages of Compact Over Solidity

Native Privacy

The most important advantage of Compact is built in privacy. Solidity exposes all data publicly, which limits its use in applications involving sensitive information.

Compact allows data to remain encrypted while still enabling computation. Only proofs of correctness are revealed, not the underlying data.

This enables entirely new categories of applications that cannot exist on transparent blockchains.

Computation on Encrypted Data

Compact enables computations to be performed on encrypted inputs. This is a significant advancement compared to traditional smart contract platforms.

Applications can process financial data, identity information, or proprietary algorithms without exposing them publicly. This opens possibilities in areas such as private finance and secure data processing.

Selective Disclosure

Compact allows developers to reveal only the information that is necessary.

For example, a user can prove they meet a condition without revealing the actual value behind it. This is useful in scenarios like credit scoring, voting systems, and compliance checks.

Stronger Security Model

The deterministic nature of Compact execution reduces several classes of vulnerabilities that exist in Solidity.

Since execution is tied to proofs and predefined circuits, there are fewer unexpected behaviors. This leads to more predictable and secure systems.

Better Suitability for Sensitive Applications

Compact is particularly well suited for applications where privacy is essential. These include private trading systems, confidential auctions, identity verification platforms, and secure data marketplaces.

Such applications are difficult or impossible to build safely using Solidity due to its transparent nature.

Alignment with Future Technologies

As artificial intelligence and data driven systems grow, privacy becomes increasingly important. Compact aligns well with this future by enabling secure computation over sensitive datasets.

It provides a foundation for integrating blockchain with privacy preserving AI and data infrastructure.

Solidity and Compact as Complementary Systems

It is important to understand that Compact and Solidity are not direct replacements for each other. They are designed for different purposes.

Solidity excels in open and composable environments where transparency is beneficial. Compact excels in environments where privacy and confidentiality are critical.

A future architecture may involve both. Solidity based systems can handle public coordination and liquidity, while Compact based systems manage private computation and sensitive logic.

Conclusion

Compact introduces a new paradigm in smart contract development. While it comes with limitations such as restricted composability and lack of on chain deployment, it provides powerful capabilities that are not possible in traditional blockchain environments.

Solidity laid the foundation for decentralized applications by enabling transparent and composable systems. Compact extends this vision by introducing privacy and verifiable computation.

As the blockchain ecosystem evolves, both approaches will play important roles in shaping the next generation of decentralized technology.

Building on Midnight with Windows — A Real Developer's WSL2 Setup Guide

Gutopro — Wed, 29 Apr 2026 23:30:33 +0000

If you're on Windows and you want to build on Midnight, the first thing you need to know is that Midnight's toolchain — the Compact compiler, proof server, and the rest — are Linux binaries. They won't run natively on Windows. Full stop.

That doesn't mean you're locked out. Windows has a feature called WSL2 — Windows Subsystem for Linux — that gives you a real Linux environment running inside Windows. Once it's set up you get a proper Ubuntu terminal, access to all the Linux dev tools you need, and a stable foundation for Midnight development.

I set up my entire Midnight development environment on WSL2. This guide documents exactly what I did — including the parts that aren't obvious and the parts that caught me off guard.

Step 1: Enable WSL2

Microsoft has official documentation for enabling WSL2. Follow that guide to get WSL installed on your machine before continuing here.

👉 Enable WSL2 on Windows — Official Microsoft Guide

Come back here once WSL is enabled and you have Ubuntu running.

Step 2: Download Ubuntu from the Microsoft Store

Open the Microsoft Store and search for Ubuntu. Select Ubuntu 24.04 LTS and click Get.

Once it installs, launch it from the Start menu. The first launch will ask you to create a Linux username and password.

Note:
When you type your password nothing shows on screen. That's intentional — Linux hides password input by default. Just type it and press Enter.

Verify WSL2 is active by opening PowerShell and running:

# Windows PowerShell
wsl --list --verbose

You should see Ubuntu listed with Version 2. If it shows Version 1, set WSL2 as the default with:

# Windows PowerShell
wsl --set-default-version 2

Step 3: Configure WSL2 Memory — Don't Skip This

This is the step I wish someone had told me about before I started.

By default WSL2 only gets 1GB of memory. The Midnight proof server needs at least 4GB to generate ZK proofs without crashing. If you skip this configuration your proof server will run but fail silently or crash mid-proof with no obvious error message. I learned this the hard way.

Create a .wslconfig file in your Windows user directory. Open PowerShell and run:

# Windows PowerShell
notepad "$env:USERPROFILE\.wslconfig"

Add this configuration:

# .wslconfig
[wsl2]
memory=8GB
processors=4
swap=3GB
localhostForwarding=true

If your machine has less than 16GB RAM adjust accordingly. The minimum that works reliably for Midnight development is memory=4GB.

Setting	Minimum	Recommended
memory	4GB	8GB
processors	2	4
swap	1GB	3GB
localhostForwarding	true	true

Save the file then restart WSL:

# Windows PowerShell
wsl --shutdown

Reopen Ubuntu from the Start menu.

Step 4: Install curl

Start with the fundamentals. curl is needed to download everything else.

# WSL Ubuntu terminal
sudo apt update
sudo apt install -y curl

Step 5: Install Git

You'll need git for version control and cloning repositories.

# WSL Ubuntu terminal
sudo apt install -y git

Step 6: Install Node.js 22

Midnight requires Node.js 22 or higher. Install it using nvm — don't use a Windows-native Node.js installation, as version conflicts will cause problems down the line.

# WSL Ubuntu terminal
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version

Note:
zsh users: Replace ~/.bashrc with ~/.zshrc in the commands above.

Note:
Why pin to 22? create-mn-app and the Midnight SDK have been validated against Node.js 22. Using a newer major version may work, but you could encounter unexpected compatibility issues. Check the Midnight documentation for the latest supported range

Note:
nvm version: The installer URL above pins nvm to v0.40.3. Check the nvm releases page before running to confirm it's still the latest stable version and update the URL if needed.

Verify the installation before moving on:

node --version   # should print v22.x.x
npm --version

Step 7: Install Docker Engine

The Midnight proof server runs as a Docker container. You need Docker Engine installed inside WSL — not Docker Desktop.

Set up Docker's apt repository:

# WSL Ubuntu terminal
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Install Docker packages:

# WSL Ubuntu terminal
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group so you can run Docker without sudo:

# WSL Ubuntu terminal
sudo usermod -aG docker $USER
newgrp docker

Start the Docker daemon:

# WSL Ubuntu terminal
sudo service docker start

Verify Docker works:

# WSL Ubuntu terminal
docker run hello-world

Step 8: Install the Compact Toolchain

# WSL Ubuntu terminal
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

Add to PATH:

# WSL Ubuntu terminal
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Note:
zsh users: Replace ~/.bashrc with ~/.zshrc.

Verify:

# WSL Ubuntu terminal
compact --version

Step 9: Scaffold Your Project with create-mn-app

This is where things get streamlined. The Midnight team ships create-mn-app — a scaffolding tool that sets up your entire project structure including wallet scripts, contract source, compilation config, and deployment tooling.

# WSL Ubuntu terminal
npx create-mn-app my-app
cd my-app
npm run setup

npm run setup will:

Compile your Compact smart contract
Check your Node.js, Docker, and Compact compiler versions for compatibility
Start the proof server via Docker Compose
Guide you interactively through wallet creation or restoration

Wallet creation is interactive. When npm run deploy runs as part of setup, it will prompt you to either create a new wallet or restore from an existing seed. If you're starting fresh, choose option 1. Your seed will be saved to .midnight-seed (chmod 600) — back it up and never commit this file.

Note:
Version mismatch: create-mn-app checks that your @midnight-ntwrk/compact-runtime version in package.json matches your installed compiler version. A mismatch causes a CompactError on compilation. If setup flags it, let it fix it automatically.

Once setup completes, your wallet address is printed to the terminal. Copy it and head to the faucet to get tNight tokens.

If you want a more complete starting point, the Counter DApp template gives you a real increment/decrement contract with ZK proofs already wired up:

# WSL Ubuntu terminal
npx create-mn-app my-app --template counter
cd my-app
npm run setup

Step 10: Get tNight from the Faucet

Every transaction on Midnight costs DUST as gas — and DUST is generated automatically once your wallet holds tNight. Your wallet address was printed during npm run setup.

Visit the preprod faucet
Paste your wallet address
Request tokens and wait ~2–5 minutes

Note:
Important: Always verify your wallet is configured for the preprod network before copying your address. The preprod faucet only recognizes addresses registered on preprod — submitting an address from a differently-configured wallet will return an invalid address error.

Note:
DUST balance: DUST accumulates over time based on the tNight in your wallet. If you attempt deployment immediately after funding and see a "Not enough DUST" error, wait a few minutes and retry with npm run deploy.

What Doesn't Work

Save yourself the debugging time — these approaches don't work:

Approach	Why it fails
Running Compact compiler in PowerShell or CMD	Linux binary — requires WSL
Running proof server natively on Windows	Linux binary — requires WSL
Using Windows-native Node.js for Midnight projects	Version and path conflicts
Keeping projects in `/mnt/c/`	Severely degraded file I/O performance
Submitting a mainnet-configured wallet address to preprod faucet	Address not registered on preprod

Troubleshooting

Proof server crashes or produces no output — Almost always a memory issue. Increase memory in .wslconfig to at least 4GB, run wsl --shutdown, restart WSL.

Docker not found — Run sudo service docker start. If that fails, verify Docker is installed with docker --version.

compact not found — Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc and run source ~/.bashrc.

Port 6300 not accessible — Add localhostForwarding=true to .wslconfig and restart WSL with wsl --shutdown.

Slow file operations — Move your project out of /mnt/c/ into your Linux home directory at ~/. The performance difference is significant.

CompactError: Version mismatch — Your compiler version and compact-runtime npm package version don't match. create-mn-app will flag this during setup and offer to fix it. If you hit it mid-project, update package.json to the matching runtime version and run npm install.

"Not enough DUST" during deployment — Your wallet is new and DUST hasn't accumulated yet. Wait a few minutes and run npm run deploy again. The deploy script retries automatically up to 8 times with a delay between attempts.

Next Steps

Your environment is ready. Run create-mn-app and let it scaffold your first project. The hello-world template compiles and deploys in minutes. Watch your transaction appear on chain in 1AM Explorer — that's your proof it's working.

If you hit issues not covered here, find me in the Midnight Discord as Guto — I've been through most of them already.

Vibe Code Your First Midnight dApp with AI Agent Skills

M Zidan Fatonie — Wed, 29 Apr 2026 16:24:48 +0000

Your AI coding assistant doesn't know Compact. It knows TypeScript, Solidity, Rust, but Midnight's ZK smart contract language didn't exist when most models were trained. Ask it to write a Compact contract and you'll get plausible-looking code that won't compile.

midnight_agent_skills is a set of 4 agent skills that fix this. Install them once, and your AI assistant has accurate knowledge of Compact syntax, the Midnight SDK, network config, and the gotchas that trip up real builders.

This is a walkthrough of using those skills to build your first Midnight dApp.

What are agent skills?

Agent skills are structured knowledge files that AI coding assistants load at context time. Instead of relying on training data, the assistant reads the skill files directly, so it gets accurate, current information rather than hallucinated guesses.

The midnight_agent_skills package has 4 skills:

midnight-concepts: ZK architecture, DUST/NIGHT tokenomics, Kachina protocol
midnight-compact: Compact language, circuits, ledger operations, best practices
midnight-api: SDK integration, wallet connection, contract deployment
midnight-network: Node setup, Docker, indexer, proof server

Step 1: Install the skills

npx skills add https://github.com/mzf11125/midnight_agent_skills

Or pick individual skills:

npx skills add https://github.com/mzf11125/midnight_agent_skills --skill midnight-compact
npx skills add https://github.com/mzf11125/midnight_agent_skills --skill midnight-api

Step 2: Start the proof server

Midnight generates ZK proofs client-side, your data stays on your machine. You need a local proof server running before you can deploy anything.

docker run -p 6300:6300 midnightnetwork/proof-server -- \
  'midnight-proof-server --network preprod'

Check it's up:

curl http://localhost:6300
# We're alive 🎉!

Step 3: Scaffold your project

npx create-midnight-app my-first-dapp
cd my-first-dapp

Step 4: Write your contract

Open your AI assistant and ask it to write a Midnight contract. With the skills loaded, it knows the correct syntax.

Here's a simple owner-gated counter, only the deployer can increment it:

pragma language_version >= 0.20;
import CompactStandardLibrary;

export ledger counter: Counter;
export ledger owner: Bytes<32>;

witness local_secret_key(): Bytes<32>;

export circuit initialize(): [] {
  const pk = publicKey(local_secret_key()).bytes;
  owner.write(disclose(pk));
}

export circuit increment(): [] {
  const caller = publicKey(local_secret_key()).bytes;
  assert(disclose(caller) == owner.read(), "Not authorized");
  counter.increment(1);
}

Things the skills teach your AI that it wouldn't otherwise know:

export circuit not function, circuits declare constraints, they don't execute
disclose() is required when moving witness data to the public ledger, the compiler rejects code without it
Counter uses .increment() and .read(), not .value()
No recursion, no unbounded loops, circuits must compile to a fixed-size constraint system

Step 5: Compile

compact build src/counter.compact src/managed/counter

Success looks like:

Fetching public parameters for k=10 [====================] 192.38 KiB
  circuit "increment" (k=10, rows=29)
Overall progress [====================] 1/1

Step 6: Deploy

With the midnight-api skill loaded, your AI generates the correct facade 4.x pattern:

import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
import { CounterContract } from './managed/counter/contract/index.js';

// facade 4.x, the old WalletFacade.init() hangs silently on standalone nodes
const wallet = new WalletFacade(shielded, unshielded, dust);
await wallet.start();

const contract = new CounterContract();
const deployed = await contract.deploy(providers, { privateCounter: 0 });
console.log('Deployed at:', deployed.deployTxData.public.contractAddress);

The skills include the SDK compatibility matrix. Your AI knows that wallet-sdk-facade@2.x uses WalletFacade.init() which hangs silently on standalone nodes, and that 4.x switched to new WalletFacade(...) + .start().

Step 7: Run a pre-flight check

Before you spend hours debugging, run:

npx midnight-doctor

It reads your package.json, running Docker containers, and config files, then cross-references them against a known compatibility matrix. The midnight-api skill documents the most common silent failures:

Symptom	Root cause
`waitForSyncedState()` hangs forever	facade 2.x + standalone node mismatch
Transactions silently fail	Duplicate `@midnight-ntwrk/ledger-v7` in node_modules
Indexer crash-loops	Missing `subscription:` block in `indexer.yml`

What the skills know that your AI doesn't

The skills pull from the official Midnight docs plus 19 community articles from the Midnight Aliit Fellowship, builders documenting real production failures.

Mental model shifts:

Circuits declare constraints, they don't execute. assert is a constraint declaration, not a runtime guard, if the condition is false, the proof can't be generated.
disclose() is a compile-time annotation, not encryption. The compiler tracks witness data through arithmetic and rejects undeclared disclosures.
Block limits are hard limits, not gas costs. BlockLimitExceeded means your transaction can't execute at all.

On-chain design patterns:

Flat maps over struct maps, reading a struct pulls every field into the circuit
Off-chain computation + Merkle root, the chain verifies, it doesn't compute
Minimal on-chain state, only what the chain needs to enforce

Common syntax gotchas:

counter.read() not counter.value()
Enum access uses . not ::, GameState.playing not GameState::playing
Witness functions have no body, declaration only
return inside for loops is not allowed, use fold

Install and start building

npx skills add https://github.com/mzf11125/midnight_agent_skills

The skills are open source. If you hit a pattern that's missing, PRs are open.

Repo: https://github.com/mzf11125/midnight_agent_skills

Circuits Are Not Functions. That Confusion Will Break You

Tushar Pamnani — Tue, 28 Apr 2026 08:53:14 +0000

The last post in this series covered the surface illusion: Compact looks like TypeScript, but it isn't. Same syntax, completely different model.

This post goes one level deeper. Into the most specific version of that mistake, the one that actually stalls people in the middle of building something.

"A circuit is just a function."

It isn't. And the gap between those two things is where most of the confusion lives.

Why the confusion is so sticky

The syntax is deliberately familiar:

export circuit transfer(amount: Uint<64>): [] {
  assert(balance >= amount, "Insufficient balance");
  balance = balance - amount;
}

You read this and your brain fires the usual pattern. Signature, body, assertions, state update. Looks like a function. Reads like a function. Must behave like one.

Here's what that assumption gets wrong: functions execute. Circuits constrain.

These are not the same thing. They're not even close.

The actual difference

A function describes a sequence of steps. You give it inputs, it runs through statements top to bottom, it produces an output. The machine does what you told it to do.

A circuit describes a set of relationships that must hold true. When you call it from your dApp, the proof system generates a zero-knowledge proof that those relationships were satisfied. What gets submitted on-chain isn't the result of running your code. It's a proof that the constraints were met.

Function:  Input → Execute steps → Output
Circuit:   Input → Declare constraints → Generate proof → Verify proof

There is no "execution" in the traditional sense. There's constraint satisfaction, proof generation, and verification.

What `return a + b` actually means in a circuit

In a function, return a + b says: compute the sum and hand it back.

In a circuit, return a + b says: the output is constrained to equal a + b. The proof proves this relationship held for the actual inputs, without revealing what those inputs were.

Same syntax. Completely different meaning.

This is why Compact works for private data at all. The proof system doesn't need to see your inputs to verify that your circuit's constraints were satisfied. It can confirm correctness without exposure. That's the point.

What `assert` actually is

In a function, assert is a runtime guard. It checks a condition and throws if it fails.

In a circuit, assert is a constraint declaration. It doesn't "throw", it defines a requirement that the proof must satisfy. If the condition is false, the proof can't be generated. There's no proof to submit. The transaction doesn't happen.

Every assert in your circuit is part of the constraint system. You're not checking inputs. You're specifying what valid inputs look like.

assert(balance >= amount, "Insufficient balance");

This doesn't say: check if balance is high enough, then continue.

It says: a proof for this circuit cannot exist if balance is less than amount.

That's a different tool. Use it differently.

Why the constraints exist (and why this isn't limiting)

Compact is deliberately bounded:

No recursion
No unbounded loops
Fixed type sizes at compile time
Immutable variable bindings

The first reaction is usually: these feel arbitrary.

They're causal. ZK proofs require finite circuits. A circuit is a fixed structure of gates and wires determined entirely at compile time. Unbounded computation can't become a circuit. If the compiler can't determine the full structure of your constraint system before runtime, there's nothing to prove.

The bounds aren't restrictions on what Compact can do. They're what makes proof generation possible at all.

This is also why return can't appear inside a for loop, and why variables can't be reassigned after binding. In a constraint system, reassignment is ambiguous. What does it mean to constrain a value that changes? It doesn't mean anything well-defined. So it's not allowed.

map and fold exist specifically for this. Transformation and accumulation without the ambiguity.

The debugging shift

This has a practical implication that catches people off guard: you can't debug circuits the way you debug functions.

With a function, you ask: what line failed? You add logging. You trace execution. You find where the state went wrong.

With a circuit, there's no execution to trace. You ask: which constraint is unsatisfied? You look at what relationships your circuit declares and figure out which one the proof can't satisfy given the actual inputs. Then you look at whether your witness is providing what the circuit expects.

Different question. Different process.

Most people hit this the hard way, they try to debug a constraint failure like a runtime error and get nowhere. The shift is: treat every failure as a constraint problem, not an execution problem.

Where this leads

Once this model is solid, the rest of Compact becomes consistent.

Witnesses are the private inputs the prover uses to generate the proof. They're not function arguments in the normal sense, they're the private side of the constraint system.

disclose() is the explicit act of moving a private constraint into public view. Not encryption. Not transmission. Just a compiler-enforced boundary that marks intentional exposure.

Ledger state is the public constraint, what everyone on-chain can see is asserted to be true.

Every concept in Compact is a piece of the same constraint model. Once you see it that way, the language is internally consistent. Before that, it seems to have arbitrary rules that don't connect.

The one sentence that changes how you read Compact

You are not writing code that runs. You are describing valid states and proving you were in them.

With that sentence as the frame:

export circuit transfer(amount: Uint<64>): [] {
  assert(balance >= amount, "Insufficient balance");
  balance = balance - amount;
}

...reads differently. You're not executing a transfer. You're describing what a valid transfer looks like and generating a proof that this one was valid. The on-chain state updates because the proof verified, not because code "ran."

The full circuits chapter is in the book

Mental models, examples, how map and fold replace return-in-loop patterns, how generics work, the full proof flow. It's structured to build the right frame first, then fill in the syntax.

→ Compact Book

Post #3 covers public vs. private state, the two-world model and what actually goes on-chain. That one connects directly to the mistakes people make once they've grasped circuits but haven't yet internalized where data lives.

Surviving Midnight SDK: a 700-line cure for the silent failure problem

Fred Santana — Mon, 27 Apr 2026 23:09:46 +0000

Why I built midnight-doctor — a pre-flight check that catches the 16 hours of debugging you don't know you're about to spend

"The information you need to align your stack already exists. It's just not executable."*

After five months building four applications on Midnight Network, I've concluded the protocol isn't the problem. The protocol is genuinely good — Compact compiles ZK circuits in three seconds without a trusted setup ceremony, and the shielded/unshielded/dust split is the cleanest answer to compliance-grade privacy I've seen.

The problem is everything that surrounds it. Specifically, the unforgiving math of: a fast-moving SDK + multiple environment tracks + a single npm namespace + zero error messages when versions misalign.

This post is the story of one specific 6-hour debugging session, the pattern I extracted from it, and the ~700-line tool I built so the next person doesn't pay the same tax.

The 6-hour silent failure

DPO2U Wallet, March 2026. I bumped @midnight-ntwrk/wallet-sdk-facade to 2.0.0 because npm marked it as latest. My local stack ran midnightntwrk/midnight-node:0.21.0 (preprod-targeted). I wrote ~50 lines of wallet bootstrap, started the dev loop, and watched:

const wallet = await WalletFacade.init({
  configuration,
  shielded,
  unshielded,
  dust,
});

await wallet.waitForSyncedState();
console.log('synced!');

The synced! line never printed.

No error. No timeout. No log. The wallet just sat in syncing state forever. I added more logging — got more "syncing" lines. Restarted Docker. Wiped state. Tried a fresh seed. Re-cloned the repo. Asked Discord. Read the SDK changelog (which didn't exist for that version). Stared at the indexer logs for 40 minutes.

Six hours in, almost by accident, I noticed the symptom: subscribeRuntimeVersion was firing once, returning, and never firing again. The standalone node closes that subscription early. The WalletFacade.init({...}) constructor in 2.x wires sync to that subscription. Result: a single missed event silently kills the entire sync loop, with zero surface.

The fix was to downgrade to facade 1.0.0 (preprod track). Forty seconds of work, after six hours of debugging. The bug was real but the cost was information asymmetry: nothing in the documentation, npm metadata, or runtime told me that "this SDK version is incompatible with this node version."

That asymmetry is the real bug. Not the runtime subscription closing. Not the constructor wiring. The fact that the system has the information needed to diagnose itself, but doesn't bother.

The pattern: silent failures from missing cross-references

After that session, I started cataloguing other times I'd been bitten the same way. Within a week I had a list:

Symptom	Root cause	Time spent
`waitForSyncedState()` hangs forever	facade 2.x + node 0.21.0 mismatch	~6h
`npm install` returns ENOTFOUND	community tutorial said `.npmrc` should point at `npm.midnight.network` (domain doesn't exist)	~2h
Transactions silently fail to submit	Two versions of `@midnight-ntwrk/ledger-v7` in `node_modules` (transitive bump)	~3h
Indexer crash-loops on startup	`indexer-standalone:4.0.0-rc.4` requires a `subscription:` block in `indexer.yml`, undocumented	~1.5h
WalletFacade behaves differently on standalone vs preprod	Same SDK, different node behavior, no warning	~4h

Across five incidents: ~16 hours of debugging silent failures. Each one had a root cause that was, with the right cross-reference, detectable in seconds:

package.json says facade is 2.0
docker ps says node is 0.21.0
A lookup table says those two are incompatible
→ Print a clear error.

The system already has all three pieces of data. There's just no glue.

The tool: `midnight-doctor`

The fix isn't a new feature in the SDK. It isn't better docs (which decay). It's an executable cross-reference — a script that reads your project, your Docker stack, and your config files; matches them against a curated compatibility table; and tells you what's wrong.

I built midnight-doctor over a weekend. ~700 lines of Node, zero runtime dependencies, single-binary install:

npx midnight-doctor

Run against my own legacy midnight-hello-world repo, it produces:

── midnight-doctor ──
project: /root/midnight-hello-world

⚠ SDK track: Preprod 3.x (legacy, OK for existing apps)
   Detected from wallet-sdk-facade@2.0.0.
⚠ Track is deprecated
   SDK 3.2 / facade 2.0 is 2 majors behind. Current is wallet-sdk@1.0.0 /
   facade@4.0.0 (released 2026-04-23). The WalletFacade.init({...}) constructor
   used in 2.0 has been removed; 4.0 reverted to `new WalletFacade(s, u, d) +
   .start()`. Plan a migration.
⚠ WalletFacade.init() in 2.x stalls on standalone dev nodes
   In SDK 2.x, WalletFacade.init() subscribes to runtime version events that the
   standalone node closes early. The wallet hangs in 'syncing' state forever
   with no error.
   → fix: Either (a) develop against preprod once past hello-world, or
     (b) upgrade to wallet-sdk-facade@4.0.0 which reverted to constructor +
     .start() pattern.
✓ node: midnightntwrk/midnight-node:0.21.0
✓ indexer: midnightntwrk/indexer-standalone:4.0.0-rc.4
✓ proof-server: midnightntwrk/proof-server:7.0.0
✓ midnight-node:0.21.0 matches SDK track

summary: 4 ok  3 warn  0 error  0 info
Status: workable, but warnings deserve a look.

The 6-hour incident from March is now a 30-second output.

Architecture

The tool is structurally trivial. Three scanners, one diagnosis engine, one report formatter. Total surface:

midnight-doctor/
├── bin/midnight-doctor.js   # CLI entry, arg parsing, exit codes
├── lib/
│   ├── scan-package.js      # reads package.json + walks node_modules
│   ├── scan-docker.js       # runs `docker ps`, parses image tags
│   ├── scan-config.js       # reads .npmrc, indexer.yml
│   ├── diagnose.js          # cross-references findings with matrix
│   ├── report.js            # ANSI-colored pretty output
│   └── index.js             # public API
├── data/compatibility-matrix.json   # the source of truth
└── test/diagnose.test.js    # node:test, no framework

The compatibility matrix is the product

The ~700 lines of code are scaffolding. The actual value is the JSON document at data/compatibility-matrix.json. It encodes three things:

Tracks — known-good combinations of SDK + Docker images, labeled (current, preprod-3x, preprod-1x)
Known issues — specific bugs keyed by package version range or config pattern
Cross-cutting checks — rules that fire when two scanners disagree (e.g., node tag vs SDK track)

A snippet:

{
  "tracks": {
    "current": {
      "label": "Current (latest npm + preprod compatible)",
      "node": "0.21.0",
      "indexer": "4.0.0-rc.4",
      "proofServer": "7.0.0",
      "packages": {
        "@midnight-ntwrk/wallet-sdk": "1.0.0",
        "@midnight-ntwrk/wallet-sdk-facade": "4.0.0",
        "@midnight-ntwrk/compact-runtime": "0.15.0",
        ...
      }
    }
  },
  "knownIssues": [
    {
      "id": "facade-2x-init-bug",
      "severity": "warn",
      "match": { "type": "package-version",
                 "package": "@midnight-ntwrk/wallet-sdk-facade",
                 "range": "2.x" },
      "title": "WalletFacade.init() in 2.x stalls on standalone dev nodes",
      "fix": "Either develop against preprod, or upgrade to facade 4.0.0..."
    }
  ]
}

This file is the same information that lives, scattered, across Discord pinned messages and individual developers' heads. Centralizing it in a JSON document accomplishes three things:

Source of truth — there's now a place to point people instead of "search the channel"
Versioned — the file has a verifiedAt: "2026-04-27" field; staleness is detectable
Executable — code can act on it; humans can read it

The scanners are deliberately dumb

Each scanner is one file, one responsibility, ~50 lines.

// lib/scan-docker.js (excerpt)
export async function scanDocker() {
  const findings = { dockerAvailable: false, containers: {} };
  try {
    await exec('docker', ['version', '--format', '{{.Server.Version}}']);
    findings.dockerAvailable = true;
  } catch { return findings; }

  const { stdout } = await exec('docker', [
    'ps', '--format', '{{.Image}}|{{.Names}}|{{.Status}}',
  ]);

  for (const line of stdout.split('\n').filter(Boolean)) {
    const [image, name, status] = line.split('|');
    const [imageName, tag = 'latest'] = image.split(':');
    if (KNOWN_IMAGES[imageName]) {
      findings.containers[KNOWN_IMAGES[imageName]] = { image: imageName, tag, name, status };
    }
  }
  return findings;
}

No Docker SDK dependency, no parsing library — just child_process.execFile and String.prototype.split. If Docker isn't installed, the scanner returns { dockerAvailable: false } and the diagnosis engine emits an info diagnostic instead of crashing.

The package scanner is similar — walks node_modules recursively (capped at 5000 directories so monorepos don't hang), records every @midnight-ntwrk/* it finds and what version. Duplicates fall out as a side effect: if the same package name has more than one version in the array, it's a duplicate.

const allInstances = await findAllInstances(projectDir, MIDNIGHT_NS);
for (const [name, versions] of Object.entries(allInstances)) {
  const unique = [...new Set(versions)];
  if (unique.length > 1) findings.duplicates[name] = unique;
}

Three lines. That's the entire duplicate-detection logic. The remaining ~50 lines of the scanner are filesystem traversal — boring, mechanical, but it works on every Node project regardless of package manager (npm, pnpm, yarn, bun all create node_modules directories with the same shape).

The diagnosis engine is glorified table joins

lib/diagnose.js takes the three scan results plus the matrix and emits diagnostics. The pattern repeats per check:

function diagnoseCrossCutting(pkg, docker, matrix) {
  const facadeVersion = pkg.installed['@midnight-ntwrk/wallet-sdk-facade'];
  const nodeContainer = docker.containers.node;
  if (!facadeVersion || !nodeContainer) return [];

  const track = matrix.tracks[detectTrack(facadeVersion, matrix)];
  if (track.node && track.node !== nodeContainer.tag) {
    return [{
      id: 'node-track-mismatch',
      severity: 'error',
      title: `midnight-node:${nodeContainer.tag} doesn't match SDK track (expects ${track.node})`,
      detail: `Mixing causes silent sync failures with no error.`,
      fix: `Either update the node container to ${track.node}, or align SDK to a track that matches your node version.`,
    }];
  }
  return [{ id: 'node-track-match', severity: 'ok',
            title: `midnight-node:${nodeContainer.tag} matches SDK track` }];
}

That's the entire body of the cross-cut check that would have saved my 6-hour March incident. Twelve lines. The information was there the whole time.

The full diagnosis file is ~200 lines. Most of it is the same shape: pick two facts from the scans, compare against the matrix, emit a diagnostic. It's deliberately boring code.

What this isn't

Scope discipline is half the value of a tool like this. Things midnight-doctor deliberately doesn't do:

It doesn't auto-fix. No --fix flag yet. The cost of a wrong auto-fix in this domain (bricked node_modules, lost work) outweighs the convenience.
It doesn't curl health endpoints. It checks Docker container presence, not health. A separate health-check script (midnight-health-check.sh) covers that already in my infra repo.
It doesn't probe the chain. No getBlockNumber(), no balance lookup. Those depend on a working SDK, which is what doctor is meant to validate before you try to use it.
It isn't a package manager. It won't run npm dedupe for you. It tells you to run it.
It doesn't write code. It doesn't generate scaffolds, codemods, or migrations. That's a different tool (create-midnight-app, eventually).

Each non-feature is a deliberate choice to keep the surface small enough that the tool stays correct.

What I'd build next, if there's appetite

midnight-doctor is the smallest useful version. The compatibility matrix as data unlocks several adjacent tools:

create-midnight-app — scaffold a project where midnight-doctor is wired into npm install lifecycle. The matrix becomes the default versions.
A codemod for the 2.x → 4.x facade migration. The API change is mechanical: WalletFacade.init({...}) → new WalletFacade(...) + .start(...). AST transform.
Compactc compiler version check. Today it's via shell-out. With a parser, doctor could read your .compact source and say "this uses syntax X, requires compactc ≥ Y."
Remote-fetched matrix. Right now the matrix is bundled. A nightly job at https://compatibility.midnight.network/matrix.json would let users not need to bump the doctor itself.
Editor integration. A VSCode extension that runs doctor on save and surfaces diagnostics in the problems panel. The CLI is for CI; the editor is for dev loop.

The first one is the highest leverage by far — it short-circuits the entire onboarding problem. But it's a much bigger project. Doctor is a Trojan horse for the matrix; once the matrix exists and people accept it as canonical, the rest is plumbing.

The broader argument: tools beat docs

Documentation rots. A README written today describes a system that, six weeks from now, has moved two majors. Anyone who builds in a fast-moving ecosystem has lived this: the official doc says "use SDK 1.0", the npm latest tag says 4.0, the GitHub README says 3.0, and the Discord pinned message says "we know, sorry, the docs are stale." None of those sources is wrong. They were all true at some point. The problem is they don't update each other.

Executable knowledge updates itself. A JSON file with a verifiedAt date that's three weeks old is visibly stale. A doc that's three weeks old looks identical to a doc that's three days old. Tools force the question "is this still true?" in a way that prose doesn't.

This isn't unique to Midnight. Every fast-moving stack reaches the point where the gap between "what the docs claim" and "what actually works" is wide enough to swallow new developers. The fix is the same: take the lookup table out of human heads, encode it as data, ship it as a tool that runs in seconds.

The Midnight protocol team doesn't need to build midnight-doctor. They could. Anyone could. The information already exists — in pinned messages, in CHANGELOG.md files, in the heads of the half-dozen people on Discord who answer the same question every week. The work isn't producing the information. It's transcribing it once, into a format machines can act on, and committing to keeping it current.

That's what this ~700-line tool does. It's not clever. It's not hard. It's just nobody had done it.

If you've spent hours on a Midnight silent failure, please run npx midnight-doctor against your project before your next debugging session. If you find a bug doctor missed, open an issue — the matrix is the artifact, the code is just glue.

Repo: github.com/fredericosanntana/midnight-doctor
Install: npm install -g midnight-doctor or npx midnight-doctor
License: MIT

If this was useful, the people who actually maintain Midnight (@MidnightNtwrk) deserve the visibility — half this matrix came from their Discord answers. The other half came from getting burned. Both contributions are essential.

Appendix: the full check list

For reference, every check midnight-doctor currently runs:

Package scanner:

✓ Detect SDK track (current, preprod-3x, preprod-1x) from wallet-sdk-facade major
✓ Flag deprecated tracks with migration guidance
✓ Detect major-version mismatch across wallet-sdk-* subpackages
✓ Detect duplicate @midnight-ntwrk/ledger-v7 in node_modules
✓ Detect duplicate @midnight-ntwrk/compact-runtime in node_modules
✓ Flag wallet-sdk-facade@2.x standalone init bug

Docker scanner:

✓ Detect running midnight-node, indexer-standalone, proof-server
✓ Cross-reference node tag with SDK track

Config scanner:

✓ Flag .npmrc with bogus npm.midnight.network registry
✓ Flag indexer.yml missing subscription: block

Cross-cutting:

✓ Node tag ↔ SDK track consistency

Roadmap:

☐ Compact compiler version vs runtime
☐ Health probes (RPC, GraphQL, proof endpoints)
☐ Monorepo workspace iteration
☐ --fix mode for safe auto-corrections
☐ Remote-fetched matrix

Total checks today: 11. Adding more is one PR each.

Building a Full-Stack ZK-Privacy App on Midnight: A Step-by-Step Guide

Haruki Kondo — Sun, 26 Apr 2026 13:11:02 +0000

Introduction

Hello everyone! 🚀

In this post, we are diving deep into Midnight, the privacy-focused blockchain!

Previously, we covered how to connect a frontend application to Lace Wallet. Now, we’re taking the next big step: connecting to a smart contract!

Implementing a full-stack ZK (Zero-Knowledge) application can be tricky, but I’ve navigated the pitfalls and version mismatches so you don't have to. Let’s get started!

What You Will Learn

How to develop a full-stack application on Midnight.
Concrete source code for calling smart contract functions via Lace Wallet.
Real-world "gotchas" and how to solve them.

The Sample App: A Full-Stack Counter

We’ll build a simple app that connects to Lace Wallet, displays balances, and interacts with a Counter smart contract.

Prerequisites

Lace Wallet browser extension (Midnight-compatible version).
PreProd network selected in Lace settings.
Some test NIGHT tokens from the official faucet.
Docker installed (for running the Proof Server).

GitHub Repository

Check out the full source code here:
https://github.com/mashharuki/midnight-sample-fullstack-app

Application Preview

Technical Features

Category	Feature	Description
Contract	Build	Compiles Compact files into WASM/ZKIR/Managed Code.
Contract	Simulator	Logic verification using `CounterSimulator` without a live network.
CLI	Deploy	Deploys to Standalone/TestNet and retrieves the contract address.
CLI	Interaction	Direct CLI commands to increment and check counter values.
App	Wallet Connect	Integration with Lace Wallet extension to fetch account data.
App	Sync	Automatically joins and fetches current state from a contract address.
App	ZK Increment	One-click UI to generate ZK proofs and send transactions.

Tech Stack

Layer	Technology
Frontend	React 19, Vite 5, Tailwind CSS v4, Lucide React, RxJS
Contract	Compact (Midnight's ZK DSL)
SDK	`@midnight-ntwrk/*` (SDK v2 / DApp Connector API v4)
Infrastructure	Midnight Node, Indexer, Proof Server (via Docker)
Tooling	Bun, Biome, Vitest, TypeScript

Deep Dive: Key Implementation Logic

The core logic resides in src/lib/counter.ts and src/hooks/useCounter.ts. This was the most challenging part of the build due to SDK version transitions and compatibility issues with Lace Wallet.

`src/lib/counter.ts`

This file handles the contract instance creation, state querying, and transaction calls.

1. Contract Instance Creation

We use the SDK to wrap the compiled Compact contract.

import * as CompactJs from "@midnight-ntwrk/compact-js";

// Initialize the compiled contract instance
export const counterContractInstance: CounterContract = (CompactJs.CompiledContract.make(
  "counter",
  Counter.Contract as any,
) as any).pipe(
  CompactJs.CompiledContract.withVacantWitnesses,
);

2. Querying State

Using queryContractState, we can fetch the ledger data (in this case, the round number of our counter).

export const getCounterValue = async (
  providers: CounterProviders,
  contractAddress: ContractAddress,
): Promise<bigint | null> => {
  assertIsContractAddress(contractAddress);

  const contractState = await providers.publicDataProvider.queryContractState(
    contractAddress,
  );

  return contractState != null
    ? Counter.ledger(contractState.data as any).round
    : null;
};

3. Calling Updates (Transactions)

The magic happens in callTx. This triggers the ZK proof generation and requests a signature from Lace Wallet.

export const incrementCounter = async (
  counterContract: DeployedCounterContract,
): Promise<void> => {
  // Call the increment() method on the contract
  await (counterContract as any).callTx.increment();
};

Getting Started: Run it Locally

1. Clone & Install

git clone https://github.com/mashharuki/midnight-lace-react-sample-app.git
cd midnight-lace-react-sample-app
bun install

2. Start the Proof Server

Midnight requires a Proof Server to generate ZK Proofs locally before sending transactions to the network.

cd pkgs/cli
# Start the Proof Server (Ensure it's version 8.0.3)
docker compose -f standalone.yml up -d

3. Build & Deploy the Contract

bun contract build

# Deploy to the PreProd network
bun cli preprod

Note: Copy the contract address displayed in the terminal!

4. Setup & Start the Frontend

# Set environment variables
cp pkgs/app/.env.local.example pkgs/app/.env

# Build and start
bun app build
bun app dev

Visit localhost:5173. You should see the following:

Connect your wallet.
Enter your deployed contract address and click Join.
Click Increment. You will be prompted to sign the transaction.

Wait a few moments for the ZK proof generation and network finalization. Once done, refresh to see the updated value!

Sequence Diagrams

Unlike traditional blockchains, Midnight involves a local ZK Proof generation step in every state-changing transaction.

Contract Deployment Flow

Increment Function Call Flow

Summary

Building with ZK-privacy is a paradigm shift. While there were hurdles—especially around SDK versions and wallet compatibility—overcoming them allows you to build applications that truly respect user privacy.

I even created a custom AI Agent skill to help debug the Midnight SDK logic, which made the final stretch much smoother! You can find my Claude skills in the repo if you're interested.

Happy coding, and see you in the next one where we might tackle some hackathon challenges! 🛡️✨

References

Build a Simple App That Connects to Midnight Lace Wallet

Haruki Kondo — Fri, 24 Apr 2026 12:35:58 +0000

Introduction

Hello everyone!

In this article, we will look at Midnight, a privacy-focused blockchain, and its dedicated wallet, Lace Wallet.

Lace | The light wallet platform to explore Web3

Discover the new light wallet platform from Input Output Global. Manage digital assets, and access NFTs, DApps, and DeFi services. Start your Web3 journey.

lace.io

The official documentation explains how to deploy and run contracts, but I could not find clear guidance on connecting Lace Wallet to a frontend app. I ran into a few tricky points while trying it, so I created a simple beginner-friendly sample app.

I hope you enjoy it!

What You Will Learn

A quick overview of Lace Wallet
How to build a simple app that connects to Lace Wallet

What Is Lace Wallet?

Lace Wallet is a lightweight wallet for storing and managing Cardano-related digital assets. It was announced by IOG, the team behind Cardano, on June 9, 2022.

It can manage digital assets on blockchains in the Cardano ecosystem, including Midnight.

Even though it is lightweight, it offers rich features such as staking and asset transfers.

It is currently optimized for the Cardano ecosystem, and it appears support for other ecosystems is planned in the future.

Build a Simple App That Connects to Lace Wallet

Prerequisites

Before running the sample code, make sure you have the following:

The Lace Wallet browser extension installed (a version with Midnight support)
PreProd selected in Lace network settings

Sample Code Repository

mashharuki / midnight-lace-react-sample-app

midnight-lace-react-sample-app

A sample dApp frontend for connecting to the Midnight Network (PreProd).
Use Lace Wallet to connect your wallet, view your shielded address, and check your balance.

Screenshots

Features

Feature	Description
Lace Wallet Connection	Detects and connects to `window.midnight.mnLace` via 100ms polling
Version Validation	Verifies that the Connector API version is `>=1.0.0`
Network Detection	Automatically tries networks in order: PreProd / mainnet / undeployed / preview
Address Display	Shows the shielded address in a copyable format
Balance Display	Shows Shielded / Unshielded / Dust balances in tDUST units
Language Toggle	Instantly switch between Japanese and English via the top-right button (persisted in localStorage)

Tech Stack

Category	Library / Tool
Framework	React 19 + TypeScript
Build	Vite 8
Styling	Tailwind CSS v4 (`@tailwindcss/vite`)
UI Components	shadcn/ui (Button, Badge, Card) + Lucide React
Internationalization	i18next 26 + react-i18next 17
Wallet Integration	`@midnight-ntwrk/dapp-connector-api`
Async Processing	RxJS 7
Package Manager	Bun
Formatter

…

View on GitHub

App Preview

This sample app is intentionally simple: connect Lace Wallet and display balances.

Feature List

Feature	Description
Lace Wallet connection	Detects and connects to `window.midnight.mnLace` using 100ms polling
Version check	Confirms Connector API version is `>=1.0.0`
Network validation	Automatically tries PreProd / mainnet / undeployed / preview in order
Address display	Shows a copyable shielded address
Balance display	Shows Shielded / Unshielded / Dust balances in tDUST
Language switch	Instantly toggles Japanese ⇆ English from the top-right button (persisted via localStorage)

Tech Stack

Category	Library / Tool
Framework	React 19 + TypeScript
Build	Vite 8
Styling	Tailwind CSS v4 (`@tailwindcss/vite`)
UI Components	shadcn/ui (Button, Badge, Card) + Lucide React
Internationalization	i18next 26 + react-i18next 17
Wallet Integration	`@midnight-ntwrk/dapp-connector-api`
Async Processing	RxJS 7
Package Manager	Bun
Formatter	Biome

Key Source Code Explanations

The overall architecture is similar to many other blockchain apps.

If you understand the SDK and API specifications, you can build a working connection app quickly.

The key SDK in this project is @midnight-ntwrk/dapp-connector-api.

It is used to implement the wallet connection logic.

All important connection-related logic is consolidated in the file below.

A key point is around line 103.

// Attempt connection. If a network mismatch occurs, fall back to the next candidate.
walletAPI = await connector.connect(networkId);
// Lace v4: getConfiguration() is on walletAPI (not connector)
const walletRaw = walletAPI as unknown as Record<string, unknown>;

From walletRaw, you can extract wallet information such as addresses.

let address = "";
let coinPublicKey = "";
let encryptionPublicKey = "";

if (typeof walletRaw.getShieldedAddresses === "function") {
  // getShieldedAddresses() may return an array (old versions) or a single object (new versions), so handle both cases
  const result = await (
    walletRaw.getShieldedAddresses as () => Promise<Record<string, unknown>>
  )();
  // Lace v4 returns a single object (not array):
  // { shieldedAddress, shieldedCoinPublicKey, shieldedEncryptionPublicKey }
  const entry = (Array.isArray(result) ? result[0] : result) as
    | Record<string, unknown>
    | undefined;
  if (entry) {
    address = String(entry.shieldedAddress ?? entry.address ?? "");
    coinPublicKey = String(
      entry.shieldedCoinPublicKey ?? entry.coinPublicKey ?? "",
    );
    encryptionPublicKey = String(
      entry.shieldedEncryptionPublicKey ?? entry.encryptionPublicKey ?? "",
    );
  }
}

Balance retrieval is implemented as a dedicated React hook.

The most important part is the fetchBalances function.

It fetches balances from three wallet-related methods:

raw.getShieldedBalances
raw.getUnshieldedBalances
raw.getDustBalance

import { formatBalance } from "@/lib/utils";
import type { BalanceState } from "@/utils/types";
import type { DAppConnectorWalletAPI } from "@midnight-ntwrk/dapp-connector-api";
import { useCallback, useState } from "react";

export type { BalanceState };

/**
 * Fetch shielded / unshielded / dust balances in parallel from the wallet API.
 *
 * The Lace SDK type definitions do not include these balance methods,
 * so this function casts to unknown and checks method availability dynamically.
 * Promise.allSettled allows us to receive remaining results even if one call fails.
 */
async function fetchBalances(walletAPI: DAppConnectorWalletAPI): Promise<{
  shielded: string;
  unshielded: string;
  dust: string;
}> {
  const raw = walletAPI as unknown as Record<string, unknown>;

  // Try fetching balances in parallel. If a method is unavailable, return null.
  const [shieldedResult, unshieldedResult, dustResult] =
    await Promise.allSettled([
      typeof raw.getShieldedBalances === "function"
        ? (raw.getShieldedBalances as () => Promise<unknown>)()
        : Promise.resolve(null),
      typeof raw.getUnshieldedBalances === "function"
        ? (raw.getUnshieldedBalances as () => Promise<unknown>)()
        : Promise.resolve(null),
      typeof raw.getDustBalance === "function"
        ? (raw.getDustBalance as () => Promise<unknown>)()
        : Promise.resolve(null),
    ]);

  return {
    shielded:
      shieldedResult.status === "fulfilled"
        ? formatBalance(shieldedResult.value)
        : "--",
    unshielded:
      unshieldedResult.status === "fulfilled"
        ? formatBalance(unshieldedResult.value)
        : "--",
    dust:
      dustResult.status === "fulfilled"
        ? formatBalance(dustResult.value)
        : "--",
  };
}

/**
 * Custom hook to manage loading and refreshing balances.
 *
 * @param walletAPI - Connected wallet API. If null, no action is taken.
 * @returns balanceState: current balance state / refresh: manual refresh trigger
 */
export function useBalance(walletAPI: DAppConnectorWalletAPI | null) {
  const [balanceState, setBalanceState] = useState<BalanceState>({
    status: "idle",
  });

  /**
   * Fetch balances from the wallet API and update state.
   * If walletAPI is null, do nothing.
   * Set status to "loading" while fetching, "loaded" on success with balances,
   * and "error" if anything fails.
   */
  const refresh = useCallback(async () => {
    if (!walletAPI) return;
    setBalanceState({ status: "loading" });
    try {
      const balances = await fetchBalances(walletAPI);
      setBalanceState({ status: "loaded", ...balances });
    } catch (e: unknown) {
      console.error("[useBalance] Failed to fetch balances:", e);
      setBalanceState({ status: "error" });
    }
  }, [walletAPI]);

  return { balanceState, refresh };
}

How to Run the App

Clone

git clone https://github.com/mashharuki/midnight-lace-react-sample-app.git

# Move to the frontend app directory
cd app

Install

bun install

Build

bun run build

Start

bun run dev

Conclusion

That is all for this tutorial.

Now you have a clear path to connect a React + Vite app with Lace Wallet, which is a solid step toward building a full-stack Midnight application.

In a future article, I plan to cover how to call functions on a smart contract deployed on Midnight and continue toward a full-stack implementation.

Thank you for reading!

References

Compact Is Not TypeScript. That's the Whole Point.

Tushar Pamnani — Thu, 23 Apr 2026 08:44:50 +0000

Most developers approach Compact with the wrong frame.

They see the syntax - functions, types, imports, curly braces, and conclude: this is basically TypeScript with some ZK stuff sprinkled in. Then they start writing. And things break in ways that don't make sense. Loops that should work don't compile. Logic that feels correct fails silently. Private data bleeds into places it shouldn't.

The syntax didn't lie to them. Their mental model did.

The Illusion Is the Lesson

Here's a Compact circuit:

export circuit get(): Uint<64> {
  assert(state == State.SET, "Value not set");
  return value;
}

Your brain reads this and fires the usual pattern: function, assertion, return value. It looks like a getter. Call it, get a thing back.

But that's not what's happening.

This circuit doesn't "run." It declares a set of constraints. When you call it from your dApp, the proof system generates a zero-knowledge proof that those constraints were satisfied, without revealing the inputs. What goes on-chain isn't the output. It's the proof.

The frame shift: You're not writing code that executes. You're writing a description of a valid state, and the system proves you were in it.

Two Mental Models. One Will Break You.

Traditional code:

Input → Code executes → Output

You write instructions. The machine follows them. You get a result.

Compact circuits:

Input → Constraints are declared → Proof is generated → Proof is verified

There are no "instructions" in the traditional sense. The circuit defines relationships. The prover proves the relationships held. The chain verifies the proof without seeing the inputs.

Nothing is executed. Correctness is proved.

This is why assert is your only runtime guard. It's not just input validation, it's the mechanism by which you define what a valid state even is. Every assert is a constraint. Every constraint becomes part of the circuit. The circuit is the proof.

The Constraints Are the Feature

The first reaction most developers have to Compact's restrictions:

No recursion
Bounded loops only (bounds must be compile-time constants)
Fixed type sizes
No any
Unsigned types only

"These seem arbitrary. Why can't I just-"

They're not arbitrary. They're causal.

ZK proofs require finite circuits. A circuit is a fixed structure; gates, wires, constraints, determined entirely at compile time. If you could write unbounded loops or recursion, the compiler couldn't produce a circuit. The circuit literally couldn't exist. The proof couldn't be generated.

The constraints don't limit what Compact can do. They're what make the magic possible at all.

Accept this, and the language makes complete sense. Fight it, and you'll spend weeks trying to port TypeScript patterns into a tool designed around a completely different model.

What "Privacy" Actually Means Here

Compact is not just "TypeScript with encryption." The privacy model is structural.

Midnight has two worlds:

World	Where	Who can see it
Public	On-chain	Everyone
Private	Local	Only you

Your sensitive data; balances, credentials, secrets, never leaves your machine. What goes on-chain is a proof that you ran the computation correctly on that private data. Validators verify the proof. They never see the inputs.

This has a concrete implication: you have to know the boundary.

export ledger is public. witness data is private. disclose() is the explicit line you cross when you intentionally move private data into public state.

The compiler enforces this. If private data tries to flow into public state without going through disclose(), it fails. But knowing why this boundary exists — not just that it does — is what lets you design contracts correctly from the start instead of debugging your way there.

The Use Cases This Unlocks

This matters because entire categories of blockchain applications were previously impossible:

Healthcare: Prove you meet age or eligibility requirements without revealing your date of birth or medical history.
Finance: Prove your balance exceeds a threshold for a loan without revealing the balance.
Identity: Prove citizenship or credential validity without revealing the underlying document.
Competitive markets: Submit bids or inventory levels that can be verified as legitimate without being revealed to competitors.

These aren't niche edge cases. They're the reason regulated industries haven't fully adopted public blockchains. With Compact, the privacy model that makes these use cases viable is built into the language, not bolted on after the fact.

Why the Comparison Breaks Down

Concept	TypeScript	Solidity	Compact
Private data	Convention only	On-chain (visible)	Stays local, always
Functions	Execute instructions	Execute instructions	Declare constraints
Loops	Unbounded	Unbounded (gas-limited)	Bounded at compile time
Recursion	Allowed	Allowed	Not allowed
Privacy enforcement	None	None	Type system + compiler

The closest thing Compact resembles isn't TypeScript. It's a constraint satisfaction system with TypeScript syntax. The syntax is a DX choice, not a design philosophy.

The One Thing to Take Away

Every concept in Compact, witnesses, circuits, disclose(), the boundedness rules, becomes clear once you have the right frame:

You're not writing programs. You're describing valid states and proving you were in them.

With that frame:

Witnesses make sense: they're the private inputs the prover uses to generate the proof.
disclose() makes sense: it's the intentional act of moving a constraint into public view.
Bounded loops make sense: the circuit is fixed at compile time, so everything has to be fixed at compile time.
assert makes sense: it's not validation, it's constraint declaration.

Without that frame, everything in Compact feels like TypeScript with arbitrary restrictions. With it, everything is exactly as it should be.

What I Built for This

Most documentation explains the what. Compact's own docs are good. But the gap isn't information, it's the conceptual layer underneath.

I've been building a structured guide that goes through each concept with the execution model shift front and center: Compact Book

If you're trying to actually understand Compact rather than just cargo-cult your way through examples, start there.

The syntax is the easy part. The mental model is the work. Get that right, and the rest follows.

Working with Maps and Merkle Trees in Compact:

Nasihudeen Jimoh — Thu, 16 Apr 2026 08:19:24 +0000

A Guide to the State Dichotomy

The Midnight blockchain introduces a fundamental architectural shift in smart contract design through its "State Dichotomy." Unlike transparency-first blockchains, Midnight enables developers to partition data into public Ledger State and private Shielded State. This guide provides a comprehensive analysis of the two primary data structures used to manage these states: Maps and Merkle Trees.

Through a dual-implementation approach featuring a public registry and an anonymous allowlist this guide explores the operational mechanics, security considerations, and SDK integration patterns required to build applications with Compact.

The State Dichotomy: Conceptual Framework

Compact contracts operates as a decentralized state machine where transitions are governed by Zero-Knowledge (ZK) circuits. The efficiency and privacy of these transitions depend on the selection of appropriate storage structures. This bifurcation of state is not merely an optimization but a core privacy Primitive.

Ledger state (Public)

The Ledger state consists of on chain data structures that are globally visible and replicated across the network nodes. Ledger state is governed by Abstract Data Types (ADTs) such as Maps, Counters, and Sets. These structures provide the shared source of truth required for applications like token supply management, administrative registries, and public consensus variables. In Compact, every ledger interaction is verifiable by any observer, ensuring that the global state remains consistent and auditable.

Shielded state (Private)

Shielded state remains off chain, residing within the prover’s local environment. Users interact with the ledger by submitting Zero Knowledge (ZK) proofs that verify a state transition has occurred according to the contract's logic without revealing the underlying data. This enables features like confidential assets, anonymous membership verification, and private governance. The shielded state is protected by the prover's secret keys and is only revealed through explicit "disclosures" within a circuit.

Choosing the correct structure

The choice between a Map and a Merkle Tree is determined by the required visibility of the relationship between a user and their data. Developers must ask: "Does the network need to know who owns this data, or only that they own it?"

Maps are used when the association between a key and a value must be public and directly queryable.
Merkle Trees are used when the goal is to prove membership within a set or the integrity of a dataset without revealing the identity of the specific member.

Associative storage with Maps

The Map ADT is the primary tool for associative storage on the Midnight ledger. It allows for O(1) lookups and insertions, functioning as a decentralized dictionary. Maps are foundational for any application where identities need to be linked to properties or permissions in a transparent way.

Syntax and declaration

In Compact, a Map is declared within a ledger block. The following definition maps a 32-byte public key to a 32-byte profile hash:

pragma language_version >= 0.16 && <= 0.21;

import CompactStandardLibrary;

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

Map operators and the disclosure rule

Every interaction with a Map must navigate the boundary between private circuit parameters and public ledger state.

1. The disclosure requirement: Bridging Private and Public

Circuit parameters are private by default. In the Compact execution model, parameters are "witnesses" known only to the prover. To store a parameter in a public Map, it must be explicitly disclosed using the disclose() operator. Failure to do so results in a compilation error, as Compact prevents the accidental leakage of private witnesses into public storage.

export circuit register(profile_hash: Bytes<32>): [] {
    const user = ownPublicKey();
    const d_profile_hash = disclose(profile_hash);
    registry.insert(user.bytes, d_profile_hash);
}

This ensures that the user is aware of exactly what information is being pushed to the ledger. If you were to attempt registry.insert(user.bytes, profile_hash), the compiler would signal a security violation, maintaining a strict "Privacy by Default" posture.

2. Detailed Map Operations

insert(key, value): Creates or updates an entry. If the key already exists, the old value is overwritten. This operation generates a ledger state update that is broadcast to the network.
lookup(key): Retrieves the value associated with a key. If the key is absent, it returns the type-specific default (e.g., zero bytes for Bytes<32>, false for Boolean).
member(key): A Boolean operator that checks for key existence without retrieving the value. This is highly efficient for access control checks where the value itself is irrelevant.
remove(key): Deletes an entry from the ledger, clearing the associated storage. This is crucial for managing "state bloat" and ensuring that outdated memberships are purged.

Zero Knowledge membership with Merkle Trees

Merkle Trees are the engine of anonymity on Midnight. By representing a large set of data with a single 32-byte root hash, they allow for membership verification that preserves the privacy of the specific leaf.

Technical specification and Depth Selection

Merkle Trees in Compact are fixed-depth. The choice of depth determines the maximum capacity of the tree ($2^{depth}$).

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

A depth of 20 supports approximately 1,048,576 entries. Choosing the correct depth is an engineering trade-off:

Higher Depth: Increases the capacity of the system but linearly increases the size of the ZK circuit and the time required for proof generation.
Lower Depth: Reduces proving time but risks hitting a "Full State" where no new members can be added without a contract migration.

Operational lifecycle: The path to proof

The verification of membership involves a transition from the ledger's public root to the prover’s private Merkle path.

1. The Merkle path witness

To prove membership, a user must provide a Merkle Path a sequence of sibling hashes representing a branch from the leaf to the root. This is defined as a witness function, identifying it as data retrieved from the prover's local environment.

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

In the SDK, this path is calculated by iterating over the local view of the tree and finding the siblings for the target leaf at each level of the binary structure.

2. Circuit-level verification logic

Inside the ZK-circuit, the merkleTreePathRoot operator reconstructs the root hash from the provided path and leaf. The circuit verifies that the hashes align at each level ($H(L, R)$).

export circuit access_exclusive_area(leaf: Bytes<32>): [] {
    const d_leaf = disclose(leaf);
    const path = get_membership_path(d_leaf);

    // ZK Re-computation of the root
    const computed_root = merkleTreePathRoot<20, Bytes<32>>(path);

    // Verification against Ledger State
    assert(allowlist.checkRoot(disclose(computed_root)), "Access Denied");
}

The "Double Disclosure" security pattern

The pattern above utilizes two disclosures that are essential for the Midnight security model:

Disclosing the Leaf: Ensures the proof corresponds to the exact data provided by the user. If the leaf were not disclosed, a malicious prover could use a different leaf than the one they claim to possess.
Disclosing the Root: The checkRoot operator must compare the computed_root against the public ledger. For this comparison to occur, the value being checked must be public. Because the root hash is already public, this disclosure does not reveal any private information about the leaf or path used. It simply confirms: "I know a secret that hashes to this public root."

Technical comparison: Maps vs. Merkle Trees

Metric	Map (Ledger ADT)	Merkle Tree (Ledger ADT)
Data Visibility	Fully Public	Root Public; Leaves/Paths Private
Access Pattern	Key-Based (Direct)	Path-Based (Indirect)
Privacy Model	Transparent Association	Set Membership Anonymity
Proof Complexity	Low (O(1))	High (O(depth) hashes)
Primary Use	Registries, Public Indices	Anonymous Allowlists, Confidential Voting
State Bloat	Linear per entry	Fixed per depth ($O(1)$ on-chain root)

Computational overhead analyze

Merkle Trees impose a higher verification cost. A tree of depth 20 requires 20 sequential hash computations within the ZK-circuit. Each hash operation increases the number of constraints in the proof, which correlates directly to proof generation time. While this provides anonymity, developers must consider that a user on a mobile device may take significantly longer to generate a proof for a depth 32 tree compared to a depth-16 tree. In contrast, Map operations are computationally negligible within a circuit.

SDK implementation: The structural validation

When integrating Compact contracts with the Midnight TypeScript SDK, developers must align the orchestrator's output with the runtime's expected data shapes. A common failure point is the Structural Validation of the Merkle path.

The `instanceof` requirement and Type Safety

The @midnight-ntwrk/compact-runtime performs strict type checking on objects returned by witness functions. Manually constructing a Merkle path object as a JSON literal will fail even if the fields (value, alignment) match. This is because the runtime's ZK IR (Intermediate Representation) requires an instance of the specific internal MerkleTreePath class.

Instead, developers must use the findPathForLeaf method provided by the ledger context.

// src/prover/allowlist_witnesses.ts
get_membership_path(context, leaf) {
  // This returns an instance of the MerkleTreePath class
  const path = context.ledger.allowlist.findPathForLeaf(leaf);

  if (!path) {
    throw new Error("Leaf discovery failed: State mismatch");
  }

  return path;
}

This ensuring that the path is derived from the current ledger state and satisfies the runtime's internal instanceof checks.

Detailed Implementation Walkthrough

The following implementation show how both structures are managed in a single application lifecycle.

Registry contract: `contract/registry.compact`

pragma language_version >= 0.16 && <= 0.21;

import CompactStandardLibrary;

// Map Bytes<32> address to Bytes<32> profile CID
export ledger registry: Map<Bytes<32>, Bytes<32>>;

export circuit register(profile_hash: Bytes<32>): [] {
    const user = ownPublicKey();
    // Public disclosure for ledger storage
    const d_profile_hash = disclose(profile_hash);
    registry.insert(user.bytes, d_profile_hash);
}

export circuit remove_registration(): [] {
    const user = ownPublicKey();
    registry.remove(user.bytes);
}

export circuit get_profile(user_pk: Bytes<32>): Bytes<32> {
    // Disclosure required for circuit parameters used in lookups
    return registry.lookup(disclose(user_pk));
}

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

Allowlist contract: `contract/allowlist.compact`

pragma language_version >= 0.16 && <= 0.21;

import CompactStandardLibrary;

// Merkle Tree for anonymous membership
export ledger allowlist: MerkleTree<20, Bytes<32>>;

export circuit update_allowlist(member_hash: Bytes<32>): [] {
    const d_member = disclose(member_hash);
    allowlist.insert(d_member);
}

export circuit access_exclusive_area(leaf: Bytes<32>): [] {
    const d_leaf = disclose(leaf);
    const path = get_membership_path(d_leaf);

    // Hash up the tree to the root
    const computed_root = merkleTreePathRoot<20, Bytes<32>>(path);

    // Check if the computed root matches the current ledger state
    assert(allowlist.checkRoot(disclose(computed_root)), "Access Denied");
}

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

TypeScript orchestrator: `src/index.ts`

import {
  createActionCircuitContext,
  dummyContractAddress,
} from "@midnight-ntwrk/compact-runtime";
import { RegistryContract } from "./managed/registry/contract/index.js";
import { AllowlistContract } from "./managed/allowlist/contract/index.js";
import { AllowlistProver } from "./prover/allowlist_witnesses.js";

async function main() {
  const alicePk = new Uint8Array(32).fill(1);
  const profileHash = new Uint8Array(32).fill(9);

  // 1. Map Interaction: Public Registry
  const registry = new RegistryContract();
  const regCtx = createActionCircuitContext(
    dummyContractAddress(),
    { bytes: alicePk },
    registry.initialContractState,
    registry.initialPrivateState,
  );

  // Insert Alice into the registry Map
  const { context: updatedRegCtx } = registry.circuits.register(
    regCtx,
    profileHash,
  );
  console.log("Registry state updated via Map insertion.");

  // 2. Merkle Interaction: Anonymous Allowlist
  const prover = new AllowlistProver();
  const allowlist = new AllowlistContract({
    // Resolve the witness using the prover logic
    get_membership_path: (context, leaf) =>
      prover.get_membership_path(context, leaf),
  });

  const allowCtx = createActionCircuitContext(
    dummyContractAddress(),
    { bytes: alicePk },
    allowlist.initialContractState,
    allowlist.initialPrivateState,
  );

  console.log("Updating on-chain Merkle root...");
  // Populate the tree before proving
  const { context: postAddCtx } = allowlist.circuits.update_allowlist(
    allowCtx,
    alicePk,
  );

  console.log("Verifying anonymous membership proof...");
  // Execute the anonymous access circuit
  allowlist.circuits.access_exclusive_area(postAddCtx, alicePk);
  console.log("Access Granted: Membership verified anonymously.");
}

main().catch(console.error);

State Bounded Merkle Trees

Forsystems processing high volumes, a static Merkle Tree can present challenges during concurrent updates. Production Midnight applications often utilize State Bounded transitions.

The Synchronization window

Because the Merkle root is global, every new addition invalidates the old root. If a user is half way through generating a 2 second proof and another transaction lands, the root will shift and the proof will fail.

Midnight addresses this with Historic Windows. A HistoricMerkleTree allows a circuit to verify a proof against any root within the last $N$ blocks. This providing a "synchronization window" that makes DApps resilient to high traffic.

State Bounded Merkle Trees

A State Bounded Merkle Tree allows for the separation of the state into bounded regions. This is particularly useful for optimizing storage, as old branches that are no longer being proven against can be pruned from active memory while maintaining the cryptographic root consistency.

Best practices

Disclosure hygiene

In Compact, the order of disclose() calls can influence the circuit's logic flow. Developers should disclose values as late as possible ideally directly before the ledger operation that requires them. This maintain a clear boundary between the private computation (witnesses) and the public assertion (disclosures).

Handling state lag in production

In a live network environment, the ledger state might be several blocks ahead of your local prover’s view. When retrieving a Merkle path, ensure your client is synchronized with the specific block height that matches the Merkle root currently stored on the ledger. Outdated paths are the most common cause of checkRoot assertion failure.

Optimization: Caching witness results

Merkle path lookups are computationally intensive for the local ledger view. If an application requires frequent verification (e.g., a private chat room), consider caching the MerkleTreePath in the private state and only updating it when the ledger's Merkle root changes.

API Reference

Operator	Structure	Return Type	Description
`insert(k, v)`	Map	`[]`	Inserts or updates a value.
`lookup(k)`	Map	`V`	Retrieves value or default.
`member(k)`	Map	`Boolean`	Checks for key existence.
`remove(k)`	Map	`[]`	Deletes a key from the ledger.
`insert(leaf)`	MerkleTree	`[]`	Appends a leaf to the tree.
`checkRoot(root)`	MerkleTree	`Boolean`	Verifies a root against state.
`merkleTreePathRoot(path)`	Witness	`Bytes<32>`	Computes root from path in ZK.

Conclusion

Maps and Merkle Trees are the fundamental storage structures that enable the state dichotomy of the Midnight blockchain. Maps provide the efficiency and directness required for public association, while Merkle Trees facilitate the zero-knowledge membership proofs that define privacy preserving interaction.

By mastering the transition between these two domains specifically the nuances of the disclose() operator and the MerkleTreePath witness resolver developers can architect complex, privacy centric applications that benefit from both transparency and confidentiality. For further exploration, consult the official Midnight Documentation.

The full code example is here you can check it up*GitHub Repository*: Kanasjnr/compact-maps-merkle-tutorial

Forem: Midnight Aliit Fellowship

I Built a Midnight dApp Like an ETH Dev. Here's Everything I Got Wrong.

The Decision That Cost Me Two Days

What "Server Wallet" Actually Meant

Why It's Wrong (Beyond the Obvious "Users Can't Sign")

The Migration: What Actually Has to Change

1. ZK Config Provider

2. Proof Provider

3. Private State Provider

4. Transaction Balancing and Submission

The Race Condition Nobody Warns You About

The Full Diff: What the Architecture Actually Looks Like Now

What I'd Tell Myself If I Could Go Back

The Honest Part Nobody Writes

Mathematically Prohibiting 'Cheating' in On-Chain RPS: A Midnight ZK dApp Case Study

Introduction

What You'll Learn

Repository

mashharuki / midnight-rps-sample-app

Midnight RPS sample dApp

midnight-rps-sample-app

Overview

Key Features

Game Flow

Quick Start

Environment

Install Lace Wallet to your browser

Lace | The light wallet platform to explore Web3

0. Clone the Repository

1. Install Dependencies

2. Compile and Build Contracts

3. Start the Proof Server (Initial Pull: ~3 mins)

4. Deploy Contract to PreProd Network

The Essence of Midnight Architecture: "Localizing" Information

App Architecture

Code Deep Dive: Mathematically Preventing Cheating

1. Security Core: Domain Separation

2. The Commit-Reveal Circuits

Commit Phase (Declaring a move while keeping it hidden)

Game State Transitions

3. Reveal Phase: Where ZK Proofs Shine

Overcoming the ZK dApp UX Hurdle

Filling the 10-Second Silence

Sequence: From Commit to Game End

Remaining Challenges

Conclusion

Follow me on X!

References

Your Data Isn't Private. You Just Haven't Put It On-Chain Yet

The actual model

export ledger means public. Completely.

Where private data actually lives

disclose() is not what you think it is

The compiler tracks the boundary, everywhere.

When you need to prove something about private data without revealing it

The design shift this requires

The one question to ask before writing any ledger field

Ledger State and Explicit Disclosure chapters cover this in full

Compact vs Solidity: Limitations and Advantages

Compact vs Solidity: Limitations and Advantages

Understanding the Core Difference

Limitations of Compact Compared to Solidity

Lack of On Chain Contract Deployment

Reduced Composability

Constraints on Dynamic Logic

Higher Learning Curve

Immature Tooling Ecosystem

Different Approach to Identity and Permissions

Advantages of Compact Over Solidity

Native Privacy

Computation on Encrypted Data

Selective Disclosure

Stronger Security Model

Better Suitability for Sensitive Applications

Alignment with Future Technologies

Solidity and Compact as Complementary Systems

Conclusion

Building on Midnight with Windows — A Real Developer's WSL2 Setup Guide

Step 1: Enable WSL2

Step 2: Download Ubuntu from the Microsoft Store

`export ledger` means public. Completely.

`disclose()` is not what you think it is

What `return a + b` actually means in a circuit

What `assert` actually is

The tool: `midnight-doctor`

`src/lib/counter.ts`