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

package/src/archiveBootstrap.ts

@@ -0,0 +1,386 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * archiveBootstrap.ts
+ *
+ * Two layers:
+ *   - bootstrapFromArchive() fetches zkApp events and returns them normalized.
+ *     No writes. Caller decides what to do with the events.
+ *   - applyEventsToStore() writes the events to licenseStore.
+ *
+ * Events handled (write side):
+ *   licenseIssued          → applyLicenseIssued
+ *   licenseIssuedNoEscrow  → applyLicenseIssued (escrowless: true)
+ *   licenseRenewed         → updateExpiry
+ *   appCreated (successor) → carryOverRecords from its predecessor (lazyBootstrap)
+ *   appRetired             → ignored (the app is frozen; its successor carries on)
+ *   refundIssued           → recordRefund
+ *   fundsReleased          → recordRelease
+ *   deviceBound            → applyDeviceBound (non-custodial binding)
+ *   deviceUnbound          → applyDeviceUnbound (non-custodial binding)
+ *   priceUpdated           → ignored (price-history tracking lives in the private
+ *                             zklicensing-app backend alongside vendor-stats)
+ *
+ * Uses LicensingAppEventsContract (from contractInterface) for fetchEvents —
+ * this lets the public verify service read events without depending on the
+ * private LicensingApp circuit source.
+ */
+
+import { PublicKey } from 'o1js';
+import {
+  LicensingAppEventsContract,
+  ExpiryUpdateEvent,
+  LicenseIssuedEvent,
+  AppCreatedEvent,
+  PriceUpdatedEvent,
+  DeviceBoundEvent,
+  DeviceUnboundEvent,
+  MONTHLY_SLOTS_N,
+  ONE_YEAR_SLOTS_N,
+  FIVE_YEAR_SLOTS_N,
+  PERPETUAL_SLOTS_N,
+} from './contractInterface.js';
+import {
+  applyLicenseIssued,
+  applyLicenseRenewed,
+  applyDeviceBound,
+  applyDeviceUnbound,
+  applyLicenseTransferred,
+  recordRefund,
+  recordRelease,
+  readRecords,
+  carryOverRecords,
+} from './licenseStore.js';
+
+export const SYNC_CHUNK_SLOTS = 10_000;
+export const MAX_LOOKBACK_SLOTS = 525_600;
+
+export type Tier = 'monthly' | 'yearly' | 'fiveYear' | 'perpetual';
+
+export type NormalizedEvent =
+  | { kind: 'licenseIssued';          slot: number; licenseHash: string; amount: bigint; issuedSlot: number; expirySlot: number; buyerAddress: string; cap: number }
+  | { kind: 'licenseIssuedNoEscrow';  slot: number; licenseHash: string; amount: bigint; issuedSlot: number; expirySlot: number; buyerAddress: string; cap: number }
+  | { kind: 'licenseRenewed';         slot: number; licenseHash: string; newExpiry: number }
+  | { kind: 'appCreated';             slot: number; predecessor: string | null }
+  | { kind: 'appRetired';             slot: number; licensesRoot: string }
+  | { kind: 'refundIssued';           slot: number; licenseHash: string }
+  | { kind: 'fundsReleased';          slot: number; licenseHash: string }
+  | { kind: 'deviceBound';            slot: number; licenseHash: string; slotIndex: number; deviceCommitment: string; boundAtSlot: number }
+  | { kind: 'deviceUnbound';          slot: number; licenseHash: string; slotIndex: number; freedAtSlot: number }
+  | { kind: 'priceUpdated';           slot: number; priceMonthly: bigint; priceYearly: bigint; priceFiveYear: bigint; pricePerpetual: bigint }
+  | { kind: 'licenseTransferred';     slot: number; from: string; to: string; wallet: string };
+
+// Back-derive the duration tier from (expirySlot - purchaseSlot). Tolerance
+// of ±2 slots matches the SLOT_TOLERANCE used in the circuit.
+export function tierFromExpiryDelta(slots: number): Tier | null {
+  const within = (target: number) => Math.abs(slots - target) <= 2;
+  if (within(MONTHLY_SLOTS_N))   return 'monthly';
+  if (within(ONE_YEAR_SLOTS_N))  return 'yearly';
+  if (within(FIVE_YEAR_SLOTS_N)) return 'fiveYear';
+  if (within(PERPETUAL_SLOTS_N)) return 'perpetual';
+  return null;
+}
+
+export type FetchRange = {
+  from?: number;
+  to?:   number;
+};
+
+export type BootstrapResult = {
+  maxSeenSlot: number;
+  events: NormalizedEvent[];
+};
+
+export async function bootstrapFromArchive(
+  zkAppAddress: string,
+  range: FetchRange = {},
+): Promise<BootstrapResult> {
+  const pubKey = PublicKey.fromBase58(zkAppAddress);
+  const zkApp  = new LicensingAppEventsContract(pubKey);
+
+  // o1js's fetchEvents(from, to) passes these directly to the archive-node
+  // GraphQL as `from`/`to`, which the reference Mina archive interprets as
+  // BLOCK HEIGHTS, not global slots. We track everything in slots, so the two
+  // never match and every query returned zero events. Fetch all events for
+  // the address and filter by globalSlot client-side — over-fetches per
+  // chunked call, but is the only correct behavior against this archive.
+  const allEvents = await zkApp.fetchEvents();
+
+  const fromSlot = range.from ?? 0;
+  const toSlot   = range.to   ?? Number.MAX_SAFE_INTEGER;
+
+  // Filter out only orphaned events; keep both 'canonical' and 'pending'.
+  // The devnet-archive-node-api.gcp.o1test.net archive returns everything
+  // with chainStatus='pending' (it doesn't finalize the flag), so a strict
+  // `=== 'canonical'` filter drops every event and the mirror stays empty.
+  // Mina's k-block finality means recently-landed events on the best chain
+  // are safe to replay; if one later reorgs out, the next sync sweep will
+  // re-derive state from the new canonical events (a no-op if none of them
+  // touch this record).
+  const canonical = [...allEvents]
+    .filter(e => e.chainStatus !== 'orphaned')
+    .filter(e => {
+      const slot = Number(e.globalSlot.toString());
+      return slot >= fromSlot && slot <= toSlot;
+    })
+    .sort((a, b) => Number(a.globalSlot.toString()) - Number(b.globalSlot.toString()));
+
+  const events: NormalizedEvent[] = [];
+
+  for (const ev of canonical) {
+    const slot = Number(ev.globalSlot.toString());
+    switch (ev.type) {
+      case 'priceUpdated': {
+        const data = ev.event.data as unknown as PriceUpdatedEvent;
+        events.push({
+          kind: 'priceUpdated',
+          slot,
+          priceMonthly:   BigInt(data.priceMonthly.toString()),
+          priceYearly:    BigInt(data.priceYearly.toString()),
+          priceFiveYear:  BigInt(data.priceFiveYear.toString()),
+          pricePerpetual: BigInt(data.pricePerpetual.toString()),
+        });
+        break;
+      }
+      case 'licenseIssued': {
+        const data = ev.event.data as unknown as LicenseIssuedEvent;
+        events.push({
+          kind: 'licenseIssued',
+          slot,
+          licenseHash:  data.licenseHash.toString(),
+          amount:       BigInt(data.amount.toString()),
+          issuedSlot:   Number(data.slot.toString()),
+          expirySlot:   Number(data.expirySlot.toString()),
+          buyerAddress: data.buyer.toBase58(),
+          cap:          Number(data.cap.toString()),
+        });
+        break;
+      }
+      case 'licenseIssuedNoEscrow': {
+        const data = ev.event.data as unknown as LicenseIssuedEvent;
+        events.push({
+          kind: 'licenseIssuedNoEscrow',
+          slot,
+          licenseHash:  data.licenseHash.toString(),
+          amount:       BigInt(data.amount.toString()),
+          issuedSlot:   Number(data.slot.toString()),
+          expirySlot:   Number(data.expirySlot.toString()),
+          buyerAddress: data.buyer.toBase58(),
+          cap:          Number(data.cap.toString()),
+        });
+        break;
+      }
+      case 'licenseRenewed': {
+        const data = ev.event.data as unknown as ExpiryUpdateEvent;
+        events.push({
+          kind: 'licenseRenewed',
+          slot,
+          licenseHash: data.licenseHash.toString(),
+          newExpiry: Number(data.newExpiry.toString()),
+        });
+        break;
+      }
+      case 'appCreated': {
+        const data = ev.event.data as unknown as AppCreatedEvent;
+        const pred = data.predecessor as PublicKey;
+        events.push({ kind: 'appCreated', slot, predecessor: pred.equals(PublicKey.empty()).toBoolean() ? null : pred.toBase58() });
+        break;
+      }
+      case 'appRetired':
+        events.push({ kind: 'appRetired', slot, licensesRoot: (ev.event.data as any).licensesRoot.toString() });
+        break;
+      case 'refundIssued':
+        events.push({ kind: 'refundIssued', slot, licenseHash: (ev.event.data as any).toString() });
+        break;
+      case 'fundsReleased':
+        events.push({ kind: 'fundsReleased', slot, licenseHash: (ev.event.data as any).toString() });
+        break;
+      case 'deviceBound': {
+        const data = ev.event.data as unknown as DeviceBoundEvent;
+        events.push({
+          kind: 'deviceBound',
+          slot,
+          licenseHash:      data.licenseHash.toString(),
+          slotIndex:        Number(data.slotIndex.toString()),
+          deviceCommitment: data.deviceCommitment.toString(),
+          // Proof-time slot, NOT the block slot. The circuit packs this into
+          // the leaf's freedAt field, so the mirror must use the same value
+          // or the reconstructed leaf hash won't match the on-chain root.
+          boundAtSlot:      Number(data.boundAtSlot.toString()),
+        });
+        break;
+      }
+      case 'licenseTransferred': {
+        const data = ev.event.data as any;
+        events.push({ kind: 'licenseTransferred', slot, from: data.from.toString(), to: data.to.toString(), wallet: data.wallet.toBase58() });
+        break;
+      }
+      case 'deviceUnbound': {
+        const data = ev.event.data as unknown as DeviceUnboundEvent;
+        events.push({
+          kind: 'deviceUnbound',
+          slot,
+          licenseHash: data.licenseHash.toString(),
+          slotIndex:   Number(data.slotIndex.toString()),
+          // Proof-time slot; see deviceBound comment above.
+          freedAtSlot: Number(data.freedAtSlot.toString()),
+        });
+        break;
+      }
+    }
+  }
+
+  const maxSeenSlot = canonical.length === 0
+    ? -1
+    : Number(canonical[canonical.length - 1].globalSlot.toString());
+
+  return { maxSeenSlot, events };
+}
+
+export async function applyEventsToStore(
+  zkAppAddress: string,
+  events: NormalizedEvent[],
+): Promise<{ count: number; warnings: string[] }> {
+  const warnings: string[] = [];
+  let count = 0;
+
+  for (const ev of events) {
+    switch (ev.kind) {
+      case 'priceUpdated':
+        break;
+      case 'licenseIssued': {
+        const tier = tierFromExpiryDelta(ev.expirySlot - ev.issuedSlot) ?? undefined;
+        await applyLicenseIssued(zkAppAddress, ev.licenseHash, {
+          expirySlot:     ev.expirySlot,
+          purchaseSlot:   ev.issuedSlot,
+          purchaseAmount: ev.amount.toString(),
+          buyerAddress:   ev.buyerAddress,
+          deviceCap:      ev.cap,
+          ...(tier ? { tier } : {}),
+        });
+        count++;
+        break;
+      }
+      case 'licenseIssuedNoEscrow': {
+        const tier = tierFromExpiryDelta(ev.expirySlot - ev.issuedSlot) ?? undefined;
+        await applyLicenseIssued(zkAppAddress, ev.licenseHash, {
+          expirySlot:     ev.expirySlot,
+          purchaseSlot:   ev.issuedSlot,
+          purchaseAmount: ev.amount.toString(),
+          escrowless:     true,
+          buyerAddress:   ev.buyerAddress,
+          deviceCap:      ev.cap,
+          ...(tier ? { tier } : {}),
+        });
+        count++;
+        break;
+      }
+      case 'licenseRenewed': {
+        const ok = await applyLicenseRenewed(zkAppAddress, ev.licenseHash, { newExpiry: ev.newExpiry });
+        if (!ok) warnings.push(`renew for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+        break;
+      }
+      case 'appCreated':
+      case 'appRetired':
+        // A successor's carried-over licenses are copied by lazyBootstrap
+        // (from its predecessor) before its own events apply.
+        break;
+      case 'refundIssued': {
+        const ok = await recordRefund(zkAppAddress, ev.licenseHash);
+        if (!ok) warnings.push(`refund for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+        break;
+      }
+      case 'fundsReleased': {
+        const ok = await recordRelease(zkAppAddress, ev.licenseHash, ev.slot);
+        if (!ok) warnings.push(`release for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+        break;
+      }
+      case 'deviceBound': {
+        const ok = await applyDeviceBound(zkAppAddress, ev.licenseHash, {
+          slotIndex:        ev.slotIndex,
+          deviceCommitment: ev.deviceCommitment,
+          boundAtSlot:      ev.boundAtSlot,
+        });
+        if (!ok) warnings.push(`bind for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+        break;
+      }
+      case 'licenseTransferred': {
+        const ok = await applyLicenseTransferred(zkAppAddress, ev.from, ev.to, { wallet: ev.wallet });
+        if (!ok) warnings.push(`transfer of unknown license ${ev.from.slice(0, 16)}…`);
+        break;
+      }
+      case 'deviceUnbound': {
+        const ok = await applyDeviceUnbound(zkAppAddress, ev.licenseHash, {
+          slotIndex:   ev.slotIndex,
+          freedAtSlot: ev.freedAtSlot,
+        });
+        if (!ok) warnings.push(`unbind for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+        break;
+      }
+    }
+  }
+
+  return { count, warnings };
+}
+
+export async function discoverAppCreatedSlot(
+  zkAppAddress: string,
+  nowSlot: number,
+  lookbackSlots: number = MAX_LOOKBACK_SLOTS,
+): Promise<number | null> {
+  const pubKey = PublicKey.fromBase58(zkAppAddress);
+  const zkApp  = new LicensingAppEventsContract(pubKey);
+  const floor  = Math.max(1, nowSlot - lookbackSlots);
+
+  // See bootstrapFromArchive: fetchEvents(from, to) filters by BLOCK HEIGHT
+  // in the reference archive, not slot. One full fetch + client-side slot
+  // filter is the only correct approach. Also keeps chainStatus='pending'
+  // events — o1test.net's devnet archive doesn't finalize that flag; strict
+  // 'canonical' filtering leaves discovery empty on freshly-deployed apps.
+  const events = await zkApp.fetchEvents();
+  const created = events
+    .filter(e => e.chainStatus !== 'orphaned' && e.type === 'appCreated')
+    .filter(e => {
+      const slot = Number(e.globalSlot.toString());
+      return slot >= floor && slot <= nowSlot;
+    })
+    .sort((a, b) => Number(a.globalSlot.toString()) - Number(b.globalSlot.toString()));
+  if (created.length > 0) return Number(created[0].globalSlot.toString());
+  return null;
+}
+
+const inFlightBootstraps = new Map<string, Promise<void>>();
+
+export async function lazyBootstrap(zkAppAddress: string): Promise<void> {
+  const existing = inFlightBootstraps.get(zkAppAddress);
+  if (existing) return existing;
+  const short = zkAppAddress.slice(0, 12) + '…';
+  const p = (async () => {
+    const started = Date.now();
+    try {
+      const { events } = await bootstrapFromArchive(zkAppAddress);
+      // A redeployed app's successor starts with its predecessor's licenses:
+      // rebuild those first (recursively), then copy them across.
+      const created = events.find(e => e.kind === 'appCreated');
+      if (created?.kind === 'appCreated' && created.predecessor) {
+        if (!(await readRecords()).some(r => r.zkAppAddress === created.predecessor)) await lazyBootstrap(created.predecessor);
+        await carryOverRecords(created.predecessor, zkAppAddress);
+      }
+      const { count, warnings } = await applyEventsToStore(zkAppAddress, events);
+      for (const w of warnings) console.warn(`[lazy-bootstrap] ${short}: ${w}`);
+      // Always log the outcome — count=0 with a mismatch trigger is the
+      // interesting case: it means either the archive is behind Mina's own
+      // best chain (transient) or the local mirror silently drifted and the
+      // replay didn't fix it (a real bug — verify will keep looping through
+      // this until the next mutation event lands). Silence would hide both.
+      console.log(`[lazy-bootstrap] ${short}: replayed ${count} record(s) in ${Date.now() - started}ms`);
+    } catch (e: any) {
+      console.warn(`[lazy-bootstrap] ${short}: ${e?.message ?? e}`);
+    } finally {
+      inFlightBootstraps.delete(zkAppAddress);
+    }
+  })();
+  inFlightBootstraps.set(zkAppAddress, p);
+  return p;
+}

package/src/atomicJson.ts

@@ -0,0 +1,53 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * atomicJson.ts — `zklicensing/internal/atomicJson`
+ *
+ * Crash-safe JSON files. A write goes to a temporary file in the same
+ * directory, is flushed to disk, and replaces the target with one rename, so
+ * a crash leaves either the old or the new file — never half of one. A read
+ * returns the fallback only when the file doesn't exist; a file that exists
+ * but doesn't parse is an error, so a damaged store is never mistaken for an
+ * empty one (and then overwritten with nothing).
+ */
+
+// Only a default import of fs/promises (no named imports from Node modules):
+// browser bundles that reach this file through licenseStore get Vite's empty
+// stub for it instead of a build error.
+import fs from 'fs/promises';
+
+export async function readJsonOr<T>(path: string, fallback: T): Promise<T> {
+  let text: string;
+  try {
+    text = await fs.readFile(path, 'utf8');
+  } catch (e: any) {
+    if (e?.code === 'ENOENT') return fallback;
+    throw e;
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch (e: any) {
+    throw new Error(`${path} exists but is not valid JSON (${e?.message ?? e}); restore it from a backup — refusing to treat it as empty`);
+  }
+}
+
+export async function writeJsonAtomic(path: string, value: unknown, opts: { mode?: number } = {}): Promise<void> {
+  // Same directory as the target (rename is only atomic within a file system).
+  const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  const suffix = [...crypto.getRandomValues(new Uint8Array(6))].map(b => b.toString(16).padStart(2, '0')).join('');
+  const tmp = `${path.slice(0, slash + 1)}.${path.slice(slash + 1)}.${suffix}.tmp`;
+  const fh = await fs.open(tmp, 'w', opts.mode ?? 0o600);
+  try {
+    await fh.writeFile(JSON.stringify(value, null, 2), 'utf8');
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  try {
+    await fs.rename(tmp, path);
+  } catch (e) {
+    await fs.rm(tmp, { force: true });
+    throw e;
+  }
+}