Designing public vs. private state: what goes where and why

One of the most common sources of confusion when building on Midnight is the question of privacy. Developers expect that marking something as "not exported" or keeping it off the main interface will make it private. It does not. On Midnight, privacy is a deliberate design decision that requires using the right tools at the right layer. This tutorial gives you a clear framework for making that decision.

By the end, you will understand the three layers of data in a Midnight smart contract, when to use disclose(), the difference between shielded and unshielded tokens, and the common mistakes that accidentally leak private information.

Prerequisites

• Midnight toolchain installed (installation guide)
• Basic familiarity with Compact. If you have not worked through the hello world tutorial, start there
• Node.js installed for running tests

The three layers of data

Every Midnight smart contract works with data at three distinct layers. Getting clarity on these layers is the foundation of good privacy design.

Public ledger state is stored on-chain and is visible to anyone. Every field you declare with ledger lives here, regardless of whether you add export. This is the permanent, verifiable record of the contract's state.

Private state lives off-chain in the user's wallet or node. It is never written to the blockchain. It is brought into circuits through witness functions, which act as a bridge between the off-chain world and the on-chain proof. Private state is the only category of data that is genuinely hidden.

The transaction transcript is what gets revealed when a transaction is submitted. Every call to disclose() in your circuit contributes to this transcript. The transcript is public and permanent.

Understanding which layer your data belongs to is the first question you should answer when designing a contract.

Exported vs. non-exported ledger fields

Both export ledger and ledger (without export) store data on-chain. The difference is not about privacy.

pragma language_version 0.23;

import CompactStandardLibrary;

// Exported: visible to TypeScript clients and other contracts via ledger()
export ledger memberCount: Counter;
export ledger registry: Map<Bytes<32>, Bytes<32>>;

// Non-exported: still stored on-chain, not part of the generated Ledger type
ledger operationCount: Counter;

export ledger memberCount makes the field accessible through the generated ledger() function in TypeScript. It also makes it callable from other Compact contracts that import this one.

ledger operationCount without export is still stored on-chain. Anyone querying the raw contract state on the blockchain can read it. What changes is that it does not appear in the generated TypeScript Ledger type, so TypeScript clients cannot access it through the standard API.

The test below demonstrates this distinction:

const state = ledger(circuitContext.currentQueryContext.state);

// memberCount is exported - accessible through the generated Ledger type
expect(state.memberCount).toBe(1n);

// operationCount is not exported - undefined in the TypeScript API
// It is still on-chain, just not surfaced by the generated bindings
expect((state as any).operationCount).toBeUndefined();

The rule: use export to control your contract's public interface, not to control privacy. If you want something to stay private, it must not go into ledger state at all. It belongs in private state, managed through witness functions.

Private state: the only true privacy

Private state is data that never touches the blockchain. In Compact, you access it through witness declarations:

witness getCallerSecret(): Bytes<32>;

When a circuit calls this witness, the TypeScript runtime provides the value from the user's private state. The value is used inside the zero-knowledge proof but never written to the ledger. The proof confirms that the circuit ran correctly without revealing what the secret was.

This is the mechanism behind Midnight's privacy guarantees. If you need to store a user's identity, a private balance, or any sensitive value, it must live in private state and be accessed through witnesses. Putting it in a non-exported ledger field achieves nothing from a privacy standpoint.

Understanding disclose()

Every circuit parameter is a private witness by default. When a private value needs to interact with the public ledger, you must explicitly mark that transition with disclose().

In the registry contract, both the id and data parameters are private circuit inputs. Since they are being written into the public ledger, they must be disclosed:

export circuit register(id: Bytes<32>, data: Bytes<32>): [] {
    assert(!registry.member(disclose(id)), "id already registered");
    registry.insert(disclose(id), disclose(data));
    memberCount.increment(1);
    operationCount.increment(1);
}

The disclose() call tells the compiler: this value is moving from the private witness domain into the public transaction transcript. It is a deliberate, explicit act. The compiler enforces this - you cannot write a private value to the public ledger without disclosing it first.

What does not need disclose() is any computation that stays private. If you compute something from a private input and the result never touches the ledger, no disclosure is needed.

Common mistake 1: thinking non-exported means private

This is the most widespread misconception. A developer adds an internal tracking counter, omits export because it is "internal," and assumes no one can see it. But the data is on-chain. Anyone running a node or querying raw contract state can read every ledger field, exported or not.

If your field tracks something sensitive, such as a per-user action count or an internal identifier, it must not be a ledger field at all. Use private state instead.

Common mistake 2: disclosing intermediate values that leak private state

disclose() does not just reveal the value you pass it. It reveals information about where that value came from.

Consider a circuit that checks whether a user's secret key belongs to a known set:

// MISTAKE: disclosing an intermediate value derived from a private input
export circuit badCheck(secret: Bytes<32>): Boolean {
    const derived = someTransformation(secret);
    return registry.member(disclose(derived));
}

Even though secret itself is never disclosed, disclosing derived reveals that the caller knows a value that maps to derived through someTransformation. If that transformation is known or guessable, an observer can narrow down what secret must be.

The rule is to disclose only what must be public, and nothing more. If the only reason a value is being disclosed is because it touches the ledger, ask whether the ledger interaction itself can be restructured to avoid the exposure.

Common mistake 3: accidental Merkle path disclosure

Merkle trees are a common tool for proving membership in a large set without revealing the full set. The membership proof is a MerkleTreePath, which contains two things: the sibling hashes along the path from the leaf to the root, and the leaf's index (its position in the tree).

If you disclose the full path, you reveal the leaf's index. Since leaves are inserted in order, the index corresponds directly to when the user was added to the set. This can de-anonymize users by linking their position to a timestamp or insertion order.

// PRIVACY RISK: disclose(path) reveals leaf.index - the user's position in the tree
export circuit riskyVerify(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    assert(allowlist.checkRoot(merkleTreePathRoot<20, Bytes<32>>(disclose(path))));
}

The correct pattern keeps the path entirely private. The path is used inside the zero-knowledge circuit to compute the root. Only the root - which is already public ledger state - is checked:

// PREFERRED: path stays private, only the computed root is compared against public state
export circuit safeVerify(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    assert(allowlist.checkRoot(merkleTreePathRoot<20, Bytes<32>>(path)));
}

The merkleTreePathRoot circuit recomputes the root from the path entirely inside the ZK proof. The path itself never enters the transaction transcript.

Shielded vs. unshielded tokens

Token transfers introduce a separate privacy dimension. Unshielded tokens record the transferred amount on-chain. Anyone can see who sent what to whom. Shielded tokens use ZK proofs to keep the amount and the recipient hidden. Only the sender and recipient know the details.

When choosing between them, start with this question: does the amount of this transfer need to be public?

For a payment in a public marketplace, unshielded is appropriate. The amount is part of the public record of the trade. For a private payroll, a confidential investment, or any transfer where the amount reveals sensitive information, shielded tokens are the right choice.

A secondary consideration is coin color. Shielded coins carry a color field that identifies the token type. Even with shielded transfers, the token type is visible. If the token type itself is sensitive information, that is a separate design problem that requires a different approach.

Decision trees for common patterns

Where does this data belong?

• Does it need to be verified by the circuit and persist across transactions?
  • Yes, and it can be public: use export ledger
  • Yes, but only needed inside this contract: use ledger (note: still on-chain)
  • Yes, but it must stay private: use private state via a witness function
• No, it is only needed for one computation: keep it as a local variable in the circuit

Does this value need disclose()?

• Is it a circuit parameter being written to the ledger? Yes: wrap in disclose()
• Is it being passed to a ledger operation like registry.member() or registry.insert()? Yes: wrap in disclose()
• Is it an intermediate value derived from a private input, not touching the ledger? No: do not disclose it
• Is it a MerkleTreePath used only to compute a root? No: pass it directly to merkleTreePathRoot() without disclosing

Shielded or unshielded tokens?

• Must the transfer amount stay private? Yes: shielded
• Is the transfer part of a public record? Yes: unshielded
• Is auditability by a third party required? Unshielded or shielded with selective disclosure

What you have built

The registry smart contract in this tutorial demonstrates:

• Declaring export ledger fields that are accessible via the generated TypeScript API
• Declaring non-exported ledger fields that are on-chain but not surfaced in TypeScript bindings
• Using disclose() correctly when writing private circuit inputs to the public ledger
• The test that shows operationCount is absent from the generated Ledger type even though it exists on-chain

The key takeaway: privacy on Midnight is not a default. It is something you design for deliberately by choosing the right data layer, using witness functions for sensitive data, and being precise about what disclose() exposes.

Next steps

• Read the Compact language reference for the full specification of ledger types and witness functions
• Explore the Midnight developer documentation to understand how private state is managed in a full DApp
• Try building a contract that combines a public Map registry with a private Merkle tree membership proof to see both patterns working together