What actually stays private on Midnight! (A builder's mental model)

Intro

Coming from the XRPL, the challenge for me has been grasping what actually stays hidden on a privacy chain and how they acomplish that. On a transparent ledger, you always know what is public, because everything is. On Midnight the answer is not obvious, and getting it wrong is exactly how supposedly private data leaks.

Here is the mental model I use. Once it clicked, most of my privacy mistakes stopped.

Three places your data can live

On Midnight, every value in a contract sits in one of three places, and the place decides who can see it:

Witness data: private inputs that never leave the user's device.
Ledger state: public, on chain, visible to everyone forever.
Disclosed values: things you deliberately move from private to public with disclose().

Get these three straight and most privacy bugs disappear.

1. Witnesses: the private inputs

A witness is a value the contract receives from the user's local environment. It feeds the zero-knowledge proof, but it never goes on chain.

import CompactStandardLibrary;

// A private input. The prover knows it. The chain never sees it.
witness getBalance(): Bytes<32>;

The key idea: a proof can depend on a witness without revealing it. A contract can prove "the balance is at least 100" while nobody learns the balance. And anything derived from a witness is also treated as private by the compiler, which matters in a minute.

2. Ledger: the public state

Ledger fields are the opposite. They are stored on chain and readable by anyone.

// Public state. Everyone can read this, now and forever.
export ledger balance: Bytes<32>;

If a value reaches a ledger field, it is public. Full stop. There is no private ledger. So the only interesting question is how a private witness ever gets into a public ledger field. It does not, unless you say so.

3. disclose(): the deliberate door

Midnight will not let you move witness-derived data into public space by accident. If you try, the compiler stops you:

export circuit recordBalance(): [] {
  balance = getBalance();   // compiler error: undeclared disclosure
}

You have to open the door on purpose with disclose():

export circuit recordBalance(): [] {
  balance = disclose(getBalance());   // ok: you declared the disclosure
}

disclose() does not encrypt or protect anything. It is a declaration: I know this value came from private data, and I am choosing to make it public. That is the entire point. Disclosure is an explicit, auditable decision, not something that happens to you.

This is the mental flip from transparent chains. There, everything is public unless you do extra work. Here, everything private stays private unless you deliberately disclose it.

Where it gets people: the boundary is sticky

The trap is that "derived from a witness" spreads. The compiler tracks it through arithmetic, type casts, function calls, even conditionals.

witness getBalance(): Uint<64>;

export circuit balanceExceeds(n: Uint<64>): Boolean {
  return getBalance() > n;   // compiler error: the boolean still leaks the balance
}

Returning whether the balance exceeds n is not safe just because you did not return the balance itself. The comparison result is derived from private data, so the compiler still makes you disclose() it. That is the feature working. It forces you to notice that even a yes or no answer is a disclosure.

A subtler leak: disclosing is not the same as hiding

Here is the part that bites even careful people. The compiler treats some standard library routines as safe to disclose. A commitment, transientCommit or persistentCommit, is treated as not containing witness data, so you can publish it without a disclose() wrapper.

But the compiler allowing it is not the same as it being secret. If you commit or hash a value that has only a few possible inputs, anyone can brute-force it:

// looks safe, is not: a yes/no vote has only two possible hashes
recordedVote = disclose(persistentHash<Field>(localVote()));

An observer hashes 0 and 1 and instantly knows the vote. The fix is a commitment with fresh secret randomness:

witness voteSalt(): Bytes<32>;   // fresh, secret, never reused

recordedVote = persistentCommit<Field>(localVote(), voteSalt());

The salt is the real secret. Same value plus a fresh salt gives a different, unguessable output. The compiler will not verify the salt is actually fresh or secret. That part is on you.

A checklist before you ship

Before any circuit goes out:

Is it a witness, or derived from one? Then it is private, and the compiler will fight you if you leak it. Good.
Does it land in a ledger field, or get returned from an exported circuit? Then it is public. Did you mean that?
Is there a disclose() in the path? Then stop and ask: is this value low-entropy or guessable? If so, use a commitment with a fresh salt, not a bare hash.
Did I reuse a salt anywhere? Identical inputs make identical commitments, which links them. Fresh salt every time.

That is the whole model. Three buckets, one deliberate door, and a hard look at anything going through it.