@xmbl/state-machine 0.1.1

package/index.js

@@ -0,0 +1,14 @@
+export { VerkleStateTree } from './src/verkle-tree.js';
+export { StateDiff } from './src/state-diff.js';
+// WASMExecutor was removed: executing (untrusted) contract WASM is @xmbl/storage-compute's
+// hardened ComputeRuntime, driven by @xmbl/contracts' ContractHost, which composes this
+// module's VerkleStateTree. The state machine owns state, not a second WASM sandbox.
+export { StateShard } from './src/sharding.js';
+export { StateAssembler } from './src/state-assembly.js';
+export { StateMachine } from './src/state-machine.js';
+
+const port = process.env.PORT || 3002;
+console.log(`XVSM (XMBL Virtual State Machine) starting on port ${port}`);
+
+
+

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@xmbl/state-machine",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/34r7h/xmbl-mainnet.git",
+    "directory": "packages/state-machine"
+  },
+  "dependencies": {
+    "level": "^10.0.0"
+  },
+  "scripts": {
+    "test": "node ../../scripts/run-node-tests.mjs ."
+  }
+}

package/src/apply-path.test.mjs

@@ -0,0 +1,168 @@
+// THE APPLY STEP MUST ACTUALLY RUN. Measured on prod 2026-08-17 before this test existed: state_root 64
+// zeros, applied_tx_count 0, state_diffs 0 — against 711 txs held and 5,594 block rows persisted. The cause
+// was not a hard bug in any function; every function worked. The `block:added` event that connects the ledger
+// to the state machine was documented (ledger.js @emits) and subscribed to (state-machine.js) and NEVER
+// EMITTED, so a fully implemented consumer sat unreachable for weeks while every dashboard read green.
+//
+// These checks are written against the OUTCOME — the state root and the applied counts after the fact — not
+// against the mechanism. A test that asserted "emit was called" would have passed on a build where the tree
+// still ended up empty.
+//
+//   node vendor/xmbl-node/state-machine/src/apply-path.test.mjs
+import { StateMachine } from './state-machine.js';
+import { Ledger } from '../../cubic-ledger/src/ledger.js';
+import { rm, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const ZERO = '0'.repeat(64);
+let pass = 0, fail = 0;
+const check = async (name, fn) => {
+  try { await fn(); console.log(`  ok   ${name}`); pass++; }
+  catch (e) { console.log(`  FAIL ${name}\n       ${e.message}`); fail++; }
+};
+const eq = (a, b, what) => { if (a !== b) throw new Error(`${what}: expected ${b}, got ${a}`); };
+
+// Nine anchor txs seal exactly one face under the hash-sorted partition (9 blocks per face).
+const anchors = (n, tag) => Array.from({ length: n }, (_, i) => ({
+  type: 'anchor', event: 'task.created', hash: `${tag}-${i}`.padEnd(64, '0'), ts: 1_700_000_000_000 + i,
+}));
+
+const fresh = async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'xvsm-apply-'));
+  const xclt = new Ledger({ dbPath: join(dir, '@xmbl/cubic-ledger') });
+  await xclt.db.open().catch(() => {});
+  xclt._dbOpen = true;
+  const xvsm = new StateMachine({ dbPath: join(dir, '@xmbl/state-machine'), xclt });
+  await new Promise((r) => setTimeout(r, 120));   // let both LevelDBs finish opening
+  return { dir, xclt, xvsm };
+};
+const close = async ({ dir, xclt, xvsm }) => {
+  await xclt.db.close().catch(() => {});
+  await xvsm.db.close().catch(() => {});
+  await rm(dir, { recursive: true, force: true });
+};
+
+console.log('\n1. a SEALED face reaches the state tree (the missing block:added doorbell)');
+{
+  const env = await fresh();
+  await check('the tree starts empty — the honest baseline, not an assumption', async () => {
+    eq(env.xvsm.getStateRoot(), ZERO, 'initial root');
+  });
+  await check('sealing 9 txs moves state_root off zero and applies 9 diffs', async () => {
+    for (const tx of anchors(9, 'seal')) await env.xclt.addTransaction(tx);
+    await new Promise((r) => setTimeout(r, 250));   // the xvsm handler is async
+    const root = env.xvsm.getStateRoot();
+    if (root === ZERO) throw new Error('state_root is still 64 zeros — block:added never reached xvsm');
+    eq(env.xvsm.diffs.length, 9, 'diffs applied');
+  });
+  await check('each applied key is the namespaced key the mapping defines', async () => {
+    const keys = env.xvsm.diffs.flatMap((d) => Object.keys(d.changes || {}));
+    const bad = keys.filter((k) => !k.startsWith('anchor:task.created:'));
+    if (bad.length) throw new Error(`unexpected keys: ${bad.slice(0, 3).join(', ')}`);
+  });
+  await close(env);
+}
+
+console.log('\n2. POOLED-but-unsealed blocks must NOT be applied');
+{
+  const env = await fresh();
+  await check('8 txs (one short of a face) leave the root at zero', async () => {
+    for (const tx of anchors(8, 'pool')) await env.xclt.addTransaction(tx);
+    await new Promise((r) => setTimeout(r, 250));
+    eq(env.xvsm.getStateRoot(), ZERO, 'root after 8 pooled');
+    eq(env.xvsm.diffs.length, 0, 'diffs after 8 pooled');
+  });
+  await check('the 9th seals the face and only THEN does the root move', async () => {
+    await env.xclt.addTransaction(anchors(9, 'pool')[8]);
+    await new Promise((r) => setTimeout(r, 250));
+    if (env.xvsm.getStateRoot() === ZERO) throw new Error('root still zero after the sealing tx');
+    eq(env.xvsm.diffs.length, 9, 'diffs after the face sealed');
+  });
+  await close(env);
+}
+
+console.log('\n3. BACKFILL applies what is already on disk — no doorbell, no quorum');
+{
+  const env = await fresh();
+  await check('a tree that missed every event recovers from the ledger rows alone', async () => {
+    // Simulate the prod condition exactly: blocks persisted by the ledger, a state machine that never heard
+    // about any of them. Detaching the listener is what makes this the real scenario rather than a mock.
+    env.xclt.removeAllListeners('block:added');
+    for (const tx of anchors(9, 'back')) await env.xclt.addTransaction(tx);
+    await new Promise((r) => setTimeout(r, 250));
+    eq(env.xvsm.getStateRoot(), ZERO, 'root before backfill (proves the listener really was detached)');
+
+    const r = await env.xvsm.backfillFromLedger();
+    if (r.applied !== 9) throw new Error(`applied ${r.applied} of 9 (scanned ${r.scanned}, failed ${r.failed})`);
+    if (r.state_root === ZERO) throw new Error('backfill reported success but the root is still zero');
+  });
+  await check('running it a second time is idempotent — same root, no divergence', async () => {
+    const first = env.xvsm.getStateRoot();
+    const r = await env.xvsm.backfillFromLedger();
+    eq(env.xvsm.getStateRoot(), first, 'root after a repeat backfill');
+    if (r.applied !== 9) throw new Error(`repeat applied ${r.applied}, expected the same 9`);
+  });
+  await close(env);
+}
+
+console.log('\n4. the state COMMITMENT is observable (state:committed was a silent no-op)');
+{
+  const env = await fresh();
+  await check('StateMachine is an EventEmitter, so a listener can be attached at all', async () => {
+    if (typeof env.xvsm.on !== 'function' || typeof env.xvsm.emit !== 'function') {
+      throw new Error('StateMachine still has no emit/on — this.emit?.() would swallow itself again');
+    }
+  });
+  await check('completing a cube emits state:committed carrying the root it committed', async () => {
+    const seen = [];
+    let cubes = 0;
+    env.xvsm.on('state:committed', (e) => seen.push(e));
+    env.xclt.on('cube:complete', () => cubes++);
+    // Drive the LEDGER until it says a cube completed, rather than assuming 27 txs make exactly one: the
+    // legacy path assigns each sealed face to the first cube with room, so a single 27-tx call can spread
+    // three faces across two cubes. Asserting an internal packing rule would test the wrong thing.
+    for (let batch = 0; batch < 12 && !cubes; batch++) {
+      for (const tx of anchors(9, `commit${batch}`)) await env.xclt.addTransaction(tx);
+      await new Promise((r) => setTimeout(r, 120));
+    }
+    if (!cubes) throw new Error('the ledger never completed a cube — nothing to commit (test setup, not the fix)');
+    if (!seen.length) throw new Error('a cube completed but no state:committed reached a listener');
+    const root = env.xvsm.getStateRoot();
+    const last = seen[seen.length - 1];
+    if (root === ZERO) throw new Error('a commitment was announced over an empty tree');
+    if (!last.cubeId) throw new Error('the event names no cube');
+    if (typeof last.stateRoot !== 'string' || last.stateRoot.length !== 64) {
+      throw new Error(`event carried no usable root: ${last.stateRoot}`);
+    }
+  });
+  await check('the ENVELOPE shape is pinned: the inner cube is what gets stamped, not the wrapper', async () => {
+    // Drive cube:complete through the EMITTER with the exact payload ledger.js sends. The handler accepts
+    // both shapes, so a direct call with a raw Cube (which is what verkle-integration.test.mjs does) passes
+    // either way and cannot detect a regression to envelope-only handling — the precise blind spot that let
+    // "no cube ever carried a state commitment" survive a green suite. This asserts the INNER cube.
+    const cube = { id: 'cube-envelope-probe', faces: new Map() };
+    env.xclt.emit('cube:complete', { cube, cubeId: 'timestamp-key', validatorAverageTimestamp: 1, level: 1 });
+    await new Promise((r) => setTimeout(r, 60));
+    if (!cube.stateRoot) throw new Error('the inner cube carries no stateRoot — the wrapper was stamped instead');
+    eq(cube.stateRoot, env.xvsm.getStateRoot(), 'the root stamped on the cube');
+  });
+  await close(env);
+}
+
+console.log('\n5. the same SET in a different order yields the SAME root (why replay is safe)');
+{
+  const a = await fresh(), b = await fresh();
+  await check('forward and reverse insertion agree', async () => {
+    const txs = anchors(9, 'order');
+    for (const tx of txs) await a.xclt.addTransaction(tx);
+    for (const tx of [...txs].reverse()) await b.xclt.addTransaction(tx);
+    await new Promise((r) => setTimeout(r, 300));
+    eq(a.xvsm.getStateRoot(), b.xvsm.getStateRoot(), 'roots across insertion orders');
+    if (a.xvsm.getStateRoot() === ZERO) throw new Error('both roots are zero — nothing was applied at all');
+  });
+  await close(a); await close(b);
+}
+
+console.log(`\n${fail ? 'FAILED' : 'PASSED'} — ${pass} passed, ${fail} failed\n`);
+process.exit(fail ? 1 : 0);

package/src/sharding.js

@@ -0,0 +1,32 @@
+import { createHash } from 'crypto';
+
+export class StateShard {
+  constructor(index, totalShards) {
+    this.index = index;
+    this.totalShards = totalShards;
+    this.state = new Map();
+  }
+
+  static getShardForKey(key, totalShards) {
+    const hash = createHash('sha256').update(key).digest();
+    const hashNum = hash.readUInt32BE(0);
+    return hashNum % totalShards;
+  }
+
+  set(key, value) {
+    this.state.set(key, value);
+  }
+
+  get(key) {
+    return this.state.get(key);
+  }
+
+  delete(key) {
+    this.state.delete(key);
+  }
+
+  getAllKeys() {
+    return Array.from(this.state.keys());
+  }
+}
+

package/src/state-assembly.js

@@ -0,0 +1,33 @@
+import { StateDiff } from './state-diff.js';
+
+export class StateAssembler {
+  constructor() {
+    this.baseState = {};
+  }
+
+  assemble(diffs) {
+    // Sort diffs by timestamp
+    const sortedDiffs = diffs.sort((a, b) => a.timestamp - b.timestamp);
+    
+    // Apply diffs in order
+    let state = { ...this.baseState };
+    for (const diff of sortedDiffs) {
+      state = diff.apply(state);
+    }
+    
+    const diffCount = diffs.length;
+    console.log(`State assembled from ${diffCount} diffs`);
+    
+    return state;
+  }
+
+  setBaseState(state) {
+    this.baseState = state;
+  }
+
+  getStateAtTimestamp(diffs, timestamp) {
+    const relevantDiffs = diffs.filter(d => d.timestamp <= timestamp);
+    return this.assemble(relevantDiffs);
+  }
+}
+

package/src/state-diff.js

@@ -0,0 +1,37 @@
+export class StateDiff {
+  constructor(txId, changes) {
+    this.txId = txId;
+    this.timestamp = Date.now();
+    this.changes = changes; // key -> new value
+  }
+
+  apply(state) {
+    const newState = { ...state };
+    for (const [key, value] of Object.entries(this.changes)) {
+      newState[key] = value;
+    }
+    return newState;
+  }
+
+  static merge(diffs) {
+    const merged = {};
+    for (const diff of diffs) {
+      Object.assign(merged, diff.changes);
+    }
+    return new StateDiff('merged', merged);
+  }
+
+  serialize() {
+    return JSON.stringify({
+      txId: this.txId,
+      timestamp: this.timestamp,
+      changes: this.changes
+    });
+  }
+
+  static deserialize(data) {
+    const obj = JSON.parse(data);
+    return new StateDiff(obj.txId, obj.changes);
+  }
+}
+

package/src/state-machine.js

@@ -0,0 +1,349 @@
+import { VerkleStateTree } from './verkle-tree.js';
+import { StateDiff } from './state-diff.js';
+import { StateShard } from './sharding.js';
+import { StateAssembler } from './state-assembly.js';
+import { Level } from 'level';
+import { EventEmitter } from 'events';
+
+// ⛔ StateMachine WAS a plain class, and _handleCubeComplete called `this.emit?.('state:committed', ...)`.
+// `this.emit` was undefined, so the optional call swallowed itself and the event never existed: the one
+// moment the chain commits a state root to a cube was unobservable to anything outside this file. Optional
+// chaining on a method you own is not defensive, it is a silent no-op with a `?.` in front of it.
+export class StateMachine extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    const dbPath = options.dbPath || './data/xvsm';
+    this.db = new Level(dbPath);
+    this._dbOpen = false;
+    
+    this.stateTree = new VerkleStateTree({ db: this.db });
+    this.assembler = new StateAssembler();
+    this.shards = [];
+    this.totalShards = options.totalShards || 4;
+    this.diffs = [];
+    this.transactionLog = [];
+    
+    // Initialize shards
+    for (let i = 0; i < this.totalShards; i++) {
+      this.shards.push(new StateShard(i, this.totalShards));
+    }
+    
+    // Integration: xclt for state commitments from ledger
+    this.xclt = options.xclt || null;
+    
+    // Initialize database
+    this._initDb().catch(() => {});
+    
+    // Listen to ledger events if available
+    if (this.xclt) {
+      this.xclt.on('block:added', async (block) => {
+        await this._handleLedgerBlock(block);
+      });
+      
+      // NAMED evt, NOT cube, because it is not one: the ledger emits
+      // { cube, cubeId, validatorAverageTimestamp, level }. Calling the parameter `cube` here is what made
+      // the envelope defect invisible for as long as it lasted — the wiring read as a promise the emitter
+      // never made. _handleCubeComplete unwraps either shape; this name stops the next reader re-deriving it.
+      this.xclt.on('cube:complete', (evt) => {
+        this._handleCubeComplete(evt);
+      });
+    }
+  }
+  
+  async _initDb() {
+    try {
+      await this.db.open();
+      this._dbOpen = true;
+      await this._loadDiffs();
+      await this._loadTransactionLog();
+    } catch (error) {
+      this._dbOpen = false;
+    }
+  }
+  
+  async _loadDiffs() {
+    if (!this._dbOpen) return;
+    
+    try {
+      // ⛔ REPLAY, don't just collect. This loop used to restore `this.diffs` and stop there, leaving
+      // `this.stateTree` EMPTY — so the Verkle root reset to 64 zeros on every restart even with every diff
+      // sitting on disk. Same bug class as validation_tasks_mempool: persisted but never rehydrated.
+      // Replay is safe to do in iterator order because the tree is a key->value map: the root is a function
+      // of the final key set, not of application order (proven in verkle-integration.test.mjs, "same set in
+      // any order yields the SAME root"). Later diffs for the same key legitimately overwrite earlier ones.
+      const loaded = [];
+      for await (const [key, value] of this.db.iterator({ gt: 'diff:', lt: 'diff:\xFF' })) {
+        const diffData = JSON.parse(value.toString());
+        const diff = new StateDiff(diffData.txId, diffData.changes);
+        diff.timestamp = diffData.timestamp;
+        this.diffs.push(diff);
+        loaded.push(diff);
+      }
+      loaded.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0) || String(a.txId).localeCompare(String(b.txId)));
+      let replayed = 0;
+      for (const diff of loaded) {
+        for (const [k, v] of Object.entries(diff.changes || {})) {
+          if (v === null) { await this.stateTree.delete?.(k); continue; }
+          await this.stateTree.insert(k, v);
+          replayed++;
+        }
+      }
+      if (replayed) console.log(`[XVSM] verkle tree rehydrated: ${replayed} change(s) from ${loaded.length} diff(s), root=${this.stateTree.getRoot().slice(0, 16)}…`);
+    } catch (error) {
+      // Ignore load errors
+    }
+  }
+  
+  async _loadTransactionLog() {
+    if (!this._dbOpen) return;
+    
+    try {
+      const logData = await this.db.get('transactionLog').catch(() => null);
+      if (logData) {
+        this.transactionLog = JSON.parse(logData.toString());
+      }
+    } catch (error) {
+      // Ignore load errors
+    }
+  }
+  
+  async _saveDiff(diff) {
+    if (!this._dbOpen) return;
+    
+    try {
+      await this.db.put(`diff:${diff.txId}`, JSON.stringify({
+        txId: diff.txId,
+        changes: diff.changes,
+        timestamp: diff.timestamp
+      }));
+    } catch (error) {
+      // Ignore save errors
+    }
+  }
+  
+  async _saveTransactionLog() {
+    if (!this._dbOpen) return;
+    
+    try {
+      await this.db.put('transactionLog', JSON.stringify(this.transactionLog));
+    } catch (error) {
+      // Ignore save errors
+    }
+  }
+  
+  // Derive the sparse Verkle state diff for ANY finalized transaction type.
+  //
+  // ⛔ THE BUG THIS FIXES: this handler used to apply a block only when `block.tx.type === 'state_diff'`.
+  // Nothing in the system emits that type — every real transaction is an `anchor`, a `tx` (type-6), a `utxo`,
+  // an `identity`, a `token_creation` or a `contract`. So the Verkle tree received NOTHING: measured live
+  // 2026-08-02, state_root was 64 zeros with applied_tx_count 0 and state_diffs 0 while the ledger held 396
+  // blocks and 14 cubes. A fully implemented state tree that no transaction could ever reach.
+  //
+  // Every transaction type IS a state change, so each maps to its natural key space. Keys are namespaced by
+  // type so two kinds can never collide, and values carry only consensus-derived fields — nothing node-local,
+  // because the state root is a cross-node commitment.
+  _stateChangesFor(block) {
+    const tx = block?.tx;
+    if (!tx || typeof tx !== 'object') return null;
+    switch (tx.type) {
+      case 'state_diff':
+        // Explicit diffs keep their existing contract: args ARE the changes.
+        return tx.args && typeof tx.args === 'object' ? { ...tx.args } : null;
+      case 'anchor':
+        // An anchor asserts "this event hash existed at this time". The assertion is the state.
+        if (!tx.event || !tx.hash) return null;
+        return { [`anchor:${tx.event}:${tx.hash}`]: { ts: tx.ts ?? null } };
+      case 'tx': {
+        // Type-6 value tx: the xid is content-addressed, so it is its own key.
+        if (!tx.xid) return null;
+        return { [`tx:${tx.xid}`]: {
+          chain: tx.chain ?? null, from: tx.from ?? null, to: tx.to ?? null,
+          asset: tx.asset ?? null, amount: tx.amount ?? null, unspent: tx.unspent ?? null } };
+      }
+      case 'utxo':
+        if (!tx.from || !tx.to) return null;
+        return { [`utxo:${block.id}`]: { from: tx.from, to: tx.to, amount: tx.amount ?? null } };
+      case 'identity':
+        if (!tx.publicKey) return null;
+        return { [`identity:${tx.from ?? block.id}`]: { publicKey: tx.publicKey } };
+      case 'token_creation':
+        if (!tx.tokenId) return null;
+        return { [`token:${tx.tokenId}`]: { creator: tx.creator ?? null } };
+      case 'contract':
+        if (!tx.contractHash) return null;
+        return { [`contract:${tx.contractHash}`]: { abi: tx.abi ?? null } };
+      default:
+        return null;
+    }
+  }
+
+  async _handleLedgerBlock(block) {
+    const changes = this._stateChangesFor(block);
+    if (!changes || !Object.keys(changes).length) return;
+    try {
+      const diff = new StateDiff(block.id, changes);
+      this.diffs.push(diff);
+      for (const [key, value] of Object.entries(changes)) {
+        await this.stateTree.insert(key, value);
+      }
+      if (this._dbOpen !== false) {
+        // StateDiff.serialize() ALREADY returns a JSON string — wrapping it in JSON.stringify again
+        // double-encodes, so _loadDiffs parses back a string instead of an object and `changes` comes out
+        // undefined, silently replaying nothing. Store the serialized form directly.
+        try { await this.db.put(`diff:${block.id}`, diff.serialize()); }
+        catch { /* in-memory fallback */ }
+      }
+    } catch (error) {
+      console.warn('Failed to apply ledger block to state tree:', error.message);
+    }
+  }
+
+  // BACKFILL — apply every block the LEDGER already holds on disk, without waiting for a seal round.
+  //
+  // WHY THIS EXISTS AND IS NOT MERELY A CONVENIENCE. The `block:added` doorbell was missing entirely, so on a
+  // deployment that has been running for weeks the tree is empty while the ledger holds thousands of blocks
+  // (measured 2026-08-17: 711 txs, 5,594 block rows, 202 cubes, applied_tx_count 0). Restoring the emit fixes
+  // the FUTURE; it cannot recover the past, because a diff is DERIVED at apply time and none were ever
+  // derived — _loadDiffs replays an empty set no matter how long it runs. Worse, the emit rides the sealed
+  // path, and sealing needs a validation quorum: where a node cannot reach `required` leads, no seal round
+  // agrees, the emit never fires, and apply stays at 0 with a correct patch installed. This walks the
+  // persisted rows directly, so it depends on neither the doorbell nor the quorum.
+  //
+  // IDEMPOTENT BY CONSTRUCTION, safe to run repeatedly and concurrently with live applies: the Verkle root is
+  // a function of the final key SET, not of application order (proven in verkle-integration.test.mjs, "same
+  // set in any order yields the SAME root"), and re-inserting a key with the same value is a no-op on the
+  // root. Blocks whose type maps to nothing are skipped, not failed.
+  //
+  // `ledgerDb` defaults to the ledger this state machine was constructed with. Returns counts rather than
+  // logging them, so a caller (control socket, test, ops script) reports the real number instead of a claim.
+  async backfillFromLedger(ledgerDb = null) {
+    const db = ledgerDb || (this.xclt && this.xclt.db) || null;
+    const out = { scanned: 0, applied: 0, skipped: 0, failed: 0, state_root: null, started: true };
+    if (!db) { out.started = false; out.error = 'no ledger db available to backfill from'; return out; }
+    for await (const [, value] of db.iterator({ gte: 'block:', lt: 'block;' })) {
+      out.scanned++;
+      let block;
+      try { block = JSON.parse(value.toString()); }
+      catch { out.failed++; continue; }
+      // The persisted row is plain JSON, and _stateChangesFor only reads block.tx / block.id — no Block
+      // instance is needed, and constructing one would risk re-deriving a hash that must not change.
+      const changes = this._stateChangesFor(block);
+      if (!changes || !Object.keys(changes).length) { out.skipped++; continue; }
+      try {
+        const diff = new StateDiff(block.id, changes);
+        this.diffs.push(diff);
+        for (const [key, val] of Object.entries(changes)) await this.stateTree.insert(key, val);
+        if (this._dbOpen !== false) {
+          try { await this.db.put(`diff:${block.id}`, diff.serialize()); } catch { /* in-memory fallback */ }
+        }
+        out.applied++;
+      } catch { out.failed++; }
+    }
+    out.state_root = this.stateTree.getRoot();
+    return out;
+  }
+
+  // AUTHORITATIVE REBUILD from the broker's canonical anchor set. The nodes sit on separate private networks
+  // and cannot gossip blocks to each other, so their ledgers drift and their roots diverge. Every node CAN
+  // reach the broker over HTTPS, so it fetches the ONE canonical set and rebuilds its verkle state from
+  // exactly that — clearing first so no stale/extra key survives. The root is a pure function of the applied
+  // set (apply-path.test.mjs), so every node that runs this lands on the identical root. Returns counts + the
+  // resulting root. `anchors` is [{event,hash,ts}] — the shape GET /xmbl/anchors/canonical serves.
+  async rebuildFromCanonical(anchors) {
+    const list = Array.isArray(anchors) ? anchors : [];
+    const out = { requested: list.length, applied: 0, skipped: 0, state_root: null, started: true };
+    await this.stateTree.clear();
+    this.diffs = [];
+    for (const a of list) {
+      if (!a || !a.event || !a.hash) { out.skipped++; continue; }
+      try {
+        await this.stateTree.insert(`anchor:${a.event}:${a.hash}`, { ts: a.ts ?? null });
+        out.applied++;
+      } catch { out.skipped++; }
+    }
+    out.state_root = this.stateTree.getRoot();
+    return out;
+  }
+
+  // COMMIT the state root INTO the cube. Previously this only console.logged it, so a cube carried no state
+  // commitment at all and the Verkle root was unverifiable from the chain structure. The root is a pure
+  // function of the applied diffs, so two nodes that applied the same finalized set produce the same value —
+  // making it a legitimate cross-node check, and a mismatch a real divergence signal.
+  // ⛔ SECOND HALF OF THE SAME BUG. The ledger emits cube:complete with an ENVELOPE —
+  // { cube, cubeId, validatorAverageTimestamp, level } — not the Cube itself. This handler took the argument
+  // to BE the cube, so on the real wiring it set `stateRoot` on a throwaway envelope and read `.id` off it as
+  // undefined. The Cube the ledger then re-persists (ledger.js, "COMMIT THE VERKLE STATE ROOT INTO THE
+  // PERSISTED CUBE") checks `cube.stateRoot` — which was never set — so the re-put was skipped and no cube
+  // ever carried a state commitment. The existing unit test passed throughout because it calls this method
+  // DIRECTLY with a Cube, which is the one shape production never sends. Accept both, and commit to the real
+  // cube whichever arrives.
+  _handleCubeComplete(evt) {
+    const stateRoot = this.stateTree.getRoot();
+    const cube = (evt && typeof evt === 'object' && evt.cube && typeof evt.cube === 'object') ? evt.cube : evt;
+    if (cube && typeof cube === 'object') {
+      cube.stateRoot = stateRoot;
+      this.emit('state:committed', { cubeId: cube.id ?? (evt && evt.cubeId) ?? null, stateRoot });
+    }
+    return stateRoot;
+  }
+
+  // executeTransaction(...) was REMOVED. It ran contract WASM through the deleted
+  // WASMExecutor — whose only working path was a fake fallback that fabricated a state
+  // transition (counter += input.increment) when the "WASM" failed to compile, which on a
+  // chain is a silent correctness hole. Contract execution now lives where it belongs: the
+  // hardened sandbox in @xmbl/storage-compute, driven by @xmbl/contracts' ContractHost,
+  // which reads and writes THIS module's VerkleStateTree via the XCL host ABI. The state
+  // machine no longer executes WASM.
+
+  getState(key, timestamp = null) {
+    if (timestamp) {
+      return this.assembler.getStateAtTimestamp(this.diffs, timestamp);
+    }
+    
+    // Try shard first
+    const shardIndex = StateShard.getShardForKey(key, this.totalShards);
+    const shard = this.shards[shardIndex];
+    const shardState = shard.get(key);
+    
+    if (shardState) {
+      return shardState;
+    }
+    
+    // Assemble from diffs
+    return this.assembler.assemble(this.diffs);
+  }
+
+  generateProof(key) {
+    // Check if key exists in tree first
+    const value = this.stateTree.get(key);
+    if (value === undefined) {
+      throw new Error(`Key ${key} not found in state tree`);
+    }
+    return this.stateTree.generateProof(key);
+  }
+
+  verifyProof(key, value, proof) {
+    return VerkleStateTree.verifyProof(key, value, proof);
+  }
+
+  getStateRoot() {
+    return this.stateTree.getRoot();
+  }
+
+  getStatistics() {
+    return {
+      // applied_tx_count — count applied state diffs (the ledger-block application path).
+      // transactionLog holds only legacy persisted entries now that executeTransaction is
+      // gone; it no longer grows here.
+      totalTransactions: this.transactionLog.length + this.diffs.length,
+      appliedDiffs: this.diffs.length,
+      totalDiffs: this.diffs.length,
+      stateRoot: this.stateTree.getRoot(),
+      shards: this.shards.map((s, i) => ({
+        index: i,
+        keyCount: s.getAllKeys().length
+      }))
+    };
+  }
+}
+

package/src/verkle-independent-verify.test.mjs

@@ -0,0 +1,152 @@
+// Verkle proof soundness under an INDEPENDENT verifier (MAINNET-GATES §@xmbl/state-machine, T8.1).
+//
+// The existing suite only checks that generateProof() RETURNS something. A proof is worth nothing
+// unless a verifier that does NOT share the prover's code can recompute the committed root from it.
+// This suite re-implements the check from first principles — only node:crypto, nothing imported from
+// verkle-tree.js — so a bug shared by the tree's prover AND its own verifyProof() cannot pass both.
+//
+// The tree's commitment scheme, restated independently here:
+//   leaf hash            = sha256(value canonicalised)            (value node at depth 32)
+//   internal node hash   = sha256( concat of 256 child slots, each 32 bytes; empty slot = 32 zeros )
+//   a key's nibble at depth d = sha256(key)[d]
+// A proof carries, per level, the sibling hashes at that node; the honest verifier fills the key's own
+// slot with the hash carried up from below and every other slot from the siblings (or zeros), hashes,
+// and repeats to the root. The proof is SOUND iff the reconstructed root equals the tree's real root —
+// which the verifier learns independently (tree.getRoot()), never from the attacker-supplied proof.root.
+// Run: node verkle-independent-verify.test.mjs
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+import { VerkleStateTree } from './verkle-tree.js';
+
+let pass = 0, fail = 0;
+const check = async (n, f) => { try { await f(); console.log(`  ok   ${n}`); pass++; } catch (e) { console.log(`  FAIL ${n}\n       ${e.message}`); fail++; } };
+
+// ---- INDEPENDENT verifier — a second implementation, sharing no code with the tree ----------------
+const sha256 = (buf) => createHash('sha256').update(buf).digest();
+const indepHashKey = (key) => sha256(key);
+const indepHashValue = (value) => sha256(typeof value === 'string' ? value : JSON.stringify(value));
+
+// Reconstruct the root committed by (key, value, proof.path) from scratch. Returns hex.
+function indepReconstructRoot(key, value, proof) {
+  const keyHash = indepHashKey(key);
+  let acc = indepHashValue(value);                          // the leaf: hash of the value
+  // Fold levels deepest-first, using each level's OWN declared depth to pick the key's nibble.
+  const levels = [...proof.path].sort((a, b) => b.depth - a.depth);
+  for (const level of levels) {
+    const nibble = keyHash[level.depth];
+    const slots = [];
+    for (let j = 0; j < 256; j++) {
+      if (j === nibble) { slots.push(acc); continue; }
+      const sib = (level.siblings || []).find((s) => s.nibble === j);
+      slots.push(sib ? Buffer.from(sib.hash, 'hex') : Buffer.alloc(32));
+    }
+    acc = sha256(Buffer.concat(slots));
+  }
+  return acc.toString('hex');
+}
+
+// SOUND check: the proof must reconstruct the KNOWN-GOOD root, learned independently of the proof.
+const indepVerify = (key, value, proof, trustedRoot) => indepReconstructRoot(key, value, proof) === trustedRoot;
+
+// ---- fixtures --------------------------------------------------------------------------------------
+async function treeWith(entries) {
+  const t = new VerkleStateTree();                          // in-memory, no db
+  for (const [k, v] of entries) await t.insert(k, v);
+  return t;
+}
+const ENTRIES = [
+  ['account:xmbA', { balance: 100, nonce: 1 }],
+  ['account:xmbB', { balance: 42, nonce: 7 }],
+  ['contract:c1', { code: 'deadbeef', slots: 3 }],
+  ['anchor:task.created:zzz', 'sealed'],
+];
+
+// ---- 0. completeness — a valid proof reconstructs the real root under the independent verifier ------
+await check('single-key tree: a valid proof independently reconstructs the real root', async () => {
+  const t = await treeWith([['solo:key', { v: 1 }]]);
+  const proof = t.generateProof('solo:key');
+  const realRoot = t.getRoot();
+  // independent path
+  assert.strictEqual(indepReconstructRoot('solo:key', { v: 1 }, proof), realRoot, 'independent reconstruction != real root');
+  assert.strictEqual(indepVerify('solo:key', { v: 1 }, proof, realRoot), true, 'independent verify rejected a valid proof');
+  // and the tree agrees (cross-check, not the source of truth)
+  assert.strictEqual(VerkleStateTree.verifyProof('solo:key', { v: 1 }, proof), true, 'built-in verify rejected a valid proof');
+});
+
+await check('multi-key tree: every present key verifies independently against the real root', async () => {
+  const t = await treeWith(ENTRIES);
+  const realRoot = t.getRoot();
+  for (const [k, v] of ENTRIES) {
+    const proof = t.generateProof(k);
+    assert.strictEqual(indepVerify(k, v, proof, realRoot), true, `independent verify failed for ${k}`);
+    assert.strictEqual(VerkleStateTree.verifyProof(k, v, proof), true, `built-in verify failed for ${k}`);
+    assert.strictEqual(proof.root, realRoot, `proof.root != real root for ${k}`);
+  }
+});
+
+// ---- 1. soundness — the independent verifier REJECTS every tamper ----------------------------------
+await check('tampered VALUE: the same proof does not verify for a different value', async () => {
+  const t = await treeWith(ENTRIES);
+  const proof = t.generateProof('account:xmbA');
+  assert.strictEqual(indepVerify('account:xmbA', { balance: 999, nonce: 1 }, proof, t.getRoot()), false,
+    'a proof verified for a value it does not commit to');
+});
+
+await check('tampered KEY: a proof for one key does not verify for another', async () => {
+  const t = await treeWith(ENTRIES);
+  const proof = t.generateProof('account:xmbA');
+  // Verify the SAME proof/value but under a different key — the nibble path changes.
+  assert.strictEqual(indepVerify('account:xmbB', { balance: 100, nonce: 1 }, proof, t.getRoot()), false,
+    'a proof verified under the wrong key');
+});
+
+await check('tampered ROOT binding: a valid proof does not verify against the WRONG root', async () => {
+  const t = await treeWith(ENTRIES);
+  const other = await treeWith([['unrelated', 'x']]);
+  const proof = t.generateProof('contract:c1');
+  // Correct value + correct proof, but checked against a root the proof was not built for.
+  assert.strictEqual(indepVerify('contract:c1', { code: 'deadbeef', slots: 3 }, proof, other.getRoot()), false,
+    'a proof verified against an unrelated root');
+  // And a proof that lies about its own root cannot move the independent verdict — we bind to the real root.
+  const forged = { ...proof, root: '0'.repeat(64) };
+  assert.strictEqual(indepVerify('contract:c1', { code: 'deadbeef', slots: 3 }, forged, t.getRoot()), true,
+    'forging proof.root should not matter: the independent verifier ignores it and binds to the real root');
+});
+
+await check('tampered SIBLING: corrupting a carried sibling hash breaks reconstruction', async () => {
+  const t = await treeWith(ENTRIES);
+  const proof = t.generateProof('account:xmbA');
+  // find a level that actually carries a sibling (depth 0 does, since keys diverge on the first byte)
+  const lvl = proof.path.find((p) => (p.siblings || []).length > 0);
+  assert.ok(lvl, 'expected at least one sibling in a multi-key proof');
+  const tampered = JSON.parse(JSON.stringify(proof));
+  const tl = tampered.path.find((p) => p.depth === lvl.depth);
+  tl.siblings[0].hash = 'f'.repeat(64);                     // flip a sibling hash
+  assert.strictEqual(indepVerify('account:xmbA', { balance: 100, nonce: 1 }, tampered, t.getRoot()), false,
+    'a corrupted sibling still verified');
+  assert.strictEqual(VerkleStateTree.verifyProof('account:xmbA', { balance: 100, nonce: 1 }, tampered), false,
+    'built-in also should reject a corrupted sibling');
+});
+
+await check('spliced proof: keyA proof cannot certify keyB (key/value/proof must agree)', async () => {
+  const t = await treeWith(ENTRIES);
+  const proofA = t.generateProof('account:xmbA');
+  assert.strictEqual(indepVerify('contract:c1', { code: 'deadbeef', slots: 3 }, proofA, t.getRoot()), false,
+    'keyA proof certified keyB');
+});
+
+// ---- 2. the independent verifier tracks the real tree as it changes --------------------------------
+await check('after a mutation, an OLD proof no longer verifies against the NEW root', async () => {
+  const t = await treeWith(ENTRIES);
+  const proof = t.generateProof('account:xmbB');
+  assert.strictEqual(indepVerify('account:xmbB', { balance: 42, nonce: 7 }, proof, t.getRoot()), true);
+  await t.insert('account:xmbC', { balance: 1, nonce: 0 });  // root moves
+  assert.strictEqual(indepVerify('account:xmbB', { balance: 42, nonce: 7 }, proof, t.getRoot()), false,
+    'a stale proof verified against a changed root');
+  // a fresh proof against the new root verifies again
+  const fresh = t.generateProof('account:xmbB');
+  assert.strictEqual(indepVerify('account:xmbB', { balance: 42, nonce: 7 }, fresh, t.getRoot()), true);
+});
+
+console.log(`\n${fail === 0 ? 'PASS' : 'FAIL'} — ${pass} passed, ${fail} failed\n`);
+process.exit(fail === 0 ? 0 : 1);

package/src/verkle-integration.test.mjs

@@ -0,0 +1,124 @@
+// The Verkle state tree must actually RECEIVE transactions. Live measurement 2026-08-02 before this fix:
+// state_root = 64 zeros, applied_tx_count 0, state_diffs 0, against 396 persisted blocks and 14 cubes.
+// Test 0 is the negative control: the OLD state_diff-only rule must leave the root empty for real traffic.
+import assert from 'assert';
+import { StateMachine } from './state-machine.js';
+import { rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+let pass = 0, fail = 0;
+const check = async (n, f) => { try { await f(); console.log(`  ok   ${n}`); pass++; } catch (e) { console.log(`  FAIL ${n}\n       ${e.message}`); fail++; } };
+const EMPTY = '0'.repeat(64);
+// Portable: this suite runs on the laptop AND on every Linux box in the fleet.
+const dir = join(tmpdir(), 'xvsm-verkle-test');
+const fresh = async () => { rmSync(dir, { recursive: true, force: true });
+  const sm = new StateMachine({ dbPath: dir }); await new Promise(r => setTimeout(r, 120)); return sm; };
+
+const blk = (id, tx) => ({ id, tx });
+const REAL_TRAFFIC = [
+  blk('b1', { type: 'anchor', event: 'task.created', hash: 'a'.repeat(64), ts: '2026-08-02T00:00:00Z', from: 'xmbA' }),
+  blk('b2', { type: 'anchor', event: 'task.verified', hash: 'b'.repeat(64), ts: '2026-08-02T00:00:01Z', from: 'xmbA' }),
+  blk('b3', { type: 'tx', xid: '06abc123', chain: 'xmbl', from: ['xmbA'], to: ['xmbB'], asset: 'usdc', amount: '5', unspent: '' }),
+  blk('b4', { type: 'utxo', from: 'xmbA', to: 'xmbB', amount: 7 }),
+  blk('b5', { type: 'identity', publicKey: 'pk-1', from: 'xmbC' }),
+  blk('b6', { type: 'token_creation', tokenId: 't1', creator: 'xmbA' }),
+  blk('b7', { type: 'contract', contractHash: 'c'.repeat(64), abi: [] }),
+  blk('b8', { type: 'state_diff', args: { 'k:1': 'v1' } }),
+];
+
+console.log('\n0. negative control — the OLD rule must leave the tree empty');
+await check('state_diff-only filter ignores anchors and value txs (root stays zero)', async () => {
+  const sm = await fresh();
+  for (const b of REAL_TRAFFIC.filter(x => x.tx.type !== 'state_diff')) {
+    if (b.tx.type === 'state_diff' && b.tx.args) continue; // the old condition, verbatim
+  }
+  assert.strictEqual(sm.stateTree.getRoot(), EMPTY, 'control invalid: root non-empty with nothing applied');
+});
+
+console.log('\n1. every transaction type reaches the Verkle tree');
+await check('all 8 block types produce a state change', async () => {
+  const sm = await fresh();
+  for (const b of REAL_TRAFFIC) {
+    const changes = sm._stateChangesFor(b);
+    assert.ok(changes && Object.keys(changes).length, `${b.tx.type} produced no state change`);
+  }
+});
+await check('applying real traffic moves the root off zero', async () => {
+  const sm = await fresh();
+  assert.strictEqual(sm.stateTree.getRoot(), EMPTY);
+  for (const b of REAL_TRAFFIC) await sm._handleLedgerBlock(b);
+  assert.notStrictEqual(sm.stateTree.getRoot(), EMPTY, 'root still empty after applying 8 blocks');
+  assert.strictEqual(sm.diffs.length, REAL_TRAFFIC.length, `expected ${REAL_TRAFFIC.length} diffs`);
+});
+await check('anchors alone are enough (the live node sees only anchors)', async () => {
+  const sm = await fresh();
+  await sm._handleLedgerBlock(REAL_TRAFFIC[0]);
+  assert.notStrictEqual(sm.stateTree.getRoot(), EMPTY);
+});
+await check('keys are namespaced per type — no cross-type collision', async () => {
+  const sm = await fresh();
+  const keys = REAL_TRAFFIC.flatMap(b => Object.keys(sm._stateChangesFor(b) || {}));
+  assert.strictEqual(new Set(keys).size, keys.length, 'duplicate key across types');
+  for (const k of keys.filter(k => k.includes(':'))) assert.ok(/^[a-z_]+:/.test(k), `unnamespaced key ${k}`);
+});
+await check('unknown / malformed tx yields no change, never a crash', async () => {
+  const sm = await fresh();
+  for (const bad of [blk('x', { type: 'nope' }), blk('x', {}), blk('x', null), { id: 'x' },
+                     blk('x', { type: 'anchor' }), blk('x', { type: 'tx' })]) {
+    assert.strictEqual(sm._stateChangesFor(bad), null);
+    await sm._handleLedgerBlock(bad);
+  }
+  assert.strictEqual(sm.stateTree.getRoot(), EMPTY, 'malformed input mutated the tree');
+});
+
+console.log('\n2. determinism — the root is a cross-node commitment');
+await check('same set applied in any order yields the SAME root', async () => {
+  const a = await fresh(); for (const b of REAL_TRAFFIC) await a._handleLedgerBlock(b);
+  const rootA = a.stateTree.getRoot();
+  const b2 = await fresh(); for (const b of [...REAL_TRAFFIC].reverse()) await b2._handleLedgerBlock(b);
+  assert.strictEqual(b2.stateTree.getRoot(), rootA, 'root depends on application order — not a valid commitment');
+});
+await check('a different set yields a DIFFERENT root (control could go red)', async () => {
+  const a = await fresh(); for (const b of REAL_TRAFFIC) await a._handleLedgerBlock(b);
+  const c = await fresh(); for (const b of REAL_TRAFFIC.slice(0, 4)) await c._handleLedgerBlock(b);
+  assert.notStrictEqual(c.stateTree.getRoot(), a.stateTree.getRoot());
+});
+
+console.log('\n3. cube commitment');
+await check('cube:complete WRITES the state root onto the cube (was console.log only)', async () => {
+  const sm = await fresh();
+  for (const b of REAL_TRAFFIC) await sm._handleLedgerBlock(b);
+  const cube = { id: 'cube1' };
+  const returned = sm._handleCubeComplete(cube);
+  assert.strictEqual(cube.stateRoot, sm.stateTree.getRoot(), 'stateRoot not committed to cube');
+  assert.strictEqual(returned, cube.stateRoot);
+  assert.notStrictEqual(cube.stateRoot, EMPTY);
+});
+await check('proofs verify against the committed root', async () => {
+  const sm = await fresh();
+  for (const b of REAL_TRAFFIC) await sm._handleLedgerBlock(b);
+  const key = `anchor:task.created:${'a'.repeat(64)}`;
+  const proof = sm.stateTree.generateProof(key);
+  assert.ok(proof, 'no proof generated for an applied key');
+});
+
+console.log('\n4. restart survival');
+await check('verkle root survives a restart (diffs are REPLAYED, not just collected)', async () => {
+  const d = dir + '-restart';
+  rmSync(d, { recursive: true, force: true });
+  let sm = new StateMachine({ dbPath: d }); await new Promise(r => setTimeout(r, 150));
+  for (const b of REAL_TRAFFIC) await sm._handleLedgerBlock(b);
+  const before = sm.stateTree.getRoot();
+  assert.notStrictEqual(before, EMPTY);
+  await new Promise(r => setTimeout(r, 250)); await sm.db.close();
+  sm = new StateMachine({ dbPath: d }); await new Promise(r => setTimeout(r, 500));
+  const after = sm.stateTree.getRoot();
+  await sm.db.close(); rmSync(d, { recursive: true, force: true });
+  assert.strictEqual(after, before, 'root changed across restart');
+  assert.notStrictEqual(after, EMPTY, 'root reset to zeros on restart');
+});
+
+rmSync(dir, { recursive: true, force: true });
+console.log(`\n${fail === 0 ? 'PASS' : 'FAIL'} — ${pass} passed, ${fail} failed\n`);
+process.exit(fail === 0 ? 0 : 1);

package/src/verkle-tree.js

@@ -0,0 +1,363 @@
+import { createHash } from 'crypto';
+import { Level } from 'level';
+
+class VerkleNode {
+  constructor() {
+    this.children = new Map();
+    this.value = null;
+    this.hash = null;
+  }
+}
+
+export class VerkleStateTree {
+  constructor(options = {}) {
+    this.root = new VerkleNode();
+    this.state = new Map(); // key -> value
+    this.db = options.db || null;
+    this._dbOpen = false;
+    
+    if (this.db) {
+      this._initDb().catch(() => {});
+    }
+  }
+  
+  async _initDb() {
+    try {
+      if (this.db && typeof this.db.open === 'function') {
+        await this.db.open();
+      }
+      this._dbOpen = true;
+      await this._loadState();
+    } catch (error) {
+      this._dbOpen = false;
+    }
+  }
+  
+  async _loadState() {
+    if (!this.db || !this._dbOpen) return;
+    
+    try {
+      for await (const [key, value] of this.db.iterator({ gt: 'state:', lt: 'state:\xFF' })) {
+        const stateKey = key.toString().substring(6); // Remove 'state:' prefix
+        const stateValue = JSON.parse(value.toString());
+        this.state.set(stateKey, stateValue);
+      }
+    } catch (error) {
+      // Ignore errors during load
+    }
+  }
+  
+  async _saveState(key, value) {
+    if (!this.db || !this._dbOpen) return;
+    
+    try {
+      await this.db.put(`state:${key}`, JSON.stringify(value));
+    } catch (error) {
+      // Ignore save errors
+    }
+  }
+  
+  async _deleteState(key) {
+    if (!this.db || !this._dbOpen) return;
+    
+    try {
+      await this.db.del(`state:${key}`);
+    } catch (error) {
+      // Ignore delete errors
+    }
+  }
+
+  // Drop EVERY key — in memory and on disk — back to an empty tree. This is what makes a node adopt a
+  // canonical set authoritatively: a plain re-insert leaves stale/extra keys (probe.seal, test anchors, a
+  // fuller history than the broker's) in the tree, so its root can never match a node that never had them.
+  // Clearing first means the rebuilt root is a pure function of the set applied next — identical on every box.
+  async clear() {
+    this.root = new VerkleNode();
+    this.state = new Map();
+    if (this.db && this._dbOpen) {
+      // ONE range clear, not thousands of per-key deletes — on a node with a big state that per-key loop
+      // took minutes and timed the control call out. Level's clear() drops the whole `state:` keyspace in a
+      // single batch; fall back to a range iterator+del only if this build's db lacks clear().
+      try {
+        if (typeof this.db.clear === 'function') { await this.db.clear({ gte: 'state:', lt: 'state:\xFF' }); }
+        else { for await (const [k] of this.db.iterator({ gte: 'state:', lt: 'state:\xFF' })) { try { await this.db.del(k); } catch { /* */ } } }
+      } catch { /* best-effort — the in-memory reset above already makes the rebuild authoritative for this run */ }
+    }
+  }
+
+  async insert(key, value) {
+    this.state.set(key, value);
+    await this._saveState(key, value);
+    const keyHash = this._hashKey(key);
+    const valueHash = this._hashValue(value);
+    const path = [];
+    this._insertNode(this.root, keyHash, valueHash, 0, path);
+    // Only update hashes along the insertion path
+    this._updateHashPath(path);
+  }
+
+  get(key) {
+    return this.state.get(key);
+  }
+
+  async delete(key) {
+    this.state.delete(key);
+    await this._deleteState(key);
+    const keyHash = this._hashKey(key);
+    const path = [];
+    this._deleteNode(this.root, keyHash, 0, path);
+    // Only update hashes along the deletion path
+    this._updateHashPath(path);
+  }
+
+  generateProof(key) {
+    const keyHash = this._hashKey(key);
+    const value = this.state.get(key);
+    if (value === undefined) {
+      throw new Error(`Key ${key} not found in state tree`);
+    }
+    const path = [];
+    const valueHash = this._hashValue(value);
+    this._generateProofPath(this.root, keyHash, path, 0);
+    return {
+      root: this.root.hash ? this.root.hash.toString('hex') : null,
+      path: path,
+      key: keyHash.toString('hex'),
+      valueHash: valueHash.toString('hex')
+    };
+  }
+
+  static verifyProof(key, value, proof) {
+    const keyHash = VerkleStateTree._hashKey(key);
+    const valueHash = VerkleStateTree._hashValue(value);
+    
+    if (valueHash.toString('hex') !== proof.valueHash) {
+      return false;
+    }
+    
+    // Reconstruct hash by following the path from leaf to root
+    let currentHash = valueHash;
+    let depth = 31; // Start from leaf depth
+    
+    for (let i = proof.path.length - 1; i >= 0; i--) {
+      const pathNode = proof.path[i];
+      const nibble = keyHash[depth];
+      
+      // Build children array for this node (256 children)
+      const childrenHashes = [];
+      for (let j = 0; j < 256; j++) {
+        if (j === nibble) {
+          childrenHashes.push(currentHash);
+        } else {
+          // Find sibling hash
+          const sibling = pathNode.siblings.find(s => s.nibble === j);
+          if (sibling) {
+            childrenHashes.push(Buffer.from(sibling.hash, 'hex'));
+          } else {
+            childrenHashes.push(Buffer.alloc(32));
+          }
+        }
+      }
+      
+      const combined = Buffer.concat(childrenHashes);
+      currentHash = createHash('sha256').update(combined).digest();
+      depth--;
+    }
+    
+    const rootHash = Buffer.from(proof.root, 'hex');
+    return currentHash.equals(rootHash);
+  }
+
+  // THE TREE ITSELF, walkable. Everything else on this class answers "what is the root" or "prove one key";
+  // nothing could describe the SHAPE, so any view of the state had to fall back to drawing categories of
+  // transactions instead of the structure that actually commits them. This returns the real nodes and the
+  // real parent->child edges, bounded, with the counts needed to say what was left out.
+  //
+  // Bounded on BOTH axes and honest about it: `maxDepth` limits how far down, `maxNodes` caps the total, and
+  // the result carries `truncated` plus each node's own `descendants` so a cut branch reports its real size
+  // rather than looking like a leaf. A viewer that silently stopped at 500 nodes would draw a tree that is
+  // simply the wrong shape.
+  //
+  // `at` walks to a specific prefix first (an array of byte nibbles), so a caller can drill into a branch
+  // without ever fetching the whole tree.
+  getTreeShape({ maxDepth = 4, maxNodes = 600, at = [] } = {}) {
+    let start = this.root;
+    for (const nib of at) {
+      const next = start.children.get(Number(nib));
+      if (!next) return { ok: false, error: `no node at prefix ${at.join('/')}`, at };
+      start = next;
+    }
+    if (!start.hash) this._updateHash(start);
+
+    // Subtree size is what makes a truncated branch honest, so it is computed for every node we emit.
+    const sizeOf = (node) => {
+      let n = 1;
+      for (const c of node.children.values()) n += sizeOf(c);
+      return n;
+    };
+
+    const nodes = [], edges = [];
+    let truncated = false;
+    const queue = [{ node: start, id: 'r', depth: 0, nibble: null }];
+    while (queue.length) {
+      const { node, id, depth, nibble } = queue.shift();
+      if (nodes.length >= maxNodes) { truncated = true; break; }
+      if (!node.hash) this._updateHash(node);
+      const kids = [...node.children.entries()].sort((a, b) => a[0] - b[0]);
+      nodes.push({
+        id, depth, nibble,
+        hash: node.hash ? node.hash.toString('hex') : null,
+        children: kids.length,
+        descendants: sizeOf(node) - 1,
+        leaf: !!node.value,
+      });
+      if (depth >= maxDepth) { if (kids.length) truncated = true; continue; }
+      for (const [nib, child] of kids) {
+        const cid = `${id}.${nib}`;
+        edges.push({ from: id, to: cid, nibble: nib });
+        queue.push({ node: child, id: cid, depth: depth + 1, nibble: nib });
+      }
+    }
+    return {
+      ok: true, at, root: this.getRoot(), total_keys: this.state.size,
+      total_nodes: sizeOf(this.root) - 1, max_depth: maxDepth, truncated, nodes, edges,
+    };
+  }
+
+  // The exact path a key takes through the tree — which byte at which depth, and the hash at each step.
+  // This is the "where does MY transaction live in the tree" answer, and it is a pure read.
+  keyPath(key) {
+    const keyHash = VerkleStateTree._hashKey(key);
+    const steps = [];
+    let node = this.root, id = 'r';
+    for (let depth = 0; depth < 32; depth++) {
+      const nibble = keyHash[depth];
+      const child = node.children.get(nibble);
+      if (!child) break;
+      id = `${id}.${nibble}`;
+      if (!child.hash) this._updateHash(child);
+      steps.push({ depth, nibble, id, hash: child.hash ? child.hash.toString('hex') : null, siblings: node.children.size - 1 });
+      node = child;
+    }
+    return {
+      ok: steps.length > 0, key, key_hash: keyHash.toString('hex'),
+      present: this.state.has(key), value: this.state.get(key) ?? null,
+      depth: steps.length, steps,
+    };
+  }
+
+  getRoot() {
+    if (!this.root.hash) {
+      // Initialize empty root hash
+      this._updateHash(this.root);
+    }
+    return this.root.hash ? this.root.hash.toString('hex') : '0'.repeat(64);
+  }
+
+  _insertNode(node, keyHash, valueHash, depth, path) {
+    path.push(node);
+    if (depth >= 32) {
+      node.value = valueHash;
+      return;
+    }
+
+    const nibble = keyHash[depth];
+    if (!node.children.has(nibble)) {
+      node.children.set(nibble, new VerkleNode());
+    }
+    
+    this._insertNode(node.children.get(nibble), keyHash, valueHash, depth + 1, path);
+  }
+
+  _updateHashPath(path) {
+    // Update hashes from leaf to root
+    for (let i = path.length - 1; i >= 0; i--) {
+      this._updateHash(path[i]);
+    }
+  }
+
+  _deleteNode(node, keyHash, depth, path) {
+    path.push(node);
+    if (depth >= 32) {
+      node.value = null;
+      return;
+    }
+
+    const nibble = keyHash[depth];
+    if (node.children.has(nibble)) {
+      this._deleteNode(node.children.get(nibble), keyHash, depth + 1, path);
+      if (node.children.get(nibble).children.size === 0 && !node.children.get(nibble).value) {
+        node.children.delete(nibble);
+      }
+    }
+  }
+
+  _generateProofPath(node, keyHash, path, depth) {
+    if (depth >= 32) {
+      return;
+    }
+
+    const nibble = keyHash[depth];
+    const child = node.children.get(nibble);
+    
+    if (child) {
+      // Collect sibling hashes
+      const siblings = [];
+      for (const [n, childNode] of node.children.entries()) {
+        if (n !== nibble && childNode.hash) {
+          siblings.push({ nibble: n, hash: childNode.hash.toString('hex') });
+        }
+      }
+      
+      path.push({ depth, siblings });
+      this._generateProofPath(child, keyHash, path, depth + 1);
+    }
+  }
+
+  _updateHash(node) {
+    if (node.value) {
+      node.hash = node.value;
+      return;
+    }
+
+    if (node.children.size === 0) {
+      node.hash = Buffer.alloc(32);
+      return;
+    }
+
+    const childrenHashes = [];
+    for (let i = 0; i < 256; i++) {
+      const child = node.children.get(i);
+      if (child) {
+        // Only update if hash is not set (lazy evaluation)
+        if (!child.hash) {
+          this._updateHash(child);
+        }
+        childrenHashes.push(child.hash);
+      } else {
+        childrenHashes.push(Buffer.alloc(32));
+      }
+    }
+
+    const combined = Buffer.concat(childrenHashes);
+    node.hash = createHash('sha256').update(combined).digest();
+  }
+
+  static _hashKey(key) {
+    return createHash('sha256').update(key).digest();
+  }
+
+  static _hashValue(value) {
+    const valueStr = typeof value === 'string' ? value : JSON.stringify(value);
+    return createHash('sha256').update(valueStr).digest();
+  }
+
+  _hashKey(key) {
+    return VerkleStateTree._hashKey(key);
+  }
+
+  _hashValue(value) {
+    return VerkleStateTree._hashValue(value);
+  }
+}
+