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

package/src/agentRecord.ts

@@ -0,0 +1,121 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * agentRecord.ts — part of `zklicensing/agent/actions`
+ *
+ * A signed record of one action an AI agent took: what it did (action,
+ * target, amounts, transaction, receipt number), under which boundary (a
+ * hash of the owner's spending policy, the standing consent it relied on)
+ * and when, signed by the agent's own key. A portable claim about the
+ * agent's activity that anyone can check with `verifyActionRecord`, kept
+ * apart from the license or permit file.
+ *
+ * What it establishes, and what it doesn't (`limits`, repeated in every
+ * record): the agent key signed this account of the action, and the
+ * transaction is on chain for anyone to check. It does not prove the policy
+ * was enforced: that ran in software on the owner's machine, not in an
+ * attested environment, so a compromised host could have bypassed it. Nor
+ * does it cover anything the agent did by another path.
+ */
+
+import type { Network, PreparedAction } from './agent.js';
+
+export const ACTION_RECORD_LIMITS =
+  'Signed by the agent key: an account of the action and the boundary it was taken under. The transaction is on chain. ' +
+  'The owner\'s policy was enforced in software on the owner\'s machine, not in an attested environment, and this record does not cover actions taken by other paths.';
+
+export type AgentActionRecord = {
+  type: 'zklicensing-agent-action';
+  version: 1;
+  network: Network;
+  action: PreparedAction['action'] | 'register-app' | 'set-prices';
+  /** The agent wallet that acted and signed. */
+  agent: string;
+  /** The zkApp or registry acted on. */
+  target: string;
+  /** License hash or permit subject. */
+  reference: string;
+  summary: string;
+  /** Nanomina, as prepared: total leaves the payer. */
+  amounts: PreparedAction['amounts'];
+  txHash: string;
+  /** The receipt or credit note number the keeper issued, if any. */
+  receipt: string | null;
+  /** SHA-256 of the owner's policy (canonical JSON), or null when none was set. */
+  policySha256: string | null;
+  /** The standing consent relied on (its statement's SHA-256), or none. */
+  consent: { givenBy: 'none' } | { givenBy: 'agent'; statementSha256: string; kinds: string[] };
+  at: string;
+  limits: string;
+  /** The text the agent key signed (actionRecordStatement). */
+  statement: string;
+  signature: { field: string; scalar: string };
+};
+
+type RecordFields = Omit<AgentActionRecord, 'type' | 'version' | 'limits' | 'statement' | 'signature'>;
+
+async function sha256Hex(text: string): Promise<string> {
+  const d = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+  return [...new Uint8Array(d)].map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/** JSON with object keys sorted, so the same policy always hashes the same. */
+export function canonicalJson(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
+  if (v && typeof v === 'object') {
+    return `{${Object.keys(v as object).sort().filter(k => (v as any)[k] !== undefined).map(k => `${JSON.stringify(k)}:${canonicalJson((v as any)[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}
+
+/** SHA-256 of a policy's canonical JSON; null for no policy. */
+export async function policyHash(policy: unknown): Promise<string | null> {
+  return policy ? sha256Hex(canonicalJson(policy)) : null;
+}
+
+/** The exact text the agent key signs. */
+export function actionRecordStatement(r: RecordFields): string {
+  const a = r.amounts;
+  return [
+    'zkLicensing agent action record',
+    `network: ${r.network}`,
+    `action: ${r.action}`,
+    `agent: ${r.agent}`,
+    `target: ${r.target}`,
+    `reference: ${r.reference}`,
+    `summary: ${r.summary}`,
+    `amount: ${a.total} nanomina (to ${a.recipient}: ${a.toRecipient}; platform: ${a.toPlatform})`,
+    `transaction: ${r.txHash}`,
+    `receipt: ${r.receipt ?? 'none'}`,
+    `policy sha256: ${r.policySha256 ?? 'none'}`,
+    `consent: ${r.consent.givenBy === 'agent' ? `standing consent ${r.consent.statementSha256} (${r.consent.kinds.join(', ')})` : 'none'}`,
+    `at: ${r.at}`,
+    `limits: ${ACTION_RECORD_LIMITS}`,
+  ].join('\n');
+}
+
+/** Signs a record with the agent wallet (a text signature, as for sign-in). */
+export async function signActionRecord(wallet: { address: string; signMessage(m: string): Promise<{ field: string; scalar: string }> }, fields: Omit<RecordFields, 'agent'>): Promise<AgentActionRecord> {
+  const r: RecordFields = { ...fields, agent: wallet.address };
+  const statement = actionRecordStatement(r);
+  return { type: 'zklicensing-agent-action', version: 1, ...r, limits: ACTION_RECORD_LIMITS, statement, signature: await wallet.signMessage(statement) };
+}
+
+/**
+ * Checks a record: its text matches its fields and the agent key signed it.
+ * Pass `policy` to check that it was taken under that policy, and the
+ * transaction can be looked up on chain by its hash.
+ */
+export async function verifyActionRecord(r: AgentActionRecord, opts: { policy?: unknown } = {}): Promise<{ ok: boolean; reason: string | null }> {
+  if (r?.type !== 'zklicensing-agent-action' || r.version !== 1) return { ok: false, reason: 'not an agent action record' };
+  const { type: _t, version: _v, limits, statement, signature, ...fields } = r;
+  if (limits !== ACTION_RECORD_LIMITS) return { ok: false, reason: 'the limits text was changed' };
+  if (statement !== actionRecordStatement(fields)) return { ok: false, reason: 'the statement does not match the record' };
+  if (opts.policy !== undefined && (await policyHash(opts.policy)) !== r.policySha256) return { ok: false, reason: 'taken under another policy' };
+  const { default: Client } = await import('mina-signer');
+  const signer = new Client({ network: r.network === 'mainnet' ? 'mainnet' : 'testnet' });
+  return signer.verifyMessage({ data: statement, publicKey: r.agent, signature })
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'the signature does not verify for the agent key' };
+}

package/src/agentVendor.ts

@@ -0,0 +1,356 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * agentVendor.ts — part of `zklicensing/agent/actions`
+ *
+ * A vendor run by an AI agent: the agent's key is the vendor wallet (it
+ * receives the payments and signs for the app), acting for its owner.
+ *
+ *   acceptVendorTerms   the Vendor Terms and legal details, under a standing
+ *                       consent covering vendor-terms (recorded as given by
+ *                       the agent)
+ *   registerApp         deploys the app's contract (paying the registration
+ *                       fee; the consent covers its withdrawal waiver) and
+ *                       lists it
+ *   setPrices           changes the tier prices on chain
+ *   updateListing       edits the listing (re-reviewed on mainnet)
+ *   updateDetails       changes the legal details on every app
+ *   status, feeStatement, trustManifest
+ *
+ * Every step checks the owner's policy (allowed actions, networks, targets,
+ * per-action and daily caps); paying steps return a signed action record.
+ * What an agent cannot do: host files on the vendor's own website (the
+ * trust manifest, and on mainnet the vendor's buy, renew and refund pages).
+ */
+
+import { AgentError, type Network } from './agent.js';
+import {
+  checkActionPolicy, consentFor,
+  type AgentWallet, type AgentPolicy, type SpendLedger, type StandingConsent,
+} from './agentActions.js';
+import { signActionRecord, policyHash } from './agentRecord.js';
+
+/** Registration fee per network (MINA), as the keeper charges it; plus 1 MINA account creation and the transaction fee. */
+export const REGISTRATION_FEE_MINA: Record<Network, number> = { devnet: 10, mainnet: 1200 };
+const VENDOR_TC_ORIGIN = 'https://zklicensing.com';
+
+export type VendorTerms = { title: string; version: string; documentHash: string; archiveUrl: string };
+
+export type VendorLegalInput = {
+  legalName: string;
+  invoiceEmail: string;
+  /** ISO 3166-1 alpha-2. */
+  country: string;
+  billingAddress: { line1: string; line2?: string; city: string; postalCode: string };
+  /** VAT or tax ID (required; EU numbers are checked in VIES). */
+  vatId: string;
+  companyRegistrationRegistry: string;
+  companyRegistrationNumber: string;
+};
+
+export type VendorListing = {
+  appId: string;
+  name: string;
+  description: string;
+  longDescription?: string;
+  category: string;
+  /** https:// — written into the contract at deployment and fixed after. */
+  website: string;
+  supportEmail: string;
+  contactEmail?: string;
+  tags?: string[];
+  showInMarketplace?: boolean;
+  /** MINA per tier; 0 = not offered (at least one above 0). */
+  prices: { monthly: number; yearly: number; fiveYear: number; perpetual: number };
+  /** Devices a license can bind, 0..5 (fixed at deployment). */
+  deviceCap?: number;
+  /** Your own buy / renew / refund pages (required on mainnet) and policy pages. */
+  buyUrl?: string; renewUrl?: string; refundUrl?: string;
+  termsOfServiceUrl?: string; privacyPolicyUrl?: string; refundPolicyUrl?: string;
+};
+
+/** The vendor acceptance text the wallet signs (the keeper derives the same). */
+export function vendorAcceptanceMessage(f: {
+  vendorAddress: string; terms: VendorTerms; legalName: string; country: string; vatId: string; billingHash: string; acceptedAt: string;
+}): string {
+  return [
+    'I accept the zkLicensing Vendor Terms of Service.',
+    '',
+    `Document: ${f.terms.title}`,
+    `Version: ${f.terms.version}`,
+    `Published: ${VENDOR_TC_ORIGIN}${f.terms.archiveUrl}`,
+    `Fingerprint: ${f.terms.documentHash}`,
+    '',
+    `Legal entity: ${f.legalName}`,
+    `Country: ${f.country}`,
+    f.vatId.length > 0 ? `VAT: ${f.vatId}` : 'VAT: (not registered)',
+    `Billing address: ${f.billingHash}`,
+    '',
+    `Signed by wallet: ${f.vendorAddress}`,
+    `Accepted at (UTC): ${f.acceptedAt}`,
+  ].join('\n');
+}
+
+/** "sha256:<hex>" of the billing address in the keeper's fixed key order. */
+export async function billingHash(a: VendorLegalInput['billingAddress']): Promise<string> {
+  const canonical = JSON.stringify({ line1: a.line1, line2: a.line2 ?? '', city: a.city, postalCode: a.postalCode });
+  const d = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+  return 'sha256:' + [...new Uint8Array(d)].map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function createVendorAgent(opts: {
+  keeperUrl: string;
+  network: Network;
+  wallet: AgentWallet;
+  policy?: AgentPolicy;
+  ledger?: SpendLedger;
+  consent?: StandingConsent;
+  /** The site for approval links (default by network). */
+  siteUrl?: string;
+  fetcher?: typeof fetch;
+}) {
+  const base = opts.keeperUrl.replace(/\/+$/, '');
+  const f = opts.fetcher ?? fetch;
+  const net = opts.network;
+  const w = opts.wallet;
+  const site = opts.siteUrl ?? (net === 'mainnet' ? 'https://zklicensing.com' : 'https://dev.zklicensing.com');
+  let permits: Promise<{ signIn(): Promise<string> }> | null = null;
+  // The wallet sign-in (VendorSession) the vendor endpoints need: the same one the permits client makes.
+  const session = async () => (await (permits ??= import('./permitsClient.js').then(m =>
+    m.createPermitsClient({ keeperUrl: opts.keeperUrl, network: net, wallet: w, fetcher: opts.fetcher })))).signIn();
+
+  async function call<T>(method: string, path: string, body?: unknown, auth = false): Promise<T> {
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (auth) headers.Authorization = `VendorSession ${await session()}`;
+    const r = await f(base + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
+    const text = await r.text();
+    let j: any = null;
+    try { j = text ? JSON.parse(text) : null; } catch { j = text; }
+    if (!r.ok) throw new AgentError(j?.error ?? `HTTP ${r.status}`, j?.code ?? (r.status === 404 ? 'NOT_FOUND' : 'HTTP_ERROR'), r.status, r.status >= 500);
+    return j as T;
+  }
+
+  /** The owner's standing consent covering vendor-terms (fails closed, as for buyers). */
+  const vendorConsent = () => consentFor({
+    requiresConsent: ['vendor-terms'], agentMayConsent: true, approvalUrl: `${site}/register.html`, network: net,
+  } as any, w.address, opts.consent, { keeperUrl: opts.keeperUrl, fetcher: opts.fetcher });
+
+  const toMinaNano = (m: number) => BigInt(Math.round(m * 1e9));
+
+  async function record(action: 'register-app' | 'set-prices', a: { target: string; reference: string; summary: string; totalNano: bigint; txHash: string; consent: Awaited<ReturnType<typeof vendorConsent>> | { givenBy: 'none' } }) {
+    try {
+      const actionRecord = await signActionRecord(w, {
+        network: net, action, target: a.target, reference: a.reference, summary: a.summary,
+        amounts: { total: a.totalNano.toString(), toRecipient: a.totalNano.toString(), toPlatform: a.totalNano.toString(), recipient: 'zkLicensing platform' },
+        txHash: a.txHash, receipt: null, policySha256: await policyHash(opts.policy),
+        consent: a.consent.givenBy === 'agent' ? { givenBy: 'agent', statementSha256: a.consent.statementSha256, kinds: [...a.consent.kinds] } : { givenBy: 'none' },
+        at: new Date().toISOString(),
+      });
+      return { actionRecord, warnings: [] as string[] };
+    } catch (e: any) {
+      return { warnings: [`The action record could not be signed (${e?.message ?? e}).`] };
+    }
+  }
+
+  /** Refuses an App ID this wallet can't register on this network (taken, or its prefix reserved by another vendor). */
+  async function appIdFree(appId: string): Promise<void> {
+    const r = await (opts.fetcher ?? fetch)(`${opts.keeperUrl.replace(/\/+$/, '')}/apps/${encodeURIComponent(appId)}?network=${net}&vendor=${encodeURIComponent(w.address)}`);
+    const b = await r.json().catch(() => null) as { error?: string; ownedBy?: string } | null;
+    if (r.status === 409) throw new AgentError(b?.error ?? `App ID prefix of "${appId}" is reserved by another vendor`, 'APP_ID_PREFIX_RESERVED', 409, false);
+    if (r.ok) throw new AgentError(`App ID "${appId}" is already registered on ${net}`, 'APP_ID_TAKEN', 409, false);
+    if (r.status === 404 && b?.ownedBy && b.ownedBy !== w.address) throw new AgentError(`App ID "${appId}" belongs to another vendor`, 'APP_ID_TAKEN', 409, false);
+    if (r.status !== 404) throw new AgentError(b?.error ?? `Could not check App ID "${appId}" (${r.status})`, 'UPSTREAM_UNAVAILABLE', r.status, true);
+  }
+
+  return {
+    address: w.address,
+
+    /** The Vendor Terms and legal details, signed by the agent key for its owner. */
+    async acceptVendorTerms(legal: VendorLegalInput, terms: VendorTerms): Promise<{ status: string; review: unknown; taxIdCheck: unknown; network: Network }> {
+      checkActionPolicy(opts.policy, { action: 'accept-vendor-terms', network: net });
+      await vendorConsent();
+      const acceptedAt = new Date().toISOString();
+      const signedMessage = vendorAcceptanceMessage({
+        vendorAddress: w.address, terms, legalName: legal.legalName, country: legal.country, vatId: legal.vatId,
+        billingHash: await billingHash(legal.billingAddress), acceptedAt,
+      });
+      const signature = await w.signMessage(signedMessage);
+      return call('POST', '/vendors/accept', {
+        vendorAddress: w.address, network: net, tcVersion: terms.version, tcDocumentHash: terms.documentHash, acceptedAt,
+        signature, signedMessage, legal, agentConsent: opts.consent,
+      });
+    },
+
+    /** Review status on this network, the terms accepted and the tax ID check. */
+    status: () => call<any>('GET', `/vendors/${w.address}/tos?network=${net}`, undefined, true),
+
+    /** Changes the legal details on every app the vendor owns. */
+    async updateDetails(legal: Partial<VendorLegalInput>) {
+      checkActionPolicy(opts.policy, { action: 'update-vendor-details', network: net });
+      return call<{ ok: true; appsUpdated: number }>('PATCH', `/vendors/${w.address}/legal`, { payload: legal }, true);
+    },
+
+    /**
+     * Deploys the app's contract (the agent wallet pays the registration fee:
+     * the owner's policy caps it, the standing consent covers its withdrawal
+     * waiver) and lists it. The legal details are the ones signed in
+     * acceptVendorTerms (changed with updateDetails), never given per app.
+     */
+    async registerApp(listing: VendorListing) {
+      const feeNano = toMinaNano(REGISTRATION_FEE_MINA[net] + 1);
+      checkActionPolicy(opts.policy, { action: 'register-app', network: net, amountNano: feeNano }, opts.ledger);
+      const consent = await vendorConsent();
+      const p = listing.prices;
+      if (![p.monthly, p.yearly, p.fiveYear, p.perpetual].some(x => x > 0)) throw new AgentError('At least one tier needs a price above 0', 'INVALID_REQUEST', 0, false);
+      if (!/^https:\/\//.test(listing.website)) throw new AgentError('website must be an https:// URL (it is written into the contract)', 'INVALID_REQUEST', 0, false);
+      await appIdFree(listing.appId); // before anything is signed or paid: the listing can't then be refused for it
+      const appSig = await w.signMessage(listing.appId);
+      await session(); // sign in before paying: the listing step needs it
+      const { proveDeploy } = await import('./deployClient.js');
+      const proved = await proveDeploy({
+        keeperUrl: opts.keeperUrl, senderPublicKey: w.address, vendorAddress: w.address,
+        priceMonthlyMina: p.monthly, priceYearlyMina: p.yearly, priceFiveYearMina: p.fiveYear, pricePerpetualMina: p.perpetual,
+        deviceCap: listing.deviceCap ?? 0, website: listing.website, network: net, fetcher: opts.fetcher,
+      });
+      const waiverAt = new Date().toISOString();
+      const txHash = await w.signAndSendTransaction(proved.provenTxJson);
+      opts.ledger?.record(feeNano);
+      const warnings: string[] = [];
+      await call('POST', '/apps', {
+          appId: listing.appId, name: listing.name, description: listing.description, longDescription: listing.longDescription ?? '',
+          category: listing.category, website: listing.website, zkAppAddress: proved.zkAppAddress, vendorAddress: w.address,
+          priceMonthlyMina: p.monthly, priceYearlyMina: p.yearly, priceFiveYearMina: p.fiveYear, pricePerpetualMina: p.perpetual,
+          deviceCap: listing.deviceCap ?? 0, txHash, verificationKeyHash: proved.verificationKeyHash,
+          tags: listing.tags ?? [], contactEmail: listing.contactEmail ?? '', supportEmail: listing.supportEmail,
+          showInMarketplace: listing.showInMarketplace !== false,
+          ...(listing.buyUrl ? { buyUrl: listing.buyUrl } : {}), ...(listing.renewUrl ? { renewUrl: listing.renewUrl } : {}),
+          ...(listing.refundUrl ? { refundUrl: listing.refundUrl } : {}),
+          ...(listing.termsOfServiceUrl ? { termsOfServiceUrl: listing.termsOfServiceUrl } : {}),
+          ...(listing.privacyPolicyUrl ? { privacyPolicyUrl: listing.privacyPolicyUrl } : {}),
+          ...(listing.refundPolicyUrl ? { refundPolicyUrl: listing.refundPolicyUrl } : {}),
+          deployFeeWaiverAcceptedAt: waiverAt, network: net, signature: appSig,
+          // The waiver is the agent's, under the owner's consent: the keeper records it as such.
+          ...(consent.givenBy === 'agent' ? { agentConsent: opts.consent } : {}),
+        }, true).catch(e => {
+          // The contract is deployed and paid for: never throw past this point; say how to finish.
+          warnings.push(`The contract is deployed (${proved.zkAppAddress}) but the listing was not recorded (${(e as Error).message}). Finish it from the dashboard with this address.`);
+        });
+      const rec = await record('register-app', { target: proved.zkAppAddress, reference: listing.appId, summary: `Register ${listing.name} (${listing.appId}) on ${net}`, totalNano: feeNano, txHash, consent });
+      return {
+        appId: listing.appId, zkAppAddress: proved.zkAppAddress, verificationKeyHash: proved.verificationKeyHash, txHash,
+        warnings: [...warnings, ...rec.warnings], ...(rec.actionRecord ? { actionRecord: rec.actionRecord } : {}),
+        next: [
+          `Host the trust manifest: trustManifest('${listing.appId}') gives the file for ${listing.website.replace(/\/+$/, '')}/.well-known/zklicensing/${proved.zkAppAddress}.json`,
+          net === 'mainnet' ? 'Mainnet listings are reviewed before they appear; buy, renew and refund pages on your own site are required.' : 'Devnet listings appear once the deployment is seen on chain.',
+        ],
+      };
+    },
+
+    /** Changes the tier prices on chain (and the listing's copy). */
+    async setPrices(appId: string, prices: VendorListing['prices']) {
+      const r = await call<{ app?: { deployments?: Record<string, { zkAppAddress?: string }>; vendorAddress?: string } }>('GET', `/apps/${encodeURIComponent(appId)}?network=${net}`);
+      const zkAppAddress = r.app?.deployments?.[net]?.zkAppAddress;
+      if (r.app?.vendorAddress && r.app.vendorAddress !== w.address) throw new AgentError(`${appId} belongs to another vendor wallet`, 'FORBIDDEN', 403, false);
+      if (!zkAppAddress) throw new AgentError(`${appId} has no ${net} deployment`, 'NOT_FOUND', 404, false);
+      checkActionPolicy(opts.policy, { action: 'set-prices', network: net, target: zkAppAddress, amountNano: 0n });
+      const proved = await call<{ provenTxJson: string }>('POST', '/prove/setPrice', {
+        vendorAddress: w.address, zkAppAddress, network: net,
+        priceMonthlyMina: prices.monthly, priceYearlyMina: prices.yearly, priceFiveYearMina: prices.fiveYear, pricePerpetualMina: prices.perpetual,
+      });
+      const txHash = await w.signAndSendTransaction(proved.provenTxJson);
+      const warnings: string[] = [];
+      // The listing's cached prices (the chain is the source of truth; the keeper reconciles).
+      await call('PUT', `/apps/${encodeURIComponent(appId)}`, {
+        vendorAddress: w.address, signature: await w.signMessage(appId),
+        payload: { priceMonthlyMina: prices.monthly, priceYearlyMina: prices.yearly, priceFiveYearMina: prices.fiveYear, pricePerpetualMina: prices.perpetual },
+      }, true).catch(e => warnings.push(`Prices are set on chain; the listing will catch up (${(e as Error).message}).`));
+      const rec = await record('set-prices', { target: zkAppAddress, reference: appId, summary: `Set prices of ${appId} on ${net}`, totalNano: 0n, txHash, consent: { givenBy: 'none' } });
+      return { appId, zkAppAddress, txHash, warnings: [...warnings, ...rec.warnings], ...(rec.actionRecord ? { actionRecord: rec.actionRecord } : {}) };
+    },
+
+    /**
+     * Takes the app's next redeploy step: it moves to a new contract account
+     * with every license carried over. The first call pauses its sales and
+     * answers `draining` (call again after readyAt); the agent key then signs
+     * the retirement, and the agent wallet sends and pays for each step:
+     * before a hard fork the retirement alone (`retired`, the new account
+     * follows after the fork); otherwise the new account's deployment (1 MINA
+     * account creation + fee).
+     */
+    async redeployApp(appId: string) {
+      const r = await call<{ app?: { deployments?: Record<string, { zkAppAddress?: string }>; vendorAddress?: string } }>('GET', `/apps/${encodeURIComponent(appId)}?network=${net}`);
+      const zkAppAddress = r.app?.deployments?.[net]?.zkAppAddress;
+      if (r.app?.vendorAddress && r.app.vendorAddress !== w.address) throw new AgentError(`${appId} belongs to another vendor wallet`, 'FORBIDDEN', 403, false);
+      if (!zkAppAddress) throw new AgentError(`${appId} has no ${net} deployment`, 'NOT_FOUND', 404, false);
+      checkActionPolicy(opts.policy, { action: 'redeploy-app', network: net, target: zkAppAddress, amountNano: toMinaNano(1.1) }, opts.ledger);
+      const d = await import('./deployClient.js');
+      let retireSignature: string | undefined;
+      for (let round = 0; round < 3; round++) {
+        const { nonce } = await d.getVendorRedeployChallenge({ keeperUrl: opts.keeperUrl, appId, network: net, fetcher: opts.fetcher });
+        const signature = await w.signMessage(nonce);
+        const res = await d.proveVendorRedeploy({ keeperUrl: opts.keeperUrl, appId, nonce, signature, senderPublicKey: w.address, retireSignature, fetcher: opts.fetcher });
+        if ('status' in res && res.status === 'draining') return { appId, status: 'draining' as const, readyAt: res.readyAt, expiresAt: res.expiresAt, next: 'Sales are paused while in-flight proofs land: call redeploy_app again after readyAt.' };
+        if ('status' in res && res.status === 'sign-retire') { retireSignature = await w.signFields(res.retireMessage); continue; }
+        if (!('provenTxJson' in res)) break;
+        const txHash = await w.signAndSendTransaction(res.provenTxJson);
+        await d.registerVendorRedeploy({ keeperUrl: opts.keeperUrl, appId, redeployId: res.redeployId, txHash, fetcher: opts.fetcher });
+        if (res.step === 'retire') {
+          opts.ledger?.record(toMinaNano(0.1));
+          return { appId, status: 'retired' as const, txHash, next: 'Retired ahead of the hard fork: call redeploy_app again after the fork to deploy the new account.' };
+        }
+        opts.ledger?.record(toMinaNano(1.1));
+        return { appId, status: 'deployed' as const, zkAppAddress: res.zkAppAddress, txHash, next: 'The listing moves to the new address once it is seen on chain; host the trust manifest for it (trustManifest).' };
+      }
+      throw new AgentError('The keeper did not accept the retire signature', 'HTTP_ERROR', 0, false);
+    },
+
+    /** Calls off this vendor's redeploy before the app is retired on chain (sales resume). */
+    async cancelRedeploy(appId: string) {
+      const d = await import('./deployClient.js');
+      const { nonce } = await d.getVendorRedeployChallenge({ keeperUrl: opts.keeperUrl, appId, network: net, fetcher: opts.fetcher });
+      return d.cancelVendorRedeploy({ keeperUrl: opts.keeperUrl, appId, nonce, signature: await w.signMessage(nonce), fetcher: opts.fetcher });
+    },
+
+    /** Edits the listing (name, descriptions, category, tags, emails, page links); mainnet edits are re-reviewed. */
+    async updateListing(appId: string, payload: Partial<Omit<VendorListing, 'appId' | 'website' | 'prices' | 'deviceCap'>>, visibility?: 'active' | 'inactive') {
+      checkActionPolicy(opts.policy, { action: 'update-listing', network: net });
+      return call<any>('PUT', `/apps/${encodeURIComponent(appId)}`, {
+        vendorAddress: w.address, signature: await w.signMessage(appId), payload,
+        ...(visibility ? { network: net, status: visibility } : {}),
+      }, true);
+    },
+
+    /**
+     * What forced retirements left in escrow on this vendor's retired
+     * contracts (Vendor Terms §8.7): per contract, the purchases whose funds
+     * stay there, their buyers and the total.
+     */
+    stranded: () => call<{ contracts: Array<{ appId: string | null; zkAppAddress: string; currentZkAppAddress: string | null; retireTxHash: string; strandedAt: string; count: number; totalNano: string; purchases: Array<{ licenseHash: string; buyerAddress: string | null; purchaseAmount: string; purchaseSlot: number; txHash: string }> }>; count: number; totalNano: string }>(
+      'GET', `/vendors/${w.address}/stranded?network=${net}`, undefined, true),
+
+    /** The platform's monthly fee statement for this vendor (month YYYY-MM). */
+    feeStatement: (month: string) => call<{ statement: unknown }>('GET', `/vendors/${w.address}/fee-statements?network=${net}&month=${encodeURIComponent(month)}`, undefined, true).then(r => r.statement),
+
+    /**
+     * The platform-signed trust manifest the vendor hosts on its website, at
+     * /.well-known/zklicensing/<address>.json for every generation address.
+     * An agent can't upload it: give the files to the owner.
+     */
+    async trustManifest(appId: string): Promise<{ content: string; files: Array<{ path: string; url: string | null }> }> {
+      const r = await f(`${base}/apps/${encodeURIComponent(appId)}?network=${net}`, { headers: { Accept: 'application/json' } });
+      if (!r.ok) throw new AgentError(`No manifest for ${appId} on ${net} (HTTP ${r.status})`, r.status === 404 ? 'NOT_FOUND' : 'HTTP_ERROR', r.status, false);
+      // The same bytes the dashboard's "Download manifest" saves: the signed generation list (and the public listing).
+      const content = await r.text();
+      const j = JSON.parse(content) as { generations?: Array<{ zkAppAddress: string }>; app?: { website?: string } };
+      const gens = j.generations ?? [];
+      const website = j.app?.website ?? null;
+      return {
+        content,
+        files: gens.map(g => ({ path: `/.well-known/zklicensing/${g.zkAppAddress}.json`, url: website ? `${website.replace(/\/+$/, '')}/.well-known/zklicensing/${g.zkAppAddress}.json` : null })),
+      };
+    },
+  };
+}
+export type VendorAgent = ReturnType<typeof createVendorAgent>;

package/src/appsLookup.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+// Pure lookup helper used by verifyService.ts + keeperService.ts to resolve
+// a client-pinned zkAppAddress back to its owning AppRecord, matching either
+// the current live address or any entry in deploymentHistory. Under the
+// backend-routing design a buyer whose app was built against the original
+// gen-1 address stays valid forever even after N generation bumps — this
+// helper is the anchor of that routing.
+//
+// Kept as a standalone pure function (not a method on any registry class)
+// so it can be unit-tested without booting the Express service, and so the
+// backend package's zklicensing/src/appsLookup.ts can share the exact same
+// semantics. See that file for the mirror.
+
+// Minimum shape of a per-network deployment slice for lookup: the current
+// live address plus the retired-generation history (empty when the app has
+// never been redeployed on that network).
+export type LookupableDeployment = {
+  zkAppAddress: string;
+  deploymentHistory?: Array<{ zkAppAddress: string }>;
+};
+
+// Minimum shape of an AppRecord we can resolve by address. Each network has
+// its own deployment (or none) — mainnet and devnet redeploys don't share a
+// zkAppAddress or history, so the lookup walks both slots independently.
+export type LookupableApp = {
+  deployments: {
+    devnet?:  LookupableDeployment;
+    mainnet?: LookupableDeployment;
+  };
+};
+
+// Return the first app whose devnet OR mainnet deployment matches (current
+// live address or any retired generation in deploymentHistory). Under the
+// backend-routing design a buyer who pinned an original devnet address stays
+// resolvable across N mainnet promotions and any number of retired gens.
+export function findAppByAnyAddress<T extends LookupableApp>(
+  apps: readonly T[],
+  zkAppAddress: string,
+): T | undefined {
+  const matches = (d?: LookupableDeployment): boolean =>
+    !!d && (
+      d.zkAppAddress === zkAppAddress ||
+      (d.deploymentHistory ?? []).some(h => h.zkAppAddress === zkAppAddress)
+    );
+  return apps.find(a => matches(a.deployments.devnet) || matches(a.deployments.mainnet));
+}