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
- Copy
templates/passport-dapp/(or work in-place) - Install root +
app/dependencies - Ensure Docker + Compact on PATH
npm run demo→ open http://localhost:5173/- Create passkey (or use
?demoMode=local) → deposit → workspace - 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:
- Create
infra/.envwith local seeds if missing npm run compilewhen managed contract JS is absentdocker composeup Midnight node + indexer + proof server- Deploy faucet + identity registry; inject addresses into the Vite app
- Start Vite on
:5173
Stop with Ctrl+C (script tears down or leaves containers — check script footer).
4) Manual browser flow
- Enter alias (e.g.
alice) → create passkey when prompted - Wait for custody deploy + registry
register_identity - Deposit Night (demo uses genesis/faucet funding)
- Open positions / workspace panels (holdings, devices, grants, recovery UI)
- 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)
| Concern | File |
|---|---|
| Passkey PRF | app/src/lib/passkey.ts |
| Session (no secrets) | app/src/lib/session.ts |
| Boot Midnight + registry helpers | app/src/lib/midnight.ts, providers.ts |
| Onboarding UX | app/src/views/Onboard.tsx |
| Custody client | src/wallet/account.ts → PassportAccount |
| Night ID client | src/wallet/identity.ts → IdentityRegistry |
| Witnesses | src/wallet/witnesses.ts |
| Commitments | src/wallet/contract.ts + pure circuits in account.compact |
| Decisions / caveats | DECISIONS.md |
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)
| Goal | Approach |
|---|---|
| Custom UI branding | Edit app/src/views/* + styles.css; keep src/wallet intact |
| Extra custody circuit | Add to account.compact, recompile, wrap method on PassportAccount |
| Production wallet | Replace genesis createWallet with 1am-wallet/ / Dynamic; keep custody deploy |
| Stronger auth | Replace require_device hash-preimage with MIP-0013 Schnorr/WebAuthn arm (see Passport research / contract track) — out of scope for foundations cut |
| Safe recovery | Replace plaintext ledger shares with PVSS / encrypted helper shares |
10) Troubleshooting
| Symptom | Fix |
|---|---|
compact: command not found |
Install Compact; ensure PATH |
| Docker permission / not running | Start Docker Desktop; docker info |
| Passkey invalid domain | Use http://localhost:5173/ |
| Unlock hangs | Localnet reset — Forget account / clear passport-demo-session |
| Compile language mismatch | Match Compact to pragma language_version 0.23 |
| Port 5173 busy | Stop other Vite; or change Vite port and RP expectations |
| E2E fails mid-deposit | Ensure demo script finished deploy; faucet address injected |
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 installat root andapp/ -
npm run demowith Docker + Compact - Verify passkey or
demoMode=localonboarding - Confirm
.nightregistration + deposit - Document prototype limits to the user
- Link
midnight-passport/for embedding APIs in another app
Related skills
| Need | Skill |
|---|---|
| Passport APIs without full demo | midnight-passport/ |
| Compact syntax | compact/ |
| midnight-js providers | midnight-js/ |
| 1AM / Dynamic wallets | 1am-wallet/, dynamic-midnight-wallet/ |
| Environment / proof server | midnight-environment-setup/ |