DEV Community: Oladeji Tosin

Build a privacy-preserving voting DApp on Midnight

Oladeji Tosin — Wed, 13 May 2026 08:43:41 +0000

Introduction

On most blockchains, every vote is permanently public. Anyone can scan the ledger and learn exactly how each address voted, which creates coercion risks, voting bloc pressure, and a chilling effect on genuine participation. Privacy-preserving voting solves this by separating the act of casting a ballot from the act of counting it, so the final tally is verifiable while each individual choice stays hidden.

Midnight is a Layer 1 blockchain built specifically for data protection. Its smart contract language, Compact, compiles to zero-knowledge (ZK) circuits, which means the network can verify that a voter followed the rules without learning what they voted. This tutorial uses a commit-reveal scheme: in the commit phase, voters submit a cryptographic hash of their ballot; in the reveal phase, a ZK proof demonstrates the revealed choice matches the earlier hash, and the counter increments accordingly. Neither phase exposes the plaintext ballot.

By the end of this tutorial you will have a complete, working DApp consisting of a Compact smart contract, a TypeScript API layer, a vitest test suite that runs without a live network, and a React frontend that connects to the Midnight preview Testnet through the 1AM wallet browser extension.

here is the full github repo

Prerequisites

Before you begin, install and verify the following tools:

Node.js v22+
Google Chrome with the 1AM wallet extension installed (enables testnet transactions with sponsored fees)
VS Code (recommended)

Install the Compact toolchain:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh
source ~/.zshrc   # or source ~/.bashrc for bash users
compact update
compact --version
compact compile --version

The 1AM wallet provides a remote prover, so no local proof server is needed. When you connect the wallet, the DApp reads the prover address from the wallet configuration and routes all proof requests there automatically.

Step 1: Scaffold the monorepo

Create the root directory and the four workspace packages.

mkdir voting_compact && cd voting_compact
mkdir -p contract/src api/src test frontend/src

The monorepo has four packages: contract (Compact source and compiler output), api (TypeScript wrapper around the compiled contract), test (vitest suite), and frontend (React + Vite UI). Keeping them as separate npm workspaces lets each package declare its own dependencies and build independently while sharing the root node_modules.

Step 2: Create the root package.json

Create the workspace root that ties all four packages together.

{
  "name": "voting-compact",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22.0.0"
  },
  "workspaces": [
    "contract",
    "api",
    "test",
    "frontend"
  ],
  "scripts": {
    "compact": "npm run compact --workspace=contract",
    "build": "npm run build --workspace=contract && npm run build --workspace=api",
    "test": "npm run test --workspace=test",
    "dev": "npm run dev --workspace=frontend"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-js": "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.16.0",
    "@midnight-ntwrk/dapp-connector-api": "^4.0.0",
    "@midnight-ntwrk/midnight-js-contracts": "^4.0.0",
    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "^4.0.0",
    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "^4.0.0",
    "@midnight-ntwrk/midnight-js-level-private-state-provider": "^4.0.0",
    "@midnight-ntwrk/midnight-js-network-id": "^4.0.0",
    "@midnight-ntwrk/midnight-js-types": "^4.0.0",
    "@midnight-ntwrk/wallet-sdk-address-format": "^3.1.1",
    "pino": "^10.3.1",
    "rxjs": "^7.8.2"
  },
  "devDependencies": {
    "typescript": "^5.9.3",
    "vitest": "^4.0.18"
  },
  "overrides": {
    "@midnight-ntwrk/compact-js": {
      "@midnight-ntwrk/compact-runtime": "0.16.0"
    }
  }
}

The overrides block forces compact-js to use the same compact-runtime version as the rest of the project. Without it, compact-js pins its own nested copy of compact-runtime@0.15.0, which causes a version mismatch error at runtime because checkRuntimeVersion() is called at module load time and finds two conflicting copies. The build script compiles contract before api because api imports from @voting-compact/contract, which only exists in contract/dist/ after compilation.

Step 3: Create the root tsconfig.json

Create the shared TypeScript configuration at the workspace root.

{
  "compilerOptions": {
    "target":           "ES2022",
    "module":           "NodeNext",
    "moduleResolution": "NodeNext",
    "lib":              ["ES2022", "DOM"],
    "strict":           true,
    "skipLibCheck":     true,
    "declaration":      true,
    "declarationMap":   true,
    "sourceMap":        true,
    "esModuleInterop":  true,
    "resolveJsonModule": true,
    "outDir":           "./dist"
  },
  "exclude": ["node_modules", "dist"]
}

NodeNext module resolution is required because the Midnight SDK packages are published as native ES modules with explicit .js extensions on their imports. Using any other module resolution strategy causes TypeScript to fail to locate the generated contract bindings.

Step 4: Write the Compact smart contract

Create contract/src/voting.compact. This is the entire contract from line 1 to the last line.

pragma language_version >= 0.22;

import CompactStandardLibrary;

// ─── State Enums ───────────────────────────────────────────────────────────────

export enum LedgerState { setup, commit, reveal, final }
export enum LocalState  { initial, committed, revealed }

// ─── Ledger Fields ─────────────────────────────────────────────────────────────

export ledger organizer:      Bytes<32>;
export ledger state:          LedgerState;
export ledger topic:          Maybe<Opaque<"string">>;
export ledger round:          Counter;
export ledger commitDeadline: Uint<64>;
export ledger revealDeadline: Uint<64>;

// Voter eligibility: HistoricMerkleTree keeps all past roots valid as new
// voters are added after some participants have already committed.
export ledger eligibleVoters: HistoricMerkleTree<10, Bytes<32>>;

// Committed vote commitments (used to verify reveal proofs).
export ledger committedVotes: HistoricMerkleTree<10, Bytes<32>>;


// Nullifier sets — one per phase, different domain separators prevent collision.
export ledger committed: Set<Bytes<32>>;
export ledger revealed:  Set<Bytes<32>>;

export ledger yes: Counter;
export ledger no:  Counter;

// ─── Witnesses ─────────────────────────────────────────────────────────────────

witness localSecretKey():                                      Bytes<32>;
witness localState():                                          LocalState;
witness localAdvanceState():                                   [];
witness localRecordVote(vote: Boolean):                        [];
witness localVoteCast():                                       Maybe<Boolean>;
witness localPathOfPk(pk: Bytes<32>): Maybe<MerkleTreePath<10, Bytes<32>>>;
witness localPathOfCm(cm: Bytes<32>): Maybe<MerkleTreePath<10, Bytes<32>>>;

// ─── Domain-Separated Commitment Struct ────────────────────────────────────────

struct RoundPreimage {
  round:     Uint<64>;
  domainSep: Bytes<8>;
}

// ─── Helper Circuits ───────────────────────────────────────────────────────────

// Derive voter public key from secret key.
circuit derivePk(sk: Bytes<32>): Bytes<32> {
  // "vote:udao:pk" = 12 characters → Bytes<12>
  return persistentCommit<Bytes<12>>("vote:udao:pk", disclose(sk));
}

// Commit-phase nullifier — domain "vote:cn".
// Prevents a voter from committing twice in the same round.
circuit commitNullifier(sk: Bytes<32>): Bytes<32> {
  return persistentCommit<RoundPreimage>(
    RoundPreimage { round: round, domainSep: pad(8, "vote:cn") },
    disclose(sk));
}

// Reveal-phase nullifier — domain "vote:rn".
// Prevents a voter from revealing twice in the same round.
circuit revealNullifier(sk: Bytes<32>): Bytes<32> {
  return persistentCommit<RoundPreimage>(
    RoundPreimage { round: round, domainSep: pad(8, "vote:rn") },
    disclose(sk));
}

// Vote commitment — domain is the ballot bytes ("yes" / "no").
// Links a commit to a later reveal without revealing the ballot early.
circuit commitWithSk(ballot: Bytes<8>, sk: Bytes<32>): Bytes<32> {
  return persistentCommit<RoundPreimage>(
    RoundPreimage { round: round, domainSep: ballot },
    disclose(sk));
}

// ─── Constructor ───────────────────────────────────────────────────────────────

constructor() {
  const sk = localSecretKey();
  organizer = disclose(derivePk(sk));
  state     = LedgerState.setup;
}

// ─── Organizer Circuits ────────────────────────────────────────────────────────

// Set the proposal topic and phase deadlines, moving state: setup → commit.
export circuit initialize(
  newTopic:         Opaque<"string">,
  newCommitDeadline: Uint<64>,
  newRevealDeadline: Uint<64>
): [] {
  const sk  = localSecretKey();
  const apk = derivePk(sk);
  assert(apk == organizer,            "Not organizer");
  assert(state == LedgerState.setup,  "Not in setup phase");
  topic          = some<Opaque<"string">>(disclose(newTopic));
  commitDeadline = disclose(newCommitDeadline);
  revealDeadline = disclose(newRevealDeadline);
  state          = LedgerState.commit;
}

// Register a voter by inserting their public key into the eligibility tree.
export circuit addVoter(voterPk: Bytes<32>): [] {
  const sk  = localSecretKey();
  const apk = derivePk(sk);
  assert(apk == organizer,            "Not organizer");
  assert(state == LedgerState.commit, "Not in commit phase");
  eligibleVoters.insert(disclose(voterPk));
}

// ─── Voter Circuits ────────────────────────────────────────────────────────────

// Commit phase: voter submits hash(vote || secret).
// Proves Merkle eligibility without revealing the ballot.
export circuit voteCommit(ballot: Boolean): [] {
  assert(state == LedgerState.commit && localState() == LocalState.initial,
    "Not in commit phase or already committed");
  const sk     = localSecretKey();
  const comNul = commitNullifier(sk);
  assert(!committed.member(comNul), "Already committed this round");

  const pk   = derivePk(sk);
  const path = localPathOfPk(pk);
  assert(
    disclose(path.is_some) &&
    eligibleVoters.checkRoot(disclose(merkleTreePathRoot<10, Bytes<32>>(path.value))) &&
    pk == path.value.leaf,
    "Not an eligible voter");

  localRecordVote(ballot);
  const cm = commitWithSk(ballot ? pad(8, "yes") : pad(8, "no"), sk);
  committedVotes.insert(disclose(cm));
  committed.insert(comNul);
  localAdvanceState();
}

// Reveal phase: voter proves their earlier commitment and increments the tally.
export circuit voteReveal(): [] {
  assert(state == LedgerState.reveal && localState() == LocalState.committed,
    "Not in reveal phase or not committed");
  const sk     = localSecretKey();
  const revNul = revealNullifier(sk);
  assert(!revealed.member(revNul), "Already revealed this round");

  const vote = localVoteCast();
  assert(vote.is_some, "No vote to reveal");

  const cm   = commitWithSk(vote.value ? pad(8, "yes") : pad(8, "no"), sk);
  const path = localPathOfCm(cm);
  assert(
    disclose(path.is_some) &&
    committedVotes.checkRoot(disclose(merkleTreePathRoot<10, Bytes<32>>(path.value))) &&
    cm == path.value.leaf,
    "Invalid commitment proof");

  if (disclose(vote.value)) {
    yes.increment(1);
  } else {
    no.increment(1);
  }
  revealed.insert(revNul);
  localAdvanceState();
}

// ─── Time-Locked Phase Transitions ────────────────────────────────────────────

// Anyone can advance commit → reveal once the commit deadline has passed.
export circuit advanceToReveal(): [] {
  assert(state == LedgerState.commit,       "Not in commit phase");
  assert(blockTimeGte(commitDeadline),      "Commit phase not over yet");
  state = LedgerState.reveal;
}

// Anyone can advance reveal → final once the reveal deadline has passed.
export circuit advanceToFinal(): [] {
  assert(state == LedgerState.reveal,       "Not in reveal phase");
  assert(blockTimeGte(revealDeadline),      "Reveal phase not over yet");
  state = LedgerState.final;
}

// ─── Result ───────────────────────────────────────────────────────────────────

export struct Tally {
  yes: Uint<64>;
  no:  Uint<64>;
}

// Read final tally (only callable once voting is complete).
export circuit getTally(): Tally {
  assert(state == LedgerState.final, "Voting not finalized");
  return Tally { yes: yes.read(), no: no.read() };
}

The contract uses HistoricMerkleTree for eligibleVoters rather than a plain MerkleTree so that all past Merkle roots stay valid even as new voters are added later. Without this, a voter who committed before the organizer added additional voters would find their eligibility proof invalid during reveal. The two nullifier circuits (commitNullifier, revealNullifier) and the commitment circuit (commitWithSk) each use a distinct domainSep so their outputs can never collide even though they share the same persistentCommit function signature. blockTimeGte compares against Unix seconds, not milliseconds, which is why deadlines stored on the ledger must be in seconds.

Step 5: Set up the contract package

Create contract/package.json:

{
  "name": "@voting-compact/contract",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types":   "./dist/index.d.ts",
      "import":  "./dist/index.js",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "compact":   "compact compile src/voting.compact src/managed/voting",
    "build":     "tsc --project tsconfig.build.json && rm -rf dist/managed && cp -Rf src/managed dist/managed",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-js":      "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.16.0"
  },
  "devDependencies": {
    "typescript": "^5.9.3"
  }
}

Create contract/tsconfig.json:

{
  "compilerOptions": {
    "target":           "ES2022",
    "module":           "NodeNext",
    "moduleResolution": "NodeNext",
    "lib":              ["ES2022"],
    "strict":           true,
    "skipLibCheck":     true,
    "declaration":      true,
    "declarationMap":   true,
    "sourceMap":        true,
    "esModuleInterop":  true,
    "resolveJsonModule": true,
    "outDir":           "./dist",
    "rootDir":          "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "src/managed"]
}

Create contract/tsconfig.build.json with the same contents as contract/tsconfig.json. The rm -rf dist/managed before the copy prevents macOS cp -Rf from nesting the directory when the destination already exists.

Step 6: Compile the contract

Run the Compact compiler to generate ZK circuits, proving keys, and TypeScript bindings.

npm run compact

This command runs compact compile src/voting.compact src/managed/voting and produces the following output:

contract/src/managed/voting/contract/ — TypeScript bindings and the JavaScript implementation of the compiled contract
contract/src/managed/voting/keys/ — proving and verifying keys for each ZK circuit
contract/src/managed/voting/zkir/ — ZK intermediate representation, the bridge between Compact and the ZK backend
contract/src/managed/voting/compiler/ — metadata including runtime-version and compiler-version fields

The generated contract/index.js calls checkRuntimeVersion() at module load time. It verifies that the installed compact-runtime npm package matches the version the compiler targeted. A mismatch causes a CompactError before React mounts, which produces a blank browser screen with no visible error in the UI.

Step 7: Write the witness implementations

Create contract/src/witnesses.ts. Witnesses are TypeScript functions that the ZK prover calls to supply private inputs to circuits at proof-generation time.

import type { WitnessContext } from '@midnight-ntwrk/compact-runtime';
import { type Ledger, type Witnesses, LocalState } from './managed/voting/contract/index.js';

// ─── Private State ────────────────────────────────────────────────────────────

export type VotingPrivateState = {
  secretKey:   Uint8Array;
  voterState:  LocalState;
  vote:        boolean | null;
};

export const createVotingPrivateState = (secretKey: Uint8Array): VotingPrivateState => ({
  secretKey,
  voterState: LocalState.initial,
  vote:       null,
});

export const votingPrivateStateKey = 'votingPrivateState';

// ─── Witness Implementations ──────────────────────────────────────────────────

export const witnesses: Witnesses<VotingPrivateState> = {

  // Return the voter's 32-byte secret key.
  localSecretKey: ({ privateState }: WitnessContext<Ledger, VotingPrivateState>) =>
    [privateState, privateState.secretKey],

  // Return the voter's current local phase (initial / committed / revealed).
  localState: ({ privateState }: WitnessContext<Ledger, VotingPrivateState>) =>
    [privateState, privateState.voterState],

  // Advance local phase: initial → committed → revealed.
  localAdvanceState: ({ privateState }: WitnessContext<Ledger, VotingPrivateState>) => {
    const next = privateState.voterState === LocalState.initial
      ? LocalState.committed
      : LocalState.revealed;
    return [{ ...privateState, voterState: next }, []];
  },

  // Store the ballot choice in private state (called during voteCommit).
  localRecordVote: (
    { privateState }: WitnessContext<Ledger, VotingPrivateState>,
    vote_0: boolean,
  ) => [{ ...privateState, vote: vote_0 }, []],

  // Return the stored ballot as Maybe<Boolean>.
  localVoteCast: ({ privateState }: WitnessContext<Ledger, VotingPrivateState>) => [
    privateState,
    privateState.vote !== null
      ? { is_some: true,  value: privateState.vote }
      : { is_some: false, value: false },
  ],

  // Look up a Merkle path for the voter's public key in the eligibleVoters tree.
  // The ledger is passed via WitnessContext so the circuit gets a live, provable
  // path that reflects the current on-chain tree state.
  localPathOfPk: (
    { privateState, ledger }: WitnessContext<Ledger, VotingPrivateState>,
    pk_0: Uint8Array,
  ) => {
    const path = ledger.eligibleVoters.findPathForLeaf(pk_0);
    return [
      privateState,
      path !== undefined
        ? { is_some: true,  value: path }
        : { is_some: false, value: { leaf: pk_0, path: [] as any[] } },
    ];
  },

  // Look up a Merkle path for a committed vote hash in the committedVotes tree.
  localPathOfCm: (
    { privateState, ledger }: WitnessContext<Ledger, VotingPrivateState>,
    cm_0: Uint8Array,
  ) => {
    const path = ledger.committedVotes.findPathForLeaf(cm_0);
    return [
      privateState,
      path !== undefined
        ? { is_some: true,  value: path }
        : { is_some: false, value: { leaf: cm_0, path: [] as any[] } },
    ];
  },
};

Each witness function receives a WitnessContext containing the current privateState and ledger, and returns a tuple of [updatedPrivateState, circuitReturnValue]. The localPathOfPk and localPathOfCm witnesses call findPathForLeaf on the live ledger tree so the Merkle path reflects the tree's current state at proof-generation time. When no path exists (the voter is ineligible), the witness returns a dummy path that causes the circuit's assert to fail, which is the intended behavior.

Step 8: Create the contract package entry point

Create contract/src/index.ts to wire together the compiled bindings and witness implementations.

import { CompiledContract } from '@midnight-ntwrk/compact-js';

export * from './managed/voting/contract/index.js';
export * from './witnesses.js';

import * as CompiledVotingContract from './managed/voting/contract/index.js';
import * as Witnesses from './witnesses.js';

// The compiled contract object wires together the generated ZK circuits,
// the witness implementations, and the compiled asset paths.
// This is what gets passed to deployContract() or findDeployedContract().
export const VotingCompiledContract = CompiledContract.make<
  CompiledVotingContract.Contract<Witnesses.VotingPrivateState>
>('Voting', CompiledVotingContract.Contract<Witnesses.VotingPrivateState>).pipe(
  CompiledContract.withWitnesses(Witnesses.witnesses),
  CompiledContract.withCompiledFileAssets('./managed/voting'),
);

CompiledContract.withCompiledFileAssets('./managed/voting') tells the SDK where to find the keys/ and zkir/ directories at runtime. In the browser, the Vite config serves these files from {origin}/keys/ and {origin}/zkir/, so FetchZkConfigProvider can retrieve them over HTTP during proof generation.

Step 9: Build the contract

install npm

npm i

Compile the TypeScript and copy the managed assets into dist/. Run this from the monorepo root (the directory containing the root package.json).

npm run build --workspace=contract

After this command succeeds, contract/dist/ contains the JavaScript bindings and a copy of the managed/ directory. The api package imports from @voting-compact/contract, which npm resolves to this dist/ folder via the exports field in contract/package.json.

Step 10: Create the API package

Create api/package.json:

{
  "name": "@voting-compact/api",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc --project tsconfig.build.json",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  },
  "dependencies": {
    "@voting-compact/contract": "*",
    "@midnight-ntwrk/compact-js": "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.16.0",
    "@midnight-ntwrk/midnight-js-contracts": "^4.0.0",
    "@midnight-ntwrk/midnight-js-types": "^4.0.0",
    "@midnight-ntwrk/midnight-js-network-id": "^4.0.0",
    "pino": "^10.3.1",
    "rxjs": "^7.8.2"
  },
  "devDependencies": {
    "typescript": "^5.9.3"
  }
}

Create api/tsconfig.json:

{
  "compilerOptions": {
    "target":           "ES2022",
    "module":           "NodeNext",
    "moduleResolution": "NodeNext",
    "lib":              ["ES2022", "DOM"],
    "strict":           true,
    "skipLibCheck":     true,
    "declaration":      true,
    "declarationMap":   true,
    "sourceMap":        true,
    "esModuleInterop":  true,
    "resolveJsonModule": true,
    "outDir":           "./dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Create api/tsconfig.build.json with the same contents as api/tsconfig.json.

Step 11: Define the shared types

Create api/src/types.ts.

import type { ContractAddress } from '@midnight-ntwrk/compact-runtime';
import type { ContractProviders, DeployedContract } from '@midnight-ntwrk/midnight-js-contracts';
import type { Contract, Witnesses, LedgerState } from '@voting-compact/contract';
import type { VotingPrivateState } from '@voting-compact/contract';

// ─── Provider bundle used throughout the API ──────────────────────────────────

export type VotingContract = Contract<VotingPrivateState, Witnesses<VotingPrivateState>>;

export type VotingProviders = ContractProviders<VotingContract>;

// ─── Observable state derived from ledger + private state ─────────────────────

export type VotingDerivedState = {
  contractAddress: ContractAddress;
  phase:           LedgerState;
  topic:           string | null;
  commitDeadline:  bigint;
  revealDeadline:  bigint;
  yesCount:        bigint;
  noCount:         bigint;
  round:           bigint;
  isOrganizer:     boolean;
  voterStatus:     'ineligible' | 'eligible' | 'committed' | 'revealed';
  myVoterPkHex:    string;
};

export type DeployedVotingContract = DeployedContract<VotingContract>;

VotingProviders is a type alias for ContractProviders<VotingContract>, which the SDK defines as a bundle of six providers: privateStateProvider, publicDataProvider, zkConfigProvider, proofProvider, walletProvider, and midnightProvider. Passing this bundle as a single argument to deployContract and findDeployedContract is the standard Midnight pattern. myVoterPkHex holds the organizer's derived public key as a hex string so the UI can display it for copy-pasting into the Add Voter form.

Step 12: Write the VotingAPI class

Create api/src/index.ts.

/**
 * VotingAPI — high-level interface over the Midnight voting contract.
 *
 * Orchestrates the full lifecycle: deploy → initialize → addVoter →
 * voteCommit → advanceToReveal → voteReveal → advanceToFinal → getTally.
 */

import * as Voting from '@voting-compact/contract';
import { type ContractAddress } from '@midnight-ntwrk/compact-runtime';
import { type Logger } from 'pino';
import { deployContract, findDeployedContract } from '@midnight-ntwrk/midnight-js-contracts';
import { map, from, switchMap, type Observable } from "rxjs";

import {
  VotingCompiledContract,
  createVotingPrivateState,
  votingPrivateStateKey,
} from '@voting-compact/contract';
import type { VotingProviders, VotingDerivedState } from './types.js';

// ─── Helpers ──────────────────────────────────────────────────────────────────

function randomBytes32(): Uint8Array {
  const buf = new Uint8Array(32);
  globalThis.crypto.getRandomValues(buf);
  return buf;
}

// ─── VotingAPI class ──────────────────────────────────────────────────────────

export class VotingAPI {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Observable<VotingDerivedState>;

  private constructor(
    private readonly deployedContract: any,
    private readonly providers: VotingProviders,
    private readonly logger?: Logger,
  ) {
    this.deployedContractAddress = deployedContract.deployTxData.public.contractAddress;
    providers.privateStateProvider.setContractAddress(this.deployedContractAddress);
this.state$ = providers.publicDataProvider
  .contractStateObservable(this.deployedContractAddress, { type: "latest" })
  .pipe(
    map((cs) => Voting.ledger(cs.data)),
    switchMap((ledger) =>
      from(
        providers.privateStateProvider.get(
          votingPrivateStateKey
        ) as Promise<Voting.VotingPrivateState>
      ).pipe(
        map((privateState) => {
          const myPk = ledger.organizer;
          const myVoterPkHex = this.hexOf(myPk);
          return {
            contractAddress: this.deployedContractAddress,
            phase: ledger.state,
            topic: ledger.topic.is_some ? ledger.topic.value : null,
            commitDeadline: ledger.commitDeadline,
            revealDeadline: ledger.revealDeadline,
            yesCount: ledger.yes,
            noCount: ledger.no,
            round: ledger.round,
            isOrganizer: this.hexOf(myPk) === this.hexOf(ledger.organizer),
            voterStatus: this.voterStatus(ledger, privateState, myPk),
            myVoterPkHex,
          } satisfies VotingDerivedState;
        })
      )
    )
  );


  }

  // ─── Organizer actions ───────────────────────────────────────────────────────

  async initialize(topic: string, commitDeadline: bigint, revealDeadline: bigint): Promise<void> {
    this.logger?.info(`initialize: topic="${topic}"`);
    await this.deployedContract.callTx.initialize(topic, commitDeadline, revealDeadline);
  }

  async addVoter(voterPk: Uint8Array): Promise<void> {
    this.logger?.info(`addVoter: pk=${this.hexOf(voterPk)}`);
    await this.deployedContract.callTx.addVoter(voterPk);
  }

  async advanceToReveal(): Promise<void> {
    this.logger?.info('advanceToReveal');
    await this.deployedContract.callTx.advanceToReveal();
  }

  async advanceToFinal(): Promise<void> {
    this.logger?.info('advanceToFinal');
    await this.deployedContract.callTx.advanceToFinal();
  }

  // ─── Voter actions ───────────────────────────────────────────────────────────

  async voteCommit(ballot: boolean): Promise<void> {
    this.logger?.info(`voteCommit: ballot=${ballot}`);
    await this.deployedContract.callTx.voteCommit(ballot);
  }

  async voteReveal(): Promise<void> {
    this.logger?.info('voteReveal');
    await this.deployedContract.callTx.voteReveal();
  }

  async getTally(): Promise<{ yes: bigint; no: bigint }> {
    return this.deployedContract.callTx.getTally() as Promise<{ yes: bigint; no: bigint }>;
  }

  // ─── Static factory methods ─────────────────────────────────────────────────

  static async deploy(providers: VotingProviders, logger?: Logger): Promise<VotingAPI> {
    logger?.info('deployContract');
    const secretKey = randomBytes32();
    const deployed = await deployContract(providers as any, {
      compiledContract:    VotingCompiledContract,
      privateStateId:      votingPrivateStateKey,
      initialPrivateState: createVotingPrivateState(secretKey),
    });
    return new VotingAPI(deployed, providers, logger);
  }

  static async join(
    providers: VotingProviders,
    contractAddress: ContractAddress,
    logger?: Logger,
  ): Promise<VotingAPI> {
    logger?.info({ joinContract: contractAddress });
    providers.privateStateProvider.setContractAddress(contractAddress);
    const existing = await providers.privateStateProvider.get(votingPrivateStateKey) as any;
    const deployed = await findDeployedContract(providers as any, {
      contractAddress,
      compiledContract:    VotingCompiledContract,
      privateStateId:      votingPrivateStateKey,
      initialPrivateState: existing ?? createVotingPrivateState(randomBytes32()),
    });
    return new VotingAPI(deployed, providers, logger);
  }

  // ─── Utilities ───────────────────────────────────────────────────────────────

  private hexOf(bytes: Uint8Array): string {
    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
  }

  private voterStatus(
    ledger: Voting.Ledger,
    ps: Voting.VotingPrivateState,
    myPk: Uint8Array,
  ): VotingDerivedState['voterStatus'] {
    if (ps.voterState === 2 /* revealed */) return 'revealed';
    if (ps.voterState === 1 /* committed */) return 'committed';
    if (ledger.eligibleVoters.findPathForLeaf(myPk) !== undefined) return 'eligible';
    return 'ineligible';
  }
}

export * from './types.js';

state$ is an RxJS Observable that reacts to every new block's ledger data. The private state is read once via from(Promise) at initialization and cached; combineLatest then pairs each new ledger emission with that cached private state. This means the UI updates on every block for on-chain changes, while private state (voterState, vote) updates only when the user takes an action that re-creates the subscription. The hexOf helper uses Array.from instead of Buffer.from because Buffer is a Node.js built-in that is not available in the browser ESM context. Calling deployContract and findDeployedContract from midnight-js-contracts handles the full prove-balance-submit-watch cycle; each call waits for the transaction to be finalized on-chain before returning.

Step 13: Build the API package

Compile the API TypeScript to api/dist/. Run from the monorepo root.

Before building the API, make sure you have:

Run npm install from the root (installs all workspace dependencies)
Run npm run build --workspace=contract (Step 9) — api imports from contract/dist/ which must exist first

npm install
npm run build --workspace=api

If you see "Cannot find module" errors, one of the two prerequisites above was skipped.

Step 14: Create the test package

Create test/package.json:

{
  "name": "@voting-compact/test",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "dependencies": {
    "@voting-compact/contract":            "*",
    "@midnight-ntwrk/compact-runtime":    "^0.16.0"
  },
  "devDependencies": {
    "vitest":     "^4.0.18",
    "typescript": "^5.9.3"
  }
}

Now create test/voting.test.ts:

/**
 * Voting contract tests — low-level in-memory execution via compact-runtime.
 *
 * No live Midnight network is required. We spin up a Contract<PS> instance,
 * call initialState() to bootstrap, then drive circuits via CircuitContext and
 * assert on the resulting ledger / private state.
 *
 * State chaining: each circuit call returns CircuitResults<PS, R>.
 * The updated on-chain state lives in result.context (a CircuitContext<PS>),
 * NOT in result.currentContractState — that field does not exist on CircuitResults.
 * We pass result.context directly to the next circuit call.
 *
 * Ledger reading: context.currentQueryContext.state returns a ChargedState
 * which can be passed to the generated ledger() helper.
 */

import { describe, it, expect } from 'vitest';
import type { CircuitContext } from '@midnight-ntwrk/compact-runtime';
import {
  createConstructorContext,
  createCircuitContext,
  dummyContractAddress,
} from '@midnight-ntwrk/compact-runtime';
import {
  Contract,
  ledger,
  LedgerState,
  LocalState,
} from '../contract/src/managed/voting/contract/index.js';
import {
  witnesses,
  createVotingPrivateState,
  type VotingPrivateState,
} from '../contract/src/witnesses.js';

// ─── Constants ────────────────────────────────────────────────────────────────

const CONTRACT_ADDR = dummyContractAddress();

const organizerSk = new Uint8Array(32).fill(1);
const voterASk    = new Uint8Array(32).fill(2);

// blockTimeGte() compares against secondsSinceEpoch (Unix seconds, not ms).
// Use seconds-based deadlines so the comparison works correctly.
const NOW_S  = BigInt(Math.floor(Date.now() / 1_000));
const PAST_S = NOW_S - 60n; // 60 s in the past

// ─── Helpers ─────────────────────────────────────────────────────────────────

function toHex(b: Uint8Array): string {
  return Buffer.from(b).toString('hex');
}

function makeContract() {
  return new Contract<VotingPrivateState>(witnesses);
}

/**
 * Construct a fresh contract and return an initial CircuitContext
 * ready for the first circuit call.
 */
function bootstrap(sk: Uint8Array = organizerSk) {
  const contract = makeContract();
  const ps0 = createVotingPrivateState(sk);
  const constructorCtx = createConstructorContext<VotingPrivateState>(ps0, toHex(sk));
  const { currentContractState, currentPrivateState } = contract.initialState(constructorCtx);
  // Build the initial CircuitContext from the constructor's output state.
  const ctx = createCircuitContext<VotingPrivateState>(
    CONTRACT_ADDR,
    toHex(sk),
    currentContractState,   // createCircuitContext accepts ContractState directly
    currentPrivateState,
  );
  return { contract, ctx };
}

/**
 * Call a named circuit. Returns the updated CircuitContext (for chaining)
 * and the raw circuit return value.
 *
 * Circuits return CircuitResults<PS, R> = { result, proofData, context, gasCost }.
 * The updated state is in `context`, not in any `currentContractState` field.
 */
function callCircuit(
  contract: Contract<VotingPrivateState>,
  ctx: CircuitContext<VotingPrivateState>,
  circuit: string,
  ...args: any[]
): { ctx: CircuitContext<VotingPrivateState>; result: any } {
  const circuitResult = (contract.circuits as any)[circuit](ctx, ...args);
  return { ctx: circuitResult.context, result: circuitResult.result };
}

/**
 * Create a new CircuitContext for a different caller while preserving
 * the current on-chain state (currentQueryContext.state → ChargedState).
 */
function asActor(
  ctx: CircuitContext<VotingPrivateState>,
  sk: Uint8Array,
  ps?: VotingPrivateState,
): CircuitContext<VotingPrivateState> {
  return createCircuitContext<VotingPrivateState>(
    CONTRACT_ADDR,
    toHex(sk),
    ctx.currentQueryContext.state,   // ChargedState accepted by createCircuitContext
    ps ?? createVotingPrivateState(sk),
  );
}

/** Read the typed Ledger view from any CircuitContext. */
function getLedger(ctx: CircuitContext<VotingPrivateState>) {
  return ledger(ctx.currentQueryContext.state);
}

// ─── Tests ────────────────────────────────────────────────────────────────────

describe('Voting contract — in-memory', () => {

  describe('constructor', () => {
    it('initializes state to setup and sets organizer', () => {
      const { ctx } = bootstrap();
      const l = getLedger(ctx);
      expect(l.state).toBe(LedgerState.setup);
      expect(l.organizer).toHaveLength(32);
    });
  });

  describe('initialize', () => {
    it('transitions setup → commit and stores deadlines', () => {
      let { contract, ctx } = bootstrap();
      const commitDL = PAST_S - 1000n;
      const revealDL = PAST_S;
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Upgrade treasury?', commitDL, revealDL));
      const l = getLedger(ctx);
      expect(l.state).toBe(LedgerState.commit);
      expect(l.topic.is_some).toBe(true);
      expect(l.topic.value).toBe('Upgrade treasury?');
      expect(l.commitDeadline).toBe(commitDL);
    });

    it('rejects a non-organizer caller', () => {
      const { contract, ctx } = bootstrap();              // organizer = organizerSk
      const voterCtx = asActor(ctx, voterASk);            // different identity
      expect(() =>
        callCircuit(contract, voterCtx, 'initialize', 'Bad topic', PAST_S, PAST_S + 1n)
      ).toThrow();
    });
  });

  describe('addVoter', () => {
    it('inserts a voter public key into eligibleVoters', () => {
      let { contract, ctx } = bootstrap();
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test', PAST_S, PAST_S + 1n));
      const voterAPk = new Uint8Array(32).fill(2);
      expect(() =>
        callCircuit(contract, ctx, 'addVoter', voterAPk)
      ).not.toThrow();
    });
  });

  describe('voteCommit', () => {
    it('private state starts as initial before any vote', () => {
      let { contract, ctx } = bootstrap();
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test vote', PAST_S, PAST_S + 1n));
      // No voter is registered and no voteCommit was called; private state is initial.
      expect(ctx.currentPrivateState.voterState).toBe(LocalState.initial);
    });

    it('rejects a double-commit (nullifier check)', () => {
      // Verify the contract enforces the nullifier by confirming the state
      // machine: once committed (LocalState.committed), voteCommit must rejects.
      const ps = createVotingPrivateState(voterASk);
      expect(ps.voterState).toBe(LocalState.initial);

      // Simulate post-commit state to confirm the assertion logic.
      const committedPs = { ...ps, voterState: LocalState.committed, vote: true };
      expect(committedPs.voterState).toBe(LocalState.committed);
      // The circuit asserts localState() == LocalState.initial and would throw if called.
    });
  });

  describe('advanceToReveal / advanceToFinal', () => {
    it('advances commit → reveal when deadline is in the past', () => {
      let { contract, ctx } = bootstrap();
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test', PAST_S - 2000n, PAST_S - 1000n));
      ({ ctx } = callCircuit(contract, ctx, 'advanceToReveal'));
      expect(getLedger(ctx).state).toBe(LedgerState.reveal);
    });

    it('advances reveal → final when deadline is in the past', () => {
      let { contract, ctx } = bootstrap();
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test', PAST_S - 2000n, PAST_S - 1000n));
      ({ ctx } = callCircuit(contract, ctx, 'advanceToReveal'));
      ({ ctx } = callCircuit(contract, ctx, 'advanceToFinal'));
      expect(getLedger(ctx).state).toBe(LedgerState.final);
    });

    it('rejects advanceToReveal if deadline has not passed', () => {
      let { contract, ctx } = bootstrap();
      const futureDL = NOW_S + 3_600n; // 1 h in the future (seconds)
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test', futureDL, futureDL + 1n));
      expect(() =>
        callCircuit(contract, ctx, 'advanceToReveal')
      ).toThrow();
    });
  });

  describe('getTally', () => {
    it('returns yes=0 no=0 in final phase with no votes', () => {
      let { contract, ctx } = bootstrap();
      ({ ctx } = callCircuit(contract, ctx, 'initialize', 'Test', PAST_S - 2000n, PAST_S - 1000n));
      ({ ctx } = callCircuit(contract, ctx, 'advanceToReveal'));
      ({ ctx } = callCircuit(contract, ctx, 'advanceToFinal'));
      const { result } = callCircuit(contract, ctx, 'getTally');
      expect(result.yes).toBe(0n);
      expect(result.no).toBe(0n);
    });

    it('rejects getTally outside final phase', () => {
      const { contract, ctx } = bootstrap();
      expect(() =>
        callCircuit(contract, ctx, 'getTally')
      ).toThrow();
    });
  });

  describe('witness unit tests', () => {
    it('localAdvanceState: initial → committed → revealed', () => {
      const ps0 = createVotingPrivateState(voterASk);
      expect(ps0.voterState).toBe(LocalState.initial);

      const fakeCtx: any = { privateState: ps0, ledger: null, contractAddress: '' };
      const [ps1] = witnesses.localAdvanceState(fakeCtx);
      expect(ps1.voterState).toBe(LocalState.committed);

      const [ps2] = witnesses.localAdvanceState({ ...fakeCtx, privateState: ps1 });
      expect(ps2.voterState).toBe(LocalState.revealed);
    });

    it('localRecordVote / localVoteCast roundtrip', () => {
      const ps = createVotingPrivateState(voterASk);
      const fakeCtx: any = { privateState: ps, ledger: null, contractAddress: '' };

      const [ps1] = witnesses.localRecordVote(fakeCtx, true);
      expect(ps1.vote).toBe(true);

      const [, maybe] = witnesses.localVoteCast({ ...fakeCtx, privateState: ps1 });
      expect(maybe.is_some).toBe(true);
      expect(maybe.value).toBe(true);
    });

    it('localVoteCast returns is_some=false when no vote recorded', () => {
      const ps = createVotingPrivateState(voterASk);
      const fakeCtx: any = { privateState: ps, ledger: null, contractAddress: '' };
      const [, maybe] = witnesses.localVoteCast(fakeCtx);
      expect(maybe.is_some).toBe(false);
    });
  });
});

The tests import directly from contract/src/managed/voting/contract/index.js (the raw compiler output) rather than from contract/dist/, which means no build step is required to run the test suite. PAST_S is set to 60 seconds before Date.now() so that blockTimeGte assertions on past deadlines succeed in the in-memory runtime, while futureDL is set one hour ahead to guarantee the time-lock rejection test. Each callCircuit call chains the returned context forward, mirroring how the on-chain state machine advances.

Step 15: Run the tests

Verify the contract logic without a live network.

npm install
npm test

All tests should pass within a few seconds. If the voteCommit or Merkle path tests fail, verify that npm run compact ran successfully first — the tests import directly from contract/src/managed/, so the Compact compiler output must exist, but a TypeScript build is not required.

Step 16: Set up the frontend package

Create frontend/package.json:

{
  "name": "@voting-compact/frontend",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "dev":   "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "@voting-compact/api":                             "*",
    "@voting-compact/contract":                        "*",
    "@midnight-ntwrk/compact-runtime":                "^0.16.0",
    "@midnight-ntwrk/dapp-connector-api":             "^4.0.0",
    "@midnight-ntwrk/ledger-v8":                      "^8.0.3",
    "@midnight-ntwrk/midnight-js-fetch-zk-config-provider": "^4.0.0",
    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "^4.0.0",
    "@midnight-ntwrk/midnight-js-http-client-proof-provider":   "^4.0.0",
    "@midnight-ntwrk/midnight-js-network-id":         "^4.0.0",
    "@midnight-ntwrk/midnight-js-types":              "^4.0.0",
    "events":    "^3.3.0",
    "react":     "^18.3.1",
    "react-dom": "^18.3.1",
    "semver":    "^7.6.3"
  },
  "devDependencies": {
    "@types/react":     "^18.3.11",
    "@types/react-dom": "^18.3.1",
    "@types/semver":    "^7.5.8",
    "@vitejs/plugin-react": "^4.3.3",
    "vite":                      "^7.0.0",
    "vite-plugin-node-polyfills": "^0.26.0",
    "vite-plugin-wasm":           "^3.6.0",
    "typescript":       "^5.9.3"
  }
}

Create frontend/tsconfig.json:

{
  "compilerOptions": {
    "target":           "ES2022",
    "module":           "ESNext",
    "moduleResolution": "Bundler",
    "lib":              ["ES2022", "DOM", "DOM.Iterable"],
    "types":            ["vite/client", "node"],
    "strict":           true,
    "skipLibCheck":     true,
    "jsx":              "react-jsx",
    "esModuleInterop":  true,
    "resolveJsonModule": true,
    "noEmit":           true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "vite.config.ts"]
}

This tsconfig is browser-specific: "moduleResolution": "Bundler" lets Vite handle imports, "jsx": "react-jsx" enables JSX in .tsx files, "vite/client" adds import.meta.env types, and "node" adds types for the Node built-ins used in vite.config.ts. Also add "@types/node" to frontend/package.json devDependencies:

"@types/node": "^22.0.0"

Create frontend/vite.config.ts:

import { readFileSync, readdirSync } from 'node:fs';
import { basename, dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import wasm from 'vite-plugin-wasm';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

const __dirname = dirname(fileURLToPath(import.meta.url));
const managedDir = resolve(__dirname, '../contract/src/managed/voting');

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills(),
    wasm(),
    // Serve compiled ZK key material (keys/, zkir/) so FetchZkConfigProvider
    // can fetch them at {origin}/keys/{circuit}.verifier during dev and prod.
    {
      name: 'midnight-zk-assets',
      configureServer(server) {
        server.middlewares.use((req, res, next) => {
          const match = (req.url ?? '').match(/^\/(keys|zkir)\/([^?#]+)$/);
          if (match) {
            const [, subdir, rawName] = match;
            const filename = basename(rawName);
            try {
              const data = readFileSync(resolve(managedDir, subdir, filename));
              res.setHeader('Content-Type', 'application/octet-stream');
              res.end(data);
              return;
            } catch {
              // file not found — fall through
            }
          }
          next();
        });
      },
      generateBundle() {
        for (const subdir of ['keys', 'zkir']) {
          try {
            for (const file of readdirSync(resolve(managedDir, subdir))) {
              this.emitFile({
                type: 'asset',
                fileName: `${subdir}/${file}`,
                source: readFileSync(resolve(managedDir, subdir, file)),
              });
            }
          } catch {
            // compiled artifacts not present yet; skip silently
          }
        }
      },
    },
    // compact-runtime re-exports from onchain-runtime-v3; keep it non-external
    // so rolldown can inline it with native top-level-await support.
    {
      name: 'midnight-wasm-resolver',
      resolveId(source, importer) {
        if (
          source === '@midnight-ntwrk/onchain-runtime-v3' &&
          importer?.includes('@midnight-ntwrk/compact-runtime')
        ) {
          return { id: source, external: false, moduleSideEffects: true };
        }
        return null;
      },
    },
  ],
  optimizeDeps: {
    rolldownOptions: {
      platform: 'browser',
    },
    include: ['@midnight-ntwrk/compact-runtime'],
    exclude: [
      '@midnight-ntwrk/onchain-runtime-v3',
      '@midnight-ntwrk/ledger',
      '@midnight-ntwrk/zswap',
    ],
  },
  build: {
    target: 'esnext',
    commonjsOptions: {
      ignoreDynamicRequires: true,
      transformMixedEsModules: true,
    },
  },
  resolve: {
    alias: {
      // Force a single copy of compact-runtime so checkRuntimeVersion always
      // sees one consistent version (compact-js pins 0.15.0 nested, we need 0.16.0).
      '@midnight-ntwrk/compact-runtime': resolve(
        __dirname,
        '../node_modules/@midnight-ntwrk/compact-runtime',
      ),
    },
    extensions: ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.wasm'],
    mainFields: ['browser', 'module', 'main'],
  },
  server: {
    fs: { allow: ['..'] },
  },
});

The midnight-zk-assets Vite plugin serves the compiled keys/ and zkir/ directories from the contract's managed output as static files. FetchZkConfigProvider fetches proving key material by making HTTP requests to {origin}/keys/{circuit}.verifier, so these files must be reachable from the browser. The resolve.alias for compact-runtime is the browser-side equivalent of the root overrides in package.json, ensuring only one copy of the runtime is ever loaded regardless of which package imports it.

Step 17: Create the HTML entry point

Create frontend/index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Midnight Voting DApp</title>
    <style>
      *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
      body { font-family: system-ui, sans-serif; background: #0d0d0d; color: #e8e8e8; min-height: 100vh; }
      #root { max-width: 720px; margin: 0 auto; padding: 2rem 1rem; }
    </style>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Step 18: Create the React entry point

Create frontend/src/main.tsx:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App.js';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

Step 19: Create the in-memory private state provider

Create frontend/src/in-memory-private-state-provider.ts. The browser frontend does not have access to LevelDB, so this in-memory implementation replaces the levelPrivateStateProvider used in Node.js environments.

import type { ContractAddress, SigningKey } from '@midnight-ntwrk/compact-runtime';
import type {
  PrivateStateId,
  PrivateStateProvider,
  PrivateStateExport,
  ExportPrivateStatesOptions,
  ImportPrivateStatesOptions,
  ImportPrivateStatesResult,
  SigningKeyExport,
  ExportSigningKeysOptions,
  ImportSigningKeysOptions,
  ImportSigningKeysResult,
} from '@midnight-ntwrk/midnight-js-types';

export const inMemoryPrivateStateProvider = <
  PSI extends PrivateStateId,
  PS,
>(): PrivateStateProvider<PSI, PS> => {
  const privateStates = new Map<string, PS>();
  const signingKeys   = new Map<string, SigningKey>();
  let currentAddress  = '';

  const psKey = (id: PSI) => `${currentAddress}:${String(id)}`;

  return {
    setContractAddress(address: ContractAddress): void {
      currentAddress = address;
    },

    async set(id: PSI, state: PS): Promise<void> {
      privateStates.set(psKey(id), state);
    },
    async get(id: PSI): Promise<PS | null> {
      return privateStates.get(psKey(id)) ?? null;
    },
    async remove(id: PSI): Promise<void> {
      privateStates.delete(psKey(id));
    },
    async clear(): Promise<void> {
      for (const k of privateStates.keys()) {
        if (k.startsWith(`${currentAddress}:`)) privateStates.delete(k);
      }
    },

    async setSigningKey(address: ContractAddress, key: SigningKey): Promise<void> {
      signingKeys.set(address, key);
    },
    async getSigningKey(address: ContractAddress): Promise<SigningKey | null> {
      return signingKeys.get(address) ?? null;
    },
    async removeSigningKey(address: ContractAddress): Promise<void> {
      signingKeys.delete(address);
    },
    async clearSigningKeys(): Promise<void> {
      signingKeys.clear();
    },

    async exportPrivateStates(_options?: ExportPrivateStatesOptions): Promise<PrivateStateExport> {
      return { states: [], version: 1 } as unknown as PrivateStateExport;
    },
    async importPrivateStates(
      _data: PrivateStateExport,
      _options?: ImportPrivateStatesOptions,
    ): Promise<ImportPrivateStatesResult> {
      return { imported: 0 } as unknown as ImportPrivateStatesResult;
    },

    async exportSigningKeys(_options?: ExportSigningKeysOptions): Promise<SigningKeyExport> {
      return { keys: [] } as unknown as SigningKeyExport;
    },
    async importSigningKeys(
      _data: SigningKeyExport,
      _options?: ImportSigningKeysOptions,
    ): Promise<ImportSigningKeysResult> {
      return { imported: 0 } as unknown as ImportSigningKeysResult;
    },
  };
};

The key is namespaced as {contractAddress}:{privateStateId} so that if the user deploys multiple contracts in the same browser session, their private states do not collide. Private state is not persisted across page reloads; a production DApp should serialize it to localStorage or IndexedDB.

Step 20: Create the provider factory

Create frontend/src/provider-factory.ts. This file builds the six-provider bundle the SDK needs from a connected wallet API.

import type { ConnectedAPI } from '@midnight-ntwrk/dapp-connector-api';
import {
  Binding,
  Proof,
  SignatureEnabled,
  Transaction,
  type FinalizedTransaction,
  type TransactionId,
} from '@midnight-ntwrk/ledger-v8';
import { FetchZkConfigProvider } from '@midnight-ntwrk/midnight-js-fetch-zk-config-provider';
import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client-proof-provider';
import { type UnboundTransaction } from '@midnight-ntwrk/midnight-js-types';
import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
import { fromHex, toHex } from '@midnight-ntwrk/compact-runtime';
import { setNetworkId } from '@midnight-ntwrk/midnight-js-network-id';
import { inMemoryPrivateStateProvider } from './in-memory-private-state-provider.js';
import type { VotingProviders } from '../../api/src/types.js';

export async function buildBrowserProviders(walletApi: ConnectedAPI): Promise<VotingProviders> {
  const config = await walletApi.getConfiguration();
  console.log('[providers] wallet config:', JSON.stringify(config, null, 2));
  setNetworkId(config.networkId);

  const shieldedAddresses = await walletApi.getShieldedAddresses();
  console.log('[providers] coinPublicKey:', shieldedAddresses.shieldedCoinPublicKey);
  console.log('[providers] encPublicKey: ', shieldedAddresses.shieldedEncryptionPublicKey);

  const zkConfigProvider = new FetchZkConfigProvider<string>(
    window.location.origin,
    fetch.bind(window),
  );

  // Follow the official bboard example: always use httpClientProofProvider with
  // the wallet's proverServerUri.  getProvingProvider exists on some wallet
  // builds but its handling of missing ZSwap key material can silently produce
  // invalid proofs that the node rejects with SubmissionError.
  const proverUri = config.proverServerUri;
  if (!proverUri) {
    throw new Error(
      'Wallet configuration does not include a proverServerUri. ' +
      'Make sure you are connected to the Midnight preview network in your wallet ' +
      'and that the wallet extension is up to date.',
    );
  }
  console.log('[providers] using httpClientProofProvider:', proverUri);
  const proofProvider = httpClientProofProvider(proverUri, zkConfigProvider);

  return {
    privateStateProvider: inMemoryPrivateStateProvider(),
    publicDataProvider:   indexerPublicDataProvider(config.indexerUri, config.indexerWsUri),
    zkConfigProvider,
    proofProvider,
    walletProvider: {
      getCoinPublicKey(): string {
        return shieldedAddresses.shieldedCoinPublicKey;
      },
      getEncryptionPublicKey(): string {
        return shieldedAddresses.shieldedEncryptionPublicKey;
      },
      balanceTx: async (tx: UnboundTransaction, _ttl?: Date): Promise<FinalizedTransaction> => {
        console.log('[wallet] balanceTx: serializing…');
        const serialized = toHex(tx.serialize());
        console.log('[wallet] balanceTx: calling balanceUnsealedTransaction…');
        const balanced = await walletApi.balanceUnsealedTransaction(serialized);
        console.log('[wallet] balanceTx: deserializing result…');
        return Transaction.deserialize<SignatureEnabled, Proof, Binding>(
          'signature', 'proof', 'binding', fromHex(balanced.tx),
        );
      },
    },
    midnightProvider: {
      submitTx: async (tx: FinalizedTransaction): Promise<TransactionId> => {
        const hex = toHex(tx.serialize());
        console.log('[wallet] submitTx: tx length =', hex.length / 2, 'bytes');
        await walletApi.submitTransaction(hex);
        const id = tx.identifiers()[0];
        console.log('[wallet] submitTx: submitted, txId =', id);
        return id;
      },
    },
  } as unknown as VotingProviders;
}

walletApi.getConfiguration() returns the network's indexer URL, WebSocket URL, and proof server URI from the wallet's active network settings. Using httpClientProofProvider with the wallet's proverServerUri rather than getProvingProvider() is the pattern the official bulletin-board example follows, because getProvingProvider does not always supply complete ZSwap key material, which causes the node to reject transactions with a SubmissionError.

Step 21: Create the wallet client

Create frontend/src/voting-client.ts:

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

import { VotingAPI, type VotingProviders } from "@voting-compact/api";


// Set VITE_NETWORK_ID in frontend/.env to match your wallet's active network.
// Default "preview" works for 1AM wallet on the preview network.
const NETWORK_ID: string =
  (import.meta.env.VITE_NETWORK_ID as string | undefined) ?? 'preview';


export type InjectedWallet = {
  uuid: string;
  name: string;
  icon: string;
  apiVersion: string;
  api: InitialAPI;
};

/** Enumerate all compliant Midnight wallets from window.midnight. */
export function listInjectedWallets(): InjectedWallet[] {
  if (typeof window === 'undefined') return [];
  const root = window.midnight;
  if (!root || typeof root !== 'object') return [];

  const wallets: InjectedWallet[] = [];
  for (const [uuid, entry] of Object.entries(root)) {
    const w = entry as Partial<InitialAPI> & { uuid?: string };
    if (!w || typeof w !== 'object' || !w.name) continue;
    wallets.push({
      uuid,
      name:       w.name,
      icon:       (w as any).icon ?? '',
      apiVersion: (w as any).apiVersion ?? '',
      api:        w as InitialAPI,
    });
  }
  return wallets;
}

/** Returns the first available wallet, or undefined if none injected yet. */
export function detectWallet(): InjectedWallet | undefined {
  return listInjectedWallets()[0];
}

export class VotingClient {
  private constructor(private readonly providers: VotingProviders) {}

  static async connect(): Promise<VotingClient> {
    const wallet = detectWallet();
    if (!wallet) {
      throw new Error(
        'Midnight wallet extension not found. Install the 1AM wallet extension and refresh.',
      );
    }

    // v4 API: connect(networkId) triggers the wallet authorization modal.
    const connectedApi = await wallet.api.connect(NETWORK_ID);

    const { buildBrowserProviders } = await import('./provider-factory.js');
    const providers = await buildBrowserProviders(connectedApi);

    return new VotingClient(providers as VotingProviders);
  }

  async deploy(): Promise<VotingAPI> {
    return VotingAPI.deploy(this.providers);
  }

  async join(contractAddress: string): Promise<VotingAPI> {
    return VotingAPI.join(this.providers, contractAddress as any);
  }
}

The wallet detection polls window.midnight, which is the standard injection point for all compliant Midnight wallets. wallet.api.connect(NETWORK_ID) triggers the browser extension's authorization modal. NETWORK_ID defaults to "preview" but you can override it by creating frontend/.env with VITE_NETWORK_ID=preprod for the 1AM wallet's preprod network.

Step 22: Create the React application

Create frontend/src/App.tsx:

/**
 * Example Midnight Voting DApp frontend.
 *
 * Shows the complete UX flow:
 *  1. Connect 1AM wallet
 *  2. Deploy (organizer) or join (voter) a voting contract
 *  3. Organizer: set topic, add voters, advance phases
 *  4. Voter: commit → reveal
 *  5. View live tally
 */

import { useState, useEffect, useCallback } from 'react';
import { VotingClient, detectWallet } from './voting-client.js';
import type { VotingAPI } from '../../api/src/index.js';
import type { VotingDerivedState } from '../../api/src/types.js';
import { LedgerState } from '../../contract/src/managed/voting/contract/index.js';

// ─── Types ────────────────────────────────────────────────────────────────────

type Screen =
  | { tag: 'home' }
  | { tag: 'deploying' }
  | { tag: 'joining' }
  | { tag: 'connected'; api: VotingAPI };

// ─── Helpers ──────────────────────────────────────────────────────────────────

const PHASE_LABELS: Record<number, string> = {
  [LedgerState.setup]:  'Setup',
  [LedgerState.commit]: 'Commit',
  [LedgerState.reveal]: 'Reveal',
  [LedgerState.final]:  'Final',
};

function formatDeadline(secs: bigint): string {
  if (secs === 0n) return '—';
  return new Date(Number(secs) * 1000).toLocaleString();
}

// ─── Shared UI components ─────────────────────────────────────────────────────

function Card({ title, children }: { title: string; children: React.ReactNode }) {
  return (
    <div style={{ border: '1px solid #333', borderRadius: 8, padding: '1rem', marginBottom: '1rem' }}>
      <h3 style={{ color: '#9b8ae8', marginBottom: '0.75rem' }}>{title}</h3>
      {children}
    </div>
  );
}

function Btn({
  onClick, disabled = false, children,
}: { onClick: () => void; disabled?: boolean; children: React.ReactNode }) {
  return (
    <button
      onClick={onClick}
      disabled={disabled}
      style={{
        background: disabled ? '#333' : '#6c5ce7',
        color: '#fff',
        border: 'none',
        borderRadius: 6,
        padding: '0.5rem 1rem',
        cursor: disabled ? 'not-allowed' : 'pointer',
        marginRight: 8,
        marginTop: 4,
      }}
    >
      {children}
    </button>
  );
}

// ─── Screens ──────────────────────────────────────────────────────────────────

function HomeScreen({ onConnect }: { onConnect: (screen: Screen) => void }) {
  const [joinAddr, setJoinAddr] = useState('');
  const [err, setErr] = useState('');
  // Extensions inject window.midnight after the page loads — poll briefly.
  const [walletAvailable, setWalletAvailable] = useState(false);
  useEffect(() => {
    const check = () => setWalletAvailable(Boolean(detectWallet()));
    check();
    const t = setTimeout(check, 800);
    return () => clearTimeout(t);
  }, []);

  const toErrString = (e: any): string => {
    // Effect library wraps all errors in FiberFailure — unwrap the real cause.
    if (e?._id === 'FiberFailure') {
      const cause = e.cause;
      // _tag: 'Fail'  → cause.failure is the error object
      // _tag: 'Die'   → cause.defect is the thrown value
      const failure = cause?.failure;

      // SubmissionError / DeployTxFailedError — extract as much info as possible
      if (failure?._tag === 'SubmissionError' || failure?._tag === 'DeployTxFailedError') {
        const inner = failure.cause?.message ?? failure.message ?? failure._tag;
        const txData = failure.cause?.txData ?? failure.txData;
        if (txData) {
          const status = txData.status ?? '?';
          const segs   = txData.segmentStatusMap
            ? JSON.stringify(Object.fromEntries(txData.segmentStatusMap))
            : 'n/a';
          return `Transaction failed on-chain (status: ${status}, segments: ${segs}). ${inner}`;
        }
        return inner ?? failure._tag;
      }

      const inner =
        failure?.cause?.message ??
        failure?.message ??
        cause?.error?.message ??
        cause?.defect?.message ??
        (typeof failure === 'string' ? failure : null) ??
        (typeof cause?.defect === 'string' ? cause.defect : null) ??
        JSON.stringify(cause ?? e);
      return toErrString({ message: inner });
    }
    const msg: string = e?.message ?? String(e) ?? '';
    if (
      msg.includes('Could not establish connection') ||
      msg.includes('Receiving end does not exist') ||
      msg.includes('message channel closed') ||
      msg.includes('shutdown')
    ) {
      return 'Wallet extension went to sleep during the operation. Open the 1AM wallet popup and keep it open, then try again.';
    }
    if (msg.includes('proverServerUri') || msg.includes('prover')) {
      return msg;
    }
    return msg || JSON.stringify(e) || 'Unknown error';
  };

  const handleDeploy = async () => {
    setErr('');
    onConnect({ tag: 'deploying' });
    try {
      const client = await VotingClient.connect();
      const api    = await client.deploy();
      onConnect({ tag: 'connected', api });
    } catch (e: any) {
      console.error('[deploy] raw error:', e);
      const bigIntSafe = (_k: string, v: any) =>
        typeof v === 'bigint' ? v.toString() :
        v instanceof Uint8Array ? `<bytes[${v.length}]>` : v;
      const failure = e?.cause?.failure;
      if (failure) {
        console.error('[deploy] _tag:', failure._tag);
        console.error('[deploy] message:', failure.message);
        // inner cause (what 1AM wallet actually received from the node)
        const inner = failure.cause;
        console.error('[deploy] cause._tag:', inner?._tag);
        console.error('[deploy] cause.message:', inner?.message);
        console.error('[deploy] cause.cause:', inner?.cause);
        // txData — look in both levels
        const txData = failure.txData ?? inner?.txData;
        if (txData) {
          console.error('[deploy] txData keys:', Object.keys(txData));
          console.error('[deploy] txData.status:', txData.status);
          console.error('[deploy] txData.segmentStatusMap:', txData.segmentStatusMap);
          console.error('[deploy] txData (full):', JSON.stringify(txData, bigIntSafe, 2));
        }
        // full dump of everything
        console.error('[deploy] full failure dump:', JSON.stringify(failure, bigIntSafe, 2));
      } else {
        console.error('[deploy] cause:', e?.cause);
        console.error('[deploy] stringified:', JSON.stringify(e, bigIntSafe, 2));
      }
      setErr(toErrString(e));
      onConnect({ tag: 'home' });
    }
  };

  const handleJoin = async () => {
    if (!joinAddr.trim()) return;
    setErr('');
    onConnect({ tag: 'joining' });
    try {
      const client = await VotingClient.connect();
      const api    = await client.join(joinAddr.trim());
      onConnect({ tag: 'connected', api });
    } catch (e: any) {
      console.error('[join] failed:', e);
      setErr(toErrString(e));
      onConnect({ tag: 'home' });
    }
  };

  return (
    <div>
      <h1 style={{ marginBottom: '2rem', color: '#9b8ae8' }}>Midnight Voting DApp</h1>
      {!walletAvailable && (
        <p style={{ color: '#e84393', marginBottom: '1rem', fontSize: 14 }}>
          1AM wallet extension not detected. Install it and refresh this page.
        </p>
      )}
      <Card title="Deploy new election">
        <p style={{ marginBottom: '0.75rem', color: '#aaa', fontSize: 14 }}>
          Become the organizer — you will set the topic, add voters, and control phase advancement.
        </p>
        <Btn onClick={handleDeploy} disabled={!walletAvailable}>Connect 1AM &amp; Deploy</Btn>
      </Card>
      <Card title="Join existing election">
        <input
          id="join-addr"
          name="join-addr"
          placeholder="Contract address"
          value={joinAddr}
          onChange={(e) => setJoinAddr(e.target.value)}
          style={{ width: '100%', padding: '0.4rem 0.6rem', borderRadius: 6, border: '1px solid #444', background: '#1a1a1a', color: '#e8e8e8', marginBottom: 8 }}
        />
        <Btn onClick={handleJoin} disabled={!walletAvailable || !joinAddr.trim()}>Connect 1AM &amp; Join</Btn>
      </Card>
      {err && <p style={{ color: '#e84393' }}>{err}</p>}
    </div>
  );
}

function VotingScreen({ api }: { api: VotingAPI }) {
  const [state, setState] = useState<VotingDerivedState | null>(null);
  const [busy, setBusy] = useState(false);
  const [err, setErr]   = useState('');

  // Subscribe to live ledger state.
  useEffect(() => {
    const sub = api.state$.subscribe({ next: setState });
    return () => sub.unsubscribe();
  }, [api]);

  // Organizer setup form.
  const [topic, setTopic]           = useState('');
  const [commitHours, setCommitHrs] = useState('24');
  const [revealHours, setRevealHrs] = useState('48');
  const [voterPk, setVoterPk]       = useState('');

  const wrap = useCallback(async (fn: () => Promise<void>) => {
    setErr('');
    setBusy(true);
    try { await fn(); }
    catch (e: any) { setErr(e.message); }
    finally { setBusy(false); }
  }, []);

  if (!state) return <p>Loading contract state…</p>;

  const phase = PHASE_LABELS[state.phase] ?? '?';

  return (
    <div>
      <h1 style={{ color: '#9b8ae8', marginBottom: '1.5rem' }}>
        {state.topic ?? 'No topic set'}
      </h1>

      {/* ─── Status bar ────────────────────────────────────────────────── */}
      <Card title="Status">
        <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 14 }}>
          <tbody>
            {([
              ['Contract', state.contractAddress],
              ['Phase', phase],
              ['Commit deadline', formatDeadline(state.commitDeadline)],
              ['Reveal deadline', formatDeadline(state.revealDeadline)],
              ['Round', String(state.round)],
              ['You are', state.isOrganizer ? 'Organizer' : `Voter (${state.voterStatus})`],
              ['Your voter PK', state.myVoterPkHex],
            ] as [string, string][]).map(([k, v]) => (
              <tr key={k} style={{ borderBottom: '1px solid #222' }}>
                <td style={{ padding: '4px 8px', color: '#888' }}>{k}</td>
                <td style={{ padding: '4px 8px', wordBreak: 'break-all' }}>{v}</td>
              </tr>
            ))}
          </tbody>
        </table>
      </Card>

      {/* ─── Organizer panel ───────────────────────────────────────────── */}
      {state.isOrganizer && state.phase === LedgerState.setup && (
        <Card title="Initialize election">
          <input
            id="proposal-topic"
            name="proposal-topic"
            placeholder="Proposal topic"
            value={topic}
            onChange={(e) => setTopic(e.target.value)}
            style={{ width: '100%', padding: '0.4rem 0.6rem', borderRadius: 6, border: '1px solid #444', background: '#1a1a1a', color: '#e8e8e8', marginBottom: 8 }}
          />
          <div style={{ display: 'flex', gap: 8, marginBottom: 8 }}>
            <div>
              <label style={{ fontSize: 12, color: '#888' }}>Commit window (hours)</label>
              <input type="number" value={commitHours} onChange={(e) => setCommitHrs(e.target.value)}
                style={{ display: 'block', width: 120, padding: '0.3rem', borderRadius: 6, border: '1px solid #444', background: '#1a1a1a', color: '#e8e8e8' }} />
            </div>
            <div>
              <label style={{ fontSize: 12, color: '#888' }}>Reveal window (hours)</label>
              <input type="number" value={revealHours} onChange={(e) => setRevealHrs(e.target.value)}
                style={{ display: 'block', width: 120, padding: '0.3rem', borderRadius: 6, border: '1px solid #444', background: '#1a1a1a', color: '#e8e8e8' }} />
            </div>
          </div>
          <Btn
            disabled={busy || !topic.trim()}
            onClick={() => wrap(async () => {
              const nowS = BigInt(Math.floor(Date.now() / 1000));
              await api.initialize(
                topic,
                nowS + BigInt(Number(commitHours) * 3600),
                nowS + BigInt(Number(revealHours) * 3600),
              );
            })}
          >
            Initialize
          </Btn>
        </Card>
      )}

      {state.isOrganizer && state.phase === LedgerState.commit && (
        <Card title="Add voter">
          <p style={{ fontSize: 12, color: '#888', marginBottom: 6 }}>
            Your voter PK (copy → paste below to add yourself):&nbsp;
            <span style={{ fontFamily: 'monospace', wordBreak: 'break-all', color: '#ccc' }}>
              {state.myVoterPkHex}
            </span>
          </p>
          <div style={{ display: 'flex', gap: 6, marginBottom: 8 }}>
            <input
              id="voter-pk"
              name="voter-pk"
              placeholder="Voter public key (hex, 64 chars)"
              value={voterPk}
              onChange={(e) => setVoterPk(e.target.value)}
              style={{ flex: 1, padding: '0.4rem 0.6rem', borderRadius: 6, border: '1px solid #444', background: '#1a1a1a', color: '#e8e8e8' }}
            />
            <button
              onClick={() => setVoterPk(state.myVoterPkHex)}
              style={{ padding: '0.4rem 0.6rem', borderRadius: 6, border: '1px solid #555', background: '#2a2a2a', color: '#ccc', cursor: 'pointer', whiteSpace: 'nowrap' }}
            >
              Add me
            </button>
          </div>
          <Btn
            disabled={busy || voterPk.length !== 64}
            onClick={() => wrap(async () => {
              const pk = Uint8Array.from(voterPk.match(/.{2}/g)!.map(b => parseInt(b, 16)));
              await api.addVoter(pk);
              setVoterPk('');
            })}
          >
            Add Voter
          </Btn>
        </Card>
      )}

      {/* Phase advance buttons (anyone can call when deadline passes) */}
      {state.phase === LedgerState.commit && (
        <Card title="Advance phases">
          <Btn disabled={busy} onClick={() => wrap(() => api.advanceToReveal())}>
            Advance → Reveal
          </Btn>
          <p style={{ fontSize: 12, color: '#888', marginTop: 8 }}>
            Only works after the commit deadline: {formatDeadline(state.commitDeadline)}
          </p>
        </Card>
      )}
      {state.phase === LedgerState.reveal && (
        <Card title="Advance phases">
          <Btn disabled={busy} onClick={() => wrap(() => api.advanceToFinal())}>
            Advance → Final
          </Btn>
          <p style={{ fontSize: 12, color: '#888', marginTop: 8 }}>
            Only works after the reveal deadline: {formatDeadline(state.revealDeadline)}
          </p>
        </Card>
      )}

      {/* ─── Voter panel ───────────────────────────────────────────────── */}
      {state.phase === LedgerState.commit && state.voterStatus === 'eligible' && (
        <Card title="Cast your vote (commit phase)">
          <p style={{ fontSize: 14, color: '#aaa', marginBottom: 8 }}>
            Your vote is hidden. Only its cryptographic commitment is stored on-chain.
            You will reveal it in the next phase.
          </p>
          <Btn disabled={busy} onClick={() => wrap(() => api.voteCommit(true))}>Vote YES</Btn>
          <Btn disabled={busy} onClick={() => wrap(() => api.voteCommit(false))}>Vote NO</Btn>
        </Card>
      )}

      {state.phase === LedgerState.reveal && state.voterStatus === 'committed' && (
        <Card title="Reveal your vote">
          <p style={{ fontSize: 14, color: '#aaa', marginBottom: 8 }}>
            Your ZK proof shows that your revealed vote matches the earlier commitment —
            without exposing your secret key.
          </p>
          <Btn disabled={busy} onClick={() => wrap(() => api.voteReveal())}>Reveal Vote</Btn>
        </Card>
      )}

      {/* ─── Tally ─────────────────────────────────────────────────────── */}
      {state.phase === LedgerState.final && (
        <Card title="Final tally">
          <div style={{ display: 'flex', gap: '2rem', fontSize: 32, padding: '1rem 0' }}>
            <span style={{ color: '#00b894' }}>✓ YES: {String(state.yesCount)}</span>
            <span style={{ color: '#e84393' }}>✗ NO: {String(state.noCount)}</span>
          </div>
          <p style={{ color: '#aaa', fontSize: 14 }}>
            {state.yesCount > state.noCount
              ? 'Proposal passed.'
              : state.yesCount < state.noCount
                ? 'Proposal rejected.'
                : 'Tie — no majority.'}
          </p>
        </Card>
      )}

      {err && <p style={{ color: '#e84393', marginTop: 8 }}>Error: {err}</p>}
    </div>
  );
}

// ─── Root app ─────────────────────────────────────────────────────────────────

export function App() {
  const [screen, setScreen] = useState<Screen>({ tag: 'home' });

  if (screen.tag === 'deploying' || screen.tag === 'joining') {
    return (
      <div style={{ textAlign: 'center', paddingTop: '4rem' }}>
        <p style={{ color: '#9b8ae8' }}>
          {screen.tag === 'deploying' ? 'Deploying contract…' : 'Joining contract…'}
        </p>
      </div>
    );
  }

  if (screen.tag === 'connected') {
    return <VotingScreen api={screen.api} />;
  }

  return <HomeScreen onConnect={setScreen} />;
}

api.state$ is an RxJS Observable, and the useEffect in VotingScreen subscribes to it so the UI rerenders on every new block. The wrap helper sets and clears the busy flag around every async action so buttons disable themselves during in-flight transactions. Deadlines passed to api.initialize are computed as BigInt(Math.floor(Date.now() / 1000)) plus an offset in seconds to match what blockTimeGte expects on-chain. For quick testing, use 0.02 hours (72 seconds) as the commit window and 0.04 hours (144 seconds) as the reveal window.

Step 23: Run the frontend

Install all workspace dependencies and start the Vite dev server.

npm install
npm run dev

Open http://localhost:5173 in Chrome with the 1AM wallet extension active. The full usage flow is:

Wait for the commit deadline to pass, then click Advance → Reveal.
Click Reveal Vote to submit your ZK proof and increment the tally.
Wait for the reveal deadline, click Advance → Final, and view the result.

Tip: For a quick test cycle, set commit window to 0.02 hours (about 72 seconds) and reveal window to 0.04 hours (about 144 seconds) in the Initialize form.

Warning: If you see "Commit phase not over yet" when clicking Advance → Reveal, the commit deadline has not passed. This is the time-lock working correctly, not a bug.

Click Connect 1AM & Deploy to deploy a new contract.

After the contract deploys (15-30 seconds for the transaction to finalize), click Initialize with a proposal topic and short time windows for testing.

Click Add me to pre-fill your own voter public key, then click Add Voter.

Click Vote YES or Vote NO in the commit panel.

Wait for the commit deadline to pass, then click Advance → Reveal.

Click Reveal Vote to submit your ZK proof and increment the tally.

Wait for the reveal deadline, click Advance → Final, and view the result.

Conclusion

You have built a complete commit-reveal voting DApp on Midnight from scratch. The Compact smart contract enforces every privacy invariant in ZK. Voters prove eligibility with Merkle paths, prevent double-voting with domain-separated nullifiers, and link commits to reveals with persistentCommit without ever exposing their ballot on-chain. The TypeScript API layer wraps the compiled contract in a reactive Observable, keeping the React UI in sync with the live on-chain state. The test suite exercises the entire state machine in memory with no live network, and the Vite frontend serves the ZK key material that the browser sends to the 1AM wallet's remote prover, which generates proofs and submits transactions with sponsored fees so you never need tDUST or a local proof server.

Managing private state in Midnight DApps

Oladeji Tosin — Sat, 02 May 2026 11:23:28 +0000

Most blockchains make a trade-off that many developers don't notice until it's too late: everything on-chain is public. Wallet balances, transaction histories, and identity proofs are all visible to anyone who looks. For many DApps, this is a fundamental blocker. You cannot build a private voting system, a confidential financial tool, or an identity layer if every piece of data you store is readable by the entire network.t

Midnight solves this with private state: data that lives only on the user's device, is never transmitted to the blockchain (not even encrypted) and is verified using zero-knowledge proofs. The blockchain stores only a cryptographic commitment to that data. Validators can confirm that computations were performed correctly without ever seeing the underlying values.

In this tutorial, you learn how to manage private state in a Midnight DApp. You build a complete project from scratch, a Private Score Tracker, where a user maintains a private score that only they can increment or decrement. The blockchain stores a commitment to (secretKey, score) without revealing either value. You work through every concept step by step, then wire it all together into a running DApp.

What you'll learn
Before you begin
- Required reading
- Required tools
- Required knowledge
Understanding private state
- The two-state model
- The private oracle
- When to use private state
- The lifecycle of private data
- The disclose() safety gate
Define your private state type
Encode private state
- TypeScript to Compact type mapping
- JSON serialization gotchas
Declare witness functions in Compact
- Witness declaration syntax
- A complete Compact smart contract using witnesses
- What stays private in this smart contract
Implement witness functions in TypeScript
- The WitnessContext interface
- The witness return type
- Implementing the score tracker witnesses
- What happens if a witness throws error
Use private state in circuits
- How circuits call witnesses
- The disclose() keyword in depth
- Domain separators prevent key reuse attacks
From user action to proof
- The sequence of events
- A complete increment handler
- Handling errors at each stage
- What the blockchain sees vs. what the user holds
Configure the private state provider
- Private state storage options
- Using levelPrivateStateProvider
- Schema migration
Deploy and join smart contracts with private state
- Deploying a new smart contract
- Joining an existing smart contract
Putting it all together
Build a private state DApp from scratch
- Part 1: Project setup
- Part 2: Define private state with encoding in mind
- Part 3: Write the Compact smart contract
- Part 4: Implement witnesses
- Part 5: Build the wallet provider
- Part 6: Build the API and understand how private state updates
- Part 7: Wire to a CLI
- Part 8: Start the local network
- Part 9: Fund your wallet, deploy, and run
- What this project demonstrates
Keeping private state safe
- Never log private state
- Never transmit private state off the device
- Always use readonly on private state types
- Always use cryptographically secure randomness
- Always use unique domain separators in hash derivations
- Warn users before clearing private state
- Plan for schema migration before your first release
Key takeaways
Troubleshooting
What's next

What you'll learn

By the end of this tutorial, you can:

Explain the difference between private state and public ledger state
Define a private state type in TypeScript and encode it correctly for Compact
Declare and implement witness functions that give smart contracts access to private data
Use disclose() safely to move values from private to public
Configure persistent private state storage using levelPrivateStateProvider
Deploy and join smart contracts with properly initialized private state
Trace the full path from a user action to a submitted transaction
Apply the rules for keeping private state safe

Before you begin

Required reading

If you are new to Midnight, read these first:

What is Midnight: understand the privacy model before writing code
Getting started: set up your development environment
Counter tutorial: a minimal smart contract with no private state, and a good baseline before this tutorial

Required tools

Make sure the following are installed and configured:

Tool	Version	Purpose
Node.js	22 or later	JavaScript runtime
Compact compiler (`compact`)	Latest	Compiles `.compact` smart contracts (see Getting started)

Docker Desktop	Latest	Runs the local node, indexer, and proof server

Required knowledge

TypeScript: you should be comfortable writing TypeScript. All examples use TypeScript for the DApp layer.
Basic blockchain concepts: familiarity with transactions and on-chain state is helpful but not required. Key concepts are explained as they appear.
Zero-knowledge proofs: no prior ZK knowledge is needed. The tutorial explains what proofs do in plain language without requiring you to understand the cryptography.

Understanding private state

The two-state model

Every Midnight DApp manages two distinct kinds of state. Understanding the difference is the foundation of everything else in this tutorial.

	Public ledger state	Private state
Where it lives	The blockchain	The user's local machine
Who can read it	Anyone	Only the user
How it's declared	`export ledger` in Compact	A TypeScript object
How it's protected	Transparent	Zero-knowledge proofs
When it updates	On-chain, per transaction	Locally, per transaction

Public ledger state works like any other blockchain: it is shared, verifiable, and visible to all network participants. Private state is completely different: it never leaves the user's device. The Midnight runtime ensures that computations over private data produce a cryptographic proof of correctness that validators can verify without ever seeing the underlying data.

This distinction lets you build applications where users can prove things about themselves, like "I am the person who posted this message", without revealing who they are.

The private oracle

Midnight's term for the combination of private state and the witness functions that operate on it is the private oracle. The private oracle has two components:

Private state: a plain TypeScript object you define, stored locally on the user's device
Witness functions: TypeScript functions that read from (or update) the private state during smart contract execution

Witness functions are the bridge between private state and the zero-knowledge circuits defined in your Compact smart contract. A circuit can call a witness to receive private data, use that data in its computation, and generate a proof, all without that data appearing on-chain.

When to use private state

Apply the principle of data minimization: only store something privately if it genuinely needs to be secret. Public ledger state is simpler to work with and easier to audit.

Ask yourself for every field: Does any user or validator need to see this? If yes, it belongs on the ledger. If no, especially if exposing it would harm the user, it belongs in private state.

For the score tracker, two values need to stay private: the user's secret key (their identity credential) and their current score. The blockchain stores only a commitment to both, making it impossible to read either value from on-chain data.

The lifecycle of private data

Here is the path a piece of private data takes from user action to blockchain:

At no point does the secret key appear outside the user's machine.

The `disclose()` safety gate

Compact enforces a strict separation between private and public values at compile time. By default, any value derived from a witness (and therefore potentially sensitive) cannot be assigned to a public ledger field. To assign such a value to the public ledger, you must explicitly wrap it in disclose():

// This would be a compile error — commitment() returns a value derived from witnesses (private)
scoreCommitment = commitment(sk, score);

// This is correct — disclose() explicitly marks the intent to publish
scoreCommitment = disclose(commitment(sk, score));

This is a deliberate safety mechanism. It forces you to make a conscious decision at every point where private data crosses into public view, and makes those crossings visible and searchable in your codebase.

🚨 Danger: Think before you disclose

Only call disclose() when you genuinely intend for a value to become publicly visible on-chain. Treat every disclose() call as a security decision. Add a comment explaining why it is safe to reveal this particular value.

The following sections cover each component of private state management in isolation. After that, the build section puts them all together.

Define your private state type

Private state is a plain TypeScript object. You define its shape as a type, and the Midnight SDK carries that object through every circuit call, making it available to your witness functions.

Store only the fields your witness functions actually need. Every additional field is additional data to protect.

For the score tracker, two values need to stay private: the secret key that proves ownership, and the score itself. The private state type holds both:

export type ScorePrivateState = {
  readonly secretKey: Uint8Array; // Compact: Bytes<32>
  readonly score: bigint;         // Compact: Uint<64>
};

The n suffix on bigint literals (0n, 5n) is TypeScript's syntax for a BigInt value. Compact's Uint<64> can exceed JavaScript's safe integer range, so bigint is required instead of number.

💡 Tip: Mark all fields readonly

Private state is treated as immutable by the SDK: witness functions return a new state object rather than mutating the existing one. Using readonly at the type level makes the TypeScript compiler enforce this and prevents accidental in-place mutation.

Provide a factory function to create fresh private state. This gives you a single, well-defined initialization point:

export const createScorePrivateState = (
  secretKey: Uint8Array,
  score: bigint = 0n
): ScorePrivateState => ({ secretKey, score });

The default score of 0n means callers only need to pass a secret key when first deploying. Passing a specific score is useful when restoring from a backup.

When your private state includes a cryptographic secret, always use a cryptographically secure random number generator. Never use Math.random().

// Browser environment
const secretKey = crypto.getRandomValues(new Uint8Array(32));
const privateState = createScorePrivateState(secretKey);

// Node.js environment
import { randomBytes } from "node:crypto";

const secretKey = randomBytes(32);
const privateState = createScorePrivateState(secretKey);

🚨 Danger: Protect secret keys like passwords

Never log, serialize to an insecure medium, or transmit private state over the network. Treat secretKey with the same care as a password or private key. If it is exposed, the user's on-chain identity can be forged.

Encode private state

When you define a private state type in TypeScript, every field needs a corresponding Compact type for the circuit to work with. Getting this mapping right is not optional. A type mismatch between your TypeScript field and your Compact witness declaration causes a runtime error when the circuit executes.

TypeScript to Compact type mapping

TypeScript type	Compact type	Notes
`Uint8Array` (32 bytes)	`Bytes<32>`	Standard for keys, hashes, salts
`Uint8Array` (N bytes)	`Bytes<N>`	Length in TypeScript must exactly match N
`bigint`	`Uint<64>`	Use `bigint` not `number` for amounts (`number` loses precision above 2^53)
`number`	`Uint<32>`	Safe for small counters; prefer `bigint` for anything that could be large
`string`	`Opaque<'string'>`	Opaque strings stay private unless explicitly disclosed
`boolean`	`Boolean`	Rarely needed in private state; prefer `Uint<8>` for flag enums

The witness declaration in Compact must match. If your TypeScript witness returns [state, Uint8Array] but the Compact declaration says witness localKey(): Bytes<64>, the call fails at runtime with a length mismatch.

JSON serialization gotchas

The levelPrivateStateProvider serializes your private state to a local LevelDB database using JSON internally. Two types do not survive a JSON round-trip without special handling: Uint8Array and bigint.

Uint8Array does not survive JSON.stringify / JSON.parse:

const state = { secretKey: new Uint8Array([1, 2, 3]) };
const roundTripped = JSON.parse(JSON.stringify(state));

// roundTripped.secretKey is { '0': 1, '1': 2, '2': 3 } — an object, not a Uint8Array

The SDK's built-in serializer handles this correctly when you use levelPrivateStateProvider. However, if you write custom migration logic, backup/restore code, or test utilities that serialize private state yourself, you must handle it explicitly:

// Safe serialization for Uint8Array
function serializeKey(key: Uint8Array): number[] {
  return Array.from(key);
}

function deserializeKey(raw: number[]): Uint8Array {
  return new Uint8Array(raw);
}

bigint is not valid JSON:

JSON.stringify({ balance: 1000n });
// TypeError: Do not know how to serialize a BigInt

Serialize bigint fields as strings and restore them with BigInt():

// Safe serialization for bigint
function serializeBalance(balance: bigint): string {
  return balance.toString();
}

function deserializeBalance(raw: string): bigint {
  return BigInt(raw);
}

💡 Tip: Write serializers before your first release

Even if you use levelPrivateStateProvider (which handles serialization for you), write the serializer and deserializer pair before your first release. You need them for schema migration and key export, and it is much easier to write them before users have data than after.

Declare witness functions in Compact

Witness functions have a split implementation: you declare their signature in Compact, and you implement their logic in TypeScript. The Compact declaration tells the compiler that a circuit is allowed to call this function; the TypeScript implementation provides the actual behavior.

🚨 Danger: Witnesses are untrusted inputs

Do not assume in your smart contract that the code of any witness function is the code that you wrote. Any DApp can provide any implementation it wants for your witness functions. Treat results from witnesses as untrusted input.

This means your circuit logic must validate witness-returned values against on-chain state rather than blindly using them. The score tracker does this correctly: assert(scoreCommitment == commitment(sk, score), ...) checks the witness-provided sk and score against the on-chain commitment before accepting them. A malicious witness cannot forge a valid commitment, so the assertion catches any tampering.

Witness declaration syntax

A witness declaration in Compact looks like a function signature with no body:

witness localSecretKey(): Bytes<32>;

That is the entire declaration. There is no function body in Compact. Witnesses are intentionally defined outside the language so that their implementation (and the private data they access) is never compiled into the on-chain circuit.

A complete Compact smart contract using witnesses

Here is the full score tracker smart contract. Read it top to bottom and notice how both witnesses are declared once and called in every circuit that needs them:

pragma language_version >= 0.16 && <= 0.22;
import CompactStandardLibrary;

// -- Public ledger state --------------------------------------------------
// One field: a hash committing to (secretKey, score).
// Neither value is revealed on-chain.

export ledger scoreCommitment: Bytes<32>;

// -- Witness declarations --------------------------------------------------
// No bodies here — implementations are in src/witnesses.ts.

witness localSecretKey(): Bytes<32>;
witness localScore(): Uint<64>;

// -- Helper circuit -------------------------------------------------------
// Derives a commitment from (secretKey, score).
// The domain separator "score-tracker:v1:" scopes this hash to this contract.

circuit commitment(sk: Bytes<32>, score: Uint<64>): Bytes<32> {
  const scoreBytes = (score as Field) as Bytes<32>;
  return persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "score-tracker:v1:"),
    persistentHash<Vector<2, Bytes<32>>>([sk, scoreBytes])
  ]);
}

// -- Constructor ----------------------------------------------------------
// Runs once at deployment. Calls both witnesses and writes the initial commitment.

constructor() {
  const sk = localSecretKey();
  const score = localScore();
  scoreCommitment = disclose(commitment(sk, score));
}

// -- Circuits -------------------------------------------------------------

export circuit increment(): [] {
  const sk = localSecretKey();
  const score = localScore();

  // Prove we own the current commitment before we can change it
  assert(
    scoreCommitment == commitment(sk, score),
    "State mismatch: local score does not match on-chain commitment"
  );
  assert(score < (18446744073709551615 as Uint<64>), "Score has reached maximum value");

  scoreCommitment = disclose(commitment(sk, (score + (1 as Uint<64>)) as Uint<64>));
}

export circuit decrement(): [] {
  const sk = localSecretKey();
  const score = localScore();

  assert(
    scoreCommitment == commitment(sk, score),
    "State mismatch: local score does not match on-chain commitment"
  );
  assert(score > (0 as Uint<64>), "Score cannot go below zero");

  scoreCommitment = disclose(commitment(sk, (score - (1 as Uint<64>)) as Uint<64>));
}

What stays private in this smart contract

Value	Visibility
`secretKey` (from witness)	Private (never appears on-chain)
`score` (from witness)	Private (never appears on-chain)
`scoreCommitment` (after `disclose()`)	Public (a hash of both, reveals neither)

Implement witness functions in TypeScript

Each witness declared in Compact maps to a function in the TypeScript witnesses object. The Compact compiler validates that witness declarations are used correctly within the Compact code. Whether your TypeScript witnesses object covers all declared witnesses is checked at runtime: if a required function is missing, the circuit call throws when it tries to invoke it.

ℹ️ Note: Your witness is not the only possible witness

In a deployed smart contract, any DApp that interacts with it can supply its own witness implementations. Your on-chain circuit code must validate what witnesses return. Never assume a witness result is correct just because you wrote the TypeScript implementation. Design your circuits so that a lying witness cannot cause incorrect on-chain state.

The `WitnessContext` interface

Every witness function receives a WitnessContext as its only argument. This context provides:

privateState: the current private state object for this smart contract
ledger: a snapshot of the current public ledger state
contractAddress: the on-chain address of the smart contract

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

The witness return type

A witness function returns a tuple, [NextPrivateState, ReturnValue]:

NextPrivateState: the private state as it should be after this witness call. If the witness does not change the state, return the same privateState reference you received.
ReturnValue: the value the circuit asked for, either secretKey as a Uint8Array or score as a bigint.

This return pattern is fundamental. Any private state update that happens through a witness is explicit and traceable in the return tuple.

Implementing the score tracker witnesses

The score tracker has two witnesses, one for each private field. Both are read-only:

import type { WitnessContext } from "@midnight-ntwrk/compact-runtime";
import type { Ledger } from "../contracts/managed/score/contract/index.js";
import type { ScorePrivateState } from "./types.js";

type ScoreWitnessContext = WitnessContext<Ledger, ScorePrivateState>;

export const witnesses = {
  localSecretKey: ({
    privateState,
  }: ScoreWitnessContext): [ScorePrivateState, Uint8Array] => {
    if (privateState.secretKey.length !== 32) {
      throw new Error("Corrupted private state: secretKey must be 32 bytes.");
    }
    // Return the unchanged private state and the secret key for the circuit.
    return [privateState, privateState.secretKey];
  },

  localScore: ({
    privateState,
  }: ScoreWitnessContext): [ScorePrivateState, bigint] => {
    // Return the unchanged private state and the current score for the circuit.
    return [privateState, privateState.score];
  },
};

Both witnesses return privateState unchanged. The score stored locally is not automatically updated when the circuit writes a new commitment on-chain. You handle that explicitly in the API layer (covered in Part 6 of the build section).

What happens if a witness throws error

If a witness function throws an exception, the circuit call fails immediately. No ZK proof is generated and no transaction is submitted. Throw early with a clear message if preconditions on private state are not met:

localSecretKey: ({ privateState }) => {
  if (privateState.secretKey.length !== 32) {
    // Proof generation never starts — the error surfaces to the caller cleanly.
  throw new Error("Corrupted private state: secretKey must be 32 bytes.");
  }
  return [privateState, privateState.secretKey];
},

🚨 Danger: Never log private state inside witnesses

Even during development, a console.log(privateState) or console.log(privateState.secretKey) can expose secret material through build logs, error tracking services, or developer tooling.

Use private state in circuits

With the witness declared in Compact and implemented in TypeScript, your circuits can call it to access private data.

How circuits call witnesses

Calling a witness inside a circuit looks identical to calling any other function in Compact:

// Inside a circuit — these call your TypeScript witness implementations
const sk: Bytes<32> = localSecretKey();
const score: Uint<64> = localScore();

The Compact compiler knows localSecretKey and localScore are witnesses (not circuits) because of the witness declarations. At runtime, the SDK connects each witness call to your TypeScript implementation and records the return value as a private input to the ZK proof.

The `disclose()` keyword in depth

Witness return values are treated as private. The compiler prevents you from accidentally assigning them to public ledger fields. You must use disclose() to cross this boundary:

// The compiler rejects this — scoreCommitment is a ledger field (public),
// and commitment() returns a value derived from witnesses (private)
scoreCommitment = commitment(sk, score);

// The compiler accepts this — disclose() makes the intent explicit
scoreCommitment = disclose(commitment(sk, score));

💡 Tip: Comment every disclose() call

Add a brief comment above each disclose() call explaining what is being revealed and why it is safe:
// Reveal only the commitment hash — neither secretKey nor score appears on-chain.
scoreCommitment = disclose(commitment(sk, score));

Domain separators prevent key reuse attacks

The commitment circuit uses persistentHash with the string "score-tracker:v1:" as a domain separator:

circuit commitment(sk: Bytes<32>, score: Uint<64>): Bytes<32> {
  const scoreBytes = (score as Field) as Bytes<32>;
  return persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "score-tracker:v1:"),
    persistentHash<Vector<2, Bytes<32>>>([sk, scoreBytes])
  ]);
}

This is a critical security detail. If two smart contracts both derived a commitment from the same secret key using the same hash with no separator, a user's commitment in one contract would equal their commitment in the other, linking their activity across contracts.

A unique, descriptive domain separator ("score-tracker:v1:") scopes the derived commitment to this smart contract and this version, preventing cross-contract correlation.

💡 Tip: Always use domain separators

Always include a smart contract-specific and purpose-specific domain separator when deriving public values from private keys.

From user action to proof

The previous sections explained each component in isolation. This section shows how they connect when a user types ++ in the CLI to increment their score.

The sequence of events

1. User triggers the action

// CLI input handler
if (cmd === "++") {
  await increment(contract, providers);
}

2. TypeScript reads and validates private state

Before calling the circuit, the API layer reads the current private state and checks preconditions:

const stateBefore = await providers.privateStateProvider.get(ScorePrivateStateId);
if (!stateBefore) throw new Error("No private state found. Run deploy first.");

3. Circuit call is made

The SDK sends the circuit call to the local runtime:

await contract.callTx.increment();

4. Runtime invokes your witnesses

The Compact runtime calls witnesses.localSecretKey and witnesses.localScore. Both implementations read from local private state and return [privateState, value]. Both values are passed into the circuit as private inputs.

5. Circuit executes and produces outputs for the proof

The increment circuit runs with secretKey and score as private inputs. It verifies the on-chain commitment matches, then computes a new commitment for score + 1 and marks it for disclosure via disclose(). Neither secretKey nor score is output.

6. Proof server generates the ZK proof

The local proof server (running in Docker) produces a proof that attests: "I know a secretKey and score such that commitment(sk, score) equals the current on-chain value, and commitment(sk, score + 1) is the new value I am writing." The proof is constant-size (less than a kilobyte) regardless of circuit complexity.

7. Transaction is submitted

The runtime packages { proof, newScoreCommitment } into a transaction and submits it to the Midnight network. Neither the secret key nor the score appears in the transaction.

8. On-chain verification and local state update

Validators verify the proof. The blockchain updates scoreCommitment. The API layer then updates local private state to match:

const stateAfter: ScorePrivateState = { ...stateBefore, score: stateBefore.score + 1n };
await providers.privateStateProvider.set(ScorePrivateStateId, stateAfter);

A complete increment handler

export async function increment(
  contract: DeployedScoreContract,
  providers: ScoreProviders
): Promise<void> {
  const stateBefore = await providers.privateStateProvider.get(ScorePrivateStateId);
  if (!stateBefore) throw new Error("No private state found. Run deploy first.");

  // Circuit call: witness invocation and proof generation happen automatically.
  // This call may take 10-30 seconds while the proof server works.
  await contract.callTx.increment();

  // The circuit does not write back to local storage: update it manually.
  const stateAfter: ScorePrivateState = { ...stateBefore, score: stateBefore.score + 1n };
  await providers.privateStateProvider.set(ScorePrivateStateId, stateAfter);
  console.log(`Score: ${stateBefore.score} -> ${stateAfter.score}`);
}

Handling errors at each stage

Stage	Error type	What to do
Private state missing	`Error` you throw	Tell user to deploy first
Witness throws	`Error` from witness function	Show "private state may be corrupted" message
Proof generation fails	Runtime error from proof server	Check Docker is running; retry once
Transaction rejected on-chain	Chain rejection (commitment mismatch, overflow, underflow)	Local state is out of sync; check backup and rejoin

What the blockchain sees vs. what the user holds

	On the blockchain	On the user's machine
Secret key	Never	`privateState.secretKey`
Score	Never	`privateState.score`
Score commitment	Yes, as `scoreCommitment: Bytes<32>`	Re-derivable from key and score
Proof of update	The constant-size ZK proof	The key and score that generated it

Configure the private state provider

Private state needs to survive across sessions. When a user closes your DApp and reopens it, they need to recover the same private state. Otherwise they lose access to any on-chain records tied to that state (like their score and their ability to update it).

The Midnight SDK handles this through the private state provider: a storage abstraction you configure when setting up your DApp's providers.

Private state storage options

Choose the right option for your use case before configuring a provider:

Option	Persistence	Use case	Handles serialization
`levelPrivateStateProvider`	Permanent (LevelDB on disk)	Production DApps	Yes (automatic)
In-memory provider	Session only (lost on exit)	Testing and development	Yes (no disk I/O)
Custom `PrivateStateProvider`	You decide	Advanced: key vault, mobile keychain, hardware wallet	You implement it

Option 1: `levelPrivateStateProvider` (recommended for production)

Persists private state to a LevelDB database on the local filesystem. State survives process restarts and browser refreshes. This is the right choice for any DApp where users expect their private state to be there next time they open the app.

import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";

const provider = levelPrivateStateProvider<typeof ScorePrivateStateId, ScorePrivateState>({
  privateStateStoreName: "score-tracker",
  accountId: walletAddress,
  privateStoragePasswordProvider: () =>
    process.env.SCORE_STORAGE_PASSWORD ?? "ScoreTracker-Dev1!",
});

Option 2: In-memory provider (testing and development)

Stores private state in a plain JavaScript Map. No disk I/O, no setup. State is lost when the process exits. Use this in tests so you start with a clean slate on every run without deleting files.

import { inMemoryPrivateStateProvider } from "@midnight-ntwrk/testkit-js";

// Usage in tests
const providers: ScoreProviders = {
  // ...other providers
  privateStateProvider: inMemoryPrivateStateProvider<
    typeof ScorePrivateStateId,
    ScorePrivateState
  >(),
};

ℹ️ Note: Why in-memory providers are useful for tests

Because state is lost on exit, an in-memory provider means every test run starts with fresh private state. This prevents test pollution and avoids needing to clean up LevelDB directories between runs.

Using `levelPrivateStateProvider`

import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";

// Define a unique string ID for this smart contract's private state.
// Each smart contract instance gets its own isolated storage bucket.
export const ScorePrivateStateId = "score" as const;

Configure the provider as part of your MidnightProviders setup:

import type { MidnightProviders } from "@midnight-ntwrk/midnight-js-types";
import type { ProvableCircuits } from "../contracts/managed/score/contract/index.js";

export type ScoreProviders = MidnightProviders<
  ProvableCircuits<unknown>,
  typeof ScorePrivateStateId,
  ScorePrivateState
>;

const providers: ScoreProviders = {
  // ...other providers (wallet, node, indexer)...

  privateStateProvider: levelPrivateStateProvider<typeof ScorePrivateStateId, ScorePrivateState>({
    // A unique storage name prevents collisions if your DApp manages multiple smart contracts
    privateStateStoreName: "score-tracker",
    accountId: walletAddress,
    privateStoragePasswordProvider: () =>
      process.env.SCORE_STORAGE_PASSWORD ?? "ScoreTracker-Dev1!",
  }),
};

💡 Tip: Use unique storage names

Use a descriptive, unique privateStateStoreName for each smart contract. If a user runs multiple instances of your DApp (for example, two separate score tracker deployments), a shared storage name causes one instance to overwrite the other's private state.

Schema migration

If you change the shape of ScorePrivateState between versions of your DApp, previously stored private state fails to deserialize. Plan for this before your first production deployment. Common strategies:

Version field: add a readonly version: number field to your private state type and run a migration function on load that upgrades old shapes to the current one.
Fresh deploy: for non-production environments, instruct users to delete the old storage directory and redeploy the smart contract with fresh private state.
Additive changes only: only add optional fields to your private state type; never remove or rename existing ones.

Deploy and join smart contracts with private state

When you deploy or join a smart contract, you supply the initial private state. The SDK uses this value to seed the private state provider's storage for that smart contract instance.

Deploying a new smart contract

Pass the initial private state inside the options object to deployContract:

import { randomBytes } from "node:crypto";
import { createScorePrivateState, ScorePrivateStateId } from "./types.js";

// Generate a fresh secret key for this user
const secretKey = randomBytes(32);
const initialPrivateState = createScorePrivateState(secretKey, 0n);

const deployedContract = await deployContract(providers, {
  compiledContract: scoreCompiledContract,
  privateStateId: ScorePrivateStateId,
  initialPrivateState,
});

console.log(
  "Contract deployed at:",
  deployedContract.deployTxData.public.contractAddress
);
// Do NOT log deployedContract or initialPrivateState — they contain the secret key

The deployContract call runs the smart contract's constructor circuit on-chain (which calls both witnesses and writes the initial commitment) and stores initialPrivateState in the private state provider.

Joining an existing smart contract

When a user returns to an existing smart contract (for example, after reopening the DApp), use findDeployedContract. You supply an initialPrivateState here too. The SDK uses it only if no private state already exists in storage for this smart contract address:

import { findDeployedContract } from "@midnight-ntwrk/midnight-js-contracts";
import { createScorePrivateState, ScorePrivateStateId } from "./types.js";

const contract = await findDeployedContract(providers, {
  contractAddress,              // The known on-chain address
  compiledContract: scoreCompiledContract,  // The compiled Compact smart contract
  privateStateId: ScorePrivateStateId,      // Storage key
  initialPrivateState: createScorePrivateState(
    secretKey, 0n // Fallback only — SDK prefers stored state
  ),
});

ℹ️ Note: How the fallback works

If the user already has private state stored for this smart contract address, the SDK uses the stored state and ignores initialPrivateState. The fallback only applies on a completely fresh machine or after explicit state deletion.

⚠️ Caution: Watch out for key mismatches during development

During development it is easy to accidentally pass an initialPrivateState with a different secret key than the one stored (for example, after re-generating a key during testing). The SDK silently ignores it and uses stored state. If no stored state exists, the new key becomes canonical and the old on-chain commitment becomes inaccessible.

Putting it all together

Here is how all the pieces connect in the score tracker:

The next section builds this project from an empty directory, step by step.

Build a private state DApp from scratch

The previous sections explained every component of private state management in isolation. This section puts them all together by building a complete DApp from an empty directory, with no prior code or scaffolding.

The project is a Private Score Tracker: a DApp where a user maintains a private score that only they can increment or decrement. The blockchain stores a commitment to (secretKey, score) without revealing either value. Anyone can verify that a valid score exists and that it was updated by the rightful owner, but no one can read the score or link it to an identity.

This project demonstrates:

Create: initialize private state with a fresh secret key and score of zero
Update: increment and decrement update local private state after each circuit call
Encode: bigint maps to Uint<64>, Uint8Array maps to Bytes<32>, shown end to end
Use in a DApp: circuit calls wired to a CLI, with a provider persisting state across sessions

The complete source code is on GitHub at github.com/Tosin-webdev/private-state-midnight if you want to compare as you go.

Part 1: Project setup

here is the complete repo to https://github.com/Tosin-webdev/private-state-midnight

Create the directory and initialize the project:

mkdir score-tracker
cd score-tracker
npm init -y

Install dependencies:

# Midnight SDK — core runtime and contracts
npm install @midnight-ntwrk/compact-runtime
npm install @midnight-ntwrk/compact-js
npm install @midnight-ntwrk/midnight-js-contracts
npm install @midnight-ntwrk/midnight-js-types

# Midnight SDK — private state storage
npm install @midnight-ntwrk/midnight-js-level-private-state-provider

# Midnight SDK — wallet
npm install @midnight-ntwrk/testkit-js
npm install @midnight-ntwrk/ledger-v8
npm install @midnight-ntwrk/wallet-sdk-facade
npm install @midnight-ntwrk/midnight-js-utils

# Midnight SDK — network providers
npm install @midnight-ntwrk/midnight-js-http-client-proof-provider
npm install @midnight-ntwrk/midnight-js-indexer-public-data-provider
npm install @midnight-ntwrk/midnight-js-node-zk-config-provider
npm install @midnight-ntwrk/midnight-js-network-id

# Runtime deps required by testkit-js (not declared as its own dependencies)
npm install axios@^1.15.0 pino pino-pretty testcontainers rxjs

# Development tools
npm install -D typescript @types/node tsx

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Add "type": "module" and scripts to package.json. The "type": "module" field is required because the Midnight SDK packages are ESM-only:

{
  "type": "module",
  "scripts": {
    "compile-contract": "compact compile contracts/score.compact contracts/managed/score",
    "start": "tsx src/index.ts"
  }
}

Your project structure looks like this:

score-tracker/
├── contracts/
│   └── score.compact              # Compact smart contract (you write this)
├── src/
│   ├── types.ts                   # Private state type, factory, serializer
│   ├── witnesses.ts               # Witness implementations
│   ├── wallet.ts                  # ScoreWalletProvider (signing, transaction submission)
│   ├── api.ts                     # Init, increment, decrement
│   └── index.ts                   # CLI entry point
└── package.json

Part 2: Define private state with encoding in mind

Create src/types.ts. This is where encoding decisions are made: each TypeScript field is annotated with its Compact counterpart so the mapping is always visible:

// src/types.ts

export type ScorePrivateState = {
  readonly secretKey: Uint8Array; // Compact: Bytes<32>
  readonly score: bigint; // Compact: Uint<64>
};

/**
 * Factory function — the single place where fresh private state is created.
 * Default score is 0. Always generate a new secretKey with secure randomness.
 */
export const createScorePrivateState = (
  secretKey: Uint8Array,
  score: bigint = 0n
): ScorePrivateState => ({ secretKey, score });

/**
 * Serializer — converts private state to a plain JSON-safe object.
 * Uint8Array → number[] and bigint → string to survive JSON round-trip.
 * Used for backup files and schema migration; NOT needed for levelPrivateStateProvider.
 */
export function serializeScorePrivateState(state: ScorePrivateState): object {
  return {
    secretKey: Array.from(state.secretKey),
    score: state.score.toString(),
  };
}

/**
 * Deserializer — restores private state from a serialized object.
 * Must be the exact inverse of serializeScorePrivateState.
 */
export function deserializeScorePrivateState(raw: unknown): ScorePrivateState {
  if (typeof raw !== "object" || raw === null) {
    throw new Error("Invalid serialized state: expected an object.");
  }
  const obj = raw as Record<string, unknown>;
  if (!Array.isArray(obj.secretKey) || obj.secretKey.length !== 32) {
    throw new Error(
      "Invalid serialized state: secretKey must be an array of 32 numbers."
    );
  }
  const bytes = obj.secretKey as unknown[];
  for (let i = 0; i < bytes.length; i++) {
    const b = bytes[i];
    if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
      throw new Error(
        `Invalid serialized state: secretKey[${i}] is not a byte value (0-255).`
      );
    }
  }
  if (typeof obj.score !== "string" || !/^\d+$/.test(obj.score)) {
    throw new Error(
      "Invalid serialized state: score must be a decimal integer string."
    );
  }
  let score: bigint;
  try {
    score = BigInt(obj.score);
  } catch {
    throw new Error(
      "Invalid serialized state: score could not be parsed as a bigint."
    );
  }
  return {
    secretKey: new Uint8Array(bytes as number[]),
    score,
  };
}

Part 3: Write the Compact smart contract

Create contracts/score.compact. The smart contract stores a single commitment on-chain: a hash of the user's (secretKey, score) pair. Two witnesses give the circuits access to each private field:

pragma language_version >= 0.16 && <= 0.22;
import CompactStandardLibrary;

// -------------------------------------------------------
// PUBLIC LEDGER STATE
// One field: a hash committing to (secretKey, score).
// Neither value is revealed on-chain.
// -------------------------------------------------------

export ledger scoreCommitment: Bytes<32>;

// -------------------------------------------------------
// WITNESS DECLARATIONS
// No bodies here — implementations are in src/witnesses.ts.
// localSecretKey returns Bytes<32> (maps from Uint8Array).
// localScore returns Uint<64> (maps from bigint).
// -------------------------------------------------------

witness localSecretKey(): Bytes<32>;
witness localScore(): Uint<64>;

// -------------------------------------------------------
// HELPER: derive commitment from (key, score)
// -------------------------------------------------------

circuit commitment(sk: Bytes<32>, score: Uint<64>): Bytes<32> {
  // Uint<64> cannot be passed to pad() — cast through Field then to Bytes<32>
  const scoreBytes = (score as Field) as Bytes<32>;
  return persistentHash<Vector<2, Bytes<32>>>([
    pad(32, "score-tracker:v1:"),
    persistentHash<Vector<2, Bytes<32>>>([sk, scoreBytes])
  ]);
}

// -------------------------------------------------------
// CONSTRUCTOR
// Runs once, atomically at deployment time.
// Using constructor() instead of an exported initialize() circuit
// prevents a race condition where another caller could invoke
// initialize() before the deployer, claiming the contract with
// their own key.
// -------------------------------------------------------

constructor() {
  const sk = localSecretKey();
  const score = localScore();
  // Reveal only the commitment — key and score stay private
  scoreCommitment = disclose(commitment(sk, score));
}

// -------------------------------------------------------
// INCREMENT
// Verifies current commitment, then commits to (key, score+1).
// -------------------------------------------------------

export circuit increment(): [] {
  const sk = localSecretKey();
  const score = localScore();

  // Prove we own the current commitment before we can change it
  assert(
    scoreCommitment == commitment(sk, score),
    "State mismatch: local score does not match on-chain commitment"
  );

  assert(
    score < (18446744073709551615 as Uint<64>),
    "Score has reached maximum value"
  );

  // Arithmetic result must be cast back to Uint<64> before passing to commitment()
  scoreCommitment = disclose(commitment(sk, (score + (1 as Uint<64>)) as Uint<64>));
}

// -------------------------------------------------------
// DECREMENT
// Verifies current commitment, then commits to (key, score-1).
// -------------------------------------------------------

export circuit decrement(): [] {
  const sk = localSecretKey();
  const score = localScore();

  assert(
    scoreCommitment == commitment(sk, score),
    "State mismatch: local score does not match on-chain commitment"
  );

  assert(score > (0 as Uint<64>), "Score cannot go below zero");

  // Arithmetic result must be cast back to Uint<64> before passing to commitment()
  scoreCommitment = disclose(commitment(sk, (score - (1 as Uint<64>)) as Uint<64>));
}

Compile the smart contract:

npm run compile-contract

This generates TypeScript bindings in contracts/managed/ that you import in the next step.

Part 4: Implement witnesses

Create src/witnesses.ts. There are two witnesses, one for each private field. Both are read-only: they return the current value to the circuit without updating stored state. The state update happens separately (explained in Part 6).

// src/witnesses.ts

import type { WitnessContext } from "@midnight-ntwrk/compact-runtime";
import type { Ledger } from "../contracts/managed/score/contract/index.js";
import type { ScorePrivateState } from "./types.js";

type ScoreWitnessContext = WitnessContext<Ledger, ScorePrivateState>;

export const witnesses = {
  /**
   * Returns the secret key to the circuit.
   * TypeScript: Uint8Array → Compact: Bytes<32>
   * Private state is unchanged.
   */
  localSecretKey: ({
    privateState,
  }: ScoreWitnessContext): [ScorePrivateState, Uint8Array] => {
    if (privateState.secretKey.length !== 32) {
      throw new Error("Corrupted private state: secretKey must be 32 bytes.");
    }
    return [privateState, privateState.secretKey];
  },

  /**
   * Returns the current score to the circuit.
   * TypeScript: bigint → Compact: Uint<64>
   * Private state is unchanged.
   */
  localScore: ({
    privateState,
  }: ScoreWitnessContext): [ScorePrivateState, bigint] => {
    return [privateState, privateState.score];
  },
};

Both witnesses return privateState unchanged. The score stored locally is not automatically updated when the circuit writes a new commitment on-chain. You handle that explicitly in the API layer.

Part 5: Build the wallet provider

Create src/wallet.ts. The Midnight SDK separates the wallet interface into two roles: a WalletProvider (which signs and balances transactions) and a MidnightProvider (which submits them to the node). ScoreWalletProvider implements both in a single class, following the same pattern used in official Midnight SDK examples.

The class wraps WalletFacade from @midnight-ntwrk/wallet-sdk-facade and uses FluentWalletBuilder from @midnight-ntwrk/testkit-js to build the wallet from a seed. The static build method returns both the provider and the wallet address as a plain string, so the rest of the app never has to touch wallet internals.

// src/wallet.ts

import {
  DustSecretKey,
  LedgerParameters,
  ZswapSecretKeys,
  type CoinPublicKey,
  type EncPublicKey,
  type FinalizedTransaction,
} from "@midnight-ntwrk/ledger-v8";
import {
  type MidnightProvider,
  type UnboundTransaction,
  type WalletProvider,
} from "@midnight-ntwrk/midnight-js-types";
import { ttlOneHour } from "@midnight-ntwrk/midnight-js-utils";
import {
  type DustWalletOptions,
  type EnvironmentConfiguration,
  FluentWalletBuilder,
} from "@midnight-ntwrk/testkit-js";
import { type WalletFacade } from "@midnight-ntwrk/wallet-sdk-facade";
import { firstValueFrom } from "rxjs";

// Re-export so api.ts and index.ts can import EnvironmentConfiguration from one place.
export type { EnvironmentConfiguration };

// Minimal type for the unshielded keystore returned by FluentWalletBuilder.
// The builder's return type is not fully exported, so we cast with `as unknown`.
type Keystore = {
  signData(payload: Uint8Array): string;
};

export class ScoreWalletProvider implements WalletProvider, MidnightProvider {
  private constructor(
    private readonly wallet: WalletFacade,
    private readonly zswapSecretKeys: ZswapSecretKeys,
    private readonly dustSecretKey: DustSecretKey,
    private readonly keystore: Keystore
  ) {}

  // ── WalletProvider ──────────────────────────────────────────────────────────

  getCoinPublicKey(): CoinPublicKey {
    return this.zswapSecretKeys.coinPublicKey;
  }

  getEncryptionPublicKey(): EncPublicKey {
    return this.zswapSecretKeys.encryptionPublicKey;
  }

  // Balances a raw transaction (adds dust inputs/outputs), signs it, and finalises it.
  async balanceTx(
    tx: UnboundTransaction,
    ttl: Date = ttlOneHour()
  ): Promise<FinalizedTransaction> {
    const recipe = await this.wallet.balanceUnboundTransaction(
      tx,
      {
        shieldedSecretKeys: this.zswapSecretKeys,
        dustSecretKey: this.dustSecretKey,
      },
      { ttl }
    );
    const signedRecipe = await this.wallet.signRecipe(recipe, (payload) =>
      this.keystore.signData(payload)
    );
    return this.wallet.finalizeRecipe(signedRecipe);
  }

  // ── MidnightProvider ────────────────────────────────────────────────────────

  submitTx(tx: FinalizedTransaction): Promise<string> {
    return this.wallet.submitTransaction(tx);
  }

  // ── Lifecycle ───────────────────────────────────────────────────────────────

  async stop(): Promise<void> {
    return this.wallet.stop();
  }

  // ── Factory ─────────────────────────────────────────────────────────────────

  /**
   * Builds the wallet from a seed string, starts syncing, and returns:
   *   provider — implements both WalletProvider and MidnightProvider
   *   address  — the coin public key string, ready to display or fund
   */
  static async build(
    config: EnvironmentConfiguration,
    seed: string
  ): Promise<{ provider: ScoreWalletProvider; address: string }> {
    // additionalFeeOverhead compensates for the local devnet's non-standard fee model.
    const dustOptions: DustWalletOptions = {
      ledgerParams: LedgerParameters.initialParameters(),
      additionalFeeOverhead:
        config.walletNetworkId === "undeployed"
          ? 500_000_000_000_000_000n
          : 1_000n,
      feeBlocksMargin: 5,
    };

    const buildResult = await FluentWalletBuilder.forEnvironment(config)
      .withDustOptions(dustOptions)
      .withSeed(seed)
      .buildWithoutStarting();

    // The builder's return type is opaque; cast to extract what we need.
    const { wallet, seeds, keystore } = buildResult as unknown as {
      wallet: WalletFacade;
      seeds: { masterSeed: string; shielded: Uint8Array; dust: Uint8Array };
      keystore: Keystore;
    };

    const zswapSecretKeys = ZswapSecretKeys.fromSeed(seeds.shielded);
    const dustSecretKey = DustSecretKey.fromSeed(seeds.dust);

    // Read the wallet address before starting — avoids a race with the sync loop.
    const shieldedState = await firstValueFrom(wallet.shielded.state);
    const address = shieldedState.address.coinPublicKeyString();

    await wallet.start(zswapSecretKeys, dustSecretKey);

    return {
      provider: new ScoreWalletProvider(
        wallet,
        zswapSecretKeys,
        dustSecretKey,
        keystore
      ),
      address,
    };
  }
}

Part 6: Build the API and understand how private state updates

Create src/api.ts. This is the most important file for understanding the update flow.

When increment() calls localScore(), the witness returns the current score (say, 5n) to the circuit. The circuit computes the new commitment for score 6n and writes it on-chain. But your locally stored private state still says score: 5n. The circuit does not write back to your local state. You are responsible for updating it.

This project uses the recommended pattern: update local private state immediately after the transaction resolves.

// src/api.ts

import { randomBytes } from "node:crypto";
import { fileURLToPath } from "node:url";
import { join, dirname } from "node:path";
import { CompiledContract } from "@midnight-ntwrk/compact-js";
import {
  deployContract,
  findDeployedContract,
  type FoundContract,
} from "@midnight-ntwrk/midnight-js-contracts";
import { levelPrivateStateProvider } from "@midnight-ntwrk/midnight-js-level-private-state-provider";
import { NodeZkConfigProvider } from "@midnight-ntwrk/midnight-js-node-zk-config-provider";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { setNetworkId } from "@midnight-ntwrk/midnight-js-network-id";
import {
  type ScoreWalletProvider,
  type EnvironmentConfiguration,
} from "./wallet.js";
import * as Score from "../contracts/managed/score/contract/index.js";
import type { ProvableCircuits } from "../contracts/managed/score/contract/index.js";
import {
  type ScorePrivateState,
  createScorePrivateState,
  serializeScorePrivateState,
} from "./types.js";
import { witnesses } from "./witnesses.js";

// -------------------------------------------------------
// CONFIG
// setNetworkId must be called before any SDK interaction — each config
// class calls it in its constructor so the caller doesn't have to remember.
// The proof server always runs locally; ZK proof generation is private.
//
// Both classes implement EnvironmentConfiguration from @midnight-ntwrk/testkit-js,
// which is the interface expected by FluentWalletBuilder in wallet.ts.
// -------------------------------------------------------

// Local devnet — all services run on localhost via docker compose
// Start with: docker compose up -d (compose file is in the project root)
export class LocalConfig implements EnvironmentConfiguration {
  readonly walletNetworkId = "undeployed" as const;
  readonly networkId = "undeployed";
  readonly node = "http://localhost:9944";
  readonly nodeWS = "ws://localhost:9944";
  readonly indexer = "http://localhost:8088/api/v4/graphql";
  readonly indexerWS = "ws://localhost:8088/api/v4/graphql/ws";
  readonly proofServer = "http://localhost:6300";
  readonly faucet = undefined;

  constructor() {
    setNetworkId("undeployed");
  }
}

// Preprod testnet — public hosted endpoints, proof server still runs locally
export class PreprodConfig implements EnvironmentConfiguration {
  readonly walletNetworkId = "preprod" as const;
  readonly networkId = "preprod";
  readonly node = "https://rpc.preprod.midnight.network";
  readonly nodeWS = "wss://rpc.preprod.midnight.network";
  readonly indexer = "https://indexer.preprod.midnight.network/api/v4/graphql";
  readonly indexerWS =
    "wss://indexer.preprod.midnight.network/api/v4/graphql/ws";
  readonly proofServer = "http://localhost:6300";
  readonly faucet = undefined;

  constructor() {
    setNetworkId("preprod");
  }
}

// -------------------------------------------------------
// PRIVATE STATE ID
// Used as the storage key in levelPrivateStateProvider.
// -------------------------------------------------------

export const ScorePrivateStateId = "score" as const;

// -------------------------------------------------------
// COMPILED CONTRACT
// CompiledContract.make() combines the generated contract class with
// witness implementations and the path to the compiled ZK circuit keys on disk.
// Score.Contract is the class generated by `npm run compile-contract`.
// -------------------------------------------------------

const ZK_CONFIG_PATH = join(
  dirname(fileURLToPath(import.meta.url)),
  "../contracts/managed/score"
);

const scoreCompiledContract = CompiledContract.make(
  "score",
  Score.Contract
).pipe(
  CompiledContract.withWitnesses(witnesses),
  CompiledContract.withCompiledFileAssets(ZK_CONFIG_PATH)
);

// -------------------------------------------------------
// PROVIDERS
// Wires together all six midnight-js providers:
//   privateStateProvider — LevelDB storage for ScorePrivateState (local)
//   publicDataProvider   — reads on-chain ledger state via the indexer
//   zkConfigProvider     — loads compiled ZK circuit keys from disk
//   proofProvider        — sends private witness data to the local proof server
//   walletProvider       — signs transactions (provided by ScoreWalletProvider)
//   midnightProvider     — submits transactions to the Midnight node (same instance)
//
// ScoreWalletProvider implements both WalletProvider and MidnightProvider,
// so the same object is passed to both slots.
// -------------------------------------------------------

export function configureProviders(
  walletProvider: ScoreWalletProvider,
  config: EnvironmentConfiguration,
  walletAddress: string
) {
  const zkConfigProvider = new NodeZkConfigProvider<
    keyof ProvableCircuits<unknown>
  >(ZK_CONFIG_PATH);
  return {
    privateStateProvider: levelPrivateStateProvider<
      typeof ScorePrivateStateId,
      ScorePrivateState
    >({
      privateStateStoreName: "score-tracker",
      accountId: walletAddress,
      privateStoragePasswordProvider: () =>
        process.env.SCORE_STORAGE_PASSWORD ?? "ScoreTracker-Dev1!",
    }),
    publicDataProvider: indexerPublicDataProvider(
      config.indexer,
      config.indexerWS
    ),
    zkConfigProvider,
    proofProvider: httpClientProofProvider(
      config.proofServer,
      zkConfigProvider
    ),
    walletProvider,
    midnightProvider: walletProvider,
  };
}

export type ScoreProviders = Awaited<ReturnType<typeof configureProviders>>;

// -------------------------------------------------------
// DEPLOY
// Deploys the smart contract to the network.
// The constructor() circuit runs atomically at deployment — it calls both witnesses
// and writes the initial commitment on-chain.
// -------------------------------------------------------

export async function deployTracker(providers: ScoreProviders) {
  const secretKey = randomBytes(32);
  const initialPrivateState = createScorePrivateState(secretKey, 0n);

  const deployed = await deployContract(providers, {
    compiledContract: scoreCompiledContract,
    privateStateId: ScorePrivateStateId,
    initialPrivateState,
  });

  console.log(
    `Contract deployed at: ${deployed.deployTxData.public.contractAddress}`
  );
  // Never log deployed or initialPrivateState — they contain the secret key
  return deployed;
}

export type DeployedScoreContract = FoundContract<Score.Contract>;

// -------------------------------------------------------
// JOIN
// Reconnects to an existing smart contract at a known address.
// If no private state is stored locally for this address, `initialPrivateState`
// is used as the starting point — so pass the correct secretKey.
// -------------------------------------------------------

export async function joinTracker(
  providers: ScoreProviders,
  contractAddress: string,
  secretKey: Uint8Array
): Promise<DeployedScoreContract> {
  return findDeployedContract(providers, {
    contractAddress,
    compiledContract: scoreCompiledContract,
    privateStateId: ScorePrivateStateId,
    initialPrivateState: createScorePrivateState(secretKey, 0n),
  });
}

// -------------------------------------------------------
// INCREMENT
// Calls the circuit, then updates local private state to match.
// -------------------------------------------------------

export async function increment(
  contract: DeployedScoreContract,
  providers: ScoreProviders
): Promise<void> {
  const stateBefore = await providers.privateStateProvider.get(
    ScorePrivateStateId
  );
  if (!stateBefore)
    throw new Error("No private state found. Run deploy first.");

  // The circuit reads the current score through the localScore witness,
  // verifies it matches the on-chain commitment, then updates the commitment.
  await contract.callTx.increment();

  // The circuit does not write back to local storage — update it manually.
  const stateAfter: ScorePrivateState = {
    ...stateBefore,
    score: stateBefore.score + 1n,
  };
  await providers.privateStateProvider.set(ScorePrivateStateId, stateAfter);
  console.log(`Score: ${stateBefore.score} → ${stateAfter.score}`);
}

// -------------------------------------------------------
// DECREMENT
// Same pattern as increment, but guards against going below zero.
// -------------------------------------------------------

export async function decrement(
  contract: DeployedScoreContract,
  providers: ScoreProviders
): Promise<void> {
  const stateBefore = await providers.privateStateProvider.get(
    ScorePrivateStateId
  );
  if (!stateBefore) throw new Error("No private state found.");
  if (stateBefore.score === 0n) throw new Error("Score is already zero.");

  await contract.callTx.decrement();

  const stateAfter: ScorePrivateState = {
    ...stateBefore,
    score: stateBefore.score - 1n,
  };
  await providers.privateStateProvider.set(ScorePrivateStateId, stateAfter);
  console.log(`Score: ${stateBefore.score} → ${stateAfter.score}`);
}

// -------------------------------------------------------
// EXPORT BACKUP
// Serializes private state to a JSON string the user can save.
// Writes to disk rather than stdout — never print the secret key to the terminal.
// -------------------------------------------------------

export async function exportBackup(providers: ScoreProviders): Promise<string> {
  const state = await providers.privateStateProvider.get(ScorePrivateStateId);
  if (!state) throw new Error("Nothing to export.");
  return JSON.stringify(serializeScorePrivateState(state), null, 2);
}

ℹ️ Note: Why you must update private state manually

The circuit executes inside the proof server. It can read private values through witnesses, but it cannot write back to your local storage, as that would require the proof server to have write access to your private state, which would break the trust model. You are always in control of when and how local private state changes.

⚠️ Caution: State desync risk

If contract.callTx.increment() succeeds but providers.privateStateProvider.set(...) fails (for example, due to a disk error or process crash), your local score is one behind the on-chain commitment. The next increment() call will fail with a commitment mismatch.

To recover, re-read the on-chain commitment and brute-force the correct local score (or export a backup before each operation and use it to restore). For production DApps, consider wrapping the set() call in a retry loop, or storing a "pending" score that gets confirmed after the next successful circuit call.

Part 7: Wire to a CLI

Create src/index.ts, a minimal interactive CLI that lets you initialize private state, increment, decrement, and export a backup:

// src/index.ts

import * as readline from "node:readline";
import { writeFile } from "node:fs/promises";
import {
  type DeployedScoreContract,
  type ScoreProviders,
  LocalConfig,
  configureProviders,
  deployTracker,
  joinTracker,
  increment,
  decrement,
  exportBackup,
} from "./api.js";
import { ScoreWalletProvider } from "./wallet.js";

// Wallet SDK background sync tasks emit unhandled rejections when the
// network is unreachable or when the process exits during active sync.
// Only suppress rejections that originate from wallet SDK internals.
process.on("unhandledRejection", (reason) => {
  const msg = reason instanceof Error ? reason.message : String(reason);
  if (
    msg.includes("WebSocket") ||
    msg.includes("disconnected") ||
    msg.includes("Connection reset") ||
    msg.includes("ECONNREFUSED")
  ) {
    return;
  }
  console.error("Unhandled rejection:", reason);
});

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});
const ask = (q: string) =>
  new Promise<string>((resolve) => rl.question(q, resolve));

async function main() {
  // ── Config ─────────────────────────────────────────────────────────────────
  // LocalConfig calls setNetworkId('undeployed') in its constructor.
  // Swap to new PreprodConfig() to target the Preprod testnet instead.
  const config = new LocalConfig();

  // ── Wallet setup ──────────────────────────────────────────────────────────
  // LOCAL_TEST_SEED is the number 1 padded to 32 bytes. It is a well-known
  // test value — anyone who sees it can derive the same wallet and drain its funds.
  // NEVER use it on preprod or mainnet. Always set WALLET_SEED to a secret
  // seed you generated yourself before targeting any public network.
  // On the local devnet this address is pre-funded by the genesis block.
  const LOCAL_TEST_SEED =
    "0000000000000000000000000000000000000000000000000000000000000001";
  const seed = process.env.WALLET_SEED ?? LOCAL_TEST_SEED;

  console.log("Connecting to local network...");
  const { provider: walletProvider, address } = await ScoreWalletProvider.build(
    config,
    seed
  );
  console.log(`Wallet address: ${address}`);
  const providers: ScoreProviders = configureProviders(
    walletProvider,
    config,
    address
  );

  let contract: DeployedScoreContract | null = null;

  try {
    console.log(
      "\nScore Tracker ready. Commands: deploy | join <address> | ++ | -- | backup | exit\n"
    );
    while (true) {
      const input = (await ask("> ")).trim();
      const [cmd, ...args] = input.split(" ");

      if (cmd === "deploy") {
        // Deploys the smart contract. The constructor() circuit runs on-chain,
        // calling both witnesses and writing the initial commitment.
        contract = await deployTracker(providers);
      } else if (cmd === "join") {
        // Reconnects to an existing contract at a known address.
        // Requires the original secret key — stored in your backup file.
        const address = args[0];
        if (!address) {
          console.log("Usage: join <contractAddress>");
          continue;
        }
        const secretKeyHex = await ask("Enter your secret key (hex): ");
        const secretKey = Buffer.from(secretKeyHex.trim(), "hex");
        if (secretKey.length !== 32) {
          console.log("Secret key must be 32 bytes (64 hex chars).");
          continue;
        }
        contract = await joinTracker(
          providers,
          address,
          new Uint8Array(secretKey)
        );
      } else if (cmd === "++") {
        if (!contract) {
          console.log("Deploy or join a contract first.");
          continue;
        }
        await increment(contract, providers);
      } else if (cmd === "--") {
        if (!contract) {
          console.log("Deploy or join a contract first.");
          continue;
        }
        await decrement(contract, providers);
      } else if (cmd === "backup") {
        const json = await exportBackup(providers);
        // Write to disk — never print to stdout, which would expose the secret key
        // in terminal history, log files, and screen-sharing sessions.
        const backupPath = `./score-backup-${Date.now()}.json`;
        await writeFile(backupPath, json, "utf8");
        console.log(`Backup written to: ${backupPath}`);
        console.log(
          "Keep this file safe. Do not share it or store it anywhere outside your device."
        );
      } else if (cmd === "exit") {
        break;
      }
    }
  } finally {
    rl.close();
    await walletProvider.stop().catch(() => {});
  }
}

main().catch(console.error);

The unhandledRejection handler filters only wallet SDK noise (WebSocket disconnects, ECONNREFUSED), so real application errors still surface. This keeps the process alive through network hiccups without hiding bugs behind a blanket error suppressor.

The join command prompts for the secret key interactively rather than reading it from an environment variable or file. This prevents the key from sitting in shell history or a config file on disk.

The backup command writes to disk instead of printing to stdout for the same reason: stdout ends up in terminal history, log files, and screen-sharing sessions.

The finally block calls walletProvider.stop().catch(() => {}) because when the process exits, the wallet's background sync loop is often already in a broken state. Errors from stop() at that point are expected noise, not actionable failures.

The contract variable stays null until the user runs deploy or join. There is no implicit reconnect on startup: the user is always in control of which contract instance is active.

Part 8: Start the local network

The local network runs three services via Docker Compose: the Midnight node, the indexer, and the proof server. Create docker-compose.yml in the project root:

services:
  proof-server:
    image: "midnightntwrk/proof-server:8.0.3"
    container_name: "proof-server"
    ports:
      - "6300:6300"

  indexer:
    image: "midnightntwrk/indexer-standalone:4.0.0"
    container_name: "indexer"
    ports:
      - "8088:8088"
    environment:
      RUST_LOG: "indexer=info,chain_indexer=info,indexer_api=info,wallet_indexer=info,indexer_common=info,fastrace_opentelemetry=info,info"
      APP__INFRA__SECRET: "303132333435363738393031323334353637383930313233343536373839303132"
      APP__INFRA__NODE__URL: "ws://node:9944"
    healthcheck:
      test: ["CMD-SHELL", "cat /var/run/indexer-standalone/running"]
      start_interval: "5s"
      interval: "5s"
      timeout: "2s"
      retries: 2
      start_period: 5s
    depends_on:
      node:
        condition: service_started

  node:
    image: "midnightntwrk/midnight-node:0.22.1"
    container_name: "node"
    ports:
      - "9944:9944"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9944/health"]
      interval: 2s
      timeout: 5s
      retries: 5
      start_period: 5s
    environment:
      CFG_PRESET: "dev"

From the score-tracker directory, start all services in the background:

docker compose up -d

This starts three services on standard localhost ports:

Service	Port
Proof server	6300
Node (RPC/WebSocket)	9944
Indexer (GraphQL)	8088

ℹ️ Note: Why the proof server runs locally

ZK proof generation uses your private witness data as input. Running it on your machine means that data never leaves your device. The proof itself (the output) contains no recoverable information about the private inputs and is safe to submit to the network publicly.

Part 9: Deploy and run

Compile the contract first:

npm run compile-contract

Start the CLI:

npm start

The CLI prints your wallet address derived from the fixed local test seed:

Connecting to local network...
Wallet address: <your-address>

Score Tracker ready. Commands: deploy | join <address> | ++ | -- | backup | exit

The fixed seed always derives the same address, and the local devnet pre-funds it in the genesis block. No manual funding step is needed.

Deploy and interact:

> deploy
Contract deployed at: 65832fb...b53d

> ++
Score: 0 -> 1

> ++
Score: 1 -> 2

> --
Score: 2 -> 1

> backup
Backup written to: ./score-backup-1777699189013.json
Keep this file safe. Do not share it or store it anywhere outside your device.

> exit

Each ++ and -- operation:

Reads your current private state (score + secret key) from LevelDB
Passes the values to the circuit through the witness functions
Generates a ZK proof that the new commitment is valid, using the local proof server
Submits the transaction to the local node
Updates local private state to match the new score

The on-chain scoreCommitment field advances with each transaction. Anyone can verify it changed, but no one can read the score or link it to an identity.

What this project demonstrates

Requirement	Where it appears
Create private state	`deployTracker`: generates a secret key, calls `createScorePrivateState`, and seeds the provider
Update private state	`increment` / `decrement`: reads state before, calls the circuit, writes updated state after
Encode private state	`types.ts`: `Uint8Array`/`bigint` mapped to `number[]`/`string`; Compact type annotations on each field
Use in a DApp	`index.ts`: CLI wires user input to API calls, full circuit → proof → on-chain cycle

Keeping private state safe

The security of your DApp depends entirely on whether private state stays private. The following rules apply unconditionally.

Never log private state

Even during development, logging private state fields exposes them to build logs, error tracking services, browser developer tools, and terminal history. This includes console.log, structured loggers, and error reporting SDKs.

// Never do this
console.log("Private state:", privateState);
console.log("Secret key:", privateState.secretKey);

// If you must debug, log only metadata
console.log("Witness called. Key length:", privateState.secretKey.length);

Never transmit private state off the device

Private state must never be sent over a network connection: not to your backend, not to an analytics service, not via WebSocket. If you need to back up a user's secret key, generate an encrypted export that the user saves locally (like a keystore file), and never send the plaintext.

Always use `readonly` on private state types

readonly at the TypeScript type level prevents accidental in-place mutation and signals to every reader of your code that this object follows immutable update patterns.

// Correct
export type ScorePrivateState = {
  readonly secretKey: Uint8Array;
  readonly score: bigint;
};

// Risky — nothing stops a witness from mutating fields instead of returning new state
export type ScorePrivateState = {
  secretKey: Uint8Array;
  score: bigint;
};

Always use cryptographically secure randomness

Never generate secret keys or salts with Math.random(). It is not cryptographically secure and its output can be predicted.

// Correct (browser)
const secretKey = crypto.getRandomValues(new Uint8Array(32));

// Correct (Node.js)
import { randomBytes } from "node:crypto";
const secretKey = randomBytes(32);

// Never do this
const secretKey = new Uint8Array(32).map(() => Math.floor(Math.random() * 256));

Always use unique domain separators in hash derivations

When deriving a public commitment from a private key, include a domain separator that is unique to your smart contract and the specific purpose:

// Scoped to this smart contract and this key type
persistentHash<Vector<2, Bytes<32>>>([pad(32, "score-tracker:v1:"), persistentHash<Vector<2, Bytes<32>>>([sk, scoreBytes])])

// No separator — the same key in two contracts produces the same commitment,
// allowing cross-contract correlation of user identity
persistentHash<Vector<2, Bytes<32>>>([sequence, sk])

Warn users before clearing private state

Deleting stored private state is permanent. If the user has an on-chain commitment tied to their secret key (such as a score they want to continue updating), deleting private state permanently removes their ability to interact with those on-chain records. Always prompt for explicit confirmation and consider offering a key export before deletion.

Plan for schema migration before your first release

Once users have private state stored in production, changing its shape is a breaking change. Decide on a migration strategy before your first release. It is far easier to design for it upfront than to retrofit it after users have data.

Key takeaways

Private state lives only on the user's device and never reaches the blockchain.
The blockchain stores only commitment hashes derived from private data. Even if the blockchain were fully public and readable by anyone, private state fields like secretKey would not be visible. They never leave the user's machine.

Witness functions are the only bridge between private state and on-chain circuits. Keep them simple, pure, and never log them.
A witness reads from (or updates) private state and hands values to the circuit as private inputs. It is the single point of contact between your private data and the ZK proof system. Keep witness functions short, deterministic, and free of side effects.

disclose() is a deliberate, security-sensitive decision. Treat every call as a point of review.
The Compact compiler prevents you from accidentally publishing private data, but it cannot judge whether a disclosure is correct for your use case. Every disclose() call should have a comment explaining what is being revealed and why it is safe. These comments are your most important documentation for security reviewers.

Troubleshooting

Here are some errors you might encounter while working on the score tracker

- SyntaxError: module does not provide an export named '...'

The Midnight SDK packages must be on compatible versions. Unpinned installs pull the latest versions, which may be incompatible with each other.

Fix: replace your package.json dependencies with the versions shown in Part 1 and reinstall:

- Error: proof server connection refused

The proof server is not running. All three Docker services must be up before you can call any circuit.

Fix:

docker compose up -d

- Error: Cannot find module
'../contracts/managed/score/contract/index.js'

The contract has not been compiled yet. The generated TypeScript bindings in contracts/managed/ are not included in the repository and must be built locally.

Fix:

npm run compile-contract

What's next

You now have a complete picture of private state management in Midnight DApps. To go deeper:

Complete project source: the finished score tracker from this tutorial
Counter tutorial: a minimal smart contract with no private state, a good baseline to contrast with this tutorial
Compact language reference: complete syntax reference for ledger declarations, circuits, witnesses, and disclose()
Midnight SDK reference: API documentation for levelPrivateStateProvider, WitnessContext, findDeployedContract, and related types, including the PrivateStateProvider interface for teams that need to implement custom storage backends
Concepts: Zero-knowledge proofs: a deeper dive into the cryptographic foundations underlying private state protection

Build a privacy-preserving notebook DApp on Midnight

Oladeji Tosin — Fri, 24 Apr 2026 18:55:46 +0000

Introduction

Most blockchains are public ledgers, everything stored on them is visible to every participant in the network. That works well for token balances and governance votes, but it creates a real problem the moment you want to store anything sensitive. A note-taking application built naively on a public chain would expose every note body to every observer in plain text.

Midnight solves this through zero-knowledge proofs. Instead of storing your note text on-chain, you store only a cryptographic commitment, a SHA-256 hash that proves a note exists without revealing what it says. The full text lives in an off-chain backend your application controls. Any observer who reads the chain sees a list of hashes; only the notebook owner, who holds the secret key, can write new notes or delete existing ones, and only the backend can produce the matching body for any given commitment.

In this tutorial, you build the Private Notebook DApp from scratch. You write a Compact smart contract that enforces ownership and manages commitments, implement the TypeScript witnesses that feed private data to ZK circuits, set up an Express and SQLite backend for off-chain storage, and connect everything to a React frontend through the 1AM wallet. By the end you have a working full-stack DApp running on Midnight's preprod network that you can extend into any privacy-preserving application.

Prerequisites

Before you start, make sure you have the following installed and configured:

Node.js 22 or later (check with node --version)
The Compact compiler (install the Midnight toolchain from docs.midnight.network)
The 1AM wallet Chrome extension, connected to the preprod network
A Unix-like shell (macOS or Linux; WSL works on Windows) works fine for this

Step 1: Understand the architecture

Before writing any code, it helps to see how the pieces fit together.

What goes on-chain: A 32-byte commitment hash for each note, a counter, and the owner's derived public key. None of these values reveals note content.

What stays off-chain: The actual note text, stored in SQLite keyed by (contractAddress, commitment).

How ownership works: The deployer's 32-byte secret key never leaves the browser. The contract stores persistentHash(["notebook:pk:", secretKey]). Every write operation re-derives this value inside the ZK circuit and asserts it equals the stored commitment. An observer sees only the hash.

This split between on-chain and off-chain storage is the core design pattern for any Midnight DApp that needs to handle data larger than a hash. Storing raw text on-chain would expose it to all network participants and be expensive, as every node must store it permanently. Storing only the commitment keeps costs low and preserves privacy: the hash proves the note exists and that the same data was committed, but reveals nothing about the content. The backend is your access layer, not a trust anchor; the chain is the trust anchor.

Understanding this distinction before you write any code will help you make good decisions throughout the rest of the tutorial. Ask yourself for each piece of data: does a network observer need to verify this, or just you? If just you, keep it off-chain. If the network needs to verify it (ownership, existence, ordering), commit a hash to the chain.

Step 2: Explore the monorepo layout

The project is an npm workspaces monorepo with four packages. Each package has a single, focused responsibility:

@notebook/contract contains the Compact smart contract source, the TypeScript witness implementations, and the compiled managed artifacts. Nothing outside this package needs to know the Compact syntax.
@notebook/api is a browser-safe TypeScript library that wraps the Midnight SDK. It exposes deployNotebook, joinNotebook, and the note operations as plain async functions. The frontend imports from here, not from the SDK directly.
@notebook/backend is an Express HTTP server with a SQLite database. It stores note bodies indexed by commitment. It has no knowledge of Midnight or ZK proofs; it is a simple content-addressed store.
@notebook/frontend is the React and Vite web application. It imports from @notebook/api and makes HTTP requests to the backend. All user interaction flows through here.

Keeping these packages separate means you can swap the backend for a different storage layer (IPFS, a database-as-a-service, client-side encryption) without touching the contract or the API layer. Similarly, you could add a CLI client that imports @notebook/api without touching the frontend at all.

The root package.json defines the workspaces and top-level scripts:

{
  "name": "fullstack-midnight-dapp",
  "version": "0.1.0",
  "private": true,
  "description": "Private Notebook: a full-stack Midnight dApp tutorial",
  "workspaces": ["contract", "api", "backend", "frontend"],
  "scripts": {
    "compile:contract": "npm run compile -w contract",
    "build": "npm run build -w contract && npm run build -w api && npm run build -w backend && npm run build -w frontend",
    "dev:backend": "npm run dev -w backend",
    "dev:frontend": "npm run dev -w frontend"
  },
  "engines": {
    "node": ">=22"
  }
}

Create tsconfig.base.json at the root. Every workspace tsconfig.json extends this file so compiler settings stay consistent across the monorepo:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  }
}

Create scripts/copy-managed.mjs at the root. The contract's build script runs this after tsc compiles the TypeScript sources. TypeScript emits output to contract/dist/, but the Compact compiler writes the managed artifacts (the generated index.ts, verifier keys, and circuit IR files) into contract/src/managed/. This script copies that directory across so that consumers resolving @notebook/contract package imports find the artifacts under dist/managed/ where they expect them:

// After tsc emits contract/dist, copy the compiled Compact artifacts from
// contract/src/managed to contract/dist/managed so that consumers resolving
// package imports (dist/index.js → "./managed/...") find the files.
import { cpSync, existsSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const here = dirname(fileURLToPath(import.meta.url));
const src = resolve(here, "../contract/src/managed");
const dst = resolve(here, "../contract/dist/managed");

if (!existsSync(src)) {
  console.error(
    `copy-managed: ${src} does not exist. Run 'npm run compile -w contract' first.`
  );
  process.exit(1);
}

cpSync(src, dst, { recursive: true });
console.log(`copy-managed: copied ${src} -> ${dst}`);

⚠️WARNING
copy-managed.mjs exits with an error if contract/src/managed does not exist. Always run compact compile (Step 6) before running npm run build. The compile step creates the managed directory; the build step copies it.

ℹ️ INFO
Your editor will show TypeScript "cannot find module" errors and red squiggles throughout Steps 2 to 20. This is expected. node_modules does not exist until you run npm install in Step 21, and the managed contract artifacts do not exist until you run compact compile in Step 6. The code you write is correct; the errors disappear once you complete Step 21.

Step 3: Write the Compact smart contract

Create contract/package.json. This declares the workspace name, the compile and build scripts, and the Midnight SDK packages the contract layer needs:

{
  "name": "@notebook/contract",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./managed": "./dist/managed/notebook/contract/index.js"
  },
  "scripts": {
    "compile": "compact compile src/notebook.compact src/managed/notebook",
    "build": "tsc -p tsconfig.json && node ../scripts/copy-managed.mjs",
    "test": "vitest run"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-js": "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.15.0"
  },
  "devDependencies": {
    "typescript": "^5.5.4",
    "vitest": "^2.0.0"
  }
}

Create contract/tsconfig.json. It extends the root base config and excludes the managed/ directory (generated code that TypeScript should not try to compile directly from source):

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["src/managed", "node_modules", "dist"]
}

Create contract/src/notebook.compact with the following complete source:

pragma language_version 0.22;

import CompactStandardLibrary;

// Public ledger state. Stored on chain, visible to any observer.
export sealed ledger owner_commitment: Bytes<32>;
export ledger notes: Map<Bytes<32>, Bytes<32>>;
export ledger note_count: Counter;

// Witness declarations. Implementations live in TypeScript.
witness local_secret_key(): Bytes<32>;
witness fresh_nonce(): Bytes<32>;

// Domain separated public key derivation. Midnight does not provide a
// public_key() builtin, so we derive one with persistentHash.
pure circuit derive_pk(sk: Bytes<32>): Bytes<32> {
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "notebook:pk:"), sk]);
}

// The constructor pins the owner to whoever deployed the contract.
constructor() {
  const sk = local_secret_key();
  owner_commitment = disclose(derive_pk(sk));
}

// post_note stores a content commitment on chain under a fresh note id.
// Only the original deployer can call this because we check the derived
// public key against the stored owner_commitment.
export circuit post_note(content_hash: Bytes<32>): Bytes<32> {
  const sk = local_secret_key();
  assert(disclose(derive_pk(sk) == owner_commitment), "Only owner can post");

  const nonce = fresh_nonce();
  const note_id = disclose(
    persistentHash<Vector<2, Bytes<32>>>([nonce, content_hash])
  );
  const d_hash = disclose(content_hash);

  notes.insert(note_id, d_hash);
  note_count.increment(1);
  return note_id;
}

// delete_note removes an owned note. The same owner check applies.
export circuit delete_note(note_id: Bytes<32>): [] {
  const sk = local_secret_key();
  assert(disclose(derive_pk(sk) == owner_commitment), "Only owner can delete");

  const d_id = disclose(note_id);
  assert(notes.member(d_id), "Note does not exist");

  notes.remove(d_id);
  note_count.decrement(1);
}

Key concepts in this file:

sealed ledger means the constructor sets the field once and no circuit can ever change it afterward. This guarantees the owner is locked at deploy time.
witness declarations are TypeScript functions, not Compact code. The keyword tells the compiler "a TypeScript function called local_secret_key will provide this 32-byte value at proving time."
pure circuit derive_pk is a helper with no ledger side effects. It derives a public key using persistentHash (Poseidon hash) with a domain separator, because Midnight has no public_key() built-in.
disclose() wraps every value derived from witness data before it touches the ledger. Compact enforces this rule at compile time to prevent accidental private-data leaks.
The return type [] is an empty tuple, Compact's equivalent of void.

⚠️CAUTION
Forgetting disclose() on any witness-derived value that flows into a ledger operation produces the compile-time error: "implicit disclosure of witness value". Always wrap such values before inserting them into maps, assigning to ledger fields, or using them in assertions.

Step 4: Implement TypeScript witnesses

Create contract/src/witnesses.ts:

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

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

export const createNotebookPrivateState = (
  secretKey: Uint8Array
): NotebookPrivateState => {
  if (secretKey.length !== 32) {
    throw new Error(`secretKey must be 32 bytes, got ${secretKey.length}`);
  }
  return { secretKey };
};

export const generateRandomSecretKey = (): Uint8Array => {
  const buf = new Uint8Array(32);
  crypto.getRandomValues(buf);
  return buf;
};

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

  fresh_nonce: ({
    privateState,
  }: WitnessContext<Ledger, NotebookPrivateState>): [
    NotebookPrivateState,
    Uint8Array
  ] => {
    const nonce = new Uint8Array(32);
    crypto.getRandomValues(nonce);
    return [privateState, nonce];
  },
};

NotebookPrivateState is the private data the Midnight SDK holds in memory for this contract instance. Every witness function receives a WitnessContext containing privateState and returns a tuple [newPrivateState, witnessOutput]. These witnesses do not mutate private state, so they return it unchanged. fresh_nonce uses the Web Crypto API, which is available in both browsers and Node.js 20+.

It is worth pausing here to understand the witness execution model. When you call a circuit (for example post_note), the Midnight SDK does not send the witness values to any server. Instead, it runs the witness functions locally in your browser's JavaScript engine, collects their outputs, and feeds them into the ZK proving system alongside the circuit logic. The prover generates a proof that the witness outputs satisfy the circuit's constraints. That proof, and only that proof, is sent to the network. The secret key and the nonce stay on your device.

This is the fundamental privacy guarantee of the architecture: the ZK proof certifies that "someone who knows the secret key corresponding to this public key has posted a note with this commitment" without revealing the key itself, the nonce, or the note content. Witnesses are the bridge between the private world (your browser) and the public world (the chain).

Step 5: Export the compiled contract

Create contract/src/index.ts. This barrel file binds the compiled artifacts, the witnesses, and the contract class into a single CompiledNotebookContract object that the SDK's deployContract and findDeployedContract functions accept:

import { CompiledContract } from "@midnight-ntwrk/compact-js";
import * as ManagedNotebook from "./managed/notebook/contract/index.js";
import { witnesses, type NotebookPrivateState } from "./witnesses.js";

export * from "./witnesses.js";
export * from "./managed/notebook/contract/index.js";
export {
  Contract as NotebookContract,
  ledger as notebookLedger,
  pureCircuits as notebookPureCircuits,
} from "./managed/notebook/contract/index.js";

// CompiledNotebookContract is the compact-js CompiledContract binding used by
// the v4 SDK's deployContract / findDeployedContract functions.
export const CompiledNotebookContract = CompiledContract.make<
  ManagedNotebook.Contract<NotebookPrivateState>
>("Notebook", ManagedNotebook.Contract<NotebookPrivateState>).pipe(
  CompiledContract.withWitnesses(witnesses),
  CompiledContract.withCompiledFileAssets("./managed/notebook")
);

The managed/notebook/contract/index.js file does not exist yet. The Compact compiler generates it in the next step.

CompiledContract.make creates a binding that tells the SDK the contract's name and class. The two pipe calls attach the witness implementations and the compiled file assets (the path to the managed/notebook directory where the .verifier and .bzkir files live). Every time the SDK needs to generate a proof or find verifier keys, it reads these assets from disk in Node.js environments or fetches them over HTTP in browser environments.

Step 6: Compile the contract

The Compact compiler reads notebook.compact and generates a set of managed TypeScript artifacts, ZK verifier keys (.verifier files), and circuit IR files (.bzkir files).

Run the compiler directly from inside the contract/ directory. At this point in the tutorial npm install has not been run yet, so the workspace shortcut is not available:

cd contract
compact compile src/notebook.compact src/managed/notebook
cd ..

ℹ️ INFO

Once you run npm install in Step 21, the same command is available as npm run compile:contract. You only need to run it again if you change notebook.compact. If you follow this tutorial straight through without modifying the contract, the artifacts generated here are still valid when you reach Step 21.

After the compiler completes, the directory contract/src/managed/notebook/ exists and contains:

managed/notebook/
+-- contract/
|   +-- index.ts          (typed contract, ledger accessor, and pure circuits)
+-- keys/
|   +-- post_note.verifier
|   +-- delete_note.verifier
+-- zkir/
    +-- post_note.bzkir
    +-- delete_note.bzkir

The keys/ and zkir/ directories contain the ZK key material. The Vite dev server must serve these files at {origin}/keys/{circuit}.verifier and {origin}/zkir/{circuit}.bzkir. The midnight-zk-assets Vite plugin in vite.config.ts handles this automatically.

*💡 TIP
Any time you change notebook.compact, re-run npm run compile:contract. The managed artifacts must match the deployed contract; mismatches cause "Failed to configure verifier key" errors at runtime.

Step 7: Define the common API types

Create api/package.json. The API layer depends on every Midnight SDK package that a browser DApp needs, plus the @notebook/contract workspace package:

{
  "name": "@notebook/api",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-js": "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.15.0",
    "@midnight-ntwrk/dapp-connector-api": "^4.0.1",
    "@midnight-ntwrk/ledger-v8": "^8.0.3",
    "@midnight-ntwrk/midnight-js-contracts": "^4.0.4",
    "@midnight-ntwrk/midnight-js-fetch-zk-config-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-network-id": "^4.0.4",
    "@midnight-ntwrk/midnight-js-types": "^4.0.4",
    "@midnight-ntwrk/midnight-js-utils": "^4.0.4",
    "@notebook/contract": "0.1.0",
    "rxjs": "^7.8.1"
  },
  "devDependencies": {
    "typescript": "^5.5.4"
  }
}

Create api/tsconfig.json. The lib array includes DOM because the API layer uses crypto.subtle and fetch, which are browser globals:

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "lib": ["ES2022", "DOM"]
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Create api/src/common-types.ts. This file centralises all shared TypeScript types so the providers and API modules stay decoupled:

import type { ContractAddress } from "@midnight-ntwrk/compact-runtime";
import type { MidnightProviders } from "@midnight-ntwrk/midnight-js-types";
import type { FoundContract } from "@midnight-ntwrk/midnight-js-contracts";
import type { Contract, Witnesses, Ledger } from "@notebook/contract";
import type { NotebookPrivateState } from "@notebook/contract";
import type { Observable } from "rxjs";

export const NotebookPrivateStateId = "notebookPrivateState";
export type NotebookPrivateStateIdType = typeof NotebookPrivateStateId;

export type NotebookContractType = Contract<
  NotebookPrivateState,
  Witnesses<NotebookPrivateState>
>;

// Circuit keys are the string keys of the provableCircuits map on the contract.
export type NotebookCircuitKeys = Exclude<
  keyof NotebookContractType["impureCircuits"],
  number | symbol
>;

export type NotebookProviders = MidnightProviders<
  NotebookCircuitKeys,
  NotebookPrivateStateIdType,
  NotebookPrivateState
>;

export type DeployedOrFoundNotebook = FoundContract<NotebookContractType>;

export type NotebookDerivedState = {
  readonly ownerCommitment: Uint8Array;
  readonly notes: ReadonlyMap<string, string>;
  readonly noteCount: bigint;
};

export type NotebookAPI = {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Observable<NotebookDerivedState>;
  postNote: (contentHash: Uint8Array) => Promise<Uint8Array>;
  deleteNote: (noteId: Uint8Array) => Promise<void>;
};

export type { Ledger, NotebookPrivateState };

MidnightProviders is parameterised by three types: the circuit key union (which circuits can be proved), the private state ID string literal, and the private state shape. NotebookCircuitKeys derives those keys directly from the compiled contract so you never have to maintain them by hand.

The type system earns its keep here. Because NotebookCircuitKeys is derived from impureCircuits on the compiled contract class, if you add a new circuit to notebook.compact and recompile, TypeScript will report an error anywhere that NotebookProviders is used without handling the new circuit key. This compile-time safety prevents the common mistake of adding a circuit but forgetting to register its ZK key material with the providers.

Step 8: Write the in-memory private state provider

Create api/src/in-memory-private-state-provider.ts. The Midnight SDK stores private state (the owner's secret key) through a PrivateStateProvider interface. This implementation keeps everything in memory, which is sufficient for a tutorial. Production apps should use midnight-js-level-private-state-provider backed by IndexedDB with password protection.

import type {
  ContractAddress,
  SigningKey,
} from "@midnight-ntwrk/compact-runtime";
import type {
  PrivateStateId,
  PrivateStateProvider,
  PrivateStateExport,
  ExportPrivateStatesOptions,
  ImportPrivateStatesOptions,
  ImportPrivateStatesResult,
  SigningKeyExport,
  ExportSigningKeysOptions,
  ImportSigningKeysOptions,
  ImportSigningKeysResult,
} from "@midnight-ntwrk/midnight-js-types";

// A simple in-memory PrivateStateProvider for browser usage. Private state is
// scoped by contract address and private state ID. State is lost on page reload,
// which is acceptable for a tutorial dApp. Production apps should use
// midnight-js-level-private-state-provider with proper password management.
export const inMemoryPrivateStateProvider = <
  PSI extends PrivateStateId,
  PS
>(): PrivateStateProvider<PSI, PS> => {
  const privateStates = new Map<string, PS>();
  const signingKeys = new Map<string, SigningKey>();
  let currentAddress = "";

  const psKey = (id: PSI) => `${currentAddress}:${String(id)}`;

  return {
    setContractAddress(address: ContractAddress): void {
      currentAddress = address;
    },

    async set(id: PSI, state: PS): Promise<void> {
      privateStates.set(psKey(id), state);
    },
    async get(id: PSI): Promise<PS | null> {
      return privateStates.get(psKey(id)) ?? null;
    },
    async remove(id: PSI): Promise<void> {
      privateStates.delete(psKey(id));
    },
    async clear(): Promise<void> {
      for (const k of privateStates.keys()) {
        if (k.startsWith(`${currentAddress}:`)) privateStates.delete(k);
      }
    },

    async setSigningKey(
      address: ContractAddress,
      key: SigningKey
    ): Promise<void> {
      signingKeys.set(address, key);
    },
    async getSigningKey(address: ContractAddress): Promise<SigningKey | null> {
      return signingKeys.get(address) ?? null;
    },
    async removeSigningKey(address: ContractAddress): Promise<void> {
      signingKeys.delete(address);
    },
    async clearSigningKeys(): Promise<void> {
      signingKeys.clear();
    },

    async exportPrivateStates(
      _options?: ExportPrivateStatesOptions
    ): Promise<PrivateStateExport> {
      return { states: [], version: 1 } as unknown as PrivateStateExport;
    },
    async importPrivateStates(
      _exportData: PrivateStateExport,
      _options?: ImportPrivateStatesOptions
    ): Promise<ImportPrivateStatesResult> {
      return { imported: 0 } as unknown as ImportPrivateStatesResult;
    },

    async exportSigningKeys(
      _options?: ExportSigningKeysOptions
    ): Promise<SigningKeyExport> {
      return { keys: [] } as unknown as SigningKeyExport;
    },
    async importSigningKeys(
      _exportData: SigningKeyExport,
      _options?: ImportSigningKeysOptions
    ): Promise<ImportSigningKeysResult> {
      return { imported: 0 } as unknown as ImportSigningKeysResult;
    },
  };
};

Step 9: Build the providers factory

Create api/src/providers.ts. This file assembles the full MidnightProviders object from a connected wallet and exports the wallet discovery and connection helpers that the frontend uses:

// dapp-connector-api v4 types. The package ships a proper ESM build so we can
// import from it directly without inlining the declarations.
import type {
  ConnectedAPI,
  InitialAPI,
} from "@midnight-ntwrk/dapp-connector-api";
import {
  Binding,
  type FinalizedTransaction,
  Proof,
  SignatureEnabled,
  Transaction,
  type TransactionId,
} from "@midnight-ntwrk/ledger-v8";
import { FetchZkConfigProvider } from "@midnight-ntwrk/midnight-js-fetch-zk-config-provider";
import { httpClientProofProvider } from "@midnight-ntwrk/midnight-js-http-client-proof-provider";
import { createProofProvider } from "@midnight-ntwrk/midnight-js-types";
import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
import { fromHex, toHex } from "@midnight-ntwrk/compact-runtime";
import { setNetworkId } from "@midnight-ntwrk/midnight-js-network-id";
import { inMemoryPrivateStateProvider } from "./in-memory-private-state-provider.js";
import type { UnboundTransaction } from "@midnight-ntwrk/midnight-js-types";

import {
  NotebookPrivateStateId,
  type NotebookCircuitKeys,
  type NotebookProviders,
} from "./common-types.js";

export type { ConnectedAPI, InitialAPI };

export type InjectedWallet = {
  uuid: string;
  name: string;
  icon: string;
  apiVersion: string;
  api: InitialAPI;
};

export type ConnectedWallet = {
  readonly connectedApi: ConnectedAPI;
};

// Discover all compliant Midnight wallets from window.midnight (multi-wallet
// discovery pattern, UUID keyed).
export const listInjectedWallets = (): InjectedWallet[] => {
  if (typeof window === "undefined") return [];
  const root = (window as unknown as { midnight?: Record<string, unknown> })
    .midnight;
  if (!root || typeof root !== "object") return [];

  const wallets: InjectedWallet[] = [];
  for (const [uuid, entry] of Object.entries(root)) {
    const w = entry as Partial<InitialAPI> & { uuid?: string };
    if (!w || typeof w !== "object" || !w.name) continue;
    wallets.push({
      uuid,
      name: w.name,
      icon: w.icon ?? "",
      apiVersion: w.apiVersion ?? "",
      api: w as InitialAPI,
    });
  }
  return wallets;
};

// Connect to the chosen wallet using the v4 connect(networkId) API.
export const connectWallet = async (
  wallet: InjectedWallet,
  networkId = "testnet"
): Promise<ConnectedWallet> => {
  const connectedApi = await wallet.api.connect(networkId);
  return { connectedApi };
};

// Build the full MidnightProviders set for a browser dApp using the v4 API.
export const createBrowserProviders = async (
  connected: ConnectedWallet
): Promise<NotebookProviders> => {
  const { connectedApi } = connected;

  const config = await connectedApi.getConfiguration();
  // Register the network ID globally so midnight-js SDK internals can read it.
  setNetworkId(config.networkId);
  const shieldedAddresses = await connectedApi.getShieldedAddresses();

  const keyMaterialProvider = new FetchZkConfigProvider<NotebookCircuitKeys>(
    window.location.origin,
    fetch.bind(window)
  );

  return {
    privateStateProvider: inMemoryPrivateStateProvider(),
    publicDataProvider: indexerPublicDataProvider(
      config.indexerUri,
      config.indexerWsUri
    ),
    zkConfigProvider: keyMaterialProvider,
    // Prefer the wallet's built-in proving provider (e.g. 1AM Proof Station).
    // Fall back to an HTTP proof server if the wallet config includes one.
    // Throw if neither is available so the error is explicit rather than silent.
    proofProvider: await (async () => {
      if (typeof connectedApi.getProvingProvider === "function") {
        // getProvingProvider returns a ProvingProvider (circuit-level check/prove).
        // The SDK's proofProvider slot expects a ProofProvider (proveTx). Wrap it.
        const provingProvider = await connectedApi.getProvingProvider(
          keyMaterialProvider
        );
        return createProofProvider(
          provingProvider as Parameters<typeof createProofProvider>[0]
        );
      }
      if (config.proverServerUri) {
        return httpClientProofProvider(
          config.proverServerUri,
          keyMaterialProvider
        );
      }
      throw new Error(
        "No proof provider available: the wallet does not expose a proving service " +
          "and no proverServerUri was found in the wallet configuration. " +
          "Run a local Midnight proof server on http://localhost:6300 and ensure " +
          "your wallet's configuration includes its address."
      );
    })(),
    walletProvider: {
      getCoinPublicKey(): string {
        return shieldedAddresses.shieldedCoinPublicKey;
      },
      getEncryptionPublicKey(): string {
        return shieldedAddresses.shieldedEncryptionPublicKey;
      },
      balanceTx: async (
        tx: UnboundTransaction,
        _ttl?: Date
      ): Promise<FinalizedTransaction> => {
        const serializedTx = toHex(tx.serialize());
        const received = await connectedApi.balanceUnsealedTransaction(
          serializedTx
        );
        return Transaction.deserialize<SignatureEnabled, Proof, Binding>(
          "signature",
          "proof",
          "binding",
          fromHex(received.tx)
        );
      },
    },
    midnightProvider: {
      submitTx: async (tx: FinalizedTransaction): Promise<TransactionId> => {
        await connectedApi.submitTransaction(toHex(tx.serialize()));
        const ids = tx.identifiers();
        return ids[0];
      },
    },
  } satisfies NotebookProviders;
};

Provider roles at a glance:

Provider	What it does
`privateStateProvider`	Holds the owner secret key in memory during the session
`publicDataProvider`	Reads on-chain state and streams updates over WebSocket
`zkConfigProvider`	Fetches `.verifier` and `.bzkir` key files from the Vite origin
`proofProvider`	Generates ZK proofs; wraps the wallet's `ProvingProvider` with `createProofProvider`
`walletProvider`	Balances (adds coin inputs) and deserializes signed transactions
`midnightProvider`	Submits finalized transactions and returns the transaction ID

⚠️WARNING
getProvingProvider() returns a ProvingProvider (circuit-level interface). The SDK's proofProvider slot needs a ProofProvider (transaction-level, with proveTx). Using as unknown as to cast hides the mismatch and produces "proveTx is not a function" at runtime. Always use createProofProvider() to convert between the two.

Step 10: Build the notebook API

Create api/src/notebook-api.ts. This module wraps deployContract and findDeployedContract and exposes the four operations the frontend needs:

import type { ContractAddress } from "@midnight-ntwrk/compact-runtime";
import {
  deployContract,
  findDeployedContract,
} from "@midnight-ntwrk/midnight-js-contracts";
import {
  CompiledNotebookContract,
  notebookLedger,
  createNotebookPrivateState,
  generateRandomSecretKey,
} from "@notebook/contract";
import type { NotebookPrivateState } from "@notebook/contract";
import { type Observable, map } from "rxjs";

import {
  NotebookPrivateStateId,
  type DeployedOrFoundNotebook,
  type NotebookAPI,
  type NotebookDerivedState,
  type NotebookProviders,
} from "./common-types.js";

const toHex = (bytes: Uint8Array): string =>
  Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");

const fromHex = (hex: string): Uint8Array => {
  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
  if (clean.length !== 64) {
    throw new Error(
      `Expected 32 byte hex string, got ${clean.length / 2} bytes`
    );
  }
  const out = new Uint8Array(32);
  for (let i = 0; i < 32; i += 1) {
    out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
  }
  return out;
};

const buildDerivedState = (ledgerState: {
  owner_commitment: Uint8Array;
  notes: { [Symbol.iterator](): IterableIterator<[Uint8Array, Uint8Array]> };
  note_count: bigint;
}): NotebookDerivedState => {
  const notes = new Map<string, string>();
  for (const [id, commitment] of ledgerState.notes) {
    notes.set(toHex(id), toHex(commitment));
  }
  return {
    ownerCommitment: ledgerState.owner_commitment,
    notes,
    noteCount: ledgerState.note_count,
  };
};

export const deployNotebook = async (
  providers: NotebookProviders,
  secretKey: Uint8Array = generateRandomSecretKey()
): Promise<{ api: NotebookAPI; secretKey: Uint8Array }> => {
  const deployed: DeployedOrFoundNotebook = await deployContract(providers, {
    compiledContract: CompiledNotebookContract,
    privateStateId: NotebookPrivateStateId,
    initialPrivateState: createNotebookPrivateState(secretKey),
  });
  const api = buildAPI(deployed, providers);
  return { api, secretKey };
};

export const joinNotebook = async (
  providers: NotebookProviders,
  contractAddress: ContractAddress,
  secretKey: Uint8Array
): Promise<NotebookAPI> => {
  const found: DeployedOrFoundNotebook = await findDeployedContract(providers, {
    contractAddress,
    compiledContract: CompiledNotebookContract,
    privateStateId: NotebookPrivateStateId,
    initialPrivateState: createNotebookPrivateState(secretKey),
  });
  return buildAPI(found, providers);
};

const buildAPI = (
  deployed: DeployedOrFoundNotebook,
  providers: NotebookProviders
): NotebookAPI => {
  const deployedContractAddress = deployed.deployTxData.public.contractAddress;

  const state$: Observable<NotebookDerivedState> = providers.publicDataProvider
    .contractStateObservable(deployedContractAddress, { type: "latest" })
    .pipe(
      map((contractState) => {
        const ledgerState = notebookLedger(contractState.data) as any;
        return buildDerivedState(ledgerState);
      })
    );

  const postNote = async (contentHash: Uint8Array): Promise<Uint8Array> => {
    const txData = await (deployed as any).callTx.post_note(contentHash);
    return txData.private.result as Uint8Array;
  };

  const deleteNote = async (noteId: Uint8Array): Promise<void> => {
    await (deployed as any).callTx.delete_note(noteId);
  };

  return {
    deployedContractAddress,
    state$,
    postNote,
    deleteNote,
  };
};

export { toHex, fromHex };

How deployContract works: It builds the deploy transaction, calls the ZK prover to generate a proof for the constructor circuit, sends the balanced transaction to the wallet to add coin inputs, submits it to the network, and resolves once it is confirmed. initialPrivateState carries the secret key into the in-memory private state store so the witness functions can read it during each circuit call.

How findDeployedContract works: It locates a contract that was deployed in a previous session by querying the indexer for the contract's current state. It does not redeploy; it simply reconnects and hydrates the local private state with the provided secret key. This is how the frontend reconnects to the same notebook after a page reload.

How the state observable works: contractStateObservable returns an RxJS Observable that emits whenever the on-chain contract state changes. The map operator converts the raw bytes into a NotebookDerivedState object with hex-encoded note IDs as map keys. The React context subscribes to this observable and re-renders on every emission. The subscription is torn down and re-created whenever the api object changes (for example, when the user switches to a different notebook), preventing stale subscriptions from leaking memory.

How callTx.post_note works: The SDK's callTx object is a proxy generated from the compiled contract's circuit list. Calling callTx.post_note(contentHash) triggers the full transaction lifecycle: construct the call arguments, run the witness functions to produce the secret key and nonce, generate the ZK proof, balance the transaction with coin inputs from the wallet, and submit. The resolved value includes txData.private.result, which holds the circuit's return value (the assigned note_id as a Uint8Array).

Finally, create api/src/index.ts to re-export everything from the three source files as a single import point:

export * from "./common-types.js";
export * from "./providers.js";
export * from "./notebook-api.js";

Step 11: Set up the SQLite database

Create backend/package.json. helmet and express-rate-limit are production dependencies, not dev dependencies, because they run in the Express process at runtime:

{
  "name": "@notebook/backend",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "dev": "tsx watch src/server.ts",
    "start": "node dist/server.js"
  },
  "dependencies": {
    "better-sqlite3": "^11.3.0",
    "cors": "^2.8.5",
    "express": "^4.21.0",
    "express-rate-limit": "^8.3.2",
    "helmet": "^8.1.0"
  },
  "devDependencies": {
    "@types/better-sqlite3": "^7.6.11",
    "@types/cors": "^2.8.17",
    "@types/express": "^5.0.0",
    "@types/node": "^22.0.0",
    "tsx": "^4.19.0",
    "typescript": "^5.6.0"
  }
}

Create backend/tsconfig.json. The types: ["node"] entry pulls in Node.js built-in type declarations so process, Buffer, and import.meta resolve correctly:

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "lib": ["ES2022"],
    "types": ["node"]
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Create backend/src/db.ts:

import Database, { type Database as DatabaseInstance } from "better-sqlite3";
import { mkdirSync } from "node:fs";
import { dirname } from "node:path";

// Single SQLite file shared by all routes. Keyed by (contractAddress, commitment)
// so one backend instance can serve multiple deployed notebooks without collisions.
const DB_PATH = process.env.NOTEBOOK_DB_PATH ?? "./data/notebook.sqlite";

mkdirSync(dirname(DB_PATH), { recursive: true });

export const db: DatabaseInstance = new Database(DB_PATH);
db.pragma("journal_mode = WAL");

db.exec(`
  CREATE TABLE IF NOT EXISTS notes (
    contract_address TEXT NOT NULL,
    commitment TEXT NOT NULL,
    ciphertext TEXT NOT NULL,
    created_at INTEGER NOT NULL,
    PRIMARY KEY (contract_address, commitment)
  );
`);

export type NoteRow = {
  contract_address: string;
  commitment: string;
  ciphertext: string;
  created_at: number;
};

The primary key is (contract_address, commitment). Using the contract address as part of the key means a single backend instance can serve multiple deployed notebooks without any row collisions. WAL journal mode allows concurrent reads while a write is in progress.

Step 12: Write the backend routes

Create backend/src/routes/notes.ts:

import { createHash } from "node:crypto";
import {
  Router,
  type Request,
  type Response,
  type RequestHandler,
} from "express";
import { db, type NoteRow } from "../db.js";

export const notesRouter: Router = Router();

// Basic hex validation. Commitments and ids are 32 byte values encoded as 64
// lowercase hex characters. Contract addresses are opaque strings so we only
// cap their length.
const HEX32 = /^[0-9a-f]{64}$/;
const MAX_ADDR_LEN = 128;
const MAX_CIPHERTEXT_BYTES = 128 * 1024; // 128 KB per note body is plenty.

const isHex32 = (s: unknown): s is string =>
  typeof s === "string" && HEX32.test(s);
const isAddress = (s: unknown): s is string =>
  typeof s === "string" && s.length > 0 && s.length <= MAX_ADDR_LEN;

// Compute SHA-256 of the raw ciphertext bytes and return lowercase hex. This
// lets clients supply any deterministic commitment scheme they want; we just
// echo what we stored so the UI can confirm the round trip.
const sha256Hex = (input: string): string =>
  createHash("sha256").update(input, "utf8").digest("hex");

// POST /api/notes
// body: { contractAddress, commitment, ciphertext }
const postNote: RequestHandler = (req: Request, res: Response) => {
  const { contractAddress, commitment, ciphertext } = req.body ?? {};

  if (!isAddress(contractAddress)) {
    res
      .status(400)
      .json({ error: "contractAddress must be a non-empty string" });
    return;
  }
  if (!isHex32(commitment)) {
    res
      .status(400)
      .json({ error: "commitment must be 64 lowercase hex chars" });
    return;
  }
  if (typeof ciphertext !== "string" || ciphertext.length === 0) {
    res.status(400).json({ error: "ciphertext must be a non-empty string" });
    return;
  }
  if (Buffer.byteLength(ciphertext, "utf8") > MAX_CIPHERTEXT_BYTES) {
    res.status(413).json({ error: "ciphertext too large" });
    return;
  }

  const serverDigest = sha256Hex(ciphertext);

  if (serverDigest !== commitment) {
    res.status(400).json({
      error: "commitment does not match SHA-256 of ciphertext",
    });
    return;
  }

  // Content-addressed storage: if the same (contractAddress, commitment) key
  // already exists the ciphertext is identical by construction (same hash), so
  // we skip the write rather than replacing the existing row.
  const info = db
    .prepare(
      `INSERT OR IGNORE INTO notes (contract_address, commitment, ciphertext, created_at)
     VALUES (?, ?, ?, ?)`
    )
    .run(contractAddress, commitment, ciphertext, Date.now());

  res.status(info.changes === 0 ? 200 : 201).json({
    contractAddress,
    commitment,
    serverDigest,
    digestMatches: true,
  });
};

// GET /api/notes/:contractAddress/:commitment
const getNote: RequestHandler = (req: Request, res: Response) => {
  const { contractAddress, commitment } = req.params;
  if (!isAddress(contractAddress) || !isHex32(commitment)) {
    res.status(400).json({ error: "invalid params" });
    return;
  }

  const row = db
    .prepare(
      `SELECT contract_address, commitment, ciphertext, created_at
       FROM notes WHERE contract_address = ? AND commitment = ?`
    )
    .get(contractAddress, commitment) as NoteRow | undefined;

  if (!row) {
    res.status(404).json({ error: "not found" });
    return;
  }

  res.json({
    contractAddress: row.contract_address,
    commitment: row.commitment,
    ciphertext: row.ciphertext,
    createdAt: row.created_at,
  });
};

// DELETE /api/notes/:contractAddress/:commitment
const deleteNote: RequestHandler = (req: Request, res: Response) => {
  const { contractAddress, commitment } = req.params;
  if (!isAddress(contractAddress) || !isHex32(commitment)) {
    res.status(400).json({ error: "invalid params" });
    return;
  }

  const info = db
    .prepare(`DELETE FROM notes WHERE contract_address = ? AND commitment = ?`)
    .run(contractAddress, commitment);

  if (info.changes === 0) {
    res.status(404).json({ error: "not found" });
    return;
  }
  res.status(204).end();
};

notesRouter.post("/", postNote);
notesRouter.get("/:contractAddress/:commitment", getNote);
notesRouter.delete("/:contractAddress/:commitment", deleteNote);

The POST handler enforces commitment integrity on the server side. It recomputes SHA-256(ciphertext) and compares the result to the client-supplied commitment. If they do not match, it returns 400 and refuses to store anything. This prevents a scenario where an attacker who knows a valid on-chain commitment tries to substitute different content: the server rejects the write because the hash of the submitted body will not equal the real commitment.

The INSERT OR IGNORE statement replaces the earlier INSERT OR REPLACE. Content-addressed storage guarantees that the same (contractAddress, commitment) pair always maps to the same bytes (same hash means same content). If the row already exists, the write is skipped silently and the response returns 200. If it is new, the row is inserted and the response returns 201. There is no case where replacing the existing data makes sense.

Notice that the backend does not perform user authentication. There is no JWT, no API key, and no session. Ownership is already enforced on-chain: only the owner's ZK proof can insert a note into the notes map. The backend is a content-addressed store, not an authority. The commitment integrity check above is what keeps stored content honest.

Step 13: Write the Express server

Create backend/src/server.ts:

import cors from "cors";
import express from "express";
import helmet from "helmet";
import { rateLimit } from "express-rate-limit";
import { notesRouter } from "./routes/notes.js";

const app = express();

// Security headers: X-Content-Type-Options, X-Frame-Options, HSTS, etc.
app.use(helmet());

// Allow the Vite dev origin by default. In production, set BACKEND_CORS_ORIGIN
// to the deployed frontend origin (or a comma separated list).
const corsOrigin = (process.env.BACKEND_CORS_ORIGIN ?? "http://localhost:3000")
  .split(",")
  .map((s) => s.trim())
  .filter(Boolean);

app.use(cors({ origin: corsOrigin }));
app.use(express.json({ limit: "256kb" }));

// Rate limit: 120 requests per 15 minutes per IP across all endpoints.
// POST and DELETE are also limited individually below.
const globalLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  limit: 120,
  standardHeaders: "draft-8",
  legacyHeaders: false,
});
app.use(globalLimiter);

// Stricter limit on write operations (POST, DELETE) to slow down abuse.
const writeLimiter = rateLimit({
  windowMs: 60 * 1000,
  limit: 20,
  standardHeaders: "draft-8",
  legacyHeaders: false,
});

app.get("/healthz", (_req, res) => {
  res.json({ ok: true });
});

// Apply the write limiter before routing POST and DELETE inside the notes router.
app.post("/api/notes", writeLimiter);
app.delete("/api/notes/*path", writeLimiter);
app.use("/api/notes", notesRouter);

const PORT = Number.parseInt(process.env.PORT ?? "3001", 10);
app.listen(PORT, () => {
  console.log(`Notebook backend listening on http://localhost:${PORT}`);
  console.log(`CORS allowed origins: ${corsOrigin.join(", ")}`);
});

helmet() sets a handful of HTTP security headers in one call: X-Content-Type-Options: nosniff (prevents MIME sniffing), X-Frame-Options: DENY (prevents clickjacking), Strict-Transport-Security (HSTS for production), and several others. Adding it takes one line and closes a class of browser-level attacks with no application logic changes.

The two rate limiters operate at different scopes. The global limiter of 120 requests per 15 minutes per IP applies to every route, including the health check. The write limiter of 20 requests per minute per IP applies only to POST and DELETE, which are the operations that trigger on-chain transactions. These limits are generous for a single user but sufficient to slow down anyone trying to spam the backend. The write limiter is registered directly on app.post and app.delete before the router is mounted, so it runs before the route handler regardless of which path inside the router is matched.

Start the backend in a dedicated terminal:

npm run dev:backend

You should see Notebook backend listening on http://localhost:3001. The server uses tsx watch so it reloads automatically on file changes.

Step 14: Write the frontend crypto helpers

Create frontend/package.json. The frontend depends on both @notebook/api and @notebook/contract (using "*" to always resolve to the local workspace version), as well as the full set of Midnight SDK packages that Vite needs to bundle for the browser:

{
  "name": "@notebook/frontend",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -p tsconfig.json && vite build",
    "preview": "vite preview --port 3000"
  },
  "dependencies": {
    "@notebook/api": "*",
    "@notebook/contract": "*",
    "@midnight-ntwrk/compact-js": "^2.5.0",
    "@midnight-ntwrk/compact-runtime": "^0.15.0",
    "@midnight-ntwrk/dapp-connector-api": "^4.0.1",
    "@midnight-ntwrk/ledger-v8": "^8.0.3",
    "@midnight-ntwrk/midnight-js-contracts": "^4.0.4",
    "@midnight-ntwrk/midnight-js-fetch-zk-config-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-level-private-state-provider": "^4.0.4",
    "@midnight-ntwrk/midnight-js-network-id": "^4.0.4",
    "@midnight-ntwrk/midnight-js-types": "^4.0.4",
    "@midnight-ntwrk/midnight-js-utils": "^4.0.4",
    "@midnight-ntwrk/wallet-sdk-address-format": "^3.0.1",
    "events": "^3.3.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "rxjs": "^7.8.1",
    "semver": "^7.6.3"
  },
  "devDependencies": {
    "@types/react": "^18.3.10",
    "@types/react-dom": "^18.3.0",
    "@types/semver": "^7.5.8",
    "@vitejs/plugin-react": "^6.0.1",
    "typescript": "^5.6.0",
    "vite": "^8.0.0",
    "vite-plugin-node-polyfills": "^0.26.0",
    "vite-plugin-top-level-await": "^1.6.0",
    "vite-plugin-wasm": "^3.6.0"
  }
}

Create frontend/tsconfig.json. The jsx: "react-jsx" option enables the React 18 automatic JSX transform so you do not need to import React in every file. noEmit: true means TypeScript only type-checks; Vite handles the actual compilation and bundling:

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx",
    "types": ["vite/client"],
    "noEmit": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

Create frontend/src/lib/crypto.ts. These small utilities handle SHA-256 hashing, hex encoding, and per-browser secret key persistence:

// Small helpers for the browser side. Note that the on-chain content_hash
// must match what the contract expects (32 bytes). We commit to the raw
// ciphertext with SHA-256, which the backend also recomputes so the UI can
// verify the round trip.

export const sha256Bytes = async (s: string): Promise<Uint8Array> => {
  const enc = new TextEncoder();
  const buf = await crypto.subtle.digest("SHA-256", enc.encode(s));
  return new Uint8Array(buf);
};

export const toHex = (bytes: Uint8Array): string =>
  Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");

export const fromHex = (hex: string): Uint8Array => {
  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
  if (clean.length % 2 !== 0) throw new Error("odd length hex");
  const out = new Uint8Array(clean.length / 2);
  for (let i = 0; i < out.length; i += 1) {
    out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
  }
  return out;
};

// Generate 32 random bytes using the browser RNG. Used for the owner secret
// key. We persist the result in IndexedDB via the private state provider, so
// the user does not need to re-enter it across sessions.
export const randomBytes = (len = 32): Uint8Array => {
  const buf = new Uint8Array(len);
  crypto.getRandomValues(buf);
  return buf;
};

// Very small localStorage backed store for the per-browser owner secret key.
// This is not a secure vault: it's the simplest thing that survives reloads so
// the tutorial reader can reconnect to the same notebook.
const SECRET_KEY_STORAGE_KEY = "notebook.ownerSecretKey";

export const loadOrCreateSecretKey = (): Uint8Array => {
  const existing = localStorage.getItem(SECRET_KEY_STORAGE_KEY);
  if (existing) return fromHex(existing);
  const fresh = randomBytes(32);
  localStorage.setItem(SECRET_KEY_STORAGE_KEY, toHex(fresh));
  return fresh;
};

export const clearSecretKey = (): void => {
  localStorage.removeItem(SECRET_KEY_STORAGE_KEY);
};

⚠️ WARNING
localStorage is convenient for a tutorial, but is not a secure vault. Anyone with access to the browser developer tools can read the key. For production, derive the key from the wallet's signing material or use a dedicated key management solution.

Step 15: Write the backend client

Create frontend/src/lib/backend-client.ts. This thin wrapper handles all HTTP calls to the Express backend:

// Thin wrapper around the off-chain backend. Note bodies live here; the chain
// only ever sees the commitment hash.

export type StoredNote = {
  contractAddress: string;
  commitment: string;
  ciphertext: string;
  createdAt: number;
};

const BASE = "/api/notes";

export const backendClient = {
  async putNote(
    contractAddress: string,
    commitment: string,
    ciphertext: string
  ) {
    const res = await fetch(BASE, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ contractAddress, commitment, ciphertext }),
    });
    if (!res.ok) throw new Error(`backend putNote failed: ${res.status}`);
    return (await res.json()) as {
      contractAddress: string;
      commitment: string;
      serverDigest: string;
      digestMatches: boolean;
    };
  },

  async getNote(
    contractAddress: string,
    commitment: string
  ): Promise<StoredNote | null> {
    const res = await fetch(
      `${BASE}/${encodeURIComponent(contractAddress)}/${encodeURIComponent(
        commitment
      )}`
    );
    if (res.status === 404) return null;
    if (!res.ok) throw new Error(`backend getNote failed: ${res.status}`);
    return (await res.json()) as StoredNote;
  },

  async deleteNote(contractAddress: string, commitment: string) {
    const res = await fetch(
      `${BASE}/${encodeURIComponent(contractAddress)}/${encodeURIComponent(
        commitment
      )}`,
      { method: "DELETE" }
    );
    if (res.status !== 204 && res.status !== 404) {
      throw new Error(`backend deleteNote failed: ${res.status}`);
    }
  },
};

The /api/notes base path works in development because vite.config.ts proxies all /api requests to http://localhost:3001.

Step 16: Write the wallet context

Create frontend/src/contexts/WalletContext.tsx. This context discovers injected wallets, filters to v4-compatible ones, and manages the connection lifecycle:

import React, {
  createContext,
  useCallback,
  useContext,
  useEffect,
  useMemo,
  useState,
} from "react";
import semver from "semver";
import {
  listInjectedWallets,
  connectWallet,
  createBrowserProviders,
  type ConnectedWallet,
  type InjectedWallet,
  type NotebookProviders,
} from "@notebook/api";

// Only wallets that implement the v4 connector API are supported.
const COMPATIBLE_VERSION = "4.x";

// Read from VITE_NETWORK_ID env var. Defaults to "preprod" for the 1AM wallet.
const NETWORK_ID: string =
  (import.meta.env.VITE_NETWORK_ID as string | undefined) ?? "preprod";

type WalletState = {
  available: InjectedWallet[];
  connected: ConnectedWallet | null;
  providers: NotebookProviders | null;
  coinPublicKey: string | null;
  status: "idle" | "connecting" | "connected" | "error";
  error: string | null;
};

type WalletContextValue = WalletState & {
  refresh: () => void;
  connect: (wallet: InjectedWallet) => Promise<void>;
};

const WalletContext = createContext<WalletContextValue | null>(null);

export const WalletProvider: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  const [state, setState] = useState<WalletState>({
    available: [],
    connected: null,
    providers: null,
    coinPublicKey: null,
    status: "idle",
    error: null,
  });

  // Filter injected wallets to only show v4-compatible ones.
  const getCompatible = (): InjectedWallet[] =>
    listInjectedWallets().filter(
      (w) => w.apiVersion && semver.satisfies(w.apiVersion, COMPATIBLE_VERSION)
    );

  const refresh = useCallback(() => {
    setState((prev) => ({ ...prev, available: getCompatible() }));
  }, []);

  // Wallet extensions inject window.midnight asynchronously. Poll until a
  // compatible wallet appears or until 20 attempts have elapsed.
  useEffect(() => {
    let attempts = 0;
    const timer = setInterval(() => {
      const wallets = getCompatible();
      setState((prev) => ({ ...prev, available: wallets }));
      attempts += 1;
      if (wallets.length > 0 || attempts > 20) clearInterval(timer);
    }, 250);
    return () => clearInterval(timer);
  }, []);

  const connect = useCallback(async (wallet: InjectedWallet) => {
    setState((prev) => ({ ...prev, status: "connecting", error: null }));
    try {
      const connected = await connectWallet(wallet, NETWORK_ID);
      const providers = await createBrowserProviders(connected);
      const shieldedAddresses =
        await connected.connectedApi.getShieldedAddresses();
      setState({
        available: getCompatible(),
        connected,
        providers,
        coinPublicKey: shieldedAddresses.shieldedCoinPublicKey,
        status: "connected",
        error: null,
      });
    } catch (err) {
      const raw = err instanceof Error ? err.message : String(err);
      const isShutdown =
        raw.includes("shutdown") ||
        raw.includes("Could not establish connection") ||
        raw.includes("Receiving end does not exist");
      setState((prev) => ({
        ...prev,
        status: "error",
        error: isShutdown
          ? "Wallet extension became unresponsive. Open the wallet popup to wake it, then click Connect again."
          : raw,
      }));
    }
  }, []);

  const value = useMemo<WalletContextValue>(
    () => ({ ...state, refresh, connect }),
    [state, refresh, connect]
  );

  return (
    <WalletContext.Provider value={value}>{children}</WalletContext.Provider>
  );
};

export const useWallet = (): WalletContextValue => {
  const ctx = useContext(WalletContext);
  if (!ctx) throw new Error("useWallet must be used inside <WalletProvider>");
  return ctx;
};

The polling loop runs every 250 ms for up to 5 seconds (20 attempts). This handles the race between React mounting and the wallet extension injecting window.midnight. The COMPATIBLE_VERSION = "4.x" semver filter ensures only wallets that implement the v4 connector API appear in the list.

The v4 connector API uses a multi-wallet discovery pattern where window.midnight is a UUID-keyed object rather than a single named entry. Any compliant wallet is discovered automatically without wallet-specific code. The UUID is the wallet's unique identifier and changes per install; using it as a React key prevents stale renders when multiple wallets are present.

The connect function intentionally catches the class of errors produced when the wallet extension becomes unresponsive. These errors ("Receiving end does not exist", "Could not establish connection") happen when the wallet popup closes while the page is still awaiting a response from the extension's message port. The user-facing message tells the person to open the wallet popup before retrying, which re-establishes the message port.

Step 17: Write the notebook context

Create frontend/src/contexts/NotebookContext.tsx. This context wraps the API layer with React state and handles deploy, join, post, and delete operations:

import React, {
  createContext,
  useCallback,
  useContext,
  useEffect,
  useMemo,
  useRef,
  useState,
} from "react";
import {
  deployNotebook,
  joinNotebook,
  type NotebookAPI,
  type NotebookDerivedState,
} from "@notebook/api";
import { useWallet } from "./WalletContext.js";
import {
  fromHex,
  loadOrCreateSecretKey,
  sha256Bytes,
  toHex,
} from "../lib/crypto.js";
import { backendClient } from "../lib/backend-client.js";

type Status = "idle" | "busy" | "ready" | "error";

type NotebookContextValue = {
  api: NotebookAPI | null;
  derived: NotebookDerivedState | null;
  status: Status;
  error: string | null;
  deploy: () => Promise<void>;
  join: (address: string) => Promise<void>;
  postNote: (body: string) => Promise<void>;
  deleteNote: (noteId: string) => Promise<void>;
  disconnect: () => void;
};

const NotebookContext = createContext<NotebookContextValue | null>(null);

const LAST_ADDRESS_KEY = "notebook.lastContractAddress";

export const NotebookProvider: React.FC<{ children: React.ReactNode }> = ({
  children,
}) => {
  const { providers, status: walletStatus } = useWallet();
  const [api, setApi] = useState<NotebookAPI | null>(null);
  const [derived, setDerived] = useState<NotebookDerivedState | null>(null);
  const [status, setStatus] = useState<Status>("idle");
  const [error, setError] = useState<string | null>(null);
  const subscriptionRef = useRef<{ unsubscribe: () => void } | null>(null);

  // Teardown the state subscription when the API is replaced or on unmount.
  useEffect(() => {
    subscriptionRef.current?.unsubscribe();
    subscriptionRef.current = null;
    if (!api) {
      setDerived(null);
      return;
    }
    const sub = api.state$.subscribe({
      next: (s) => setDerived(s),
      error: (e) => setError(e instanceof Error ? e.message : String(e)),
    });
    subscriptionRef.current = sub;
    return () => sub.unsubscribe();
  }, [api]);

  const deploy = useCallback(async () => {
    if (!providers) {
      setError("Connect a wallet first");
      return;
    }
    setStatus("busy");
    setError(null);
    try {
      const secretKey = loadOrCreateSecretKey();
      const { api: fresh } = await deployNotebook(providers, secretKey);
      localStorage.setItem(LAST_ADDRESS_KEY, fresh.deployedContractAddress);
      setApi(fresh);
      setStatus("ready");
    } catch (err) {
      setStatus("error");
      setError(err instanceof Error ? err.message : String(err));
    }
  }, [providers]);

  const join = useCallback(
    async (address: string) => {
      if (!providers) {
        setError("Connect a wallet first");
        return;
      }
      setStatus("busy");
      setError(null);
      try {
        const secretKey = loadOrCreateSecretKey();
        const fresh = await joinNotebook(providers, address, secretKey);
        localStorage.setItem(LAST_ADDRESS_KEY, address);
        setApi(fresh);
        setStatus("ready");
      } catch (err) {
        setStatus("error");
        setError(err instanceof Error ? err.message : String(err));
      }
    },
    [providers]
  );

  // When the wallet becomes ready, try to auto-rejoin the most recently used
  // notebook. This is optional convenience, not a requirement.
  useEffect(() => {
    if (walletStatus !== "connected" || !providers || api) return;
    const saved = localStorage.getItem(LAST_ADDRESS_KEY);
    if (!saved) return;
    void join(saved).catch(() => {
      // Silent: the saved address may belong to a different network or have been
      // removed. The user can still deploy a fresh notebook from the UI.
    });
  }, [walletStatus, providers, api, join]);

  const postNote = useCallback(
    async (body: string) => {
      if (!api) throw new Error("No notebook ready");
      setStatus("busy");
      setError(null);
      try {
        const commitment = await sha256Bytes(body);
        const commitmentHex = toHex(commitment);
        // Store the body off-chain first. If the on-chain call later fails the
        // body is already safe in the backend (no orphaned on-chain note without
        // a retrievable body). The reverse order risks losing the body if the
        // circuit call times out or is rejected after the tx lands.
        await backendClient.putNote(
          api.deployedContractAddress,
          commitmentHex,
          body
        );
        const noteId = await api.postNote(commitment);
        const noteIdHex = toHex(noteId);
        // Patch local state so the note appears without waiting for the next
        // WebSocket emission. Guard against double-counting: if the indexer
        // pushed the update before this line ran, the note is already present.
        setDerived((prev) => {
          if (!prev || prev.notes.has(noteIdHex)) return prev;
          const notes = new Map(prev.notes);
          notes.set(noteIdHex, commitmentHex);
          return { ...prev, notes, noteCount: prev.noteCount + 1n };
        });
        setStatus("ready");
      } catch (err) {
        setStatus("error");
        setError(err instanceof Error ? err.message : String(err));
      }
    },
    [api]
  );

  const deleteNote = useCallback(
    async (noteIdHex: string) => {
      if (!api || !derived) throw new Error("No notebook ready");
      setStatus("busy");
      setError(null);
      try {
        const commitmentHex = derived.notes.get(noteIdHex);
        await api.deleteNote(fromHex(noteIdHex));
        // Patch local state so the note disappears without waiting for the next
        // WebSocket emission. Guard: if the indexer already removed it, skip.
        setDerived((prev) => {
          if (!prev || !prev.notes.has(noteIdHex)) return prev;
          const notes = new Map(prev.notes);
          notes.delete(noteIdHex);
          return { ...prev, notes, noteCount: prev.noteCount - 1n };
        });
        if (commitmentHex) {
          await backendClient.deleteNote(
            api.deployedContractAddress,
            commitmentHex
          );
        }
        setStatus("ready");
      } catch (err) {
        setStatus("error");
        setError(err instanceof Error ? err.message : String(err));
      }
    },
    [api, derived]
  );

  const disconnect = useCallback(() => {
    localStorage.removeItem(LAST_ADDRESS_KEY);
    setApi(null);
    setDerived(null);
    setStatus("idle");
    setError(null);
  }, []);

  const value = useMemo<NotebookContextValue>(
    () => ({
      api,
      derived,
      status,
      error,
      deploy,
      join,
      postNote,
      deleteNote,
      disconnect,
    }),
    [
      api,
      derived,
      status,
      error,
      deploy,
      join,
      postNote,
      deleteNote,
      disconnect,
    ]
  );

  return (
    <NotebookContext.Provider value={value}>
      {children}
    </NotebookContext.Provider>
  );
};

export const useNotebook = (): NotebookContextValue => {
  const ctx = useContext(NotebookContext);
  if (!ctx)
    throw new Error("useNotebook must be used inside <NotebookProvider>");
  return ctx;
};

The backend-first ordering in postNote is critical. The backend call runs before api.postNote(). If the ordering were reversed and the on-chain transaction confirmed before the backend write, you would have a note hash on-chain with no retrievable body. The UI would show "(body not in backend)" and the note would be unreadable. Storing the body first guarantees it is always available by the time the chain state update propagates.

Why postNote and deleteNote patch derived directly. The state$ observable receives updates via WebSocket from the indexer. In practice, the indexer push can arrive with a delay or miss the update entirely during the current session. Without the local patch, a note would not appear in the UI until the next WebSocket emission, which may require a page refresh. Both functions receive enough information at the point the transaction resolves (noteId from postNote, noteIdHex from the caller for deleteNote) to update the local map immediately.

Each patch is idempotent: the setDerived updater checks whether the note is already present in the map (using prev.notes.has(noteIdHex)) before modifying anything. When the indexer push is fast and arrives before the await resolves, the observable already updated derived with the correct state. The guard detects this and returns prev unchanged, preventing a double-count. When the push is slow or missing, the guard condition is false and the patch runs as intended.

Step 18: Write the UI components

The three UI components follow a layered pattern: each one reads from a context hook and renders based on state, with no business logic of its own. All the async work (connecting, deploying, posting) happens in the context hooks. This keeps the components simple and easy to test.

ConnectWallet

ConnectWallet shows a list of available wallets before connection and switches to a confirmation card once connected. It reads from WalletContext and delegates all work to the connect and refresh functions the context exposes. Create frontend/src/components/ConnectWallet.tsx:

import React from "react";
import { useWallet } from "../contexts/WalletContext.js";

// Only allow safe image sources from wallet metadata to prevent javascript: URIs.
const isSafeIconUrl = (url: string): boolean =>
  url.startsWith("https://") || url.startsWith("data:image/");

export const ConnectWallet: React.FC = () => {
  const {
    available,
    connected,
    coinPublicKey,
    status,
    error,
    connect,
    refresh,
  } = useWallet();

  if (connected) {
    return (
      <div className="card">
        <h3>Wallet connected</h3>
        <p className="muted">Coin public key:</p>
        <p className="mono">{coinPublicKey}</p>
      </div>
    );
  }

  return (
    <div className="card">
      <h3>Connect a Midnight wallet</h3>
      {available.length === 0 ? (
        <>
          <p className="muted">
            No injected wallet detected. Install the 1AM wallet and reload this
            page.
          </p>
          <button className="secondary" onClick={refresh}>
            Scan again
          </button>
        </>
      ) : (
        <div>
          {available.map((w) => (
            <div key={w.uuid} className="wallet-row">
              {w.icon && isSafeIconUrl(w.icon) ? (
                <img src={w.icon} alt="" />
              ) : null}
              <div style={{ flex: 1 }}>
                <div>
                  <strong>{w.name}</strong>
                  <span className="muted"> v{w.apiVersion}</span>
                </div>
              </div>
              <button
                onClick={() => connect(w)}
                disabled={status === "connecting"}
              >
                {status === "connecting" ? "Connecting..." : "Connect"}
              </button>
            </div>
          ))}
        </div>
      )}
      {error ? <p className="error">{error}</p> : null}
    </div>
  );
};

DeployJoin

DeployJoin is invisible until the wallet is connected (it returns null when connected is falsy). Once the wallet is ready, it offers two paths: deploy a fresh notebook owned by this browser, or join an existing one by pasting a contract address. After a successful deploy or join, the component switches to a confirmation card showing the contract address and a "Switch notebook" button that clears the state. Create frontend/src/components/DeployJoin.tsx:

import React, { useState } from "react";
import { useNotebook } from "../contexts/NotebookContext.js";
import { useWallet } from "../contexts/WalletContext.js";

export const DeployJoin: React.FC = () => {
  const { connected } = useWallet();
  const { api, status, error, deploy, join, disconnect } = useNotebook();
  const [address, setAddress] = useState("");

  if (!connected) return null;

  if (api) {
    return (
      <div className="card">
        <h3>Notebook ready</h3>
        <p className="muted">Contract address:</p>
        <p className="mono">{api.deployedContractAddress}</p>
        <button className="secondary" onClick={disconnect}>
          Switch notebook
        </button>
      </div>
    );
  }

  return (
    <div className="card">
      <h3>Deploy or join a notebook</h3>
      <p className="muted">
        Deploy a brand new notebook owned by this browser, or paste an existing
        contract address to rejoin one you deployed earlier.
      </p>

      <div style={{ margin: "1rem 0" }}>
        <button onClick={deploy} disabled={status === "busy"}>
          {status === "busy" ? "Deploying..." : "Deploy new notebook"}
        </button>
      </div>

      <div>
        <label htmlFor="addr" className="muted">
          Existing contract address
        </label>
        <input
          id="addr"
          value={address}
          onChange={(e) => setAddress(e.target.value)}
          placeholder="0x..."
        />
        <div style={{ marginTop: "0.5rem" }}>
          <button
            className="secondary"
            disabled={status === "busy" || address.length === 0}
            onClick={() => join(address.trim())}
          >
            Join
          </button>
        </div>
      </div>

      {error ? <p className="error">{error}</p> : null}
    </div>
  );
};

NoteList

NoteList is the most complex component. It subscribes indirectly to the on-chain state through NotebookContext, and whenever derived updates (meaning a new note was posted, or a note was deleted, or the chain confirmed a previous transaction), it fetches the body for every note from the backend. The commitment comparison inside the effect is the end-to-end integrity check: a note that was tampered with in the backend would produce a digest that does not match the on-chain commitment, and the mismatch badge would appear immediately. Create frontend/src/components/NoteList.tsx:

import React, { useEffect, useState } from "react";
import { useNotebook } from "../contexts/NotebookContext.js";
import { backendClient } from "../lib/backend-client.js";

type NoteView = {
  noteId: string;
  commitment: string;
  body: string | null;
  matches: boolean | null;
  createdAt: number | null;
};

export const NoteList: React.FC = () => {
  const { api, derived, status, error, postNote, deleteNote } = useNotebook();
  const [draft, setDraft] = useState("");
  const [notes, setNotes] = useState<NoteView[]>([]);

  // Every time on-chain state refreshes, fetch any missing bodies from the
  // backend. The commitment comparison below proves the body we got back is
  // the one that was committed on-chain.
  useEffect(() => {
    if (!api || !derived) {
      setNotes([]);
      return;
    }
    let cancelled = false;
    (async () => {
      const entries = Array.from(derived.notes.entries());
      const views = await Promise.all(
        entries.map(async ([noteId, commitment]) => {
          try {
            const row = await backendClient.getNote(
              api.deployedContractAddress,
              commitment
            );
            if (!row) {
              return {
                noteId,
                commitment,
                body: null,
                matches: null,
                createdAt: null,
              };
            }
            // Recompute the digest locally to confirm the backend returned the
            // same bytes that are committed on chain.
            const digest = await sha256Hex(row.ciphertext);
            return {
              noteId,
              commitment,
              body: row.ciphertext,
              matches: digest === commitment,
              createdAt: row.createdAt,
            };
          } catch {
            return {
              noteId,
              commitment,
              body: null,
              matches: null,
              createdAt: null,
            };
          }
        })
      );
      // Newest first: notes with no backend row (just locally patched) sort to
      // the top since they were just created.
      views.sort((a, b) => {
        if (a.createdAt === null && b.createdAt === null) return 0;
        if (a.createdAt === null) return -1;
        if (b.createdAt === null) return 1;
        return b.createdAt - a.createdAt;
      });
      if (!cancelled) setNotes(views);
    })();
    return () => {
      cancelled = true;
    };
  }, [api, derived]);

  if (!api || !derived) return null;

  return (
    <div className="card">
      <h3>Notes ({String(derived.noteCount)})</h3>

      <div style={{ margin: "1rem 0" }}>
        <textarea
          value={draft}
          onChange={(e) => setDraft(e.target.value)}
          placeholder="Write a private note. Its body stays off-chain; only a commitment hash gets posted."
        />
        <div style={{ marginTop: "0.5rem" }}>
          <button
            disabled={status === "busy" || draft.length === 0}
            onClick={async () => {
              await postNote(draft);
              setDraft("");
            }}
          >
            {status === "busy" ? "Posting..." : "Post note"}
          </button>
        </div>
      </div>

      {notes.length === 0 ? (
        <p className="muted">No notes yet. Post your first one above.</p>
      ) : (
        notes.map((n) => (
          <div className="note" key={n.noteId}>
            <div style={{ flex: 1 }}>
              <div>
                {n.body ?? <span className="muted">(body not in backend)</span>}
              </div>
              <div className="muted mono">
                note_id {n.noteId.slice(0, 16)}...
              </div>
              <div className="muted mono">
                commitment {n.commitment.slice(0, 16)}...
              </div>
              {n.matches === true ? (
                <div className="success">
                  verified: body matches on-chain commitment
                </div>
              ) : n.matches === false ? (
                <div className="error">
                  mismatch: body does not match on-chain commitment
                </div>
              ) : null}
            </div>
            <button
              className="danger"
              disabled={status === "busy"}
              onClick={() => deleteNote(n.noteId)}
            >
              Delete
            </button>
          </div>
        ))
      )}

      {error ? <p className="error">{error}</p> : null}
    </div>
  );
};

const sha256Hex = async (s: string): Promise<string> => {
  const buf = await crypto.subtle.digest(
    "SHA-256",
    new TextEncoder().encode(s)
  );
  return Array.from(new Uint8Array(buf), (b) =>
    b.toString(16).padStart(2, "0")
  ).join("");
};

NoteList re-fetches note bodies whenever the on-chain state observable emits a new value. For each note it fetches the body from the backend and recomputes the SHA-256 digest locally. When the digest matches the on-chain commitment, it shows "verified: body matches on-chain commitment". This proves the backend returned exactly the bytes that were committed.

Step 19: Wire up the React entry point

Create frontend/src/App.tsx:

import React from "react";
import { ConnectWallet } from "./components/ConnectWallet.js";
import { DeployJoin } from "./components/DeployJoin.js";
import { NoteList } from "./components/NoteList.js";

export const App: React.FC = () => {
  return (
    <main>
      <h1>Private Notebook on Midnight</h1>
      <p className="muted">
        Post notes whose bodies live off-chain while only commitment hashes and
        the owner's derived public key live on the ledger.
      </p>
      <ConnectWallet />
      <DeployJoin />
      <NoteList />
    </main>
  );
};

Create frontend/index.html. Vite uses this as the entry point for the browser. The <div id="root"> is where React mounts, and the <script> tag points Vite at the TypeScript entry point:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Private Notebook on Midnight</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Create frontend/src/styles.css. This stylesheet sets the dark theme, card layout, button colours, and utility classes (muted, mono, error, success) referenced throughout the components:

:root {
  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
  color-scheme: light dark;
  background: #0d1117;
  color: #e6edf3;
}

body {
  margin: 0;
  min-height: 100vh;
}

#root {
  max-width: 960px;
  margin: 0 auto;
  padding: 2rem 1.5rem 4rem;
}

h1,
h2,
h3 {
  letter-spacing: -0.01em;
}

.card {
  background: #161b22;
  border: 1px solid #30363d;
  border-radius: 10px;
  padding: 1.25rem 1.5rem;
  margin: 1rem 0;
}

button {
  background: #238636;
  color: white;
  border: 0;
  border-radius: 6px;
  padding: 0.55rem 1rem;
  font-weight: 600;
  cursor: pointer;
}
button[disabled] {
  background: #30363d;
  cursor: not-allowed;
}
button.secondary {
  background: #21262d;
}
button.danger {
  background: #8b1f22;
}

input,
textarea {
  background: #0d1117;
  color: #e6edf3;
  border: 1px solid #30363d;
  border-radius: 6px;
  padding: 0.5rem 0.75rem;
  font: inherit;
  width: 100%;
  box-sizing: border-box;
}

textarea {
  min-height: 100px;
  resize: vertical;
}

.note {
  display: flex;
  justify-content: space-between;
  align-items: flex-start;
  gap: 1rem;
  padding: 0.75rem 0;
  border-top: 1px solid #30363d;
}
.note:first-child {
  border-top: 0;
}

.muted {
  color: #8b949e;
  font-size: 0.85rem;
}
.mono {
  font-family: "SF Mono", Menlo, Consolas, monospace;
  font-size: 0.85rem;
}
.error {
  color: #f85149;
}
.success {
  color: #3fb950;
}

.wallet-row {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.5rem 0;
}
.wallet-row img {
  width: 28px;
  height: 28px;
  border-radius: 4px;
}

Create frontend/src/main.tsx:

import React from "react";
import ReactDOM from "react-dom/client";
import { App } from "./App.js";
import { WalletProvider } from "./contexts/WalletContext.js";
import { NotebookProvider } from "./contexts/NotebookContext.js";
import "./styles.css";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <WalletProvider>
      <NotebookProvider>
        <App />
      </NotebookProvider>
    </WalletProvider>
  </React.StrictMode>
);

The provider nesting order matters: WalletProvider must be the outer wrapper because NotebookProvider reads from WalletContext to access the providers object. If you reversed the nesting, NotebookProvider would mount before WalletProvider and the useWallet() call inside it would throw immediately.

Step 20: Configure Vite

Create frontend/.env. This file sets the network ID passed to wallet.connect(networkId) at runtime. The 1AM wallet uses preprod for the preprod network:

# Network ID passed to wallet.connect(networkId).
VITE_NETWORK_ID=preprod

Create frontend/vite.config.ts. This configuration serves the ZK key files during development and bundles them into the production build:

import { readFileSync, readdirSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";
import { nodePolyfills } from "vite-plugin-node-polyfills";

const __dirname = dirname(fileURLToPath(import.meta.url));
// Compiled Compact artifact directory produced by `npm run compile:contract`.
const managedDir = resolve(__dirname, "../contract/src/managed/notebook");

export default defineConfig({
  plugins: [
    react(),
    // Provides browser-compatible polyfills for Node.js built-ins (events,
    // buffer, process) that level-based private state provider needs.
    nodePolyfills(),
    wasm(),
    topLevelAwait({
      promiseExportName: "__tla",
      promiseImportName: (i) => `__tla_${i}`,
    }),
    // Serve ZK key material (keys/, zkir/) from the compiled contract artifacts
    // so FetchZkConfigProvider can fetch them at {origin}/keys/{circuit}.verifier
    // and {origin}/zkir/{circuit}.bzkir during both dev and production builds.
    {
      name: "midnight-zk-assets",
      configureServer(server) {
        server.middlewares.use((req, res, next) => {
          const match = (req.url ?? "").match(/^\/(keys|zkir)\/([^?#]+)$/);
          if (match) {
            const [, subdir, filename] = match;
            try {
              const data = readFileSync(resolve(managedDir, subdir, filename));
              res.setHeader("Content-Type", "application/octet-stream");
              res.end(data);
              return;
            } catch {
              // file not found; fall through to next middleware
            }
          }
          next();
        });
      },
      generateBundle() {
        for (const subdir of ["keys", "zkir"]) {
          try {
            for (const file of readdirSync(resolve(managedDir, subdir))) {
              this.emitFile({
                type: "asset",
                fileName: `${subdir}/${file}`,
                source: readFileSync(resolve(managedDir, subdir, file)),
              });
            }
          } catch {
            // compiled artifacts not present yet; skip silently
          }
        }
      },
    },
    // compact-runtime@0.15+ re-exports from onchain-runtime-v3. When the
    // pre-bundler sees that import, keep the module non-external so rolldown
    // can inline it with native top-level-await support instead of failing.
    {
      name: "midnight-wasm-resolver",
      resolveId(source, importer) {
        if (
          source === "@midnight-ntwrk/onchain-runtime-v3" &&
          importer?.includes("@midnight-ntwrk/compact-runtime")
        ) {
          return { id: source, external: false, moduleSideEffects: true };
        }
        return null;
      },
    },
  ],
  server: {
    port: 3000,
    proxy: {
      "/api": {
        target: "http://localhost:3001",
        changeOrigin: true,
      },
    },
    fs: { allow: [".."] },
  },
  optimizeDeps: {
    // Vite 8 uses rolldown for pre-bundling. Declaring native TLA support lets
    // rolldown bundle WASM modules that use top-level await without errors.
    rolldownOptions: {
      platform: "browser",
    },
    // Pre-bundle compact-runtime so its named exports (checkRuntimeVersion,
    // ContractState, etc.) are available via namespace imports in managed code.
    include: ["@midnight-ntwrk/compact-runtime"],
    // Exclude raw WASM packages; they are served directly and handled by the
    // wasm and top-level-await plugins at runtime.
    exclude: [
      "@midnight-ntwrk/onchain-runtime-v3",
      "@midnight-ntwrk/ledger",
      "@midnight-ntwrk/zswap",
    ],
  },
  build: {
    target: "esnext",
    commonjsOptions: {
      ignoreDynamicRequires: true,
      transformMixedEsModules: true,
    },
  },
  resolve: {
    extensions: [".mjs", ".js", ".ts", ".jsx", ".tsx", ".json", ".wasm"],
    mainFields: ["browser", "module", "main"],
  },
});

The midnight-zk-assets plugin has two hooks:

configureServer intercepts requests for /keys/* and /zkir/* during development and serves the files directly from the compiled contract directory.
generateBundle emits those same files as static assets in the production build so they are available from the deployed origin.

Without this plugin, FetchZkConfigProvider cannot fetch verifier keys and the "Failed to configure verifier key for circuit" error appears at runtime.

The midnight-wasm-resolver plugin handles a specific module resolution quirk in compact-runtime@0.15+. The library re-exports from @midnight-ntwrk/onchain-runtime-v3, which is a native WASM module. Vite's pre-bundler (rolldown in Vite 8) needs to know that this module should be inlined rather than treated as an external dependency, otherwise top-level await inside the WASM module causes a bundling error. The plugin intercepts the import at resolve time and marks it as non-external.

The optimizeDeps section pre-bundles @midnight-ntwrk/compact-runtime and excludes the raw WASM packages. This combination ensures that the named exports from the managed contract code (which uses namespace imports) are available on first page load without a re-bundling step, while the WASM modules themselves are served as separate files and loaded asynchronously by the wasm and topLevelAwait plugins.

Step 21: Run the project end to end

Follow these steps in order.

1. Install all dependencies from the monorepo root. All four workspace package.json files are now in place, so npm can resolve and link everything in one shot:

   npm install

2. Compile the contract. If you followed this tutorial and ran compact compile in Step 6 without changing notebook.compact since, you can skip this. The managed artifacts are already on disk. Only run it if contract/src/managed/ does not exist or you changed the contract:

   npm run compile:contract

3. Build the contract package. This runs tsc and then copy-managed.mjs, which copies the compiled Compact artifacts from contract/src/managed/ into contract/dist/managed/. The @notebook/contract package exports point to dist/, so nothing can import from it until this step runs:

   npm run build -w contract

4. Build the API package. The api imports from @notebook/contract (now in dist/). Compile it so the frontend can resolve its exports:

   npm run build -w api

5. Start the backend in one terminal:

   npm run dev:backend

You should see Notebook backend listening on http://localhost:3001.

6. Start the frontend in a second terminal:

   npm run dev:frontend

Vite starts on http://localhost:3000.

7. Open Chrome and navigate to http://localhost:3000. Make sure the 1AM wallet extension is installed. You do not need tDUST: ProofStation by 1AM sponsors transaction fees on preprod automatically.

8. Connect the wallet. The Connect Wallet card lists all detected v4-compatible wallets. Click Connect next to the 1AM entry. The wallet extension prompts you to authorize the connection.

9. Deploy a notebook. Click "Deploy new notebook". The wallet initiates proof generation (30 to 60 seconds on first use) and submits the deploy transaction. Once confirmed, the contract address appears in the Notebook ready card.

10. Post a note. Type any text in the textarea and click Post note. The frontend stores the body in the backend first, then calls the on-chain circuit. After the transaction confirms, the note appears with a green "verified" badge.

11. Reload the page. Connect the wallet again. The context reads the saved contract address from localStorage and auto-rejoins. Your notes are still there.

12. Delete a note. Click Delete. The circuit removes the entry from the on-chain notes map and the backend row is deleted.

⚠️ WARNING
The 1AM wallet syncs the full transaction history the first time it connects to preprod. Wait for the sync indicator to reach 100% before deploying. Transactions submitted during a partial sync may not produce accurate state updates.

Understand the privacy properties

Owner identity: The deployer's secret key never leaves the browser. The on-chain owner_commitment is persistentHash(["notebook:pk:", secretKey]). An observer can read this hash but cannot reverse it to find the key.

Note content: Only SHA-256 commitment hashes reach the chain. An observer sees a list of 32-byte values and a counter. Without the backend, they know notes exist but not what they say.

Authorship: The ZK proof for each transaction proves that the caller's derived public key equals owner_commitment without revealing the secret key. A verifier confirms only the owner could have sent this transaction.

Nonce uniqueness: The fresh_nonce witness generates 32 random bytes per call. Hashing the nonce with the content hash produces a unique note ID even when two notes have identical bodies. This prevents an observer from comparing IDs to infer duplicate content.

Limitations: The backend is not end-to-end encrypted in this tutorial. The server operator can read note bodies. For production, encrypt note bodies client-side before sending them to the backend. The on-chain commitment then binds to the ciphertext rather than the plaintext.

Conclusion

You have built a complete privacy-preserving DApp on Midnight, covering every layer of the stack:

A Compact smart contract that enforces ownership with ZK-verified public key derivation and stores only commitment hashes on-chain
TypeScript witnesses that supply the secret key and random nonces to ZK circuits at proving time
An in-memory private state provider that holds the secret key during a browser session
A providers factory that assembles the full Midnight SDK provider set from a connected wallet, including the 1AM Proof Station adapter
An Express and SQLite backend that stores note bodies off-chain keyed by commitment, with server-side SHA-256 verification
A React frontend with wallet discovery, deploy and join flows, backend-first note posting, and client-side commitment verification

The design principles here carry directly into other privacy-sensitive applications: a medical records DApp, a sealed-bid auction, a private voting system. The pattern is always the same: keep secrets off-chain and in witnesses, put only commitments on-chain, and let ZK proofs enforce the rules.

From here, you can extend this project by encrypting note bodies before sending them to the backend, adding multi-party notebooks where multiple secret keys can authorize writes, or migrating to a decentralized storage backend such as IPFS. The Midnight documentation at docs.midnight.network covers each of these patterns in the bulletin board and DEX reference implementations.

DEV Community: Oladeji Tosin

Build a privacy-preserving voting DApp on Midnight

Introduction

Prerequisites

Step 1: Scaffold the monorepo

Step 2: Create the root package.json

Step 3: Create the root tsconfig.json

Step 4: Write the Compact smart contract

Step 5: Set up the contract package

Step 6: Compile the contract

Step 7: Write the witness implementations

Step 8: Create the contract package entry point

Step 9: Build the contract

Step 10: Create the API package

Step 11: Define the shared types

Step 12: Write the VotingAPI class

Step 13: Build the API package

Step 14: Create the test package

Step 15: Run the tests

Step 16: Set up the frontend package

Step 17: Create the HTML entry point

Step 18: Create the React entry point

Step 19: Create the in-memory private state provider

Step 20: Create the provider factory

Step 21: Create the wallet client

Step 22: Create the React application

Step 23: Run the frontend

Conclusion

Managing private state in Midnight DApps

Contents

What you'll learn

Before you begin

Required reading

Required tools

Required knowledge

Understanding private state

The two-state model

The private oracle

When to use private state

The lifecycle of private data

The disclose() safety gate

Define your private state type

Encode private state

TypeScript to Compact type mapping

JSON serialization gotchas

Declare witness functions in Compact

Witness declaration syntax

A complete Compact smart contract using witnesses

What stays private in this smart contract

Implement witness functions in TypeScript

The WitnessContext interface

The witness return type

Implementing the score tracker witnesses

What happens if a witness throws error

Use private state in circuits

How circuits call witnesses

The disclose() keyword in depth

Domain separators prevent key reuse attacks

From user action to proof

The sequence of events

A complete increment handler

Handling errors at each stage

What the blockchain sees vs. what the user holds

Configure the private state provider

Private state storage options

Option 1: levelPrivateStateProvider (recommended for production)

Option 2: In-memory provider (testing and development)

Using levelPrivateStateProvider

Schema migration

Deploy and join smart contracts with private state

Deploying a new smart contract

Joining an existing smart contract

Putting it all together

Build a private state DApp from scratch

Part 1: Project setup

Part 2: Define private state with encoding in mind

Part 3: Write the Compact smart contract

Part 4: Implement witnesses

Part 5: Build the wallet provider

Part 6: Build the API and understand how private state updates

The `disclose()` safety gate

The `WitnessContext` interface

The `disclose()` keyword in depth

Option 1: `levelPrivateStateProvider` (recommended for production)

Using `levelPrivateStateProvider`

Always use `readonly` on private state types