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

package/src/deployClient.ts

@@ -0,0 +1,517 @@
+// 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 backend'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 backend 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 backend'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;
+  pricePerpetualMina: number;
+  // Per-license device cap, 0..5 (0 = binding disabled). Stored immutably in
+  // the contract's state at deploy; must match the cap the app is registered
+  // with (checked at approval).
+  deviceCap:         number;
+  // Successor-generation deploys pass the announced fork activation slot so
+  // migrated licenses whose pre-fork expiry falls before activation get their
+  // expiry bumped forward at migration time (7-day grace then runs from
+  // activation, preserving renewal stacking). Omit or 0 for first-generation
+  // deploys — no ancestor tree, no bump.
+  forkActivationSlot?: number;
+  // The network to deploy on (the keeper defaults to devnet without it).
+  network?:          'devnet' | 'mainnet';
+  // The app's https:// website, written into the contract's zkappUri (the
+  // fixed half of the vendor's /.well-known trust anchor).
+  website?:          string;
+  // Where the vendor's 98% goes (default: vendorAddress). It never signs;
+  // the vendor can change it later, effective after a 48 h delay.
+  payoutAddress?:    string;
+  fetcher?:          typeof fetch;
+  signal?:           AbortSignal;
+};
+
+export type ProveDeployResponse = {
+  provenTxJson:        string;
+  verificationKeyHash: string;
+  zkAppAddress:        string;
+};
+
+/**
+ * The keeper's deploy watch (GET /deploy/status): `landed` once the zkApp
+ * account is on chain, `timeout` if the watch gave up waiting, `unknown` for
+ * an address it isn't watching.
+ */
+export type DeployStatus = {
+  status:               'unknown' | 'pending' | 'landed' | 'timeout';
+  landedAtSlot?:        number;
+  landedAtBlockHeight?: 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 — the backend 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 four tier prices must be > 0 (enforced by the backend
+// *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,
+      pricePerpetualMina: req.pricePerpetualMina,
+      deviceCap:          req.deviceCap,
+      ...(req.forkActivationSlot !== undefined ? { forkActivationSlot: req.forkActivationSlot } : {}),
+      ...(req.network ? { network: req.network } : {}),
+      ...(req.website ? { website: req.website } : {}),
+      ...(req.payoutAddress ? { payoutAddress: req.payoutAddress } : {}),
+    }),
+  });
+  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 ('landed' or
+// 'timeout') or the timeout fires. 'unknown' means the backend 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 === 'landed' || status.status === 'timeout') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}
+
+// ─── Admin redeploy ──────────────────────────────────────────────────────────
+//
+// Wraps the backend's `/admin/redeploy*` endpoints. These are platform-operator
+// tools; the backend reads the authoritative vendor/prices from chain. The
+// admin wallet (the platform key; the keeper holds no key) signs the retire
+// and pays: a call answers { step: 'sign-retire', retireMessage } until
+// `retireSignature` is given; with it and `feePayer` (the admin wallet's
+// address) it answers the proved transaction of the app's next step, which
+// the wallet signs and sends, then registerAdminRedeploy. Before a hard fork
+// the step retires the app (`step: 'retire'`); after it, it deploys the
+// successor, which starts with the retired app's licenses (`step: 'deploy'`).
+// Guards enforced by the backend: refund window closed, escrow empty,
+// on-chain version still in supported range. Auth is a platform-admin bearer
+// token.
+
+export type RedeployAppRequest = {
+  keeperUrl:  string;
+  appId:      string;
+  adminToken: string;
+  network?:   'devnet' | 'mainnet';
+  // The platform key's base58 signature over `retireMessage` from a
+  // sign-retire answer, made in the admin wallet (the keeper holds no key).
+  retireSignature?: string;
+  // The admin wallet's address: it signs, sends and pays for the step.
+  feePayer?:  string;
+  // Retire with purchases still in escrow (their funds stay on the old
+  // contract for good); the platform key signs it. Last resort ahead of a fork.
+  force?:     boolean;
+  fetcher?:   typeof fetch;
+  signal?:    AbortSignal;
+};
+
+/**
+ * A proved redeploy step for the signer's wallet to sign, send and pay
+ * (vendor or admin wallet); then register its hash with `redeployId`.
+ */
+export type RedeployTx =
+  | { step: 'retire'; provenTxJson: string; redeployId: string; retiredAddress: string; successor: string }
+  | { step: 'retireAndDeploy' | 'deploy'; provenTxJson: string; redeployId: string; retiredAddress: string; zkAppAddress: string; verificationKeyHash: string };
+
+/** The step a redeploy call took. */
+export type RedeployStepResult =
+  | { step: 'sign-retire'; retireMessage: string[]; licensesRoot: string; successor: string; then: 'retire' | 'retireAndDeploy' | 'deploy'; force: boolean }
+  | RedeployTx;
+
+export type RedeployAppResponse = { ok: true } & RedeployStepResult;
+
+export type RedeployAllRequest = {
+  keeperUrl:  string;
+  adminToken: string;
+  network?:   'devnet' | 'mainnet';
+  fetcher?:   typeof fetch;
+  signal?:    AbortSignal;
+};
+
+export type RedeployAllResponse = {
+  ok:      true;
+  count:   number;
+  /** Apps whose retirement gate is up, ready for their next step. */
+  ready:   number;
+  results: Array<
+    | { appId: string; ok: true; step: 'retire' | 'retireAndDeploy' | 'deploy'; readyAt: number }
+    | { 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 — the next redeploy step for a single app.
+// Rejects with a descriptive error if any backend guard fails (409) or the
+// transaction itself throws (500). After a deploy step the returned
+// `zkAppAddress` is the successor's; the old one stays on chain, retired.
+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.network ? { network: req.network } : {}),
+      ...(req.retireSignature ? { retireSignature: req.retireSignature } : {}),
+      ...(req.feePayer ? { feePayer: req.feePayer } : {}),
+      ...(req.force ? { force: true } : {}),
+    }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as RedeployAppResponse;
+}
+
+// POST /admin/redeploy/:appId/register — the admin wallet sent the proved
+// step: a retire is marked on the app; a deploy is watched until it lands,
+// then the app moves to its successor.
+export async function registerAdminRedeploy(req: { keeperUrl: string; appId: string; adminToken: string; redeployId: string; txHash: string; fetcher?: typeof fetch; signal?: AbortSignal }): Promise<{ ok: true; step: 'retire' | 'deploy' }> {
+  const resp = await (req.fetcher ?? fetch)(`${baseUrl(req.keeperUrl)}/admin/redeploy/${encodeURIComponent(req.appId)}/register`, {
+    method: 'POST', headers: adminHeaders(req.adminToken), 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; step: 'retire' | 'deploy' };
+}
+
+// POST /admin/redeploy-all — raises every eligible app's retirement gate at
+// once (one shared drain) and reports each app's next step; the admin wallet
+// then takes them one app at a time with redeployApp (it signs and pays).
+// Apps that can't be redeployed surface as ok:false with the reason.
+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.network ? { network: req.network } : {}),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as RedeployAllResponse;
+}
+
+// ─── Vendor-triggered redeploy ───────────────────────────────────────────────
+//
+// Same steps as the admin path, but authenticated by a Mina signature against
+// the on-chain vendor of the target app (no admin token required), and the
+// vendor signs the retire. The vendor's wallet pays for every step (retire
+// and successor). Flow, mirroring first-time /prove/deploy →
+// wallet-broadcast → /apps register:
+//
+//   1. getVendorRedeployChallenge      → { nonce, expiresAt }
+//   2. vendor's wallet signs `nonce`  → { field, scalar }
+//   3. proveVendorRedeploy             → 202 draining (come back after readyAt),
+//                                        202 sign-retire (sign retireMessage with
+//                                        signFields, call again with
+//                                        retireSignature), then
+//                                        { step, provenTxJson, redeployId, … }
+//                                        (step 'retire' before a fork)
+//   4. wallet adds fee-payer sig + broadcasts (mirrors proveDeploy flow)
+//   5. registerVendorRedeploy          → a retire is marked on the app; a
+//                                        deploy arms the backend's
+//                                        deploy-watcher on the new address. On
+//                                        landing, the backend promotes the new
+//                                        deployment onto the AppRecord
+//                                        (deploymentHistory[] etc).
+//
+// Each call to step 3 needs a fresh challenge. Guards (freeze slot
+// configured, refund window closed, escrow empty, active status, supported
+// version) all apply; an app retires only with an empty escrow.
+//
+// ⚠ Vendor-embedded buy links — after redeploy, `proveVendorRedeploy` returns
+// the successor's `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 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 carry on in the successor under the same hash; the retired
+// address refuses new buys.
+
+export type VendorRedeployPreflight = {
+  // True iff every guard passes and the redeploy can proceed.
+  ok:                    boolean;
+  freezeSlotConfigured:  boolean;
+  appExists:             boolean;
+  status?:               'active' | 'inactive' | 'pending';
+  refundWindow:          { closed: boolean; opensAtSlot: number; currentSlot: number };
+  onChainAccount:        { exists: boolean };
+  // The app retires only with an empty escrow: wait for refunds and releases.
+  escrow:                { empty: boolean };
+  version:               { current: number; supported: boolean; supportedList: readonly number[] };
+  // Live deployment already runs the keeper's current circuit.
+  alreadyCurrent:        boolean;
+  // The live deployment is retired on chain: its successor is next.
+  retired:               boolean;
+  // The platform is draining the app: new purchases are paused until the escrow is empty.
+  draining:              { startedAt: string } | null;
+  // What the redeploy would do next (null when a guard blocks it).
+  step:                  'retire' | 'retireAndDeploy' | 'deploy' | null;
+  // Set while a redeploy is in progress: the current deployment is read-only
+  // (no buys, renewals or device changes) until the successor lands. Before
+  // `readyAt` the prove call answers `draining`.
+  retirement:            { readyAt: number; expiresAt: number } | null;
+  // Human-readable reasons for every failing guard, in evaluation order.
+  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;
+  network:   'devnet' | 'mainnet';
+  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?network=${opts.network}`, {
+    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;
+  /** The deployment to redeploy (the keeper requires it). */
+  network:   'devnet' | 'mainnet';
+  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?network=${opts.network}`, {
+    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
+  // The vendor's base58 signature over `retireMessage` (from the sign-retire
+  // answer), made with the wallet's signFields.
+  retireSignature?: string;
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+// The successor's zkApp address (on a deploy step) is where the app moves.
+// 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. `redeployId` is the capability token for
+// registerVendorRedeploy.
+export type ProveVendorRedeployResponse = RedeployTx;
+
+// Returned (HTTP 202) by the first prove call: the keeper has made the current
+// deployment read-only and is waiting out in-flight proofs before the app can
+// retire. Call proveVendorRedeploy again (fresh challenge + signature) after
+// `readyAt`, before `expiresAt`.
+export type VendorRedeployDraining = {
+  status:    'draining';
+  readyAt:   number;   // epoch ms
+  expiresAt: number;   // epoch ms — the pause lifts if the redeploy isn't finished
+  message:   string;
+};
+
+// Returned (HTTP 202) when the app must retire and no retireSignature was
+// given: sign `retireMessage` (field strings) with the vendor key and call
+// again with `retireSignature`.
+export type VendorRedeploySignRetire = {
+  status:        'sign-retire';
+  retireMessage: string[];
+  licensesRoot:  string;
+  /** The new zkApp address the retirement names: only it can start from these licenses. */
+  successor:     string;
+  message:       string;
+};
+
+// POST /vendor/redeploy/:appId/prove — the backend verifies the nonce +
+// signature against the on-chain vendor of the app and runs all redeploy
+// guards, then answers with the next step (see the flow above).
+export async function proveVendorRedeploy(req: ProveVendorRedeployRequest): Promise<
+  ProveVendorRedeployResponse | VendorRedeployDraining | VendorRedeploySignRetire
+> {
+  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.retireSignature ? { retireSignature: req.retireSignature } : {}),
+    }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as ProveVendorRedeployResponse | VendorRedeployDraining | VendorRedeploySignRetire;
+}
+
+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 backend's deploy-watcher on
+// the new address. On confirmation the backend 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.
+// POST /vendor/redeploy/:appId/cancel — calls off the vendor's redeploy
+// (gate, drain) before the app is retired on chain. A fresh signed challenge.
+export async function cancelVendorRedeploy(req: { keeperUrl: string; appId: string; nonce: string; signature: { field: string; scalar: string }; fetcher?: typeof fetch; signal?: AbortSignal }): Promise<{ ok: true }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/vendor/redeploy/${encodeURIComponent(req.appId)}/cancel`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: req.signal,
+    body: JSON.stringify({ nonce: req.nonce, signature: req.signature }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as { ok: true };
+}
+
+// POST /admin/redeploy/:appId/drain — the platform starts a redeploy of an
+// app with purchases in escrow: new purchases pause until it is empty.
+export async function startRedeployDrain(req: { keeperUrl: string; appId: string; adminToken: string; network: 'devnet' | 'mainnet'; fetcher?: typeof fetch }): Promise<{ ok: true; draining: { startedAt: string }; alreadyEmpty: boolean }> {
+  const resp = await (req.fetcher ?? fetch)(`${baseUrl(req.keeperUrl)}/admin/redeploy/${encodeURIComponent(req.appId)}/drain`, {
+    method: 'POST', headers: adminHeaders(req.adminToken), body: JSON.stringify({ network: req.network }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as { ok: true; draining: { startedAt: string }; alreadyEmpty: boolean };
+}
+
+// POST /admin/redeploy/:appId/cancel — calls off a redeploy or drain not yet retired on chain.
+export async function cancelRedeploy(req: { keeperUrl: string; appId: string; adminToken: string; network: 'devnet' | 'mainnet'; fetcher?: typeof fetch }): Promise<{ ok: true }> {
+  const resp = await (req.fetcher ?? fetch)(`${baseUrl(req.keeperUrl)}/admin/redeploy/${encodeURIComponent(req.appId)}/cancel`, {
+    method: 'POST', headers: adminHeaders(req.adminToken), body: JSON.stringify({ network: req.network }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as { ok: true };
+}
+
+// POST /admin/redeploy-notice — ahead of an announced hard fork, emails the vendors of live apps.
+export async function sendRedeployNotices(req: { keeperUrl: string; adminToken: string; network: 'devnet' | 'mainnet'; fetcher?: typeof fetch }): Promise<{ ok: true; notified: string[]; forkActivationSlot: number }> {
+  const resp = await (req.fetcher ?? fetch)(`${baseUrl(req.keeperUrl)}/admin/redeploy-notice`, {
+    method: 'POST', headers: adminHeaders(req.adminToken), body: JSON.stringify({ network: req.network }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as { ok: true; notified: string[]; forkActivationSlot: number };
+}
+
+export async function registerVendorRedeploy(req: RegisterVendorRedeployRequest): Promise<{ ok: true; step: 'retire' | 'deploy' }> {
+  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; step: 'retire' | 'deploy' };
+}