enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/sale-witness.mjs

@@ -0,0 +1,783 @@
+// sale-witness.mjs — client-side witness builder for
+// circuits/sealed_sale_release.circom — the ZKCP "Sealed Sale" release proof.
+//
+// Binding spec (SaleCircuit-confirmed via hub, 2026-08-23): a Groth16 proof
+// that a Poseidon-CTR ciphertext (committed in a note of the shared note tree)
+// decrypts under a committed data-encryption key (DEK), AND that the same DEK
+// is wrapped to the buyer's BabyJubJub public key in a recipient-bound
+// envelope. Payment releases ONLY against this proof; no key material ever
+// touches the chain.
+//
+// Circuit legs mirrored here EXACTLY:
+//   Leg A — note membership: note = Poseidon3(ownerKey, rho, payloadCommitPos)
+//           ∈ noteRoot (shared note tree, D=20, LSB-first path bits).
+//   Leg B — encryption consistency (Poseidon-CTR stream cipher, field add):
+//           ks_i = Poseidon4(dekLo, dekHi, nonce, i)
+//           c_i  = p_i + ks_i            (mod r; circuit enforces c_i - ks_i = p_i)
+//           payloadCommitPos = fold(acc=0; Poseidon2(acc, p_i))   (PUBLIC)
+//           cipherCommit     = fold(acc=0; Poseidon2(acc, c_i))   (PUBLIC —
+//                              fund-loss fix: the delivered ciphertext is
+//                              bound on-chain, so junk delivery is provable
+//                              before the buyer pays)
+//   Leg C — keyCommit = Poseidon2(dekLo, dekHi); dekLo/dekHi each < 2^128.
+//   Leg D — recipient-bound envelope (BabyJubJub on BN254, circomlib babyjub):
+//           buyer pubkey B on-curve (BabyCheck equation) AND not small-order
+//           (B8 = 8·B via three doublings, constrain B8.x ≠ 0 — the only
+//           on-curve points with x=0 are identity (0,1) and order-2 (0,-1),
+//           so x≠0 ⟺ 8·B ≠ identity ⟺ B not in the 8-torsion).
+//           epk = esk·Base8, shared = esk·B (esk < 2^253, Num2Bits(253))
+//           ss = Poseidon2(shared.x, shared.y)
+//           encDEK_lo = dekLo + Poseidon2(ss, 0)   (mod r)
+//           encDEK_hi = dekHi + Poseidon2(ss, 1)   (mod r)
+//           envelopeCommit = Poseidon4(epk.x, epk.y, encDEK_lo, encDEK_hi) (PUBLIC)
+//   Leg E — saleTermsHash = Poseidon9(DOMAIN_SALE, sellerLo, sellerHi,
+//           buyerPubX, buyerPubY, mintLo, mintHi, price, expirySlot);
+//           seller/mint are Solana pubkeys split LE 128-bit limbs;
+//           price < 2^64; expirySlot < 2^48. The buyer pubkey limbs are
+//           bound into the terms (fund-loss fix, Main 2026-08-23): without
+//           them a seller could claim a buyer's escrow with a receipt
+//           wrapped to a colluder under the SAME terms hash.
+//
+// Public signals (exact order/names): noteRoot, payloadCommitPos,
+//   cipherCommit, keyCommit, saleTermsHash, envelopeCommit.
+// Private signals: ownerKey, rho, notePathElements[20], notePathIndices[20]
+//   (LSB-first), plaintext[32], ciphertext[32], nonce, dekLo, dekHi,
+//   buyerPubX, buyerPubY, esk, sellerLo, sellerHi, mintLo, mintHi, price,
+//   expirySlot.
+//
+// All field elements are emitted as DECIMAL STRINGS (snarkjs JSON convention).
+
+import { randomBytes } from "node:crypto";
+
+import { buildBabyjub } from "circomlibjs";
+import bs58 from "bs58";
+
+ import { FIELD_R, NoteTree, poseidon } from "./zk-tree.mjs";
+
+/** BabyJubJub curve over the BN254 scalar field (circomlibjs). Coordinates
+ *  live in Fr — identical to the circuit's field, so no modulus translation
+ *  is ever needed. */
+const babyJub = await buildBabyjub();
+const JF = babyJub.F;
+
+/** Note tree depth (matches the shared note tree / NoteTree default). */
+export const NOTE_DEPTH = 20;
+
+/**
+ * DOMAIN_SALE = 0x656e69676d615f73616c65 ("enigma_sale" ASCII, 11 bytes,
+ * big-endian) = 122622912455040968075340901. Confirmed with SaleCircuit.
+ */
+export const DOMAIN_SALE = BigInt("0x656e69676d615f73616c65");
+/** Domain separator for the salted plaintext-fold init ("enigma_psalt" ASCII BE). */
+export const DOMAIN_PSALT = BigInt("0x656e69676d615f7073616c74");
+
+/** Public signal names in exact on-chain/circuit order (6 publics, IC 7).
+ *  cipherCommit sits at index 2 (fund-loss fix, Main 2026-08-23): the buyer
+ *  verifies the delivered ciphertext folds to this PUBLIC commitment before
+ *  paying — that check is the junk-delivery defense. */
+export const SALE_PUBLIC_SIGNALS = Object.freeze([
+  "noteRoot",
+  "payloadCommitPos",
+  "cipherCommit",
+  "keyCommit",
+  "saleTermsHash",
+  "envelopeCommit",
+]);
+
+/** Fixed plaintext/ciphertext chunk count (circuit shape is fixed at n=32). */
+export const CHUNK_COUNT = 32;
+/** Bytes per chunk: 31-byte little-endian limbs (< 2^248 < r, always canonical). */
+export const CHUNK_BYTES = 31;
+/** Maximum plaintext size: 32 chunks × 31 bytes. */
+export const PAYLOAD_CAPACITY = CHUNK_COUNT * CHUNK_BYTES; // 992
+
+const R = FIELD_R; // BN254 scalar field modulus
+const TWO_64 = 1n << 64n;
+const TWO_128 = 1n << 128n;
+const TWO_48 = 1n << 48n;
+const TWO_248 = 1n << 248n;
+const TWO_253 = 1n << 253n;
+
+const SUB_ORDER = BigInt(babyJub.subOrder.toString()); // prime subgroup order
+
+// ---------------------------------------------------------------------------
+// Byte/limb helpers
+// ---------------------------------------------------------------------------
+
+/** Little-endian bytes → bigint. */
+export function bytesToBigIntLE(bytes) {
+  let v = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) v = (v << 8n) | BigInt(bytes[i]);
+  return v;
+}
+
+/** bigint → exactly `len` little-endian bytes. */
+export function bigIntToBytesLE(value, len) {
+  let v = BigInt(value);
+  if (v < 0n) throw new RangeError("bigIntToBytesLE: negative value");
+  const out = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    out[i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  if (v !== 0n) throw new RangeError(`bigIntToBytesLE: value does not fit in ${len} bytes`);
+  return out;
+}
+
+/**
+ * Plaintext bytes → exactly CHUNK_COUNT field chunks: consecutive 31-byte
+ * little-endian limbs, zero-padded. Every chunk < 2^248 < r (canonical).
+ * @param {Uint8Array} bytes at most PAYLOAD_CAPACITY (992) bytes
+ * @returns {bigint[]} length-CHUNK_COUNT array
+ */
+export function bytesToChunks(bytes) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError("bytesToChunks: expected a Uint8Array");
+  }
+  if (bytes.length > PAYLOAD_CAPACITY) {
+    throw new RangeError(
+      `payload too large: ${bytes.length} bytes > capacity ${PAYLOAD_CAPACITY}`,
+    );
+  }
+  const chunks = new Array(CHUNK_COUNT);
+  for (let i = 0; i < CHUNK_COUNT; i++) {
+    chunks[i] = bytesToBigIntLE(bytes.subarray(i * CHUNK_BYTES, (i + 1) * CHUNK_BYTES));
+  }
+  return chunks;
+}
+/** Alias kept for the spec wording (chunksFromBytes ≡ bytesToChunks). */
+export const chunksFromBytes = bytesToChunks;
+
+/**
+ * Field chunks → bytes (inverse of bytesToChunks). Because chunks are
+ * zero-padded, the ORIGINAL byte length must be supplied to round-trip
+ * plaintexts with trailing 0x00 bytes; defaults to the full capacity.
+ * @param {bigint[]|string[]|number[]} chunks exactly CHUNK_COUNT limbs, each < 2^248
+ * @param {number} [byteLength] bytes to emit (default PAYLOAD_CAPACITY)
+ * @returns {Uint8Array}
+ */
+export function chunksToBytes(chunks, byteLength = PAYLOAD_CAPACITY) {
+  if (!Array.isArray(chunks) || chunks.length !== CHUNK_COUNT) {
+    throw new TypeError(`chunksToBytes: expected ${CHUNK_COUNT} chunks`);
+  }
+  if (!Number.isInteger(byteLength) || byteLength < 0 || byteLength > PAYLOAD_CAPACITY) {
+    throw new RangeError(`chunksToBytes: byteLength ${byteLength} out of [0, ${PAYLOAD_CAPACITY}]`);
+  }
+  const out = new Uint8Array(PAYLOAD_CAPACITY);
+  for (let i = 0; i < CHUNK_COUNT; i++) {
+    const c = BigInt(chunks[i]);
+    if (c < 0n || c >= TWO_248) {
+      throw new RangeError(`chunksToBytes: chunk ${i} outside [0, 2^248)`);
+    }
+    out.set(bigIntToBytesLE(c, CHUNK_BYTES), i * CHUNK_BYTES);
+  }
+  return out.subarray(0, byteLength);
+}
+/** Alias kept for the spec wording (bytesFromChunks ≡ chunksToBytes). */
+export const bytesFromChunks = chunksToBytes;
+
+// ---------------------------------------------------------------------------
+// BabyJubJub helpers (circomlib babyjub — BabyJubJub on BN254; the curve base
+// field IS the circuit scalar field, so coordinates are circuit-native).
+// ---------------------------------------------------------------------------
+
+/** Internal: normalize a point given as {x,y} (bigint|string|number) or [x,y]. */
+function toPoint(p, what = "point") {
+  let x;
+  let y;
+  if (Array.isArray(p)) {
+    [x, y] = p;
+  } else if (p && typeof p === "object") {
+    ({ x, y } = p);
+  }
+  if (x === undefined || y === undefined) {
+    throw new TypeError(`${what}: expected {x, y} or [x, y]`);
+  }
+  return [BigInt(x), BigInt(y)];
+}
+
+/**
+ * Encode a BabyJub point as decimal-string coordinates.
+ * @param {bigint[]|{x:bigint,y:bigint}} p
+ * @returns {{x: string, y: string}}
+ */
+export function encodePoint(p) {
+  const [x, y] = Array.isArray(p) ? p.map((c) => JF.toObject(c)) : toPoint(p);
+  return { x: BigInt(x).toString(10), y: BigInt(y).toString(10) };
+}
+
+/**
+ * Decode decimal-string coordinates → [x, y] bigints. Does NOT validate
+ * curve membership (use validateBuyerPublicKey for that).
+ */
+export function decodePoint(p) {
+  return toPoint(p);
+}
+
+/**
+ * Buyer public-key validation matching the circuit EXACTLY:
+ *   1. coordinates canonical (< r — circuit signals are field elements);
+ *   2. on-curve via the BabyJubJub equation (circomlib BabyCheck:
+ *      a·x² + y² = 1 + d·x²·y² with a=168700, d=168696);
+ *   3. not small-order: B8 = 8·B must have B8.x ≠ 0. The only on-curve
+ *      points with x = 0 are identity (0,1) and the order-2 point (0,−1);
+ *      since the curve has no order-16 points, 8·B ∈ {(0,1),(0,−1)} iff B
+ *      lies in the 8-torsion — so x ≠ 0 ⟺ B is not small-order.
+ * Throws on any failure; returns the point as [x, y] bigints on success.
+ */
+export function validateBuyerPublicKey(pub, what = "buyerPub") {
+  const [x, y] = toPoint(pub, what);
+  if (x < 0n || x >= R || y < 0n || y >= R) {
+    throw new RangeError(`${what}: coordinates must be canonical field elements (< r)`);
+  }
+  const P = [JF.e(x), JF.e(y)];
+  if (!babyJub.inCurve(P)) {
+    throw new Error(`${what}: point is not on the BabyJubJub curve`);
+  }
+  const P8 = babyJub.mulPointEscalar(P, 8n);
+  if (JF.isZero(P8[0])) {
+    throw new Error(`${what}: small-order point rejected (8·B has x = 0)`);
+  }
+  return [x, y];
+}
+
+/**
+ * Generate a buyer BabyJubJub key pair.
+ * @returns {{ secret: bigint, publicKey: {x: bigint, y: bigint} }}
+ *   secret ∈ [1, subOrder); publicKey = secret·Base8.
+ */
+export function generateBuyerKeyPair() {
+  let secret = 0n;
+  while (secret === 0n) {
+    secret = bytesToBigIntLE(randomBytes(32)) % SUB_ORDER;
+  }
+  const P = babyJub.mulPointEscalar(babyJub.Base8, secret);
+  return { secret, publicKey: { x: JF.toObject(P[0]), y: JF.toObject(P[1]) } };
+}
+
+/**
+ * Buyer-side ECDH: shared = buyerSecret · epk; ss = Poseidon2(shared.x, shared.y).
+ * Validates epk with the same rules the circuit applies to the buyer key.
+ * @returns {{ ss: bigint, shared: {x: bigint, y: bigint} }}
+ */
+export function deriveSharedSecret(buyerSecret, epk) {
+  const [x, y] = validateBuyerPublicKey(epk, "epk");
+  const P = babyJub.mulPointEscalar([JF.e(x), JF.e(y)], BigInt(buyerSecret));
+  const shared = { x: JF.toObject(P[0]), y: JF.toObject(P[1]) };
+  return { ss: poseidon([shared.x, shared.y]), shared };
+}
+
+// ---------------------------------------------------------------------------
+// Poseidon-CTR stream cipher (field-add; mirrors circuit Leg B)
+// ---------------------------------------------------------------------------
+
+/** Keystream chunk: ks_i = Poseidon4(dekLo, dekHi, nonce, i). */
+export function keystreamChunk(dekLo, dekHi, nonce, i) {
+  return poseidon([BigInt(dekLo), BigInt(dekHi), BigInt(nonce), BigInt(i)]);
+}
+
+/**
+ * Encrypt plaintext chunks: c_i = p_i + Poseidon4(dekLo, dekHi, nonce, i) (mod r).
+ * @param {bigint[]|string[]|number[]} plaintextChunks CHUNK_COUNT limbs
+ * @returns {bigint[]} CHUNK_COUNT ciphertext chunks
+ */
+export function encryptPayload(plaintextChunks, dekLo, dekHi, nonce) {
+  if (!Array.isArray(plaintextChunks) || plaintextChunks.length !== CHUNK_COUNT) {
+    throw new TypeError(`encryptPayload: expected ${CHUNK_COUNT} plaintext chunks`);
+  }
+  const out = new Array(CHUNK_COUNT);
+  for (let i = 0; i < CHUNK_COUNT; i++) {
+    out[i] = (BigInt(plaintextChunks[i]) + keystreamChunk(dekLo, dekHi, nonce, i)) % R;
+  }
+  return out;
+}
+
+/**
+ * Decrypt ciphertext chunks: p_i = c_i − Poseidon4(dekLo, dekHi, nonce, i) (mod r).
+ * @param {bigint[]|string[]|number[]} ciphertextChunks CHUNK_COUNT limbs
+ * @returns {bigint[]} CHUNK_COUNT plaintext chunks
+ */
+export function decryptPayload(ciphertextChunks, dekLo, dekHi, nonce) {
+  if (!Array.isArray(ciphertextChunks) || ciphertextChunks.length !== CHUNK_COUNT) {
+    throw new TypeError(`decryptPayload: expected ${CHUNK_COUNT} ciphertext chunks`);
+  }
+  const out = new Array(CHUNK_COUNT);
+  for (let i = 0; i < CHUNK_COUNT; i++) {
+    out[i] = (BigInt(ciphertextChunks[i]) - keystreamChunk(dekLo, dekHi, nonce, i)) % R;
+    if (out[i] < 0n) out[i] += R;
+  }
+  return out;
+}
+
+/**
+ * Chunk-commitment fold: acc_0 = 0; acc_{i+1} = Poseidon2(acc_i, chunk_i).
+ * Used for BOTH payloadCommitPos (plaintext fold, public) and cipherCommit
+ * (ciphertext fold, private).
+ */
+/** DEK-blinded, domain-separated plaintext fold (mirrors circuit Leg B init).
+ *  payloadCommitPos = fold(Poseidon2, Poseidon3(DOMAIN_PSALT, dekLo, dekHi), chunks).
+ *  The seed is secret until the paid claim reveal, so neither observers nor the
+ *  pre-payment buyer can dictionary-test the public digest. */
+export function foldChunksBlind(chunks, dekLo, dekHi) {
+  let acc = poseidon([DOMAIN_PSALT, BigInt(dekLo), BigInt(dekHi)]);
+  for (const c of chunks) acc = poseidon([acc, BigInt(c)]);
+  return acc;
+}
+
+export function foldChunks(chunks) {
+  if (!Array.isArray(chunks) || chunks.length !== CHUNK_COUNT) {
+    throw new TypeError(`foldChunks: expected ${CHUNK_COUNT} chunks`);
+  }
+  let acc = 0n;
+  for (const c of chunks) acc = poseidon([acc, BigInt(c)]);
+  return acc;
+}
+
+// ---------------------------------------------------------------------------
+// Poseidon commitments (mirror the circuit exactly)
+// ---------------------------------------------------------------------------
+
+/** keyCommit = Poseidon2(dekLo, dekHi). */
+export function computeKeyCommit(dekLo, dekHi) {
+  return poseidon([BigInt(dekLo), BigInt(dekHi)]);
+}
+
+/** Sale note leaf = Poseidon3(ownerKey, rho, payloadCommitPos) — insert into NoteTree. */
+export function computeSaleNote(ownerKey, rho, payloadCommitPos) {
+  return poseidon([BigInt(ownerKey), BigInt(rho), BigInt(payloadCommitPos)]);
+}
+
+/** base58 → exactly `len` bytes (Solana pubkey / fixed-size buffer). */
+function decodeBase58Fixed(b58, len, what) {
+  if (typeof b58 !== "string" || b58.length === 0) {
+    throw new TypeError(`${what}: expected a non-empty base58 string`);
+  }
+  const bytes = bs58.decode(b58);
+  if (bytes.length !== len) {
+    throw new Error(`${what}: expected ${len} bytes, got ${bytes.length}`);
+  }
+  return bytes;
+}
+
+/**
+ * saleTermsHash = Poseidon9(DOMAIN_SALE, sellerLo, sellerHi, buyerPubX,
+ * buyerPubY, mintLo, mintHi, price, expirySlot). seller/mint: base58 32-byte
+ * Solana pubkeys split into little-endian 128-bit limbs; buyerPub: BabyJub
+ * public key (validated exactly as the circuit validates it); price: u64
+ * lamports; expirySlot < 2^48.
+ * @returns {{ saleTermsHash: bigint, sellerLo: bigint, sellerHi: bigint,
+ *   buyerPubX: bigint, buyerPubY: bigint, mintLo: bigint, mintHi: bigint,
+ *   price: bigint, expirySlot: bigint }}
+ */
+export function computeSaleTermsHash({ sellerPubkey, buyerPub, mint, priceLamports, expirySlot, payloadLen }) {
+  const sBytes = decodeBase58Fixed(sellerPubkey, 32, "sellerPubkey");
+  const mBytes = decodeBase58Fixed(mint, 32, "mint");
+  const [buyerPubX, buyerPubY] = validateBuyerPublicKey(buyerPub);
+  const price = BigInt(priceLamports);
+  const expiry = BigInt(expirySlot);
+  if (price < 0n || price >= TWO_64) {
+    throw new RangeError(`priceLamports ${price} out of u64 range`);
+  }
+  if (expiry < 0n || expiry >= TWO_48) {
+    throw new RangeError(`expirySlot ${expiry} out of 48-bit range`);
+  }
+  if (payloadLen === undefined || payloadLen === null) {
+    throw new TypeError("computeSaleTermsHash: payloadLen required (bound into the terms)");
+  }
+  const length = BigInt(payloadLen);
+  if (length < 1n || length > BigInt(PAYLOAD_CAPACITY)) {
+    throw new RangeError(`payloadLen ${length} out of range 1..${PAYLOAD_CAPACITY}`);
+  }
+  const limbs = {
+    sellerLo: bytesToBigIntLE(sBytes.subarray(0, 16)),
+    sellerHi: bytesToBigIntLE(sBytes.subarray(16, 32)),
+    buyerPubX,
+    buyerPubY,
+    mintLo: bytesToBigIntLE(mBytes.subarray(0, 16)),
+    mintHi: bytesToBigIntLE(mBytes.subarray(16, 32)),
+    price,
+    expirySlot: expiry,
+    payloadLen: length,
+  };
+  const saleTermsHash = poseidon([
+    DOMAIN_SALE,
+    limbs.sellerLo,
+    limbs.sellerHi,
+    limbs.buyerPubX,
+    limbs.buyerPubY,
+    limbs.mintLo,
+    limbs.mintHi,
+    limbs.price,
+    limbs.expirySlot,
+    limbs.payloadLen,
+  ]);
+  return { saleTermsHash, ...limbs };
+}
+
+// ---------------------------------------------------------------------------
+// Envelope (Leg D) — seller-side wrap, buyer-side unwrap
+// ---------------------------------------------------------------------------
+
+/** Field add mod r. */
+const fadd = (a, b) => (BigInt(a) + BigInt(b)) % R;
+/** Field sub mod r. */
+const fsub = (a, b) => {
+  const v = (BigInt(a) - BigInt(b)) % R;
+  return v < 0n ? v + R : v;
+};
+
+/**
+ * Seller-side DEK wrap to the buyer's public key.
+ * @returns {{ epk: {x: bigint, y: bigint}, encDEK_lo: bigint, encDEK_hi: bigint,
+ *   envelopeCommit: bigint, ss: bigint }}
+ */
+function wrapDek({ dekLo, dekHi, nonce, buyerPub, esk }) {
+  const [bx, by] = validateBuyerPublicKey(buyerPub);
+  if (esk < 0n || esk >= TWO_253) {
+    throw new RangeError(`esk out of range: circuit constrains Num2Bits(253)`);
+  }
+  if (esk % SUB_ORDER === 0n) {
+    // esk = 0 or esk = subOrder → epk = identity → shared secret publicly
+    // derivable → envelope opens for ANYONE. The circuit rejects this too
+    // (epk.x ≠ 0), fail here first with a clear reason.
+    throw new RangeError('esk must not be 0 mod subOrder (epk would be the identity point)');
+  }
+  if (nonce === undefined || nonce === null) {
+    throw new TypeError('wrapDek: nonce required — it is bound into envelopeCommit');
+  }
+  const B = [JF.e(bx), JF.e(by)];
+  const epkP = babyJub.mulPointEscalar(babyJub.Base8, esk);
+  const sharedP = babyJub.mulPointEscalar(B, esk);
+  const shared = { x: JF.toObject(sharedP[0]), y: JF.toObject(sharedP[1]) };
+  const ss = poseidon([shared.x, shared.y]);
+  const encDEK_lo = fadd(dekLo, poseidon([ss, 0n]));
+  const encDEK_hi = fadd(dekHi, poseidon([ss, 1n]));
+  const epk = { x: JF.toObject(epkP[0]), y: JF.toObject(epkP[1]) };
+  // Poseidon5 binds the CTR nonce: the claim-time reveal is the only (epk,
+  // encDEK, nonce) triple the proof could have committed to.
+  const envelopeCommit = poseidon([epk.x, epk.y, encDEK_lo, encDEK_hi, BigInt(nonce)]);
+  return { epk, encDEK_lo, encDEK_hi, envelopeCommit, ss };
+}
+
+/**
+ * Buyer-side DEK unwrap: shared = buyerSecret·epk; ss = Poseidon2(shared.x,
+ * shared.y); dekLo = encDEK_lo − Poseidon2(ss, 0); dekHi = encDEK_hi −
+ * Poseidon2(ss, 1) (all mod r).
+ * @param {bigint|string} buyerSecret buyer's BabyJub secret scalar
+ * @param {{x,y}|[x,y]} epk ephemeral public key (validated like the circuit
+ *   validates the buyer key: on-curve, not small-order)
+ * @returns {{ dekLo: bigint, dekHi: bigint, ss: bigint }}
+ */
+export function openSaleEnvelope(buyerSecret, epk, encDEK_lo, encDEK_hi) {
+  const { ss } = deriveSharedSecret(buyerSecret, epk);
+  const dekLo = fsub(encDEK_lo, poseidon([ss, 0n]));
+  const dekHi = fsub(encDEK_hi, poseidon([ss, 1n]));
+  return { dekLo, dekHi, ss };
+}
+
+/**
+ * Full buyer-side open. Verifies, IN ORDER:
+ *   1. JUNK-DELIVERY DEFENSE: the delivered ciphertext chunks fold to the
+ *      PUBLIC cipherCommit (public input index 2). This is the check the
+ *      buyer runs against the on-chain listing BEFORE paying — a seller who
+ *      delivers bytes that do not fold to the committed cipherCommit is
+ *      caught here, before any decryption.
+ *   2. Envelope unwrap (ECDH) → DEK.
+ *   3. Decrypt → assert the plaintext fold equals the listed
+ *      payloadCommitPos. A third party with the wrong buyer secret derives
+ *      the wrong DEK → wrong plaintext → this assert fails.
+ *
+ * @param {object} args
+ * @param {bigint|string} args.buyerSecret
+ * @param {{x,y}|[x,y]} args.epk
+ * @param {bigint|string} args.encDEK_lo
+ * @param {bigint|string} args.encDEK_hi
+ * @param {bigint[]|string[]} args.ciphertext CHUNK_COUNT delivered ciphertext chunks
+ * @param {bigint|string} args.cipherCommit PUBLIC ciphertext fold (on-chain listing)
+ * @param {bigint|string} args.nonce Poseidon-CTR nonce
+ * @param {bigint|string} args.payloadCommitPos listed plaintext commitment
+ * @returns {{ dekLo: bigint, dekHi: bigint, plaintextChunks: bigint[],
+ *   cipherCommit: bigint, payloadCommitPos: bigint }}
+ */
+export function openAndVerifySale(args) {
+  if (args.cipherCommit === undefined || args.cipherCommit === null) {
+    throw new TypeError("openAndVerifySale: missing cipherCommit (public ciphertext fold)");
+  }
+  const cipherCommit = foldChunks(args.ciphertext);
+  if (cipherCommit !== BigInt(args.cipherCommit)) {
+    throw new Error(
+      "junk delivery: delivered ciphertext fold != public cipherCommit — do not pay",
+    );
+  }
+  const { dekLo, dekHi } = openSaleEnvelope(
+    args.buyerSecret,
+    args.epk,
+    args.encDEK_lo,
+    args.encDEK_hi,
+  );
+  const plaintextChunks = decryptPayload(args.ciphertext, dekLo, dekHi, args.nonce);
+  const digest = foldChunksBlind(plaintextChunks, dekLo, dekHi);
+  if (digest !== BigInt(args.payloadCommitPos)) {
+    throw new Error(
+      "sale payload digest mismatch: decrypted blinded fold != listed payloadCommitPos",
+    );
+  }
+  return { dekLo, dekHi, plaintextChunks, cipherCommit, payloadCommitPos: digest };
+}
+
+// ---------------------------------------------------------------------------
+// Witness builder
+// ---------------------------------------------------------------------------
+
+/** Recursively convert bigints → decimal strings for snarkjs input JSON. */
+function toDec(x) {
+  if (typeof x === "bigint") return x.toString(10);
+  if (Array.isArray(x)) return x.map(toDec);
+  if (typeof x === "number") return String(x);
+  if (typeof x === "object" && x !== null) {
+    return Object.fromEntries(Object.entries(x).map(([k, v]) => [k, toDec(v)]));
+  }
+  return x;
+}
+
+function need(value, name) {
+  if (value === undefined || value === null) {
+    throw new TypeError(`buildSaleWitness: missing ${name}`);
+  }
+  return BigInt(value);
+}
+
+/**
+ * Build the snarkjs input for one sealed-sale release proof.
+ *
+ * @param {object} args
+ * @param {NoteTree} args.noteTree        shared note tree at the current on-chain note_root
+ * @param {number} args.noteIndex         index of the sale note in noteTree
+ * @param {bigint|number|string} args.ownerKey  note opening
+ * @param {bigint|number|string} args.rho       note opening
+ * @param {Uint8Array} args.plaintextBytes  E2EE memory plaintext (≤ 992 bytes)
+ * @param {bigint|number|string} args.dekLo   DEK low limb (< 2^128)
+ * @param {bigint|number|string} args.dekHi   DEK high limb (< 2^128)
+ * @param {bigint|number|string} args.nonce   Poseidon-CTR nonce (field element)
+ * @param {{x,y}|[x,y]} args.buyerPub        buyer BabyJub public key (decimal strings or bigints)
+ * @param {string} args.sellerPubkey          seller base58 32B pubkey
+ * @param {string} args.mint                  payment mint, base58 32B pubkey
+ * @param {bigint|number|string} args.priceLamports  price (u64)
+ * @param {bigint|number|string} args.expirySlot     escrow expiry slot (< 2^48)
+ * @param {bigint|number|string} [args.esk]   ephemeral secret (< 2^253); random if omitted
+ * @returns {{
+ *   input: object,            // snarkjs input JSON (decimal strings), exact circuit signal names
+ *   note: bigint, noteRoot: bigint,
+ *   plaintextChunks: bigint[], ciphertextChunks: bigint[],
+ *   payloadCommitPos: bigint, cipherCommit: bigint, keyCommit: bigint,
+ *   saleTermsHash: bigint, envelopeCommit: bigint,
+ *   epk: {x: bigint, y: bigint}, encDEK_lo: bigint, encDEK_hi: bigint,
+ *   esk: bigint,
+ *   sellerLo: bigint, sellerHi: bigint, buyerPubX: bigint, buyerPubY: bigint,
+ *   mintLo: bigint, mintHi: bigint, price: bigint, expirySlot: bigint,
+ * }}
+ */
+export function buildSaleWitness(args) {
+  const { noteTree, noteIndex } = args;
+  if (!(noteTree instanceof NoteTree)) throw new TypeError("noteTree must be a NoteTree");
+  if (!Number.isInteger(noteIndex) || noteIndex < 0 || noteIndex >= noteTree.nextIndex) {
+    throw new RangeError(`noteIndex ${noteIndex} not present in note tree`);
+  }
+
+  const ownerKey = need(args.ownerKey, "ownerKey");
+  const rho = need(args.rho, "rho");
+  const dekLo = need(args.dekLo, "dekLo");
+  const dekHi = need(args.dekHi, "dekHi");
+  const nonce = need(args.nonce, "nonce");
+
+  if (dekLo < 0n || dekLo >= TWO_128 || dekHi < 0n || dekHi >= TWO_128) {
+    throw new RangeError("dekLo/dekHi must each be < 2^128 (circuit Num2Bits(128))");
+  }
+  if (nonce < 0n || nonce >= R) throw new RangeError("nonce must be a field element");
+  if (ownerKey < 0n || ownerKey >= R || rho < 0n || rho >= R) {
+    throw new RangeError("ownerKey/rho must be field elements");
+  }
+  if (args.plaintextBytes === undefined || args.plaintextBytes === null) {
+    throw new TypeError("buildSaleWitness: missing plaintextBytes");
+  }
+  const payloadLen = BigInt(args.plaintextBytes.length);
+  if (payloadLen < 1n || payloadLen > BigInt(PAYLOAD_CAPACITY)) {
+    throw new RangeError(
+      `buildSaleWitness: payload length ${payloadLen} out of range 1..${PAYLOAD_CAPACITY}`,
+    );
+  }
+  if (args.buyerPub === undefined || args.buyerPub === null) {
+    throw new TypeError("buildSaleWitness: missing buyerPub");
+  }
+
+  // ---- Leg B: Poseidon-CTR encryption + folds ----
+  // The plaintext fold is blinded by a DEK-derived seed — no separate salt.
+  const plaintextChunks = bytesToChunks(args.plaintextBytes);
+  const ciphertextChunks = encryptPayload(plaintextChunks, dekLo, dekHi, nonce);
+  const payloadCommitPos = foldChunksBlind(plaintextChunks, dekLo, dekHi);
+  const cipherCommit = foldChunks(ciphertextChunks);
+
+  // ---- Leg C: key commitment ----
+  const keyCommit = computeKeyCommit(dekLo, dekHi);
+
+  // ---- Leg A: note membership ----
+  const note = computeSaleNote(ownerKey, rho, payloadCommitPos);
+  if (noteTree.leaves[noteIndex] !== note) {
+    throw new Error("note opening does not match the leaf at noteIndex");
+  }
+  const noteProof = noteTree.getProof(noteIndex);
+  const noteRoot = noteTree.root();
+
+  // ---- Leg D: recipient-bound envelope ----
+  let esk;
+  if (args.esk !== undefined && args.esk !== null) {
+    esk = BigInt(args.esk);
+  } else {
+    do {
+      esk = bytesToBigIntLE(randomBytes(32)) % TWO_253;
+    } while (esk % SUB_ORDER === 0n);
+  }
+  const [buyerPubX, buyerPubY] = validateBuyerPublicKey(args.buyerPub);
+  const { epk, encDEK_lo, encDEK_hi, envelopeCommit } = wrapDek({
+    dekLo,
+    dekHi,
+    nonce,
+    buyerPub: [buyerPubX, buyerPubY],
+    esk,
+  });
+
+  // ---- Leg E: sale terms (buyer- and length-bound: Poseidon10 over seller,
+  // buyer key, mint, price, expiry, payloadLen) ----
+  const terms = computeSaleTermsHash({
+    sellerPubkey: args.sellerPubkey,
+    buyerPub: [buyerPubX, buyerPubY],
+    mint: args.mint,
+    priceLamports: args.priceLamports,
+    expirySlot: args.expirySlot,
+    payloadLen,
+  });
+
+  const input = toDec({
+    // public (exact contract order/names)
+    noteRoot,
+    payloadCommitPos,
+    cipherCommit,
+    keyCommit,
+    saleTermsHash: terms.saleTermsHash,
+    envelopeCommit,
+    // private
+    ownerKey,
+    rho,
+    notePathElements: noteProof.pathElements,
+    notePathIndices: noteProof.pathIndices,
+    plaintext: plaintextChunks,
+    ciphertext: ciphertextChunks,
+    nonce,
+    dekLo,
+    dekHi,
+    buyerPubX,
+    buyerPubY,
+    esk,
+    sellerLo: terms.sellerLo,
+    sellerHi: terms.sellerHi,
+    mintLo: terms.mintLo,
+    mintHi: terms.mintHi,
+    price: terms.price,
+    expirySlot: terms.expirySlot,
+    payloadLen,
+  });
+
+  return {
+    input,
+    note,
+    noteRoot,
+    payloadLen,
+    plaintextChunks,
+    ciphertextChunks,
+    payloadCommitPos,
+    cipherCommit,
+    keyCommit,
+    saleTermsHash: terms.saleTermsHash,
+    envelopeCommit,
+    epk,
+    encDEK_lo,
+    encDEK_hi,
+    esk,
+    sellerLo: terms.sellerLo,
+    sellerHi: terms.sellerHi,
+    buyerPubX: terms.buyerPubX,
+    buyerPubY: terms.buyerPubY,
+    mintLo: terms.mintLo,
+    mintHi: terms.mintHi,
+    price: terms.price,
+    expirySlot: terms.expirySlot,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic demo fixture (proof-of-life / setup-sale.mjs)
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic end-to-end sale fixture: a note tree holding the sale note,
+ * a fixed buyer key pair, a fixed DEK/esk, and the full witness input.
+ * @returns {Promise<{
+ *   input: object,              // complete circom witness input (decimal strings)
+ *   expectedPublic: string[],   // the 5 public signals, SALE_PUBLIC_SIGNALS order
+ *   artifacts: object,          // full buildSaleWitness result (epk, encDEK_*, ...)
+ *   buyerSecret: bigint,        // demo buyer secret (envelope opening)
+ *   plaintextBytes: Uint8Array, // demo plaintext
+ * }>}
+ */
+export async function buildSaleDemoFixture() {
+  const buyer = generateBuyerKeyPairDeterministic();
+  const plaintextBytes = new TextEncoder().encode(
+    "Enigma sealed-sale demo memory: the cortex remembers what the chain never sees.",
+  );
+  const dekLo = 0x0de0b6b3a7640000f1f2f3f4f5f6f7f8n; // < 2^128
+  const dekHi = 0x00112233445566778899aabbccddeeffn; // < 2^128
+  const nonce = 424242424242n;
+  const esk = 0x1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403n; // < 2^253
+  const ownerKey = 11111111111111111111111111111111111111111111111111n;
+  const rho = 22222222222222222222222222222222222222222222222222n;
+
+  // Pre-compute the note so the tree holds the exact leaf the witness opens.
+  const plaintextChunks = bytesToChunks(plaintextBytes);
+  const payloadCommitPos = foldChunksBlind(plaintextChunks, dekLo, dekHi);
+  const noteTree = new NoteTree();
+  noteTree.insert(555n); // filler note at index 0
+  noteTree.insert(computeSaleNote(ownerKey, rho, payloadCommitPos)); // index 1
+
+  const result = buildSaleWitness({
+    noteTree,
+    noteIndex: 1,
+    ownerKey,
+    rho,
+    plaintextBytes,
+    dekLo,
+    dekHi,
+    nonce,
+    buyerPub: buyer.publicKey,
+    sellerPubkey: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint addr as seller
+    mint: "So11111111111111111111111111111111111111112", // wSOL mint
+    priceLamports: 2_000_000_000n, // 2 SOL
+    expirySlot: 300_000_000n,
+    esk,
+  });
+
+  const expectedPublic = SALE_PUBLIC_SIGNALS.map((name) => result.input[name]);
+  return {
+    input: result.input,
+    expectedPublic,
+    artifacts: result,
+    buyerSecret: buyer.secret,
+    plaintextBytes,
+  };
+}
+
+/** Deterministic buyer key pair for the demo fixture (fixed secret). */
+function generateBuyerKeyPairDeterministic() {
+  const secret = 0x0a0b0c0d0e0f101112131415161718191a1b1c1d1e1f2021222324252n % SUB_ORDER;
+  const P = babyJub.mulPointEscalar(babyJub.Base8, secret);
+  return { secret, publicKey: { x: JF.toObject(P[0]), y: JF.toObject(P[1]) } };
+}