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

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