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

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

• 
  .


• Docker installed (for running the Proof Server).

GitHub Repository

Check out the full source code here:

Technical Features

Tech Stack

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,

);

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;

};

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();

};

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

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

3. Build & Deploy the Contract

bun contract build



# Deploy to the PreProd network

bun cli preprod

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

Visit localhost:5173. You should see the following:

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

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