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

package/src/trustAnchorVerifyCli.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * trustAnchorVerifyCli.ts
+ *
+ * Command-line front-end for verifyTrustAnchor(). Ships as the `zklicensing-verify-trust`
+ * bin — the sibling of `zklicensing-verify` (which is the verifyService HTTP daemon).
+ *
+ * Usage:
+ *   zklicensing-verify-trust \
+ *     --origin https://store.example.com \
+ *     --address B62q... \
+ *     --pinned-key <base64-ed25519-pubkey> \
+ *     [--mina-graphql https://api.minascan.io/node/mainnet/v1/graphql] \
+ *     [--mina-network-id mainnet|testnet|devnet] \
+ *     [--skip-chain-checks] \
+ *     [--json]
+ *
+ * The manifest lives at `<origin>/.well-known/zklicensing/<address>.json` —
+ * one file per generation address, all signed by the same platform key. The
+ * appId is read out of the signed payload; callers never need to know it
+ * out-of-band, which lets buyers verify from just the address their wallet
+ * shows them (including addresses for retired generations).
+ *
+ * Permit registries:
+ *   zklicensing-verify-trust --registry B62q... [--origin https://authority.example]
+ *     [--mina-network-id mainnet|devnet] [--keeper-url https://zklicensing.com/api/keeper]
+ *     [--no-well-known] [--mina-graphql <url>] [--json]
+ * checks the registry's verification key against the published PermitRegistry
+ * hashes, its locked permissions and network binding, the authority website
+ * written into it at deploy (on the --origin host, when given) and that the
+ * website's /.well-known/zkpermits/<address>.json claims it, and (with
+ * --keeper-url) that the keeper's authority keys, payout and website match.
+ *
+ * Exit codes:
+ *   0 — every finding passed
+ *   1 — one or more findings failed
+ *   2 — invalid arguments
+ *
+ * --pinned-key is required and may be repeated; the CLI ships NO baked-in
+ * pin. Source it from https://zklicensing.com/trustanchor.html (published
+ * next to each generation's VK hash). See the SDK README for details.
+ */
+
+import { verifyTrustAnchor, type Finding, type TrustAnchorReport } from './trustAnchorVerify.js';
+import { verifyRegistryTrust } from './registryTrustVerify.js';
+
+type Args = {
+  origin?: string;
+  address?: string;
+  registry?: string;
+  keeperUrl?: string;
+  pinnedKeys: string[];
+  // undefined = fall back to DEFAULT_GRAPHQL[minaNetworkId] at resolve time,
+  // so `--mina-network-id devnet` alone auto-picks the devnet endpoint even
+  // when the user doesn't pass --mina-graphql.
+  minaGraphql?: string;
+  minaNetworkId: 'mainnet' | 'devnet';
+  skipChainChecks: boolean;
+  crossCheck: boolean;
+  wellKnown: boolean;
+  json: boolean;
+  help: boolean;
+};
+
+const DEFAULT_GRAPHQL: Record<Args['minaNetworkId'], string> = {
+  mainnet: 'https://api.minascan.io/node/mainnet/v1/graphql',
+  // O1 Labs' devnet-plain node is the reliable public endpoint for freshly
+  // deployed accounts — public indexers like Minascan lag by several slots
+  // and often return null for a zkApp minutes after landing.
+  devnet:  'https://devnet-plain-1.gcp.o1test.net/graphql',
+};
+
+function usage(): string {
+  return [
+    'zklicensing-verify-trust — verify a vendor page + on-chain zkApp mutually bind',
+    '',
+    'Required:',
+    '  --origin <url>        Vendor origin (https://...)',
+    '  --address <B62q...>   zkApp address (the address your wallet shows you)',
+    '  --pinned-key <b64>    Platform manifest pubkey (repeatable during rotation)',
+    '',
+    'Or, for a permit registry:',
+    '  --registry <B62q...>  Registry address; checks VK, permissions, network,',
+    '                        the website bound at deploy and its .well-known claim',
+    '  --origin <url>        The authority website you expect (compared by host)',
+    '  --keeper-url <url>    Also compare the keeper\'s authority keys, payout, website',
+    '  --no-well-known       Skip fetching <website>/.well-known/zkpermits/<registry>.json',
+    '',
+    'Optional:',
+    '  --mina-graphql <url>         Mina GraphQL endpoint (default depends on',
+    '                               --mina-network-id: mainnet →',
+    `                               ${DEFAULT_GRAPHQL.mainnet};`,
+    `                               devnet → ${DEFAULT_GRAPHQL.devnet})`,
+    '  --mina-network-id <id>       mainnet | devnet (default: devnet)',
+    '  --skip-chain-checks          Manifest-only audit — no o1js chain reads',
+    '  --no-cross-check             Skip the platform backend cross-check',
+    '                               (default: on — verifies vendor manifest matches',
+    '                               https://zklicensing.com/apps/by-address/<address>)',
+    '  --json                       Emit TrustAnchorReport as JSON on stdout',
+    '',
+    'Exit: 0 all-ok · 1 any check failed · 2 bad args',
+  ].join('\n');
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    pinnedKeys: [],
+    minaNetworkId: 'devnet',
+    skipChainChecks: false,
+    // Default on — the platform backend cross-check is cheap and catches
+    // vendors whose local manifest has drifted from the signed platform
+    // record. Opt out with --no-cross-check for a pure origin+chain audit.
+    crossCheck: true,
+    wellKnown: true,
+    json: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`missing value for ${a}`);
+      return v;
+    };
+    switch (a) {
+      case '--origin': args.origin = next(); break;
+      case '--address': args.address = next(); break;
+      case '--registry': args.registry = next(); break;
+      case '--keeper-url': args.keeperUrl = next(); break;
+      case '--pinned-key': args.pinnedKeys.push(next()); break;
+      case '--mina-graphql': args.minaGraphql = next(); break;
+      case '--mina-network-id': {
+        const v = next();
+        if (v !== 'mainnet' && v !== 'devnet') {
+          throw new Error(`--mina-network-id must be mainnet|devnet, got "${v}"`);
+        }
+        args.minaNetworkId = v;
+        break;
+      }
+      case '--skip-chain-checks': args.skipChainChecks = true; break;
+      case '--no-well-known': args.wellKnown = false; break;
+      // Kept as a no-op flag so any existing invocation that passed
+      // --cross-check keeps working. --no-cross-check opts out.
+      case '--cross-check': args.crossCheck = true; break;
+      case '--no-cross-check': args.crossCheck = false; break;
+      case '--json': args.json = true; break;
+      case '-h':
+      case '--help': args.help = true; break;
+      default: throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return args;
+}
+
+function formatHuman(report: TrustAnchorReport): string {
+  const lines: string[] = [];
+  const banner = report.ok ? 'TRUST ANCHOR VERIFIED' : 'TRUST ANCHOR FAILED';
+  lines.push(banner);
+  lines.push(`  origin:     ${report.origin}`);
+  lines.push(`  address:    ${report.address}`);
+  if (report.appId) lines.push(`  appId:      ${report.appId}`);
+  if (report.generation !== undefined) lines.push(`  generation: ${report.generation}`);
+  lines.push('');
+  for (const f of report.findings) {
+    const mark = f.ok ? '[ok]  ' : '[FAIL]';
+    lines.push(`  ${mark} ${f.name} — ${f.detail}`);
+  }
+  return lines.join('\n');
+}
+
+async function main(): Promise<number> {
+  let args: Args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err: any) {
+    process.stderr.write(`${err.message}\n\n${usage()}\n`);
+    return 2;
+  }
+  if (args.help) {
+    process.stdout.write(`${usage()}\n`);
+    return 0;
+  }
+  if (args.registry) {
+    const report = await verifyRegistryTrust({
+      address: args.registry, network: args.minaNetworkId, minaGraphqlUrl: args.minaGraphql, keeperUrl: args.keeperUrl,
+      website: args.origin, checkWellKnown: args.wellKnown,
+    });
+    if (args.json) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    else {
+      process.stdout.write([report.ok ? 'REGISTRY VERIFIED' : 'REGISTRY FAILED', `  registry: ${report.address}`, `  network:  ${report.network}`, '',
+        ...(report.findings.some(f => f.name === 'website_claims_registry' && !f.ok) ? [`  The authority publishes the claim at <website>/.well-known/zkpermits/${report.address}.json`, ''] : []),
+        ...report.findings.map(f => `  ${f.ok ? '[ok]  ' : '[FAIL]'} ${f.name} — ${f.detail}`)].join('\n') + '\n');
+    }
+    return report.ok ? 0 : 1;
+  }
+  const missing: string[] = [];
+  if (!args.origin) missing.push('--origin');
+  if (!args.address) missing.push('--address');
+  if (args.pinnedKeys.length === 0) missing.push('--pinned-key');
+  if (missing.length > 0) {
+    process.stderr.write(`missing required argument(s): ${missing.join(', ')}\n\n${usage()}\n`);
+    return 2;
+  }
+  const report = await verifyTrustAnchor({
+    origin: args.origin!,
+    address: args.address!,
+    pinnedPublicKeysBase64: args.pinnedKeys,
+    minaGraphqlUrl: args.minaGraphql ?? DEFAULT_GRAPHQL[args.minaNetworkId],
+    minaNetworkId: args.minaNetworkId,
+    skipChainChecks: args.skipChainChecks,
+    crossCheck: args.crossCheck,
+  });
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${formatHuman(report)}\n`);
+  }
+  return report.ok ? 0 : 1;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`unexpected error: ${err?.stack ?? err}\n`);
+    process.exit(1);
+  },
+);
+
+// Silence unused-import warning when someone bundles the module (Finding is
+// re-exported here for consumers that import from the CLI module directly).
+export type { Finding };

package/src/txBroadcastClient.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * txBroadcastClient.ts
+ *
+ * Small helper for POST /tx-broadcast. Called by the buy/renew/migrate
+ * flows immediately after the buyer's wallet returns a txHash — signals
+ * the backend to extend the app's in-flight slot from the short signing-TTL
+ * to the longer landing-TTL, so concurrent buyers on the same app don't
+ * think the slot has expired while an honest signed tx is still in the
+ * mempool.
+ *
+ * Fire-and-forget by design: this is a tightening signal, not a
+ * correctness dependency. Land-clear in the buy-watcher and the
+ * signing-TTL both remain live regardless of whether this call succeeds.
+ * Failures are swallowed with an optional log callback so a network blip
+ * doesn't surface as a confusing error mid-checkout.
+ */
+
+export type NotifyBroadcastRequest = {
+  keeperUrl: string;
+  appId:     string;
+  txHash:    string;
+  fetcher?:  typeof fetch;
+  signal?:   AbortSignal;
+  // Optional hook for surfacing swallowed failures to the caller's logger.
+  // Not called on the happy path.
+  onError?:  (err: unknown) => void;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+export async function notifyBroadcast(req: NotifyBroadcastRequest): Promise<void> {
+  const fetcher = req.fetcher ?? fetch;
+  try {
+    await fetcher(`${baseUrl(req.keeperUrl)}/tx-broadcast`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      signal: req.signal,
+      body: JSON.stringify({ appId: req.appId, txHash: req.txHash }),
+    });
+  } catch (err) {
+    req.onError?.(err);
+  }
+}

package/src/unbindClient.ts

@@ -0,0 +1,233 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * unbindClient.ts
+ *
+ * Browser-safe client for the non-custodial device-unbinding flow.
+ * Mirrors `bindClient.ts` in shape: signs the unbind message with
+ * TAG_UNBINDING, POSTs to /prove/unbind, then /confirm/unbind after
+ * the wallet returns a txHash.
+ *
+ * Notable asymmetry with bind: the unbind message shape carries the
+ * deviceCommitment position too, but the backend and circuit both
+ * hard-code it to `Field(0)` (the "not about any specific new
+ * device" sentinel — the message is about freeing a slot, not
+ * introducing a new device). The SDK matches by omitting
+ * deviceCommitment from the request and using "0" when computing
+ * the signature preimage.
+ *
+ * Non-custodial invariant: the signature is re-verified in-circuit
+ * against the leaf's `licenseHash` (which IS the owner-pubkey
+ * commitment — the circuit asserts equality at buy time), so no
+ * backend / vendor can unilaterally kick a device — only the
+ * passphrase holder can.
+ * A user who lost the physical device but still has the passphrase
+ * can unbind the missing device's slot from any device that holds
+ * the ownership key (the "remote log-off" case).
+ */
+
+import { Field, PrivateKey, PublicKey, Signature } from 'o1js';
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import { encodePublicKey, encodeSignature, signUnbinding } from './ownershipSignature.js';
+import { fetchBindingState } from './bindClient.js';
+
+export type ProveUnbindRequest = {
+  keeperUrl:       string;
+  network:         'devnet' | 'mainnet';
+  zkAppAddress:    string;
+  licenseHash:     string;
+  ownerPrivateKey: PrivateKey;
+  // Which slot (0..cap-1) to free.
+  slotIndex:       number;
+  buyerAddress:    string;
+  // Optional nonce override. Sampled fresh (128-bit random) when
+  // omitted — same shape as bindClient.
+  nonce?:          string;
+  // Optional overrides for the state the signature commits to — same
+  // semantics as ProveBindRequest.slotState / expirySlot.
+  slotState?:      string;
+  expirySlot?:     number;
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+export type ProveUnbindResponse = {
+  provenTxJson: string;
+  licenseHash:  string;
+  slotIndex:    number;
+};
+
+export type ConfirmUnbindRequest = {
+  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}`;
+}
+
+function freshNonce(): string {
+  const crypto = (globalThis as any).crypto as Crypto | undefined;
+  if (!crypto?.getRandomValues) {
+    throw new Error(
+      'crypto.getRandomValues unavailable — unbindClient requires Node ≥ 20 or a modern browser',
+    );
+  }
+  const bytes = new Uint8Array(16); // 128 bits
+  crypto.getRandomValues(bytes);
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return Field(n).toString();
+}
+
+// POST /prove/unbind — same retry contract as /prove/bind. Returns
+// 409 `ProveQueueBusyError` when another root-mutating tx for the
+// same app is in flight; the caller retries with the server-supplied
+// `retryAfterMs` cadence.
+export async function proveUnbind(req: ProveUnbindRequest): Promise<ProveUnbindResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const nonce = req.nonce ?? freshNonce();
+  const { slotState, expirySlot } = (req.slotState !== undefined && req.expirySlot !== undefined)
+    ? { slotState: req.slotState, expirySlot: req.expirySlot }
+    : await fetchBindingState({ ...req, fetcher });
+
+  const ownerPubKey: PublicKey = req.ownerPrivateKey.toPublicKey();
+  // deviceCommitment=0 for the preimage — matches TAG_UNBINDING's
+  // circuit-side check (see verifyUnbinding / bindingLikeFields in
+  // ownershipSignature.ts).
+  const ownerSig: Signature = signUnbinding(req.ownerPrivateKey, {
+    licenseHash:      req.licenseHash,
+    deviceCommitment: '0',
+    slotIndex:        req.slotIndex,
+    nonce,
+    slotState,
+    expirySlot,
+    zkAppAddress:     req.zkAppAddress,
+  });
+
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/unbind`, {
+    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,
+      ownerPubKey:  encodePublicKey(ownerPubKey),
+      ownerSig:     encodeSignature(ownerSig),
+      slotIndex:    req.slotIndex,
+      nonce,
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveUnbindResponse;
+}
+
+// POST /confirm/unbind — pass-through no-op mirror of /confirm/bind.
+export async function confirmUnbind(req: ConfirmUnbindRequest): Promise<{ ok: true }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/unbind`, {
+    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 };
+}
+
+export type UnbindStatus = {
+  // 'confirmed' once eventSync has observed the DeviceUnbound event and
+  // the target slot's commitment has flipped back to '0'. 'pending' while
+  // the tx is in flight. 'unknown' if the license record hasn't been
+  // persisted yet.
+  status: 'confirmed' | 'pending' | 'unknown';
+  slotIndex?:        number;
+  deviceCommitment?: string;
+  elapsedMs?:        number;
+};
+
+export type PollUnbindStatusOptions = {
+  keeperUrl:    string;
+  network:      'devnet' | 'mainnet';
+  zkAppAddress: string;
+  licenseHash:  string;
+  slotIndex:    number;
+  fetcher?:     typeof fetch;
+  intervalMs?:  number;  // default 10 000
+  timeoutMs?:   number;  // default 20 min
+  signal?:      AbortSignal;
+  onTick?:      (status: UnbindStatus) => void;
+};
+
+// Polls GET /license/:zkAppAddress/:licenseHash until the unbind has
+// landed on-chain (the target slot's commitment is '0') or the timeout
+// fires. Mirrors pollBindStatus in shape.
+export async function pollUnbindStatus(opts: PollUnbindStatusOptions): Promise<UnbindStatus> {
+  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('pollUnbindStatus aborted');
+    let status: UnbindStatus = { 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;
+          devices?: Array<{ slotIndex: number; deviceCommitment: string }>;
+        };
+        if (body.found) {
+          const slot = (body.devices ?? []).find(d => d.slotIndex === opts.slotIndex);
+          const commitment = slot?.deviceCommitment ?? '0';
+          if (commitment === '0') {
+            status = {
+              status: 'confirmed',
+              slotIndex: opts.slotIndex,
+              deviceCommitment: commitment,
+              elapsedMs: Date.now() - startedAt,
+            };
+          } else {
+            status = {
+              status: 'pending',
+              slotIndex: opts.slotIndex,
+              deviceCommitment: commitment,
+              elapsedMs: Date.now() - startedAt,
+            };
+          }
+        }
+      }
+    } catch { /* transient network — try again on next tick */ }
+    opts.onTick?.(status);
+    if (status.status === 'confirmed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}

package/src/units.ts

@@ -0,0 +1,74 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * units.ts — the unit amounts are shown in.
+ *
+ * Devnet amounts are test MINA (tMINA), which has no value; mainnet amounts
+ * are MINA. Only what people read changes: field names (`priceYearlyMina`,
+ * nanomina amounts) stay the same on both networks. The MINA price in euros
+ * or dollars is real and still shown on devnet, but only as a reference for
+ * mainnet MINA (`fiatReference`), never as the value of tMINA.
+ */
+
+import { isEuCountry } from './taxId.js';
+
+export type MinaUnit = 'MINA' | 'tMINA';
+
+/** 'tMINA' on devnet (and any test network), 'MINA' on mainnet. */
+export function minaUnit(network: string): MinaUnit {
+  return network === 'mainnet' ? 'MINA' : 'tMINA';
+}
+
+/** "12.5 tMINA" / "12.5 MINA" for an amount in MINA (number or decimal string). */
+export function formatMina(amountMina: number | string, network: string): string {
+  return `${amountMina} ${minaUnit(network)}`;
+}
+
+/** "12.5 tMINA" for an amount in nanomina. */
+export function formatNanomina(nano: bigint | string | number, network: string): string {
+  const n = BigInt(nano);
+  const neg = n < 0n;
+  const a = neg ? -n : n;
+  const frac = (a % 1_000_000_000n).toString().padStart(9, '0').replace(/0+$/, '');
+  return `${neg ? '-' : ''}${(a / 1_000_000_000n).toString()}${frac ? '.' + frac : ''} ${minaUnit(network)}`;
+}
+
+/**
+ * The words that go with a fiat value. Mainnet: "≈ €2.10". Devnet: the same
+ * amount of real MINA, said as such ("as MINA ≈ €2.10"), plus a note that
+ * tMINA itself has no value.
+ */
+export function fiatReference(network: string): { prefix: string; note: string | null } {
+  return network === 'mainnet'
+    ? { prefix: '≈', note: null }
+    : { prefix: 'as MINA ≈', note: 'tMINA has no value; this is what the same amount of mainnet MINA is worth.' };
+}
+
+export type FiatCurrency = 'eur' | 'usd' | 'gbp';
+const SYMBOL: Record<FiatCurrency, string> = { eur: '€', usd: '$', gbp: '£' };
+
+/**
+ * Which money a person sees amounts in, by their country: euros in the EU,
+ * pounds and euros in the UK, dollars in the US, euros and dollars elsewhere
+ * (or when the country is unknown).
+ */
+export function fiatCurrencies(country?: string | null): FiatCurrency[] {
+  const c = String(country ?? '').trim().toUpperCase();
+  if (isEuCountry(c)) return ['eur'];
+  if (c === 'GB' || c === 'UK') return ['gbp', 'eur'];
+  if (c === 'US') return ['usd'];
+  return ['eur', 'usd'];
+}
+
+/** "€2.10", "-€26.78" for an amount of money. */
+export function formatFiat(amount: number | string, currency: FiatCurrency, digits = 2): string {
+  const n = typeof amount === 'string' ? Number(amount) : amount;
+  return `${n < 0 ? '-' : ''}${SYMBOL[currency]}${Math.abs(n).toFixed(digits)}`;
+}
+
+/** "€2.10 · $2.30" for the given currencies (a currency without a rate is left out). */
+export function formatFiatList(values: Partial<Record<FiatCurrency, number | string>>, currencies: FiatCurrency[], digits = 2): string {
+  return currencies.filter(c => values[c] !== undefined && values[c] !== null && values[c] !== '')
+    .map(c => formatFiat(values[c]!, c, digits)).join(' · ');
+}

package/src/vatRates.ts

@@ -0,0 +1,100 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * vatRates.ts — `zklicensing/vat`
+ *
+ * Standard VAT rates (EU member states and the UK, with their history) and
+ * the VAT included in a VAT-inclusive price. Prices on zkLicensing are fixed
+ * per tier on-chain and include VAT: a buyer pays the listed price, and the
+ * VAT in it is at the buyer's country's standard rate on the sale date.
+ *
+ *   standardVatRate('FI', '2026-10-13')          → 25.5
+ *   vatIncludedNano(10_000_000_000n, 25.5)       → { netNano: 7_968_127_490n, vatNano: 2_031_872_510n }
+ *
+ * For vendors' own reporting and buyers' information — an estimate for
+ * consumer sales, not tax advice: business buyers with a VAT number are
+ * usually reverse-charged, and the EU's €10,000 cross-border threshold is
+ * not applied. Countries without VAT in the table give null.
+ */
+
+import { STANDARD_VAT_RATES, VAT_RATES_FETCHED, VAT_RATES_SOURCE } from './vatRatesData.js';
+
+export { VAT_RATES_FETCHED, VAT_RATES_SOURCE };
+
+function isoDay(date: Date | string | number): string {
+  const d = date instanceof Date ? date : new Date(date);
+  if (!Number.isFinite(d.getTime())) throw new Error('invalid date');
+  return d.toISOString().slice(0, 10);
+}
+
+/** The standard VAT rate (percent) in force in `country` on `date`, or null if the country isn't in the table. */
+export function standardVatRate(country: string, date: Date | string | number = new Date()): number | null {
+  const c = String(country ?? '').toUpperCase();
+  const periods = Object.prototype.hasOwnProperty.call(STANDARD_VAT_RATES, c) ? STANDARD_VAT_RATES[c] : undefined;
+  if (!periods) return null;
+  const day = isoDay(date);
+  let rate: number | null = null;
+  for (const [from, r] of periods) if (from <= day) rate = r;
+  return rate;
+}
+
+/** Countries in the table (ISO codes). */
+export function vatCountries(): string[] {
+  return Object.keys(STANDARD_VAT_RATES);
+}
+
+const bp = (ratePct: number) => {
+  if (!Number.isFinite(ratePct) || ratePct < 0 || ratePct >= 100) throw new Error('rate must be a percentage in [0, 100)');
+  return BigInt(Math.round(ratePct * 100));
+};
+
+/** The VAT included in a VAT-inclusive `totalNano` at `ratePct`: vat = total × r / (100 + r), rounded to the nearest nanomina. */
+export function vatIncludedNano(totalNano: bigint, ratePct: number): { netNano: bigint; vatNano: bigint } {
+  if (totalNano < 0n) throw new Error('total must not be negative');
+  const r = bp(ratePct);
+  const den = 10_000n + r;
+  const vatNano = (totalNano * r * 2n + den) / (den * 2n);
+  return { netNano: totalNano - vatNano, vatNano };
+}
+
+/** Same, for a MINA amount (display only). */
+export function vatIncludedMina(totalMina: number, ratePct: number): { net: number; vat: number } {
+  const { netNano, vatNano } = vatIncludedNano(BigInt(Math.round(totalMina * 1e9)), ratePct);
+  return { net: Number(netNano) / 1e9, vat: Number(vatNano) / 1e9 };
+}
+
+/** The price shown to a buyer in `country` on `date`: the total, and the VAT it includes. Null rate outside the table. */
+export function priceWithVat(totalNano: bigint, country: string, date: Date | string | number = new Date()):
+  { totalNano: bigint; country: string; rate: number | null; netNano: bigint; vatNano: bigint } {
+  const rate = standardVatRate(country, date);
+  const split = rate === null ? { netNano: totalNano, vatNano: 0n } : vatIncludedNano(totalNano, rate);
+  return { totalNano, country: String(country).toUpperCase(), rate, ...split };
+}
+
+/** The VAT block of a license receipt (amounts as decimal MINA strings). */
+export type VatReceipt = {
+  country: string;
+  /** Standard rate (percent) on the sale date; null when the country has no VAT in the table. */
+  ratePct: number | null;
+  totalMina: string;
+  vatMina: string;
+  netMina: string;
+  /** Which rates table was used. */
+  rates: string;
+};
+
+const minaString = (nano: bigint) => {
+  const s = nano.toString().padStart(10, '0');
+  return `${s.slice(0, -9)}.${s.slice(-9)}`.replace(/\.?0+$/, '') || '0';
+};
+
+/** The VAT included in a purchase of `totalNano` by a buyer in `country` on `date`, for the license file. */
+export function vatReceipt(totalNano: bigint, country: string, date: Date | string | number = new Date()): VatReceipt {
+  const p = priceWithVat(totalNano, country, date);
+  return {
+    country: p.country, ratePct: p.rate,
+    totalMina: minaString(p.totalNano), vatMina: minaString(p.vatNano), netMina: minaString(p.netNano),
+    rates: `${VAT_RATES_SOURCE}, ${VAT_RATES_FETCHED}`,
+  };
+}