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

package/src/licenseTrustless.ts

@@ -0,0 +1,207 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseTrustless.ts — a license check that doesn't trust the keeper.
+ *
+ * The keeper's `/verify` reads the chain for you; here the caller reads it:
+ *
+ *   1. From a Mina node: the contract account at each address checked (its
+ *      license root, verification key and permissions) and the current slot.
+ *      The contract must run a published LicensingApp release (the pinned
+ *      CANONICAL_VK_HASHES) and be locked: state changes only by proof, no
+ *      new verification key, no new permissions.
+ *   2. From the keeper: only the license's leaf fields and Merkle path
+ *      (`/witness`). They are hashed and folded up to the root read in 1, so
+ *      a keeper that lies, or is behind, can't make the check pass; it can
+ *      only make it fail. An absent license is proved the same way (an
+ *      empty leaf folds to the root).
+ *   3. Which addresses belong to the app: the platform-signed generation
+ *      list (`/apps/by-address`), checked against the pinned manifest keys.
+ *      As the keeper does, the current generation is tried first, then the
+ *      address given, then the other retired ones (licenses refunded or
+ *      expired before a redeploy stay there). Without a valid signed list the
+ *      given address and its on-chain successors are checked: a retired
+ *      contract names its successor in its state (see successorChain.ts).
+ *
+ * Whether the address is the app you think it is (the seller's website) is
+ * a separate check: verifyTrustAnchor. Loads o1js (for Poseidon).
+ */
+
+import { AgentError, PLATFORM_MANIFEST_PUBKEYS } from './agent.js';
+import { CANONICAL_VK_HASHES, GRACE_PERIOD_N, LICENSING_APP_STATE, MS_PER_SLOT_N, SLOTS_PER_DAY_N, effectiveExpirySlot } from './contractInterface.js';
+import { DEFAULT_MINA_GRAPHQL_URLS } from './onChainRoot.js';
+import { MinaNodeError, readZkappHead } from './chainHead.js';
+import { LICENSING_LINEAGE, currentOnChain } from './successorChain.js';
+import { verifyManifest } from './manifestVerify.js';
+
+export type TrustlessLicenseVerification = {
+  valid: boolean;
+  expiresAt: string | null;
+  expirySlot: number;
+  inGracePeriod: boolean;
+  remainingDays: number;
+  reason: string | null;
+  trustless: true;
+  /** The contract address the license was checked at (another generation of the app's contract, if that's where it is). */
+  resolvedAddress: string;
+  /** LicensingApp release (generation) of that contract, from its verification key. */
+  generation: number | null;
+  /** Current slot, as the Mina node reported it. */
+  slot: number;
+  /** Whether the app's generation list came signed by the platform ("verified") or only the given address and its on-chain successors were checked. */
+  generations: 'verified' | 'given-address-only';
+};
+
+type ContractHead = { found: boolean; root?: string; forkSlot?: number; vkHash?: string; editState?: string; setPermissions?: string; setVerificationKey?: string; slot: number };
+
+async function readContract(address: string, graphqlUrl: string, f: typeof fetch): Promise<ContractHead> {
+  let head: Awaited<ReturnType<typeof readZkappHead>>;
+  try {
+    head = await readZkappHead({ address, graphqlUrl, fetcher: f });
+  } catch (e: any) {
+    throw new AgentError(e?.message ?? String(e), 'UPSTREAM_UNAVAILABLE', e instanceof MinaNodeError ? e.status : 0, true);
+  }
+  const { account: a, slot } = head;
+  if (slot === undefined) throw new AgentError(`Mina node ${graphqlUrl} did not report the current slot`, 'UPSTREAM_UNAVAILABLE', 0, true);
+  if (!a.found) return { found: false, slot };
+  return {
+    found: true, slot,
+    root: a.appState?.[0],
+    forkSlot: Number(a.appState?.[LICENSING_APP_STATE.forkActivationSlot] ?? 0),
+    vkHash: a.vkHash,
+    editState: a.permissions?.editState, setPermissions: a.permissions?.setPermissions, setVerificationKey: a.permissions?.setVerificationKey?.auth,
+  };
+}
+
+/** Why a contract isn't a genuine, locked LicensingApp, or null. */
+export function contractProblem(c: ContractHead): string | null {
+  if (!c.found || !c.root) return 'no zkApp at this address on this network';
+  if (!c.vkHash || !Object.values(CANONICAL_VK_HASHES).includes(c.vkHash)) return 'the contract is not a published LicensingApp release (verification key)';
+  if (c.editState !== 'Proof') return 'the contract state can be changed without a proof';
+  if (c.setVerificationKey !== 'Impossible') return 'the contract\'s verification key can be replaced';
+  if (c.setPermissions !== 'Impossible') return 'the contract\'s permissions can be changed';
+  return null;
+}
+
+/** Addresses to try, current generation first; null when no valid signed list. */
+async function signedGenerations(base: string, address: string, f: typeof fetch, pinned: readonly string[], network: 'devnet' | 'mainnet'): Promise<string[] | null> {
+  try {
+    const r = await f(`${base}/apps/by-address/${encodeURIComponent(address)}`, { headers: { Accept: 'application/json' } });
+    if (!r.ok) return null;
+    // Only the signed fields count (the keeper adds unsigned envelope fields after signing).
+    const b = await verifyManifest(await r.json(), pinned, { network });
+    if (!b) return null;
+    const gens = (b.generations as Array<{ gen?: number; zkAppAddress?: string }>).filter(g => typeof g.zkAppAddress === 'string');
+    if (!gens.some(g => g.zkAppAddress === address)) return null;
+    const current = gens.find(g => g.gen === b.current)?.zkAppAddress;
+    const others = gens.map(g => g.zkAppAddress!).filter(a => a !== current && a !== address).reverse();
+    return [...new Set([current, address, ...others].filter((a): a is string => !!a))];
+  } catch {
+    return null;
+  }
+}
+
+type Witness = { root?: string; currentValue: string; isLefts: boolean[]; siblings: string[]; leaf: { expirySlot: number; deviceCap: number; deviceSlotsRoot: string; deviceSlotsFilled: number } };
+
+/** Folds the keeper's leaf fields and path; the on-chain root decides. */
+async function foldsTo(w: Witness, licenseHash: string, root: string): Promise<boolean> {
+  const { Field, UInt32 } = await import('o1js');
+  const { LicenseLeaf, leafHash } = await import('./licenseLeaf.js');
+  const { deserializeWitness } = await import('./licenseStore.js');
+  const leafValue = w.currentValue === '0'
+    ? Field(0)
+    : leafHash(new LicenseLeaf({
+      licenseHash: Field(licenseHash), expirySlot: UInt32.from(w.leaf.expirySlot), cap: UInt32.from(w.leaf.deviceCap),
+      deviceSlotsRoot: Field(w.leaf.deviceSlotsRoot), deviceSlotsFilled: UInt32.from(w.leaf.deviceSlotsFilled),
+    }));
+  const [computedRoot, key] = deserializeWitness({ isLefts: w.isLefts, siblings: w.siblings }).computeRootAndKey(leafValue);
+  return key.toString() === Field(licenseHash).toString() && computedRoot.toString() === root;
+}
+
+export async function verifyLicenseTrustless(opts: {
+  keeperUrl: string;
+  network: 'devnet' | 'mainnet';
+  zkAppAddress: string;
+  licenseHash: string;
+  /** Your own Mina node (default: a public one per network). */
+  graphqlUrl?: string;
+  fetcher?: typeof fetch;
+  pinnedPublicKeysBase64?: readonly string[];
+  /** Wait between the two witness reads when the keeper is behind the chain (ms). */
+  retryDelayMs?: number;
+}): Promise<TrustlessLicenseVerification> {
+  const f = opts.fetcher ?? fetch;
+  const base = opts.keeperUrl.replace(/\/+$/, '');
+  const graphqlUrl = opts.graphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[opts.network];
+  if (!/^\d{1,80}$/.test(opts.licenseHash)) throw new AgentError('licenseHash must be a decimal field element', 'INVALID_REQUEST', 0, false);
+
+  const signed = await signedGenerations(base, opts.zkAppAddress, f, opts.pinnedPublicKeysBase64 ?? PLATFORM_MANIFEST_PUBKEYS, opts.network);
+  // The chain names the current generation too: a retired contract stores
+  // its successor. One found there goes first, so a missing or stale list
+  // still finds it.
+  let current: string;
+  try {
+    current = (await currentOnChain({ start: opts.zkAppAddress, layout: LICENSING_LINEAGE, canonicalVks: Object.values(CANONICAL_VK_HASHES), graphqlUrl, fetcher: f })).address;
+  } catch (e: any) {
+    if (e instanceof MinaNodeError) throw new AgentError(e.message, 'UPSTREAM_UNAVAILABLE', e.status, true);
+    return result({ valid: false, reason: `Not a genuine licensing lineage: ${e?.message ?? e}` }, opts.zkAppAddress, null, 0, signed);
+  }
+  const listed = signed ?? [opts.zkAppAddress];
+  const addresses = current === opts.zkAppAddress ? listed : [...new Set([current, ...listed])];
+
+  let last: { address: string; generation: number | null; slot: number } | null = null;
+  for (const address of addresses) {
+    const c = await readContract(address, graphqlUrl, f);
+    const problem = contractProblem(c);
+    if (problem) {
+      // The address asked about must be genuine; a broken other generation is skipped.
+      if (address === opts.zkAppAddress) {
+        return result({ valid: false, reason: `Not a genuine licensing contract: ${problem}` }, address, null, c.slot, signed);
+      }
+      continue;
+    }
+    const generation = Number(Object.entries(CANONICAL_VK_HASHES).find(([, h]) => h === c.vkHash)![0]);
+    let w: Witness | null = null;
+    let ok = false;
+    // The keeper may be a block or two behind a fresh purchase: one more read.
+    for (let attempt = 0; attempt < 2 && !ok; attempt++) {
+      if (attempt > 0) await new Promise(r => setTimeout(r, opts.retryDelayMs ?? 3000));
+      const r = await f(`${base}/witness/${encodeURIComponent(address)}/${encodeURIComponent(opts.licenseHash)}?network=${opts.network}`, { headers: { Accept: 'application/json' } }).catch(() => null);
+      if (!r?.ok) continue;
+      w = await r.json().catch(() => null) as Witness | null;
+      if (w && Array.isArray(w.isLefts) && Array.isArray(w.siblings) && w.leaf) ok = await foldsTo(w, opts.licenseHash, c.root!);
+    }
+    if (!ok || !w) {
+      throw new AgentError(`The keeper's copy of ${address} does not match the chain (it may be catching up); retry, or check without trustless`, 'STATE_MISMATCH', 0, true, 10_000);
+    }
+    last = { address, generation, slot: c.slot };
+    if (w.currentValue === '0') continue; // proved absent here: try the next generation
+    const expirySlot = w.leaf.expirySlot;
+    // A license that lapsed during the pre-fork sales freeze counts from the fork slot.
+    const until = effectiveExpirySlot(expirySlot, c.forkSlot ?? 0);
+    const inGracePeriod = c.slot > until && c.slot <= until + GRACE_PERIOD_N;
+    const expired = c.slot > until + GRACE_PERIOD_N;
+    return result({
+      valid: !expired,
+      expirySlot,
+      inGracePeriod: !expired && inGracePeriod,
+      expiresAt: new Date(Date.now() + (until - c.slot) * MS_PER_SLOT_N).toISOString(),
+      remainingDays: Math.floor((until - c.slot) / SLOTS_PER_DAY_N),
+      reason: expired ? 'License has expired' : inGracePeriod ? 'License is in grace period — renew to avoid interruption' : null,
+    }, address, generation, c.slot, signed);
+  }
+  return result({ valid: false, reason: 'License not found on chain (never bought at this app, or refunded)' },
+    last?.address ?? opts.zkAppAddress, last?.generation ?? null, last?.slot ?? 0, signed);
+}
+
+function result(
+  r: Partial<TrustlessLicenseVerification> & { valid: boolean; reason: string | null },
+  address: string, generation: number | null, slot: number, signed: string[] | null,
+): TrustlessLicenseVerification {
+  return {
+    valid: r.valid, expiresAt: r.expiresAt ?? null, expirySlot: r.expirySlot ?? 0, inGracePeriod: r.inGracePeriod ?? false,
+    remainingDays: r.remainingDays ?? 0, reason: r.reason, trustless: true,
+    resolvedAddress: address, generation, slot, generations: signed ? 'verified' : 'given-address-only',
+  };
+}

package/src/manifestVerify.ts

@@ -0,0 +1,164 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * manifestVerify.ts
+ *
+ * Browser + Node Ed25519 signature verification for platform-signed manifests
+ * (currently: the generation-list served at GET /apps/:appId, next: the
+ * sales-freeze manifest). The backend signs with the platform manifest key
+ * loaded via PLATFORM_MANIFEST_KEY_FILE; the SDK pins the public key against
+ * a caller-supplied allow-list and verifies before trusting anything.
+ *
+ * Runtime: browsers and Node ≥ 20 expose `globalThis.crypto.subtle`. The
+ * SDK's `engines.node` is `>=20` for this reason — Node 18 child workers
+ * (spawned by `node --test`) do not populate `globalThis.crypto`.
+ *
+ * Canonicalization must match `src/manifestSign.ts` byte-for-byte:
+ *   - sorted object keys
+ *   - no whitespace
+ *   - arrays preserved in order
+ * Any divergence silently breaks verification, so keep the algorithm dead
+ * simple and mirrored.
+ */
+
+// Canonical JSON: sorted keys, no whitespace, arrays preserved in order.
+// Undefined values are skipped, mirroring JSON.stringify — otherwise the
+// signed bytes would contain `"key":undefined` for optional fields left
+// unset, while `res.json()` on the wire would strip them, and the signature
+// would never verify.
+// Mirror of src/manifestSign.ts:canonicalize. Divergence here silently
+// breaks verification.
+export function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).filter(k => obj[k] !== undefined).sort();
+  return '{' + keys.map(k =>
+    JSON.stringify(k) + ':' + canonicalize(obj[k])
+  ).join(',') + '}';
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  // atob is present in every modern JS runtime we target (browser + Node ≥ 16).
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+// SPKI DER wrapper around a raw 32-byte Ed25519 public key.
+// Same prefix used by src/manifestSign.ts:verifyPayload — WebCrypto needs
+// SPKI to import; the wire format is raw base64 for space.
+const ED25519_SPKI_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+function rawEd25519ToSpki(raw: Uint8Array): Uint8Array {
+  if (raw.length !== 32) throw new Error(`Ed25519 pubkey must be 32 bytes, got ${raw.length}`);
+  const out = new Uint8Array(ED25519_SPKI_PREFIX.length + raw.length);
+  out.set(ED25519_SPKI_PREFIX, 0);
+  out.set(raw, ED25519_SPKI_PREFIX.length);
+  return out;
+}
+
+/**
+ * Verify a base64 Ed25519 signature over a canonicalized payload against
+ * one of the pinned base64 public keys. Returns true iff at least one
+ * pinned key verifies. Fails closed on any error (unknown key format,
+ * WebCrypto rejection, missing subtle) — callers must interpret `false`
+ * as "do not trust."
+ */
+export async function verifyManifestSignature(
+  payload: unknown,
+  signatureBase64: string,
+  pinnedPublicKeysBase64: readonly string[],
+): Promise<boolean> {
+  if (!pinnedPublicKeysBase64.length) return false;
+  const subtle = (globalThis.crypto as Crypto | undefined)?.subtle;
+  if (!subtle) return false;
+  const messageBytes = utf8Bytes(canonicalize(payload));
+  let signatureBytes: Uint8Array;
+  try { signatureBytes = base64ToBytes(signatureBase64); }
+  catch { return false; }
+  for (const pinB64 of pinnedPublicKeysBase64) {
+    try {
+      const spki = rawEd25519ToSpki(base64ToBytes(pinB64));
+      const key = await subtle.importKey(
+        'spki',
+        spki as unknown as ArrayBuffer,
+        { name: 'Ed25519' },
+        false,
+        ['verify'],
+      );
+      const ok = await subtle.verify(
+        { name: 'Ed25519' },
+        key,
+        signatureBytes as unknown as ArrayBuffer,
+        messageBytes as unknown as ArrayBuffer,
+      );
+      if (ok) return true;
+    } catch {
+      // Try the next pin — one bad entry in the pin list must not mask
+      // a valid signature under a different pin.
+    }
+  }
+  return false;
+}
+
+/**
+ * The fields the platform signs in an app's generation manifest (GET
+ * /apps/:appId, and the vendor's /.well-known/zklicensing/<address>.json).
+ * The keeper adds envelope fields after signing (signature, publicKey, app,
+ * forkActivationSlot…), so verifiers rebuild exactly these. `network` keeps a
+ * devnet manifest from passing for mainnet and the other way round.
+ */
+export type SignedManifest = {
+  appId: string;
+  network: 'devnet' | 'mainnet';
+  current: number;
+  generations: unknown[];
+  issuedAt: string;
+};
+
+/** The signed fields of a manifest body, or null when any is missing. */
+export function signedManifestOf(body: unknown): SignedManifest | null {
+  if (!body || typeof body !== 'object') return null;
+  const b = body as Record<string, unknown>;
+  if (typeof b.appId !== 'string' || (b.network !== 'devnet' && b.network !== 'mainnet') || typeof b.current !== 'number'
+    || !Array.isArray(b.generations) || typeof b.issuedAt !== 'string') return null;
+  return { appId: b.appId, network: b.network, current: b.current, generations: b.generations, issuedAt: b.issuedAt };
+}
+
+/**
+ * Every signature a manifest carries: `signature`, and `signatures` (one per
+ * platform key; during a key rotation both the old and the new key sign).
+ */
+export function manifestSignaturesOf(body: unknown): string[] {
+  if (!body || typeof body !== 'object') return [];
+  const b = body as { signature?: unknown; signatures?: unknown };
+  const list = Array.isArray(b.signatures) ? b.signatures.map((s: any) => s?.signature).filter((s: unknown): s is string => typeof s === 'string') : [];
+  return [...new Set([...(typeof b.signature === 'string' ? [b.signature] : []), ...list])];
+}
+
+/**
+ * The signed manifest in `body` when one of its signatures verifies against
+ * a pinned key (and it is for `expect.network`, when given); else null.
+ */
+export async function verifyManifest(
+  body: unknown,
+  pinnedPublicKeysBase64: readonly string[],
+  expect: { network?: 'devnet' | 'mainnet' } = {},
+): Promise<SignedManifest | null> {
+  const payload = signedManifestOf(body);
+  if (!payload) return null;
+  if (expect.network && payload.network !== expect.network) return null;
+  for (const sig of manifestSignaturesOf(body)) {
+    if (await verifyManifestSignature(payload, sig, pinnedPublicKeysBase64)) return payload;
+  }
+  return null;
+}

package/src/minaPriceHistory.ts

@@ -0,0 +1,166 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * minaPriceHistory.ts
+ *
+ * Historical MINA→fiat lookups for archive-replayed license records that were
+ * created before the backend had a live CoinGecko cache. Uses CoinGecko's
+ * free-tier `/coins/mina-protocol/history?date=DD-MM-YYYY` endpoint, which
+ * returns a UTC end-of-day snapshot in a single call. Rates for a past day
+ * never change, so results are cached permanently to a JSON file — a repeat
+ * bootstrap replays without another HTTP round-trip.
+ *
+ * Not used by live purchase / renew flows — those keep hitting the 5-minute
+ * `/simple/price` cache in keeperService.ts. Only invoked by the backfill
+ * pass that stamps historical `fiatSnapshot` after archive replay.
+ */
+
+import fs from 'fs/promises';
+
+// Mina consensus slot is 3 min in theory; on-chain block time targets 90s.
+// The stats module uses the same constant for its monthly aggregation
+// (stats.ts:25). Any drift here shows up as records stamped with the wrong
+// day's rate for events near the UTC midnight boundary.
+const SLOT_DURATION_MS = 90 * 1000;
+
+// CoinGecko free-tier is ~30 req/min. A 1.5s spacing keeps us comfortably
+// under that for a single-tenant backend backfill; if a very large replay ever
+// hits the limit CoinGecko returns 429 and getMinaFiatForDate returns null,
+// leaving that day's records unstamped (dashboards render fiat as `—`).
+const THROTTLE_MS = 1500;
+
+// Days for which CoinGecko returned no usable data. Kept in-memory only —
+// they don't get written to the on-disk cache so a follow-up bootstrap after
+// e.g. a CoinGecko outage will retry them. Guards against re-hitting the
+// endpoint for the same missing date within one process lifetime.
+const missingDates = new Set<string>();
+
+export type HistoricalRate = {
+  eur: number;
+  usd: number;
+  gbp: number;
+};
+
+// Convert a Mina global slot to a UTC calendar date (YYYY-MM-DD). Uses the
+// per-network (currentSlot, nowMs) pair as the anchor so caller can pass the
+// clock captured at bootstrap time. Same trick stats.ts:slotToMonthKey uses.
+export function slotToUtcDate(slot: number, currentSlot: number, nowMs: number): string {
+  const ms = nowMs - (currentSlot - slot) * SLOT_DURATION_MS;
+  const d = new Date(ms);
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')}`;
+}
+
+function isoToCoinGeckoDate(iso: string): string {
+  const [y, m, d] = iso.split('-');
+  return `${d}-${m}-${y}`;
+}
+
+function cachePath(): string {
+  return process.env.MINA_PRICE_CACHE_PATH ?? 'mina-prices.json';
+}
+
+type CacheFile = Record<string, HistoricalRate>;
+
+let cache: CacheFile | null = null;
+let cacheLoaded = false;
+
+async function loadCache(): Promise<CacheFile> {
+  if (cacheLoaded && cache) return cache;
+  try {
+    const raw = await fs.readFile(cachePath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') {
+      cache = parsed as CacheFile;
+    } else {
+      cache = {};
+    }
+  } catch {
+    cache = {};
+  }
+  cacheLoaded = true;
+  return cache;
+}
+
+// Serialize cache writes so concurrent stamping calls don't clobber each
+// other's entries. Every write flushes the whole file — tiny (< 10KB even
+// for years of dates) so no need for anything fancier.
+let writeChain: Promise<void> = Promise.resolve();
+function withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  const result = writeChain.then(fn, fn);
+  writeChain = result.then(() => {}, () => {});
+  return result;
+}
+
+async function persistCache(): Promise<void> {
+  if (!cache) return;
+  await fs.writeFile(cachePath(), JSON.stringify(cache, null, 2));
+}
+
+// Serialize the outbound HTTP calls so we respect CoinGecko's rate limit
+// without a global scheduler. Concurrent callers of getMinaFiatForDate for
+// distinct dates queue up 1.5s apart.
+let lastFetchAt = 0;
+let fetchChain: Promise<void> = Promise.resolve();
+function throttled<T>(fn: () => Promise<T>): Promise<T> {
+  const next = fetchChain.then(async () => {
+    const wait = Math.max(0, THROTTLE_MS - (Date.now() - lastFetchAt));
+    if (wait > 0) await new Promise(r => setTimeout(r, wait));
+    lastFetchAt = Date.now();
+  });
+  fetchChain = next.then(() => {}, () => {});
+  return next.then(fn);
+}
+
+// Return { eur, usd, gbp } for the given UTC calendar date, or null if the
+// endpoint fails or omits any of the three currencies. Cached results are
+// returned immediately. Fail-soft: no exceptions, just null → caller leaves
+// the record unstamped.
+export async function getMinaFiatForDate(iso: string): Promise<HistoricalRate | null> {
+  const c = await loadCache();
+  if (c[iso]) return c[iso];
+  if (missingDates.has(iso)) return null;
+  const cgDate = isoToCoinGeckoDate(iso);
+  const url = `https://api.coingecko.com/api/v3/coins/mina-protocol/history?date=${cgDate}&localization=false`;
+  try {
+    const r = await throttled(() => fetch(url));
+    if (!r.ok) {
+      missingDates.add(iso);
+      return null;
+    }
+    const d = await r.json() as { market_data?: { current_price?: { eur?: number; usd?: number; gbp?: number } } };
+    const px = d?.market_data?.current_price;
+    const eur = px?.eur;
+    const usd = px?.usd;
+    const gbp = px?.gbp;
+    const eurOk = typeof eur === 'number' && Number.isFinite(eur) && eur > 0;
+    const usdOk = typeof usd === 'number' && Number.isFinite(usd) && usd > 0;
+    const gbpOk = typeof gbp === 'number' && Number.isFinite(gbp) && gbp > 0;
+    if (!eurOk || !usdOk || !gbpOk) {
+      missingDates.add(iso);
+      return null;
+    }
+    const rate: HistoricalRate = { eur: eur!, usd: usd!, gbp: gbp! };
+    await withWriteLock(async () => {
+      const cc = await loadCache();
+      cc[iso] = rate;
+      await persistCache();
+    });
+    return rate;
+  } catch {
+    missingDates.add(iso);
+    return null;
+  }
+}
+
+// Test-only: reset in-process state so unit tests can exercise fresh cache
+// misses without cross-contamination. Not exported through the SDK's public
+// entry points.
+export function _resetForTests(): void {
+  cache = null;
+  cacheLoaded = false;
+  missingDates.clear();
+  lastFetchAt = 0;
+  fetchChain = Promise.resolve();
+  writeChain = Promise.resolve();
+}

package/src/onChainRoot.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * onChainRoot.ts
+ *
+ * Non-custodial trust anchor for `verifyOffline`. Reads the live
+ * `licensesRoot` (`zkapp.appState[0]`) directly from Mina — no
+ * licensing-service round-trip, no trust assumption about whoever
+ * served the witness / license record.
+ *
+ * Pair it with `verifyOffline` to close the trust loop:
+ *
+ *   ```ts
+ *   import { fetchOnChainLicensesRoot } from 'zklicensing/on-chain-root';
+ *   import { verifyOffline }            from 'zklicensing/verify-offline';
+ *
+ *   // 1. Ask the licensing service for a witness + slot snapshot.
+ *   const snap = await fetch(`${service}/witness?licenseHash=${h}&zkAppAddress=${a}`).then(r => r.json());
+ *
+ *   // 2. Fetch the on-chain root INDEPENDENTLY, from Mina.
+ *   const onChainRoot = await fetchOnChainLicensesRoot({ zkAppAddress: a, network: 'devnet' });
+ *
+ *   // 3. Cross-check — if they disagree, the service is stale/wrong; bail.
+ *   if (snap.root !== onChainRoot) throw new Error('service root disagrees with chain');
+ *
+ *   // 4. Fold-verify the snapshot against the on-chain root.
+ *   const res = verifyOffline({ licensesRoot: onChainRoot, ...snap });
+ *   ```
+ *
+ * The read goes to the node's GraphQL API directly: no o1js is needed
+ * and o1js's global Mina instance is never touched, so it is safe in
+ * long-lived hosts that talk to several networks.
+ */
+
+// Default read-only public Mina GraphQL endpoints. Devnet points at
+// o1Labs' Mesa cluster (the current stable devnet node published at
+// devnet-plain-1.gcp.o1test.net); mainnet uses Minascan's public node.
+// Neither requires auth or a rate-limit key. Vendors who prefer their
+// own Mina node can override via `graphqlUrl` on the input.
+export const DEFAULT_MINA_GRAPHQL_URLS = {
+  mainnet: 'https://api.minascan.io/node/mainnet/v1/graphql',
+  devnet:  'https://devnet-plain-1.gcp.o1test.net/graphql',
+} as const;
+
+export type NetworkName = 'mainnet' | 'devnet';
+
+export type FetchOnChainLicensesRootInput = {
+  /** B62q… address of the deployed LicensingApp for this app. */
+  zkAppAddress: string;
+} & (
+  | { network: NetworkName; graphqlUrl?: string }
+  | { graphqlUrl: string; network?: NetworkName }
+);
+
+/**
+ * Read the live `licensesRoot` from the deployed LicensingApp's
+ * on-chain state. Returns the field value as a decimal string,
+ * matching the shape `verifyOffline` and the licensing service both
+ * consume.
+ *
+ * Throws on any of:
+ *   - `fetchAccount` returned an error (network down, wrong endpoint,
+ *     account doesn't exist on this chain);
+ *   - account exists but has no zkApp state (not a zkApp address, or
+ *     contract deployed but `initialize()` never ran).
+ */
+export async function fetchOnChainLicensesRoot(
+  input: FetchOnChainLicensesRootInput,
+): Promise<string> {
+  const { zkAppAddress } = input;
+  const network: NetworkName = input.network ?? 'devnet';
+  const graphqlUrl = input.graphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[network];
+
+  // Over the node's GraphQL API: no o1js, no global Mina instance.
+  const { readZkappAccount } = await import('./chainHead.js');
+  let account;
+  try {
+    account = await readZkappAccount({ address: zkAppAddress, graphqlUrl });
+  } catch (e: any) {
+    throw new Error(`fetchAccount(${zkAppAddress}) via ${graphqlUrl} failed: ${e?.message ?? e}`);
+  }
+  const root = account.found ? account.appState?.[0] : undefined;
+  if (!root) {
+    throw new Error(
+      `zkApp ${zkAppAddress} has no appState — is the LicensingApp deployed and initialized on ${network}?`,
+    );
+  }
+  return root;
+}

package/src/ownershipLicenseHash.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * ownershipLicenseHash.ts
+ *
+ * Field-side binding between the buyer's Pallas Schnorr pubkey and the
+ * `licenseHash` Field stored on-chain. The buy circuit and the buy client
+ * both compute this from the pubkey and assert equality — that mutual
+ * assertion is what proves knowledge of the passphrase without ever
+ * showing the passphrase to the network.
+ *
+ * A Pallas `PublicKey` is `(x: Field, isOdd: Bool)` — the two Fields that
+ * uniquely identify the compressed point. Poseidon-hashing them yields a
+ * single Field that matches the on-chain shape of every other `licenseHash`
+ * used by LicensingApp (which treats licenseHash as an opaque Field
+ * commitment, not a specific preimage).
+ */
+
+import { Poseidon, PublicKey } from 'o1js';
+
+/**
+ * Derive the Field-side `licenseHash` from a Pallas Schnorr pubkey. The
+ * hash is domain-free because the whole platform treats `licenseHash` as
+ * an opaque commitment — the on-chain contract never re-derives it from
+ * a preimage, so there's no cross-preimage collision surface to guard
+ * against here.
+ */
+export function licenseHashFromPubkey(publicKey: PublicKey): string {
+  return Poseidon.hash([publicKey.x, publicKey.isOdd.toField()]).toString();
+}