DEV Community: Syv

[Tutorial] Reading and Reacting to Contract State from a Frontend on Midnight network

Syv — Thu, 07 May 2026 21:02:50 +0000

📁 Full Source Code: midnight-apps/unshielded-token

Target audience: Developers

Prerequisites

Node.js installed (v20+)
A Midnight Wallet (e.g., 1AM or Lace)
Some Preprod faucet NIGHT tokens
An existing Midnight DApp with a deployed smart contract
The smart contract compiled so its JS bindings exist (e.g., /contracts/managed/<name>/contract/index.js)
INDEXER_HTTP and INDEXER_WS constants pointing to the Preprod indexer
A package.json with the needed packages:
- @midnight-ntwrk/midnight-js-indexer-public-data-provider
- @midnight-ntwrk/midnight-js-contracts
- @midnight-ntwrk/midnight-js-types
- @midnight-ntwrk/compact-runtime
- @midnight-ntwrk/dapp-connector-api
- @midnight-ntwrk/ledger-v8
- @midnight-ntwrk/midnight-js-fetch-zk-config-provider
- @midnight-ntwrk/midnight-js-http-client-proof-provider
- @midnight-ntwrk/midnight-js-level-private-state-provider
- @midnight-ntwrk/midnight-js-network-id
- react, react-dom, react-router-dom
- zustand

Summary

This guide shows how to query and visualize deployed smart contract state from a React frontend on the Midnight network. You will learn how to use indexerPublicDataProvider for GraphQL queries, how to deserialize ledger state into typed fields, and how to render everything in the frontend.

You have a reusable useContractState hook that keeps your frontend in sync with on-chain state, whether you prefer polling or push-based subscriptions over WebSocket. This works with any smart contract that you have previously deployed; the example presented below is an unshielded stablecoin vault, but the patterns apply to any Midnight DApp needing to display on-chain data.

Understanding the smart contract ledger

Before you query anything, you need to know what you are querying.

Property	What's inside	How you access it
`data`	The contract's ledger state as a `ChargedState` object, including typed fields declared with `export ledger` in Compact	`contractModule.ledger(contractState.data)`
`balance`	A `Map<TokenType, bigint>` of tokens held by the smart contract	`contractState.balance` directly

View the full ContractState reference in the Midnight documentation.

The ledger is defined in your .compact file. For the example smart contract used in this tutorial (unshielded token vault), the ledger looks like this:

pragma language_version 0.22;
import CompactStandardLibrary;

export ledger totalSupply: Uint<64>;
export ledger totalBurned: Uint<64>;
export ledger burnedBalance: Uint<64>;

When you compile the smart contract, it generates a JavaScript ledger() constructor that knows exactly how to read the ledger state through ledger() to access those three typed fields. The library responsible for the deserialization is @midnight-ntwrk/compact-runtime, and the results are plain bigint values.

const ledgerState = contractModule.ledger(contractState.data);

// ledgerState.totalSupply  → bigint
// ledgerState.totalBurned  → bigint
// ledgerState.burnedBalance → bigint

1. The indexer provider

@midnight-ntwrk/midnight-js-indexer-public-data-provider exports indexerPublicDataProvider. It wraps an Apollo Client around the indexer's GraphQL V4 endpoint. It implements PublicDataProvider interface and gives you typed methods for querying chain data.

import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';

const provider = indexerPublicDataProvider(
  'https://indexer.preprod.midnight.network/api/v4/graphql',
  'wss://indexer.preprod.midnight.network/api/v4/graphql/ws'
);

The provider contains three useful methods for querying smart contract state:

Method	Returns	Use when
`queryContractState(address)`	`ContractState`	You only need the smart contract's public ledger data
`queryZSwapAndContractState(address)`	`[ZswapChainState, ContractState, LedgerParameters]`	You also need the global shielded state or parameters
`queryUnshieldedBalances(address)`	`UnshieldedBalances`	You only need the smart contract's native token balances

All three — queryContractState(address), queryZSwapAndContractState(address), and queryUnshieldedBalances(address) — accept an optional second argument to query at a specific block height or hash. If omitted, the latest state is returned.

2. One-time smart contract state queries

Querying raw smart contract state

A simple entry point is queryContractState. It returns null immediately if the indexer has never seen the smart contract.

queryContractState works well if you need the smart contract's public ledger data.

export async function getContractBalance(): Promise<bigint> {
  try {
    const mods = await getModules();
    const { indexerModule } = mods;
    const indexerPublicDataProvider = indexerModule.indexerPublicDataProvider;
    const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);

    const contractState = await provider.queryContractState(CONTRACT_ADDRESS);
    console.log('[getContractBalance] Contract state balance:', contractState?.balance);

    if (!contractState?.balance) return 0n;

    for (const [key, value] of contractState.balance.entries()) {
      console.log('[getContractBalance] Key:', key, 'Value:', value.toString());
      if (key && typeof key === 'object' && 'raw' in key && key.raw === STABLECOIN_TOKEN) {
        console.log('[getContractBalance] Found balance:', value.toString());
        return value;
      }
    }

    return 0n;
  } catch (err) {
    console.error('[getContractBalance] Error:', err);
    return 0n;
  }
}

contractState.balance is a Map<TokenType, bigint> of token balances held by the smart contract. This is useful for a vault-type smart contract.

Querying combined ZSwap + smart contract state

If your smart contract interacts with shielded coins, call queryZSwapAndContractState to get the global ZswapChainState, the smart contract state, and the ledger parameters in one atomic query. This is more consistent between the two states because they come from the same block.

export async function getZSwapAndContractState(): Promise<{ firstFree: bigint; totalSupply: bigint; totalBurned: bigint; burnedBalance: bigint; dustParams: any } | null> {
  try {
    const mods = await getModules();
    const { indexerModule } = mods;
    const indexerPublicDataProvider = indexerModule.indexerPublicDataProvider;
    const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);

    const result = await provider.queryZSwapAndContractState(CONTRACT_ADDRESS);
    if (!result) {
      console.log('[ZSwapState] No zswap+contract state found');
      return null;
    }

    const [zswapState, contractState, ledgerParams] = result;
    console.log('[ZSwapState] zswapState.firstFree:', zswapState.firstFree.toString());

    const contractModule = await import(CONTRACT_PATH + '/contract/index.js');
    const ledgerState = contractModule.ledger(contractState.data);
    console.log('[ZSwapState] ledgerState.totalSupply:', ledgerState.totalSupply.toString());
    console.log('[ZSwapState] ledgerState.totalBurned:', ledgerState.totalBurned.toString());

    const burnedBalance = ledgerState.burnedBalance ?? 0n;
    console.log('[ZSwapState] ledgerState.burnedBalance:', burnedBalance.toString());

    console.log('[ZSwapState] ledgerParams.dust:', JSON.stringify(ledgerParams.dust, (_, v) => typeof v === 'bigint' ? v.toString() : v));

    return {
      firstFree: zswapState.firstFree,
      totalSupply: ledgerState.totalSupply,
      totalBurned: ledgerState.totalBurned,
      burnedBalance,
      dustParams: ledgerParams.dust,
    };
  } catch (err) {
    console.error('[ZSwapState] Error:', err);
    return null;
  }
}

3. Reading wallet balances

The @midnight-ntwrk/dapp-connector-api package exposes getUnshieldedBalances() on the ConnectedAPI, which returns the user-owned tokens.

export async function getUserStablecoinBalance(connectedApi: ConnectedAPI): Promise<bigint> {
  try {
    const balances = await connectedApi.getUnshieldedBalances();
    console.log('[getUserStablecoinBalance] Raw balances:', balances);
    const stablecoinBalance = balances[STABLECOIN_TOKEN];
    console.log('[getUserStablecoinBalance] STABLECOIN_TOKEN:', STABLECOIN_TOKEN, '=>', stablecoinBalance?.toString() ?? '0');
    return stablecoinBalance || 0n;
  } catch (err) {
    console.error('[getUserStablecoinBalance] Error:', err);
    return 0n;
  }
}

Your wallet holds many tokens. 0000... represents native tNIGHT. Looking up wallet balances is easier than querying the smart contract state because the wallet already tracks its own balances. You simply look up the key matching your token color.

Where do token colors come from?

Every token on Midnight has a unique color: a 32-byte hex string that identifies the token type on the ledger. You can see this color in the [getUserStablecoinBalance] Raw balances: log. The color is generated when the token is first minted, and it is not hardcoded in the smart contract source code.

If you do not know the color yet, inspect the vault's ContractState balance map after at least one mint transaction has occurred. Store the color in a constant, and reuse it for balance lookups:

export const STABLECOIN_TOKEN =
  '88aca75e4dfebf5991aee89918528338809dacb71d62c4b7ed8a713839e46bbb';

4. Deserializing ledger fields

The indexer returns raw bytes that are unreadable without deserialization. To turn them into typed fields like totalSupply, import the compiled smart contract module with the help of @midnight-ntwrk/compact-runtime and pass the raw data through its ledger() constructor.

const contractModule = await import(CONTRACT_PATH + '/contract/index.js');
const ledgerState = contractModule.ledger(contractState.data);

console.log('[ContractState] Ledger totalSupply:', ledgerState.totalSupply.toString());
console.log('[ContractState] Ledger totalBurned:', ledgerState.totalBurned.toString());

5. Displaying contract state in a UI

Now that you have all the data you need, all that remains is to render it in the frontend as totalSupply, totalBurned, contractBalance, and walletBalance.

The actual Home.tsx uses the useContractState hook and renders them inline:

import { useWalletStore } from '../hooks/useWallet';
import { ConnectButton } from '../components/ui/ConnectButton';
import { useContractState } from '../hooks/useContractState';

// .. other utilities

export function HomePage() {
  const { isConnected, connectedApi } = useWalletStore();
  const { state } = useContractState(connectedApi, { pollInterval: 15000 });

  const totalSupply = state?.totalSupply ?? 0n;
  const totalBurned = state?.totalBurned ?? 0n;
  const burnedBalance = state?.burnedBalance ?? 0n;
  const contractBalance = state?.contractBalance ?? 0n;
  const walletBalance = state?.walletBalance ?? 0n;

  return (
    <div className="w-full max-w-4xl mx-auto">
      {isConnected && (
        <div className="py-12 space-y-8">
          {/* Stats Row */}
          <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
            <div className="bg-bg-tertiary/40 border border-border/80 rounded-2xl p-4">
              <p className="text-[11px] uppercase tracking-widest text-text-muted/60 mb-1">Total Supply</p>
              <p className="text-xl font-semibold text-white">{totalSupply.toString()}</p>
            </div>
            <div className="bg-bg-tertiary/40 border border-border/80 rounded-2xl p-4">
              <p className="text-[11px] uppercase tracking-widest text-text-muted/60 mb-1">Total Burned</p>
              <p className="text-xl font-semibold text-white">{totalBurned.toString()}</p>
            </div>
            <div className="bg-bg-tertiary/40 border border-border/80 rounded-2xl p-4">
              <p className="text-[11px] uppercase tracking-widest text-text-muted/60 mb-1">Vault Balance</p>
              <p className="text-xl font-semibold text-white">{contractBalance.toString()}</p>
              {burnedBalance > 0n && (
                <p className="text-[10px] text-text-muted/40 mt-1">{burnedBalance.toString()} burned held</p>
              )}
            </div>
            <div className="bg-bg-tertiary/40 border border-border/80 rounded-2xl p-4">
              <p className="text-[11px] uppercase tracking-widest text-text-muted/60 mb-1">Wallet Balance</p>
              <p className="text-xl font-semibold text-white">{walletBalance.toString()}</p>
            </div>
          </div>
        </div>
      )}
    </div>
  );
}

The hook returns null while loading, so the frontend does not crash and uses ?? 0n as a fallback. The grid uses grid-cols-2 on mobile and grid-cols-4 on larger screens. The vault balance shows held burned tokens, so users know the raw balance includes burned tokens.

You can use this pattern with any other smart contract; all that changes are the ledger fields you deserialize and the token you look up by color in the balance map.

6. Real-time updates with WebSocket subscriptions

Using useEffect for polling technically works, but it is inefficient for dashboards that need to stay up to date. The Midnight indexer exposes GraphQL subscriptions over WebSocket. contractActions emits an event every time your smart contract is called / deployed.

indexerPublicDataProvider does not surface subscriptions directly, so open a raw WebSocket to the indexer and send a GraphQL start message to wss://indexer.preprod.midnight.network/api/v4/graphql/ws:

const INDEXER_WS = 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws';

      ws = new WebSocket(INDEXER_WS, 'graphql-ws');
      wsRef.current = ws;

      ws.onopen = () => {
        console.log('[useContractState] Socket: connected');
        reconnectDelay = 1000; // Reset backoff on successful connection
        ws!.send(JSON.stringify({ type: 'connection_init' }));
        ws!.send(JSON.stringify({
          id: 'contract-state-sub',
          type: 'start',
          payload: {
            query: `
              subscription ContractStateUpdates($address: HexEncoded!) {
                contractActions(address: $address) {
                  state
                  transaction { block { height } }
                }
              }
            `,
            variables: { address: CONTRACT_ADDRESS },
          },
        }));
      };

The WebSocket is used as a notification system. Whenever a message is received, fetchState() is called, which in turn triggers getContractState(), getContractBalance(), and getUserStablecoinBalance().

  const fetchState = useCallback(async () => {
    try {
      const [s, cb, wb] = await Promise.all([
        getContractState(),
        getContractBalance(),
        connectedApi ? getUserStablecoinBalance(connectedApi) : Promise.resolve(0n),
      ]);
      // Usable contract balance = raw balance minus tokens that were burned into the contract
      const usableContractBalance = cb > s.burnedBalance ? cb - s.burnedBalance : 0n;
      setState({
        totalSupply: s.totalSupply,
        totalBurned: s.totalBurned,
        burnedBalance: s.burnedBalance,
        contractBalance: usableContractBalance,
        walletBalance: wb,
      });
      setError(null);
    } catch (err: any) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }, [connectedApi]);

The `useContractState` hook

This project implements the full pattern in src/hooks/useContractState.ts. It combines polling with a WebSocket subscription, falling back to polling every 15 seconds if the WebSocket drops.

import { useState, useEffect, useRef, useCallback } from 'react';
import {
  CONTRACT_ADDRESS,
  INDEXER_WS,
} from './wallet/wallet.constants';
import {
  getContractState,
  getContractBalance,
  getUserStablecoinBalance,
} from './wallet/services/contractCalls';
import type { ConnectedAPI } from '@midnight-ntwrk/dapp-connector-api';

export interface ContractStateSnapshot {
  totalSupply: bigint;
  totalBurned: bigint;
  burnedBalance: bigint;
  contractBalance: bigint;
  walletBalance: bigint;
  blockHeight?: number;
}

export function useContractState(
  connectedApi: ConnectedAPI | null,
  opts: { pollInterval?: number } = {}
) {
  const { pollInterval = 15000 } = opts;
  const [state, setState] = useState<ContractStateSnapshot | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const wsRef = useRef<WebSocket | null>(null);
  const reconnectRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const lastBlockRef = useRef<number | undefined>(undefined);
  const intentionalCloseRef = useRef(new WeakSet<WebSocket>());

  const fetchState = useCallback(async () => {
    try {
      const [s, cb, wb] = await Promise.all([
        getContractState(),
        getContractBalance(),
        connectedApi ? getUserStablecoinBalance(connectedApi) : Promise.resolve(0n),
      ]);
      // Usable contract balance = raw balance minus tokens that were burned into the contract
      const usableContractBalance = cb > s.burnedBalance ? cb - s.burnedBalance : 0n;
      setState({
        totalSupply: s.totalSupply,
        totalBurned: s.totalBurned,
        burnedBalance: s.burnedBalance,
        contractBalance: usableContractBalance,
        walletBalance: wb,
      });
      setError(null);
    } catch (err: any) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }, [connectedApi]);

  // Initial fetch + polling fallback
  useEffect(() => {
    if (!connectedApi) {
      setLoading(false);
      return;
    }
    console.log('[useContractState] Polling: fetching state...');
    fetchState();
    const id = setInterval(() => {
      console.log('[useContractState] Polling: interval tick');
      fetchState();
    }, pollInterval);
    return () => clearInterval(id);
  }, [fetchState, pollInterval, connectedApi]);

  // WebSocket subscription for push updates
  useEffect(() => {
    if (!connectedApi) return;

    let ws: WebSocket | null = null;
    let reconnectDelay = 1000;
    const maxReconnectDelay = 30000;
    let debounceTimer: ReturnType<typeof setTimeout> | null = null;
    const DEBOUNCE_MS = 500;

    function connect() {
      ws = new WebSocket(INDEXER_WS, 'graphql-ws');
      wsRef.current = ws;

      ws.onopen = () => {
        console.log('[useContractState] Socket: connected');
        reconnectDelay = 1000; // Reset backoff on successful connection
        ws!.send(JSON.stringify({ type: 'connection_init' }));
        ws!.send(JSON.stringify({
          id: 'contract-state-sub',
          type: 'start',
          payload: {
            query: `
              subscription ContractStateUpdates($address: HexEncoded!) {
                contractActions(address: $address) {
                  state
                  transaction { block { height } }
                }
              }
            `,
            variables: { address: CONTRACT_ADDRESS },
          },
        }));
      };

      ws.onmessage = (event) => {
        try {
          const msg = JSON.parse(event.data);
          if (msg.type === 'data' && msg.payload?.data?.contractActions) {
            const action = msg.payload.data.contractActions;
            const blockHeight = action.transaction?.block?.height;
            if (blockHeight && blockHeight !== lastBlockRef.current) {
              lastBlockRef.current = blockHeight;
              // Debounce: the indexer sends a backlog of historical actions on connect.
              // Wait for the flood to stop before fetching, so 150 messages become 1 fetch.
              if (debounceTimer) clearTimeout(debounceTimer);
              debounceTimer = setTimeout(() => {
                console.log('[useContractState] Socket: debounced fetch for block', blockHeight);
                fetchState();
                debounceTimer = null;
              }, DEBOUNCE_MS);
            }
          }
          if (msg.type === 'ka') {
            // Keep-alive, ignore
          }
        } catch (e) {
          console.error('[useContractState] Failed to parse message:', e);
        }
      };

      ws.onerror = (err) => {
        // Suppress errors from intentional closes (React Strict Mode cleanup)
        if (ws && intentionalCloseRef.current.has(ws)) return;
        console.error('[useContractState] WebSocket error:', err);
      };

      ws.onclose = () => {
        if (ws && intentionalCloseRef.current.has(ws)) {
          console.log('[useContractState] Socket: closed intentionally');
          return;
        }
        console.log(`[useContractState] Socket: disconnected, reconnecting in ${reconnectDelay}ms...`);
        if (reconnectRef.current) clearTimeout(reconnectRef.current);
        reconnectRef.current = setTimeout(() => {
          reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
          connect();
        }, reconnectDelay);
      };
    }

    connect();

    return () => {
      if (reconnectRef.current) {
        clearTimeout(reconnectRef.current);
        reconnectRef.current = null;
      }
      if (debounceTimer) {
        clearTimeout(debounceTimer);
        debounceTimer = null;
      }
      if (ws) {
        intentionalCloseRef.current.add(ws);
        if (ws.readyState === WebSocket.OPEN) {
          try { ws.send(JSON.stringify({ id: 'contract-state-sub', type: 'stop' })); } catch {}
          ws.close();
        }
        // If the socket is still CONNECTING (common in React Strict Mode),
        // do not call close(). The browser will clean it up, and calling
        // close() on a CONNECTING socket produces a console warning.
      }
    };
  }, [connectedApi, fetchState]);

  return { state, loading, error, refetch: fetchState };
}

If you want to enable/disable polling fallback, simply comment or uncomment the polling part.

Note: graphql-ws expects a connection_init before start, so if you use subscriptions-transport-ws (older protocol), the handshake is slightly different. The Preprod indexer supports graphql-ws.

7. When to poll vs when to subscribe

Approach	Pros	Cons	Best for
Polling	Quick entry, works behind firewalls.	Higher latency, more resources used.	Low-traffic UIs (admin panel)
WebSocket subscription	Efficient for real-time updates.	Requires stable connection, harder to debug.	Apps requiring real-time updates

The hybrid approach used in useContractState is robust: it uses a background poll as a safety net in case the WebSocket is unresponsive, while keeping the WebSocket as the primary layer because of its lower latency.

Conclusion

You now have a complete pipeline for querying smart contract state from a React/TypeScript frontend on the Midnight network. The pattern is always the same: build an indexerPublicDataProvider, call the query method that works for your needs, deserialize the ledger state with your compiled smart contract's ledger() constructor, and render the fields in your UI.

This is not limited to stablecoin vaults. Any smart contract that exposes export ledger fields can be queried the same way. You only need to change the ledger fields you choose to deserialize, for example totalSupply or totalEmployees, and the token colors you look up in the balance map.

Next steps

Now that you've finished this tutorial, here are a few things you can do next:

Check the full repository source code
Deploy a hello-world contract and display ledger fields on a frontend
Read the Midnight Compact language docs
Understand ContractState from the Midnight documentation

Troubleshooting

"Wallet not detected" → Make sure 1AM or Lace browser extensions are installed
Transactions failing → Make sure you have tDUST and that the wallet is fully synced
0 Values → Make sure that the wallet is fully synced. Sometimes you need to open the wallet popup to force a sync (you could also manage this systematically)
Spurious WebSocket errors in development → React Strict Mode mounts components twice. Use a WeakSet to suppress errors from intentional socket closes
Invalid payload: requires tx (hex string) → makeTransfer already returns a balanced transaction. Do not pass it through balanceUnsealedTransaction
WebSocket connectivity issues → Make sure that your network is stable

[Tutorial] DApp Connector API: Connecting a Browser dApp to Midnight Wallets

Syv — Sun, 03 May 2026 21:00:56 +0000

This guide walks through the complete lifecycle of connecting web apps to the Midnight blockchain. You learn how to detect injected wallets in the browser, make a connection, monitor state changes, and submit transactions through both the browser extension flow and the CLI. You also learn the difference between them.

Target audience: Developers

Prerequisites

Node.js installed (v20+)
A Midnight wallet (for example, 1AM or Lace)
Some Preprod faucet NIGHT tokens
A package.json with the needed packages:
- @midnight-ntwrk/dapp-connector-api
- @midnight-ntwrk/ledger-v8
- @midnight-ntwrk/midnight-js-utils
- @midnight-ntwrk/midnight-js-fetch-zk-config-provider
- @midnight-ntwrk/midnight-js-network-id
- @midnight-ntwrk/wallet-sdk-address-format
- @midnight-ntwrk/wallet-sdk-facade
- @midnight-ntwrk/wallet-sdk-shielded
- @midnight-ntwrk/wallet-sdk-unshielded-wallet
- @midnight-ntwrk/wallet-sdk-dust-wallet
- @midnight-ntwrk/wallet-sdk-hd
- @scure/bip39
- react, react-dom, react-router-dom
- zustand, rxjs, semver, ws
- typescript, vite

Architecture: browser vs CLI

Midnight DApps operate in two different security contexts. Understanding the boundary between them is essential before writing any code.

Context	Custodian	Balancing method	Signature	Use case
Browser / DApp	Injected extension	`balanceUnsealedTransaction`	Wallet handles it	UI / DApps
CLI / backend	Your script	`transferTransaction` + `signRecipe`	Manual	Agents, automation

In the browser flow, the wallet extension handles the user's private key (typically encrypted on the user's device with a password). All keys are derived internally, and the DApp never sees secret material. The DApp builds a transaction blueprint, serializes it, and hands it to the wallet through the DApp Connector API. The wallet selects inputs, adds balancing outputs through balanceUnsealedTransaction, creates the signatures, and returns a finalized transaction.

In the CLI / backend flow, your script holds the 24-word mnemonic directly. It derives ZswapSecretKeys, DustSecretKey, and an UnshieldedKeystore from the mnemonic. Because there is no wallet extension to handle balancing and signing, the script uses transferTransaction to build a recipe, then signRecipe with the unshielded keystore, then finalizeRecipe and submitTransaction. The script acts as the wallet.

Both flows submit the same transaction format to the Midnight network. The only difference is who holds the keys and who performs the balancing.

Detecting wallets via `window.midnight`

Midnight wallets inject a global window.midnight object before page load.

Note: COMPATIBLE_CONNECTOR_API_VERSION is '4.x', not '^4.0.0'. The '4.x' semver range accepts any 4.x.y version the wallet reports.

View the full wallet.constants.ts and useWallet.ts files on GitHub.

// src/hooks/wallet.constants.ts
export const COMPATIBLE_CONNECTOR_API_VERSION = '4.x';
export const NETWORK_ID = 'preprod';

The detection function enumerates window.midnight, validates each entry, and filters by version.

// src/hooks/useWallet.ts
export function getCompatibleWallets(): InitialAPI[] {
  if (!window.midnight) return [];

  return Object.values(window.midnight).filter(
    (wallet): wallet is InitialAPI =>
      !!wallet &&
      typeof wallet === 'object' &&
      'apiVersion' in wallet &&
      semver.satisfies(wallet.apiVersion, COMPATIBLE_CONNECTOR_API_VERSION)
  );
}

Wallet selection modal

When one or more wallets are installed, a modal is shown so the user can pick.

View the full WalletSelectModal.tsx file on GitHub.

// src/components/WalletSelectModal.tsx
function getWalletIcon(rdns: string | undefined): string | null {
  if (!rdns) return null;
  if (rdns.includes('lace')) return laceSvg;
  if (rdns.includes('1am') || rdns.includes('iam')) return iamSvg;
  return null;
}

export function WalletSelectModal({ isOpen, onClose, wallets, onSelect, connecting }: Props) {
  const [pending, setPending] = useState<InitialAPI | null>(null);
  if (!isOpen) return null;

  return (
    <div>
      <h3>Connect Wallet</h3>
      {wallets.map((w) => (
        <button
          key={w.rdns}
          onClick={() => {
            setPending(w);
            onSelect(w);
          }}
          disabled={connecting}
        >
          <img src={getWalletIcon(w.rdns) ?? fallback} />
          <span>{w.name}</span>
        </button>
      ))}
      {connecting && pending && <div>Connecting to {pending.name}...</div>}
      <Button onClick={onClose} disabled={connecting}>Cancel</Button>
    </div>
  );
}

Installed wallets are discovered using InitialAPI[]. Each object is injected by a browser-installed wallet extension.

Connecting to Lace or 1AM

ConnectButton ties detection, selection, and connection together. If a single wallet is detected, it directly prompts for wallet connection approval. If multiple wallets are detected, a modal is shown.

View the full ConnectButton.tsx file on GitHub.

// src/components/ConnectButton.tsx
export function ConnectButton() {
  const { isConnected, connect, setWallet, setShowAccountModal } = useWalletStore();
  const [wallets] = useState(() => getCompatibleWallets());
  const [showModal, setShowModal] = useState(false);

  const handleConnect = async (selectedWallet: InitialAPI) => {
    setWallet(selectedWallet);
    setShowModal(false);
    await connect('preprod');
  };

  const handleClick = () => {
    if (isConnected) {
      setShowAccountModal(true);
    } else if (wallets.length === 1) {
      handleConnect(wallets[0]);
    } else {
      setShowModal(true);
    }
  };

  return (
    <>
      <Button onClick={handleClick}>Connect Wallet</Button>
      <Modal isOpen={showModal} onClose={() => setShowModal(false)}>
        <WalletSelectModal
          isOpen={showModal}
          onClose={() => setShowModal(false)}
          wallets={wallets}
          onSelect={handleConnect}
          connecting={isConnecting}
        />
      </Modal>
    </>
  );
}

The connection flow

When wallet.connect(networkId) is called, it triggers the wallet extension connection flow.

View the full useWallet.ts file on GitHub.

// src/hooks/useWallet.ts
connect: async (networkId = NETWORK_ID) => {
  const { wallet } = get();
  if (!wallet) {
    set({ error: 'No wallet selected' });
    return;
  }

  set({ isConnecting: true, error: null });

  try {
    const connectedApi = await wallet.connect(networkId);
    const status = await connectedApi.getConnectionStatus();

    if (status.status !== 'connected') {
      throw new Error(`Wallet status: ${status.status}`);
    }

    const config = await connectedApi.getConfiguration();
    const shielded = await connectedApi.getShieldedAddresses();
    const unshielded = await connectedApi.getUnshieldedAddress();
    const dustAddr = await connectedApi.getDustAddress();

    set({
      connectedApi,
      isConnected: true,
      config,
      addresses: {
        shieldedAddress: shielded.shieldedAddress,
        shieldedCoinPublicKey: shielded.shieldedCoinPublicKey,
        shieldedEncryptionPublicKey: shielded.shieldedEncryptionPublicKey,
        unshieldedAddress: unshielded.unshieldedAddress,
        dustAddress: dustAddr.dustAddress,
      },
      balances: {
        shielded: {},
        unshielded: {},
        dust: { balance: 0n, cap: 0n },
      },
    });

    localStorage.setItem('midnight_last_wallet', wallet.rdns);
  } catch (err) {
    set({
      error: err instanceof Error ? err.message : 'Connection failed',
      isConnected: false,
      connectedApi: null,
    });
  } finally {
    set({ isConnecting: false });
  }
},

Note: connect() fetches addresses, not balances. The dustAddress is fetched here, but balances are loaded separately in loadWalletState().

Auto-reconnect

Store the last connected wallet's rdns in localStorage and attempt to reconnect on page reload.

// src/hooks/useWallet.ts
export async function tryAutoConnect(): Promise<void> {
  const lastRdns = localStorage.getItem('midnight_last_wallet');
  if (!lastRdns || !window.midnight) return;

  const wallets = getCompatibleWallets();
  const match = wallets.find((w) => w.rdns === lastRdns);
  if (!match) return;

  const store = useWalletStore.getState();
  store.setWallet(match);
  await store.connect();
}

Account modal

Clicking the connected button opens a popup showing balances, addresses, copy buttons, refresh, and disconnect.

View the full AccountModal.tsx file on GitHub.

// src/components/AccountModal.tsx
export function AccountModal() {
  const {
    showAccountModal, setShowAccountModal,
    addresses, balances, config,
    isLoadingState, loadWalletState,
    disconnect, wallet, error,
  } = useWalletStore();

  const [copiedKey, setCopiedKey] = useState<string | null>(null);

  const handleCopy = (key: string, address: string | undefined) => {
    if (!address) return;
    navigator.clipboard.writeText(address);
    setCopiedKey(key);
    setTimeout(() => setCopiedKey(null), 2000);
  };

  // Renders shielded/unshielded/dust balances,
  // copyable addresses, refresh button, disconnect
}

Subscribing to wallet state changes

The DApp Connector v4 API does not expose a native push/subscription API. Reactive updates are built on top of polling.

View the full useWalletSubscription.ts file on GitHub.

// src/hooks/useWalletSubscription.ts
export function useWalletSubscription(options = {}) {
  const { balanceInterval = 15000, connectionInterval = 5000 } = options;
  const { connectedApi, isConnected, loadWalletState, disconnect } = useWalletStore();
  const lastStatusRef = useRef<'connected' | 'disconnected'>('disconnected');

  // 1. Balance polling
  useEffect(() => {
    if (!isConnected || !connectedApi) return;
    loadWalletState();
    const id = setInterval(() => loadWalletState(), balanceInterval);
    return () => clearInterval(id);
  }, [isConnected, connectedApi, loadWalletState, balanceInterval]);

  // 2. Connection-status polling
  useEffect(() => {
    if (!isConnected || !connectedApi) return;

    const check = async () => {
      try {
        const status = await connectedApi.getConnectionStatus();
        lastStatusRef.current = status.status;
        if (status.status === 'disconnected') disconnect();
      } catch {
        if (lastStatusRef.current === 'connected') disconnect();
      }
    };

    const id = setInterval(check, connectionInterval);
    return () => clearInterval(id);
  }, [isConnected, connectedApi, disconnect, connectionInterval]);
}

loadWalletState fetches all balance types at the same time.

// src/hooks/useWallet.ts
loadWalletState: async () => {
  const { connectedApi } = get();
  if (!connectedApi) return;

  set({ isLoadingState: true, error: null });

  try {
    const [shieldedBalances, unshieldedBalances, dustBalance] = await Promise.all([
      connectedApi.getShieldedBalances(),
      connectedApi.getUnshieldedBalances(),
      connectedApi.getDustBalance(),
    ]);

    set({
      balances: {
        shielded: shieldedBalances,
        unshielded: unshieldedBalances,
        dust: dustBalance,
      },
    });
  } catch (err) {
    set({ error: err instanceof Error ? err.message : 'Failed to load wallet state' });
  } finally {
    set({ isLoadingState: false });
  }
},

CLI: native push subscriptions

Using the Wallet SDK, you get true push-based state through RxJS.

Build a small helper function. View the full transaction-cli.ts file on GitHub.

// src/lib/transaction-cli.ts
import * as Rx from 'rxjs';

export function subscribeToWalletSdkState(
  ctx: CliWalletContext,
  listener: (state: any) => void
): () => void {
  const sub = (ctx.wallet as any).state().subscribe(listener);
  return () => sub.unsubscribe();
}

export async function waitForWalletSync(ctx: CliWalletContext): Promise<any> {
  return Rx.firstValueFrom(
    (ctx.wallet as any)
      .state()
      .pipe(Rx.filter((s: any) => s.isSynced))
  );
}

Build the flow. View test-subscription.ts for the complete script.

// scripts/test-subscription.ts
const ctx = await restoreWalletState(MNEMONIC);

// 1. Block until fully synced
await waitForWalletSync(ctx);

// 2. Subscribe to push updates
const unsubscribe = subscribeToWalletSdkState(ctx, (state: any) => {
  if (!state.isSynced) return;

  const shielded = state.shielded?.balances ?? {};
  const unshielded = state.unshielded?.balances ?? {};
  const dust = state.dust?.balance(new Date()) ?? 0n;

  console.log('Shielded:', Object.entries(shielded)
    .map(([k, v]) => `${k.slice(0, 8)}..=${v?.toString()}`).join(', ') || '(empty)');
  console.log('Unshielded:', Object.entries(unshielded)
    .map(([k, v]) => `${k.slice(0, 8)}..=${v?.toString()}`).join(', ') || '(empty)');
  console.log('Dust:', dust.toString());
});

The browser transaction flow (`balanceUnsealedTransaction`)

Once connected, the browser DApp requests the wallet to balance and submit the transaction. The app uses manual construction: building an Intent with an UnshieldedOffer, proving it, then calling balanceUnsealedTransaction.

The DApp Connector API also exposes makeTransfer, a convenience method for simple transfers. This app does not use it because the manual path gives full control over the transaction blueprint and works for both pure transfers and contract calls.

Here is the full lifecycle of the transfer page. View the full Transfer.tsx file on GitHub.

// src/pages/Transfer.tsx
const handleTransfer = useCallback(async () => {
  if (!connectedApi) {
    setError('Wallet not connected');
    return;
  }

  try {
    const value = BigInt(Math.round(Number(amount) * 1_000_000));

    // 1. Decode Bech32 address to raw hex bytes
    const parsed = MidnightBech32m.parse(recipient);
    const unshieldedAddr = parsed.decode(UnshieldedAddress, 'preprod');
    const hexRecipient = unshieldedAddr.data.toString('hex');

    // 2. Build an unproven transaction blueprint manually
    const unshieldedOffer = UnshieldedOffer.new(
      [], // inputs — wallet selects these
      [{ value, owner: hexRecipient, type: nativeToken().raw }],
      [] // signatures — wallet adds these
    );

    const intent = Intent.new(new Date(Date.now() + 30 * 60 * 1000));
    (intent as any).fallibleUnshieldedOffer = unshieldedOffer;

    const unsealedTx = Transaction.fromParts('preprod', undefined, undefined, intent as any);

    // 3. Prove the transaction (PreProof → Proof)
    const zkConfigProvider = new FetchZkConfigProvider(window.location.origin);
    const provingProvider = await connectedApi.getProvingProvider(zkConfigProvider);
    const provenTx = await unsealedTx.prove(provingProvider, CostModel.initialCostModel());

    const serializedTx = toHex(provenTx.serialize());

    // 4. Wallet balances, signs, and pays fees
    const result = await connectedApi.balanceUnsealedTransaction(serializedTx, { payFees: true });

    // 5. Submit
    await connectedApi.submitTransaction(result.tx);

    setTxId(result.tx.slice(0, 64));
    loadWalletState();
  } catch (err) {
    setError(err instanceof Error ? err.message : String(err));
  }
}, [connectedApi, recipient, amount, loadWalletState]);

Why each step matters

Bech32 → hex: The DApp Connector returns addresses in Bech32 (mn_addr_preprod1...), but UnshieldedOffer.new expects raw hex bytes for the owner field.

The correct flow is:

const parsed = MidnightBech32m.parse(recipient);
const unshieldedAddr = parsed.decode(UnshieldedAddress, 'preprod');
const hexRecipient = unshieldedAddr.data.toString('hex');

Network ID: Transaction.fromParts must use 'preprod' (matching the wallet connection). Using 'undeployed' causes:

BALANCE_FAILED: invalid network ID - expect 'preprod' found 'undeployed'

tx.prove(): balanceUnsealedTransaction expects a transaction with the Proof marker. Without prove(), the transaction serializes with proof-preimage (PreProof state) and the wallet rejects it with:

expected header tag '...proof...', got '...proof-preimage...'

Security model: In the browser flow, the DApp never sees secret keys. The wallet extension derives all keys locally and signs intents internally. The DApp only handles public addresses and serialized transaction bytes.

The CLI transaction flow

The CLI performs transactions without a browser wallet, which is essential for agents and other systems to act autonomously.

Key derivation

Derive secret keys directly from a 24-word BIP-39 mnemonic. Call hdWallet.hdWallet.clear() after derivation to clear the seed from memory.

View the full transaction-cli.ts file on GitHub.

// src/lib/transaction-cli.ts
const seed = Buffer.from(await bip39.mnemonicToSeed(mnemonic));
const hdWallet = HDWallet.fromSeed(seed);

const derivationResult = hdWallet.hdWallet
  .selectAccount(0)
  .selectRoles([Roles.Zswap, Roles.NightExternal, Roles.Dust])
  .deriveKeysAt(0);

hdWallet.hdWallet.clear(); // Security: wipe seed from memory

const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(derivationResult.keys[Roles.Zswap]);
const dustSecretKey = ledger.DustSecretKey.fromSeed(derivationResult.keys[Roles.Dust]);
const unshieldedKeystore = createKeystore(derivationResult.keys[Roles.NightExternal], 'preprod');

Wallet initialization

Initialize a headless WalletFacade with three sub-wallets. Wallet SDK v3 requires several config fields that were optional in previous versions.

// src/lib/transaction-cli.ts
const baseConfig: any = {
  networkId: 'preprod',
  indexerClientConnection: {
    indexerHttpUrl: 'https://indexer.preprod.midnight.network/api/v4/graphql',
    indexerWsUrl: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
  },
  relayURL: new URL('wss://rpc.preprod.midnight.network'),
  provingServerUrl: new URL('http://localhost:6300'),
  costParameters: { additionalFeeOverhead: 300_000_000_000_000n, feeBlocksMargin: 5 },
  txHistoryStorage: new InMemoryTransactionHistoryStorage(),
  batchUpdates: { size: 500, timeout: 50, spacing: 0 },
};

const wallet: any = await (WalletFacade as any).init({
  configuration: baseConfig,
  shielded: (cfg: any) => ShieldedWallet(cfg).startWithSecretKeys(shieldedSecretKeys),
  unshielded: (cfg: any) =>
    UnshieldedWallet({ ...cfg, txHistoryStorage: new InMemoryTransactionHistoryStorage() })
      .startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
  dust: (cfg: any) =>
    DustWallet(cfg).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
});

await wallet.start(shieldedSecretKeys, dustSecretKey);

Required v3 fields:

provingServerUrl: The local proof server URL
costParameters: Fee overhead and block margin
txHistoryStorage: Unshielded transaction history storage
batchUpdates: Tuning for dust sync performance ({ size: 500, timeout: 50, spacing: 0 })
PublicKey.fromKeyStore(): Wraps the unshielded keystore for the wallet
LedgerParameters.initialParameters().dust: Dust ledger parameters

CLI transfer: `transferTransaction` + `signRecipe`

For CLI transfers, use transferTransaction followed by signRecipe:

View the full test-v3-sync-and-transfer.ts file on GitHub.

// scripts/test-v3-sync-and-transfer.ts
import { unshieldedToken } from '@midnight-ntwrk/ledger-v8';

const recipe = await ctx.wallet.transferTransaction(
  [
    {
      type: 'unshielded',
      outputs: [
        {
          amount: 1n,
          receiverAddress: ctx.unshieldedKeystore.getBech32Address(),
          type: unshieldedToken().raw,
        },
      ],
    },
  ],
  { shieldedSecretKeys: ctx.shieldedSecretKeys, dustSecretKey: ctx.dustSecretKey },
  { ttl: new Date(Date.now() + 30 * 60 * 1000) }
);

const signedRecipe = await ctx.wallet.signRecipe(
  recipe,
  (payload: Uint8Array) => ctx.unshieldedKeystore.signData(payload)
);

const finalized = await ctx.wallet.finalizeRecipe(signedRecipe);
const txId = await ctx.wallet.submitTransaction(finalized);

Note: The CLI uses unshieldedToken().raw for the token type in transferTransaction.

Dust sync handling

First-time dust syncing can take some time (approximately 70 minutes in testing). A 2-hour timeout is used.

// scripts/test-v3-sync-and-transfer.ts
const syncedState = await Rx.firstValueFrom(
  ctx.wallet.state().pipe(
    Rx.throttleTime(5_000),
    Rx.tap((s: any) => {
      // ...log progress...
    }),
    Rx.filter((s: any) => s.isSynced === true),
    Rx.timeout(120 * 60 * 1000), // 2 hours for first-time dust sync
  )
);

Most importantly, save state on SIGINT/SIGTERM so progress is not lost if the user interrupts.

const saveBeforeExit = async () => {
  console.log('\n[Test] Interrupted — saving partial state...');
  await saveWalletState(ctx, '.wallet-state');
  await ctx.wallet.stop();
  process.exit(0);
};
process.on('SIGINT', saveBeforeExit);
process.on('SIGTERM', saveBeforeExit);

Run the CLI transfer script

MNEMONIC="word1 word2 ... word24" npx tsx scripts/test-v3-sync-and-transfer.ts

Note: Sometimes the transfer fails. This is often caused by network issues.

Conclusion

dapp-connect is a reference implementation for connecting to the Midnight blockchain from both the browser and the CLI. It demonstrates the complete wallet lifecycle, from detection to connection, state monitoring, and transaction construction, proving, balancing, signing, and submitting, across two different security contexts.

Next steps

Clone the project at https://github.com/0xfdbu/midnight-apps/tree/main/dapp-connect
Deploy a compact smart contract and integrate it into the DApp
Build an AI agent around the CLI

Troubleshooting

Browser errors

Error	Cause	Fix
`Invalid character 'm' at position 0`	Bech32 address passed to `UnshieldedOffer.new`	Decode with `MidnightBech32m.parse(addr).decode(UnshieldedAddress, 'preprod').data.toString('hex')`
`expected header tag '...proof...', got '...proof-preimage...'`	Missing `tx.prove()` before `balanceUnsealedTransaction`	Call `await tx.prove(provingProvider, CostModel.initialCostModel())`
`BALANCE_FAILED: invalid network ID`	Wrong network in `Transaction.fromParts`	Use `'preprod'`, not `'undeployed'`
`No compatible wallet found`	Extension reports API version outside `'4.x'`	Update the wallet extension

CLI errors

Error	Cause	Fix
`Missing required configuration: 'provingServerUrl'`	`WalletFacade.init` missing proof server URL	Add `provingServerUrl: new URL('http://localhost:6300')` to config
`Custom error: 192`	Missing `signRecipe` step before `finalizeRecipe`	Add `await wallet.signRecipe(recipe, signFn)` before `finalizeRecipe`
`Custom error: 170`	Wallet not fully synced	Wait for `isSynced = true` before submitting
Dust sync timeout	First-time sync from genesis is slow	Use `restoreWalletState()`; save on SIGINT; allow 2h timeout

Built with @midnight-ntwrk/midnight-js 4.0.4 and Wallet SDK 3.0.0 for the Midnight Preprod network.

[Tutorial] Building a full-stack Midnight DApp: zero-knowledge attestation protocol

Syv — Thu, 23 Apr 2026 16:31:30 +0000

📁 Full source code and installation steps: midnight-apps/fullstack-dapp

Target audience: Developers

Within the next few sections, you go through smart contract compilation and focus on the DApp lifecycle.

Prerequisites

Node.js installed (v20+)
A Midnight Wallet (e.g., 1AM or Lace)
Some Preprod faucet NIGHT tokens
A package.json with the needed packages
- @midnight-ntwrk/compact-runtime
- @midnight-ntwrk/dapp-connector-api
- @midnight-ntwrk/ledger-v8
- @midnight-ntwrk/midnight-js-contracts
- @midnight-ntwrk/midnight-js-dapp-connector-proof-provider
- @midnight-ntwrk/midnight-js-fetch-zk-config-provider
- @midnight-ntwrk/midnight-js-http-client-proof-provider
- @midnight-ntwrk/midnight-js-indexer-public-data-provider
- @midnight-ntwrk/midnight-js-level-private-state-provider
- @midnight-ntwrk/midnight-js-network-id
- @midnight-ntwrk/midnight-js-node-zk-config-provider
- @midnight-ntwrk/midnight-js-types
- @midnight-ntwrk/wallet-sdk-address-format
- @midnight-ntwrk/wallet-sdk-dust-wallet
- @midnight-ntwrk/wallet-sdk-facade
- @midnight-ntwrk/wallet-sdk-hd
- @midnight-ntwrk/wallet-sdk-shielded
- @midnight-ntwrk/wallet-sdk-unshielded-wallet
- @scure/bip39, cors, express, postgres, react, react-dom, react-router-dom, rxjs, semver, vite-plugin-node-polyfills, vite-plugin-top-level-await, vite-plugin-wasm, ws, zustand

1. Building the smart contract

For this attestation you need two core witnesses. localSecretKey() will be used to fetch the user's secret key, and findAgePath(commit: Bytes<32>) fetches the required cryptographic Merkle path from the local private state and passes it to the circuit(s) as needed.

witness localSecretKey(): Bytes<32>;
witness findAgePath(commit: Bytes<32>): MerkleTreePath<10, Bytes<32>>;

You also need some essential ledgers:

authority stores the public key of the admin (only the authority can issue attestations)

  export sealed ledger authority: Bytes<32>;

ageCommitments uses HistoricMerkleTree. Think of it as a secure cryptographic folder. Use it instead of a list for privacy. Later, the user can mathematically prove their commitment is inside this tree without the blockchain knowing which leaf belongs to them.

  export ledger ageCommitments: HistoricMerkleTree<10, Bytes<32>>;

usedNullifiers: whenever a user proves their age, a circuit generates a unique nullifier hash from their secret key, so if they try to prove a second time, the circuit sees their nullifier is already present.

  export ledger usedNullifiers: Set<Bytes<32>>;

totalAgeProofs is a simple ledger. It is incremented later in the proveAge() circuit

  export ledger totalAgeProofs: Counter;

You also need a simple constructor to initialize the smart contract. Constructor arguments are witness data — in this case, authoritySk.

constructor(authoritySk: Bytes<32>) {
    // authoritySk is a constructor argument (witness data) — disclose required
    authority = disclose(publicKey(authoritySk));
}

The first circuit is attestAge(). It fetches the secret key via the localSecretKey() witness and then checks whether the entity attempting to run attestAge() is an authority.

export circuit attestAge(userCommit: Bytes<32>): [] {
    const sk = localSecretKey();
    assert(authority == disclose(publicKey(sk)), "Not the authority");
    ageCommitments.insert(disclose(userCommit));
}

But as you can see, attestAge() requires a userCommit. The user can forward a commitment to the authority, so userCommit is an authority input to grant the user an attestation that they can use to prove their age.

Create a private helper circuit commitment() to compute a deterministic hash with the user's secret key and a domain separator.

circuit commitment(sk: Bytes<32>, domain: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>(
        [pad(32, "mydapp:commit:v1"), domain, sk]
    );
}

You can then use it in a getCommitment() circuit. Because it is an export, the frontend can execute this off-chain to generate the commitment.

export circuit getCommitment(sk: Bytes<32>, domain: Bytes<32>): Bytes<32> {
    return commitment(sk, domain);
}

The proveAge() circuit fetches localSecretKey() via witness and defines domain as age for this circuit. Compute a commitment using both values, then call the findAgePath(commit) witness to check whether an active attestation by an authority exists in the Merkle Tree. If there is, return whether the user has a valid attestation.

You then generate a nullifier. To understand why you need it, look at the privacy guarantees of the smart contract. If a user proves they are over 18 once, the blockchain only sees TRUE; it does not know who proved it, so without a nullifier, a malicious user can spam the protocol with hundreds of generated on-chain proofs.

circuit nullifier(sk: Bytes<32>, domain: Bytes<32>): Bytes<32> {
    return persistentHash<Vector<3, Bytes<32>>>(
        [pad(32, "mydapp:nullify:v1"), domain, sk]
    );
}

The full proveAge() demonstrates how the nullifier is implemented to address the issue.

export circuit proveAge(): Boolean {
    const sk = localSecretKey();
    const domain = pad(32, "age");
    const commit = commitment(sk, domain);
    const path = findAgePath(commit);

    assert(
        ageCommitments.checkRoot(disclose(merkleTreePathRoot<10, Bytes<32>>(path))),
        "Age not attested"
    );

    const nul = nullifier(sk, domain);
    assert(!usedNullifiers.member(disclose(nul)), "Age proof already used");
    usedNullifiers.insert(disclose(nul));
    totalAgeProofs.increment(1);

    return disclose(true);
}

Note: The example uses domain because the smart contract is set to handle multiple types of attestations (age, residency, certifications). Refer to the GitHub repo for more information.

You now need to compile this smart contract, but first install compact dev tools

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

Then run compact compile contracts/Contract.compact src/contracts. In this case, you can assume src/contracts is a directory your frontend and API will use to load the compiled smart contract (ZKIR, keys, etc.).

2. Wallet, identity & providers

You begin by setting up a wallet connection. For this you need DApp connector API v4 installed

import type { InitialAPI } from '@midnight-ntwrk/dapp-connector-api';

You can discover installed wallets using InitialAPI[]. Each object is injected by the browser-installed wallet extensions. In this case, there are 3 wallets installed (1AM, Lace, GSD).

interface WalletSelectModalProps {
  isOpen: boolean;
  onClose: () => void;
  wallets: InitialAPI[];
  onSelect: (wallet: InitialAPI) => void;
  connecting: boolean;
}

View the full WalletSelectModal.tsx on GitHub.

            {wallets.map((wallet) => {
              const iconUrl = getWalletIcon(wallet.rdns);
                // rest of the code
            })}

Create a Zustand hook in useWallet.ts to manage the wallet lifecycle. It is a Zustand store that manages the entire wallet lifecycle, and it scans for installed wallets.

// 1. Find injected wallets
export function getCompatibleWallets(): InitialAPI[] {
  if (!window.midnight) return [];
  return Object.values(window.midnight).filter(
    (wallet): wallet is InitialAPI =>
      !!wallet &&
      typeof wallet === 'object' &&
      'apiVersion' in wallet &&
      semver.satisfies(wallet.apiVersion, COMPATIBLE_CONNECTOR_API_VERSION)
  );
}

Then create a wallet connection by calling:

      const connectedApi = await wallet.connect(networkId);
      const status = await connectedApi.getConnectionStatus();

Note: You reuse useWallet.ts across all the frontend pages (Deploy, Attest, Prove)

Derive your identity deterministically from two inputs: userPassword and shieldedAddresses.shieldedCoinPublicKey. Hash them with domain-specific salts (User/Authority) to generate attest_sk (prove identity) for users and authoritySk (deploy/attest identity) for authorities.

This derivation is used everywhere, including Deploy to create the authority key, Attest to sign attestations, and Prove to generate ZK proofs. Same wallet + same password always produces the same key, so you do not lose your identity even if you clear browser storage. However, you would lose it if you forget your password.

This goes through a lock screen / session model, as shown below

const masterKey = await deriveKeyFromPassword(userPassword, shieldedAddresses.shieldedCoinPublicKey);

The most crucial step of this project is making sure the witnesses are correctly set up. You need a witnesses.ts file for this.

Point index.js to the path where you compiled the smart contract previously

import type { WitnessContext } from '@midnight-ntwrk/compact-runtime';
import type { Ledger } from '../contracts/managed/attest/contract/index.js';

You need to define AttestPrivateState. This defines the shape of the smart contract's private state. You only need the secretKey, and createAttestPrivateState is a helper that constructs an object.

export type AttestPrivateState = {
  readonly secretKey: Uint8Array;
};

export const createAttestPrivateState = (
  secretKey: Uint8Array,
): AttestPrivateState => ({
  secretKey,
});

Then you have two witnesses set up. localSecretKey() will be used to fetch the user's secret key, and findAgePath(commit: Bytes<32>) fetches the required cryptographic Merkle path from the local private state and passes it to the circuit(s) as needed.

export const witnesses = {
  localSecretKey: ({
    privateState,
  }: WitnessContext<Ledger, AttestPrivateState>): [AttestPrivateState, Uint8Array] => [
    privateState,
    privateState.secretKey,
  ],

  findAgePath: (
    { privateState, ledger }: WitnessContext<Ledger, AttestPrivateState>,
    commit: Uint8Array,
  ) => {
    const path = ledger.ageCommitments.findPathForLeaf(commit);
    if (!path) throw new Error('Age commitment not found in tree');
    return [privateState, path];
  },
};

You can now proceed to set up the providers, as shown below:

privateStateProvider: uses levelPrivateStateProvider for persistent localStorage (IndexedDB)
publicDataProvider: reads on-chain state from the indexer
zkConfigProvider: loads FetchZkConfigProvider — compiled verifiers, keys...
proofProvider: generates zero-knowledge proofs on your proof server
walletProvider: handles balanceTx via connectedApi.balanceUnsealedTransaction
midnightProvider: submits transactions via connectedApi.submitTransaction

      const providers = {
        privateStateProvider: privateState,
        publicDataProvider: indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS),
        zkConfigProvider: zkConfig,
        proofProvider,
        walletProvider,
        midnightProvider,
      };

3. Deploy the smart contract

You can now proceed to create Deploy.tsx

Begin by setting the network — in this case, it's preprod

import { setNetworkId } from '@midnight-ntwrk/midnight-js-network-id';

setNetworkId('preprod');

Run a proof server locally.

# Run on docker
sudo docker run -p 6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v

Then build the smart contract using CompiledContract API from @midnight-ntwrk/compact-js

      const cc = CompiledContract.make('attest', contractModule.Contract);
      const ccWithWitnesses = CompiledContract.withWitnesses(cc, witnesses as any);
      const compiledContract = CompiledContract.withCompiledFileAssets(ccWithWitnesses, ZK_ARTIFACTS_PATH);

Then the next step is to deploy, passing authoritySk as an argument. This makes the admin deploying the smart contract an authority with the ability to create attestations.

      const deployed = await deployContract(providers as any, {
        compiledContract,
        privateStateId: 'attestState',
        initialPrivateState,
        args: [authoritySk],
      } as any);

You then retrieve the deployed address using

const address = deployed.deployTxData.public.contractAddress;

4. Generate a commitment

A commitment is a tunnel between your private identity and the public ledger. It is a deterministic hash computed from the secret key (derived from userPassword + shieldedAddresses.shieldedCoinPublicKey) and a domain separator such as age (it could be anything — residence, etc.). Because the hash is one-way, anybody can see the commitment on-chain without learning your secret key. This is the core of the privacy model: the authority knows that you are attested but never learns who you are. However, be sure to force a strong password because an attacker can attempt to compute a similar commitment in many ways.

Generate the commitment off-chain in Home.tsx. The getCommitment circuit takes two inputs: your secretKey (passed as witness from your private state) and a domain such as age, residency, or certification. The domain acts as a namespace, so a commitment for age is completely different from a commitment for residency even when both use the same secret key.

      const commitment = contractModule.pureCircuits.getCommitment(
        secretKey,
        domainToBytes(domain)
      );

The output is a 32-byte hash. Send this commitment to the authority through any channel of communication. The authority never sees your secret key; they only receive the commitment. Once the authority creates an attestation, they insert the commitment into the ageCommitments Merkle tree on-chain. You can then use it to generate a zero-knowledge proof (ZKP) validating that your secret key produced a commitment that exists in the tree.

When the commitment is deterministic, the same wallet and password always generate the same hash. The current design does not rely on localStorage. Derive the secret key from the public key and a user password instead — this prevents losing your identity.

5. Attest a credential

The authority creates an attestation by selecting type and pasting the user commitment.

This page goes through a couple of steps:

Set up the providers

The provider bundle is the bridge between your frontend and the Midnight network. Each provider handles a specific responsibility:

privateStateProvider manages your local encrypted state (secret keys, Merkle paths) via IndexedDB
publicDataProvider reads on-chain data from the indexer without submitting transactions
zkConfigProvider loads the compiled ZK circuit artifacts (proving keys, verifier keys)
proofProvider forwards proof-generation requests to your local proof server on port 6300
walletProvider handles transaction balancing: it serializes the unsigned transaction, sends it to your wallet extension for fee coverage and signing, then returns the balanced transaction
midnightProvider submits the final signed transaction to the network and returns the transaction identifier

      const providers = {
        privateStateProvider,
        publicDataProvider: indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS),
        zkConfigProvider: zkConfig,
        proofProvider: httpClientProofProvider(PROOF_SERVER, zkConfig),
        walletProvider: {
          getCoinPublicKey(): string {
            return shieldedAddresses.shieldedCoinPublicKey;
          },
          getEncryptionPublicKey(): string {
            return shieldedAddresses.shieldedEncryptionPublicKey;
          },
          async balanceTx(tx: unknown, _ttl?: Date): Promise<unknown> {
            const serializedTx = toHex((tx as { serialize: () => Uint8Array }).serialize());
            const received = await connectedApi.balanceUnsealedTransaction(serializedTx);
            return Transaction.deserialize(
              'signature', 'proof', 'binding', fromHex(received.tx)
            );
          },
        },
        midnightProvider: {
          async submitTx(tx: unknown): Promise<string> {
            const txData = tx as { serialize: () => Uint8Array; identifiers: () => string[] };
            await connectedApi.submitTransaction(toHex(txData.serialize()));
            return txData.identifiers()?.[0] ?? '';
          },
        },
      };

Build the smart contract interface

Reconstruct the deployed smart contract's runtime interface. This is a three-step process:

CompiledContract.make() creates a base contract descriptor from the generated Compact module
CompiledContract.withWitnesses() binds your TypeScript witness implementations so the runtime knows how to resolve localSecretKey() and findAgePath() when the circuit calls them
CompiledContract.withCompiledFileAssets() loads the ZK artifacts from disk — the proving keys, verifier keys, and circuit definitions that the proof server needs

      const cc = CompiledContract.make('attest', contractModule.Contract);
      const ccWithWitnesses = CompiledContract.withWitnesses(cc, witnesses as any);
      const finalContract = CompiledContract.withCompiledFileAssets(
        ccWithWitnesses,
        ZK_ARTIFACTS_PATH
      );

Connect to the deployed smart contract

findDeployedContract() serves multiple purposes. It fetches the on-chain smart contract state, then extracts the embedded verifier keys and compares them head-to-head with the compiled artifacts generated after running compact contracts/Contract.compact {compile_path}. If there is a mismatch between the verifier keys, it throws an error instead of proceeding. This acts like protection against accidentally interacting with the wrong smart contract.

findDeployedContract() also initializes your local private state. Pass authoritySk to createAttestPrivateState() so the witness localSecretKey() resolves correctly when the circuit runs. If the private state ID collides with another role — for example, the prover state — the authentication step would fail with an error, so keeping attestState separate is crucial.

      await findDeployedContract(providers as never, {
        contractAddress,
        compiledContract: finalContract as never,
        privateStateId,
        initialPrivateState: createAttestPrivateState(authoritySk),
      });

Create the transaction interface

createCircuitCallTxInterface() builds a proxy over the deployed smart contract. Instead of manually building transactions, you can call methods such as txInterface.attestAge(commitBytes) directly, and the installed library handles constructing the transaction.

It looks up the circuit definition, wires the witnesses, prepares the private state, and returns a transaction builder that you can execute directly.

      const txInterface = createCircuitCallTxInterface(
        providers as never,
        finalContract as never,
        contractAddress,
        privateStateId
      );

Attestation execution

Calling attestAge() triggers the full Midnight transaction process:

Witness resolution: localSecretKey() fetches authoritySk from the private state
Authority check: the circuit verifies whether the user is an authority by checking if publicKey(sk) == authority on-chain
A zero-knowledge proof is then generated by the proof server, proving that the authority check passes.
Transaction balancing: walletProvider sends the unsigned transaction to your wallet extension/provider, which calculates fees and signs it.
Submission: midnightProvider broadcasts the signed transaction to the Midnight network
Confirmation: the network includes the transaction in a block and inserts the commitment into the ageCommitments Merkle Tree. The user can then use that commitment to prove their age.

result = await (txInterface as any).attestAge(commitBytes);

Now the user has a valid attestation under their unique commitment, which was computed using the secret key passed through witness.

6. Prove your eligibility

The user verifies and generates a proof in Prove.tsx

handleProve() goes through a similar flow to handleAttest(), except that it calls the proveAge() circuit and uses attestSk instead of authoritySk for authentication.

privateStateId is also different. Attest passes attestState, while Prove passes attestProverState — otherwise the transaction fails with Unsupported state unable to authenticate data

initialPrivateState differs too. Attest passes createAttestPrivateState(authoritySk), while Prove passes { secretKey: attestSk } — the prover identity key, not the authority key.

result = await (txInterface as any).proveAge();

Now look at the nullifier in action. In this example, the age has already been verified, as you can see in the explorer: proveAge

https://explorer.1am.xyz/tx/a6b14a14c15d486bc547a449342cc196036be74e4c04699f2a6a1be1ebd03ccb

Execution successful

The wallet returns Proof already used — each credential can only be proven once. The console shows: Prove error: Error: Unexpected error executing scoped transaction '<unnamed>': Error: failed assert: Age proof already used

This means the smart contract is working exactly as intended — the nullifier is recognized as already used.

7. State read flow

When you unlock the Home page, it checks whether you are an authority or not. It does this by querying the smart contract state from the indexer. The raw state data is fed into contractModule.ledger(), which deserializes it into typed ledger fields, including authority: Bytes<32>.

        // Compute publicKey(authoritySk) using the same hash as the contract
        const enc = new TextEncoder();
        const pad = new Uint8Array(32);
        pad.set(enc.encode('mydapp:pk:v1'));
        const descriptor = new CompactTypeVector(2, new CompactTypeBytes(32));
        const authorityPublicKey = persistentHash(descriptor, [pad, authoritySk]);

        const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);
        const state = await provider.queryContractState(contractAddress);
        if (!state) return;

        const ledger = contractModule.ledger(state.data);
        const onChainAuthority = ledger.authority;

The frontend derives your authority secret key from the same master key that unlocked your identity. It then hashes that key through the smart contract's publicKey() circuit to produce your authority public key. If the on-chain authority matches your computed public key byte-for-byte, a green badge appears saying "You are the authority". If there is a mismatch, a grey badge shows "Not the authority".

        const match = onChainAuthority.length === authorityPublicKey.length &&
          onChainAuthority.every((b: number, i: number) => b === authorityPublicKey[i]);

Note: Even if you use the same wallet but there is a password mismatch, it does not show "You are the authority".

8. Off-chain API to store data

Directly requesting the smart contract state from the indexer loads the network unnecessarily and creates a slow user experience. A solution to this is to run a lightweight Express server connected to PostgreSQL. It polls the indexer every 15 seconds or so and caches the data inside PostgreSQL, improving the user experience.

Import a factory function that queries data via GraphQL on the indexer:

import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';

Use setNetworkId('preprod') to set the network to Preprod:

import { setNetworkId } from '@midnight-ntwrk/midnight-js-network-id';

Import compact-runtime. contractRuntime.ContractState.deserialize(serialized) reconstructs a contract's state from its serialized bytes so you can read ledger data such as totalAgeProofs.

import * as contractRuntime from '@midnight-ntwrk/compact-runtime';

Use the V4 Midnight indexer GraphQL endpoints:

const INDEXER_HTTP = 'https://indexer.preprod.midnight.network/api/v4/graphql';
const INDEXER_WS = 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws';

Database schema

When you start the server, it begins tracking the hardcoded smart contract

const TRACKED_CONTRACT = '331460e632fad9146d23b2176433413e8405976afef8a6f0999dda10433f599d';

A simple database schema stores the data. The contracts table tracks which smart contracts are being monitored.

await sql`
  CREATE TABLE contracts (
    address TEXT PRIMARY KEY,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    status TEXT DEFAULT 'synced'
  )
`;

await sql`
  CREATE TABLE contract_states (
    id SERIAL PRIMARY KEY,
    contract_address TEXT REFERENCES contracts(address) ON DELETE CASCADE,
    total_age_proofs BIGINT NOT NULL DEFAULT 0,
    total_residency_proofs BIGINT NOT NULL DEFAULT 0,
    total_cert_proofs BIGINT NOT NULL DEFAULT 0,
    recorded_at TIMESTAMPTZ DEFAULT NOW()
  )
`;

Polling lifecycle

When you start the server, it calls startPolling(TRACKED_CONTRACT). TRACKED_CONTRACT is a hardcoded 331460e632fad9146d23b2176433413e8405976afef8a6f0999dda10433f599d smart contract value. It then begins fetching the current state and registers a setInterval loop repeating every 15 seconds. If the server shuts down, stopPolling() clears the interval and closes the database connection.

function startPolling(address: string) {
  const poll = async () => {
    try {
      const state = await provider.queryContractState(address);
      if (state) await insertState(address, state);
    } catch (e) {
      console.error(`[Poll] ${address.slice(0, 12)}:`, e);
    }
  };

  poll();
  const interval = setInterval(poll, 15_000);
  pollingIntervals.set(address, interval);
}

Parsing and inserting state

The generated smart contract code cannot read raw states returned by the indexer GraphQL V4 endpoint. They must first be serialized back into bytes, then deserialized through ContractState.deserialize(). This is when @midnight-ntwrk/compact-runtime comes in. Finally, the state is passed to ledger() to extract fields such as totalAgeProofs (number of age proofs committed), and then the insertState() function inserts the values into the PostgreSQL database contract_states table.

async function parseContractState(address: string, state: any) {
  const serialized = state.serialize();
  const freshState = contractRuntime.ContractState.deserialize(serialized);
  const ls = ledger(freshState.data);

  return {
    totalAgeProofs: Number(ls.totalAgeProofs) || 0,
    totalResidencyProofs: Number(ls.totalResidencyProofs) || 0,
    totalCertProofs: Number(ls.totalCertProofs) || 0,
  };
}

Serving cached data

The frontend sends a GET /contract request to retrieve the latest snapshot stored in the database. The endpoint joins the contracts and contract_states tables, returning the most recent row ordered by recorded_at.

app.get('/contract', async (req, res) => {
  const c = await sql`SELECT * FROM contracts WHERE address = ${TRACKED_CONTRACT}`;
  if (!c.length) return res.status(404).json({ error: 'Not tracked' });

  const latest = await sql`
    SELECT total_age_proofs, total_residency_proofs, total_cert_proofs, recorded_at
    FROM contract_states
    WHERE contract_address = ${TRACKED_CONTRACT}
    ORDER BY recorded_at DESC
    LIMIT 1
  `;

  res.json({
    address: TRACKED_CONTRACT,
    totalAgeProofs: Number(latest[0]?.total_age_proofs ?? 0),
    totalResidencyProofs: Number(latest[0]?.total_residency_proofs ?? 0),
    totalCertProofs: Number(latest[0]?.total_cert_proofs ?? 0),
  });
});

In the frontend, the Home page sends a request to the /contract endpoint, then renders the cached data.

Now the data is being successfully cached: age=2 residency=1 cert=0

Conclusion

You have now built a full-stack DApp on the Midnight network: a complete zero-knowledge attestation system. It consists of a Compact contract enforcing privacy-preserving zero-knowledge proofs, a UI that derives identities deterministically from nothing but a wallet's shieldedAddresses.shieldedCoinPublicKey and a user password, and an Express API that caches smart contract state. Your identity is not stored. If you lose your password, you lose your identity. Remember these critical design decisions.

Next steps

Now that you've finished this tutorial, here are a few things you can do next:

Check the full repository source code
Add a new credential type e.g., "employment"
Read the Midnight Compact language docs

Troubleshooting

"Wallet not detected" → Make sure 1AM or Lace browser extensions are installed
Transactions failing → Make sure you have tDUST and that the wallet is fully synced
Not the authority → Password or wallet mismatch
Age proof already used → You already proved this credential; use a different one.

[Tutorial] Building an Unshielded Token DApp with UI on Midnight network

Syv — Sat, 18 Apr 2026 14:58:24 +0000

📁 Full Source Code: midnight-apps/unshielded-token

Target audience: Developers

Prerequisites

Node.js installed (v20+)
A Midnight Wallet (e.g., 1AM or Lace)
Some Preprod faucet NIGHT tokens
A package.json with the needed packages
- @midnight-ntwrk/compact-runtime
- @midnight-ntwrk/dapp-connector-api
- @midnight-ntwrk/ledger-v8
- @midnight-ntwrk/midnight-js-contracts
- @midnight-ntwrk/midnight-js-dapp-connector-proof-provider
- @midnight-ntwrk/midnight-js-fetch-zk-config-provider
- @midnight-ntwrk/midnight-js-http-client-proof-provider
- @midnight-ntwrk/midnight-js-indexer-public-data-provider
- @midnight-ntwrk/midnight-js-level-private-state-provider
- @midnight-ntwrk/midnight-js-network-id
- @midnight-ntwrk/midnight-js-node-zk-config-provider
- @midnight-ntwrk/midnight-js-types
- @midnight-ntwrk/wallet-sdk-dust-wallet
- @midnight-ntwrk/wallet-sdk-facade
- @midnight-ntwrk/wallet-sdk-hd
- @midnight-ntwrk/wallet-sdk-shielded
- @midnight-ntwrk/wallet-sdk-unshielded-wallet
- @scure/bip39, react, react-dom, react-router-dom, semver, vite-plugin-node-polyfills, vite-plugin-top-level-await, vite-plugin-wasm, ws, zustand

Clone the dapp-connect project as a starting point. It includes wallet detection, connection, state polling, and the account modal — everything you need before adding smart contract operations.

git clone https://github.com/0xfdbu/midnight-apps.git
cd midnight-apps/dapp-connect
npm install
npm run dev

With the frontend ready to connect, the next step is the smart contract side. Here are three core circuits that handle the native mint for the unshielded token vault lifecycle:

Natively minting a stablecoin into the vault with mintUnshieldedToken

Use a padded string for the domain to define the token standard — in this case, "stablecoin:usd"

export circuit mintToContract(amount: Uint<64>): Bytes<32> {
    const domain = pad(32, "stablecoin:usd");
    const color = mintUnshieldedToken(
        disclose(domain),
        disclose(amount),
        left<ContractAddress, UserAddress>(kernel.self())
    );
    totalSupply = totalSupply + disclose(amount) as Uint<64>;
    return color;
}

Note: You have to cast amount to Uint<64> when updating totalSupply

Transferring with sendUnshielded from vault

To move tokens, sendToUser requires you to reconstruct the color using the same domain and the smart contract's address (kernel.self())

export circuit sendToUser(amount: Uint<64>, userAddr: UserAddress): [] {
    const domain = pad(32, "stablecoin:usd");
    const color = tokenType(disclose(domain), kernel.self());
    sendUnshielded(
        color,
        disclose(amount) as Uint<128>,
        right<ContractAddress, UserAddress>(disclose(userAddr))
    );
}

Depositing into vault with receiveUnshielded

For the receiveTokens circuit, you need to be careful with bit sizes. Unlike the mint function, receiveUnshielded strictly requires a Uint<128> for the amount

export circuit receiveTokens(amount: Uint<128>): [] {
    const domain = pad(32, "stablecoin:usd");
    const color = tokenType(disclose(domain), kernel.self());
    receiveUnshielded(color, disclose(amount));
}

View the full smart contract code in Contract.compact on GitHub.

Compiling the smart contract

Now compile the smart contract so you can use its artifacts in the frontend (verifiers, provers, ZKIR...).

First, install the Compact dev tools

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

Then compile

compact compile contracts/Contract.compact contracts/managed/stablecoin

Note: Skip this step if you want to clone the repo. If you generate new keys, you need to redeploy because the old keys in this path would no longer be usable by the frontend. A smart contract is already deployed on Preprod: 0c0ad6d96daa1b983751db2149a093c34ea73714c33fbad40d291d9e887f8084

If you do decide to recompile and redeploy, run:

MNEMONIC="24 secret seed phrase from Lace or 1AM" npx tsx scripts/go.ts

A simple approach to quickly deploy and save time of wallet syncing by using your existing wallet extension state, View Deploy.tsx (Highly recommended)

Disclaimer: This demonstration uses a smart contract where anybody can mint so do not use for production without proper authentication.

Frontend integration

Now that the smart contract is deployed on Preprod, the next step is to integrate it with the frontend. The features to cover are shown in the screenshot below:

Smart contract operations: mint tokens into the vault, send tokens from the vault to an address, and deposit tokens into the vault.
Statistics: total supply, smart contract (vault) balance, wallet balance.
User wallet: basic operations such as transferring from your own wallet to another wallet and displaying your receiving address and balance.

1. Smart contract operations

Set up the smart contract providers

privateStateProvider: uses levelPrivateStateProvider for persistent localStorage
publicDataProvider: reads on-chain state from the indexer
zkConfigProvider: loads FetchZkConfigProvider — compiled verifiers...
proofProvider: generates zero-knowledge proofs on your proof server
walletProvider: handles balanceTx via connectedApi.balanceUnsealedTransaction
midnightProvider: submits transactions via connectedApi.submitTransaction

Note: In this tutorial, the providers are rebuilt in every function. In a production environment, initialize them once and reuse them across all operations.

The function below covers the full lifecycle of minting into the vault smart contract. Call await mintToContract(BigInt(amount)) in the UI to execute it.

It runs through four stages inside a try/catch:

export async function mintToContract(
  connectedApi: ConnectedAPI,
  coinPublicKey: string,
  shieldedAddresses: { shieldedEncryptionPublicKey: string },
  amount: bigint,
  onSuccess: (txId: string) => void,
  onError: (err: string) => void
): Promise<void> {
  try {
    // stages below
  } catch (err) {
    console.error('[Mint] Error:', err);
    onError(err instanceof Error ? err.message : String(err));
  }
}

1. Load dependencies

Define mods by awaiting getModules(), which imports the compiled contract dependencies. These are cached on the first call.

const mods = await getModules();
const { indexerModule, FetchZkConfigProvider, levelModule, CompiledContract, ledger, proofModule } = mods;

2. Build providers

privateStateProvider: uses levelPrivateStateProvider for persistent localStorage
publicDataProvider: reads on-chain state from the indexer
zkConfigProvider: loads FetchZkConfigProvider — compiled verifiers...
proofProvider: generates zero-knowledge proofs on your proof server
walletProvider: handles balanceTx via connectedApi.balanceUnsealedTransaction
midnightProvider: submits transactions via connectedApi.submitTransaction

const indexerPublicDataProvider = indexerModule.indexerPublicDataProvider;
const levelPrivateStateProvider = levelModule.levelPrivateStateProvider;
const zkConfigProvider = new FetchZkConfigProvider(window.location.origin + CONTRACT_PATH, fetch.bind(window));
const proofProvider = proofModule.httpClientProofProvider(PROOF_SERVER, zkConfigProvider);

const providers: any = {
  privateStateProvider: levelPrivateStateProvider({
    midnightDbName: 'midnight-stablecoin-db',
    privateStateStoreName: STORE_NAME,
    accountId: coinPublicKey,
    privateStoragePasswordProvider: () => STORAGE_PASSWORD,
  }),
  publicDataProvider: indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS),
  zkConfigProvider,
  proofProvider,
  walletProvider: {
    getCoinPublicKey: () => coinPublicKey,
    getEncryptionPublicKey: () => shieldedAddresses.shieldedEncryptionPublicKey,
    async balanceTx(tx: any) {
      const serialized = uint8ArrayToHex(tx.serialize());
      const result = await connectedApi.balanceUnsealedTransaction(serialized);
      const bytes = hexToUint8Array(result.tx);
      return ledger.Transaction.deserialize('signature', 'proof', 'binding', bytes);
    },
  },
  midnightProvider: {
    submitTx: async (tx: any): Promise<string> => {
      const serialized = uint8ArrayToHex(tx.serialize());
      await connectedApi.submitTransaction(serialized);
      return tx.identifiers()[0];
    },
  },
};

3. Connect to the contract

Import the contract module and attach it to the live instance on Preprod. callTx maps directly to your Compact circuits.

const [{ findDeployedContract }] = await Promise.all([
  import('@midnight-ntwrk/midnight-js-contracts'),
]);

const contractModule = await import(CONTRACT_PATH + '/contract/index.js');
const compiledContract = CompiledContract.make('stablecoin', contractModule.Contract).pipe(
  CompiledContract.withVacantWitnesses,
  CompiledContract.withCompiledFileAssets(CONTRACT_PATH)
);

const contract: any = await findDeployedContract(providers, {
  contractAddress: CONTRACT_ADDRESS,
  compiledContract,
  privateStateId: 'stablecoinState',
  initialPrivateState: {},
});

4. Execute the mint

Generate the zero-knowledge proof, then submit the transaction and await the hash

const txData = await contract.callTx.mintToContract(amount);
onSuccess(txData.public.txId);

Note: The proof generation might take some time before the popup appears. This example uses a local proof server at port 6300, so it is fast.

Now that tokens are minted into the vault, the next step is to send them from the vault to an address.

First, handle how user addresses are encoded. The helper function parses a Bech32m string, decodes it to an unshielded address, and returns raw bytes because the sendToUser circuit expects a Bytes<32> field.

export async function encodeUserAddress(bech32Address: string): Promise<Uint8Array> {
  const mods = await getModules();
  const { addressModule } = mods;
  const { MidnightBech32m, UnshieldedAddress } = addressModule;

  try {
    const parsed = MidnightBech32m.parse(bech32Address);
    const decoded: any = parsed.decode(UnshieldedAddress, 'preprod');
    return decoded.data;
  } catch (e) {
    console.error('[encodeUserAddress] Error:', e);
    throw new Error('Invalid address format');
  }
}

This function takes user input and runs it through encodeUserAddress(recipient). It then calls store.contractSend(params...), which invokes the sendToUser circuit containing sendUnshielded.

  const handleSend = async () => {
    if (!amount || !recipient || !connectedApi) return;

    const recipientBytes = await encodeUserAddress(recipient);
    const store = useWalletStore.getState();
    const shieldedAddresses = await connectedApi.getShieldedAddresses();
    const coinPublicKey = shieldedAddresses.shieldedCoinPublicKey;

    await store.contractSend(
      connectedApi,
      coinPublicKey,
      shieldedAddresses,
      BigInt(amount),
      recipientBytes,
      (txId: string) => {
        useWalletStore.getState().setTransactionHash(txId);
        useWalletStore.getState().loadWalletState();
      },
      (errMsg: string) => {
        useWalletStore.getState().setError(errMsg);
      }
    );
  };

Now deposit the stablecoin token into the vault using receiveUnshielded.

The frontend has handleReceive. It functions similarly to handleSend: store.receiveTokens(params...) calls the exported receiveTokens(amount: Uint<128>) circuit, which contains receiveUnshielded(color, disclose(amount)).

   const handleReceive = async () => {
    if (!amount || !connectedApi) return;

    const store = useWalletStore.getState();
    const shieldedAddresses = await connectedApi.getShieldedAddresses();
    const coinPublicKey = shieldedAddresses.shieldedCoinPublicKey;

    await store.receiveTokens(
      connectedApi,
      coinPublicKey,
      shieldedAddresses,
      BigInt(amount),
      (txId: string) => {
        useWalletStore.getState().setTransactionHash(txId);
        useWalletStore.getState().loadWalletState();
      },
      (errMsg: string) => {
        useWalletStore.getState().setError(errMsg);
      }
    );
  };

Note: Use getShieldedAddresses() because it retrieves both keys in one call. It returns shieldedAddress, shieldedCoinPublicKey, and shieldedEncryptionPublicKey.

2. Statistics

The vault smart contract has a state called balance, which returns a set of token balances. The approach here is to iterate through the balances array to find how many tokens match the token ID. For a token ID to appear, you need to execute a mint operation.

export async function getContractBalance(): Promise<bigint> {
  try {
    const mods = await getModules();
    const { indexerModule } = mods;
    const indexerPublicDataProvider = indexerModule.indexerPublicDataProvider;
    const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);

    const contractState = await provider.queryContractState(CONTRACT_ADDRESS);
    console.log('[getContractBalance] Contract state balance:', contractState?.balance);

    if (!contractState?.balance) return 0n;

    for (const [key, value] of contractState.balance.entries()) {
      console.log('[getContractBalance] Key:', key, 'Value:', value.toString());
      if (key && typeof key === 'object' && 'raw' in key && key.raw === STABLECOIN_TOKEN) {
        console.log('[getContractBalance] Found balance:', value.toString());
        return value;
      }
    }

    return 0n;
  } catch (err) {
    console.error('[getContractBalance] Error:', err);
    return 0n;
  }
}

Now get the user's stablecoin balance. First call connectedApi.getUnshieldedBalances() to get all user wallet balances, then filter the results with balances[STABLECOIN_TOKEN].

export async function getUserStablecoinBalance(connectedApi: ConnectedAPI): Promise<bigint> {
  try {
    const balances = await connectedApi.getUnshieldedBalances();
    const stablecoinBalance = balances[STABLECOIN_TOKEN];
    return stablecoinBalance || 0n;
  } catch (err) {
    console.error('[getUserStablecoinBalance] Error:', err);
    return 0n;
  }
}

To retrieve totalSupply, create a function getContractState(). It works in three stages:

export async function getContractState(): Promise<ContractState> {
  try {
    // stages below
  } catch (err) {
    console.error('[ContractState] Error:', err);
    return { totalSupply: 0n, totalBurned: 0n };
  }
}

1. Query the indexer

Fetch the raw contract state from the Preprod indexer.

const mods = await getModules();
const { indexerModule } = mods;

const indexerPublicDataProvider = indexerModule.indexerPublicDataProvider;
const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);

const contractState = await provider.queryContractState(CONTRACT_ADDRESS);
if (!contractState) {
  return { totalSupply: 0n, totalBurned: 0n };
}

2. Deserialize into typed ledger state

The indexer returns raw bytes. Import the contract module and pass the raw data through ledger() to get typed fields like totalSupply and totalBurned.

const contractModule = await import(CONTRACT_PATH + '/contract/index.js');
const ledgerState = contractModule.ledger(contractState.data);

3. Return the values

return {
  totalSupply: ledgerState.totalSupply,
  totalBurned: ledgerState.totalBurned,
};

3. Wallet operations

For displaying user receiving addresses and stablecoin balances, see section 2.

const unshieldedAddress = await connectedApi.getUnshieldedAddress();
const unshieldedBalances = await connectedApi.getUnshieldedBalances();

import { useState, useEffect } from 'react';
import { Link } from 'react-router-dom';
import { useWalletStore } from '../hooks/useWallet';
import { getUserStablecoinBalance } from '../hooks/wallet/services/contractCalls';

export function WalletInfoPage() {
  const { connectedApi, addresses } = useWalletStore();
  const [balance, setBalance] = useState<bigint | null>(null);
  const [copied, setCopied] = useState<string | null>(null);

  useEffect(() => {
    if (!connectedApi) return;

    const fetchBalance = async () => {
      const bal = await getUserStablecoinBalance(connectedApi);
      setBalance(bal);
    };

    fetchBalance();
    const interval = setInterval(fetchBalance, 15000);
    return () => clearInterval(interval);
  }, [connectedApi]);

  const handleCopy = async (text: string, field: string) => {
    await navigator.clipboard.writeText(text);
    setCopied(field);
    setTimeout(() => setCopied(null), 2000);
  };

  const formatBalance = (bal: bigint | null): string => {
    if (bal === null) return '—';
    return bal.toLocaleString();
  };

  const formatAddress = (addr: string): string => {
    if (!addr) return '—';
    return addr.length > 24 ? `${addr.slice(0, 12)}...${addr.slice(-12)}` : addr;
  };

Next, send the stablecoin token between user wallets. The handleSend function — different from contractSend — looks like this:

const handleSend = async () => {
    if (!amount || !recipient) return;
    await sendStablecoin(recipient, BigInt(amount));
  };

sendStablecoin wraps connectedApi.makeTransfer. Instead of sending nativeToken, it passes the stablecoin token ID as the type, so the wallet knows which asset to transfer. The makeTransfer call below is what actually happens inside sendStablecoin: it constructs the output we need, balances the transaction, which is then submitted with connectedApi.submitTransaction(result.tx).

export async function sendStablecoin(
  connectedApi: ConnectedAPI,
  recipient: string,
  amount: bigint,
  onSuccess: () => void,
  onError: (err: string) => void
): Promise<void> {
  try {
    const desiredOutput: DesiredOutput = {
      kind: 'unshielded',
      type: STABLECOIN_TOKEN,
      value: amount,
      recipient,
    };
    const result = await connectedApi.makeTransfer([desiredOutput]);
       if (result.tx) {
      // wallet returned an unsigned tx — submit it
      await connectedApi.submitTransaction(result.tx);
    }
    onSuccess();
  } catch (err) {
    if ((err as any)?.type === 'DAppConnectorAPIError' && (err as any)?.code === 'Disconnected') {
      throw err;
    }
    onError(handleWalletError(err));
  }
}

Key differences from contractSend

	`contractSend`	`makeTransfer`
Funds source	Vault funds	User funds
Mechanism	`handleSend`	DApp connector `makeTransfer`
Address encoding	Requires encoding → `Bytes<32>`	Passes `Bech32m` directly
ZK proofs	Required for circuit execution	Handled by wallet

When to use unshielded vs shielded tokens and the privacy trade-offs

	Unshielded	Shielded
Privacy mechanism	None — completely transparent blockchain transactions	Zero-knowledge proofs (Zswap)
Legal Compliance	Can be audited for AML	Requires keys for selective disclosure
Use cases	Compliant stablecoins... as required by regulators	Confidential transfers...

Why choose unshielded for the stablecoin

Regulatory compliance: Stablecoin issuers typically need to demonstrate full traceability of supply and transfers due to AML (anti-money laundering) regulations.
Verifiability: The vault demonstrates native mint functionality for this stablecoin. It contains a public state totalSupply that is publicly readable so regulators can monitor it.
Exchange listings: Many exchanges have delisted privacy coins due to regulatory pressure, while unshielded tokens such as NIGHT have been listed because they offer full transparency.

When to choose shielded over unshielded

Private tokenized securities: Transfers are confidential while specific properties like voting rights remain verifiable.
Regulated industries requiring data minimization: In healthcare, frameworks like GDPR, CCPA, and HIPAA require minimal data disclosure. Shielded tokens ensure sensitive information stays in local storage while zero-knowledge proofs can still confirm eligibility and compliance.
Forward secrecy: Even if encryption keys are compromised in the future, shielded transactions remain private. This is something unshielded transactions cannot offer.

Conclusion

Midnight's multi-modal design is different from other networks that enforce a single model. You are not forced into shielded transactions only, like XMR, or fully transparent ones, like Bitcoin. Instead, you can use whatever fits your use case at the circuit level.

Next steps

Now that you have finished this tutorial, here are a few things you can do next:

Check the full repository source code on GitHub
Read the Midnight Compact language docs
Add authentication / whitelist for mint

Troubleshooting

"Wallet not detected" → Make sure 1AM or Lace browser extensions are installed.
Transactions failing → Make sure you have tDUST and that the wallet is fully synced.

DEV Community: Syv

[Tutorial] Reading and Reacting to Contract State from a Frontend on Midnight network

Prerequisites

Summary

Understanding the smart contract ledger

1. The indexer provider

2. One-time smart contract state queries

Querying raw smart contract state

Querying combined ZSwap + smart contract state

3. Reading wallet balances

Where do token colors come from?

4. Deserializing ledger fields

5. Displaying contract state in a UI

6. Real-time updates with WebSocket subscriptions

The useContractState hook

7. When to poll vs when to subscribe

Conclusion

Next steps

Troubleshooting

[Tutorial] DApp Connector API: Connecting a Browser dApp to Midnight Wallets

Prerequisites

Architecture: browser vs CLI

Detecting wallets via window.midnight

Wallet selection modal

Connecting to Lace or 1AM

The connection flow

Auto-reconnect

Account modal

Subscribing to wallet state changes

CLI: native push subscriptions

The browser transaction flow (balanceUnsealedTransaction)

Why each step matters

The CLI transaction flow

Key derivation

Wallet initialization

CLI transfer: transferTransaction + signRecipe

Dust sync handling

Run the CLI transfer script

Conclusion

Next steps

Troubleshooting

Browser errors

CLI errors

[Tutorial] Building a full-stack Midnight DApp: zero-knowledge attestation protocol

Prerequisites

1. Building the smart contract

2. Wallet, identity & providers

3. Deploy the smart contract

4. Generate a commitment

5. Attest a credential

Set up the providers

Build the smart contract interface

Connect to the deployed smart contract

Create the transaction interface

Attestation execution

6. Prove your eligibility

7. State read flow

8. Off-chain API to store data

Database schema

Polling lifecycle

Parsing and inserting state

Serving cached data

Conclusion

Next steps

Troubleshooting

[Tutorial] Building an Unshielded Token DApp with UI on Midnight network

Prerequisites

Compiling the smart contract

Frontend integration

1. Smart contract operations

2. Statistics

3. Wallet operations

When to use unshielded vs shielded tokens and the privacy trade-offs

Why choose unshielded for the stablecoin

When to choose shielded over unshielded

Conclusion

Next steps

Troubleshooting

The `useContractState` hook

Detecting wallets via `window.midnight`

The browser transaction flow (`balanceUnsealedTransaction`)

CLI transfer: `transferTransaction` + `signRecipe`