@aztec/world-state 0.0.1-commit.2f68f620 → 0.0.1-commit.3100065

package/dest/native/ipc_world_state_instance.js

@@ -1,139 +1,38 @@
+import { AsyncApi } from '@aztec/bb.js/aztec-wsdb';
 import { ARCHIVE_HEIGHT, DomainSeparator, L1_TO_L2_MSG_TREE_HEIGHT, MAX_NULLIFIERS_PER_TX, MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX, NOTE_HASH_TREE_HEIGHT, NULLIFIER_TREE_HEIGHT, PUBLIC_DATA_TREE_HEIGHT } from '@aztec/constants';
 import { createLogger } from '@aztec/foundation/log';
 import { MerkleTreeId } from '@aztec/stdlib/trees';
-import { WsdbService } from '@aztec/wsdb';
-import { cpus } from 'node:os';
+import assert from 'assert';
+import { Decoder, Encoder } from 'msgpackr';
+import { WorldStateMessageType, isWithCanonical, isWithForkId, isWithRevision } from './message.js';
+import { WorldStateOpsQueue } from './world_state_ops_queue.js';
+// ————— Msgpack helpers —————
+const msgpackEncoder = new Encoder({
+    useRecords: false
+});
+const msgpackDecoder = new Decoder({
+    useRecords: false
+});
+/** Msgpack-encode a SerializedLeafValue into bytes for IPC transport. */ function serializeLeafToBytes(leaf) {
+    return Buffer.from(msgpackEncoder.pack(leaf));
+}
 // ————— Request conversion helpers —————
 function toWsdbRevision(rev) {
     return {
-        forkId: rev.forkId,
-        blockNumber: Number(rev.blockNumber),
-        includeUncommitted: rev.includeUncommitted
+        forkid: rev.forkId,
+        blocknumber: Number(rev.blockNumber),
+        includeuncommitted: rev.includeUncommitted
     };
 }
 function blockStateRefToMap(ref) {
-    return [
-        ...ref.entries()
-    ].map(([treeId, [root, size]])=>({
-            treeId,
-            root: new Uint8Array(root),
-            size: Number(size)
-        }));
-}
-function toPublicDataLeaf(leaf) {
-    if (leaf instanceof Buffer || !('slot' in leaf)) {
-        throw new Error('Expected public data leaf');
-    }
-    return {
-        slot: new Uint8Array(leaf.slot),
-        value: new Uint8Array(leaf.value)
-    };
-}
-function toNullifierLeaf(leaf) {
-    if (leaf instanceof Buffer || !('nullifier' in leaf)) {
-        throw new Error('Expected nullifier leaf');
-    }
-    return {
-        nullifier: new Uint8Array(leaf.nullifier)
-    };
-}
-function fromPublicDataLeaf(leaf) {
-    return {
-        slot: Buffer.from(leaf.slot),
-        value: Buffer.from(leaf.value)
-    };
-}
-function fromNullifierLeaf(leaf) {
-    return {
-        nullifier: Buffer.from(leaf.nullifier)
-    };
-}
-function fromIndexedLeaf(leaf, convertLeaf) {
-    return {
-        leaf: convertLeaf(leaf.leaf),
-        nextIndex: leaf.nextIndex,
-        nextKey: Buffer.from(leaf.nextKey)
-    };
-}
-function fromLeafUpdateWitnessData(data, convertLeaf) {
-    return {
-        leaf: fromIndexedLeaf(data.leaf, convertLeaf),
-        index: data.index,
-        path: data.path.map((p)=>Buffer.from(p))
-    };
-}
-function fromBatchInsertionResult(result, convertLeaf) {
-    return {
-        lowLeafWitnessData: result.lowLeafWitnessData.map((data)=>fromLeafUpdateWitnessData(data, convertLeaf)),
-        sortedLeaves: result.sortedLeaves.map(({ leaf, index })=>[
-                convertLeaf(leaf),
-                index
-            ]),
-        subtreePath: result.subtreePath.map((p)=>Buffer.from(p))
-    };
-}
-function fromSequentialInsertionResult(result, convertLeaf) {
-    return {
-        lowLeafWitnessData: result.lowLeafWitnessData.map((data)=>fromLeafUpdateWitnessData(data, convertLeaf)),
-        insertionWitnessData: result.insertionWitnessData.map((data)=>fromLeafUpdateWitnessData(data, convertLeaf))
-    };
-}
-function toFrLeaf(leaf) {
-    if (!(leaf instanceof Buffer)) {
-        throw new Error('Expected field leaf');
+    const result = new Map();
+    for (const [treeId, [root, size]] of ref.entries()){
+        result.set(treeId, [
+            new Uint8Array(root),
+            Number(size)
+        ]);
     }
-    return new Uint8Array(leaf);
-}
-function formatMap(map) {
-    if (!map || Object.keys(map).length === 0) {
-        return undefined;
-    }
-    return `{${Object.entries(map).map(([key, value])=>`${key}:${value}`).join(',')}}`;
-}
-/** SHM request/response ring size for the spawned aztec-wsdb process (32 MiB). */ const WSDB_SHM_RING_SIZE = 32 * 1024 * 1024;
-function getWsdbThreadCount() {
-    return Math.min(16, cpus().length);
-}
-function getWsdbExtraArgs(dataDir, wsTreeMapSizes, genesis, threads) {
-    const options = getWsdbOptions(dataDir, wsTreeMapSizes);
-    const args = [
-        '--data-dir',
-        dataDir,
-        '--threads',
-        threads.toString()
-    ];
-    // Size the SHM rings generously. Responses such as batch-insertion witnesses
-    // run to a few MB, and an SHM frame is capped at half the ring (the wrap
-    // handling needs that headroom), so 32 MiB rings give ~16 MiB per message.
-    // Ignored by the UDS transport. Pages are demand-faulted, so unused capacity
-    // is cheap.
-    args.push('--request-ring-size', WSDB_SHM_RING_SIZE.toString());
-    args.push('--response-ring-size', WSDB_SHM_RING_SIZE.toString());
-    const treeHeights = formatMap(options.treeHeights);
-    if (treeHeights) {
-        args.push('--tree-heights', treeHeights);
-    }
-    const treePrefill = formatMap(options.treePrefill);
-    if (treePrefill) {
-        args.push('--tree-prefill', treePrefill);
-    }
-    const mapSizes = formatMap(options.mapSizes);
-    if (mapSizes) {
-        args.push('--map-sizes', mapSizes);
-    }
-    args.push('--initial-header-generator-point', options.initialHeaderGeneratorPoint.toString());
-    if (genesis.prefilledPublicData.length > 0) {
-        const pairs = genesis.prefilledPublicData.map((data)=>[
-                data.slot.toBuffer().toString('hex'),
-                data.value.toBuffer().toString('hex')
-            ]);
-        args.push('--prefilled-public-data', JSON.stringify(pairs));
-    }
-    const genesisTimestamp = Number(genesis.genesisTimestamp);
-    if (genesisTimestamp !== 0) {
-        args.push('--genesis-timestamp', genesisTimestamp.toString());
-    }
-    return args;
+    return result;
 }
 // ————— Response conversion helpers —————
 /** Convert Uint8Array fields to Buffer recursively (for opaque blob responses). */ function convertUint8ArraysToBuffers(obj) {
@@ -152,49 +51,57 @@ function getWsdbExtraArgs(dataDir, wsTreeMapSizes, genesis, threads) {
     }
     return obj;
 }
+/** Decode a msgpack-encoded leaf value blob and convert Uint8Arrays to Buffers. */ function decodeLeafValue(encoded) {
+    const decoded = msgpackDecoder.unpack(Buffer.from(encoded));
+    return convertUint8ArraysToBuffers(decoded);
+}
+/** Decode a msgpack-encoded indexed leaf preimage blob. */ function decodeLeafPreimage(encoded) {
+    const decoded = msgpackDecoder.unpack(Buffer.from(encoded));
+    return convertUint8ArraysToBuffers(decoded);
+}
 /** Convert Wsdb state reference (Record<number, [Uint8Array, number]>) to NAPI format. */ function convertStateRef(state) {
     const result = {};
-    for (const { treeId, root, size } of state){
-        result[treeId] = [
+    for (const [key, [root, size]] of Object.entries(state)){
+        result[Number(key)] = [
             Buffer.from(root),
             BigInt(size)
         ];
     }
     return result;
 }
-/** Convert Wsdb WorldStateStatusSummary to the native world-state format. */ function convertStatusSummary(s) {
+/** Convert Wsdb WorldStateStatusSummary (lowercase) to NAPI format (camelCase). */ function convertStatusSummary(s) {
     return {
-        unfinalizedBlockNumber: s.unfinalizedBlockNumber,
-        finalizedBlockNumber: s.finalizedBlockNumber,
-        oldestHistoricalBlock: s.oldestHistoricalBlock,
-        treesAreSynched: s.treesAreSynched
+        unfinalizedBlockNumber: s.unfinalizedblocknumber,
+        finalizedBlockNumber: s.finalizedblocknumber,
+        oldestHistoricalBlock: s.oldesthistoricalblock,
+        treesAreSynched: s.treesaresynched
     };
 }
 function convertDBStats(s) {
     return {
         name: s.name,
-        numDataItems: s.numDataItems,
-        totalUsedSize: s.totalUsedSize
+        numDataItems: s.numdataitems,
+        totalUsedSize: s.totalusedsize
     };
 }
 function convertTreeDBStats(s) {
     return {
-        mapSize: s.mapSize,
-        physicalFileSize: s.physicalFileSize,
-        blocksDBStats: convertDBStats(s.blocksDBStats),
-        nodesDBStats: convertDBStats(s.nodesDBStats),
-        leafPreimagesDBStats: convertDBStats(s.leafPreimagesDBStats),
-        leafIndicesDBStats: convertDBStats(s.leafIndicesDBStats),
-        blockIndicesDBStats: convertDBStats(s.blockIndicesDBStats)
+        mapSize: s.mapsize,
+        physicalFileSize: s.physicalfilesize,
+        blocksDBStats: convertDBStats(s.blocksdbstats),
+        nodesDBStats: convertDBStats(s.nodesdbstats),
+        leafPreimagesDBStats: convertDBStats(s.leafpreimagesdbstats),
+        leafIndicesDBStats: convertDBStats(s.leafindicesdbstats),
+        blockIndicesDBStats: convertDBStats(s.blockindicesdbstats)
     };
 }
 function convertWorldStateDBStats(s) {
     return {
-        noteHashTreeStats: convertTreeDBStats(s.noteHashTreeStats),
-        messageTreeStats: convertTreeDBStats(s.messageTreeStats),
-        archiveTreeStats: convertTreeDBStats(s.archiveTreeStats),
-        publicDataTreeStats: convertTreeDBStats(s.publicDataTreeStats),
-        nullifierTreeStats: convertTreeDBStats(s.nullifierTreeStats)
+        noteHashTreeStats: convertTreeDBStats(s.notehashtreestats),
+        messageTreeStats: convertTreeDBStats(s.messagetreestats),
+        archiveTreeStats: convertTreeDBStats(s.archivetreestats),
+        publicDataTreeStats: convertTreeDBStats(s.publicdatatreestats),
+        nullifierTreeStats: convertTreeDBStats(s.nullifiertreestats)
     };
 }
 function convertTreeMeta(m) {
@@ -202,28 +109,28 @@ function convertTreeMeta(m) {
         name: m.name,
         depth: m.depth,
         size: m.size,
-        committedSize: m.committedSize,
+        committedSize: m.committedsize,
         root: m.root,
-        initialSize: m.initialSize,
-        initialRoot: m.initialRoot,
-        oldestHistoricBlock: m.oldestHistoricBlock,
-        unfinalizedBlockHeight: m.unfinalizedBlockHeight,
-        finalizedBlockHeight: m.finalizedBlockHeight
+        initialSize: m.initialsize,
+        initialRoot: m.initialroot,
+        oldestHistoricBlock: m.oldesthistoricblock,
+        unfinalizedBlockHeight: m.unfinalizedblockheight,
+        finalizedBlockHeight: m.finalizedblockheight
     };
 }
 function convertWorldStateMeta(m) {
     return {
-        noteHashTreeMeta: convertTreeMeta(m.noteHashTreeMeta),
-        messageTreeMeta: convertTreeMeta(m.messageTreeMeta),
-        archiveTreeMeta: convertTreeMeta(m.archiveTreeMeta),
-        publicDataTreeMeta: convertTreeMeta(m.publicDataTreeMeta),
-        nullifierTreeMeta: convertTreeMeta(m.nullifierTreeMeta)
+        noteHashTreeMeta: convertTreeMeta(m.notehashtreemeta),
+        messageTreeMeta: convertTreeMeta(m.messagetreemeta),
+        archiveTreeMeta: convertTreeMeta(m.archivetreemeta),
+        publicDataTreeMeta: convertTreeMeta(m.publicdatatreemeta),
+        nullifierTreeMeta: convertTreeMeta(m.nullifiertreemeta)
     };
 }
 function convertStatusFull(s) {
     return {
         summary: convertStatusSummary(s.summary),
-        dbStats: convertWorldStateDBStats(s.dbStats),
+        dbStats: convertWorldStateDBStats(s.dbstats),
         meta: convertWorldStateMeta(s.meta)
     };
 }
@@ -236,405 +143,473 @@ function convertStatusFull(s) {
         path: s.path.map((p)=>Buffer.from(p))
     };
 }
-// ————— Public API —————
 /**
  * IPC-backed world state instance.
- * Uses WsdbService (spawns aztec-wsdb binary) and the generated AsyncApi
+ * Uses WsdbBackend (spawns aztec-wsdb binary) and the generated AsyncApi
  * to communicate via the NamedUnion IPC protocol.
  */ export class IpcWorldState {
-    wsdb;
+    wsdbBackend;
     instrumentation;
     log;
     open;
+    queues;
     api;
     /** Tracks checkpoint depth per fork (WSDB IPC doesn't return depth in response). */ checkpointDepths;
-    constructor(wsdb, instrumentation, bindings, log = createLogger('world-state:ipc-database', bindings)){
-        this.wsdb = wsdb;
+    constructor(wsdbBackend, instrumentation, bindings, log = createLogger('world-state:ipc-database', bindings)){
+        this.wsdbBackend = wsdbBackend;
         this.instrumentation = instrumentation;
         this.log = log;
         this.open = true;
+        this.queues = new Map();
         this.checkpointDepths = new Map();
-        this.api = wsdb;
+        this.api = new AsyncApi(wsdbBackend);
+        this.queues.set(0, new WorldStateOpsQueue());
         this.log.info('Created IPC-backed world state instance');
     }
+    /** Returns the socket path of the underlying wsdb server. */ getSocketPath() {
+        return this.wsdbBackend.getSocketPath();
+    }
     /**
-   * Spawn an `aztec-wsdb` subprocess and return an IPC-backed world state wrapping it.
-   * Encapsulates wsdb binary discovery, service construction, and readiness wait.
-   */ static async spawn(dataDir, wsTreeMapSizes, genesis, instrumentation, bindings) {
-        const threads = getWsdbThreadCount();
-        const transport = process.env.WSDB_TRANSPORT === 'shm' ? 'shm' : 'uds';
-        const wsdb = await WsdbService.spawn({
-            transport,
-            extraArgs: getWsdbExtraArgs(dataDir, wsTreeMapSizes, genesis, threads),
-            env: {
-                HARDWARE_CONCURRENCY: threads.toString()
+   * Required by `NativeWorldStateInstance` for compatibility with the in-process
+   * NAPI path. The IPC backend does not expose an in-process pointer; callers that
+   * need to reach the WSDB process must use {@link getSocketPath} instead.
+   */ getHandle() {
+        throw new Error('IpcWorldState has no in-process handle; use getSocketPath() instead');
+    }
+    async call(messageType, body, responseHandler = (response)=>response, errorHandler = (_)=>{}) {
+        let forkId = -1;
+        let committedOnly = false;
+        if (isWithCanonical(body)) {
+            forkId = 0;
+        } else if (isWithForkId(body)) {
+            forkId = body.forkId;
+        } else if (isWithRevision(body)) {
+            forkId = body.revision.forkId;
+            committedOnly = body.revision.includeUncommitted === false;
+        } else {
+            const _ = body;
+            throw new Error(`Unable to determine forkId for message=${WorldStateMessageType[messageType]}`);
+        }
+        let requestQueue = this.queues.get(forkId);
+        if (requestQueue === undefined) {
+            requestQueue = new WorldStateOpsQueue();
+            this.queues.set(forkId, requestQueue);
+        }
+        // The per-fork queue is cleaned up in `finally` even on error, so the JS-side queues map cannot outlive
+        // the native fork (e.g. when the native fork was already destroyed by an unwind/historical-prune and
+        // DELETE_FORK rejects with "Fork not found").
+        let shouldDeleteForkQueue = false;
+        try {
+            const response = await requestQueue.execute(async ()=>{
+                assert.notEqual(messageType, WorldStateMessageType.CLOSE, 'Use close() to close the IPC instance');
+                assert.equal(this.open, true, 'IPC instance is closed');
+                let response;
+                try {
+                    response = await this._sendMessage(messageType, body);
+                } catch (error) {
+                    errorHandler(error.message);
+                    throw error;
+                }
+                return responseHandler(response);
+            }, messageType, committedOnly);
+            return response;
+        } catch (err) {
+            shouldDeleteForkQueue = forkId !== 0 && err?.message === 'Fork not found';
+            throw err;
+        } finally{
+            if (messageType === WorldStateMessageType.DELETE_FORK || shouldDeleteForkQueue) {
+                await requestQueue.stop();
+                this.queues.delete(forkId);
             }
-        });
-        return new IpcWorldState(wsdb, instrumentation, bindings);
-    }
-    getIpcPath() {
-        return this.wsdb.getIpcPath();
+        }
     }
     async close() {
         if (!this.open) {
             return;
         }
         this.open = false;
-        await this.wsdb.destroy();
-    }
-    getTreeInfo(treeId, revision) {
-        return this.execute('getTreeInfo', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = await this.api.getTreeInfo({
-                treeId,
-                revision: toWsdbRevision(revision)
-            });
-            return {
-                treeId: resp.treeId,
-                root: Buffer.from(resp.root),
-                size: BigInt(resp.size),
-                depth: resp.depth
-            };
-        });
-    }
-    getStateReference(revision) {
-        return this.execute('getStateReference', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = await this.api.getStateReference({
-                revision: toWsdbRevision(revision)
-            });
-            return convertStateRef(resp.state);
-        });
-    }
-    getInitialStateReference() {
-        return this.execute('getInitialStateReference', 0, false, async ()=>{
-            const resp = await this.api.getInitialStateReference({});
-            return convertStateRef(resp.state);
-        });
-    }
-    getLeafValue(treeId, revision, leafIndex) {
-        return this.execute('getLeafValue', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const wsdbRevision = toWsdbRevision(revision);
-            const wsdbLeafIndex = Number(leafIndex);
-            if (treeId === MerkleTreeId.PUBLIC_DATA_TREE) {
-                const resp = await this.api.getPublicDataLeafValue({
-                    revision: wsdbRevision,
-                    leafIndex: wsdbLeafIndex
-                });
-                return resp.value ? fromPublicDataLeaf(resp.value) : undefined;
-            }
-            if (treeId === MerkleTreeId.NULLIFIER_TREE) {
-                const resp = await this.api.getNullifierLeafValue({
-                    revision: wsdbRevision,
-                    leafIndex: wsdbLeafIndex
-                });
-                return resp.value ? fromNullifierLeaf(resp.value) : undefined;
-            }
-            const resp = await this.api.getLeafValue({
-                treeId,
-                revision: wsdbRevision,
-                leafIndex: wsdbLeafIndex
-            });
-            return resp.value ? Buffer.from(resp.value) : undefined;
-        });
-    }
-    getLeafPreimage(treeId, revision, leafIndex) {
-        return this.execute('getLeafPreimage', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = treeId === MerkleTreeId.PUBLIC_DATA_TREE ? await this.api.getPublicDataLeafPreimage({
-                revision: toWsdbRevision(revision),
-                leafIndex: Number(leafIndex)
-            }) : await this.api.getNullifierLeafPreimage({
-                revision: toWsdbRevision(revision),
-                leafIndex: Number(leafIndex)
-            });
-            return resp.preimage ? convertUint8ArraysToBuffers(resp.preimage) : undefined;
-        });
-    }
-    getSiblingPath(treeId, revision, leafIndex) {
-        return this.execute('getSiblingPath', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = await this.api.getSiblingPath({
-                treeId,
-                revision: toWsdbRevision(revision),
-                leafIndex: Number(leafIndex)
-            });
-            return resp.path.map((p)=>Buffer.from(p));
-        });
-    }
-    getBlockNumbersForLeafIndices(treeId, revision, leafIndices) {
-        return this.execute('getBlockNumbersForLeafIndices', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = await this.api.getBlockNumbersForLeafIndices({
-                treeId,
-                revision: toWsdbRevision(revision),
-                leafIndices: leafIndices.map(Number)
-            });
-            return resp.blockNumbers.map((n)=>n != null ? BigInt(n) : undefined);
-        });
-    }
-    findLeafIndices(treeId, revision, leaves, startIndex) {
-        return this.execute('findLeafIndices', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const wsdbRevision = toWsdbRevision(revision);
-            const wsdbStartIndex = Number(startIndex);
-            const resp = treeId === MerkleTreeId.PUBLIC_DATA_TREE ? await this.api.findPublicDataLeafIndices({
-                revision: wsdbRevision,
-                leaves: leaves.map(toPublicDataLeaf),
-                startIndex: wsdbStartIndex
-            }) : treeId === MerkleTreeId.NULLIFIER_TREE ? await this.api.findNullifierLeafIndices({
-                revision: wsdbRevision,
-                leaves: leaves.map(toNullifierLeaf),
-                startIndex: wsdbStartIndex
-            }) : await this.api.findLeafIndices({
-                treeId,
-                revision: wsdbRevision,
-                leaves: leaves.map(toFrLeaf),
-                startIndex: wsdbStartIndex
-            });
-            return resp.indices.map((n)=>n != null ? BigInt(n) : undefined);
-        });
-    }
-    findLowLeaf(treeId, revision, key) {
-        return this.execute('findLowLeaf', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const resp = await this.api.findLowLeaf({
-                treeId,
-                revision: toWsdbRevision(revision),
-                key: new Uint8Array(key.toBuffer())
-            });
-            return {
-                alreadyPresent: resp.alreadyPresent,
-                index: BigInt(resp.index)
-            };
-        });
-    }
-    findSiblingPaths(treeId, revision, leaves) {
-        return this.execute('findSiblingPaths', revision.forkId, revision.includeUncommitted === false, async ()=>{
-            const wsdbRevision = toWsdbRevision(revision);
-            const resp = treeId === MerkleTreeId.PUBLIC_DATA_TREE ? await this.api.findPublicDataSiblingPaths({
-                revision: wsdbRevision,
-                leaves: leaves.map(toPublicDataLeaf)
-            }) : treeId === MerkleTreeId.NULLIFIER_TREE ? await this.api.findNullifierSiblingPaths({
-                revision: wsdbRevision,
-                leaves: leaves.map(toNullifierLeaf)
-            }) : await this.api.findSiblingPaths({
-                treeId,
-                revision: wsdbRevision,
-                leaves: leaves.map(toFrLeaf)
-            });
-            return resp.paths.map(convertSiblingPathAndIndex);
-        });
-    }
-    updateArchive(forkId, blockStateRef, blockHeaderHash) {
-        return this.execute('updateArchive', forkId, false, async ()=>{
-            await this.api.updateArchive({
-                blockStateRef: blockStateRefToMap(blockStateRef),
-                blockHeaderHash: new Uint8Array(blockHeaderHash),
-                forkId
-            });
-        });
-    }
-    appendLeaves(treeId, forkId, leaves) {
-        return this.execute('appendLeaves', forkId, false, async ()=>{
-            if (treeId === MerkleTreeId.PUBLIC_DATA_TREE) {
-                await this.api.appendPublicDataLeaves({
-                    leaves: leaves.map(toPublicDataLeaf),
-                    forkId
-                });
-            } else if (treeId === MerkleTreeId.NULLIFIER_TREE) {
-                await this.api.appendNullifierLeaves({
-                    leaves: leaves.map(toNullifierLeaf),
-                    forkId
-                });
-            } else {
-                await this.api.appendLeaves({
-                    treeId,
-                    leaves: leaves.map(toFrLeaf),
-                    forkId
-                });
-            }
-        });
-    }
-    batchInsert(treeId, forkId, leaves, subtreeDepth) {
-        return this.execute('batchInsert', forkId, false, async ()=>{
-            const resp = treeId === MerkleTreeId.PUBLIC_DATA_TREE ? await this.api.batchInsertPublicData({
-                leaves: leaves.map(toPublicDataLeaf),
-                subtreeDepth,
-                forkId
-            }) : await this.api.batchInsertNullifier({
-                leaves: leaves.map(toNullifierLeaf),
-                subtreeDepth,
-                forkId
-            });
-            return treeId === MerkleTreeId.PUBLIC_DATA_TREE ? fromBatchInsertionResult(resp.result, fromPublicDataLeaf) : fromBatchInsertionResult(resp.result, fromNullifierLeaf);
-        });
-    }
-    sequentialInsert(treeId, forkId, leaves) {
-        return this.execute('sequentialInsert', forkId, false, async ()=>{
-            const resp = treeId === MerkleTreeId.PUBLIC_DATA_TREE ? await this.api.sequentialInsertPublicData({
-                leaves: leaves.map(toPublicDataLeaf),
-                forkId
-            }) : await this.api.sequentialInsertNullifier({
-                leaves: leaves.map(toNullifierLeaf),
-                forkId
-            });
-            return treeId === MerkleTreeId.PUBLIC_DATA_TREE ? fromSequentialInsertionResult(resp.result, fromPublicDataLeaf) : fromSequentialInsertionResult(resp.result, fromNullifierLeaf);
-        });
-    }
-    syncBlock(input) {
-        return this.execute('syncBlock', 0, false, async ()=>{
-            const resp = await this.api.syncBlock({
-                blockNumber: Number(input.blockNumber),
-                blockStateRef: blockStateRefToMap(input.blockStateRef),
-                blockHeaderHash: new Uint8Array(input.blockHeaderHash),
-                paddedNoteHashes: input.paddedNoteHashes.map(toFrLeaf),
-                paddedL1ToL2Messages: input.paddedL1ToL2Messages.map(toFrLeaf),
-                paddedNullifiers: input.paddedNullifiers.map(toNullifierLeaf),
-                publicDataWrites: input.publicDataWrites.map(toPublicDataLeaf)
-            });
-            return convertStatusFull(resp.status);
-        });
-    }
-    createFork(input) {
-        return this.execute('createFork', 0, false, async ()=>{
-            const resp = await this.api.createFork({
-                latest: input.latest,
-                blockNumber: Number(input.blockNumber)
-            });
-            return resp.forkId;
-        });
-    }
-    deleteFork(forkId) {
-        return this.execute('deleteFork', forkId, false, async ()=>{
-            await this.api.deleteFork({
-                forkId
-            });
-        });
-    }
-    finalizeBlocks(toBlockNumber) {
-        return this.execute('finalizeBlocks', 0, false, async ()=>{
-            const resp = await this.api.finalizeBlocks({
-                toBlockNumber: Number(toBlockNumber)
-            });
-            return convertStatusSummary(resp.status);
-        });
-    }
-    unwindBlocks(toBlockNumber) {
-        return this.execute('unwindBlocks', 0, false, async ()=>{
-            const resp = await this.api.unwindBlocks({
-                toBlockNumber: Number(toBlockNumber)
-            });
-            return convertStatusFull(resp.status);
-        });
-    }
-    removeHistoricalBlocks(toBlockNumber) {
-        return this.execute('removeHistoricalBlocks', 0, false, async ()=>{
-            const resp = await this.api.removeHistoricalBlocks({
-                toBlockNumber: Number(toBlockNumber)
-            });
-            return convertStatusFull(resp.status);
-        });
-    }
-    getStatus() {
-        return this.execute('getStatus', 0, false, async ()=>{
-            const resp = await this.api.getStatus({});
-            return convertStatusSummary(resp.status);
-        });
-    }
-    createCheckpoint(forkId) {
-        return this.execute('createCheckpoint', forkId, false, async ()=>{
-            await this.api.createCheckpoint({
-                forkId
-            });
-            const depth = (this.checkpointDepths.get(forkId) ?? 0) + 1;
-            this.checkpointDepths.set(forkId, depth);
-            return depth;
-        });
-    }
-    commitCheckpoint(forkId) {
-        return this.execute('commitCheckpoint', forkId, false, async ()=>{
-            await this.api.commitCheckpoint({
-                forkId
-            });
-            const depth = Math.max(0, (this.checkpointDepths.get(forkId) ?? 0) - 1);
-            this.checkpointDepths.set(forkId, depth);
-        });
-    }
-    revertCheckpoint(forkId) {
-        return this.execute('revertCheckpoint', forkId, false, async ()=>{
-            await this.api.revertCheckpoint({
-                forkId
-            });
-            const depth = Math.max(0, (this.checkpointDepths.get(forkId) ?? 0) - 1);
-            this.checkpointDepths.set(forkId, depth);
-        });
-    }
-    commitAllCheckpoints(forkId, depth) {
-        return this.execute('commitAllCheckpoints', forkId, false, async ()=>{
-            const currentDepth = this.checkpointDepths.get(forkId) ?? 0;
-            if (depth === 0) {
-                await this.api.commitAllCheckpoints({
-                    forkId
-                });
-            } else {
-                for(let d = currentDepth; d > depth; d--){
-                    await this.api.commitCheckpoint({
-                        forkId
-                    });
-                }
-            }
-            this.checkpointDepths.set(forkId, depth);
-        });
-    }
-    revertAllCheckpoints(forkId, depth) {
-        return this.execute('revertAllCheckpoints', forkId, false, async ()=>{
-            const currentDepth = this.checkpointDepths.get(forkId) ?? 0;
-            if (depth === 0) {
-                await this.api.revertAllCheckpoints({
-                    forkId
-                });
-            } else {
-                for(let d = currentDepth; d > depth; d--){
-                    await this.api.revertCheckpoint({
-                        forkId
-                    });
-                }
-            }
-            this.checkpointDepths.set(forkId, depth);
-        });
-    }
-    copyStores(dstPath, compact) {
-        return this.execute('copyStores', 0, false, async ()=>{
-            await this.api.copyStores({
-                dstPath,
-                compact
-            });
-        });
-    }
-    // Read/write ordering is enforced server-side by the wsdb per-fork scheduler,
-    // so the client no longer queues: every op is sent immediately and the server
-    // serializes writes per fork while running reads concurrently. `_forkId` and
-    // `_committedOnly` are retained in the signature (they describe the op) but are
-    // no longer needed for client-side ordering.
-    async execute(operation, _forkId, _committedOnly, request) {
-        if (!this.open) {
-            throw new Error('IPC instance is closed');
+        const queue = this.queues.get(0);
+        // Send shutdown command. Under normal operation, the WSDB process sends its
+        // response before exiting (via ShutdownRequested in ipc_server.hpp). The
+        // try/catch is defensive: if the process is killed externally (SIGKILL, OOM)
+        // before responding, the pending IPC callback would be rejected by the socket
+        // close handler. We proceed to destroy the backend regardless.
+        try {
+            await queue.execute(async ()=>{
+                await this.api.wsdbShutdown({});
+            }, WorldStateMessageType.CLOSE, false);
+        } catch (err) {
+            this.log.debug(`wsdbShutdown completed with error: ${err.message}`);
+        }
+        await queue.stop();
+        if (this.wsdbBackend.destroy) {
+            await this.wsdbBackend.destroy();
         }
-        return await this.send(operation, request);
     }
-    async send(operation, request) {
+    async _sendMessage(messageType, body) {
         const start = performance.now();
         try {
-            const response = await request();
+            const response = await this.dispatch(messageType, body);
             const durationMs = performance.now() - start;
-            this.log.trace(`Call ${operation} took (ms)`, {
+            this.log.trace(`Call ${WorldStateMessageType[messageType]} took (ms)`, {
                 duration: durationMs
             });
-            this.instrumentation.recordRoundTrip(durationMs * 1000, operation);
+            this.instrumentation.recordRoundTrip(durationMs * 1000, messageType);
             return response;
         } catch (error) {
-            this.log.error(`Call ${operation} failed: ${error}`, error);
+            this.log.error(`Call ${WorldStateMessageType[messageType]} failed: ${error}`, error);
             throw error;
         }
     }
+    async dispatch(messageType, body) {
+        switch(messageType){
+            // ——— Tree info & state reference ———
+            case WorldStateMessageType.GET_TREE_INFO:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetTreeInfo({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision)
+                    });
+                    return {
+                        treeId: resp.treeid,
+                        root: Buffer.from(resp.root),
+                        size: resp.size,
+                        depth: resp.depth
+                    };
+                }
+            case WorldStateMessageType.GET_STATE_REFERENCE:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetStateReference({
+                        revision: toWsdbRevision(b.revision)
+                    });
+                    return {
+                        state: convertStateRef(resp.state)
+                    };
+                }
+            case WorldStateMessageType.GET_INITIAL_STATE_REFERENCE:
+                {
+                    const resp = await this.api.wsdbGetInitialStateReference({});
+                    return {
+                        state: convertStateRef(resp.state)
+                    };
+                }
+            // ——— Leaf queries ———
+            case WorldStateMessageType.GET_LEAF_VALUE:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetLeafValue({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leafindex: Number(b.leafIndex)
+                    });
+                    if (!resp.value) {
+                        return undefined;
+                    }
+                    return decodeLeafValue(resp.value);
+                }
+            case WorldStateMessageType.GET_LEAF_PREIMAGE:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetLeafPreimage({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leafindex: Number(b.leafIndex)
+                    });
+                    if (!resp.preimage) {
+                        return undefined;
+                    }
+                    return decodeLeafPreimage(resp.preimage);
+                }
+            case WorldStateMessageType.GET_SIBLING_PATH:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetSiblingPath({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leafindex: Number(b.leafIndex)
+                    });
+                    return resp.path.map((p)=>Buffer.from(p));
+                }
+            case WorldStateMessageType.GET_BLOCK_NUMBERS_FOR_LEAF_INDICES:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbGetBlockNumbersForLeafIndices({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leafindices: b.leafIndices.map(Number)
+                    });
+                    return {
+                        blockNumbers: resp.blocknumbers.map((n)=>n != null ? BigInt(n) : undefined)
+                    };
+                }
+            // ——— Find operations ———
+            case WorldStateMessageType.FIND_LEAF_INDICES:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbFindLeafIndices({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leaves: b.leaves.map(serializeLeafToBytes),
+                        startindex: Number(b.startIndex)
+                    });
+                    return {
+                        indices: resp.indices.map((n)=>n != null ? BigInt(n) : undefined)
+                    };
+                }
+            case WorldStateMessageType.FIND_LOW_LEAF:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbFindLowLeaf({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        key: new Uint8Array(b.key.toBuffer())
+                    });
+                    return {
+                        alreadyPresent: resp.alreadypresent,
+                        index: BigInt(resp.index)
+                    };
+                }
+            case WorldStateMessageType.FIND_SIBLING_PATHS:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbFindSiblingPaths({
+                        treeid: b.treeId,
+                        revision: toWsdbRevision(b.revision),
+                        leaves: b.leaves.map(serializeLeafToBytes)
+                    });
+                    return {
+                        paths: resp.paths.map(convertSiblingPathAndIndex)
+                    };
+                }
+            // ——— Mutations ———
+            case WorldStateMessageType.APPEND_LEAVES:
+                {
+                    const b = body;
+                    await this.api.wsdbAppendLeaves({
+                        treeid: b.treeId,
+                        leaves: b.leaves.map(serializeLeafToBytes),
+                        forkid: b.forkId
+                    });
+                    return undefined;
+                }
+            case WorldStateMessageType.BATCH_INSERT:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbBatchInsert({
+                        treeid: b.treeId,
+                        leaves: b.leaves.map(serializeLeafToBytes),
+                        subtreedepth: b.subtreeDepth,
+                        forkid: b.forkId
+                    });
+                    const decoded = msgpackDecoder.unpack(Buffer.from(resp.result));
+                    return convertUint8ArraysToBuffers(decoded);
+                }
+            case WorldStateMessageType.SEQUENTIAL_INSERT:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbSequentialInsert({
+                        treeid: b.treeId,
+                        leaves: b.leaves.map(serializeLeafToBytes),
+                        forkid: b.forkId
+                    });
+                    const decoded = msgpackDecoder.unpack(Buffer.from(resp.result));
+                    return convertUint8ArraysToBuffers(decoded);
+                }
+            case WorldStateMessageType.UPDATE_ARCHIVE:
+                {
+                    const b = body;
+                    await this.api.wsdbUpdateArchive({
+                        blockstateref: blockStateRefToMap(b.blockStateRef),
+                        blockheaderhash: new Uint8Array(b.blockHeaderHash),
+                        forkid: b.forkId
+                    });
+                    return undefined;
+                }
+            // ——— Commit / Rollback ———
+            case WorldStateMessageType.COMMIT:
+                {
+                    await this.api.wsdbCommit({});
+                    return undefined;
+                }
+            case WorldStateMessageType.ROLLBACK:
+                {
+                    await this.api.wsdbRollback({});
+                    return undefined;
+                }
+            // ——— Block sync ———
+            case WorldStateMessageType.SYNC_BLOCK:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbSyncBlock({
+                        blocknumber: Number(b.blockNumber),
+                        blockstateref: blockStateRefToMap(b.blockStateRef),
+                        blockheaderhash: new Uint8Array(b.blockHeaderHash),
+                        // Forwarded so the wsdb (IPC) sync path enforces the same archive-root divergence check as the napi path.
+                        expectedarchiveroot: new Uint8Array(b.expectedArchiveRoot),
+                        expectedpreviousarchiveroot: new Uint8Array(b.expectedPreviousArchiveRoot),
+                        paddednotehashes: b.paddedNoteHashes.map((l)=>new Uint8Array(l)),
+                        paddedl1tol2messages: b.paddedL1ToL2Messages.map((l)=>new Uint8Array(l)),
+                        paddednullifiers: b.paddedNullifiers.map((l)=>({
+                                nullifier: new Uint8Array(l.nullifier)
+                            })),
+                        publicdatawrites: b.publicDataWrites.map((l)=>({
+                                slot: new Uint8Array(l.slot),
+                                value: new Uint8Array(l.value)
+                            }))
+                    });
+                    return convertStatusFull(resp.status);
+                }
+            // ——— Fork management ———
+            case WorldStateMessageType.CREATE_FORK:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbCreateFork({
+                        latest: b.latest,
+                        blocknumber: Number(b.blockNumber)
+                    });
+                    return {
+                        forkId: resp.forkid
+                    };
+                }
+            case WorldStateMessageType.DELETE_FORK:
+                {
+                    const b = body;
+                    await this.api.wsdbDeleteFork({
+                        forkid: b.forkId
+                    });
+                    return undefined;
+                }
+            // ——— Block finalization ———
+            case WorldStateMessageType.FINALIZE_BLOCKS:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbFinalizeBlocks({
+                        toblocknumber: Number(b.toBlockNumber)
+                    });
+                    return convertStatusSummary(resp.status);
+                }
+            case WorldStateMessageType.UNWIND_BLOCKS:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbUnwindBlocks({
+                        toblocknumber: Number(b.toBlockNumber)
+                    });
+                    return convertStatusFull(resp.status);
+                }
+            case WorldStateMessageType.REMOVE_HISTORICAL_BLOCKS:
+                {
+                    const b = body;
+                    const resp = await this.api.wsdbRemoveHistoricalBlocks({
+                        toblocknumber: Number(b.toBlockNumber)
+                    });
+                    return convertStatusFull(resp.status);
+                }
+            // ——— Status ———
+            case WorldStateMessageType.GET_STATUS:
+                {
+                    const resp = await this.api.wsdbGetStatus({});
+                    return convertStatusSummary(resp.status);
+                }
+            // ——— Checkpoints ———
+            case WorldStateMessageType.CREATE_CHECKPOINT:
+                {
+                    const b = body;
+                    await this.api.wsdbCreateCheckpoint({
+                        forkid: b.forkId
+                    });
+                    const depth = (this.checkpointDepths.get(b.forkId) ?? 0) + 1;
+                    this.checkpointDepths.set(b.forkId, depth);
+                    return {
+                        depth
+                    };
+                }
+            case WorldStateMessageType.COMMIT_CHECKPOINT:
+                {
+                    const b = body;
+                    await this.api.wsdbCommitCheckpoint({
+                        forkid: b.forkId
+                    });
+                    const depth = Math.max(0, (this.checkpointDepths.get(b.forkId) ?? 0) - 1);
+                    this.checkpointDepths.set(b.forkId, depth);
+                    return undefined;
+                }
+            case WorldStateMessageType.REVERT_CHECKPOINT:
+                {
+                    const b = body;
+                    await this.api.wsdbRevertCheckpoint({
+                        forkid: b.forkId
+                    });
+                    const depth = Math.max(0, (this.checkpointDepths.get(b.forkId) ?? 0) - 1);
+                    this.checkpointDepths.set(b.forkId, depth);
+                    return undefined;
+                }
+            case WorldStateMessageType.COMMIT_ALL_CHECKPOINTS:
+                {
+                    const b = body;
+                    const targetDepth = b.depth ?? 0;
+                    const currentDepth = this.checkpointDepths.get(b.forkId) ?? 0;
+                    if (targetDepth === 0) {
+                        // Commit everything — use the bulk operation
+                        await this.api.wsdbCommitAllCheckpoints({
+                            forkid: b.forkId
+                        });
+                    } else {
+                        // Commit one level at a time down to target depth
+                        for(let d = currentDepth; d > targetDepth; d--){
+                            await this.api.wsdbCommitCheckpoint({
+                                forkid: b.forkId
+                            });
+                        }
+                    }
+                    this.checkpointDepths.set(b.forkId, targetDepth);
+                    return undefined;
+                }
+            case WorldStateMessageType.REVERT_ALL_CHECKPOINTS:
+                {
+                    const b = body;
+                    const targetDepth = b.depth ?? 0;
+                    const currentDepth = this.checkpointDepths.get(b.forkId) ?? 0;
+                    if (targetDepth === 0) {
+                        // Revert everything — use the bulk operation
+                        await this.api.wsdbRevertAllCheckpoints({
+                            forkid: b.forkId
+                        });
+                    } else {
+                        // Revert one level at a time down to target depth
+                        for(let d = currentDepth; d > targetDepth; d--){
+                            await this.api.wsdbRevertCheckpoint({
+                                forkid: b.forkId
+                            });
+                        }
+                    }
+                    this.checkpointDepths.set(b.forkId, targetDepth);
+                    return undefined;
+                }
+            // ——— Misc ———
+            case WorldStateMessageType.COPY_STORES:
+                {
+                    const b = body;
+                    await this.api.wsdbCopyStores({
+                        dstpath: b.dstPath,
+                        compact: b.compact
+                    });
+                    return undefined;
+                }
+            case WorldStateMessageType.CLOSE:
+                {
+                    await this.api.wsdbShutdown({});
+                    return undefined;
+                }
+            default:
+                throw new Error(`Unknown message type: ${messageType}`);
+        }
+    }
 }
 /**
  * Helper to create WsdbOptions from standard world state config.
- * Returns the options needed to construct a wsdb service command line.
+ * Returns the options needed to construct a WsdbBackend.
  */ export function getWsdbOptions(dataDir, wsTreeMapSizes) {
     return {
         treeHeights: {