alberta-buck-core 0.1.1

package/src/chart.js

@@ -0,0 +1,70 @@
+// Tiny dependency-free SVG line charts, BigInt-free numbers in, string
+// out -- renders identically in node (write to a .svg file) and the
+// browser (innerHTML), so the demo page and bin/eqsim.mjs share it.
+
+const COLORS = ["#2563eb", "#dc2626", "#059669", "#d97706", "#7c3aed"];
+
+/**
+ * @param opts.title  chart title
+ * @param opts.series [{label, points: [[x, y], ...]}] -- y as Number
+ * @param opts.refY   optional dashed reference line (e.g. 1.0 parity)
+ * @param opts.yFmt   tick formatter
+ * @returns a standalone <svg> fragment string (nestable via svgDoc)
+ */
+export function lineChart({ title, series, width = 860, height = 240,
+                            refY = null, yFmt = (v) => v.toPrecision(4) }) {
+  const m = { l: 64, r: 14, t: 26, b: 22 };
+  const pts = series.flatMap((s) => s.points);
+  const xs = pts.map((p) => p[0]), ys = pts.map((p) => p[1]);
+  const xmin = Math.min(...xs), xmax = Math.max(...xs);
+  let ymin = Math.min(...ys, refY ?? Infinity);
+  let ymax = Math.max(...ys, refY ?? -Infinity);
+  const pad = (ymax - ymin || Math.abs(ymax) || 1) * 0.08;
+  ymin -= pad; ymax += pad;
+  const sx = (x) => m.l + ((x - xmin) / (xmax - xmin || 1)) * (width - m.l - m.r);
+  const sy = (y) => height - m.b - ((y - ymin) / (ymax - ymin)) * (height - m.t - m.b);
+
+  const yTicks = [0, 1, 2, 3, 4].map((i) => ymin + (i / 4) * (ymax - ymin));
+  const xTicks = [0, 1, 2, 3, 4, 5].map((i) => xmin + (i / 5) * (xmax - xmin));
+  const el = [];
+  el.push(`<rect width="${width}" height="${height}" fill="#ffffff"/>`);
+  el.push(`<text x="${m.l}" y="16" font-size="13" font-weight="bold" ` +
+          `font-family="monospace">${title}</text>`);
+  for (const t of yTicks) {
+    el.push(`<line x1="${m.l}" y1="${sy(t)}" x2="${width - m.r}" y2="${sy(t)}" ` +
+            `stroke="#e5e7eb"/>`);
+    el.push(`<text x="${m.l - 6}" y="${sy(t) + 4}" font-size="10" ` +
+            `font-family="monospace" text-anchor="end">${yFmt(t)}</text>`);
+  }
+  for (const t of xTicks) {
+    el.push(`<text x="${sx(t)}" y="${height - 6}" font-size="10" ` +
+            `font-family="monospace" text-anchor="middle">${Math.round(t)}</text>`);
+  }
+  if (refY !== null) {
+    el.push(`<line x1="${m.l}" y1="${sy(refY)}" x2="${width - m.r}" ` +
+            `y2="${sy(refY)}" stroke="#9ca3af" stroke-dasharray="5,4"/>`);
+  }
+  series.forEach((s, i) => {
+    const path = s.points.map((p) => `${sx(p[0]).toFixed(1)},${sy(p[1]).toFixed(1)}`)
+                         .join(" ");
+    const c = s.color ?? COLORS[i % COLORS.length];
+    el.push(`<polyline points="${path}" fill="none" stroke="${c}" stroke-width="1.6"/>`);
+    el.push(`<text x="${width - m.r}" y="${m.t + 12 * i}" font-size="11" ` +
+            `font-family="monospace" text-anchor="end" fill="${c}">${s.label}</text>`);
+  });
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" ` +
+         `height="${height}" viewBox="0 0 ${width} ${height}">${el.join("")}</svg>`;
+}
+
+/** Stack chart fragments vertically into one SVG document. */
+export function svgDoc(charts, { width = 860 } = {}) {
+  let y = 0;
+  const parts = [];
+  for (const c of charts) {
+    const h = Number(c.match(/height="(\d+)"/)[1]);
+    parts.push(`<svg y="${y}">${c.replace(/<\/?svg[^>]*>/g, "")}</svg>`);
+    y += h + 8;
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${y}">` +
+         parts.join("") + `</svg>`;
+}

package/src/identity-core.js

@@ -0,0 +1,248 @@
+// BigInt-native wrapper over the buck-identity wasm kernel -- the
+// environment-free CORE.  `wrapIdentity(wasm)` takes the raw wasm module
+// (0x-hex string ABI) however the host loaded it -- node require of the
+// nodejs-target package (identity.js) or awaited init of the web-target
+// package (identity-web.js) -- and returns the structured API:
+//
+//   point       {x, y}                       (BigInt; {0n, 0n} = infinity)
+//   G2 point    {x: [c0, c1], y: [c0, c1]}
+//   ciphertext  {R: point, C: point}
+//   PS sig      {sigma_1: point, sigma_2: point}
+//   proofs      objects with the Python dataclass field names
+//
+// Deterministic: every nonce is an argument.  `randScalar()` draws from
+// WebCrypto for live use; tests replay recorded nonces from
+// core/vectors/identity-kernel-vectors.json.
+
+// ---------------------------------------------------------------------------
+// Pure helpers (no wasm)
+// ---------------------------------------------------------------------------
+
+export const hex = (v) => "0x" + BigInt(v).toString(16).padStart(64, "0");
+export const big = (s) => BigInt(s);
+
+/** THE canonical JSON dialect: sorted keys, compact separators, raw
+ *  UTF-8 -- byte-identical to Python's canonical_json(), shared by the
+ *  identity preimage (canonical_identity_data) and the AB-RCPT/1 receipt
+ *  core.  Values must be strings and integers (floats are not canonical).
+ *  JSON.stringify emits this natively once keys are sorted. */
+export function canonicalIdentity(fields) {
+  const sort = (v) => {
+    if (Array.isArray(v)) return v.map(sort);
+    if (v && typeof v === "object") {
+      return Object.fromEntries(
+        Object.keys(v).sort().map((k) => [k, sort(v[k])]),
+      );
+    }
+    return v;
+  };
+  return JSON.stringify(sort(fields));
+}
+
+// ---------------------------------------------------------------------------
+// The wrapped API
+// ---------------------------------------------------------------------------
+
+export function wrapIdentity(wasm) {
+  const P = (arr, i = 0) => ({ x: big(arr[i]), y: big(arr[i + 1]) });
+  const CT = (arr, i = 0) => ({ R: P(arr, i), C: P(arr, i + 2) });
+  const flatP = (p) => [hex(p.x), hex(p.y)];
+  const flatCT = (ct) => [...flatP(ct.R), ...flatP(ct.C)];
+  const flatG2 = (g) => [hex(g.x[0]), hex(g.x[1]), hex(g.y[0]), hex(g.y[1])];
+
+  const ORDER = big(wasm.order());
+
+  /** Random non-zero scalar mod ORDER via WebCrypto. */
+  function randScalar() {
+    for (;;) {
+      const bytes = new Uint8Array(32);
+      globalThis.crypto.getRandomValues(bytes);
+      let v = 0n;
+      for (const b of bytes) v = (v << 8n) | BigInt(b);
+      v %= ORDER;
+      if (v !== 0n) return v;
+    }
+  }
+
+  return {
+    hex, big, canonicalIdentity, randScalar,
+
+    // ---- constants --------------------------------------------------------
+    ORDER,
+    F_R: ORDER,
+    FIELD_MODULUS: big(wasm.field_modulus()),
+    G1: P(wasm.g1_generator()),
+    G2: (() => {
+      const g = wasm.g2_generator();
+      return { x: [big(g[0]), big(g[1])], y: [big(g[2]), big(g[3])] };
+    })(),
+    H_POINT: P(wasm.h_point()),
+    FLAVOR_A1: 1,
+    FLAVOR_A2: 2,
+    FLAVOR_B1: 3,
+
+    // ---- curve ops / hashes ------------------------------------------------
+    g1Add: (a, b) => P(wasm.g1_add(...flatP(a), ...flatP(b))),
+    g1Mul: (p, k) => P(wasm.g1_mul(...flatP(p), hex(k))),
+    g1Neg: (p) => P(wasm.g1_neg(...flatP(p))),
+    g2Mul: (g, k) => {
+      const r = wasm.g2_mul(...flatG2(g), hex(k));
+      return { x: [big(r[0]), big(r[1])], y: [big(r[2]), big(r[3])] };
+    },
+    /** EVM ecPairing semantics: pairs = [[g1Point, g2Point], ...]. */
+    pairingCheck: (pairs) =>
+      wasm.pairing_check(pairs.flatMap(([p, q]) => [...flatP(p), ...flatG2(q)])),
+    keccakScalar: (words) => big(wasm.keccak_scalar(words.map(hex))),
+    identityScalar: (canonical) => big(wasm.identity_scalar(canonical)),
+    reduceModOrder: (v) => big(wasm.reduce_mod_order(hex(v))),
+    poseidon: (inputs) => big(wasm.poseidon(inputs.map(hex))),
+
+    // ---- ElGamal / PS ------------------------------------------------------
+    elgamalEncrypt: (M, pk, r) =>
+      CT(wasm.elgamal_encrypt(...flatP(M), ...flatP(pk), hex(r))),
+    elgamalDecrypt: (E, sk) => P(wasm.elgamal_decrypt(...flatCT(E), hex(sk))),
+    psSign(skX, skY, m, t) {
+      const r = wasm.ps_sign(hex(skX), hex(skY), hex(m), hex(t));
+      return { sigma_1: P(r, 0), sigma_2: P(r, 2) };
+    },
+    psVerify: (pkX, pkY, sig, m) =>
+      wasm.ps_verify(flatG2(pkX), flatG2(pkY),
+        ...flatP(sig.sigma_1), ...flatP(sig.sigma_2), hex(m)),
+    psRerandomize(sig, t) {
+      const r = wasm.ps_rerandomize(...flatP(sig.sigma_1), ...flatP(sig.sigma_2), hex(t));
+      return { sigma_1: P(r, 0), sigma_2: P(r, 2) };
+    },
+
+    // ---- Schnorr batch binding ---------------------------------------------
+    /** Raw UNREDUCED keccak word (what the Schnorr transcript signs). */
+    batchCommitment: (cms) => big(wasm.batch_commitment(cms.map(hex))),
+    issuerSchnorrSign(skIss, hBatch, issuer, chainid, k) {
+      const r = wasm.issuer_schnorr_sign(
+        hex(skIss), hex(hBatch), hex(issuer), hex(chainid), hex(k));
+      return { e: big(r[0]), s: big(r[1]), R: P(r, 2) };
+    },
+    issuerSchnorrVerify: (pkIss, proof, hBatch, issuer, chainid) =>
+      wasm.issuer_schnorr_verify(
+        ...flatP(pkIss),
+        [hex(proof.e), hex(proof.s), ...flatP(proof.R)],
+        hex(hBatch), hex(issuer), hex(chainid)),
+
+    // ---- Registration NIZK -------------------------------------------------
+    registrationProve(sig, m, r, pk, E, registrant, mTilde, rTilde) {
+      const o = wasm.registration_prove(
+        [...flatP(sig.sigma_1), ...flatP(sig.sigma_2)],
+        hex(m), hex(r), ...flatP(pk), flatCT(E),
+        hex(registrant), hex(mTilde), hex(rTilde));
+      return { e: big(o[0]), s_m: big(o[1]), s_r: big(o[2]),
+               A_ps: P(o, 3), T_C: P(o, 5), T_R: P(o, 7) };
+    },
+    registrationVerify: (sig, E, pk, issuerX, issuerY, proof, registrant) =>
+      wasm.registration_verify(
+        [...flatP(sig.sigma_1), ...flatP(sig.sigma_2)],
+        flatCT(E), ...flatP(pk), flatG2(issuerX), flatG2(issuerY),
+        [hex(proof.e), hex(proof.s_m), hex(proof.s_r),
+         ...flatP(proof.A_ps), ...flatP(proof.T_C), ...flatP(proof.T_R)],
+        hex(registrant)),
+
+    // ---- Chaum-Pedersen approve --------------------------------------------
+    chaumPedersenProve(eAlice, eBob, pkA, pkB, skA, rPrime,
+                       sender, spender, chainid, k1, k2) {
+      const o = wasm.chaum_pedersen_prove(
+        flatCT(eAlice), flatCT(eBob), ...flatP(pkA), ...flatP(pkB),
+        hex(skA), hex(rPrime), hex(sender), hex(spender), hex(chainid),
+        hex(k1), hex(k2));
+      return { e: big(o[0]), s1: big(o[1]), s2: big(o[2]),
+               T1: P(o, 3), T2: P(o, 5), T3: P(o, 7) };
+    },
+    chaumPedersenVerify: (eAlice, eBob, pkA, pkB, proof, sender, spender, chainid) =>
+      wasm.chaum_pedersen_verify(
+        flatCT(eAlice), flatCT(eBob), ...flatP(pkA), ...flatP(pkB),
+        [hex(proof.e), hex(proof.s1), hex(proof.s2),
+         ...flatP(proof.T1), ...flatP(proof.T2), ...flatP(proof.T3)],
+        hex(sender), hex(spender), hex(chainid)),
+
+    // ---- Verifiable decryption ---------------------------------------------
+    verifiableDecryptProve(E, sk, M, account, chainid, t) {
+      const o = wasm.verifiable_decrypt_prove(
+        flatCT(E), hex(sk), ...flatP(M), hex(account), hex(chainid), hex(t));
+      return { e: big(o[0]), s: big(o[1]), T1: P(o, 2), T2: P(o, 4) };
+    },
+    verifiableDecryptVerify: (E, pk, M, proof, account, chainid) =>
+      wasm.verifiable_decrypt_verify(
+        flatCT(E), ...flatP(pk), ...flatP(M),
+        [hex(proof.e), hex(proof.s), ...flatP(proof.T1), ...flatP(proof.T2)],
+        hex(account), hex(chainid)),
+
+    // ---- A2 issuer re-encryption binding -----------------------------------
+    issuerReencProve(skIss, rPrime, pkRec, eReg, eIss, issuer, chainid,
+                     beta, gamma, kR, kB, kS, kG) {
+      const o = wasm.issuer_reenc_prove(
+        hex(skIss), hex(rPrime), ...flatP(pkRec), flatCT(eReg), flatCT(eIss),
+        hex(issuer), hex(chainid),
+        hex(beta), hex(gamma), hex(kR), hex(kB), hex(kS), hex(kG));
+      return {
+        e: big(o[0]), s_r: big(o[1]), s_b: big(o[2]), s_s: big(o[3]), s_g: big(o[4]),
+        A1: P(o, 5), A2: P(o, 7), A3: P(o, 9), A4: P(o, 11), A5: P(o, 13),
+        Q: P(o, 15), U: P(o, 17), T: P(o, 19),
+      };
+    },
+    issuerReencVerify: (pkIss, eReg, eIss, proof, issuer, chainid) =>
+      wasm.issuer_reenc_verify(
+        ...flatP(pkIss), flatCT(eReg), flatCT(eIss),
+        [hex(proof.e), hex(proof.s_r), hex(proof.s_b), hex(proof.s_s), hex(proof.s_g),
+         ...flatP(proof.A1), ...flatP(proof.A2), ...flatP(proof.A3),
+         ...flatP(proof.A4), ...flatP(proof.A5),
+         ...flatP(proof.Q), ...flatP(proof.U), ...flatP(proof.T)],
+        hex(issuer), hex(chainid)),
+
+    // ---- Deposit coupling / B1 depositor binding ----------------------------
+    depositCoupleProve(mRec, skDep, eDep, eIss, account, chainid, b, kM, kS, kB) {
+      const o = wasm.deposit_couple_prove(
+        hex(mRec), hex(skDep), flatCT(eDep), flatCT(eIss),
+        hex(account), hex(chainid), hex(b), hex(kM), hex(kS), hex(kB));
+      return {
+        e: big(o[0]), s_m: big(o[1]), s_s: big(o[2]), s_b: big(o[3]),
+        A2: P(o, 4), A3: P(o, 6), A4: P(o, 8), P_I: P(o, 10),
+      };
+    },
+    depositCoupleVerify: (pkDep, eDep, eIss, proof, account, chainid) =>
+      wasm.deposit_couple_verify(
+        ...flatP(pkDep), flatCT(eDep), flatCT(eIss),
+        [hex(proof.e), hex(proof.s_m), hex(proof.s_s), hex(proof.s_b),
+         ...flatP(proof.A2), ...flatP(proof.A3), ...flatP(proof.A4), ...flatP(proof.P_I)],
+        hex(account), hex(chainid)),
+    b1BindProve(mDep, skDep, eDep, pkIss, account, chainid, r, b, kM, kS, kR, kB) {
+      const o = wasm.b1_bind_prove(
+        hex(mDep), hex(skDep), flatCT(eDep), ...flatP(pkIss),
+        hex(account), hex(chainid),
+        hex(r), hex(b), hex(kM), hex(kS), hex(kR), hex(kB));
+      return {
+        proof: {
+          e: big(o[0]), s_m: big(o[1]), s_s: big(o[2]), s_r: big(o[3]), s_b: big(o[4]),
+          A2: P(o, 5), A4: P(o, 7), B1: P(o, 9), B2: P(o, 11),
+          A_p: P(o, 13), P_dep: P(o, 15),
+        },
+        eDepForIss: CT(o, 17),
+      };
+    },
+    b1BindVerify: (pkDep, eDep, pkIss, eDepForIss, proof, account, chainid) =>
+      wasm.b1_bind_verify(
+        ...flatP(pkDep), flatCT(eDep), ...flatP(pkIss), flatCT(eDepForIss),
+        [hex(proof.e), hex(proof.s_m), hex(proof.s_s), hex(proof.s_r), hex(proof.s_b),
+         ...flatP(proof.A2), ...flatP(proof.A4), ...flatP(proof.B1),
+         ...flatP(proof.B2), ...flatP(proof.A_p), ...flatP(proof.P_dep)],
+        hex(account), hex(chainid)),
+
+    // ---- Notes family --------------------------------------------------------
+    noteCommitment: (flavor, v, rho, idHash, predicate) =>
+      big(wasm.note_commitment(Number(flavor), hex(v), hex(rho), hex(idHash), hex(predicate))),
+    nullifierB: (rho, idHash) => big(wasm.nullifier_b(hex(rho), hex(idHash))),
+    nullifierA: (rho, idHash) => big(wasm.nullifier_a(hex(rho), hex(idHash))),
+    idHashB1: (mIssuer, sigmaR, sigmaS) =>
+      big(wasm.id_hash_b1(hex(mIssuer), ...flatP(sigmaR), hex(sigmaS))),
+    idHashA1: (eNote, mIssuer, sigmaR, sigmaS) =>
+      big(wasm.id_hash_a1(flatCT(eNote), hex(mIssuer), ...flatP(sigmaR), hex(sigmaS))),
+    idHashA2: (eNote, eIss) => big(wasm.id_hash_a2(flatCT(eNote), flatCT(eIss))),
+    identityLeaf: (M) => big(wasm.identity_leaf(...flatP(M))),
+  };
+}

package/src/identity-web.js

@@ -0,0 +1,19 @@
+// Browser entry for the buck-identity kernel: initializes the WEB-target
+// wasm package (built by `make nix-core-build-wasm-web` into
+// the alberta-buck-kernel package) and wraps it in the same BigInt-native API node code
+// gets from identity.js.
+//
+// Always pass an explicit wasm source -- a URL string the page serves
+// (e.g. "./wasm-web/buck_identity_bg.wasm"), a Response/Promise thereof,
+// or a BufferSource -- because bundlers break wasm-bindgen's default
+// import.meta.url-relative fetch.
+
+import { wrapIdentity } from "./identity-core.js";
+
+export async function loadIdentity(wasmSource) {
+  const mod = await import("alberta-buck-kernel/web/identity");
+  await mod.default(
+    wasmSource !== undefined ? { module_or_path: wasmSource } : undefined,
+  );
+  return wrapIdentity(mod);
+}

package/src/identity.js

@@ -0,0 +1,32 @@
+// Node entry for the buck-identity kernel: loads the nodejs-target wasm
+// package (built by `make nix-core-build-wasm`) and wraps it in the
+// BigInt-native API.  The wrapper itself lives in identity-core.js
+// (environment-free); the browser loads the web-target package through
+// identity-web.js instead.
+
+import { createRequire } from "node:module";
+
+import { wrapIdentity } from "./identity-core.js";
+
+const require = createRequire(import.meta.url);
+const api = wrapIdentity(require("alberta-buck-kernel/identity"));
+
+export default api;
+export const {
+  hex, big, canonicalIdentity, randScalar,
+  ORDER, F_R, FIELD_MODULUS, G1, G2, H_POINT,
+  FLAVOR_A1, FLAVOR_A2, FLAVOR_B1,
+  g1Add, g1Mul, g1Neg, g2Mul, pairingCheck,
+  keccakScalar, identityScalar, reduceModOrder, poseidon,
+  elgamalEncrypt, elgamalDecrypt,
+  psSign, psVerify, psRerandomize,
+  batchCommitment, issuerSchnorrSign, issuerSchnorrVerify,
+  registrationProve, registrationVerify,
+  chaumPedersenProve, chaumPedersenVerify,
+  verifiableDecryptProve, verifiableDecryptVerify,
+  issuerReencProve, issuerReencVerify,
+  depositCoupleProve, depositCoupleVerify,
+  b1BindProve, b1BindVerify,
+  noteCommitment, nullifierB, nullifierA,
+  idHashB1, idHashA1, idHashA2, identityLeaf,
+} = api;

package/src/index.js

@@ -0,0 +1,13 @@
+// alberta-buck-core -- the JS side of the Alberta Buck platform.
+// See alberta-buck-platform.org and core/README.md.
+
+export { FIELDS, JournalWriter, parseJournal, mismatches, totalGas,
+         summarize } from "./journal.js";
+export { CALL_GAS, DEPLOY_GAS, Session } from "./session.js";
+export { DEV_KEYS, devAccount, anvilSession, tevmSession } from "./backends.js";
+export { MIN_SQRT_RATIO, MAX_SQRT_RATIO, HUGE, Q96, isqrt, sqrtPriceX96,
+         fullRangeTicks, spotFromSqrtPriceX96 } from "./v3.js";
+export { runDays } from "./world.js";
+export { PinWhale } from "./agents/whale.js";
+export { RoundTripTrader } from "./agents/trader.js";
+export { buildOnePool } from "./scenarios/onepool.js";

package/src/journal.js

@@ -0,0 +1,86 @@
+// Journal: the shared JSONL operation record of a ChainSession run.
+//
+// Schema (alberta-buck-platform.org, Layer 1; pinned by
+// core/vectors/journal-sample.jsonl, asserted identically by the Python
+// suite): one JSON object per line with fields
+//   i, tag, op, fn, sender, expect, outcome, matched, gas, tx, block, err
+// Unknown fields are ignored; extra whitespace/blank lines are tolerated.
+//
+// JournalWriter mirrors buck_core.session.Journal: entries in FIELDS
+// order, compact separators, missing fields as "" -- so identical runs
+// produce byte-identical lines across languages.  It writes through a
+// caller-supplied sink so this module stays environment-agnostic; use
+// nodefs.js fileJournalWriter() for a file sink in Node.
+
+const REQUIRED = ["i", "op", "fn", "expect", "outcome", "matched"];
+
+export const FIELDS = ["i", "tag", "op", "fn", "sender", "expect", "outcome",
+                       "matched", "gas", "tx", "block", "err"];
+
+export class JournalWriter {
+  /** @param {(line: string) => void} sink called with one JSONL line per entry */
+  constructor(sink) {
+    this.sink = sink;
+    this.seq = 0;
+  }
+
+  /** Record one entry; fills schema order, returns the entry object. */
+  record(fields) {
+    this.seq += 1;
+    const entry = { i: this.seq };
+    for (const f of FIELDS) {
+      if (f !== "i") entry[f] = fields[f] ?? "";
+    }
+    this.sink(JSON.stringify(entry) + "\n");
+    return entry;
+  }
+}
+
+/** Parse JSONL journal text into an array of entry objects. */
+export function parseJournal(text) {
+  const entries = [];
+  for (const [n, raw] of text.split("\n").entries()) {
+    const line = raw.trim();
+    if (!line) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (e) {
+      throw new Error(`journal line ${n + 1}: invalid JSON: ${e.message}`);
+    }
+    for (const f of REQUIRED) {
+      if (!(f in entry)) {
+        throw new Error(`journal line ${n + 1}: missing field '${f}'`);
+      }
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+/** Entries whose outcome contradicted their declared expectation. */
+export function mismatches(entries) {
+  return entries.filter((e) => e.matched === false);
+}
+
+/** Total gasUsed across entries. */
+export function totalGas(entries) {
+  return entries.reduce((sum, e) => sum + (e.gas ?? 0), 0);
+}
+
+/** One-object rollup of a journal: op counts, reverts, mismatches, gas. */
+export function summarize(entries) {
+  const ops = {};
+  let reverts = 0;
+  for (const e of entries) {
+    ops[e.op] = (ops[e.op] ?? 0) + 1;
+    if (e.outcome === "revert") reverts += 1;
+  }
+  return {
+    entries: entries.length,
+    ops,
+    reverts,
+    mismatches: mismatches(entries).length,
+    gas: totalGas(entries),
+  };
+}

package/src/nodefs.js

@@ -0,0 +1,52 @@
+// Node-only IO glue: repo/artifact discovery and file journal sinks.
+// Keep environment-specific imports here so session.js/journal.js/v3.js
+// stay loadable in the browser (Phase 4).
+
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { JournalWriter } from "./journal.js";
+
+/** The repository checkout root: ALBERTA_BUCK_REPO, or walk up from cwd
+ *  (then from this file) looking for foundry.toml -- the same resolution
+ *  the Python side uses (buck_core.artifacts.repo_root). */
+export function repoRoot() {
+  const starts = [];
+  if (process.env.ALBERTA_BUCK_REPO) starts.push(process.env.ALBERTA_BUCK_REPO);
+  starts.push(process.cwd(), dirname(new URL(import.meta.url).pathname));
+  for (const start of starts) {
+    let p = resolve(start);
+    for (;;) {
+      if (existsSync(join(p, "foundry.toml"))) return p;
+      const up = dirname(p);
+      if (up === p) break;
+      p = up;
+    }
+  }
+  throw new Error(
+    "alberta-buck repo root not found (looked for foundry.toml); " +
+    "set ALBERTA_BUCK_REPO or run from inside the repo checkout");
+}
+
+/** Return {abi, bytecode} for out/<solFile or name>.sol/<name>.json. */
+export function loadArtifact(name, solFile = null) {
+  const f = join(repoRoot(), "out", `${solFile ?? name}.sol`, `${name}.json`);
+  const art = JSON.parse(readFileSync(f, "utf8"));
+  return { abi: art.abi, bytecode: art.bytecode.object };
+}
+
+/** True when the Foundry artifacts are built (tests skip when not). */
+export function artifactsAvailable() {
+  try {
+    loadArtifact("MockERC20");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** A JournalWriter appending JSONL lines to `path`. */
+export function fileJournalWriter(path) {
+  mkdirSync(dirname(resolve(path)), { recursive: true });
+  return new JournalWriter((line) => appendFileSync(path, line));
+}

package/src/prices.js

@@ -0,0 +1,38 @@
+// Seeded synthetic price walk -- deterministic BigInt-only math so any
+// platform (or a re-run) reproduces the same path bit-for-bit.  The demo's
+// stand-in for the Python sim's CSV Brownian-bridge quotes; the Stage-4
+// parity mini-scenario pins its targets in core/vectors/mini-scenario.json
+// instead (no cross-language RNG at all).
+
+/** A 64-bit LCG (MMIX constants) over BigInt. */
+export function lcg(seed) {
+  let s = BigInt(seed) & ((1n << 64n) - 1n);
+  return () => {
+    s = (s * 6364136223846793005n + 1442695040888963407n) & ((1n << 64n) - 1n);
+    return s;
+  };
+}
+
+/**
+ * A multiplicative random walk: each step moves the price by a draw in
+ * [-stepBp, +stepBp] basis points.
+ *
+ * @param opts.seed    walk seed
+ * @param opts.start   starting price (quote base units per whole token)
+ * @param opts.stepBp  max per-step move in basis points (default 150)
+ * @param opts.steps   path length
+ * @returns BigInt[] of length `steps` (walk[0] === start)
+ */
+export function seededWalk({ seed, start, stepBp = 150, steps }) {
+  const next = lcg(seed);
+  const out = [BigInt(start)];
+  const span = BigInt(2 * stepBp + 1);
+  while (out.length < steps) {
+    const delta = (next() % span) - BigInt(stepBp);   // [-stepBp, +stepBp]
+    const prev = out[out.length - 1];
+    let p = (prev * (10_000n + delta)) / 10_000n;
+    if (p < 1n) p = 1n;
+    out.push(p);
+  }
+  return out;
+}

package/src/router.js

@@ -0,0 +1,76 @@
+// REAL Uniswap periphery for JS worlds: the Universal Router deploy
+// recipe the Python sim proved on anvil (deploy.py), and the
+// V3_SWAP_EXACT_IN encoding (mirroring alberta_buck/sim/router.py).
+//
+// The pools were always real (UniswapV3Factory/Pool); SimLP only stood in
+// for the periphery.  Doctrine: SimLP remains for simulation god-modes
+// (whale pinning, liquidity seeding); agent and USER swaps go through the
+// real router -- the code path an integrator copies, and the surface real
+// JS AMM tooling (@uniswap/v3-sdk et al.) can be pointed at.
+//
+// Wiring facts (proven by the Python sim, mirrored here):
+//   * permit2 is a DUMMY address: swaps use the pre-fund route
+//     (transfer the input to the router, execute with payerIsUser=false),
+//     so Permit2 is never consulted.  Real Permit2 is optional follow-up
+//     for signature-based approvals.
+//   * poolInitCodeHash = keccak of OUR compiled UniswapV3Pool creation
+//     bytecode -- the router computes pool addresses via CREATE2, and the
+//     locally-built pool hash differs from mainnet's canonical one.
+//   * in BUCK worlds the router must be identity-bound public+carrying
+//     (it transiently custodies BUCK mid-route); deploy.py shows the bind.
+
+import { encodeAbiParameters, encodePacked, keccak256 } from "viem";
+
+export const ZERO_ADDR = "0x" + "00".repeat(20);
+export const DUMMY_PERMIT2 = "0x" + "be".repeat(20);   // pre-fund route: unused
+
+/**
+ * Deploy the Universal Router from the vendored artifact
+ * (alberta_buck/sim/artifacts/UniversalRouter.json), wired exactly as the
+ * Python sim wires it.  RouterParameters field NAMES come from the
+ * artifact's ABI; the VALUES follow deploy.py's order.
+ *
+ * @param session     a Session (deployer pays)
+ * @param urArtifact  the parsed UniversalRouter.json artifact
+ * @param opts.weth         WETH9 address (unused by V3 swaps; real for fidelity)
+ * @param opts.v3Factory    our UniswapV3Factory address
+ * @param opts.poolInitCode our UniswapV3Pool CREATION bytecode (0x-hex)
+ */
+export async function deployUniversalRouter(session, urArtifact,
+    { weth, v3Factory, poolInitCode, gas = 15_000_000n }) {
+  const ctor = urArtifact.abi.find((e) => e.type === "constructor");
+  const comps = ctor.inputs[0].components;
+  const vals = [DUMMY_PERMIT2, weth, ZERO_ADDR, v3Factory,
+                "0x" + "00".repeat(32), keccak256(poolInitCode),
+                ZERO_ADDR, ZERO_ADDR, ZERO_ADDR, ZERO_ADDR];
+  if (comps.length !== vals.length) {
+    throw new Error(`UniversalRouter constructor has ${comps.length} ` +
+                    `params; the deploy.py recipe wires ${vals.length}`);
+  }
+  const params = Object.fromEntries(comps.map((c, i) => [c.name, vals[i]]));
+  // Accept the raw forge-artifact shape ({bytecode: {object}}) and the
+  // flattened bundle shape ({bytecode: "0x.."}) alike.
+  const bytecode = urArtifact.bytecode.object ?? urArtifact.bytecode;
+  return session.deploy(
+    { abi: urArtifact.abi, bytecode },
+    [params], { name: "UniversalRouter", gas });
+}
+
+/** [tokenA, fee0, tokenB, fee1, tokenC, ...] -> packed V3 path bytes. */
+export function encodePath(tokensFees) {
+  const types = tokensFees.map((_, i) => (i % 2 === 0 ? "address" : "uint24"));
+  return encodePacked(types, tokensFees);
+}
+
+/**
+ * (commands, inputs) for UniversalRouter.execute V3_SWAP_EXACT_IN on the
+ * pre-fund route (payerIsUser=false: the router pays from its own
+ * balance, so transfer amountIn to the router first).
+ */
+export function urExecArgs(recipient, amountIn, path) {
+  const input = encodeAbiParameters(
+    [{ type: "address" }, { type: "uint256" }, { type: "uint256" },
+     { type: "bytes" }, { type: "bool" }, { type: "uint256[]" }],
+    [recipient, amountIn, 0n, path, false, []]);
+  return ["0x00", [input]];   // 0x00 = V3_SWAP_EXACT_IN
+}