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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/README.md +132 -23
  2. package/build/archiveBootstrap.d.ts.map +1 -0
  3. package/build/archiveBootstrap.js +1 -1
  4. package/build/archiveBootstrap.js.map +1 -0
  5. package/build/buyClient.d.ts +2 -0
  6. package/build/buyClient.d.ts.map +1 -0
  7. package/build/buyClient.js +8 -2
  8. package/build/buyClient.js.map +1 -0
  9. package/build/contractInterface.d.ts.map +1 -0
  10. package/build/contractInterface.js +1 -1
  11. package/build/contractInterface.js.map +1 -0
  12. package/build/countryStats.d.ts +6 -1
  13. package/build/countryStats.d.ts.map +1 -0
  14. package/build/countryStats.js +33 -9
  15. package/build/countryStats.js.map +1 -0
  16. package/build/deployClient.d.ts.map +1 -0
  17. package/build/deployClient.js +1 -1
  18. package/build/deployClient.js.map +1 -0
  19. package/build/freezeClient.d.ts.map +1 -0
  20. package/build/freezeClient.js +1 -1
  21. package/build/freezeClient.js.map +1 -0
  22. package/build/generationClient.d.ts.map +1 -0
  23. package/build/generationClient.js +1 -1
  24. package/build/generationClient.js.map +1 -0
  25. package/build/index.d.ts.map +1 -0
  26. package/build/index.js +1 -1
  27. package/build/index.js.map +1 -0
  28. package/build/licenseProof.d.ts.map +1 -0
  29. package/build/licenseProof.js +1 -1
  30. package/build/licenseProof.js.map +1 -0
  31. package/build/licenseRecord.d.ts +10 -0
  32. package/build/licenseRecord.d.ts.map +1 -0
  33. package/build/licenseRecord.js +1 -1
  34. package/build/licenseRecord.js.map +1 -0
  35. package/build/licenseStore.d.ts +1 -1
  36. package/build/licenseStore.d.ts.map +1 -0
  37. package/build/licenseStore.js +4 -2
  38. package/build/licenseStore.js.map +1 -0
  39. package/build/manifestVerify.d.ts.map +1 -0
  40. package/build/manifestVerify.js +1 -1
  41. package/build/manifestVerify.js.map +1 -0
  42. package/build/migrateClient.d.ts +5 -21
  43. package/build/migrateClient.d.ts.map +1 -0
  44. package/build/migrateClient.js +29 -17
  45. package/build/migrateClient.js.map +1 -0
  46. package/build/ownership.d.ts.map +1 -0
  47. package/build/ownership.js +1 -1
  48. package/build/ownership.js.map +1 -0
  49. package/build/proveErrors.d.ts +35 -0
  50. package/build/proveErrors.d.ts.map +1 -0
  51. package/build/proveErrors.js +49 -0
  52. package/build/proveErrors.js.map +1 -0
  53. package/build/proveRetry.d.ts +38 -0
  54. package/build/proveRetry.d.ts.map +1 -0
  55. package/build/proveRetry.js +89 -0
  56. package/build/proveRetry.js.map +1 -0
  57. package/build/refundClient.d.ts.map +1 -0
  58. package/build/refundClient.js +1 -1
  59. package/build/refundClient.js.map +1 -0
  60. package/build/renewClient.d.ts +1 -0
  61. package/build/renewClient.d.ts.map +1 -0
  62. package/build/renewClient.js +9 -3
  63. package/build/renewClient.js.map +1 -0
  64. package/build/statsClient.d.ts +28 -0
  65. package/build/statsClient.d.ts.map +1 -0
  66. package/build/statsClient.js +34 -5
  67. package/build/statsClient.js.map +1 -0
  68. package/build/txBroadcastClient.d.ts +26 -0
  69. package/build/txBroadcastClient.d.ts.map +1 -0
  70. package/build/txBroadcastClient.js +20 -0
  71. package/build/txBroadcastClient.js.map +1 -0
  72. package/build/vendorAccountClient.d.ts +55 -0
  73. package/build/vendorAccountClient.d.ts.map +1 -0
  74. package/build/vendorAccountClient.js +44 -0
  75. package/build/vendorAccountClient.js.map +1 -0
  76. package/build/verifyCore.d.ts.map +1 -0
  77. package/build/verifyCore.js +1 -1
  78. package/build/verifyCore.js.map +1 -0
  79. package/build/verifyService.d.ts.map +1 -0
  80. package/build/verifyService.js +1 -1
  81. package/build/verifyService.js.map +1 -0
  82. package/build/zipToState.d.ts +2 -0
  83. package/build/zipToState.d.ts.map +1 -0
  84. package/build/zipToState.js +94 -0
  85. package/build/zipToState.js.map +1 -0
  86. package/package.json +19 -4
  87. package/src/archiveBootstrap.ts +285 -0
  88. package/src/buyClient.ts +259 -0
  89. package/src/contractInterface.d.ts +55 -0
  90. package/src/contractInterface.ts +242 -0
  91. package/src/countryStats.ts +171 -0
  92. package/src/deployClient.ts +388 -0
  93. package/src/freezeClient.ts +117 -0
  94. package/src/generationClient.ts +164 -0
  95. package/src/index.ts +392 -0
  96. package/src/licenseProof.d.ts +26 -0
  97. package/src/licenseProof.ts +48 -0
  98. package/src/licenseRecord.ts +91 -0
  99. package/src/licenseStore.ts +358 -0
  100. package/src/manifestVerify.ts +106 -0
  101. package/src/migrateClient.ts +82 -0
  102. package/src/ownership.ts +198 -0
  103. package/src/proveErrors.ts +70 -0
  104. package/src/refundClient.ts +144 -0
  105. package/src/renewClient.ts +209 -0
  106. package/src/statsClient.ts +190 -0
  107. package/src/txBroadcastClient.ts +48 -0
  108. package/src/vendorAccountClient.ts +106 -0
  109. package/src/verifyCore.ts +84 -0
  110. package/src/verifyService.ts +799 -0
  111. package/src/zipToState.ts +94 -0
@@ -0,0 +1,190 @@
1
+ // Copyright (c) 2025-2026 zkLicensing project developers
2
+ // SPDX-License-Identifier: BUSL-1.1
3
+
4
+ /**
5
+ * statsClient.ts
6
+ *
7
+ * Browser-safe HTTP client for the vendor-facing keeper endpoints that back
8
+ * the dashboard: GET /stats, GET /transactions, and GET /apps/vendor/:addr.
9
+ *
10
+ * Types mirror the keeper's response shapes so a dashboard implementation
11
+ * (this repo's zklicensing.com dashboard or a third-party one) doesn't have
12
+ * to re-derive them. New optional fields on the server should be added here
13
+ * as `?:` so older clients still typecheck against a newer keeper.
14
+ */
15
+
16
+ import type { CountryBreakdown } from './countryStats.js';
17
+ import type { FiatRateSnapshot } from './licenseRecord.js';
18
+
19
+ export type Tier = 'monthly' | 'yearly' | 'fiveYear';
20
+
21
+ export type AppRecord = {
22
+ appId: string;
23
+ name: string;
24
+ description: string;
25
+ longDescription?: string;
26
+ category: string;
27
+ website: string;
28
+ zkAppAddress: string;
29
+ vendorAddress: string;
30
+ priceMonthlyMina: number;
31
+ priceYearlyMina: number;
32
+ priceFiveYearMina: number;
33
+ txHash: string;
34
+ verificationKeyHash?: string;
35
+ logo?: string;
36
+ // Best favicon URL for the vendor's website, resolved server-side by the
37
+ // keeper (parses `<link rel="icon">` tags on the website). Undefined until
38
+ // the vendor's next edit for grandfathered apps — clients should fall back
39
+ // to `${host}/favicon.ico` in that case.
40
+ iconUrl?: string;
41
+ tags?: string[];
42
+ contactEmail?: string;
43
+ supportEmail?: string;
44
+ country?: string;
45
+ status?: 'pending' | 'active' | 'inactive' | 'rejected';
46
+ rejectionReason?: string;
47
+ createdAt: string;
48
+ approvedAt?: string;
49
+ pendingEdit?: Partial<AppRecord> & { editedAt: string };
50
+ // Append-only audit trail of status transitions. Optional so older keepers
51
+ // that don't yet emit it still typecheck.
52
+ statusHistory?: { status: string; at: string; actor: string; note?: string }[];
53
+ // Vendor legal / billing block — collected at registration for compliance
54
+ // (CRD Art. 6, e-Commerce Directive Art. 5) and reused in the vendor's
55
+ // tax-year CSV export. All optional here so older keepers that don't yet
56
+ // return these fields still typecheck. `country` (top-level above) is the
57
+ // billing country and pairs with `billingAddress` — the address struct
58
+ // intentionally omits a country field to avoid drift.
59
+ legalName?: string;
60
+ billingAddress?: { line1: string; line2?: string; city: string; postalCode: string };
61
+ invoiceEmail?: string;
62
+ vatId?: string;
63
+ companyRegistrationRegistry?: string;
64
+ companyRegistrationNumber?: string;
65
+ };
66
+
67
+ export type VendorStatsResponse = {
68
+ apps: AppRecord[];
69
+ activeLicenses: number;
70
+ totalLicenses: number;
71
+ totalRevenueMina: number;
72
+ pendingRevenueMina?: number;
73
+ // Vendor's post-fee share of refunded purchases, in MINA. Optional so older
74
+ // keepers (pre-refund-tracking) still typecheck against this SDK.
75
+ refundedRevenueMina?: number;
76
+ renewalRate: number | null;
77
+ monthlyRevenueMina: { month: string; mina: number }[];
78
+ licensesByTier?: { monthly: number; yearly: number; fiveYear: number };
79
+ deltas: { revenuePct: number | null };
80
+ countryBreakdown?: CountryBreakdown;
81
+ };
82
+
83
+ export type Transaction = {
84
+ type: 'purchase' | 'renewal' | 'release' | 'refund';
85
+ appId: string;
86
+ appName: string;
87
+ // Only populated on the admin __all response — vendor-scoped queries omit it
88
+ // since the caller already knows the vendor from the query itself.
89
+ vendorAddress?: string;
90
+ tier: Tier | null;
91
+ amountMina: number;
92
+ txHash: string;
93
+ date: string; // ISO
94
+ // Buyer's ISO-3166 alpha-2 country at purchase (present on purchase rows and
95
+ // any downstream renewal/refund/release rows for the same record). Optional
96
+ // for pre-country-capture legacy rows.
97
+ buyerCountry?: string;
98
+ // MINA→fiat rates snapshotted at the moment the underlying purchase/renewal
99
+ // confirmed — same fields as the receipt email. Missing on archive-replayed
100
+ // records and on rows created before the first successful CoinGecko fetch.
101
+ fiatSnapshot?: FiatRateSnapshot;
102
+ };
103
+
104
+ export type TransactionsResponse = { transactions: Transaction[] };
105
+
106
+ export type VendorAppsResponse = { apps: AppRecord[] };
107
+
108
+ function baseUrl(url: string): string {
109
+ return url.replace(/\/+$/, '');
110
+ }
111
+
112
+ // Admin __all mode: pass `adminToken` and omit `vendorAddress` (or pass '__all').
113
+ // Fetches aggregate over every registered app. Server gates with Bearer auth.
114
+ // tzOffsetMinutes: signed minutes east of UTC — shifts tax-year cutovers on the
115
+ // countryBreakdown so a UK vendor's 2026 doesn't include a Dec 31 23:30 PST
116
+ // purchase. Default omitted → UTC bucketing preserved for existing callers.
117
+ export async function fetchVendorStats(opts: {
118
+ keeperUrl: string;
119
+ vendorAddress: string;
120
+ adminToken?: string;
121
+ tzOffsetMinutes?: number;
122
+ fetcher?: typeof fetch;
123
+ signal?: AbortSignal;
124
+ }): Promise<VendorStatsResponse | null> {
125
+ const fetcher = opts.fetcher ?? fetch;
126
+ const headers: Record<string, string> = {};
127
+ if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
128
+ const tzQ = typeof opts.tzOffsetMinutes === 'number' ? `&tz=${opts.tzOffsetMinutes}` : '';
129
+ const resp = await fetcher(
130
+ `${baseUrl(opts.keeperUrl)}/stats?vendor=${encodeURIComponent(opts.vendorAddress)}${tzQ}`,
131
+ { signal: opts.signal, headers },
132
+ );
133
+ if (!resp.ok) return null;
134
+ return await resp.json() as VendorStatsResponse;
135
+ }
136
+
137
+ export async function fetchTransactions(opts: {
138
+ keeperUrl: string;
139
+ vendorAddress: string;
140
+ adminToken?: string;
141
+ // Rolling window in days. Default 30. Ignored when both `from` and `to` are
142
+ // set (explicit range wins) — used for the dashboard's "last N days" view.
143
+ days?: number;
144
+ // Explicit inclusive-start / exclusive-end ISO dates (YYYY-MM-DD). When both
145
+ // are set the server filters to [from, to) instead of the rolling window.
146
+ // Used by the CSV export to fetch an exact tax year without over-fetching.
147
+ from?: string;
148
+ to?: string;
149
+ fetcher?: typeof fetch;
150
+ signal?: AbortSignal;
151
+ }): Promise<TransactionsResponse | null> {
152
+ const fetcher = opts.fetcher ?? fetch;
153
+ const headers: Record<string, string> = {};
154
+ if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
155
+ const qs = new URLSearchParams({ vendor: opts.vendorAddress });
156
+ if (opts.from && opts.to) {
157
+ qs.set('from', opts.from);
158
+ qs.set('to', opts.to);
159
+ } else {
160
+ qs.set('days', String(opts.days ?? 30));
161
+ }
162
+ const resp = await fetcher(
163
+ `${baseUrl(opts.keeperUrl)}/transactions?${qs.toString()}`,
164
+ { signal: opts.signal, headers },
165
+ );
166
+ if (!resp.ok) return null;
167
+ return await resp.json() as TransactionsResponse;
168
+ }
169
+
170
+ // Admin all-apps mode: pass `adminToken` and set `vendorAddress` to '__all'.
171
+ // Hits GET /apps (no auth needed today; the admin overload just uses a
172
+ // different URL) so vendors visiting their own dashboard still hit the same
173
+ // per-vendor endpoint.
174
+ export async function fetchVendorApps(opts: {
175
+ keeperUrl: string;
176
+ vendorAddress: string;
177
+ adminToken?: string;
178
+ fetcher?: typeof fetch;
179
+ signal?: AbortSignal;
180
+ }): Promise<VendorAppsResponse | null> {
181
+ const fetcher = opts.fetcher ?? fetch;
182
+ const headers: Record<string, string> = {};
183
+ if (opts.adminToken) headers.Authorization = `Bearer ${opts.adminToken}`;
184
+ const url = opts.adminToken && opts.vendorAddress === '__all'
185
+ ? `${baseUrl(opts.keeperUrl)}/apps?all=1`
186
+ : `${baseUrl(opts.keeperUrl)}/apps/vendor/${encodeURIComponent(opts.vendorAddress)}`;
187
+ const resp = await fetcher(url, { signal: opts.signal, headers });
188
+ if (!resp.ok) return null;
189
+ return await resp.json() as VendorAppsResponse;
190
+ }
@@ -0,0 +1,48 @@
1
+ // Copyright (c) 2025-2026 zkLicensing project developers
2
+ // SPDX-License-Identifier: BUSL-1.1
3
+
4
+ /**
5
+ * txBroadcastClient.ts
6
+ *
7
+ * Small helper for POST /tx-broadcast. Called by the buy/renew/migrate
8
+ * flows immediately after the buyer's wallet returns a txHash — signals
9
+ * the keeper to extend the app's in-flight slot from the short signing-TTL
10
+ * to the longer landing-TTL, so concurrent buyers on the same app don't
11
+ * think the slot has expired while an honest signed tx is still in the
12
+ * mempool.
13
+ *
14
+ * Fire-and-forget by design: this is a tightening signal, not a
15
+ * correctness dependency. Land-clear in the buy-watcher and the
16
+ * signing-TTL both remain live regardless of whether this call succeeds.
17
+ * Failures are swallowed with an optional log callback so a network blip
18
+ * doesn't surface as a confusing error mid-checkout.
19
+ */
20
+
21
+ export type NotifyBroadcastRequest = {
22
+ keeperUrl: string;
23
+ appId: string;
24
+ txHash: string;
25
+ fetcher?: typeof fetch;
26
+ signal?: AbortSignal;
27
+ // Optional hook for surfacing swallowed failures to the caller's logger.
28
+ // Not called on the happy path.
29
+ onError?: (err: unknown) => void;
30
+ };
31
+
32
+ function baseUrl(url: string): string {
33
+ return url.replace(/\/+$/, '');
34
+ }
35
+
36
+ export async function notifyBroadcast(req: NotifyBroadcastRequest): Promise<void> {
37
+ const fetcher = req.fetcher ?? fetch;
38
+ try {
39
+ await fetcher(`${baseUrl(req.keeperUrl)}/tx-broadcast`, {
40
+ method: 'POST',
41
+ headers: { 'Content-Type': 'application/json' },
42
+ signal: req.signal,
43
+ body: JSON.stringify({ appId: req.appId, txHash: req.txHash }),
44
+ });
45
+ } catch (err) {
46
+ req.onError?.(err);
47
+ }
48
+ }
@@ -0,0 +1,106 @@
1
+ // Copyright (c) 2025-2026 zkLicensing project developers
2
+ // SPDX-License-Identifier: BUSL-1.1
3
+
4
+ /**
5
+ * vendorAccountClient.ts
6
+ *
7
+ * Browser-safe client for the vendor's shared legal/billing block —
8
+ * the fields that must stay consistent across every app registered by
9
+ * one vendor wallet (legal entity name, billing country and address,
10
+ * VAT id, company registry). One PATCH updates all of the vendor's
11
+ * apps atomically on the keeper, so a legal-entity rename or address
12
+ * move doesn't leave old apps advertising stale CRD Art. 6 disclosures.
13
+ *
14
+ * Signature covers the vendor address, mirroring the "sign the
15
+ * resource id" pattern PUT /apps/:appId uses. The keeper verifies
16
+ * against the on-chain vendor recorded on the app records.
17
+ */
18
+
19
+ export type VendorLegalBlock = {
20
+ country?: string;
21
+ legalName?: string;
22
+ billingAddress?: {
23
+ line1: string;
24
+ line2?: string;
25
+ city: string;
26
+ postalCode: string;
27
+ };
28
+ invoiceEmail?: string;
29
+ vatId?: string;
30
+ companyRegistrationRegistry?: string;
31
+ companyRegistrationNumber?: string;
32
+ };
33
+
34
+ export type GetVendorLegalRequest = {
35
+ keeperUrl: string;
36
+ vendorAddress: string;
37
+ fetcher?: typeof fetch;
38
+ signal?: AbortSignal;
39
+ };
40
+
41
+ export type GetVendorLegalResponse = {
42
+ // null when the wallet has no apps yet — register form should prompt
43
+ // for the block instead of treating first-app registration as an error.
44
+ legal: VendorLegalBlock | null;
45
+ };
46
+
47
+ export type UpdateVendorLegalRequest = {
48
+ keeperUrl: string;
49
+ vendorAddress: string;
50
+ signature: { field: string; scalar: string };
51
+ payload: VendorLegalBlock;
52
+ fetcher?: typeof fetch;
53
+ signal?: AbortSignal;
54
+ };
55
+
56
+ export type UpdateVendorLegalResponse = {
57
+ ok: true;
58
+ appsUpdated: number;
59
+ };
60
+
61
+ function baseUrl(url: string): string {
62
+ return url.replace(/\/+$/, '');
63
+ }
64
+
65
+ async function readJsonError(resp: Response): Promise<string> {
66
+ try {
67
+ const body = await resp.json() as Record<string, unknown>;
68
+ if (typeof body.error === 'string') return body.error;
69
+ } catch { /* body wasn't JSON */ }
70
+ return `HTTP ${resp.status}`;
71
+ }
72
+
73
+ // GET /vendors/:address/legal — fetch the shared legal block for a wallet.
74
+ // Returns `{ legal: null }` for wallets with no registered apps.
75
+ export async function getVendorLegal(req: GetVendorLegalRequest): Promise<GetVendorLegalResponse> {
76
+ const fetcher = req.fetcher ?? fetch;
77
+ const resp = await fetcher(
78
+ `${baseUrl(req.keeperUrl)}/vendors/${encodeURIComponent(req.vendorAddress)}/legal`,
79
+ { signal: req.signal },
80
+ );
81
+ if (!resp.ok) throw new Error(await readJsonError(resp));
82
+ return await resp.json() as GetVendorLegalResponse;
83
+ }
84
+
85
+ // PATCH /vendors/:address/legal — updates the block on EVERY app the vendor
86
+ // owns in a single atomic sweep. Bypasses the pendingEdit staging that
87
+ // per-app metadata edits go through; legal fields are factual (not
88
+ // marketing copy) so admin review doesn't gain anything and staleness
89
+ // hurts CRD Art. 6 compliance.
90
+ export async function updateVendorLegal(req: UpdateVendorLegalRequest): Promise<UpdateVendorLegalResponse> {
91
+ const fetcher = req.fetcher ?? fetch;
92
+ const resp = await fetcher(
93
+ `${baseUrl(req.keeperUrl)}/vendors/${encodeURIComponent(req.vendorAddress)}/legal`,
94
+ {
95
+ method: 'PATCH',
96
+ headers: { 'Content-Type': 'application/json' },
97
+ signal: req.signal,
98
+ body: JSON.stringify({
99
+ signature: req.signature,
100
+ payload: req.payload,
101
+ }),
102
+ },
103
+ );
104
+ if (!resp.ok) throw new Error(await readJsonError(resp));
105
+ return await resp.json() as UpdateVendorLegalResponse;
106
+ }
@@ -0,0 +1,84 @@
1
+ // Copyright (c) 2025-2026 zkLicensing project developers
2
+ // SPDX-License-Identifier: BUSL-1.1
3
+
4
+ /**
5
+ * verifyCore.ts
6
+ *
7
+ * Pure verification logic shared by keeperService and verifyService.
8
+ * No HTTP, no network — takes already-fetched on-chain state and
9
+ * performs Merkle inclusion check + expiry logic.
10
+ */
11
+
12
+ import { Field } from 'o1js';
13
+ import { buildMap, type LicenseRecord } from './licenseStore.js';
14
+ import { GRACE_PERIOD_N, MS_PER_SLOT_N, SLOTS_PER_DAY_N } from './contractInterface.js';
15
+
16
+ export type VerifyResponse = {
17
+ valid: boolean;
18
+ expiresAt: string | null;
19
+ expirySlot: number;
20
+ inGracePeriod: boolean;
21
+ // Whole days until expiry. Negative while in the grace period (down to ~-7
22
+ // — GRACE_PERIOD_N is 6 720 slots = 7 days) and below that once expired.
23
+ // 0 when expirySlot is unknown (unknown/refunded/root-mismatch).
24
+ remainingDays: number;
25
+ reason: string | null;
26
+ };
27
+
28
+ function computeRemainingDays(expirySlot: number, currentSlot: number): number {
29
+ if (expirySlot === 0) return 0;
30
+ return Math.floor((expirySlot - currentSlot) / SLOTS_PER_DAY_N);
31
+ }
32
+
33
+ /**
34
+ * Core license verification.
35
+ *
36
+ * @param zkAppAddress - app address (composite key with licenseHash)
37
+ * @param licenseHash - Poseidon.hash([secretHash]) as a field string
38
+ * @param records - current off-chain license records (from licenseStore)
39
+ * @param onChainRoot - zkApp appState[0] fetched from Mina
40
+ * @param currentSlot - current blockchain slot (globalSlotSinceGenesis)
41
+ */
42
+ export function verifyLicenseCore(params: {
43
+ zkAppAddress: string;
44
+ licenseHash: string;
45
+ records: LicenseRecord[];
46
+ onChainRoot: string;
47
+ currentSlot: number;
48
+ }): VerifyResponse {
49
+ const { zkAppAddress, licenseHash, records, onChainRoot, currentSlot } = params;
50
+
51
+ const map = buildMap(records, zkAppAddress);
52
+ const key = Field(licenseHash);
53
+ const currentValue = map.get(key).toString();
54
+ const witness = map.getWitness(key);
55
+
56
+ const [computedRoot] = witness.computeRootAndKey(Field(currentValue));
57
+
58
+ if (computedRoot.toString() !== onChainRoot) {
59
+ return { valid: false, expiresAt: null, expirySlot: 0, inGracePeriod: false, remainingDays: 0, reason: 'License state does not match on-chain root' };
60
+ }
61
+
62
+ if (currentValue === '0') {
63
+ return { valid: false, expiresAt: null, expirySlot: 0, inGracePeriod: false, remainingDays: 0, reason: 'License has been refunded' };
64
+ }
65
+
66
+ const expirySlot = Number(currentValue);
67
+ const inGracePeriod = currentSlot > expirySlot && currentSlot <= expirySlot + GRACE_PERIOD_N;
68
+ const expired = currentSlot > expirySlot + GRACE_PERIOD_N;
69
+ const expiresAt = new Date(Date.now() + (expirySlot - currentSlot) * MS_PER_SLOT_N).toISOString();
70
+ const remainingDays = computeRemainingDays(expirySlot, currentSlot);
71
+
72
+ if (expired) {
73
+ return { valid: false, expiresAt, expirySlot, inGracePeriod: false, remainingDays, reason: 'License has expired' };
74
+ }
75
+
76
+ return {
77
+ valid: true,
78
+ expiresAt,
79
+ expirySlot,
80
+ inGracePeriod,
81
+ remainingDays,
82
+ reason: inGracePeriod ? 'License is in grace period — renew to avoid interruption' : null,
83
+ };
84
+ }