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

package/src/releaseClient.ts

@@ -0,0 +1,101 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * releaseClient.ts
+ *
+ * Vendor-signed release path — call POST /prove/release-vendor to get an
+ * unsigned proved tx, then broadcast it through the vendor's wallet
+ * (`provider.sendTransaction`). The vendor pays the transaction fee and
+ * signs the fee-payer AU themselves — the licensing service never needs
+ * its own feepayer key for this path.
+ *
+ * `releaseFunds` is permissionless on-chain, so anyone willing to pay gas
+ * may call this. There is no server-side identity check — the client's
+ * wallet holds full authority via the fee-payer signature.
+ *
+ * On-chain settlement is observed by the licensing service's event-sync
+ * loop. That sweep runs every 30 minutes, so callers who want the
+ * `released` flag to flip within seconds of inclusion should call
+ * `confirmVendorRelease` with the wallet's returned tx hash — the service
+ * then watches bestChain and mirrors the fundsReleased event optimistically.
+ * The event-sync sweep is still authoritative; the confirm/watch path is a
+ * latency shortcut and is idempotent.
+ */
+
+import { readErrorBody, keeperError } from './proveErrors.js';
+
+export type ProveVendorReleaseRequest = {
+  keeperUrl:       string;
+  licenseHash:     string;
+  zkAppAddress:    string;
+  senderPublicKey: string;
+  // Optional — the service will resolve the network from the zkAppAddress
+  // when omitted. Set explicitly when the caller already knows which
+  // network the deployment lives on.
+  network?:        'devnet' | 'mainnet';
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+export type ProveVendorReleaseResponse = {
+  // Serialized Mina.transaction JSON, proved but with an unsigned fee-payer
+  // AU. Pass verbatim to `provider.sendTransaction({ transaction })`.
+  provenTxJson: string;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+export async function proveVendorRelease(req: ProveVendorReleaseRequest): Promise<ProveVendorReleaseResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/release-vendor`, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal:  req.signal,
+    body:    JSON.stringify({
+      licenseHash:     req.licenseHash,
+      zkAppAddress:    req.zkAppAddress,
+      senderPublicKey: req.senderPublicKey,
+      ...(req.network ? { network: req.network } : {}),
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveVendorReleaseResponse;
+}
+
+export type ConfirmVendorReleaseRequest = {
+  keeperUrl:    string;
+  licenseHash:  string;
+  zkAppAddress: string;
+  // Tx hash returned by the wallet after broadcast. The service polls
+  // bestChain for this hash and flips `record.released` on sight.
+  txHash:       string;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+export type ConfirmVendorReleaseResponse = { ok: true };
+
+export async function confirmVendorRelease(req: ConfirmVendorReleaseRequest): Promise<ConfirmVendorReleaseResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/release-vendor`, {
+    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) {
+    const parsed = await readErrorBody(resp);
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ConfirmVendorReleaseResponse;
+}

package/src/renewClient.ts

@@ -0,0 +1,234 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * renewClient.ts
+ *
+ * Browser-safe client for the renew flow. Mirrors `buyClient.ts` in shape:
+ * the caller drives the wallet step between `proveRenew` and `confirmRenew`
+ * so the SDK stays wallet-agnostic.
+ *
+ * Unlike buy, renew carries a legally load-bearing `waiverAccepted` flag —
+ * EU/UK CRD Article 16(m) extinguishes the 14-day right of withdrawal only
+ * on the buyer's express affirmative act (consent to immediate delivery +
+ * acknowledgment of loss of withdrawal). We refuse the /prove/renew call
+ * when the flag is false to keep third-party integrators from silently
+ * shipping a UI that omits the waiver gate.
+ *
+ * Also refused pre-network when the backend's sales-freeze schedule has
+ * fired (salesFrozen === true) — the backend would 423 the request anyway,
+ * so surfacing the specific message client-side avoids a wasted round-trip.
+ */
+
+import type { PurchaseReceipt } from './receipt.js';
+import { resolveFreezeState } from './freezeClient.js';
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+
+export type ProveRenewRequest = {
+  // Standing consent (zklicensing/agent/actions) when an AI agent gives the
+  // withdrawal waiver for its owner.
+  agentConsent?:  unknown;
+  keeperUrl:       string;
+  licenseHash:     string;
+  buyerAddress:    string;
+  zkAppAddress:    string;
+  // Mina network this renewal targets. Pull from your persisted ProofFile
+  // so it always matches the network the original buy was proved against.
+  network:         'devnet' | 'mainnet';
+  duration:        0 | 1 | 2 | 3; // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
+  // Set from the UI's Article 16(m) consent gate. Missing/false raises
+  // before the network call — the SDK never proves a renew without it.
+  waiverAccepted:  boolean;
+  // Optional freeze-slot override. When omitted the SDK reads
+  // `process.env.FREEZE_AFTER_SLOT` (Node only), else GET /health.
+  freezeAfterSlot?: number | null;
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+export type ProveRenewResponse = {
+  provenTxJson:  string;
+  newExpirySlot: number;
+  licenseHash:   string;
+  renewAmount:   string; // nanomina
+  // Deployment generation the backend proved against. If the buyer's stored
+  // ProofFile.generation is smaller, renew.ts walks ancestors and calls
+  // migrateLicense on each hop before submitting the renew.
+  generation:    number;
+  // Key the backend stored the per-app in-flight slot under. Passed back to
+  // POST /tx-broadcast after the wallet returns a hash. See ProveBuyResponse.
+  appKey:        string;
+};
+
+export type ConfirmRenewRequest = {
+  keeperUrl:    string;
+  zkAppAddress: string;
+  licenseHash:  string;
+  txHash:       string;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+async function readJsonError(resp: Response): Promise<string> {
+  try {
+    const body = await resp.json() as Record<string, unknown>;
+    if (typeof body.error === 'string') return body.error;
+  } catch { /* body wasn't JSON */ }
+  return `HTTP ${resp.status}`;
+}
+
+// POST /prove/renew — the backend compiles + proves the renew tx.
+// Rejects locally when `waiverAccepted` is false; a network call in that
+// state would be wasted work and would give the caller no signal that the
+// legal precondition was missing. Also rejects when the backend's freeze
+// has fired — same reasoning.
+export async function proveRenew(req: ProveRenewRequest): Promise<ProveRenewResponse> {
+  if (req.waiverAccepted !== true) {
+    throw new Error('waiverAccepted must be true — Article 16(m) waiver required to renew');
+  }
+  const fetcher = req.fetcher ?? fetch;
+  const freeze = await resolveFreezeState({
+    keeperUrl:       req.keeperUrl,
+    network:         req.network,
+    freezeAfterSlot: req.freezeAfterSlot,
+    fetcher,
+    signal:          req.signal,
+  });
+  if (freeze.salesFrozen) {
+    throw new Error('Sales frozen — new renewals refused ahead of scheduled hardfork migration');
+  }
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/renew`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      licenseHash:  req.licenseHash,
+      buyerAddress: req.buyerAddress,
+      zkAppAddress: req.zkAppAddress,
+      network:      req.network,
+      duration:     req.duration,
+      ...(req.agentConsent ? { agentConsent: req.agentConsent } : {}),
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveRenewResponse;
+}
+
+// POST /confirm/renew — promotes the in-memory renew intent to a pending
+// LicenseRecord. Call this only after the wallet returns a txHash.
+/** Returns the buyer's receipt for the renewal when the keeper issued one (put it in the license file as `receipt`). */
+export async function confirmRenew(req: ConfirmRenewRequest): Promise<{ ok: true; receipt?: PurchaseReceipt }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/renew`, {
+    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));
+  const body = await resp.json().catch(() => ({})) as { receipt?: PurchaseReceipt };
+  return { ok: true, ...(body?.receipt ? { receipt: body.receipt } : {}) };
+}
+
+export type RenewStatus = {
+  // 'confirmed' once the eventSync sweep has observed the licenseRenewed event
+  // on-chain and cleared the pending flag with the new expiry in place.
+  // 'pending' while the tx is in flight. 'unknown' if the license record
+  // hasn't been persisted yet (confirmRenew hasn't run or the intent expired).
+  // 'failed' if the keeper saw the transaction included but failed on chain
+  // (failureReason says why): the license is as it was; terminal.
+  status: 'confirmed' | 'pending' | 'unknown' | 'failed';
+  failureReason?: string;
+  expirySlot?: number;
+  txHash?:     string | null;
+  elapsedMs?:  number;
+};
+
+export type PollRenewStatusOptions = {
+  keeperUrl:     string;
+  network:       'devnet' | 'mainnet';
+  zkAppAddress:  string;
+  licenseHash:   string;
+  // The expected new expiry (from ProveRenewResponse). Confirmation requires
+  // BOTH pending=false AND the on-chain record's expirySlot matching or
+  // exceeding this — the pending flag alone flips before the sweep, so
+  // matching against the expected slot avoids reporting confirmed on the
+  // stale pre-renew record.
+  newExpirySlot: number;
+  fetcher?:      typeof fetch;
+  // Mina slots are ~90 s and a tx usually lands within a few slots, so a
+  // 10 s tick keeps the UI live without hammering the backend.
+  intervalMs?:   number;  // default 10 000
+  timeoutMs?:    number;  // default 20 min
+  signal?:       AbortSignal;
+  onTick?:       (status: RenewStatus) => void;
+};
+
+// Polls GET /license/:zkAppAddress/:licenseHash until the renew has landed
+// on-chain (pending flipped and new expiry recorded) or the timeout fires.
+// Mirrors pollBuyStatus, except the terminal condition is Mina-side rather
+// than a backend-side buy-watch — renew has no dedicated watch map.
+export async function pollRenewStatus(opts: PollRenewStatusOptions): Promise<RenewStatus> {
+  const fetcher = opts.fetcher ?? fetch;
+  const interval = opts.intervalMs ?? 10_000;
+  const timeout  = opts.timeoutMs  ?? 20 * 60 * 1000;
+  const startedAt = Date.now();
+  const deadline  = startedAt + timeout;
+  const url = `${baseUrl(opts.keeperUrl)}/license/${encodeURIComponent(opts.zkAppAddress)}/${encodeURIComponent(opts.licenseHash)}?network=${opts.network}`;
+
+  while (true) {
+    if (opts.signal?.aborted) throw new Error('pollRenewStatus aborted');
+    let status: RenewStatus = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+    try {
+      const resp = await fetcher(url, { signal: opts.signal });
+      if (resp.ok) {
+        const body = await resp.json() as {
+          found?: boolean; expirySlot?: number; pending?: boolean; txHash?: string | null;
+        };
+        if (!body.found) {
+          status = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+        } else if (body.pending === false && (body.expirySlot ?? 0) >= opts.newExpirySlot) {
+          status = {
+            status: 'confirmed',
+            expirySlot: body.expirySlot,
+            txHash: body.txHash ?? null,
+            elapsedMs: Date.now() - startedAt,
+          };
+        } else {
+          status = {
+            status: 'pending',
+            expirySlot: body.expirySlot,
+            txHash: body.txHash ?? null,
+            elapsedMs: Date.now() - startedAt,
+          };
+        }
+      }
+    } catch { /* transient network — try again on next tick */ }
+    // Not confirmed yet: the keeper's landing watch says whether the
+    // transaction failed on chain (a keeper without the route: 404, ignored).
+    if (status.status !== 'confirmed') {
+      try {
+        const w = await fetcher(`${baseUrl(opts.keeperUrl)}/renew/status?licenseHash=${encodeURIComponent(opts.licenseHash)}`, { signal: opts.signal });
+        const watch = w.ok ? await w.json() as { status?: string; failureReason?: string } : null;
+        if (watch?.status === 'failed') status = { ...status, status: 'failed', ...(watch.failureReason ? { failureReason: watch.failureReason } : {}) };
+      } catch { /* transient — 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<void>((r) => setTimeout(r, interval));
+  }
+}

package/src/seatName.ts

@@ -0,0 +1,165 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * seatName.ts
+ *
+ * Human-readable device names for the device-binding slot list
+ * ("Silent Otter", "Curious Panda"). Meant for the SDK UI so a buyer
+ * looking at their bound-devices panel sees "the laptop I left in the
+ * office" instead of an opaque device commitment.
+ *
+ * The name is purely cosmetic — the on-chain circuit never gates on it,
+ * verifyOffline never inspects it, and unbind targets `slotIndex`, not
+ * name. It exists solely so the SDK's device-manager UI has something
+ * readable to render next to each slot.
+ *
+ * Names are NOT persisted on-chain and NOT persisted off-chain either —
+ * `seatNameFor` derives the label deterministically from three on-chain
+ * fields (`licenseHash`, `slotIndex`, `boundAtSlot`), so every viewer of
+ * the same license computes the same name for a given occupied slot with
+ * no naming sidecar and no stored state.
+ *
+ * The wordlists are intentionally boring: no scary animals, no negative
+ * adjectives, no cultural landmines, no words with awkward secondary
+ * meanings. Order and word choice are stable — changing them shifts every
+ * slot's name on the next mint, which would be jarring for users looking
+ * at their device list.
+ */
+
+// 250 friendly adjectives. Short, common, unambiguously positive or
+// neutral. Ordering is alphabetical for maintainability — the derivation
+// is index-based so order does not affect behavior.
+const ADJECTIVES: readonly string[] = [
+  'Agile', 'Alert', 'Amber', 'Ample', 'Ancient', 'Apricot', 'Arctic', 'Ashen',
+  'Aspen', 'Autumn', 'Azure', 'Balmy', 'Bashful', 'Beaming', 'Beige', 'Bold',
+  'Bouncy', 'Brave', 'Breezy', 'Bright', 'Brisk', 'Bronze', 'Bubbly', 'Busy',
+  'Calm', 'Candid', 'Cedar', 'Cheery', 'Chic', 'Chipper', 'Chunky', 'Classic',
+  'Clean', 'Clever', 'Cloudy', 'Clumsy', 'Coastal', 'Comet', 'Cool', 'Copper',
+  'Coral', 'Cosmic', 'Cosy', 'Crafty', 'Creamy', 'Crimson', 'Crisp', 'Cuddly',
+  'Curious', 'Daisy', 'Dandy', 'Dapper', 'Daring', 'Dawn', 'Deft', 'Delta',
+  'Devout', 'Dewy', 'Diamond', 'Doughty', 'Dreamy', 'Dusky', 'Dusty', 'Eager',
+  'Earnest', 'Earthy', 'Easy', 'Ebony', 'Elder', 'Elm', 'Ember', 'Emerald',
+  'Epic', 'Fabled', 'Faint', 'Fair', 'Fancy', 'Fearless', 'Feisty', 'Fern',
+  'Fiery', 'Fine', 'Firm', 'Flaxen', 'Fleet', 'Floral', 'Fluffy', 'Foggy',
+  'Fond', 'Forest', 'Frank', 'Freckled', 'Friendly', 'Frosty', 'Frugal', 'Furry',
+  'Fuzzy', 'Gallant', 'Genial', 'Gentle', 'Gilded', 'Ginger', 'Glad', 'Glassy',
+  'Gleaming', 'Glossy', 'Glowing', 'Golden', 'Graceful', 'Grand', 'Grassy',
+  'Green', 'Handy', 'Happy', 'Hardy', 'Hazel', 'Hearty', 'Helpful', 'Honest',
+  'Humble', 'Icy', 'Indigo', 'Inky', 'Iron', 'Ivory', 'Jade', 'Jaunty', 'Jazzy',
+  'Jolly', 'Jovial', 'Joyful', 'Juniper', 'Keen', 'Kind', 'Lanky', 'Lark',
+  'Lavender', 'Lazy', 'Leaf', 'Lilac', 'Limber', 'Lively', 'Lofty', 'Loyal',
+  'Lucky', 'Lush', 'Marble', 'Matte', 'Meadow', 'Mellow', 'Merry', 'Mighty',
+  'Milky', 'Mindful', 'Minty', 'Misty', 'Modest', 'Mossy', 'Nautical', 'Nectar',
+  'Nifty', 'Nimble', 'Noble', 'Nutmeg', 'Oaken', 'Ochre', 'Olive', 'Onyx',
+  'Opal', 'Orange', 'Orchid', 'Pale', 'Patient', 'Peachy', 'Pearl', 'Pebble',
+  'Perky', 'Piney', 'Placid', 'Playful', 'Plucky', 'Plum', 'Plush', 'Polar',
+  'Polite', 'Prairie', 'Proud', 'Prudent', 'Punchy', 'Purple', 'Quaint', 'Quick',
+  'Quiet', 'Radiant', 'Rainy', 'Rapid', 'Rare', 'Ready', 'Ripe', 'River',
+  'Rocky', 'Rosy', 'Royal', 'Ruby', 'Rugged', 'Rustic', 'Saffron', 'Sage',
+  'Sandy', 'Sapphire', 'Scarlet', 'Serene', 'Shady', 'Sharp', 'Shy', 'Silent',
+  'Silken', 'Silky', 'Silver', 'Sincere', 'Sleek', 'Sleepy', 'Slender', 'Small',
+  'Smart', 'Smiling', 'Snowy', 'Solar', 'Solid', 'Sonic', 'Soulful', 'Speedy',
+  'Spirited', 'Splendid', 'Sprightly', 'Spry', 'Starry', 'Steady', 'Stellar',
+  'Sterling', 'Stormy', 'Stout', 'Sunny', 'Sunset', 'Swift', 'Tangy', 'Teal',
+  'Tender', 'Thankful', 'Thoughtful', 'Thrifty', 'Tidy', 'Timber', 'Tiny',
+  'Topaz', 'Tranquil', 'Trusty', 'Turquoise', 'Twilight', 'Upright', 'Valiant',
+  'Velvet', 'Verdant', 'Violet', 'Vivid', 'Warm', 'Whimsical', 'Willow',
+  'Windy', 'Winsome', 'Wise', 'Witty', 'Woodland', 'Woolly', 'Zealous', 'Zesty',
+];
+
+// 250 friendly animals. Common, recognisable, unambiguously non-threatening
+// (no predators-of-humans, no venomous ones, no polarising taxidermy). Two-
+// word species (mountain goat, sea otter) are collapsed to the base name so
+// the final "Adjective Animal" reads cleanly. Ordering is alphabetical.
+const ANIMALS: readonly string[] = [
+  'Alpaca', 'Anteater', 'Antelope', 'Ape', 'Armadillo', 'Auk', 'Aurochs',
+  'Axolotl', 'Baboon', 'Badger', 'Barnacle', 'Bat', 'Beagle', 'Bear', 'Beaver',
+  'Bee', 'Beetle', 'Bison', 'Blackbird', 'Bluebird', 'Boar', 'Bobcat', 'Bonobo',
+  'Booby', 'Buffalo', 'Bulldog', 'Bullfinch', 'Bumblebee', 'Butterfly', 'Camel',
+  'Capybara', 'Cardinal', 'Caribou', 'Cassowary', 'Cat', 'Caterpillar',
+  'Catfish', 'Chameleon', 'Chamois', 'Cheetah', 'Chickadee', 'Chinchilla',
+  'Chipmunk', 'Clam', 'Clownfish', 'Coati', 'Cobra', 'Cockatoo', 'Codfish',
+  'Colt', 'Condor', 'Coot', 'Cormorant', 'Corgi', 'Cougar', 'Cow', 'Coyote',
+  'Crab', 'Crane', 'Cricket', 'Crow', 'Cub', 'Cuckoo', 'Curlew', 'Deer',
+  'Dingo', 'Dolphin', 'Donkey', 'Dormouse', 'Dove', 'Dragonfly', 'Drake',
+  'Duck', 'Duckling', 'Eagle', 'Echidna', 'Eel', 'Egret', 'Elephant', 'Elk',
+  'Emu', 'Falcon', 'Fawn', 'Ferret', 'Finch', 'Firefly', 'Fish', 'Flamingo',
+  'Fox', 'Frog', 'Gecko', 'Gerbil', 'Gibbon', 'Giraffe', 'Gnu', 'Goat',
+  'Godwit', 'Goldfinch', 'Goldfish', 'Goose', 'Gorilla', 'Grebe', 'Griffon',
+  'Grouse', 'Guanaco', 'Guineafowl', 'Gull', 'Guppy', 'Hamster', 'Hare',
+  'Harrier', 'Hawk', 'Hedgehog', 'Heron', 'Herring', 'Hippo', 'Hoatzin',
+  'Hoopoe', 'Hornbill', 'Horse', 'Hound', 'Hummingbird', 'Ibex', 'Ibis',
+  'Iguana', 'Impala', 'Jackal', 'Jackrabbit', 'Jaguar', 'Jay', 'Jellyfish',
+  'Kakapo', 'Kangaroo', 'Kestrel', 'Kingfisher', 'Kinkajou', 'Kite', 'Kitten',
+  'Kiwi', 'Koala', 'Kookaburra', 'Ladybug', 'Lamb', 'Lapwing', 'Lark',
+  'Lemming', 'Lemur', 'Leopard', 'Lion', 'Lizard', 'Llama', 'Lobster',
+  'Lorikeet', 'Loris', 'Lynx', 'Macaque', 'Macaw', 'Magpie', 'Mallard',
+  'Manatee', 'Mandrill', 'Mantis', 'Marmoset', 'Marmot', 'Marten', 'Meerkat',
+  'Mink', 'Minnow', 'Mole', 'Mongoose', 'Monkey', 'Moose', 'Moth', 'Mouse',
+  'Mule', 'Muntjac', 'Muskrat', 'Narwhal', 'Newt', 'Nightingale', 'Numbat',
+  'Nuthatch', 'Ocelot', 'Octopus', 'Okapi', 'Opossum', 'Orangutan', 'Oriole',
+  'Ostrich', 'Otter', 'Owl', 'Ox', 'Oyster', 'Panda', 'Pangolin', 'Panther',
+  'Parakeet', 'Parrot', 'Partridge', 'Peacock', 'Pelican', 'Penguin', 'Perch',
+  'Pheasant', 'Pig', 'Pigeon', 'Piglet', 'Pika', 'Pipit', 'Platypus', 'Plover',
+  'Pointer', 'Polecat', 'Pony', 'Porcupine', 'Porpoise', 'Possum', 'Prawn',
+  'Ptarmigan', 'Puffin', 'Puma', 'Pup', 'Puppy', 'Quail', 'Quokka', 'Rabbit',
+  'Raccoon', 'Ram', 'Rat', 'Raven', 'Reindeer', 'Rhino', 'Roadrunner', 'Robin',
+  'Rook', 'Salamander', 'Salmon', 'Sandpiper', 'Sardine', 'Scallop', 'Seahorse',
+  'Seal', 'Serval', 'Shrew', 'Shrimp', 'Skunk', 'Sloth', 'Snail', 'Snake',
+  'Snipe', 'Sparrow', 'Spider', 'Squid', 'Squirrel', 'Starling', 'Stoat',
+  'Stork', 'Sturgeon', 'Swallow', 'Swan', 'Tamarin', 'Tanager', 'Tapir',
+  'Tarsier', 'Teal', 'Tern', 'Terrier', 'Thrush', 'Tiger', 'Toad', 'Toucan',
+  'Trout', 'Tuna', 'Turkey', 'Turtle', 'Vole', 'Wagtail', 'Walrus', 'Wapiti',
+  'Warbler', 'Wasp', 'Weasel', 'Whale', 'Whippet', 'Wolf', 'Wolverine',
+  'Wombat', 'Woodchuck', 'Woodpecker', 'Wren', 'Yak', 'Zebra',
+];
+
+// Total combinations = ADJECTIVES.length * ANIMALS.length. Exposed for
+// diagnostics and for tests that want to assert the name space is large
+// enough to cover the expected ceiling of licenses × cap.
+export const SEAT_NAME_COMBINATIONS: number = ADJECTIVES.length * ANIMALS.length;
+
+// FNV-1a — a fast, non-cryptographic 32-bit hash. Uniform enough over 250
+// buckets that the modulo bias (~1 in 17M) is invisible in practice. Not
+// used for security; just to derive a stable pair of small indices from
+// the seat's on-chain identity fields.
+function fnv1a(s: string, seed: number): number {
+  let h = seed >>> 0;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+// Deterministic seat-name derivation. Two viewers holding the same
+// `LicenseLeaf` compute the same name for a given occupied slot, without
+// a naming sidecar or any persisted state — the function is a pure fold
+// over three on-chain fields.
+//
+// Key composition — `licenseHash + slotIndex + boundAtSlot`:
+//   - `licenseHash` scopes names to a single license, so slot 0 on
+//     license A doesn't collide with slot 0 on license B.
+//   - `slotIndex` separates concurrent occupants of the same license.
+//   - `boundAtSlot` binds the name to the device-instance in that slot at
+//     that bind moment. Unbind + rebind at the same slotIndex produces
+//     a fresh name, matching the mental model of "the laptop I bound in
+//     March" rather than "seat 0 forever".
+//
+// Empty slots (`boundAtSlot === 0`) are the caller's responsibility to
+// filter — the function returns a valid string for any input rather than
+// throwing, to keep the surface pure. Match on `deviceCommitment !== '0'`
+// or `boundAtSlot > 0` before calling.
+export type SeatNameInput = {
+  licenseHash: string;   // Poseidon-hash decimal string from ProofFile / LicenseRecord
+  slotIndex:   number;   // 0..deviceCap-1
+  boundAtSlot: number;   // Mina slot the bind() tx landed at
+};
+
+export function seatNameFor(input: SeatNameInput): string {
+  const key = `${input.licenseHash}|${input.slotIndex}|${input.boundAtSlot}`;
+  const adj    = ADJECTIVES[fnv1a(key, 0x811c9dc5) % ADJECTIVES.length];
+  const animal = ANIMALS[   fnv1a(key, 0xdeadbeef) % ANIMALS.length];
+  return `${adj} ${animal}`;
+}

package/src/slotConstants.ts

@@ -0,0 +1,18 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * Slot math of the licensing contract (90 s per slot after the Mesa
+ * upgrade), as plain numbers. No o1js: the package root imports these, and
+ * o1js is an optional peer dependency (README, Publishing to npm).
+ * contractInterface re-exports them.
+ */
+
+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 PERPETUAL_SLOTS_N  = 350_640_000; // 1000 × ONE_YEAR_SLOTS_N ("perpetual — until vendor sunset")
+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