Local Setup

1. Build Circuits

./build-circuits.sh

This compiles all Noir circuits, generates Solidity verifiers, and creates TypeScript FFI bindings.

2. Start Hardhat Node

cd contracts
npm install
npm run start

3. Deploy Contracts

In a separate terminal:

cd contracts
npm run deploy

4. Start Web Services

cd web
pnpm install
pnpm dev:hardhat       # Starts all apps configured for local Hardhat

Individual services can be started separately:

pnpm --filter app dev          # Frontend
pnpm --filter rpc-proxy dev    # RPC proxy
pnpm --filter relayer dev      # Relayer
pnpm --filter faucet dev       # Faucet

5. HTTPS Setup (Required)

The frontend requires HTTPS for secure cookies. Use Caddy as a reverse proxy.

Install Dependencies

# Arch/Manjaro
sudo pacman -S caddy mkcert

# macOS
brew install caddy mkcert

# Ubuntu/Debian
sudo apt install caddy mkcert

Generate SSL Certificates

mkcert -install
mkdir -p ~/.local/share/caddy/certs
cd ~/.local/share/caddy/certs
mkcert "*.local.dev" localhost 127.0.0.1 ::1

Add Domain to Hosts

echo "127.0.0.1 nullmask.local.dev" | sudo tee -a /etc/hosts

Create Caddyfile

Create ~/Caddyfile:

nullmask.local.dev {
    tls ~/.local/share/caddy/certs/_wildcard.local.dev+3.pem ~/.local/share/caddy/certs/_wildcard.local.dev+3-key.pem

    handle /guard* {
        uri strip_prefix /guard
        reverse_proxy localhost:8549
    }

    handle /faucet* {
        reverse_proxy localhost:8547
    }

    handle /rpc* {
        uri strip_prefix /rpc
        reverse_proxy localhost:8545
    }

    handle /node* {
        uri strip_prefix /node
        reverse_proxy localhost:9000
    }

    handle {
        reverse_proxy localhost:3000
    }
}

Update Environment Files

web/apps/app/.env:

NEXT_PUBLIC_RPC_PROXY_URL=https://nullmask.local.dev/rpc
NEXT_PUBLIC_FAUCET_URL=https://nullmask.local.dev
NEXT_PUBLIC_RPC_CONTRACT_URL=https://nullmask.local.dev/node
NEXT_PUBLIC_GUARD_URL=https://nullmask.local.dev/guard

web/apps/rpc-proxy/.env:

BASE_DOMAIN=nullmask.local.dev

Start Caddy

caddy run --config ~/Caddyfile

Verify

Open https://nullmask.local.dev in your browser.

Troubleshooting

• Certificate not trusted: Run mkcert -install again and restart your browser

• Port 443 permission denied: sudo setcap cap_net_bind_service=+ep $(which caddy)

• LMDB stale data after Hardhat restart: Run ./wipe-lmdb.sh and restart web services