zklicensing 0.1.0-beta.1 → 0.1.0-beta.10

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 proof 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 cross-generation migration: `migrateLicense` copies the ancestor leaf verbatim (including the device slot array) into the successor tree.
+
+**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 proof.json → 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`, `/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.
+
+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.
+
+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.
+
 ### `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
@@ -269,35 +296,7 @@ The SDK does not expose a raw `initialize()` helper. `initialize()` sets `vendor
 
 #### 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.
-
-#### Vendor-triggered redeploy
-
-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:
+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:
 
 ```ts
 import {
@@ -337,9 +336,9 @@ await registerVendorRedeploy({ keeperUrl, appId, redeployId, txHash });
 await pollDeployStatus({ keeperUrl, zkAppAddress });
 ```
 
-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`, 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.
+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.
 
 > **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,6 +363,22 @@ 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.
 
+**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, 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.
 
 **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.
@@ -374,28 +389,58 @@ Never trusts `current` blindly: renew always continues against the licence's own
 
 ### `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 });
@@ -416,21 +461,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
-});
+  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
+};
+
+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;
+  }
+}
+const { provenTxJson, newExpirySlot, renewAmount, appKey } = proved!;
 
 // Send `provenTxJson` to the wallet, obtain txHash, then:
+void notifyBroadcast({ keeperUrl, appId: appKey, txHash });   // fire-and-forget
 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`.
+`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
 
@@ -446,27 +509,31 @@ The keeper 409s `/prove/renew` and `/prove/buy*` for any retired `zkAppAddress`,
 
 ```ts
 import { proveMigrate, ProveMigrateError } from 'zklicensing/migrate';
+import { ProveQueueBusyError } from 'zklicensing/prove-errors';
 
 try {
-  const { provenTxJson, ancestorGen, expirySlot, zkAppAddress } = await proveMigrate({
-    keeperUrl:    'https://zklicensing.com/api/keeper',
+  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 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.
+  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 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.
+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: 404 "license refunded or unknown" (no leaf in any generation — stop), 409 "already migrated" (leaf already in the current live map — refresh the record).
+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
 
@@ -476,7 +543,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 +558,69 @@ 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.
 
 ### `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/migrate, 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 });
@@ -562,6 +677,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`, `proveMigrate`, 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/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.
+
+### `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 / proveMigrate
+  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 +728,81 @@ 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 })` — 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.
+
+### `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.
 
-`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).
+```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,
+});
+```
 
-### Verify service — ownership tokens & concurrent-device cap
+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.
 
-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.
+Two sourcing modes for `licensesRoot`:
 
-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.
+- **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.
 
-Three lifecycle endpoints back the cap:
+Default public Mina GraphQL endpoints are wired in (`DEFAULT_MINA_GRAPHQL_URLS.mainnet` / `.devnet`); pass `graphqlUrl` to point at your own node.
 
-- **`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.
+### Verify service — on-chain state only
 
-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.
+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.
 
 ## 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