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

package/src/licenseLeaf.ts

@@ -0,0 +1,221 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseLeaf.ts
+ *
+ * On-chain leaf value stored at every occupied `licensesRoot` slot. Bundles
+ * the license expiry with the device-binding state (cap, slot commitments,
+ * fill counter) so a single tree lookup returns everything a verifier or a
+ * `/prove/bind` call needs.
+ *
+ * Wire shape (in order of hash preimage):
+ *   licenseHash          Field       the tree key, also carried in the leaf
+ *                                    so a stolen witness can't be re-pointed
+ *                                    at another entry. Doubles as the owner-
+ *                                    pubkey commitment — buyLicense asserts
+ *                                    licenseHash == Poseidon(pk.x, pk.isOdd)
+ *                                    so bind/unbind's ownership check reads
+ *                                    the same field as the tree key. Storing
+ *                                    them separately would be pure redundancy.
+ *   expirySlot           UInt32→Field UInt32 packed into a Field
+ *   cap                  UInt32→Field 0 disables /prove/bind; ≤DEVICE_SLOT_CAP
+ *                                    (kept as UInt32 in-circuit because o1js's
+ *                                    provable types don't include UInt8)
+ *   deviceSlotsRoot      Field       Poseidon fold over the 10 slot fields
+ *                                    below (2 fields × DEVICE_SLOT_CAP)
+ *   deviceSlotsFilled    UInt32→Field how many of the DEVICE_SLOT_CAP slots
+ *                                    are currently non-empty — carried
+ *                                    alongside the fold so `bind()` can do
+ *                                    a cheap "cap - filled > 0" check
+ *                                    without re-summing the array
+ *
+ * DEVICE_SLOT_CAP is fixed at 5 so the slot arrays have a size known to the
+ * circuit at compile time. `cap` in the leaf may be smaller — it's a
+ * per-license limit; slots [cap..DEVICE_SLOT_CAP) must always stay empty
+ * (Field(0)) and `bind()` rejects any write to them. `cap = 0` disables
+ * binding entirely; `bind()` rejects immediately without ever touching a
+ * slot.
+ *
+ * Slot encoding (fields carried in the fold, per slot i):
+ *   occupied[i]  Field   0 (empty) or Poseidon(devicePubKeyHash)
+ *   freedAt[i]   Field   packed (boundAtSlot << 32) | freedAtSlot; both
+ *                        are UInt32-range Mina slot numbers. On a fresh
+ *                        empty slot both halves are 0. On bind, boundAt
+ *                        gets the current slot and freedAt stays 0. On
+ *                        unbind, freedAt gets the current slot (boundAt
+ *                        is preserved for audit / cooldown math).
+ *
+ * The struct + helpers live in the SDK (not the circuit package) so both
+ * the on-chain `@method` bodies AND the off-chain backend / verifier /
+ * dashboards can share a single source of truth for the leaf hash. The
+ * circuit re-exports them from `LicensingApp.ts` so existing consumers
+ * that import from there keep working.
+ */
+
+import { Field, Poseidon, Provable, PublicKey, Struct, UInt32 } from 'o1js';
+import type { LicenseRecord } from './licenseRecord.js';
+
+// Fixed slot-array width. Per the device-binding-noncustodial plan: 5 is
+// the sweet spot between "enough seats for a normal user" and "witnesses
+// stay small." Changing this is a hardfork migration (would flip every
+// leaf hash) — not a runtime tunable.
+export const DEVICE_SLOT_CAP_N = 5;
+export const DEVICE_SLOT_CAP = UInt32.from(DEVICE_SLOT_CAP_N);
+
+// Poseidon-fold of DEVICE_SLOT_CAP × 2 = 10 zero Fields, used as the
+// initial deviceSlotsRoot on every freshly-minted leaf. Precomputed once
+// at module load so `freshLeaf()` doesn't reconstruct it per-call.
+export const EMPTY_DEVICE_SLOTS_ROOT: Field = Poseidon.hash(
+  Array.from({ length: DEVICE_SLOT_CAP_N * 2 }, () => Field(0)),
+);
+
+// Poseidon-bound identity of the passphrase-derived ownership pubkey.
+// The full PublicKey is (x: Field, isOdd: Bool); Poseidon(x, isOdd.toField())
+// gives a single Field commitment. The buy circuit asserts this equals
+// `licenseHash`, so the leaf carries no separate owner-pubkey field —
+// `licenseHash` IS the on-chain owner-pubkey commitment.
+export function ownerPubKeyHash(pub: PublicKey): Field {
+  return Poseidon.hash([pub.x, pub.isOdd.toField()]);
+}
+
+// Pack (boundAtSlot, freedAtSlot) into a single Field. Both are Mina
+// slot numbers (UInt32-range, ≤ 2^32-1), so the concatenation fits in 64
+// bits. Layout mirrors packPrices in LicensingApp.ts — low bits first so
+// the more frequently-read half (freedAt, checked by every bind cooldown)
+// unpacks with a single mask.
+const SHIFT_32 = Field(1n << 32n);
+
+export function packSlotTimes(boundAtSlot: UInt32, freedAtSlot: UInt32): Field {
+  return freedAtSlot.value.add(boundAtSlot.value.mul(SHIFT_32));
+}
+
+export function unpackSlotTimes(packed: Field): { boundAtSlot: UInt32; freedAtSlot: UInt32 } {
+  // toBits(64) enforces the high 190 bits are zero — belt-and-suspenders
+  // since we only ever write via packSlotTimes, but keeps the circuit
+  // sound against an adversarially-crafted slot in a future upgrade.
+  const bits = packed.toBits(64);
+  const freedAtSlot = UInt32.Unsafe.fromField(Field.fromBits(bits.slice(0,  32)));
+  const boundAtSlot = UInt32.Unsafe.fromField(Field.fromBits(bits.slice(32, 64)));
+  return { boundAtSlot, freedAtSlot };
+}
+
+// Fold the parallel slot arrays into `deviceSlotsRoot`. Same order every
+// time — occupied[0], freedAt[0], occupied[1], freedAt[1], ... — so a
+// buyer that reconstructs the fold off-chain (verifier, dashboard) gets
+// the same commitment the circuit computed.
+export function computeDeviceSlotsRoot(
+  occupied: Field[],
+  freedAt:  Field[],
+): Field {
+  if (occupied.length !== DEVICE_SLOT_CAP_N || freedAt.length !== DEVICE_SLOT_CAP_N) {
+    throw new Error(
+      `computeDeviceSlotsRoot expects exactly ${DEVICE_SLOT_CAP_N} entries in each array ` +
+      `(got occupied=${occupied.length}, freedAt=${freedAt.length})`,
+    );
+  }
+  const fields: Field[] = [];
+  for (let i = 0; i < DEVICE_SLOT_CAP_N; i++) {
+    fields.push(occupied[i], freedAt[i]);
+  }
+  return Poseidon.hash(fields);
+}
+
+// Per-slot payload. The Struct wrapper is what lets o1js serialize this
+// inside larger provable structures — it also gives us a fixed
+// two-Field width so DeviceSlots.slots can be a `Provable.Array` of a
+// well-known type instead of a bag of loose Fields.
+//
+// Same `const X: any = Struct(...)` pattern as contractInterface.ts —
+// annotating as `any` sidesteps TS2742 (o1js sits outside the package
+// rootDir under npm hoisting, so tsc can't emit portable declarations
+// for the inferred Struct class). Instance methods and `static empty()`
+// therefore live as standalone helpers below rather than on the class.
+export const DeviceSlot: any = Struct({
+  occupied: Field,   // 0 or Poseidon(devicePubKeyHash)
+  freedAt:  Field,   // packSlotTimes(boundAtSlot, freedAtSlot)
+});
+export type DeviceSlot = any;
+
+export function emptyDeviceSlot(): DeviceSlot {
+  return new DeviceSlot({ occupied: Field(0), freedAt: Field(0) });
+}
+
+// Fixed-width slot array. `Provable.Array(DeviceSlot, N)` promises the
+// circuit an exact length so witnesses can address slots by static index.
+export const DeviceSlots: any = Struct({
+  slots: Provable.Array(DeviceSlot, DEVICE_SLOT_CAP_N),
+});
+export type DeviceSlots = any;
+
+export function emptyDeviceSlots(): DeviceSlots {
+  return new DeviceSlots({
+    slots: Array.from({ length: DEVICE_SLOT_CAP_N }, () => emptyDeviceSlot()),
+  });
+}
+
+// In-circuit fold — takes a DeviceSlots value so it composes cleanly
+// inside `@method` bodies. The array length is fixed by the Struct's
+// Provable.Array declaration, so no runtime length guard is needed.
+export function deviceSlotsHash(ds: DeviceSlots): Field {
+  const fields: Field[] = [];
+  for (const s of ds.slots) {
+    fields.push(s.occupied, s.freedAt);
+  }
+  return Poseidon.hash(fields);
+}
+
+// The leaf value itself. `LicensingApp.buyLicense` builds one of these
+// with EMPTY_DEVICE_SLOTS_ROOT and writes leafHash(leaf) into licensesRoot;
+// subsequent mutations (renew, refund, migrate, bind, unbind) each build
+// a new leaf with the appropriate field(s) updated and write its hash.
+export const LicenseLeaf: any = Struct({
+  licenseHash:       Field,
+  expirySlot:        UInt32,
+  cap:               UInt32,
+  deviceSlotsRoot:   Field,
+  deviceSlotsFilled: UInt32,
+});
+export type LicenseLeaf = any;
+
+export function leafHash(leaf: LicenseLeaf): Field {
+  return Poseidon.hash([
+    leaf.licenseHash,
+    leaf.expirySlot.value,
+    leaf.cap.value,
+    leaf.deviceSlotsRoot,
+    leaf.deviceSlotsFilled.value,
+  ]);
+}
+
+// Construct the leaf a fresh buy writes into the tree — no devices bound
+// yet, filled counter at zero, slot-fold at the precomputed empty root.
+export function freshLeaf(
+  licenseHash: Field,
+  expirySlot:  UInt32,
+  cap:         UInt32,
+): LicenseLeaf {
+  return new LicenseLeaf({
+    licenseHash,
+    expirySlot,
+    cap,
+    deviceSlotsRoot:   EMPTY_DEVICE_SLOTS_ROOT,
+    deviceSlotsFilled: UInt32.zero,
+  });
+}
+
+// Reconstruct the leaf that lives at `record.licenseHash` in the licensesRoot
+// MerkleMap. `LicenseRecord` optionally persists the device-binding fields;
+// anything missing falls back to the fresh-leaf defaults, matching the state
+// a just-issued license was minted with.
+export function leafFromRecord(record: LicenseRecord): LicenseLeaf {
+  return new LicenseLeaf({
+    licenseHash:       Field(record.licenseHash),
+    expirySlot:        UInt32.from(record.expirySlot),
+    cap:               UInt32.from(record.deviceCap ?? 0),
+    deviceSlotsRoot:   record.deviceSlotsRoot !== undefined
+      ? Field(record.deviceSlotsRoot)
+      : EMPTY_DEVICE_SLOTS_ROOT,
+    deviceSlotsFilled: UInt32.from(record.deviceSlotsFilled ?? 0),
+  });
+}

package/src/licenseRecord.ts

@@ -0,0 +1,190 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseRecord.ts
+ *
+ * The `LicenseRecord` shape and related pure types/constants. Split out from
+ * licenseStore.ts (which pulls in Node `fs`) so browser-side modules — the
+ * buy client, the stats client, the country-stats computation — can consume
+ * the same type without dragging in filesystem code. licenseStore.ts
+ * re-exports these to keep existing Node imports working.
+ */
+
+// MINA→fiat rate snapshot captured at the moment a business event happens
+// (registration, purchase, renewal). Immutable — the value at time of event
+// is what tax authorities want, so the backend snapshots against the same
+// 5-minute CoinGecko cache used by receipts and never re-fetches. Records
+// created before the very first successful CoinGecko response get no
+// snapshot; dashboards render fiat as `—` for those.
+export type FiatRateSnapshot = {
+  minaEurRate:   number;
+  minaUsdRate:   number;
+  minaGbpRate:   number;
+  recordedAt:    string;
+};
+
+export type LicenseRecord = {
+  /** Carried over from this earlier deployment when the app was redeployed (its successor starts with the same licenses): license state only, the sale stays on the earlier record. */
+  carriedOverFrom?: string;
+  /**
+   * Moved to another owner key (transferLicense): this record keeps the sale,
+   * and the license itself is the record under `transferredTo` (which names
+   * its origin in `transferredFrom`, with no sale of its own).
+   */
+  transferredTo?: string;
+  transferredFrom?: string;
+  zkAppAddress:   string;  // REQUIRED — composite key with licenseHash
+  licenseHash:    string;  // Poseidon([pk.x, pk.isOdd.toField()]) over the buyer's passphrase-derived Pallas Schnorr pubkey — see ownershipLicenseHash.ts
+  expirySlot:     number;  // 0 = refunded / empty
+  purchaseSlot:   number;  // block slot when purchased (0 after escrow released/refunded)
+  purchaseAmount: string;  // nanomina paid (as string to avoid BigInt serialisation issues)
+  txHash:         string;
+  createdAt:      string;
+  // The three fields below reconstruct the on-chain LicenseLeaf so the backend
+  // can rebuild licensesRoot and produce witnesses for renew/refund/bind.
+  // (The leaf's owner-pubkey commitment lives in `licenseHash` itself —
+  // buyLicense asserts licenseHash == Poseidon(pk.x, pk.isOdd) — so there is
+  // no separate ownerPubKeyHash field.)
+  deviceCap?:       number;  // per-license device cap (0 = binding disabled)
+  deviceSlotsRoot?: string;  // Poseidon fold over the fixed-width slot array
+  deviceSlotsFilled?: number;  // count of currently-occupied slots
+  // Populated by eventSyncLoop from DeviceBound/DeviceUnbound events — array
+  // position IS slotIndex, absent entries or entries with `deviceCommitment === '0'`
+  // are empty. Source of truth is on-chain; this mirror is for the API surface.
+  devices?: Array<{
+    slotIndex:        number;
+    deviceCommitment: string;  // "0" = empty slot; otherwise Poseidon(devicePubKeyHash)
+    boundAtSlot:      number;  // 0 for empty
+    freedAtSlot:      number;  // 0 for pristine; the slot when last unbind fired
+  }>;
+  buyerAddress:   string;  // buyer's public key (B62q...) — the payer of the buy tx. Required so buyers can enumerate their licenses across origins via GET /licenses?buyer=<addr>, and to reconstruct the escrow commitment for auto-release. Legacy records lacking this field will simply not enumerate — no backfill.
+  // buyerCountry / buyerZip are NOT persisted to licenses.json by the backend —
+  // they live in the backend's append-only buyer-attribution.log and get
+  // joined into records at read time via enrichRecordsWithAttribution().
+  // Kept optional on the type so backend endpoints that echo enriched records
+  // (e.g. /stats, /transactions) can still expose them; browser-side records
+  // materialized purely from disk (no backend enrichment step) will never
+  // carry them.
+  buyerCountry?:  string;  // ISO 3166-1 alpha-2 self-declared buyer jurisdiction
+  buyerZip?:      string;  // US-only postal code (state-level sales-tax attribution)
+  // VAT evidence, joined in the same way: the country of the buyer's IP
+  // address at purchase (null: unknown or private address) and the
+  // geolocation database version. The address itself is never kept.
+  buyerIpCountry?: string | null;
+  geoDb?:         string;
+  pending?:       boolean; // true if staged at prove-time but not yet confirmed by chain events
+  provedAtSlot?:  number;  // slot at which prove succeeded — used by reaper to drop unsubmitted records
+  // The record as it was before this pending change (a renewal or refund
+  // staged over it), restored if the transaction fails on chain or never
+  // lands. Absent on a pending purchase: the record is removed instead.
+  pendingPrior?:  LicenseRecord;
+  // Captured at licenseIssued and never mutated by renewal. Lets stats decide
+  // who's past their first paid period without re-walking events.
+  initialExpirySlot?: number;
+  // Back-derived from (initialExpirySlot - purchaseSlot) at issue time. Lets
+  // licensesByTier roll up active counts without keeping the issued slot.
+  tier?: 'monthly' | 'yearly' | 'fiveYear' | 'perpetual';
+  // True after a licenseRenewed event has been observed. Lets the stats
+  // accumulator detect the FIRST renewal per license without re-counting.
+  renewedAtLeastOnce?: boolean;
+  // Refund state.
+  //   undefined | false → not refunded
+  //   'fast'            → the tx-land watcher observed a refund tx in bestchain
+  //                       but the archive event-sync hasn't confirmed it yet.
+  //                       Treated as refunded for filtering (truthy), but a
+  //                       reorg-revert reaper will roll it back to false if
+  //                       the event never appears in the archive within
+  //                       REORG_REVERT_AFTER_SLOTS.
+  //   true              → confirmed by a canonical refundIssued event in the
+  //                       archive (or written directly by the pre-provisional
+  //                       code path).
+  refunded?: boolean | 'fast';
+  // Release state. Same two-tier semantics as `refunded` above — see
+  // recordRelease / revertProvisionalFlip in licenseStore.ts.
+  released?: boolean | 'fast';
+  releaseSlot?: number;
+  // Tx hash of the fundsReleased broadcast. Persisted so the vendor's
+  // transaction feed can link the release row to the explorer. Optional for
+  // backward-compat: pre-tracking records and archive-replayed events
+  // (which don't carry the tx hash) simply omit it.
+  releaseTxHash?: string;
+  // Each renewal pushes { slot, amount, newExpiry, txHash?, fiatSnapshot? }
+  // where amount is the nanomina paid. newExpiry is the resulting expiry —
+  // used as a dedup key so confirm-time entries don't double up when archive
+  // sync later replays the same renewedEvent. fiatSnapshot captures the
+  // MINA→fiat rates at renewal confirm time (missing on archive-replayed
+  // renewals, which have no live backend context).
+  renewals?: Array<{ slot: number; amount: string; newExpiry: number; txHash?: string; fiatSnapshot?: FiatRateSnapshot; waiverGivenBy?: AgentWaiverRecord; ipCountry?: string | null; geoDb?: string }>;
+  // MINA→fiat rates captured at buy confirm time. Immutable — the rate at
+  // time of purchase is what tax authorities want. Missing on records created
+  // before the first successful CoinGecko response and on archive-replayed
+  // purchases (dashboards render fiat as `—`).
+  fiatSnapshot?: FiatRateSnapshot;
+  // ISO timestamp of the buyer's express waiver of the 14-day refund window,
+  // captured at buy time when a FREEZE_AFTER_SLOT was scheduled on the
+  // backend. Absent for normal (non-freeze-window) buys. Kept for audit /
+  // dispute purposes — the waiver is the buyer's acknowledgment that the
+  // scheduled hardfork can truncate their refund window.
+  refundWaiverAcceptedAt?: string;
+  // True when the buy was minted through the no-escrow circuit method
+  // (buyLicenseNoEscrow). Funds went straight to vendor + platform (98/2)
+  // rather than into the contract's escrow tree, so there is nothing to
+  // refund. The buyer accepted this at purchase (see refundWaiverAcceptedAt).
+  // The UI uses this flag to hide the "Refund" CTA on the licenses page.
+  escrowless?: boolean;
+  // Set when the platform force-retired the app (Vendor Terms §8.7) while
+  // this purchase was still in escrow: its funds stay on the retired
+  // contract, which settles nothing any more, so no refund or release can
+  // follow. The license itself carried over to the successor.
+  escrowStranded?: { txHash: string; at: string };
+  // Set when the buyer's withdrawal waiver was given by an AI agent under a
+  // standing consent the buyer signed (Terms §7.8), so the vendor can see it.
+  waiverGivenBy?: AgentWaiverRecord;
+  // Slot at which released|refunded was set to 'fast' by the tx-land watcher.
+  // The reorg-revert reaper compares against currentSlot to decide when to
+  // give up waiting for archive confirmation and roll a 'fast' flip back to
+  // false. Absent when neither field is provisional.
+  provisionalFlipAtSlot?: number;
+};
+
+// Reap pending records this many slots after prove time if no event ever lands.
+// 60 slots ≈ 90 minutes — a generous window for tx inclusion under devnet conditions.
+export const PENDING_REAP_SLOTS = 60;
+
+export type LicenseStatus = 'active' | 'refunded' | 'expired' | 'transferred' | 'unknown';
+
+/** A withdrawal waiver an agent gave under the buyer's standing consent. */
+export type AgentWaiverRecord = {
+  agent: string;
+  owner: string;
+  /** SHA-256 of the signed statement; the full consent is in the keeper's consent log. */
+  statementSha256: string;
+  issuedAt: string;
+};
+
+/**
+ * The file name of the license receipt a buyer downloads: `license-<appId>.json`,
+ * so an app looks for its own file and a buyer's receipts for different apps
+ * don't collide. Falls back to the zkApp address when there is no app ID (a
+ * contract that isn't registered as an app).
+ */
+export function licenseFileName(appId: string | null | undefined, zkAppAddress?: string): string {
+  if (appId && /^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$/.test(appId)) return `license-${appId}.json`;
+  if (zkAppAddress && /^B62q[1-9A-HJ-NP-Za-km-z]{51}$/.test(zkAppAddress)) return `license-${zkAppAddress}.json`;
+  return 'license.json';
+}
+
+/**
+ * The 98/2 split exactly as the licensing circuit pays it (LicensingApp:
+ * fee = amount.div(50), vendor = amount.sub(fee)); the two always add up to
+ * the amount. Use these for every off-chain figure, so dashboards, stats
+ * and tax exports match the on-chain payouts to the nanomina.
+ */
+export function platformFeeNano(amount: bigint): bigint {
+  return amount / 50n;
+}
+
+export function vendorShareNano(amount: bigint): bigint {
+  return amount - amount / 50n;
+}