@xmbl/simulator 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xmbl/simulator",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "description": "XMBL Simulator",
+  "scripts": {
+    "devnet": "node src/devnet-run.mjs",
+    "soak": "node index.js --run",
+    "test": "node src/devnet.test.mjs && node src/devnet-rpc.test.mjs"
+  },
+  "dependencies": {
+    "@faker-js/faker": "^8.4.1",
+    "chance": "^1.1.13"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/34r7h/xmbl-mainnet.git",
+    "directory": "packages/simulator"
+  },
+  "exports": {
+    ".": "./index.js"
+  }
+}

package/readme.md

@@ -0,0 +1,7 @@
+# XSIM - XMBL Simulator
+
+XMBL's Simulator module.
+
+This simulator runs infinitely. It has two modes, a deterministic mode where we know exactly what to expect and will be used for system e2e tests then also a random mode with chaotic qualities. 
+
+every type of interaction and activity in the total xmbl system, including creation of identities, posting txs, validations, storage, compute, state machine diff txs, assembling app-centric diffs into current state, etc

package/src/capabilities.js

@@ -0,0 +1,110 @@
+// Node-side capability runners for the browser extension. The extension popup cannot run xmbl's
+// zk / homomorphic-encryption / signature primitives in-page (they need node:crypto; an MV3 page
+// CSP and WebCrypto's async sha256 make a faithful in-page port impossible), so the devnet node
+// process — which already loads the REAL modules — runs each primitive end-to-end and returns a
+// JSON-safe verdict. Each runner does the honest thing and its NEGATIVE control in one call: it
+// proves the capability verifies true input AND rejects tampered input, so a green card on screen
+// is backed by a real refusal, not a fabricated pass. Every flow mirrors the headless
+// reproductions in @xmbl/contracts (reproductions/contract-zk.mjs, contract-he.mjs,
+// agentic-contract-e2e.mjs) so the extension and the audit prove the same thing.
+import { setup, blindedCurve, prove, verify as zkVerify } from '../../zero-knowledge/index.js';
+import {
+  cubicSigKeyGen, cubicSigSign, cubicSigVerify,
+  cubicLweKeyGen, encryptBit, decryptBit, addCiphertexts,
+  sealSecret, openSecret, sealKeyPair,
+} from '../../identity/index.js';
+
+const bi = (v) => BigInt(v);
+const str = (v) => (typeof v === 'bigint' ? v.toString() : v);
+
+// A real, non-collinear cube plane for the spatial binding (normal ≠ 0).
+const CUBE_CONTEXT = {
+  cubeAddress: 'cube-xbe-demo',
+  coordinates: [{ x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }, { x: 0, y: 0, z: 1 }],
+};
+
+// ── Coordinate / curve zero-knowledge (@xmbl/zero-knowledge, FRI, ⛔ UNAUDITED) ──
+// A prover shows a coordinate (derivedX, derivedY) lies on a curve through secret points, and a
+// verifier checks it WITHOUT the secret points. We prove the honest coordinate and reject a
+// tampered y (derivedY+1) — the exact pair reproductions/contract-zk.mjs gates a Verkle write on.
+export function zkProof({ derivedX = 99 } = {}) {
+  const ctx = setup();
+  const publicPoints = [{ x: 11n, y: 101n }, { x: 12n, y: 205n }, { x: 13n, y: 313n }, { x: 14n, y: 419n }];
+  const secretPoints = [{ x: 21n, y: 55555n }, { x: 22n, y: 66666n }, { x: 23n, y: 77777n }];
+  const dX = bi(derivedX);
+  const { Pt, derivedY } = blindedCurve(ctx, { publicPoints, secretPoints, derivedX: dX });
+  const proof = prove(ctx, { Pt, publicPoints, derivedX: dX, derivedY });
+  const honest = zkVerify(ctx, { proof, publicPoints, derivedX: dX, derivedY });
+  const tampered = zkVerify(ctx, { proof, publicPoints, derivedX: dX, derivedY: derivedY + 1n });
+  return {
+    ok: honest === true && tampered === false,
+    scheme: 'xzk (FRI coordinate/curve proof, UNAUDITED)',
+    derivedX: str(dX), derivedY: str(derivedY),
+    publicAnchors: publicPoints.length,
+    honestVerifies: honest, tamperedRejected: tampered === false,
+    note: 'proof checked without the secret points; a coordinate off the curve is rejected',
+  };
+}
+
+// ── Homomorphic add (post-quantum cubic-LWE) ──
+// ENC(a) ⊞ ENC(b) decrypts to a+b with NO secret key present during the add. Single-bit message
+// space wraps mod 2 (the documented behavior in reproductions/contract-he.mjs). a,b ∈ {0,1}.
+export function heAdd({ a = 1, b = 1 } = {}) {
+  // The message space is a single bit; reject anything else rather than silently coercing (a
+  // coerced 3→1 would return ok:true for an operation nobody asked for).
+  if (![0, 1].includes(a) || ![0, 1].includes(b)) {
+    return { ok: false, scheme: 'cubic-LWE (single-bit message space)', a, b, error: 'heAdd: a and b must each be 0 or 1' };
+  }
+  const bitA = a, bitB = b;
+  const { sk, pk } = cubicLweKeyGen();
+  const ctA = encryptBit(pk, bitA);
+  const ctB = encryptBit(pk, bitB);
+  const ctSum = addCiphertexts(ctA, ctB); // NO secret key here — the add is blind
+  const sum = decryptBit(sk, ctSum);      // decrypt OFF to the side, with sk
+  const expected = (bitA + bitB) % 2;
+  return {
+    ok: sum === expected,
+    scheme: 'cubic-LWE (post-quantum, single-bit message space mod 2)',
+    a: bitA, b: bitB, sum, expected,
+    note: 'ENC(a) ⊞ ENC(b) added with no secret key; decryption needs sk and is on no contract ABI',
+  };
+}
+
+// ── Cubic-SIG signature verify (spatially bound to a cube plane) ──
+// Sign a message, verify it, then prove a tampered message is rejected.
+export function sigVerify({ message = 'xmbl-extension' } = {}) {
+  const { sk, pk } = cubicSigKeyGen();
+  const sig = cubicSigSign(message, sk, pk, CUBE_CONTEXT);
+  const good = cubicSigVerify(message, sig, pk, CUBE_CONTEXT);
+  const bad = cubicSigVerify(message + '!', sig, pk, CUBE_CONTEXT);
+  return {
+    ok: good === true && bad === false,
+    scheme: 'Cubic-SIG (Schnorr bound to a 3-point cube plane)',
+    message, signedVerifies: good, tamperedRejected: bad === false,
+    note: '[s]G == R + [e]pk over the cube plane; a changed message fails verification',
+  };
+}
+
+// ── Seal (post-quantum KEM envelope, MAINNET_N) ──
+// Seal a secret to a receiver's public key; only the receiver's secret key opens it.
+export function sealRoundTrip({ secret = 'authorizing-key' } = {}) {
+  const receiver = sealKeyPair();
+  const bytes = new TextEncoder().encode(secret);
+  const env = sealSecret(receiver.pk, bytes);
+  const opened = openSecret(receiver.sk, env);
+  const back = new TextDecoder().decode(Uint8Array.from(opened));
+  return {
+    ok: back === secret,
+    scheme: 'cubic-LWE KEM seal (post-quantum, MAINNET_N)',
+    roundTrip: back === secret,
+    note: 'sealed to the receiver’s public key; opens only with their secret key, never custodied',
+  };
+}
+
+// Dispatch table: message.type → runner. Kept here so DevnetRpc.handle stays a thin router.
+export const CAPABILITIES = {
+  zkProof: (m) => zkProof(m),
+  heAdd: (m) => heAdd(m),
+  sigVerify: (m) => sigVerify(m),
+  seal: (m) => sealRoundTrip(m),
+};

package/src/devnet-rpc.js

@@ -0,0 +1,114 @@
+// DevnetRpc — serves the browser-extension's background message contract over loopback HTTP,
+// backed by a real LocalDevnet. This is the drop-in replacement for the extension's stub
+// BackgroundNode (packages/browser-extension/src/background.js): POST JSON `{type, ...}` and get
+// back a response IDENTICAL in shape to what that stub returns — but computed from REAL devnet
+// state, not mocked.
+//
+//   getBalance      {type, address?}  → { balance, address }   // net of APPLIED utxo deltas
+//   sendTransaction {type, tx:{to,amount}} → { txId } | { error } // a real signed+verified tx lands
+//   getNodeStatus   {type}            → { running, peers, height }
+//   startNode       {type}            → { success }
+//   stopNode        {type}            → { success }
+//
+// Contract deploy/call are intentionally NOT served here — the in-page contract path is already
+// node-parity-proven in the extension, and a deploy route pulls in the delegation gate + worker
+// isolation questions, which are a separate piece.
+//
+// It ALSO serves the node-side capability surface the extension cannot run in-page — each a REAL
+// primitive run end-to-end in this node process, verdict returned JSON-safe (see capabilities.js):
+//   getStateRoot    {type}                  → { root, pooled, landed }   // live ledger state root
+//   zkProof         {type, derivedX?}       → { ok, derivedX, derivedY, honestVerifies, tamperedRejected, … }
+//   heAdd           {type, a?, b?}          → { ok, a, b, sum, expected, … }  // homomorphic add
+//   sigVerify       {type, message?}        → { ok, signedVerifies, tamperedRejected, … }  // Cubic-SIG
+//   seal            {type, secret?}         → { ok, roundTrip, … }             // PQ KEM seal
+import { createServer } from 'node:http';
+import { CAPABILITIES } from './capabilities.js';
+
+export class DevnetRpc {
+  constructor(devnet, options = {}) {
+    this.net = devnet;
+    this.walletIndex = options.walletIndex ?? 0; // identity[0] is the "wallet" the extension speaks for
+    this.server = null;
+    this.port = null;
+    this.host = options.host ?? '127.0.0.1';
+  }
+
+  /** Map one extension message to a real devnet response. */
+  async handle(message) {
+    switch (message && message.type) {
+      case 'getBalance': {
+        const address = message.address || this.net.addressOf(this.walletIndex);
+        return { balance: this.net.balanceOf(address), address };
+      }
+      case 'sendTransaction': {
+        const tx = message.tx || {};
+        const amount = Number(tx.amount);
+        if (!tx.to || !Number.isFinite(amount)) return { error: 'sendTransaction needs tx.to and a numeric tx.amount' };
+        // Resolve a known participant by address, else send to the raw external address.
+        const toIndex = this.net.identities.findIndex((i) => i.address === tx.to);
+        const r = toIndex >= 0
+          ? await this.net.submitTransfer(this.walletIndex, toIndex, amount)
+          : await this.net.submitTransferToAddress(this.walletIndex, tx.to, amount);
+        return r.ok ? { txId: r.id } : { error: r.error };
+      }
+      case 'getNodeStatus':
+        return {
+          running: this.net.isRunning(),
+          peers: Math.max(0, this.net.identities.length - 1),
+          height: this.net.height(),
+        };
+      case 'startNode':
+        if (!this.net.isRunning()) await this.net.start();
+        return { success: true };
+      case 'stopNode':
+        if (this.net.isRunning()) await this.net.stop();
+        return { success: true };
+      case 'getStateRoot': {
+        const m = await this.net.getMetrics();
+        return { root: m.root ?? null, pooled: m.pooled ?? 0, landed: m.landed ?? this.net.height() };
+      }
+      default: {
+        // Node-side capability surface (zk / HE / signature / seal): a real primitive run to a
+        // verdict in this process. Unknown types still fall through to an honest error.
+        const cap = CAPABILITIES[message && message.type];
+        if (cap) return cap(message || {});
+        return { error: `Unknown message type: ${message && message.type}` };
+      }
+    }
+  }
+
+  /** Start listening on loopback. port 0 → an OS-assigned port (returned). */
+  async listen(port = 0) {
+    this.server = createServer((req, res) => {
+      // CORS preflight / permissive origin so a page or service worker on any origin can call it.
+      res.setHeader('access-control-allow-origin', '*');
+      res.setHeader('access-control-allow-headers', 'content-type');
+      if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
+      if (req.method !== 'POST') { res.writeHead(405); res.end('POST JSON only'); return; }
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; if (body.length > 1e6) req.destroy(); });
+      req.on('end', async () => {
+        let message;
+        try { message = JSON.parse(body || '{}'); } catch { res.writeHead(400, { 'content-type': 'application/json' }); res.end('{"error":"invalid json"}'); return; }
+        try {
+          const response = await this.handle(message);
+          res.writeHead(200, { 'content-type': 'application/json' });
+          res.end(JSON.stringify(response));
+        } catch (error) {
+          res.writeHead(500, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: error.message }));
+        }
+      });
+    });
+    await new Promise((resolve) => this.server.listen(port, this.host, resolve));
+    this.port = this.server.address().port;
+    return this.port;
+  }
+
+  url() { return this.port ? `http://${this.host}:${this.port}` : null; }
+
+  async close() {
+    if (this.server) await new Promise((resolve) => this.server.close(resolve));
+    this.server = null;
+  }
+}

package/src/devnet-rpc.test.mjs

@@ -0,0 +1,91 @@
+// Gate test for DevnetRpc: drives the REAL loopback HTTP surface through the browser-extension's
+// five background message types and asserts responses computed from REAL devnet state. Proves the
+// RPC is a faithful, non-mocked drop-in for the extension's stub BackgroundNode. Self-contained;
+// exits non-zero on failure.
+import assert from 'node:assert/strict';
+import { LocalDevnet } from './devnet.js';
+import { DevnetRpc } from './devnet-rpc.js';
+
+let pass = 0;
+const ok = (name, cond, detail = '') => { assert.ok(cond, `${name}${detail ? ' — ' + detail : ''}`); console.log('  ok  ' + name); pass++; };
+
+const net = await new LocalDevnet({ identities: 3 }).start();
+const rpc = new DevnetRpc(net, { walletIndex: 0 });
+const port = await rpc.listen(0);
+ok('RPC listens on a loopback port', Number.isInteger(port) && port > 0, `port=${port}`);
+
+const call = async (msg) => {
+  const res = await fetch(rpc.url(), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(msg) });
+  return res.json();
+};
+
+try {
+  // status: real running flag, peers = other identities, height starts at 0
+  const s0 = await call({ type: 'getNodeStatus' });
+  ok('getNodeStatus reports running', s0.running === true);
+  ok('getNodeStatus peers = other identities', s0.peers === 2, `peers=${s0.peers}`);
+  ok('getNodeStatus height starts at 0', s0.height === 0, `height=${s0.height}`);
+
+  // balance: wallet (identity 0) starts at 0 — real, not fabricated
+  const b0 = await call({ type: 'getBalance' });
+  ok('getBalance defaults to the wallet address', b0.address === net.addressOf(0));
+  ok('wallet balance starts at 0', b0.balance === 0, `balance=${b0.balance}`);
+
+  // send a real signed+verified tx from the wallet to another participant
+  const recipient = net.addressOf(1);
+  const sent = await call({ type: 'sendTransaction', tx: { to: recipient, amount: 25 } });
+  ok('sendTransaction returns a real landed txId', typeof sent.txId === 'string' && /^dtx_/.test(sent.txId), JSON.stringify(sent));
+
+  // balances reflect the landed transfer (REAL applied delta), height advanced
+  const br = await call({ type: 'getBalance', address: recipient });
+  ok('recipient balance reflects the landed transfer', br.balance === 25, `balance=${br.balance}`);
+  const bw = await call({ type: 'getBalance' });
+  ok('wallet balance is negated by the send', bw.balance === -25, `balance=${bw.balance}`);
+  const s1 = await call({ type: 'getNodeStatus' });
+  ok('height advanced after the send', s1.height === 1, `height=${s1.height}`);
+
+  // a malformed send is reported, not crashed
+  const bad = await call({ type: 'sendTransaction', tx: { amount: 5 } });
+  ok('sendTransaction without a recipient returns an error', typeof bad.error === 'string', JSON.stringify(bad));
+
+  // live ledger state root (real, moves as faces seal)
+  const sr = await call({ type: 'getStateRoot' });
+  ok('getStateRoot returns landed count and pooled', sr.landed === 1 && typeof sr.pooled === 'number', JSON.stringify(sr));
+
+  // ── node-side capability surface: each a REAL primitive verified + negative-controlled ──
+  const zk = await call({ type: 'zkProof', derivedX: 99 });
+  ok('zkProof verifies the honest coordinate and rejects the tampered one', zk.ok === true && zk.honestVerifies === true && zk.tamperedRejected === true, JSON.stringify(zk));
+
+  const he1 = await call({ type: 'heAdd', a: 1, b: 0 });
+  ok('heAdd: ENC(1) ⊞ ENC(0) decrypts to 1 (blind add)', he1.ok === true && he1.sum === 1, JSON.stringify(he1));
+  const he2 = await call({ type: 'heAdd', a: 1, b: 1 });
+  ok('heAdd: ENC(1) ⊞ ENC(1) decrypts to 0 (mod-2 wrap)', he2.ok === true && he2.sum === 0, JSON.stringify(he2));
+  // the message space is a single bit: a non-bit operand is rejected, NOT silently coerced to a
+  // green verdict for an operation nobody asked for
+  const heBad = await call({ type: 'heAdd', a: 3, b: 5 });
+  ok('heAdd rejects non-bit operands (no coerced false pass)', heBad.ok === false && /0 or 1/.test(heBad.error || ''), JSON.stringify(heBad));
+
+  const sig = await call({ type: 'sigVerify', message: 'xbe' });
+  ok('sigVerify signs+verifies and rejects a tampered message', sig.ok === true && sig.signedVerifies === true && sig.tamperedRejected === true, JSON.stringify(sig));
+
+  const seal = await call({ type: 'seal', secret: 'authorizing-key' });
+  ok('seal round-trips a secret through a PQ KEM envelope', seal.ok === true && seal.roundTrip === true, JSON.stringify(seal));
+
+  // unknown type is reported
+  const unk = await call({ type: 'frobnicate' });
+  ok('unknown message type returns an error', /Unknown message type/.test(unk.error || ''), JSON.stringify(unk));
+
+  // node lifecycle toggles real state
+  const stop = await call({ type: 'stopNode' });
+  ok('stopNode succeeds', stop.success === true);
+  ok('devnet actually stopped', net.isRunning() === false);
+  const start = await call({ type: 'startNode' });
+  ok('startNode succeeds', start.success === true);
+  ok('devnet actually running again', net.isRunning() === true);
+
+  console.log(`\n✅ devnet-rpc: ${pass} checks passed`);
+} finally {
+  await rpc.close();
+  await net.stop();
+}
+process.exit(0);

package/src/devnet-run.mjs

@@ -0,0 +1,46 @@
+// Runner for the XMBL LocalDevnet + its RPC surface.  `npm run devnet -w packages/simulator`
+//
+// Boots a real local network (real MAYO identities + real cubic ledger, signature verification
+// ON), seeds a little activity so balances/height are non-trivial, then serves the browser
+// -extension message contract over loopback HTTP and stays up until Ctrl-C. The printed URL is
+// the one a node bridge (replacing the extension's stub BackgroundNode) would POST to.
+//
+//   PORT=8645 npm run devnet -w packages/simulator     # pin a different RPC port
+//   IDENTITIES=6 SEED=12 npm run devnet -w packages/simulator
+//
+// The default port is 8646 — the browser extension's documented default endpoint (its Config tab
+// and `xmbl:devnetUrl` default to http://127.0.0.1:8646), so `npm run devnet` serves the loaded
+// extension with no reconfiguration. Override with PORT to run elsewhere (then re-point the
+// extension's Config tab to match).
+import { LocalDevnet } from './devnet.js';
+import { DevnetRpc } from './devnet-rpc.js';
+
+const identities = Number(process.env.IDENTITIES || 4);
+const seed = Number(process.env.SEED || 9);
+const port = Number(process.env.PORT || 8646);
+
+const net = await new LocalDevnet({ identities }).start();
+console.log(`[devnet] booted ${net.metrics.identities} real identities; wallet = ${net.addressOf(0)}`);
+
+// Seed: wallet → participant 1, varied amounts, through the real verified direct path.
+for (let k = 0; k < seed; k++) {
+  const r = await net.submitTransfer(0, 1, 1 + k);
+  if (!r.ok) console.warn(`[devnet] seed tx ${k} rejected: ${r.error}`);
+}
+const m = await net.getMetrics();
+console.log(`[devnet] seeded ${m.landed} landed tx, ${m.facesCompleted} face(s) sealed, pooled ${m.pooled}, root ${m.root ?? '(none)'}`);
+
+const rpc = new DevnetRpc(net, { walletIndex: 0 });
+await rpc.listen(port);
+console.log(`[devnet] RPC (extension message contract) listening at ${rpc.url()}`);
+console.log('[devnet] POST JSON {type:"getNodeStatus"} | {"getBalance"} | {"sendTransaction",tx:{to,amount}} | {"startNode"} | {"stopNode"}');
+console.log('[devnet] Ctrl-C to stop.');
+
+const shutdown = async () => {
+  console.log('\n[devnet] shutting down…');
+  await rpc.close();
+  await net.dispose();
+  process.exit(0);
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/src/devnet.js

@@ -0,0 +1,180 @@
+// LocalDevnet — a light local XMBL network you can run and verify against "in reality".
+//
+// This is the "hardhat for XMBL": a SCRIPTED, BOUNDED driver over the REAL protocol modules
+// (@xmbl/identity + @xmbl/cubic-ledger), with the ledger's signature verification turned ON
+// (it wires BOTH `xid` and `getPublicKeyByAddress`, the combination that activates
+// Identity.verifyTransaction on every tx). Every operation is an awaited, discrete step — no
+// setInterval, no Math.random in control flow — so counts and block/face formation are
+// repeatable run to run. That repeatability, not byte-identical faker output, is what makes a
+// gate test possible (see devnet.test.mjs).
+//
+// WHY THE DIRECT LEDGER PATH (ledger.addTransaction), NOT CONSENSUS:
+//   A signed node-authored tx, submitted directly, is verified by the ledger as-signed and
+//   lands — proven here with real MAYO keys + real verification. Two ledger-entry defects that
+//   the direct path never hit but the consensus finalize route did are now FIXED (proven by
+//   devnet.test.mjs, documented in ../DEVNET-SEAM-FINDING.md):
+//     (a) FIXED — ConsensusWorkflow.finalizeTransaction no longer overwrites the signed `id`
+//         with `validatedHash`; the signed id survives the handoff so re-verification matches.
+//     (b) FIXED — ledger.addSealedBatch now verifies via the static Identity.verifyTransaction
+//         (it used to call the nonexistent this.xid.verify → TypeError, so it verified nothing).
+//   ONE seam remains OPEN and audit-scoped (defect (c) in the finding): moveToProcessing injects
+//   `validationTimestamp` INTO the signed body, so the FULL consensus path still cannot re-verify
+//   at the ledger without a signature-domain / block-id decision. Ledger-side re-verification is
+//   therefore still OFF in the production daemon (core/index.js constructs the Ledger without
+//   getPublicKeyByAddress); the devnet opts it in, which is why the direct path is what it drives.
+import { EventEmitter } from 'node:events';
+import { Identity } from '../../identity/index.js';
+import { Ledger } from '../../cubic-ledger/index.js';
+
+export class LocalDevnet extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = {
+      identities: options.identities ?? 4,
+      scheme: options.scheme ?? 'mayo',
+      dbPath: options.dbPath ?? null, // null → in-memory ledger
+      ...options,
+    };
+    this.identities = [];            // real Identity instances (hold private keys)
+    this.byAddress = new Map();       // address → Identity
+    this.ledger = null;
+    this._applied = [];               // every utxo tx the REAL ledger accepted (post-verification)
+    this._seq = 0;
+    this.running = false;
+    this.metrics = {
+      identities: 0,
+      submitted: 0,
+      landed: 0,
+      rejected: 0,
+      facesCompleted: 0,
+      cubesCompleted: 0,
+    };
+  }
+
+  /**
+   * Start accepting work. The FIRST call bootstraps (mints real identities + a real ledger with
+   * signature verification ON); later calls after a stop() just resume — identities, ledger and
+   * applied balances persist across a stop/start, as a real node's chain would. Full teardown is
+   * dispose().
+   */
+  async start() {
+    if (this.running) return this;
+    if (this.ledger) { this.running = true; this.emit('started', { identities: this.identities.length, resumed: true }); return this; }
+    this.ledger = new Ledger({
+      dbPath: this.options.dbPath,
+      // Wiring this lookup is what activates ledger-side signature verification.
+      getPublicKeyByAddress: (address) => {
+        const id = this.byAddress.get(address);
+        return id ? id.publicKey : null;
+      },
+    });
+    this.ledger.on('face:complete', () => { this.metrics.facesCompleted++; this.emit('face:complete'); });
+    this.ledger.on('cube:complete', () => { this.metrics.cubesCompleted++; this.emit('cube:complete'); });
+
+    for (let i = 0; i < this.options.identities; i++) {
+      const id = await Identity.create(this.options.scheme);
+      this.identities.push(id);
+      this.byAddress.set(id.address, id);
+      this.metrics.identities++;
+      this.emit('identity:created', { index: i, address: id.address });
+    }
+    // ledger.xid must be truthy for the verification branch to run; the static
+    // Identity.verifyTransaction does the actual work, so any identity instance serves.
+    this.ledger.xid = this.identities[0] || Identity;
+    this.running = true;
+    this.emit('started', { identities: this.identities.length });
+    return this;
+  }
+
+  /** Address of a devnet participant by index (0 is the default "wallet"). */
+  addressOf(index = 0) {
+    const id = this.identities[index];
+    return id ? id.address : null;
+  }
+
+  /**
+   * Submit a SIGNED utxo transfer between two devnet participants (by index).
+   * Returns { ok, id, result?|error? }; the signature is verified by the ledger before it lands.
+   */
+  async submitTransfer(fromIndex, toIndex, amount) {
+    const to = this.identities[toIndex];
+    if (!to) throw new Error(`bad recipient index (have ${this.identities.length})`);
+    return this.submitTransferToAddress(fromIndex, to.address, amount);
+  }
+
+  /**
+   * Submit a SIGNED utxo transfer FROM a devnet participant TO an arbitrary address
+   * (the recipient need not be a known identity — the ledger only verifies the signer's
+   * ownership of `from`). This is what the RPC `sendTransaction` maps to.
+   */
+  async submitTransferToAddress(fromIndex, toAddress, amount) {
+    if (!this.running) throw new Error('devnet not started');
+    const from = this.identities[fromIndex];
+    if (!from) throw new Error(`bad sender index (have ${this.identities.length})`);
+    if (!toAddress || typeof toAddress !== 'string') throw new Error('toAddress required');
+    const tx = {
+      id: `dtx_${++this._seq}`,
+      type: 'utxo',
+      from: from.address,
+      to: toAddress,
+      amount,
+      timestamp: Date.now(),
+    };
+    const signed = await from.signTransaction(tx); // sets from=from.address, adds MAYO sig
+    this.metrics.submitted++;
+    try {
+      const result = await this.ledger.addTransaction(signed);
+      this.metrics.landed++;
+      this._applied.push({ from: signed.from, to: signed.to, amount: Number(amount) });
+      this.emit('tx:landed', { id: signed.id, from: signed.from, to: signed.to, amount: Number(amount) });
+      return { ok: true, id: signed.id, result };
+    } catch (error) {
+      this.metrics.rejected++;
+      this.emit('tx:rejected', { id: signed.id, error: error.message });
+      return { ok: false, id: signed.id, error: error.message };
+    }
+  }
+
+  /**
+   * REAL balance of an address: the net of every utxo tx the ledger actually accepted
+   * (each passed signature verification). Not a fabricated figure — it is the sum of applied
+   * deltas, so a fresh devnet reports 0 and only submitted+landed transfers move it.
+   */
+  balanceOf(address) {
+    let bal = 0;
+    for (const tx of this._applied) {
+      if (tx.to === address) bal += tx.amount;
+      if (tx.from === address) bal -= tx.amount;
+    }
+    return bal;
+  }
+
+  /** Current height: number of blocks the ledger is holding/has sealed this session. */
+  height() {
+    return this.metrics.landed;
+  }
+
+  async getMetrics() {
+    let root = null;
+    try { root = await this.ledger?.getStateRoot?.(); } catch { /* root optional */ }
+    return { ...this.metrics, pooled: this.ledger?.getMembershipPool?.().length ?? 0, root };
+  }
+
+  isRunning() { return this.running; }
+
+  /** Halt accepting work but KEEP state (identities, ledger, balances) so start() can resume. */
+  async stop() {
+    if (!this.running) return;
+    this.running = false;
+    this.emit('stopped', { ...this.metrics });
+  }
+
+  /** Final teardown: stop and release the ledger. After this, start() bootstraps afresh. */
+  async dispose() {
+    await this.stop();
+    try { await this.ledger?.close?.(); } catch { /* in-memory has no close */ }
+    this.ledger = null;
+    this.identities = [];
+    this.byAddress.clear();
+  }
+}