@aztec-labs/world-state 6.0.0-nightly.20260829

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +40 -0
  2. package/dest/index.d.ts +6 -0
  3. package/dest/index.d.ts.map +1 -0
  4. package/dest/index.js +5 -0
  5. package/dest/instrumentation/instrumentation.d.ts +25 -0
  6. package/dest/instrumentation/instrumentation.d.ts.map +1 -0
  7. package/dest/instrumentation/instrumentation.js +96 -0
  8. package/dest/native/bench_metrics.d.ts +23 -0
  9. package/dest/native/bench_metrics.d.ts.map +1 -0
  10. package/dest/native/bench_metrics.js +81 -0
  11. package/dest/native/fork_checkpoint.d.ts +16 -0
  12. package/dest/native/fork_checkpoint.d.ts.map +1 -0
  13. package/dest/native/fork_checkpoint.js +38 -0
  14. package/dest/native/index.d.ts +4 -0
  15. package/dest/native/index.d.ts.map +1 -0
  16. package/dest/native/index.js +3 -0
  17. package/dest/native/ipc_world_state_instance.d.ts +91 -0
  18. package/dest/native/ipc_world_state_instance.d.ts.map +1 -0
  19. package/dest/native/ipc_world_state_instance.js +672 -0
  20. package/dest/native/merkle_trees_facade.d.ts +58 -0
  21. package/dest/native/merkle_trees_facade.d.ts.map +1 -0
  22. package/dest/native/merkle_trees_facade.js +250 -0
  23. package/dest/native/message.d.ts +145 -0
  24. package/dest/native/message.d.ts.map +1 -0
  25. package/dest/native/message.js +150 -0
  26. package/dest/native/native_world_state.d.ts +77 -0
  27. package/dest/native/native_world_state.d.ts.map +1 -0
  28. package/dest/native/native_world_state.js +350 -0
  29. package/dest/native/native_world_state_instance.d.ts +63 -0
  30. package/dest/native/native_world_state_instance.d.ts.map +1 -0
  31. package/dest/native/native_world_state_instance.js +1 -0
  32. package/dest/native/world_state_operation.d.ts +7 -0
  33. package/dest/native/world_state_operation.d.ts.map +1 -0
  34. package/dest/native/world_state_operation.js +5 -0
  35. package/dest/synchronizer/config.d.ts +31 -0
  36. package/dest/synchronizer/config.d.ts.map +1 -0
  37. package/dest/synchronizer/config.js +61 -0
  38. package/dest/synchronizer/errors.d.ts +11 -0
  39. package/dest/synchronizer/errors.d.ts.map +1 -0
  40. package/dest/synchronizer/errors.js +12 -0
  41. package/dest/synchronizer/factory.d.ts +20 -0
  42. package/dest/synchronizer/factory.d.ts.map +1 -0
  43. package/dest/synchronizer/factory.js +30 -0
  44. package/dest/synchronizer/index.d.ts +4 -0
  45. package/dest/synchronizer/index.d.ts.map +1 -0
  46. package/dest/synchronizer/index.js +3 -0
  47. package/dest/synchronizer/server_world_state_synchronizer.d.ts +83 -0
  48. package/dest/synchronizer/server_world_state_synchronizer.d.ts.map +1 -0
  49. package/dest/synchronizer/server_world_state_synchronizer.js +434 -0
  50. package/dest/test/index.d.ts +2 -0
  51. package/dest/test/index.d.ts.map +1 -0
  52. package/dest/test/index.js +1 -0
  53. package/dest/test/utils.d.ts +35 -0
  54. package/dest/test/utils.d.ts.map +1 -0
  55. package/dest/test/utils.js +118 -0
  56. package/dest/testing.d.ts +11 -0
  57. package/dest/testing.d.ts.map +1 -0
  58. package/dest/testing.js +48 -0
  59. package/dest/world-state-db/index.d.ts +3 -0
  60. package/dest/world-state-db/index.d.ts.map +1 -0
  61. package/dest/world-state-db/index.js +1 -0
  62. package/dest/world-state-db/merkle_tree_db.d.ts +65 -0
  63. package/dest/world-state-db/merkle_tree_db.d.ts.map +1 -0
  64. package/dest/world-state-db/merkle_tree_db.js +17 -0
  65. package/package.json +98 -0
  66. package/src/index.ts +5 -0
  67. package/src/instrumentation/instrumentation.ts +150 -0
  68. package/src/native/bench_metrics.ts +91 -0
  69. package/src/native/fork_checkpoint.ts +46 -0
  70. package/src/native/index.ts +3 -0
  71. package/src/native/ipc_world_state_instance.ts +849 -0
  72. package/src/native/merkle_trees_facade.ts +375 -0
  73. package/src/native/message.ts +287 -0
  74. package/src/native/native_world_state.ts +435 -0
  75. package/src/native/native_world_state_instance.ts +104 -0
  76. package/src/native/world_state_operation.ts +33 -0
  77. package/src/synchronizer/config.ts +106 -0
  78. package/src/synchronizer/errors.ts +13 -0
  79. package/src/synchronizer/factory.ts +83 -0
  80. package/src/synchronizer/index.ts +3 -0
  81. package/src/synchronizer/server_world_state_synchronizer.ts +525 -0
  82. package/src/test/index.ts +1 -0
  83. package/src/test/utils.ts +184 -0
  84. package/src/testing.ts +65 -0
  85. package/src/world-state-db/index.ts +3 -0
  86. package/src/world-state-db/merkle_tree_db.ts +80 -0
@@ -0,0 +1,435 @@
1
+ import { MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX } from '@aztec-labs/constants';
2
+ import { BlockNumber } from '@aztec-labs/foundation/branded-types';
3
+ import { fromEntries, padArrayEnd } from '@aztec-labs/foundation/collection';
4
+ import { Fr } from '@aztec-labs/foundation/curves/bn254';
5
+ import { EthAddress } from '@aztec-labs/foundation/eth-address';
6
+ import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
7
+ import type { L2Block } from '@aztec-labs/stdlib/block';
8
+ import { DatabaseVersionManager } from '@aztec-labs/stdlib/database-version/manager';
9
+ import type {
10
+ IndexedTreeId,
11
+ MerkleTreeReadOperations,
12
+ MerkleTreeWriteOperations,
13
+ } from '@aztec-labs/stdlib/interfaces/server';
14
+ import type { SnapshotDataKeys } from '@aztec-labs/stdlib/snapshots';
15
+ import { MerkleTreeId, NullifierLeaf, type NullifierLeafPreimage, PublicDataTreeLeaf } from '@aztec-labs/stdlib/trees';
16
+ import { BlockHeader, GlobalVariables, PartialStateReference, StateReference } from '@aztec-labs/stdlib/tx';
17
+ import { EMPTY_GENESIS_DATA, type GenesisData, WorldStateRevision } from '@aztec-labs/stdlib/world-state';
18
+ import { getTelemetryClient } from '@aztec-labs/telemetry-client';
19
+ import assert from 'assert/strict';
20
+ import { mkdir, mkdtemp, rm } from 'fs/promises';
21
+ import { tmpdir } from 'os';
22
+ import { join } from 'path';
23
+
24
+ import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
25
+ import type { WorldStateTreeMapSizes } from '../synchronizer/factory.js';
26
+ import type { MerkleTreeAdminDatabase as MerkleTreeDatabase } from '../world-state-db/merkle_tree_db.js';
27
+ import { IpcWorldState } from './ipc_world_state_instance.js';
28
+ import { MerkleTreesFacade, MerkleTreesForkFacade, serializeLeaf } from './merkle_trees_facade.js';
29
+ import {
30
+ type WorldStateStatusFull,
31
+ type WorldStateStatusSummary,
32
+ blockStateReference,
33
+ sanitizeFullStatus,
34
+ sanitizeSummary,
35
+ treeStateReferenceToSnapshot,
36
+ } from './message.js';
37
+ import type { NativeWorldStateInstance } from './native_world_state_instance.js';
38
+
39
+ // The current version of the world state database schema
40
+ // Increment this when making incompatible changes to the database schema
41
+ export const WORLD_STATE_DB_VERSION = 2; // The initial version
42
+
43
+ export const WORLD_STATE_DIR = 'world_state';
44
+
45
+ export class NativeWorldStateService implements MerkleTreeDatabase {
46
+ protected initialHeader: BlockHeader | undefined;
47
+ // This is read heavily and only changes when data is persisted, so we cache it
48
+ private cachedStatusSummary: WorldStateStatusSummary | undefined;
49
+
50
+ protected constructor(
51
+ protected instance: NativeWorldStateInstance,
52
+ protected readonly worldStateInstrumentation: WorldStateInstrumentation,
53
+ protected readonly log: Logger,
54
+ private readonly genesis: GenesisData = EMPTY_GENESIS_DATA,
55
+ private readonly cleanup = () => Promise.resolve(),
56
+ /** Factory to recreate a fresh IpcWorldState after clear(). */
57
+ private readonly recreateInstance?: () => Promise<NativeWorldStateInstance>,
58
+ ) {}
59
+
60
+ static async new(
61
+ rollupAddress: EthAddress,
62
+ dataDir: string,
63
+ wsTreeMapSizes: WorldStateTreeMapSizes,
64
+ genesis: GenesisData = EMPTY_GENESIS_DATA,
65
+ instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
66
+ bindings?: LoggerBindings,
67
+ cleanup = () => Promise.resolve(),
68
+ ): Promise<NativeWorldStateService> {
69
+ for (const [key, value] of Object.entries(wsTreeMapSizes)) {
70
+ if (value <= 0) {
71
+ throw new Error(`Map size must be a positive number, got ${value} for ${key}`);
72
+ }
73
+ }
74
+
75
+ const log = createLogger('world-state:database', bindings);
76
+ const worldStateDirectory = join(dataDir, WORLD_STATE_DIR);
77
+
78
+ const versionManager = new DatabaseVersionManager({
79
+ schemaVersion: WORLD_STATE_DB_VERSION,
80
+ rollupAddress,
81
+ dataDirectory: worldStateDirectory,
82
+ onOpen: dir => IpcWorldState.spawn(dir, wsTreeMapSizes, genesis, instrumentation, bindings),
83
+ });
84
+
85
+ const [instance] = await versionManager.open();
86
+
87
+ const recreateInstance = async () => {
88
+ await rm(worldStateDirectory, { recursive: true, force: true, maxRetries: 3 });
89
+ await mkdir(worldStateDirectory, { recursive: true });
90
+ return IpcWorldState.spawn(worldStateDirectory, wsTreeMapSizes, genesis, instrumentation, bindings);
91
+ };
92
+
93
+ const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
94
+ try {
95
+ await worldState.init();
96
+ } catch (e) {
97
+ log.error(`Error initializing world state: ${e}`);
98
+ throw e;
99
+ }
100
+
101
+ return worldState;
102
+ }
103
+
104
+ static async tmp(
105
+ cleanupTmpDir = true,
106
+ genesis: GenesisData = EMPTY_GENESIS_DATA,
107
+ instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
108
+ bindings?: LoggerBindings,
109
+ threads?: number,
110
+ ): Promise<NativeWorldStateService> {
111
+ const log = createLogger('world-state:database', bindings);
112
+ const dataDir = await mkdtemp(join(tmpdir(), 'aztec-world-state-'));
113
+ // Temporary (test/dev) world states are small and short-lived. Keep the LMDB
114
+ // map sizes in the MB range: with the IPC backend each tmp() spawns a separate
115
+ // aztec-wsdb that maps these per tree, and oversized maps add real cold-start
116
+ // I/O under parallel CI load. 256 MB/tree is ample for tests.
117
+ const dbMapSizeKb = 256 * 1024;
118
+ const worldStateTreeMapSizes: WorldStateTreeMapSizes = {
119
+ archiveTreeMapSizeKb: dbMapSizeKb,
120
+ nullifierTreeMapSizeKb: dbMapSizeKb,
121
+ noteHashTreeMapSizeKb: dbMapSizeKb,
122
+ messageTreeMapSizeKb: dbMapSizeKb,
123
+ publicDataTreeMapSizeKb: dbMapSizeKb,
124
+ };
125
+ log.debug(`Created temporary world state database at: ${dataDir} with tree map size: ${dbMapSizeKb}`);
126
+
127
+ const instance = await IpcWorldState.spawn(
128
+ dataDir,
129
+ worldStateTreeMapSizes,
130
+ genesis,
131
+ instrumentation,
132
+ bindings,
133
+ threads,
134
+ );
135
+
136
+ const cleanup = async () => {
137
+ if (cleanupTmpDir) {
138
+ await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
139
+ log.debug(`Deleted temporary world state database: ${dataDir}`);
140
+ } else {
141
+ log.debug(`Leaving temporary world state database: ${dataDir}`);
142
+ }
143
+ };
144
+
145
+ const recreateInstance = async () => {
146
+ await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
147
+ await mkdir(dataDir, { recursive: true });
148
+ return IpcWorldState.spawn(dataDir, worldStateTreeMapSizes, genesis, instrumentation, bindings, threads);
149
+ };
150
+
151
+ const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
152
+ try {
153
+ await worldState.init();
154
+ } catch (e) {
155
+ log.error(`Error initializing tmp world state: ${e}`);
156
+ throw e;
157
+ }
158
+ return worldState;
159
+ }
160
+
161
+ static ephemeral(
162
+ genesis: GenesisData = EMPTY_GENESIS_DATA,
163
+ instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
164
+ bindings?: LoggerBindings,
165
+ ): Promise<NativeWorldStateService> {
166
+ // The TXE spins up one tiny, short-lived world state per test, many concurrently. Cap the wsdb thread
167
+ // usage to the minimum: a single tree-op thread instead of one per core (the C++ IPC dispatcher pool
168
+ // still floors at 2). This avoids ~32 threads per wsdb multiplied across dozens of concurrent test
169
+ // world states — the trees are cache-sized (see tmp's map-size note), so extra threads buy nothing.
170
+ return this.tmp(/*cleanupTmpDir=*/ true, genesis, instrumentation, bindings, /*threads=*/ 1);
171
+ }
172
+
173
+ static async fromIpc(
174
+ wsdbBackend: ConstructorParameters<typeof IpcWorldState>[0],
175
+ instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
176
+ bindings?: LoggerBindings,
177
+ genesis: GenesisData = EMPTY_GENESIS_DATA,
178
+ cleanup = () => Promise.resolve(),
179
+ recreateInstance?: () => Promise<NativeWorldStateInstance>,
180
+ ): Promise<NativeWorldStateService> {
181
+ const log = createLogger('world-state:database', bindings);
182
+ const instance = new IpcWorldState(wsdbBackend, instrumentation, bindings);
183
+ const worldState = new this(instance, instrumentation, log, genesis, cleanup, recreateInstance);
184
+ await worldState.init();
185
+ return worldState;
186
+ }
187
+
188
+ protected async init() {
189
+ const status = await this.getStatusSummary();
190
+ if (!status.treesAreSynched) {
191
+ throw new Error('World state trees are out of sync, please delete your data directory and re-sync');
192
+ }
193
+ this.initialHeader = await this.buildInitialHeader();
194
+ const committed = this.getCommitted();
195
+
196
+ // validate the initial state
197
+ const archive = await committed.getTreeInfo(MerkleTreeId.ARCHIVE);
198
+ if (archive.size === 0n) {
199
+ throw new Error("Archive tree can't be empty");
200
+ }
201
+
202
+ // the initial header _must_ be the first element in the archive tree
203
+ // if this assertion fails, check that the hashing done in Header in yarn-project matches the initial header hash done in world_state.cpp
204
+ const indices = await committed.findLeafIndices(MerkleTreeId.ARCHIVE, [await this.initialHeader.hash()]);
205
+ const initialHeaderIndex = indices[0];
206
+ assert.strictEqual(initialHeaderIndex, 0n, 'Invalid initial archive state');
207
+ }
208
+
209
+ public async clear(): Promise<void> {
210
+ if (!this.recreateInstance) {
211
+ throw new Error('clear() is not available for externally-managed IPC backends');
212
+ }
213
+ this.log.warn('Clearing world state: shutting down WSDB, deleting data, and recreating');
214
+ await this.instance.close();
215
+ this.cachedStatusSummary = undefined;
216
+ this.instance = await this.recreateInstance();
217
+ await this.init();
218
+ this.log.info('World state cleared and reinitialized from genesis');
219
+ }
220
+
221
+ /** Returns the IPC path of the underlying IPC backend, if available. */
222
+ public getIpcPath(): string {
223
+ if (this.instance instanceof IpcWorldState) {
224
+ return this.instance.getIpcPath();
225
+ }
226
+ throw new Error('getIpcPath() is only available with IPC world state');
227
+ }
228
+
229
+ public getCommitted(): MerkleTreeReadOperations {
230
+ return new MerkleTreesFacade(this.instance, this.initialHeader!, WorldStateRevision.empty());
231
+ }
232
+
233
+ public getSnapshot(blockNumber: BlockNumber): MerkleTreeReadOperations {
234
+ return new MerkleTreesFacade(
235
+ this.instance,
236
+ this.initialHeader!,
237
+ new WorldStateRevision(/*forkId=*/ 0, /* blockNumber=*/ blockNumber, /* includeUncommitted=*/ false),
238
+ );
239
+ }
240
+
241
+ public async fork(
242
+ blockNumber?: BlockNumber,
243
+ opts: { closeDelayMs?: number } = {},
244
+ ): Promise<MerkleTreeWriteOperations> {
245
+ const forkId = await this.instance.createFork({
246
+ latest: blockNumber === undefined,
247
+ blockNumber: blockNumber ?? BlockNumber.ZERO,
248
+ });
249
+ return new MerkleTreesForkFacade(
250
+ this.instance,
251
+ this.initialHeader!,
252
+ new WorldStateRevision(
253
+ /*forkId=*/ forkId,
254
+ /* blockNumber=*/ WorldStateRevision.LATEST,
255
+ /* includeUncommitted=*/ true,
256
+ ),
257
+ opts,
258
+ );
259
+ }
260
+
261
+ public getInitialHeader(): BlockHeader {
262
+ return this.initialHeader!;
263
+ }
264
+
265
+ public async handleL2BlockAndMessages(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull> {
266
+ // Any block may carry an L1-to-L2 message bundle and transition the L1-to-L2 message tree by its real (unpadded,
267
+ // compact) leaves, matching how the circuits build the tree.
268
+
269
+ // We have to pad the note hashes and nullifiers within tx effects because that's how the trees are built by
270
+ // circuits.
271
+ const paddedNoteHashes = l2Block.body.txEffects.flatMap(txEffect =>
272
+ padArrayEnd(txEffect.noteHashes, Fr.ZERO, MAX_NOTE_HASHES_PER_TX),
273
+ );
274
+
275
+ const paddedNullifiers = l2Block.body.txEffects
276
+ .flatMap(txEffect => padArrayEnd(txEffect.nullifiers, Fr.ZERO, MAX_NULLIFIERS_PER_TX))
277
+ .map(nullifier => new NullifierLeaf(nullifier));
278
+
279
+ const publicDataWrites: PublicDataTreeLeaf[] = l2Block.body.txEffects.flatMap(txEffect => {
280
+ return txEffect.publicDataWrites.map(write => {
281
+ if (write.isEmpty()) {
282
+ throw new Error('Public data write must not be empty when syncing');
283
+ }
284
+ return new PublicDataTreeLeaf(write.leafSlot, write.value);
285
+ });
286
+ });
287
+
288
+ try {
289
+ const status = await this.instance.syncBlock({
290
+ blockNumber: l2Block.number,
291
+ blockHeaderHash: (await l2Block.hash()).toBuffer(),
292
+ // Forwarded so the native sync verifies the archive root against canonical and rejects a divergent tree.
293
+ expectedArchiveRoot: l2Block.archive.root.toBuffer(),
294
+ expectedPreviousArchiveRoot: l2Block.header.lastArchive.root.toBuffer(),
295
+ paddedL1ToL2Messages: l1ToL2Messages.map(serializeLeaf),
296
+ paddedNoteHashes: paddedNoteHashes.map(serializeLeaf),
297
+ paddedNullifiers: paddedNullifiers.map(serializeLeaf),
298
+ publicDataWrites: publicDataWrites.map(serializeLeaf),
299
+ blockStateRef: blockStateReference(l2Block.header.state),
300
+ });
301
+ return this.sanitizeAndCacheSummaryFromFull(status);
302
+ } catch (err) {
303
+ this.deleteCachedSummary();
304
+ this.worldStateInstrumentation.incCriticalErrors('synch_pending_block');
305
+ throw err;
306
+ }
307
+ }
308
+
309
+ public async close(): Promise<void> {
310
+ try {
311
+ await this.instance.close();
312
+ } finally {
313
+ await this.cleanup();
314
+ }
315
+ }
316
+
317
+ async [Symbol.asyncDispose](): Promise<void> {
318
+ await this.close();
319
+ }
320
+
321
+ private async buildInitialHeader(): Promise<BlockHeader> {
322
+ const state = await this.getInitialStateReference();
323
+ return BlockHeader.empty({
324
+ state,
325
+ globalVariables: GlobalVariables.empty({ timestamp: this.genesis.genesisTimestamp }),
326
+ });
327
+ }
328
+
329
+ private sanitizeAndCacheSummaryFromFull(response: WorldStateStatusFull) {
330
+ const sanitized = sanitizeFullStatus(response);
331
+ this.cachedStatusSummary = { ...sanitized.summary };
332
+ return sanitized;
333
+ }
334
+
335
+ private sanitizeAndCacheSummary(response: WorldStateStatusSummary) {
336
+ const sanitized = sanitizeSummary(response);
337
+ this.cachedStatusSummary = { ...sanitized };
338
+ return sanitized;
339
+ }
340
+
341
+ private deleteCachedSummary() {
342
+ this.cachedStatusSummary = undefined;
343
+ }
344
+
345
+ /**
346
+ * Advances the finalized block number to be the number provided
347
+ * @param toBlockNumber The block number that is now the tip of the finalized chain
348
+ * @returns The new WorldStateStatus
349
+ */
350
+ public async setFinalized(toBlockNumber: BlockNumber) {
351
+ try {
352
+ this.sanitizeAndCacheSummary(await this.instance.finalizeBlocks(toBlockNumber));
353
+ } catch (err) {
354
+ this.deleteCachedSummary();
355
+ this.worldStateInstrumentation.incCriticalErrors('finalize_block');
356
+ throw err;
357
+ }
358
+ return this.getStatusSummary();
359
+ }
360
+
361
+ /**
362
+ * Removes all historical snapshots up to but not including the given block number
363
+ * @param toBlockNumber The block number of the new oldest historical block
364
+ * @returns The new WorldStateStatus
365
+ */
366
+ public async removeHistoricalBlocks(toBlockNumber: BlockNumber) {
367
+ try {
368
+ return this.sanitizeAndCacheSummaryFromFull(await this.instance.removeHistoricalBlocks(toBlockNumber));
369
+ } catch (err) {
370
+ this.deleteCachedSummary();
371
+ this.worldStateInstrumentation.incCriticalErrors('prune_historical_block');
372
+ throw err;
373
+ }
374
+ }
375
+
376
+ /**
377
+ * Removes all pending blocks down to but not including the given block number
378
+ * @param toBlockNumber The block number of the new tip of the pending chain,
379
+ * @returns The new WorldStateStatus
380
+ */
381
+ public async unwindBlocks(toBlockNumber: BlockNumber) {
382
+ try {
383
+ return this.sanitizeAndCacheSummaryFromFull(await this.instance.unwindBlocks(toBlockNumber));
384
+ } catch (err) {
385
+ this.deleteCachedSummary();
386
+ this.worldStateInstrumentation.incCriticalErrors('prune_pending_block');
387
+ throw err;
388
+ }
389
+ }
390
+
391
+ public async getStatusSummary() {
392
+ if (this.cachedStatusSummary !== undefined) {
393
+ return { ...this.cachedStatusSummary };
394
+ }
395
+ return this.sanitizeAndCacheSummary(await this.instance.getStatus());
396
+ }
397
+
398
+ updateLeaf<ID extends IndexedTreeId>(
399
+ _treeId: ID,
400
+ _leaf: NullifierLeafPreimage | Buffer,
401
+ _index: bigint,
402
+ ): Promise<void> {
403
+ return Promise.reject(new Error('Method not implemented'));
404
+ }
405
+
406
+ private async getInitialStateReference(): Promise<StateReference> {
407
+ const state = await this.instance.getInitialStateReference();
408
+
409
+ return new StateReference(
410
+ treeStateReferenceToSnapshot(state[MerkleTreeId.L1_TO_L2_MESSAGE_TREE]),
411
+ new PartialStateReference(
412
+ treeStateReferenceToSnapshot(state[MerkleTreeId.NOTE_HASH_TREE]),
413
+ treeStateReferenceToSnapshot(state[MerkleTreeId.NULLIFIER_TREE]),
414
+ treeStateReferenceToSnapshot(state[MerkleTreeId.PUBLIC_DATA_TREE]),
415
+ ),
416
+ );
417
+ }
418
+
419
+ public async backupTo(
420
+ dstPath: string,
421
+ compact: boolean = true,
422
+ ): Promise<Record<Exclude<SnapshotDataKeys, 'archiver'>, string>> {
423
+ await this.instance.copyStores(dstPath, compact);
424
+ return fromEntries(NATIVE_WORLD_STATE_DBS.map(([name, dir]) => [name, join(dstPath, dir, 'data.mdb')] as const));
425
+ }
426
+ }
427
+
428
+ // The following paths are defined in cpp-land
429
+ export const NATIVE_WORLD_STATE_DBS = [
430
+ ['l1-to-l2-message-tree', 'L1ToL2MessageTree'],
431
+ ['archive-tree', 'ArchiveTree'],
432
+ ['public-data-tree', 'PublicDataTree'],
433
+ ['note-hash-tree', 'NoteHashTree'],
434
+ ['nullifier-tree', 'NullifierTree'],
435
+ ] as const;
@@ -0,0 +1,104 @@
1
+ import type { BlockNumber } from '@aztec-labs/foundation/branded-types';
2
+ import type { Fr } from '@aztec-labs/foundation/curves/bn254';
3
+ import type { IndexedTreeId, TreeInfo } from '@aztec-labs/stdlib/interfaces/server';
4
+ import type { MerkleTreeId } from '@aztec-labs/stdlib/trees';
5
+ import type { WorldStateRevision } from '@aztec-labs/stdlib/world-state';
6
+
7
+ import type {
8
+ BlockStateReference,
9
+ SerializedBatchInsertionResult,
10
+ SerializedIndexedLeaf,
11
+ SerializedLeafValue,
12
+ SerializedSequentialInsertionResult,
13
+ SerializedSiblingPathAndIndex,
14
+ TreeStateReference,
15
+ WorldStateStatusFull,
16
+ WorldStateStatusSummary,
17
+ } from './message.js';
18
+
19
+ /** Backend-agnostic handle to a running aztec-wsdb world state, accessed by the TS layer. */
20
+ export interface NativeWorldStateInstance {
21
+ getTreeInfo(treeId: MerkleTreeId, revision: WorldStateRevision): Promise<TreeInfo>;
22
+ getStateReference(revision: WorldStateRevision): Promise<Record<number, TreeStateReference>>;
23
+ getInitialStateReference(): Promise<Record<number, TreeStateReference>>;
24
+ getLeafValue(
25
+ treeId: MerkleTreeId,
26
+ revision: WorldStateRevision,
27
+ leafIndex: bigint,
28
+ ): Promise<SerializedLeafValue | undefined>;
29
+ getLeafPreimage(
30
+ treeId: IndexedTreeId,
31
+ revision: WorldStateRevision,
32
+ leafIndex: bigint,
33
+ ): Promise<SerializedIndexedLeaf | undefined>;
34
+ getSiblingPath(treeId: MerkleTreeId, revision: WorldStateRevision, leafIndex: bigint): Promise<Buffer[]>;
35
+ getBlockNumbersForLeafIndices(
36
+ treeId: MerkleTreeId,
37
+ revision: WorldStateRevision,
38
+ leafIndices: bigint[],
39
+ ): Promise<(bigint | undefined)[]>;
40
+ findLeafIndices(
41
+ treeId: MerkleTreeId,
42
+ revision: WorldStateRevision,
43
+ leaves: SerializedLeafValue[],
44
+ startIndex: bigint,
45
+ ): Promise<(bigint | undefined)[]>;
46
+ findLowLeaf(
47
+ treeId: IndexedTreeId,
48
+ revision: WorldStateRevision,
49
+ key: Fr,
50
+ ): Promise<{ index: bigint; alreadyPresent: boolean }>;
51
+ findSiblingPaths(
52
+ treeId: MerkleTreeId,
53
+ revision: WorldStateRevision,
54
+ leaves: SerializedLeafValue[],
55
+ ): Promise<(SerializedSiblingPathAndIndex | undefined)[]>;
56
+ updateArchive(forkId: number, blockStateRef: BlockStateReference, blockHeaderHash: Buffer): Promise<void>;
57
+ appendLeaves(treeId: MerkleTreeId, forkId: number, leaves: SerializedLeafValue[]): Promise<void>;
58
+ batchInsert(
59
+ treeId: IndexedTreeId,
60
+ forkId: number,
61
+ leaves: SerializedLeafValue[],
62
+ subtreeDepth: number,
63
+ ): Promise<SerializedBatchInsertionResult>;
64
+ sequentialInsert(
65
+ treeId: IndexedTreeId,
66
+ forkId: number,
67
+ leaves: SerializedLeafValue[],
68
+ ): Promise<SerializedSequentialInsertionResult>;
69
+ syncBlock(input: {
70
+ blockNumber: BlockNumber;
71
+ blockStateRef: BlockStateReference;
72
+ blockHeaderHash: Buffer;
73
+ expectedArchiveRoot: Buffer;
74
+ expectedPreviousArchiveRoot: Buffer;
75
+ paddedNoteHashes: readonly SerializedLeafValue[];
76
+ paddedL1ToL2Messages: readonly SerializedLeafValue[];
77
+ paddedNullifiers: readonly SerializedLeafValue[];
78
+ publicDataWrites: readonly SerializedLeafValue[];
79
+ }): Promise<WorldStateStatusFull>;
80
+ createFork(input: { latest: boolean; blockNumber: BlockNumber }): Promise<number>;
81
+ deleteFork(forkId: number): Promise<void>;
82
+ finalizeBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusSummary>;
83
+ unwindBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
84
+ removeHistoricalBlocks(toBlockNumber: BlockNumber): Promise<WorldStateStatusFull>;
85
+ getStatus(): Promise<WorldStateStatusSummary>;
86
+ createCheckpoint(forkId: number): Promise<number>;
87
+ commitCheckpoint(forkId: number): Promise<void>;
88
+ revertCheckpoint(forkId: number): Promise<void>;
89
+ commitAllCheckpoints(forkId: number, depth: number): Promise<void>;
90
+ revertAllCheckpoints(forkId: number, depth: number): Promise<void>;
91
+ copyStores(dstPath: string, compact: boolean): Promise<void>;
92
+
93
+ /**
94
+ * IPC path the underlying aztec-wsdb process listens on. The C++ AVM uses this to attach to the
95
+ * same world state instance the TS layer is using.
96
+ */
97
+ getIpcPath(): string;
98
+
99
+ /**
100
+ * Shut down the world state instance. Cancels any in-flight queues, closes the IPC channel, and
101
+ * terminates the underlying aztec-wsdb process. Idempotent.
102
+ */
103
+ close(): Promise<void>;
104
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Names of the world-state operations, used as labels for instrumentation and
3
+ * logging. (Read/write ordering is enforced server-side by the wsdb scheduler,
4
+ * so there is no longer a client-side operation queue.)
5
+ */
6
+ export type WorldStateOperationName =
7
+ | 'getTreeInfo'
8
+ | 'getStateReference'
9
+ | 'getInitialStateReference'
10
+ | 'getLeafValue'
11
+ | 'getLeafPreimage'
12
+ | 'getSiblingPath'
13
+ | 'getBlockNumbersForLeafIndices'
14
+ | 'findLeafIndices'
15
+ | 'findLowLeaf'
16
+ | 'findSiblingPaths'
17
+ | 'appendLeaves'
18
+ | 'batchInsert'
19
+ | 'sequentialInsert'
20
+ | 'updateArchive'
21
+ | 'syncBlock'
22
+ | 'createFork'
23
+ | 'deleteFork'
24
+ | 'finalizeBlocks'
25
+ | 'unwindBlocks'
26
+ | 'removeHistoricalBlocks'
27
+ | 'getStatus'
28
+ | 'createCheckpoint'
29
+ | 'commitCheckpoint'
30
+ | 'revertCheckpoint'
31
+ | 'commitAllCheckpoints'
32
+ | 'revertAllCheckpoints'
33
+ | 'copyStores';
@@ -0,0 +1,106 @@
1
+ import {
2
+ type ConfigMappingsType,
3
+ getConfigFromMappings,
4
+ numberConfigHelper,
5
+ optionalNumberConfigHelper,
6
+ } from '@aztec-labs/foundation/config';
7
+
8
+ /** World State synchronizer configuration values. */
9
+ export interface WorldStateConfig {
10
+ /** The frequency in which to check. */
11
+ worldStateBlockCheckIntervalMS: number;
12
+
13
+ /** Size of the batch for each get-blocks request from the synchronizer to the archiver. */
14
+ worldStateBlockRequestBatchSize?: number;
15
+
16
+ /** The map size to be provided to LMDB for each world state tree DB, optional, will inherit from the general dataStoreMapSizeKb if not specified*/
17
+ worldStateDbMapSizeKb?: number;
18
+
19
+ /** The map size to be provided to LMDB for each world state archive tree, optional, will inherit from the general worldStateDbMapSizeKb if not specified*/
20
+ archiveTreeMapSizeKb?: number;
21
+
22
+ /** The map size to be provided to LMDB for each world state nullifier tree, optional, will inherit from the general worldStateDbMapSizeKb if not specified*/
23
+ nullifierTreeMapSizeKb?: number;
24
+
25
+ /** The map size to be provided to LMDB for each world state note hash tree, optional, will inherit from the general worldStateDbMapSizeKb if not specified*/
26
+ noteHashTreeMapSizeKb?: number;
27
+
28
+ /** The map size to be provided to LMDB for each world state message tree, optional, will inherit from the general worldStateDbMapSizeKb if not specified*/
29
+ messageTreeMapSizeKb?: number;
30
+
31
+ /** The map size to be provided to LMDB for each world state public data tree, optional, will inherit from the general worldStateDbMapSizeKb if not specified*/
32
+ publicDataTreeMapSizeKb?: number;
33
+
34
+ /** Optional directory for the world state DB, if unspecified will default to the general data directory */
35
+ worldStateDataDirectory?: string;
36
+
37
+ /** The number of historic checkpoints worth of blocks to maintain */
38
+ worldStateCheckpointHistory: number;
39
+ }
40
+
41
+ export const worldStateConfigMappings: ConfigMappingsType<WorldStateConfig> = {
42
+ worldStateBlockCheckIntervalMS: {
43
+ env: 'WS_BLOCK_CHECK_INTERVAL_MS',
44
+ ...numberConfigHelper(100),
45
+ description: 'The frequency in which to check.',
46
+ },
47
+ worldStateBlockRequestBatchSize: {
48
+ env: 'WS_BLOCK_REQUEST_BATCH_SIZE',
49
+ ...optionalNumberConfigHelper(),
50
+ description: 'Size of the batch for each get-blocks request from the synchronizer to the archiver.',
51
+ },
52
+ worldStateDbMapSizeKb: {
53
+ env: 'WS_DB_MAP_SIZE_KB',
54
+ ...optionalNumberConfigHelper(),
55
+ description: 'The maximum possible size of the world state DB in KB. Overwrites the general dataStoreMapSizeKb.',
56
+ },
57
+ archiveTreeMapSizeKb: {
58
+ env: 'ARCHIVE_TREE_MAP_SIZE_KB',
59
+ ...optionalNumberConfigHelper(),
60
+ description:
61
+ 'The maximum possible size of the world state archive tree in KB. Overwrites the general worldStateDbMapSizeKb.',
62
+ },
63
+ nullifierTreeMapSizeKb: {
64
+ env: 'NULLIFIER_TREE_MAP_SIZE_KB',
65
+ ...optionalNumberConfigHelper(),
66
+ description:
67
+ 'The maximum possible size of the world state nullifier tree in KB. Overwrites the general worldStateDbMapSizeKb.',
68
+ },
69
+ noteHashTreeMapSizeKb: {
70
+ env: 'NOTE_HASH_TREE_MAP_SIZE_KB',
71
+ ...optionalNumberConfigHelper(),
72
+ description:
73
+ 'The maximum possible size of the world state note hash tree in KB. Overwrites the general worldStateDbMapSizeKb.',
74
+ },
75
+ messageTreeMapSizeKb: {
76
+ env: 'MESSAGE_TREE_MAP_SIZE_KB',
77
+ ...optionalNumberConfigHelper(),
78
+ description:
79
+ 'The maximum possible size of the world state message tree in KB. Overwrites the general worldStateDbMapSizeKb.',
80
+ },
81
+ publicDataTreeMapSizeKb: {
82
+ env: 'PUBLIC_DATA_TREE_MAP_SIZE_KB',
83
+ ...optionalNumberConfigHelper(),
84
+ description:
85
+ 'The maximum possible size of the world state public data tree in KB. Overwrites the general worldStateDbMapSizeKb.',
86
+ },
87
+ worldStateDataDirectory: {
88
+ env: 'WS_DATA_DIRECTORY',
89
+ description: 'Optional directory for the world state database',
90
+ },
91
+ worldStateCheckpointHistory: {
92
+ env: 'WS_NUM_HISTORIC_CHECKPOINTS',
93
+ description:
94
+ 'The number of historic checkpoints worth of blocks to maintain. Values less than 1 mean all history is maintained',
95
+ fallback: ['WS_NUM_HISTORIC_BLOCKS'],
96
+ ...numberConfigHelper(64),
97
+ },
98
+ };
99
+
100
+ /**
101
+ * Returns the configuration values for the world state synchronizer.
102
+ * @returns The configuration values for the world state synchronizer.
103
+ */
104
+ export function getWorldStateConfigFromEnv(): WorldStateConfig {
105
+ return getConfigFromMappings<WorldStateConfig>(worldStateConfigMappings);
106
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Thrown by {@link ServerWorldStateSynchronizer.syncImmediate} when world state cannot be synced to the requested
3
+ * target: either the block is not available from the block source (`block_not_available`, e.g. it was pruned away)
4
+ * or the synced block does not match the requested hash (`block_hash_mismatch`, i.e. a reorg). Both causes are
5
+ * transient from the caller's perspective: re-resolving the query against the current chain and retrying may succeed
6
+ * or produce a more precise error.
7
+ */
8
+ export class WorldStateSynchronizerError extends Error {
9
+ constructor(message: string, options?: ErrorOptions) {
10
+ super(message, options);
11
+ this.name = 'WorldStateSynchronizerError';
12
+ }
13
+ }