alberta-buck-core 0.1.1

package/README.md

@@ -0,0 +1,66 @@
+# alberta-buck-core
+
+The JavaScript side of the Alberta Buck platform: one testing API over every
+EVM backend, an agent simulation platform that runs in a browser, and
+BigInt-native wrappers around the WebAssembly kernels.
+
+- **`Session`** -- the ChainSession API. Send, call and deploy against Tevm
+  in-process, anvil, or a public testnet, with the same code. Every
+  state-changing operation declares whether it is expected to succeed or
+  revert, so expectation mismatches are first-class results rather than
+  surprises.
+- **Journal** -- an append-only JSONL record of every operation: tag, op,
+  sender, expectation, outcome, gas, tx hash, block, error. Journals make
+  runs auditable, diffable across backends *and across languages* (the
+  Python platform writes the same schema), and replayable for demos.
+- **Agents and worlds** -- `runDays`, whales, round-trip traders, and the
+  scenario builders that stand up a pool world.
+- **Kernel wrappers** -- `identity.js` and `wallet.js` wrap
+  [`alberta-buck-kernel`](https://www.npmjs.com/package/alberta-buck-kernel)
+  in a BigInt-native API; `identity-web.js` does the same for the browser,
+  taking an explicit wasm source because bundlers break wasm-bindgen's
+  default relative fetch.
+
+## Install
+
+```sh
+npm install alberta-buck-core
+```
+
+## Use
+
+```js
+import { tevmSession, runDays } from "alberta-buck-core";
+
+const session = await tevmSession();          // or anvilSession(...)
+// ... deploy contracts, then let agents run simulated days
+```
+
+```js
+import identity from "alberta-buck-core/identity";
+
+const scalar = identity.reduceModOrder(12345n);
+```
+
+Subpaths map onto the modules directly: `alberta-buck-core/session`,
+`/journal`, `/identity`, `/wallet`, `/world`, `/v3`, and so on.
+
+Contract artifacts are not bundled here. A world needs the compiled
+contracts, which ship separately so that Uniswap's own artifacts come from
+Uniswap rather than from us.
+
+## Status
+
+0.1.0, prototype. Unaudited software for a monetary system, published so the
+simulation and identity work can be reproduced and built on -- not for
+custody of anything real.
+
+## Licence
+
+CAL-1.0 (Cryptographic Autonomy License v1.0). Beyond the usual copyleft,
+CAL requires that anyone you provide this software's functionality to
+receives their own data and is not locked out of it by cryptographic or
+technical means. See
+[LICENSING.md](https://github.com/alberta-buck/alberta-buck/blob/master/LICENSING.md).
+
+Repository: <https://github.com/alberta-buck/alberta-buck>

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "alberta-buck-core",
+  "version": "0.1.1",
+  "description": "Alberta Buck core platform (JS): the ChainSession API over Tevm/anvil/testnets with expectation journaling, the agent simulation platform, and the BigInt-native wrappers around the WebAssembly kernels",
+  "type": "module",
+  "license": "CAL-1.0",
+  "author": "Perry Kundert <perry@dominionrnd.com>",
+  "homepage": "https://github.com/alberta-buck/alberta-buck",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alberta-buck/alberta-buck.git",
+    "directory": "core/js"
+  },
+  "bugs": "https://github.com/alberta-buck/alberta-buck/issues",
+  "keywords": [
+    "ethereum",
+    "stablecoin",
+    "simulation",
+    "viem",
+    "tevm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "workspaces": [
+    "kernel"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./*": "./src/*.js"
+  },
+  "dependencies": {
+    "alberta-buck-kernel": "0.1.1",
+    "tevm": "^1.0.0-next.149",
+    "viem": "^2.54.2"
+  },
+  "devDependencies": {
+    "buffer": "^6.0.3",
+    "esbuild": "^0.28.1",
+    "wasm-pack": "^0.15.0"
+  }
+}

package/src/agents/arb.js

@@ -0,0 +1,61 @@
+// ParityArb: keeps the pool TRIANGLE consistent -- TOKEN/BUCK vs the
+// price implied by TOKEN/USDC x BUCK/USDC.  When the basket pool drifts
+// from the implied price by more than thresholdBp, it routes the
+// profitable triangle through the REAL Universal Router (both legs
+// start and end in USDC, so the arb needs no identity: BUCK only
+// passes through the bound router mid-hop), sized small and iterated
+// until the gap closes or maxIters runs out.
+//
+// This is the agent that makes basketValueInBuck MEAN something: the
+// controller reads the TOKEN/BUCK pools, the whale pins TOKEN/USDC to
+// the reference feeds, and the arb ties the two together -- so BUCK
+// supply/demand pressure in the floating BUCK/USDC pool propagates
+// into the observable the PID defends.
+
+export class ParityArb {
+  /**
+   * @param opts.size        USDC base units per triangle leg
+   * @param opts.thresholdBp act when |divergence| exceeds this
+   * @param opts.maxIters    triangles per token per tick
+   */
+  constructor({ size = 2_000n * 10n ** 6n, thresholdBp = 100n,
+                maxIters = 3 } = {}) {
+    Object.assign(this, { size, thresholdBp, maxIters });
+    this.triangles = 0;          // ops counter, for the curious
+  }
+
+  async setup(world) {
+    this.me = world.session.account;    // the deployer account arbs
+    await world.fiatIn(this.me, 10_000_000n * 10n ** 6n,
+                       { tag: "arb:endow" });
+  }
+
+  async act(world, day, tick) {
+    if (tick !== 0) return;
+    const { usdc, buck, fees } = world;
+    for (let i = 0; i < world.tokens.length; i++) {
+      const t = world.tokens[i];
+      for (let iter = 0; iter < this.maxIters; iter++) {
+        const [pTU, pUB, pTB] = await Promise.all(
+          [world.spotUsd(i), world.spotUB(), world.spotBuck(i)]);
+        const implied = (pTU * 1_000_000n) / pUB;
+        const div = ((pTB - implied) * 10_000n) / implied;
+        if (div > -this.thresholdBp && div < this.thresholdBp) break;
+
+        // TOKEN rich in BUCK: buy it direct, sell it via the BUCK legs
+        // (and vice versa).  Both directions push pTB toward implied.
+        const inPath = div > 0n
+          ? [usdc.address, fees.usdc, t.erc20.address]
+          : [usdc.address, fees.ub, buck.address, fees.buck, t.erc20.address];
+        const outPath = div > 0n
+          ? [t.erc20.address, fees.buck, buck.address, fees.ub, usdc.address]
+          : [t.erc20.address, fees.usdc, usdc.address];
+        const got = await world.route(inPath, this.size, this.me,
+          { tag: `arb:${t.sym}:in:d${day}` });
+        await world.route(outPath, got, this.me,
+          { tag: `arb:${t.sym}:out:d${day}` });
+        this.triangles++;
+      }
+    }
+  }
+}

package/src/agents/saver.js

@@ -0,0 +1,72 @@
+// BasketSaver: the live evolution of prototypes/basket-investor.js --
+// USDC wealth deployed into the BuckBasket for a term, acquiring the
+// constituent TOKEN via whichever route quotes the better after-swap
+// valuation (direct, or through BUCK -- world.buyTokenBest).  A single
+// registered EOA: deposits need no identity, but redemption pays BUCK,
+// so setup runs the real onboarding ceremony.
+//
+// ROI accounting follows the Python DM agents: USD committed vs USD
+// realized, with dollar-days so returns annualize
+// (profitUsd * 365n / dollarDays).
+
+import { fundAccount, onboard } from "../buckworld.js";
+
+export class BasketSaver {
+  /**
+   * @param opts.account  fresh viem account (funded + onboarded in setup)
+   * @param opts.budget   USDC base units to deploy per cycle
+   * @param opts.holdDays days from deposit to redemption
+   * @param opts.tokenIdx which basket constituent to acquire
+   * @param opts.fields   identity KYC fields (defaults provided)
+   */
+  constructor({ account, budget = 25_000n * 10n ** 6n, holdDays = 60,
+                tokenIdx = 0, fields = null }) {
+    Object.assign(this, { account, budget, holdDays, tokenIdx, fields });
+    this.position = null;
+    this.ledger = [];        // {day, event, usd} -- the ROI chart
+    this.profitUsd = 0n;
+    this.dollarDays = 0n;
+  }
+
+  async setup(world) {
+    await fundAccount(world, this.account.address);
+    await onboard(world, this.account, this.fields ?? {
+      given_name: "Sana", family_name: "Saver",
+      id_type: "Alberta Identity Card", id_number: "AIC-2026-0055501",
+      jurisdiction: "Alberta, Canada", date_of_birth: "1991-05-05",
+      issued_at: "2026-07-04T00:00:00Z", epoch: 42,
+    });
+    await world.fiatIn(this.account, this.budget, { tag: "saver:endow" });
+    this.usdc = this.budget;
+  }
+
+  async act(world, day, tick) {
+    if (tick !== 0) return;
+
+    if (!this.position) {
+      if (this.usdc < 1_000n * 10n ** 6n) return;   // spent: hold
+      const spend = this.usdc;
+      const { out, viaBuck } = await world.buyTokenBest(
+        this.tokenIdx, spend, this.account, { tag: `saver:acquire:d${day}` });
+      const { receiptId } = await world.basketDeposit(
+        this.tokenIdx, out, this.account, { tag: `saver:deposit:d${day}` });
+      this.usdc = 0n;
+      this.position = { receiptId, day, costUsd: spend };
+      this.ledger.push({ day, event: "deposit", usd: -spend, viaBuck });
+      return;
+    }
+
+    const mark = await world.receiptValueUsd(this.position.receiptId, day);
+    this.ledger.push({ day, event: "mark", usd: mark });
+
+    if (day - this.position.day >= this.holdDays) {
+      const gotUsd = await world.basketRedeem(
+        this.position.receiptId, this.account, { tag: `saver:redeem:d${day}` });
+      this.profitUsd += gotUsd - this.position.costUsd;
+      this.dollarDays += this.position.costUsd
+                       * BigInt(day - this.position.day);
+      this.ledger.push({ day, event: "redeem", usd: gotUsd });
+      this.position = null;    // holds the redeemed assets; one cycle v1
+    }
+  }
+}

package/src/agents/trader.js

@@ -0,0 +1,70 @@
+// RoundTripTrader: the walking-skeleton "arb-shaped" agent.  Each day it
+// sells a fixed TOKEN amount into the pool and buys back with the quote
+// proceeds -- two real V3 swaps through SimLP, both journaled.  On day 0
+// it also demonstrates a DECLARED failure: a swap whose price limit is on
+// the wrong side, sent with expect:"revert" (Uniswap's SPL check), which
+// the journal records as matched rather than an error.
+//
+// Swap mechanics (SimLP pays the pool from its own balance): fund SimLP
+// with the input token, then SimLP.swap(pool, recipient=self, ...) sends
+// the output to the trader.
+
+import { MIN_SQRT_RATIO, MAX_SQRT_RATIO } from "../v3.js";
+
+export class RoundTripTrader {
+  /**
+   * @param opts.simlp  SimLP handle    @param opts.pool  pool handle
+   * @param opts.token  TOKEN handle (ERC20 abi) -- the trader's base asset
+   * @param opts.quote  quote handle (ERC20 abi)
+   * @param opts.amount TOKEN base units to round-trip each day
+   * @param opts.account viem Account for this agent (defaults to session's)
+   */
+  constructor({ simlp, pool, token, quote, amount, account = undefined }) {
+    Object.assign(this, { simlp, pool, token, quote, amount, account });
+  }
+
+  async setup(world) {
+    this.tokenIs0 =
+      this.token.address.toLowerCase() < this.quote.address.toLowerCase();
+    this.me = (this.account ?? world.session.account).address;
+    this.opts = { account: this.account };
+  }
+
+  #swapArgs(zeroForOne, amountIn) {
+    // exact-in (positive amount), price limit wide open on the swap side
+    const limit = zeroForOne ? MIN_SQRT_RATIO + 1n : MAX_SQRT_RATIO - 1n;
+    const [t0, t1] = this.tokenIs0
+      ? [this.token.address, this.quote.address]
+      : [this.quote.address, this.token.address];
+    return [this.pool.address, this.me, zeroForOne, amountIn, limit, t0, t1];
+  }
+
+  async act(world, day, tick) {
+    if (tick !== 0) return;
+    const s = world.session;
+
+    if (day === 0) {
+      // Declared failure: zeroForOne with a limit ABOVE spot always
+      // violates Uniswap's sqrt-price-limit require ("SPL").
+      const bad = this.#swapArgs(true, this.amount);
+      bad[4] = MAX_SQRT_RATIO - 1n;
+      await s.send(this.simlp, "swap", bad,
+        { ...this.opts, expect: "revert", tag: `trader:spl-demo:d${day}` });
+    }
+
+    // Sell TOKEN -> quote: fund SimLP, swap with self as recipient.
+    const quoteBefore = await s.call(this.quote, "balanceOf", [this.me]);
+    await s.send(this.token, "transfer", [this.simlp.address, this.amount],
+                 { ...this.opts, tag: `trader:fund:d${day}` });
+    await s.send(this.simlp, "swap", this.#swapArgs(this.tokenIs0, this.amount),
+                 { ...this.opts, tag: `trader:sell:d${day}` });
+    const quoteAfter = await s.call(this.quote, "balanceOf", [this.me]);
+    const proceeds = quoteAfter - quoteBefore;
+
+    // Buy back TOKEN with the proceeds.
+    await s.send(this.quote, "transfer", [this.simlp.address, proceeds],
+                 { ...this.opts, tag: `trader:refund:d${day}` });
+    await s.send(this.simlp, "swap", this.#swapArgs(!this.tokenIs0, proceeds),
+                 { ...this.opts, tag: `trader:buyback:d${day}` });
+  }
+}

package/src/agents/whale.js

@@ -0,0 +1,45 @@
+// PinWhale: snaps a TOKEN/quote V3 pool to a reference price path --
+// the JS peer of the Python sim's MarketMakerWhale.snap().
+//
+// The V3 trick (identical to agents.py): swap an effectively unlimited
+// amount with sqrtPriceLimitX96 = the target -- the pool executes exactly
+// enough volume to land on the limit.  Paid from the SimLP helper's own
+// token custody, so the whale only needs SimLP to be stocked (the Python
+// deploy leaves it holding deep TOKEN+quote reserves).
+
+import { HUGE, sqrtPriceX96 } from "../v3.js";
+
+export class PinWhale {
+  /**
+   * @param opts.simlp   SimLP contract handle
+   * @param opts.pool    UniswapV3Pool handle (TOKEN/quote)
+   * @param opts.token   TOKEN address   @param opts.tokenDec its decimals
+   * @param opts.quote   quote address (e.g. USDC)
+   * @param opts.refPrice (day) => quote base units per whole TOKEN
+   */
+  constructor({ simlp, pool, token, tokenDec, quote, refPrice }) {
+    Object.assign(this, { simlp, pool, token, tokenDec, quote, refPrice });
+  }
+
+  async setup(world) {
+    const [t0, t1] = await Promise.all([
+      world.session.call(this.pool, "token0"),
+      world.session.call(this.pool, "token1"),
+    ]);
+    this.t0 = t0;
+    this.t1 = t1;
+  }
+
+  async act(world, day, tick) {
+    if (tick !== 0) return;                       // one snap per day
+    const slot0 = await world.session.call(this.pool, "slot0");
+    const cur = slot0[0];                          // sqrtPriceX96
+    const targ = sqrtPriceX96(this.token, 10n ** BigInt(this.tokenDec),
+                              this.quote, this.refPrice(day));
+    if (cur === targ) return;
+    await world.session.send(this.simlp, "swap",
+      [this.pool.address, this.simlp.address, targ < cur, HUGE, targ,
+       this.t0, this.t1],
+      { tag: `whale:snap:d${day}` });
+  }
+}

package/src/backends.js

@@ -0,0 +1,54 @@
+// Session constructors for the two Phase 1 backends.
+//
+//   anvilSession(url)  -- join a running anvil (e.g. one a Python sim
+//                         deployed into): HTTP transport, zero-fee legacy
+//                         txs matching the sim's anvil profile.
+//   tevmSession()      -- standalone in-process EVM (Tevm MemoryClient);
+//                         the same session/agents run wholly in JS.
+//
+// Both sign with well-known anvil/tevm dev accounts (mnemonic "test test
+// ... junk"), so one code path -- local-account raw txs -- serves both.
+
+import { createPublicClient, createWalletClient, http, publicActions } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+import { Session } from "./session.js";
+
+// The standard prefunded dev accounts (anvil and tevm share them).
+export const DEV_KEYS = [
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
+  "0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a",
+  "0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6",
+  "0x47e179ec197488593b187f80a00eb0da91f1b9d0b13f8733639f19c30a34926a",
+  "0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba",
+  "0x92db14e403b83dfe3df233f83dfa3a0d7096f21ca9b0d6d6b8d88b2b4ec1564e",
+  "0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356",
+  "0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97",
+  "0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6",
+];
+
+export function devAccount(index = 0) {
+  return privateKeyToAccount(DEV_KEYS[index]);
+}
+
+/** Join a running anvil node (the Python sim's zero-fee profile). */
+export function anvilSession(url, { accountIndex = 9, journal = null } = {}) {
+  const client = createWalletClient({ transport: http(url) })
+    .extend(publicActions);
+  return new Session(client, {
+    account: devAccount(accountIndex),
+    journal,
+    txOverrides: { gasPrice: 0n },   // anvil runs --base-fee 0 --gas-price 0
+  });
+}
+
+/** Standalone in-process EVM. Import lazily: tevm is a heavy dependency. */
+export async function tevmSession({ accountIndex = 0, journal = null } = {}) {
+  const { createMemoryClient } = await import("tevm");
+  const client = createMemoryClient();
+  return new Session(client, {
+    account: devAccount(accountIndex),
+    journal,
+  });
+}

package/src/buckworld.js

@@ -0,0 +1,198 @@
+// buildBuckWorld: the REAL BUCK stack on any session (Tevm in-process or
+// anvil), mirroring the Python sim's deploy.py order -- IdentityRegistry
+// (+ a kernel-keyed trusted issuer), BuckCredit, BuckKControllerDirect,
+// Buck, and their wiring.  The V3 pool world composes alongside via
+// buildOnePool (scenarios/onepool.js); the basket lands with the
+// background-rebalancing stage.
+//
+// Identity onboarding runs the FULL wallet ceremony on the wasm
+// buck-identity kernel (canonical identity -> m -> PS sign/rerandomize ->
+// ElGamal -> registration NIZK) and the real Solidity verifier accepts it
+// on-chain -- the capability the in-browser demo rests on.
+//
+// Environment-free by injection (the artifacts(name) pattern): pass the
+// identity kernel API as opts.identity -- node code loads it from
+// ./identity.js, the browser from ./identity-web.js -- and optionally
+// opts.rng (a () => bigint scalar drawer) to reproduce a world; the
+// default draws WebCrypto.
+
+// BN254.sol struct components are UPPERCASE X/Y at the ABI.
+const g = (p) => ({ X: p.x, Y: p.y });
+const ct = (E) => ({ R: g(E.R), C: g(E.C) });
+const g2 = (p) => ({ X: [p.x[0], p.x[1]], Y: [p.y[0], p.y[1]] });
+
+// Controller deploy defaults -- the SAME values experiment.deploy_params
+// derives for the Python sim (gains real*1e12: Kp = kp_frac*dk_rail/e_max
+// = 0.1 -> 1e11; Ki = dk_rail/(e_max*tau_I) = 0.5/777600s -> 643004;
+// dt 1800s; K rails 0..0.95, K0 0.75).
+export const DEPLOY_DEFAULTS = {
+  kp: 100_000_000_000n,
+  ki: 643_004n,
+  kd: 0n,
+  dt: 1800n,
+  kmin: 0n,
+  kmax: 950_000_000_000_000_000n,
+  k0: 750_000_000_000_000_000n,
+};
+
+export const DAY = 86_400;
+
+/**
+ * Deploy the BUCK identity + monetary stack.
+ *
+ * @param session   a Session (deployer = session.account)
+ * @param artifacts (name) => {abi, bytecode}
+ * @param opts.identity the buck-identity kernel API (REQUIRED: import
+ *                  from ./identity.js in node, loadIdentity() in the browser)
+ * @param opts.gov      governance address    (default: deployer)
+ * @param opts.poolAcct funding-pool address  (default: deployer)
+ * @param opts.params   controller overrides over DEPLOY_DEFAULTS
+ * @param opts.rng      scalar drawer for the issuer PS keypair
+ * @returns world {session, artifacts, id, reg, credit, kctrl, buck, gov,
+ *                 poolAcct, issuer:{addr, skX, skY, pkX, pkY}}
+ */
+export async function buildBuckWorld(session, artifacts, opts = {}) {
+  const id = opts.identity;
+  if (!id) {
+    throw new Error(
+      "buildBuckWorld needs opts.identity (the buck-identity kernel API: " +
+      "import from src/identity.js in node, loadIdentity() in the browser)");
+  }
+  const gas = 15_000_000n;
+  const gov = opts.gov ?? session.account.address;
+  const poolAcct = opts.poolAcct ?? session.account.address;
+  const p = { ...DEPLOY_DEFAULTS, ...(opts.params ?? {}) };
+  const rng = opts.rng ?? id.randScalar;
+
+  // --- identity layer (deploy.py order) ---------------------------------
+  const reg = await session.deploy(artifacts("IdentityRegistry"), [gov],
+    { name: "IdentityRegistry", gas });
+  const [skX, skY] = [rng(), rng()];
+  const issuer = {
+    addr: "0x" + "15".repeat(20),   // the trust-anchor address
+    skX, skY,
+    pkX: id.g2Mul(id.G2, skX),
+    pkY: id.g2Mul(id.G2, skY),
+  };
+  await session.send(reg, "trustIssuer",
+    [issuer.addr, { X: g2(issuer.pkX), Y: g2(issuer.pkY) }],
+    { tag: "world:trustIssuer" });
+
+  // --- Direct BUCK stack -------------------------------------------------
+  const credit = await session.deploy(artifacts("BuckCredit"), [],
+    { name: "BuckCredit", gas });
+  const kctrl = await session.deploy(artifacts("BuckKControllerDirect"),
+    [p.kp, p.ki, p.kd, p.dt, p.kmin, p.kmax, p.k0, gov],
+    { name: "BuckKControllerDirect", gas });
+  const buck = await session.deploy(artifacts("Buck"),
+    [credit.address, kctrl.address, reg.address, poolAcct],
+    { name: "Buck", gas });
+  await session.send(reg, "setBuck", [buck.address], { tag: "world:reg.setBuck" });
+  await session.send(credit, "setBuck", [buck.address], { tag: "world:credit.setBuck" });
+
+  return { session, artifacts, id, reg, credit, kctrl, buck, gov, poolAcct, issuer };
+}
+
+/**
+ * Register `account` with a REAL cryptographic identity: the full wallet
+ * ceremony on the wasm kernel, verified on-chain by IdentityRegistry.
+ *
+ * @param world    from buildBuckWorld
+ * @param account  a viem account (signs the register tx)
+ * @param fields   identity KYC fields (issuer_id is stamped)
+ * @param opts.rng scalar drawer (default WebCrypto)
+ * @returns handle {account, fields, canonical, m, M, kp:{sk, pk}, E}
+ */
+export async function onboard(world, account, fields, opts = {}) {
+  const id = world.id;
+  const rng = opts.rng ?? id.randScalar;
+  const full = { ...fields, issuer_id: fields.issuer_id ?? "atb-financial-ca" };
+  const canonical = id.canonicalIdentity(full);
+  const m = id.identityScalar(canonical);
+
+  const sigma = id.psSign(world.issuer.skX, world.issuer.skY, m, rng());
+  const sigmaP = id.psRerandomize(sigma, rng());
+  const sk = rng();
+  const pk = id.g1Mul(id.G1, sk);
+  const M = id.g1Mul(id.G1, m);
+  const r = rng();
+  const E = id.elgamalEncrypt(M, pk, r);
+  const proof = id.registrationProve(
+    sigmaP, m, r, pk, E, BigInt(account.address), rng(), rng());
+
+  await world.session.send(world.reg, "register", [
+    world.issuer.addr, g(pk), ct(E),
+    { sigma_1: g(sigmaP.sigma_1), sigma_2: g(sigmaP.sigma_2) },
+    { e: proof.e, s_m: proof.s_m, s_r: proof.s_r,
+      A_ps: g(proof.A_ps), T_C: g(proof.T_C), T_R: g(proof.T_R) },
+  ], { tag: `onboard:${full.given_name ?? account.address}`, gas: 3_000_000n,
+       account });
+
+  return { account, fields: full, canonical, m, M, kp: { sk, pk }, E };
+}
+
+/**
+ * The identity-approve handshake: `from` re-encrypts their REGISTERED
+ * identity under `to`'s key with a Chaum-Pedersen equality proof
+ * (IdentityRegistry.verifyApprove), storing the receipt fragment that
+ * gates Buck transfers.  Private<->private payments need BOTH directions
+ * (each party approves the other); a public counterparty is exempt.
+ *
+ * @returns the re-encryption {R, C} handed to `to` (their decryption key
+ *          recovers `from.M` -- the bilateral-disclosure half).
+ */
+export async function identityApprove(world, from, to, opts = {}) {
+  const id = world.id;
+  const rng = opts.rng ?? id.randScalar;
+  const chainid = BigInt(await world.session.client.getChainId());
+  const rPrime = rng();
+  const eForTo = id.elgamalEncrypt(from.M, to.kp.pk, rPrime);
+  const proof = id.chaumPedersenProve(
+    from.E, eForTo, from.kp.pk, to.kp.pk, from.kp.sk, rPrime,
+    BigInt(from.account.address), BigInt(to.account.address), chainid,
+    rng(), rng());
+  await world.session.send(world.buck, "approve", [
+    to.account.address, opts.allowance ?? 0n, ct(eForTo),
+    { e: proof.e, s1: proof.s1, s2: proof.s2,
+      T1: g(proof.T1), T2: g(proof.T2), T3: g(proof.T3) },
+  ], { tag: `approve:${from.fields.given_name}->${to.fields.given_name}`,
+       gas: 1_000_000n, account: from.account });
+  return eForTo;
+}
+
+/**
+ * Create a BuckCredit NFT for `holder` and activate its face through
+ * Buck.mint (zero premium: activates credit headroom; BUCK circulates
+ * when the holder draws by transferring).
+ */
+export async function createCredit(world, holder, face, opts = {}) {
+  const now = (await world.session.client.getBlock()).timestamp;
+  await world.session.send(world.credit, "createCredit",
+    [holder.account.address, opts.assetClass ?? 0, face,
+     opts.floor ?? 0n, opts.depType ?? 0, opts.depRate ?? 0,
+     now, opts.premiumRate ?? 0],
+    { tag: "world:createCredit" });
+  await world.session.send(world.buck, "mint", [face],
+    { tag: "world:activate", account: holder.account, gas: 3_000_000n });
+}
+
+/** Fund a fresh account with ETH from the deployer (plain value transfer:
+ *  works on tevm and anvil alike; new demo citizens need gas money). */
+export async function fundAccount(world, to, wei = 10n ** 19n) {
+  const hash = await world.session.client.sendTransaction({
+    account: world.session.account, to, value: wei,
+    gas: 21_000n, chain: null, ...world.session.txOverrides,
+  });
+  await world.session.client.waitForTransactionReceipt({ hash });
+}
+
+/** Jump the chain clock forward and mine one block. */
+export async function advanceTime(world, seconds) {
+  const now = (await world.session.client.getBlock()).timestamp;
+  await world.session.client.request({
+    method: "evm_setNextBlockTimestamp",
+    params: [Number(now) + Number(seconds)],
+  });
+  await world.session.client.request({ method: "evm_mine", params: [] });
+  return (await world.session.client.getBlock()).timestamp;
+}