enigma-memory 0.1.18 → 0.1.22

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

@@ -0,0 +1,365 @@
+// intent-witness.mjs — client-side witness builder for
+// circuits/intent_attestation.circom — IntentAttestation(NOTE_DEPTH=20, ALLOW_DEPTH=16).
+//
+// Binding spec: "verifiable agent intent" — a Groth16 proof that an x402
+// payment action is consistent with a policy committed in the shared note
+// tree. RECONCILIATION POINT: circuits/intent_attestation.circom is built
+// concurrently (IntentCircuitBuild); every signal name below is taken VERBATIM
+// from the circuit spec, and intent-witness.test.mjs re-reads the .circom
+// file (when present) and asserts the names match exactly.
+//
+// Public signals (exact order/names): noteRoot, actionHash, nullifier, currentSlot.
+// Private signals: ownerKey, rho, maxAmount, allowlistRoot, validAfterSlot,
+//   notePathElements[20], notePathIndices[20] (LSB-first),
+//   rLo, rHi, mintLo, mintHi, amount, nonce (x402 descriptor limbs, each < 2^128),
+//   allowPathElements[16], allowPathIndices[16].
+//
+// In-circuit semantics mirrored here:
+//   payloadCommit = Poseidon4(DOMAIN_POLICY, maxAmount, allowlistRoot, validAfterSlot)
+//   note          = Poseidon3(ownerKey, rho, payloadCommit)   (member of noteRoot)
+//   payeeLeaf     = Poseidon3(DOMAIN_ALLOW, rLo, rHi)         (member of allowlistRoot)
+//   actionHash    = Poseidon7(DOMAIN_ACTION, rLo, rHi, mintLo, mintHi, amount, nonce)
+//   nullifier     = Poseidon3(DOMAIN_INTENT_NF, ownerKey, actionHash)
+//   amount <= maxAmount (u64), validAfterSlot <= currentSlot (< 2^48)
+//
+// x402 descriptor limbs (deterministic, each < 2^128, little-endian):
+//   recipient (32B) = rLo (LE bytes 0..16) | rHi (LE bytes 16..32)
+//   mint      (32B) = mintLo | mintHi      (same split)
+//   amount    = u64 LE lamports
+//   nonce     = 16 bytes LE
+//
+// All field elements are emitted as DECIMAL STRINGS (snarkjs JSON convention).
+
+import bs58 from "bs58";
+
+import {
+  NoteTree,
+  buildZeros,
+  computeProof,
+  computeRoot,
+  poseidon,
+  verifyMerkleProof,
+} from "./zk-tree.mjs";
+
+/** Note tree depth (matches the shared note tree / NoteTree default). */
+export const NOTE_DEPTH = 20;
+/** Allowlist tree depth. */
+export const ALLOW_DEPTH = 16;
+
+// Domain separators ("enigma_policy" / "enigma_allow" / "enigma_action" /
+// "enigma_intent" ASCII, decimal — the circuit binds these exact values).
+export const DOMAIN_POLICY = 8036215190653564880547136234361n;
+export const DOMAIN_ALLOW = 31391465588490487750162411383n;
+export const DOMAIN_ACTION = 8036215190653564864003056430958n;
+export const DOMAIN_INTENT_NF = 8036215190653564872846393831028n;
+
+/** Public signal names in exact on-chain/circuit order. */
+export const INTENT_PUBLIC_SIGNALS = Object.freeze([
+  "noteRoot",
+  "actionHash",
+  "nullifier",
+  "currentSlot",
+]);
+
+const TWO_64 = 1n << 64n;
+const TWO_128 = 1n << 128n;
+const TWO_48 = 1n << 48n;
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+/** 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;
+}
+
+/**
+ * Split the x402 payment descriptor into circuit limbs.
+ * recipient/mint: base58-encoded 32-byte Solana pubkeys.
+ * amountLamports: u64. nonceBytes: exactly 16 bytes.
+ * Returns { rLo, rHi, mintLo, mintHi, amount, nonce } — bigints, each < 2^128.
+ */
+export function splitDescriptor({ recipient, mint, amountLamports, nonceBytes }) {
+  const rBytes = decodeBase58Fixed(recipient, 32, "recipient");
+  const mBytes = decodeBase58Fixed(mint, 32, "mint");
+  const amount = BigInt(amountLamports);
+  if (amount < 0n || amount >= TWO_64) {
+    throw new RangeError(`amountLamports ${amount} out of u64 range`);
+  }
+  const nonce = bytesToBigIntLE(nonceBytes);
+  if (!(nonceBytes instanceof Uint8Array) || nonceBytes.length !== 16) {
+    throw new Error(`nonceBytes: expected exactly 16 bytes, got ${nonceBytes?.length}`);
+  }
+  if (nonce >= TWO_128) throw new RangeError("nonce limb overflow"); // unreachable for 16B
+  return {
+    rLo: bytesToBigIntLE(rBytes.subarray(0, 16)),
+    rHi: bytesToBigIntLE(rBytes.subarray(16, 32)),
+    mintLo: bytesToBigIntLE(mBytes.subarray(0, 16)),
+    mintHi: bytesToBigIntLE(mBytes.subarray(16, 32)),
+    amount,
+    nonce,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Poseidon commitments (mirror the circuit exactly)
+// ---------------------------------------------------------------------------
+
+/**
+ * actionHash = Poseidon7(DOMAIN_ACTION, rLo, rHi, mintLo, mintHi, amount, nonce).
+ * @returns {{ actionHash: bigint, rLo: bigint, rHi: bigint, mintLo: bigint,
+ *   mintHi: bigint, amount: bigint, nonce: bigint }}
+ */
+export function computeActionHash({ recipientPubkeyBase58, mintBase58, amountLamports, nonceBytes }) {
+  const limbs = splitDescriptor({
+    recipient: recipientPubkeyBase58,
+    mint: mintBase58,
+    amountLamports,
+    nonceBytes,
+  });
+  const actionHash = poseidon([
+    DOMAIN_ACTION,
+    limbs.rLo,
+    limbs.rHi,
+    limbs.mintLo,
+    limbs.mintHi,
+    limbs.amount,
+    limbs.nonce,
+  ]);
+  return { actionHash, ...limbs };
+}
+
+/** payloadCommit = Poseidon4(DOMAIN_POLICY, maxAmount, allowlistRoot, validAfterSlot). */
+export function computePayloadCommit({ maxAmount, allowlistRoot, validAfterSlot }) {
+  return poseidon([
+    DOMAIN_POLICY,
+    BigInt(maxAmount),
+    BigInt(allowlistRoot),
+    BigInt(validAfterSlot),
+  ]);
+}
+
+/** nullifier = Poseidon3(DOMAIN_INTENT_NF, ownerKey, actionHash). */
+export function computeIntentNullifier(ownerKey, actionHash) {
+  return poseidon([DOMAIN_INTENT_NF, BigInt(ownerKey), BigInt(actionHash)]);
+}
+/** Policy note leaf = Poseidon3(ownerKey, rho, payloadCommit) — insert into NoteTree. */
+export function computeIntentNote(ownerKey, rho, payloadCommit) {
+  return poseidon([BigInt(ownerKey), BigInt(rho), BigInt(payloadCommit)]);
+}
+
+// ---------------------------------------------------------------------------
+// AllowlistTree — depth-16 Poseidon Merkle tree of allowlisted payees.
+// leaf = Poseidon3(DOMAIN_ALLOW, rLo, rHi); append-only, same sparse-prefix
+// machinery as the note tree (computeRoot/computeProof accept a depth param).
+// ---------------------------------------------------------------------------
+
+export class AllowlistTree {
+  constructor(depth = ALLOW_DEPTH) {
+    this.depth = depth;
+    this.zeros = buildZeros(depth);
+    /** @type {{rLo: bigint, rHi: bigint, leaf: bigint}[]} */
+    this.payees = [];
+  }
+
+  get leaves() {
+    return this.payees.map((p) => p.leaf);
+  }
+
+  get nextIndex() {
+    return this.payees.length;
+  }
+
+  root() {
+    return computeRoot(this.leaves, this.zeros, this.depth);
+  }
+
+  /** Proof for any index (filled leaf or zero slot) against the current root. */
+  getProof(index) {
+    return computeProof(this.leaves, index, this.zeros, this.depth);
+  }
+
+  /**
+   * Append a payee by base58 recipient pubkey. Returns
+   * { index, leaf, pathElements, pathIndices } — the proof of the inserted
+   * leaf against the POST-insert root (what the intent circuit consumes).
+   */
+  insert(recipientBase58) {
+    const index = this.payees.length;
+    if (index >= 2 ** this.depth) throw new RangeError("allowlist tree full");
+    const { rLo, rHi } = splitDescriptor({
+      recipient: recipientBase58,
+      mint: recipientBase58, // unused limbs; recipient drives rLo/rHi
+      amountLamports: 0n,
+      nonceBytes: new Uint8Array(16),
+    });
+    const leaf = poseidon([DOMAIN_ALLOW, rLo, rHi]);
+    this.payees.push({ rLo, rHi, leaf });
+    const { pathElements, pathIndices } = this.getProof(index);
+    return { index, leaf, pathElements, pathIndices };
+  }
+
+  /** Index of the payee leaf for (rLo, rHi), or -1 if not allowlisted. */
+  indexOf(rLo, rHi) {
+    for (let i = 0; i < this.payees.length; i++) {
+      if (this.payees[i].rLo === rLo && this.payees[i].rHi === rHi) return i;
+    }
+    return -1;
+  }
+
+  verifyProof(leaf, pathElements, pathIndices, root = this.root()) {
+    return verifyMerkleProof(leaf, pathElements, pathIndices, root, this.depth);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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(`buildIntentWitness: missing ${name}`);
+  }
+  return BigInt(value);
+}
+
+/**
+ * Build the snarkjs input for one intent attestation.
+ *
+ * @param {object} args
+ * @param {NoteTree} args.noteTree          shared note tree at the current on-chain note_root
+ * @param {number} args.noteIndex           index of the policy note in noteTree
+ * @param {bigint|number|string} args.ownerKey   note opening
+ * @param {bigint|number|string} args.rho        note opening
+ * @param {bigint|number|string} args.maxAmount  policy cap (u64 lamports)
+ * @param {AllowlistTree} args.allowlist    payee allowlist tree (contains recipient)
+ * @param {bigint|number|string} args.validAfterSlot  policy time lock (slot, < 2^48)
+ * @param {string} args.recipient           x402 payee, base58 32B pubkey
+ * @param {string} args.mint                x402 mint, base58 32B pubkey
+ * @param {bigint|number|string} args.amountLamports  payment amount (u64)
+ * @param {Uint8Array} args.nonceBytes      16-byte action nonce (LE limb)
+ * @param {bigint|number|string} args.currentSlot   current slot (< 2^48, <= Clock on-chain)
+ * @returns {object} snarkjs input JSON (all values decimal strings); public
+ *   signals are INTENT_PUBLIC_SIGNALS in order.
+ */
+export function buildIntentWitness(args) {
+  const { noteTree, allowlist, noteIndex } = args;
+  if (!(noteTree instanceof NoteTree)) throw new TypeError("noteTree must be a NoteTree");
+  if (!(allowlist instanceof AllowlistTree)) {
+    throw new TypeError("allowlist must be an AllowlistTree");
+  }
+  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 maxAmount = need(args.maxAmount, "maxAmount");
+  const validAfterSlot = need(args.validAfterSlot, "validAfterSlot");
+  const currentSlot = need(args.currentSlot, "currentSlot");
+
+  if (maxAmount < 0n || maxAmount >= TWO_64) {
+    throw new RangeError(`maxAmount ${maxAmount} out of u64 range`);
+  }
+  if (validAfterSlot < 0n || validAfterSlot >= TWO_48) {
+    throw new RangeError(`validAfterSlot ${validAfterSlot} out of 48-bit range`);
+  }
+  if (currentSlot < 0n || currentSlot >= TWO_48) {
+    throw new RangeError(`currentSlot ${currentSlot} out of 48-bit range`);
+  }
+
+  // x402 descriptor limbs + public actionHash.
+  if (args.recipient === undefined || args.recipient === null) {
+    throw new TypeError("buildIntentWitness: missing recipient");
+  }
+  if (args.mint === undefined || args.mint === null) {
+    throw new TypeError("buildIntentWitness: missing mint");
+  }
+  const { actionHash, rLo, rHi, mintLo, mintHi, amount, nonce } = computeActionHash({
+    recipientPubkeyBase58: args.recipient,
+    mintBase58: args.mint,
+    amountLamports: args.amountLamports,
+    nonceBytes: args.nonceBytes,
+  });
+
+  // Client-side policy checks (the circuit enforces the same constraints;
+  // failing early gives a usable error instead of a wasm assertion trap).
+  if (amount > maxAmount) {
+    throw new Error(`amount ${amount} exceeds policy maxAmount ${maxAmount}`);
+  }
+  if (validAfterSlot > currentSlot) {
+    throw new Error(`policy not yet valid: validAfterSlot ${validAfterSlot} > currentSlot ${currentSlot}`);
+  }
+
+  // Policy commitment + note opening; the note must sit at noteIndex.
+  const allowlistRoot = allowlist.root();
+  const payloadCommit = computePayloadCommit({ maxAmount, allowlistRoot, validAfterSlot });
+  const note = computeIntentNote(ownerKey, rho, payloadCommit);
+  if (noteTree.leaves[noteIndex] !== note) {
+    throw new Error("note opening does not match the leaf at noteIndex");
+  }
+
+  // Note membership proof vs the current (pre-submission) note root.
+  const noteProof = noteTree.getProof(noteIndex);
+  const noteRoot = noteTree.root();
+
+  // Payee allowlist membership.
+  const payeeIndex = allowlist.indexOf(rLo, rHi);
+  if (payeeIndex === -1) {
+    throw new Error("recipient is not in the allowlist");
+  }
+  const allowProof = allowlist.getProof(payeeIndex);
+
+  // Non-replay nullifier bound to (ownerKey, actionHash).
+  const nullifier = computeIntentNullifier(ownerKey, actionHash);
+
+  return toDec({
+    // public (exact contract order/names)
+    noteRoot,
+    actionHash,
+    nullifier,
+    currentSlot,
+    // private
+    ownerKey,
+    rho,
+    maxAmount,
+    allowlistRoot,
+    validAfterSlot,
+    notePathElements: noteProof.pathElements,
+    notePathIndices: noteProof.pathIndices,
+    rLo,
+    rHi,
+    mintLo,
+    mintHi,
+    amount,
+    nonce,
+    allowPathElements: allowProof.pathElements,
+    allowPathIndices: allowProof.pathIndices,
+  });
+}