DEV Community

BossChaos
BossChaos

Posted on

Compact Standard Library: A Practical Guide to Every Export

#blockchain #privacy

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];
  }
}
Enter fullscreen mode Exit fullscreen mode

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);
  }
}
Enter fullscreen mode Exit fullscreen mode

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];
  }
}
Enter fullscreen mode Exit fullscreen mode

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];
  }
}
Enter fullscreen mode Exit fullscreen mode

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];
}
Enter fullscreen mode Exit fullscreen mode

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)];
}
Enter fullscreen mode Exit fullscreen mode

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)];
}
Enter fullscreen mode Exit fullscreen mode

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))];
}
Enter fullscreen mode Exit fullscreen mode

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";
  }
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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()];
}
Enter fullscreen mode Exit fullscreen mode

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];
}
Enter fullscreen mode Exit fullscreen mode

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];
}
Enter fullscreen mode Exit fullscreen mode

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";
}
Enter fullscreen mode Exit fullscreen mode

tokenType(ContractAddress)

Derives the token type identifier for a custom token contract.

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

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];
}
Enter fullscreen mode Exit fullscreen mode

shieldedBurnAddress()

Returns the canonical burn address for Midnight.

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

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];
}
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

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;
  }
}
Enter fullscreen mode Exit fullscreen mode

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());
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)