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

package/README.md

@@ -1,6 +1,6 @@
 # zklicensing
 
-Client SDK for verifying [zkLicensing](https://zklicensing.com) software licenses.
+Client SDK for verifying [zkLicensing](https://dev.zklicensing.com) software licenses.
 
 `verifyLicense` calls the verifier's `GET /verify` endpoint during the on-chain refund window (~14 days), then writes a one-shot anchor to local storage and verifies fully offline from that point on. Works in browsers (via `localStorage`) and in Node (with an injected storage adapter). Zero runtime dependencies.
 
@@ -18,10 +18,8 @@ import { verifyLicense } from 'zklicensing';
 // `proof` is the JSON the buyer downloaded after purchase
 const result = await verifyLicense({
   licenseHash:    proof.licenseHash,
-  zkAppAddress:   proof.zkAppAddress,                    // your deployed zkApp address (B62q…)
+  zkAppAddress:   proof.zkAppAddress,   // your deployed zkApp address (B62q…)
   expirySlot:     proof.expirySlot,
-  purchaseSlot:   proof.purchaseSlot,
-  verifierUrl:    'https://zklicensing.com/api/verify',  // hosted verify service
 });
 
 if (result.valid) {
@@ -41,9 +39,7 @@ purchase ─────► verifier (every call) ─────► anchor writ
 
 For the first ~14 days the licence can still be refunded on-chain, so the SDK calls the verifier on every check to catch refunds. Once the verifier itself reports the refund window has closed (`currentSlot > purchaseSlot + 13 440 slots`, ≈ 14 days at one slot every 90 s post-Mesa), the SDK writes an anchor into local storage and never touches the network again for that licence.
 
-> **Note:** "Offline" here refers to the validity/expiry check performed by `verifyLicense`. If the vendor set a concurrent-device cap (`maxConcurrentDevices > 0`) on their app, the *separate* activation-token flow (`/challenge` → `/respond` → session token) still round-trips the verifier on every session — that's stateful by design and cannot be anchored locally. Apps with `maxConcurrentDevices = 0` (unlimited, the default) are fully offline post-refund.
-
-The anchor stores `{ anchoredSlot, anchoredAtMs, expirySlot, ownership }`. In the offline branch the current slot is estimated as `anchoredSlot + (now − anchoredAtMs) / 90 000 ms`, and the same 7-day grace window (`6 720 slots`) is applied either side.
+The anchor stores `{ anchoredSlot, anchoredAtMs, expirySlot }`. In the offline branch the current slot is estimated as `anchoredSlot + (now − anchoredAtMs) / 90 000 ms`, and the same 7-day grace window (`6 720 slots`) is applied either side.
 
 A renewal advances the proof's `expirySlot`; that mismatch invalidates the anchor and the SDK falls back to one more verifier call before re-anchoring with the new expiry.
 
@@ -58,12 +54,9 @@ type ProofInput = {
   licenseHash:    string;   // Poseidon hash identifying the licence on-chain
   zkAppAddress:   string;   // Your deployed zkApp's Mina address (B62q…)
   expirySlot:     number;   // From the proof; invalidates stale anchors on renewal
-  purchaseSlot:   number;   // From the proof; decides when the refund window has closed
-  verifierUrl?:   string;
 };
 
 type VerifyOptions = {
-  verifierUrl?: string;
   storage?:   Storage | null;   // default: globalThis.localStorage; null disables anchoring
   fetcher?:   typeof fetch;     // default: globalThis.fetch
   now?:       () => number;     // default: Date.now
@@ -72,7 +65,10 @@ type VerifyOptions = {
 type VerifyResult = {
   valid:         boolean;
   expirySlot:    number;
+  expiresAt:     string | null;         // ISO-8601; estimated in the offline branch
+  currentSlot:   number;                // from the verifier, or estimated offline
   inGracePeriod: boolean;
+  remainingDays: number;                // negative through grace and beyond
   reason:        string | null;
   source:        'chain' | 'offline';
 };
@@ -80,6 +76,8 @@ 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 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:
 
 ```ts
@@ -87,6 +85,62 @@ import { REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT } from 'zklicensing';
 // 13_440, 6_720, 90_000
 ```
 
+### Non-custodial device binding
+
+For apps with a per-license device cap (`deviceCap > 0`), the SDK ships a bind/unbind client that writes device slots directly to the on-chain `LicenseLeaf`. There is no session server: the leaf carries a fixed-width slot array (`DEVICE_SLOT_CAP_N = 5`), the on-chain `bind()` / `unbind()` methods re-verify the buyer's Pallas Schnorr ownership signature IN-CIRCUIT via `Signature.verify()`, and offline verification checks the device's local commitment against the cached leaf.
+
+```ts
+import {
+  proveBind,
+  confirmBind,
+  proveUnbind,
+  confirmUnbind,
+  getOrCreateDeviceIdentity,
+  deriveOwnershipKeypair,
+} from 'zklicensing';
+
+// Fresh device: generate (or load) a Pallas keypair kept in OS secure
+// storage. Only its Poseidon commitment ever crosses the wire.
+const { deviceCommitment } = await getOrCreateDeviceIdentity('myapp/license/device');
+
+// Owner key — derived from the buyer's passphrase + the app's zkApp
+// address. Same keypair `licenseHash` was derived from at buy time.
+const { privateKey: ownerPrivateKey } = await deriveOwnershipKeypair(
+  passphrase,
+  zkAppAddress,
+);
+
+// Bind — the on-chain circuit re-verifies this signature, so a
+// compromised backend cannot forge a bind.
+const { provenTxJson, slotIndex } = await proveBind({
+  keeperUrl:     'https://dev.zklicensing.com/api/keeper',
+  network:       'mainnet',
+  zkAppAddress,
+  licenseHash,
+  ownerPrivateKey,
+  deviceCommitment,
+  slotIndex:     0,               // 0..deviceCap-1
+  buyerAddress:  wallet.address,
+});
+
+const txHash = await wallet.sendTransaction(provenTxJson);
+await confirmBind({ keeperUrl, zkAppAddress, licenseHash, txHash });
+```
+
+**Remote log-off.** `proveUnbind` needs only the ownership key — not physical possession of the target device. Any device with the passphrase-derived key can unbind any slot on the license, including one bound to a lost or stolen device.
+
+**Slot behaviour.**
+
+- Binding into an empty slot succeeds immediately.
+- 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 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.
+
+Non-custodial guarantees preserved: the keeper cannot bind or unbind (no signature to sign with), the vendor cannot revoke a bound device (no admin unbind path in the circuit), and the platform cannot revoke either. The only party who can add or remove a device commitment is whoever holds the passphrase-derived ownership private key.
+
 ## Node storage adapter
 
 In the browser the SDK uses `localStorage` automatically. In Node, supply your own — otherwise the offline branch will never activate and every call will hit the verifier:
@@ -115,7 +169,7 @@ Pass `storage: null` to disable the offline path entirely (every call hits the v
 
 ## Verifier response contract
 
-If you self-host the verification endpoint, it must return:
+The verifier returns:
 
 ```ts
 {
@@ -134,36 +188,26 @@ For non-JavaScript clients (Android, iOS, Python, …) call the verifier's `GET
 
 ## Platform examples
 
-Two variants matter per platform:
-
-- **Unlimited** — the vendor set `maxConcurrentDevices = 0`. Just call `GET /verify`; there is no ownership token.
-- **JTI-capped** — the vendor set `maxConcurrentDevices > 0`. Obtain a session token once via a small backend helper that runs `LicenseProof.compile()`, drives `POST /verify/challenge` + `/respond`, and returns the HMAC-JTI token to cache client-side (o1js can't run on-device). Pass `&token=` on every `GET /verify`. Renew silently against `POST /verify/refresh`; release the seat on logout with `POST /verify/releaseSeat`.
+Device-cap enforcement is fully on-chain via [Non-custodial device binding](#non-custodial-device-binding) — the verifier never mints session tokens, so every platform reduces to the same `GET /verify` call. If the vendor set `deviceCap > 0` at registration, the SDK's bind/unbind clients drive on-chain slot writes; the verifier is stateless and passphrase-free.
 
 ### Android (Kotlin)
 
 ```kotlin
-// Unlimited — no token
 val licenseHash = prefs.getString("licenseHash", "") ?: ""
 val zkApp       = "B62q…"
-val url = "https://zklicensing.com/api/verify" +
+val url = "https://dev.zklicensing.com/api/verify" +
           "?licenseHash=$licenseHash&zkAppAddress=$zkApp"
 val body = OkHttpClient().newCall(Request.Builder().url(url).build())
                         .execute().body?.string() ?: "{}"
 val r = JSONObject(body)
 if (r.getBoolean("valid")) unlockFeatures()
-
-// JTI-capped — append &token, refreshed off the backend helper
-val token = prefs.getString("ownershipToken", null)
-val capped = url + (token?.let { "&token=$it" } ?: "")
-// … same fetch + parse; on 429 { activeSessions, deviceLimit } prompt "log out other device"
 ```
 
 ### iOS (Swift)
 
 ```swift
-// Unlimited — no token
 let zkApp = "B62q…"
-var c = URLComponents(string: "https://zklicensing.com/api/verify")!
+var c = URLComponents(string: "https://dev.zklicensing.com/api/verify")!
 c.queryItems = [
   URLQueryItem(name: "licenseHash",  value: licenseHash),
   URLQueryItem(name: "zkAppAddress", value: zkApp),
@@ -171,41 +215,11 @@ c.queryItems = [
 let (data, _) = try await URLSession.shared.data(from: c.url!)
 let r = try JSONDecoder().decode(VerifyResult.self, from: data)
 if r.valid { unlockFeatures() }
-
-// JTI-capped — append &token; refresh via POST /verify/refresh
-if let token = UserDefaults.standard.string(forKey: "ownershipToken") {
-  c.queryItems! += [URLQueryItem(name: "token", value: token)]
-}
 ```
 
 ### Browser / PWA
 
-Unlimited licenses are just the top-of-file `verifyLicense` example — no `secretHash`, no `prover`. For JTI-capped apps, load `zklicensing/prove` + `o1js` lazily on first verify only, then let the SDK's stored `secretHash` renew silently:
-
-```ts
-import { verifyLicense } from 'zklicensing';
-
-// `promptPassphraseOnce` is your helper — check localStorage yourself and
-// skip the modal when an activation already exists. On the first successful
-// /challenge + /respond the SDK persists { token, expiresAt, secretHash }
-// to `options.storage` (defaults to localStorage in browsers), and from
-// then on renews silently using the stored secretHash.
-const rawSecret  = await promptPassphraseOnce();
-const [o1js, prove] = await Promise.all([import('o1js'), import('zklicensing/prove')]);
-const secretHash = o1js.Poseidon.hash(o1js.Encoding.stringToFields(rawSecret)).toString();
-await prove.LicenseProof.compile();
-
-const r = await verifyLicense(proof, {
-  secretHash,
-  prover: async ({ licenseHash, nonce, secretHash }) => {
-    const pub = new prove.OwnershipChallenge({
-      licenseHash: o1js.Field(licenseHash), nonce: o1js.Field(nonce),
-    });
-    return (await prove.LicenseProof.prove(pub, o1js.Field(secretHash))).proof.toJSON();
-  },
-});
-if (r.valid && r.ownership === 'verified') unlockFeatures();
-```
+`verifyLicense` is the top-of-file example — no `signer`, no passphrase round-trip. If your app also needs to bind/unbind devices, see [Non-custodial device binding](#non-custodial-device-binding) below for the `proveBind` / `proveUnbind` flow that uses the buyer's passphrase-derived Pallas Schnorr ownership key to authorize on-chain slot writes.
 
 ## Quick Start: Building a vendor site
 
@@ -214,6 +228,8 @@ Three drop-in pages, one SDK. Fork them, restyle, ship.
 - **`examples/buy.html`** — passphrase → wallet sign → licence file.
 - **`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 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.
 
@@ -221,7 +237,7 @@ Each page is a self-contained HTML + TS pair calling one SDK subpath.
 
 ```bash
 # 1. Register your app and download apps.json
-open https://zklicensing.com/register.html   # click "Download apps.json"
+open https://dev.zklicensing.com/register.html   # click "Download apps.json"
 
 # 2. Drop apps.json into the examples/ directory
 mv ~/Downloads/apps.json packages/sdk/examples/
@@ -232,7 +248,7 @@ npm install
 npm run dev
 ```
 
-Vite serves `index.html`, `buy.html`, `renew.html`, and `refund.html` at
+Vite serves `index.html`, `buy.html`, `renew.html`, `refund.html`, `bind.html`, `unbind.html`, and `verify.html` at
 `http://localhost:5173`. The pages `fetch('/apps.json')` for their config —
 no `.env` file needed. Ship them as static assets with `npm run build`.
 
@@ -244,6 +260,16 @@ via `VITE_WALLETCONNECT_PROJECT_ID` to enable the mobile QR fallback.
 
 The main entry point (`zklicensing`) covers licence verification. Additional entry points are shipped alongside for integrators building a buy page, a vendor dashboard, or tax-report tooling — all browser-safe, no `fs`.
 
+### Per-app in-flight proving guard
+
+`/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 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` and `zklicensing/renew` references this contract.
+
 ### `zklicensing/deploy` — deploy flow client
 
 Wraps the backend's `/prove/deploy` endpoint. The backend generates a throwaway zkApp keypair, bundles `deploy() + initialize()` as a single atomic tx, proves it, signs the zkApp AccountUpdate with the throwaway key, and returns the provenTxJson — the vendor's wallet only adds the fee-payer signature.
@@ -252,12 +278,13 @@ Wraps the backend's `/prove/deploy` endpoint. The backend generates a throwaway
 import { proveDeploy, pollDeployStatus } from 'zklicensing/deploy';
 
 const { provenTxJson, zkAppAddress, verificationKeyHash } = await proveDeploy({
-  keeperUrl:         'https://zklicensing.com/api/keeper',
+  keeperUrl:         'https://dev.zklicensing.com/api/keeper',
   senderPublicKey:   'B62q…',   // vendor's fee-payer wallet
   vendorAddress:     'B62q…',
-  priceMonthlyMina:  1,
-  priceYearlyMina:   10,
-  priceFiveYearMina: 40,
+  priceMonthlyMina:   1,
+  priceYearlyMina:    10,
+  priceFiveYearMina:  40,
+  pricePerpetualMina: 10000,
 });
 
 // Send `provenTxJson` to the wallet for signing, obtain txHash, register the
@@ -267,37 +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
-
-After a Mina hardfork relaxes `impossibleDuringCurrentVersion` back to `signature()`, every existing zkApp becomes uneditable in place (deploy keys are already discarded). The platform migrates each app to a fresh v2 address via admin endpoints, guarded by `KEEPER_ADMIN_TOKEN`:
-
-```ts
-import { redeployApp, redeployAll } from 'zklicensing/deploy';
-
-// Migrate one app.
-const { zkAppAddress, txHash, verificationKeyHash, onChainVersion } = await redeployApp({
-  keeperUrl:  'https://zklicensing.example.com',
-  appId:      'acme-editor',
-  adminToken: process.env.KEEPER_ADMIN_TOKEN!,
-});
-
-// Batch — top-level `ok` is always true unless the whole request errored;
-// per-app failures surface as { ok: false, error } inside `results`.
-const batch = await redeployAll({ keeperUrl, adminToken });
-for (const r of batch.results) {
-  if (!r.ok) console.warn(`${r.appId}: ${r.error}`);
-}
-```
-
-The backend reads authoritative `vendor` + prices from the old v1 contract (no vendor RPC), mints a fresh throwaway zkApp keypair, and broadcasts a merged-sign atomic redeploy. Guards (HTTP 409): sales frozen, refund window closed, `escrowRoot === EMPTY_ROOT`, on-chain version still in `SUPPORTED_LICENSING_APP_VERSIONS`. Both endpoints are idempotent — already-migrated apps surface as `{ ok: false, error: "already outside supported range" }`, so reruns after a partial batch are safe.
-
-Pass `force: true` on either helper to bypass the `escrowRoot === EMPTY_ROOT` guard when the platform accepts responsibility for the unrefunded balance. Other guards remain strict. Successful responses that used the override return `forcedEscrowNonEmpty: true` alongside the usual fields; unrefunded buyers keep their independent refund path against the retired v1 address (its on-chain state persists), so pointing them at `deploymentHistory[]` addresses out-of-band remains the mitigation.
-
-Confirmation polling is not baked in — reuse `pollDeployStatus({ keeperUrl, zkAppAddress })` against the returned address.
+#### Redeploy (hard fork)
 
-#### Vendor-triggered redeploy
+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`).
 
-Vendors don't have to wait for the platform to migrate their app — they can trigger the redeploy themselves through the SDK. Authentication is a Mina signature against the on-chain vendor of the target app (no `KEEPER_ADMIN_TOKEN` required), and the vendor pays gas via their own fee-payer AU. Three-step flow, mirroring the first-time deploy:
+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 {
@@ -307,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 are identical to the admin path: 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`.
 
-`force: true` is available to vendors too, with the same semantics as the admin path — useful when the freeze is scheduled late enough that a straggling refund is still in flight. 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.
 
@@ -364,38 +360,84 @@ Guards are identical to the admin path: freeze slot configured, refund window cl
 
 The buy/renew receipts include a `generation: number` field baked into `ProofFile`, so a licence bought against gen 2 can be told apart from one bought against gen 5 without a second network call.
 
-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.
+**Resolving by `zkAppAddress` instead of `appId`.** The keeper also exposes `GET /apps/by-address/:zkAppAddress`, which resolves any registered address — current or historical — to the same signed generation-list body **plus** an `app: AppRecord` field:
+
+```ts
+{
+  ...signedGenerationList,   // same shape as GET /apps/:appId
+  app: AppRecord             // full record; usable for name / prices / vendor legal
+}
+```
+
+Two properties matter for integrators:
+
+1. It accepts *any* generation's address (live or retired) and always returns the current lineage — so a buyer holding a link with a retired `?app=<addr>` still reaches the correct app.
+2. It does **not** filter by marketplace status. `pending`, `active`, `inactive`, and `rejected` apps all resolve. Contrast with `GET /apps`, which is `status: 'active'`-only for the storefront listing.
+
+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, 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
 
-Wraps the backend's three-step buy roundtrip so a custom marketplace or CLI can drive it without re-deriving the crypto. Peer dep: `o1js` (for the `secretHash` Poseidon derivation).
+Wraps the backend's three-step buy roundtrip so a custom marketplace or CLI can drive it without re-deriving the crypto. Peer dep: `o1js` (for the `licenseHash` binding to the buyer's derived ownership pubkey).
 
 ```ts
 import { deriveBuyIdentity, proveBuy, confirmBuy, pollBuyStatus } from 'zklicensing/buy';
+import { ProveQueueBusyError } from 'zklicensing/prove-errors';
+import { notifyBroadcast }     from 'zklicensing/tx-broadcast';
+
+// 1. Derive the identity from the buyer's passphrase and the app's zkApp
+//    address (deterministic — the resulting ownership pubkey is hashed into
+//    the on-chain licenseHash). Binding to zkAppAddress means the same
+//    passphrase yields different keypairs across apps, so a leaked
+//    passphrase for one app cannot be replayed against any other.
+const { licenseHash } = await deriveBuyIdentity(passphrase, zkAppAddress);
+
+// 2. Ask the backend to compile + prove the buy tx. Retry on shared per-app
+//    queue-busy — server drives cadence via `retryAfterMs`, which caps at
+//    ~one slot (~90s at Mesa) once /tx-broadcast has fired. 10 attempts
+//    covers ~15 min of slot-by-slot polling — at 40 % fill that's < 1 %
+//    chance of exhausting before a block lands.
+async function proveBuyWithRetry(): Promise<Awaited<ReturnType<typeof proveBuy>>> {
+  const MAX_ATTEMPTS = 10;
+  for (let n = 1; n <= MAX_ATTEMPTS; n++) {
+    try {
+      return await proveBuy({
+        keeperUrl:    'https://dev.zklicensing.com/api/keeper',
+        licenseHash,
+        buyerAddress: 'B62q…',
+        zkAppAddress: 'B62q…',
+        network:      'mainnet',   // 'devnet' or 'mainnet' — must match your ProofFile
+        duration:     0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
+        buyerCountry: 'FI',        // ISO 3166-1 alpha-2, required
+        // Required only when a sales freeze is scheduled — see `zklicensing/freeze`
+        // below. Ignored (safe to pass anyway) when no freeze is announced.
+        refundWaiverAccepted: true,
+      });
+    } catch (err) {
+      if (err instanceof ProveQueueBusyError && n < MAX_ATTEMPTS) {
+        await new Promise(r => setTimeout(r, err.retryAfterMs));
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error('unreachable');
+}
 
-// 1. Derive the identity from the buyer's passphrase (deterministic).
-const { secretHash, licenseHash } = deriveBuyIdentity(passphrase);
-
-// 2. Ask the backend to compile + prove the buy tx.
-const { provenTxJson, expirySlot, purchaseAmount, verificationKeyHash } = await proveBuy({
-  keeperUrl:    'https://zklicensing.com/api/keeper',
-  secretHash,
-  buyerAddress: 'B62q…',
-  zkAppAddress: 'B62q…',
-  duration:     0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years
-  buyerCountry: 'FI',        // ISO 3166-1 alpha-2, required
-  // Required only when a sales freeze is scheduled — see `zklicensing/freeze`
-  // below. Ignored (safe to pass anyway) when no freeze is announced.
-  refundWaiverAccepted: true,
-});
+const { provenTxJson, expirySlot, purchaseAmount, verificationKeyHash, appKey } = await proveBuyWithRetry();
 
 // 3. Send `provenTxJson` to the buyer's wallet for signing, obtain txHash.
+//    …then signal the keeper so the in-flight slot extends from signing-TTL
+//    to landing-TTL. Fire-and-forget; a network failure here is not fatal.
+void notifyBroadcast({ keeperUrl, appId: appKey, txHash });
 
 // 4. Persist the pending record — the caller drives this only after the wallet returned.
 await confirmBuy({ keeperUrl, zkAppAddress, licenseHash, txHash });
@@ -404,11 +446,13 @@ await confirmBuy({ keeperUrl, zkAppAddress, licenseHash, txHash });
 const status = await pollBuyStatus({ keeperUrl, licenseHash });
 ```
 
+`status.status` ends as `'landed'`, `'timeout'` (not included in time) or `'failed'`: included but failed on chain, with `failureReason` (usually the wallet could pay the fee but not the price). A failed purchase issues no license, only the network fee is paid, and the keeper drops the pending record and marks its receipt `voided`. `pollRenewStatus` and `pollRefundStatus` report `'failed'` the same way, and the license stays as it was.
+
 The SDK never touches a wallet — the caller drives the sign step between `proveBuy` and `confirmBuy` — so this client works for any wallet integration (Auro, WalletConnect, mobile, CLI).
 
 `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
 
@@ -416,57 +460,39 @@ Same shape as `zklicensing/buy`. `proveRenew` takes an explicit `waiverAccepted`
 
 ```ts
 import { proveRenew, confirmRenew } from 'zklicensing/renew';
+import { ProveQueueBusyError }      from 'zklicensing/prove-errors';
+import { notifyBroadcast }          from 'zklicensing/tx-broadcast';
 
-const { provenTxJson, newExpirySlot, renewAmount } = await proveRenew({
-  keeperUrl:      'https://zklicensing.com/api/keeper',
+const proveArgs = {
+  keeperUrl:      'https://dev.zklicensing.com/api/keeper',
   licenseHash:    '…',
   buyerAddress:   'B62q…',
   zkAppAddress:   'B62q…',
-  duration:       0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years
-  waiverAccepted: true,        // required — throws before the network call if false
-});
-
-// Send `provenTxJson` to the wallet, obtain txHash, then:
-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`.
-
-### `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';
+  network:        'mainnet' as 'devnet' | 'mainnet',   // must match your ProofFile
+  duration:       0 as 0 | 1 | 2 | 3,   // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
+  waiverAccepted: true,             // required — throws before the network call if false
+};
 
-try {
-  const { provenTxJson, ancestorGen, expirySlot, zkAppAddress } = await proveMigrate({
-    keeperUrl:    'https://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 ProveMigrateError && e.status === 409 && e.retryAfterMs) {
-    // "migration in flight" — another caller is proving right now.
-    // Wait retryAfterMs before retrying rather than opening a second wallet prompt.
+const MAX_ATTEMPTS = 10;   // ~15 min slot-by-slot coverage at Mesa/0.4
+let proved;
+for (let n = 1; n <= MAX_ATTEMPTS; n++) {
+  try { proved = await proveRenew(proveArgs); break; }
+  catch (err) {
+    if (err instanceof ProveQueueBusyError && n < MAX_ATTEMPTS) {
+      await new Promise(r => setTimeout(r, err.retryAfterMs));
+      continue;
+    }
+    throw err;
   }
-  throw e;
 }
-```
+const { provenTxJson, newExpirySlot, renewAmount, appKey } = proved!;
 
-Single-flight is enforced keeper-side via a per-`licenseHash` in-flight marker: the second concurrent caller receives a 409 with `retryAfterMs` (surfaced on `ProveMigrateError`) before any wallet prompt, so the buyer never signs a transaction for a live-map that another proof is about to change.
+// Send `provenTxJson` to the wallet, obtain txHash, then:
+void notifyBroadcast({ keeperUrl, appId: appKey, txHash });   // fire-and-forget
+await confirmRenew({ keeperUrl, zkAppAddress, licenseHash, txHash });
+```
 
-Terminal 4xx surfaces: 404 "license refunded or unknown" (no leaf in any generation — stop), 409 "already migrated" (leaf already in the current live map — refresh the record).
+`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/generation` — signed generation-list client
 
@@ -476,7 +502,7 @@ Wraps `GET /apps/:appId` — every past `zkAppAddress` plus the currently live o
 import { fetchGenerationInfo } from 'zklicensing/generation';
 
 const info = await fetchGenerationInfo({
-  keeperUrl:              'https://zklicensing.com/api/keeper',
+  keeperUrl:              'https://dev.zklicensing.com/api/keeper',
   appId:                  'app_…',
   pinnedPublicKeysBase64: [/* platform manifest pubkeys, base64 Ed25519 */],
 });
@@ -491,21 +517,75 @@ Trust model: the keeper is not the trust anchor for this data — it can be re-h
 
 Rotation-friendly: the pin list is a set. Multiple pins can be listed during a key rotation window; verification succeeds on the first pin that matches.
 
-Optional out-of-band corroboration: an operator that publishes `https://<vendor-host>/.well-known/zklicensing/<appId>.json` under vendor TLS (with the same keeper-signed payload) can be cross-checked from the on-chain `zkappUri`. Per-app filename because a vendor may host several apps at one origin; the cross-check is opt-in per app — absence of the file (404) is not a failure signal, just "no corroboration published for this app." That's the caller's job, not this module's; the platform signature is the trust anchor.
+Optional out-of-band corroboration: an operator that publishes `https://<vendor-host>/.well-known/zklicensing/<zkAppAddress>.json` under vendor TLS (with the same keeper-signed payload) can be cross-checked from the on-chain `zkappUri`. Per-address filename because a buyer's wallet shows the zkApp address, not the platform appId — keying by address lets any buyer verify from just the address they were prompted to sign, including addresses for retired generations they may still hold licenses under. The cross-check is opt-in per app — absence of the file (404) is not a failure signal, just "no corroboration published for this address." That's the caller's job, not this module's; the platform signature is the trust anchor.
+
+#### Publishing the manifest (vendor side)
+
+Vendors who want to enable the corroboration path host the same signed payload the keeper returns for their app. The vendor console exposes this as a one-click flow:
+
+1. Open the vendor dashboard, find the app card, and click **Download manifest**. This downloads the exact bytes served by `GET /apps/:appId` — one `<zkAppAddress>.json` file per generation address (current live + every retired address), all byte-identical, Ed25519 signature intact.
+2. Serve each downloaded file, unchanged, at `https://<vendor-host>/.well-known/zklicensing/<zkAppAddress>.json` under the vendor's TLS certificate. Any static host works; no dynamic logic needed.
+3. Make sure the app's on-chain `zkappUri` points at `https://<vendor-host>` (the origin — the `.well-known` path is fixed). Callers derive the corroboration URL from that origin plus the address their wallet already showed them.
+
+Re-download and re-publish after each retirement or redeploy: the `current` index changes, the `generations[]` list grows by one, and the payload's `issuedAt` timestamp rolls forward — every address file must be replaced with the new signed bytes. Serving a stale copy is not a security failure (the signature still verifies), but callers that compare `current` against the keeper's response will treat the vendor copy as behind.
+
+#### `zklicensing-verify-trust` — trust-anchor CLI
+
+Ships as a `bin` in this package. Runs the full trust-anchor pipeline for a single zkApp address end-to-end: fetches `.well-known/zklicensing/<zkAppAddress>.json` from the vendor origin, verifies the platform signature against caller-provided pins, asserts the address appears in the signed `generations[]`, then reads the on-chain zkApp and checks that its `zkappUri` binds back to the same origin, that its verification-key hash equals the pinned canonical value for that generation, and that the six-line permission matrix from `LicensingApp.init()` is intact (URI freeze, meta-freeze, VK lock, `send`/`editState` proof-only). Structured findings — no boolean collapse — so vendor CI can pin the exact check that regressed.
+
+```sh
+zklicensing-verify-trust \
+  --origin https://store.example.com \
+  --address B62q… \
+  --pinned-key O5BBGskSzE+BOxgf3rukMiV2e4t0I1oTwi0ERtvbUfA= \
+  --mina-graphql https://api.minascan.io/node/mainnet/v1/graphql \
+  --cross-check \
+  --json
+```
+
+`--cross-check` adds a `manifest_matches_backend` finding: fetches `https://dev.zklicensing.com/apps/by-address/<address>`, verifies its signature against the same `--pinned-key` values (never trusts the backend response blind), and byte-compares the canonicalized payload against the vendor's `.well-known` copy. Catches a vendor serving a stale or rolled-back manifest even when its signature is still valid. Opt-in — adds one extra network fetch and couples the verifier to zklicensing.com being reachable.
+
+`--address` is the zkApp address the buyer's wallet displays — the same address they'd see in a purchase or renewal signature prompt. The platform appId is not an input; the CLI reads it out of the signed payload after the signature verifies. Buyers with only a wallet-shown address (including addresses for retired-generation licenses) can self-verify with nothing else. Exit 0 on all-ok, 1 on any check failure, 2 on bad args. Default output is a human summary; `--json` emits the `TrustAnchorReport` for CI. Add `--skip-chain-checks` for offline manifest-only audits (no o1js peer dep required in that mode).
+
+> **Badge policy.** Per Vendor Terms §7.7, the zkLicensing trust-anchor badge (and any equivalent "trust anchor by zkLicensing" mark) may be displayed on vendor pages **only while this CLI returns all-`ok`** against your live `origin` and vendor `--address`, with `--pinned-key` sourced from the attestation table at <https://dev.zklicensing.com/trustanchor.html>. If a chain-side or manifest-side check starts failing, remove the badge until compliance is restored. Wiring this CLI into CI (fail the build on non-zero exit) is the simplest way to keep the two in sync.
+
+**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. 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).
+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';
+import { ProveQueueBusyError }        from 'zklicensing/prove-errors';
 
-const { provenTxJson } = await proveRefund({
-  keeperUrl:    'https://zklicensing.com/api/keeper',
+const proveArgs = {
+  keeperUrl:    'https://dev.zklicensing.com/api/keeper',
   licenseHash:  '…',
   buyerAddress: 'B62q…',
   zkAppAddress: 'B62q…',
-});
+  network:      'mainnet' as 'devnet' | 'mainnet',   // must match your ProofFile
+};
+
+const MAX_ATTEMPTS = 10;   // ~15 min slot-by-slot coverage at Mesa/0.4
+let proved;
+for (let n = 1; n <= MAX_ATTEMPTS; n++) {
+  try { proved = await proveRefund(proveArgs); break; }
+  catch (err) {
+    if (err instanceof ProveQueueBusyError && n < MAX_ATTEMPTS) {
+      await new Promise(r => setTimeout(r, err.retryAfterMs));
+      continue;
+    }
+    throw err;
+  }
+}
+const { provenTxJson } = proved!;
 
 // Send `provenTxJson` to the wallet, obtain txHash, then:
 await confirmRefund({ keeperUrl, zkAppAddress, licenseHash, txHash });
@@ -513,7 +593,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';
@@ -549,6 +629,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.
@@ -562,6 +650,49 @@ const breakdown = computeCountryBreakdown(apps, records, currentSlot, nowMs);
 
 Purchase revenue attributes to `createdAt` (falling back to slot-derived time for legacy records). Renewals attribute to the renewal slot. Refunded purchases contribute zero revenue but still count as licences.
 
+### `zklicensing/prove-errors` — shared typed errors
+
+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';
+
+try {
+  const proved = await proveBuy(args);
+} catch (err) {
+  if (err instanceof ProveQueueBusyError) {
+    // err.status === 409
+    // err.retryAfterMs — ms to wait before retrying; server drives the cadence
+    // err.queueDepth   — always 1 in v1 (forward-compat hook for a future queue)
+    await new Promise(r => setTimeout(r, err.retryAfterMs));
+    // retry — no wallet popup was opened, no fee was paid
+  }
+  throw err;
+}
+```
+
+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
+
+Fire-and-forget `POST /tx-broadcast` from the SDK the moment the buyer's wallet returns a tx hash. Extends the in-flight slot from signing-TTL (~90 s) to landing-TTL (~11 min at Mesa/40 %) so the honest broadcast has room to land before the next prove goes through.
+
+```ts
+import { notifyBroadcast } from 'zklicensing/tx-broadcast';
+
+// After sendWithWallet returns:
+void notifyBroadcast({
+  keeperUrl,
+  appId:  appKey,   // the `appKey` returned by proveBuy / proveRenew
+  txHash,
+});
+```
+
+Contract:
+- **Fire-and-forget.** Network failures are swallowed (optionally reported via `onError`); a missed extension only means the slot self-clears at signing-TTL, at worst delaying the next prove by seconds — not a correctness dependency.
+- **First-come only.** The keeper accepts one extension per slot; a second call for the same slot returns `409 { ok: false, reason: 'already extended' }`. Combined with the corroboration strike (~11 min later, revert on non-observation) this keeps the endpoint DoS-safe despite being unauthenticated.
+- **`appId` = `appKey`.** Slot keys are computed keeper-side (`slotKeyForApp(zkAppAddress, apps)`) — pass the `appKey` from the prove response verbatim rather than trying to reconstruct it.
+
 ### `zklicensing/record` — `LicenseRecord` type
 
 The off-chain record shape written by the backend. Import if you're building tooling that consumes the raw store (Node) or that consumes it via the analytics endpoints.
@@ -570,29 +701,114 @@ The off-chain record shape written by the backend. Import if you're building too
 import type { LicenseRecord, LicenseStatus } from 'zklicensing/record';
 ```
 
-### `zklicensing/prove` — ownership `ZkProgram`
+### `zklicensing/internal/ownershipSignature` — ownership challenge signer
+
+`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
+
+Pure fold verifier. Given a `licensesRoot` you have anchored to, a serialized `MerkleMapWitness`, and the `LicenseLeaf` field set, `verifyOffline` reconstructs the leaf hash, walks the witness back to the root, cross-checks against the anchor, and (when `deviceCap > 0`) folds the device slot array and confirms the caller's device commitment appears in an occupied slot. No network, no service round-trip — the trust question reduces entirely to "where did `licensesRoot` come from?".
+
+```ts
+import { verifyOffline } from 'zklicensing/verify-offline';
+
+const result = verifyOffline({
+  licensesRoot,          // see below — trust anchor
+  currentSlot,           // Mina slot to check expiry against
+  licenseHash,
+  expirySlot,
+  deviceCap,
+  devices,               // DeviceSlotSnapshot[]
+  witness,               // { root, isLefts[], siblings[] } — from GET /witness
+  devicePubKey,          // optional; required when deviceCap > 0
+});
+
+if (!result.valid) throw new Error(result.reason ?? 'invalid');
+```
+
+### `zklicensing/on-chain-root` — non-custodial trust anchor
+
+Reads `licensesRoot` (`zkapp.appState[0]`) directly from Mina via `fetchAccount`. Pair it with `verify-offline` to remove the licensing service from the trust boundary — the service supplies the witness and license record, Mina supplies the root, and the two are cross-checked before any leaf is trusted. `o1js` is a peer dep and imported dynamically so this only costs the o1js payload for callers that actually use it.
+
+```ts
+import { fetchOnChainLicensesRoot } from 'zklicensing/on-chain-root';
+import { verifyOffline }             from 'zklicensing/verify-offline';
+
+// 1. Fetch witness + license record from the licensing service.
+const [w, rec] = await Promise.all([
+  fetch(`${service}/witness/${zkApp}/${licenseHash}`).then(r => r.json()),
+  fetch(`${service}/license/${zkApp}/${licenseHash}?network=mainnet`).then(r => r.json()),
+]);
+
+// 2. Fetch the on-chain root INDEPENDENTLY.
+const onChainRoot = await fetchOnChainLicensesRoot({ zkAppAddress: zkApp, network: 'mainnet' });
+
+// 3. Cross-check. If they disagree the service is stale/wrong; bail.
+if (w.root !== onChainRoot) throw new Error('service root disagrees with chain');
+
+// 4. Fold-verify.
+const res = verifyOffline({
+  licensesRoot: onChainRoot,
+  currentSlot,
+  licenseHash,
+  expirySlot:   rec.expirySlot,
+  deviceCap:    rec.deviceCap ?? 0,
+  devices:      rec.devices  ?? [],
+  witness:      w,
+});
+```
+
+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`:
+
+- **Non-custodial (recommended).** Fetch it via `fetchOnChainLicensesRoot`. The service never gets to say "trust me, this leaf is real" — a service serving a stale or forged witness fails the cross-check and the leaf is refused.
+- **Custodial (trusted-service).** Reuse the `root` field the service returned on its `/verify` or `/witness` response. Faster (no o1js + Mina RPC round-trip) but relies on the service to report the true chain state. Fine for callers that already trust the service; not the recommended default.
+
+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
 
-`LicenseOwnershipProgram` — the challenge/response proof used by verifiers to bind a proof to a fresh nonce. Loaded on demand by clients that produce ownership proofs (verify itself never imports it).
+`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' }
+```
 
-### Verify service — ownership tokens & concurrent-device cap
+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.
 
-The verify service issues an HMAC-SHA256 bearer **token** through a challenge/response flow: `GET /challenge?licenseHash=…` returns a fresh nonce, the client produces a `LicenseProof` binding `(licenseHash, nonce)`, `POST /respond` verifies the proof and returns `{ token, expiresAt, jti, activeSessions, deviceLimit }`. Token TTL is 7 days; the client renews in the background via `POST /refresh` while the app is running so the user only redoes the passphrase-gated `/respond` after a full week of inactivity or an explicit logout. Passing `token` on subsequent `GET /?licenseHash=…&zkAppAddress=…&token=…` calls upgrades the response from "on-chain state" to "verified caller owns this license." Tokens carry a random `jti` (JWT-style unique id) that ties them to an in-memory session-store row so revocation and concurrency caps are enforceable on top of the stateless HMAC.
+### Verify service — on-chain state only
 
-The AppRecord field `maxConcurrentDevices` (register-time or dashboard-editable, `0` = unlimited, capped at 10,000) is the per-license active-device cap. `POST /respond` reserves a session slot for the newly minted `jti` before signing; when the cap is reached and no expired session is available, it returns `429` with `{ activeSessions, deviceLimit }`. The store also prunes on TTL, so the cap is self-recovering.
+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.
 
-Three lifecycle endpoints back the cap:
+### `zklicensing/permits/*` — zkPermits
 
-- **`POST /refresh`** — body `{ token }`. Verifies HMAC + `jti` still active, reissues a token with the same `jti` and a fresh expiry. No LicenseProof needed. Used by running apps to keep sessions warm across the 7-day TTL. If the seat was released in the meantime, returns `401 Seat released`.
-- **`POST /releaseSeat`** — body `{ token }`. Releases the seat identified by the token's `jti`. Idempotent. Same threat model as any bearer token: possession is authorization. Enables an in-app "Log this device out" button.
-- **`POST /reset-sessions`** — body `{ zkAppAddress, proof }`. Drops **all** sessions for the license proved by the `LicenseProof`. Requires the same passphrase-gated challenge/response as `/respond`, so only the license owner can invoke it. Intended as a self-service recovery for owners who hit the cap after an app reinstall or a lost device didn't `POST /releaseSeat` on the way out. The caller runs a fresh `/respond` afterwards to re-provision under a zero active count.
+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).
 
-Sessions are in-memory by design — a service restart drops every session, forcing devices to re-prove. That is intentional: persisted sessions would let a stolen token bypass the cap across restarts with no signal to the license owner.
+| 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 — [zklicensing.com/docs](https://zklicensing.com/docs)
-- FAQ — [zklicensing.com/faq](https://zklicensing.com/faq)
-- Register an app — [zklicensing.com/register](https://zklicensing.com/register)
+- Integration walkthrough — [dev.zklicensing.com/docs.html](https://dev.zklicensing.com/docs.html)
+- FAQ — [dev.zklicensing.com/faq.html](https://dev.zklicensing.com/faq.html)
+- Register an app — [dev.zklicensing.com/register.html](https://dev.zklicensing.com/register.html)
 
 ## Licence