zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/build/verifyService.js

@@ -1,219 +1,425 @@
 #!/usr/bin/env node
 // Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
-/**
- * verifyService.ts
- *
- * Lightweight, standalone license verification service.
- *
- * Exposes the same state endpoints as the keeper but contains NO ZK prover —
- * no circuit compilation, no o1js native backend. Starts in ~2 seconds and
- * runs on any small VPS or container.
- *
- * No write endpoints — chain events are the source of truth. License state
- * is rebuilt from the archive node in three ways:
- *   - auto-bootstrap on startup when licenses.json is empty,
- *   - lazy bootstrap inside GET / when the computed Merkle root
- *     disagrees with the on-chain root for the requested app (the canonical
- *     "we're stale" signal). One replay + one retry is enough — root is
- *     consensus. This catches licenses issued, renewed, or refunded after
- *     boot on the very next verify call, with zero work done when no one is
- *     asking. Concurrent verifies for the same app share one in-flight
- *     bootstrap so a popular license under load does not stampede the
- *     archive node.
- *   - POST /bootstrap (admin) for ad-hoc reasons: a newly registered zkApp
- *     (verify won't trigger a sync for an app no client knows about yet), a
- *     corrupted licenses.json, or repopulating the offline /license/...
- *     debug endpoint without first hitting /verify.
- *
- * Deployment modes
- * ----------------
- * 1. Same-machine as the keeper
- *    - Run from the keeper's working directory so apps.json and licenses.json
- *      are shared transparently. Optionally set LICENSE_STORE_PATH to point at
- *      a shared file.
- *
- * 2. Separate machine (replica)
- *    - Copy the keeper's apps.json into the verifyService working directory.
- *      apps.json tells the service which zkApp addresses to replay events for.
- *    - Start the service. On boot it auto-bootstraps every app in apps.json
- *      from the archive node. MINA_ARCHIVE_URL defaults to the Minascan public
- *      archive matching MINA_NETWORK_ID:
- *        mainnet → https://api.minascan.io/archive/mainnet/v1/graphql
- *        else    → https://api.minascan.io/archive/devnet/v1/graphql
- *      Override by setting MINA_ARCHIVE_URL in the environment.
- *    - To register a NEW app on the replica afterwards:
- *        a) Re-copy apps.json from the keeper (it owns the registry), then
- *        b) POST /bootstrap with the new zkAppAddress to ingest its events.
- *    - Re-copying apps.json on a cron (or pulling it via GET /apps from the
- *      keeper) is the recommended way to keep the registry in sync.
- *
- * Usage:
- *   node build/src/verifyService.js
- *
- * Configuration is read from environment variables (see README §Configuration).
- * Required: MINA_GRAPHQL_URL, PLATFORM_ADDRESS.
- * Optional: MINA_NETWORK_ID (default testnet), MINA_ARCHIVE_URL (defaults by
- * network), VERIFY_PORT (default 8081), VERIFY_ADMIN_TOKEN.
- *
- * Endpoints:
- *   GET  /health
- *   GET  /?licenseHash=...&zkAppAddress=...        ← primary endpoint for apps
- *   GET  /challenge?licenseHash=...                 ← ownership nonce
- *   POST /respond                                   ← ownership proof + token
- *   POST /refresh                                   ← extend token TTL (no re-prove)
- *   POST /releaseSeat                                ← release this device's seat
- *   POST /reset-sessions                            ← drop all sessions (re-prove)
- *   GET  /root?zkApp=...
- *   GET  /witness/:zkAppAddress/:licenseHash
- *   GET  /license/:zkAppAddress/:licenseHash
- *   GET  /apps
- *   POST /bootstrap                                 ← replay events from archive
- */
-import fs from 'fs/promises';
-import { mkdirSync } from 'fs';
-import { homedir } from 'os';
-import { join } from 'path';
+// SPDX-License-Identifier: BUSL-1.1
 import express from 'express';
-import { Field, Mina, fetchLastBlock, fetchAccount, PublicKey, Cache, setBackend, verify, } from 'o1js';
+import { Field, Mina, fetchLastBlock, fetchAccount, PublicKey, setBackend, setGraphqlEndpoint, setArchiveGraphqlEndpoint, } from 'o1js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { dirname, resolve as pathResolve } from 'path';
 import { buildMap, getLicense, licenseStatus, readRecords, serializeWitness, } from './licenseStore.js';
-import { verifyLicenseCore } from './verifyCore.js';
-import { bootstrapFromArchive, applyEventsToStore, lazyBootstrap } from './archiveBootstrap.js';
-import { LicenseProof, LicenseProofProof } from './licenseProof.js';
-import { CANONICAL_VK_HASHES, CANONICAL_LICENSE_PROOF_VK_HASH, SUPPORTED_LICENSING_APP_VERSIONS, fetchLicensingAppVersion, } from './contractInterface.js';
-import { createChallengeStore, createSessionStore, newJti, signOwnershipToken, verifyOwnershipToken, newOwnershipKey, OWNERSHIP_TOKEN_TTL_MS, } from './ownership.js';
+import { verifyLicenseWithAncestors } from './verifyWithAncestors.js';
+import { bootstrapFromArchive, applyEventsToStore } from './archiveBootstrap.js';
+import { CANONICAL_VK_HASHES, LICENSING_APP_STATE, SUPPORTED_LICENSING_APP_VERSIONS, fetchLicensingAppVersion, } from './contractInterface.js';
+import { readJsonOr } from './atomicJson.js';
 setBackend('native');
-const CIRCUIT_CACHE_DIR = join(homedir(), '.cache', 'zklic-verifier');
-mkdirSync(CIRCUIT_CACHE_DIR, { recursive: true });
-// ------------------------------------------------------------
-// CONFIG (env vars) & NETWORK
-// ------------------------------------------------------------
-function requireEnv(name, hint) {
-    const v = process.env[name];
-    if (!v) {
-        console.error(`❌ ${name} env var is required. ${hint}`);
-        process.exit(1);
-    }
-    return v;
-}
-const MINA_NETWORK_ID = process.env.MINA_NETWORK_ID ?? 'devnet';
-const MINA_GRAPHQL_URL = requireEnv('MINA_GRAPHQL_URL', 'e.g. https://api.minascan.io/node/devnet/v1/graphql');
+const NETWORKS = ['devnet', 'mainnet'];
+const MINA_DEVNET_GRAPHQL_URL = process.env.MINA_DEVNET_GRAPHQL_URL;
+const MINA_DEVNET_ARCHIVE_URL = process.env.MINA_DEVNET_ARCHIVE_URL;
+const MINA_DEVNET_GRAPHQL_FALLBACK = process.env.MINA_DEVNET_GRAPHQL_FALLBACK;
+const MINA_DEVNET_ARCHIVE_FALLBACK = process.env.MINA_DEVNET_ARCHIVE_FALLBACK;
+const MINA_MAINNET_GRAPHQL_URL = process.env.MINA_MAINNET_GRAPHQL_URL;
+const MINA_MAINNET_ARCHIVE_URL = process.env.MINA_MAINNET_ARCHIVE_URL;
+const MINA_MAINNET_GRAPHQL_FALLBACK = process.env.MINA_MAINNET_GRAPHQL_FALLBACK;
+const MINA_MAINNET_ARCHIVE_FALLBACK = process.env.MINA_MAINNET_ARCHIVE_FALLBACK;
 const PORT = parseInt(process.env.VERIFY_PORT ?? '8081', 10);
-function defaultArchiveUrl(networkId) {
-    switch (networkId) {
-        case 'mainnet':
-            return 'https://api.minascan.io/archive/mainnet/v1/graphql';
-        case 'devnet':
-            return 'https://api.minascan.io/archive/devnet/v1/graphql';
-        default:
-            return null;
-    }
+// Default archive endpoint per network. Devnet uses o1Labs' Mesa archive
+// (devnet-archive-node-api.gcp.o1test.net); mainnet falls back to Minascan's
+// public archive. When the operator sets an explicit MINA_*_ARCHIVE_URL env
+// var, that value wins.
+const DEFAULT_ARCHIVE_URL = {
+    devnet: 'https://devnet-archive-node-api.gcp.o1test.net',
+    mainnet: 'https://api.minascan.io/archive/mainnet/v1/graphql',
+};
+// Build per-network Mina.Network instances. Any network the operator didn't
+// configure (no RPC URL) stays out of the map — requests targeting it fall
+// through to `unregistered-address`. At least one must be configured.
+const NETWORK_CONFIG = {};
+function buildNetworkConfig(networkId, graphqlUrl, archiveEnv, graphqlFallbackEnv, archiveFallbackEnv) {
+    if (!graphqlUrl)
+        return;
+    const archiveUrl = archiveEnv ?? DEFAULT_ARCHIVE_URL[networkId];
+    const trim = (s) => (s ? s.trim() : '');
+    const graphqlFallback = trim(graphqlFallbackEnv) && trim(graphqlFallbackEnv) !== graphqlUrl
+        ? trim(graphqlFallbackEnv) : null;
+    const archiveFallback = trim(archiveFallbackEnv) && trim(archiveFallbackEnv) !== archiveUrl
+        ? trim(archiveFallbackEnv) : null;
+    // See keeperService.ts for the full rationale: o1js's array-based fallback
+    // form (`mina: [primary, fallback]`) is unusable — Promise.race lets a fast
+    // 5xx from primary beat a slow 200 from fallback, and the winning-URL
+    // cache-key bug causes subsequent `.get()` calls to miss. Manual rotation
+    // via a second single-URL Mina.Network instance is the sole failover path.
+    const fallbackMinaArg = graphqlFallback ? graphqlFallback : null;
+    const fallbackArchiveArg = graphqlFallback ? (archiveFallback ?? archiveUrl) : null;
+    NETWORK_CONFIG[networkId] = {
+        networkId,
+        graphqlUrl,
+        archiveUrl,
+        graphqlFallback,
+        archiveFallback,
+        network: Mina.Network({ networkId: networkId, mina: graphqlUrl, archive: archiveUrl }),
+        fallbackNetwork: fallbackMinaArg
+            ? Mina.Network({ networkId: networkId, mina: fallbackMinaArg, archive: fallbackArchiveArg })
+            : null,
+    };
+    console.log(`🔗 ${networkId.padEnd(7)} Mina node:    ${graphqlUrl}`);
+    if (graphqlFallback)
+        console.log(`   ${networkId.padEnd(7)}   fallback:   ${graphqlFallback}`);
+    console.log(`📚 ${networkId.padEnd(7)} Archive node: ${archiveUrl}${archiveEnv ? ' (from env)' : ' (default)'}`);
+    if (archiveFallback)
+        console.log(`   ${networkId.padEnd(7)}   fallback:   ${archiveFallback}`);
 }
-const archiveUrl = process.env.MINA_ARCHIVE_URL ?? defaultArchiveUrl(MINA_NETWORK_ID);
-if (!archiveUrl) {
-    console.error(`❌ No archive URL for MINA_NETWORK_ID="${MINA_NETWORK_ID}" and no built-in default for this network.\n` +
-        `   Set MINA_ARCHIVE_URL to the archive node GraphQL endpoint.`);
+buildNetworkConfig('devnet', MINA_DEVNET_GRAPHQL_URL, MINA_DEVNET_ARCHIVE_URL, MINA_DEVNET_GRAPHQL_FALLBACK, MINA_DEVNET_ARCHIVE_FALLBACK);
+buildNetworkConfig('mainnet', MINA_MAINNET_GRAPHQL_URL, MINA_MAINNET_ARCHIVE_URL, MINA_MAINNET_GRAPHQL_FALLBACK, MINA_MAINNET_ARCHIVE_FALLBACK);
+if (Object.keys(NETWORK_CONFIG).length === 0) {
+    console.error('❌ No Mina network configured. Set at least one of MINA_DEVNET_GRAPHQL_URL / MINA_MAINNET_GRAPHQL_URL.');
     process.exit(1);
 }
-console.log(`🔗 Mina node:    ${MINA_GRAPHQL_URL}`);
-console.log(`📚 Archive node: ${archiveUrl}${process.env.MINA_ARCHIVE_URL ? ' (from MINA_ARCHIVE_URL)' : ' (default — set MINA_ARCHIVE_URL to override)'}`);
-Mina.setActiveInstance(Mina.Network({
-    networkId: MINA_NETWORK_ID,
-    mina: MINA_GRAPHQL_URL,
-    archive: archiveUrl,
-}));
-// ------------------------------------------------------------
-// CIRCUIT — LicenseProof (ownership challenge/response)
-// ------------------------------------------------------------
-let licenseProofVk = null;
-let licenseProofCompile = null;
-async function ensureCompiled() {
-    if (licenseProofVk)
+// Leaked-transaction-context reset scaffolding. The verifier has no
+// Mina.transaction() calls today, so the leak defense is theoretical — but
+// it's cheap (one dynamic import at boot) and future-proofs against a code
+// path we haven't accounted for taking the process out until systemd
+// restarts it. Same shape as keeperService.ts.
+const _o1jsRequire = createRequire(import.meta.url);
+let _o1jsCurrentTransaction = null;
+try {
+    const o1jsMainPath = _o1jsRequire.resolve('o1js');
+    const contextUrl = pathToFileURL(pathResolve(dirname(o1jsMainPath), 'lib/mina/v1/transaction-context.js')).href;
+    const mod = await import(contextUrl);
+    _o1jsCurrentTransaction = mod.currentTransaction ?? null;
+}
+catch (e) {
+    console.warn('[withNetwork] o1js leak defense disabled — could not reach internal transaction-context:', e?.message ?? e);
+}
+function resetLeakedTransactionContext() {
+    if (!_o1jsCurrentTransaction)
         return;
-    licenseProofCompile ??= (async () => {
-        const cached = Cache.FileSystem(CIRCUIT_CACHE_DIR);
-        const t = Date.now();
-        console.log(`[verify-prover] Compiling LicenseProof (cache: ${CIRCUIT_CACHE_DIR})…`);
-        const lpVk = await LicenseProof.compile({ cache: cached });
-        const vk = lpVk.verificationKey;
-        if (CANONICAL_LICENSE_PROOF_VK_HASH && vk.hash.toString() !== CANONICAL_LICENSE_PROOF_VK_HASH) {
-            throw new Error(`LicenseProof VK hash ${vk.hash.toString()} does not match CANONICAL_LICENSE_PROOF_VK_HASH ${CANONICAL_LICENSE_PROOF_VK_HASH}`);
+    while (_o1jsCurrentTransaction.has()) {
+        try {
+            _o1jsCurrentTransaction.leave(_o1jsCurrentTransaction.id());
+        }
+        catch {
+            break;
         }
-        licenseProofVk = vk;
-        console.log(`[verify-prover] Ready in ${((Date.now() - t) / 1000).toFixed(1)}s — vk ${vk.hash.toString().slice(0, 16)}…`);
-    })();
-    await licenseProofCompile;
+    }
 }
-ensureCompiled().catch((e) => console.error('[verify-prover] Compile failed:', e));
-// ------------------------------------------------------------
-// OWNERSHIP — challenge + activation token (helpers live in ownership.ts)
-// ------------------------------------------------------------
-const ownershipChallenges = createChallengeStore();
-setInterval(() => { /* opportunistic GC */ ownershipChallenges.size(); }, 30_000).unref();
-// Per-license active-device session store. Backs the concurrent-device cap
-// (AppRecord.maxConcurrentDevices), /releaseSeat, and /reset-sessions. In-memory
-// by design — a keeper restart drops every session, forcing devices to
-// re-prove ownership. That is a security feature: persisted sessions would
-// let a stolen token bypass concurrency caps across restarts.
-const ownershipSessions = createSessionStore();
-setInterval(() => { /* opportunistic GC — activeCount touches prune */ ownershipSessions.size(); }, 30_000).unref();
-async function loadAppByAddress(zkAppAddress) {
-    const apps = await readApps();
-    return apps.find((a) => a.zkAppAddress === zkAppAddress) ?? null;
+let _networkMutexTail = Promise.resolve();
+// Which endpoint (primary vs fallback) currently succeeds for each network.
+// Updated by the rotation helpers whenever a call succeeds on a specific
+// endpoint. `withNetwork` restores from this map at region entry so that a
+// successful fallback rotation in one region persists into the next region
+// — otherwise a resetToPrimary here would stomp the fallback state and the
+// following .get() cache lookup would miss on primary (the o1js account
+// cache is keyed by graphql endpoint URL).
+//
+// Sticky-until-proven-broken semantics: we don't automatically retry primary
+// on every region entry. If primary comes back up, the next rotation call
+// will hit it first (attempt 1) and flip us back.
+const _activeEndpointByNetwork = new Map();
+// Swap the active Mina instance AND the o1js module-global fetch endpoint
+// atomically. These are two independent globals inside o1js:
+//   - `activeInstance` (mina-instance.js) — what zkApp.<state>.get() closes
+//     over for its cache lookups
+//   - `networkConfig.minaEndpoint` (fetch.js) — the DEFAULT endpoint for
+//     bare `fetchAccount({publicKey})` / `fetchLastBlock()` calls
+// `Mina.setActiveInstance` only touches the first. Because we build TWO
+// Mina.Network() instances at startup (primary + fallback) and the second
+// call's Fetch.setGraphqlEndpoint side-effect leaves `networkConfig.minaEndpoint`
+// pinned to the LAST-constructed URL (the fallback), a plain
+// setActiveInstance(cfg.network) leaves fetchAccount hitting the fallback URL
+// while zkApp.<state>.get() looks up under the primary URL — cache miss →
+// "Could not find account". We must always keep the two endpoints in sync,
+// which this helper does.
+function activateNetworkEndpoints(cfg, useFallback) {
+    if (useFallback && cfg.fallbackNetwork) {
+        Mina.setActiveInstance(cfg.fallbackNetwork);
+        setGraphqlEndpoint(cfg.graphqlFallback ?? cfg.graphqlUrl);
+        setArchiveGraphqlEndpoint(cfg.archiveFallback ?? cfg.archiveUrl);
+        _activeEndpointByNetwork.set(cfg.networkId, 'fallback');
+    }
+    else {
+        Mina.setActiveInstance(cfg.network);
+        setGraphqlEndpoint(cfg.graphqlUrl);
+        setArchiveGraphqlEndpoint(cfg.archiveUrl);
+        _activeEndpointByNetwork.set(cfg.networkId, 'primary');
+    }
 }
-// Resolve which generation a zkAppAddress claims to belong to by walking the
-// keeper's AppRecord.deploymentHistory[]. The top-level address is the current
-// generation (history.length + 1); older addresses live in history at
-// increasing index. Returns null when the address is not present in any
-// app's history — which is exactly what stops a "genuine v1 circuit
-// redeployed at a fresh address" impersonation: unlisted address → no
-// generation → verify rejects. See CANONICAL_VK_HASHES in contractInterface.ts.
-async function resolveGenerationByAddress(zkAppAddress) {
-    const apps = await readApps();
-    for (const a of apps) {
-        const historyLen = a.deploymentHistory?.length ?? 0;
-        if (a.zkAppAddress === zkAppAddress)
-            return historyLen + 1;
-        if (a.deploymentHistory) {
-            for (let i = 0; i < a.deploymentHistory.length; i++) {
-                if (a.deploymentHistory[i].zkAppAddress === zkAppAddress)
-                    return i + 1;
-            }
+// Active-instance juggling: o1js/Mina keeps a single global active network
+// instance, so multi-network handlers must switch it before making any
+// on-chain call. Wrap the region that needs a specific network in
+// withNetwork(network, () => …). Handlers that don't touch chain state
+// (local record reads, witness computation) don't need this.
+async function withNetwork(networkId, fn) {
+    const cfg = NETWORK_CONFIG[networkId];
+    if (!cfg)
+        throw new Error(`Network ${networkId} is not configured on this verifier`);
+    let release = () => { };
+    const prev = _networkMutexTail;
+    _networkMutexTail = new Promise((r) => { release = r; });
+    await prev;
+    try {
+        const stickyFallback = _activeEndpointByNetwork.get(networkId) === 'fallback';
+        activateNetworkEndpoints(cfg, stickyFallback);
+        return await fn();
+    }
+    catch (err) {
+        resetLeakedTransactionContext();
+        throw err;
+    }
+    finally {
+        release();
+    }
+}
+// Per-attempt timeout for fetchLastBlock. Sized for the SLOW path: the
+// Minascan public node (often used as fallback) frequently rate-limits and
+// can take 60–120s to return during load spikes. Cutting the timeout shorter
+// would surface as a spurious "fetchLastBlock failed" after primary is down
+// — the exact situation this fallback exists to cover. Primary endpoints
+// (minataur, self-hosted) that return quickly aren't penalized because a
+// fast success short-circuits the timer.
+const CURRENT_SLOT_TIMEOUT_MS = 180_000;
+// 5xx and 408 (o1js's own timeout stand-in) rotate to the fallback. 404 means
+// "account genuinely doesn't exist" and short-circuits — no point rotating.
+// Anything else (4xx GraphQL error, 400 malformed request) also short-circuits
+// because it's not endpoint-health related.
+function shouldRotateOnError(statusCode) {
+    if (statusCode === undefined)
+        return true; // network throw with no status — treat as transport
+    if (statusCode === 408)
+        return true;
+    if (statusCode >= 500 && statusCode <= 599)
+        return true;
+    return false;
+}
+// Manual endpoint rotation for fetchAccount. Must be called from inside a
+// withNetwork() region so the mutex prevents concurrent handlers from
+// observing a mid-flight setActiveInstance swap. On success leaves the
+// winning instance active so the next zkApp.<state>.get() cache lookup finds
+// the freshly-fetched account under the same graphql-endpoint cache key.
+async function fetchAccountWithRotation(networkId, publicKey, attempts, backoffMs = (a) => 400 * a) {
+    const cfg = NETWORK_CONFIG[networkId];
+    if (!cfg)
+        throw new Error(`Network ${networkId} is not configured on this verifier`);
+    let last = { account: undefined, error: { statusCode: 500, statusText: 'no attempt made' } };
+    let succeededOn = null;
+    const trace = [];
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        // Alternate primary / fallback across attempts when fallback exists:
+        // attempt 1 → primary, 2 → fallback, 3 → primary, …
+        const useFallback = cfg.fallbackNetwork !== null && attempt % 2 === 0;
+        const url = useFallback ? (cfg.graphqlFallback ?? cfg.graphqlUrl) : cfg.graphqlUrl;
+        activateNetworkEndpoints(cfg, useFallback);
+        last = await fetchAccount({ publicKey });
+        if (last.account) {
+            succeededOn = useFallback ? 'fallback' : 'primary';
+            trace.push({ url, outcome: 'ok' });
+            break;
         }
+        const status = last.error?.statusCode;
+        const outcome = status === 404 ? '404' : `HTTP ${status ?? '?'} ${last.error?.statusText ?? ''}`.trim();
+        trace.push({ url, outcome });
+        if (status === 404)
+            break; // real not-found
+        if (!shouldRotateOnError(status))
+            break; // non-transport error
+        if (attempt < attempts)
+            await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+    }
+    if (!last.account && last.error?.statusCode !== 404) {
+        logUtc('fetchAccountWithRotation', '✗ all attempts failed', {
+            network: networkId,
+            publicKey: publicKey.toBase58(),
+            attempts,
+            trace,
+        });
     }
-    return null;
+    if (succeededOn === null) {
+        activateNetworkEndpoints(cfg, false);
+    }
+    return last;
 }
-const OWNERSHIP_KEY_PATH = process.env.OWNERSHIP_KEY_PATH ?? join(CIRCUIT_CACHE_DIR, 'ownership-hmac.key');
-let ownershipKey;
-try {
-    ownershipKey = await fs.readFile(OWNERSHIP_KEY_PATH);
-    console.log(`🔑 Ownership HMAC key loaded from ${OWNERSHIP_KEY_PATH}`);
+// Same rotation semantics as fetchAccountWithRotation but for fetchLastBlock.
+// Wraps the o1js call in the CURRENT_SLOT_TIMEOUT_MS timeout race so a dead
+// endpoint doesn't hang the whole attempt. Must be called from inside a
+// withNetwork() region. Returns null on terminal failure so callers can decide
+// (throw, retry higher up, or degrade gracefully — currentSlot returns 0).
+async function fetchLastBlockWithRotation(networkId, attempts, backoffMs = (a) => 400 * a) {
+    const cfg = NETWORK_CONFIG[networkId];
+    if (!cfg)
+        throw new Error(`Network ${networkId} is not configured on this verifier`);
+    let succeededOn = null;
+    const trace = [];
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        const useFallback = cfg.fallbackNetwork !== null && attempt % 2 === 0;
+        const url = useFallback ? (cfg.graphqlFallback ?? cfg.graphqlUrl) : cfg.graphqlUrl;
+        activateNetworkEndpoints(cfg, useFallback);
+        try {
+            const block = await Promise.race([
+                fetchLastBlock(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`fetchLastBlock timed out after ${CURRENT_SLOT_TIMEOUT_MS}ms`)), CURRENT_SLOT_TIMEOUT_MS)),
+            ]);
+            succeededOn = useFallback ? 'fallback' : 'primary';
+            trace.push({ url, outcome: 'ok' });
+            return block;
+        }
+        catch (err) {
+            trace.push({ url, outcome: err?.message ?? String(err) });
+            if (attempt < attempts)
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+        }
+    }
+    if (succeededOn === null) {
+        activateNetworkEndpoints(cfg, false);
+    }
+    logUtc('fetchLastBlockWithRotation', '✗ all attempts failed', {
+        network: networkId,
+        attempts,
+        trace,
+    });
+    return null;
 }
-catch {
-    ownershipKey = newOwnershipKey();
-    await fs.writeFile(OWNERSHIP_KEY_PATH, ownershipKey, { mode: 0o600 });
-    console.log(`🔑 Ownership HMAC key generated → ${OWNERSHIP_KEY_PATH}`);
+// UTC-stamped structured log. Arrays/objects in `extra` are JSON-stringified
+// so per-attempt traces don't render as [object Object].
+function logUtc(scope, msg, extra) {
+    const ts = new Date().toISOString();
+    const tail = extra
+        ? ' ' + Object.entries(extra).map(([k, v]) => {
+            const s = (v !== null && typeof v === 'object') ? JSON.stringify(v) : `${v}`;
+            return `${k}=${s}`;
+        }).join(' ')
+        : '';
+    console.log(`[${ts}] [${scope}] ${msg}${tail}`);
 }
+// Default the active instance to whichever network is configured (mainnet
+// wins if both are up, so idle background code without explicit context lands
+// on the production network). withNetwork() overrides this per-request.
+activateNetworkEndpoints((NETWORK_CONFIG.mainnet ?? NETWORK_CONFIG.devnet), false);
 // ------------------------------------------------------------
 // HELPERS
 // ------------------------------------------------------------
-async function currentSlot() {
+// Fetch the current slot on the specified network. Rotation-aware. Callers
+// that need the value in a broader on-chain region should pass the network
+// they already resolved from the zkAppAddress.
+async function currentSlot(network) {
     try {
-        const block = await fetchLastBlock();
+        const block = await withNetwork(network, () => fetchLastBlockWithRotation(network, 3));
+        if (!block)
+            return 0;
         return Number(block.globalSlotSinceGenesis.toString());
     }
-    catch {
+    catch (e) {
+        logUtc('currentSlot', '✗ fetchLastBlock failed', { network, reason: e?.message ?? String(e) });
         return 0;
     }
 }
-const APPS_FILE = 'apps.json';
-async function readApps() {
+// Return an error message if `zkAppAddress` isn't a well-formed B62q address,
+// null otherwise. Called at request-parse time so garbage input fails with a
+// legible 400 in a couple of ms instead of ~1 s of proof-verify CPU followed
+// by a generic 502 from `fromBase58` throwing deep inside checkOnChainLicense.
+function validateZkAppAddress(zkAppAddress) {
     try {
-        return JSON.parse(await fs.readFile(APPS_FILE, 'utf8'));
+        PublicKey.fromBase58(zkAppAddress);
+        return null;
+    }
+    catch (err) {
+        return `Invalid zkAppAddress: ${err?.message || 'not a valid Mina B62q address'}`;
     }
-    catch {
-        return [];
+}
+// Resolve a zkAppAddress to its owning AppRecord + network + deployment
+// slice. Walks both networks' current-live address and every entry in
+// deploymentHistory. Under the backend-routing design a buyer who pinned an
+// original gen-1 address stays valid forever even after N generation bumps.
+function resolveAppAndNetwork(apps, zkAppAddress) {
+    for (const app of apps) {
+        for (const net of NETWORKS) {
+            const dep = app.deployments[net];
+            if (!dep)
+                continue;
+            if (dep.zkAppAddress === zkAppAddress ||
+                (dep.deploymentHistory ?? []).some(h => h.zkAppAddress === zkAppAddress)) {
+                return { app, network: net, deployment: dep };
+            }
+        }
     }
+    return null;
+}
+// Fetch fresh on-chain state and delegate address routing + ancestor walk
+// to verifyLicenseWithAncestors. Resolves the target network from the
+// zkAppAddress; unknown addresses (not in any configured network's registry)
+// surface as `unregistered-address`. Throws only on network / RPC failure.
+//
+// The `generation` field echoes the *request* address's own stable
+// generation, so a client that pinned an older address at build time sees
+// a token whose `g` still matches its local expectation across bumps.
+async function checkOnChainLicense(zkAppAddress, licenseHash) {
+    const apps = await readApps();
+    const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+    if (!resolved)
+        return { kind: 'unregistered-address' };
+    const { network, deployment } = resolved;
+    if (!NETWORK_CONFIG[network])
+        return { kind: 'unregistered-address' };
+    const historyLen = deployment.deploymentHistory?.length ?? 0;
+    const currentGeneration = historyLen + 1;
+    const currentLive = deployment.zkAppAddress;
+    // Echo: the request address's own stable generation. Stays consistent
+    // across bumps for any client that pinned an older address.
+    let requestGeneration = currentGeneration;
+    if (zkAppAddress !== currentLive) {
+        const idx = (deployment.deploymentHistory ?? []).findIndex((d) => d.zkAppAddress === zkAppAddress);
+        if (idx >= 0)
+            requestGeneration = idx + 1;
+    }
+    // Sequential (was Promise.all): the rotation helpers do Mina.setActiveInstance
+    // internally, so running fetchAccount + fetchLastBlock in parallel would race
+    // the instance swap. Same pattern as the backend sweep.
+    const records = await readRecords();
+    const { account } = await withNetwork(network, () => fetchAccountWithRotation(network, PublicKey.fromBase58(currentLive), 3));
+    const lastBlock = await withNetwork(network, () => fetchLastBlockWithRotation(network, 3));
+    if (!lastBlock) {
+        throw new Error('fetchLastBlock failed');
+    }
+    const currentRoot = account?.zkapp?.appState?.[0]?.toString();
+    if (!currentRoot)
+        return { kind: 'zkapp-not-found' };
+    // `version` is state slot 5 (licensesRoot, vendor ×2, escrowRoot,
+    // pricesPacked, version, …).
+    const zkAppVersion = Number(account?.zkapp?.appState?.[5]?.toString() ?? '0');
+    // The live contract must run one of the published circuits. Pinned by
+    // circuit, not by this app's redeploy count: a redeploy doesn't imply a
+    // new circuit (and an app deployed after a circuit bump starts at app
+    // generation 1 on the newer circuit). Fail closed when the VK is missing
+    // or unknown — previously a redeployed app had no table entry for its
+    // generation and the check was skipped entirely.
+    const onChainVk = account?.zkapp?.verificationKey?.hash?.toString();
+    if (!onChainVk || !Object.values(CANONICAL_VK_HASHES).includes(onChainVk)) {
+        return { kind: 'vk-mismatch', generation: currentGeneration };
+    }
+    const currentSlotNum = Number(lastBlock.globalSlotSinceGenesis.toString());
+    // verifyLicenseWithAncestors uses bare fetchAccount internally on retired
+    // addresses — wrap it in withNetwork so the active instance points at the
+    // correct network for the whole walk.
+    const walked = await withNetwork(network, () => verifyLicenseWithAncestors({
+        deployment,
+        licenseHash,
+        currentSlot: currentSlotNum,
+        currentLiveRoot: currentRoot,
+        currentLiveForkSlot: Number(account?.zkapp?.appState?.[LICENSING_APP_STATE.forkActivationSlot]?.toString() ?? '0'),
+        records,
+    }));
+    return {
+        kind: 'checked',
+        onChainRoot: walked.onChainRoot,
+        currentSlot: currentSlotNum,
+        zkAppVersion,
+        generation: requestGeneration,
+        resolvedAddress: walked.resolvedAddress,
+        liveRecords: walked.liveRecords,
+        result: walked.result,
+    };
+}
+const APPS_FILE = 'apps.json';
+async function readApps() {
+    return readJsonOr(APPS_FILE, []);
 }
 // ------------------------------------------------------------
 // EXPRESS SERVER
@@ -230,6 +436,26 @@ app.use((_req, res, next) => {
     }
     next();
 });
+// Per-request access log. One line per request: method + path + status + ms.
+// Skips CORS preflights (already short-circuited above with 204). Path is the
+// raw req.path — query strings are dropped so the licenseHash from `GET /`
+// doesn't leak into logs (the redacted-prefix log on the / handler below is
+// the canonical place to see which license was queried).
+// Toggle off with VERIFY_ACCESS_LOG=off if the verifier ever runs behind a
+// hot-path API where per-request lines become noise.
+const ACCESS_LOG_ENABLED = (process.env.VERIFY_ACCESS_LOG ?? '').toLowerCase() !== 'off';
+if (ACCESS_LOG_ENABLED) {
+    app.use((req, res, next) => {
+        const started = Date.now();
+        res.on('finish', () => {
+            logUtc('access', `${req.method} ${req.path}`, {
+                status: res.statusCode,
+                elapsed_ms: Date.now() - started,
+            });
+        });
+        next();
+    });
+}
 const VERIFY_ADMIN_TOKEN = process.env.VERIFY_ADMIN_TOKEN ?? '';
 function requireAdmin(req, res, next) {
     if (!VERIFY_ADMIN_TOKEN) {
@@ -244,11 +470,29 @@ function requireAdmin(req, res, next) {
     }
     next();
 }
-// Health
+// Health.
+//
+// `networkId` per entry is the authoritative "which Mina chain" answer — a
+// stable identifier the client can compare against exactly. `network` (the
+// raw GraphQL URL) is kept for operator-facing observability only, since it
+// can rotate providers (Minascan ↔ Minataur ↔ self-hosted) without the chain
+// changing. `fallback` mirrors the same for the configured fallback endpoint.
 app.get('/health', (_req, res) => {
-    res.json({ status: 'ok', service: 'verify', network: MINA_GRAPHQL_URL });
+    const networks = {};
+    for (const net of NETWORKS) {
+        const cfg = NETWORK_CONFIG[net];
+        if (!cfg)
+            continue;
+        networks[net] = {
+            networkId: cfg.networkId,
+            network: cfg.graphqlUrl,
+            fallback: cfg.graphqlFallback,
+        };
+    }
+    res.json({ status: 'ok', service: 'verify', networks });
 });
-// Current MerkleMap root for a specific zkApp.
+// Current MerkleMap root for a specific zkApp. Network-agnostic — reads local
+// records only.
 app.get('/root', async (req, res) => {
     const zkAppAddress = req.query.zkApp ?? '';
     if (!zkAppAddress) {
@@ -258,308 +502,99 @@ app.get('/root', async (req, res) => {
     const map = buildMap(records, zkAppAddress);
     res.json({ root: map.getRoot().toString() });
 });
-// GET /challenge?licenseHash=...
-// Issues a nonce for the ownership challenge-response flow.
-app.get('/challenge', (req, res) => {
-    const licenseHash = String(req.query.licenseHash ?? '');
-    if (!licenseHash) {
-        return res.status(400).json({ error: 'Missing licenseHash' });
-    }
-    res.json(ownershipChallenges.issue(licenseHash));
-});
-// POST /respond — body: { zkAppAddress, proof }
-// Verifies a LicenseProof against the issued nonce, consumes the nonce,
-// enforces the vendor's concurrent-device cap (if any), and returns
-// { ownership: 'verified', token, expiresAt, jti, activeSessions, deviceLimit }
-// on success. On cap overflow returns 429 without minting a token — clients
-// must release a seat (POST /releaseSeat), reset all sessions (POST
-// /reset-sessions), or wait for the oldest to hit TTL.
-app.post('/respond', async (req, res) => {
-    await ensureCompiled();
-    if (!licenseProofVk) {
-        return res.status(503).json({ error: 'Verify service not ready — circuits compiling' });
-    }
-    const { zkAppAddress, proof: proofJson } = req.body;
-    if (!zkAppAddress || !proofJson) {
-        return res.status(400).json({ error: 'Missing zkAppAddress or proof' });
-    }
-    let proof;
-    try {
-        proof = await LicenseProofProof.fromJSON(proofJson);
-    }
-    catch {
-        return res.status(400).json({ error: 'Invalid proof format' });
-    }
-    let proofValid = false;
-    try {
-        proofValid = await verify(proof, licenseProofVk);
-    }
-    catch {
-        return res.status(400).json({ error: 'Proof verification threw' });
-    }
-    if (!proofValid) {
-        return res.status(400).json({ error: 'Proof is cryptographically invalid' });
-    }
-    const licenseHash = proof.publicInput.licenseHash.toString();
-    const nonce = proof.publicInput.nonce.toString();
-    const nonceState = ownershipChallenges.consume(licenseHash, nonce);
-    if (nonceState !== 'ok') {
-        return res.status(400).json({ error: `Nonce ${nonceState} — request a fresh /challenge` });
-    }
-    // Concurrent-device cap enforcement. Read the vendor's per-app limit
-    // (0/undefined = unlimited) and try to reserve a session slot BEFORE
-    // minting the HMAC — a token without a matching session-store entry is
-    // dead on arrival at GET / anyway, so refusing here avoids handing the
-    // caller a bearer that they can only use to be rejected.
-    const app_record = await loadAppByAddress(zkAppAddress);
-    const cap = Math.max(0, Math.floor(app_record?.maxConcurrentDevices ?? 0));
-    const jti = newJti();
-    const exp = Date.now() + OWNERSHIP_TOKEN_TTL_MS;
-    const reserved = ownershipSessions.insert(licenseHash, jti, exp, cap);
-    if (reserved.state === 'at-cap') {
-        return res.status(429).json({
-            error: 'Concurrent-device limit reached — release a seat, run POST /reset-sessions, or wait for the oldest session to expire',
-            activeSessions: reserved.active,
-            deviceLimit: cap,
-        });
-    }
-    const token = signOwnershipToken(ownershipKey, { z: zkAppAddress, l: licenseHash, e: exp, jti });
-    res.json({
-        ownership: 'verified',
-        token,
-        expiresAt: exp,
-        jti,
-        activeSessions: reserved.active,
-        deviceLimit: cap,
-    });
-});
-// POST /releaseSeat — body: { token }
-// Releases the seat identified by the token's jti. Possession of the token
-// is authorization to release it (same threat model as any bearer token);
-// no proof-of-ownership is required. Enables an in-app "log out this device"
-// button. Idempotent — a second call with the same token silently no-ops.
-app.post('/releaseSeat', (req, res) => {
-    const { token } = req.body;
-    if (!token)
-        return res.status(400).json({ error: 'Missing token' });
-    const payload = verifyOwnershipToken(ownershipKey, token);
-    if (!payload)
-        return res.status(401).json({ error: 'Invalid or expired token' });
-    if (!payload.jti) {
-        // Pre-jti tokens aren't tracked in the session store, so there's no seat
-        // to release. Return 200 for idempotency — the caller's intent (log this
-        // device out) is satisfied by the local token delete.
-        return res.json({ ok: true, released: false, reason: 'token has no jti (pre-jti issue)' });
-    }
-    const released = ownershipSessions.releaseSeat(payload.l, payload.jti);
-    res.json({ ok: true, released, jti: payload.jti });
-});
-// POST /refresh — body: { token }
-// Extends the lifetime of the current session without a fresh ownership proof.
-// The caller sends the token they already hold; the server verifies the HMAC,
-// checks the jti is still active in the session store (i.e. not released or
-// evicted), and issues a new token with the same jti and a fresh exp. The
-// session store's insert is idempotent per jti, so no cap check is needed —
-// the slot was already reserved at /respond time.
-//
-// Intended for background renewal from a running app: the client polls this
-// endpoint before the token expires so a user who keeps the app open never
-// has to redo the passphrase-gated challenge/response. A stolen token can be
-// refreshed too, which is why /releaseSeat exists — losing a device means the
-// owner explicitly logs it out, and subsequent refreshes fail.
-//
-// Pre-jti tokens (legacy /respond without session tracking) can also refresh:
-// they're valid HMAC, they carry no jti, and there's no session-store row to
-// gate against. The reissued token is identically pre-jti. Callers that want
-// concurrency enforcement must reissue via /respond so a jti gets minted.
-app.post('/refresh', (req, res) => {
-    const { token } = req.body;
-    if (!token)
-        return res.status(400).json({ error: 'Missing token' });
-    const payload = verifyOwnershipToken(ownershipKey, token);
-    if (!payload)
-        return res.status(401).json({ error: 'Invalid or expired token' });
-    const newExp = Date.now() + OWNERSHIP_TOKEN_TTL_MS;
-    if (payload.jti) {
-        if (!ownershipSessions.has(payload.l, payload.jti)) {
-            return res.status(401).json({ error: 'Seat released' });
-        }
-        // Idempotent for existing jti — updates the expiry, never trips the cap.
-        ownershipSessions.insert(payload.l, payload.jti, newExp, 0);
-    }
-    const next = {
-        z: payload.z,
-        l: payload.l,
-        e: newExp,
-        ...(payload.jti ? { jti: payload.jti } : {}),
-    };
-    const nextToken = signOwnershipToken(ownershipKey, next);
-    res.json({ token: nextToken, expiresAt: newExp, jti: payload.jti });
-});
-// POST /reset-sessions — body: { zkAppAddress, proof }
-// Drops ALL active sessions for the licenseHash proved by the LicenseProof.
-// Requires the same challenge/response as /respond — only the passphrase
-// holder can invoke it. Intended for "reinstall unsticks a device that
-// burned a slot without logging out" recovery. After this returns, the
-// caller runs a fresh /respond to re-provision a session under a zero
-// active count.
-app.post('/reset-sessions', async (req, res) => {
-    await ensureCompiled();
-    if (!licenseProofVk) {
-        return res.status(503).json({ error: 'Verify service not ready — circuits compiling' });
-    }
-    const { zkAppAddress, proof: proofJson } = req.body;
-    if (!zkAppAddress || !proofJson) {
-        return res.status(400).json({ error: 'Missing zkAppAddress or proof' });
-    }
-    let proof;
-    try {
-        proof = await LicenseProofProof.fromJSON(proofJson);
-    }
-    catch {
-        return res.status(400).json({ error: 'Invalid proof format' });
-    }
-    let proofValid = false;
-    try {
-        proofValid = await verify(proof, licenseProofVk);
-    }
-    catch {
-        return res.status(400).json({ error: 'Proof verification threw' });
-    }
-    if (!proofValid) {
-        return res.status(400).json({ error: 'Proof is cryptographically invalid' });
-    }
-    const licenseHash = proof.publicInput.licenseHash.toString();
-    const nonce = proof.publicInput.nonce.toString();
-    const nonceState = ownershipChallenges.consume(licenseHash, nonce);
-    if (nonceState !== 'ok') {
-        return res.status(400).json({ error: `Nonce ${nonceState} — request a fresh /challenge` });
-    }
-    const dropped = ownershipSessions.reset(licenseHash);
-    res.json({ ok: true, dropped });
-});
-// GET /?licenseHash=...&zkAppAddress=...[&token=...]
-// Primary endpoint for Android, iOS, PWA, and Node SDK license verification.
-//
-// Ownership semantics:
-//  - Without `token`, the response describes the state of the on-chain leaf
-//    only — it does NOT prove the caller owns the license. This is fine for
-//    status displays; gate access behind /respond or pass a fresh
-//    activation `token` in the query string.
-//  - With `token`, the service checks the HMAC and refuses if the token isn't
-//    for this (zkAppAddress, licenseHash) pair.
+// GET /?licenseHash=...&zkAppAddress=...
+// Primary endpoint for Android, PWA, and Node SDK license verification.
+// Describes the on-chain state of the requested license leaf — validity,
+// expiry slot, grace-period flag, purchaseSlot. Callers that need to prove
+// ownership of the license (e.g. before revealing app features) do so via
+// the passphrase-derived Pallas Schnorr keypair off-band — this endpoint is
+// state-only.
 app.get('/', async (req, res) => {
-    const { licenseHash: licenseHashStr, zkAppAddress, token } = req.query;
+    const { licenseHash: licenseHashStr, zkAppAddress } = req.query;
     if (!licenseHashStr || !zkAppAddress) {
         return res.status(400).json({ error: 'Missing required query params: licenseHash, zkAppAddress' });
     }
-    let ownershipVerified = false;
-    if (token) {
-        const payload = verifyOwnershipToken(ownershipKey, token);
-        if (!payload || payload.z !== zkAppAddress || payload.l !== licenseHashStr) {
-            return res.status(401).json({ error: 'Invalid or expired ownership token' });
-        }
-        // Session-store gate: a jti-bearing token must still be in the active-
-        // session set for its license. A token whose jti was released (via
-        // /releaseSeat, /reset-sessions, or evicted by TTL prune) is refused even if
-        // it's still HMAC-valid and inside its exp. Pre-jti tokens (issued
-        // before the session-tracking rollout) skip this check and remain
-        // usable until their exp — no forced logout across the migration.
-        if (payload.jti && !ownershipSessions.has(payload.l, payload.jti)) {
-            return res.status(401).json({ error: 'Seat released — call POST /respond to acquire a fresh token' });
-        }
-        ownershipVerified = true;
-    }
-    try {
-        const [records, { account }, lastBlock] = await Promise.all([
-            readRecords(),
-            fetchAccount({ publicKey: PublicKey.fromBase58(zkAppAddress) }),
-            fetchLastBlock(),
-        ]);
-        const onChainRoot = account?.zkapp?.appState?.[0]?.toString();
-        if (!onChainRoot) {
-            return res.status(404).json({ error: 'zkApp not found on chain' });
-        }
-        // Source-version tag from the already-fetched account state — free byte
-        // for the SDK / dashboard to label which protocol revision a license lives
-        // on. Not a security gate (that's the boot + bootstrap check); purely
-        // informational.
-        const zkAppVersion = Number(account?.zkapp?.appState?.[7]?.toString() ?? '0');
-        // Defense in depth against impersonation. The contract locks
-        // `setVerificationKey` via `Permissions.VerificationKey
-        // .impossibleDuringCurrentVersion()` plus deploy-key disposal, so VK
-        // rotation post-deploy is impossible for any *listed* address. The check
-        // below resolves the address's generation via keeper deploymentHistory
-        // and asserts its on-chain VK equals that generation's canonical hash.
-        // Two failure modes: (a) the address is unknown (not the current live
-        // deployment of any registered app, not in any deploymentHistory[]) —
-        // reject; that stops a genuine old circuit deployed at a fresh address.
-        // (b) the address is listed but its VK doesn't equal its generation's
-        // hash — reject; that's a loud index-corruption tripwire.
-        const onChainVk = account?.zkapp?.verificationKey?.hash?.toString();
-        const generation = await resolveGenerationByAddress(zkAppAddress);
-        if (generation === null) {
-            return res.json({
-                valid: false,
-                expiresAt: null,
-                expirySlot: 0,
-                inGracePeriod: false,
-                remainingDays: 0,
-                reason: 'zkAppAddress is not in any registered app deployment history',
-                ownership: ownershipVerified ? 'verified' : 'unverified',
-            });
-        }
-        const expectedVk = CANONICAL_VK_HASHES[generation];
-        if (expectedVk && onChainVk !== expectedVk) {
-            return res.json({
-                valid: false,
-                expiresAt: null,
-                expirySlot: 0,
-                inGracePeriod: false,
-                remainingDays: 0,
-                reason: `zkApp verification key does not match generation ${generation}'s canonical LicensingApp circuit`,
-                ownership: ownershipVerified ? 'verified' : 'unverified',
-            });
-        }
-        const currentSlot = Number(lastBlock.globalSlotSinceGenesis.toString());
-        let liveRecords = records;
-        let result = verifyLicenseCore({
-            zkAppAddress,
-            licenseHash: licenseHashStr,
-            records: liveRecords,
-            onChainRoot,
-            currentSlot,
+    // Per-request verdict log. Redacts licenseHash to a 12-char prefix so logs
+    // stay pseudonymous but retain enough entropy to correlate a user's report
+    // ("my activation says invalid at 03:52") to the exact decision without
+    // grepping full hashes. resolvedAddress lets you see when an older
+    // generation was the actual match (pre-bump buyer).
+    const startedAt = Date.now();
+    const hashShort = licenseHashStr.slice(0, 12) + '…';
+    const emitVerdict = (verdict, reason, resolvedAddress) => {
+        logUtc('verify', 'verdict', {
+            licenseHash: hashShort,
+            zkAppAddress: zkAppAddress.slice(0, 12) + '…',
+            resolvedAddress: resolvedAddress ? resolvedAddress.slice(0, 12) + '…' : undefined,
+            verdict,
+            reason: reason ?? undefined,
+            elapsed_ms: Date.now() - startedAt,
         });
-        // Lazy self-heal: a root mismatch means the local store is stale (a
-        // license has been bought, renewed, or refunded since we last replayed).
-        // One replay + one retry is enough — the on-chain root is the source of
-        // truth and the archive node will reflect it.
-        if (!result.valid && result.reason === 'License state does not match on-chain root') {
-            await lazyBootstrap(zkAppAddress);
-            liveRecords = await readRecords();
-            result = verifyLicenseCore({
-                zkAppAddress,
-                licenseHash: licenseHashStr,
-                records: liveRecords,
-                onChainRoot,
-                currentSlot,
-            });
+    };
+    // Defense-in-depth against impersonation: the helper resolves the address's
+    // generation via backend deploymentHistory and asserts its on-chain VK equals
+    // that generation's canonical hash. Two rejection modes it covers: (a) the
+    // address is not in any registered app's deployment history — stops a
+    // genuine old circuit redeployed at a fresh address; (b) the address is
+    // listed but its VK doesn't match — a loud index-corruption tripwire.
+    try {
+        const onChain = await checkOnChainLicense(zkAppAddress, licenseHashStr);
+        switch (onChain.kind) {
+            case 'zkapp-not-found':
+                emitVerdict('zkapp-not-found');
+                return res.status(404).json({ error: 'zkApp not found on chain' });
+            case 'unregistered-address':
+                emitVerdict('unregistered-address');
+                return res.json({
+                    valid: false,
+                    expiresAt: null,
+                    expirySlot: 0,
+                    inGracePeriod: false,
+                    remainingDays: 0,
+                    reason: 'zkAppAddress is not in any registered app deployment history',
+                });
+            case 'vk-mismatch':
+                emitVerdict('vk-mismatch', `generation=${onChain.generation}`);
+                return res.json({
+                    valid: false,
+                    expiresAt: null,
+                    expirySlot: 0,
+                    inGracePeriod: false,
+                    remainingDays: 0,
+                    reason: `zkApp verification key does not match generation ${onChain.generation}'s canonical LicensingApp circuit`,
+                });
+            case 'checked': {
+                // Key on resolvedAddress (the address the license was actually found
+                // under) rather than the request address — for pre-bump buyers who
+                // never migrated, these differ: request is the retired addr the
+                // client pinned, resolved is the retired addr the record lives on.
+                const record = onChain.liveRecords.find(r => r.zkAppAddress === onChain.resolvedAddress && r.licenseHash === licenseHashStr);
+                // Collapse the VerifyResponse shape into a single-word verdict for
+                // log scanning: valid | grace | invalid. `invalid` carries the
+                // core's own reason string ("License not found", "License state
+                // does not match on-chain root", …) so the log line is enough to
+                // triage without opening the JSON body.
+                const verdict = onChain.result.valid
+                    ? (onChain.result.inGracePeriod ? 'grace' : 'valid')
+                    : 'invalid';
+                emitVerdict(verdict, onChain.result.reason, onChain.resolvedAddress);
+                return res.json({
+                    ...onChain.result,
+                    currentSlot: onChain.currentSlot,
+                    purchaseSlot: record?.purchaseSlot ?? 0,
+                    zkAppVersion: onChain.zkAppVersion,
+                });
+            }
         }
-        const record = liveRecords.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHashStr);
-        return res.json({
-            ...result,
-            currentSlot,
-            purchaseSlot: record?.purchaseSlot ?? 0,
-            ownership: ownershipVerified ? 'verified' : 'unverified',
-            zkAppVersion,
-        });
     }
     catch (err) {
+        emitVerdict('error', err?.message ?? String(err));
         console.error('[verify]', err?.message ?? err);
         res.status(500).json({ error: err?.message ?? 'Verification failed' });
     }
 });
-// License map witness — composite (zkAppAddress, licenseHash) key.
+// License map witness — composite (zkAppAddress, licenseHash) key. Network-
+// agnostic — witness comes from the local MerkleMap of records.
 app.get('/witness/:zkAppAddress/:licenseHash', async (req, res) => {
     const { zkAppAddress, licenseHash } = req.params;
     try {
@@ -578,16 +613,31 @@ app.get('/witness/:zkAppAddress/:licenseHash', async (req, res) => {
     }
 });
 // License status — composite (zkAppAddress, licenseHash) key.
+// deviceCap + devices ride along so vendor SDKs can drive their bind flow
+// (activate() reads these to decide whether to prompt for a bind and which
+// slot to target). Sourced from the license record, which is the on-chain
+// mirror populated by eventSyncLoop from DeviceBound/DeviceUnbound events.
 app.get('/license/:zkAppAddress/:licenseHash', async (req, res) => {
     const { zkAppAddress, licenseHash } = req.params;
     const record = await getLicense(zkAppAddress, licenseHash);
-    const slot = await currentSlot();
-    const status = licenseStatus(record, slot);
+    // Resolve the address's network so currentSlot hits the right chain. An
+    // unregistered address (or one whose network isn't configured here) falls
+    // back to slot 0 — status computation still returns a sensible verdict from
+    // the record's own expirySlot.
+    const apps = await readApps();
+    const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+    const slot = resolved && NETWORK_CONFIG[resolved.network]
+        ? await currentSlot(resolved.network)
+        : 0;
+    const fork = resolved?.deployment.zkAppAddress === zkAppAddress ? resolved.deployment.forkActivationSlot ?? 0 : 0;
+    const status = licenseStatus(record, slot, fork);
     res.json({
         found: record !== null,
         expirySlot: record?.expirySlot ?? 0,
         status,
         txHash: record?.txHash ?? null,
+        deviceCap: record?.deviceCap ?? 0,
+        devices: record?.devices ?? [],
     });
 });
 // List registered apps
@@ -605,11 +655,23 @@ app.post('/bootstrap', requireAdmin, async (req, res) => {
     if (!zkAppAddress) {
         return res.status(400).json({ error: 'Missing zkAppAddress' });
     }
+    const addrErr = validateZkAppAddress(zkAppAddress);
+    if (addrErr)
+        return res.status(400).json({ error: addrErr });
     try {
+        const apps = await readApps();
+        const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+        if (!resolved) {
+            return res.status(400).json({ error: `zkAppAddress not in any registered app deployment history` });
+        }
+        const { network } = resolved;
+        if (!NETWORK_CONFIG[network]) {
+            return res.status(400).json({ error: `zkAppAddress belongs to ${network} but that network is not configured on this verifier` });
+        }
         // Refuse to replay a zkApp whose immutable source-version tag doesn't match
         // one this verifier understands. Otherwise a v2-deployed contract's events
         // could be decoded with a v1 schema and yield subtly wrong state.
-        const onChainVersion = await fetchLicensingAppVersion(zkAppAddress);
+        const onChainVersion = await withNetwork(network, () => fetchLicensingAppVersion(zkAppAddress));
         if (onChainVersion === null) {
             return res.status(400).json({ error: `zkApp ${zkAppAddress.slice(0, 16)}… not visible on chain` });
         }
@@ -618,8 +680,9 @@ app.post('/bootstrap', requireAdmin, async (req, res) => {
                 error: `unsupported LicensingApp version — on-chain v${onChainVersion}, this verifier supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}`,
             });
         }
-        console.log(`[bootstrap] Replaying events for ${zkAppAddress.slice(0, 16)}… (v${onChainVersion}) from ${archiveUrl}`);
-        const { events } = await bootstrapFromArchive(zkAppAddress);
+        const cfg = NETWORK_CONFIG[network];
+        console.log(`[bootstrap] Replaying events for ${zkAppAddress.slice(0, 16)}… (${network} v${onChainVersion}) from ${cfg.archiveUrl}`);
+        const { events } = await withNetwork(network, () => bootstrapFromArchive(zkAppAddress));
         const { count, warnings } = await applyEventsToStore(zkAppAddress, events);
         for (const w of warnings)
             console.warn('[bootstrap]', w);
@@ -635,32 +698,43 @@ app.post('/bootstrap', requireAdmin, async (req, res) => {
 // START
 // ------------------------------------------------------------
 let records = await readRecords();
-// Auto-bootstrap from archive if store is empty.
+// Auto-bootstrap from archive if store is empty. Iterates every configured
+// network and each of that network's registered apps. Apps whose network
+// isn't configured on this verifier are skipped silently.
 if (records.length === 0) {
     const apps = await readApps();
-    if (apps.length > 0) {
-        console.log(`📦 licenses.json is empty — bootstrapping ${apps.length} app(s) from archive node…`);
-        for (const appRecord of apps) {
+    const configuredNetworks = NETWORKS.filter(n => !!NETWORK_CONFIG[n]);
+    const bootstrapPlan = [];
+    for (const network of configuredNetworks) {
+        for (const app of apps) {
+            const dep = app.deployments[network];
+            if (dep)
+                bootstrapPlan.push({ network, app, dep });
+        }
+    }
+    if (bootstrapPlan.length > 0) {
+        console.log(`📦 licenses.json is empty — bootstrapping ${bootstrapPlan.length} app deployment(s) from archive node…`);
+        for (const { network, app: appRecord, dep } of bootstrapPlan) {
             try {
                 // Same version guard as POST /bootstrap — refuse to replay any address
                 // whose on-chain source-version tag this verifier doesn't understand.
-                const onChainVersion = await fetchLicensingAppVersion(appRecord.zkAppAddress);
+                const onChainVersion = await withNetwork(network, () => fetchLicensingAppVersion(dep.zkAppAddress));
                 if (onChainVersion === null) {
-                    console.warn(`   ⚠️  ${appRecord.name}: zkApp not visible on chain — skipping`);
+                    console.warn(`   ⚠️  ${appRecord.name} (${network}): zkApp not visible on chain — skipping`);
                     continue;
                 }
                 if (!SUPPORTED_LICENSING_APP_VERSIONS.includes(onChainVersion)) {
-                    console.warn(`   ⚠️  ${appRecord.name}: on-chain v${onChainVersion} not supported (supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}) — skipping`);
+                    console.warn(`   ⚠️  ${appRecord.name} (${network}): on-chain v${onChainVersion} not supported (supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}) — skipping`);
                     continue;
                 }
-                const { events } = await bootstrapFromArchive(appRecord.zkAppAddress);
-                const { count, warnings } = await applyEventsToStore(appRecord.zkAppAddress, events);
+                const { events } = await withNetwork(network, () => bootstrapFromArchive(dep.zkAppAddress));
+                const { count, warnings } = await applyEventsToStore(dep.zkAppAddress, events);
                 for (const w of warnings)
                     console.warn('⚠️', w);
-                console.log(`   ✅ ${appRecord.name} (v${onChainVersion}): ${count} records`);
+                console.log(`   ✅ ${appRecord.name} (${network} v${onChainVersion}): ${count} records`);
             }
             catch (err) {
-                console.warn(`   ⚠️  ${appRecord.name}: bootstrap failed — ${err?.message ?? err}`);
+                console.warn(`   ⚠️  ${appRecord.name} (${network}): bootstrap failed — ${err?.message ?? err}`);
             }
         }
         records = await readRecords();
@@ -669,12 +743,7 @@ if (records.length === 0) {
 console.log(`📋 Loaded ${records.length} license records across ${new Set(records.map(r => r.zkAppAddress)).size} zkApp(s)`);
 app.listen(PORT, () => {
     console.log(`🔍 Verify service listening on http://localhost:${PORT}`);
-    console.log(`   GET  /?licenseHash=...&zkAppAddress=...[&token=...]`);
-    console.log(`   GET  /challenge?licenseHash=...`);
-    console.log(`   POST /respond`);
-    console.log(`   POST /refresh`);
-    console.log(`   POST /releaseSeat`);
-    console.log(`   POST /reset-sessions`);
+    console.log(`   GET  /?licenseHash=...&zkAppAddress=...`);
     console.log(`   GET  /witness/:zkAppAddress/:licenseHash`);
     console.log(`   GET  /license/:zkAppAddress/:licenseHash`);
     console.log(`   GET  /apps`);
@@ -686,5 +755,6 @@ app.listen(PORT, () => {
         console.log(`⚠️  Admin endpoints disabled (set VERIFY_ADMIN_TOKEN to enable)`);
     }
     console.log(`🔁 Lazy bootstrap on root mismatch (no periodic poller)`);
+    console.log(`📝 Access log: ${ACCESS_LOG_ENABLED ? 'ON' : 'off (VERIFY_ACCESS_LOG=off)'}`);
 });
 //# sourceMappingURL=verifyService.js.map