Module 04

Your First Project

This module is written from a real deploy, on real Windows hardware, including every environment issue that actually came up. If you hit the same ones, that's normal — not a sign you did something wrong.

The contract

Clone the official starter and install dependencies:

git clone https://github.com/midnightntwrk/example-hello-world.git
cd example-hello-world
yarn install

Then write contracts/hello-world.compact:

pragma language_version 0.23;

export ledger message: Opaque<"string">;

export circuit storeMessage(newMessage: Opaque<"string">): [] {
 message = disclose(newMessage);
}

ledger declares public, on-chain state. Circuit inputs are private by default — the disclose() call is a deliberate guardrail: the compiler refuses to let private data touch public state unless you say so explicitly. That guardrail, sitting right there in working code, is the whole idea of programmable privacy from Module 01, made concrete.

If you're on Windows: read this first

The Compact toolchain expects a Linux-like environment. On Windows, that means WSL2 — not plain PowerShell. Budget real time for this part; it can be the longest step in the whole tutorial.

Snag: "WSL is not supported" / stuck on WSL1

Some machines silently install WSL as version 1. Check with wsl -l -v. If it shows 1, run wsl --set-version Ubuntu 2.

Snag: WSL2 refuses to start — virtualization disabled

This is a BIOS/firmware setting, not a Windows setting. Restart into BIOS (on HP: tap F10 at boot), find Virtualization Technology (VTx) under System Options, enable it, save and exit.

Snag: "cannot execute binary file" on sudo, after apt upgrade

Real-time antivirus (Windows Defender or third-party) can corrupt WSL2's virtual disk during heavy install operations. Add an exclusion for %LocalAppData%\Packagesin Windows Security → Virus & threat protection → Exclusions, then wipe and reinstall: wsl --unregister Ubuntu, wsl --install -d Ubuntu.

Snag: yarn install fails with EPERM on /mnt/c/...

Never run a Node project from the Windows-mounted drive (/mnt/c/...) inside WSL — permission models clash across that boundary. Clone the project into Linux's own filesystem instead, e.g. ~/example-hello-world.

Snag: compact update fails to unpack the compiler

A minimal Ubuntu install may be missing archive tools. Run sudo apt-get install -y xz-utils tar gzip zstd unzip, then delete the broken partial version folder before retrying: rm -rf ~/.compact/versions/[version].

Compiling

compact compile contracts/hello-world.compact contracts/managed/hello-world

Running the local devnet

The starter repo includes a script that brings up a full local stack — node, indexer, and proof server together — via Docker:

yarn env:up

In a second terminal, once that's healthy:

yarn test:local

This deploys your contract to the local devnet, calls storeMessage, and verifies it worked — including generating a real local wallet and a real zero-knowledge proof. A passing result looks like two green checks: Deploys the contract and Stores Hello World!

Next: Module 05 — Folder Structure →