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

package/src/permitDescribe.ts

@@ -0,0 +1,362 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitDescribe.ts — `zklicensing/permits/describe`
+ *
+ * What a zkPermits field signature means, in words. Wallets show these
+ * messages as a list of numbers, and most carry only a hash of the details
+ * (the permit, the fees, the keys). So the description is built the other
+ * way round: from the request's details, the message is rebuilt and must
+ * equal the numbers about to be signed — only then is the summary
+ * `verified`. Show it before asking the wallet, with the fingerprint (how
+ * many numbers, and how the last one ends) for comparing with the wallet's
+ * screen.
+ */
+
+import { Bool, Field, PublicKey, UInt32, UInt64 } from 'o1js';
+import {
+  PERMIT_TAGS, PERMIT_NETWORK, acceptMessage, applyMessage, approveMessage, authorityKeys, authorityKeysHash, grantMessage,
+  DEFAULT_DECISION_WINDOW, DEFAULT_MIN_PROCESSING_FEE, initMessage, networkField, packApplicationTerms, packFees, packPolicy, rejectMessage, retireMessage, rotateMessage, setFeesMessage,
+  statusMessage, surrenderMessage, payoutMessage, payoutCancelMessage, rekeyMessage, unpackApplicationTerms, unpackFees, withdrawMessage, type PermitNetwork,
+} from './permitMessages.js';
+import { recordToApplication, recordToLeaf, type ApplicationRecord, type PermitRecord } from './permitRegistryRebuild.js';
+import { minaUnit } from './units.js';
+import { EMPTY_ROOT } from './contractInterface.js';
+
+export type PermitMessageDescription = {
+  kind: string;
+  /** One line: what signing does. */
+  title: string;
+  /** The details, as label/value pairs. */
+  facts: Array<[string, string]>;
+  network: PermitNetwork | null;
+  registry: string | null;
+  /** The details were checked to give exactly these numbers. */
+  verified: boolean;
+  /** Why not, when not verified. */
+  problem?: string;
+  /** For comparing with the wallet: "7 numbers, the last ending …123456". */
+  fingerprint: string;
+};
+
+export type DescribeContext = {
+  /** Activity names by bit (the registry's scopes). */
+  scopeLabel?: (bit: number) => string;
+  /** A date for a slot. */
+  slotLabel?: (slot: number) => string;
+  /** The registry's configuration, for a deployment request. */
+  registry?: {
+    keys: string[]; threshold: number; payout: string; metadataHash: string;
+    policy: { gracePeriod: number; maxTerm: number; singleKeySuspend: boolean; holderSigRequired: boolean };
+    /** processingFee and minProcessingFee default to DEFAULT_MIN_PROCESSING_FEE, as the keeper does for older drafts. */
+    fees: { grantFee: string; renewalFee: string; minFee: string; processingFee?: string; minProcessingFee?: string };
+    /** Slots from filing an application to its decision deadline (default DEFAULT_DECISION_WINDOW). */
+    decisionWindow?: number;
+    /** A redeploy: the frozen tree this one starts with and the registry it replaces (the chain checks both). */
+    initialPermitsRoot?: string;
+    forkActivationSlot?: number;
+    predecessor?: string;
+    generation?: number;
+  };
+};
+
+const TAG_KIND = new Map<string, string>(Object.entries(PERMIT_TAGS).map(([k, v]) => [v.toString(), k]));
+const NET_NAME = new Map<string, PermitNetwork>(Object.entries(PERMIT_NETWORK).map(([k, v]) => [v.toString(), k as PermitNetwork]));
+const NO_EXPIRY = 4294967295;
+
+export function fingerprint(fields: string[]): string {
+  const last = fields[fields.length - 1] ?? '';
+  return `${fields.length} numbers, the last ending …${last.slice(-6)}`;
+}
+
+// Devnet fees are tMINA (test MINA, no value).
+const mina = (nano: string | bigint, network?: string | null) => {
+  const s = BigInt(nano).toString().padStart(10, '0');
+  return `${s.slice(0, -9)}.${s.slice(-9)}`.replace(/\.?0+$/, '') + ' ' + minaUnit(network ?? 'mainnet');
+};
+const short = (s: string) => (s.length > 14 ? `${s.slice(0, 6)}…${s.slice(-6)}` : s);
+
+function scopeText(scope: string, ctx: DescribeContext): string {
+  const v = BigInt(scope);
+  const bits: number[] = [];
+  for (let i = 0; i < 254; i++) if ((v >> BigInt(i)) & 1n) bits.push(i);
+  return bits.length ? bits.map(b => ctx.scopeLabel?.(b) ?? `activity ${b}`).join(', ') : 'none';
+}
+const slotText = (slot: number, ctx: DescribeContext) => (slot >= NO_EXPIRY ? 'no expiry' : ctx.slotLabel?.(slot) ?? `slot ${slot}`);
+
+const windowText = (slots: number) => `${Math.round(slots / 960)} days after the application`;
+
+function applicationFacts(a: ApplicationRecord, ctx: DescribeContext, network: string | null): Array<[string, string]> {
+  return [
+    ['Activities', scopeText(a.scope, ctx)],
+    ['Valid', `${slotText(a.validFrom, ctx)} – ${slotText(a.expirySlot, ctx)}`],
+    ['Document hash', short(a.docHash)],
+    ['Kind', a.baseSeq === 0 ? 'new permit' : 'renewal or change'],
+    ['Fee in escrow', mina(a.fee, network)],
+    ['Decision deadline', slotText(a.deadline, ctx)],
+  ];
+}
+
+function leafFacts(prefix: string, r: PermitRecord, ctx: DescribeContext): Array<[string, string]> {
+  return [
+    [`${prefix}activities`, scopeText(r.scope, ctx)],
+    [`${prefix}valid`, `${slotText(r.validFrom, ctx)} – ${slotText(r.expirySlot, ctx)}`],
+    [`${prefix}document hash`, short(r.docHash)],
+  ];
+}
+
+/** The message's tag, network and registry (readable from the numbers themselves). */
+function header(fields: string[]): { kind: string | null; network: PermitNetwork | null; registry: string | null } {
+  const kind = TAG_KIND.get(fields[0] ?? '') ?? null;
+  const network = NET_NAME.get(fields[1] ?? '') ?? null;
+  let registry: string | null = null;
+  try { registry = PublicKey.fromFields([Field(fields[2]), Field(fields[3])]).toBase58(); } catch { /* not a key */ }
+  return { kind, network, registry };
+}
+
+const same = (a: Field[], b: string[]) => a.length === b.length && a.every((f, i) => f.toString() === b[i]);
+
+/**
+ * Describes an authority request (the keeper's RequestView: kind, message
+ * and its details) and checks that the details give exactly `message`.
+ */
+export function describeRequest(q: {
+  kind: string; registry: string; message: string[];
+  oldLeaf?: PermitRecord; newLeaf?: PermitRecord; fee?: string; reasonCode?: string;
+  newFeesPacked?: string; newAppTermsPacked?: string; newKeys?: string[]; newThreshold?: number;
+  application?: ApplicationRecord; newPayout?: string;
+}, ctx: DescribeContext = {}): PermitMessageDescription {
+  const fields = q.message;
+  const h = header(fields);
+  const base = { kind: q.kind, network: h.network, registry: h.registry, fingerprint: fingerprint(fields) };
+  const fail = (title: string, problem: string, facts: Array<[string, string]> = []): PermitMessageDescription => ({ ...base, title, facts, verified: false, problem });
+  if (!h.network) return fail('Unknown message', 'The message names no zkPermits network.');
+  if (h.registry !== q.registry) return fail('Unknown message', 'The message is for another registry than the request says.');
+  const net = networkField(h.network);
+  const reg = PublicKey.fromBase58(q.registry);
+  const epoch = UInt32.from(fields[4] ?? 0);
+  const nonce = UInt32.from(fields[5] ?? 0);
+  let expected: Field[];
+  let title: string;
+  let facts: Array<[string, string]> = [];
+  try {
+    switch (q.kind) {
+      case 'grant': {
+        if (!q.oldLeaf || !q.newLeaf) return fail('Grant', 'The request has no permit details.');
+        expected = grantMessage({ network: net, registry: reg, epoch, oldLeaf: recordToLeaf(q.oldLeaf), newLeaf: recordToLeaf(q.newLeaf) });
+        const isNew = q.oldLeaf.seq === 0 && !q.oldLeaf.holderKey;
+        title = isNew ? `Approve a new permit for ${short(q.newLeaf.holderKey)}` : `Approve a change to permit ${short(q.newLeaf.subject)}`;
+        facts = [
+          ['Permit', short(q.newLeaf.subject)],
+          ['Holder key', q.newLeaf.holderKey],
+          ...leafFacts('', q.newLeaf, ctx),
+          ...(isNew ? [] : leafFacts('Before: ', q.oldLeaf, ctx)),
+          ...(q.fee ? [['Fee the holder pays', mina(q.fee, h.network)] as [string, string]] : []),
+        ];
+        break;
+      }
+      case 'suspend': case 'reinstate': case 'revoke': {
+        if (!q.oldLeaf) return fail(q.kind, 'The request has no permit details.');
+        expected = statusMessage(q.kind, { network: net, registry: reg, epoch, leaf: recordToLeaf(q.oldLeaf), reasonCode: Field(q.reasonCode ?? 0) });
+        title = `${q.kind === 'suspend' ? 'Suspend' : q.kind === 'reinstate' ? 'Reinstate' : 'Revoke (final)'} permit ${short(q.oldLeaf.subject)}`;
+        facts = [['Permit', short(q.oldLeaf.subject)], ['Holder key', q.oldLeaf.holderKey], ['Activities', scopeText(q.oldLeaf.scope, ctx)], ['Reason code', String(q.reasonCode ?? 0)]];
+        break;
+      }
+      case 'setFees': {
+        if (!q.newFeesPacked || !q.newAppTermsPacked) return fail('Change fees', 'The request has no fees.');
+        expected = setFeesMessage({ network: net, registry: reg, epoch, actionNonce: nonce, newFeesPacked: Field(q.newFeesPacked), newAppTermsPacked: Field(q.newAppTermsPacked) });
+        const f = unpackFees(Field(q.newFeesPacked));
+        const t = unpackApplicationTerms(Field(q.newAppTermsPacked));
+        title = 'Change the registry\'s fees';
+        facts = [
+          ['Permit fee', mina(f.grantFee.toBigInt(), h.network)], ['Renewal fee', mina(f.renewalFee.toBigInt(), h.network)], ['Minimum', mina(f.minFee.toBigInt(), h.network)],
+          ['Processing fee (kept on rejection or withdrawal)', mina(t.processingFee.toBigInt(), h.network)],
+          ['Decision deadline', windowText(Number(t.decisionWindow.toString()))],
+        ];
+        break;
+      }
+      case 'approveApplication': case 'rejectApplication': {
+        if (!q.application) return fail('Application', 'The request has no application.');
+        const app = recordToApplication(q.application);
+        const reject = q.kind === 'rejectApplication';
+        expected = reject
+          ? rejectMessage({ network: net, registry: reg, epoch, application: app, reasonCode: Field(q.reasonCode ?? 0) })
+          : approveMessage({ network: net, registry: reg, epoch, application: app });
+        const kept = BigInt(q.application.processingFee);
+        title = reject
+          ? `Reject the application of ${short(q.application.holderKey)}`
+          : `Approve the application of ${short(q.application.holderKey)} (permit active at once)`;
+        facts = [
+          ['Applicant key', q.application.holderKey],
+          ...applicationFacts(q.application, ctx, h.network),
+          ...(reject
+            ? [['Kept (processing fee)', mina(kept, h.network)], ['Refunded to the payer', mina(BigInt(q.application.fee) - kept, h.network)], ['Reason code', String(q.reasonCode ?? 0)]] as Array<[string, string]>
+            : [['Paid out from escrow', mina(q.application.fee, h.network)]] as Array<[string, string]>),
+        ];
+        break;
+      }
+      case 'rotate': {
+        if (!q.newKeys || !q.newThreshold) return fail('Rotate keys', 'The request has no new keys.');
+        const newKeysHash = authorityKeysHash(authorityKeys(q.newKeys.map(k => PublicKey.fromBase58(k)), q.newThreshold));
+        expected = rotateMessage({ network: net, registry: reg, epoch, actionNonce: nonce, newKeysHash });
+        title = 'Replace the authority keys';
+        facts = [...q.newKeys.map((k, i) => [`New key ${i + 1}`, k] as [string, string]), ['Signatures needed', `${q.newThreshold} of ${q.newKeys.length}`]];
+        break;
+      }
+      case 'payout': {
+        if (!q.newPayout) return fail('Change the payout address', 'The request has no address.');
+        expected = payoutMessage({ network: net, registry: reg, epoch, actionNonce: nonce, payout: PublicKey.fromBase58(q.newPayout) });
+        title = 'Change the payout address (after 48 hours)';
+        facts = [['New payout address', q.newPayout], ['Takes effect', '48 hours after it lands; until then fees go to the current address, and the keys can cancel it']];
+        break;
+      }
+      case 'payoutCancel': {
+        expected = payoutCancelMessage({ network: net, registry: reg, epoch, actionNonce: nonce });
+        title = 'Cancel the pending payout address change';
+        facts = q.newPayout ? [['Cancelled address', q.newPayout]] : [];
+        break;
+      }
+      case 'retire': {
+        const root = fields[6];
+        if (root === undefined || fields[7] === undefined || fields[8] === undefined) return fail('Retire the registry', 'The message names no permits root or successor.');
+        let successor: PublicKey;
+        try { successor = PublicKey.fromFields([Field(fields[7]), Field(fields[8])]); } catch { return fail('Retire the registry', 'The successor in the message is not a valid address.'); }
+        expected = retireMessage({ network: net, registry: reg, epoch, actionNonce: nonce, permitsRoot: Field(root), successor });
+        title = 'Retire the registry for a redeploy (final)';
+        facts = [
+          ['Effect', 'no more changes here: no grants, renewals, status changes, applications or surrenders'],
+          ['Permits', 'carry over, all at once and unchanged, to the new registry below: only it can start from them'],
+          ['New registry', successor.toBase58()],
+          ['Frozen permits root', root],
+        ];
+        break;
+      }
+      case 'init': {
+        const r = ctx.registry;
+        if (!r) return fail('Deploy registry', 'The registry\'s configuration is needed to check this message.');
+        const keysHash = authorityKeysHash(authorityKeys(r.keys.map(k => PublicKey.fromBase58(k)), r.threshold));
+        const policyPacked = packPolicy({ gracePeriod: UInt32.from(r.policy.gracePeriod), maxTerm: UInt32.from(r.policy.maxTerm), singleKeySuspend: Bool(r.policy.singleKeySuspend), holderSigRequired: Bool(r.policy.holderSigRequired) });
+        const feesPacked = packFees({ grantFee: UInt64.from(r.fees.grantFee), renewalFee: UInt64.from(r.fees.renewalFee), minFee: UInt64.from(r.fees.minFee) });
+        const processingFee = r.fees.processingFee ?? DEFAULT_MIN_PROCESSING_FEE.toString();
+        const decisionWindow = r.decisionWindow ?? Number(DEFAULT_DECISION_WINDOW.toBigint());
+        const appTermsPacked = packApplicationTerms({
+          processingFee: UInt64.from(processingFee), minProcessingFee: UInt64.from(r.fees.minProcessingFee ?? DEFAULT_MIN_PROCESSING_FEE.toString()), decisionWindow: UInt32.from(decisionWindow),
+        });
+        expected = initMessage({
+          network: net, registry: reg, keysHash, policyPacked, feesPacked, appTermsPacked, metadataHash: Field(r.metadataHash), payout: PublicKey.fromBase58(r.payout),
+          forkActivationSlot: UInt32.from(r.forkActivationSlot ?? 0),
+          predecessor: r.predecessor ? PublicKey.fromBase58(r.predecessor) : PublicKey.empty(),
+          initialPermitsRoot: Field(r.initialPermitsRoot ?? EMPTY_ROOT.toString()),
+        });
+        title = r.predecessor
+          ? `Redeploy the registry (generation ${r.generation ?? 2}, replacing ${short(r.predecessor)})`
+          : 'Set up the registry (keys, rules and fees)';
+        facts = [
+          ...(r.predecessor ? [['Replaces', r.predecessor], ['Permits', `starts with all permits of the replaced registry, as they are when it retires (permits root ${short(r.initialPermitsRoot ?? '')})`]] as Array<[string, string]> : []),
+          ...r.keys.map((k, i) => [`Key ${i + 1}`, k] as [string, string]),
+          ['Signatures needed', `${r.threshold} of ${r.keys.length}`],
+          ['Permit fee', mina(r.fees.grantFee, h.network)], ['Renewal fee', mina(r.fees.renewalFee, h.network)],
+          ['Processing fee (kept on rejection or withdrawal)', mina(processingFee, h.network)],
+          ['Decision deadline', windowText(decisionWindow)],
+          ['Fees paid to', r.payout],
+          ['Suspension', r.policy.singleKeySuspend ? 'any one key' : 'same as other actions'],
+        ];
+        break;
+      }
+      default:
+        return fail('Unknown request', `Unknown request kind ${q.kind}.`);
+    }
+  } catch (e: any) {
+    return fail('Unreadable request', e?.message ?? String(e));
+  }
+  facts.unshift(['Registry', q.registry], ['Network', h.network]);
+  if (!same(expected, fields)) return { ...base, title, facts, verified: false, problem: 'The numbers to sign do not match these details. Do not sign.' };
+  return { ...base, title, facts, verified: true };
+}
+
+/** The holder accepting a permit and its fee (acceptMessage). */
+export function describeAccept(a: { network: PermitNetwork; registry: string; newLeaf: PermitRecord; fee: string; fields: string[] }, ctx: DescribeContext = {}): PermitMessageDescription {
+  const expected = acceptMessage({ network: networkField(a.network), registry: PublicKey.fromBase58(a.registry), newLeaf: recordToLeaf(a.newLeaf), fee: UInt64.from(a.fee) });
+  const ok = same(expected, a.fields);
+  return {
+    kind: 'accept', title: `Accept permit ${short(a.newLeaf.subject)} and pay ${mina(a.fee, a.network)}`,
+    facts: [['Registry', a.registry], ['Network', a.network], ...leafFacts('', a.newLeaf, ctx), ['Fee', mina(a.fee, a.network)]],
+    network: a.network, registry: a.registry, verified: ok, ...(ok ? {} : { problem: 'The numbers to sign do not match these details. Do not sign.' }),
+    fingerprint: fingerprint(a.fields),
+  };
+}
+
+/**
+ * The holder moving a permit to a new key (rekeyMessage): signed by the
+ * current key and the new one. Same terms, a new subject; the old one closes.
+ */
+export function describeRekey(a: { network: PermitNetwork; registry: string; leaf: PermitRecord; newSubject: string; newHolderKey: string; fields: string[] }, ctx: DescribeContext = {}): PermitMessageDescription {
+  const expected = rekeyMessage({ network: networkField(a.network), registry: PublicKey.fromBase58(a.registry), leaf: recordToLeaf(a.leaf), newSubject: Field(a.newSubject), newHolderKey: PublicKey.fromBase58(a.newHolderKey) });
+  const ok = same(expected, a.fields);
+  return {
+    kind: 'rekey', title: `Move permit ${short(a.leaf.subject)} to the key ${short(a.newHolderKey)}`,
+    facts: [['Registry', a.registry], ['Network', a.network], ['New holder key', a.newHolderKey], ['Activities', scopeText(a.leaf.scope, ctx)], ['Effect', 'the same permit under the new key; this one closes (moved)']],
+    network: a.network, registry: a.registry, verified: ok, ...(ok ? {} : { problem: 'The numbers to sign do not match these details. Do not sign.' }),
+    fingerprint: fingerprint(a.fields),
+  };
+}
+
+/** The holder giving up a permit (surrenderMessage). */
+export function describeSurrender(a: { network: PermitNetwork; registry: string; leaf: PermitRecord; fields: string[] }, ctx: DescribeContext = {}): PermitMessageDescription {
+  const expected = surrenderMessage({ network: networkField(a.network), registry: PublicKey.fromBase58(a.registry), leaf: recordToLeaf(a.leaf) });
+  const ok = same(expected, a.fields);
+  return {
+    kind: 'surrender', title: `Give up permit ${short(a.leaf.subject)} (final)`,
+    facts: [['Registry', a.registry], ['Network', a.network], ['Activities', scopeText(a.leaf.scope, ctx)]],
+    network: a.network, registry: a.registry, verified: ok, ...(ok ? {} : { problem: 'The numbers to sign do not match these details. Do not sign.' }),
+    fingerprint: fingerprint(a.fields),
+  };
+}
+
+/**
+ * The holder's application (applyMessage): the terms and the fee put in
+ * escrow. `application.payer` and `deadline` aren't part of what the holder
+ * signs (the sender pays; the contract sets the deadline).
+ */
+export function describeApply(a: { network: PermitNetwork; registry: string; application: ApplicationRecord; fields: string[] }, ctx: DescribeContext = {}): PermitMessageDescription {
+  const expected = applyMessage({ network: networkField(a.network), registry: PublicKey.fromBase58(a.registry), application: recordToApplication(a.application) });
+  const ok = same(expected, a.fields);
+  const kept = BigInt(a.application.processingFee);
+  return {
+    kind: 'apply', title: `Apply for a permit and put ${mina(a.application.fee, a.network)} in escrow`,
+    facts: [
+      ['Registry', a.registry], ['Network', a.network],
+      ['Activities', scopeText(a.application.scope, ctx)],
+      ['Valid', `${slotText(a.application.validFrom, ctx)} – ${slotText(a.application.expirySlot, ctx)}`],
+      ['Document hash', short(a.application.docHash)],
+      ['Fee in escrow', mina(a.application.fee, a.network)],
+      ['If approved', 'the permit is active at once and the fee is paid'],
+      ['If rejected or withdrawn', `${mina(kept, a.network)} processing fee kept, ${mina(BigInt(a.application.fee) - kept, a.network)} refunded`],
+      ['If no decision by the deadline', 'full refund'],
+    ],
+    network: a.network, registry: a.registry, verified: ok, ...(ok ? {} : { problem: 'The numbers to sign do not match these details. Do not sign.' }),
+    fingerprint: fingerprint(a.fields),
+  };
+}
+
+/** The holder withdrawing an application (withdrawMessage). */
+export function describeWithdraw(a: { network: PermitNetwork; registry: string; application: ApplicationRecord; fields: string[] }, ctx: DescribeContext = {}): PermitMessageDescription {
+  const expected = withdrawMessage({ network: networkField(a.network), registry: PublicKey.fromBase58(a.registry), application: recordToApplication(a.application) });
+  const ok = same(expected, a.fields);
+  const kept = BigInt(a.application.processingFee);
+  return {
+    kind: 'withdraw', title: 'Withdraw the application',
+    facts: [
+      ['Registry', a.registry], ['Network', a.network], ['Activities', scopeText(a.application.scope, ctx)],
+      ['Kept (processing fee)', mina(kept, a.network)], ['Refunded to the payer', mina(BigInt(a.application.fee) - kept, a.network)],
+    ],
+    network: a.network, registry: a.registry, verified: ok, ...(ok ? {} : { problem: 'The numbers to sign do not match these details. Do not sign.' }),
+    fingerprint: fingerprint(a.fields),
+  };
+}
+
+/** What any zkPermits field message is, from the numbers alone (kind, network, registry); details need describeRequest. */
+export function identifyPermitMessage(fields: string[]): { kind: string | null; network: PermitNetwork | null; registry: string | null; fingerprint: string } {
+  return { ...header(fields), fingerprint: fingerprint(fields) };
+}

package/src/permitInterface.ts

@@ -0,0 +1,146 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitInterface.ts — `zklicensing/permits/interface`
+ *
+ * Public interface of the PermitRegistry contract: event shapes, state
+ * layout indices and the canonical verification-key hashes. Enough to
+ * decode events and rebuild a registry's tree without the private circuit
+ * source (same split as contractInterface.ts for licensing).
+ */
+
+import { Bool, Field, PublicKey, SmartContract, Struct, UInt32, UInt64 } from 'o1js';
+import { Application, PermitLeaf } from './permitMessages.js';
+import { PayoutChangedEvent, PayoutProposedEvent, PlatformChangedEvent } from './contractInterface.js';
+export { PayoutChangedEvent, PayoutProposedEvent, PlatformChangedEvent };
+
+export const PermitGrantedEvent: any = Struct({
+  leaf: PermitLeaf,
+  fee: UInt64,
+  payer: PublicKey,
+  isNew: Field,       // 1 = first grant for this subject, 0 = renewal / change
+});
+export type PermitGrantedEvent = any;
+
+export const PermitStatusEvent: any = Struct({
+  leaf: PermitLeaf,   // the leaf after the change
+  reasonCode: Field,  // authority's reason code; 0 for surrender
+});
+export type PermitStatusEvent = any;
+
+export const FeesUpdatedEvent: any = Struct({ feesPacked: Field, appTermsPacked: Field, actionNonce: UInt32 });
+export type FeesUpdatedEvent = any;
+
+export const AuthorityRotatedEvent: any = Struct({ keysHash: Field, epoch: UInt32 });
+export type AuthorityRotatedEvent = any;
+
+/**
+ * The registry was initialized; `permitsRoot` is the tree it starts with (its
+ * predecessor's frozen permits on a redeploy) and `predecessor` the retired
+ * registry it continues (PublicKey.empty() for a first generation), so a
+ * registry's lineage can be rebuilt from chain events alone.
+ */
+export const RegistryCreatedEvent: any = Struct({ keysHash: Field, network: Field, payout: PublicKey, permitsRoot: Field, predecessor: PublicKey });
+/** The registry was retired for a redeploy: its permits are frozen at `permitsRoot`, and only `successor` can start from them. */
+/**
+ * `byPlatform`: retired by the platform key (retireByPlatform), not the
+ * authority's keys; `forced`: with application fees still in escrow, which
+ * stay on the retired registry.
+ */
+export const RegistryRetiredEvent: any = Struct({ permitsRoot: Field, actionNonce: UInt32, successor: PublicKey, byPlatform: Bool, forced: Bool });
+export type RegistryCreatedEvent = any;
+
+// Application escrow.
+export const ApplicationFiledEvent: any = Struct({ application: Application });
+export type ApplicationFiledEvent = any;
+
+/** A permit moved to a new holder key: `leaf` is the new one (its old leaf is closed as MOVED, in a permitStatusChanged event). */
+export const PermitMovedEvent: any = Struct({ oldSubject: Field, leaf: PermitLeaf });
+export type PermitMovedEvent = any;
+
+export const ApplicationSettledEvent: any = Struct({
+  subject: Field,
+  applicationHash: Field,
+  outcome: Field,     // APPLICATION_OUTCOME: 1 approved, 2 rejected, 3 withdrawn, 4 reclaimed, 5 cancelled by the platform
+  kept: UInt64,       // paid out to the authority and the platform (98/2)
+  refunded: UInt64,   // returned to the payer
+});
+export type ApplicationSettledEvent = any;
+
+
+/** On-chain state layout (appState index → field), for direct account reads. */
+export const PERMIT_REGISTRY_STATE = {
+  permitsRoot: 0,
+  authorityKeysHash: 1,
+  authorityEpoch: 2,
+  actionNonce: 3,
+  policyPacked: 4,
+  feesPacked: 5,
+  payoutX: 6,
+  payoutIsOdd: 7,
+  version: 8,
+  ancestorsRoot: 9,
+  forkActivationSlot: 10,
+  metadataHash: 11,
+  networkId: 12,
+  escrowRoot: 13,
+  appTermsPacked: 14,
+  filingCount: 15,
+  successorX: 16,
+  successorIsOdd: 17,
+  pendingPayoutX: 18,
+  pendingPayoutIsOdd: 19,
+  pendingPayoutSlot: 20,
+  platformX: 21,
+  platformIsOdd: 22,
+  treasuryX: 23,
+  treasuryIsOdd: 24,
+  platformEpoch: 25,
+  /** Set by a platform retire: the key set the successor must keep (0 after the authority's own retire). */
+  frozenKeysHash: 26,
+} as const;
+
+/** Source version of the PermitRegistry circuit, set at initialize. */
+export const PERMIT_REGISTRY_VERSION = 1;
+
+/**
+ * Canonical PermitRegistry verification-key hashes by generation (the
+ * platform address is compiled in). Append-only, like CANONICAL_VK_HASHES:
+ * add a row for a new circuit release, never delete one. The keeper refuses
+ * to prove with a circuit whose hash isn't the current row, and the
+ * vkDrift test catches an unintended change.
+ */
+export const CANONICAL_PERMIT_VK_HASHES: Readonly<Record<number, string>> = {
+  1: '27337945734556665205684717094424577317630618958452630976255659397562153215921',
+};
+
+export const CURRENT_PERMIT_GENERATION: number = 1;
+
+export const CANONICAL_PERMIT_VK_HASH: string = CANONICAL_PERMIT_VK_HASHES[CURRENT_PERMIT_GENERATION];
+
+/** Verification-key hash of the PermitProof holder-proof ZkProgram. */
+export const CANONICAL_PERMIT_PROOF_VK_HASH: string = '17966873603167039790277974846902264570097359740655050143055465189220786366055';
+
+/**
+ * Events-only view of a PermitRegistry: `new PermitRegistryEvents(address)
+ * .fetchEvents(from?)` decodes a registry's events (archive node or local
+ * chain) without the private circuit source. Event names and shapes match
+ * PermitRegistry exactly, so the type indices agree.
+ */
+export const PermitRegistryEvents: any = class PermitRegistryEvents extends SmartContract {
+  events: any = {
+    registryCreated:     RegistryCreatedEvent,
+    permitGranted:       PermitGrantedEvent,
+    permitStatusChanged: PermitStatusEvent,
+    feesUpdated:         FeesUpdatedEvent,
+    authorityRotated:    AuthorityRotatedEvent,
+    applicationFiled:    ApplicationFiledEvent,
+    applicationSettled:  ApplicationSettledEvent,
+    registryRetired:     RegistryRetiredEvent,
+    permitMoved:         PermitMovedEvent,
+    payoutProposed:      PayoutProposedEvent,
+    payoutChanged:       PayoutChangedEvent,
+    platformChanged:     PlatformChangedEvent,
+  };
+};