zklicensing 0.1.0-beta.2 → 0.1.0-beta.3

package/src/contractInterface.ts

@@ -0,0 +1,242 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * contractInterface.ts
+ *
+ * Public contract interface: event Structs, slot/grace constants, duration
+ * helpers, and a minimal `LicensingAppEventsContract` SmartContract subclass
+ * that has the events declaration but no @method bodies.
+ *
+ * The full `LicensingApp` (with provable method bodies) lives in the private
+ * zklicensing-app package; only the things needed to decode events and reason
+ * about durations are published here so a public verify service can replay
+ * the archive without pulling in the contract source.
+ *
+ * `CANONICAL_VK_HASH` and `CANONICAL_LICENSE_PROOF_VK_HASH` are the
+ * verification-key hashes of the two published circuits — `LicensingApp`
+ * (the on-chain zkApp) and `LicenseOwnershipProgram` (the ownership
+ * challenge/response `ZkProgram`), respectively. Both are hand-maintained
+ * constants — bump them whenever the corresponding circuit changes and
+ * rerun the keeper's boot assertion (see zklicensing-app/src/keeperService.ts)
+ * / the verify service's `ensureCompiled()` check to catch drift.
+ */
+
+import { declareState, fetchAccount, Field, PublicKey, SmartContract, Struct, UInt32, UInt64, MerkleMap } from 'o1js';
+
+// ------------------------------------------------------------
+// EVENT STRUCTS
+// ------------------------------------------------------------
+
+// Struct() returns a class whose type references o1js internals that fall
+// outside this package's rootDir (npm hoists o1js to the workspace root).
+// Annotating each export as `any` keeps tsc from inferring (and therefore
+// emitting) those internal type references. Consumers get full typing through
+// the hand-written contractInterface.d.ts shim.
+//
+// The clean alternative — `export class X extends Struct({...}) {}` as the
+// mina-fungible-token repo does — only works when o1js sits inside rootDir,
+// which a workspace member can't guarantee.
+
+export const LicenseIssuedEvent: any = Struct({
+  licenseHash: Field,
+  buyer:       PublicKey,
+  amount:      UInt64,
+  slot:        UInt32,
+  expirySlot:  UInt32,
+});
+export type LicenseIssuedEvent = any;
+
+export const ExpiryUpdateEvent: any = Struct({
+  licenseHash: Field,
+  newExpiry:   UInt32,
+});
+export type ExpiryUpdateEvent = any;
+
+export const PriceUpdatedEvent: any = Struct({
+  priceMonthly:  UInt64,
+  priceYearly:   UInt64,
+  priceFiveYear: UInt64,
+});
+export type PriceUpdatedEvent = any;
+
+export const AppCreatedEvent: any = Struct({
+  vendor: PublicKey,
+});
+export type AppCreatedEvent = any;
+
+// Emitted by `migrateLicense` when a license issued under an ancestor
+// deployment is re-minted into this deployment at zero payment. `licenseHash`
+// is stable across all deployments because the buyer's derived hash is what
+// identifies the license; `expirySlot` is copied verbatim from the ancestor's
+// licensesRoot entry; `ancestorGen` is the generation index the migration
+// resolved against (needed so archive replay and auditors can trace which
+// frozen root supplied the entry — skip-generation migrations are one-hop).
+export const LicenseMigratedEvent: any = Struct({
+  licenseHash: Field,
+  expirySlot:  UInt32,
+  ancestorGen: UInt32,
+});
+export type LicenseMigratedEvent = any;
+
+// ------------------------------------------------------------
+// CONSTANTS (slot math — 90 s/slot after Mesa upgrade)
+// ------------------------------------------------------------
+
+export const MONTHLY_SLOTS_N    = 28_800;     // 30 days × 24 × 40
+export const ONE_YEAR_SLOTS_N   = 350_640;    // 365.25 days × 24 × 40 (Julian year)
+export const FIVE_YEAR_SLOTS_N  = 1_753_200;  // 5 × ONE_YEAR_SLOTS_N
+export const REFUND_WINDOW_N    = 13_440;
+export const GRACE_PERIOD_N     = 6_720;
+export const MS_PER_SLOT_N      = 90_000;    // Mesa slot duration in ms
+export const SLOTS_PER_DAY_N    = 960;       // 86_400_000 / MS_PER_SLOT_N
+
+// Slot tolerance for the globalSlotSinceGenesis precondition. Applied uniformly to
+// every method that reads currentSlot. 40 slots × 90 s = 1 hour — sized to
+// clear the honest-user prove+wallet+mempool latency envelope. The refund vs
+// release windows stay disjoint by construction: requestRefund asserts against
+// the lower bound (currentSlot ≤ purchaseSlot + REFUND_WINDOW), releaseFunds
+// asserts against a threshold shifted by +TOLERANCE_WINDOW so neither can
+// land on the same real slot as the other. See AUDIT_BRIEF.md §7.
+export const TOLERANCE_WINDOW_N = 40;
+
+export const EMPTY: Field      = Field(0);
+export const EMPTY_ROOT: Field = new MerkleMap().getRoot();
+
+// ------------------------------------------------------------
+// DURATION HELPERS
+// ------------------------------------------------------------
+
+export const DURATION_LABELS = ['1 Month', '1 Year', '5 Years'] as const;
+export type DurationLabel = typeof DURATION_LABELS[number];
+
+export const DURATION_INDEX = { '1 Month': 0, '1 Year': 1, '5 Years': 2 } as const;
+
+export function durationSlotsFromLabel(label?: string | null): number | null {
+  if (label === '1 Month') return MONTHLY_SLOTS_N;
+  if (label === '1 Year')  return ONE_YEAR_SLOTS_N;
+  if (label === '5 Years') return FIVE_YEAR_SLOTS_N;
+  return null;
+}
+
+export function durationIndexFromLabel(label?: string | null): number | null {
+  if (label === '1 Month') return 0;
+  if (label === '1 Year')  return 1;
+  if (label === '5 Years') return 2;
+  return null;
+}
+
+export function durationLabelFromIndex(idx: number): DurationLabel | null {
+  return DURATION_LABELS[idx] ?? null;
+}
+
+// ------------------------------------------------------------
+// EVENTS-ONLY CONTRACT
+//
+// A SmartContract subclass with the same `events: { ... }` declaration as
+// LicensingApp but no `@method` bodies. Used by archive-replay code to call
+// `.fetchEvents()` without depending on the private circuit source.
+// ------------------------------------------------------------
+
+export class LicensingAppEventsContract extends SmartContract {
+  events: any = {
+    appCreated:             AppCreatedEvent,
+    licenseIssued:          LicenseIssuedEvent,
+    licenseIssuedNoEscrow:  LicenseIssuedEvent,
+    licenseRenewed:         ExpiryUpdateEvent,
+    licenseMigrated:        LicenseMigratedEvent,
+    refundIssued:           Field,
+    fundsReleased:          Field,
+    priceUpdated:           PriceUpdatedEvent,
+  };
+}
+
+// State-slot layout mirrors LicensingApp's declareState(). Read-only from here
+// — no @method bodies exist. Consumers use `.version.get()`, `.licensesRoot.get()`
+// etc. after fetchAccount(). `pricesPacked` is a single Field with the three
+// UInt64 tier prices packed as [pM | pY<<64 | pF<<128]; unpack with
+// `unpackPrices` if you need the individual tiers off-chain.
+declareState(LicensingAppEventsContract, {
+  licensesRoot:    Field,
+  vendor:          PublicKey,
+  escrowRoot:      Field,
+  pricesPacked:    Field,
+  version:         UInt32,
+  ancestorsRoot:   Field,
+} as any);
+
+// Off-chain mirror of the in-circuit price packing (see LicensingApp.ts). Kept
+// here so the events service can decode `pricesPacked` slots without pulling
+// the private contract source.
+export function unpackPrices(packed: Field): { priceMonthly: UInt64; priceYearly: UInt64; priceFiveYear: UInt64 } {
+  const raw = packed.toBigInt();
+  const mask = (1n << 64n) - 1n;
+  return {
+    priceMonthly:  UInt64.from(raw & mask),
+    priceYearly:   UInt64.from((raw >> 64n) & mask),
+    priceFiveYear: UInt64.from((raw >> 128n) & mask),
+  };
+}
+
+// ------------------------------------------------------------
+// SUPPORTED SOURCE VERSIONS
+//
+// On-chain `version` slot is set at init() and can never change (setPermissions
+// is impossible; setVerificationKey is impossibleDuringCurrentVersion). A
+// keeper / verifier that only understands v1 state decodes must refuse to serve
+// a zkApp deployed from a different source revision — otherwise it could
+// mis-decode events or feed a stale state format to the verifier.
+//
+// Add new versions here once the corresponding decoder / verifier code path
+// lands. Never remove: dropping a version is a support-removal decision that
+// belongs in a release note, not silent breakage.
+// ------------------------------------------------------------
+
+export const SUPPORTED_LICENSING_APP_VERSIONS: readonly number[] = [1];
+
+// Read the immutable `version` slot from a deployed LicensingApp. Returns null
+// when the account is not (yet) a zkApp — caller decides whether to retry
+// (deploy still pending) or reject (wrong address).
+export async function fetchLicensingAppVersion(zkAppAddress: string): Promise<number | null> {
+  const pub = PublicKey.fromBase58(zkAppAddress);
+  await fetchAccount({ publicKey: pub });
+  const contract: any = new LicensingAppEventsContract(pub);
+  try {
+    const v = contract.version.get();
+    return Number(v.toString());
+  } catch {
+    return null;
+  }
+}
+
+// ------------------------------------------------------------
+// CANONICAL VK HASHES
+//
+// Per-generation, append-only. The keeper boots with `LicensingApp.compile()`
+// and asserts the resulting VK hash matches `CANONICAL_VK_HASH` (the current
+// generation's row); the verify service resolves an address's generation via
+// AppRecord.deploymentHistory and asserts the on-chain VK hash matches
+// `CANONICAL_VK_HASHES[generation]`. Retired-generation licenses (e.g. a
+// 5-year buyer whose license lives on v1 after the platform bumped to v2/v3)
+// continue to verify because the historical row is still present. A genuine
+// old circuit deployed at a fresh address fails: the address is not in any
+// `deploymentHistory[]`, so the resolver returns null and verify rejects.
+//
+// Rules:
+//   - Append the new generation's row at each hardfork migration; never
+//     delete historical rows.
+//   - Bump `CURRENT_GENERATION` to the new key alongside the row.
+//   - `CANONICAL_VK_HASH` is derived from the record — drift test and keeper
+//     boot-assert are unchanged.
+// ------------------------------------------------------------
+
+export const CANONICAL_VK_HASHES: Readonly<Record<number, string>> = {
+  1: '25510637873522061606403949338800808972643356911784243535869508122414992770753',
+  // 2: '…' — append at each hardfork migration, never delete.
+};
+
+export const CURRENT_GENERATION: number = 1;
+
+export const CANONICAL_VK_HASH: string = CANONICAL_VK_HASHES[CURRENT_GENERATION];
+
+export const CANONICAL_LICENSE_PROOF_VK_HASH: string = '6592142093294558010952934797827640785154417146015648013584661926355710165692';

package/src/countryStats.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * countryStats.ts
+ *
+ * Buyer-country breakdown of a vendor's revenue, bucketed by UTC calendar year.
+ * Structured for tax reporting: one row per (year, appId, countryCode) with
+ * license count + the vendor's cut in MINA. Both the keeper (source of
+ * truth for /stats) and the dashboard UI import from here so the numbers can
+ * never drift between them.
+ *
+ * Purchases attribute to the year the buyer confirmed on-chain (LicenseRecord
+ * `createdAt` ISO timestamp). Legacy records that predate `createdAt` fall
+ * back to slot-derived time. Renewals attribute to the renewal year via
+ * `renewals[i].slot → time`. Refunded purchases contribute zero revenue but
+ * still count the license (a purchase happened even if the money was
+ * returned) — remove `count` from refunded rows client-side if you want a
+ * strictly net view.
+ *
+ * Browser-safe: pure computation, no fs, no fetch.
+ */
+
+import type { LicenseRecord } from './licenseRecord.js';
+import { zipToState } from './zipToState.js';
+
+export { zipToState } from './zipToState.js';
+
+// LicensingApp charges a 2 % platform fee (200 basis points); the vendor
+// receives the remaining 9 800 bps. Keep this in sync with the on-chain
+// constant in LicensingApp.
+const PLATFORM_FEE_BASIS_POINTS = 200n;
+const VENDOR_BPS = 10_000n - PLATFORM_FEE_BASIS_POINTS;
+
+// 90 s/slot post-Mesa. Used only for slot→time fallback attribution.
+const SLOT_DURATION_MS = 90_000;
+
+export type CountryBucket = {
+  count: number;         // licenses purchased by buyers from this country (renewals don't bump)
+  revenueMina: number;   // vendor cut in MINA — purchase + renewals combined
+  // State sub-buckets — populated only for US buyers, derived from
+  // `buyerZip` via zipToState. States are the jurisdictional unit that US
+  // sales-tax filings care about; the raw ZIP stays on the LicenseRecord
+  // for audit trail but isn't rolled up here. Missing entirely on non-US
+  // rows; may be missing on US rows for legacy records that predate ZIP
+  // capture or whose ZIP prefix doesn't resolve to a state.
+  states?: Record<string, { count: number; revenueMina: number }>;
+};
+export type CountryYearBreakdown = {
+  aggregate: Record<string, CountryBucket>;                       // keyed by ISO-alpha-2 (or '??' when missing)
+  byApp:     Record<string, Record<string, CountryBucket>>;       // appId → country → bucket
+};
+export type CountryBreakdown = {
+  years:  number[];                              // UTC calendar years with activity, most-recent first
+  byYear: Record<number, CountryYearBreakdown>;
+};
+
+// tzOffsetMinutes: signed minutes east of UTC (e.g. +60 for CET, -480 for PST).
+// Purchase/renewal timestamps are shifted by this offset before extracting the
+// calendar year, so the "tax year" cut-over aligns with the operator's local
+// clock instead of hardcoded UTC. Defaults to 0 (UTC) for callers who don't
+// pass it — preserves the pre-tz behavior.
+export function computeCountryBreakdown(
+  apps: { appId: string; zkAppAddress: string }[],
+  records: LicenseRecord[],
+  currentSlot: number,
+  nowMs: number,
+  tzOffsetMinutes: number = 0,
+): CountryBreakdown {
+  const appByAddress = new Map(apps.map(a => [a.zkAppAddress, a.appId] as const));
+  const byYear: Record<number, CountryYearBreakdown> = {};
+  const yearSet = new Set<number>();
+  const tzShiftMs = tzOffsetMinutes * 60_000;
+
+  const ensureYear = (year: number): CountryYearBreakdown => {
+    let yb = byYear[year];
+    if (!yb) {
+      yb = { aggregate: {}, byApp: {} };
+      byYear[year] = yb;
+      yearSet.add(year);
+    }
+    return yb;
+  };
+  const ensureAppBucket = (yb: CountryYearBreakdown, appId: string): Record<string, CountryBucket> => {
+    let ab = yb.byApp[appId];
+    if (!ab) {
+      ab = {};
+      yb.byApp[appId] = ab;
+    }
+    return ab;
+  };
+  const add = (
+    bucket: Record<string, CountryBucket>,
+    code: string,
+    count: number,
+    revenueNano: bigint,
+    state?: string,
+  ): void => {
+    let b = bucket[code];
+    if (!b) {
+      b = { count: 0, revenueMina: 0 };
+      bucket[code] = b;
+    }
+    b.count += count;
+    b.revenueMina += Number(revenueNano) / 1e9;
+    // State sub-bucket only for US rows whose ZIP resolved to a state.
+    // Non-US or unresolvable rows just add to the country total.
+    if (code === 'US' && state) {
+      const states = b.states ?? (b.states = {});
+      let sb = states[state];
+      if (!sb) {
+        sb = { count: 0, revenueMina: 0 };
+        states[state] = sb;
+      }
+      sb.count += count;
+      sb.revenueMina += Number(revenueNano) / 1e9;
+    }
+  };
+  const slotToYear = (slot: number): number | null => {
+    if (currentSlot <= 0) return null;
+    const ms = nowMs - (currentSlot - slot) * SLOT_DURATION_MS;
+    const y = new Date(ms + tzShiftMs).getUTCFullYear();
+    return Number.isFinite(y) ? y : null;
+  };
+
+  for (const r of records) {
+    const appId = appByAddress.get(r.zkAppAddress);
+    if (!appId) continue;
+    const country = r.buyerCountry && /^[A-Z]{2}$/.test(r.buyerCountry) ? r.buyerCountry : '??';
+    // Only US rows carry a meaningful ZIP for sales-tax purposes; derive
+    // the state jurisdiction here and let `add` roll it up. Non-US ZIPs
+    // and unresolvable prefixes fall through to country-total only.
+    const state = country === 'US' && r.buyerZip ? zipToState(r.buyerZip) : undefined;
+
+    // Purchase — attribute to the year of confirm-on-chain (createdAt).
+    // Fallback: slot-derived time for legacy records that lack createdAt.
+    let purchaseYear: number | null = null;
+    if (r.createdAt) {
+      const y = new Date(new Date(r.createdAt).getTime() + tzShiftMs).getUTCFullYear();
+      if (Number.isFinite(y)) purchaseYear = y;
+    }
+    if (purchaseYear === null && r.purchaseSlot > 0) {
+      purchaseYear = slotToYear(r.purchaseSlot);
+    }
+    if (purchaseYear !== null) {
+      const yb = ensureYear(purchaseYear);
+      const ab = ensureAppBucket(yb, appId);
+      const purchaseCut = (!r.refunded && r.purchaseAmount && r.purchaseAmount !== '0')
+        ? (BigInt(r.purchaseAmount) * VENDOR_BPS) / 10_000n
+        : 0n;
+      add(ab, country, 1, purchaseCut, state);
+      add(yb.aggregate, country, 1, purchaseCut, state);
+    }
+
+    // Renewals — revenue only (no license count), attributed to renewal year.
+    for (const rn of r.renewals ?? []) {
+      const y = slotToYear(rn.slot);
+      if (y === null) continue;
+      const yb = ensureYear(y);
+      const ab = ensureAppBucket(yb, appId);
+      const cut = (BigInt(rn.amount) * VENDOR_BPS) / 10_000n;
+      add(ab, country, 0, cut, state);
+      add(yb.aggregate, country, 0, cut, state);
+    }
+  }
+
+  return {
+    years: Array.from(yearSet).sort((a, b) => b - a),
+    byYear,
+  };
+}