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

package/src/permitProof.ts

@@ -0,0 +1,230 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitProof.ts — `zklicensing/permits/proof`
+ *
+ * Zero-knowledge proof that the prover holds an active permit in a registry
+ * (PERMITS_PLAN.md §7.2), without revealing which permit or which key:
+ *
+ *   public:  registry, root, slot, requiredScope, context
+ *   output:  nullifier = Poseidon(holder secret, context)
+ *   private: the permit leaf, its Merkle witness, the holder secret, and the
+ *            holder's signature over (registry, root, context)
+ *
+ * The verifier checks the proof, that `root` is a recent root of the
+ * registry (from a Mina node, or the keeper's /roots), that `slot` is close
+ * to now, and — if it wants one use per holder per context — that the
+ * nullifier is new. Proving runs on the holder's device: it needs the
+ * holder's signature and secret, which never leave it.
+ *
+ * The holder secret: permit subjects are public (each permit is published
+ * with its subject), so a nullifier computed from the subject could be
+ * recomputed by anyone for every permit and matched. The nullifier is
+ * computed from a secret only the holder's wallet can produce instead: the
+ * hash of its text signature over (registry, network, a counter), which is
+ * deterministic, so the same wallet re-derives it anywhere from the chain
+ * alone (holderSecret.ts). The permit's
+ * salt is the hash of that secret, so the keeper and the authority, who see
+ * the salt, still cannot compute nullifiers; and one secret per permit keeps
+ * one nullifier per permit and context.
+ */
+
+import { Field, MerkleMapWitness, Poseidon, PublicKey, Signature, Struct, UInt32, ZkProgram } from 'o1js';
+import {
+  PermitLeaf, permitLeafHash, permitSubject, PERMIT_STATUS_ACTIVE,
+} from './permitMessages.js';
+import { saltFromHolderSecret } from './holderSecret.js';
+
+/** Tag for the holder's proof signature (distinct from every registry message). */
+export const PERMIT_PROOF_TAG: Field = Field([...'zkPermits/v1/proof'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+
+export const PermitProofInput: any = Struct({
+  registry: PublicKey,
+  root: Field,
+  slot: UInt32,
+  requiredScope: Field,
+  context: Field,
+});
+export type PermitProofInput = any;
+
+/** The message the holder signs to prove control of the permit's key. */
+export function holderProofMessage(registry: PublicKey, root: Field, context: Field): Field[] {
+  return [PERMIT_PROOF_TAG, ...registry.toFields(), root, context];
+}
+
+/** Nullifier: stable per (permit, context), unlinkable across contexts; needs the holder secret. */
+export function permitNullifier(holderSecret: Field, context: Field): Field {
+  return Poseidon.hash([PERMIT_PROOF_TAG, holderSecret, context]);
+}
+
+// ── Holder secret ─── (holderSecret.ts; re-exported here)
+
+export {
+  HOLDER_SECRET_TAG, HOLDER_SALT_TAG, holderSecretText, holderSecretFromSignature, saltFromHolderSecret, deriveHolderSecret,
+  findHolderSecret, holderSecretMatches, MAX_HOLDER_SECRETS,
+} from './holderSecret.js';
+
+// ── Verifier-bound challenges ───────────────────────────────────────────────
+//
+// The proof's `context` is a public input the verifier chooses, and the
+// nullifier is Poseidon(tag, subject, context). If two verifiers handed out
+// the same raw context, the same holder would give both the same nullifier,
+// and comparing lists would link the two uses. So the context is derived
+// from the verifier's identity and its nonce: verifiers with different
+// identities always get different contexts, whatever nonces they pick. The
+// holder derives it from the identity it actually talks to (a site's
+// origin, a service's address), never from a context the verifier supplies.
+
+/** Tag for verifier-bound contexts (distinct from PERMIT_PROOF_TAG). */
+export const VERIFIER_CONTEXT_TAG: Field = Field([...'zkPermits/v1/verifier'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+
+/**
+ * The canonical form of a verifier identity: a URL becomes its origin
+ * (scheme, lower-case host, non-default port; path and query dropped), so
+ * `https://Shop.Example/verify?x=1` and `https://shop.example` are the same
+ * verifier. Anything else is a service name, trimmed and lower-cased with
+ * runs of whitespace collapsed.
+ */
+export function normalizeVerifier(verifier: string): string {
+  const raw = String(verifier ?? '').trim();
+  let id: string;
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+    let origin: string;
+    try { origin = new URL(raw).origin; } catch { throw new Error(`verifier is not a valid URL: ${raw}`); }
+    if (!origin || origin === 'null') throw new Error(`verifier URL has no origin: ${raw}`);
+    id = origin;
+  } else {
+    id = raw.toLowerCase().replace(/\s+/g, ' ');
+  }
+  if (!id) throw new Error('verifier identity is empty');
+  if (id.length > 256) throw new Error('verifier identity is longer than 256 characters');
+  if (/[\u0000-\u001f\u007f]/.test(id)) throw new Error('verifier identity contains control characters');
+  return id;
+}
+
+/** A fresh 128-bit nonce for a verifier to hand to a holder. */
+export function randomNonce(): bigint {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  return b.reduce((v, x) => (v << 8n) | BigInt(x), 0n);
+}
+
+function parseNonce(nonce: bigint | string): bigint {
+  const n = typeof nonce === 'bigint' ? nonce : /^\d{1,80}$/.test(String(nonce).trim()) ? BigInt(String(nonce).trim()) : -1n;
+  if (n < 0n || n >= 1n << 253n) throw new Error('nonce must be a decimal integer below 2^253');
+  return n;
+}
+
+/**
+ * The proof context for `verifier` (see normalizeVerifier) and its `nonce`:
+ * Poseidon(VERIFIER_CONTEXT_TAG, byteLength, identity in 31-byte chunks, nonce).
+ * Holder and verifier compute it the same way.
+ */
+export function verifierContext(verifier: string, nonce: bigint | string): bigint {
+  const bytes = new TextEncoder().encode(normalizeVerifier(verifier));
+  const chunks: Field[] = [];
+  for (let i = 0; i < bytes.length; i += 31) {
+    chunks.push(Field(bytes.slice(i, i + 31).reduce((v, x) => (v << 8n) | BigInt(x), 0n)));
+  }
+  return Poseidon.hash([VERIFIER_CONTEXT_TAG, Field(bytes.length), ...chunks, Field(parseNonce(nonce))]).toBigInt();
+}
+
+/** In-circuit: every bit set in `required` is set in `scope` (254-bit masks). */
+function assertScopeCovers(scope: Field, required: Field): void {
+  const s = scope.toBits(254);
+  const r = required.toBits(254);
+  for (let i = 0; i < 254; i++) r[i].not().or(s[i]).assertTrue();
+}
+
+export const PermitProof: any = ZkProgram({
+  name: 'zkPermits-holder-proof',
+  publicInput: PermitProofInput,
+  publicOutput: Field,
+  methods: {
+    prove: {
+      privateInputs: [PermitLeaf, MerkleMapWitness, Field, Signature],
+      async method(input: PermitProofInput, leaf: PermitLeaf, witness: MerkleMapWitness, holderSecret: Field, holderSig: Signature) {
+        const [root, key] = witness.computeRootAndKey(permitLeafHash(leaf));
+        root.assertEquals(input.root);
+        key.assertEquals(leaf.subject);
+        permitSubject(leaf.holderKey, saltFromHolderSecret(holderSecret)).assertEquals(leaf.subject);
+        holderSig.verify(leaf.holderKey, holderProofMessage(input.registry, input.root, input.context)).assertTrue();
+        leaf.status.assertEquals(PERMIT_STATUS_ACTIVE);
+        leaf.validFrom.assertLessThanOrEqual(input.slot);
+        input.slot.assertLessThanOrEqual(leaf.expirySlot);
+        assertScopeCovers(leaf.scope, input.requiredScope);
+        return { publicOutput: permitNullifier(holderSecret, input.context) };
+      },
+    },
+  },
+});
+
+export type HolderProofRequest = {
+  registry: string;
+  /** Root the witness is for (the keeper's GET …/permits/:subject returns both). */
+  root: string;
+  witness: { isLefts: boolean[]; siblings: string[] };
+  leaf: PermitLeaf;
+  /** The holder secret (deriveHolderSecret). Never leaves the holder's device. */
+  holderSecret: string;
+  slot: number;
+  requiredScope: bigint;
+  context: bigint;
+  /** Signature over holderProofMessage(registry, root, context) by the holder key (wallet signFields). */
+  holderSignature: string;
+};
+
+/** Holder side: compiles (once) and proves. Returns the proof as JSON. */
+export async function proveHolder(r: HolderProofRequest): Promise<{ proof: unknown; nullifier: string }> {
+  const { Bool } = await import('o1js');
+  await PermitProof.compile();
+  const input = new PermitProofInput({
+    registry: PublicKey.fromBase58(r.registry),
+    root: Field(r.root),
+    slot: UInt32.from(r.slot),
+    requiredScope: Field(r.requiredScope),
+    context: Field(r.context),
+  });
+  const witness = new MerkleMapWitness(r.witness.isLefts.map(b => Bool(b)), r.witness.siblings.map(s => Field(s)));
+  const { proof } = await PermitProof.prove(input, r.leaf, witness, Field(r.holderSecret), Signature.fromBase58(r.holderSignature));
+  return { proof: proof.toJSON(), nullifier: proof.publicOutput.toString() };
+}
+
+export type HolderProofCheck = {
+  registry: string;
+  /** Roots accepted as current (e.g. from a Mina node, or the keeper's recent /roots). */
+  acceptedRoots: string[];
+  currentSlot: number;
+  /** How far the proof's slot may be from `currentSlot`. Default 10 slots. */
+  maxSlotSkew?: number;
+  requiredScope?: bigint;
+} & (
+  /** Your identity as the holder saw it and the nonce you issued: the expected context is verifierContext(verifier, nonce). */
+  | { verifier: string; nonce: bigint | string; context?: never }
+  /** A raw expected context, for schemes that derive it otherwise. */
+  | { context: bigint; verifier?: never; nonce?: never }
+);
+
+/** Verifier side: checks the proof and its public inputs. Returns the nullifier. */
+export async function verifyHolderProof(proofJson: unknown, check: HolderProofCheck): Promise<{ valid: boolean; nullifier: string | null; reason: string | null }> {
+  const { verificationKey } = await PermitProof.compile();
+  const ProofClass = ZkProgram.Proof(PermitProof);
+  let proof: any;
+  try { proof = await ProofClass.fromJSON(proofJson as any); } catch (e: any) {
+    return { valid: false, nullifier: null, reason: `malformed proof: ${e?.message ?? e}` };
+  }
+  const pub = proof.publicInput;
+  const fail = (reason: string) => ({ valid: false, nullifier: null, reason });
+  if (pub.registry.toBase58() !== check.registry) return fail('proof is for another registry');
+  if (!check.acceptedRoots.includes(pub.root.toString())) return fail('root is not a current root of the registry');
+  if (Math.abs(Number(pub.slot.toString()) - check.currentSlot) > (check.maxSlotSkew ?? 10)) return fail('slot is too far from now');
+  if (pub.requiredScope.toBigInt() !== (check.requiredScope ?? 0n)) return fail('proof is for other scope bits');
+  let expected: bigint;
+  try { expected = check.verifier !== undefined ? verifierContext(check.verifier, check.nonce) : check.context; }
+  catch (e: any) { return fail(e?.message ?? String(e)); }
+  if (pub.context.toBigInt() !== expected) return fail('proof is for another context');
+  const { verify } = await import('o1js');
+  if (!(await verify(proof, verificationKey))) return fail('proof does not verify');
+  return { valid: true, nullifier: proof.publicOutput.toString(), reason: null };
+}

package/src/permitRegistryRebuild.ts

@@ -0,0 +1,423 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitRegistryRebuild.ts — `zklicensing/permits/rebuild`
+ *
+ * Rebuilds a PermitRegistry's permits tree from its events alone. Every
+ * event that changes a permit carries the full new leaf, so the tree is
+ * recoverable from the chain without the Keeper (PERMITS_PLAN.md §8.2).
+ * The Keeper's indexer uses this same code. Open applications (fees in
+ * escrow) are rebuilt the same way: filed minus settled.
+ */
+
+import { Field, PublicKey, UInt32, UInt64 } from 'o1js';
+import { CompactMerkleMap, encodeFields, decodeFields } from './compactMerkleMap.js';
+import { Application, PermitLeaf, applicationHash, permitLeafHash, unpackFees, unpackPolicy } from './permitMessages.js';
+import { PermitRegistryEvents } from './permitInterface.js';
+import { forkBumpedExpiry } from './contractInterface.js';
+
+/** A decoded event, as returned by `fetchEvents` (fields we use). */
+export type RegistryEvent = {
+  type: string;
+  event: { data: any };
+  blockHeight?: UInt32 | { toString(): string };
+  globalSlot?: UInt32 | { toString(): string };
+};
+
+export type PermitRecord = {
+  subject: string;
+  holderKey: string;
+  scope: string;
+  validFrom: number;
+  expirySlot: number;
+  status: number;
+  seq: number;
+  docHash: string;
+};
+
+/** An application with its fee in escrow, as JSON (amounts in nanomina, slots as numbers). */
+export type ApplicationRecord = {
+  subject: string;
+  holderKey: string;
+  payer: string;
+  baseSeq: number;
+  scope: string;
+  validFrom: number;
+  expirySlot: number;
+  docHash: string;
+  fee: string;
+  processingFee: string;
+  deadline: number;
+  /** The registry's filing number. */
+  filing: number;
+};
+
+/** How an application ended (APPLICATION_OUTCOME), amounts in nanomina. */
+export type Settlement = { subject: string; outcome: number; kept: string; refunded: string };
+
+export type RegistryView = {
+  /** The permits tree (a MerkleMap drop-in that can be saved and loaded without re-hashing). */
+  tree: CompactMerkleMap;
+  root: string;
+  permits: Map<string, PermitRecord>;
+  keysHash: string | null;
+  epoch: number;
+  feesPacked: string | null;
+  /** The escrow tree (subject → applicationHash of the open application) and its root. */
+  escrow: CompactMerkleMap;
+  escrowRoot: string;
+  /** Open applications by subject. */
+  applications: Map<string, ApplicationRecord>;
+  /** Settled applications by application hash: how each ended. */
+  settlements: Map<string, Settlement>;
+  eventsApplied: number;
+  /** Set once the registry was retired (redeployed): its frozen permits root. */
+  retiredRoot?: string;
+  /** Whether the platform key retired it (retireByPlatform) rather than the authority. */
+  retiredByPlatform?: boolean;
+  /** Whether it was retired with application fees in escrow (they stay on it). */
+  retiredForced?: boolean;
+  /**
+   * A redeployed registry starts with its predecessor's permits
+   * (seededRegistryView): the tree it started with, and each carried-over
+   * permit's seq then, so its next change is seq + 1.
+   */
+  start?: { root: string; seqs: Map<string, number> };
+};
+
+export function leafToRecord(leaf: PermitLeaf): PermitRecord {
+  return {
+    subject: leaf.subject.toString(),
+    // The never-granted leaf's key is PublicKey.empty() (not a curve point): ''.
+    holderKey: leaf.holderKey.equals(PublicKey.empty()).toBoolean() ? '' : leaf.holderKey.toBase58(),
+    scope: leaf.scope.toString(),
+    validFrom: Number(leaf.validFrom.toString()),
+    expirySlot: Number(leaf.expirySlot.toString()),
+    status: Number(leaf.status.toString()),
+    seq: Number(leaf.seq.toString()),
+    docHash: leaf.docHash.toString(),
+  };
+}
+
+export function applicationToRecord(app: Application): ApplicationRecord {
+  return {
+    subject: app.subject.toString(),
+    holderKey: app.holderKey.toBase58(),
+    payer: app.payer.toBase58(),
+    baseSeq: Number(app.baseSeq.toString()),
+    scope: app.scope.toString(),
+    validFrom: Number(app.validFrom.toString()),
+    expirySlot: Number(app.expirySlot.toString()),
+    docHash: app.docHash.toString(),
+    fee: app.fee.toString(),
+    processingFee: app.processingFee.toString(),
+    deadline: Number(app.deadline.toString()),
+    filing: Number(app.filing.toString()),
+  };
+}
+
+export function recordToApplication(r: ApplicationRecord): Application {
+  return new Application({
+    subject: Field(r.subject),
+    holderKey: PublicKey.fromBase58(r.holderKey),
+    payer: PublicKey.fromBase58(r.payer),
+    baseSeq: UInt32.from(r.baseSeq),
+    scope: Field(r.scope),
+    validFrom: UInt32.from(r.validFrom),
+    expirySlot: UInt32.from(r.expirySlot),
+    docHash: Field(r.docHash),
+    fee: UInt64.from(r.fee),
+    processingFee: UInt64.from(r.processingFee),
+    deadline: UInt32.from(r.deadline),
+    filing: UInt32.from(r.filing),
+  });
+}
+
+export function recordToLeaf(r: PermitRecord): PermitLeaf {
+  return new PermitLeaf({
+    subject: Field(r.subject),
+    holderKey: r.holderKey === '' ? PublicKey.empty() : PublicKey.fromBase58(r.holderKey),
+    scope: Field(r.scope),
+    validFrom: UInt32.from(r.validFrom),
+    expirySlot: UInt32.from(r.expirySlot),
+    status: UInt32.from(r.status),
+    seq: UInt32.from(r.seq),
+    docHash: Field(r.docHash),
+  });
+}
+
+/**
+ * The view a redeployed registry starts with: a copy of its retired
+ * predecessor's permits and tree (the initialPermitsRoot its keys signed).
+ * Its own events then apply on top; `registryCreated` checks the root.
+ */
+export function seededRegistryView(predecessor: RegistryView): RegistryView {
+  const view = registryViewFromStored({ ...registryViewToStored(predecessor), applications: [] });
+  view.start = { root: view.root, seqs: new Map([...view.permits.values()].map(p => [p.subject, p.seq] as const)) };
+  return view;
+}
+
+/**
+ * The retired registry a registry continues, from its `registryCreated`
+ * event (base58), or null for a first generation. With it a registry's
+ * lineage can be walked back on chain events alone; the successor's start
+ * was checked against the predecessor's retired root when it was deployed.
+ */
+export function registryPredecessor(events: RegistryEvent[]): string | null {
+  const created = events.find(e => e.type === 'registryCreated');
+  const p = created?.event.data.predecessor as PublicKey | undefined;
+  if (!p || p.equals(PublicKey.empty()).toBoolean()) return null;
+  return p.toBase58();
+}
+
+export function emptyRegistryView(): RegistryView {
+  const tree = new CompactMerkleMap();
+  return { tree, root: tree.getRoot().toString(), permits: new Map(), keysHash: null, epoch: 0, feesPacked: null, ...emptyEscrow(), eventsApplied: 0 };
+}
+
+function emptyEscrow() {
+  const escrow = new CompactMerkleMap();
+  return { escrow, escrowRoot: escrow.getRoot().toString(), applications: new Map<string, ApplicationRecord>(), settlements: new Map<string, Settlement>() };
+}
+
+/**
+ * Open applications from filed and settled events. A settled event names the
+ * application by hash; the same hash can be filed again after it settles, so
+ * filings and settlements are counted. Events of a transaction the chain
+ * refused can show up in some sources (the local test chain records them):
+ * a settlement with no filing is ignored, and of two open filings for one
+ * subject the later filing wins, since a subject can only be filed again
+ * once its previous application settled. The view's escrowRoot against the
+ * contract's is the check that the result is right.
+ */
+function openApplications(filed: Application[], settled: string[]): Map<string, ApplicationRecord> {
+  const closed = new Map<string, number>();
+  for (const h of settled) closed.set(h, (closed.get(h) ?? 0) + 1);
+  const open = new Map<string, ApplicationRecord>();
+  for (const app of filed) {
+    const h = applicationHash(app).toString();
+    const n = closed.get(h) ?? 0;
+    if (n > 0) { closed.set(h, n - 1); continue; }
+    const rec = applicationToRecord(app);
+    const other = open.get(rec.subject);
+    if (!other || rec.filing > other.filing) open.set(rec.subject, rec);
+  }
+  return open;
+}
+
+/** Replaces the view's open applications and rebuilds the (small) escrow tree. */
+function setApplications(view: RegistryView, open: Map<string, ApplicationRecord>) {
+  const escrow = new CompactMerkleMap();
+  escrow.setMany([...open.values()].map(r => [Field(r.subject), applicationHash(recordToApplication(r))] as [Field, Field]));
+  view.escrow = escrow;
+  view.escrowRoot = escrow.getRoot().toString();
+  view.applications = open;
+}
+
+/**
+ * Applies events in any order. Archive nodes, local chains and paginated
+ * fetches don't agree on ordering, so none is assumed: each subject's leaves
+ * are ordered by `seq` (the contract advances it by exactly one per change),
+ * key rotations by `epoch` and fee changes by `actionNonce`. A gap in a
+ * subject's sequence means events are missing, and throws rather than build
+ * a wrong tree. Applying to a non-empty view continues from its state.
+ */
+export function applyRegistryEvents(view: RegistryView, events: RegistryEvent[]): RegistryView {
+  const updates: Array<[Field, Field]> = [];
+  const esc = { filed: [...view.applications.values()].map(recordToApplication), settled: [] as string[] };
+  for (const [subject, last] of collectRegistryEvents(view, events, esc)) {
+    updates.push([last.leaf.subject, permitLeafHash(last.leaf)]);
+    view.permits.set(subject, last.rec);
+  }
+  view.tree.setMany(updates);
+  view.root = view.tree.getRoot().toString();
+  setApplications(view, openApplications(esc.filed, esc.settled));
+  return view;
+}
+
+/**
+ * Brings `view` up to date with a registry's full event list, re-hashing only
+ * the permits whose latest leaf changed: a full rebuild costs a 256-level tree
+ * path per permit, a refresh one per changed permit. Returns the subjects
+ * that changed (added or updated).
+ */
+export function refreshRegistryView(view: RegistryView, events: RegistryEvent[]): string[] {
+  const fresh: RegistryView = { tree: view.tree, root: view.root, permits: new Map(), keysHash: null, epoch: 0, feesPacked: null, ...emptyEscrow(), eventsApplied: 0, ...(view.start ? { start: view.start } : {}) };
+  const esc = { filed: [] as Application[], settled: [] as string[] };
+  const latest = collectRegistryEvents(fresh, events, esc);
+  const changed: string[] = [];
+  const updates: Array<[Field, Field]> = [];
+  for (const [subject, last] of latest) {
+    const cur = view.permits.get(subject);
+    if (cur && sameRecord(cur, last.rec)) continue;
+    updates.push([last.leaf.subject, permitLeafHash(last.leaf)]);
+    view.permits.set(subject, last.rec);
+    changed.push(subject);
+  }
+  view.tree.setMany(updates);
+  view.keysHash = fresh.keysHash; view.epoch = fresh.epoch; view.feesPacked = fresh.feesPacked; view.eventsApplied = fresh.eventsApplied;
+  view.settlements = fresh.settlements;
+  view.root = view.tree.getRoot().toString();
+  setApplications(view, openApplications(esc.filed, esc.settled));
+  return changed;
+}
+
+/** Same permit leaf (field by field: cheaper than hashing both). */
+function sameRecord(a: PermitRecord, b: PermitRecord): boolean {
+  return a.seq === b.seq && a.status === b.status && a.scope === b.scope && a.validFrom === b.validFrom
+    && a.expirySlot === b.expirySlot && a.holderKey === b.holderKey && a.docHash === b.docHash && a.subject === b.subject;
+}
+
+/**
+ * Validates the events and returns each subject's latest leaf; updates the
+ * view's keys, epoch and fees, and collects escrow events into `esc`.
+ */
+function collectRegistryEvents(view: RegistryView, events: RegistryEvent[], esc: { filed: Application[]; settled: string[] }): Map<string, { type: string; leaf: PermitLeaf; rec: PermitRecord }> {
+  const bySubject = new Map<string, Array<{ type: string; leaf: PermitLeaf; rec: PermitRecord }>>();
+  let lastEpoch = view.epoch;
+  let lastFeeNonce = -1;
+  for (const e of events) {
+    const d = e.event.data;
+    switch (e.type) {
+      case 'registryCreated': {
+        if (view.keysHash === null) view.keysHash = d.keysHash.toString();
+        const startRoot = view.start?.root ?? emptyRegistryView().root;
+        if (d.permitsRoot !== undefined && d.permitsRoot.toString() !== startRoot) {
+          throw new Error('the registry started from another permits tree: seed the view with its predecessor (seededRegistryView)');
+        }
+        break;
+      }
+      case 'authorityRotated': {
+        const epoch = Number(d.epoch.toString());
+        if (epoch > lastEpoch || view.keysHash === null) { lastEpoch = epoch; view.keysHash = d.keysHash.toString(); view.epoch = epoch; }
+        break;
+      }
+      case 'feesUpdated': {
+        const nonce = Number(d.actionNonce.toString());
+        if (nonce > lastFeeNonce) { lastFeeNonce = nonce; view.feesPacked = d.feesPacked.toString(); }
+        break;
+      }
+      // A permit moved to a new holder key: its new leaf (seq 1, a new subject);
+      // the old one closes as MOVED in a permitStatusChanged event.
+      case 'permitMoved':
+      case 'permitGranted':
+      case 'permitStatusChanged': {
+        const leaf = d.leaf as PermitLeaf;
+        const rec = leafToRecord(leaf);
+        const list = bySubject.get(rec.subject) ?? [];
+        list.push({ type: e.type, leaf, rec });
+        bySubject.set(rec.subject, list);
+        break;
+      }
+      case 'applicationFiled':
+        esc.filed.push(d.application as Application);
+        break;
+      case 'applicationSettled': {
+        const hash = d.applicationHash.toString();
+        esc.settled.push(hash);
+        view.settlements.set(hash, { subject: d.subject.toString(), outcome: Number(d.outcome.toString()), kept: d.kept.toString(), refunded: d.refunded.toString() });
+        break;
+      }
+      // Payout and platform-key changes touch no permit (the account state has them).
+      case 'payoutProposed':
+      case 'payoutChanged':
+      case 'platformChanged':
+        break;
+      case 'registryRetired':
+        view.retiredRoot = d.permitsRoot.toString();
+        view.retiredByPlatform = d.byPlatform.toBoolean();
+        view.retiredForced = d.forced.toBoolean();
+        break;
+      default:
+        throw new Error(`unknown registry event type: ${e.type}`);
+    }
+    view.eventsApplied++;
+  }
+  // A rotation to epoch N implies the registryCreated keys were replaced.
+  const out = new Map<string, { type: string; leaf: PermitLeaf; rec: PermitRecord }>();
+  for (const [subject, list] of bySubject) {
+    list.sort((a, b) => a.rec.seq - b.rec.seq);
+    // Each change is the previous seq + 1, from the start: 0, or the seq a
+    // carried-over permit had when the registry started.
+    let prevSeq = view.permits.get(subject)?.seq ?? view.start?.seqs.get(subject) ?? 0;
+    for (const item of list) {
+      if (item.rec.seq !== prevSeq + 1) {
+        throw new Error(`event out of order for ${subject}: seq ${item.rec.seq} after ${prevSeq || 'none'}`);
+      }
+      prevSeq = item.rec.seq;
+    }
+    out.set(subject, list[list.length - 1]);
+  }
+  return out;
+}
+
+/** Fetches a registry's events (active Mina instance) and rebuilds its tree. */
+export async function rebuildRegistry(address: PublicKey | string): Promise<RegistryView> {
+  const pk = typeof address === 'string' ? PublicKey.fromBase58(address) : address;
+  const events = await new PermitRegistryEvents(pk).fetchEvents();
+  return applyRegistryEvents(emptyRegistryView(), events as RegistryEvent[]);
+}
+
+/** 'moved': the holder moved it to a new key (a new permit, under a new subject); this one is closed. */
+export type PermitStatusName = 'active' | 'suspended' | 'revoked' | 'moved' | 'expired' | 'not-yet-valid' | 'in-grace' | 'unknown';
+
+/**
+ * Effective status of a permit at `slot`: revoked and suspended win, then the
+ * dates. `gracePeriod` comes from the registry policy.
+ */
+/**
+ * A permit's status at `slot`. With the registry's `forkActivationSlot`
+ * (a successor deployed after a Mina hard fork): a permit that lapsed
+ * shortly before the fork, while its registry was retired and couldn't
+ * renew it, counts as expiring at the fork slot, so its grace runs from the
+ * fork (as licensing's effectiveExpirySlot). Anonymous holder proofs check
+ * the expiry as granted.
+ */
+export function permitStatusAt(rec: PermitRecord | undefined, slot: number, gracePeriod = 0, forkActivationSlot = 0): PermitStatusName {
+  if (!rec) return 'unknown';
+  if (rec.status === 2) return 'revoked';
+  if (rec.status === 3) return 'moved';
+  if (rec.status === 1) return 'suspended';
+  if (slot < rec.validFrom) return 'not-yet-valid';
+  const expiry = forkBumpedExpiry(rec.expirySlot, forkActivationSlot, gracePeriod);
+  if (slot <= expiry) return 'active';
+  if (slot <= expiry + gracePeriod) return 'in-grace';
+  return 'expired';
+}
+
+export { unpackFees, unpackPolicy };
+
+/** A registry view saved without its tree's hashes recomputed (see CompactMerkleMap). */
+export type StoredRegistryView = {
+  root: string;
+  permits: PermitRecord[];
+  tree: { indices: string; leaves: string; splits: string };
+  /** Open applications (absent in views saved before escrow). */
+  applications?: ApplicationRecord[];
+  /** A redeployed registry's start (RegistryView.start): its root and the carried-over seqs. */
+  start?: { root: string; seqs: Array<[string, number]> };
+};
+
+export function registryViewToStored(view: RegistryView): StoredRegistryView {
+  const d = view.tree.toCompact();
+  return {
+    root: view.root, permits: [...view.permits.values()], applications: [...view.applications.values()],
+    tree: { indices: encodeFields(d.indices), leaves: encodeFields(d.leaves), splits: encodeFields(d.splits) },
+    ...(view.start ? { start: { root: view.start.root, seqs: [...view.start.seqs] } } : {}),
+  };
+}
+
+/**
+ * Loads a saved view without re-hashing; its keys, epoch and fees come back
+ * with the next refreshRegistryView. Throws if the copy is inconsistent.
+ */
+export function registryViewFromStored(s: StoredRegistryView): RegistryView {
+  const tree = CompactMerkleMap.fromCompact({ indices: decodeFields(s.tree.indices), leaves: decodeFields(s.tree.leaves), splits: decodeFields(s.tree.splits) }, s.root);
+  if (tree.size !== s.permits.length) throw new Error('saved registry view: the permits and the tree disagree');
+  const permits = new Map(s.permits.map(p => [p.subject, p] as const));
+  const view: RegistryView = { tree, root: s.root, permits, keysHash: null, epoch: 0, feesPacked: null, ...emptyEscrow(), eventsApplied: 0 };
+  setApplications(view, new Map((s.applications ?? []).map(a => [a.subject, a] as const)));
+  if (s.start) view.start = { root: s.start.root, seqs: new Map(s.start.seqs) };
+  return view;
+}