zklicensing 0.1.0-beta.2 → 0.1.0-beta.3

package/src/deployClient.ts

@@ -0,0 +1,388 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * deployClient.ts
+ *
+ * Browser-safe client for the deploy flow. Mirrors the buy / renew / refund
+ * client shape: `proveDeploy` posts to the keeper's `/prove/deploy` endpoint
+ * and returns the atomic deploy+initialize tx already signed with the
+ * throwaway zkApp key. The vendor's wallet then adds the fee-payer signature
+ * and broadcasts.
+ *
+ * The atomic bundling is what makes single-shot initialization safe:
+ * `provenTxJson` holds both `zkApp.deploy()` and `zkApp.initialize()`
+ * AccountUpdates in the same transaction, and the keeper generates a
+ * throwaway zkApp keypair per request that is discarded before the tx is
+ * returned — so the target address is not observable to an attacker until
+ * the initialize AU inside is already signed and locked to `(vendor,
+ * prices)`. Combined with the in-circuit `vendor.requireEquals(empty())`
+ * precondition on `initialize()`, this yields a one-shot init per account.
+ *
+ * Also exports admin-side `redeployApp` / `redeployAll` for the platform
+ * operator to trigger post-hardfork v1→v2 migrations via the keeper's
+ * `/admin/redeploy*` endpoints (bearer-token auth).
+ */
+
+export type ProveDeployRequest = {
+  keeperUrl:         string;
+  senderPublicKey:   string;   // vendor's fee-payer wallet
+  vendorAddress:     string;   // owner slot; may equal senderPublicKey
+  priceMonthlyMina:  number;
+  priceYearlyMina:   number;
+  priceFiveYearMina: number;
+  fetcher?:          typeof fetch;
+  signal?:           AbortSignal;
+};
+
+export type ProveDeployResponse = {
+  provenTxJson:        string;
+  verificationKeyHash: string;
+  zkAppAddress:        string;
+};
+
+export type DeployStatus = {
+  status:        'unknown' | 'pending' | 'confirmed' | 'failed';
+  landedAtSlot?: number;
+  elapsedMs?:    number;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+async function readJsonError(resp: Response): Promise<string> {
+  try {
+    const body = await resp.json() as Record<string, unknown>;
+    if (typeof body.error === 'string') return body.error;
+  } catch { /* body wasn't JSON */ }
+  return `HTTP ${resp.status}`;
+}
+
+// POST /prove/deploy — keeper generates the throwaway zkApp keypair, assembles
+// the deploy+initialize tx, proves it, and signs the zkApp AccountUpdate with
+// the throwaway key. The caller forwards `provenTxJson` to the vendor's wallet
+// for the fee-payer signature.
+//
+// At least one of the three prices must be > 0 (enforced by the keeper *and*
+// by the circuit's `initialize()`).
+export async function proveDeploy(req: ProveDeployRequest): Promise<ProveDeployResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/deploy`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      senderPublicKey:   req.senderPublicKey,
+      vendorAddress:     req.vendorAddress,
+      priceMonthlyMina:  req.priceMonthlyMina,
+      priceYearlyMina:   req.priceYearlyMina,
+      priceFiveYearMina: req.priceFiveYearMina,
+    }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as ProveDeployResponse;
+}
+
+export type PollDeployStatusOptions = {
+  keeperUrl:      string;
+  zkAppAddress:   string;
+  fetcher?:       typeof fetch;
+  intervalMs?:    number;  // default 3 000
+  timeoutMs?:     number;  // default 10 min
+  signal?:        AbortSignal;
+  onTick?:        (status: DeployStatus) => void;
+};
+
+// Polls GET /deploy/status until it returns a terminal state ('confirmed' or
+// 'failed') or the timeout fires. 'unknown' means the keeper hasn't seen the
+// tx yet (register step not called or watch not armed).
+export async function pollDeployStatus(opts: PollDeployStatusOptions): Promise<DeployStatus> {
+  const fetcher = opts.fetcher ?? fetch;
+  const interval = opts.intervalMs ?? 3_000;
+  const timeout = opts.timeoutMs ?? 10 * 60 * 1000;
+  const deadline = Date.now() + timeout;
+  const url = `${baseUrl(opts.keeperUrl)}/deploy/status?zkAppAddress=${encodeURIComponent(opts.zkAppAddress)}`;
+
+  while (true) {
+    if (opts.signal?.aborted) throw new Error('pollDeployStatus aborted');
+    let status: DeployStatus = { status: 'unknown' };
+    try {
+      const resp = await fetcher(url, { signal: opts.signal });
+      if (resp.ok) status = await resp.json() as DeployStatus;
+    } catch { /* transient network — try again on next tick */ }
+    opts.onTick?.(status);
+    if (status.status === 'confirmed' || status.status === 'failed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}
+
+// ─── Admin redeploy (post-hardfork v1 → v2 migration) ────────────────────────
+//
+// Wraps the keeper's `/admin/redeploy*` endpoints. These are platform-operator
+// tools — the keeper pays gas with its own FEEPAYER_KEY and reads authoritative
+// vendor/prices from the on-chain v1 contract, so the caller supplies no
+// per-app parameters. Guards enforced keeper-side: refund window closed,
+// escrow empty, on-chain version still in supported range. Auth is
+// KEEPER_ADMIN_TOKEN as a Bearer header.
+
+export type RedeployAppRequest = {
+  keeperUrl:  string;
+  appId:      string;
+  adminToken: string;
+  // Bypass the `escrowRoot === EMPTY_ROOT` guard. Other guards (refund
+  // window, app status, on-chain version, keeper key configuration) are not
+  // bypassable. Buyers with unrefunded escrow can still call requestRefund
+  // against the retired v1 address directly (its on-chain state persists).
+  force?:     boolean;
+  fetcher?:   typeof fetch;
+  signal?:    AbortSignal;
+};
+
+export type RedeployAppResponse = {
+  ok:                  true;
+  zkAppAddress:        string;
+  txHash:              string;
+  verificationKeyHash: string;
+  onChainVersion:      number;
+  // Present (=== true) when `force: true` was used and the v1 escrowRoot was
+  // non-empty at the time of redeploy. Absent otherwise.
+  forcedEscrowNonEmpty?: true;
+};
+
+export type RedeployAllRequest = {
+  keeperUrl:  string;
+  adminToken: string;
+  // Applied uniformly to every app in the batch. See RedeployAppRequest.force.
+  force?:     boolean;
+  fetcher?:   typeof fetch;
+  signal?:    AbortSignal;
+};
+
+export type RedeployAllResponse = {
+  ok:        true;
+  count:     number;
+  succeeded: number;
+  results:   Array<
+    | { appId: string; ok: true;  zkAppAddress: string; txHash: string; verificationKeyHash: string; onChainVersion: number; forcedEscrowNonEmpty?: true }
+    | { appId: string; ok: false; error: string }
+  >;
+};
+
+function adminHeaders(token: string): Record<string, string> {
+  return {
+    'Content-Type':  'application/json',
+    'Authorization': `Bearer ${token}`,
+  };
+}
+
+// POST /admin/redeploy/:appId — one-shot migration for a single app. Rejects
+// with a descriptive error if any keeper-side guard fails (409) or the deploy
+// itself throws (500). The returned `zkAppAddress` is the *new* v2 address; the
+// old one stays on chain but is no longer referenced by keeper records.
+export async function redeployApp(req: RedeployAppRequest): Promise<RedeployAppResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/admin/redeploy/${encodeURIComponent(req.appId)}`, {
+    method:  'POST',
+    headers: adminHeaders(req.adminToken),
+    signal:  req.signal,
+    body:    JSON.stringify(req.force ? { force: true } : {}),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as RedeployAppResponse;
+}
+
+// POST /admin/redeploy-all — iterate every registered app and attempt migration.
+// Idempotent: apps already migrated surface as ok:false with a clear error, so
+// a rerun after a partial failure retries only the remaining ones. Callers
+// should inspect `results` for per-app outcomes rather than relying on the
+// top-level `ok`, which is always true unless the whole request failed.
+export async function redeployAll(req: RedeployAllRequest): Promise<RedeployAllResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/admin/redeploy-all`, {
+    method:  'POST',
+    headers: adminHeaders(req.adminToken),
+    signal:  req.signal,
+    body:    JSON.stringify(req.force ? { force: true } : {}),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as RedeployAllResponse;
+}
+
+// ─── Vendor-triggered redeploy (post-hardfork v1 → v2 migration) ─────────────
+//
+// Same migration flow as the admin path, but authenticated by a Mina signature
+// against the on-chain vendor of the target app (no admin token required).
+// Vendor pays gas via their own fee-payer AU. Three-step flow, mirroring
+// first-time /prove/deploy → wallet-broadcast → /apps register:
+//
+//   1. getVendorRedeployChallenge      → { nonce, expiresAt }
+//   2. vendor's wallet signs `nonce`  → { field, scalar }
+//   3. proveVendorRedeploy             → { provenTxJson, zkAppAddress, redeployId }
+//   4. wallet adds fee-payer sig + broadcasts (mirrors proveDeploy flow)
+//   5. registerVendorRedeploy          → arms the keeper's deploy-watcher on
+//                                        the new address. On landing, keeper
+//                                        promotes the new deployment onto the
+//                                        AppRecord (deploymentHistory[] etc).
+//
+// `force: true` is allowed on the vendor path (same semantics as admin —
+// bypasses the escrow-empty guard; unrefunded buyers retain the v1 refund
+// path against the retired address). All other guards (freeze slot
+// configured, refund window closed, active status, supported version) apply.
+//
+// ⚠ Vendor-embedded buy links — after redeploy, `proveVendorRedeploy` returns
+// the NEW v2 `zkAppAddress`. Platform-hosted marketplace pages handle this
+// automatically: the marketplace stores your registered `buyUrl`/`renewUrl`/
+// `refundUrl` as base URLs and appends `?app=<zkAppAddress>&network=<net>`
+// at render time, so the "Get" button routes to the new v2 address the
+// moment `finalizeRedeploy` promotes it onto the AppRecord — no vendor
+// action required. Only vendor-hosted surfaces where the raw `zkAppAddress`
+// is hand-embedded (docs, storefront, emails) need manual updating.
+// Existing licenses on the retired v1 address remain independently
+// verifiable (v1 on-chain state persists), but new buys against the old URL
+// would land on the retired contract and be refused (its v1 version is
+// outside the supported range
+// after migration).
+
+export type VendorRedeployPreflight = {
+  // True iff the vendor path can proceed without `force`. Escrow non-empty is
+  // NOT part of `ok`: the button should still be actionable with a
+  // force-required warning when the only failing guard is escrow.
+  ok:                    boolean;
+  freezeSlotConfigured:  boolean;
+  appExists:             boolean;
+  status?:               'active' | 'inactive' | 'pending';
+  refundWindow:          { closed: boolean; opensAtSlot: number; currentSlot: number };
+  onChainAccount:        { exists: boolean };
+  // `empty: false` alone does not disqualify the redeploy — `force: true` on
+  // /prove bypasses this guard. UIs should surface the state as a warning.
+  escrow:                { empty: boolean };
+  version:               { current: number; supported: boolean; supportedList: readonly number[] };
+  // Human-readable reasons for every failing guard, in evaluation order. Empty
+  // array iff every guard passes and no force is needed.
+  reasons:               string[];
+};
+
+// GET /vendor/redeploy/:appId/preflight — read-only guard status. No nonce
+// consumed, no signature required. UI decides button state from the returned
+// fields; 404 means the app itself is unknown (a distinct failure mode from a
+// known app failing individual guards).
+export async function fetchVendorRedeployPreflight(opts: {
+  keeperUrl: string;
+  appId:     string;
+  fetcher?:  typeof fetch;
+  signal?:   AbortSignal;
+}): Promise<VendorRedeployPreflight> {
+  const fetcher = opts.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(opts.keeperUrl)}/vendor/redeploy/${encodeURIComponent(opts.appId)}/preflight`, {
+    signal: opts.signal,
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as VendorRedeployPreflight;
+}
+
+export type VendorRedeployChallenge = {
+  nonce:     string;
+  expiresAt: number; // ms epoch
+};
+
+// GET /vendor/redeploy/:appId/challenge — mint a one-shot nonce that the
+// vendor's wallet signs. The nonce is bound to the appId and expires in 60s;
+// consumed on /prove.
+export async function getVendorRedeployChallenge(opts: {
+  keeperUrl: string;
+  appId:     string;
+  fetcher?:  typeof fetch;
+  signal?:   AbortSignal;
+}): Promise<VendorRedeployChallenge> {
+  const fetcher = opts.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(opts.keeperUrl)}/vendor/redeploy/${encodeURIComponent(opts.appId)}/challenge`, {
+    signal: opts.signal,
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as VendorRedeployChallenge;
+}
+
+export type ProveVendorRedeployRequest = {
+  keeperUrl:       string;
+  appId:           string;
+  nonce:           string;
+  signature:       { field: string; scalar: string };
+  senderPublicKey: string; // vendor's fee-payer wallet
+  // Bypass the `escrowRoot === EMPTY_ROOT` guard. Unlike the admin path this
+  // is available to the vendor as well — in case the freeze is scheduled
+  // late enough that a straggling refund is still pending when they want to
+  // migrate. Buyers with unrefunded escrow can still call requestRefund
+  // against the retired v1 address directly (its on-chain state persists).
+  force?:          boolean;
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+export type ProveVendorRedeployResponse = {
+  provenTxJson:         string;
+  // New v2 zkApp address (fresh throwaway keypair, discarded by the keeper).
+  // Marketplace links auto-update: the platform appends `?app=<zkAppAddress>
+  // &network=<net>` to your registered `buyUrl`/`renewUrl`/`refundUrl` at
+  // render time, so the "Get" button routes to this new address once
+  // `finalizeRedeploy` promotes it onto the AppRecord — no vendor action
+  // required. Only vendor-hosted surfaces where the raw address is embedded
+  // by hand need manual updating.
+  zkAppAddress:         string;
+  verificationKeyHash:  string;
+  redeployId:           string; // capability token — pass to registerVendorRedeploy
+  // Present (=== true) when `force: true` was used and the v1 escrowRoot was
+  // non-empty at the time of the prove call. Absent otherwise.
+  forcedEscrowNonEmpty?: true;
+};
+
+// POST /vendor/redeploy/:appId/prove — keeper verifies the nonce + signature
+// against the on-chain vendor of the app, runs all redeploy guards, generates
+// a throwaway zkApp keypair, builds and proves the deploy+initialize tx, and
+// signs the zkApp AU with the throwaway key. Returns the tx JSON for the
+// vendor's wallet to add the fee-payer signature and broadcast.
+export async function proveVendorRedeploy(req: ProveVendorRedeployRequest): Promise<ProveVendorRedeployResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/vendor/redeploy/${encodeURIComponent(req.appId)}/prove`, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal:  req.signal,
+    body:    JSON.stringify({
+      nonce:           req.nonce,
+      signature:       req.signature,
+      senderPublicKey: req.senderPublicKey,
+      ...(req.force ? { force: true } : {}),
+    }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as ProveVendorRedeployResponse;
+}
+
+export type RegisterVendorRedeployRequest = {
+  keeperUrl:  string;
+  appId:      string;
+  redeployId: string; // capability token from proveVendorRedeploy
+  txHash:     string; // returned by the vendor's wallet after broadcast
+  fetcher?:   typeof fetch;
+  signal?:    AbortSignal;
+};
+
+// POST /vendor/redeploy/:appId/register — arm the keeper's deploy-watcher on
+// the new address. On confirmation the keeper mutates AppRecord to promote
+// the new deployment (push old to deploymentHistory[], overwrite live fields,
+// clear event-sync cursors). Idempotent to duplicate calls (the watcher
+// checks whether one is already armed for the address). Poll GET
+// /deploy/status?zkAppAddress=<new> — or use pollDeployStatus — for landing
+// progress, same as first-time deploys.
+export async function registerVendorRedeploy(req: RegisterVendorRedeployRequest): Promise<{ ok: true }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/vendor/redeploy/${encodeURIComponent(req.appId)}/register`, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal:  req.signal,
+    body:    JSON.stringify({ redeployId: req.redeployId, txHash: req.txHash }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as { ok: true };
+}

package/src/freezeClient.ts

@@ -0,0 +1,117 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * freezeClient.ts
+ *
+ * Client-side view of the keeper's sales-freeze schedule. A freeze is set
+ * ahead of a hardfork so every open escrow window can drain (refund or
+ * release) before v1 → v2 migration. Once past the freeze slot the keeper
+ * refuses new buys and renewals; refunds and verify remain open.
+ *
+ * Resolution order for buy/renew clients that want to know the current
+ * freeze state:
+ *   1. Caller-supplied `freezeAfterSlot` (explicit override — build-time
+ *      constant, or pulled from the vendor's own env at boot).
+ *   2. `process.env.FREEZE_AFTER_SLOT` when running under Node (server-side
+ *      integrators / CLIs).
+ *   3. Keeper's own `/health` payload — the authoritative source of truth.
+ *
+ * A `freezeAfterSlot` of 0 / null / undefined means "no freeze scheduled".
+ */
+
+export type KeeperHealth = {
+  status:          string;
+  network:         string;
+  slot:            number;
+  salesFrozen:     boolean;
+  freezeAfterSlot: number | null;
+};
+
+export type FreezeState = {
+  // True when the current slot is past freezeAfterSlot — new buys and
+  // renewals are refused keeper-side.
+  salesFrozen:     boolean;
+  // Scheduled freeze slot (announced ahead of a hardfork). Null when no
+  // freeze is configured. Buy clients should require an explicit
+  // refund-window waiver only when the buyer's 14-day refund window would
+  // extend past this slot (i.e. currentSlot + REFUND_WINDOW_N > freezeAfterSlot).
+  freezeAfterSlot: number | null;
+  // Chain slot at resolution time. Populated from /health; null on the
+  // caller-override / env paths where the slot is not known client-side.
+  // Callers computing refund-window overlap should treat null
+  // conservatively (require the waiver) — the keeper's own guard is still
+  // the last line of defence.
+  currentSlot:     number | null;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+function envFreezeSlot(): number | null {
+  // Runs both in Node (process.env) and browser (no `process`). The typeof
+  // guard keeps bundlers from choking on the reference.
+  if (typeof process === 'undefined' || !process.env) return null;
+  const raw = process.env.FREEZE_AFTER_SLOT;
+  if (!raw) return null;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export type GetKeeperHealthOptions = {
+  keeperUrl: string;
+  fetcher?:  typeof fetch;
+  signal?:   AbortSignal;
+};
+
+// GET /health — raw payload. Callers that only need the freeze state
+// should use resolveFreezeState() instead; this is exposed for UIs that
+// surface slot / network info alongside freeze.
+export async function getKeeperHealth(opts: GetKeeperHealthOptions): Promise<KeeperHealth> {
+  const fetcher = opts.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(opts.keeperUrl)}/health`, { signal: opts.signal });
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+  return await resp.json() as KeeperHealth;
+}
+
+export type ResolveFreezeStateOptions = {
+  keeperUrl:        string;
+  // Explicit override (highest precedence). Null/undefined falls through
+  // to env, then /health.
+  freezeAfterSlot?: number | null;
+  fetcher?:         typeof fetch;
+  signal?:          AbortSignal;
+};
+
+// Resolves the effective freeze state for the caller. When the source is
+// the caller override or process.env, the current slot is not known
+// client-side, so salesFrozen is filled from /health only — the override
+// path returns { freezeAfterSlot: N, salesFrozen: false, currentSlot: null }
+// and lets the keeper reject the actual prove call if the freeze has fired.
+export async function resolveFreezeState(opts: ResolveFreezeStateOptions): Promise<FreezeState> {
+  if (typeof opts.freezeAfterSlot === 'number' && opts.freezeAfterSlot > 0) {
+    return { salesFrozen: false, freezeAfterSlot: opts.freezeAfterSlot, currentSlot: null };
+  }
+  const envSlot = envFreezeSlot();
+  if (envSlot !== null) {
+    return { salesFrozen: false, freezeAfterSlot: envSlot, currentSlot: null };
+  }
+  try {
+    const health = await getKeeperHealth({
+      keeperUrl: opts.keeperUrl,
+      fetcher:   opts.fetcher,
+      signal:    opts.signal,
+    });
+    return {
+      salesFrozen:     health.salesFrozen === true,
+      freezeAfterSlot: typeof health.freezeAfterSlot === 'number' ? health.freezeAfterSlot : null,
+      currentSlot:     typeof health.slot === 'number' ? health.slot : null,
+    };
+  } catch {
+    // /health unreachable — treat as no freeze so we don't block buys on a
+    // transient network hiccup. The keeper's own guard is still the last
+    // line of defense.
+    return { salesFrozen: false, freezeAfterSlot: null, currentSlot: null };
+  }
+}

package/src/generationClient.ts

@@ -0,0 +1,164 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * generationClient.ts
+ *
+ * Browser-safe fetcher for the keeper's signed generation-list. Returns the
+ * app's deployment history — every past address plus the current live one —
+ * verified against a caller-supplied pin list of platform manifest public
+ * keys.
+ *
+ * Trust model: the keeper is not the trust anchor for this data — it can
+ * be re-hosted, mirrored, cached, or (worst case) impersonated. The pin
+ * list is. Any response that fails signature verification is surfaced as
+ * `verified: false` with `generations: []` so callers cannot accidentally
+ * route a wallet prompt to an unverified address.
+ *
+ * Optional corroboration channel: an operator that publishes
+ *   https://<vendor-host>/.well-known/zklicensing/<appId>.json
+ * (using 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 — a 404 at that
+ * URL is not a failure signal, just "no corroboration published for this
+ * app." That's the caller's job, not this module's.
+ */
+
+import { verifyManifestSignature } from './manifestVerify.js';
+
+export interface GenerationEntry {
+  gen:          number;
+  zkAppAddress: string;
+  status:       'retired' | 'live';
+  frozenRoot?:  string;
+  deployedAt?:  string;
+  retiredAt?:   string;
+}
+
+export interface GenerationInfo {
+  /** Live-generation index (matches the entry with status: 'live'). Null when unverified or missing. */
+  current:     number | null;
+  generations: GenerationEntry[];
+  /** True iff signature verified against one of the pinned pubkeys. */
+  verified:    boolean;
+}
+
+export interface FetchGenerationRequest {
+  keeperUrl: string;
+  appId:    string;
+  /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+  pinnedPublicKeysBase64: readonly string[];
+  fetcher?: typeof fetch;
+  signal?:  AbortSignal;
+}
+
+export interface FetchGenerationByAddressRequest {
+  keeperUrl: string;
+  /** Any zkApp address in the app's generation chain — current live or any retired. */
+  zkAppAddress: string;
+  /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+  pinnedPublicKeysBase64: readonly string[];
+  fetcher?: typeof fetch;
+  signal?:  AbortSignal;
+}
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+interface ParsedGenerationBody {
+  current:     number | null;
+  generations: GenerationEntry[];
+  signature:   string | null;
+  issuedAt:    string | null;
+  appId:       string | null;
+}
+
+function parseGenerationBody(body: Record<string, unknown>): ParsedGenerationBody {
+  const gensRaw = body.generations;
+  return {
+    current:     typeof body.current   === 'number' ? body.current   : null,
+    generations: Array.isArray(gensRaw) ? gensRaw as GenerationEntry[] : [],
+    signature:   typeof body.signature === 'string' ? body.signature : null,
+    issuedAt:    typeof body.issuedAt  === 'string' ? body.issuedAt  : null,
+    appId:       typeof body.appId     === 'string' ? body.appId     : null,
+  };
+}
+
+async function verifyAndProject(
+  parsed: ParsedGenerationBody,
+  pinnedPublicKeysBase64: readonly string[],
+): Promise<GenerationInfo> {
+  const { current, generations, signature, issuedAt, appId } = parsed;
+  if (!signature || !issuedAt || !appId || current === null) {
+    return { current, generations, verified: false };
+  }
+  // Reconstruct the canonical payload — must match keeperService's
+  // signPayload input exactly.
+  const canonical = { appId, current, generations, issuedAt };
+  const verified = await verifyManifestSignature(canonical, signature, pinnedPublicKeysBase64);
+  if (!verified) {
+    // Never surface unverified `current`/`generations` — a caller must not
+    // accidentally route a wallet prompt to an address we couldn't authenticate.
+    return { current: null, generations: [], verified: false };
+  }
+  return { current, generations, verified: true };
+}
+
+/**
+ * GET /apps/:appId — returns { appId, current, generations, issuedAt, publicKey, signature }.
+ * We reconstruct the canonical payload (everything except `publicKey` +
+ * `signature`) and verify against the pin list. `publicKey` in the response
+ * is advisory only — it's the key the keeper claims to have signed with;
+ * the SDK never trusts it in place of a pin.
+ */
+export async function fetchGenerationInfo(req: FetchGenerationRequest): Promise<GenerationInfo> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/apps/${encodeURIComponent(req.appId)}`, {
+    method: 'GET',
+    signal: req.signal,
+  });
+  if (!resp.ok) {
+    return { current: null, generations: [], verified: false };
+  }
+  let body: Record<string, unknown>;
+  try { body = await resp.json() as Record<string, unknown>; }
+  catch { return { current: null, generations: [], verified: false }; }
+
+  return verifyAndProject(parseGenerationBody(body), req.pinnedPublicKeysBase64);
+}
+
+/**
+ * GET /apps/by-address/:zkAppAddress — same signed payload as fetchGenerationInfo,
+ * but keyed by an address the caller already has (direct-paste buys, renew on a
+ * since-retired address). Buyers arriving without an appId would otherwise have
+ * to trust the keeper's unsigned `/apps` list to bind their address to an appId
+ * first — defeating the pin.
+ *
+ * Extra assertion beyond the appId flow: the queried address MUST appear in the
+ * returned `generations[]`. Without this, a malicious keeper could return a
+ * validly-signed payload for a DIFFERENT app in response to the query, and the
+ * signature check alone wouldn't catch it.
+ */
+export async function fetchGenerationInfoByAddress(
+  req: FetchGenerationByAddressRequest,
+): Promise<GenerationInfo> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(
+    `${baseUrl(req.keeperUrl)}/apps/by-address/${encodeURIComponent(req.zkAppAddress)}`,
+    { method: 'GET', signal: req.signal },
+  );
+  if (!resp.ok) {
+    return { current: null, generations: [], verified: false };
+  }
+  let body: Record<string, unknown>;
+  try { body = await resp.json() as Record<string, unknown>; }
+  catch { return { current: null, generations: [], verified: false }; }
+
+  const projected = await verifyAndProject(parseGenerationBody(body), req.pinnedPublicKeysBase64);
+  if (!projected.verified) return projected;
+  if (!projected.generations.some(g => g.zkAppAddress === req.zkAppAddress)) {
+    return { current: null, generations: [], verified: false };
+  }
+  return projected;
+}