devLap

Building a Full-Stack ZK-Privacy App on Midnight: A Step-by-Step Guide

typescript dev.to

Introduction

Hello everyone! 🚀

In this post, we are diving deep into Midnight, the privacy-focused blockchain!

Previously, we covered how to connect a frontend application to Lace Wallet. Now, we’re taking the next big step: connecting to a smart contract!

Implementing a full-stack ZK (Zero-Knowledge) application can be tricky, but I’ve navigated the pitfalls and version mismatches so you don't have to. Let’s get started!

What You Will Learn

  • How to develop a full-stack application on Midnight.
  • Concrete source code for calling smart contract functions via Lace Wallet.
  • Real-world "gotchas" and how to solve them.

The Sample App: A Full-Stack Counter

We’ll build a simple app that connects to Lace Wallet, displays balances, and interacts with a Counter smart contract.

Prerequisites

  • Lace Wallet browser extension (Midnight-compatible version).
  • PreProd network selected in Lace settings.
  • Some test NIGHT tokens from the official faucet.
  • Docker installed (for running the Proof Server).

GitHub Repository

Check out the full source code here:
https://github.com/mashharuki/midnight-sample-fullstack-app

Application Preview

Technical Features

Category Feature Description
Contract Build Compiles Compact files into WASM/ZKIR/Managed Code.
Contract Simulator Logic verification using CounterSimulator without a live network.
CLI Deploy Deploys to Standalone/TestNet and retrieves the contract address.
CLI Interaction Direct CLI commands to increment and check counter values.
App Wallet Connect Integration with Lace Wallet extension to fetch account data.
App Sync Automatically joins and fetches current state from a contract address.
App ZK Increment One-click UI to generate ZK proofs and send transactions.

Tech Stack

Layer Technology
Frontend React 19, Vite 5, Tailwind CSS v4, Lucide React, RxJS
Contract Compact (Midnight's ZK DSL)
SDK @midnight-ntwrk/* (SDK v2 / DApp Connector API v4)
Infrastructure Midnight Node, Indexer, Proof Server (via Docker)
Tooling Bun, Biome, Vitest, TypeScript

Deep Dive: Key Implementation Logic

The core logic resides in src/lib/counter.ts and src/hooks/useCounter.ts. This was the most challenging part of the build due to SDK version transitions and compatibility issues with Lace Wallet.

src/lib/counter.ts

This file handles the contract instance creation, state querying, and transaction calls.

1. Contract Instance Creation

We use the SDK to wrap the compiled Compact contract.

import * as CompactJs from "@midnight-ntwrk/compact-js";

// Initialize the compiled contract instance
export const counterContractInstance: CounterContract = (CompactJs.CompiledContract.make(
  "counter",
  Counter.Contract as any,
) as any).pipe(
  CompactJs.CompiledContract.withVacantWitnesses,
);
Enter fullscreen mode Exit fullscreen mode

2. Querying State

Using queryContractState, we can fetch the ledger data (in this case, the round number of our counter).

export const getCounterValue = async (
  providers: CounterProviders,
  contractAddress: ContractAddress,
): Promise<bigint | null> => {
  assertIsContractAddress(contractAddress);

  const contractState = await providers.publicDataProvider.queryContractState(
    contractAddress,
  );

  return contractState != null
    ? Counter.ledger(contractState.data as any).round
    : null;
};
Enter fullscreen mode Exit fullscreen mode

3. Calling Updates (Transactions)

The magic happens in callTx. This triggers the ZK proof generation and requests a signature from Lace Wallet.

export const incrementCounter = async (
  counterContract: DeployedCounterContract,
): Promise<void> => {
  // Call the increment() method on the contract
  await (counterContract as any).callTx.increment();
};
Enter fullscreen mode Exit fullscreen mode

Getting Started: Run it Locally

1. Clone & Install 

git clone https://github.com/mashharuki/midnight-lace-react-sample-app.git
cd midnight-lace-react-sample-app
bun install
Enter fullscreen mode Exit fullscreen mode

2. Start the Proof Server

Midnight requires a Proof Server to generate ZK Proofs locally before sending transactions to the network.

cd pkgs/cli
# Start the Proof Server (Ensure it's version 8.0.3)
docker compose -f standalone.yml up -d
Enter fullscreen mode Exit fullscreen mode

3. Build & Deploy the Contract 

bun contract build

# Deploy to the PreProd network
bun cli preprod
Enter fullscreen mode Exit fullscreen mode

Note: Copy the contract address displayed in the terminal!

4. Setup & Start the Frontend 

# Set environment variables
cp pkgs/app/.env.local.example pkgs/app/.env

# Build and start
bun app build
bun app dev
Enter fullscreen mode Exit fullscreen mode

Visit localhost:5173. You should see the following:

  1. Connect your wallet.
  2. Enter your deployed contract address and click Join.
  3. Click Increment. You will be prompted to sign the transaction.

Wait a few moments for the ZK proof generation and network finalization. Once done, refresh to see the updated value!

Sequence Diagrams

Unlike traditional blockchains, Midnight involves a local ZK Proof generation step in every state-changing transaction.

Contract Deployment Flow

Increment Function Call Flow

Summary

Building with ZK-privacy is a paradigm shift. While there were hurdles—especially around SDK versions and wallet compatibility—overcoming them allows you to build applications that truly respect user privacy.

I even created a custom AI Agent skill to help debug the Midnight SDK logic, which made the final stretch much smoother! You can find my Claude skills in the repo if you're interested.

Happy coding, and see you in the next one where we might tackle some hackathon challenges! 🛡️✨

References

Source: dev.to

arrow_back Back to Tutorials