example-leaderboard-dapp

Midnight Network Leaderboard DApp

A privacy-preserving leaderboard where players submit scores on-chain with three display modes and prove they own an entry using verifyOwnership — a ZK circuit that checks ownerCommitment(secretKey) matches the stored ownerHash without revealing the secret.

Runnable template: Copy templates/leaderboard-dapp/ for a complete Next.js project (contract + UI). Run npm install && npm run compact && npm run sync:assets && npm run dev after installing the 1AM wallet.

What this skill produces:

• contract/ — Compact leaderboard + TypeScript witnesses + compile scripts
• app/leaderboard/ — Next.js client UI (click game, privacy mode picker, leaderboard table)
• lib/midnight.ts — wallet session + patched indexer provider (copy from references/midnight-session.md or templates/leaderboard-dapp/lib/midnight.ts)
• lib/leaderboard.ts — deploy, submitScore, verifyOwnership, ledger decode
• lib/display-name.ts — decode anonymous hash bytes to generated names ("Crimson Tiger")
• public/zk/leaderboard/ — ZK proving assets synced from contract build

Shared references (canonical provider + troubleshooting — do not duplicate in prompts):

• references/midnight-session.md — createConnectedSession, indexer patch, deploy/call helpers
• references/gotchas.md — preprod deploy hangs, GraphQL offset: null, ZK asset paths
• references/versions.json — pinned @midnight-ntwrk/* versions

Primary references:

• example-locker-dapp/ / templates/locker-dapp/ — Next.js + 1AM pattern, low-level deploy/call
• example-payment-dapp/ — provider wiring, indexer polling
• compact/ — disclose(), witnesses, persistentHash, Map, Counter, assert
• security/ — what is public on-chain vs private in witness data
• indexer/ — read contract state without wallet connection

Key architecture notes:

• scores is a public Map<Uint<64>, ScoreEntry> — readable from the indexer by anyone
• localSecretKey witness returns a 32-byte secret from private state; never disclosed on-chain
• ownerCommitment(sk) uses persistentHash with domain separator "leaderboard:owner:"
• useCustomName boolean selects witness-fed name vs hash-based anonymous display name
• verifyOwnership is a proof-only circuit — no ledger writes; use for "prove this is my score"
• Persist secret key in localStorage so ownership proofs work after page refresh
• Use createUnprovenDeployTx + submitTxAsync — not deployContract() (hangs on preprod)
• Wrap indexerPublicDataProvider with patched queryContractState (GraphQL offset: null bug)
• Leaderboard table can load from indexer without wallet — only submit/verify need connection

Workflow

When helping the user, follow this sequence:

1. Contract — leaderboard.compact compile + witnesses (localSecretKey, getCustomName)
2. Providers — createConnectedSession (from references/midnight-session.md)
3. Deploy — low-level deploy, persist private state + contract address
4. Read state — indexer GraphQL → ContractState.deserialize → ledger() → decode entries
5. Submit score — submitScore(score, useCustomName) with optional setCustomName beforehand
6. Verify ownership — verifyOwnership(entryId) for prize claims or "yours" badges
7. UI — click game, privacy mode selector, leaderboard table with prove button

1) Project Structure

leaderboard-dapp/
├── package.json
├── next.config.mjs
├── lib/
│   ├── isomorphic-ws-fix.mjs
│   ├── midnight.ts                 # session, patched provider, hex helpers
│   ├── leaderboard.ts              # deploy, submitScore, verifyOwnership, decode
│   └── display-name.ts             # anonymous name generator
├── app/
│   ├── layout.tsx
│   └── leaderboard/

2) Compact Contract

contract/src/leaderboard.compact:

Privacy design:

• Anonymous mode (useCustomName = false): displayName = persistentHash(sk) — UI decodes to generated name
• Public / Custom mode (useCustomName = true): displayName = getCustomName() witness — app feeds address or user name
• Ownership: ownerHash = ownerCommitment(sk) stored on every entry; verifyOwnership re-derives and compares

Compile:

3) Witnesses

contract/src/witnesses.ts:

Call setCustomName(name) in TypeScript before submitScore when using public or custom display modes.

4) TypeScript Integration

lib/leaderboard.ts mirrors the locker-dapp pattern:

ZK asset path: /zk/leaderboard (synced to public/zk/leaderboard/).

5) Browser UI

LeaderboardClient.tsx flow:

1. Connect — detectWallet() → wallet.connect('preprod') → createConnectedSession(api, ZK_PATH)
2. Deploy / Join — deploy new contract or paste existing 64-char hex address
3. Play — 10-second click challenge
4. Submit — pick Anonymous / Public / Custom, then submitScore
5. Leaderboard — auto-refresh from indexer every 15s (no wallet required to read)
6. Prove — verifyOwnership(entryId) marks entry as yours in UI

Indexer-only reads mean spectators can watch the leaderboard without connecting a wallet.

6) Prerequisites

Wallet: 1AM extension on Preprod, proof server http://localhost:6300, tNIGHT + tDUST from faucet.

7) Compatibility Matrix

Pin versions from references/versions.json. Cross-check docs.midnight.network support matrix before upgrading.

8) Production Notes

• Deploy frontend to Vercel/Netlify; set public/zk/leaderboard assets in build step (npm run sync:assets)
• Store default contract address in env or localStorage for returning players
• verifyOwnership does not mutate ledger — safe for repeated "prove mine" UX
• For mainnet, update network ID, indexer URLs, and proof server config via wallet getConfiguration()

Quick Commands

Open http://localhost:3000 → Connect 1AM → Deploy New → play → submit → refresh leaderboard.