@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,83 @@
1
+ import type { LoggerBindings } from '@aztec-labs/foundation/log';
2
+ import type { L2BlockSource } from '@aztec-labs/stdlib/block';
3
+ import type { DataStoreConfig } from '@aztec-labs/stdlib/kv-store';
4
+ import type { L1ToL2MessageSource } from '@aztec-labs/stdlib/messaging';
5
+ import { EMPTY_GENESIS_DATA, type GenesisData, isGenesisData } from '@aztec-labs/stdlib/world-state';
6
+ import { type TelemetryClient, getTelemetryClient } from '@aztec-labs/telemetry-client';
7
+
8
+ import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
9
+ import { NativeWorldStateService } from '../native/native_world_state.js';
10
+ import type { WorldStateConfig } from './config.js';
11
+ import { ServerWorldStateSynchronizer } from './server_world_state_synchronizer.js';
12
+
13
+ export interface WorldStateTreeMapSizes {
14
+ archiveTreeMapSizeKb: number;
15
+ nullifierTreeMapSizeKb: number;
16
+ noteHashTreeMapSizeKb: number;
17
+ messageTreeMapSizeKb: number;
18
+ publicDataTreeMapSizeKb: number;
19
+ }
20
+
21
+ export async function createWorldStateSynchronizer(
22
+ config: WorldStateConfig & DataStoreConfig,
23
+ l2BlockSource: L2BlockSource & L1ToL2MessageSource,
24
+ genesisOrNativeWorldState: GenesisData | NativeWorldStateService,
25
+ client: TelemetryClient = getTelemetryClient(),
26
+ bindings?: LoggerBindings,
27
+ ) {
28
+ const instrumentation = new WorldStateInstrumentation(client);
29
+ const merkleTrees = isGenesisData(genesisOrNativeWorldState)
30
+ ? await createWorldState(config, genesisOrNativeWorldState, instrumentation, bindings)
31
+ : genesisOrNativeWorldState;
32
+ return new ServerWorldStateSynchronizer(merkleTrees, l2BlockSource, config, instrumentation);
33
+ }
34
+
35
+ export async function createWorldState(
36
+ config: Pick<
37
+ WorldStateConfig,
38
+ | 'worldStateDataDirectory'
39
+ | 'worldStateDbMapSizeKb'
40
+ | 'archiveTreeMapSizeKb'
41
+ | 'nullifierTreeMapSizeKb'
42
+ | 'noteHashTreeMapSizeKb'
43
+ | 'messageTreeMapSizeKb'
44
+ | 'publicDataTreeMapSizeKb'
45
+ > &
46
+ Pick<DataStoreConfig, 'dataDirectory' | 'dataStoreMapSizeKb' | 'rollupAddress'>,
47
+ genesis: GenesisData = EMPTY_GENESIS_DATA,
48
+ instrumentation: WorldStateInstrumentation = new WorldStateInstrumentation(getTelemetryClient()),
49
+ bindings?: LoggerBindings,
50
+ ) {
51
+ const dataDirectory = config.worldStateDataDirectory ?? config.dataDirectory;
52
+ const dataStoreMapSizeKb = config.worldStateDbMapSizeKb ?? config.dataStoreMapSizeKb;
53
+ const wsTreeMapSizes: WorldStateTreeMapSizes = {
54
+ archiveTreeMapSizeKb: config.archiveTreeMapSizeKb ?? dataStoreMapSizeKb,
55
+ nullifierTreeMapSizeKb: config.nullifierTreeMapSizeKb ?? dataStoreMapSizeKb,
56
+ noteHashTreeMapSizeKb: config.noteHashTreeMapSizeKb ?? dataStoreMapSizeKb,
57
+ messageTreeMapSizeKb: config.messageTreeMapSizeKb ?? dataStoreMapSizeKb,
58
+ publicDataTreeMapSizeKb: config.publicDataTreeMapSizeKb ?? dataStoreMapSizeKb,
59
+ };
60
+
61
+ if (!config.rollupAddress) {
62
+ throw new Error('Rollup address is required to create a world state synchronizer.');
63
+ }
64
+
65
+ // If a data directory is provided in config, then create a persistent store.
66
+ const merkleTrees = dataDirectory
67
+ ? await NativeWorldStateService.new(
68
+ config.rollupAddress,
69
+ dataDirectory,
70
+ wsTreeMapSizes,
71
+ genesis,
72
+ instrumentation,
73
+ bindings,
74
+ )
75
+ : await NativeWorldStateService.tmp(
76
+ !['true', '1'].includes(process.env.DEBUG_WORLD_STATE!),
77
+ genesis,
78
+ instrumentation,
79
+ bindings,
80
+ );
81
+
82
+ return merkleTrees;
83
+ }
@@ -0,0 +1,3 @@
1
+ export * from './server_world_state_synchronizer.js';
2
+ export * from './factory.js';
3
+ export * from './errors.js';
@@ -0,0 +1,525 @@
1
+ import { INITIAL_L2_BLOCK_NUM } from '@aztec-labs/constants';
2
+ import { BlockNumber, CheckpointNumber } from '@aztec-labs/foundation/branded-types';
3
+ import type { Fr } from '@aztec-labs/foundation/curves/bn254';
4
+ import { type Logger, createLogger } from '@aztec-labs/foundation/log';
5
+ import { promiseWithResolvers } from '@aztec-labs/foundation/promise';
6
+ import { elapsed } from '@aztec-labs/foundation/timer';
7
+ import {
8
+ type BlockHash,
9
+ EventDrivenL2BlockStream,
10
+ type L2Block,
11
+ type L2BlockSource,
12
+ type L2BlockStreamEvent,
13
+ type L2BlockStreamEventHandler,
14
+ type L2BlockStreamLocalDataProvider,
15
+ type LocalChainTips,
16
+ } from '@aztec-labs/stdlib/block';
17
+ import {
18
+ WorldStateRunningState,
19
+ type WorldStateSyncStatus,
20
+ type WorldStateSynchronizer,
21
+ type WorldStateSynchronizerStatus,
22
+ } from '@aztec-labs/stdlib/interfaces/server';
23
+ import type { L1ToL2MessageSource } from '@aztec-labs/stdlib/messaging';
24
+ import type { SnapshotDataKeys } from '@aztec-labs/stdlib/snapshots';
25
+ import type { L2BlockHandledStats } from '@aztec-labs/stdlib/stats';
26
+ import { MerkleTreeId, type MerkleTreeReadOperations, type MerkleTreeWriteOperations } from '@aztec-labs/stdlib/trees';
27
+ import { getTelemetryClient } from '@aztec-labs/telemetry-client';
28
+
29
+ import { WorldStateInstrumentation } from '../instrumentation/instrumentation.js';
30
+ import type { WorldStateStatusFull } from '../native/message.js';
31
+ import type { MerkleTreeAdminDatabase } from '../world-state-db/merkle_tree_db.js';
32
+ import type { WorldStateConfig } from './config.js';
33
+ import { WorldStateSynchronizerError } from './errors.js';
34
+
35
+ export type { SnapshotDataKeys };
36
+
37
+ /**
38
+ * Synchronizes the world state with the L2 blocks from a L2BlockSource via a block stream.
39
+ * The synchronizer will download the L2 blocks from the L2BlockSource and update the merkle trees.
40
+ * Handles chain reorgs via the L2BlockStream.
41
+ */
42
+ export class ServerWorldStateSynchronizer
43
+ implements WorldStateSynchronizer, L2BlockStreamLocalDataProvider, L2BlockStreamEventHandler
44
+ {
45
+ private readonly merkleTreeCommitted: MerkleTreeReadOperations;
46
+
47
+ private latestBlockNumberAtStart = BlockNumber.ZERO;
48
+ private historyToKeep: number | undefined;
49
+ private currentState: WorldStateRunningState = WorldStateRunningState.IDLE;
50
+
51
+ private syncPromise = promiseWithResolvers<void>();
52
+ protected blockStream: EventDrivenL2BlockStream | undefined;
53
+
54
+ // WorldState doesn't track the proven block number, it only tracks the latest tips of the pending chain and the finalized chain
55
+ // store the proven block number here, in the synchronizer, so that we don't end up spamming the logs with 'chain-proved' events
56
+ private provenBlockNumber: BlockNumber | undefined;
57
+
58
+ constructor(
59
+ private readonly merkleTreeDb: MerkleTreeAdminDatabase,
60
+ private readonly l2BlockSource: L2BlockSource & L1ToL2MessageSource,
61
+ private readonly config: WorldStateConfig,
62
+ private instrumentation = new WorldStateInstrumentation(getTelemetryClient()),
63
+ private readonly log: Logger = createLogger('world_state'),
64
+ ) {
65
+ this.merkleTreeCommitted = this.merkleTreeDb.getCommitted();
66
+ this.historyToKeep = config.worldStateCheckpointHistory < 1 ? undefined : config.worldStateCheckpointHistory;
67
+ this.log.info(
68
+ `Created world state synchroniser with block history of ${
69
+ this.historyToKeep === undefined ? 'infinity' : this.historyToKeep
70
+ }`,
71
+ );
72
+ }
73
+
74
+ public getCommitted(): MerkleTreeReadOperations {
75
+ return this.merkleTreeDb.getCommitted();
76
+ }
77
+
78
+ public getSnapshot(blockNumber: BlockNumber): MerkleTreeReadOperations {
79
+ return this.merkleTreeDb.getSnapshot(blockNumber);
80
+ }
81
+
82
+ public async getVerifiedSnapshot(blockNumber: BlockNumber, blockHash: BlockHash): Promise<MerkleTreeReadOperations> {
83
+ const snapshot = this.merkleTreeDb.getSnapshot(blockNumber);
84
+ // Block 0's snapshot is the pre-genesis archive view (size 0), so archive leaf 0 is not visible from it;
85
+ // verify against the initial header hash instead. For later blocks, read archive leaf `blockNumber` from the
86
+ // snapshot's own view so the exact handle we return is validated against the requested fork.
87
+ const actualHash =
88
+ blockNumber === BlockNumber.ZERO
89
+ ? (await this.merkleTreeCommitted.getInitialHeader().hash()).toString()
90
+ : (await snapshot.getLeafValue(MerkleTreeId.ARCHIVE, BigInt(blockNumber)))?.toString();
91
+
92
+ if (actualHash === undefined) {
93
+ // A missing archive leaf means either the block's history has been pruned away (permanent: the block predates
94
+ // the oldest historical block kept by world state) or a reorg flipped the fork between the sync and this read
95
+ // (transient). Only the latter is worth retrying, so it alone surfaces as WorldStateSynchronizerError.
96
+ const { oldestHistoricalBlock } = await this.merkleTreeDb.getStatusSummary();
97
+ if (blockNumber < oldestHistoricalBlock) {
98
+ throw new Error(
99
+ `Unable to find leaf for block ${blockNumber} in the archive tree: world state history has been pruned to block ${oldestHistoricalBlock}`,
100
+ );
101
+ }
102
+ throw new WorldStateSynchronizerError(`Unable to read block hash at block ${blockNumber} to verify snapshot`, {
103
+ cause: { reason: 'block_not_available', targetBlockNumber: blockNumber },
104
+ });
105
+ }
106
+ if (actualHash !== blockHash.toString()) {
107
+ throw new WorldStateSynchronizerError(
108
+ `Block hash mismatch at block ${blockNumber} (expected ${blockHash} but got ${actualHash})`,
109
+ {
110
+ cause: {
111
+ reason: 'block_hash_mismatch',
112
+ targetBlockNumber: blockNumber,
113
+ expectedHash: blockHash.toString(),
114
+ actualHash,
115
+ },
116
+ },
117
+ );
118
+ }
119
+ return snapshot;
120
+ }
121
+
122
+ public fork(blockNumber?: BlockNumber, opts?: { closeDelayMs?: number }): Promise<MerkleTreeWriteOperations> {
123
+ return this.merkleTreeDb.fork(blockNumber, opts);
124
+ }
125
+
126
+ public backupTo(dstPath: string, compact?: boolean): Promise<Record<Exclude<SnapshotDataKeys, 'archiver'>, string>> {
127
+ return this.merkleTreeDb.backupTo(dstPath, compact);
128
+ }
129
+
130
+ public clear(): Promise<void> {
131
+ return this.merkleTreeDb.clear();
132
+ }
133
+
134
+ public async start() {
135
+ if (this.currentState === WorldStateRunningState.STOPPED) {
136
+ throw new Error('Synchronizer already stopped');
137
+ }
138
+ if (this.currentState !== WorldStateRunningState.IDLE) {
139
+ return this.syncPromise;
140
+ }
141
+
142
+ // Get the current latest block number
143
+ this.latestBlockNumberAtStart = BlockNumber(await this.l2BlockSource.getBlockNumber());
144
+
145
+ const blockToDownloadFrom = (await this.getLatestBlockNumber()) + 1;
146
+
147
+ if (blockToDownloadFrom <= this.latestBlockNumberAtStart) {
148
+ // If there are blocks to be retrieved, go to a synching state
149
+ this.setCurrentState(WorldStateRunningState.SYNCHING);
150
+ this.log.verbose(`Starting sync from ${blockToDownloadFrom} to latest block ${this.latestBlockNumberAtStart}`);
151
+ } else {
152
+ // If no blocks to be retrieved, go straight to running
153
+ this.setCurrentState(WorldStateRunningState.RUNNING);
154
+ this.syncPromise.resolve();
155
+ this.log.debug(`Next block ${blockToDownloadFrom} already beyond latest block ${this.latestBlockNumberAtStart}`);
156
+ }
157
+
158
+ this.blockStream = this.createBlockStream();
159
+ this.blockStream.start();
160
+ this.log.info(`Started world state synchronizer from block ${blockToDownloadFrom}`);
161
+ return this.syncPromise.promise;
162
+ }
163
+
164
+ protected createBlockStream(): EventDrivenL2BlockStream {
165
+ const logger = createLogger('world-state:block_stream');
166
+ return new EventDrivenL2BlockStream(this.l2BlockSource, this, this, logger, {
167
+ pollIntervalMS: this.config.worldStateBlockCheckIntervalMS,
168
+ batchSize: this.config.worldStateBlockRequestBatchSize,
169
+ ignoreCheckpoints: true,
170
+ });
171
+ }
172
+
173
+ public async stop() {
174
+ this.log.debug('Stopping block stream...');
175
+ await this.blockStream?.stop();
176
+ this.log.debug('Stopping merkle trees...');
177
+ await this.merkleTreeDb.close();
178
+ this.setCurrentState(WorldStateRunningState.STOPPED);
179
+ this.log.info(`Stopped world state synchronizer`);
180
+ }
181
+
182
+ public async status(): Promise<WorldStateSynchronizerStatus> {
183
+ const summary = await this.merkleTreeDb.getStatusSummary();
184
+ const status: WorldStateSyncStatus = {
185
+ latestBlockNumber: summary.unfinalizedBlockNumber,
186
+ latestBlockHash: (await this.getL2BlockHash(summary.unfinalizedBlockNumber)) ?? '',
187
+ finalizedBlockNumber: summary.finalizedBlockNumber,
188
+ oldestHistoricBlockNumber: summary.oldestHistoricalBlock,
189
+ treesAreSynched: summary.treesAreSynched,
190
+ };
191
+ return {
192
+ syncSummary: status,
193
+ state: this.currentState,
194
+ };
195
+ }
196
+
197
+ public async getLatestBlockNumber() {
198
+ return (await this.getL2Tips()).proposed.number;
199
+ }
200
+
201
+ public async stopSync() {
202
+ this.log.debug('Stopping sync...');
203
+ await this.blockStream?.stop();
204
+ this.log.info('Stopped sync');
205
+ }
206
+
207
+ public resumeSync() {
208
+ if (!this.blockStream) {
209
+ throw new Error('Cannot resume sync as block stream is not initialized');
210
+ }
211
+ this.log.debug('Resuming sync...');
212
+ this.blockStream.start();
213
+ this.log.info('Resumed sync');
214
+ }
215
+
216
+ /**
217
+ * Forces an immediate sync.
218
+ * @param targetBlockNumber - The target block number that we must sync to. Will download unproven blocks if needed to reach it.
219
+ * @param blockHash - If provided, verifies the block at targetBlockNumber matches this hash. On mismatch, triggers a resync (reorg detection).
220
+ * @returns A promise that resolves with the block number the world state was synced to
221
+ */
222
+ public async syncImmediate(targetBlockNumber?: BlockNumber, blockHash?: BlockHash): Promise<BlockNumber> {
223
+ if (this.currentState !== WorldStateRunningState.RUNNING) {
224
+ throw new Error(`World State is not running. Unable to perform sync.`);
225
+ }
226
+
227
+ if (this.blockStream === undefined) {
228
+ throw new Error('Block stream is not initialized. Unable to perform sync.');
229
+ }
230
+
231
+ // If we have been given a block number to sync to and we have reached that number then return
232
+ const currentBlockNumber = await this.getLatestBlockNumber();
233
+ if (targetBlockNumber !== undefined && targetBlockNumber <= currentBlockNumber) {
234
+ if (blockHash === undefined) {
235
+ return currentBlockNumber;
236
+ }
237
+
238
+ // If a block hash was provided, verify we're on the expected fork
239
+ const currentHash = await this.getL2BlockHash(targetBlockNumber);
240
+ if (currentHash === blockHash.toString()) {
241
+ return currentBlockNumber;
242
+ }
243
+ // Hash mismatch: a reorg may have occurred, fall through to trigger sync
244
+ this.log.debug(
245
+ `World state block hash mismatch at ${targetBlockNumber} (expected ${blockHash}, got ${currentHash}). Triggering resync.`,
246
+ );
247
+ }
248
+ this.log.debug(`World State at ${currentBlockNumber} told to sync to ${targetBlockNumber ?? 'latest'}`);
249
+
250
+ // If the archiver is behind the target block, force an archiver sync
251
+ if (targetBlockNumber) {
252
+ const archiverLatestBlock = BlockNumber(await this.l2BlockSource.getBlockNumber());
253
+ if (archiverLatestBlock < targetBlockNumber) {
254
+ this.log.debug(`Archiver is at ${archiverLatestBlock} behind target block ${targetBlockNumber}.`);
255
+ await this.l2BlockSource.syncImmediate();
256
+ }
257
+ }
258
+
259
+ // Force the block stream to sync against the archiver now
260
+ await this.blockStream.sync();
261
+
262
+ // If we have been given a block number to sync to and we have not reached that number then fail
263
+ const updatedBlockNumber = await this.getLatestBlockNumber();
264
+ if (targetBlockNumber !== undefined && targetBlockNumber > updatedBlockNumber) {
265
+ throw new WorldStateSynchronizerError(
266
+ `Unable to sync to block number ${targetBlockNumber} (last synced is ${updatedBlockNumber})`,
267
+ {
268
+ cause: {
269
+ reason: 'block_not_available',
270
+ previousBlockNumber: currentBlockNumber,
271
+ updatedBlockNumber,
272
+ targetBlockNumber,
273
+ },
274
+ },
275
+ );
276
+ }
277
+
278
+ // If a block hash was provided, verify we're on the expected fork after syncing, throw otherwise
279
+ if (blockHash !== undefined && targetBlockNumber !== undefined) {
280
+ const updatedHash = await this.getL2BlockHash(targetBlockNumber);
281
+ if (updatedHash !== blockHash.toString()) {
282
+ throw new WorldStateSynchronizerError(
283
+ `Block hash mismatch at block ${targetBlockNumber} (expected ${blockHash} but got ${updatedHash})`,
284
+ {
285
+ cause: {
286
+ reason: 'block_hash_mismatch',
287
+ targetBlockNumber,
288
+ expectedHash: blockHash.toString(),
289
+ actualHash: updatedHash,
290
+ },
291
+ },
292
+ );
293
+ }
294
+ }
295
+
296
+ return updatedBlockNumber;
297
+ }
298
+
299
+ /** Returns the L2 block hash for a given number. Used by the L2BlockStream for detecting reorgs. */
300
+ public async getL2BlockHash(number: BlockNumber): Promise<string | undefined> {
301
+ if (number === BlockNumber.ZERO) {
302
+ return (await this.merkleTreeCommitted.getInitialHeader().hash()).toString();
303
+ }
304
+ return this.merkleTreeCommitted.getLeafValue(MerkleTreeId.ARCHIVE, BigInt(number)).then(leaf => leaf?.toString());
305
+ }
306
+
307
+ /**
308
+ * Returns the proposed, proven, and finalized block tips of the chain. World state drives its block stream with
309
+ * `ignoreCheckpoints`, so it does not track checkpointed blocks or checkpoints and omits `checkpointed` from the tips
310
+ * it reports.
311
+ */
312
+ public async getL2Tips(): Promise<LocalChainTips> {
313
+ const status = await this.merkleTreeDb.getStatusSummary();
314
+ const unfinalizedBlockHashPromise = this.getL2BlockHash(status.unfinalizedBlockNumber);
315
+ const finalizedBlockHashPromise = this.getL2BlockHash(status.finalizedBlockNumber);
316
+
317
+ const provenBlockNumber = this.provenBlockNumber ?? status.finalizedBlockNumber;
318
+ const provenBlockHashPromise =
319
+ this.provenBlockNumber === undefined ? finalizedBlockHashPromise : this.getL2BlockHash(this.provenBlockNumber);
320
+
321
+ const [unfinalizedBlockHash, finalizedBlockHash, provenBlockHash] = await Promise.all([
322
+ unfinalizedBlockHashPromise,
323
+ finalizedBlockHashPromise,
324
+ provenBlockHashPromise,
325
+ ]);
326
+ return {
327
+ proposed: { number: status.unfinalizedBlockNumber, hash: unfinalizedBlockHash },
328
+ finalized: {
329
+ block: { number: status.finalizedBlockNumber, hash: finalizedBlockHash },
330
+ },
331
+ proven: {
332
+ block: { number: provenBlockNumber, hash: provenBlockHash },
333
+ },
334
+ };
335
+ }
336
+
337
+ /** Handles an event emitted by the block stream. */
338
+ public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
339
+ switch (event.type) {
340
+ case 'blocks-added':
341
+ await this.handleL2Blocks(event.blocks);
342
+ break;
343
+ case 'chain-pruned':
344
+ await this.handleChainPruned(event.block.number);
345
+ break;
346
+ case 'chain-proven':
347
+ await this.handleChainProven(event.block.number);
348
+ break;
349
+ case 'chain-finalized':
350
+ await this.handleChainFinalized(event.block.number);
351
+ break;
352
+ // World state runs in block mode with ignoreCheckpoints: it tracks tips via blocks-added/pruned/proven/finalized
353
+ // and ignores the thin tip events (it never anchors on them).
354
+ case 'chain-proposed':
355
+ case 'chain-checkpointed':
356
+ break;
357
+ default: {
358
+ const _: never = event;
359
+ break;
360
+ }
361
+ }
362
+ }
363
+
364
+ /**
365
+ * Handles a list of L2 blocks (i.e. Inserts the new note hashes into the merkle tree).
366
+ * @param l2Blocks - The L2 blocks to handle.
367
+ * @returns Whether the block handled was produced by this same node.
368
+ */
369
+ private async handleL2Blocks(l2Blocks: L2Block[]) {
370
+ this.log.debug(`Handling L2 blocks ${l2Blocks[0].number} to ${l2Blocks.at(-1)!.number}`);
371
+
372
+ // Derive each block's real L1-to-L2 message bundle from the compact leaf-index range it inserted:
373
+ // the messages between the parent block's L1-to-L2 tree leaf count and this block's, resolved via the
374
+ // Inbox buckets. Blocks in a batch are consecutive, so we track the running leaf count.
375
+ const messagesForBlocks = new Map<BlockNumber, Fr[]>();
376
+ let prevLeafCount = await this.getL1ToL2LeafCountBefore(l2Blocks[0].number);
377
+ for (const block of l2Blocks) {
378
+ const blockLeafCount = BigInt(block.header.state.l1ToL2MessageTree.nextAvailableLeafIndex);
379
+ if (blockLeafCount > prevLeafCount) {
380
+ const startBucket = await this.l2BlockSource.getInboxBucketByTotalMsgCount(prevLeafCount);
381
+ const endBucket = await this.l2BlockSource.getInboxBucketByTotalMsgCount(blockLeafCount);
382
+ if (startBucket !== undefined && endBucket !== undefined) {
383
+ messagesForBlocks.set(
384
+ block.number,
385
+ await this.l2BlockSource.getL1ToL2MessagesBetweenBuckets(startBucket.seq, endBucket.seq),
386
+ );
387
+ }
388
+ }
389
+ prevLeafCount = blockLeafCount;
390
+ }
391
+
392
+ let updateStatus: WorldStateStatusFull | undefined = undefined;
393
+ for (const block of l2Blocks) {
394
+ const [duration, result] = await elapsed(() =>
395
+ this.handleL2Block(block, messagesForBlocks.get(block.number) ?? []),
396
+ );
397
+ this.log.info(`World state updated with L2 block ${block.number}`, {
398
+ eventName: 'l2-block-handled',
399
+ duration,
400
+ unfinalizedBlockNumber: BigInt(result.summary.unfinalizedBlockNumber),
401
+ finalizedBlockNumber: BigInt(result.summary.finalizedBlockNumber),
402
+ oldestHistoricBlock: BigInt(result.summary.oldestHistoricalBlock),
403
+ ...block.getStats(),
404
+ } satisfies L2BlockHandledStats);
405
+ updateStatus = result;
406
+ }
407
+ if (!updateStatus) {
408
+ return;
409
+ }
410
+ this.instrumentation.updateWorldStateMetrics(updateStatus);
411
+ }
412
+
413
+ /** The L1-to-L2 message tree leaf count as of the block before `blockNumber` (0 if that block is genesis). */
414
+ private async getL1ToL2LeafCountBefore(blockNumber: BlockNumber): Promise<bigint> {
415
+ const parentNumber = blockNumber - 1;
416
+ if (parentNumber < INITIAL_L2_BLOCK_NUM) {
417
+ return 0n;
418
+ }
419
+ const parentBlock = await this.l2BlockSource.getBlockData({ number: BlockNumber(parentNumber) });
420
+ return parentBlock === undefined ? 0n : BigInt(parentBlock.header.state.l1ToL2MessageTree.nextAvailableLeafIndex);
421
+ }
422
+
423
+ /**
424
+ * Handles a single L2 block (i.e. Inserts the new note hashes into the merkle tree).
425
+ * @param l2Block - The L2 block to handle.
426
+ * @param l1ToL2Messages - The L1 to L2 messages for the block.
427
+ * @returns Whether the block handled was produced by this same node.
428
+ */
429
+ protected async handleL2Block(l2Block: L2Block, l1ToL2Messages: Fr[]): Promise<WorldStateStatusFull> {
430
+ this.log.debug(`Pushing L2 block ${l2Block.number} to merkle tree db `, {
431
+ blockNumber: l2Block.number,
432
+ blockHash: await l2Block.hash().then(h => h.toString()),
433
+ l1ToL2Messages: l1ToL2Messages.map(msg => msg.toString()),
434
+ blockHeader: l2Block.header.toInspect(),
435
+ blockStats: l2Block.getStats(),
436
+ });
437
+ const result = await this.merkleTreeDb.handleL2BlockAndMessages(l2Block, l1ToL2Messages);
438
+
439
+ if (this.currentState === WorldStateRunningState.SYNCHING && l2Block.number >= this.latestBlockNumberAtStart) {
440
+ this.setCurrentState(WorldStateRunningState.RUNNING);
441
+ this.syncPromise.resolve();
442
+ }
443
+
444
+ return result;
445
+ }
446
+
447
+ private async handleChainFinalized(blockNumber: BlockNumber) {
448
+ this.log.verbose(`Finalized chain is now at block ${blockNumber}`);
449
+ // If the finalized block number is older than the oldest available block in world state,
450
+ // skip entirely. The finalized block number can jump backwards (e.g. when the finalization
451
+ // heuristic changes) and try to read block data that has already been pruned. When this
452
+ // happens, there is nothing useful to do — the native world state is already finalized
453
+ // past this point and pruning has already happened.
454
+ const currentSummary = await this.merkleTreeDb.getStatusSummary();
455
+ if (blockNumber < currentSummary.oldestHistoricalBlock || blockNumber < 1) {
456
+ this.log.trace(
457
+ `Finalized block ${blockNumber} is older than the oldest available block ${currentSummary.oldestHistoricalBlock}. Skipping.`,
458
+ );
459
+ return;
460
+ }
461
+ const summary = await this.merkleTreeDb.setFinalized(blockNumber);
462
+ if (this.historyToKeep === undefined) {
463
+ return;
464
+ }
465
+ const finalisedBlockData = await this.l2BlockSource.getBlockData({ number: summary.finalizedBlockNumber });
466
+ if (finalisedBlockData === undefined) {
467
+ this.log.warn(
468
+ `Failed to retrieve checkpointed block for finalized block number: ${summary.finalizedBlockNumber}`,
469
+ );
470
+ return;
471
+ }
472
+ // Compute the required historic checkpoint number
473
+ const newHistoricCheckpointNumber = finalisedBlockData.checkpointNumber - this.historyToKeep + 1;
474
+ if (newHistoricCheckpointNumber <= 1) {
475
+ return;
476
+ }
477
+ // Retrieve the historic checkpoint
478
+ const historicCheckpoint = await this.l2BlockSource.getCheckpoint({
479
+ number: CheckpointNumber(newHistoricCheckpointNumber),
480
+ });
481
+ if (!historicCheckpoint) {
482
+ this.log.warn(`Failed to retrieve checkpoint number ${newHistoricCheckpointNumber} from Archiver`);
483
+ return;
484
+ }
485
+ if (historicCheckpoint.checkpoint.blocks.length === 0 || historicCheckpoint.checkpoint.blocks[0] === undefined) {
486
+ this.log.warn(`Retrieved checkpoint number ${newHistoricCheckpointNumber} has no blocks!`);
487
+ return;
488
+ }
489
+ // Find the block at the start of the checkpoint and remove blocks up to this one
490
+ const newHistoricBlock = historicCheckpoint.checkpoint.blocks[0];
491
+ if (newHistoricBlock.number <= currentSummary.oldestHistoricalBlock) {
492
+ this.log.debug(
493
+ `Historic block ${newHistoricBlock.number} is not newer than oldest available ${currentSummary.oldestHistoricalBlock}. Skipping prune.`,
494
+ );
495
+ return;
496
+ }
497
+ this.log.verbose(`Pruning historic blocks to ${newHistoricBlock.number}`);
498
+ const status = await this.merkleTreeDb.removeHistoricalBlocks(BlockNumber(newHistoricBlock.number));
499
+ this.log.debug(`World state summary `, status.summary);
500
+ }
501
+
502
+ private handleChainProven(blockNumber: BlockNumber) {
503
+ this.provenBlockNumber = blockNumber;
504
+ this.log.debug(`Proven chain is now at block ${blockNumber}`);
505
+ return Promise.resolve();
506
+ }
507
+
508
+ private async handleChainPruned(blockNumber: BlockNumber) {
509
+ this.log.info(`Chain pruned to block ${blockNumber}`);
510
+ const status = await this.merkleTreeDb.unwindBlocks(blockNumber);
511
+ if (this.provenBlockNumber !== undefined && this.provenBlockNumber > blockNumber) {
512
+ this.provenBlockNumber = undefined;
513
+ }
514
+ this.instrumentation.updateWorldStateMetrics(status);
515
+ }
516
+
517
+ /**
518
+ * Method to set the value of the current state.
519
+ * @param newState - New state value.
520
+ */
521
+ private setCurrentState(newState: WorldStateRunningState) {
522
+ this.currentState = newState;
523
+ this.log.debug(`Moved to state ${WorldStateRunningState[this.currentState]}`);
524
+ }
525
+ }
@@ -0,0 +1 @@
1
+ export * from './utils.js';