DEV Community: Tosin Akinbowa

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.

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 the contract controls when it moves.

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.

# 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.