Forem: Tosin Akinbowa

# Working with Maps and Merkle Trees in Compact

Tosin Akinbowa — Wed, 22 Apr 2026 09:12:32 +0000

Two data structures power most on-chain state management on Midnight: Map and MerkleTree. They look similar at first glance because both associate keys with values, but they solve different problems. A Map gives you mutable key-value storage with direct lookups. A MerkleTree gives you an append-only commitment structure where membership can be proven without revealing anything else.

This tutorial walks you through building two contracts. The first is a Map-based registry that stores and retrieves entries by key. The second is a depth-20 Merkle-tree-based allowlist where membership is verified with a cryptographic path proof. By the end, you will know when to reach for each structure and how to wire them up correctly in Compact.

Prerequisites

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

Map vs MerkleTree: when to use each

Before writing any code, it helps to understand what problem each structure solves.

A Map is a mutable key-value store in the public ledger. You can insert, update, and delete entries freely. Lookups are direct. The entire map contents are visible on-chain, and you can iterate over them from TypeScript. Use a Map when you need to associate keys with values that change over time and when the size of the dataset is manageable.

A MerkleTree is an append-only structure. You insert leaves, but you cannot delete or update them directly. The tree's value is its root hash: a single 32-byte commitment that summarizes every leaf. Membership is proven by providing a path from the leaf to the root, not by exposing the tree contents. Use a MerkleTree when you need to prove that something is in a set without revealing the full set, or when the set can grow large and you want compact membership proofs.

The key difference is mutability vs commitment. Maps are for state you need to read and write freely. Merkle trees are for sets you need to commit to and prove membership in.

Part 1: Map-based registry

The registry contract stores entries as key-value pairs on the public ledger. Each entry maps a 32-byte key (an identifier, address, or hash) to a 32-byte value (metadata, a name hash, or any other fixed-size data). You can register new entries, look up existing ones, update values, deregister entries, and check membership. A Counter tracks the total number of registrations.

The smart contract

Create a file called registry.compact:

pragma language_version 0.22;

import CompactStandardLibrary;

export ledger registry: Map<Bytes<32>, Bytes<32>>;

export ledger entryCount: Counter;

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

export circuit update(key: Bytes<32>, newValue: Bytes<32>): [] {
    assert(registry.member(disclose(key)), "key not registered");
    registry.insert(disclose(key), disclose(newValue));
}

export circuit deregister(key: Bytes<32>): [] {
    assert(registry.member(disclose(key)), "key not registered");
    registry.remove(disclose(key));
}

export circuit isRegistered(key: Bytes<32>): Boolean {
    return registry.member(disclose(key));
}

Declaring a Map ledger field

The Map type takes two type parameters: the key type and the value type.

export ledger registry: Map<Bytes<32>, Bytes<32>>;

Keys can be any regular Compact type: Boolean, Field, Uint<N>, Bytes<N>, structs, enums, and more. Values can be any regular Compact type or any ledger-state type except Kernel. This means you can even nest Maps:

ledger nested: Map<Bytes<32>, Map<Uint<16>, Counter>>;

Nested ledger-state values must be initialized before first use with default<T>. Attempting to operate on an uninitialized nested value is a dynamic error.

Map operations in circuits

The full set of operations available inside a circuit:

registry.insert(key, value);        // insert or overwrite
registry.remove(key);               // delete an entry
registry.member(key)                // Boolean: is key present?
registry.lookup(key)                // returns the value
registry.size()                     // Uint<64>: number of entries
registry.isEmpty()                  // Boolean
registry.insertDefault(key);        // insert the default value for the value type
registry.resetToDefault();          // clear the entire map

One important rule: calling lookup on a key that does not exist is a dynamic error. Always guard lookups with a member check or an assertion, as the update and deregister circuits do above.

Why disclose?

Every circuit parameter is a private witness by default. When you write to the public ledger, Compact requires you to explicitly mark the transition with disclose. This prevents accidental leakage of private data into the public transaction transcript.

In the registry circuits, both the key and value are circuit inputs (private witnesses). Since insert writes them into the public ledger, both must be wrapped in disclose:

registry.insert(disclose(key), disclose(value));

The member check also takes a circuit input, so it needs disclose too:

assert(!registry.member(disclose(key)), "key already registered");

Iterating over a Map

Map iteration is only available from TypeScript, not inside Compact circuits. There is no in-circuit iteration syntax.

From TypeScript, after reading contract state, you can iterate using the standard iterator protocol:

const state = ledger(circuitContext.currentQueryContext.state);
for (const [key, value] of state.registry) {
  // process key and value
}

This is useful for building off-chain indexes, syncing UI state, or running queries against the contract without modifying it.

Map size and emptiness

You can query the size and emptiness of a Map inside a circuit:

const count = registry.size();    // Uint<64>
const empty = registry.isEmpty(); // Boolean

These are useful for circuits that enforce limits. For example, a registry with a maximum capacity could assert registry.size() < maxEntries before inserting.

Compile

compact compile registry.compact managed/registry

Testing the registry

Install dependencies:

npm install --save-dev vitest
npm install @midnight-ntwrk/compact-runtime

Create src/registry.test.ts:

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/registry/contract/index.js';

const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({});
  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx);

  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );

  return { contract, circuitContext };
}

const keyA = new Uint8Array(32).fill(1);
const valueA = new Uint8Array(32).fill(2);
const valueB = new Uint8Array(32).fill(3);
const keyB = new Uint8Array(32).fill(4);

describe('registry contract', () => {
  it('registers a new entry and increments the counter', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.entryCount).toBe(1n);
    expect(state.registry.member(keyA)).toBe(true);
  });

  it('looks up a registered entry', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.registry.lookup(keyA)).toEqual(valueA);
  });

  it('updates an existing entry', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    ({ context: circuitContext } = contract.impureCircuits.update(circuitContext, keyA, valueB));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.registry.lookup(keyA)).toEqual(valueB);
  });

  it('deregisters an entry', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));
    ({ context: circuitContext } = contract.impureCircuits.deregister(circuitContext, keyA));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.registry.member(keyA)).toBe(false);
  });

  it('reports correct membership for registered and unregistered keys', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.register(circuitContext, keyA, valueA));

    const { result: isA } = contract.impureCircuits.isRegistered(circuitContext, keyA);
    const { result: isB } = contract.impureCircuits.isRegistered(circuitContext, keyB);

    expect(isA).toBe(true);
    expect(isB).toBe(false);
  });
});

Run the tests:

npx vitest run src/registry.test.ts

Part 2: Merkle-tree-based allowlist

The smart contract

Create a file called allowlist.compact:

pragma language_version 0.22;

import CompactStandardLibrary;

export ledger allowlist: MerkleTree<20, Bytes<32>>;

export ledger leafCount: Counter;

witness findLeaf(leaf: Bytes<32>): MerkleTreePath<20, Bytes<32>>;

export circuit addToAllowlist(leaf: Bytes<32>): [] {
    allowlist.insert(disclose(leaf));
    leafCount.increment(1);
}

export circuit verify(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    assert(allowlist.checkRoot(merkleTreePathRoot<20, Bytes<32>>(disclose(path))), "leaf is not in allowlist");
}

Declaring a MerkleTree ledger field

The MerkleTree type takes two parameters: the depth and the leaf value type.

export ledger allowlist: MerkleTree<20, Bytes<32>>;

The depth must satisfy 2 <= depth <= 32. A depth-20 tree can hold up to 2^20 = 1,048,576 leaves. There is also a HistoricMerkleTree<depth, T> variant that accepts membership proofs made against prior versions of the tree. This is useful when the tree has frequent insertions and you want proofs to remain valid even after new leaves are added.

One important constraint: Opaque<"string"> and Opaque<"Uint8Array"> cannot be used as leaf value types. The compiler enforces this because those types cannot be correctly hashed in a ZK proof. Use Bytes<32>, Field, or other non-opaque Compact types as leaf types.

Inserting leaves

Several insert operations are available:

allowlist.insert(item);               // insert at the next free index
allowlist.insertHash(hash);           // insert a raw Bytes<32> hash
allowlist.insertIndex(item, index);   // insert at a specific index
allowlist.insertIndexDefault(index);  // insert the default value (emulates removal)

The insert operation appends the leaf at the current first free index, which increments automatically. The tree is append-only: there is no remove operation. To logically remove a leaf, insert the default value at its index using insertIndexDefault.

Witness functions and the MerkleTreePath type

Verifying membership requires a Merkle path: the sequence of sibling hashes from the leaf up to the root. This path is computed off-chain, since the circuit cannot iterate over the tree to find it.

You declare a witness function to provide the path from TypeScript:

witness findLeaf(leaf: Bytes<32>): MerkleTreePath<20, Bytes<32>>;

A witness function is not a circuit. It is a hook that lets the off-chain TypeScript code inject values into a circuit. The circuit calls findLeaf(leaf) and receives the path. The path is then used to verify membership.

MerkleTreePath<20, Bytes<32>> is the proof type. It contains the leaf value and a vector of 20 sibling entries, each with a sibling hash and a direction flag. You pass the path to merkleTreePathRoot to recompute the root, then compare it against the tree's current root with checkRoot.

Path verification

export circuit verify(leaf: Bytes<32>): [] {
    const path = findLeaf(leaf);
    assert(allowlist.checkRoot(merkleTreePathRoot<20, Bytes<32>>(disclose(path))), "leaf is not in allowlist");
}

merkleTreePathRoot recomputes the Merkle root from the path. checkRoot verifies that the computed root matches the tree's actual current root. If the leaf is not in the tree, the path will produce the wrong root and the assertion fails.

The path returned by the witness function is private data. It must be wrapped in disclose when passed to merkleTreePathRoot because the root computation involves ledger state, which is part of the public transaction transcript.

HistoricMerkleTree

There is a second variant called HistoricMerkleTree<depth, T>. It accepts membership proofs made against any past version of the tree, not just the current root. This matters in practice because Midnight transactions are submitted and confirmed asynchronously. If a new leaf is inserted between the time a user generates their proof and the time their transaction is confirmed, a regular MerkleTree would reject the now-outdated proof. A HistoricMerkleTree stores past roots and accepts proofs against any of them, making proofs resilient to concurrent insertions.

For an allowlist with infrequent insertions, the regular MerkleTree is sufficient. For high-traffic applications where the tree is updated frequently, HistoricMerkleTree is the safer choice.

Compile

compact compile allowlist.compact managed/allowlist

Implementing the witness in TypeScript

The witness function is provided when constructing the Contract object. It receives a WitnessContext and the leaf value, and must return a tuple of [privateState, path].

The WitnessContext exposes the current ledger state via context.ledger. The compiled contract's Ledger type includes findPathForLeaf on the allowlist field, which does a linear scan of the tree and returns the path for a matching leaf:

const contract = new Contract({
  findLeaf: (context: any, leaf: Uint8Array) => {
    const path = context.ledger.allowlist.findPathForLeaf(leaf);
    if (!path) throw new Error('leaf not found in allowlist');
    return [context.privateState, path];
  },
});

If you know the leaf's index, use pathForLeaf(index, leaf) instead. It runs in O(1) rather than scanning the whole tree.

Testing the allowlist

Create src/allowlist.test.ts:

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/allowlist/contract/index.js';

const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({
    findLeaf: (context: any, leaf: Uint8Array) => {
      const path = context.ledger.allowlist.findPathForLeaf(leaf);
      if (!path) throw new Error('leaf not found in allowlist');
      return [context.privateState, path];
    },
  });

  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx);

  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );

  return { contract, circuitContext };
}

const leafA = new Uint8Array(32).fill(1);
const leafB = new Uint8Array(32).fill(2);

describe('allowlist contract', () => {
  it('adds a leaf and increments the counter', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.leafCount).toBe(1n);
  });

  it('adds multiple leaves', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));
    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafB));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.leafCount).toBe(2n);
  });

  it('verifies a leaf that is in the allowlist', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));

    expect(() => {
      contract.impureCircuits.verify(circuitContext, leafA);
    }).not.toThrow();
  });

  it('rejects a leaf that is not in the allowlist', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.addToAllowlist(circuitContext, leafA));

    expect(() => {
      contract.impureCircuits.verify(circuitContext, leafB);
    }).toThrow();
  });
});

Run the tests:

npx vitest run src/allowlist.test.ts

Comparing the two approaches

The registry and allowlist illustrate two completely different approaches to the same general problem of tracking membership.

With the Map registry, every key and value is stored in the public ledger. Lookups are O(1). Updates and deletions are first-class operations. The full dataset is readable from TypeScript. The cost is that the entire registry lives on-chain, visible to anyone.

With the Merkle tree allowlist, the tree root is the only commitment stored on-chain. Proving membership requires a path of 20 sibling hashes, computed off-chain by the TypeScript witness. The circuit only verifies the proof against the root: it never reads the full tree. This lets you maintain a large allowlist without exposing all entries in the public transaction transcript. The trade-off is that deletion requires a workaround (inserting the default value), and the path lookup runs in O(n) unless you track indices separately.

Choose a Map when your contract needs mutable key-value state and the data can be public. Choose a MerkleTree when you need to prove membership in a large set with minimal on-chain footprint, or when the contents of the set should not be fully revealed.

What you have built

The registry contract demonstrates:

Declaring a Map<Bytes<32>, Bytes<32>> ledger field
Inserting, updating, and removing entries with insert, remove, and member
Using disclose when writing circuit inputs to the public ledger
Iterating over Map entries from TypeScript

The allowlist contract demonstrates:

Declaring a MerkleTree<20, Bytes<32>> ledger field with depth 20
Inserting leaves with insert
Declaring a witness function to supply a MerkleTreePath from TypeScript
Verifying membership with merkleTreePathRoot and checkRoot
Implementing the witness using findPathForLeaf from the generated Ledger type

Next steps

Explore the Compact language reference to learn about other ledger types and circuit patterns
Read the Midnight developer documentation to understand how smart contracts are deployed and queried on the network
Try combining a Map and a MerkleTree in a single smart contract to manage both mutable state and membership proofs

Accepting token deposits into a contract: receiveShielded and escrow patterns

Tosin Akinbowa — Tue, 21 Apr 2026 03:24:46 +0000

Most smart contracts treat token transfers as public events. Anyone can see who sent what to whom. Midnight flips this default. Tokens move privately, balances stay hidden, and contracts can hold funds on behalf of users without exposing the amounts involved.

This tutorial walks you through building a shielded escrow contract on Midnight. The escrow accepts a private deposit from one party, holds it securely, and releases it either to a beneficiary or back to the original depositor. You will see exactly how receiveShielded, writeCoin, mergeCoinImmediate, and sendShielded work together, and why the distinction between contract-held and user-held coins matters at every step.

What you'll build

A two-party escrow contract that:

Accepts a shielded deposit via receiveShielded and stores it using writeCoin
Accumulates additional funds using mergeCoinImmediate
Releases funds to a beneficiary via sendShielded
Returns funds to the original depositor via sendShielded
Tracks escrow state with a settled flag to prevent double-spending

Prerequisites

Midnight toolchain installed (installation guide)
Basic familiarity with Compact. If you haven't gone through the hello world tutorial, start there
Node.js installed for running tests

Contract-held coins vs user-held coins

Before writing any code, you need to understand the most important distinction in Midnight's shielded token model.

Every shielded coin has a recipient encoded into its commitment. That recipient is either a user's public key or a contract address. This isn't a metadata field. It's cryptographically embedded in the coin commitment hash itself:

commitment = hash(domain_sep, coin_info, recipient_type, recipient_bytes)

When recipient_type is left (a ZswapCoinPublicKey), the coin belongs to a user and lives in their wallet. When it's right (a ContractAddress), the coin belongs to the contract and only the contract can authorize spending it.

In Compact, you express this using the Either type:

// Sends coin to a user's wallet - user-held
left<ZswapCoinPublicKey, ContractAddress>(disclose(publicKey))

// Keeps coin with the contract - contract-held
right<ZswapCoinPublicKey, ContractAddress>(kernel.self())

In an escrow contract, the deposited coin transitions from user-held (in the depositor's wallet) to contract-held (locked in escrow) on deposit. When the escrow settles, it transitions back to user-held, going either to the beneficiary or back to the depositor.

The escrow contract

Create a file called escrow.compact. Here is the full contract:

pragma language_version 0.22;

import CompactStandardLibrary;

// The shielded coin currently held in escrow
export ledger escrowVault: QualifiedShieldedCoinInfo;

// Whether the escrow currently holds tokens
export ledger hasDeposit: Boolean;

// The depositor's public key - set at deploy time
export ledger depositor: Bytes<32>;

// The beneficiary's public key - set at deploy time
export ledger beneficiary: Bytes<32>;

// Whether the escrow has been settled (released or reclaimed)
export ledger settled: Boolean;

// Total number of deposits made
export ledger totalDeposits: Counter;

constructor(depositorPk: Bytes<32>, beneficiaryPk: Bytes<32>) {
    depositor = disclose(depositorPk);
    beneficiary = disclose(beneficiaryPk);
}

// First deposit: initializes the escrow with a coin
export circuit deposit(coin: ShieldedCoinInfo): [] {
    assert(!hasDeposit, "escrow already holds a deposit");
    assert(!settled, "escrow has already been settled");
    receiveShielded(disclose(coin));
    escrowVault.writeCoin(
        disclose(coin),
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    hasDeposit = true;
    totalDeposits.increment(1);
}

// Add more funds: merges new coin into the existing escrow balance
export circuit addFunds(coin: ShieldedCoinInfo): [] {
    assert(hasDeposit, "no deposit yet, call deposit first");
    assert(!settled, "escrow has already been settled");
    const pot = escrowVault;
    receiveShielded(disclose(coin));
    const merged = mergeCoinImmediate(pot, disclose(coin));
    escrowVault.writeCoin(
        merged,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    totalDeposits.increment(1);
}

// Release: sends the escrowed funds to the beneficiary
export circuit release(beneficiaryKey: ZswapCoinPublicKey): ShieldedSendResult {
    assert(hasDeposit, "escrow is empty");
    assert(!settled, "escrow has already been settled");
    const pot = escrowVault;
    const result = sendShielded(
        pot,
        left<ZswapCoinPublicKey, ContractAddress>(disclose(beneficiaryKey)),
        disclose(pot.value)
    );
    hasDeposit = false;
    settled = true;
    return result;
}

// Reclaim: returns the escrowed funds to the depositor
export circuit reclaim(depositorKey: ZswapCoinPublicKey): ShieldedSendResult {
    assert(hasDeposit, "escrow is empty");
    assert(!settled, "escrow has already been settled");
    const pot = escrowVault;
    const result = sendShielded(
        pot,
        left<ZswapCoinPublicKey, ContractAddress>(disclose(depositorKey)),
        disclose(pot.value)
    );
    hasDeposit = false;
    settled = true;
    return result;
}

Let's go through each section.

Ledger state

The ledger fields store everything the escrow needs to track on-chain. Every field is public but carefully chosen to reveal nothing sensitive about the amounts involved.

escrowVault holds the current locked coin as a QualifiedShieldedCoinInfo. This type represents a coin that already exists on the ledger with a known Merkle tree position. It contains a nonce, a color (the token type), a value, and an mt_index.

hasDeposit tracks whether the escrow currently holds funds. The deposit circuit sets it to true. The release and reclaim circuits clear it when the escrow settles.

depositor and beneficiary are set at deploy time via the constructor. They store the public keys of the two parties. A production escrow would use these to enforce who can call release and reclaim.

settled is a one-way flag. Once an escrow settles, no further deposits or withdrawals are allowed. This prevents the contract from being reused after the escrow agreement has concluded.

totalDeposits is a Counter that records how many deposit operations occurred. You increment it with .increment(1).

Accepting deposits with `receiveShielded` and `writeCoin`

The deposit circuit handles the first deposit into an empty escrow:

export circuit deposit(coin: ShieldedCoinInfo): [] {
    assert(!hasDeposit, "escrow already holds a deposit");
    assert(!settled, "escrow has already been settled");
    receiveShielded(disclose(coin));
    escrowVault.writeCoin(
        disclose(coin),
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    hasDeposit = true;
    totalDeposits.increment(1);
}

receiveShielded is a standard library circuit that registers a shielded coin as received by the calling contract:

circuit receiveShielded(coin: ShieldedCoinInfo): [];

It takes a ShieldedCoinInfo, a struct with three fields:

struct ShieldedCoinInfo {
  nonce: Bytes<32>;
  color: Bytes<32>;
  value: Uint<128>;
}

You must call disclose(coin) when passing the coin to receiveShielded. This makes the coin information visible in the transaction's public transcript so the network can validate that the shielded output exists.

After calling receiveShielded, you store the coin in the ledger using writeCoin:

escrowVault.writeCoin(
    disclose(coin),
    right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
);

writeCoin is the correct way to persist a received coin to ledger state. It accepts a ShieldedCoinInfo and a recipient, then automatically looks up the correct Merkle tree index at runtime. You cannot set mt_index manually to a meaningful value at circuit time because the blockchain assigns that index when the transaction is confirmed.

The right wrapper makes the stored coin contract-held. Only this contract can authorize spending it.

Accumulating funds with `mergeCoinImmediate`

The addFunds circuit allows additional deposits after the first, merging them into the existing balance:

export circuit addFunds(coin: ShieldedCoinInfo): [] {
    assert(hasDeposit, "no deposit yet, call deposit first");
    assert(!settled, "escrow has already been settled");
    const pot = escrowVault;
    receiveShielded(disclose(coin));
    const merged = mergeCoinImmediate(pot, disclose(coin));
    escrowVault.writeCoin(
        merged,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    totalDeposits.increment(1);
}

mergeCoinImmediate combines two coins into one:

circuit mergeCoinImmediate(a: QualifiedShieldedCoinInfo, b: ShieldedCoinInfo): CoinInfo;

The parameters serve different roles:

a is a QualifiedShieldedCoinInfo, the existing coin already on the ledger (the current escrow balance)
b is a ShieldedCoinInfo, the newly received coin from the current transaction

This is different from mergeCoin, which requires both coins to already be on the ledger. A coin that was just deposited in the current transaction isn't yet on the ledger with a Merkle index. mergeCoinImmediate handles exactly this case.

The function returns a CoinInfo. You pass this result to writeCoin, which handles the Merkle tree index:

const merged = mergeCoinImmediate(pot, disclose(coin));
escrowVault.writeCoin(merged, right<ZswapCoinPublicKey, ContractAddress>(kernel.self()));

The order matters: read the existing escrow coin first, then receive the new deposit, then merge.

Storing coins in `QualifiedShieldedCoinInfo` ledger fields

The escrowVault ledger field has type QualifiedShieldedCoinInfo. This type represents a coin that is fully qualified for spending, meaning it has a known position in the Merkle tree.

You never construct this type manually inside a circuit. Instead you use writeCoin on the ledger cell. writeCoin takes a ShieldedCoinInfo (or CoinInfo from a merge), looks up the Merkle index allocated during the current transaction, and stores the result as QualifiedShieldedCoinInfo:

escrowVault.writeCoin(coin, recipient);

This is important. Setting mt_index: 0 manually would only be valid if you were spending the coin in the same transaction it was created. For coins that need to persist across transactions, writeCoin is the only correct approach.

Releasing and reclaiming with `sendShielded`

sendShielded moves a contract-held coin to a user's wallet:

circuit sendShielded(
    input: QualifiedShieldedCoinInfo,
    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
    value: Uint<128>
): ShieldedSendResult;

It returns a ShieldedSendResult:

struct ShieldedSendResult {
  change: Maybe<ShieldedCoinInfo>;
  sent: ShieldedCoinInfo;
}

sent is the coin that goes to the recipient. change holds any remainder if you sent less than the full balance.

Both release and reclaim send the full escrow balance, so there is no change. They use pot.value to read the full amount from the stored coin:

const pot = escrowVault;
const result = sendShielded(
    pot,
    left<ZswapCoinPublicKey, ContractAddress>(disclose(beneficiaryKey)),
    disclose(pot.value)
);
hasDeposit = false;
settled = true;
return result;

The left wrapper sends the coin to the recipient's public key as a user-held coin. The network creates an encrypted output so their wallet can discover it.

Setting settled = true after the transfer permanently closes the escrow. The assert(!settled, ...) guards in every circuit prevent any further operations.

Compiling the contract

Run the Compact compiler against your escrow contract:

compact compile escrow.compact managed/escrow

This generates:

managed/escrow/contract/index.js: the compiled JavaScript contract
managed/escrow/contract/index.d.ts: TypeScript type definitions
managed/escrow/zkir/: ZK intermediate representation files for each circuit

Testing the escrow

Install dependencies:

npm install --save-dev vitest
npm install @midnight-ntwrk/compact-runtime

Create a test file at src/escrow.test.ts:

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/escrow/contract/index.js';

const depositorPk = new Uint8Array(32).fill(1);
const beneficiaryPk = new Uint8Array(32).fill(2);
const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({});
  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx, depositorPk, beneficiaryPk);

  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );

  return { contract, circuitContext };
}

const mockCoin = {
  nonce: new Uint8Array(32).fill(3),
  color: new Uint8Array(32).fill(4),
  value: 100n,
};

describe('escrow contract', () => {
  it('accepts a deposit into an empty escrow', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.deposit(circuitContext, mockCoin));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasDeposit).toBe(true);
    expect(state.totalDeposits).toBe(1n);
    expect(state.settled).toBe(false);
  });

  it('increments deposit counter when adding more funds', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.deposit(circuitContext, mockCoin));
    ({ context: circuitContext } = contract.impureCircuits.addFunds(circuitContext, mockCoin));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.totalDeposits).toBe(2n);
    expect(state.hasDeposit).toBe(true);
  });

  it('releases funds to beneficiary and marks escrow as settled', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.deposit(circuitContext, mockCoin));

    const beneficiaryKey = { bytes: new Uint8Array(32).fill(2) };
    ({ context: circuitContext } = contract.impureCircuits.release(
      circuitContext,
      beneficiaryKey,
    ));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasDeposit).toBe(false);
    expect(state.settled).toBe(true);
  });

  it('reclaims funds to depositor and marks escrow as settled', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.deposit(circuitContext, mockCoin));

    const depositorKey = { bytes: new Uint8Array(32).fill(1) };
    ({ context: circuitContext } = contract.impureCircuits.reclaim(
      circuitContext,
      depositorKey,
    ));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasDeposit).toBe(false);
    expect(state.settled).toBe(true);
  });
});

Run the tests:

npx vitest run src/escrow.test.ts

Each test initializes the contract, runs one or more circuits, then reads the resulting ledger state. No network, no proof server, no wallet required.

What you've built

Your escrow contract demonstrates the full lifecycle of shielded token deposits on Midnight:

receiveShielded registers a shielded coin as received by the contract, making the coin information visible in the public transaction transcript
writeCoin persists the received coin into a QualifiedShieldedCoinInfo ledger field, handling the Merkle tree index lookup automatically
mergeCoinImmediate accumulates additional deposits by combining an existing ledger coin with a newly received transient coin
sendShielded with left<ZswapCoinPublicKey, ContractAddress> transfers the escrowed funds to either the beneficiary or the depositor as a user-held coin
The settled flag permanently closes the escrow after a single settlement, preventing reuse

The transition from user-held to contract-held on deposit, and back to user-held on settlement, is enforced cryptographically. The recipient type is embedded in the coin commitment hash itself. Your escrow exploits this to hold tokens privately on behalf of two parties while maintaining clear rules about when and how the funds move.

Next steps

Explore the Compact language reference to learn about other ledger types and circuit patterns
Read the Midnight developer documentation to understand how smart contracts are deployed and queried on the network
Try combining a Map and a MerkleTree in a single smart contract to manage both mutable state and membership proofs

Building a shielded token vault: deposit, accumulate, and withdraw

Tosin Akinbowa — Sat, 18 Apr 2026 16:48:25 +0000

Most blockchain applications treat token balances as public information. You can look up any address and see exactly what it holds. Midnight takes a different approach. It lets you build contracts where balances stay private, transactions reveal only what they must, and users retain control of their financial data.

This tutorial walks you through building a shielded token vault on Midnight. By the end, you'll have a working Compact contract that accepts private deposits, accumulates them using coin merging, and handles withdrawals, along with tests to verify each circuit.

What you'll build

A vault contract that:

Accepts shielded token deposits via receiveShielded
Accumulates multiple deposits into a single vault coin using mergeCoinImmediate
Tracks vault state using ledger commitments
Handles withdrawals via sendShielded, splitting the vault coin into a user coin and a change coin
Distinguishes between contract-held and user-held coins at every step

Prerequisites

Midnight toolchain installed (installation guide)
Basic familiarity with Compact. If you haven't gone through the hello world tutorial, start there
Node.js and a package manager for running tests

Contract-held coins vs user-held coins

Before writing any code, you need to understand the most fundamental distinction in Midnight's shielded token model.

commitment = hash(domain_sep, coin_info, recipient_type, recipient_bytes)

In Compact, you express this distinction using the Either type:

// Sends coin to a user's wallet - user-held
left<ZswapCoinPublicKey, ContractAddress>(disclose(publicKey))

// Keeps coin with the contract - contract-held
right<ZswapCoinPublicKey, ContractAddress>(kernel.self())

A vault contract holds tokens on behalf of users. When someone deposits, their coin becomes contract-held. When they withdraw, the contract sends a user-held coin back to their wallet. This transition from user-held to contract-held on deposit, and back to user-held on withdrawal, is the core lifecycle of your vault.

The vault contract

Create a file called vault.compact. Here is the full contract:

pragma language_version 0.22;

import CompactStandardLibrary;

// The shielded coin currently held by the vault
export ledger shieldedVault: QualifiedShieldedCoinInfo;

// Whether the vault currently holds tokens
export ledger hasShieldedTokens: Boolean;

// The vault owner's public key - set at deploy time
export ledger owner: Bytes<32>;

// Total number of deposits made
export ledger totalShieldedDeposits: Counter;

// Total number of withdrawals made
export ledger totalShieldedWithdrawals: Counter;

constructor(ownerPk: Bytes<32>) {
    owner = disclose(ownerPk);
}

// First deposit: call this when the vault is empty
export circuit initVault(coin: ShieldedCoinInfo): [] {
    assert(!hasShieldedTokens, "vault already initialized");
    receiveShielded(disclose(coin));
    shieldedVault.writeCoin(
        disclose(coin),
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    hasShieldedTokens = true;
    totalShieldedDeposits.increment(1);
}

// Subsequent deposits: merges new coin into the existing vault coin
export circuit depositShielded(coin: ShieldedCoinInfo): [] {
    assert(hasShieldedTokens, "vault not initialized, call initVault first");
    const pot = shieldedVault;
    receiveShielded(disclose(coin));
    const merged = mergeCoinImmediate(pot, disclose(coin));
    shieldedVault.writeCoin(
        merged,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    totalShieldedDeposits.increment(1);
}

export circuit withdrawShielded(
    publicKey: ZswapCoinPublicKey,
    value: Uint<128>
): ShieldedSendResult {
    assert(hasShieldedTokens, "vault is empty");
    const pot = shieldedVault;
    const result = sendShielded(
        pot,
        left<ZswapCoinPublicKey, ContractAddress>(disclose(publicKey)),
        disclose(value)
    );
    if (result.change.is_some) {
        shieldedVault.writeCoin(
            result.change.value,
            right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
        );
    } else {
        hasShieldedTokens = false;
    }
    totalShieldedWithdrawals.increment(1);
    return result;
}

Let's go through each section.

Ledger state

The ledger declarations are what the contract stores on-chain. Every field is public, visible to anyone who queries the contract state, but the values are carefully chosen to reveal nothing sensitive.

shieldedVault holds the current vault coin as a QualifiedShieldedCoinInfo. This is a coin that already exists on the ledger and can be spent. It contains a nonce, a color (the token type), a value, and an mt_index for its position in the Merkle tree.

hasShieldedTokens is a simple flag. initVault sets it to true on the first deposit. withdrawShielded clears it if the vault is fully drained.

owner stores the vault owner's public key as a Bytes<32>. You set this at deploy time via the constructor. A production vault would use this to gate withdrawals so only the owner can call withdrawShielded.

totalShieldedDeposits and totalShieldedWithdrawals are Counter types. They don't reveal amounts, but they give you an on-chain audit trail of activity. You increment them with .increment(1), not arithmetic assignment.

Initializing the vault with `initVault`

The vault uses two separate deposit circuits because the first deposit and subsequent deposits require different operations.

initVault handles the first deposit. The vault is empty, so there is no existing coin to merge with:

export circuit initVault(coin: ShieldedCoinInfo): [] {
    assert(!hasShieldedTokens, "vault already initialized");
    receiveShielded(disclose(coin));
    shieldedVault.writeCoin(
        disclose(coin),
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    hasShieldedTokens = true;
    totalShieldedDeposits.increment(1);
}

receiveShielded is a standard library circuit that marks a shielded coin as received by the calling contract. Its signature is:

circuit receiveShielded(coin: ShieldedCoinInfo): [];

It takes a ShieldedCoinInfo, a struct containing a nonce, a color (token type identifier), and a value:

struct ShieldedCoinInfo {
  nonce: Bytes<32>;
  color: Bytes<32>;
  value: Uint<128>;
}

You must call disclose(coin) when passing the coin to receiveShielded. This makes the coin information visible in the transaction's public transcript, which the network needs to validate that the shielded output actually exists.

After receiving the coin, writeCoin stores it in the shieldedVault ledger field:

shieldedVault.writeCoin(disclose(coin), right<ZswapCoinPublicKey, ContractAddress>(kernel.self()));

writeCoin accepts a ShieldedCoinInfo and a recipient, and automatically looks up the correct Merkle tree index at runtime. You cannot set mt_index to a meaningful value at circuit time because the index is assigned by the blockchain when the transaction is confirmed. writeCoin handles this lookup for you.

The right wrapper makes the coin contract-held, meaning only this contract can spend it.

Accumulating deposits with `depositShielded` and `mergeCoinImmediate`

depositShielded handles all deposits after the first. This is where the vault's accumulation logic lives:

export circuit depositShielded(coin: ShieldedCoinInfo): [] {
    assert(hasShieldedTokens, "vault not initialized, call initVault first");
    const pot = shieldedVault;
    receiveShielded(disclose(coin));
    const merged = mergeCoinImmediate(pot, disclose(coin));
    shieldedVault.writeCoin(
        merged,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
    totalShieldedDeposits.increment(1);
}

mergeCoinImmediate combines the existing vault coin with the newly deposited coin:

circuit mergeCoinImmediate(a: QualifiedShieldedCoinInfo, b: ShieldedCoinInfo): CoinInfo;

The key distinction between its two parameters:

a is a QualifiedShieldedCoinInfo, an existing coin already on the ledger (your vault's current balance)
b is a ShieldedCoinInfo, a newly created coin arriving in the current transaction (the deposit)

This is different from mergeCoin, which takes two coins both already on the ledger. When a user deposits, their coin exists only as a transient created within the same transaction. mergeCoinImmediate is designed exactly for this case.

The function returns a CoinInfo. You store it back to the vault ledger field using writeCoin, which handles the Merkle tree index automatically:

const merged = mergeCoinImmediate(pot, disclose(coin));
shieldedVault.writeCoin(merged, right<ZswapCoinPublicKey, ContractAddress>(kernel.self()));

The order matters: read the existing vault coin first, receive the new deposit, then merge.

Tracking balances with commitments

The vault's on-chain state never stores a raw balance. It stores QualifiedShieldedCoinInfo and the actual value inside that struct is part of the shielded coin commitment, not plaintext.

If you need to track per-user private balances separately from the coin itself, Compact provides persistentCommit:

commitment = persistentCommit<Uint<64>>(balance, randomness)

This produces a Bytes<32> that you can store on the ledger. Anyone can see the commitment, but without knowing both the balance and the randomness, they can't determine the actual value. In a ZK circuit, you can prove that a new commitment is consistent with an old one, that the balance changed by exactly a certain delta, without revealing either value.

For the vault contract in this tutorial, the coin value itself serves as the balance tracker. The shieldedVault field always reflects the current accumulated total inside its shielded commitment. You don't need a separate balance commitment unless you're building multi-user vaults where different depositors track their individual shares.

Withdrawing with `sendShielded`

sendShielded is the circuit that moves a contract-held coin to a user's wallet:

circuit sendShielded(
    input: QualifiedShieldedCoinInfo,
    recipient: Either<ZswapCoinPublicKey, ContractAddress>,
    value: Uint<128>
): ShieldedSendResult;

It returns a ShieldedSendResult:

struct ShieldedSendResult {
  change: Maybe<ShieldedCoinInfo>;
  sent: ShieldedCoinInfo;
}

sent is the user-held coin that goes to the recipient's wallet. change is the remaining balance, a new ShieldedCoinInfo if input.value > value. Your withdrawShielded circuit handles both cases:

const result = sendShielded(
    pot,
    left<ZswapCoinPublicKey, ContractAddress>(disclose(publicKey)),
    disclose(value)
);
if (result.change.is_some) {
    shieldedVault.writeCoin(
        result.change.value,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
} else {
    hasShieldedTokens = false;
}

The change field is a Maybe<ShieldedCoinInfo>. You check result.change.is_some before accessing result.change.value. The change coin is stored back into the vault using writeCoin, keeping it contract-held.

The left wrapper sends the sent coin to the user's public key, making it user-held. The network creates an encrypted output so the user's wallet can discover and track it.

One important note from the documentation: sendShielded does not currently create coin ciphertexts for arbitrary recipients. This means that if you're sending to a public key other than the caller's own wallet, that recipient won't automatically discover the coin. For production vaults, ensure the recipient is the same user calling the circuit.

Compiling the contract

Run the Compact compiler against your vault contract:

compact compile vault.compact managed/vault

This generates:

managed/vault/contract/index.js: the compiled JavaScript contract
managed/vault/contract/index.d.ts: TypeScript type definitions
managed/vault/zkir/: ZK intermediate representation files for each circuit

Testing the vault

Install the required dependencies:

npm install --save-dev vitest
npm install @midnight-ntwrk/compact-runtime

Create a test file at src/vault.test.ts. Compact's compiled output is a standard ES module, so you can test circuits directly without a running node or proof server:

import { describe, it, expect } from 'vitest';
import {
  createConstructorContext,
  createCircuitContext,
  sampleContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import { Contract, ledger } from '../managed/vault/contract/index.js';

const ownerPk = new Uint8Array(32);
const coinPublicKey = new Uint8Array(32);
const contractAddress = sampleContractAddress();

function createSimulator() {
  const contract = new Contract({});
  const constructorCtx = createConstructorContext({}, coinPublicKey);
  const { currentPrivateState, currentContractState, currentZswapLocalState } =
    contract.initialState(constructorCtx, ownerPk);

  const circuitContext = createCircuitContext(
    contractAddress,
    currentZswapLocalState,
    currentContractState,
    currentPrivateState,
  );

  return { contract, circuitContext };
}

const mockCoin = {
  nonce: new Uint8Array(32).fill(1),
  color: new Uint8Array(32).fill(2),
  value: 100n,
};

describe('vault contract', () => {
  it('initializes vault on first deposit', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.initVault(circuitContext, mockCoin));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasShieldedTokens).toBe(true);
    expect(state.totalShieldedDeposits).toBe(1n);
  });

  it('increments deposit counter on subsequent deposit', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.initVault(circuitContext, mockCoin));
    ({ context: circuitContext } = contract.impureCircuits.depositShielded(circuitContext, mockCoin));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.totalShieldedDeposits).toBe(2n);
  });

  it('clears hasShieldedTokens after a full withdrawal', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.initVault(circuitContext, mockCoin));

    const userPublicKey = { bytes: new Uint8Array(32).fill(9) };
    ({ context: circuitContext } = contract.impureCircuits.withdrawShielded(
      circuitContext,
      userPublicKey,
      100n,
    ));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasShieldedTokens).toBe(false);
    expect(state.totalShieldedWithdrawals).toBe(1n);
  });

  it('keeps change in vault after a partial withdrawal', () => {
    let { contract, circuitContext } = createSimulator();

    ({ context: circuitContext } = contract.impureCircuits.initVault(circuitContext, {
      ...mockCoin,
      value: 200n,
    }));

    const userPublicKey = { bytes: new Uint8Array(32).fill(9) };
    ({ context: circuitContext } = contract.impureCircuits.withdrawShielded(
      circuitContext,
      userPublicKey,
      50n,
    ));
    const state = ledger(circuitContext.currentQueryContext.state);

    expect(state.hasShieldedTokens).toBe(true);
    expect(state.totalShieldedWithdrawals).toBe(1n);
  });
});

Run the tests:

npx vitest run src/vault.test.ts

Each test calls a circuit directly on the compiled contract object, passes a context with the initial ledger and private state, and asserts on the resulting state. No network, no proof server, no wallet required.

What you've built

Your vault contract demonstrates the full shielded token lifecycle on Midnight:

initVault accepts the first coin deposit and stores it using writeCoin, which handles the Merkle tree index lookup automatically
depositShielded uses mergeCoinImmediate to accumulate subsequent deposits, merging the existing ledger coin with the new transient deposit coin
writeCoin is the correct way to persist any shielded coin to ledger state for future spending
sendShielded with left<ZswapCoinPublicKey, ContractAddress> transfers a user-held coin back to the caller's wallet
The change field in ShieldedSendResult lets partial withdrawals leave a remainder in the vault, also stored via writeCoin

The distinction between contract-held and user-held coins isn't just architectural. It's cryptographic. The recipient type is embedded in the coin commitment hash, and only the right key can authorize spending each type. Your vault exploits this to hold tokens privately on behalf of users while maintaining full control over when and how they move.

Next steps

Explore the Compact language reference to learn about other ledger types and circuit patterns
Read the Midnight developer documentation to understand how smart contracts are deployed and queried on the network
Try combining a Map and a MerkleTree in a single smart contract to manage both mutable state and membership proofs

# Understanding wallet sync: why your deploy fails before it starts

Tosin Akinbowa — Mon, 13 Apr 2026 15:00:19 +0000

You've set up the Midnight toolchain, written your first Compact contract, and you're ready to deploy. You call balanceUnboundTransaction and either nothing happens, or you get an error that gives you nothing useful to work with. You restart, try again, same result.

This is a sync timing problem, and it's one of the most common stumbling blocks for developers new to Midnight. Once you understand why it happens and how the wallet is structured internally, you won't fall into this trap again.

This tutorial covers what balanceUnboundTransaction needs before it can work, how Midnight's wallet splits into three separate sub-wallets that each sync independently, a real documented bug with the dust wallet on idle chains, and the safe pattern for waiting on sync before you touch any transaction logic.

What `balanceUnboundTransaction` actually does

When you build a transaction in Midnight, you start with an unbound transaction a description of what you intend to do without any inputs or outputs selected yet. Before the network can process it, the wallet needs to figure out which UTXOs to draw from, handle any shielded balancing using ZK notes, and attach tDUST to cover fees.

balanceUnboundTransaction does all of that in up to four steps: shielded balancing (creating a separate shielded balancing transaction), unshielded balancing (applied in place on the base transaction), dust/fee balancing (using tDUST tokens), and finally merging the shielded and fee components together.

The method signature reflects this it needs more than just the transaction:

const recipe = await facade.balanceUnboundTransaction(
  tx,
  {
    shieldedSecretKeys: myZswapSecretKeys,
    dustSecretKey: myDustSecretKey,
  },
  { ttl: new Date(Date.now() + 60 * 60 * 1000) }, // 1 hour TTL
);

// recipe is an UnboundTransactionRecipe finalize it before submitting
const finalizedTx = await facade.finalizeRecipe(recipe);

The result is an UnboundTransactionRecipe, not a ready-to-submit transaction. You call finalizeRecipe on it afterward to get a FinalizedTransaction.

Both steps balanceUnboundTransaction and finalizeRecipe pull from the wallet's local state. The wallet doesn't query the network each time; it works from what it has already indexed. If the wallet hasn't finished syncing, that local state is incomplete. You might get an error, or worse, a "balanced" transaction built on stale data that the network rejects downstream with a cryptic error that looks like a contract issue rather than a sync issue.

The fix is simple in principle: wait for the wallet to finish syncing before you call any transaction methods. Understanding what that sync actually involves is what makes the fix reliable.

The three sub-wallets: shielded, unshielded, and dust

Midnight's wallet isn't a single component. It's a facade that wraps three separate sub-wallets, each responsible for a different type of asset. The FacadeState you get from facade.state() reflects all three:

// FacadeState structure
class FacadeState {
  shielded: ShieldedWalletState;   // state.shielded.state.progress
  unshielded: UnshieldedWalletState; // state.unshielded.progress
  dust: DustWalletState;           // state.dust.state.progress

  get isSynced(): boolean {
    return (
      this.shielded.state.progress.isStrictlyComplete() &&
      this.dust.state.progress.isStrictlyComplete() &&
      this.unshielded.progress.isStrictlyComplete()
    );
  }
}

Each sub-wallet syncs on its own timeline. All three need to reach the current chain tip before isSynced returns true.

Shielded wallet

The shielded wallet manages private assets protected by zero-knowledge proofs. Every shielded transaction on-chain is encrypted only the holder of the correct spending keys can read it. Your wallet scans every block, attempts trial decryption of every shielded output, and builds an internal Merkle tree of your unspent notes.

This is the heaviest sync of the three. For each block, the wallet runs cryptographic work to check whether outputs belong to you. On a chain with significant history, the first sync can take several minutes. On a fresh local devnet with minimal block history, it's much faster. The shielded wallet is considered synced when it has processed all blocks up to the current chain tip and decrypted all relevant notes.

Unshielded wallet

The unshielded wallet handles transparent UTXO-based assets tokens and coins visible on-chain. Syncing works similarly to how a Bitcoin wallet catches up: it scans for UTXOs associated with your public address and tracks which have been spent.

Because it doesn't need to perform ZK trial decryption, it syncs faster than the shielded wallet. It still scans from your wallet's birthday block (the height at which the wallet was created), so on chains with high transaction volume it's not instant.

Dust wallet

The dust wallet manages tDUST the small token denomination used to pay transaction fees. Every transaction you submit consumes tDUST from this wallet. It aggregates small UTXOs and keeps enough available to fund transactions without requiring you to manage fees manually.

The dust wallet has a different sync model from the other two. Rather than scanning for your addresses or decrypting your notes, it tracks and aggregates a class of small UTXOs. This works efficiently on active chains, but it creates a specific edge case on idle ones that can silently break your application.

The dust wallet bug: `isStrictlyComplete()` on idle chains

On an active chain, there's a regular stream of new blocks. The dust wallet processes each block, updates its progress, and eventually reports that it has caught up to the current tip isStrictlyComplete() returns true.

On an idle chain one with no recent transactions that stream stalls. The dust wallet reaches the last known block and then waits. No new blocks arrive, so it never gets confirmation that it's at the tip. isStrictlyComplete() keeps returning false.

The result: any sync strategy that requires isStrictlyComplete() to return true for the dust wallet will silently wait forever on an idle chain.

This hits hardest in local development. Your local devnet sits idle between your own transactions. If you're running integration tests, the chain may have no activity at all between test runs. Here's the pattern from the Midnight bulletin board example (wallet-utils.ts) that demonstrates the problem:

Rx.filter(
  (state: FacadeState) =>
    isProgressStrictlyComplete(state.shielded.state.progress) &&
    isProgressStrictlyComplete(state.dust.state.progress) &&      // ← never true on idle chains
    isProgressStrictlyComplete(state.unshielded.progress),
)

The filter requires all three to return true before passing the state downstream. On an idle chain, state.dust.state.progress.isStrictlyComplete() never flips, so this filter never passes. The observable waits, your application appears frozen, and after the timeout (default 180 seconds) it finally throws an error.

If you've ever run a Midnight app locally and watched it hang at "syncing wallet..." without ever progressing, this is why.

The safe sync pattern

The right approach is to use facade.state() combined with a filter on isSynced and an explicit timeout:

import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
import * as Rx from 'rxjs';

async function waitForWalletSync(facade: WalletFacade): Promise<void> {
  await Rx.firstValueFrom(
    facade.state().pipe(
      Rx.filter(s => s.isSynced),
      Rx.timeout({
        each: 180_000,
        with: () =>
          Rx.throwError(
            () => new Error('Wallet sync timed out. Check your node connection.'),
          ),
      }),
    ),
  );
}

Breaking this down:

facade.state() returns an Observable<FacadeState> built with combineLatest across all three sub-wallet state streams. It emits a new FacadeState whenever any sub-wallet updates.
filter(s => s.isSynced) checks the facade's isSynced computed getter, which evaluates isStrictlyComplete() on all three sub-wallets synchronously. States where isSynced is false are discarded.
firstValueFrom resolves the observable into a promise that completes after the first state where isSynced is true.
timeout ensures the promise rejects with a meaningful error if sync never completes which happens when the node is unreachable or, on idle chains, when the dust wallet's progress never reaches strictly complete.

The timeout is what turns a silent hang into an actionable error. Without it, on an idle chain where the dust wallet never completes, your application waits indefinitely.

A complete working example

Here's an initialization and deployment sequence. Wallet setup requires key derivation via HDWallet the focus here is the sync wait between start() and any transaction call:

import * as ledger from '@midnight-ntwrk/ledger-v8';
import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
import { ShieldedWallet } from '@midnight-ntwrk/wallet-sdk-shielded';
import { UnshieldedWallet, PublicKey, createKeystore } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
import { DustWallet } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
import * as Rx from 'rxjs';

async function initializeWallet(
  configuration: DefaultConfiguration,
  shieldedSecretKeys: ledger.ZswapSecretKeys,
  dustSecretKey: ledger.DustSecretKey,
  unshieldedKeystore: ReturnType<typeof createKeystore>,
): Promise<WalletFacade> {
  // WalletFacade.init() wires together the three sub-wallets and supporting services
  const facade = await WalletFacade.init({
    configuration,
    shielded: (config) => ShieldedWallet(config).startWithSecretKeys(shieldedSecretKeys),
    unshielded: (config) => UnshieldedWallet(config).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
    dust: (config) =>
      DustWallet(config).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
  });

  // start() begins sync for all three sub-wallets — it requires the secret keys needed
  // for shielded and dust scanning, but it returns before sync completes
  await facade.start(shieldedSecretKeys, dustSecretKey);

  // Wait until all three sub-wallets report isSynced === true before proceeding
  await Rx.firstValueFrom(
    facade.state().pipe(
      Rx.filter(s => s.isSynced),
      Rx.timeout({
        each: 180_000,
        with: () =>
          Rx.throwError(() => new Error('Wallet sync timed out after 3 minutes')),
      }),
    ),
  );

  return facade;
}

async function deployContract(
  facade: WalletFacade,
  unboundTx: UnboundTransaction,
  shieldedSecretKeys: ledger.ZswapSecretKeys,
  dustSecretKey: ledger.DustSecretKey,
): Promise<void> {
  const ttl = new Date(Date.now() + 60 * 60 * 1000); // 1 hour

  // Balance the transaction — selects UTXOs, handles shielded/unshielded/dust
  const recipe = await facade.balanceUnboundTransaction(
    unboundTx,
    { shieldedSecretKeys, dustSecretKey },
    { ttl },
  );

  // Finalize the recipe into a submittable transaction
  const finalizedTx = await facade.finalizeRecipe(recipe);

  await facade.submitTransaction(finalizedTx);
}

The unsafe version which you'll see in early examples looks like this:

// Unsafe: start() returns before sync is complete
await facade.start(shieldedSecretKeys, dustSecretKey);
const recipe = await facade.balanceUnboundTransaction(unboundTx, secretKeys, { ttl }); // race condition

facade.start() returns as soon as the sync process begins, not when it completes. If you call balanceUnboundTransaction immediately after, you're in a race against all three sub-wallets, and on any chain with real history, the wallet isn't ready yet.

Showing sync progress in a frontend

If you're building a UI, subscribe to the wallet state and surface progress to your users:

facade.state().subscribe(state => {
  if (!state.isSynced) {
    console.log('Syncing...');
    // Access per-sub-wallet balances once synced
    // state.shielded.balances — shielded token balances
    // state.unshielded.balances — unshielded token balances
    // state.dust.walletBalance(new Date()) — available tDUST
  } else {
    console.log('Wallet ready.');
  }
});

A progress indicator while the wallet syncs prevents users from concluding the application is broken and closing it before it finishes.

Common mistakes to avoid

Calling balanceUnboundTransaction right after facade.start(). The start call returns early. Always wait on isSynced before any transaction work.

Not setting a sync timeout. On idle chains, the dust wallet may never reach strictly complete and isSynced will stay false. Add Rx.timeout() to convert a silent hang into a clear error.

Assuming the wallet stays synced on restart. If your user closes and reopens the application, the wallet needs to catch up on blocks produced while it was offline. Always wait on isSynced, even if the wallet has synced before.

Checking isStrictlyComplete() on individual sub-wallet progress directly. Use s.isSynced from the facade state instead. The facade getter is the right level of abstraction checking individual sub-wallets bypasses any facade-level handling and exposes you directly to the idle chain behavior.

Summary

The wallet sync issue on Midnight comes from one simple misunderstanding: facade.start() begins sync but doesn't wait for it to finish. All three sub-wallets shielded, unshielded, and dust need to reach the current chain tip before balanceUnboundTransaction has the complete local state it needs.

The dust wallet makes this harder. On chains with no recent activity, its progress never reaches isStrictlyComplete() === true, which means isSynced stays false and any code waiting on sync appears to hang.

The safe pattern pairs filter(s => s.isSynced) with a timeout() operator so your application either proceeds cleanly or fails with a useful error message:

await Rx.firstValueFrom(
  facade.state().pipe(
    Rx.filter(s => s.isSynced),
    Rx.timeout({ each: 180_000, with: () => Rx.throwError(() => new Error('Sync timed out')) }),
  ),
);

Put this between facade.start() and any call to balanceUnboundTransaction, and your deploys will start on solid ground every time.

Next steps

Explore the Compact language reference to learn about other ledger types and circuit patterns
Read the Midnight developer documentation to understand how smart contracts are deployed and queried on the network
Try combining a Map and a MerkleTree in a single smart contract to manage both mutable state and membership proofs

Forem: Tosin Akinbowa

# Working with Maps and Merkle Trees in Compact

Prerequisites

Map vs MerkleTree: when to use each

Part 1: Map-based registry

The smart contract

Declaring a Map ledger field

Map operations in circuits

Why disclose?

Iterating over a Map

Map size and emptiness

Compile

Testing the registry

Part 2: Merkle-tree-based allowlist

The smart contract

Declaring a MerkleTree ledger field

Inserting leaves

Witness functions and the MerkleTreePath type

Path verification

HistoricMerkleTree

Compile

Implementing the witness in TypeScript

Testing the allowlist

Comparing the two approaches

What you have built

Next steps

Accepting token deposits into a contract: receiveShielded and escrow patterns

What you'll build

Prerequisites

Contract-held coins vs user-held coins

The escrow contract

Ledger state

Accepting deposits with receiveShielded and writeCoin

Accumulating funds with mergeCoinImmediate

Storing coins in QualifiedShieldedCoinInfo ledger fields

Releasing and reclaiming with sendShielded

Compiling the contract

Testing the escrow

What you've built

Next steps

Building a shielded token vault: deposit, accumulate, and withdraw

What you'll build

Prerequisites

Contract-held coins vs user-held coins

The vault contract

Ledger state

Initializing the vault with initVault

Accumulating deposits with depositShielded and mergeCoinImmediate

Tracking balances with commitments

Withdrawing with sendShielded

Compiling the contract

Testing the vault

What you've built

Next steps

# Understanding wallet sync: why your deploy fails before it starts

What balanceUnboundTransaction actually does

The three sub-wallets: shielded, unshielded, and dust

Shielded wallet

Unshielded wallet

Dust wallet

The dust wallet bug: isStrictlyComplete() on idle chains

The safe sync pattern

A complete working example

Showing sync progress in a frontend

Common mistakes to avoid

Summary

Next steps

Accepting deposits with `receiveShielded` and `writeCoin`

Accumulating funds with `mergeCoinImmediate`

Storing coins in `QualifiedShieldedCoinInfo` ledger fields

Releasing and reclaiming with `sendShielded`

Initializing the vault with `initVault`

Accumulating deposits with `depositShielded` and `mergeCoinImmediate`

Withdrawing with `sendShielded`

What `balanceUnboundTransaction` actually does

The dust wallet bug: `isStrictlyComplete()` on idle chains