Setup & deployment

Prerequisites

• Node.js ≥ 20 (developed on 24), npm ≥ 10
• A Solana wallet — Phantom, Solflare (extension or web wallet at solflare.com), Backpack or Glow — set to Devnet for local testing
• Circom 2.2.x only if you want to rebuild the circuit — compiled artifacts are committed

Local quick start

npm install
npm run keygen                    # writes app/.env.local with fresh attester + registry keys

Get a token to prove. Either set GHOST_SNAPSHOT_MINTS in app/.env.local to any SPL mint you hold on devnet, or create a test token:

npm run devnet:mint -- <YOUR_WALLET_ADDRESS> --amount=1500
# prints:  GHOST_SNAPSHOT_MINTS=<mint>   → paste into app/.env.local

(If the devnet faucet rate-limits the airdrop, fund the printed fee-payer address at https://faucet.solana.com and re-run.)

npm run dev                       # builds the SDK, starts http://localhost:3000

Then in the browser:

1. Create → connect wallet → Sign to unlock → Generate & register (second signature).
2. Dashboard → Take snapshot now (dev mode). Your ghost should show its balance, decrypted locally.
3. Verify → Ghost Gate → choose a threshold → Request access with GHOST → a popup opens on Prove → Generate zero-knowledge proof → Send to localhost:3000. The gate verifies server-side and shows every check.
4. Repeat step 3 in “1 entry / wallet” mode: the nullifier check rejects the second attempt. Try a threshold above your balance: GHOST refuses to prove.

Environment variables (app/.env.local)

Tests

npm test                 # SDK (41 tests, real Groth16 proofs) + app (11 registry/storage tests)
npm run typecheck

What is covered:

Production deployment

GHOST runs as a single Node.js server (npm run build && npm start). The bundled JSON-file stores assume one instance with a persistent disk (a VM, container with a volume, Fly.io/Render/Railway with a volume). Serverless platforms with ephemeral filesystems (e.g. Vercel functions) need the stores replaced with a database first: implement ChallengeStore/NullifierStore (SDK interfaces) and swap JsonFileStore in app/src/lib/server/services.ts for Postgres/Redis.

npm ci
npm run build
NODE_ENV=production npm start          # port 3000; put TLS + a reverse proxy in front

Schedule snapshots instead of letting users trigger them:

# every 6 hours
0 */6 * * *  cd /srv/ghost && GHOST_ADMIN_TOKEN=… GHOST_PUBLIC_URL=https://ghost.example npm run snapshot -w ghost-app

Production checklist

• Independent security audit of circuit, SDK and server. Until then, do not claim production security.
• <a id="trusted-setup"></a>MPC phase-2 trusted setup with several independent contributors and a public beacon; publish the transcript and new vkey hash.
• Attester key in an HSM / KMS; consider multiple attesters run by independent parties.
• Private or self-hosted Solana RPC for snapshots (privacy and integrity).
• GHOST_ALLOW_PUBLIC_SNAPSHOT unset; strong GHOST_ADMIN_TOKEN; cron snapshots.
• Back up GHOST_REGISTRY_ENCRYPTION_KEY and the data directory separately.
• TLS everywhere; reverse proxy that does not log client IPs if you want to reduce metadata.
• Nonce-based CSP (remove unsafe-inline), HSTS.
• Database-backed stores for multi-instance deployments; atomic challenge/nullifier operations.
• Monitor snapshot slot ranges (slotMax - slotMin) and alert if wide.
• Publish attester public keys and artifact hashes out-of-band for verifiers to pin.

Troubleshooting