alberta-buck-core 0.1.1

package/src/session.js

@@ -0,0 +1,122 @@
+// ChainSession, JS side: send/call/deploy with declared expectations and
+// the shared JSONL journal (alberta-buck-platform.org, Layer 1).
+//
+// The peer of buck_core.session.Web3Session with identical semantics:
+//   * expect: "ok" (default) or "revert".  An unexpected revert THROWS
+//     (with the Solidity reason, extracted by replaying the call at the
+//     receipt's block); an unexpected success logs a warning.  Either way
+//     the outcome is journaled and contradictions accumulate in
+//     session.mismatches.
+//   * reads (call) are not journaled.
+//
+// Works over any viem-compatible client -- anvil/testnets by HTTP
+// transport, Tevm's in-process MemoryClient in Node or the browser (see
+// backends.js).  Contract handles are plain {abi, address} objects.
+
+export const CALL_GAS = 12_000_000n;
+export const DEPLOY_GAS = 55_000_000n;
+
+export class Session {
+  /**
+   * @param client viem client with public + wallet actions
+   * @param opts.account default viem Account for sends/deploys
+   * @param opts.journal a JournalWriter (or null: journaling off)
+   * @param opts.txOverrides merged into every tx, e.g. {gasPrice: 0n} on
+   *        the zero-fee anvil profile the Python sim uses
+   */
+  constructor(client, { account, journal = null, txOverrides = {} } = {}) {
+    this.client = client;
+    this.account = account;
+    this.journal = journal;
+    this.txOverrides = txOverrides;
+    this.mismatches = [];
+    this.lastRevertReason = "";
+  }
+
+  /** A contract handle: just {abi, address}. */
+  contractAt(abi, address) {
+    return { abi, address };
+  }
+
+  async call(contract, functionName, args = []) {
+    return this.client.readContract({
+      address: contract.address, abi: contract.abi, functionName, args,
+    });
+  }
+
+  async send(contract, functionName, args = [],
+             { account, gas = CALL_GAS, value = 0n,
+               expect = "ok", tag = "" } = {}) {
+    const acct = account ?? this.account;
+    const hash = await this.client.writeContract({
+      address: contract.address, abi: contract.abi, functionName, args,
+      account: acct, gas, value, chain: null, ...this.txOverrides,
+    });
+    const rcpt = await this.client.waitForTransactionReceipt({ hash });
+    const ok = rcpt.status === "success";
+    const err = ok ? "" : await this.#revertReason(
+      contract, functionName, args, acct, gas, value, rcpt.blockNumber);
+    this.lastRevertReason = err;
+    const entry = this.#journalOp(
+      "send", functionName, acct.address, expect, ok, rcpt, err, tag);
+    // expect "either": a legitimately-uncertain send (e.g. a funding-gate
+    // mint that reverting IS the signal) -- journaled, never a mismatch;
+    // the caller reads rcpt.status.
+    if (ok && expect === "revert") {
+      console.warn(`expected REVERT but ${functionName} succeeded ` +
+                   `(tag=${tag} tx=${rcpt.transactionHash})`);
+      this.mismatches.push(entry);
+    }
+    if (!ok && expect === "ok") {
+      this.mismatches.push(entry);
+      throw new Error(`tx reverted: ${functionName} :: ${err}`);
+    }
+    return rcpt;
+  }
+
+  /** Deploy from an {abi, bytecode} artifact; returns a contract handle. */
+  async deploy(artifact, args = [],
+               { account, gas = DEPLOY_GAS, name = "", tag = "" } = {}) {
+    const acct = account ?? this.account;
+    const hash = await this.client.deployContract({
+      abi: artifact.abi, bytecode: artifact.bytecode, args,
+      account: acct, gas, chain: null, ...this.txOverrides,
+    });
+    const rcpt = await this.client.waitForTransactionReceipt({ hash });
+    const ok = rcpt.status === "success";
+    this.#journalOp("deploy", "constructor", acct.address, "ok", ok, rcpt,
+                    ok ? "" : "deploy reverted", tag || `deploy:${name}`);
+    if (!ok) throw new Error(`deploy ${name} reverted`);
+    return this.contractAt(artifact.abi, rcpt.contractAddress);
+  }
+
+  async #revertReason(contract, functionName, args, acct, gas, value, block) {
+    try {
+      await this.client.simulateContract({
+        address: contract.address, abi: contract.abi, functionName, args,
+        account: acct, gas, value, blockNumber: block,
+      });
+    } catch (e) {
+      // Prefer the decoded Solidity reason: a require string ("SPL") or a
+      // custom error name (ERC20InsufficientBalance) over viem's generic
+      // "The contract function ... reverted." shortMessage.
+      const revert = e.walk?.((c) => c?.name === "ContractFunctionRevertedError");
+      const reason = revert?.reason ?? revert?.data?.errorName;
+      return String(reason ?? e.shortMessage ?? e.message ?? e).slice(0, 400);
+    }
+    return "";
+  }
+
+  #journalOp(op, fn, sender, expect, ok, rcpt, err, tag) {
+    const entry = {
+      tag, op, fn, sender,
+      expect, outcome: ok ? "ok" : "revert",
+      matched: (ok ? "ok" : "revert") === expect,
+      gas: Number(rcpt.gasUsed ?? 0n),
+      tx: rcpt.transactionHash ?? "",
+      block: Number(rcpt.blockNumber ?? 0n),
+      err,
+    };
+    return this.journal ? this.journal.record(entry) : entry;
+  }
+}

package/src/v3.js

@@ -0,0 +1,48 @@
+// Uniswap V3 price/tick math, BigInt throughout -- mirrors
+// alberta_buck/sim/router.py (sqrt_price_x96, full_range_ticks) exactly.
+
+export const MIN_SQRT_RATIO = 4295128739n;
+export const MAX_SQRT_RATIO =
+  1461446703485210103287273052203988822378723970342n;
+
+/** int256 "swap everything until the price limit" amount (whale snaps). */
+export const HUGE = (1n << 127n) - 1n;
+
+export const Q96 = 1n << 96n;
+
+/** Integer square root (floor), Newton's method on BigInt. */
+export function isqrt(n) {
+  if (n < 0n) throw new Error("isqrt of negative");
+  if (n < 2n) return n;
+  let x = 1n << (BigInt(n.toString(2).length + 1) >> 1n);
+  for (;;) {
+    const y = (x + n / x) >> 1n;
+    if (y >= x) return x;
+    x = y;
+  }
+}
+
+/** sqrtPriceX96 so 1 `baseAmt` of base costs `quoteAmt` of quote
+ *  (token0/token1 by address order, exactly as router.py). */
+export function sqrtPriceX96(base, baseAmt, quote, quoteAmt) {
+  const baseIs0 = base.toLowerCase() < quote.toLowerCase();
+  const a0 = baseIs0 ? baseAmt : quoteAmt;
+  const a1 = baseIs0 ? quoteAmt : baseAmt;
+  return isqrt((a1 << 192n) / a0);
+}
+
+/** Full-range tick bounds for a spacing; truncates toward zero to stay
+ *  inside [-887272, 887272], matching Solidity (MIN_TICK/spacing)*spacing. */
+export function fullRangeTicks(spacing) {
+  const hi = Math.trunc(887272 / spacing) * spacing;
+  return [-hi, hi];
+}
+
+/** Spot price of one whole token (10^dec base units) in quote base units,
+ *  from a pool's sqrtPriceX96.  The inverse of sqrtPriceX96(). */
+export function spotFromSqrtPriceX96(sqrtX96, token, tokenDec, quote) {
+  const tokenIs0 = token.toLowerCase() < quote.toLowerCase();
+  const unit = 10n ** BigInt(tokenDec);
+  const num = sqrtX96 * sqrtX96;
+  return tokenIs0 ? (num * unit) >> 192n : (unit << 192n) / num;
+}

package/src/wallet-core.js

@@ -0,0 +1,75 @@
+// Structured wrapper over the buck-wallet + buck-registry wasm kernel --
+// the environment-free CORE.  `wrapWallet(wasm)` takes the raw wasm
+// module (the same buck_identity package: one blob carries all three
+// kernels) and returns the wallet/registry API:
+//
+//   receipt cores    canonical JSON text (the serialization IS the object)
+//   structured args  plain objects in the vector-fixture shapes --
+//                    "0x..." hex words, {x, y} points, {R, C} ciphertexts
+//   certificates     Uint8Array wire bytes (the Python-pinned formats)
+//   accumulators     the MerkleTree / Aggregator wasm classes
+//
+// Deterministic: every nonce rides inside the args (`nonces: {...}`),
+// exactly the order the Python reference draws them.
+
+export function wrapWallet(wasm) {
+  const toText = (v) => (typeof v === "string" ? v : JSON.stringify(v));
+  const enc = new TextEncoder();
+  const toBytes = (v) => (typeof v === "string" ? enc.encode(v) : v);
+
+  return {
+    // ---- canonical dialect + envelope ---------------------------------
+    canonicalJson: (v) => wasm.wallet_canonical_json(toText(v)),
+    canonicalIdentityData: (v) => wasm.wallet_canonical_identity_data(toText(v)),
+    receiptId: (canonical, prefixLen = 12) =>
+      wasm.wallet_receipt_id(toBytes(canonical), prefixLen),
+    envelopeText: (canonical, width = 64) =>
+      wasm.wallet_envelope_text(toBytes(canonical), width),
+    parseEnvelope: (text) => wasm.wallet_parse_envelope(text),
+
+    // ---- receipts ------------------------------------------------------
+    /** Build any receipt kind from named args; returns canonical text. */
+    buildReceipt: (args) => wasm.wallet_build_receipt(toText(args)),
+    /** Tier-1 offline verify -> {ok, reason, identity_M, value}. */
+    verifyReceipt: (core) => JSON.parse(wasm.wallet_verify_receipt(toText(core))),
+
+    // ---- unilateral identity-targeted Note flows -----------------------
+    mintUnilateralA2: (a) => JSON.parse(wasm.wallet_mint_unilateral_a2(toText(a))),
+    makeReceiptA2: (a) => JSON.parse(wasm.wallet_make_receipt_a2(toText(a))),
+    verifyReceiptA2: (a) => JSON.parse(wasm.wallet_verify_receipt_a2(toText(a))),
+    mintUnilateralA1: (a) => JSON.parse(wasm.wallet_mint_unilateral_a1(toText(a))),
+    makeReceiptA1: (a) => JSON.parse(wasm.wallet_make_receipt_a1(toText(a))),
+    verifyReceiptA1: (a) => JSON.parse(wasm.wallet_verify_receipt_a1(toText(a))),
+
+    // ---- issuer ceremony -----------------------------------------------
+    issueCredential: (a) => JSON.parse(wasm.wallet_issue_credential(toText(a))),
+
+    // ---- registry ------------------------------------------------------
+    registry: {
+      /** -> [e, s, Rx, Ry] hex words. */
+      schnorrSign: (sk, msgHash, registryId, chainid, k) =>
+        wasm.registry_schnorr_sign(sk, msgHash, registryId, chainid, k),
+      schnorrVerify: (pk, e, s, r, msgHash, registryId, chainid) =>
+        wasm.registry_schnorr_verify(
+          pk.x, pk.y, e, s, r.x, r.y, msgHash, registryId, chainid),
+      /** -> SignedCertificate wire bytes (Python-pinned format). */
+      signCertificate: (sk, registryId, canonical, serial, issuedAt, expiresAt, chainid, k) =>
+        wasm.registry_sign_certificate(
+          sk, registryId, canonical,
+          BigInt(serial), BigInt(issuedAt), BigInt(expiresAt), chainid, k),
+      verifyCertificate: (wire, chainid) =>
+        wasm.registry_verify_certificate(wire, chainid),
+      sealCertificate: (wire, clientPk, r) =>
+        wasm.registry_seal_certificate(wire, clientPk.x, clientPk.y, r),
+      unsealCertificate: (envelope, clientSk) =>
+        wasm.registry_unseal_certificate(envelope, clientSk),
+      /** Sub-tree + aggregator path pair -> bool. */
+      verifyFullProof: (subProof, aggProof) =>
+        wasm.registry_verify_full_proof(toText(subProof), toText(aggProof)),
+      /** The identity Merkle accumulator (stateful wasm class). */
+      MerkleTree: wasm.MerkleTree,
+      /** The central sub-root aggregator (stateful wasm class). */
+      Aggregator: wasm.Aggregator,
+    },
+  };
+}

package/src/wallet.js

@@ -0,0 +1,23 @@
+// Node entry for the buck-wallet + buck-registry kernels: loads the
+// nodejs-target wasm package (the same buck_identity blob; built by
+// `make nix-core-build-wasm`) and wraps it in the structured API.  The
+// wrapper itself lives in wallet-core.js (environment-free); a browser
+// loads the web-target package and calls wrapWallet itself.
+
+import { createRequire } from "node:module";
+
+import { wrapWallet } from "./wallet-core.js";
+
+const require = createRequire(import.meta.url);
+const api = wrapWallet(require("alberta-buck-kernel/identity"));
+
+export default api;
+export const {
+  canonicalJson, canonicalIdentityData,
+  receiptId, envelopeText, parseEnvelope,
+  buildReceipt, verifyReceipt,
+  mintUnilateralA2, makeReceiptA2, verifyReceiptA2,
+  mintUnilateralA1, makeReceiptA1, verifyReceiptA1,
+  issueCredential,
+  registry,
+} = api;

package/src/world.js

@@ -0,0 +1,21 @@
+// The agent loop, deliberately tiny (understandability is a decision of
+// record).  A "world" is a plain object the scenario builder returns --
+// at minimum {session}, plus whatever contract handles the agents need.
+// An agent is any object with optional `setup(world)` and required
+// `act(world, day, tick)`, both async.  Mirrors the Python sim's
+// setup()/act(day, tick) shape.
+
+export async function runDays(world, agents,
+                              { days, ticksPerDay = 1, onDay = null } = {}) {
+  for (const a of agents) {
+    if (a.setup) await a.setup(world);
+  }
+  for (let day = 0; day < days; day++) {
+    for (let tick = 0; tick < ticksPerDay; tick++) {
+      for (const a of agents) {
+        await a.act(world, day, tick);
+      }
+    }
+    if (onDay) await onDay(day);
+  }
+}