Forem: BossChaos

Building Privacy-First Apps with Midnight Easy SDK

BossChaos — Sun, 03 May 2026 11:48:38 +0000

🌙 Midnight Easy SDK: Privacy-First Development Made Simple

This is a submission for the Midnight Network "Privacy First" Challenge

Track: Enhance the Ecosystem + Best Tutorial

License: Apache 2.0

GitHub: github.com/BossChaos/midnight-easy-sdk

📌 Project Overview

I built @midnight/easy-sdk to lower the barrier for developers who want to add privacy features to their apps but don't want to become zero-knowledge cryptography experts.

The SDK wraps Midnight's cryptographic primitives in a clean TypeScript API. You get seal, verify, and decrypt operations, plus React hooks that handle loading states and error recovery out of the box.

🛠️ Tech Stack

Layer	Technology
Language	TypeScript
UI Framework	React + Hooks
Cryptography	Midnight ZK circuits (Noir)
Testing	Vitest
License	Apache 2.0

💡 Core Value

No ZK expertise required — Seal data, verify proofs, and decrypt results with three function calls
React-first design — useSeal, useVerify, useDecrypt hooks handle all the async complexity
Selective disclosure — Reveal only the metadata you choose, keeping the rest private
Drop-in installation — npm install @midnight/easy-sdk and you're ready to go

🚀 Quick Start

npm install @midnight/easy-sdk

import { MidnightEasy } from '@midnight/easy-sdk';

const midnight = new MidnightEasy({ network: 'testnet' });
await midnight.init();

Core API

1. Seal Data

seal() creates a confidential commitment from your data. Under the hood, it generates a zero-knowledge note that hides the input while allowing later selective disclosure.

const sealed = await midnight.seal({
  value: 1_000_000n,
  asset: 'USDC',
  owner: 'did:mad:test...',
  metadata: { purpose: 'escrow' }
});

console.log(sealed.commitment);   // '0xabc123...'
console.log(sealed.nullifier);    // '0xdef456...'

The commitment is posted to the Midnight ledger. Observers see a hash — not the underlying value.

2. Verify a Proof

verify() checks a zero-knowledge proof against a commitment without revealing the sealed data.

const result = await midnight.verify({
  commitment: sealed.commitment,
  conditions: { minValue: 500_000n, allowedAssets: ['USDC'] },
  proof: userProvidedProof,
});

console.log(result.valid);    // true
console.log(result.metadata); // { purpose: 'escrow' }

3. Decrypt Results

decrypt() reveals the plaintext to authorized recipients only, using Midnight's threshold decryption.

const plaintext = await midnight.decrypt({
  ciphertext: transfer.encryptedResult,
  recipientKey: recipient.publicKey,
  threshold: 2,
});

React Hooks

For UI-driven privacy flows, the SDK provides React hooks:

import { MidnightProvider, useSeal } from '@midnight/easy-sdk/react';

function App() {
  return (
    <MidnightProvider network="testnet" autoConnect>
      <EscrowPanel />
    </MidnightProvider>
  );
}

function EscrowPanel() {
  const { seal, isLoading, error } = useSeal();
  const handleSeal = async () => {
    const result = await seal({ value: 500_000n, asset: 'USDC', owner: myDID });
    console.log('Committed:', result.commitment);
  };
  return <button onClick={handleSeal}>Seal</button>;
}

Real-World Example: Private Escrow

// Alice seals her deposit
const deposit = await midnight.seal({
  value: 500_000n, asset: 'USDC', owner: aliceDID,
  metadata: { role: 'depositor' }
});

// Bob seals his acceptance
const acceptance = await midnight.seal({
  value: 0n, asset: 'USDC', owner: bobDID,
  metadata: { role: 'acceptor' }
});

// Contract verifies both
const valid = await midnight.verify({
  commitment: deposit.commitment,
  conditions: { allowedAssets: ['USDC'] }
});

Contributing

Open source under Apache 2.0. Contributions welcome:

📖 Improve documentation
🧪 Expand test coverage
🛠️ Add new primitives and hooks

GitHub Repository

Built for the Midnight Network "Privacy First" Challenge — Enhance the Ecosystem & Best Tutorial tracks.

Building a Governance Token dApp on Midnight

BossChaos — Sun, 03 May 2026 08:15:36 +0000

Complete Source Code: GitHub Repository

Network: Midnight Preprod

Stack: Compact + TypeScript + React + Vite

Introduction

Midnight is famous for privacy-first smart contracts using zero-knowledge proofs. But not everything needs to be private. Sometimes you want transparent, publicly verifiable transactions — like community governance tokens, loyalty points, or public reward systems.

In this tutorial, we will build a complete unshielded token dApp on Midnight with role-based minting, transfer memos, and balance snapshots for governance voting.

Why Unshielded Tokens

Unshielded tokens are perfect for governance because transparency builds trust. Unlike shielded tokens that hide balances and transfers behind ZK proofs, unshielded tokens offer lower gas costs and faster confirmation times.

Use cases include governance voting, public reward systems, and loyalty programs where auditability matters more than privacy.

The Smart Contract

Our GovernanceToken contract implements three key features for decentralized governance:

Role-Based Minting

Instead of a single minter, the contract uses a minter role system. The deployer can grant or revoke minting permissions to other addresses, enabling multi-sig governance or DAO-controlled token issuance.

Transfer with Memo

Every transfer supports an optional 64-byte memo field. This creates an on-chain audit trail useful for payment references, vote tracking, and compliance reporting.

Balance Snapshots

For governance voting, you need to know a user balance at a specific point in time. Snapshots lock in balances so users cannot game the system by transferring tokens after a vote is announced.

TypeScript Integration

The TypeScript layer connects the React frontend to the Midnight blockchain through the DApp Connector API. It handles wallet building, contract deployment, and transaction submission.

Key components include the WalletBuilder for seed-based wallet creation, the IndexerProvider for balance queries, and the NodeZkConfigProvider for proof generation.

Building the UI

The React frontend provides four main panels:

WalletConnect handles wallet discovery and connection state management
BalanceDisplay shows token balances with real-time refresh from the indexer
MintPanel provides a form for authorized minters to issue new tokens
TransferPanel enables token transfers with memo field support

The UI uses TailwindCSS for a dark theme optimized for developer workflows.

Testing and Deployment

Before going live, test all contract functions against the Midnight local Docker stack. The deployment script handles wallet initialization, contract compilation, and transaction submission.

Run the integration test suite to verify minting permissions, transfer memo encoding, and snapshot accuracy before deploying to preprod.

Full source code available at https://github.com/BossChaos/midnight-governance-token

Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

BossChaos — Sat, 02 May 2026 13:05:55 +0000

Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

Last month, I was tasked with building an allowlist system for a Midnight dApp. The requirement seemed simple: let authorized users access a feature without revealing who they are. In the clear-text world, you'd just check if (user in allowedList). But on a privacy platform, that if statement leaks everything.

This tutorial walks through building a complete anonymous membership proof system — from the Compact contract on-chain to the TypeScript tooling that generates Merkle proofs locally. We'll cover sparse Merkle trees, depth-20 path verification, nullifier-based replay prevention, and admin root management.

Why Merkle Trees for Allowlists?

Traditional allowlists publish every member's address on-chain. That's fine for transparency, but terrible for privacy. A Merkle tree solves this differently:

Off-chain: The admin maintains a list of member secrets
On-chain: Only a single 32-byte hash (the Merkle root) is stored
Proof: A member proves they know a secret that hashes to a leaf in the tree, without revealing which leaf

                    Root (on-chain)
                   /    \
                 H01    H23
                /  \    /  \
               H0  H1  H2  H3
              / \  / \ / \ / \
             L0 L1 L2 L3 ...  (2^20 leaves)

To prove you're L1, you provide H0, H23, and the path indices. The verifier recomputes the root and checks it matches the on-chain value. Your secret (L1's preimage) stays private.

The Compact Contract

The contract manages three pieces of state:

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

Witnesses (Secret Inputs)

These are the prover-side inputs that never appear on-chain:

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

Recomputing the Merkle Path

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

Checking Membership

circuit isMember(): (Bytes<32>, Bytes<32>) {
  let secret = getSecret();
  let context = getContext();
  let leaf = poseidonHash(secret);
  let computed_root = leaf;
  let siblings = getSiblings();
  let indices = getPathIndices();

  for (i in 0..20) {
    computed_root = hashLevelNode(indices[i], computed_root, siblings[i]);
  }

  assert(computed_root == merkle_root.read(), "Invalid membership proof");

  let nullifier = persistentHash<Vector<2, Bytes<32>>>([secret, context]);
  assert(not used_nullifiers.contains(nullifier), "Nullifier already used");

  (computed_root, nullifier)
}

Admin Root Management

export circuit setRoot(new_root: Bytes<32>): [] {
  let admin_secret = getAdminSecret();
  let commitment = poseidonHash(admin_secret);
  assert(commitment == admin_commitment.read(), "Not authorized");
  merkle_root.write(disclose(new_root));
}

The TypeScript Tooling

Sparse Merkle Tree Implementation

export class MerkleTree {
  readonly depth: number;
  private leaves: HashHex[] = [];
  private layers: Map<number, Map<number, HashHex>> = new Map();
  private zeroHashes: HashHex[];

  constructor(depth: number = 20) {
    this.depth = depth;
    this.zeroHashes = computeZeroHashes(depth);
    for (let i = 0; i <= depth; i++) {
      this.layers.set(i, new Map());
    }
  }

  insertLeaf(leafHash: HashHex): number {
    const leafIndex = this.leaves.length;
    this.leaves.push(leafHash);
    this.setNode(0, leafIndex, leafHash);

    let currentIndex = leafIndex;
    for (let level = 0; level < this.depth; level++) {
      const parentIndex = Math.floor(currentIndex / 2);
      const leftChild = this.getNode(level, parentIndex * 2);
      const rightChild = this.getNode(level, parentIndex * 2 + 1);
      const parentHash = hashNode(leftChild, rightChild);
      this.setNode(level + 1, parentIndex, parentHash);
      currentIndex = parentIndex;
    }
    return leafIndex;
  }
}

The Complete Flow

Step 1: Admin Sets Up the Contract

ADMIN_SECRET=$(openssl rand -hex 32)
ADMIN_COMMITMENT=$(echo -n $ADMIN_SECRET | poseidon-hash)
compact deploy --ledger admin_commitment=$ADMIN_COMMITMENT

Step 2: Add Members Off-Chain

midnight-allowlist add-member --secret "alice-secret-123"
ROOT=$(midnight-allowlist get-root)

Step 3: Push Root On-Chain

compact call setRoot --arg new_root=$ROOT --witness admin_secret=$ADMIN_SECRET

Step 4: Member Generates and Submits Proof

PROOF=$(midnight-allowlist generate-proof --secret "alice-secret-123" --context "voting-round-1")
compact call proveMembership --proof $PROOF

Edge Cases and Gotchas

1. Zero Hash Collisions

The sparse tree uses pre-computed zero hashes. Make sure your computeZeroHashes function matches exactly what the Compact contract expects.

2. Context Binding

The nullifier is hash(secret || context). Use distinct contexts for different operations:

const VOTE_CONTEXT = "governance-vote-q2-2026";
const AIRDROP_CONTEXT = "token-airdrop-genesis";

3. Tree Capacity Planning

A depth-20 tree supports ~1M members. Each additional level doubles capacity but increases proof generation time linearly.

Testing

describe('ZK Allowlist', () => {
  it('should verify valid membership proof', async () => {
    const tree = new MerkleTree(20);
    tree.insertLeaf(hashLeaf('alice-secret'));
    const proof = tree.generateMerkleProof(0);
    expect(verifyProof(tree.root, proof, hashLeaf('alice-secret'))).toBe(true);
  });
});

What's Next?

This system handles the core membership proof flow. Production deployments should consider batch root updates, Merkle tree snapshots, circuit optimization, and frontend integration.

The complete source code is available in the companion repository linked in the PR.

This tutorial is part of the Midnight Network bounty program. For more developer resources, visit docs.midnight.network.

When Proofs Fail: A Deep Dive into Debugging Midnight Proof Server Errors

BossChaos — Sat, 02 May 2026 12:36:52 +0000

When Proofs Fail: A Deep Dive into Debugging Midnight Proof Server Errors

Your contract compiles. The witness generates correctly. But proveTx hangs for five minutes and throws an error you've never seen before. Welcome to the world of ZK proof generation — where the gap between "should work" and "does work" is measured in docker logs, wire format mismatches, and version drift.

I've spent the last few months debugging proof server failures across multiple Midnight dApp projects. Most tutorials tell you to "check docker logs" and leave it at that. This one goes deeper — into the SDK source code, the HTTP protocol between your app and the proof server, and the exact failure modes that cause proofs to silently reject or timeout.

How the Proof Server Actually Works (The Architecture You Need to Understand)

Before debugging, you need to understand the request flow. The Midnight SDK doesn't use a single /prove-tx endpoint. Instead, it breaks proving into two HTTP calls against the proof server:

Your dApp
    │
    │ httpClientProofProvider(url, zkConfigProvider)
    │
    ├─→ POST /check   (validates circuit preimage)
    │       ↓
    │    Returns constraint check results
    │
    └─→ POST /prove   (generates the actual ZK proof)
            ↓
         Returns proof bytes

From the httpClientProofProvider source code, here's the critical part:

const retryOptions = {
  retries: 3,
  retryDelay: (attempt: number) => 2 ** attempt * 1_000,  // 2s, 4s, 8s
  retryOn: [500, 503]
};

The SDK automatically retries on HTTP 500 and 503 errors with exponential backoff. If you see a request taking 14+ seconds and then failing, that's not your code — that's three retries timing out.

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

BossChaos — Sat, 02 May 2026 09:32:06 +0000

Compact Standard Library: A Practical Guide to Every Export

BossChaos — Sat, 02 May 2026 04:24:22 +0000

Compact Standard Library: A Practical Guide to Every Export

The Compact standard library ships with every Midnight project — you don't install it, you don't import a package manager dependency. It's just there, baked into the compiler. But the official docs are sparse enough that most developers only discover what's available by reading other people's contracts or stumbling into a type error.

This guide fixes that. I'll walk through every meaningful export, grouped by what it actually does, with working code examples you can compile and test. The companion repository contains all the contracts as individual .compact files, ready to compile with compactc.

If you've been writing Compact contracts and keep wondering "is there a built-in way to do this?", the answer is probably in here.

Generic Types: Maybe and Either

These two show up in nearly every non-trivial contract. If you've written TypeScript or Rust, the concepts are familiar — but the ZK context adds some nuances that matter.

Maybe<T>

Maybe<T> represents an optional value: either Some(value) or None. No nulls, no sentinel values like 0 or -1 pretending to mean "not set."

contract MaybeExample {
  ledger admin: Maybe<ContractAddress>;
  ledger config: Maybe<Uint<64>>;

  circuit setAdmin(addr: ContractAddress): [] {
    assert ledger.admin.isNone : "admin already set";
    ledger.admin = Maybe.some(addr);
  }

  circuit clearAdmin(): [] {
    assert ledger.admin.isSome : "no admin to clear";
    ledger.admin = Maybe.none();
  }

  circuit isAdmin(addr: ContractAddress): [Boolean] {
    const current = ledger.admin;
    return [current.isSome && current.value == addr];
  }
}

The key properties:

.isSome — Boolean, true if the value exists
.isNone — Boolean, true if the value is absent
.value — The inner value of type T, but only safe to access when you know it's Some

Here's the critical gotcha: accessing .value on a None inside a ZK circuit doesn't throw an exception — it makes the proof impossible to generate. The constraint solver hits an unsatisfiable condition and fails silently. Always gate .value access behind an .isSome check.

A common pattern is lazy initialization:

circuit initConfig(value: Uint<64>): [] {
  if ledger.config.isNone {
    ledger.config = Maybe.some(value);
  }
}

Either<L, R>

Either<L, R> is a tagged union — one of two possible types, Left(L) or Right(R). By convention, Left carries error information and Right carries success values. Compact doesn't enforce this convention, but following it makes your code readable.

contract EitherDemo {
  circuit safeDivide(
    witness dividend: Uint<64>,
    witness divisor: Uint<64>
  ): [Either<Bytes<32>, Uint<64>>] {
    if divisor == Uint<64>::from(0) {
      return [Either.left(bytes("division by zero"))];
    }
    return [Either.right(dividend / divisor)];
  }

  circuit processResult(
    witness a: Uint<64>,
    witness b: Uint<64>
  ): [Boolean, Uint<64>] {
    const result = EitherDemo::safeDivide(a, b);
    if result.isLeft {
      return [false, Uint<64>::from(0)];
    }
    return [true, result.rightValue];
  }
}

Discriminate with .isLeft, .isRight, .leftValue, and .rightValue. Same caveat as Maybe — accessing the wrong branch causes a constraint failure, not a recoverable error.

Merkle Trees and Commitments

Merkle trees are the backbone of ZK contract design. The standard library gives you the tree type itself plus the commitment and verification primitives you need for privacy-preserving state proofs.

MerkleTree<N, T>

MerkleTree<N, T> is a complete binary Merkle tree with N levels — meaning 2^N leaves — holding values of type T. The size is fixed at compile time.

contract MerkleRegistry {
  export ledger members: MerkleTree<20, Bytes<32>>;
  export ledger memberCount: Uint<64>;

  circuit addMember(commitment: Bytes<32>): [Uint<64>] {
    const index = ledger.memberCount;
    ledger.members.set(index, commitment);
    ledger.memberCount = index + Uint<64>::from(1);
    return [index];
  }
}

Plan your tree depth early. N=16 gives you 65,536 entries (fine for small registries). N=20 gives you ~1 million (good for most production use cases). N=32 gives you 4 billion (overkill unless you're building something at scale).

The tree supports .root() to get the current root hash and .set(index, value) to update a leaf. You can verify membership with verifyMerkleProof(leaf, root, pathElements, pathIndices) — this is how you prove someone is in the registry without revealing who else is.

persistentCommit

persistentCommit(witness: Bytes<32>) creates a commitment anchored to Midnight's state tree. It's deterministic — the same secret always produces the same commitment — and it's tied to a specific epoch, enabling "this value existed at this point in time" proofs.

circuit commit(witness secret: Bytes<32>): [Bytes<32>] {
  const commitment = persistentCommit(secret);
  ledger.commitments.set(index, commitment);
  return [commitment];
}

This is the foundation of commit-reveal patterns. Commit on-chain now, reveal off-chain later when you're ready.

verifyCommitment

The counterpart to persistentCommit: given a secret and a commitment, verify they match.

circuit reveal(
  witness secret: Bytes<32>,
  public commitment: Bytes<32>
): [Boolean] {
  return [verifyCommitment(secret, commitment)];
}

Together, persistentCommit and verifyCommitment power sealed-bid auctions, private voting, and nullifier-based replay prevention.

Elliptic Curves

Midnight's ZK circuits operate over elliptic curves under the hood. The standard library surfaces some of this for contracts that need explicit cryptographic operations.

CurvePoint

CurvePoint represents a point on Midnight's elliptic curve. You interact with these when doing key derivation, signature verification, or building custom commitment schemes.

circuit derivePublicKey(
  witness privateKey: Scalar
): [CurvePoint] {
  const G = CurvePoint.generator();
  return [G.multiply(privateKey)];
}

Operations:

.generator() — Static method, returns the base point G
.multiply(scalar) — Scalar multiplication (expensive in ZK)
.add(other) — Point addition (cheaper)
.negate() — Point negation
.hashToCurve(bytes) — Hash arbitrary data to a curve point

Scalar

Scalar is a field element in the elliptic curve's scalar field. It's what you use for private keys, blinding factors, and random nonces.

circuit pedersenCommit(
  witness value: Uint<64>,
  witness blinding: Scalar
): [CurvePoint] {
  const H = CurvePoint.hashToCurve(bytes("value"));
  const G = CurvePoint.generator();
  return [H.multiply(Scalar.fromUint(value)).add(G.multiply(blinding))];
}

The Pedersen commitment pattern above is worth knowing: it commits to a value while keeping it hidden, and the commitments are additively homomorphic.

Kernel Types

These types bridge the ZK contract world and Midnight's transaction kernel. They're how your contract talks about identity, addresses, and shielded coin state.

ContractAddress

ContractAddress is the canonical identity for smart contracts. It's derived from the contract's code hash and deployment parameters — deterministic and unique.

contract AccessControlled {
  export ledger admin: ContractAddress;

  circuit initialize(adminAddr: ContractAddress): [] {
    assert ledger.admin == ContractAddress.zero() : "already initialized";
    ledger.admin = adminAddr;
  }

  circuit adminAction(): [] {
    assert ledger.admin == ContractAddress.self() : "unauthorized";
  }
}

Key methods:

.zero() — Returns the zero address (the default/unset value)
.self() — Returns this contract's own address

Use ContractAddress for identity-based access control. Never use ownPublicKey() for this purpose.

ZswapCoinPublicKey

ZswapCoinPublicKey is the public key type for Zswap coin ownership — Midnight's shielded asset system.

ledger depositor: ZswapCoinPublicKey;

circuit recordDepositor(pk: ZswapCoinPublicKey): [] {
  ledger.depositor = pk;
}

UserAddress

UserAddress is a higher-level address type that wraps both a ZswapCoinPublicKey and a spending key derivation path.

circuit getRecipientKey(userAddr: UserAddress): [ZswapCoinPublicKey] {
  return [userAddr.spendingKey()];
}

ShieldedCoinInfo

ShieldedCoinInfo describes a shielded coin: its value, token type, and randomness.

circuit inspectCoin(coinInfo: ShieldedCoinInfo): [Uint<64>, Bytes<32>] {
  return [coinInfo.value, coinInfo.tokenType];
}

QualifiedShieldedCoinInfo

QualifiedShieldedCoinInfo extends ShieldedCoinInfo with the nullifier key needed to spend the coin.

circuit deposit(witness coinProof: CoinProof): [QualifiedShieldedCoinInfo] {
  const coin = receiveShielded(coinProof);
  return [coin];
}

CoinProof

CoinProof is the ZK proof that demonstrates ownership of a shielded coin without revealing the coin's details.

Helper Circuits

These are the high-level operations for working with tokens and shielded transfers.

nativeToken()

Returns the token type identifier for MNT, Midnight's native token.

circuit acceptMNTOnly(coinType: Bytes<32>): [] {
  assert coinType == nativeToken() : "only MNT accepted";
}

tokenType(ContractAddress)

Derives the token type identifier for a custom token contract.

circuit isMyToken(coinType: Bytes<32>): [Boolean] {
  return [coinType == tokenType(ContractAddress.self())];
}

evolveNonce

evolveNonce(nonce: Bytes<32>) advances a nonce to prevent replay attacks.

circuit useNonce(witness action: Bytes<32>): [Bytes<32>] {
  const nonce = ledger.currentNonce;
  const nextNonce = evolveNonce(nonce);
  ledger.currentNonce = nextNonce;
  assert verifyCommitment(action, nonce) : "invalid nonce";
  return [nextNonce];
}

shieldedBurnAddress()

Returns the canonical burn address for Midnight.

circuit burn(amount: Uint<64>): [] {
  sendShielded(shieldedBurnAddress(), amount);
}

Shielded Token Operations

receiveShielded

receiveShielded(coinProof: CoinProof) processes an incoming shielded coin transfer.

circuit deposit(witness coinProof: CoinProof): [QualifiedShieldedCoinInfo] {
  const coin = receiveShielded(coinProof);
  assert coin.info.tokenType == nativeToken() : "MNT only";
  ledger.balance = ledger.balance + coin.info.value;
  return [coin];
}

sendShielded

sendShielded(recipient: ZswapCoinPublicKey, coin: QualifiedShieldedCoinInfo, amount: Uint<64>) constructs and sends a shielded transfer.

circuit withdraw(
  recipient: ZswapCoinPublicKey,
  amount: Uint<64>
): [] {
  assert amount <= ledger.balance : "insufficient balance";
  ledger.balance = ledger.balance - amount;
  sendShielded(recipient, ledger.heldCoin, amount);
}

Block-Time Queries

getBlockTime()

Returns the current block timestamp as a Uint<64> (Unix epoch seconds).

getBlockNumber()

Returns the current block height as a Uint<64>.

getEpoch()

Returns the current epoch number as a Uint<64>.

contract TimeEscrow {
  export ledger unlockBlock: Uint<64>;
  export ledger locked: Boolean;

  circuit lock(duration: Uint<64>): [] {
    assert !ledger.locked : "already locked";
    ledger.unlockBlock = getBlockNumber() + duration;
    ledger.locked = true;
  }

  circuit release(): [] {
    assert getBlockNumber() >= ledger.unlockBlock : "still locked";
    ledger.locked = false;
  }
}

Use getBlockNumber() for relative timing, getBlockTime() for absolute deadlines, and getEpoch() for rate-limiting.

Putting It All Together: A Token Vault

pragma language_version >= 0.22;

contract TokenVault {
  export ledger deposits: MerkleTree<16, Bytes<32>>;
  export ledger depositCount: Uint<64>;
  export ledger totalBalance: Uint<64>;
  export ledger heldCoins: MerkleTree<16, QualifiedShieldedCoinInfo>;

  circuit deposit(witness coinProof: CoinProof): [Uint<64>] {
    const coin = receiveShielded(coinProof);
    assert coin.info.tokenType == nativeToken() : "MNT only";

    const index = ledger.depositCount;
    ledger.heldCoins.set(index, coin);
    ledger.totalBalance = ledger.totalBalance + coin.info.value;
    ledger.depositCount = index + Uint<64>::from(1);

    const commitment = persistentCommit(
      coin.info.value.toBytes().concat(index.toBytes())
    );
    ledger.deposits.set(index, commitment);

    return [index];
  }

  circuit withdraw(
    coinIndex: Uint<64>,
    recipient: ZswapCoinPublicKey
  ): [] {
    const coin = ledger.heldCoins.get(coinIndex);
    assert coin.isSome : "coin not found";
    ledger.totalBalance = ledger.totalBalance - coin.value.info.value;
    sendShielded(recipient, coin.value, coin.value.info.value);
    ledger.heldCoins.set(coinIndex, Maybe.none());
  }
}

Quick Reference

Export	Category	Purpose
`Maybe<T>`	Generic	Optional values, nullable ledger fields
`Either<L, R>`	Generic	Two-outcome results, structured errors
`MerkleTree<N, T>`	Merkle	Fixed-size on-chain indexed storage
`persistentCommit`	Merkle	Creating verifiable commitments
`verifyCommitment`	Merkle	Verifying commitments in proofs
`verifyMerkleProof`	Merkle	Proving leaf membership in a tree
`CurvePoint`	Crypto	Key derivation, Pedersen commitments
`Scalar`	Crypto	Private keys, blinding factors
`ContractAddress`	Kernel	Contract identity, access control
`ZswapCoinPublicKey`	Kernel	Shielded coin recipient keys
`UserAddress`	Kernel	User-facing addresses
`ShieldedCoinInfo`	Kernel	Coin value/type metadata
`QualifiedShieldedCoinInfo`	Kernel	Spendable coin with nullifier key
`CoinProof`	Kernel	ZK proof of coin ownership
`nativeToken()`	Helper	MNT token type identifier
`tokenType(addr)`	Helper	Custom token type identifier
`evolveNonce`	Helper	Replay-protected nonce chaining
`shieldedBurnAddress()`	Helper	Canonical token burn address
`receiveShielded`	Transfer	Accept incoming shielded coins
`sendShielded`	Transfer	Send shielded coins to recipient
`getBlockTime()`	Time	Current block timestamp
`getBlockNumber()`	Time	Current block height
`getEpoch()`	Time	Current consensus epoch

Final Notes

The Compact standard library is deliberately minimal. Midnight's philosophy is to give you the cryptographic building blocks and let you compose them.

The types you'll reach for in every contract: Maybe<T>, ContractAddress, receiveShielded, sendShielded. Everything else is situational.

The biggest gotcha for newcomers: all of these operations happen inside ZK circuits. "Optional" doesn't mean "try/catch" — it means "the proof is either valid or it isn't."

All code examples are available as individual .compact files in the companion repository:
https://github.com/BossChaos/contributor-hub/tree/bounty/293-compact-stdlib/bounties/293-compact-stdlib

MidnightforDevs #Compact #ZK #Privacy #Blockchain