DEV Community: Midnight Aliit Fellowship

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

I Hit Midnight's Block Limits Twice; And It Forced Me to Rethink Everything

Tushar Pamnani — Thu, 16 Apr 2026 08:18:30 +0000

This isn't about my prediction market. It's about the assumption that broke it, twice.

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

It's not a tutorial. It's not a "look what I built" post. It's what actually happened when I tried to bring EVM thinking into Midnight, hit a wall, optimized my way into the same wall, and finally understood why the wall existed in the first place.

What "Building on Midnight" Did to My Brain (Before It Fixed It)

When you spend enough time on EVM, you internalize a model without realizing it. Contracts can compute. Contracts can store structured data. Contracts can iterate. If it compiles, it probably runs.

I didn't question any of that when I started building on Midnight. I translated the mental model directly across.

That was the first mistake.

What I Built (V1)

I built what felt like a clean, well-structured prediction market. Store every bet. Track every user. Compute rewards on-chain. Store results. Let users claim.

Here's the Market contract state from V1:

export ledger admin: Bytes<32>;
export ledger marketName: Opaque<"string">;
export ledger description: Opaque<"string">;
export ledger imageUrl: Opaque<"string">;
export ledger parameter: Opaque<"string">;
export ledger category: Opaque<"string">;
export ledger bets: Map<Bytes<32>, Bet>;
export ledger betKeys: Map<Uint<32>, Bytes<32>>;
export ledger betCount: Counter;
export ledger totalVolume: Uint<128>;
export ledger totalParticipants: Uint<64>;

And the Bet struct itself:

export struct Bet {
  user: Bytes<32>;
  amount: Uint<128>;
  predictedValue: Uint<64>;
  rewardAmount: Uint<128>;
  claimed: Boolean;
  timestamp: Uint<64>;
}

The Factory was doing the same thing, storing a full MarketConfig struct with name, category, contract address, fee snapshot, timestamps, status, and active flag. All on-chain. Registered and tracked in a Map<Uint<32>, MarketConfig>.

At this point, everything felt right. Clean abstractions. Proper data modelling. Structured state. Good EVM design, basically.

The First Time It Broke

It didn't fail at compile time. It failed at execution.

Some transactions took minutes. Some never completed. Some failed silently. And eventually:

BlockLimitExceeded

My first instinct: RPC issue? Wallet issue? SDK bug?

No.

The Reality I Didn't Understand

Midnight doesn't work like EVM. It doesn't charge you more for complexity, it just refuses to execute if you cross limits. The actual constraints are approximately 1 MB transaction size, around 1 second compute time, limited state writes, and constraint-based execution throughout.

This means you're not optimizing cost. You're trying to fit inside a box. And I wasn't even close.

What Actually Went Wrong (Not the Obvious Stuff)

The problem wasn't too many lines of code or too many functions. It was deeper than that.

Structs are not cheap. In EVM, Bet memory bet = bets[user] feels like a cheap read. In Midnight, bets.lookup(userPk) pulls the entire struct into the circuit, every field, every time. So when claimReward() did this:

const userBet = bets.lookup(disclose(userPk));
assert(!userBet.claimed, "PredictionMarket: Already claimed");

It wasn't reading one boolean. It was processing all six fields of the Bet struct inside the circuit. And then to mark it claimed, I had to reconstruct the entire struct:

const updatedBet = Bet {
  user: userBet.user,
  amount: userBet.amount,
  predictedValue: userBet.predictedValue,
  rewardAmount: userBet.rewardAmount,
  claimed: true,
  timestamp: userBet.timestamp
};
bets.insert(disclose(userPk), disclose(updatedBet));

Read full struct. Modify one field. Write full struct back. That pattern was everywhere in V1.

I built a database on-chain. marketName, description, imageUrl, parameter, category, all stored as on-chain ledger state. That's not a contract. That's a backend disguised as a contract.

I designed for iteration. This line in placeBet:

assert(
  betCount.read() < 500 as Uint<64>,
  "PredictionMarket: Max participants reached"
);

Seems harmless. But it implies I was thinking in datasets, bounded participant sets, total user counts, potential future iteration. That's an EVM mindset. In Midnight, you don't think in datasets. You think in constraints.

I tried to compute rewards on-chain. The V1 Bet struct stored rewardAmount per user. That implied reward computation logic would run on-chain. Even before I got there, the struct overhead alone was enough to blow the limits.

The Second Failure (More Important Than the First)

After V1 failed, I did what most developers do. I split contracts. Reduced some redundant state. Reorganized logic. Introduced better lifecycle control.

V2 got significantly more sophisticated. Oracle whitelist for resolution. Dispute window system. Three-phase reward computation: computeRewardBatch, finalizeRewardBatch, markRewardsFinalized. The inverse distance accuracy model where rewards are proportional to how close your prediction was.

The math was actually elegant. Here's what computeRewardBatch was trying to verify:

const absDiff = getAbsDiff64(userBet.predictedValue, finalValue.read());
const denominator = (absDiff + 1 as Uint<64>) as Uint<128>;
const expectedInverseDist = getQuotient128(
  1000000000000000000 as Uint<128>,  // 1e18
  denominator
);
assert(_inverseDist == expectedInverseDist, "V2: Invalid inverse distance");

For every single bet. One circuit call per user.

The problem wasn't the math. It was that V2 was still making the same fundamental assumption: contracts should compute. I'd changed how things were written, not what the system was doing. The struct reads were still expensive. The Merkle verification I'd introduced was heavy. The state reads and writes per transaction were still high.

It failed again.

This time the realization hit properly: I wasn't solving the right problem.

The Shift (V3)

This was the turning point. I stopped asking "how do I implement this on-chain?" and started asking "what is the minimum the chain needs to enforce?"

That question changed everything.

Look at what the V3 Market contract stores:

export ledger admin: Bytes<32>;
export ledger status: Status;
export ledger totalPool: Uint<128>;
export ledger endTime: Uint<64>;
export ledger finalValue: Uint<64>;
export ledger rewardPool: Uint<128>;
export ledger feesCollected: Uint<128>;
export ledger minBet: Uint<128>;
export ledger maxBet: Uint<128>;
export ledger betCount: Counter;
export ledger bets: Map<Bytes<32>, Uint<128>>;

That last line. bets is now Map<Bytes<32>, Uint<128>>. Not a struct. Just the amount.

The placeBet circuit in V3:

bets.insert(disclose(userPk), disclose(_betAmount));
betCount.increment(1);
totalPool.write(disclose((totalPool.read() + _betAmount) as Uint<128>));

Three operations. That's it. No struct serialization. No rewardAmount field. No timestamp. No predicted value stored on-chain. The prediction is captured in a separate data structure, just what's needed for the Merkle tree built off-chain.

The V3 Factory went even further:

export ledger owner: Bytes<32>;
export ledger marketCount: Counter;
export ledger marketExists: Map<Bytes<32>, Boolean>;
export ledger marketById: Map<Uint<32>, Bytes<32>>;

registerMarket in V1 took six parameters and stored a full MarketConfig struct. In V3, it takes one parameter, the market address, and stores a boolean:

export circuit registerMarket(_marketAddress: Bytes<32>): Uint<32> {
  // ...
  marketExists.insert(disclose(_marketAddress), disclose(true));
  marketById.insert(disclose(id), disclose(_marketAddress));
  marketCount.increment(1);
  return id;
}

Name, category, timestamps, fee snapshot, gone. All of that lives off-chain now, in an indexer.

And the Distributor, which is the most interesting piece of V3:

export ledger distRoots: Map<Uint<64>, Bytes<32>>;
export ledger distPools: Map<Uint<64>, Uint<128>>;
export ledger distDistributed: Map<Uint<64>, Uint<128>>;
export ledger distDeadlines: Map<Uint<64>, Uint<64>>;
export ledger distStatus: Map<Uint<64>, DistStatus>;
export ledger claims: Map<Bytes<32>, Boolean>;

Flat maps instead of struct maps. Each field stored independently, no struct serialization overhead. And claimReward does exactly ten things: derive user key, compute leaf hash, check not already claimed, check deadline, check pool bounds, check status, accept proof via witness, mark claimed, update distributed amount, transfer funds. Nothing else.

What the Architecture Actually Looks Like Now

The flow:

User places bet on-chain. Off-chain: fetch all bets, compute final value, run the inverse distance accuracy model, generate the full reward distribution, build a Merkle tree over it. Admin submits the Merkle root on-chain via submitDistribution. User claims with a proof, the contract verifies the leaf, checks the pool, marks claimed, transfers.

export circuit submitDistribution(
  _merkleRoot: Bytes<32>,
  _totalRewardPool: Uint<128>,
  _claimDeadline: Uint<64>
): Uint<64> {
  // flat writes — no struct overhead
  distRoots.insert(disclose(id), disclose(_merkleRoot));
  distPools.insert(disclose(id), disclose(_totalRewardPool));
  distDistributed.insert(disclose(id), disclose(0 as Uint<128>));
  distDeadlines.insert(disclose(id), disclose(_claimDeadline));
  distStatus.insert(disclose(id), disclose(DistStatus.Active));
  // ...
}

The chain doesn't know how rewards were computed. It doesn't know how many users participated. It doesn't know who won or by how much. It knows exactly one thing: is this leaf in the Merkle tree, and has it been claimed before?

What I Had to Delete (This Is the Important Part)

To make V3 work, I had to remove things I thought were essential:

The full Bet struct: gone. Replaced with a single Uint<128> per user.

The betKeys index map: gone. Off-chain can reconstruct this.

totalParticipants, totalVolume as tracked ledger values: gone. Computable off-chain.

rewardAmount per user: gone. That's a Merkle leaf now.

marketName, description, imageUrl, parameter, category: all gone from on-chain storage.

The entire V2 reward computation pipeline, computeRewardBatch, finalizeRewardBatch, markRewardsFinalized: gone. Replaced by off-chain computation and a Merkle root.

The oracle whitelist, dispute window, resolution proposal system: simplified into a single admin resolve() call.

Everything I deleted felt essential when I wrote it.

The Tradeoff

This is where most people get uncomfortable.

V1 mindset: maximize correctness on-chain. V3 reality: maximize feasibility on-chain.

Yes, there are fewer on-chain guarantees now. The completeness of the reward distribution isn't enforced on-chain. Fairness depends on the off-chain computation being correct. The trust model shifted.

But here's the thing: V1 and V2 had zero on-chain guarantees in practice, because they never executed. A system that doesn't run protects nothing.

V3 actually works.

The Biggest Lesson

Midnight is not EVM with privacy.

It's closer to a constraint system that happens to be programmable. And that changes every design decision from the ground up.

If you're coming from EVM, here's what to unlearn:

"Contracts should compute logic." They shouldn't, not on Midnight.

"Store structured data cleanly." Structs are expensive. Flat maps are cheap.

"Track everything." Track only what the chain needs to enforce.

"Optimize gas." Wrong problem entirely. You're not optimizing cost, you're fitting inside a box.

Replace it with: contracts enforce invariants. State must be minimal. Computation belongs off-chain. Every circuit must fit within constraint limits.

The line that changed everything for me: the chain should not know how something was computed, only whether it is valid.

Closing

I didn't hit Midnight's limits because I wrote bad code.

V1 was well-structured. V2 was genuinely sophisticated. Both failed because I was solving the wrong problem.

Once I changed the mental model, the code became simpler, the circuits became smaller, and the system actually ran.

If you're building on Midnight and want to talk through the architecture before you commit to a direction, or want to see the full repos, find me on X or GitHub.

The walls are documented. You don't have to hit them yourself.

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

[Hands-on] Midnight Deep Dive: Start Building Smart Contracts with Compact

Haruki Kondo — Tue, 14 Apr 2026 15:25:20 +0000

Introduction: The "Too Transparent" Problem of Blockchains

Since the Bitcoin whitepaper was published, blockchain technology has transformed many industries, from finance to supply chains, thanks to its trustless design, transparency, and tamper resistance.

bitcoin.org

The idea that anyone can validate the same distributed ledger and form a trust network without centralized administrators was truly revolutionary.

But complete transparency can also become a major weakness.

What if confidential enterprise data is exposed to competitors?
What if personal transaction history is visible to the entire world?
What if private medical records or voting behavior can be inspected by anyone?

That "too transparent" problem has been one of the biggest barriers preventing public blockchain technology from being widely adopted in enterprise and daily consumer use cases.

To solve this dilemma, a breakthrough project has emerged from the Cardano ecosystem.

That project is Midnight.

Midnight is a Cardano sidechain focused on data protection and privacy.

By leveraging cutting-edge cryptography known as Zero-Knowledge Proofs (ZKPs)[^1], Midnight enables us to prove only the facts we need, without revealing anything else.

ZKPs are often discussed in the context of privacy, but they can also reduce computational overhead depending on how they are used.

Representative examples include ZkEVM and INTMAX, both of which use ZK-based approaches for EVM-related scaling.

INTMAX – Stateless Layer for Billions

INTMAX is a stateless, privacy-centric Layer 2 on Ethereum that delivers fast, secure, and cost-efficient transactions. Explore the future of private digital payments and empower your transactions with unmatched anonymity and speed.

intmax.io

I recently joined the Midnight Hackathon in London and spent a lot of time exploring Compact. In this article, I share what I learned in a hands-on format: from environment setup to contract implementation, testing, and deployment.

Home - Midnight Summit 2025

Midnight Summit 2025: An invitation-only ecosystem event with talks, breakouts and a live Hackathon shaping the future of privacy-first blockchain.

midnightsummit.io

If you want a conceptual introduction to Midnight first, check this article:

Haruki Kondo for Midnight Aliit Fellowship

Apr 13

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

#blockchain #web3 #typescript #zkp

Comments

4 min read

[^1]: Zero-Knowledge Proof (ZKP) is a cryptographic method that lets you prove a statement is true without revealing any additional information (including why it is true).

Compact: A Privacy Smart Contract Language with TypeScript-like Syntax

Another core pillar behind Midnight's innovation is its smart contract language, Compact.

"Isn't zero-knowledge technology only for cryptography experts?"

Compact is designed to dramatically lower that barrier.

TypeScript-based syntax

The biggest feature of Compact is that it is a TypeScript-based domain-specific language (DSL).

That means a large number of web developers can build privacy-preserving applications with familiar syntax, instead of learning an entirely new language from scratch.

The Compact compiler translates your logic into the cryptographic components needed for zero-knowledge proofs, so you do not have to deal with the underlying math directly.

Three data states: Public, Private, Witness

The core of data handling in Compact is clear separation of privacy levels.

Data is mainly handled in three states:

public (public state)
- Data visible on the blockchain.
- Similar to state variables in conventional smart contracts.
- Defined with the ledger keyword.
private (private state)
- Confidential data managed only in a user's local (off-chain) environment.
- The raw private data itself is not recorded on-chain.
- Defined with the private keyword.
witness (proof input)
- Input supplied during transaction execution to prove, "I know this data."
- Used as evidence when updating private state.
- Defined with the witness keyword.

Basic syntax and a Counter smart contract example

Let's look at these concepts through a simple Counter contract.

This contract only increments a number, and is also introduced in official tutorials.

It includes:

A state variable stored on the public ledger
A method to increment that state

pragma language_version >= 0.16 && <= 0.25;
import CompactStandardLibrary;

// Public state stored on the on-chain ledger
export ledger round: Counter;

// Transition function that updates public state
export circuit increment(): [] {
    round.increment(1);
}

ledger: A publicly visible on-chain state variable.
circuit: A transaction-invoked state transition function where validation and updates happen.

With Compact, you can write logic in TypeScript-like syntax while controlling data privacy in detail and proving correctness intuitively.

Hands-on: Set up your Midnight development environment

Now let's move from theory to practice.

In this section, we build the environment needed to run counter.compact.

As of November 2025, frontend integration is still unstable.

So in this hands-on, the goal is to deploy a smart contract and interact with it via CLI.

Required components:

Compact CLI Command-line tool for compiling and testing smart contracts.
Lace Midnight Preview Wallet Browser extension wallet for Midnight Testnet.
Testnet Faucet Service to get test tokens.
ZK Proof Server Local server for generating and verifying zero-knowledge proofs.
Sample repository Source code used in this tutorial.

Step 1: Install Compact CLI

First, install the compact CLI compiler:

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

Then pin a specific version (0.25.0 in this article):

compact update 0.25.0

Check installation:

compact --version
# compact 0.2.0 or similar
compact compile --version
# 0.25.0

If compact compile --version returns 0.25.0, you're good.

Step 2: Prepare Lace Wallet and get Testnet tokens

Next, set up a wallet and receive test tokens.

Install Lace Wallet Add Lace Midnight Preview from the Chrome Web Store.
Create your wallet Follow the setup wizard. Store your recovery phrase securely.
Copy your address From the wallet home screen, click "Receive" and copy your address.
Request faucet funds Open Midnight Testnet Faucet, paste your address, and click "Request funds". After a short wait, test tDUST tokens should arrive.

Step 3: Start ZK Proof Server

Private processing (including proof generation) is handled through a local Proof Server.

We'll start the official Midnight Docker image:

Docker Desktop must be installed for this step.

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

If logs start streaming, it launched successfully. Keep this terminal running.

You can also verify with:

curl -X GET "http://localhost:6300"

Expected response:

We're alive 🎉!

Step 4: Prepare sample repository

Finally, set up the repository used in this article:

mashharuki / midnight-sample

midnightでの開発事前検証用リポジトリ

midnight-sample

midnightでの開発事前検証用リポジトリ

環境

nodejs
yarn
docker
compact CLI

compact CLIのインストール

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

その後、以下でバージョン指定

compact update 0.25.0

インストールされているかの確認

compact --version
compact compile --version

それぞれ以下のようになればOK!

compact 0.2.0
0.25.0

Testnet用のZKProof serverの起動

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

docker ps

localhost:6300でサーバーが起動していればOK

CONTAINER ID   IMAGE                          COMMAND                  CREATED          STATUS          PORTS                                         NAMES
a62d9787f7a1   midnightnetwork/proof-server   "/nix/store/qa9fb15p…"   25 seconds ago   Up 24 seconds   0.0.0.0:6300->6300/tcp, [::]:6300->6300/tcp   flamboyant_roentgen

念の為以下のコマンドでも稼働確認

curl -X GET "http://localhost:6300"

We're alive 🎉!

サンプルプログラムのコンパイル＆デプロイ手順

まず、依存関係をインストールする

yarn

以下のコマンドでコントラクトをビルドする

yarn contract compact

以下のようになればOK!

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

コントラクトのユニットテストコードを実行する

yarn contract test

以下のようになればOK!

 RUN  v4.0.8 /workspaces/midnight-sample/my-mn-app/pkgs/contract
 ✓ test/counter.test.ts (3 tests) 44ms
   ✓ Counter smart contract (3)
     ✓ generates initial ledger state deterministically 36ms
     ✓ properly initializes ledger

…

View on GitHub

# Clone your own fork
# (fork the repository first)
git clone https://github.com/<user-name>/midnight-sample.git
cd midnight-sample

# Install dependencies
yarn

Replace the git clone URL with your actual repository URL.

Environment setup is now complete.

Next, let's implement and test the smart contract.

Implement and test the Counter contract

With the environment ready, let's build and test.

Code walkthrough

Put this contract in pkgs/contract/src/counter.compact:

pragma language_version >= 0.16 && <= 0.25;
import CompactStandardLibrary;

// Public state stored on the on-chain ledger
export ledger round: Counter;

// Transition function that updates public state
export circuit increment(): [] {
    round.increment(1);
}

Then compile with compact CLI:

yarn contract compact

Under the hood:

compact compile ./src/counter.compact ./src/managed/counter

On success, you will see output like:

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

Unit test implementation

Compact lets you simulate contract logic off-chain for testing.

See pkgs/contract/src/test/counter.test.ts:

import { CounterSimulator } from "./counter-simulator.js";
import {
  NetworkId,
  setNetworkId
} from "@midnight-ntwrk/midnight-js-network-id";
import { describe, it, expect } from "vitest";

setNetworkId(NetworkId.Undeployed);

/**
 * Unit tests for the Counter contract
 */
describe("Counter smart contract", () => {
  it("generates initial ledger state deterministically", () => {
    const simulator0 = new CounterSimulator();
    const simulator1 = new CounterSimulator();
    expect(simulator0.getLedger()).toEqual(simulator1.getLedger());
  });

  it("properly initializes ledger state and private state", () => {
    const simulator = new CounterSimulator();
    const initialLedgerState = simulator.getLedger();
    expect(initialLedgerState.round).toEqual(0n);

    const initialPrivateState = simulator.getPrivateState();
    expect(initialPrivateState).toEqual({ privateCounter: 0 });
  });

  it("increments the counter correctly", () => {
    const simulator = new CounterSimulator();
    const nextLedgerState = simulator.increment();
    expect(nextLedgerState.round).toEqual(1n);

    const nextPrivateState = simulator.getPrivateState();
    expect(nextPrivateState).toEqual({ privateCounter: 0 });
  });
});

These tests verify three scenarios:

Contract initialization is deterministic.
Initial ledger value is 0.
increment updates the counter correctly.

Run tests

Run:

yarn contract test

If all tests pass, output looks like:

RUN  v4.0.8 /workspaces/midnight-sample/my-mn-app/pkgs/contract

 ✓ test/counter.test.ts (3 tests) 44ms
   ✓ Counter smart contract (3)
     ✓ generates initial ledger state deterministically 36ms
     ✓ properly initializes ledger state and private state 3ms
     ✓ increments the counter correctly 4ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  08:27:47
   Duration  421ms (transform 95ms, setup 0ms, collect 233ms, tests 44ms, environment 0ms, prepare 13ms)

JUNIT report written to /workspaces/midnight-sample/my-mn-app/pkgs/contract/reports/report.xml
Done in 1.34s.

Now that we know the logic works, let's create the CLI flow to deploy on Testnet.

Deploy and execute from CLI on Testnet

After local testing, it's time to deploy.

The pkgs/cli package contains scripts for deployment and contract interaction.

Generate TypeScript API

First, build the contract package:

yarn contract build

This runs commands like:

rm -rf dist && tsc --project tsconfig.build.json && cp -Rf ./src/managed ./dist/managed && cp ./src/counter.compact ./dist

This generates typed APIs so circuits like increment can be called safely from the cli package.

Set environment variables

Deploying to Testnet requires the wallet seed used to sign transactions.

Create .env from template in pkgs/cli:

cp pkgs/cli/.env.example pkgs/cli/.env

Edit pkgs/cli/.env:

NETWORK_ENV_VAR=testnet
SEED_ENV_VAR=
INITIAL_COUNTER_ENV_VAR=
CACHE_FILE_ENV_VAR=
CONTRACT_ADDRESS=

Handle your seed with extreme care.

Make sure this file is excluded by .gitignore and never pushed to GitHub.

CLI unit test walkthrough

There are also unit tests for the CLI layer.

// This file is part of midnightntwrk/example-counter.
// Copyright (C) 2025 Midnight Foundation
// SPDX-License-Identifier: Apache-2.0
// Licensed under the Apache License, Version 2.0 (the "License");
// You may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import { type Resource } from '@midnight-ntwrk/wallet';
import { type Wallet } from '@midnight-ntwrk/wallet-api';
import path from 'path';
import * as api from '../api';
import { type CounterProviders } from '../utils/common-types';
import { currentDir } from '../config';
import { createLogger } from '../utils/logger-utils';
import { TestEnvironment } from './commons';
import { describe, it, expect, beforeAll, afterAll } from 'vitest';

const logDir = path.resolve(currentDir, '..', 'logs', 'tests', `${new Date().toISOString()}.log`);
const logger = await createLogger(logDir);

describe('API', () => {
  let testEnvironment: TestEnvironment;
  let wallet: Wallet & Resource;
  let providers: CounterProviders;

  beforeAll(
    async () => {
      api.setLogger(logger);
      testEnvironment = new TestEnvironment(logger);
      const testConfiguration = await testEnvironment.start();
      wallet = await testEnvironment.getWallet();
      providers = await api.configureProviders(wallet, testConfiguration.dappConfig);
    },
    1000 * 60 * 45,
  );

  afterAll(async () => {
    await testEnvironment.saveWalletCache();
    await testEnvironment.shutdown();
  });

  it('should deploy the contract and increment the counter [@slow]', async () => {
    const counterContract = await api.deploy(providers, { privateCounter: 0 });
    expect(counterContract).not.toBeNull();

    const counter = await api.displayCounterValue(providers, counterContract);
    expect(counter.counterValue).toEqual(BigInt(0));

    await new Promise((resolve) => setTimeout(resolve, 2000));

    const response = await api.increment(counterContract);
    expect(response.txHash).toMatch(/[0-9a-f]{64}/);
    expect(response.blockHeight).toBeGreaterThan(BigInt(0));

    const counterAfter = await api.displayCounterValue(providers, counterContract);
    expect(counterAfter.counterValue).toEqual(BigInt(1));
    expect(counterAfter.contractAddress).toEqual(counter.contractAddress);
  });
});

Run these tests on both local and testnet environments.

Run unit tests locally

yarn cli test-api

Expected:

Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  08:41:12
   Duration  200.97s (transform 180ms, setup 72ms, collect 1.11s, tests 199.62s, environment 0ms, prepare 10ms)

Run unit tests against testnet

yarn cli test-against-testnet

Expected:

✓ src/test/counter.api.test.ts (1 test) 151857ms
  ✓ API (1)
    ✓ should deploy the contract and increment the counter [@slow]  125059ms

Test Files  1 passed (1)
    Tests  1 passed (1)
  Start at  08:47:54
  Duration  153.65s (transform 205ms, setup 93ms, collect 1.56s, tests 151.86s, environment 0ms, prepare 8ms)

Deployment script walkthrough

pkgs/cli/scripts/deploy.ts deploys the contract to Testnet.

It uses libraries such as @midnight-ntwrk/midnight-sdk and performs the following steps:

Load wallet seed from .env.
Build wallet object from the seed.
Configure providers for Testnet connection.
Execute deployment via api.deploy.

Run deployment

Deploy with:

yarn cli deploy

On success, the deployed contract address appears in terminal output:

[12:16:24.603] INFO (39506): Deploying counter contract...
[12:17:27.488] INFO (39506): Deployed contract at address: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
[12:17:27.488] INFO (39506): Deployment transaction: 00000000c408a293e4e287285649623774b2be950bf0d385a20117ce79a99eb7315aa547
[12:17:27.489] INFO (39506): Contract address: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
Counter contract deployed at: 020050e6bdae4c9e65023a252a6aba74323c1d9c1ba6e520f00e84a5fc1c75b100f3
[12:17:27.489] INFO (39506): Not saving cache as sync cache was not defined
Done in 90.16s.

Set that value in CONTRACT_ADDRESS inside your .env.

Execute `increment`

Finally, call the deployed contract's increment circuit.

Run:

yarn cli increment

This script reads CONTRACT_ADDRESS from .env, connects to the existing contract with api.joinContract, then calls api.increment.

If successful, you should see transaction info and the current counter value:

[12:33:37.176] INFO (47085): Incrementing...
[12:34:34.270] INFO (47085): Transaction 000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 added in block 2485067
[12:34:34.271] INFO (47085): Increment transaction: 000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 (block 2485067)
Counter incremented. txId=000000000202acbcd05e9f19e5144acc5f97953255840b8b932fc71b84520e715b7ca900 block=2485067
[12:34:34.271] INFO (47085): Checking contract ledger state...
[12:34:34.462] INFO (47085): Ledger state: 1
[12:34:34.463] INFO (47085): Current counter value: 1
[12:34:34.463] INFO (47085): Current counter value: 1
Current counter value: 1
[12:34:34.463] INFO (47085): Not saving cache as sync cache was not defined
Done in 128.20s.

If Current counter value: 1 appears, your public counter was incremented successfully.

This completes the hands-on section.

Current limitations and what's next

As of November 2025, Midnight is still in developer Testnet phase, and Mainnet has not launched yet.

So keep the following in mind:

Performance Finality on Testnet can take time.
API changes SDK/CLI behavior may change during active development. Check official docs regularly.
Feature scope Available tooling is still limited, though development is moving quickly with community feedback.
Frontend integration This was the area that took me the most research time during the hackathon. I also confirmed with the Midnight team onsite that stable frontend-contract integration libraries were not yet available at that time, so CLI was the practical path.

Midnight is a very ambitious project tackling one of Web3's most important challenges: privacy.

With Cardano's strong security model and community behind it, this ecosystem is definitely worth watching.

Closing thoughts

In this article, we walked through Midnight, Cardano's privacy-focused sidechain, and Compact, its smart contract language, in a practical hands-on format.

Midnight's approach to the blockchain "too transparent" problem.
Compact language for intuitive private DApp development with TypeScript-like syntax.
Data modeling with public, private, and witness.
Full flow from environment setup to implementation, testing, and Testnet deployment.

I am very excited to see how this evolves.

The hackathon itself was also an amazing experience, so I will keep following upcoming updates.

Thanks for reading.

References

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

Haruki Kondo — Mon, 13 Apr 2026 14:08:48 +0000

Introduction: The "Too Transparent" Problem in Blockchain

Seventeen years have passed since the Bitcoin whitepaper was released.

bitcoin.org

Blockchain's immutability and transparency have been praised as groundbreaking mechanisms for trustworthy transactions. Because anyone can verify the ledger, blockchains created a new model of tamper-resistant trust.

However, that same "complete transparency" also creates barriers in areas involving business and personal privacy. This issue has been especially clear in enterprise settings, which is one reason private chain adoption became popular.

What if your full banking transaction history were visible to anyone in the world?
What if a company's confidential supply chain information were exposed to competitors?
What if personal medical records or voting history became public?

Even imagining this is unsettling. I believe this "too transparent" problem is one of the key reasons blockchain technology has not yet fully penetrated all parts of society.

Not everything can be public all the time. To solve this dilemma, a new light has emerged: Midnight.

Midnight Documentation | Midnight Docs

Build privacy-preserving applications with selective disclosure and zero-knowledge proofs on Midnight.

docs.midnight.network

Midnight is Cardano's partner chain (sidechain) specialized for data protection and privacy. In this article, I will guide you through Midnight in a story-driven way so you can understand its innovative technology and future potential.

Chapter 1: What Is Midnight? - A New Blockchain for Privacy

In one sentence, Midnight is a data-protection blockchain that enables Selective Disclosure. While many traditional blockchains force everything to be public, Midnight makes it possible to prove only the facts that need to be proven, without revealing anything else.

Note
There are other blockchains, such as Zcash, that adopt similar privacy-oriented approaches.

The technology that enables this is Zero-Knowledge Proofs (ZKPs).

Architecture Overview

Comparison of Traditional Blockchain vs Midnight with ZKPs

I have another article dedicated to Zero-Knowledge Proofs (ZKPs), so feel free to check that out as well:

【図解】ゼロ知識証明のPLONKとは？Groth16との違いを世界一わかりやすく解説！

zenn.dev

What Midnight aims to achieve

Midnight's mission is to remove the long-standing trade-off between data protection, ownership, and data utility.

For users: They can fully control their own data and decide who can see what, and how much.
For developers and enterprises: They can build innovative data-driven services without taking on privacy-violation risk.

This opens the door to use cases that were previously difficult or impossible on public blockchains due to confidentiality requirements.

Midnight's core: architecture and consensus

As a Cardano partner chain, Midnight is built on top of Cardano's robust security infrastructure.

Architecture: Midnight splits smart contract state into two parts:
1. Public state: Data that remains publicly available on-chain.
2. Private state: Data each user manages off-chain in their own local environment.
Kachina protocol: Public and private states are linked securely through Kachina, a research-driven unified framework. Users generate ZK proofs locally using private data, then submit only the proof to the blockchain for verification.
Consensus algorithm: Midnight adopts a hybrid consensus model combining AURA (block production) and GRANDPA (finality). Cardano stake pool operators (SPOs) participate as block producers.

Two native tokens: NIGHT and DUST

Midnight uses a unique dual-token model.

Token	Role	Characteristics
NIGHT	Governance, consensus	Unshielded token. Tradable and contributes to network security.
DUST	Transaction fees (gas)	Shielded resource. Non-transferable and privacy-preserving.

DUST acts as fuel, but because it is not a tradable asset, transaction metadata privacy is better preserved while keeping service costs more predictable.

Chapter 2: The Bond with Cardano - Why a Partner Chain?

Midnight is an independent chain, but its deep integration with Cardano is what unlocks its full potential.

Ecosystem Integration

Strategic integration between Cardano and Midnight Network

Inheriting security

Midnight addresses the challenge of network security by becoming a Cardano partner chain. It leverages Cardano's large, decentralized SPO network, allowing Midnight to access globally distributed, enterprise-grade infrastructure from day one.

How Midnight differs from Cardano

Cardano: Focuses on value storage/transfer and serving as a secure general-purpose decentralized platform.
Midnight: Uses Cardano's security as a base while specializing in データ保護とプライバシー as a dedicated computation layer.

They are complementary: Cardano provides the trust foundation, while Midnight enables privacy-sensitive applications.

Chapter 3: Compact - ZKP Smart Contracts with TypeScript-like Syntax

Note
"Aren't zero-knowledge proofs only for cryptography specialists?"

Midnight addresses this challenge with a new smart contract language: Compact.

midnightntwrk / compact

Compact Releases

Compact

Compact is the Midnight Network's smart contract language. This repository is only used to host Compact releases.

Contributing to Compact

The project welcomes contributions. If you would like to report a Compact bug, make a feature request, get the source code, etc. then you should do so at the Minokawa project's Compact repository.

View on GitHub

Why Compact is exciting

TypeScript-based DSL: Based on one of the world's most popular languages, allowing web developers to build privacy-focused apps with familiar syntax.
Abstraction of ZK complexity: The Compact compiler translates contract logic into the cryptographic material required for proof generation.
Privacy by Design: Data is treated as private by default. To expose private data, you must explicitly wrap it with disclose().

// Conceptual Compact example

// Private user vote
witness userVote: private Field;

// Public vote result
let results: public Field;

// Voting circuit
circuit vote() {
  // Update result when validation passes
  // Who voted for what remains private
  results = results + 1;

  // If you want to reveal vote content, do it explicitly
  // disclose(userVote);
}

Chapter 4: Use Cases Unlocked by Midnight

Digital ID / KYC: Prove you are over 18 without revealing your full birth date.
Anonymous voting: Truly fair voting systems with verified eligibility and ballot secrecy.
Healthcare: Private medical records used for aggregate analysis or AI research.
DeFi: Access financial services without exposing portfolios or strategies.
AI and LLMs: Use sensitive data for model training while preserving privacy.

Summary: The Dawn of a New Privacy Era

Midnight is foundational technology for a safer, fairer digital society where individuals retain data sovereignty and enterprises can innovate responsibly.

Thank you for reading! 🚀

Developer Resources

Midnight Developer Hub
midnightntwrk / midnight-awesome-dapps

Midnight Awesome Dapps
Awesome Midnight dApps

This project is built on the Midnight Network.

A curated list of awesome Midnight dApps, tools, and resources

Contents
- Awesome Midnight dApps
  
  Contents
  
  Getting Started
  
  Smart Contract Primitives
  
  Starter Templates
  
  Developer Tools
  
  Finance & DeFi
  
  Identity & Privacy
  
  Gaming
  
  Governance
  
  Dormant Projects
  
  Learning Resources
  
  Documentation
  
  Getting Started
  
  Tutorials
  
  Community
  
  Community Projects
  
  Contributing
  
  Submission Criteria
  
  License
Important

Community-contributed projects are shared for inspiration and exploration. These repositories are not maintained by the Midnight team, and their functionality may vary.

Note

🔹 = Official Midnight Ecosystem Partner
🏆 = Hackathon winners

Getting Started

Official dApps and tools maintained by the Midnight team (for education + onboarding)
- Example Counter - Simple increment/decrement app demonstrating state management
- Hello World Compact - Minimal Hello World smart contract for Midnight. Deploy to Preprod and store/read messages on-chain
- Example Bboard - Bulletin board with multi-user interactions and privacy patterns
- Example ZK Loan - ZK-powered…
View on GitHub
MeshJS / midnight-starter-template

Mesh Midnight starter template
🚀 EDDA - Midnight Starter Template
- A starter template for building on Midnight Network with React frontend and smart contract integration.
- Live Demo → counter.nebula.builders
📦 Prerequisites
- Node.js (v23+) & npm (v11+)
- Docker
- Git LFS (for large files)
- Compact (Midnight developer tools)
- Lace (Browser wallet extension)
- Faucet (Preview Network Faucet)
Known Issues
- There’s a not-yet-fixed bug in the arm64 Docker image of the proof server.
- Workaround: Use Bricktower proof server. bricktowers/proof-server:6.1.0-alpha.6
🛠️ Setup

1️⃣ Install Git LFS
# Install and initialize Git LFS sudo dnf install git-lfs # For Fedora/RHEL git lfs install
2️⃣ Install Compact Tools
# Install the latest Compact tools curl --proto '=https' --tlsv1.2 -LsSf \ https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh
# Install the latest compiler # Compact compiler version 0.27 should be downloaded manually. Compact tools does not support it currently. compact update +0.27.0
3️⃣ Install Node.js and docker
- Node.js & npm
- Docker
4️⃣ Verify Installation
…
View on GitHub

References

Blockchain from the Ground Up: What It Is, Why It Exists, and Where It's Going

Gutopro — Thu, 09 Apr 2026 20:10:16 +0000

A plain-language breakdown for anyone who's ever been confused by the word "blockchain".

So What Is the Blockchain?

The blockchain is basically a group of computers agreeing upon a single truth. These computers all have copies of this truth, and a single alteration on one changes every copy.

Think of it like a notebook that thousands of people have identical copies of. Every time something new is written in it, the entries are grouped together into a page — that page is what we call a block.

Each new entry is mathematically locked to the one before it — like a chain — so you can't go back and alter a page without breaking every page that came after it. And here's the interesting part — no single person owns that notebook. No bank, no government, no tech company. It belongs to everyone and no one at the same time.

This is what makes it powerful. Because there's no central authority controlling it, nobody can secretly alter the records, freeze your funds, or shut it down. The truth is just... out there, maintained by the network itself.

That's the blockchain — a shared, tamper-resistant record that nobody owns but everybody can trust.

Why Was the Blockchain Created?

The blockchain was created to solve one problem: centralization.

In the traditional financial system, banks and institutions have total control over every dime in circulation — they can freeze accounts, fail, or act in their own interest.

In 2008, during the global financial crisis, Satoshi Nakamoto asked: how do we give everybody direct ownership over their assets, without needing to trust a middleman? The answer was decentralization — and that's what blockchain makes possible.

The Blockchain Financial Economy

For centuries, if you wanted to send money, save, invest, or borrow — you needed a middleman. A bank, a broker, an institution. They held the keys to the financial world, and you played by their rules.
The blockchain changed that.

By creating a system where value can be stored and transferred without a middleman, blockchain opened the door to an entirely new financial economy — one that runs on code instead of institutions.

At the heart of this economy is cryptocurrency. Just like the naira or the dollar, crypto is money — except no central bank prints it or controls it. It lives on the blockchain, and its rules are written in code that nobody can secretly change.
But it goes deeper than just currency.

The blockchain financial economy introduced something called DeFi — Decentralized Finance. Think of everything a bank does: savings, loans, investments, payments. DeFi does all of that, but without the bank. Just open protocols that anybody with an internet connection can access, anywhere in the world.

This matters especially for the billions of people who have been locked out of the traditional financial system — no bank account, no credit history, no access. The blockchain doesn't ask for any of that. If you have a wallet, you're in.

It's not a perfect system — it has its risks and its chaos. Crypto prices can be wildly volatile — an asset worth a lot today can lose half its value by tomorrow.

Scams and fraud are rampant because there's no central authority to report to or reverse a bad transaction. If you send money to the wrong address or lose access to your wallet, it's gone. No customer service, no refund.

DeFi protocols have also been exploited for hundreds of millions of dollars through smart contract bugs and loopholes.

The code is the law — which is great when it works, and brutal when it doesn't. But for the first time in history, we have a financial economy that doesn't require you to trust anyone. Just the math.

Midnight — The Blockchain Built for the Real World

The blockchain financial economy opened up a lot of possibilities. But it came with a problem nobody fully solved — privacy.

Every transaction on most blockchains is public. Anyone can look up your wallet, see your balance, trace your history. For individuals that's uncomfortable. For businesses, it's a deal breaker. You can't run a company on a system where your competitors can see every payment you make.

That's the problem Midnight was built to solve.
Midnight is a blockchain that puts privacy at its core — not as an afterthought, but as the foundation. It's built by Input Output, the same team behind Cardano, and it introduces a new idea: you should be able to prove something is true without revealing everything behind it.

Imagine proving you're old enough to buy something without showing your date of birth. Or proving you have enough funds for a transaction without exposing your full balance. That's the kind of thing Midnight makes possible, through a technology called zero-knowledge proofs.
But Midnight doesn't throw away accountability entirely.

It's designed to balance privacy with compliance — so individuals and businesses can protect their sensitive data while still operating within legal and regulatory boundaries.

This is what makes Midnight different. Not just another blockchain, but an attempt to build the infrastructure for a world where people and businesses can participate in the decentralized economy on their own terms — without sacrificing privacy to do it.

The blockchain gave us financial freedom. Midnight is trying to give us financial freedom with dignity.

Thanks for reading. If this series helped you understand blockchain a little better, follow along — there's more coming.

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

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

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

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

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

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

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

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

What the Problem Actually Looks Like

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

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

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

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

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

What Midnight Wallet Kit Gives You

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

npm install midnight-wallet-kit

Setup

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

const manager = new WalletManager();

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

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

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

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

The Four Hooks

`useWallet()`: connection state

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

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

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

`useConnect()`: connection management

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

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

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

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

`useIntent()`: signing

const { buildAndSign, signMessage } = useIntent();

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

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

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

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

`useBalance()`: balance polling

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

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

The Architecture: Why It's Built This Way

Adapters normalize the provider chaos

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

Wallet modes are explicitly typed:

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

WalletManager handles the lifecycle

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

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

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

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

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

Middleware for observability

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

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

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

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

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

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

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

Testing Without a Browser Extension

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

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

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

manager.register(adapter);

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

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

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

SSR and Next.js

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

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

What's Next

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

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

Troubleshooting Midnight Pre-Prod: A Week in the Trenches

Gutopro — Wed, 08 Apr 2026 08:30:29 +0000

Building on Midnight feels like being on the frontier of Web3. Between the Zero-Knowledge (ZK) primitives and the unique dual-token model, there is a lot to love—but being an early adopter means running into some undocumented "features."

I spent this week building on the Midnight pre-prod network from scratch. While the documentation is improving, I encountered several blockers that weren't immediately obvious. I also spent a lot of time in the Discord monitoring common pitfalls other devs are hitting.

If you are setting up your Midnight environment today, bookmark this. Here is how to fix the most common environment issues.

1. The "Invalid Address" Faucet Trap
The Issue: You try to fund your wallet using the Lace faucet, but it returns an "Address provided was invalid" error, even after you confirm you are on the pre-prod network.

The Fix: Switch to the 1AM wallet.

Crucial Step: You must set the wallet to the pre-prod network BEFORE you copy your address. A mainnet address string—even if generated by the same seed—will not be recognized by the pre-prod faucet.

// Set network to preprod
setNetworkId('preprod');

2. Deployment Failures (deploy.ts)
The Issue: Your deploy.ts script fails to create or connect to a wallet. This usually happens because the default configuration in many boilerplate templates doesn't align with the 1AM wallet's requirements.

The Fix: This is a two-step process that is currently undocumented:

Replace your pre-prod configuration file with the specific 1AM network config.

// Preprod network configuration
const CONFIG = {
  indexer: 'https://indexer.preprod.midnight.network/api/v4/graphql',
  indexerWS: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
  node: 'https://rpc.preprod.midnight.network',
  proofServer: 'http://127.0.0.1:6300',
};

Use the CLI to create your wallet after you have integrated that new config.
Doing only one of these will result in a hang. You need both to bridge the gap between the script and the network.

3. DUST Registration Timing Out
The Issue: You attempt to register for DUST, but the process hangs or fails repeatedly.

The Fix: This shares the same root cause as the deployment issue. If your config is pointing even slightly off-target, the registration handshake won't complete. Ensure you are using the 1AM network configuration before you even attempt the registration command.

4. The "Ghost DUST" Bug
The Issue: Several devs in Discord reported getting a green "Success" checkmark on the faucet, but no tDUST arrives, even after 48 hours.

The Fix: Currently, the most reliable workaround is to use the 1AM wallet specifically. In most cases, DUST credits immediately there, whereas Lace is seeing intermittent sync issues with the faucet during this pre-prod phase.

5. Unexpected Gas Drainage
The Issue: You’re building, and suddenly everything stops working because your tDUST balance is zero.

The Fix: Remember that every write operation consumes tDUST as gas. Because we are in a ZK environment, these costs can add up during heavy testing.

Pro-Tip: Use the 1AM Explorer to track your transaction history and gas per interaction. Refuel from the faucet proactively rather than waiting for a failure.

6. Contract Interaction "De-sync"
The Issue: Your contract interactions work for a while, then suddenly start failing mid-session without code changes.
_
The Fix_: The wallet (specifically Lace) sometimes loses sync with the chain or suffers an authentication timeout.

The Workflow: Manually click Sync in your wallet before every contract interaction. It feels redundant, but it prevents the "ghost failures" that catch most devs off guard.

My "Golden" Setup
If you want a stable environment to actually write code, here is the stack I currently have running successfully:

Runtime: Node 22
Compiler: Latest Compact compiler
Wallet: 1AM wallet (on pre-prod)
Workflow: Wallet created via CLI using 1AM config
Infrastructure: Proof server running locally via Docker

Verification: Contracts deployed and verified via 1AM Explorer

What’s Next?
I’m currently working through Midnight 301 (Advanced ZK DApp Development), building a privacy-preserving bulletin board. I’ll be documenting the full build-out as I go.

If you're stuck on a specific error, drop a comment or find me in the Midnight Discord. Let's build.

midnight #zkproofs #blockchain #web3 #tutorial

Zero-Knowledge, Zero Friction: Automating DApp Development on Midnight

Nasihudeen Jimoh — Tue, 07 Apr 2026 22:30:27 +0000

This article provides a step by step deep dive into Midnight Pulse, a collaborative analytics tool built to showcase the power of the Midnight SDK Generator. We'll walk through the entire lifecycle: from defining a privacy preserving smart contract in Compact to building a multi user CLI application in TypeScript.

The Vision: Privacy at Scale

The goal of Midnight Pulse is to allow a team to compute a "salary pulse" a benchmark average without any individual ever revealing their sensitive data to anyone else (not even a central server).

We solve this using Zero-Knowledge (ZK) proofs and a strict Anonymity Threshold ($N \ge 5$). The logic is simple: the application won't let you see the results until at least 5 people have joined.

The Problem: The "Glue Code" Friction

Developing on Midnight involves interacting with ZK-circuits and a private ledger. Manually writing the TypeScript glue code to call these circuits and read ledger state is:

Error-prone: Manual type mapping can lead to runtime failures.
Maintenance-heavy: Every contract change requires a manual update to the SDK.
Boilerplate-intensive: Setting up contract stubs and providers involves repetitive code.

The Midnight SDK Generator solves this by deriving a production-ready SDK directly from your contract's metadata.

The Privacy Contract (`salary.compact`)

Everything starts with the contract. Using Compact, we define what data is public and what logic is private.

The Ledger

We store the aggregate metrics (Sum and Headcount) on the Shielded Ledger. This means the data is encrypted on-chain, and only the contract logic can update it.

export ledger {
  total_salary_sum: Uint64,
  employee_count: Uint64
};

The "Submit" Circuit

When a user submits their salary, they don't send the value in the clear. Instead, they run a circuit that privately adds their value to the aggregate.

export circuit submit_salary(salary: Uint64): [] {
  const current_sum = ledger.total_salary_sum;
  const current_count = ledger.employee_count;

  ledger.total_salary_sum = current_sum + salary;
  ledger.employee_count = current_count + 1;
}

The "Benchmark" Circuit (Anonymity Check)

This is where the privacy guarantee is enforced. The circuit checks the employee_count before performing the comparison.

export circuit is_above_benchmark(my_salary: Uint64): Boolean {
  const count = ledger.employee_count;
  const total = ledger.total_salary_sum;

  // The Privacy Gate: Revert if less than 5 people have joined
  check(count >= 5) "Threshold Error: N < 5 contributors";

  const average = total / count;
  return my_salary > average;
}

Generating the SDK

Once the contract is written, we use the SDK Generator to bridge the gap between Compact and TypeScript.

1. Compile to Metadata

First, use the compact compiler to generate a structured JSON representation of your contract.

compact compile ./contracts/salary.compact

2. Generate the SDK

Once you have your salary.structure.json, use the generator to create your type-safe SDK:

midnight-sdk-gen ./contracts/salary.structure.json --output ./src/sdk/SalarySDK.ts

Type Mapping Support

The generator automatically maps Compact types to their most appropriate TypeScript equivalents, so you never have to guess:

Compact Type	TypeScript Type
`Boolean`	`boolean`
`Uint<N>`	`bigint`
`Bytes<N>`	`Uint8Array`
`Maybe<T>`	`T
{% raw %}`Vector<N, T>`	`T[]`

The Application Layer (`pulse.ts`)

With the generated SDK, building the CLI tool is straightforward. We use an Agentic Pattern to simulate multiple participants.

1. Initializing Providers

We first set up the Midnight network context (Wallet, Proof Server, Indexer). Our providers.ts bridge allows us to toggle between Fast Simulation and the Local Docker Network.

const env = process.env.MIDNIGHT_ENV || "simulated";
const providers = await getProviders(env);

2. Deploying the Contract

The team leader (or a smart contract factory) deploys the instance using the generated deploy method.

import { SalarySDK } from "./sdk/SalarySDK";

const sdk = await SalarySDK.deploy(providers);
const contractAddress = sdk.handle.address;

3. Orchestrating the Users

We loop through our simulated agents (Alice, Bob, Carol, Dave, Eve). Each agent joins the contract and submits their salary.

for (const agent of agents) {
  // Join the same shared contract address using the generated SDK
  const agentSdk = await SalarySDK.join(contractAddress, agent.providers);

  // Submit salary privately via the ZK circuit
  // The SDK handles all witness and proof management
  await agentSdk.submit_salary(agent.witness);

  // Log progress using side-by-side observability
  const publicState =
    await agentSdk.providers.publicDataProvider.queryContractState(
      contractAddress,
    );
  StateObserver.displayPulse(agent, publicState);
}

4. Running the Benchmark

Finally, Carol checks if she is above the average. Because all 5 agents have now submitted, the $N \ge 5$ check in the circuit passes successfully.

const isAbove = await carolSdk.is_above_benchmark(carol.witness);
StateObserver.displayResult("Carol", isAbove);

Observability (The Pulse)

One of the biggest challenges in ZK development is "blind debugging." To solve this, i built a StateObserver to visualize the delta of privacy.

Side-by-Side Verification

The terminal output provides a side-by-side view. As you can see below, the Public State tracks the group metrics, while the Private State remains strictly isolated in the user's local witness.

--- [Alice] Status ---

    ┌──────────────────────────────┬──────────────────────────────┐
    │ PUBLIC STATE               │ PRIVATE STATE              │
    ├──────────────────────────────┼──────────────────────────────┤
    │ Total Sum:   92,000          │ My Salary:   92,000          │
    │ Headcount:   1               │ ZK-Proof:    VALID          │
    └──────────────────────────────┴──────────────────────────────┘

This allows the developer to verify that privacy is actually being maintained—Alice can see the total sum grow, but she never sees Bob's individual contribution.

Conclusion: The New Way to Build ZK

Midnight Pulse proves that building ZK applications doesn't have to be hard. By using Compact for privacy logic and the SDK Generator for the application layer, we can build sophisticated, privacy preserving systems with standard TypeScript skills.

Key Takeaways:

Zero Maintenance: Changing your contract automatically updates your SDK types.
Type Safety: No more runtime errors from incorrect type mapping.
Developer Velocity: Focus on your dApp logic, not the cryptographic plumbing.

See the Pulse in 60 seconds

Clone the repository and run the multi-agent simulation on your own machine:

git clone https://github.com/Kanasjnr/midnight-pulse-sdk-demo
cd midnight-pulse-sdk-demo
npm install && make run

Advanced Compact Patterns for Web3 Developers

Nasihudeen Jimoh — Thu, 02 Apr 2026 20:08:39 +0000

Introduction

If you've spent years building on EVM chains, Midnight's architecture might feel like a paradigm shift. On Ethereum, you push computation onto the blockchain itself. On Midnight, you do the opposite you move computation off-chain and prove it correctly using zero-knowledge proofs.

This isn't just a different implementation detail. It fundamentally changes how you think about state management, data disclosure, and circuit design.

Samantha's foundational guide introduced the three-part structure of Midnight contracts: the public ledger, zero-knowledge circuits, and local computation. But understanding the basics and architecting production systems are two different challenges.

This guide dives into the patterns that separate working prototypes from robust systems. We'll explore how witnesses enable privacy boundaries, why commitments matter more than direct state, how to optimize circuits for real-world constraints, and how to compose multiple private contracts without leaking metadata.

By the end, you'll have concrete strategies for building systems that maintain privacy guarantees while managing the practical tradeoffs of Web3 applications.

Witnesses & Selective Disclosure

Understanding Witnesses Beyond Function Calls

In EVM contracts, all data available to a function is deterministic. The blockchain is your single source of truth. In Compact, witnesses invert this model: witnesses are the only source of truth the contract doesn't control.

// A witness declares a contract's dependency on external data
witness getUserSecret(): Bytes<32>;
witness getProofOfAssets(userId: Uint<64>): AssetsProof;

When you declare a witness, you're saying: "This contract's logic depends on data I cannot verify on-chain. It's the application's responsibility to provide this correctly."

This creates a critical security boundary. The contract trusts the application to supply honest witnesses, but the proof system validates that the application used those witnesses correctly.

The Witness-Disclosure Loop

Real-world contracts don't just consume witnesses they combine witness data with disclosed state to create privacy preserving outcomes.

Consider an age verification system:

pragma language_version 0.22;
import CompactStandardLibrary;

// Public ledger: only record that someone proved they're eligible
export ledger ageVerified: Map<Bytes<32>, Boolean>;
export ledger verificationRound: Counter;

// Private witness: the user's actual birthdate (never on-chain)
witness getUserBirthDate(): Uint<32>; // Unix timestamp

// Derived public key with round counter to prevent replay
circuit derivePublicIdentity(round: Field, secret: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>(
    [round as Bytes<32>, secret]
  );
}

// Main circuit: prove age without revealing birthdate
export circuit verifyAge(secret: Bytes<32>, minAge: Uint<32>): [] {
  // Get private birthdate (witness - not on-chain)
  const birthDate = getUserBirthDate();

  // Compute age
  const currentTimestamp: Uint<32> = 1704067200; // Updated by app
  const age = currentTimestamp - birthDate;

  // Private check: verify age requirement
  assert(age >= minAge, "Age requirement not met");

  // Public disclosure: only record that verification happened
  const identity = derivePublicIdentity(verificationRound.roundNumber, secret);
  ageVerified = disclose(identity, true);
  verificationRound.increment(1);
}

Key pattern: The witness data (getUserBirthDate) is never directly disclosed. Instead, you compute a predicate over it (age >= minAge), and then disclose only the outcome the user consents to.

The tradeoff: The application code that supplies the witness must be trusted. If a malicious DApp sends a false birthdate, the proof system can't detect it—but it will prove the user accepted false data. This is why witness sourcing matters as much as circuit logic.

Practical Consideration: Witness Sourcing

Where do witnesses come from in real applications?

User-held secrets: API keys, private keys, personal data
External APIs: Proof-of-reserve attestations, oracle feeds, credential issuers
Zero-knowledge proofs themselves: A sub-proof generated off-chain that proves something about external data
Trusted hardware: TEE attestations or trusted execution environment outputs

Each source has different security properties. A witness from a user's secret key is as strong as that key's protection. A witness from an untrusted API might need cryptographic verification itself.

For example, if your witness comes from an API like "get current asset price," the application must either:

Trust the API (weak)
Verify the API response against multiple oracles (medium)
Require the API to provide a signature from a trusted source (better)
Use sub-proofs to prove the API data meets certain criteria without revealing it (best)

Commitments & Zero-Knowledge Proof Architecture

From State Mutation to Commitment Schemes

EVM developers are accustomed to direct state mutations:

// Ethereum: modify state directly
mapping(address => uint256) balance;
balance[user] += amount;

In Midnight, public state mutations must be proven by a zero-knowledge circuit. This means your public state must be designed around commitment schemes cryptographic structures that let you prove you know a value without revealing it.

Here's the conceptual bridge:

EVM thinking: State is a mutable cell. Update it directly.
Midnight thinking: State is a commitment to a value. Prove you know the value, then update the commitment.

Building a Private Ledger with Commitments

Let's walk through a private token transfer system:

pragma language_version 0.22;
import CompactStandardLibrary;

// Public state: only commitments to balances, never actual amounts
export ledger balanceCommitment: Map<Bytes<32>, Field>;
export ledger totalSupply: Uint<128>;
export ledger transferRound: Counter;

// Private data structure (never on-chain, only proven)
struct Account {
  owner: Bytes<32>,
  balance: Uint<128>,
  nonce: Uint<64>
}

// Witness: the actual account data, held privately by user
witness getAccount(): Account;
witness getNullifierSecret(): Bytes<32>;

// Helper: derive a nullifier to prevent double-spending
circuit deriveNullifier(nonce: Uint<64>, secret: Bytes<32>): Field {
  return persistentHash<Vector<2, Field>>(
    [persistentHash<Bytes<32>>(nonce as Bytes<32>), 
     persistentHash<Bytes<32>>(secret)]
  ) as Field;
}

// Helper: commitment to an account
circuit commitToAccount(account: Account, salt: Bytes<32>): Field {
  return persistentHash<Vector<2, Field>>(
    [persistentHash<Account>(account),
     persistentHash<Bytes<32>>(salt)]
  ) as Field;
}

// Main circuit: prove a valid token transfer
export circuit transfer(
  recipient: Bytes<32>,
  amount: Uint<128>,
  salt: Bytes<32>,
  newSalt: Bytes<32>
): [] {
  // Load private account data
  const account = getAccount();
  const nullifierSecret = getNullifierSecret();

  // Verify the account commitment exists
  const oldCommitment = commitToAccount(account, salt);
  assert(
    balanceCommitment[account.owner] == oldCommitment,
    "Account commitment mismatch"
  );

  // Private verification: user has sufficient balance
  assert(account.balance >= amount, "Insufficient balance");

  // Compute new account state (private)
  const newAccount: Account = [
    owner: account.owner,
    balance: account.balance - amount,
    nonce: account.nonce + 1
  ];

  // Create nullifier to prevent replay
  const nullifier = deriveNullifier(account.nonce, nullifierSecret);

  // Update public state with new commitment
  const newCommitment = commitToAccount(newAccount, newSalt);
  balanceCommitment = disclose(account.owner, newCommitment);

  // Record nullifier to prevent double-spend
  // In a real system, this would be a set of spent nullifiers
  // For now, we disclose it as proof of spending
  disclose(nullifier);

  // Recipient balance update (simplified: assume recipient pre-existed)
  // In production, you'd handle account creation
  transferRound.increment(1);
}

The Commitment Tradeoff

This approach provides strong privacy but requires careful design:

Advantages:

Balances are never visible on-chain (only commitments)
Transfers reveal no information except that a transfer occurred
The system is composable with other private circuits

Costs:

Every balance update requires a full commitment recomputation
Clients must store balance commitments locally (or query from a private oracle)
Replay protection requires tracking spent nullifiers
The circuit is more complex, leading to larger proofs and longer proving times

Real world consideration: For most applications, you won't implement full commitment schemes from scratch. You'll use Midnight's standard library, which provides optimized versions. But understanding the underlying structure helps you choose the right patterns for your use case.

Circuit Optimization

Why Circuit Optimization Matters

Compact circuits must be bounded at compile time. You can't have unbounded loops or recursive calls. This constraint exists because every circuit must compile to a fixed-size zero-knowledge proof.

For EVM developers, this is a significant mindset shift. On Ethereum, you pay gas for computation. On Midnight, you accept predetermined computation bounds.

// This won't compile unbounded recursion
circuit traverse(node: TreeNode): Uint<64> {
  if (node.left == null) {
    return node.value;
  } else {
    return traverse(node.left);
  }
}

// This works—bounded by tree depth
export circuit traverseFixed<#DEPTH>(
  node: TreeNode, 
  path: Vector<#DEPTH, Boolean>
): Uint<64> {
  let current = node;
  for (let i = 0; i < #DEPTH; i++) {
    if (path[i]) {
      current = current.right; // Assumes node structure allows this
    } else {
      current = current.left;
    }
  }
  return current.value;
}

Optimization Strategies

1: Vectorization and Batching

For operations on multiple items, vectorize instead of looping:

// Less efficient: separate proofs for each item
export circuit verifyAge(secret: Bytes<32>, minAge: Uint<32>): [] {
  const birthDate = getUserBirthDate();
  assert(currentTime - birthDate >= minAge, "Too young");
}

// More efficient: batch verification
export circuit verifyAgesInBatch<#N>(
  secrets: Vector<#N, Bytes<32>>,
  minAges: Vector<#N, Uint<32>>
): [] {
  for (let i = 0; i < #N; i++) {
    // Witness supplies ages for all users
    const birthDates = getUserBirthDates(i);
    assert(
      currentTime - birthDates >= minAges[i],
      "Age check failed"
    );
  }
}

2: Lazy Evaluation with Merkle Trees

Instead of processing all data inline, use Merkle trees to prove membership:

// Direct approach: verify all items (O(n) circuit size)
export circuit verifyAllBalances<#N>(
  balances: Vector<#N, Uint<128>>,
  totalRequired: Uint<128>
): [] {
  let sum: Uint<128> = 0;
  for (let i = 0; i < #N; i++) {
    sum = sum + balances[i];
  }
  assert(sum >= totalRequired, "Insufficient total");
}

// Optimized: verify membership in Merkle tree (O(log n) circuit size)
export circuit verifyBalanceProof(
  balance: Uint<128>,
  merkleProof: Vector<32, Field>, // Log2(2^32) = 32 levels
  merkleRoot: Field,
  leaf_index: Uint<32>
): [] {
  // Recompute leaf and verify path
  const leaf = persistentHash<Uint<128>>(balance) as Field;
  let current = leaf;

  for (let i = 0; i < 32; i++) {
    const proofElement = merkleProof[i];
    // Combine in canonical order to prevent tree structure attacks
    if (leaf_index & (1 << i) == 0) {
      current = persistentHash<Vector<2, Field>>([current, proofElement]) as Field;
    } else {
      current = persistentHash<Vector<2, Field>>([proofElement, current]) as Field;
    }
  }

  assert(current == merkleRoot, "Merkle proof failed");
}

3: Proof Aggregation

When you have multiple privacy preserving properties to prove, you have two choices: prove them all in one circuit (larger proof), or split into separate circuits (multiple proofs, sequential verification).

// Single circuit: proves age AND asset ownership
// Proof size: large, proving time: high
export circuit verifyAgeAndAssets(
  secret: Bytes<32>,
  minAge: Uint<32>,
  assetsProof: AssetsProof
): [] {
  const birthDate = getUserBirthDate();
  assert(currentTime - birthDate >= minAge, "Too young");

  const assets = getAssets(assetsProof);
  assert(assets.value >= 100000, "Insufficient assets");
}

// Split circuits: separate concerns, compose on app level
// Proof size: smaller per circuit, proving time: faster
export circuit verifyAge(secret: Bytes<32>, minAge: Uint<32>): Bytes<32> {
  const birthDate = getUserBirthDate();
  assert(currentTime - birthDate >= minAge, "Too young");
  return disclose(persistentHash<Bytes<32>>(secret));
}

export circuit verifyAssets(assetsProof: AssetsProof): Bytes<32> {
  const assets = getAssets(assetsProof);
  assert(assets.value >= 100000, "Insufficient assets");
  return disclose(persistentHash<Bytes<32>>(assetsProof));
}

// Application composes both proofs
// Tradeoff: two proofs to verify, but faster to prove each one

Benchmarking Your Circuits

Different circuit structures have dramatic performance differences. Use this framework to evaluate:

Structure	Pros	Cons	Use When
Direct computation	Simple, straightforward	Large proof, slow	Small bounded operations
Merkle proof verification	Logarithmic size, scales well	Higher cryptographic complexity	Membership checks in large sets
Vectorized batching	Efficient for repeated ops	Requires uniform structure	Batch processing many similar items
Split circuits	Faster per-circuit proving	Coordination overhead	When proofs are logically independent

Multi-Contract Privacy Architecture

Composing Private Contracts

Midnight's biggest strength is that multiple private contracts can interact while maintaining privacy boundaries. However, composing contracts introduces new considerations:

Problem: The Metadata Leak

Even if all data is encrypted, metadata can leak information:

// Privacy leak: contract call pattern reveals intent
export circuit buyAsset(assetId: Uint<64>): Bytes<32> {
  // If specific assetIds always correlate with specific users,
  // blockchain analysis can link buyers to assets even without seeing amounts
  const proof = getOwnershipProof(assetId);
  verify(proof);
  return disclose(persistentHash<Uint<64>>(assetId));
}

// Mitigated: hide specific asset, batch with dummy calls
export circuit batchBuyAssets<#N>(
  assetIds: Vector<#N, Uint<64>>,
  proofs: Vector<#N, Bytes<32>>,
  isReal: Vector<#N, Boolean>
): Vector<#N, Bytes<32>> {
  let results: Vector<#N, Bytes<32>> = [];
  for (let i = 0; i < #N; i++) {
    // Verify proof only if real purchase (circuits execute either way)
    if (isReal[i]) {
      verify(proofs[i]);
    }
    results[i] = disclose(persistentHash<Uint<64>>(assetIds[i]));
  }
  return results;
}

Pattern: Shielded Contract Composition

When one private contract depends on another, you need a protocol for safe interaction:

pragma language_version 0.22;
import CompactStandardLibrary;

// Contract A: Identity registry
export ledger identityCommitment: Map<Bytes<32>, Field>;

export circuit registerIdentity(publicKey: Bytes<32>): [] {
  const commitment = persistentHash<Bytes<32>>(publicKey) as Field;
  identityCommitment = disclose(publicKey, commitment);
}

// Contract B: Private voting (depends on Contract A)
export ledger voteCommitment: Map<Field, Field>; // (identityHash, voteHash)

export circuit castVote(
  publicKey: Bytes<32>,
  voteChoice: Uint<8>,
  salt: Bytes<32>
): [] {
  // Prove participation in Contract A without revealing identity
  const commitment = persistentHash<Bytes<32>>(publicKey) as Field;
  assert(identityCommitment[publicKey] == commitment, "Not registered");

  // Cast vote privately
  const voteHash = persistentHash<Vector<2, Field>>(
    [persistentHash<Uint<8>>(voteChoice) as Field, 
     persistentHash<Bytes<32>>(salt) as Field]
  ) as Field;

  voteCommitment = disclose(commitment, voteHash);
}

Key insight: Contract B proves it respects Contract A's invariants (the user is registered) without revealing the user's identity. This is the foundation of composable privacy.

Considerations: State Consistency

When multiple contracts touch shared state, you must be careful about ordering:

// Race condition possible: State updated after verification
export circuit transferWithFeeShare(
  amount: Uint<128>,
  feeRecipient: Bytes<32>
): [] {
  const balance = getBalance(); // Witness
  assert(balance >= amount + fee, "Insufficient");

  // Race condition: if another proof updates fee rate before on-chain execution,
  // this assertion might have been based on stale assumptions
  const currentFee = feeContract.queryFee();
}

//  Fixed: Include fee data in the proof
export circuit transferWithFeeShare(
  amount: Uint<128>,
  feeRecipient: Bytes<32>,
  expectedFeeRate: Uint<16>, // App provides expected fee
  feeProof: Bytes<32> // Proof that fee rate matches
): [] {
  const balance = getBalance();

  // Verify fee was what we expected at proof time
  verify(feeProof);

  const fee = (amount * expectedFeeRate) / 100000;
  assert(balance >= amount + fee, "Insufficient");
}

Real-World Tradeoffs

Decision Matrix

Use Case	Pattern	Witness Source	Proof Strategy	Notes
Privacy-first tokens	Commitments + Nullifiers	User secret key	Split by operation type	Requires nullifier tracking
KYC/AML compliance	Age/identity verification	Credential issuer	Selective disclosure	Issuer must be trusted
DAO voting	Shielded voting + identity registry	User secret, registry contract	Batched dummy votes	Metadata still visible (voting time)
Asset swaps	DEX with private pricing**	Oracle feeds, user orders	Batch matching	Requires MEV-resistant ordering

Debugging & Testing Advanced Patterns

Console Logging in Compact

While developing, use logging carefully (it's not available in production proofs):

export circuit debugTransfer(
  recipient: Bytes<32>,
  amount: Uint<128>
): [] {
  const balance = getBalance();

  // Debug logging helps during development
  assert(balance >= amount, "Insufficient");

  // The proof doesn't include debug output, but your app runner sees it
}

Testing Strategy for Circuits

Since circuits must be proven, test thoroughly before deployment:

// TypeScript test harness
import { Contract } from '@midnight-protocol/sdk';

const contract = new Contract(compiledCircuit);

// Test 1: Valid transfer
const validTransfer = await contract.transfer({
  recipient: publicKey,
  amount: 1000n,
  salt: randomSalt,
  newSalt: newRandomSalt
});

assert(validTransfer.proof != null, 'Valid transfer should produce proof');

// Test 2: Insufficient balance should fail
const invalidTransfer = await contract.transfer({
  recipient: publicKey,
  amount: 999999999999n,
  salt: randomSalt,
  newSalt: newRandomSalt
});

assert(invalidTransfer.proof == null, 'Invalid transfer should not produce proof');

Conclusion

Advanced Compact patterns aren't just optimizations they're architectural decisions that shape what's possible in your application.

As you move from learning Compact to building production systems, keep these principles in mind:

Witnesses are your privacy boundary. Choose witness sources carefully; they determine your security model.
Commitments enable privacy at scale. Direct state disclosure doesn't mix with zero-knowledge proofs; use commitments instead.
Circuits must be bounded, but cleverly. Vectorization, Merkle trees, and proof aggregation let you handle complexity without exceeding bounds.
Composition requires explicit coordination. Multiple private circuits can interact, but metadata and state consistency need careful handling.
Privacy and usability are in tension. Batching dummy transactions protects metadata but increases proof sizes. Splitting circuits proves faster but requires coordination. Choose based on your threat model.

Midnight gives you powerful tools for building privacy-first applications. Mastering these patterns lets you use them effectively.

Midnight Mainnet Is Live. The Privacy Stack Just Got Real.

Barnabas — Thu, 02 Apr 2026 16:37:39 +0000

If you've been following the Midnight Network since its early testnet days, you already know the core pitch: a fourth-generation blockchain designed around programmable privacy, zero-knowledge proofs, and selective disclosure. After years of groundwork, multiple hackathon cycles, a massive token distribution, and a developer ecosystem that quietly grew into something serious, mainnet is live.

On March 30, 2026, the Midnight genesis block was produced. Developers, institutions, and partners can now deploy applications and migrate assets on a live production chain. This isn't vaporware anymore. This is a running network.

Let me break down what actually happened over the past month, what's technically significant about the launch architecture, and where this ecosystem is heading.

The Launch: What "Federated Mainnet" Actually Means

One thing worth clarifying upfront: the Midnight mainnet is launching in a federated model, not a fully decentralized one. Hoskinson himself called it a "guarded era." That's intentional, and it's actually a smart engineering decision.

The initial validator set consists of nine federated node partners: Worldpay, Bullish, MoneyGram, Pairpoint by Vodafone, eToro, AlphaTON Capital, Google Cloud, Blockdaemon, and Shielded Technologies. These are institutional-grade operators running infrastructure under explicit participation rules. The goal is to launch a stable, secure network where the early DApps being deployed have a hardened foundation to run on, not to rush decentralization before the system is ready for it.

There are already 130+ post-launch bug fixes queued, none critical, but the team expects to spend two to three weeks hardening the system. This is exactly the right approach for a network whose primary value proposition is security and privacy. You can't afford to rush that.

The move to broader decentralization, bringing Cardano Stake Pool Operators online, launching the DUST Capacity Exchange, and enabling community-driven block production, comes in the next roadmap phase, Mōhalu, targeted for mid-2026.

The Architecture: What Makes Midnight Different Under the Hood

There's a lot of noise in the privacy blockchain space, and most of it is about anonymity. Midnight is doing something different: programmable privacy, which means developers control the privacy rules, not the protocol forcing one-size-fits-all opacity.

Here's what the architecture actually looks like:

Hybrid Dual-State Model

Midnight implements a combined UTXO and account-based model in a single atomic step. Public state lives on the ledger (unshielded), and private state lives in an off-chain execution environment. The Kachina Protocol is the bridge between these two worlds. It lets you process private state transitions off-chain and then submit only a zero-knowledge proof to the public ledger. The network verifies that your computation was valid without ever seeing the underlying data.

This is significantly different from, say, Zcash's approach (which shielded transactions rather than computation) or Tornado Cash-style mixing (which is really just obfuscating transfers). What Midnight enables is ZK-verified application logic, including compliance checks, eligibility proofs, and identity verification, all done without the sensitive data touching the chain.

Client-Side Proofs

Here's one of the design decisions that matters most from a privacy standpoint: ZK proofs are generated client-side. Using a local proof server, sensitive data stays on the user's device. The proof is what gets submitted to the network, not the underlying information. So when you're proving you meet some eligibility threshold, or that you hold a certain credential, that data never leaves your machine.

Shielded and Unshielded Assets

The network supports both. Shielded assets keep balances, counterparties, and transaction flows off the public ledger. Unshielded assets provide full on-chain visibility, useful for things like DeFi where you need composability and public auditability. Developers can mix both in a single application, choosing at the contract level what must stay private and what can be public.

This is what "selective disclosure" means in practice: you can build a DeFi protocol that verifies a user's KYC status without storing their personal data on-chain. The compliance proof goes on-chain; the identity stays off-chain.

The Dual-Token Model: NIGHT and DUST

This is one of the more technically interesting tokenomic designs in recent blockchain history, and it's worth understanding properly before dismissing it as complexity for complexity's sake.

NIGHT is the utility and governance token. It launched on Cardano as a native asset back in December 2025 (the Hilo phase), and it's now mirrored onto the Midnight ledger via a protocol-level mechanism that prevents value duplication across both chains.

DUST is the network resource token, used to pay for transactions and smart contract execution. The key property of DUST is that it regenerates over time based on NIGHT holdings. A full recharge takes seven days. You don't spend NIGHT on transactions; you spend DUST, which regenerates from your NIGHT holdings.

Why does this matter? It separates capital assets from operational costs. In most Layer 1s, every transaction competes for the same token that's also your store of value and governance instrument. That creates volatile transaction costs tied to market speculation. Midnight's model makes transaction costs significantly more predictable, especially important for enterprise applications that need to budget for on-chain compute in advance.

Compact: The ZK Smart Contract Language

This is the piece of the puzzle that determines whether developers actually build on this network or just admire it from a distance.

Compact is a statically-typed domain-specific language built on TypeScript syntax, designed specifically for writing privacy-preserving smart contracts on Midnight. The core design goal is to eliminate the need for deep cryptographic expertise to build ZK applications.

Most ZK development today requires intimate knowledge of circuit design, proof system internals, and constraint systems. Compact abstracts that away. You write familiar TypeScript-style code, manage both public and private state within a single contract, and the compiler handles the ZK proof generation machinery underneath.

The current stable version as of mainnet launch is Compact 0.28.0, paired with:

midnight-js 3.0.0
wallet-sdk 1.0.0
Proof Server 7.0.0

The team recently overhauled the Ledger to v7.0.0 as part of mainnet prep, which included switching to Midnight SRS and midnight-zk 1.0, implementing dimension-based pricing for transactions, and integrating fixes from external security audits.

For developers migrating existing projects to preprod (which everyone should be doing now), the core scaffolding tool create-mn-app makes bootstrapping a new Midnight project straightforward via npm. The reference DApps, Counter and Bulletin Board, are fully updated for the preprod environment and serve as solid starting points for understanding the contract model.

One underrated tool that shipped earlier this year: the MCP server for Midnight. General-purpose AI coding assistants like Claude, Cursor, and Copilot don't have training data on Compact, so they generate hallucinated or invalid code. The MCP server bridges that gap by giving AI coding tools direct, structured access to the Compact codebase and static analysis tools. It's been downloaded over 6,000 times via NPM, a good signal that the developer experience tooling is being taken seriously.

The Ecosystem: What's Actually Being Built

The Aliit Fellowship launched late last year as Midnight's technical leadership program, with 17 fellows from 11 countries, including ZK researchers, open-source maintainers, and educators. This cohort is actively building reference architectures, localizing technical documentation, and mentoring new developers coming through the Midnight Academy.

The Academy itself recently released a new hands-on module focused on actually building DApps rather than just understanding ZK theory. If you've completed the foundational courses on zero-knowledge proofs, the new module walks you through writing Compact smart contracts and wiring them into a functional application end-to-end.

Network metrics tell the story of accelerating builder activity:

1,617% surge in smart contract deployments recorded in November during the Midnight Summit hackathon period
35% rise in smart contract deployments month-over-month in December
19% increase in block producers in the same period
120+ builders engaged during the Summit hackathon alone

These aren't just engagement numbers. Smart contract deployments on a testnet are a leading indicator of what's going to show up on mainnet.

Interoperability: LayerZero and USDCx

Two announcements from Consensus Hong Kong in February are worth highlighting because they significantly expand Midnight's surface area.

LayerZero integration is probably the biggest interoperability unlock in the ecosystem's history. LayerZero connects over 160 blockchains. For Midnight, this means zero-knowledge proofs and selective disclosure can extend across blockchain networks. You're not locked into the Midnight ecosystem to benefit from its privacy architecture. This is the "Hua" phase vision, cross-chain Hybrid DApps, starting to take shape now.

USDCx, a regulatory-compliant stablecoin mirrored 1:1 with Circle's USDC via xReserve infrastructure, launched on Cardano ahead of mainnet. The historical liquidity gap in the Cardano/Midnight ecosystem has been a real limitation for DeFi use cases. USDCx addresses that directly, providing institutional-grade collateral that can flow into Midnight-native protocols.

What's Coming Next: The Roadmap Ahead

The four-phase roadmap gives a clear picture of trajectory:

Kūkolu (Now) — Federated mainnet is live. First wave of production DApps deploying. Developer tooling stabilizing. This is where we are.

Mōhalu (Mid-2026) — Broader decentralization kicks in. Cardano Stake Pool Operators come online as block producers. The DUST Capacity Exchange activates, letting NIGHT holders trade their DUST generation capacity. Staking rewards go live, creating economic incentives for network participation.

Hua (Late 2026) — The Hybrid DApp era. Midnight's privacy layer becomes embeddable into applications on other chains. This is when it stops being a standalone blockchain and starts functioning as privacy infrastructure for the broader Web3 ecosystem.

Each phase follows the previous one rather than running in parallel, which is a sensible sequencing decision. You can't properly decentralize a network until the production environment is stable. You can't build Hybrid DApps into other ecosystems until your interoperability rails (LayerZero, USDCx) are proven in production. The ordering matters.

My Take

What struck me most over the past month is how the technical decisions compound on each other. Client-side proof generation protects data. Compact removes the expertise barrier to ZK development. The federated validator set provides stability without premature decentralization. The DUST model makes transaction costs predictable for enterprise use cases. None of these are flashy standalone features; they're design choices that collectively make real-world deployment practical rather than theoretical.

The next few months will tell us whether the builder ecosystem actually produces compelling DApps, and whether the federated network stays stable as more applications come online. There are 130+ fixes being worked through right now, which is actually a healthy sign. It means the testnet cycle did its job of surfacing real issues before they hit production.

For anyone building in the privacy or compliance space, Midnight's mainnet going live is worth paying close attention to. The infrastructure is here. The question now is what gets built on it.

Resources:

ZK Membership Proofs on Midnight

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

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

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

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

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

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

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

The Problem: Membership Without Identity

The naive approach to allowlisting is just a mapping:

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

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

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

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

Merkle trees make this possible.

Why Merkle Trees Work for ZK Membership

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

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

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

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

The Ledger: Minimal Public Surface

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

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

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

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

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

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

The Witnesses: Everything Private

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

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

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

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

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

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

The `hashLevelNode` Circuit

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

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

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

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

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

The `verifyAndUse` Circuit, Step by Step

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

Step 1: Witness loading

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

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

Step 2: Leaf computation

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

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

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

Step 3: Nullifier verification

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

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

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

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

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

Step 4: Merkle path reconstruction

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

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

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

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

Step 5: Root assertion

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

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

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

Step 6: Nullifier recording

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

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

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

The Admin Pattern: ZK Governance

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

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

The setup circuit is a one-time initialization:

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

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

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

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

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

generateProof does three things:

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

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

The proof object itself is structured as:

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

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

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

The Concatenation Bug the Tests Found

The test suite discovered a real vulnerability worth understanding:

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

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

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

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

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

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

What's Actually on the Chain

Being precise, as always:

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

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

The General Pattern

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

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

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

2. On-chain: store only the root

export ledger merkle_root: Bytes<32>;

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

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

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

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

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

What's Next

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

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

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

Building Privacy-Preserving Decentralized Identity on Midnight

Nasihudeen Jimoh — Wed, 01 Apr 2026 13:28:20 +0000

This isn't another high-level overview you'll forget in a week. This is a complete,technical deep-dive i wish i had when i started building on Midnight three weeks ago.
I've spent countless nights debugging witnesses, fighting with PK derivation mismatches, and discovering exactly what works and what doesn't.

By the time you finish this guide, you'll have a complete, tested, DID + Verifiable Credentials system that actually runs today on Midnight Preview.

Why This Actually Matters

KYC/AML checks. Age verification. Accredited investor authentication. Voting eligibility. Healthcare access control. These aren't optional features they're regulatory requirements for any serious DeFi, enterprise, or consumer app in 2026.

Here's the problem:

Traditional centralized systems = complete data leakage to issuers and verifiers

Public blockchains = every claim is permanently visible to the entire world

"Privacy-focused" solutions = still require off-chain oracles or expose too much metadata

Midnight solves this perfectly because it's shielded by default. The ledger only ever sees commitments and zero-knowledge proofs. Your raw data (birthdate, net worth, KYC status) stays on your device forever.

Today we're building exactly that: a W3C-aligned Decentralized Identifier (DID) system with Verifiable Credentials that supports selective disclosure using Midnight's Compact language and persistentHash-based commitments.

Prerequisites & Setup (Do This First)

You need:

Node.js 18+
A wallet seed from the Midnight faucet (Preview or Preprod)
Docker (for the local proof server)

Run these commands:

git clone https://github.com/Kanasjnr/Midnight-Privacy-Preserving-DID-System
cp .env.example .env
# Edit .env and put your 64-char WALLET_SEED
npm install
npm run setup

What npm run setup does:

Compiles all four Compact contracts → artifacts in contracts/managed/
Builds the TypeScript layer with tsc
Runs deploy.js to deploy contracts and saves addresses to deployment.json

After setup, you'll have:

did-registry
schema-registry
credential-issuer
proof-verifier

Check everything is ready:

npm run check-balance # to check your wallet balance
npm run register-dust   # to register your tNight to DUST for gas

You're now ready to go.

Part 1: Understanding the Architecture

Before we dive into contracts, let's think about what we're building.

The Three Layers

Layer 1: On-Chain Ledger

The ledger stores only cryptographic commitments. Not data. Not hashes of data. Specifically, commitments that are generated from raw data + a salt, using the persistentHash function.

Think of it like this the issuer takes your birthdate (19900101) and a salt (a random 32-byte value), hashes them together, and stores the result on-chain. The ledger now has: commitment = persistentHash([19900101, salt]). That commitment is public. But from that commitment alone, it's computationally infeasible to reverse-engineer either the birthdate or the salt.

Layer 2: Local Credential Storage

The holder keeps the raw data locally. Encrypted. Never shared.

When the issuer issues a credential, they don't store the raw claim. They only store:

{
  claims: { dateOfBirth: 19900101 },
  salt: <32 random bytes>,
  commitment: <sha256 hash of claims + salt>
}

The commitment goes on-chain. Everything else stays on the holder's device. This separation is critical the issuer can't prove the data later because they never stored it.

Layer 3: Proof Generation (Offline)

When the holder needs to prove something ("I'm over 18"), they use the raw credential stored locally to generate a zero-knowledge proof. This proof is created locally, without touching the ledger.

The proof says: "I know a value whose hash equals this commitment, and that value satisfies this property (age > 18)." The verifier can check the math without learning what the value is.

The Actual Flow

the verifier doesn't need to query the ledger at all. They just need the proof and the commitment (which is public anyway).

Part 1: Understanding persistentHash

This is where most developers get stuck, so let's go deep.

persistentHash is Midnight's built-in hash function in Compact. It's deterministic same input always produces the same output. It takes a vector of byte arrays and returns a 32-byte hash.

Example:

const commitment = persistentHash<Vector<2, Bytes<32>>>([
  dateOfBirth as Bytes<32>,
  salt
]);

This is saying: "Create a persistent hash of a vector containing 2 elements (both 32-byte arrays): the DOB and the salt."

When you hash in Compact, you're working with Bytes<32>. Everything gets padded to 32 bytes. So if your birthdate is 19900101 (an integer), you need to cast it:

(dateOfBirth as Field) as Bytes<32>

This isn't intuitive. But it's how Compact works. I fought with this for hours. The error messages don't tell you what went wrong you just get "type mismatch" and have to guess.

Now, when the verifier checks the proof, they use the exact same hash function. If the prover claims "this value hashes to commitment X" and the math doesn't check out, the proof fails.

Part 2: The Contracts

We're building four Compact contracts. All in one directory: contracts/.

Contract 1 — types.compact (Shared Types)

This file is imported by every other contract. It defines the data structures we'll use everywhere.


pragma language_version >= 0.20 && <= 0.21;
import CompactStandardLibrary;

export struct DIDEntry {
  document_commitment: Bytes<32>,   // hash of the DID document
  controller_pk: Bytes<32>          // derived from controller secret key
}

export enum CredentialStatus {
  ACTIVE,
  REVOKED,
  SUSPENDED
}

export struct SchemaMetadata {
  name: Bytes<32>,
  version: Uint<8>,
  creator_pk: Bytes<32>,
  json_schema_hash: Bytes<32>
}

export struct IssuanceEntry {
  holder_did_hash: Bytes<32>,
  schema_id: Bytes<32>,
  credential_commitment: Bytes<32>,   // ← this is the magic
  issuer_pk: Bytes<32>,
  status: CredentialStatus
}

Why this structure?

DIDEntry stores the commitment of the DID document + the controller's public key
CredentialStatus lets us revoke credentials without removing them
IssuanceEntry links a holder, schema, and credential commitment together

The credential_commitment field is crucial. It's not the claim itself. It's a hash of (claim + salt). From this alone, you can't reverse-engineer the claim.

Contract 2: did-registry.compact (The Root of Trust)

This contract is the foundation. It's where DIDs are registered and updated. A DID is basically a public key that controls an identity.


pragma language_version >= 0.20 && <= 0.21;
import CompactStandardLibrary;
include 'types';

export ledger did_registry: Map<Bytes<32>, DIDEntry>;

// This witness is never stored on-chain
witness controller_secret_key(): Bytes<32>;

pure circuit derive_pk(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "midnight:pk:"),   // 12-byte prefix + 20 zero bytes
    sk
  ]);
}

export circuit registerDID(
  did_id: Bytes<32>, 
  document_commitment: Bytes<32>,
  controller_pk: Bytes<32>
): [] {
  const d_id = disclose(did_id);
  const d_doc = disclose(document_commitment);
  const d_pk = disclose(controller_pk);

  assert(!did_registry.member(d_id), "DID already exists");
  did_registry.insert(d_id, DIDEntry{ d_doc, d_pk });
}

export circuit updateDocument(
  did_id: Bytes<32>,
  new_commitment: Bytes<32>
): [] {
  const d_id = disclose(did_id);
  const d_new_doc = disclose(new_commitment);

  const entry = did_registry.lookup(d_id);
  const derived_pk = derive_pk(controller_secret_key());
  assert(entry.controller_pk == derived_pk, "Not authorized");

  did_registry.insert(d_id, DIDEntry{ d_new_doc, entry.controller_pk });
}

Let me walk you through what's happening:

controller_secret_key() witness — This is the holder's private key. It's passed to the circuit but never stored on-chain. The circuit uses it to derive the public key and verify authorization.
derive_pk() function — This is critical. It hashes the secret key in a specific way to produce the public key. The exact same function must exist in your TypeScript code. If it doesn't match byte-for-byte, authorization will fail. Trust me, I spent 3 hours debugging this.
registerDID() — Creates a new DID entry. The disclose() calls mean these values are public inputs to the zero-knowledge proof.
updateDocument() — Updates the DID document commitment. The key move: it looks up the existing entry, derives the public key from the secret key witness, and verifies it matches. Only the real controller can update.

The circuit:

Derives the public key from the secret key using derive_pk()
Looks up the stored DID entry
Compares: does the derived PK match the stored PK?
If yes, authorization is granted. If no, the circuit fails.

This is how Midnight enforces authorization without a traditional "signed transaction" model. The secret key is the witness only the true controller knows it.

Contract 3: schema-registry.compact (Credential Types)

This contract stores metadata about credential schemas. It's straightforward:

export ledger schema_registry: Map<Bytes<32>, SchemaMetadata>;

export circuit registerSchema(
  schema_id: Bytes<32>,
  name: Bytes<32>,
  version: Uint<8>,
  creator_pk: Bytes<32>,
  json_schema_hash: Bytes<32>
): [] {
  const d_id = disclose(schema_id);
  const d_name = disclose(name);
  const d_version = disclose(version);
  const d_creator = disclose(creator_pk);
  const d_hash = disclose(json_schema_hash);

  assert(!schema_registry.member(d_id), "Schema already registered");
  schema_registry.insert(d_id, SchemaMetadata{ d_name, d_version, d_creator, d_hash });
}

This lets you define schemas like:

"age-credential" (has a dateOfBirth field)
"accredited-investor" (has netWorth and accreditationDate)
"passport" (has various identity fields)

Each schema gets a unique ID and is registered on-chain. The json_schema_hash points to the full JSON schema stored off-chain (e.g., on IPFS).

Contract 4: credential-issuer.compact (Issuing Commitments)

The issuer's job: take claims (birthdate, net worth, etc.), hash them with a salt, and store the commitment on-chain.


export ledger credential_ledger: Map<Bytes<32>, IssuanceEntry>;

export circuit issueCredential(
  holder_did_hash: Bytes<32>,
  schema_id: Bytes<32>,
  credential_commitment: Bytes<32>,
  issuer_pk: Bytes<32>
): [] {
  const d_holder = disclose(holder_did_hash);
  const d_schema = disclose(schema_id);
  const d_commitment = disclose(credential_commitment);
  const d_issuer = disclose(issuer_pk);

  const issuance_id = persistentHash<Vector<4, Bytes<32>>>([
    d_holder, d_schema, d_commitment, d_issuer
  ]);

  assert(!credential_ledger.member(issuance_id), "Credential already issued");
  credential_ledger.insert(issuance_id, IssuanceEntry{
    d_holder,
    d_schema,
    d_commitment,
    d_issuer,
    ACTIVE
  });
}

export circuit revokeCredential(
  issuance_id: Bytes<32>
): [] {
  const d_id = disclose(issuance_id);
  const entry = credential_ledger.lookup(d_id);
  const issuer_pk = derive_pk(issuer_secret_key());

  assert(entry.issuer_pk == issuer_pk, "Only issuer can revoke");
  // Update status without removing from ledger
  credential_ledger.insert(d_id, IssuanceEntry{
    entry.holder_did_hash,
    entry.schema_id,
    entry.credential_commitment,
    entry.issuer_pk,
    REVOKED
  });
}

Key insight: The issuer posts only the commitment. Not the raw claim. The commitment is a hash of (claim + salt). The issuer sends the raw claim and salt to the holder separately (securely, off-chain).

When later the holder proves "I'm over 18", they use the raw claim + salt (stored locally) to reconstruct the commitment and prove it matches.

Contract 5: proof-verifier.compact (Zero-Knowledge Heart)

This is where selective disclosure happens. The circuit proves something about the commitment without revealing the underlying data.

pragma language_version >= 0.20 && <= 0.21;
import CompactStandardLibrary;

export ledger dummy: Field; // forces ZK circuit generation

// These are witnesses — private inputs only the prover knows
witness dateOfBirth(): Uint<32>; // YYYYMMDD format
witness salt(): Bytes<32>;

export circuit verifyAge(
  current_date: Uint<32>,
  threshold_years: Uint<32>,
  expected_commitment: Bytes<32>
): [] {
  const _force_zk = dummy;

  // These are disclosed (public inputs)
  const d_current = disclose(current_date);
  const d_threshold = disclose(threshold_years);
  const d_expected = disclose(expected_commitment);

  // These stay private (only in the circuit)
  const dob = dateOfBirth();
  const s = salt();

  // Recompute commitment exactly as the issuer did
  const computed = persistentHash<Vector<2, Bytes<32>>>([
    (dob as Field) as Bytes<32>,
    s
  ]);
  assert(computed == d_expected, "Invalid credential commitment");

  // Age math inside the circuit — raw DOB never leaves the prover
  assert(d_current - dob >= (d_threshold * 10000 as Uint<32>), "Underage");
}

This is the magic. Let me break it down:

Witnesses — dateOfBirth and salt are private inputs. Only the prover knows them.
Public inputs — current_date, threshold_years, expected_commitment are disclosed.
Commitment verification — We recompute the commitment inside the circuit. If it matches, we know the DOB and salt are real.
Age check — We do the math: (year * 10000 + month * 100 + day) - dob >= threshold * 10000. All inside the circuit.
Output — A zero-knowledge proof that proves "the holder is over the threshold" without revealing the DOB.

The verifier sees:

✅ The proof
✅ The commitment (already public from issuance)
✅ The threshold age
❌ NOT the birthdate
❌ NOT the salt

This is selective disclosure. This is privacy-preserving verification.

Part 3: The TypeScript SDK

Now we need code that talks to these contracts. The SDK lives in src/.

3.1 DIDManager.ts — Creating and Controlling DIDs

This is the entry point. A holder creates a DID and keeps their secret key safe.

import { createHash, randomBytes } from "crypto";
import { CompactTypeBytes, persistentHash } from "@midnight-ntwrk/compact-sdk";

export class DIDManager {
  private controllerSecretKey: Uint8Array;

  constructor(secretKey?: Uint8Array) {
    this.controllerSecretKey = secretKey || randomBytes(32);
  }

  // This MUST match the Compact derive_pk exactly
  private deriveCompactPk(sk: Uint8Array): Uint8Array {
    const bytes32 = new CompactTypeBytes(32);
    const vector2 = new CompactTypeVector(2, bytes32);

    // Exact same prefix as in Compact: "midnight:pk:" + padding
    const prefix = new Uint8Array(32);
    const prefixStr = Buffer.from("midnight:pk:");
    prefix.set(prefixStr, 0);

    return persistentHash(vector2, [prefix, sk]);
  }

  public getPublicKey(): Uint8Array {
    return this.deriveCompactPk(this.controllerSecretKey);
  }

  public deriveDIDHash(didName: string): Uint8Array {
    return createHash("sha256").update(didName).digest();
  }

  public async registerDID(didName: string): Promise<void> {
    const didHash = this.deriveDIDHash(didName);
    const documentCommitment = createHash("sha256")
      .update(JSON.stringify({ name: didName, created: Date.now() }))
      .digest();
    const controllerPk = this.getPublicKey();

    // Call the Midnight contract
    const txData = await this.callContract("registerDID", [
      didHash,
      documentCommitment,
      controllerPk
    ]);

    console.log(`[DID Registered] ${didName}`);
    console.log(`[DID Hash] ${didHash.toString("hex")}`);
    console.log(`[Commitment] ${documentCommitment.toString("hex")}`);
  }
}

The deriveCompactPk() function is critical. It must match the contract's derive_pk() exactly:

Same prefix: "midnight:pk:" padded to 32 bytes
Same hash function: persistentHash
Same vector type: Vector<2, Bytes<32>>

If this doesn't match, when the contract tries to authorize you, the derived public key won't match the stored public key, and the circuit fails with an authorization error.

The secret key is never sent to the contract—only the derived public key.
The holder keeps the secret key safe locally.

3.2 CredentialManager.ts — Issuing and Storing Credentials

The issuer uses this to issue credentials. The holder stores them locally.

import { createHash, randomBytes } from "crypto";
import fs from "fs";

export interface Credential {
  holderDIDHash: string;
  schemaId: string;
  claims: Record<string, any>;
  salt: string;
  commitment: string;
  issuedAt: number;
}

export class CredentialManager {
  private credentialStorage: Map<string, Credential> = new Map();
  private storageFile = "credentials.json";

  constructor() {
    this.loadFromFile();
  }

  public async issueCredential(
    holderDIDHash: Uint8Array,
    schemaId: Uint8Array,
    claims: Record<string, any>
  ): Promise<Credential> {
    // Generate commitment: hash(claims || salt)
    const salt = randomBytes(32);
    const claimsStr = JSON.stringify(claims);
    const credential_commitment = createHash("sha256")
      .update(claimsStr + salt.toString("hex"))
      .digest();

    const credential: Credential = {
      holderDIDHash: holderDIDHash.toString("hex"),
      schemaId: schemaId.toString("hex"),
      claims,
      salt: salt.toString("hex"),
      commitment: credential_commitment.toString("hex"),
      issuedAt: Date.now()
    };

    // Store locally (NOT on-chain yet)
    const key = credential.commitment;
    this.credentialStorage.set(key, credential);

    // Now issue on-chain (only the commitment)
    await this.callContract("issueCredential", [
      holderDIDHash,
      schemaId,
      credential_commitment,
      this.issuerPublicKey
    ]);

    console.log(`[Credential Issued] Commitment: ${credential.commitment}`);

    return credential;
  }

  private saveToFile(): void {
    const data: Record<string, Credential> = {};
    this.credentialStorage.forEach((cred, key) => {
      data[key] = cred;
    });
    fs.writeFileSync(this.storageFile, JSON.stringify(data, null, 2));
  }

  private loadFromFile(): void {
    if (fs.existsSync(this.storageFile)) {
      const data = JSON.parse(fs.readFileSync(this.storageFile, "utf-8"));
      Object.entries(data).forEach(([key, cred]) => {
        this.credentialStorage.set(key, cred as Credential);
      });
    }
  }
}

Why separate issuer and holder?

The issuer creates the commitment and posts it on-chain
The holder receives the raw claims and salt
Only the holder stores the credential locally (encrypted)
The issuer never stores raw data

3.3 ProofGenerator.ts — Creating Zero-Knowledge Proofs

When the holder needs to prove something, they generate a proof locally. No ledger interaction needed.

import { CircuitContext, proveCircuit } from "@midnight-ntwrk/compact-sdk";

export class ProofGenerator {
  private credential: Credential;

  constructor(credential: Credential) {
    this.credential = credential;
  }

  public async generateAgeProof(
    currentDate: number,
    thresholdYears: number,
    verifierAddress: string
  ): Promise<string> {
    // Create circuit context
    const circuitContext = new CircuitContext(
      verifierAddress,
      "verifyAge" // circuit name
    );

    // Set public inputs
    circuitContext.setPublicInput("current_date", currentDate);
    circuitContext.setPublicInput("threshold_years", thresholdYears);
    circuitContext.setPublicInput("expected_commitment", this.credential.commitment);

    // Set private inputs (witnesses)
    const dob = parseInt(this.credential.claims.dateOfBirth); // YYYYMMDD
    const salt = Buffer.from(this.credential.salt, "hex");

    circuitContext.setWitness("dateOfBirth", dob);
    circuitContext.setWitness("salt", salt);

    // Generate proof
    const proof = await proveCircuit(circuitContext);

    console.log(`[Proof Generated] Age proof created`);
    console.log(`[Proof Size] ${proof.length} bytes`);

    return proof;
  }
}

The flow:

The holder loads their credential from local storage (raw claims + salt)
Calls generateAgeProof() with current date and threshold age
The circuit verifies: "I know a value (DOB) that hashes to the commitment AND is old enough"
The proof is generated locally, completely offline
The proof can be sent to any verifier

The verifier doesn't need to query the ledger. They just check the proof.

Part 4: The Interactive CLI

I built a CLI that lets you interact with the entire system.

npm run cli

This launches an interactive prompt:

? What would you like to do?
  → Register DID
  → Issue Credential (DOB)
  → Verify Credential
  → Generate Age Proof
  → Check Status

Demo workflow:

Choose "Register DID" → Enter alice.night(or whatever DID you want to register)
- Creates DID, stores secret key, shows DID hash and commitment
Choose "Issue Credential (DOB)" → Enter DOB 19901225
- Generates commitment, stores credential locally, posts to ledger
- Open credentials.json — you'll see the raw DOB and salt only locally
Choose "Verify Credential" → Verification happens on-chain
- Posts proof, checks it, updates status
Choose "Generate Age Proof" → Offline proof generation
- Generates ZK proof proving "over 18"
- No ledger interaction
- Proof can be sent to any verifier

Part 5: Use Case 1 — Age Verification

Scenario: A DeFi protocol needs to verify users are adults before allowing participation.

Step 1: Holder Registers

alice$ npm run cli
→ Register DID
→ alice
[DID Registered] alice
[DID Hash] 0x7f3a...
[Controller PK] 0x2b9e...

Step 2: Issuer Issues Credential

issuer$ npm run cli
→ Issue Credential (DOB)
→ holder: alice
→ dob: 19901225
[Credential Issued] 
[Commitment] 0x5d4e...
[On-chain Tx] 0xabc123...

The ledger now has:

credential_ledger {
  holder_did_hash: 0x7f3a...,
  schema_id: 0x...age-schema...,
  credential_commitment: 0x5d4e...,
  issuer_pk: 0x...,
  status: ACTIVE
}

But the raw DOB? Only in credentials.json on alice's device.

Step 3: Holder Generates Proof

alice$ npm run cli
→ Generate Age Proof
→ current_date: 20260401
→ threshold: 18
→ verifier_address: 0xprotocol...

[Proof Generated]
[Proof Hash] 0x9a2f...

Step 4: Verifier Checks Proof

verifier$ npm run verify-proof \
  --proof 0x9a2f... \
  --commitment 0x5d4e... \
  --threshold 18

Proof Valid
Age Verified: Over 18
DID: alice

What the verifier learned:

✅ Alice is over 18
✅ The proof is mathematically valid
❌ Alice's actual birthdate
❌ Any other PII

This is selective disclosure. This is privacy.

Part 6: Use Case 2 — Accredited Investor Verification

Accredited investors must prove net worth > $1M without revealing exact net worth. Here's how:

Step 1: New Schema Registration

const accreditedSchema = {
  name: "accredited-investor-v1",
  version: 1,
  claims: {
    netWorth: "Uint<64>",
    accreditationStatus: "String<32>",
    verificationDate: "Uint<32>"
  }
};

// Register on-chain
await schemaRegistry.registerSchema(accreditedSchema);

Step 2: Issuer Issues Credential

const claims = {
  netWorth: 1500000,
  accreditationStatus: "accredited",
  verificationDate: 20260401
};

await credentialManager.issueCredential(
  holderDIDHash,
  accreditedSchemaId,
  claims
);

Again, only the commitment goes on-chain.

Step 3: New Circuit for Accredited Proof

export circuit verifyAccredited(
  min_net_worth: Uint<64>,
  expected_commitment: Bytes<32>
): [] {
  const d_min = disclose(min_net_worth);
  const d_expected = disclose(expected_commitment);

  const net_worth = netWorth();
  const s = salt();

  const computed = persistentHash<Vector<2, Bytes<32>>>([
    (net_worth as Field) as Bytes<32>,
    s
  ]);
  assert(computed == d_expected, "Invalid credential");
  assert(net_worth >= d_min, "Not accredited");
}

Step 4: Generate and Verify

// Generate proof
const proof = await proofGenerator.generateAccreditedProof(
  1000000, // minimum net worth
  verifierAddress
);

// Verify
const result = await verifier.verifyAccredited(proof);
// Result: "User is accredited" (without revealing $1.5M)

Same pattern. Different constraints. Total privacy.

Part 7: Security Model & What We Protect

Let me walk through exactly what's protected and what isn't.

What Is Protected

Raw PII — Birthdate, net worth, SSN, medical records. Never touches the ledger. Only hashes.

Controller Secret Keys — Never sent to the contract. Only the derived public key, which cannot be reversed.

Witness Data — Supplied only at proof generation time. Not stored anywhere except in memory during proof.

Selective Disclosure — We prove specific claims without proving everything. Age without revealing DOB. Accreditation without revealing wealth.

What Isn't Protected

Commitment — It's public. Anyone can see you have an age credential.

Timing Metadata — When you registered, when you generated proofs. Blockchain is transparent.

Holder Identity — If someone knows your DID name (like "alice"), they can link credentials.

Attack Vectors We Mitigated

Replay Attacks

→ Each issuance includes a unique hash of (holder, schema, commitment, issuer). Can't reuse a credential.

Unauthorized Updates

→ DID updates require the controller secret key. Only the real owner can update the document.

Commitment Collisions

→ Poseidon hash is cryptographically secure. Chance of collision is 2^-256.

False Proofs

→ The zero knowledge circuit forces the math to check. Can't prove "over 18" if you're not.

Salt Reuse

→ I recommend unique salts per credential. If you reuse salts, clever analysis might link credentials.

Part 8: Some likely errors you might hit

I'm going to be brutally honest about what broke and what i learned.

1: PK Derivation Byte Mismatch

The Problem:

deriving the public key in TypeScript but it didn't match the Compact circuit. Authorization failed every time.

The Cause:

The padding in the prefix was different. TypeScript was doing 32 bytes of padding, Compact was doing 12 bytes prefix + 20 zeros.

The Fix:

const prefix = new Uint8Array(32);
const prefixStr = Buffer.from("midnight:pk:");
prefix.set(prefixStr, 0);
// Rest is zeros automatically

And in Compact:

pad(32, "midnight:pk:")  // 12 bytes + 20 zeros

Now they match. Always verify PK derivation matches exactly.

2: Witness Timing Race Conditions

The Problem:

Witnesses were sometimes undefined when the proof circuit ran.

The Cause:

I was setting witnesses after the circuit started executing.

The Fix:

Deferred provider pattern:

const getWitnesses = (dataProvider: () => WitnessData) => ({
  dateOfBirth: (context: any) => {
    const data = dataProvider();
    return [context, BigInt(data.dob)];
  },
  salt: (context: any) => {
    const data = dataProvider();
    return [context, data.salt];
  }
});

Witnesses are resolved right before the circuit needs them.

The Complete Code

Everything in this guide is in the repo. Clone it and run it.

git https://github.com/Kanasjnr/Midnight-Privacy-Preserving-DID-System
npm run setup
npm run cli

Next Steps — What You Should Build Today

Clone and run → npm run setup && npm run cli
Understand the contracts → Open each .compact file and trace through the logic
Extend the schema → Add a new credential type (driver's license expiry, KYC status)
Build the accredited investor circuit → Implement verifyAccredited() in Compact
Test with real data → Issue credentials with real names and dates
Share your fork → Post in the Midnight Dev Forum

You now have a complete, production-ready, privacy-first identity stack. You can issue credentials, generate proofs, and verify claims all without ever exposing raw PII to the ledger.

We just proved that compliance and privacy are no longer mutually exclusive.

Conclusion

You've just built a system that:

Issues verifiable credentials without storing PII
Generates zero-knowledge proofs without ledger interaction
Enables selective disclosure (prove one thing without proving everything)
Never exposes raw data to the blockchain
Supports revocation and key rotation
Works on production Midnight today

This is not theoretical. This is not a prototype. This is a complete, tested system.

The private web is here. Midnight made it possible. You just built it.

Now go build something amazing.

Questions? Drop them in the comments. I will read every single one.

Found a bug? Open an issue on GitHub.

Want to extend it? Fork the repo and ship it.

Repo: https://github.com/Kanasjnr/Midnight-Privacy-Preserving-DID-System

Star it. Fork it. Ship real apps with it.

Happy hacking!

DEV Community: Midnight Aliit Fellowship

Working with Maps and Merkle Trees in Compact:

A Guide to the State Dichotomy

The State Dichotomy: Conceptual Framework

Ledger state (Public)

Shielded state (Private)

Choosing the correct structure

Associative storage with Maps

Syntax and declaration

Map operators and the disclosure rule

1. The disclosure requirement: Bridging Private and Public

2. Detailed Map Operations

Zero Knowledge membership with Merkle Trees

Technical specification and Depth Selection

Operational lifecycle: The path to proof

1. The Merkle path witness

2. Circuit-level verification logic

The "Double Disclosure" security pattern

Technical comparison: Maps vs. Merkle Trees

Computational overhead analyze

SDK implementation: The structural validation

The instanceof requirement and Type Safety

Detailed Implementation Walkthrough

Registry contract: contract/registry.compact

Allowlist contract: contract/allowlist.compact

TypeScript orchestrator: src/index.ts

State Bounded Merkle Trees

The Synchronization window

State Bounded Merkle Trees

Best practices

Disclosure hygiene

Handling state lag in production

Optimization: Caching witness results

API Reference

Conclusion

I Hit Midnight's Block Limits Twice; And It Forced Me to Rethink Everything

[Hands-on] Midnight Deep Dive: Start Building Smart Contracts with Compact

Introduction: The "Too Transparent" Problem of Blockchains

INTMAX – Stateless Layer for Billions

Home - Midnight Summit 2025

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

Compact: A Privacy Smart Contract Language with TypeScript-like Syntax

TypeScript-based syntax

Three data states: Public, Private, Witness

Basic syntax and a Counter smart contract example

Hands-on: Set up your Midnight development environment

Step 1: Install Compact CLI

Step 2: Prepare Lace Wallet and get Testnet tokens

Step 3: Start ZK Proof Server

Step 4: Prepare sample repository

mashharuki / midnight-sample

midnightでの開発事前検証用リポジトリ

midnight-sample

環境

compact CLIのインストール

Testnet用のZKProof serverの起動

サンプルプログラムのコンパイル＆デプロイ手順

Implement and test the Counter contract

Code walkthrough

Unit test implementation

Run tests

Deploy and execute from CLI on Testnet

Generate TypeScript API

Set environment variables

CLI unit test walkthrough

Run unit tests locally

Run unit tests against testnet

Deployment script walkthrough

Run deployment

Execute increment

Current limitations and what's next

Closing thoughts

References

The Future of Privacy: A Deep Dive into Cardano's Midnight & Zero-Knowledge Proofs

Introduction: The "Too Transparent" Problem in Blockchain

Midnight Documentation | Midnight Docs

Chapter 1: What Is Midnight? - A New Blockchain for Privacy

Architecture Overview

【図解】ゼロ知識証明のPLONKとは？Groth16との違いを世界一わかりやすく解説！

What Midnight aims to achieve

The `instanceof` requirement and Type Safety

Registry contract: `contract/registry.compact`

Allowlist contract: `contract/allowlist.compact`

TypeScript orchestrator: `src/index.ts`

Execute `increment`

`useWallet()`: connection state

`useConnect()`: connection management

`useIntent()`: signing

`useBalance()`: balance polling

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

The Privacy Contract (`salary.compact`)

The Application Layer (`pulse.ts`)