zklicensing 0.1.0-beta.15 → 0.1.0-beta.17

package/README.md

@@ -76,7 +76,7 @@ type VerifyResult = {
 function verifyLicense(proof: ProofInput, options?: VerifyOptions): Promise<VerifyResult>;
 ```
 
-The refund-window decision is server-side: the verifier returns `refundWindowClosed: boolean` on its `/verify` response, computed from its own `purchaseSlot` record against the on-chain `currentSlot`. The SDK gates anchor writes on that boolean and never trusts a `purchaseSlot` supplied by the local proof file, so a user who forges their proof metadata cannot force the offline branch prematurely.
+The refund-window decision is server-side: the verifier returns `refundWindowClosed: boolean` on its `/verify` response, computed from its own `purchaseSlot` record against the on-chain `currentSlot`. The SDK gates anchor writes on that boolean and never trusts a `purchaseSlot` supplied by the local license file, so a user who forges their proof metadata cannot force the offline branch prematurely.
 
 The package also re-exports the three constants the SDK uses internally:
 
@@ -135,7 +135,7 @@ await confirmBind({ keeperUrl, zkAppAddress, licenseHash, txHash });
 - Unbinding stamps `freedAt = currentSlot`; the slot cannot be re-bound until `COOLDOWN_SLOTS_N = 6_720` slots (≈ 7 days at 90 s/slot) have elapsed. The cooldown is a flat one-week wait for every tier (monthly, yearly, five-year), independent of `deviceCap` — one number to reason about, not a per-tier formula.
 - `deviceCap = 0` disables binding entirely — `bind()` rejects with "bindings disabled" and no slot state is written to the leaf.
 - Cap is committed to the leaf at buy time and immutable for the life of the license. A vendor cannot tighten enforcement retroactively.
-- Bindings survive cross-generation migration: `migrateLicense` copies the ancestor leaf verbatim (including the device slot array) into the successor tree.
+- Bindings survive a redeploy: the successor starts with its predecessor's licenses tree as it was at retirement (device slots included), checked on chain.
 
 **Offline verification.** After bind, the SDK caches the leaf's slot array locally. `verifyOffline` compares the device's local Poseidon commitment against `occupiedSlot[]`; a stolen laptop's commitment vanishing from the slot array denies access on the next launch without any network call.
 
@@ -229,7 +229,7 @@ Three drop-in pages, one SDK. Fork them, restyle, ship.
 - **`examples/renew.html`** — one click, one wallet prompt.
 - **`examples/refund.html`** — 14-day window, handled.
 - **`examples/bind.html`** / **`examples/unbind.html`** — device-slot writes for `deviceCap > 0` apps.
-- **`examples/verify.html`** — non-custodial verify: paste proof.json → witness + record from the service, root from Mina, folded locally.
+- **`examples/verify.html`** — non-custodial verify: paste license file → witness + record from the service, root from Mina, folded locally.
 
 Each page is a self-contained HTML + TS pair calling one SDK subpath.
 
@@ -262,13 +262,13 @@ The main entry point (`zklicensing`) covers licence verification. Additional ent
 
 ### Per-app in-flight proving guard
 
-`/prove/buy`, `/prove/buy-no-escrow`, `/prove/renew`, `/prove/migrate`, and `/prove/refund` all mutate the same on-chain `licensesRoot` (and, for buy/refund, `escrowRoot`) preconditions. Two proofs assembled against the same pre-state root within one landing window are mutually exclusive — the chain admits whichever lands first, the second's precondition fails and the tx is dropped. Left unguarded, the second buyer pays the wallet-popup + fee for a doomed tx.
+`/prove/buy`, `/prove/buy-no-escrow`, `/prove/renew`, and `/prove/refund` all mutate the same on-chain `licensesRoot` (and, for buy/refund, `escrowRoot`) preconditions. Two proofs assembled against the same pre-state root within one landing window are mutually exclusive — the chain admits whichever lands first, the second's precondition fails and the tx is dropped. Left unguarded, the second buyer pays the wallet-popup + fee for a doomed tx.
 
-The keeper defends against this with a **per-app in-flight slot** shared across all five endpoints. While the slot is held, a second concurrent request for the same app receives an immediate `409 { error: "proving queue busy", retryAfterMs, queueDepth }` — before any circuit work or wallet prompt. The SDK surfaces this as a shared `ProveQueueBusyError` (from `zklicensing/prove-errors`) thrown by `proveBuy`, `proveRenew`, `proveMigrate`, and `proveRefund`. Callers wait `retryAfterMs`, then retry — no popup, no fee, no signed-tx-doomed-to-fail.
+The keeper defends against this with a **per-app in-flight slot** shared across all four endpoints. While the slot is held, a second concurrent request for the same app receives an immediate `409 { error: "proving queue busy", retryAfterMs, queueDepth }` — before any circuit work or wallet prompt. The SDK surfaces this as a shared `ProveQueueBusyError` (from `zklicensing/prove-errors`) thrown by `proveBuy`, `proveRenew`, and `proveRefund`. Callers wait `retryAfterMs`, then retry — no popup, no fee, no signed-tx-doomed-to-fail.
 
 Each prove response carries an `appKey` field — the same value the keeper uses to key the slot. After the wallet returns a tx hash, the SDK client calls `notifyBroadcast({ keeperUrl, appId: appKey, txHash })` (from `zklicensing/tx-broadcast`, fire-and-forget) to extend the slot's TTL from signing-TTL to landing-TTL, giving the honest broadcast room to land before another prove goes through.
 
-See [`zklicensing/prove-errors`](#zklicensingprove-errors--shared-typed-errors) and [`zklicensing/tx-broadcast`](#zklicensingtx-broadcast--broadcast-signal) below; each of `zklicensing/buy`, `zklicensing/renew`, `zklicensing/migrate` references this contract.
+See [`zklicensing/prove-errors`](#zklicensingprove-errors--shared-typed-errors) and [`zklicensing/tx-broadcast`](#zklicensingtx-broadcast--broadcast-signal) below; each of `zklicensing/buy` and `zklicensing/renew` references this contract.
 
 ### `zklicensing/deploy` — deploy flow client
 
@@ -294,9 +294,11 @@ const status = await pollDeployStatus({ keeperUrl, zkAppAddress });
 
 The SDK does not expose a raw `initialize()` helper. `initialize()` sets `vendor` on-chain and is guarded only by a `vendor.requireEquals(PublicKey.empty())` precondition — no in-circuit signature check (adding one collides with the proof-based `editState` permission that `deploy()` installs). Front-running is prevented operationally instead: the backend puts `deploy()` and `initialize()` in the same `Mina.transaction`, and the throwaway zkApp keypair is generated inside the handler and dropped at return, so the target address is not observable to an attacker until the initialize AU is already signed and locked to `(vendor, prices)`. Drivers bypassing `proveDeploy` are responsible for the same discipline.
 
-#### Post-hardfork redeploy
+#### Redeploy (hard fork)
 
-After a Mina hardfork relaxes `impossibleDuringCurrentVersion` back to `signature()`, every existing zkApp becomes uneditable in place (deploy keys are already discarded). Vendors migrate their app to a fresh v2 address themselves. Authentication is a Mina signature against the on-chain vendor of the target app, and the vendor pays gas via their own fee-payer AU. Three-step flow, mirroring the first-time deploy:
+A redeploy moves an app to a fresh zkApp address in two on-chain steps. **Retire**: the old app, with an empty escrow, freezes its licenses tree; the vendor's key (or the platform key, on a platform redeploy) signs it. **Successor**: the new app starts with that frozen tree — its initialization checks on chain that the predecessor is retired at that root with the same vendor, prices and device cap, and its `appCreated` event names the predecessor. Licenses carry on there under the same hashes; nothing for buyers to do. Before a hard fork only the retire happens (the old circuit can't prove after the fork); the successor follows after it. A license that lapsed during the pre-fork sales freeze renews from the fork slot (`effectiveExpirySlot`).
+
+Authentication is a Mina signature against the on-chain vendor of the target app, and the vendor's wallet pays for every step (the retire and the successor), as the admin wallet does on a platform redeploy: the keeper proves each step and holds no key.
 
 ```ts
 import {
@@ -306,39 +308,34 @@ import {
   pollDeployStatus,
 } from 'zklicensing/deploy';
 
-// 1. Ask the backend for a single-use signing challenge.
-const { nonce } = await getVendorRedeployChallenge({ keeperUrl, appId });
-
-// 2. Vendor's wallet signs the nonce (Auro / Mina wallet's mina_signMessage
-//    or the equivalent that returns a Signature.toObject() form).
-const signature = await wallet.signMessage(nonce); // { field, scalar }
-
-// 3. Backend verifies signature against on-chain vendor, runs all redeploy
-//    guards, generates a throwaway zkApp keypair, and returns the proven tx
-//    for the wallet to sign + broadcast.
-const { provenTxJson, zkAppAddress, redeployId } = await proveVendorRedeploy({
-  keeperUrl, appId,
-  nonce,
-  signature,
-  senderPublicKey: vendorAddress, // fee payer
-  // force: true,                  // optional — bypass escrow-empty guard
-});
-
-// 4. Wallet adds the fee-payer signature and broadcasts (same as proveDeploy).
-const { hash: txHash } = await wallet.sendTransaction({ transaction: provenTxJson });
-
-// 5. Register the pending redeploy so the backend arms its deploy-watcher.
-//    On landing, the backend promotes the new deployment onto the AppRecord
-//    (push old to deploymentHistory[], overwrite live fields, clear sync cursors).
-await registerVendorRedeploy({ keeperUrl, appId, redeployId, txHash });
+let retireSignature: string | undefined;
+for (;;) {
+  // 1. A single-use signing challenge (one per prove call), signed by the vendor's wallet.
+  const { nonce } = await getVendorRedeployChallenge({ keeperUrl, appId });
+  const signature = await wallet.signMessage(nonce); // { field, scalar }
+
+  // 2. The backend verifies the signature against the on-chain vendor, runs
+  //    the redeploy guards and answers with the next step.
+  const r = await proveVendorRedeploy({ keeperUrl, appId, nonce, signature, senderPublicKey: vendorAddress, retireSignature });
+  if ('status' in r && r.status === 'draining') break;           // sales paused; come back after r.readyAt
+  if ('status' in r && r.status === 'sign-retire') {             // the vendor signs the retirement
+    retireSignature = await wallet.signFields(r.retireMessage);  // base58
+    continue;
+  }
 
-// 6. Poll for landing.
-await pollDeployStatus({ keeperUrl, zkAppAddress });
+  // 3. The wallet adds the fee-payer signature, sends and pays for the step.
+  const { hash: txHash } = await wallet.sendTransaction({ transaction: r.provenTxJson });
+  // 4. Register it: a retire is marked (before a fork; the successor follows
+  //    after it), a deploy is promoted when it lands.
+  await registerVendorRedeploy({ keeperUrl, appId, redeployId: r.redeployId, txHash });
+  if (r.step !== 'retire') await pollDeployStatus({ keeperUrl, zkAppAddress: r.zkAppAddress });
+  break;
+}
 ```
 
-Guards enforced by the backend before proving: freeze slot configured, refund window closed past `FREEZE_AFTER_SLOT + REFUND_WINDOW`, app status `active`, on-chain version in `SUPPORTED_LICENSING_APP_VERSIONS`. The nonce expires 60 seconds after `getVendorRedeployChallenge` returns; consumed on `proveVendorRedeploy`.
+Guards enforced by the backend before proving: freeze slot configured, refund window closed past `FREEZE_AFTER_SLOT + REFUND_WINDOW`, escrow empty, app status `active`, on-chain version in `SUPPORTED_LICENSING_APP_VERSIONS`. The nonce expires 60 seconds after `getVendorRedeployChallenge` returns; consumed on `proveVendorRedeploy`.
 
-Pass `force: true` to bypass the `escrowRoot === EMPTY_ROOT` guard when a straggling refund is still in flight and the vendor accepts responsibility for the unrefunded balance. Other guards remain strict. Unrefunded buyers retain the refund path against the retired v1 address; its on-chain state persists indefinitely, and the retired address stays in `AppRecord.deploymentHistory[]` for out-of-band buyer notification.
+An app retires only with an empty escrow (the circuit requires it): refunds and releases must be done first.
 
 > **Buy links auto-update — vendor-embedded links do not.** `proveVendorRedeploy` returns a fresh `zkAppAddress`. The platform marketplace stores your `buyUrl`/`renewUrl`/`refundUrl` as **base URLs** and appends `?app=<zkAppAddress>&network=<net>` at render time, so the "Get" button on the `/apps` listing routes buyers to the new v2 address automatically the moment `finalizeRedeploy` promotes it onto the AppRecord — no vendor action required. Only surfaces where you have hand-embedded the raw `zkAppAddress` yourself (landing pages, docs, emails, screenshots) need manual updating. Existing licenses on the retired v1 address remain independently verifiable.
 
@@ -379,13 +376,13 @@ Two properties matter for integrators:
 
 This is what `buy.html` and `renew.html` on zklicensing.com call — an inactive-listing app can still be bought and renewed against so long as its on-chain LicensingApp is live. Use this endpoint when starting from a `zkAppAddress` (URL param, wallet paste); use `GET /apps/:appId` when you already know the stable app ID and only need the lineage.
 
-On renew, `renew.ts` fetches this endpoint and, if the licence's `zkAppAddress` is retired, presents a **blocking** "Migrate & Renew" flow (the keeper 409s `/prove/renew` and `/prove/buy*` on retired addresses — buyer-held renewals against a retired tree would silently strand). Migration is a single call — no hop-walking — and copies the current expiry verbatim into the live map; see `zklicensing/migrate` below.
+On renew, `renew.ts` fetches this endpoint and, if the licence's `zkAppAddress` is retired, renews on the current one instead: the successor started with the retired app's licenses, so the licence is there under the same hash (the keeper 409s `/prove/renew` and `/prove/buy*` on retired addresses, and a retired app refuses them on chain).
 
 **Signed generation-list, pin-verified.** The response body carries a `publicKey` + `signature` over the canonical `{ appId, current, generations, issuedAt }` payload, signed with the platform manifest Ed25519 key (the same key material that signs the freeze manifest). The SDK verifies against a caller-supplied pin list (`fetchGenerationInfo({ pinnedPublicKeysBase64 })`, see `zklicensing/generation` below) and fails closed — `verified: false` with `current: null` and `generations: []` — when the signature doesn't match. The keeper is not the trust anchor; the pin list is.
 
-Snapshot atomicity: `finalizeRedeploy` gates a retiring generation from all `/prove/*` handlers **before** draining the tolerance window, capturing `frozenRoot`, and persisting — so any buyer-held `provenTxJson` proven against the retiring tree becomes unlandable inside the drain window rather than accidentally landing after the ancestor root is composed.
+Retirement atomicity: the keeper gates a retiring generation from all `/prove/*` handlers **before** draining the tolerance window and retiring it — so any buyer-held `provenTxJson` proven against the retiring tree becomes unlandable inside the drain window; after `retire` the app refuses writes on chain.
 
-Never trusts `current` blindly: renew always continues against the licence's own stored `zkAppAddress` unless the buyer explicitly opts into the migrate flow. This means a compromised or misreporting keeper cannot redirect a renew to an address the buyer didn't already receive at purchase time. A verified signature is required to even enable the "Migrate & Renew" button.
+Never trusts `current` blindly: renew moves to the current address only when the generation list verifies against the pinned key, so a compromised or misreporting keeper cannot redirect a renew to an address of its choosing.
 
 ### `zklicensing/buy` — buy flow client
 
@@ -453,7 +450,7 @@ The SDK never touches a wallet — the caller drives the sign step between `prov
 
 `proveBuy` also refuses locally when the backend's sales freeze is in effect (fetched from `GET /health`) — the request would 423 anyway, so surfacing the message before the round-trip saves a wasted call. See `zklicensing/freeze` below.
 
-**No-escrow routing.** When the buyer's advertised 14-day refund window would land past `FREEZE_AFTER_SLOT` (checked as `currentSlot + REFUND_WINDOW_N + TOLERANCE_WINDOW_N > FREEZE_AFTER_SLOT`), `proveBuy` transparently switches to `POST /prove/buy-no-escrow` — the backend endpoint for a distinct circuit method (`buyLicenseNoEscrow`) that pays vendor + platform directly at buy time (98 / 2, same as `renewLicense`) and never writes an escrow entry. This is the mechanism that makes the pre-hardfork waiver materially real: with no escrow entry there is nothing for the freeze-window migration guard to strand, and no refund path exists at all (a refund would fail the `escrowCommitment` check by construction). Passing `refundWaiverAccepted: true` is mandatory on those routed calls; the backend refuses the endpoint without it. When the backend hasn't yet been redeployed with a build that offers `/prove/buy-no-escrow`, the client throws an actionable message rather than silently falling back to an escrow-backed buy that would strand funds — vendors on old backend builds must complete their §12.13 redeploy before the overlap-window sales resume.
+**No-escrow routing.** When the buyer's advertised 14-day refund window would land past `FREEZE_AFTER_SLOT` (checked as `currentSlot + REFUND_WINDOW_N + TOLERANCE_WINDOW_N > FREEZE_AFTER_SLOT`), `proveBuy` transparently switches to `POST /prove/buy-no-escrow` — the backend endpoint for a distinct circuit method (`buyLicenseNoEscrow`) that pays vendor + platform directly at buy time (98 / 2, same as `renewLicense`) and never writes an escrow entry. This is the mechanism that makes the pre-hardfork waiver materially real: with no escrow entry nothing blocks the redeploy (an app retires only with an empty escrow), and no refund path exists at all (a refund would fail the `escrowCommitment` check by construction). Passing `refundWaiverAccepted: true` is mandatory on those routed calls; the backend refuses the endpoint without it. When the backend hasn't yet been redeployed with a build that offers `/prove/buy-no-escrow`, the client throws an actionable message rather than silently falling back to an escrow-backed buy that would strand funds — vendors on old backend builds must complete their §12.13 redeploy before the overlap-window sales resume.
 
 ### `zklicensing/renew` — renew flow client
 
@@ -495,46 +492,6 @@ await confirmRenew({ keeperUrl, zkAppAddress, licenseHash, txHash });
 
 `proveRenew` also refuses locally when the backend's sales freeze is in effect (fetched from `GET /health`), for the same reason as `proveBuy`. Concurrent-prove serialization is via the shared per-app in-flight guard — see [Per-app in-flight proving guard](#per-app-in-flight-proving-guard).
 
-### `zklicensing/migrate` — cross-generation migrate client
-
-Wraps `POST /prove/migrate`. The keeper locates the buyer's licence in the freshest ancestor generation where it still exists, assembles the three witnesses (ancestor / predecessor / current-live-empty), and returns a signable transaction that copies the expiry verbatim into the current live map at zero payment.
-
-**Full "Migrate & Renew" sequence** (two txs, one wallet sign each):
-
-1. `fetchGenerationInfo` (see `zklicensing/generation`) — pin-verified signed lineage. If the licence's `zkAppAddress` is retired, present the buyer with a blocking "Migrate & Renew" step.
-2. `proveMigrate` → wallet signs `provenTxJson` → broadcast → poll landing on the current `zkAppAddress`.
-3. `proveRenew` (see `zklicensing/renew`) against the current `zkAppAddress` → wallet signs → broadcast → poll → rewrite `ProofFile` with the new `{ generation, zkAppAddress, expirySlot }`.
-
-The keeper 409s `/prove/renew` and `/prove/buy*` for any retired `zkAppAddress`, so skipping step 2 is not an option.
-
-```ts
-import { proveMigrate, ProveMigrateError } from 'zklicensing/migrate';
-import { ProveQueueBusyError } from 'zklicensing/prove-errors';
-
-try {
-  const { provenTxJson, ancestorGen, expirySlot, zkAppAddress, appKey } = await proveMigrate({
-    keeperUrl:    'https://dev.zklicensing.com/api/keeper',
-    licenseHash:  '…',
-    appId:        'app_…',
-    buyerAddress: 'B62q…',   // fee payer (buyer-signed mode)
-  });
-  // Wallet signs provenTxJson → broadcast → poll landing → resume with renew.
-} catch (e) {
-  if (e instanceof ProveQueueBusyError) {
-    // Another root-mutating prove (buy / renew / migrate) is in flight on this app.
-    // Wait e.retryAfterMs, then retry — no wallet popup was opened.
-  }
-  if (e instanceof ProveMigrateError) {
-    // Terminal 4xx: 404 "license refunded or unknown", 409 "already migrated", etc.
-  }
-  throw e;
-}
-```
-
-Single-flight is enforced keeper-side by the shared per-app in-flight slot (see [§Per-app in-flight proving guard](#per-app-in-flight-proving-guard)) — not a per-`licenseHash` marker. The second concurrent caller on the same app receives an immediate `409 { error: "proving queue busy", retryAfterMs, queueDepth }` before any wallet prompt, whether the other request was a buy, renew, or migrate against the same `licensesRoot`. This is stricter than the previous per-`licenseHash` marker: two migrates of *different* licenses on the same app are also serialized, because both mutate the same root.
-
-Terminal 4xx surfaces (`ProveMigrateError`): 404 "license refunded or unknown" (no leaf in any generation — stop), 409 "already migrated" (leaf already in the current live map — refresh the record).
-
 ### `zklicensing/generation` — signed generation-list client
 
 Wraps `GET /apps/:appId` — every past `zkAppAddress` plus the currently live one, with the response's Ed25519 signature verified against a caller-supplied pin list of platform manifest public keys.
@@ -592,9 +549,15 @@ zklicensing-verify-trust \
 
 **Where `--pinned-key` comes from.** Read the current platform manifest pubkey(s) off the published trust-anchor page — <https://dev.zklicensing.com/trustanchor.html> lists them alongside each generation's verification-key hash. The same data is served as JSON for CI: <https://dev.zklicensing.com/trustanchor/manifest-pubkeys.json> (and VK hashes at <https://dev.zklicensing.com/trustanchor/vk-hashes.json>). Copy that base64 value into your build config and pass it as `--pinned-key`. **Do not** rely on the pubkey embedded inside the `.well-known` manifest itself — it is the signer's self-declaration and is not trusted; only the caller-pinned list is. Repeat `--pinned-key <b64>` once per key during a rotation window.
 
+**Permit registries.** `--registry <address>` checks a zkPermits registry instead (`verifyRegistryTrust` in `zklicensing/permits/trust`): the on-chain verification key is a published `PermitRegistry` release (`CANONICAL_PERMIT_VK_HASHES`), initialize ran, the registry is bound to the network, and its permissions are locked (verification key, permissions, zkApp URI, delegate and timing impossible; `send` and `editState` proof-only). It also checks who the registry belongs to: the authority's https website is written into its `zkappUri` at deployment (frozen), `--origin` compares that website's host with the one you expect, and the website must serve `/.well-known/zkpermits/<address>.json` naming the registry and network (`wellKnownFile(address, network)` builds it; skip the fetch with `--no-well-known`). With `--keeper-url` it also checks that the keeper's authority keys, payout address and website match the chain.
+
+```sh
+zklicensing-verify-trust --registry B62q… --origin https://permits.city.example --mina-network-id mainnet --keeper-url https://zklicensing.com/api/keeper
+```
+
 ### `zklicensing/refund` — refund flow client
 
-Same shape as buy/renew. The backend enforces the 14-day refund window and returns HTTP 409 when it has closed — the error surfaces through the thrown `Error` message, so the SDK doesn't second-guess it locally. Refunds stay open during a sales freeze (that's the whole point of freezing). Refund shares the per-app in-flight guard with buy/renew/migrate, so `proveRefund` throws `ProveQueueBusyError` on concurrent-prove collisions.
+Same shape as buy/renew. The backend enforces the 14-day refund window and returns HTTP 409 when it has closed — the error surfaces through the thrown `Error` message, so the SDK doesn't second-guess it locally. Refunds stay open during a sales freeze (that's the whole point of freezing). Refund shares the per-app in-flight guard with buy/renew, so `proveRefund` throws `ProveQueueBusyError` on concurrent-prove collisions.
 
 ```ts
 import { proveRefund, confirmRefund } from 'zklicensing/refund';
@@ -628,7 +591,7 @@ await confirmRefund({ keeperUrl, zkAppAddress, licenseHash, txHash });
 
 ### `zklicensing/freeze` — sales-freeze state
 
-Read helpers for the backend's sales-freeze schedule. A platform operator sets `FREEZE_AFTER_SLOT` on the backend ahead of a hardfork migration; from that slot on the backend refuses new buys and renewals so open escrow can drain. Refunds, releases, and verify stay open throughout.
+Read helpers for the backend's sales-freeze schedule. A platform operator sets `FREEZE_AFTER_SLOT` on the backend ahead of a hardfork redeploy; from that slot on the backend refuses new buys and renewals so open escrow can drain. Refunds, releases, and verify stay open throughout.
 
 ```ts
 import { getKeeperHealth, resolveFreezeState } from 'zklicensing/freeze';
@@ -664,6 +627,14 @@ const apps  = await fetchVendorApps({ keeperUrl, vendorAddress });
 
 Each helper returns `null` on non-OK response so a degraded backend doesn't tear the dashboard down.
 
+### `zklicensing/vat` — VAT rates and VAT-inclusive prices
+
+Prices on zkLicensing include VAT. `standardVatRate(country, date)` gives the standard rate in force on a date (EU member states and the UK, with history; pinned from `ibericode/vat-rates`, MIT; regenerate with `node scripts/build-vat-rates.mjs`). `vatIncludedNano(totalNano, rate)` splits a VAT-inclusive amount exactly; `priceWithVat(totalNano, country)` gives what a buyer sees (net + VAT = total); `vatReceipt(...)` is the `vat` block for a license file. Countries outside the table give `null`. For display and vendors' own reporting — an estimate for consumer sales, not tax advice.
+
+### `zklicensing/tax-id` — vendor tax IDs
+
+`checkTaxId(country, taxId)` checks a vendor's tax ID for their country, offline: EU VAT numbers (format per member state; the keeper also looks them up in VIES), UK VAT, Norwegian MVA, Swiss UID, Australian ABN, New Zealand GST, Canadian BN and Indian GSTIN (format and check digits), US EIN, Japanese and Singapore registration numbers (format). Other countries are accepted for an admin to review. Returns the normalized form, or an error and an `example`; `taxIdExample(country)` gives a form placeholder.
+
 ### `zklicensing/country-stats` — buyer-country breakdown
 
 Pure computation over `LicenseRecord[]`, bucketed by UTC calendar year and structured for tax reporting (one row per `year × appId × countryCode`). Used by both the backend (for `/stats.countryBreakdown`) and any downstream dashboard, so numbers can never drift between them.
@@ -679,7 +650,7 @@ Purchase revenue attributes to `createdAt` (falling back to slot-derived time fo
 
 ### `zklicensing/prove-errors` — shared typed errors
 
-Typed error surface for the per-app in-flight guard shared across `proveBuy`, `proveRenew`, `proveMigrate`, and `proveRefund`. See [Per-app in-flight proving guard](#per-app-in-flight-proving-guard) for the wire contract.
+Typed error surface for the per-app in-flight guard shared across `proveBuy`, `proveRenew`, and `proveRefund`. See [Per-app in-flight proving guard](#per-app-in-flight-proving-guard) for the wire contract.
 
 ```ts
 import { ProveQueueBusyError } from 'zklicensing/prove-errors';
@@ -698,7 +669,7 @@ try {
 }
 ```
 
-Also exports `readErrorBody(resp)` + `tryQueueBusyFromBody(parsed)` — pure helpers used internally by the buy/renew/migrate clients to consume the response body exactly once and then classify it. Available for driver integrations that need to inspect a keeper 409 without re-parsing.
+Also exports `readErrorBody(resp)` + `tryQueueBusyFromBody(parsed)` — pure helpers used internally by the buy/renew/refund clients to consume the response body exactly once and then classify it. Available for driver integrations that need to inspect a keeper 409 without re-parsing.
 
 ### `zklicensing/tx-broadcast` — broadcast signal
 
@@ -710,7 +681,7 @@ import { notifyBroadcast } from 'zklicensing/tx-broadcast';
 // After sendWithWallet returns:
 void notifyBroadcast({
   keeperUrl,
-  appId:  appKey,   // the `appKey` returned by proveBuy / proveRenew / proveMigrate
+  appId:  appKey,   // the `appKey` returned by proveBuy / proveRenew
   txHash,
 });
 ```
@@ -730,7 +701,7 @@ import type { LicenseRecord, LicenseStatus } from 'zklicensing/record';
 
 ### `zklicensing/internal/ownershipSignature` — ownership challenge signer
 
-`deriveOwnershipKeypair(passphrase, zkAppAddress)` + `signBinding(privateKey, { licenseHash, deviceCommitment, slotIndex, nonce })` — the Pallas Schnorr signer used by the bind/unbind clients to authorize on-chain slot writes. Derivation is bound to the app's zkApp address, so a leaked passphrase for one app cannot bind against any other. Signatures are re-verified IN-CIRCUIT by `Signature.verify()`, so a compromised backend cannot forge a bind or unbind. Runs via `o1js` — the same primitive `licenseHash` was derived from at buy time.
+`deriveOwnershipKeypair(passphrase, zkAppAddress)` + `signBinding(privateKey, { licenseHash, deviceCommitment, slotIndex, nonce, slotState, expirySlot, zkAppAddress })` — the Pallas Schnorr signer used by the bind/unbind clients to authorize on-chain slot writes. `slotState` is the target slot's current packed `(boundAt, freedAt)` (`slotStateOf(devices[slotIndex])` from `GET /license`) and `expirySlot` the license's current expiry (`fetchBindingState(...)` returns both); together they make each signature single-use, so a captured signature cannot be replayed once the slot changes — including after a refund and re-buy with the same passphrase. `proveBind` / `proveUnbind` fill it in automatically. Derivation is bound to the app's zkApp address, so a leaked passphrase for one app cannot bind against any other. Signatures are re-verified IN-CIRCUIT by `Signature.verify()`, so a compromised backend cannot forge a bind or unbind. Runs via `o1js` — the same primitive `licenseHash` was derived from at buy time.
 
 ### `zklicensing/verify-offline` — non-custodial offline verify
 
@@ -785,7 +756,7 @@ const res = verifyOffline({
 });
 ```
 
-A worked end-to-end example — proof.json paste box, three-way fetch, cross-check, verdict — lives at `packages/sdk/examples/verify.html` alongside the buy / renew / refund / bind / unbind pages.
+A worked end-to-end example — license file paste box, three-way fetch, cross-check, verdict — lives at `packages/sdk/examples/verify.html` alongside the buy / renew / refund / bind / unbind pages.
 
 Two sourcing modes for `licensesRoot`:
 
@@ -794,10 +765,43 @@ Two sourcing modes for `licensesRoot`:
 
 Default public Mina GraphQL endpoints are wired in (`DEFAULT_MINA_GRAPHQL_URLS.mainnet` / `.devnet`); pass `graphqlUrl` to point at your own node.
 
+### `zklicensing/verify-trustless` — the same, in one call
+
+`verifyLicenseTrustless` does the steps above for you, plus the checks a raw root read leaves out: the contract at the address must run a published LicensingApp release (its verification key is one of `CANONICAL_VK_HASHES`) and be locked (state changes only by proof, no new verification key, no new permissions), and the current slot comes from the node too. The service supplies only the leaf fields and Merkle path; they must hash to the on-chain root, so a stale or lying service can make the check fail but never pass. An absent license is proved the same way. The app's contract generations come from the platform-signed list (checked against the pinned manifest keys), current generation first, so a license file naming a retired contract still verifies (the license carried over to the current one). The chain names the current generation too: a retired contract stores its successor, and each successor must run a published release and have started from its predecessor's frozen root. Without a valid signed list, the given address and its on-chain successors are checked (`generations: 'given-address-only'`).
+
+```ts
+import { verifyLicenseTrustless } from 'zklicensing/verify-trustless';
+
+const r = await verifyLicenseTrustless({ keeperUrl, network: 'mainnet', zkAppAddress, licenseHash /*, graphqlUrl: your own node */ });
+// { valid, expiresAt, expirySlot, inGracePeriod, remainingDays, reason, trustless: true,
+//   resolvedAddress, generation, slot, generations: 'verified' | 'given-address-only' }
+```
+
+A service that is a block or two behind a fresh purchase gets one more read; after that the call throws `STATE_MISMATCH` (retryable). Whether the address is the app you think it is (the seller's website) is `verifyTrustAnchor`. The agent client's `verifyLicense({ …, trustless: true })` and the MCP `verify_license` tool use it.
+
 ### Verify service — on-chain state only
 
 The verify service is a stateless mirror of on-chain license state. `GET /verify?licenseHash=…&zkAppAddress=…` returns `{ valid, expirySlot, inGracePeriod, reason, currentSlot, purchaseSlot }`. No session tokens, no HMAC-signed bearer state, no challenge/response — the verifier reads the archive and reports. Device-cap enforcement lives entirely on-chain via the [Non-custodial device binding](#non-custodial-device-binding) flow: the buyer's `bind()` / `unbind()` transactions write into the `LicenseLeaf`'s slot array, and offline verification checks the local device commitment against the cached leaf. There is no server-side seat concept the verifier or keeper can revoke; the only party who can add or remove a device commitment is whoever holds the passphrase-derived ownership private key.
 
+### `zklicensing/permits/*` — zkPermits
+
+Registries of permits run by an authority (multi-key approval), held by a holder's wallet, checkable by anyone. Working pages for each role are in [`examples/`](examples/README.md#permits).
+
+| Subpath | What it gives you |
+|---|---|
+| `zklicensing/permits/client` | `createPermitsClient({ keeperUrl, network, wallet })`: reads (`listRegistries`, `getRegistry`, `getPermit`, `verifyPermit`), the holder flow (`apply`, which pays the fee into escrow, or `apply(…, { pay: false })` then `fileApplication(id, payer?)`; `getApplication`, `withdrawApplication`, `reclaimApplication` after an undecided deadline, `acceptGrant` for a renewal the authority offers, `surrender`) and the authority flow (`acceptAuthorityTerms`, `createRegistry` with `processingFeeMina` and `decisionWindow`, `signRequest`, `deployRegistry`, `approveApplication` / `rejectApplication` (exactly as filed), `requestRenewal` / `requestStatus` / `requestFees` / `requestRotation`, `executeRequest`, and `redeployRegistry` / `cancelRedeploy` / `getDeployment` for moving a registry to the current release: it drains open applications, then the keys sign `retire` (the old registry freezes) and the next generation's deployment, which commits to the frozen permits; `getPermit` and `verifyPermitTrustless` follow the generations). An approval pays the escrowed fee out 98/2; a rejection or withdrawal keeps the registry's processing fee and refunds the rest to the payer; past the decision deadline the payer gets it all back. Writes sign in first; the sign-in text names the site and network and the session works only on that network. `acceptAuthorityTerms` takes `AuthorityDetails`: on mainnet also `registrationNumber` and `billingAddress`, and `vatId` only if the authority is VAT-registered; `authorityFeeStatement(month)` returns the platform's monthly fee statement for the wallet's registries. Also `verifyPermitTrustless` (the keeper's leaf and witness must fold to the root read from a Mina node, dated by the node's slot), `readRegistryHead` (a registry's root and the current slot from a Mina node) and `minaSignerWallet` (a `PermitWallet` from a private key, for scripts and agents). Options `confirmSignature(description)` (called before every field signature with what it does in words and a fingerprint to compare with the wallet; return `false` to cancel, error code `CANCELLED`) and `describeContext(registry)` (activity names and dates for those descriptions). The client rebuilds every message from the request's details first and refuses one that doesn't match (`SIGNATURE_INVALID`). |
+| `zklicensing/receipt` | The purchase receipt (`PurchaseReceipt`): the durable confirmation the keeper issues at `confirmBuy`, `confirmRenew` and permit `acceptGrant` (each returns it as `receipt`), for an approved permit application when the approval is sent, and for the processing fee kept on a rejection or withdrawal (kind `permit-processing`; `withdrawApplication` returns it, otherwise `getReceipt(txHash)` with the holder's sign-in), in the seller's name and numbered in the seller's own series; `confirmRefund` returns a credit note (`creditNote`, kind `license-refund`, negative amounts, `creditFor` naming the receipt it cancels) in the seller's credit-note series. It is a document of its own, not part of the license or permit file: offer it as a separate download, `receiptHtml(receipt or list)` (a self-contained printable page, no scripts) saved as `receiptFileName(…)` (Vendor Terms §7.1). The buyer can fetch them again from `GET /receipts` with their wallet sign-in. |
+| `zklicensing/permits/describe` | Field signatures appear in wallets as bare numbers. `describeRequest(request, ctx)`, `describeAccept`, `describeSurrender` rebuild the message from its details and return `{ title, facts, verified, problem?, fingerprint }` (`fingerprint`: "7 numbers, the last ending …123456", to compare with the wallet's screen); `identifyPermitMessage(fields)` reads the kind, network and registry from any message's numbers alone. |
+| `zklicensing/permits/holder-secret` | The holder secret behind anonymous proofs, without loading the proof: `deriveHolderSecret(wallet, { lineage, network, index })` (one text `signMessage` over `holderSecretText(lineage, network, index)`, which the wallet shows in words; `lineage` is the registry's first address, `registry.lineage` from the keeper or `client.registryLineage(registry)`, the same in every generation so a permit's secret survives redeploys; `index` counts the key's permits in the registry: 0, 1, …; signatures are deterministic, so nothing needs keeping), `findHolderSecret(wallet, { lineage, network, subject })` (recovers a permit's secret from the chain alone: tries 0, 1, … until the subject matches, usually the first), `saltFromHolderSecret`, and `holderSecretMatches(holderKey, subject, secret)`. Only sign that text on pages you trust: anyone holding the signature can recognise that permit's nullifiers (not prove with it). |
+| `zklicensing/permits/rebuild` (also) | `RegistryView.tree` is a `CompactMerkleMap`: a MerkleMap drop-in (same roots and witnesses) that stores only the leaves and the split-children values, so `registryViewToStored` / `registryViewFromStored` save and load a registry without re-hashing (10,000 permits: 4 MB, 0.3 s to load; a rebuild from events re-hashes a 256-level path per permit, about 17 min), and `refreshRegistryView(view, events)` re-hashes only the permits that changed. |
+| `zklicensing/permits/tree` | A compact copy of a registry's permits tree: every permit plus the 2(N − 1) node values where two permits' paths split, so a holder builds its Merkle witness without the keeper learning which permit and without re-hashing the 256-level tree (about 0.1 s per permit). `compactTreeFrom` (keeper side, from the full tree), `witnessFromCompactTree` (checked by folding to the root), `applyTreeDiff` (the permits changed since a root; re-hashes only above them), `syncRegistryTree({ registry, fetchTree, cache })` (cached copy brought up to date, else a full download). Measured: 10,000 permits ≈ 1.5 MB gzipped and 0.4 s on the device; 100,000 ≈ 15 MB and 3.5 s. |
+| `zklicensing/permits/check` | Anonymous checks through the keeper's relay (the site's verify.html Anonymous mode and prove.html use it). `createCheckRelay(keeperUrl)`: `openCheck` (own nonce, nullifiers never repeat), `createEvent` + `openEventCheck` (one nonce per event: a permit's nullifier repeats there, so second use shows), `getCheck`, `submitProof`, `markSeen` / `seenCount` (the event's shared list, with its key), `getTree`. `proveForCheck({ checkId, permit, wallet, origin, treeCache? })` (holder: builds the witness from a compact copy of the whole registry so the keeper can't tell which permit, re-derives the secret, proves, sends) and `verifyCheck({ checkId, origin, trustless? })` (checker). `origin` is the site both sides are on: the challenge is `verifierContext(origin, nonce)`. |
+| `zklicensing/permits/proof` | The holder's anonymous proof: `proveHolder` (runs on the holder's device — it needs the holder's signature over `holderProofMessage(registry, root, context)` and the holder secret, which the holder's wallet re-derives from the chain with `findHolderSecret` (`zklicensing/permits/holder-secret`); the client's `apply` derives it and sends only its hash, the salt) and `verifyHolderProof` (checks the proof, its registry, root, slot, required activities and challenge; returns the nullifier, the same for one holder and one challenge). The nullifier is `Poseidon(tag, holderSecret, context)`: subjects are public and the keeper and authority see the salt, but only the holder's wallet can produce the secret, so nobody else can match a nullifier to a permit. The challenge is bound to the verifier: `context = verifierContext(verifier, nonce)`, from the verifier's identity as the holder reaches it (a URL counts as its origin, `normalizeVerifier`) and a `randomNonce()`; verifiers pass `{ verifier, nonce }` to `verifyHolderProof`. Two verifiers that agree on one nonce still get different challenges, so they can't link a holder by comparing nullifiers. |
+| `zklicensing/permits/trust` | `verifyRegistryTrust`: is an address a genuine, unmodifiable registry (a published verification key from `CANONICAL_PERMIT_VK_HASHES`, initialized, bound to the network, permissions locked), and does it belong to the website it names (`zkappUri`, options `website` and `checkWellKnown`; `wellKnownPath` / `wellKnownFile` for the authority's claim file)? Also the `--registry` mode of `zklicensing-verify-trust`. |
+| `zklicensing/permits/messages` | The permit leaf, its hash and subject, packed fees and policy, the escrowed `Application` (its `filing` number is the registry's `filingCount` when filed, so every filing hashes differently and a decision or withdrawal signature settles only that filing; `applicationTermsHash`, which the holder signs, leaves out the payer, deadline and filing number) and the exact field messages the authority keys and the holder sign (`toSignableFields` turns one into wallet `signFields` input). |
+| `zklicensing/permits/rebuild` | `rebuildRegistry` / `applyRegistryEvents`: a registry's permits and root from its on-chain events alone, without the keeper; `permitStatusAt` for a permit's status at a slot. |
+| `zklicensing/permits/interface` | Event shapes, the on-chain state layout, `CANONICAL_PERMIT_VK_HASHES` and `CANONICAL_PERMIT_PROOF_VK_HASH`. |
+
 ## Documentation
 
 - Integration walkthrough — [dev.zklicensing.com/docs.html](https://dev.zklicensing.com/docs.html)