@aztec/world-state 0.0.1-commit.a5db02d → 0.0.1-commit.aa0c64f

package/dest/native/ipc_world_state_instance.js

@@ -1,38 +1,148 @@
-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 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));
-}
+import { WsdbService } from '@aztec/wsdb';
+import { cpus } from 'node:os';
 // ————— 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) {
-    const result = new Map();
-    for (const [treeId, [root, size]] of ref.entries()){
-        result.set(treeId, [
-            new Uint8Array(root),
-            Number(size)
-        ]);
+    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 result;
+    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');
+    }
+    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 prefilledNullifiers = genesis.prefilledNullifiers ?? [];
+    for(let i = 1; i < prefilledNullifiers.length; i++){
+        if (prefilledNullifiers[i].toBigInt() <= prefilledNullifiers[i - 1].toBigInt()) {
+            throw new Error('Prefilled genesis nullifiers must be unique and strictly increasing');
+        }
+    }
+    if (prefilledNullifiers.length > 0) {
+        args.push('--prefilled-nullifiers', JSON.stringify(prefilledNullifiers.map((nullifier)=>nullifier.toBuffer().toString('hex'))));
+    }
+    const genesisTimestamp = Number(genesis.genesisTimestamp);
+    if (genesisTimestamp !== 0) {
+        args.push('--genesis-timestamp', genesisTimestamp.toString());
+    }
+    return args;
 }
 // ————— Response conversion helpers —————
 /** Convert Uint8Array fields to Buffer recursively (for opaque blob responses). */ function convertUint8ArraysToBuffers(obj) {
@@ -51,57 +161,49 @@ function blockStateRefToMap(ref) {
     }
     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 [key, [root, size]] of Object.entries(state)){
-        result[Number(key)] = [
+    for (const { treeId, root, size } of state){
+        result[treeId] = [
             Buffer.from(root),
             BigInt(size)
         ];
     }
     return result;
 }
-/** Convert Wsdb WorldStateStatusSummary (lowercase) to NAPI format (camelCase). */ function convertStatusSummary(s) {
+/** Convert Wsdb WorldStateStatusSummary to the native world-state format. */ 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) {
@@ -109,28 +211,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)
     };
 }
@@ -143,473 +245,406 @@ function convertStatusFull(s) {
         path: s.path.map((p)=>Buffer.from(p))
     };
 }
+// ————— Public API —————
 /**
  * IPC-backed world state instance.
- * Uses WsdbBackend (spawns aztec-wsdb binary) and the generated AsyncApi
+ * Uses WsdbService (spawns aztec-wsdb binary) and the generated AsyncApi
  * to communicate via the NamedUnion IPC protocol.
  */ export class IpcWorldState {
-    wsdbBackend;
+    wsdb;
     instrumentation;
     log;
     open;
-    queues;
     api;
     /** Tracks checkpoint depth per fork (WSDB IPC doesn't return depth in response). */ checkpointDepths;
-    constructor(wsdbBackend, instrumentation, bindings, log = createLogger('world-state:ipc-database', bindings)){
-        this.wsdbBackend = wsdbBackend;
+    constructor(wsdb, instrumentation, bindings, log = createLogger('world-state:ipc-database', bindings)){
+        this.wsdb = wsdb;
         this.instrumentation = instrumentation;
         this.log = log;
         this.open = true;
-        this.queues = new Map();
         this.checkpointDepths = new Map();
-        this.api = new AsyncApi(wsdbBackend);
-        this.queues.set(0, new WorldStateOpsQueue());
+        this.api = wsdb;
         this.log.info('Created IPC-backed world state instance');
     }
-    /** Returns the socket path of the underlying wsdb server. */ getSocketPath() {
-        return this.wsdbBackend.getSocketPath();
-    }
     /**
-   * 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);
+   * 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, 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()
             }
-        }
+        });
+        return new IpcWorldState(wsdb, instrumentation, bindings);
+    }
+    getIpcPath() {
+        return this.wsdb.getIpcPath();
     }
     async close() {
         if (!this.open) {
             return;
         }
         this.open = false;
-        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();
+        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),
+                expectedArchiveRoot: new Uint8Array(input.expectedArchiveRoot),
+                expectedPreviousArchiveRoot: new Uint8Array(input.expectedPreviousArchiveRoot),
+                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');
         }
+        return await this.send(operation, request);
     }
-    async _sendMessage(messageType, body) {
+    async send(operation, request) {
         const start = performance.now();
         try {
-            const response = await this.dispatch(messageType, body);
+            const response = await request();
             const durationMs = performance.now() - start;
-            this.log.trace(`Call ${WorldStateMessageType[messageType]} took (ms)`, {
+            this.log.trace(`Call ${operation} took (ms)`, {
                 duration: durationMs
             });
-            this.instrumentation.recordRoundTrip(durationMs * 1000, messageType);
+            this.instrumentation.recordRoundTrip(durationMs * 1000, operation);
             return response;
         } catch (error) {
-            this.log.error(`Call ${WorldStateMessageType[messageType]} failed: ${error}`, error);
+            this.log.error(`Call ${operation} 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 WsdbBackend.
+ * Returns the options needed to construct a wsdb service command line.
  */ export function getWsdbOptions(dataDir, wsTreeMapSizes) {
     return {
         treeHeights: {