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

package/build/countryStats.js

@@ -1,16 +1,43 @@
 // Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
+// 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 backend (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 { vendorShareNano } from './licenseRecord.js';
+import { standardVatRate, vatIncludedNano } from './vatRates.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 = 10000n - PLATFORM_FEE_BASIS_POINTS;
 // 90 s/slot post-Mesa. Used only for slot→time fallback attribution.
 const SLOT_DURATION_MS = 90_000;
-export function computeCountryBreakdown(apps, records, currentSlot, nowMs) {
+// 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, records, currentSlot, nowMs, tzOffsetMinutes = 0) {
     const appByAddress = new Map(apps.map(a => [a.zkAppAddress, a.appId]));
     const byYear = {};
     const yearSet = new Set();
+    const tzShiftMs = tzOffsetMinutes * 60_000;
     const ensureYear = (year) => {
         let yb = byYear[year];
         if (!yb) {
@@ -28,20 +55,51 @@ export function computeCountryBreakdown(apps, records, currentSlot, nowMs) {
         }
         return ab;
     };
-    const add = (bucket, code, count, revenueNano) => {
+    const add = (bucket, code, count, revenueNano, grossNano, saleMs, state) => {
         let b = bucket[code];
         if (!b) {
-            b = { count: 0, revenueMina: 0 };
+            b = { count: 0, revenueMina: 0, grossMina: 0 };
             bucket[code] = b;
         }
         b.count += count;
         b.revenueMina += Number(revenueNano) / 1e9;
+        b.grossMina += Number(grossNano) / 1e9;
+        // VAT included at the rate in force on the sale date.
+        const rate = code !== '??' && saleMs !== null ? standardVatRate(code, saleMs) : null;
+        if (rate !== null) {
+            b.estimatedVatMina = (b.estimatedVatMina ?? 0) + Number(vatIncludedNano(grossNano, rate).vatNano) / 1e9;
+            if (grossNano > 0n) {
+                const rates = (b.vatRates ??= []);
+                if (!rates.includes(rate)) {
+                    rates.push(rate);
+                    rates.sort((x, y) => x - y);
+                }
+            }
+        }
+        // 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, grossMina: 0 };
+                states[state] = sb;
+            }
+            sb.count += count;
+            sb.revenueMina += Number(revenueNano) / 1e9;
+            sb.grossMina += Number(grossNano) / 1e9;
+        }
     };
-    const slotToYear = (slot) => {
+    const slotToMs = (slot) => {
         if (currentSlot <= 0)
             return null;
         const ms = nowMs - (currentSlot - slot) * SLOT_DURATION_MS;
-        const y = new Date(ms).getUTCFullYear();
+        return Number.isFinite(ms) ? ms : null;
+    };
+    const msToYear = (ms) => {
+        if (ms === null)
+            return null;
+        const y = new Date(ms + tzShiftMs).getUTCFullYear();
         return Number.isFinite(y) ? y : null;
     };
     for (const r of records) {
@@ -49,36 +107,42 @@ export function computeCountryBreakdown(apps, records, currentSlot, nowMs) {
         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 = null;
+        let purchaseMs = null;
         if (r.createdAt) {
-            const y = new Date(r.createdAt).getUTCFullYear();
-            if (Number.isFinite(y))
-                purchaseYear = y;
+            const t = new Date(r.createdAt).getTime();
+            if (Number.isFinite(t))
+                purchaseMs = t;
         }
-        if (purchaseYear === null && r.purchaseSlot > 0) {
-            purchaseYear = slotToYear(r.purchaseSlot);
+        if (purchaseMs === null && r.purchaseSlot > 0) {
+            purchaseMs = slotToMs(r.purchaseSlot);
         }
+        const purchaseYear = msToYear(purchaseMs);
         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) / 10000n
-                : 0n;
-            add(ab, country, 1, purchaseCut);
-            add(yb.aggregate, country, 1, purchaseCut);
+            const purchaseGross = (!r.refunded && r.purchaseAmount && r.purchaseAmount !== '0') ? BigInt(r.purchaseAmount) : 0n;
+            const purchaseCut = purchaseGross > 0n ? vendorShareNano(purchaseGross) : 0n;
+            add(ab, country, 1, purchaseCut, purchaseGross, purchaseMs, state);
+            add(yb.aggregate, country, 1, purchaseCut, purchaseGross, purchaseMs, state);
         }
         // Renewals — revenue only (no license count), attributed to renewal year.
         for (const rn of r.renewals ?? []) {
-            const y = slotToYear(rn.slot);
+            const ms = slotToMs(rn.slot);
+            const y = msToYear(ms);
             if (y === null)
                 continue;
             const yb = ensureYear(y);
             const ab = ensureAppBucket(yb, appId);
-            const cut = (BigInt(rn.amount) * VENDOR_BPS) / 10000n;
-            add(ab, country, 0, cut);
-            add(yb.aggregate, country, 0, cut);
+            const gross = BigInt(rn.amount);
+            const cut = vendorShareNano(gross);
+            add(ab, country, 0, cut, gross, ms, state);
+            add(yb.aggregate, country, 0, cut, gross, ms, state);
         }
     }
     return {

package/build/countryStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"countryStats.js","sourceRoot":"","sources":["../src/countryStats.ts"],"names":[],"mappings":"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"}

package/build/deployClient.d.ts

@@ -2,14 +2,14 @@
  * deployClient.ts
  *
  * Browser-safe client for the deploy flow. Mirrors the buy / renew / refund
- * client shape: `proveDeploy` posts to the keeper's `/prove/deploy` endpoint
+ * client shape: `proveDeploy` posts to the backend's `/prove/deploy` endpoint
  * and returns the atomic deploy+initialize tx already signed with the
  * throwaway zkApp key. The vendor's wallet then adds the fee-payer signature
  * and broadcasts.
  *
  * The atomic bundling is what makes single-shot initialization safe:
  * `provenTxJson` holds both `zkApp.deploy()` and `zkApp.initialize()`
- * AccountUpdates in the same transaction, and the keeper generates a
+ * AccountUpdates in the same transaction, and the backend generates a
  * throwaway zkApp keypair per request that is discarded before the tx is
  * returned — so the target address is not observable to an attacker until
  * the initialize AU inside is already signed and locked to `(vendor,
@@ -17,7 +17,7 @@
  * precondition on `initialize()`, this yields a one-shot init per account.
  *
  * Also exports admin-side `redeployApp` / `redeployAll` for the platform
- * operator to trigger post-hardfork v1→v2 migrations via the keeper's
+ * operator to trigger post-hardfork v1→v2 migrations via the backend's
  * `/admin/redeploy*` endpoints (bearer-token auth).
  */
 export type ProveDeployRequest = {
@@ -27,6 +27,12 @@ export type ProveDeployRequest = {
     priceMonthlyMina: number;
     priceYearlyMina: number;
     priceFiveYearMina: number;
+    pricePerpetualMina: number;
+    deviceCap: number;
+    forkActivationSlot?: number;
+    network?: 'devnet' | 'mainnet';
+    website?: string;
+    payoutAddress?: string;
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 };
@@ -35,9 +41,15 @@ export type ProveDeployResponse = {
     verificationKeyHash: string;
     zkAppAddress: string;
 };
+/**
+ * The keeper's deploy watch (GET /deploy/status): `landed` once the zkApp
+ * account is on chain, `timeout` if the watch gave up waiting, `unknown` for
+ * an address it isn't watching.
+ */
 export type DeployStatus = {
-    status: 'unknown' | 'pending' | 'confirmed' | 'failed';
+    status: 'unknown' | 'pending' | 'landed' | 'timeout';
     landedAtSlot?: number;
+    landedAtBlockHeight?: number;
     elapsedMs?: number;
 };
 export declare function proveDeploy(req: ProveDeployRequest): Promise<ProveDeployResponse>;
@@ -55,37 +67,60 @@ export type RedeployAppRequest = {
     keeperUrl: string;
     appId: string;
     adminToken: string;
+    network?: 'devnet' | 'mainnet';
+    retireSignature?: string;
+    feePayer?: string;
     force?: boolean;
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 };
-export type RedeployAppResponse = {
-    ok: true;
+/**
+ * A proved redeploy step for the signer's wallet to sign, send and pay
+ * (vendor or admin wallet); then register its hash with `redeployId`.
+ */
+export type RedeployTx = {
+    step: 'retire';
+    provenTxJson: string;
+    redeployId: string;
+    retiredAddress: string;
+    successor: string;
+} | {
+    step: 'retireAndDeploy' | 'deploy';
+    provenTxJson: string;
+    redeployId: string;
+    retiredAddress: string;
     zkAppAddress: string;
-    txHash: string;
     verificationKeyHash: string;
-    onChainVersion: number;
-    forcedEscrowNonEmpty?: true;
 };
+/** The step a redeploy call took. */
+export type RedeployStepResult = {
+    step: 'sign-retire';
+    retireMessage: string[];
+    licensesRoot: string;
+    successor: string;
+    then: 'retire' | 'retireAndDeploy' | 'deploy';
+    force: boolean;
+} | RedeployTx;
+export type RedeployAppResponse = {
+    ok: true;
+} & RedeployStepResult;
 export type RedeployAllRequest = {
     keeperUrl: string;
     adminToken: string;
-    force?: boolean;
+    network?: 'devnet' | 'mainnet';
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 };
 export type RedeployAllResponse = {
     ok: true;
     count: number;
-    succeeded: number;
+    /** Apps whose retirement gate is up, ready for their next step. */
+    ready: number;
     results: Array<{
         appId: string;
         ok: true;
-        zkAppAddress: string;
-        txHash: string;
-        verificationKeyHash: string;
-        onChainVersion: number;
-        forcedEscrowNonEmpty?: true;
+        step: 'retire' | 'retireAndDeploy' | 'deploy';
+        readyAt: number;
     } | {
         appId: string;
         ok: false;
@@ -93,6 +128,18 @@ export type RedeployAllResponse = {
     }>;
 };
 export declare function redeployApp(req: RedeployAppRequest): Promise<RedeployAppResponse>;
+export declare function registerAdminRedeploy(req: {
+    keeperUrl: string;
+    appId: string;
+    adminToken: string;
+    redeployId: string;
+    txHash: string;
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<{
+    ok: true;
+    step: 'retire' | 'deploy';
+}>;
 export declare function redeployAll(req: RedeployAllRequest): Promise<RedeployAllResponse>;
 export type VendorRedeployPreflight = {
     ok: boolean;
@@ -115,11 +162,22 @@ export type VendorRedeployPreflight = {
         supported: boolean;
         supportedList: readonly number[];
     };
+    alreadyCurrent: boolean;
+    retired: boolean;
+    draining: {
+        startedAt: string;
+    } | null;
+    step: 'retire' | 'retireAndDeploy' | 'deploy' | null;
+    retirement: {
+        readyAt: number;
+        expiresAt: number;
+    } | null;
     reasons: string[];
 };
 export declare function fetchVendorRedeployPreflight(opts: {
     keeperUrl: string;
     appId: string;
+    network: 'devnet' | 'mainnet';
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 }): Promise<VendorRedeployPreflight>;
@@ -130,6 +188,8 @@ export type VendorRedeployChallenge = {
 export declare function getVendorRedeployChallenge(opts: {
     keeperUrl: string;
     appId: string;
+    /** The deployment to redeploy (the keeper requires it). */
+    network: 'devnet' | 'mainnet';
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 }): Promise<VendorRedeployChallenge>;
@@ -142,18 +202,26 @@ export type ProveVendorRedeployRequest = {
         scalar: string;
     };
     senderPublicKey: string;
-    force?: boolean;
+    retireSignature?: string;
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 };
-export type ProveVendorRedeployResponse = {
-    provenTxJson: string;
-    zkAppAddress: string;
-    verificationKeyHash: string;
-    redeployId: string;
-    forcedEscrowNonEmpty?: true;
+export type ProveVendorRedeployResponse = RedeployTx;
+export type VendorRedeployDraining = {
+    status: 'draining';
+    readyAt: number;
+    expiresAt: number;
+    message: string;
+};
+export type VendorRedeploySignRetire = {
+    status: 'sign-retire';
+    retireMessage: string[];
+    licensesRoot: string;
+    /** The new zkApp address the retirement names: only it can start from these licenses. */
+    successor: string;
+    message: string;
 };
-export declare function proveVendorRedeploy(req: ProveVendorRedeployRequest): Promise<ProveVendorRedeployResponse>;
+export declare function proveVendorRedeploy(req: ProveVendorRedeployRequest): Promise<ProveVendorRedeployResponse | VendorRedeployDraining | VendorRedeploySignRetire>;
 export type RegisterVendorRedeployRequest = {
     keeperUrl: string;
     appId: string;
@@ -162,7 +230,53 @@ export type RegisterVendorRedeployRequest = {
     fetcher?: typeof fetch;
     signal?: AbortSignal;
 };
+export declare function cancelVendorRedeploy(req: {
+    keeperUrl: string;
+    appId: string;
+    nonce: string;
+    signature: {
+        field: string;
+        scalar: string;
+    };
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<{
+    ok: true;
+}>;
+export declare function startRedeployDrain(req: {
+    keeperUrl: string;
+    appId: string;
+    adminToken: string;
+    network: 'devnet' | 'mainnet';
+    fetcher?: typeof fetch;
+}): Promise<{
+    ok: true;
+    draining: {
+        startedAt: string;
+    };
+    alreadyEmpty: boolean;
+}>;
+export declare function cancelRedeploy(req: {
+    keeperUrl: string;
+    appId: string;
+    adminToken: string;
+    network: 'devnet' | 'mainnet';
+    fetcher?: typeof fetch;
+}): Promise<{
+    ok: true;
+}>;
+export declare function sendRedeployNotices(req: {
+    keeperUrl: string;
+    adminToken: string;
+    network: 'devnet' | 'mainnet';
+    fetcher?: typeof fetch;
+}): Promise<{
+    ok: true;
+    notified: string[];
+    forkActivationSlot: number;
+}>;
 export declare function registerVendorRedeploy(req: RegisterVendorRedeployRequest): Promise<{
     ok: true;
+    step: 'retire' | 'deploy';
 }>;
 //# sourceMappingURL=deployClient.d.ts.map

package/build/deployClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployClient.d.ts","sourceRoot":"","sources":["../src/deployClient.ts"],"names":[],"mappings":"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"}