Skip to main content
For the complete documentation index, see llms.txt

Edda Midnight starter template

Edda Midnight Starter Template is a full-stack monorepo for building DApps on the Midnight Network. It ships a working counter application with a Compact smart contract, a React (Vite) frontend, and a CLI - ready to clone, build, and deploy to Vercel. A live demo runs at counter.nebula.builders.

The project includes educational materials with video walkthroughs in English, Spanish, and Portuguese, making it a practical entry point for developers new to Midnight.

The Edda Labs maintainers built this as a fork of MeshJS/midnight-starter-template, adding the Apache-2.0 license, deployment automation, and the educational-material directory.

Community-maintained - not audited

Edda Labs maintains this template, not the Midnight Foundation. It has not been audited. The smart contract is a minimal counter example intended for learning - evaluate any production use independently.

Prerequisites​

Before using the template, ensure that you have:

Compatibility​

This template targets specific Compact compiler, runtime, and tooling versions. Verify these against your local environment before building.

ComponentVersionNotes
Compact compiler0.30.0Set via compact update +0.30.0
Compact language>= 0.22Per pragma in the contract source
Node.js22+Pinned in .node-version and engines.node
pnpm10.14.0Pinned via packageManager in package.json
Build orchestratorTurborepoTop-level scripts dispatch through turbo run
Networksundeployed, Preview, Preprod, MainnetStandalone undeployed network runs via Docker
LicenseApache-2.0(Upstream Mesh template carries no license; Edda's fork added Apache-2.0.)

Monorepo structure​

The template organizes code into three workspace packages:

PackagePurpose
counter-contractCompact smart contract with a single increment circuit that advances a public round counter. Compiles to TypeScript bindings and ZK proof artifacts.
counter-cliCLI tool for deploying and interacting with the contract from the terminal. Supports all three networks.
frontend-vite-reactReact 19 + Vite frontend with Lace wallet integration, TailwindCSS styling, and TanStack Router. Connects to the deployed contract and displays counter state.

Installation​

Clone the repository:

git clone https://github.com/eddalabs/midnight-starter-template.git
cd midnight-starter-template

Download the zero-knowledge proof artifacts via Git Large File Storage (LFS):

git lfs install
git lfs pull

Update the Compact Toolchain to the version the template targets:

compact update +0.30.0

Install dependencies and build all workspace packages:

pnpm install
pnpm build

Both counter-cli/ and frontend-vite-react/ ship a .env_template file. Copy each to .env and fill in the values before running locally.

Git LFS required

The repository stores zero-knowledge proof artifacts (prover keys, verifier keys, ZKIR files) via Git LFS. Without git lfs install and git lfs pull, these files appear as text pointers instead of binary data, and contract deployment fails with "mismatched verifier keys" errors.

Run locally​

Start the frontend against the Preview network:

pnpm dev:frontend

For a fully local setup with no external network dependency, start the standalone network first:

pnpm setup-standalone
pnpm dev:frontend

The standalone network runs Midnight node, indexer, and proof server containers in Docker.

Testing​

The CLI ships Vitest-based test suites that run the contract end-to-end on each network:

pnpm --filter @eddalabs/counter-cli test-undeployed
pnpm --filter @eddalabs/counter-cli test-preview
pnpm --filter @eddalabs/counter-cli test-preprod

These scripts spin up the relevant infrastructure (containers for undeployed, faucet calls for preview / preprod), deploy the contract, and assert on circuit behavior. They serve as a useful reference for setting up your own contract test harness.

The smart contract​

The contract is a minimal counter with a single exported circuit:

pragma language_version >= 0.22;

import CompactStandardLibrary;

export ledger round: Counter;

export circuit increment(): [] {
  round.increment(1);
}

The contract is deliberately minimal - the template's value is the full-stack scaffolding around it (wallet connection, provider wiring, deployment pipeline), not the contract logic. Replace it with your own contract and the surrounding infrastructure adapts.

Deploy to Vercel​

The Edda Labs team documents the full deployment procedure in their DEPLOYMENT_PROCEDURE.md. The key steps:

  1. Enable Git LFS in your Vercel project settings before the first build.
  2. Set the build command to npm run build-production (the script is workspace-aware and pulls LFS artifacts before building).
  3. Set the output directory to frontend-vite-react/dist.
  4. Add VITE_CONTRACT_ADDRESS as an environment variable with your deployed contract address.
Git LFS in Vercel

If you deploy without enabling Git LFS in Vercel's settings, then the build completes but the DApp fails at runtime. The proof artifacts are LFS pointers instead of binary files. Enable LFS first, then redeploy without cache.

Educational materials​

The repository includes an educational-material/ directory with structured session guides covering:

  • zero-knowledge proofs and privacy-enhanced DApps
  • devnet, Preview, and Testnet environments
  • Video walkthroughs on the Edda Labs YouTube channel
  • Available in English, Spanish, and Portuguese

Resources​

Report issues​

For issues with the template, file on Edda Labs' tracker.

For issues with this documentation page, file on the Midnight docs repository.