zklicensing 0.1.0-beta.0

package/build/archiveBootstrap.js

@@ -0,0 +1,234 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * 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
+ *   licenseMigrated        → applyLicenseIssued (escrowless: true, migrated: true)
+ *   refundIssued           → recordRefund
+ *   fundsReleased          → recordRelease
+ *   priceUpdated           → ignored (price-history tracking lives in the private
+ *                             zklicensing-app keeper 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, UInt32 } from 'o1js';
+import { LicensingAppEventsContract, MONTHLY_SLOTS_N, ONE_YEAR_SLOTS_N, FIVE_YEAR_SLOTS_N, } from './contractInterface.js';
+import { applyLicenseIssued, updateExpiry, recordRefund, recordRelease, } from './licenseStore.js';
+export const SYNC_CHUNK_SLOTS = 10_000;
+export const MAX_LOOKBACK_SLOTS = 525_600;
+// Back-derive the duration tier from (expirySlot - purchaseSlot). Tolerance
+// of ±2 slots matches the SLOT_TOLERANCE used in the circuit.
+export function tierFromExpiryDelta(slots) {
+    const within = (target) => 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';
+    return null;
+}
+export async function bootstrapFromArchive(zkAppAddress, range = {}) {
+    const pubKey = PublicKey.fromBase58(zkAppAddress);
+    const zkApp = new LicensingAppEventsContract(pubKey);
+    const start = range.from !== undefined ? UInt32.from(range.from) : undefined;
+    const end = range.to !== undefined ? UInt32.from(range.to) : undefined;
+    const allEvents = await zkApp.fetchEvents(start, end);
+    const canonical = [...allEvents]
+        .filter(e => e.chainStatus === 'canonical')
+        .sort((a, b) => Number(a.globalSlot.toString()) - Number(b.globalSlot.toString()));
+    const events = [];
+    for (const ev of canonical) {
+        const slot = Number(ev.globalSlot.toString());
+        switch (ev.type) {
+            case 'priceUpdated': {
+                const data = ev.event.data;
+                events.push({
+                    kind: 'priceUpdated',
+                    slot,
+                    priceMonthly: BigInt(data.priceMonthly.toString()),
+                    priceYearly: BigInt(data.priceYearly.toString()),
+                    priceFiveYear: BigInt(data.priceFiveYear.toString()),
+                });
+                break;
+            }
+            case 'licenseIssued': {
+                const data = ev.event.data;
+                events.push({
+                    kind: 'licenseIssued',
+                    slot,
+                    licenseHash: data.licenseHash.toString(),
+                    amount: BigInt(data.amount.toString()),
+                    issuedSlot: Number(data.slot.toString()),
+                    expirySlot: Number(data.expirySlot.toString()),
+                });
+                break;
+            }
+            case 'licenseIssuedNoEscrow': {
+                const data = ev.event.data;
+                events.push({
+                    kind: 'licenseIssuedNoEscrow',
+                    slot,
+                    licenseHash: data.licenseHash.toString(),
+                    amount: BigInt(data.amount.toString()),
+                    issuedSlot: Number(data.slot.toString()),
+                    expirySlot: Number(data.expirySlot.toString()),
+                });
+                break;
+            }
+            case 'licenseRenewed': {
+                const data = ev.event.data;
+                events.push({
+                    kind: 'licenseRenewed',
+                    slot,
+                    licenseHash: data.licenseHash.toString(),
+                    newExpiry: Number(data.newExpiry.toString()),
+                });
+                break;
+            }
+            case 'licenseMigrated': {
+                const data = ev.event.data;
+                events.push({
+                    kind: 'licenseMigrated',
+                    slot,
+                    licenseHash: data.licenseHash.toString(),
+                    expirySlot: Number(data.expirySlot.toString()),
+                    ancestorGen: Number(data.ancestorGen.toString()),
+                });
+                break;
+            }
+            case 'refundIssued':
+                events.push({ kind: 'refundIssued', slot, licenseHash: ev.event.data.toString() });
+                break;
+            case 'fundsReleased':
+                events.push({ kind: 'fundsReleased', slot, licenseHash: ev.event.data.toString() });
+                break;
+        }
+    }
+    const maxSeenSlot = canonical.length === 0
+        ? -1
+        : Number(canonical[canonical.length - 1].globalSlot.toString());
+    return { maxSeenSlot, events };
+}
+export async function applyEventsToStore(zkAppAddress, events) {
+    const warnings = [];
+    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(),
+                    ...(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,
+                    ...(tier ? { tier } : {}),
+                });
+                count++;
+                break;
+            }
+            case 'licenseRenewed': {
+                const ok = await updateExpiry(zkAppAddress, ev.licenseHash, ev.newExpiry, {
+                    markRenewed: true,
+                });
+                if (!ok)
+                    warnings.push(`renew for unknown license ${ev.licenseHash.slice(0, 16)}…`);
+                break;
+            }
+            case 'licenseMigrated': {
+                await applyLicenseIssued(zkAppAddress, ev.licenseHash, {
+                    expirySlot: ev.expirySlot,
+                    purchaseSlot: 0,
+                    purchaseAmount: '0',
+                    escrowless: true,
+                });
+                count++;
+                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;
+            }
+        }
+    }
+    return { count, warnings };
+}
+export async function discoverAppCreatedSlot(zkAppAddress, nowSlot, lookbackSlots = MAX_LOOKBACK_SLOTS) {
+    const pubKey = PublicKey.fromBase58(zkAppAddress);
+    const zkApp = new LicensingAppEventsContract(pubKey);
+    const floor = Math.max(1, nowSlot - lookbackSlots);
+    let to = nowSlot;
+    while (to >= floor) {
+        const from = Math.max(floor, to - SYNC_CHUNK_SLOTS + 1);
+        const events = await zkApp.fetchEvents(UInt32.from(from), UInt32.from(to));
+        const created = events
+            .filter(e => e.chainStatus === 'canonical' && e.type === 'appCreated')
+            .sort((a, b) => Number(a.globalSlot.toString()) - Number(b.globalSlot.toString()));
+        if (created.length > 0) {
+            return Number(created[0].globalSlot.toString());
+        }
+        if (from <= floor)
+            break;
+        to = from - 1;
+    }
+    return null;
+}
+const inFlightBootstraps = new Map();
+export async function lazyBootstrap(zkAppAddress) {
+    const existing = inFlightBootstraps.get(zkAppAddress);
+    if (existing)
+        return existing;
+    const short = zkAppAddress.slice(0, 12) + '…';
+    const p = (async () => {
+        try {
+            const { events } = await bootstrapFromArchive(zkAppAddress);
+            const { count, warnings } = await applyEventsToStore(zkAppAddress, events);
+            for (const w of warnings)
+                console.warn(`[lazy-bootstrap] ${short}: ${w}`);
+            if (count > 0) {
+                console.log(`[lazy-bootstrap] ${short}: replayed ${count} record(s)`);
+            }
+        }
+        catch (e) {
+            console.warn(`[lazy-bootstrap] ${short}: ${e?.message ?? e}`);
+        }
+        finally {
+            inFlightBootstraps.delete(zkAppAddress);
+        }
+    })();
+    inFlightBootstraps.set(zkAppAddress, p);
+    return p;
+}
+//# sourceMappingURL=archiveBootstrap.js.map

package/build/buyClient.d.ts

@@ -0,0 +1,58 @@
+export type BuyIdentity = {
+    secretHash: string;
+    licenseHash: string;
+};
+export declare function deriveBuyIdentity(passphrase: string): BuyIdentity;
+export type ProveBuyRequest = {
+    keeperUrl: string;
+    licenseHash: string;
+    buyerAddress: string;
+    zkAppAddress: string;
+    duration: 0 | 1 | 2;
+    buyerCountry: string;
+    refundWaiverAccepted?: boolean;
+    freezeAfterSlot?: number | null;
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+};
+export type ProveBuyResponse = {
+    provenTxJson: string;
+    expirySlot: number;
+    licenseHash: string;
+    verificationKeyHash: string;
+    purchaseSlot: number;
+    purchaseAmount: string;
+    duration: number;
+    durationLabel: string;
+    generation: number;
+};
+export type ConfirmBuyRequest = {
+    keeperUrl: string;
+    zkAppAddress: string;
+    licenseHash: string;
+    txHash: string;
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+};
+export type BuyStatus = {
+    status: 'unknown' | 'pending' | 'confirmed' | 'failed';
+    txHash?: string;
+    landedAtBlockHeight?: number;
+    landedAtSlot?: number;
+    elapsedMs?: number;
+};
+export declare function proveBuy(req: ProveBuyRequest): Promise<ProveBuyResponse>;
+export declare function confirmBuy(req: ConfirmBuyRequest): Promise<{
+    ok: true;
+}>;
+export type PollBuyStatusOptions = {
+    keeperUrl: string;
+    licenseHash: string;
+    fetcher?: typeof fetch;
+    intervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onTick?: (status: BuyStatus) => void;
+};
+export declare function pollBuyStatus(opts: PollBuyStatusOptions): Promise<BuyStatus>;
+//# sourceMappingURL=buyClient.d.ts.map

package/build/buyClient.js

@@ -0,0 +1,162 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * buyClient.ts
+ *
+ * Browser-safe client for the buy flow. Exposes the three keeper roundtrips
+ * (derive identity → prove → confirm) as small, individually testable
+ * functions plus a `pollBuyStatus` helper. Deliberately does NOT talk to a
+ * wallet — the caller drives the wallet step between `proveBuy` and
+ * `confirmBuy`, so the SDK stays wallet-agnostic and can be reused by CLI
+ * tools, alternate UIs, and third-party integrators.
+ *
+ * Peer dep: o1js (for Poseidon + Encoding). Consumers of ./buy must have
+ * o1js in their dependency graph.
+ */
+import { Encoding, Poseidon } from 'o1js';
+import { resolveFreezeState } from './freezeClient.js';
+import { REFUND_WINDOW_N, TOLERANCE_WINDOW_N } from './contractInterface.js';
+// Derive the two hashes the buy flow keys off. Deterministic in the
+// passphrase — same passphrase always maps to the same licenseHash on a
+// given zkApp, so a buyer's passphrase choice locks in their license
+// identity from day one. Only `licenseHash` is sent to the keeper (see
+// proveBuy); `secretHash` stays on the buyer's device and is used only by
+// the client-side LicenseOwnershipProgram challenge/response.
+export function deriveBuyIdentity(passphrase) {
+    const secretHash = Poseidon.hash(Encoding.stringToFields(passphrase));
+    const licenseHash = Poseidon.hash([secretHash]);
+    return { secretHash: secretHash.toString(), licenseHash: licenseHash.toString() };
+}
+function baseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+async function readJsonError(resp) {
+    try {
+        const body = await resp.json();
+        if (typeof body.error === 'string')
+            return body.error;
+    }
+    catch { /* body wasn't JSON */ }
+    return `HTTP ${resp.status}`;
+}
+// POST /prove/buy — keeper compiles + proves the buy tx.
+// The buyer's wallet then signs the returned provenTxJson.
+//
+// Pre-network guards:
+//   - salesFrozen === true → refuse immediately (keeper would 423 anyway).
+//   - freezeAfterSlot announced AND this buy's 14-day refund window would
+//     extend past the freeze slot AND refundWaiverAccepted !== true →
+//     refuse (buyer must explicitly accept that the scheduled hardfork
+//     can truncate their refund window). Buys whose full window ends
+//     before the freeze proceed without a waiver.
+//
+// Endpoint routing:
+//   - refundWaiverAccepted === true → POST /prove/buy-no-escrow. The no-escrow
+//     circuit method pays vendor+platform directly (98/2 split, no escrow
+//     tree write). This is chosen either voluntarily by the buyer (opting out
+//     of the 14-day statutory right of withdrawal in exchange for immediate
+//     delivery) or forced by a freeze overlap.
+//   - refundWaiverAccepted !== true → POST /prove/buy (standard escrow path
+//     with a 14-day refund window).
+export async function proveBuy(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const freeze = await resolveFreezeState({
+        keeperUrl: req.keeperUrl,
+        freezeAfterSlot: req.freezeAfterSlot,
+        fetcher,
+        signal: req.signal,
+    });
+    if (freeze.salesFrozen) {
+        throw new Error('Sales frozen — new buys refused ahead of scheduled hardfork migration');
+    }
+    let windowOverlapsFreeze = false;
+    if (freeze.freezeAfterSlot !== null) {
+        // Waiver required when the refund window would overlap the freeze, or
+        // when the current slot is unknown client-side (safe default). The
+        // +TOLERANCE_WINDOW_N margin accounts for slot-precondition slop
+        // between prove and inclusion: the real inclusion slot can be up to
+        // TOLERANCE_WINDOW_N slots past `currentSlot`, so we include that in
+        // the overlap comparison rather than let a late inclusion silently
+        // push the refund deadline past the freeze without a waiver.
+        windowOverlapsFreeze =
+            freeze.currentSlot === null ||
+                freeze.currentSlot + REFUND_WINDOW_N + TOLERANCE_WINDOW_N > freeze.freezeAfterSlot;
+        if (windowOverlapsFreeze && req.refundWaiverAccepted !== true) {
+            throw new Error(`refundWaiverAccepted must be true — the scheduled hardfork at slot ${freeze.freezeAfterSlot} can truncate the 14-day refund window`);
+        }
+    }
+    const useNoEscrow = req.refundWaiverAccepted === true;
+    const endpoint = useNoEscrow ? '/prove/buy-no-escrow' : '/prove/buy';
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}${endpoint}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal: req.signal,
+        body: JSON.stringify({
+            licenseHash: req.licenseHash,
+            buyerAddress: req.buyerAddress,
+            zkAppAddress: req.zkAppAddress,
+            duration: req.duration,
+            buyerCountry: req.buyerCountry,
+            ...(req.refundWaiverAccepted === true ? { refundWaiverAccepted: true } : {}),
+        }),
+    });
+    if (!resp.ok) {
+        // Distinct guidance for the no-escrow path: a 404 here means the
+        // vendor's zkApp was deployed before the no-escrow method existed. Fix
+        // is a redeploy through the hardfork-migration flow (§12.13); until
+        // then the escrowless (waiver) path is unavailable on this vendor.
+        if (useNoEscrow && resp.status === 404) {
+            throw new Error('Keeper does not offer /prove/buy-no-escrow — this vendor\'s zkApp does not support the escrowless (waiver) path; vendor must redeploy via the hardfork-migration flow');
+        }
+        throw new Error(await readJsonError(resp));
+    }
+    return await resp.json();
+}
+// POST /confirm/buy — promotes the in-memory intent staged by /prove/buy
+// into a persisted (pending: true) LicenseRecord. Call this only after the
+// wallet has actually returned a txHash — a cancelled or dropped signature
+// leaves the intent to expire on its own.
+export async function confirmBuy(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/buy`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal: req.signal,
+        body: JSON.stringify({
+            zkAppAddress: req.zkAppAddress,
+            licenseHash: req.licenseHash,
+            txHash: req.txHash,
+        }),
+    });
+    if (!resp.ok)
+        throw new Error(await readJsonError(resp));
+    return { ok: true };
+}
+// Polls GET /buy/status until it returns a terminal state ('confirmed' or
+// 'failed') or the timeout fires. Terminal state is resolved via the
+// returned status; 'unknown' just means the keeper hasn't seen the tx yet.
+export async function pollBuyStatus(opts) {
+    const fetcher = opts.fetcher ?? fetch;
+    const interval = opts.intervalMs ?? 3_000;
+    const timeout = opts.timeoutMs ?? 10 * 60 * 1000;
+    const deadline = Date.now() + timeout;
+    const url = `${baseUrl(opts.keeperUrl)}/buy/status?licenseHash=${encodeURIComponent(opts.licenseHash)}`;
+    while (true) {
+        if (opts.signal?.aborted)
+            throw new Error('pollBuyStatus aborted');
+        let status = { status: 'unknown' };
+        try {
+            const resp = await fetcher(url, { signal: opts.signal });
+            if (resp.ok)
+                status = await resp.json();
+        }
+        catch { /* transient network — try again on next tick */ }
+        opts.onTick?.(status);
+        if (status.status === 'confirmed' || status.status === 'failed')
+            return status;
+        if (Date.now() >= deadline)
+            return status;
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+//# sourceMappingURL=buyClient.js.map

package/build/contractInterface.d.ts

@@ -0,0 +1,55 @@
+// Hand-written declarations for contractInterface.ts.
+// tsc can't emit these automatically because the inferred return types of
+// Struct() and SmartContract reference internal o1js paths outside this
+// package's rootDir, triggering TS2742. Callers get full typing on the
+// methods they actually invoke by importing the corresponding o1js types
+// directly (Field, PublicKey, etc.) in their own code.
+
+import type { Field, UInt64 } from 'o1js';
+
+export const LicenseIssuedEvent: any;
+export type LicenseIssuedEvent = any;
+
+export const ExpiryUpdateEvent: any;
+export type ExpiryUpdateEvent = any;
+
+export const PriceUpdatedEvent: any;
+export type PriceUpdatedEvent = any;
+
+export const AppCreatedEvent: any;
+export type AppCreatedEvent = any;
+
+export const LicenseMigratedEvent: any;
+export type LicenseMigratedEvent = any;
+
+export function unpackPrices(packed: Field): { priceMonthly: UInt64; priceYearly: UInt64; priceFiveYear: UInt64 };
+
+export const MONTHLY_SLOTS_N: number;
+export const ONE_YEAR_SLOTS_N: number;
+export const FIVE_YEAR_SLOTS_N: number;
+export const REFUND_WINDOW_N: number;
+export const GRACE_PERIOD_N: number;
+export const MS_PER_SLOT_N: number;
+export const SLOTS_PER_DAY_N: number;
+export const TOLERANCE_WINDOW_N: number;
+
+export const EMPTY: Field;
+export const EMPTY_ROOT: Field;
+
+export const DURATION_LABELS: readonly ['1 Month', '1 Year', '5 Years'];
+export type DurationLabel = '1 Month' | '1 Year' | '5 Years';
+export const DURATION_INDEX: { readonly '1 Month': 0; readonly '1 Year': 1; readonly '5 Years': 2 };
+
+export function durationSlotsFromLabel(label?: string | null): number | null;
+export function durationIndexFromLabel(label?: string | null): number | null;
+export function durationLabelFromIndex(idx: number): DurationLabel | null;
+
+export const LicensingAppEventsContract: any;
+
+export const SUPPORTED_LICENSING_APP_VERSIONS: readonly number[];
+export function fetchLicensingAppVersion(zkAppAddress: string): Promise<number | null>;
+
+export const CANONICAL_VK_HASHES: Readonly<Record<number, string>>;
+export const CURRENT_GENERATION: number;
+export const CANONICAL_VK_HASH: string;
+export const CANONICAL_LICENSE_PROOF_VK_HASH: string;