Example: Midnight Passport DApp

End-to-end MN Passport foundations demo: onboard with a passkey → deploy a custody contract → bind alice.night → deposit Night → explore custody workspace → logout/login restore.

Runnable template: templates/passport-dapp/
Integration API skill: midnight-passport/

What this skill produces / runs:

• Vite React app (app/)
• Compact contracts: account, faucet, identity_registry
• Platform-neutral wallet client (src/wallet/)
• Localnet Docker stack + one-command npm run demo
• Lifecycle tests + headless E2E

Not production: recovery shares on public ledger (TODO PVSS); hash-preimage auth (Schnorr deferred); genesis-funded deposits.

Workflow

1. Copy templates/passport-dapp/ (or work in-place)
2. Install root + app/ dependencies
3. Ensure Docker + Compact on PATH
4. npm run demo → open http://localhost:5173/
5. Create passkey (or use ?demoMode=local) → deposit → workspace
6. Optional: npm run demo:e2e, npm test, lifecycle scripts

1) Project structure

templates/passport-dapp/
├── package.json                 # compile, demo, lifecycle tests
├── scripts/demo-local.mjs       # env + compile + docker + deploy + vite
├── infra/                       # docker-compose localnet + proof server
├── contracts/
│   ├── account.compact          # per-user custody
│   ├── faucet.compact           # demo funding
│   └── identity_registry.compact
├── src/
│   ├── wallet/                  # PassportAccount, IdentityRegistry, witnesses
│   ├── node/                    # localnet wallet/providers
│   └── tests/                   # lifecycle-night, shielded, grants, recovery
├── app/                         # Vite + React UI
│   ├── src/lib/{passkey,session,midnight,providers}.ts
│   └── src/views/{Onboard,WalletPanel,DevicesPanel,...}.tsx
├── DECISIONS.md                 # prototype decision record (C1–C14)
└── README.md

2) Prerequisites

node --version    # >= 22
docker --version  # required for npm run demo

# Compact compiler (language 0.23 / toolchain ~0.30+)
curl --proto '=https' --tlsv1.2 -sSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh
source "$HOME/.local/bin/env"
compact --version

Chrome/Chromium for npm run demo:e2e (puppeteer-core).

3) Install and run

cp -R templates/passport-dapp my-passport-dapp   # if not already in repo
cd my-passport-dapp   # or: cd templates/passport-dapp

npm install
cd app && npm install && cd ..

npm run demo

Open http://localhost:5173/ (prefer localhost, not 127.0.0.1, for passkeys).

demo-local.mjs will:

1. Create infra/.env with local seeds if missing
2. npm run compile when managed contract JS is absent
3. docker compose up Midnight node + indexer + proof server
4. Deploy faucet + identity registry; inject addresses into the Vite app
5. Start Vite on :5173

Stop with Ctrl+C (script tears down or leaves containers — check script footer).

4) Manual browser flow

1. Enter alias (e.g. alice) → create passkey when prompted
2. Wait for custody deploy + registry register_identity
3. Deposit Night (demo uses genesis/faucet funding)
4. Open positions / workspace panels (holdings, devices, grants, recovery UI)
5. Refresh page → Unlock re-derives PRF device secret and reconnects

Automation / CI without passkey UI:

http://localhost:5173/?demoMode=local

or run:

npm run demo:e2e

5) Compile contracts only

npm run compile
# expands to:
# compact compile contracts/account.compact contracts/managed/account
# compact compile contracts/faucet.compact contracts/managed/faucet
# compact compile contracts/identity_registry.compact contracts/managed/identity_registry

Managed output is gitignored — always compile before node tests if missing.

6) Core code maps (agents must use these files)

When extending the app, import these modules — do not reinvent commitment tags or witness shapes.

7) Onboarding code path (reference)

// Pseudocode matching Onboard.tsx + PassportAccount

const alias = normalizeAlias(label); // lowercase trim
const passkey = await createPasskey(`${alias}.night`);
const deviceSecret = await deriveDeviceSecret(passkey);
const recoverySecret = randomBytes32();

const account = await PassportAccount.deploy(mid.accountProviders, compiledAccountContract(), {
  deviceSecret,
  recoverySecret,
});

await registerIdentity(mid, alias, account.address);

saveSession({
  accountAddress: account.address,
  alias,
  passkey,
  identityRegistryAddress: mid.identityRegistryAddress,
});
// never persist deviceSecret / recoverySecret

Unlock:

const deviceSecret = session.devMode
  ? await deriveDevModeSecret(LOCAL_DEMO_SECRET)
  : await deriveDeviceSecret(session.passkey);

const account = await PassportAccount.connect(
  mid.accountProviders,
  compiledAccountContract(),
  session.accountAddress,
  { deviceSecret },
);

8) Tests

npm test                    # vitest unit (simulator / shamir / account)
npm run test:lifecycle      # Night deposit/withdraw path on localnet
npm run test:shielded
npm run test:grants
npm run test:recovery
npm run demo:e2e            # browser automation against running demo

Lifecycle scripts expect a live localnet (same stack as npm run demo).

9) Extending the demo (agent guidance)

10) Troubleshooting

Full API semantics: midnight-passport/.
Provider gotchas on public nets: references/gotchas.md, indexer/.

11) Agent checklist

• Start from templates/passport-dapp/ (complete, not a stub)
• npm install at root and app/
• npm run demo with Docker + Compact
• Verify passkey or demoMode=local onboarding
• Confirm .night registration + deposit
• Document prototype limits to the user
• Link midnight-passport/ for embedding APIs in another app

Related skills