enigma-memory 0.1.18 → 0.1.22

package/apps/desktop/src/zk-state.mjs

@@ -0,0 +1,1789 @@
+// Persistence and client runtime for the desktop ZK proof layer.
+//
+// State file (default .enigma/zk-tree-state.json, next to the vault bundle),
+// format v2:
+//   - PLAINTEXT section is public tree data only: noteLeaves, imtLeaves,
+//     nullifierValues, and per-note public metadata (index, scope, sealed
+//     ciphertext, tx signatures). None of it can decrypt a note or forge a
+//     revocation.
+//   - ALL secrets (install ownerKey, X25519 recipient secret key, and the
+//     per-note openings rho/payloadCommit) live exclusively inside
+//     `secretEnvelope`: Electron safeStorage (OS DPAPI/Keychain) when injected,
+//     otherwise host-bound AES-256-GCM (scrypt over hostname:username:
+//     platform:arch), matching packages/terminal-console/signer-store.mjs.
+//   - The sealed payload embeds a SHA-256 digest of the public section; the
+//     GCM AAD is 'enigma.zk_state_secrets.v1'. Envelopes therefore cannot be
+//     swapped across state files or survive public-state tampering: decryption
+//     fails closed.
+//
+// Legacy v1 plaintext state files are NEVER migrated. readZkState rejects them
+// with a precise reset error.
+//
+// The local tree snapshot is not an indexer. If the chain is ahead of this
+// file, historical Poseidon leaves cannot be recovered from roots, so actions
+// fail closed until a matching snapshot is restored.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createZkSettlementEvidence } from '../../../cortex-v3/zk/settlement-evidence.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..');
+const DEFAULT_CORTEX_DIR = path.join(REPO_ROOT, 'cortex-v3');
+const DEFAULT_BUILD_DIR = path.join(DEFAULT_CORTEX_DIR, 'circuits', 'build');
+const STATE_VERSION = 2;
+const FIELD_R = BigInt('0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001');
+
+const PUBLIC_STATE_WARNING = 'Public ZK tree data only; note openings and recipient keys live encrypted in secretEnvelope';
+const SECRET_AAD = Buffer.from('enigma.zk_state_secrets.v1', 'utf8');
+const SAFESTORAGE_SCHEME = 'enigma.zk_state_safestorage.v1';
+const HOSTBOUND_SCHEME = 'enigma.zk_state_hostbound.v1';
+const HOST_KEY_SALT = 'enigma-zk-state-dpapi-salt-v1';
+const CUSTOM_KEY_SALT = 'enigma-zk-state-custom-salt-v1';
+
+export const ZK_HONESTY_NOTE = 'Localnet demo — dev ceremony; nullifiers prove non-use, not deletion.';
+
+function zeroizeBuffer(buf) {
+  if (Buffer.isBuffer(buf)) {
+    try { buf.fill(0); } catch {}
+  }
+}
+
+function zeroizePrivateObject(value) {
+  if (!value || typeof value !== 'object') return;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    try { value.fill(0); } catch {}
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    const entry = value[key];
+    if (entry && typeof entry === 'object') {
+      zeroizePrivateObject(entry);
+    } else if (typeof entry === 'bigint') {
+      value[key] = 0n;
+    } else if (typeof entry === 'number') {
+      value[key] = 0;
+    } else if (typeof entry === 'string') {
+      value[key] = '';
+    } else {
+      value[key] = null;
+    }
+  }
+}
+
+// --- Custody: mirrors packages/terminal-console/signer-store.mjs -------------
+
+function deriveHostBoundKey() {
+  const hostIdentity = [
+    os.hostname() || 'localhost',
+    os.userInfo()?.username || 'user',
+    process.platform || 'win32',
+    process.arch || 'x64',
+  ].join(':');
+  return crypto.scryptSync(hostIdentity, HOST_KEY_SALT, 32);
+}
+
+function deriveCustomKey(customKey) {
+  if (Buffer.isBuffer(customKey) || customKey instanceof Uint8Array) {
+    const key = Buffer.from(customKey);
+    if (key.length !== 32) throw new RangeError('customKey bytes must be exactly 32 bytes (AES-256)');
+    return key;
+  }
+  if (typeof customKey === 'string' && customKey.length > 0) {
+    return crypto.scryptSync(customKey, CUSTOM_KEY_SALT, 32);
+  }
+  throw new TypeError('customKey must be a non-empty string or 32 bytes');
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function publicStateOf(state) {
+  return {
+    version: STATE_VERSION,
+    warning: PUBLIC_STATE_WARNING,
+    noteLeaves: state.noteLeaves,
+    imtLeaves: state.imtLeaves,
+    nullifierValues: state.nullifierValues,
+    notes: state.notes,
+  };
+}
+
+function publicDigest(publicState) {
+  return crypto.createHash('sha256').update(stableStringify(publicState), 'utf8').digest('hex');
+}
+
+// Custody policy: OS safeStorage is production custody; customKey is for tests/
+// operators; the deterministic host-bound derivation is demo-only and must be
+// explicitly requested — silent fallback would be weak custody masquerading as
+// secure storage (host key is derivable by any same-host attacker).
+function assertCustodyExplicit(custody) {
+  if (custody.safeStorage && typeof custody.safeStorage.encryptString === 'function') return;
+  if (custody.customKey !== undefined) return;
+  if (custody.allowHostBoundDemo === true) return;
+  throw new Error(
+    'ZK secret custody not configured: provide safeStorage (OS DPAPI/Keychain), '
+    + 'a customKey, or explicitly set allowHostBoundDemo:true for local demos'
+  );
+}
+
+/**
+ * Encrypt the secrets payload for `state`'s current public section.
+ * custody: { safeStorage?, customKey?, allowHostBoundDemo? } — safeStorage wins when present.
+ */
+export function sealZkSecrets(secrets, state, custody = {}) {
+  assertCustodyExplicit(custody);
+
+  const payload = {
+    install: secrets.install,
+    noteOpenings: secrets.noteOpenings || {},
+    saleEnvelopes: secrets.saleEnvelopes || {},
+    publicDigest: publicDigest(publicStateOf(state)),
+  };
+  const plaintext = Buffer.from(JSON.stringify(payload), 'utf8');
+  try {
+    if (custody.safeStorage && typeof custody.safeStorage.encryptString === 'function') {
+      // JS strings cannot be zeroized; the plaintext Buffer copy is.
+      const encrypted = custody.safeStorage.encryptString(plaintext.toString('utf8'));
+      return {
+        scheme: SAFESTORAGE_SCHEME,
+        encryptedHex: Buffer.from(encrypted).toString('hex'),
+        storage: 'electron-safestorage-dpapi',
+        created_at: new Date().toISOString(),
+      };
+    }
+    const key = custody.customKey !== undefined ? deriveCustomKey(custody.customKey) : deriveHostBoundKey();
+    try {
+      const iv = crypto.randomBytes(12);
+      const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+      cipher.setAAD(SECRET_AAD);
+      const data = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      return {
+        scheme: HOSTBOUND_SCHEME,
+        iv: iv.toString('hex'),
+        tag: tag.toString('hex'),
+        data: data.toString('hex'),
+        storage: custody.customKey !== undefined ? 'custom-key-aes-256-gcm' : 'host-bound-aes-256-gcm',
+        created_at: new Date().toISOString(),
+      };
+    } finally {
+      zeroizeBuffer(key);
+    }
+  } finally {
+    zeroizeBuffer(plaintext);
+  }
+}
+
+
+/**
+ * Decrypt and verify `state.secretEnvelope`. Returns { install, noteOpenings, saleEnvelopes }.
+ * Throws precise fail-closed errors on wrong key, tampering, or a public-state
+ * digest mismatch (envelope swapped across state files).
+ */
+export function unlockZkState(state, custody = {}) {
+  assertCustodyExplicit(custody);
+  const envelope = state?.secretEnvelope;
+  if (!envelope) return null;
+
+  let decrypted;
+  if (envelope.scheme === SAFESTORAGE_SCHEME) {
+    if (!custody.safeStorage || typeof custody.safeStorage.decryptString !== 'function') {
+      throw new Error('Cannot decrypt safeStorage envelope outside an active Electron session');
+    }
+    const plainText = custody.safeStorage.decryptString(Buffer.from(envelope.encryptedHex, 'hex'));
+    decrypted = Buffer.from(String(plainText), 'utf8');
+  } else if (envelope.scheme === HOSTBOUND_SCHEME) {
+    const key = custody.customKey !== undefined ? deriveCustomKey(custody.customKey) : deriveHostBoundKey();
+    try {
+      const decipher = crypto.createDecipheriv(
+        'aes-256-gcm', key, Buffer.from(envelope.iv, 'hex'),
+      );
+      decipher.setAAD(SECRET_AAD);
+      decipher.setAuthTag(Buffer.from(envelope.tag, 'hex'));
+      decrypted = Buffer.concat([decipher.update(Buffer.from(envelope.data, 'hex')), decipher.final()]);
+    } catch {
+      throw new Error('secret envelope authentication failed (wrong key or tampered ZK state file)');
+    } finally {
+      zeroizeBuffer(key);
+    }
+  } else {
+    throw new Error(`unsupported ZK secret envelope scheme ${JSON.stringify(envelope.scheme)}`);
+  }
+
+  try {
+    const payload = JSON.parse(decrypted.toString('utf8'));
+    const expected = publicDigest(publicStateOf(state));
+    if (payload.publicDigest !== expected) {
+      throw new Error('secret envelope does not match the public tree state (digest mismatch: file swap or post-seal mutation); refusing to use openings');
+    }
+
+    if (!payload.install || typeof payload.noteOpenings !== 'object') {
+      throw new Error('secret envelope payload is malformed (missing install/noteOpenings)');
+    }
+    return {
+      install: payload.install,
+      noteOpenings: payload.noteOpenings,
+      saleEnvelopes: payload.saleEnvelopes && typeof payload.saleEnvelopes === 'object' ? payload.saleEnvelopes : {},
+    };
+  } finally {
+    zeroizeBuffer(decrypted);
+  }
+}
+
+// --- Public state shape ------------------------------------------------------
+
+function rootHex(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'bigint' || typeof value === 'number') {
+    return BigInt(value).toString(16).padStart(64, '0');
+  }
+  if (typeof value === 'string') {
+    if (/^[0-9a-f]{64}$/i.test(value)) return value.toLowerCase();
+    return BigInt(value).toString(16).padStart(64, '0');
+  }
+  return Buffer.from(value).toString('hex').padStart(64, '0');
+}
+
+function publicKeyString(value) {
+  if (!value) return null;
+  if (typeof value === 'string') return value;
+  if (typeof value.toBase58 === 'function') return value.toBase58();
+  return String(value);
+}
+
+function clusterForRpc(rpcUrl) {
+  if (/devnet/i.test(rpcUrl)) return 'devnet';
+  if (/mainnet/i.test(rpcUrl)) return 'mainnet-beta';
+  if (/testnet/i.test(rpcUrl)) return 'testnet';
+  return 'localnet';
+}
+
+function explorerUrlFor(sig, cluster) {
+  if (cluster === 'devnet' || cluster === 'testnet') {
+    return `https://explorer.solana.com/tx/${sig}?cluster=${cluster}`;
+  }
+  if (cluster === 'mainnet-beta') return `https://explorer.solana.com/tx/${sig}`;
+  return null;
+}
+
+function randomFieldElement() {
+  const value = BigInt(`0x${crypto.randomBytes(32).toString('hex')}`) % (FIELD_R - 1n);
+  return (value + 1n).toString(10);
+}
+
+function emptySnapshot() {
+  return {
+    version: STATE_VERSION,
+    warning: PUBLIC_STATE_WARNING,
+    noteLeaves: [],
+    imtLeaves: null,
+    notes: [],
+    nullifierValues: [],
+  };
+}
+
+export function defaultZkStatePath(bundlePath) {
+  return path.join(path.dirname(path.resolve(bundlePath)), 'zk-tree-state.json');
+}
+
+/**
+ * Read the public state section. opts.unlock (+ opts.safeStorage/customKey)
+ * also decrypts the envelope and attaches it as `state.secrets`.
+ * Legacy v1 plaintext files are rejected with a precise reset error.
+ */
+export function readZkState(statePath, opts = {}) {
+  if (!fs.existsSync(statePath)) return null;
+  const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object') throw new Error('ZK tree state is not a JSON object');
+  if (parsed.version === 1 || parsed.version === undefined) {
+    throw new Error(
+      `legacy v1 plaintext ZK state at ${statePath} is unsupported and insecure (plaintext note openings); ` +
+      'discard or reset the file — v1 secrets are never migrated',
+    );
+  }
+  if (parsed.version !== STATE_VERSION) {
+    throw new Error(`unsupported ZK tree state version ${parsed.version}`);
+  }
+  if (!Array.isArray(parsed.noteLeaves)) throw new Error('invalid ZK state: noteLeaves must be an array');
+  if (parsed.imtLeaves !== null && parsed.imtLeaves !== undefined && !Array.isArray(parsed.imtLeaves)) {
+    throw new Error('invalid ZK state: imtLeaves must be an array');
+  }
+  if (!Array.isArray(parsed.notes)) parsed.notes = [];
+  if (!Array.isArray(parsed.nullifierValues)) parsed.nullifierValues = [];
+  for (const note of parsed.notes) {
+    // Defense in depth: v2 notes are public metadata only.
+    delete note.ownerKey;
+    delete note.rho;
+    delete note.payloadCommit;
+    delete note.noteContext;
+    delete note.leaf;
+  }
+  if (opts.unlock && parsed.secretEnvelope) {
+    parsed.secrets = unlockZkState(parsed, opts);
+  }
+  return parsed;
+}
+
+/**
+ * Atomically persist state (0600 best-effort). When `state.secrets` is set it
+ * is sealed into `secretEnvelope` bound to the public section being written;
+ * in-memory secrets are never written in plaintext.
+ */
+export function writeZkState(statePath, state, custody = {}) {
+  const publicState = publicStateOf(state);
+  const envelope = state.secrets
+    ? sealZkSecrets(state.secrets, publicState, custody)
+    : state.secretEnvelope;
+  const out = envelope ? { ...publicState, secretEnvelope: envelope } : publicState;
+
+  fs.mkdirSync(path.dirname(statePath), { recursive: true, mode: 0o700 });
+  const tempPath = `${statePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  const body = `${JSON.stringify(out, null, 2)}\n`;
+  try {
+    fs.writeFileSync(tempPath, body, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    try { fs.chmodSync(tempPath, 0o600); } catch {}
+    fs.renameSync(tempPath, statePath);
+    try { fs.chmodSync(statePath, 0o600); } catch {}
+  } catch (error) {
+    try { fs.unlinkSync(tempPath); } catch {}
+    throw error;
+  }
+  state.secretEnvelope = envelope;
+}
+
+function ensureInstallSecrets(state, e2ee) {
+
+  if (!state.secrets) {
+    state.secrets = { install: null, noteOpenings: {}, saleEnvelopes: {} };
+  }
+  if (!state.secrets.noteOpenings || typeof state.secrets.noteOpenings !== 'object') {
+    state.secrets.noteOpenings = {};
+  }
+  if (!state.secrets.saleEnvelopes || typeof state.secrets.saleEnvelopes !== 'object') {
+    state.secrets.saleEnvelopes = {};
+  }
+  const install = state.secrets.install;
+  if (install?.ownerKey && install?.recipientSecretKeyB64 && install?.recipientPublicKeyB64) {
+    return;
+  }
+  const recipient = e2ee.generateRecipientKeyPair();
+  state.secrets.install = {
+    ownerKey: randomFieldElement(),
+    recipientSecretKeyB64: recipient.secretKeyB64,
+    recipientPublicKeyB64: recipient.publicKeyB64,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function exportImtLeaves(tree) {
+  return tree.leaves.map((leaf) => ({
+    value: BigInt(leaf.value).toString(10),
+    nextIndex: BigInt(leaf.nextIndex).toString(10),
+    nextValue: BigInt(leaf.nextValue).toString(10),
+  }));
+}
+
+export function rebuildZkTrees(state, zkTree) {
+  const noteTree = new zkTree.NoteTree(undefined, state.noteLeaves.map((leaf) => BigInt(leaf)));
+  const nullifierTree = new zkTree.NullifierIMT();
+
+  if (Array.isArray(state.imtLeaves) && state.imtLeaves.length > 0) {
+    nullifierTree.leaves = state.imtLeaves.map((leaf) => ({
+      value: BigInt(leaf.value),
+      nextIndex: BigInt(leaf.nextIndex),
+      nextValue: BigInt(leaf.nextValue),
+    }));
+  } else if (Array.isArray(state.nullifierValues)) {
+    for (const value of state.nullifierValues) nullifierTree.insert(BigInt(value));
+  }
+
+  return { noteTree, nullifierTree };
+}
+
+function snapshotFromTrees(state, noteTree, nullifierTree) {
+  state.noteLeaves = noteTree.leaves.map((leaf) => BigInt(leaf).toString(10));
+  state.imtLeaves = exportImtLeaves(nullifierTree);
+}
+
+function reconcileState(state, onChain, zkTree) {
+  let changed = false;
+  const chainNoteCount = Number(onChain.noteCount);
+  const chainNullCount = Number(onChain.nullCount);
+
+  if (chainNoteCount < 0 || chainNullCount < 1) {
+    return { ok: false, reason: 'on-chain ZK counters are invalid' };
+  }
+
+  if (state.noteLeaves.length > chainNoteCount) {
+    state.noteLeaves = state.noteLeaves.slice(0, chainNoteCount);
+    state.notes = state.notes.filter((note) => Number(note.index) < chainNoteCount);
+    changed = true;
+  }
+
+  const currentNullCount = Array.isArray(state.imtLeaves) && state.imtLeaves.length > 0
+    ? state.imtLeaves.length
+    : 1 + state.nullifierValues.length;
+  if (currentNullCount > chainNullCount) {
+    if (state.nullifierValues.length !== currentNullCount - 1) {
+      return {
+        ok: false,
+        reason: `state drift: local null_count=${currentNullCount} is ahead of chain=${chainNullCount}, but the insertion log is incomplete`,
+      };
+    }
+    const rebuilt = new zkTree.NullifierIMT();
+    state.nullifierValues = state.nullifierValues.slice(0, chainNullCount - 1);
+    for (const value of state.nullifierValues) rebuilt.insert(BigInt(value));
+    state.imtLeaves = exportImtLeaves(rebuilt);
+    changed = true;
+  }
+
+  const localNullCount = Array.isArray(state.imtLeaves) && state.imtLeaves.length > 0
+    ? state.imtLeaves.length
+    : 1 + state.nullifierValues.length;
+  if (state.noteLeaves.length < chainNoteCount || localNullCount < chainNullCount) {
+    return {
+      ok: false,
+      reason: `state drift: chain is ahead of local persistence (note_count chain=${chainNoteCount} local=${state.noteLeaves.length}; null_count chain=${chainNullCount} local=${localNullCount}). Historical leaves are not recoverable without an indexer; restore a matching zk-tree-state.json`,
+    };
+  }
+
+  let trees;
+  try {
+    trees = rebuildZkTrees(state, zkTree);
+  } catch (error) {
+    return { ok: false, reason: `invalid local ZK tree snapshot: ${error.message}` };
+  }
+  const localNoteRoot = rootHex(trees.noteTree.root());
+  const localNullRoot = rootHex(trees.nullifierTree.root());
+  const chainNoteRoot = rootHex(onChain.noteRoot);
+  const chainNullRoot = rootHex(onChain.nullRoot);
+  if (localNoteRoot !== chainNoteRoot || localNullRoot !== chainNullRoot) {
+    return {
+      ok: false,
+      reason: `state drift: local roots do not match chain at equal counts (note ${localNoteRoot.slice(0, 12)}… != ${chainNoteRoot.slice(0, 12)}…; null ${localNullRoot.slice(0, 12)}… != ${chainNullRoot.slice(0, 12)}…)`,
+    };
+  }
+
+  return { ok: true, changed, trees, localNoteRoot, localNullRoot };
+}
+
+async function withTimeout(promise, timeoutMs, label) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function loadRealDeps(options) {
+  const cortexDir = path.resolve(options.cortexDir || DEFAULT_CORTEX_DIR);
+  const require = createRequire(path.join(cortexDir, 'package.json'));
+
+  const { Connection, Keypair, PublicKey } = require('@solana/web3.js');
+  const snarkjs = require('snarkjs');
+  const zkDir = path.join(cortexDir, 'zk');
+  const zkTree = await import(pathToFileURL(path.join(zkDir, 'zk-tree.mjs')).href);
+  const witness = await import(pathToFileURL(path.join(zkDir, 'witness.mjs')).href);
+  const codec = await import(pathToFileURL(path.join(zkDir, 'zk-codec.mjs')).href);
+  const settle = await import(pathToFileURL(path.join(zkDir, 'zk-settle.mjs')).href);
+  const sale = await import(pathToFileURL(path.join(zkDir, 'sale-witness.mjs')).href);
+  const provingAssets = await import(pathToFileURL(path.join(zkDir, 'proving-assets.mjs')).href);
+  const e2ee = await import(pathToFileURL(path.join(REPO_ROOT, 'packages', 'vault', 'src', 'e2ee.mjs')).href);
+  const connection = new Connection(options.rpcUrl, 'confirmed');
+  const payerPath = path.resolve(options.payerPath || path.join(os.homedir(), '.config', 'solana', 'id.json'));
+  const payer = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(fs.readFileSync(payerPath, 'utf8'))));
+  const buildDir = path.resolve(options.buildDir || DEFAULT_BUILD_DIR);
+  const wasmPath = path.join(buildDir, 'action_transition_js', 'action_transition.wasm');
+  const zkeyPath = path.join(buildDir, 'action_transition.zkey');
+
+
+  // VK GATE: never prove against a key the chain would reject. Before every
+  // fullProve the manifest-pinned VK must exactly equal the on-chain VK PDA.
+  const prover = async (witnessInput) => {
+    const { vk } = await provingAssets.resolveVerifyingKey('action_transition');
+    await settle.assertOnChainVerifyingKey(connection, 1, vk);
+    // Packaged installs: resolve via the checksum-pinned asset resolver
+    // (source checkout → verified cache → pinned download), never raw paths.
+    const assets = await provingAssets.resolveProvingAssets('action_transition');
+    const { proof, publicSignals } = await snarkjs.groth16.fullProve(witnessInput, assets.wasm, assets.zkey);
+    return {
+      proofBytes: codec.proofFromSnarkjs(proof),
+      publicInputs: codec.publicInputsFromSnarkjs(publicSignals),
+    };
+  };
+  // Sealed-sale prover. Proving keys are NOT shipped in the npm package, so
+  // the wasm/zkey resolve through the checksum-pinned asset resolver (source
+  // checkout → verified cache → pinned release download) instead of reading
+  // circuits/build directly; it fails closed with ProvingAssetError (code +
+  // remediation) when no verified artifact is available.
+  const saleProver = async (witnessInput) => {
+    const { vk } = await provingAssets.resolveVerifyingKey('sealed_sale_release');
+    await settle.assertOnChainVerifyingKey(connection, 3, vk);
+    const assets = await provingAssets.resolveProvingAssets('sealed_sale_release');
+    const { proof, publicSignals } = await snarkjs.groth16.fullProve(witnessInput, assets.wasm, assets.zkey);
+    return {
+      proofBytes: codec.proofFromSnarkjs(proof),
+      publicInputs: codec.publicInputsFromSnarkjs(publicSignals),
+    };
+  };
+  return { zkTree, witness, codec, settle, sale, e2ee, web3: { Keypair, PublicKey }, connection, payer, prover, saleProver, provingAssets };
+}
+
+export async function createZkRuntime(options = {}) {
+  const rpcUrl = options.rpcUrl || process.env.ENIGMA_ZK_RPC_URL || process.env.SOLANA_RPC_URL || 'http://127.0.0.1:8899';
+  const cluster = options.cluster || clusterForRpc(rpcUrl);
+  const buildDir = path.resolve(options.buildDir || DEFAULT_BUILD_DIR);
+  const statePath = path.resolve(options.statePath);
+  const custody = {
+    safeStorage: options.safeStorage,
+    customKey: options.customKey,
+    allowHostBoundDemo: options.allowHostBoundDemo === true,
+  };
+  const artifactPaths = {
+    wasm: path.join(buildDir, 'action_transition_js', 'action_transition.wasm'),
+    zkey: path.join(buildDir, 'action_transition.zkey'),
+  };
+
+  // Packaged installs do not ship proving keys (40MB+, gitignored). The real
+  // action-circuit paths therefore resolve through the checksum-pinned asset
+  // resolver (source checkout → verified cache → pinned release download).
+  // With injected deps (tests) the source-checkout defaults are returned.
+  let resolvedActionAssets = null;
+  async function getProvingAssetPaths() {
+    if (options.deps) return artifactPaths;
+    if (resolvedActionAssets) return resolvedActionAssets;
+    const activeDeps = await ensureDeps();
+    resolvedActionAssets = await activeDeps.provingAssets.resolveProvingAssets('action_transition');
+    return resolvedActionAssets;
+  }
+  // Availability probe for status(): never downloads, never throws.
+  async function probeProvingAssets() {
+    if (options.deps) {
+      return fs.existsSync(artifactPaths.wasm) && fs.existsSync(artifactPaths.zkey);
+    }
+    try {
+      const activeDeps = await ensureDeps();
+      await activeDeps.provingAssets.resolveProvingAssets('action_transition', { allowDownload: false });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  let deps = options.deps || null;
+  let depsPromise = null;
+  const timeoutMs = Number(options.rpcTimeoutMs || 5_000);
+  // Sealed Sale (ZKCP) constants. Saleable notes commit a DEK-blinded
+  // Poseidon fold of the plaintext (payloadCommitPos) as their tree
+  // payloadCommit, so the sealed_sale_release circuit's Leg A membership
+  // check passes against the on-chain leaf. The plaintext itself stays in
+  // the E2EE sealed note for local custody recovery at listing time.
+  const SALE_PAYLOAD_CAPACITY = 992; // 32 chunks × 31-byte LE limbs
+  const WRAPPED_SOL_MINT = 'So11111111111111111111111111111111111111112';
+  let sharedStatePda = publicKeyString(deps?.settle?.SHARED_STATE_PDA || options.sharedStatePda);
+  let programId = publicKeyString(deps?.settle?.PROGRAM_ID || options.programId);
+
+  async function ensureDeps() {
+    if (deps) return deps;
+    if (!depsPromise) {
+      depsPromise = loadRealDeps({ ...options, rpcUrl, buildDir }).then((loaded) => {
+        deps = loaded;
+        sharedStatePda = publicKeyString(loaded.settle.SHARED_STATE_PDA || options.sharedStatePda);
+        programId = publicKeyString(loaded.settle.PROGRAM_ID || options.programId);
+        return loaded;
+      });
+    }
+    return depsPromise;
+  }
+
+  const statusBase = () => ({
+    available: false,
+    reason: null,
+    cluster,
+    sharedStatePda,
+    programId,
+    noteRoot: null,
+    nullRoot: null,
+    noteCount: null,
+    nullCount: null,
+    localNoteCount: null,
+    localNullCount: null,
+    provingArtifacts: null, // filled by status() via probeProvingAssets()
+    honesty: ZK_HONESTY_NOTE,
+  });
+
+  async function fetchOnChain(activeDeps) {
+    return withTimeout(
+      activeDeps.settle.fetchSharedState(activeDeps.connection),
+      timeoutMs,
+      'validator request',
+    );
+  }
+
+  // Shared chain/local reconciliation. READ-ONLY callers (status) get a report;
+  // operational callers (requireReady) get a hard failure — external writers
+  // (multi-party use) advance the on-chain tree, and witnesses built from a
+  // stale local snapshot would be rejected on-chain. Returns {state, reconciled}
+  // or throws ZK_UNAVAILABLE with the reason.
+  async function reconcileForOperation(activeDeps, onChain) {
+    const state = readZkState(statePath) || emptySnapshot();
+    const reconciled = reconcileState(state, onChain, activeDeps.zkTree);
+    if (!reconciled.ok) {
+      const error = new Error(reconciled.reason);
+      error.code = 'ZK_UNAVAILABLE';
+      throw error;
+    }
+    if (reconciled.changed) {
+      if (state.secretEnvelope) {
+        const error = new Error('chain rolled back behind the sealed local snapshot (validator reset?); refusing to rewrite public state under a sealed envelope — reset zk-tree-state.json');
+        error.code = 'ZK_UNAVAILABLE';
+        throw error;
+      }
+      writeZkState(statePath, state, custody);
+    }
+    return state;
+  }
+
+  // Read-only by design: status NEVER decrypts the secret envelope, so the
+  // endpoint cannot leak openings even if the UI is compromised.
+  async function status() {
+    const out = statusBase();
+    out.provingArtifacts = await probeProvingAssets();
+    if (!out.provingArtifacts) {
+      out.reason = `proving artifacts missing for ${artifactPaths.wasm} / ${artifactPaths.zkey} — ` +
+        'packaged installs download them on first use (checksum-pinned), or run the setup script in a source checkout';
+      return out;
+    }
+
+    let activeDeps;
+    try {
+      activeDeps = await ensureDeps();
+      out.sharedStatePda = sharedStatePda;
+      out.programId = programId;
+    } catch (error) {
+      out.reason = `ZK client dependencies unavailable: ${error.message}`;
+      return out;
+    }
+
+    let onChain;
+    try {
+      onChain = await fetchOnChain(activeDeps);
+    } catch (error) {
+      out.reason = `validator unavailable at ${rpcUrl}: ${error.message}`;
+      return out;
+    }
+    if (!onChain) {
+      out.reason = `shared ZK state is not initialized at ${sharedStatePda || 'the configured PDA'}`;
+      return out;
+    }
+
+    out.noteRoot = rootHex(onChain.noteRoot);
+    out.nullRoot = rootHex(onChain.nullRoot);
+    out.noteCount = Number(onChain.noteCount);
+    out.nullCount = Number(onChain.nullCount);
+
+    let state;
+    try {
+      state = readZkState(statePath) || emptySnapshot();
+    } catch (error) {
+      out.reason = `local ZK state unreadable: ${error.message}`;
+      return out;
+    }
+    out.localNoteCount = state.noteLeaves.length;
+    out.localNullCount = Array.isArray(state.imtLeaves) && state.imtLeaves.length > 0
+      ? state.imtLeaves.length
+      : 1 + state.nullifierValues.length;
+    try {
+      state = await reconcileForOperation(activeDeps, onChain);
+    } catch (error) {
+      out.reason = error.message;
+      return out;
+    }
+    out.available = true;
+    return out;
+  }
+
+
+  // VK GATE (job acceptance): /api/zk/prepare, /api/zk/relay, and the sale
+  // endpoints refuse work up front when the on-chain verifying key for the
+  // circuit is absent or differs from the manifest-pinned VK — a proof made
+  // against the wrong ceremony could never settle. The provers in
+  // loadRealDeps re-assert the same gate immediately before fullProve.
+  const VK_GATE_CIRCUITS = {
+    action: { circuit: 'action_transition', version: 1 },
+    intent: { circuit: 'intent_attestation', version: 2 },
+    sale: { circuit: 'sealed_sale_release', version: 3 },
+  };
+  async function assertVkGate(activeDeps, mode) {
+    const spec = VK_GATE_CIRCUITS[mode];
+    try {
+      const { vk } = await activeDeps.provingAssets.resolveVerifyingKey(spec.circuit);
+      await activeDeps.settle.assertOnChainVerifyingKey(activeDeps.connection, spec.version, vk);
+    } catch (err) {
+      if (err.name === 'ProvingAssetError') throw err;
+      const wrapped = new Error(`verifying-key gate refused ${spec.circuit} (circuit version ${spec.version}): ${err.message}`);
+      wrapped.code = 'VK_GATE_REJECTED';
+      throw wrapped;
+    }
+  }
+
+  // Operational readiness RESOLVES proving assets (downloading checksum-pinned
+  // artifacts on first use) instead of probing with downloads disabled — the
+  // status() probe is a read-only report and must not gate operations, or a
+  // fresh packaged install deadlocks (status says unavailable, operations
+  // never reach the resolver).
+  async function requireReady() {
+    const activeDeps = await ensureDeps();
+    try {
+      await getProvingAssetPaths();
+    } catch (err) {
+      const error = new Error(`proving assets unavailable: ${err.message}`);
+      error.code = 'ZK_UNAVAILABLE';
+      throw error;
+    }
+    let onChain;
+    try {
+      onChain = await fetchOnChain(activeDeps);
+    } catch (err) {
+      const error = new Error(`validator unavailable at ${rpcUrl}: ${err.message}`);
+      error.code = 'ZK_UNAVAILABLE';
+      throw error;
+    }
+    if (!onChain) {
+      const error = new Error(`shared ZK state is not initialized at ${sharedStatePda || 'the configured PDA'}`);
+      error.code = 'ZK_UNAVAILABLE';
+      throw error;
+    }
+    // Reconcile external writers' on-chain growth into the local snapshot
+    // BEFORE rebuilding trees (multi-party invariant; shared with status()).
+    const state = await reconcileForOperation(activeDeps, onChain);
+    if (state.secretEnvelope) {
+      state.secrets = unlockZkState(state, custody);
+    }
+    ensureInstallSecrets(state, activeDeps.e2ee);
+    return { state, deps: activeDeps, onChain, ...rebuildZkTrees(state, activeDeps.zkTree) };
+  }
+
+  // --- Split-phase proving (browser prover + relayer) -------------------------
+  // prepare* builds the witness and captures the pending values WITHOUT
+  // settling or persisting; relayAction re-derives the witness
+  // deterministically, refuses to settle on any drift, and only then applies
+  // the exact state mutation the one-shot append/revoke paths use.
+
+  function expectedActionPublicInputs(witnessInput, codec) {
+    return [
+      witnessInput.oldNoteRoot,
+      witnessInput.newNoteRoot,
+      witnessInput.oldNullRoot,
+      witnessInput.newNullRoot,
+      witnessInput.nullifier,
+      witnessInput.packed,
+    ].map((value) => codec.frToBytes32BE(value));
+  }
+
+  function publicInputsEqual(left, right) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((value, index) => Buffer.from(value).equals(Buffer.from(right[index])));
+  }
+  function assertProverPublicInputs(expected, actual, label) {
+    if (!publicInputsEqual(expected, actual)) {
+      const error = new Error(`${label} prover returned public inputs that do not match the locally built witness; refusing settlement and persistence`);
+      error.code = 'PROOF_STATE_MISMATCH';
+      throw error;
+    }
+  }
+
+
+  function applyAppendOutcome(state, { scope, sealed, rho, sig, sale }, noteTree, nullifierTree) {
+    const index = state.noteLeaves.length;
+    // Public metadata only; openings go to the encrypted envelope.
+    state.notes.push({
+      index,
+      scope,
+      sealed: {
+        ciphertextB64: sealed.ciphertextB64,
+        nonceB64: sealed.nonceB64,
+        envelopes: sealed.envelopes,
+      },
+      appendSig: sig,
+      appendedAt: new Date().toISOString(),
+      ...(sale ? { saleable: true } : {}),
+    });
+    state.secrets.noteOpenings[String(index)] = {
+      rho,
+      payloadCommit: sale ? sale.payloadCommitPos : sealed.payloadCommit,
+      scope,
+      ...(sale ? { dekLo: sale.dekLo, dekHi: sale.dekHi } : {}),
+    };
+    snapshotFromTrees(state, noteTree, nullifierTree);
+    return index;
+  }
+
+  function applyRevokeOutcome(state, { noteIndex, nullifier, sig }, noteTree, nullifierTree) {
+    const note = state.notes.find((entry) => Number(entry.index) === noteIndex);
+    if (note) {
+      note.revokeSig = sig;
+      note.revokedAt = new Date().toISOString();
+    }
+    state.nullifierValues.push(nullifier);
+    snapshotFromTrees(state, noteTree, nullifierTree);
+  }
+
+  function publicSettlementState(onChain, extra = {}) {
+    return {
+      note_root: rootHex(onChain.noteRoot),
+      null_root: rootHex(onChain.nullRoot),
+      note_count: Number(onChain.noteCount),
+      null_count: Number(onChain.nullCount),
+      ...extra,
+    };
+  }
+
+  function attachSettlementEvidence(result, state, activeDeps, {
+    event,
+    proofBytes = null,
+    publicInputs = [],
+    predecessorRefs = [],
+    evidenceState,
+  }) {
+    const settlementReceipt = createZkSettlementEvidence({
+      event,
+      programId,
+      cluster,
+      transactionSignature: result.sig ?? result.signature ?? null,
+      explorerUrl: result.explorerUrl ?? null,
+      proofBytes,
+      publicInputs,
+      state: evidenceState,
+      signerSecret: state.secrets.install.ownerKey,
+      signerId: publicKeyString(activeDeps.payer?.publicKey),
+      predecessorRefs,
+    });
+    return {
+      ...result,
+      receiptRef: settlementReceipt.receipt_ref,
+      settlementReceipt,
+    };
+  }
+
+  async function settledResult(activeDeps, state, sig, extra, evidence) {
+    const after = await fetchOnChain(activeDeps);
+    const result = {
+      sig,
+      explorerUrl: explorerUrlFor(sig, cluster),
+      cluster,
+      noteCount: Number(after.noteCount),
+      nullCount: Number(after.nullCount),
+      noteRoot: rootHex(after.noteRoot),
+      nullRoot: rootHex(after.nullRoot),
+      ...extra,
+    };
+    const evidenceState = publicSettlementState(after, evidence.evidenceState);
+    if (evidence.event === 'action.append' || evidence.event === 'action.revoke') {
+      const appendMode = evidence.event === 'action.append';
+      evidenceState.previous_note_root = Buffer.from(evidence.publicInputs[0]).toString('hex');
+      evidenceState.previous_null_root = Buffer.from(evidence.publicInputs[2]).toString('hex');
+      evidenceState.previous_note_count = evidenceState.note_count - (appendMode ? 1 : 0);
+      evidenceState.previous_null_count = evidenceState.null_count - (appendMode ? 0 : 1);
+    }
+    return attachSettlementEvidence(result, state, activeDeps, {
+      ...evidence,
+      evidenceState,
+    });
+  }
+
+
+  // DEK-blinded plaintext commitment for a saleable note: fresh 128-bit DEK
+  // limbs per note; the blinded fold replaces the E2EE payloadCommit as the
+  // tree-committed value (the action circuit binds any field element).
+  function sealSalePayload(sale, plaintext) {
+    const plaintextBytes = Buffer.from(plaintext, 'utf8');
+    if (plaintextBytes.length < 1 || plaintextBytes.length > SALE_PAYLOAD_CAPACITY) {
+      const error = new Error(`saleable memories are limited to ${SALE_PAYLOAD_CAPACITY} bytes (sealed_sale_release circuit capacity); got ${plaintextBytes.length}`);
+      error.code = 'BAD_REQUEST';
+      throw error;
+    }
+    const dekLo = BigInt(`0x${crypto.randomBytes(16).toString('hex')}`).toString(10);
+    const dekHi = BigInt(`0x${crypto.randomBytes(16).toString('hex')}`).toString(10);
+    const payloadCommitPos = sale.foldChunksBlind(sale.bytesToChunks(plaintextBytes), dekLo, dekHi).toString(10);
+    return { dekLo, dekHi, payloadCommitPos };
+  }
+
+  async function append({ plaintext, scope, saleable = false }) {
+    const { state, deps: activeDeps, noteTree, nullifierTree } = await requireReady();
+    const ownerKey = state.secrets.install.ownerKey;
+    // Fresh rho PER NOTE: reusing one rho would give every note the same
+    // nullifier Poseidon(DOMAIN_REVOCATION, ownerKey, rho) and make all but
+    // the first revocation unprovable.
+    const rho = randomFieldElement();
+    const noteContext = activeDeps.e2ee.deriveNoteContext({ ownerKey, rho, scope });
+    const sealed = await activeDeps.e2ee.e2eeEncrypt({
+      plaintext,
+      recipients: [state.secrets.install.recipientPublicKeyB64],
+      scope,
+      noteContext,
+    });
+    const sale = saleable ? sealSalePayload(activeDeps.sale, plaintext) : null;
+
+    const witnessInput = activeDeps.witness.buildActionWitness({
+      mode: 'append', noteTree, nullifierTree, ownerKey, rho,
+      payloadCommit: sale ? sale.payloadCommitPos : sealed.payloadCommit,
+    });
+
+    await assertVkGate(activeDeps, 'action');
+    const proveStartedAt = Date.now();
+    const { proofBytes, publicInputs } = await activeDeps.prover(witnessInput);
+    assertProverPublicInputs(
+      expectedActionPublicInputs(witnessInput, activeDeps.codec),
+      publicInputs,
+      'action append',
+    );
+    const proveMs = Date.now() - proveStartedAt;
+    const sig = await activeDeps.settle.settleAction(
+      activeDeps.connection,
+      activeDeps.payer,
+      proofBytes,
+      publicInputs,
+      1,
+    );
+
+    const index = applyAppendOutcome(state, { scope, sealed, rho, sig, sale }, noteTree, nullifierTree);
+    writeZkState(statePath, state, custody);
+    return settledResult(activeDeps, state, sig, { noteIndex: index, proveMs }, {
+      event: 'action.append',
+      proofBytes,
+      publicInputs,
+      evidenceState: {
+        note_root: Buffer.from(publicInputs[1]).toString('hex'),
+        null_root: Buffer.from(publicInputs[3]).toString('hex'),
+        note_index: index,
+      },
+    });
+  }
+
+  async function revoke({ noteIndex }) {
+    const { state, deps: activeDeps, noteTree, nullifierTree } = await requireReady();
+    const opening = state.secrets.noteOpenings[String(noteIndex)];
+    if (!opening?.rho || !opening?.payloadCommit) {
+      const error = new Error(`noteIndex ${noteIndex} has no local opening; only notes created by this persisted install can be revoked`);
+      error.code = 'NOTE_OPENING_MISSING';
+      throw error;
+    }
+
+    const witnessInput = activeDeps.witness.buildActionWitness({
+      mode: 'revoke', noteTree, nullifierTree,
+      // Per-note identity wins: third-party writers (e.g. the multi-agent
+      // demo) custody their own ownerKey per opening; desktop-created notes
+      // fall back to the install identity.
+      ownerKey: opening.ownerKey ?? state.secrets.install.ownerKey,
+      rho: opening.rho,
+      payloadCommit: opening.payloadCommit,
+      noteIndex,
+    });
+
+    await assertVkGate(activeDeps, 'action');
+    const proveStartedAt = Date.now();
+    const { proofBytes, publicInputs } = await activeDeps.prover(witnessInput);
+    assertProverPublicInputs(
+      expectedActionPublicInputs(witnessInput, activeDeps.codec),
+      publicInputs,
+      'action revoke',
+    );
+    const proveMs = Date.now() - proveStartedAt;
+    const sig = await activeDeps.settle.settleAction(
+      activeDeps.connection,
+      activeDeps.payer,
+      proofBytes,
+      publicInputs,
+      1,
+    );
+
+    applyRevokeOutcome(state, { noteIndex, nullifier: witnessInput.nullifier, sig }, noteTree, nullifierTree);
+    writeZkState(statePath, state, custody);
+    return settledResult(activeDeps, state, sig, { noteIndex, proveMs }, {
+      event: 'action.revoke',
+      proofBytes,
+      publicInputs,
+      evidenceState: {
+        note_root: Buffer.from(publicInputs[1]).toString('hex'),
+        null_root: Buffer.from(publicInputs[3]).toString('hex'),
+        note_index: noteIndex,
+      },
+    });
+  }
+
+  // A fresh install generates its identity lazily inside requireReady. The
+  // split-phase flow MUST persist that identity at prepare time: relayAction
+  // re-reads the state file, and a regenerated ownerKey would make the
+  // rebuilt witness diverge from the browser's proof. Only the sealed
+  // envelope is written here — notes/nullifiers persist exclusively after a
+  // confirmed settlement.
+  function hasPersistedInstall() {
+    try {
+      return Boolean(readZkState(statePath)?.secretEnvelope);
+    } catch {
+      return false;
+    }
+  }
+
+  // Split-phase append: build the private proving input and pending mutation
+  // inside custody. The server proves it locally and exposes only an opaque
+  // single-use handle to the renderer.
+
+  async function prepareAppend({ plaintext, scope, saleable = false }) {
+    const installPersisted = hasPersistedInstall();
+    const { state, deps: activeDeps, noteTree, nullifierTree } = await requireReady();
+    if (!installPersisted) writeZkState(statePath, state, custody);
+    const ownerKey = state.secrets.install.ownerKey;
+    // Fresh rho PER NOTE, same invariant as the one-shot append path.
+    const rho = randomFieldElement();
+    const noteContext = activeDeps.e2ee.deriveNoteContext({ ownerKey, rho, scope });
+    const sealed = await activeDeps.e2ee.e2eeEncrypt({
+      plaintext,
+      recipients: [state.secrets.install.recipientPublicKeyB64],
+      scope,
+      noteContext,
+    });
+
+    const sale = saleable ? sealSalePayload(activeDeps.sale, plaintext) : null;
+    await assertVkGate(activeDeps, 'action');
+    const witnessInput = activeDeps.witness.buildActionWitness({
+      mode: 'append', noteTree, nullifierTree, ownerKey, rho,
+      payloadCommit: sale ? sale.payloadCommitPos : sealed.payloadCommit,
+    });
+    return { witnessInput, pending: { mode: 'append', scope, rho, sealed, sale } };
+  }
+
+  async function prepareRevoke({ noteIndex }) {
+    const installPersisted = hasPersistedInstall();
+    const { state, deps: activeDeps, noteTree, nullifierTree } = await requireReady();
+    if (!installPersisted) writeZkState(statePath, state, custody);
+    const opening = state.secrets.noteOpenings[String(noteIndex)];
+    if (!opening?.rho || !opening?.payloadCommit) {
+      const error = new Error(`noteIndex ${noteIndex} has no local opening; only notes created by this persisted install can be revoked`);
+      error.code = 'NOTE_OPENING_MISSING';
+      throw error;
+    }
+    const witnessInput = activeDeps.witness.buildActionWitness({
+      mode: 'revoke', noteTree, nullifierTree,
+      ownerKey: opening.ownerKey ?? state.secrets.install.ownerKey,
+      rho: opening.rho,
+
+      payloadCommit: opening.payloadCommit,
+      noteIndex,
+    });
+    await assertVkGate(activeDeps, 'action');
+    return { witnessInput, pending: { mode: 'revoke', noteIndex } };
+  }
+
+  async function provePreparedAction(witnessInput) {
+    const activeDeps = await ensureDeps();
+    try {
+      const { proofBytes, publicInputs } = await activeDeps.prover(witnessInput);
+      assertProverPublicInputs(
+        expectedActionPublicInputs(witnessInput, activeDeps.codec),
+        publicInputs,
+        'prepared action',
+      );
+      return { proofBytes, publicInputs };
+    } finally {
+      zeroizePrivateObject(witnessInput);
+    }
+  }
+
+  // Settlement for a custody-local action proof. The private proving input is
+  // rebuilt deterministically from pending values; if shared state drifted
+  // after preparation, the proof/public inputs are rejected before settlement.
+  async function relayAction({ pending, proofBytes, publicInputs }) {
+    if (!pending || (pending.mode !== 'append' && pending.mode !== 'revoke')) {
+      throw new Error('relayAction requires a pending prepare session (mode append|revoke)');
+    }
+    const { state, deps: activeDeps, noteTree, nullifierTree } = await requireReady();
+
+    let witnessInput;
+    if (pending.mode === 'append') {
+      witnessInput = activeDeps.witness.buildActionWitness({
+        mode: 'append', noteTree, nullifierTree,
+        ownerKey: state.secrets.install.ownerKey,
+        rho: pending.rho,
+        payloadCommit: pending.sale ? pending.sale.payloadCommitPos : pending.sealed.payloadCommit,
+      });
+    } else {
+      const opening = state.secrets.noteOpenings[String(pending.noteIndex)];
+      if (!opening?.rho || !opening?.payloadCommit) {
+        const error = new Error(`noteIndex ${pending.noteIndex} has no local opening; only notes created by this persisted install can be revoked`);
+        error.code = 'NOTE_OPENING_MISSING';
+        throw error;
+      }
+      witnessInput = activeDeps.witness.buildActionWitness({
+        mode: 'revoke', noteTree, nullifierTree,
+        ownerKey: opening.ownerKey ?? state.secrets.install.ownerKey,
+        rho: opening.rho,
+        payloadCommit: opening.payloadCommit,
+        noteIndex: pending.noteIndex,
+      });
+    }
+
+    const expected = expectedActionPublicInputs(witnessInput, activeDeps.codec);
+    if (!publicInputsEqual(expected, publicInputs)) {
+      const error = new Error('proved public inputs do not match the current shared tree state (state drifted after prepare); re-run prepare and prove again');
+      error.code = 'PROOF_STATE_MISMATCH';
+      throw error;
+    }
+    await assertVkGate(activeDeps, 'action');
+    const sig = await activeDeps.settle.settleAction(
+      activeDeps.connection,
+      activeDeps.payer,
+      proofBytes,
+      publicInputs,
+      1,
+    );
+
+    let extra;
+    if (pending.mode === 'append') {
+      const index = applyAppendOutcome(state, { scope: pending.scope, sealed: pending.sealed, rho: pending.rho, sig, sale: pending.sale || null }, noteTree, nullifierTree);
+      extra = { noteIndex: index };
+    } else {
+      applyRevokeOutcome(state, { noteIndex: pending.noteIndex, nullifier: witnessInput.nullifier, sig }, noteTree, nullifierTree);
+      extra = { noteIndex: pending.noteIndex };
+    }
+    writeZkState(statePath, state, custody);
+    return settledResult(activeDeps, state, sig, extra, {
+      event: pending.mode === 'append' ? 'action.append' : 'action.revoke',
+      proofBytes,
+      publicInputs,
+      evidenceState: {
+        note_root: Buffer.from(publicInputs[1]).toString('hex'),
+        null_root: Buffer.from(publicInputs[3]).toString('hex'),
+        note_index: extra.noteIndex,
+      },
+    });
+  }
+
+  // Intent attestations carry no local tree mutation: the relayer simply pays
+  // for settlement. publicInputs = 4 × 32B [noteRoot, actionHash, nullifier, currentSlot].
+
+  async function relayIntent({ proofBytes, publicInputs }) {
+    const activeDeps = await ensureDeps();
+    await assertVkGate(activeDeps, 'intent');
+    const sig = await activeDeps.settle.settleIntent(
+      activeDeps.connection,
+      activeDeps.payer,
+      proofBytes,
+      publicInputs,
+    );
+    return {
+      sig,
+      explorerUrl: explorerUrlFor(sig, cluster),
+      cluster,
+    };
+  }
+
+
+  // --- Sealed Sale (ZKCP) marketplace ----------------------------------------
+  // Sovereignty invariant: ownerKey/rho/DEK/buyerSecret/plaintext never leave
+  // this process. Everything returned below is proof bytes, public inputs,
+  // pubkeys, or terms — the exact wire shape settle_sale/claim_sale accept.
+
+  // Buyer identities live in the sealed envelope next to the install secrets:
+  // a Solana keypair (escrow signer) and labeled BabyJub key pairs (sale
+  // protocol recipient keys). Created lazily, persisted immediately.
+  function ensureBuyerSecrets(state, activeDeps) {
+    const install = state.secrets.install;
+    let mutated = false;
+    if (!install.buyerSolanaSecretKeyB64) {
+      const keypair = activeDeps.web3.Keypair.generate();
+      install.buyerSolanaSecretKeyB64 = Buffer.from(keypair.secretKey).toString('base64');
+      mutated = true;
+    }
+    if (!install.buyerKeys || typeof install.buyerKeys !== 'object') {
+      install.buyerKeys = {};
+      mutated = true;
+    }
+    if (!install.buyerKeys.default) {
+      const pair = activeDeps.sale.generateBuyerKeyPair();
+      install.buyerKeys.default = {
+        secret: pair.secret.toString(10),
+        publicKeyX: pair.publicKey.x.toString(10),
+        publicKeyY: pair.publicKey.y.toString(10),
+        createdAt: new Date().toISOString(),
+      };
+      mutated = true;
+    }
+    return mutated;
+  }
+
+  const zeroBytes = (value) => Buffer.from(value).every((byte) => byte === 0);
+  const frFromBytes = (value) => BigInt(`0x${Buffer.from(value).toString('hex')}`);
+
+  function saleError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+  }
+
+  // Read-only chain view of a sale receipt; never touches custody.
+  async function saleReceipt({ keyCommitBytes, envelopeCommitBytes }) {
+    const activeDeps = await ensureDeps();
+    const receipt = await withTimeout(
+      activeDeps.settle.fetchSaleReceipt(activeDeps.connection, keyCommitBytes, envelopeCommitBytes),
+      timeoutMs,
+      'validator request',
+    );
+    return {
+      receipt,
+      receiptPda: publicKeyString(activeDeps.settle.saleReceiptPda(keyCommitBytes, envelopeCommitBytes)),
+    };
+  }
+
+
+  // Phase 1 (seller): decrypt the note from local custody, build the sale
+  // witness, prove locally. FAIR EXCHANGE: the DEK envelope triple
+  // (epk/encDek/nonce) is sealed into seller custody keyed by the terms hash
+  // and NEVER returned — the only way it leaves custody is claimSale, which
+  // reveals it on-chain atomically with payment. The response carries only
+  // the proof, the 6 public inputs, the ciphertext chunks, and commitments.
+
+  async function prepareSaleListing({ noteIndex, priceLamports, buyerPub, buyerKeyLabel, expirySlots, mint }) {
+    const { state, deps: activeDeps, noteTree } = await requireReady();
+    const opening = state.secrets.noteOpenings[String(noteIndex)];
+    if (!opening?.rho || !opening?.payloadCommit) {
+      throw saleError('NOTE_OPENING_MISSING', `noteIndex ${noteIndex} has no local opening; only notes created by this persisted install can be listed`);
+    }
+    if (!opening.dekLo || !opening.dekHi) {
+      throw saleError('NOTE_NOT_SALEABLE', `noteIndex ${noteIndex} was not sealed for sale — its note commitment is not a DEK-blinded plaintext fold; append the memory with saleable:true first`);
+    }
+    const note = state.notes.find((entry) => Number(entry.index) === noteIndex);
+    if (!note?.sealed?.ciphertextB64) {
+      throw saleError('NOTE_OPENING_MISSING', `noteIndex ${noteIndex} has no local sealed payload; the plaintext cannot be recovered for proving`);
+    }
+    const ownerKey = opening.ownerKey ?? state.secrets.install.ownerKey;
+    // Local-only plaintext recovery for witness building (AEAD-verified).
+    const noteContext = activeDeps.e2ee.deriveNoteContext({ ownerKey, rho: opening.rho, scope: note.scope });
+    const plaintextBytes = Buffer.from(await activeDeps.e2ee.e2eeDecrypt({
+      ciphertextB64: note.sealed.ciphertextB64,
+      nonceB64: note.sealed.nonceB64,
+      envelopes: note.sealed.envelopes,
+      recipientSecretKey: state.secrets.install.recipientSecretKeyB64,
+      scope: note.scope,
+      noteContext,
+    }));
+
+
+
+    // Buyer keys (if used) and the sealed envelope are both persisted by the
+    // writeZkState after proving — one sealed write covers both.
+    let buyer = buyerPub;
+    if (!buyer && !buyerKeyLabel) {
+      throw saleError('BAD_REQUEST', 'buyerPubkeyX/buyerPubkeyY required — a listing must bind the buyer\'s BabyJub public key (the buyer exposes it via GET /api/zk/sale/buyer-identity); silently defaulting to this device\'s own key would create an unsellable self-bound listing');
+    }
+    if (!buyer) {
+      const label = buyerKeyLabel;
+      ensureBuyerSecrets(state, activeDeps);
+      const key = state.secrets.install.buyerKeys[label];
+      if (!key) {
+        throw saleError('BAD_REQUEST', `unknown buyerKeyLabel "${label}"; this device custodies: ${Object.keys(state.secrets.install.buyerKeys).join(', ') || '(none)'}`);
+      }
+      buyer = { x: key.publicKeyX, y: key.publicKeyY };
+    }
+
+    const currentSlot = await withTimeout(
+      Promise.resolve(activeDeps.connection.getSlot()),
+      timeoutMs,
+      'validator request',
+    );
+    const expirySlot = BigInt(currentSlot) + BigInt(expirySlots);
+    const nonce = randomFieldElement();
+    // The desktop payer is the seller identity: claim_sale must be signed by
+    // the seller, and this server already pays/signs with the payer key.
+    const sellerPubkey = activeDeps.payer.publicKey.toBase58();
+    const saleMint = mint || WRAPPED_SOL_MINT;
+
+
+    await assertVkGate(activeDeps, 'sale');
+    let artifacts;
+    try {
+      artifacts = activeDeps.sale.buildSaleWitness({
+        noteTree,
+        noteIndex,
+        ownerKey,
+        rho: opening.rho,
+        dekLo: opening.dekLo,
+        dekHi: opening.dekHi,
+        nonce,
+        plaintextBytes,
+        buyerPub: buyer,
+        sellerPubkey,
+        mint: saleMint,
+        priceLamports,
+        expirySlot,
+      });
+    } catch (err) {
+      throw saleError('BAD_REQUEST', `sale witness rejected the inputs: ${err.message}`);
+    }
+
+    const { proofBytes, publicInputs } = await activeDeps.saleProver(artifacts.input);
+    assertProverPublicInputs(
+      [
+        artifacts.noteRoot,
+        artifacts.payloadCommitPos,
+        artifacts.cipherCommit,
+        artifacts.keyCommit,
+        artifacts.saleTermsHash,
+        artifacts.envelopeCommit,
+      ].map((value) => activeDeps.codec.frToBytes32BE(value)),
+      publicInputs,
+      'sealed sale listing',
+    );
+
+    // Seal the envelope triple into seller custody BEFORE responding; it is
+    // re-sealed with the same v2 mechanism as every other ZK secret.
+    // CUSTODY KEY = the unique receipt identity (keyCommit:envelopeCommit),
+    // NOT the terms hash: two listings with identical buyer/seller/mint/price/
+    // expiry/payloadLen share a terms-hash preimage and would overwrite each
+    // other — the first would become unclaimable (commitment mismatch).
+    const saleTermsHashHex = rootHex(artifacts.saleTermsHash);
+    const keyCommitHex = rootHex(artifacts.keyCommit);
+    const envelopeCommitHex = rootHex(artifacts.envelopeCommit);
+    state.secrets.saleEnvelopes[`${keyCommitHex}:${envelopeCommitHex}`] = {
+      epkX: artifacts.epk.x.toString(10),
+      epkY: artifacts.epk.y.toString(10),
+      encDekLo: artifacts.encDEK_lo.toString(10),
+      encDekHi: artifacts.encDEK_hi.toString(10),
+      nonce: nonce.toString(10),
+      saleTermsHashHex,
+      keyCommitHex,
+      envelopeCommitHex,
+      noteIndex,
+      sellerPubkey,
+      mint: saleMint,
+      priceLamports: BigInt(priceLamports).toString(10),
+      expirySlot: expirySlot.toString(10),
+      payloadLen: plaintextBytes.length,
+      createdAt: new Date().toISOString(),
+    };
+    writeZkState(statePath, state, custody);
+
+    return {
+      proofBytes: {
+        a: Buffer.from(proofBytes.a).toString('hex'),
+        b: Buffer.from(proofBytes.b).toString('hex'),
+        c: Buffer.from(proofBytes.c).toString('hex'),
+      },
+      publicInputs: publicInputs.map((value) => Buffer.from(value).toString('hex')),
+      ciphertextChunks: artifacts.ciphertextChunks.map((chunk) => chunk.toString(10)),
+      saleTermsHashHex,
+      payloadCommitPosHex: rootHex(artifacts.payloadCommitPos),
+      keyCommitHex,
+      envelopeCommitHex,
+      // Public terms preimage — the buyer MUST recompute saleTermsHash from
+      // these fields with their own custodied buyer key before escrowing
+      // (colluder-wrap defense; the chain cannot check the preimage).
+      sellerPubkey,
+      mint: saleMint,
+      priceLamports: BigInt(priceLamports).toString(10),
+      expirySlot: expirySlot.toString(10),
+      payloadLen: plaintextBytes.length,
+      receiptPda: publicKeyString(activeDeps.settle.saleReceiptPda(
+        activeDeps.codec.frToBytes32BE(artifacts.keyCommit),
+        activeDeps.codec.frToBytes32BE(artifacts.envelopeCommit),
+      )),
+    };
+  }
+
+  // Seller claim: the ONLY path by which the sealed envelope leaves custody.
+  // claim_sale verifies the (epk, encDek, nonce) triple against the on-chain
+  // envelopeCommit (Poseidon5) and releases the buyer's escrow payment in the
+  // same transaction — the reveal is atomic with getting paid.
+  async function claimSale({ saleTermsHashBytes, buyerPubkey, keyCommitBytes, envelopeCommitBytes, predecessorReceiptRefs = [] }) {
+    // Custody-only: claim builds no action-tree witness, so it must survive
+    // unrelated appends advancing the chain after listing — otherwise paid
+    // escrow would strand until refund. The program enforces claim validity.
+    const { state, deps: activeDeps } = await requireCustody();
+    const saleTermsHashHex = Buffer.from(saleTermsHashBytes).toString('hex');
+    const custodyKey = `${Buffer.from(keyCommitBytes).toString('hex')}:${Buffer.from(envelopeCommitBytes).toString('hex')}`;
+    const envelope = state.secrets.saleEnvelopes?.[custodyKey];
+    if (!envelope) {
+      throw saleError('SALE_ENVELOPE_MISSING', `no sealed sale envelope in custody for receipt ${custodyKey.slice(0, 24)}…; only the listing device can claim`);
+    }
+    if (envelope.saleTermsHashHex !== saleTermsHashHex) {
+      throw saleError('SALE_ENVELOPE_MISMATCH', 'the supplied saleTermsHash does not match the sealed envelope for this receipt; refusing to claim');
+    }
+    // A spent listing cannot be claimed twice; fail closed before paying fees.
+    const { receipt } = await saleReceipt({ keyCommitBytes, envelopeCommitBytes });
+    if (!receipt) {
+      throw saleError('SALE_RECEIPT_MISSING', 'no sale receipt on-chain for this keyCommit + envelopeCommit pair; submit the listing first');
+    }
+    if (!zeroBytes(receipt.epk) || !zeroBytes(receipt.encDek) || !zeroBytes(receipt.nonce)) {
+      throw saleError('SALE_ALREADY_CLAIMED', 'this sale was already claimed (envelope revealed on-chain)');
+    }
+    const sharedState = await fetchOnChain(activeDeps);
+    let buyer;
+    try {
+      buyer = new activeDeps.web3.PublicKey(buyerPubkey);
+    } catch {
+      throw saleError('BAD_REQUEST', 'buyerPubkey must be a base58 Solana public key');
+    }
+    const fr = activeDeps.codec.frToBytes32BE;
+    const epkBytes = Buffer.concat([fr(BigInt(envelope.epkX)), fr(BigInt(envelope.epkY))]);
+    const encDekBytes = Buffer.concat([fr(BigInt(envelope.encDekLo)), fr(BigInt(envelope.encDekHi))]);
+    const nonceBytes = Buffer.from(fr(BigInt(envelope.nonce)));
+    // The desktop payer IS the seller identity (it signed the listing's terms
+    // hash), so the same custodied key signs the claim.
+    const sig = await activeDeps.settle.claimSale(
+      activeDeps.connection,
+      activeDeps.payer,
+      buyer,
+      saleTermsHashBytes,
+      keyCommitBytes,
+      envelopeCommitBytes,
+      epkBytes,
+      encDekBytes,
+      nonceBytes,
+    );
+    const result = {
+      signature: sig,
+      explorerUrl: explorerUrlFor(sig, cluster),
+      cluster,
+    };
+    return attachSettlementEvidence(result, state, activeDeps, {
+      event: 'sale.claim',
+      predecessorRefs: predecessorReceiptRefs,
+      evidenceState: publicSettlementState(sharedState, {
+        sale_terms_hash: saleTermsHashHex,
+        key_commit: Buffer.from(keyCommitBytes).toString('hex'),
+        envelope_commit: Buffer.from(envelopeCommitBytes).toString('hex'),
+        sale_receipt_pda: publicKeyString(activeDeps.settle.saleReceiptPda(keyCommitBytes, envelopeCommitBytes)),
+        buyer_pubkey: buyerPubkey,
+      }),
+    });
+  }
+
+  // Phase 2 (seller): attest the sale on-chain. The proof binds the note root,
+  // commitments, and terms, and settle_sale verifies them against shared
+  // state. No tree snapshot is mutated; only the encrypted local receipt
+  // signing identity is persisted when this is a fresh install.
+
+  async function submitSaleListing({ proofBytes, publicInputs, predecessorReceiptRefs = [] }) {
+    const { state, deps: activeDeps } = await requireCustody();
+    if (!hasPersistedInstall()) writeZkState(statePath, state, custody);
+    const sharedState = await fetchOnChain(activeDeps);
+    await assertVkGate(activeDeps, 'sale');
+    const sig = await activeDeps.settle.settleSale(
+      activeDeps.connection,
+      activeDeps.payer,
+      proofBytes,
+      publicInputs,
+    );
+    const receiptPda = activeDeps.settle.saleReceiptPda(
+      publicInputs[3],
+      publicInputs[5],
+    );
+    const result = {
+      sig,
+      signature: sig,
+      txSignature: sig,
+      receiptPda: publicKeyString(receiptPda),
+      explorerUrl: explorerUrlFor(sig, cluster),
+      cluster,
+    };
+    return attachSettlementEvidence(result, state, activeDeps, {
+      event: 'sale.list',
+      proofBytes,
+      publicInputs,
+      predecessorRefs: predecessorReceiptRefs,
+      evidenceState: publicSettlementState(sharedState, {
+        note_root: Buffer.from(publicInputs[0]).toString('hex'),
+        payload_commit_pos: Buffer.from(publicInputs[1]).toString('hex'),
+        cipher_commit: Buffer.from(publicInputs[2]).toString('hex'),
+        key_commit: Buffer.from(publicInputs[3]).toString('hex'),
+        sale_terms_hash: Buffer.from(publicInputs[4]).toString('hex'),
+        envelope_commit: Buffer.from(publicInputs[5]).toString('hex'),
+        sale_receipt_pda: publicKeyString(receiptPda),
+      }),
+    });
+  }
+
+  // Phase 3 (buyer): verify an offered listing against the attested receipt.
+  // The buyer calculates cipherCommit from delivered ciphertext chunks and
+  // confirms it matches the receipt BEFORE paying — the proof ensures the
+  // seller holds a matching plaintext.
+  async function verifySale({ saleTermsHashBytes, keyCommitBytes, envelopeCommitBytes, ciphertextChunks }) {
+    const activeDeps = await ensureDeps();
+    const { receipt, receiptPda } = await saleReceipt({ keyCommitBytes, envelopeCommitBytes });
+    if (!receipt) {
+      throw saleError('SALE_RECEIPT_MISSING', 'no sale receipt on-chain for this keyCommit + envelopeCommit pair; the listing has not been attested');
+    }
+    const deliveredFold = activeDeps.sale.foldChunks(ciphertextChunks.map((chunk) => BigInt(chunk)));
+    const checks = {
+      receiptExists: true,
+      keyCommitMatch: Buffer.from(receipt.keyCommit).equals(Buffer.from(keyCommitBytes)),
+      envelopeCommitMatch: Buffer.from(receipt.envelopeCommit).equals(Buffer.from(envelopeCommitBytes)),
+      cipherFoldMatch: deliveredFold === frFromBytes(receipt.cipherCommit),
+      saleTermsHashMatch: Buffer.from(receipt.saleTermsHash).equals(Buffer.from(saleTermsHashBytes)),
+      envelopeCommitNonzero: !zeroBytes(receipt.envelopeCommit),
+      envelopeZeroOnChain: zeroBytes(receipt.epk) && zeroBytes(receipt.encDek) && zeroBytes(receipt.nonce),
+    };
+    return { ok: Object.values(checks).every(Boolean), checks, receiptPda, slot: receipt.slot };
+  }
+
+  // Buyer escrow, pinned to the attested receipt. The buyer Solana keypair
+  // comes from local custody; it never appears in any request/response.
+  async function createSaleEscrow({ saleTermsHashBytes, priceLamports, expirySlot, sellerPubkey, keyCommitBytes, envelopeCommitBytes, mint, payloadLen, buyerKeyLabel, ciphertextChunks }) {
+    const installPersisted = hasPersistedInstall();
+    const { state, deps: activeDeps } = await requireCustody();
+    const mutated = ensureBuyerSecrets(state, activeDeps);
+    if (!installPersisted || mutated) writeZkState(statePath, state, custody);
+
+    const { receipt } = await saleReceipt({ keyCommitBytes, envelopeCommitBytes });
+    if (!receipt) {
+      throw saleError('SALE_RECEIPT_MISSING', 'no sale receipt on-chain for this keyCommit + envelopeCommit pair');
+    }
+    if (!zeroBytes(receipt.epk) || !zeroBytes(receipt.encDek) || !zeroBytes(receipt.nonce)) {
+      throw saleError('SALE_ALREADY_CLAIMED', 'this sale was already claimed (envelope revealed on-chain); do not escrow against a spent listing');
+    }
+    if (!Buffer.from(receipt.saleTermsHash).equals(Buffer.from(saleTermsHashBytes))) {
+      throw saleError('SALE_TERMS_MISMATCH', 'the advertised saleTermsHash does not match the on-chain receipt; refusing to escrow');
+    }
+
+    // CIPHERTEXT FOLD: the separate VERIFY step is advisory and bypassable —
+    // the fold check is enforced HERE, atomically before any transfer. Junk
+    // ciphertext (fold != the on-chain cipherCommit) can never be escrowed.
+    // Canonical limbs only (same rules as OPEN's parser): a non-canonical or
+    // out-of-field limb would fold mod r here but be rejected at open time —
+    // the buyer would pay for a listing the UI refuses to decrypt.
+    const FR = FIELD_R;
+    if (!Array.isArray(ciphertextChunks) || ciphertextChunks.length !== 32) {
+      throw saleError('BAD_REQUEST', 'ciphertextChunks must be an array of 32 decimal strings (fold enforced at escrow)');
+    }
+    for (let i = 0; i < 32; i += 1) {
+      const chunk = ciphertextChunks[i];
+      if (typeof chunk !== 'string' || !/^(0|[1-9][0-9]*)$/.test(chunk)) {
+        throw saleError('BAD_REQUEST', `ciphertextChunks[${i}] must be a canonical decimal string`);
+      }
+      if (BigInt(chunk) >= FR) {
+        throw saleError('BAD_REQUEST', `ciphertextChunks[${i}] is not a canonical BN254 scalar field element`);
+      }
+    }
+    const deliveredFold = activeDeps.sale.foldChunks(ciphertextChunks.map((c) => BigInt(c)));
+    const deliveredFoldHex = deliveredFold.toString(16).padStart(64, '0');
+    if (deliveredFoldHex !== Buffer.from(receipt.cipherCommit).toString('hex')) {
+      throw saleError(
+        'SALE_CIPHER_MISMATCH',
+        'the delivered ciphertext does not fold to the on-chain cipherCommit — junk delivery; refusing to escrow',
+      );
+    }
+
+    // COLLUDER-WRAP DEFENSE: the on-chain program cannot know the saleTermsHash
+    // preimage — only the buyer can check the listing binds THEIR key. Recompute
+    // the terms hash locally from the FULL listing (seller, mint, price, expiry,
+    // payloadLen) with THIS device's custodied BabyJub public key, and require it
+    // equals both the advertised hash and the on-chain receipt. A listing whose
+    // envelope wraps to a colluder key fails here, before any lamports move.
+    const label = buyerKeyLabel || 'default';
+    const buyerKey = state.secrets.install.buyerKeys?.[label];
+    if (!buyerKey) {
+      throw saleError('BAD_REQUEST', `unknown buyerKeyLabel "${label}"`);
+    }
+    if (typeof mint !== 'string' || !mint.trim()) {
+      throw saleError('BAD_REQUEST', 'mint must be a non-empty base58 string (required for the terms recompute)');
+    }
+    const payloadLenN = Number(payloadLen);
+    if (!Number.isSafeInteger(payloadLenN) || payloadLenN < 1 || payloadLenN > SALE_PAYLOAD_CAPACITY) {
+      throw saleError('BAD_REQUEST', `payloadLen must be an integer 1..${SALE_PAYLOAD_CAPACITY} (required for the terms recompute)`);
+    }
+    let recomputed;
+    try {
+      recomputed = activeDeps.sale.computeSaleTermsHash({
+        sellerPubkey,
+        buyerPub: [BigInt(buyerKey.publicKeyX), BigInt(buyerKey.publicKeyY)],
+        mint: mint.trim(),
+        priceLamports: BigInt(priceLamports),
+        expirySlot: BigInt(expirySlot),
+        payloadLen: BigInt(payloadLenN),
+      });
+    } catch (err) {
+      throw saleError('BAD_REQUEST', `listing terms failed validation: ${err.message}`);
+    }
+    const recomputedHex = recomputed.saleTermsHash.toString(16).padStart(64, '0');
+    if (recomputedHex !== Buffer.from(saleTermsHashBytes).toString('hex')) {
+      throw saleError(
+        'SALE_TERMS_NOT_BUYER_BOUND',
+        'the listing terms do not hash to the advertised saleTermsHash with THIS device\'s buyer key — ' +
+        'the envelope is likely wrapped to a different (colluder) key; refusing to escrow',
+      );
+    }
+
+    let seller;
+    try {
+      seller = new activeDeps.web3.PublicKey(sellerPubkey);
+    } catch {
+      throw saleError('BAD_REQUEST', 'sellerPubkey must be a base58 Solana public key');
+    }
+    const buyer = activeDeps.web3.Keypair.fromSecretKey(
+      new Uint8Array(Buffer.from(state.secrets.install.buyerSolanaSecretKeyB64, 'base64')),
+    );
+    const receiptPda = activeDeps.settle.saleReceiptPda(keyCommitBytes, envelopeCommitBytes);
+    const sig = await activeDeps.settle.createSaleEscrow(
+      activeDeps.connection,
+      buyer,
+      seller,
+      saleTermsHashBytes,
+      BigInt(priceLamports),
+      BigInt(expirySlot),
+      receiptPda,
+    );
+    return {
+      signature: sig,
+      buyerPubkey: buyer.publicKey.toBase58(),
+      escrowPda: publicKeyString(activeDeps.settle.saleEscrowPda(buyer.publicKey, saleTermsHashBytes)),
+      receiptPda: publicKeyString(receiptPda),
+      explorerUrl: explorerUrlFor(sig, cluster),
+      cluster,
+    };
+  }
+
+  // Buyer post-claim open: everything decryptive comes from the on-chain
+  // receipt (envelope + nonce revealed atomically at claim) plus the local
+  // buyer secret. Fails closed while the envelope is still zero.
+  async function openSale({ keyCommitBytes, envelopeCommitBytes, ciphertextChunks, payloadLen, buyerKeyLabel, predecessorReceiptRefs = [] }) {
+    const { state, deps: activeDeps } = await requireCustody();
+    const label = buyerKeyLabel || 'default';
+    const key = state.secrets.install?.buyerKeys?.[label];
+    if (!key?.secret) {
+      throw saleError('BUYER_KEY_MISSING', `no buyer key labeled "${label}" in local custody; only the buyer key a listing was bound to can open it`);
+    }
+    const { receipt } = await saleReceipt({ keyCommitBytes, envelopeCommitBytes });
+    if (!receipt) {
+      throw saleError('SALE_RECEIPT_MISSING', 'no sale receipt on-chain for this keyCommit + envelopeCommit pair');
+    }
+    if (zeroBytes(receipt.epk) && zeroBytes(receipt.encDek) && zeroBytes(receipt.nonce)) {
+      throw saleError('SALE_NOT_CLAIMED', 'sale receipt envelope is still zero on-chain — the seller has not claimed payment yet; the DEK envelope + nonce are revealed atomically at claim');
+    }
+    const sharedState = await fetchOnChain(activeDeps);
+    let revealed;
+    try {
+      revealed = activeDeps.sale.openAndVerifySale({
+        buyerSecret: key.secret,
+        epk: { x: frFromBytes(receipt.epk.subarray(0, 32)), y: frFromBytes(receipt.epk.subarray(32, 64)) },
+        encDEK_lo: frFromBytes(receipt.encDek.subarray(0, 32)),
+        encDEK_hi: frFromBytes(receipt.encDek.subarray(32, 64)),
+        ciphertext: ciphertextChunks.map((chunk) => BigInt(chunk)),
+        cipherCommit: frFromBytes(receipt.cipherCommit),
+        nonce: frFromBytes(receipt.nonce),
+        payloadCommitPos: frFromBytes(receipt.payloadCommitPos),
+      });
+    } catch (err) {
+      throw saleError('SALE_OPEN_REJECTED', `sealed sale open failed verification: ${err.message}`);
+    }
+    const full = Buffer.from(activeDeps.sale.chunksToBytes(revealed.plaintextChunks));
+    let byteLen = Number.isInteger(payloadLen) && payloadLen >= 0 && payloadLen <= full.length ? payloadLen : null;
+    if (byteLen === null) {
+      // Payload length is terms-bound, not separately on-chain; the default
+      // strips the zero padding bytesToChunks added to fill the fixed chunks.
+      byteLen = full.length;
+      while (byteLen > 0 && full[byteLen - 1] === 0) byteLen -= 1;
+    }
+    const result = { plaintextUtf8: full.subarray(0, byteLen).toString('utf8'), payloadLen: byteLen };
+    return attachSettlementEvidence(result, state, activeDeps, {
+      event: 'sale.open',
+      predecessorRefs: predecessorReceiptRefs,
+      evidenceState: publicSettlementState(sharedState, {
+        sale_terms_hash: Buffer.from(receipt.saleTermsHash).toString('hex'),
+        key_commit: Buffer.from(receipt.keyCommit).toString('hex'),
+        envelope_commit: Buffer.from(receipt.envelopeCommit).toString('hex'),
+        cipher_commit: Buffer.from(receipt.cipherCommit).toString('hex'),
+        payload_commit_pos: Buffer.from(receipt.payloadCommitPos).toString('hex'),
+        sale_receipt_pda: publicKeyString(activeDeps.settle.saleReceiptPda(keyCommitBytes, envelopeCommitBytes)),
+        receipt_slot: String(receipt.slot),
+        ciphertext_digest: `sha256:${crypto.createHash('sha256').update(JSON.stringify(ciphertextChunks.map(String))).digest('hex')}`,
+        opened_payload_bytes: byteLen,
+      }),
+    });
+  }
+
+
+  // Public-only buyer identity: the addresses a fresh install must fund (SOL
+  // escrow keypair) and hand to sellers (BabyJub public key). Generates on
+  // first call so there is always something to fund; NEVER returns secrets.
+  // Custody-only readiness for BUYER-side sale operations (escrow, open,
+  // identity): these build NO action-tree witnesses, so they must not require
+  // historical leaves or chain/local reconciliation — a fresh buyer with zero
+  // local notes can purchase from a seller whose appends advanced the chain.
+  async function requireCustody() {
+    const activeDeps = await ensureDeps();
+    const state = readZkState(statePath) || emptySnapshot();
+    if (state.secretEnvelope) {
+      state.secrets = unlockZkState(state, custody);
+    }
+    ensureInstallSecrets(state, activeDeps.e2ee);
+    return { state, deps: activeDeps };
+  }
+
+  async function buyerIdentity() {
+    const installPersisted = hasPersistedInstall();
+    // Identity is public-only and INDEPENDENT of proof/chain readiness: a fresh
+    // install must be able to show (and fund) its buyer address before proving
+    // assets are downloaded or the validator is reachable.
+    const activeDeps = await ensureDeps();
+    const state = readZkState(statePath) || emptySnapshot();
+    if (state.secretEnvelope) {
+      state.secrets = unlockZkState(state, custody);
+    }
+    ensureInstallSecrets(state, activeDeps.e2ee);
+    const mutated = ensureBuyerSecrets(state, activeDeps);
+    if (!installPersisted || mutated) writeZkState(statePath, state, custody);
+    const install = state.secrets.install;
+    const solanaPubkey = activeDeps.web3.Keypair.fromSecretKey(
+      new Uint8Array(Buffer.from(install.buyerSolanaSecretKeyB64, 'base64')),
+    ).publicKey;
+    let solBalanceLamports = null;
+    try {
+      solBalanceLamports = await activeDeps.connection.getBalance(solanaPubkey);
+    } catch { /* cluster unreachable — identity still returned */ }
+    const babyJubKeys = {};
+    for (const [label, key] of Object.entries(install.buyerKeys ?? {})) {
+      babyJubKeys[label] = { publicKeyX: key.publicKeyX, publicKeyY: key.publicKeyY };
+    }
+    return {
+      solanaPubkey: solanaPubkey.toBase58(),
+      solBalanceLamports,
+      babyJubKeys,
+      defaultBuyerKeyLabel: 'default',
+      cluster,
+    };
+  }
+
+  async function syncNoteLeaves(leaves) {
+    if (!Array.isArray(leaves)) throw new Error('leaves must be an array of leaf strings');
+    const activeDeps = await ensureDeps();
+    const state = readZkState(statePath, { unlock: true, ...custody }) || emptySnapshot();
+    state.noteLeaves = leaves.map((l) => String(l));
+    const onChain = await fetchOnChain(activeDeps);
+    if (onChain) {
+      const reconciled = reconcileState(state, onChain, activeDeps.zkTree);
+      if (!reconciled.ok) throw new Error(`sync failed: ${reconciled.reason}`);
+    }
+    ensureInstallSecrets(state, activeDeps.e2ee);
+    writeZkState(statePath, state, custody);
+    return { ok: true, noteCount: state.noteLeaves.length };
+  }
+
+  return { status, append, revoke, syncNoteLeaves, prepareAppend, prepareRevoke, provePreparedAction, relayAction, relayIntent, prepareSaleListing, submitSaleListing, verifySale, createSaleEscrow, claimSale, saleReceipt, openSale, buyerIdentity, getProvingAssetPaths, statePath, artifactPaths, cluster, rpcUrl };
+}