enigma-memory 0.1.18 → 0.1.22

package/cortex-v3/zk/zk-codec.test.mjs

@@ -0,0 +1,293 @@
+/**
+ * zk-codec.test.mjs — known-answer tests + integration round-trip for the
+ * Enigma action-transition snarkjs→raw-BE codec.
+ *
+ * KAT vectors:
+ *  - G1 generator (1, 2): externally known BN254 generator.
+ *  - G2 generator: expected "c1c0" hex is the canonical EIP-196/EIP-197
+ *    alt_bn128 encoding (im, re) — externally sourced.
+ *  - Non-trivial G1 pair: expected hex computed independently (Python
+ *    int.to_bytes(32, 'big')).
+ *
+ * Run: node --test cortex-v3/zk/zk-codec.test.mjs
+ * Integration test waits up to ZK_CODEC_INTEGRATION_WAIT_MS (default 20s) for
+ * circuits/build/verification_key.json (produced by zk/setup.mjs), then skips
+ * gracefully if absent.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  FR_MODULUS,
+  FQ_MODULUS,
+  EXPECTED_IC_LENGTH,
+  NUM_PUBLIC_INPUTS,
+  vkFromSnarkjs,
+  proofFromSnarkjs,
+  publicInputsFromSnarkjs,
+  g1ToBytes,
+  g2ToBytes,
+  frToBytes32BE,
+} from "./zk-codec.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BUILD_DIR = path.resolve(HERE, "..", "circuits", "build");
+const VK_JSON_PATH = path.join(BUILD_DIR, "verification_key.json");
+const VK_BYTES_PATH = path.join(BUILD_DIR, "vk_bytes.json");
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------------------
+// KAT vectors
+// ---------------------------------------------------------------------------
+
+// bn254 G1 generator.
+const G1_GEN_DECIMAL = ["1", "2"];
+const G1_GEN_HEX =
+  "0000000000000000000000000000000000000000000000000000000000000001" +
+  "0000000000000000000000000000000000000000000000000000000000000002";
+
+// Non-trivial G1 pair (alpha of a Groth16 vk); expected hex computed
+// independently via Python int.to_bytes(32, "big").
+const G1_ALPHA_DECIMAL = [
+  "20491192805390485299153009773594534940189261866228447918068658471970481763042",
+  "9383485363053290200918347156157836566562967994039712273449902621266178545958",
+];
+const G1_ALPHA_HEX =
+  "2d4d9aa7e302d9df41749d5507949d05dbea33fbb16c643b22f599a2be6df2e2" +
+  "14bedd503c37ceb061d8ec60209fe345ce89830a19230301f076caff004d1926";
+
+// bn254 G2 generator in snarkjs JSON limb order [c0, c1] = [re, im].
+const G2_GEN_SNARKJS = [
+  [
+    "10857046999023057135944570762232829481370756359578518086990519993285655852781",
+    "11559732032986387107991004021392285783925812861821192530917403151452391805634",
+  ],
+  [
+    "8495653923123431417604973247489272438418190587263600148770280649306958101930",
+    "4082367875863433681332203403145435568316851327593401208105741076214120093531",
+  ],
+  ["1", "0"],
+];
+// Canonical EIP-196 alt_bn128 encoding of the G2 generator: (im, re) per coord.
+const G2_GEN_C1C0_HEX =
+  "198e9393920d483a7260bfb731fb5d25f1aa493335a9e71297e485b7aef312c2" +
+  "1800deef121f1e76426a00665e5c4479674322d4f75edadd46debd5cd992f6ed" +
+  "090689d0585ff075ec9e99ad690c3395bc4b313370b38ef355acdadcd122975b" +
+  "12c85ea5db8c6deb4aab71808dcb408fe3d1e7690c43d37b4ce6cc0166fa7daa";
+// Raw snarkjs limb order (re, im) per coord — the "c0c1" option.
+const G2_GEN_C0C1_HEX =
+  "1800deef121f1e76426a00665e5c4479674322d4f75edadd46debd5cd992f6ed" +
+  "198e9393920d483a7260bfb731fb5d25f1aa493335a9e71297e485b7aef312c2" +
+  "12c85ea5db8c6deb4aab71808dcb408fe3d1e7690c43d37b4ce6cc0166fa7daa" +
+  "090689d0585ff075ec9e99ad690c3395bc4b313370b38ef355acdadcd122975b";
+
+// Scalar field modulus r and neighbours.
+const R_DECIMAL = FR_MODULUS.toString(10);
+const R_MINUS_1_HEX =
+  "30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000000";
+
+// ---------------------------------------------------------------------------
+// KAT: G1 decimal pair → exact 64B hex
+// ---------------------------------------------------------------------------
+
+test("KAT: G1 generator decimal pair → exact 64B BE hex", () => {
+  const out = g1ToBytes(G1_GEN_DECIMAL);
+  assert.equal(out.length, 64);
+  assert.equal(out.toString("hex"), G1_GEN_HEX);
+});
+
+test("KAT: non-trivial G1 decimal pair → exact 64B BE hex", () => {
+  const out = g1ToBytes(G1_ALPHA_DECIMAL);
+  assert.equal(out.length, 64);
+  assert.equal(out.toString("hex"), G1_ALPHA_HEX);
+});
+
+// ---------------------------------------------------------------------------
+// KAT: G2 decimal quad → exact 128B hex, both limb orders
+// ---------------------------------------------------------------------------
+
+test("KAT: G2 generator → c1c0 (default) matches EIP-196 (im,re) encoding", () => {
+  const out = g2ToBytes(G2_GEN_SNARKJS, "c1c0");
+  assert.equal(out.length, 128);
+  assert.equal(out.toString("hex"), G2_GEN_C1C0_HEX);
+});
+
+test("KAT: G2 generator → c0c1 option matches raw snarkjs limb order", () => {
+  const out = g2ToBytes(G2_GEN_SNARKJS, "c0c1");
+  assert.equal(out.length, 128);
+  assert.equal(out.toString("hex"), G2_GEN_C0C1_HEX);
+});
+
+test("g2LimbOrder defaults to c1c0 and rejects unknown orders", () => {
+  assert.equal(g2ToBytes(G2_GEN_SNARKJS).toString("hex"), G2_GEN_C1C0_HEX);
+  assert.throws(() => g2ToBytes(G2_GEN_SNARKJS, "c2c3"), /g2LimbOrder/);
+});
+
+// ---------------------------------------------------------------------------
+// KAT: scalar canonicality (< r)
+// ---------------------------------------------------------------------------
+
+test("KAT: public input r - 1 → exact 32B BE hex", () => {
+  const [out] = publicInputsFromSnarkjs([(FR_MODULUS - 1n).toString(10)]);
+  assert.equal(out.length, 32);
+  assert.equal(out.toString("hex"), R_MINUS_1_HEX);
+});
+
+test("scalar >= r throws (canonicality)", () => {
+  assert.throws(() => publicInputsFromSnarkjs([R_DECIMAL]), /canonical/);
+  assert.throws(
+    () => publicInputsFromSnarkjs([(FR_MODULUS + 1n).toString(10)]),
+    /canonical/,
+  );
+  assert.throws(() => frToBytes32BE(R_DECIMAL), /canonical/);
+});
+
+test("public inputs reject non-decimal / negative / negative-zero junk", () => {
+  assert.throws(() => publicInputsFromSnarkjs(["0x10"]));
+  assert.throws(() => publicInputsFromSnarkjs(["-1"]));
+  assert.throws(() => publicInputsFromSnarkjs(["01"])); // non-canonical decimal string
+  assert.throws(() => publicInputsFromSnarkjs("not json {"));
+  assert.throws(() => publicInputsFromSnarkjs({}));
+});
+
+test("G1/G2 coordinates >= q throw (canonicality)", () => {
+  assert.throws(() => g1ToBytes([FQ_MODULUS.toString(10), "1"]), /canonical/);
+  assert.throws(
+    () => g2ToBytes([["1", FQ_MODULUS.toString(10)], ["1", "2"]], "c1c0"),
+    /canonical/,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// KAT: proof passthrough — A is NEVER negated by the codec
+// ---------------------------------------------------------------------------
+
+test("proofFromSnarkjs passes A through raw (program negates on-chain)", () => {
+  const proofJson = {
+    pi_a: [...G1_ALPHA_DECIMAL, "1"],
+    pi_b: G2_GEN_SNARKJS,
+    pi_c: [...G1_GEN_DECIMAL, "1"],
+  };
+  const { a, b, c } = proofFromSnarkjs(proofJson);
+  assert.equal(a.length, 64);
+  assert.equal(b.length, 128);
+  assert.equal(c.length, 64);
+  assert.equal(a.toString("hex"), G1_ALPHA_HEX, "A must be the raw affine point");
+  assert.equal(b.toString("hex"), G2_GEN_C1C0_HEX);
+  assert.equal(c.toString("hex"), G1_GEN_HEX);
+  const { b: bSwapped } = proofFromSnarkjs(proofJson, { g2LimbOrder: "c0c1" });
+  assert.equal(bSwapped.toString("hex"), G2_GEN_C0C1_HEX);
+});
+
+// ---------------------------------------------------------------------------
+// KAT: 7-IC vk round-trip shape (v3 contract: ic[0] + 6 public inputs)
+// ---------------------------------------------------------------------------
+
+function makeVkJson(icCount) {
+  return {
+    protocol: "groth16",
+    curve: "bn128",
+    nPublic: icCount - 1,
+    vk_alpha_1: [...G1_ALPHA_DECIMAL, "1"],
+    vk_beta_2: G2_GEN_SNARKJS,
+    vk_gamma_2: G2_GEN_SNARKJS,
+    vk_delta_2: G2_GEN_SNARKJS,
+    vk_alphabeta_12: [],
+    IC: Array.from({ length: icCount }, (_, i) => [
+      String(i + 1),
+      String(i + 2),
+      "1",
+    ]),
+  };
+}
+
+test("KAT: 7-IC vk round-trip shape (ic[0] + 6 public inputs)", () => {
+  assert.equal(NUM_PUBLIC_INPUTS, 6);
+  assert.equal(EXPECTED_IC_LENGTH, 7);
+  const vk = vkFromSnarkjs(makeVkJson(7));
+  assert.equal(vk.alphaG1.length, 64);
+  assert.equal(vk.alphaG1.toString("hex"), G1_ALPHA_HEX);
+  for (const g2 of [vk.betaG2, vk.gammaG2, vk.deltaG2]) {
+    assert.equal(g2.length, 128);
+    assert.equal(g2.toString("hex"), G2_GEN_C1C0_HEX);
+  }
+  assert.equal(vk.ic.length, 7);
+  for (const [i, p] of vk.ic.entries()) {
+    assert.equal(p.length, 64);
+    const expectedX = Buffer.alloc(32);
+    expectedX[31] = i + 1;
+    const expectedY = Buffer.alloc(32);
+    expectedY[31] = i + 2;
+    assert.deepEqual(p, Buffer.concat([expectedX, expectedY]));
+  }
+  // Accepts a JSON string too.
+  const fromString = vkFromSnarkjs(JSON.stringify(makeVkJson(7)));
+  assert.deepEqual(fromString.ic, vk.ic);
+});
+
+test("vkFromSnarkjs rejects IC length != 7 (e.g. old 8-IC epoch circuit)", () => {
+  assert.throws(() => vkFromSnarkjs(makeVkJson(8)), /IC length 8 != expected 7/);
+  assert.throws(() => vkFromSnarkjs(makeVkJson(6)), /IC length 6 != expected 7/);
+  // Explicit override works for foreign circuits.
+  const vk8 = vkFromSnarkjs(makeVkJson(8), { expectedIc: 8 });
+  assert.equal(vk8.ic.length, 8);
+});
+
+test("vkFromSnarkjs rejects malformed vk JSON", () => {
+  const bad = makeVkJson(7);
+  delete bad.vk_delta_2;
+  assert.throws(() => vkFromSnarkjs(bad), /vk_delta_2/);
+  assert.throws(() => vkFromSnarkjs("{nope"), /not valid JSON/);
+});
+
+// ---------------------------------------------------------------------------
+// Integration: round-trip the real ceremony outputs (setup.mjs product)
+// ---------------------------------------------------------------------------
+
+test("integration: circuits/build/verification_key.json → codec → matches vk_bytes.json", async (t) => {
+  const waitMs = Number(process.env.ZK_CODEC_INTEGRATION_WAIT_MS ?? 20_000);
+  const deadline = Date.now() + waitMs;
+  while (!existsSync(VK_JSON_PATH) && Date.now() < deadline) {
+    await sleep(1000);
+  }
+  if (!existsSync(VK_JSON_PATH)) {
+    t.skip(
+      `verification_key.json not present after ${waitMs}ms — run zk/setup.mjs first ` +
+        `(set ZK_CODEC_INTEGRATION_WAIT_MS to wait longer)`,
+    );
+    return;
+  }
+
+  const vkJson = JSON.parse(readFileSync(VK_JSON_PATH, "utf8"));
+  assert.equal(vkJson.nPublic, NUM_PUBLIC_INPUTS, "circuit must have 6 public inputs");
+  const vk = vkFromSnarkjs(vkJson); // asserts IC == 7
+  assert.equal(vk.ic.length, EXPECTED_IC_LENGTH);
+  assert.equal(vk.alphaG1.length, 64);
+  for (const g2 of [vk.betaG2, vk.gammaG2, vk.deltaG2]) {
+    assert.equal(g2.length, 128);
+  }
+
+  assert.ok(
+    existsSync(VK_BYTES_PATH),
+    `vk_bytes.json must exist next to verification_key.json (${VK_BYTES_PATH})`,
+  );
+  const vkBytes = JSON.parse(readFileSync(VK_BYTES_PATH, "utf8"));
+  assert.equal(vkBytes.format, "raw-be-hex-v1");
+  assert.equal(vkBytes.g2LimbOrder, "c1c0");
+  assert.equal(vkBytes.icCount, EXPECTED_IC_LENGTH);
+  assert.equal(vkBytes.numPublicInputs, NUM_PUBLIC_INPUTS);
+  const strip = (h) => h.replace(/^0x/, "");
+  assert.equal(strip(vkBytes.alphaG1), vk.alphaG1.toString("hex"));
+  assert.equal(strip(vkBytes.betaG2), vk.betaG2.toString("hex"));
+  assert.equal(strip(vkBytes.gammaG2), vk.gammaG2.toString("hex"));
+  assert.equal(strip(vkBytes.deltaG2), vk.deltaG2.toString("hex"));
+  assert.equal(vkBytes.ic.length, EXPECTED_IC_LENGTH);
+  for (const [i, h] of vkBytes.ic.entries()) {
+    assert.equal(strip(h), vk.ic[i].toString("hex"), `IC[${i}] mismatch`);
+  }
+});

package/cortex-v3/zk/zk-settle.mjs

@@ -0,0 +1,370 @@
+// On-chain settlement client for the Enigma shared ZK state layer.
+// Flow: install pinned VK (governance) → initialize shared state (governance) →
+// submit client-generated Groth16 action proofs (permissionless).
+//
+// Sovereignty invariant: only { proof bytes, 6 public inputs } are transmitted.
+// No witness material (ownerKey, rho, payloadCommit, Merkle paths) appears here.
+import { createHash } from 'node:crypto';
+import {
+  PublicKey, SystemProgram, Transaction, TransactionInstruction,
+  sendAndConfirmTransaction,
+} from '@solana/web3.js';
+
+export const PROGRAM_ID = new PublicKey('E18KZR1Jq8fG3FFACpoHsE21ME3t1ftKPEwXL7cFWkoZ');
+export const BPF_UPGRADEABLE_LOADER = new PublicKey('BPFLoaderUpgradeab1e11111111111111111111111');
+export const disc = (name) => createHash('sha256').update(`global:${name}`).digest().subarray(0, 8);
+export const [SHARED_STATE_PDA] = PublicKey.findProgramAddressSync(
+  [Buffer.from('shared_state')], PROGRAM_ID);
+export const [PROGRAM_DATA_PDA] = PublicKey.findProgramAddressSync(
+  [PROGRAM_ID.toBuffer()], BPF_UPGRADEABLE_LOADER);
+
+export function verifyingKeyPda(circuitVersion = 1) {
+  const buf = Buffer.alloc(8);
+  buf.writeBigUInt64BE(BigInt(circuitVersion));
+  return PublicKey.findProgramAddressSync([Buffer.from('verifying_key'), buf], PROGRAM_ID)[0];
+}
+
+// --- On-chain VK inspection ----------------------------------------------------
+/**
+ * Normalize a VK from any accepted representation (Buffer/Uint8Array or hex
+ * string, as produced by resolveVerifyingKey's parsed JSON) into Buffers with
+ * EXACT length validation: 64B alpha, 128B beta/gamma/delta, exactly 7×64B IC.
+ */
+export function normalizeVkBytes(vk) {
+  const toBuf = (v, len, name) => {
+    const b = typeof v === 'string' ? Buffer.from(v, 'hex') : Buffer.from(v);
+    if (b.length !== len) throw new Error(`VK ${name}: expected ${len} bytes, got ${b.length}`);
+    return b;
+  };
+  if (!vk || typeof vk !== 'object') throw new TypeError('VK must be an object');
+  if (!Array.isArray(vk.ic) || vk.ic.length !== 7) {
+    throw new Error(`VK ic: expected exactly 7 points, got ${vk.ic?.length}`);
+  }
+  return {
+    alphaG1: toBuf(vk.alphaG1, 64, 'alphaG1'),
+    betaG2: toBuf(vk.betaG2, 128, 'betaG2'),
+    gammaG2: toBuf(vk.gammaG2, 128, 'gammaG2'),
+    deltaG2: toBuf(vk.deltaG2, 128, 'deltaG2'),
+    ic: vk.ic.map((p, i) => toBuf(p, 64, `ic[${i}]`)),
+  };
+}
+
+export function decodeVerifyingKey(d) {
+  if (d.length !== 952) throw new Error(`CircuitVerifyingKey: expected 952 bytes, got ${d.length}`);
+  const ic = [];
+  for (let i = 0; i < 7; i++) ic.push(d.subarray(496 + i * 64, 496 + (i + 1) * 64));
+  return {
+    authority: d.subarray(8, 40),
+    circuitVersion: Number(d.readBigUInt64LE(40)),
+    alphaG1: d.subarray(48, 112),
+    betaG2: d.subarray(112, 240),
+    gammaG2: d.subarray(240, 368),
+    deltaG2: d.subarray(368, 496),
+    ic,
+  };
+}
+
+export async function fetchVerifyingKey(connection, circuitVersion = 1) {
+  const acct = await connection.getAccountInfo(verifyingKeyPda(circuitVersion));
+  if (!acct) return null;
+  return decodeVerifyingKey(acct.data);
+}
+// CircuitVerifyingKey layout: 8 disc + 32 authority + 8 circuit_version
+// + 64 alpha_g1 + 128 beta_g2 + 128 gamma_g2 + 128 delta_g2 + 7×64 ic + 8 created_at
+
+/**
+ * Fail-closed gate: the on-chain VK PDA must EXACTLY equal the manifest-pinned
+ * VK before any proof is generated/submitted — proving against a mismatched or
+ * absent VK guarantees rejection (or worse, a different ceremony's key).
+ * Returns 'match' | 'installed' (when authority installs a missing key).
+ * Throws otherwise.
+ */
+export async function assertOnChainVerifyingKey(connection, circuitVersion, vkBytes, opts = {}) {
+  const onchain = await fetchVerifyingKey(connection, circuitVersion);
+  const want = normalizeVkBytes(vkBytes);
+  const eq = (a, b) => Buffer.from(a).equals(Buffer.from(b));
+  if (!onchain) {
+    if (opts.installAuthority) {
+      await installVerifyingKey(connection, opts.installAuthority, want, circuitVersion);
+      return 'installed';
+    }
+    throw new Error(
+      `no on-chain verifying key for circuit version ${circuitVersion} — install it via governance before proving`,
+    );
+  }
+  const matches = eq(onchain.alphaG1, want.alphaG1) && eq(onchain.betaG2, want.betaG2)
+    && eq(onchain.gammaG2, want.gammaG2) && eq(onchain.deltaG2, want.deltaG2)
+    && onchain.ic.length === want.ic.length
+    && onchain.ic.every((p, i) => eq(p, want.ic[i]));
+  if (!matches) {
+    throw new Error(
+      `on-chain verifying key for circuit version ${circuitVersion} does NOT match the manifest-pinned VK — refusing to prove`,
+    );
+  }
+  return 'match';
+}
+
+// --- Governance: install the pinned verifying key -----------------------------
+// vkBytes: { alphaG1, betaG2, gammaG2, deltaG2, ic[7] } as Uint8Array/Buffer
+export async function installVerifyingKey(connection, authority, vkBytes, circuitVersion = 1) {
+  // Borsh u64 arg = little-endian (the PDA SEED stays big-endian per program source).
+  const versionBuf = Buffer.alloc(8);
+  versionBuf.writeBigUInt64LE(BigInt(circuitVersion));
+  const icFlat = Buffer.concat(vkBytes.ic.map((p) => Buffer.from(p)));
+  const data = Buffer.concat([
+    disc('initialize_circuit_verifying_key'),
+    versionBuf,
+    Buffer.from(vkBytes.alphaG1),
+    Buffer.from(vkBytes.betaG2),
+    Buffer.from(vkBytes.gammaG2),
+    Buffer.from(vkBytes.deltaG2),
+    icFlat,
+  ]);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: verifyingKeyPda(circuitVersion), isSigner: false, isWritable: true },
+      { pubkey: PROGRAM_ID, isSigner: false, isWritable: false },
+      { pubkey: PROGRAM_DATA_PDA, isSigner: false, isWritable: false },
+      { pubkey: authority.publicKey, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [authority]);
+}
+
+// --- Governance: initialize the shared state with genesis roots ---------------
+export async function initializeSharedState(connection, authority, genesisNoteRoot, genesisNullRoot) {
+  const data = Buffer.concat([
+    disc('initialize_shared_state'),
+    Buffer.from(genesisNoteRoot),
+    Buffer.from(genesisNullRoot),
+  ]);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: SHARED_STATE_PDA, isSigner: false, isWritable: true },
+      { pubkey: PROGRAM_ID, isSigner: false, isWritable: false },
+      { pubkey: PROGRAM_DATA_PDA, isSigner: false, isWritable: false },
+      { pubkey: authority.publicKey, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [authority]);
+}
+
+// --- Permissionless: settle one client-generated action proof ------------------
+// proofBytes: { a: 64B, b: 128B, c: 64B } raw BE (program negates A internally)
+// publicInputs: 6 × 32B BE buffers, canonical < r
+export async function settleAction(connection, payer, proofBytes, publicInputs, circuitVersion = 1) {
+  const data = Buffer.concat([
+    disc('settle_action'),
+    Buffer.from(proofBytes.a),
+    Buffer.from(proofBytes.b),
+    Buffer.from(proofBytes.c),
+    ...publicInputs.map((p) => Buffer.from(p)),
+  ]);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: SHARED_STATE_PDA, isSigner: false, isWritable: true },
+      { pubkey: verifyingKeyPda(circuitVersion), isSigner: false, isWritable: false },
+      { pubkey: payer.publicKey, isSigner: true, isWritable: true },
+    ],
+    data,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [payer]);
+}
+
+export const INTENT_CIRCUIT_VERSION = 2;
+export const SALE_CIRCUIT_VERSION = 3;
+
+export function saleReceiptPda(keyCommitBytes, envelopeCommitBytes) {
+  const seed = createHash('sha256')
+    .update(Buffer.from(keyCommitBytes))
+    .update(Buffer.from(envelopeCommitBytes))
+    .digest();
+  return PublicKey.findProgramAddressSync([Buffer.from('sale_receipt'), seed], PROGRAM_ID)[0];
+}
+
+export function saleEscrowPda(buyerPubkey, saleTermsHashBytes) {
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from('sale_escrow'), buyerPubkey.toBuffer(), Buffer.from(saleTermsHashBytes)], PROGRAM_ID)[0];
+}
+
+// --- Sealed Sale (ZKCP): verify encryption-consistent, recipient-bound proof ---
+// publicInputs: 7 × 32B BE [noteRoot, payloadCommitPos, cipherCommit, keyCommit,
+// saleTermsHash, envelopeCommit, payloadLen]. Attestation stores COMMITMENTS
+// ONLY — the envelope (epk/encDek) + CTR nonce are revealed inside claim_sale,
+// atomically with payment (Poseidon5-bound on-chain).
+export async function settleSale(connection, payer, proofBytes, publicInputs) {
+  const data = Buffer.concat([
+    disc('settle_sale'),
+    Buffer.from(proofBytes.a),
+    Buffer.from(proofBytes.b),
+    Buffer.from(proofBytes.c),
+    ...publicInputs.map((p) => Buffer.from(p)),
+  ]);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: SHARED_STATE_PDA, isSigner: false, isWritable: false },
+      { pubkey: verifyingKeyPda(SALE_CIRCUIT_VERSION), isSigner: false, isWritable: false },
+      { pubkey: saleReceiptPda(publicInputs[3], publicInputs[5]), isSigner: false, isWritable: true },
+      { pubkey: payer.publicKey, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [payer]);
+}
+
+export async function createSaleEscrow(connection, buyer, sellerPubkey, saleTermsHashBytes, priceLamports, expirySlot, receiptPubkey) {
+  const args = Buffer.alloc(8 + 32 + 8 + 8);
+  let o = 0;
+  disc('create_sale_escrow').copy(args, 0); o = 8;
+  Buffer.from(saleTermsHashBytes).copy(args, o); o += 32;
+  args.writeBigUInt64LE(BigInt(priceLamports), o); o += 8;
+  args.writeBigUInt64LE(BigInt(expirySlot), o);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: saleEscrowPda(buyer.publicKey, saleTermsHashBytes), isSigner: false, isWritable: true },
+      { pubkey: buyer.publicKey, isSigner: true, isWritable: true },
+      { pubkey: sellerPubkey, isSigner: false, isWritable: false },
+      { pubkey: receiptPubkey, isSigner: false, isWritable: false },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data: args,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [buyer]);
+}
+
+export function createClaimSaleInstruction(sellerPubkey, buyerPubkey, saleTermsHashBytes, keyCommitBytes, envelopeCommitBytes, epk, encDek, nonceBytes) {
+  const data = Buffer.concat([
+    disc('claim_sale'),
+    Buffer.from(saleTermsHashBytes),
+    Buffer.from(epk),
+    Buffer.from(encDek),
+    Buffer.from(nonceBytes),
+  ]);
+  return new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: saleEscrowPda(buyerPubkey, saleTermsHashBytes), isSigner: false, isWritable: true },
+      { pubkey: saleReceiptPda(keyCommitBytes, envelopeCommitBytes), isSigner: false, isWritable: true },
+      { pubkey: sellerPubkey, isSigner: true, isWritable: true },
+      { pubkey: buyerPubkey, isSigner: false, isWritable: true },
+    ],
+    data,
+  });
+}
+
+export async function claimSale(connection, seller, buyerPubkey, saleTermsHashBytes, keyCommitBytes, envelopeCommitBytes, epk, encDek, nonceBytes) {
+  const ix = createClaimSaleInstruction(seller.publicKey, buyerPubkey, saleTermsHashBytes, keyCommitBytes, envelopeCommitBytes, epk, encDek, nonceBytes);
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [seller]);
+}
+
+// SaleReceipt layout (MUST match the Rust struct field order exactly):
+//   8 disc + 32 sale_terms_hash + 32 key_commit + 32 cipher_commit
+//   + 32 envelope_commit + 32 payload_commit_pos + 64 epk + 64 enc_dek
+//   + 32 nonce + 8 slot + 8 timestamp = 344 bytes
+export const SALE_RECEIPT_LAYOUT = Object.freeze({
+  discriminator: 8,
+  saleTermsHash: [8, 40],
+  keyCommit: [40, 72],
+  cipherCommit: [72, 104],
+  envelopeCommit: [104, 136],
+  payloadCommitPos: [136, 168],
+  epk: [168, 232],
+  encDek: [232, 296],
+  nonce: [296, 328],
+  slot: 328,
+  total: 344,
+});
+
+export function decodeSaleReceipt(d) {
+  const L = SALE_RECEIPT_LAYOUT;
+  if (d.length !== L.total) {
+    throw new Error(`SaleReceipt decode: expected ${L.total} bytes, got ${d.length}`);
+  }
+  return {
+    saleTermsHash: d.subarray(...L.saleTermsHash),
+    keyCommit: d.subarray(...L.keyCommit),
+    cipherCommit: d.subarray(...L.cipherCommit),
+    envelopeCommit: d.subarray(...L.envelopeCommit),
+    payloadCommitPos: d.subarray(...L.payloadCommitPos),
+    epk: d.subarray(...L.epk),
+    encDek: d.subarray(...L.encDek),
+    nonce: d.subarray(...L.nonce),
+    slot: Number(d.readBigUInt64LE(L.slot)),
+  };
+}
+
+export async function fetchSaleReceipt(connection, keyCommitBytes, envelopeCommitBytes) {
+  const acct = await connection.getAccountInfo(saleReceiptPda(keyCommitBytes, envelopeCommitBytes));
+  if (!acct) return null;
+  return decodeSaleReceipt(acct.data);
+}
+
+export function createRefundSaleInstruction(buyerPubkey, saleTermsHashBytes) {
+  const data = Buffer.concat([disc('refund_sale'), Buffer.from(saleTermsHashBytes)]);
+  return new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: saleEscrowPda(buyerPubkey, saleTermsHashBytes), isSigner: false, isWritable: true },
+      { pubkey: buyerPubkey, isSigner: true, isWritable: true },
+    ],
+    data,
+  });
+}
+
+export async function refundSale(connection, buyer, saleTermsHashBytes) {
+  const ix = createRefundSaleInstruction(buyer.publicKey, saleTermsHashBytes);
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [buyer]);
+}
+
+export function intentReceiptPda(nullifierBytes) {
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from('intent_null'), Buffer.from(nullifierBytes)], PROGRAM_ID)[0];
+}
+
+// --- Permissionless: settle a verifiable-agent-intent attestation --------------
+// publicInputs: 4 × 32B BE [noteRoot, actionHash, nullifier, currentSlot]
+export async function settleIntent(connection, payer, proofBytes, publicInputs) {
+  const data = Buffer.concat([
+    disc('settle_intent'),
+    Buffer.from(proofBytes.a),
+    Buffer.from(proofBytes.b),
+    Buffer.from(proofBytes.c),
+    ...publicInputs.map((p) => Buffer.from(p)),
+  ]);
+  const ix = new TransactionInstruction({
+    programId: PROGRAM_ID,
+    keys: [
+      { pubkey: SHARED_STATE_PDA, isSigner: false, isWritable: false },
+      { pubkey: verifyingKeyPda(INTENT_CIRCUIT_VERSION), isSigner: false, isWritable: false },
+      { pubkey: intentReceiptPda(publicInputs[2]), isSigner: false, isWritable: true },
+      { pubkey: payer.publicKey, isSigner: true, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data,
+  });
+  return sendAndConfirmTransaction(connection, new Transaction().add(ix), [payer]);
+}
+
+// SharedState layout: 8 disc + 32 authority + 32 note_root + 32 null_root
+//                     + 8 note_count + 8 null_count + 8 created_at
+export async function fetchSharedState(connection) {
+  const acct = await connection.getAccountInfo(SHARED_STATE_PDA);
+  if (!acct) return null;
+  const d = acct.data;
+  return {
+    noteRoot: d.subarray(40, 72),
+    nullRoot: d.subarray(72, 104),
+    noteCount: Number(d.readBigUInt64LE(104)),
+    nullCount: Number(d.readBigUInt64LE(112)),
+  };
+}