@aztec/archiver 0.0.1-commit.a89ec08 → 0.0.1-commit.aa0c64f

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 (121) hide show
  1. package/README.md +19 -11
  2. package/dest/archiver.d.ts +71 -16
  3. package/dest/archiver.d.ts.map +1 -1
  4. package/dest/archiver.js +276 -71
  5. package/dest/config.d.ts +7 -3
  6. package/dest/config.d.ts.map +1 -1
  7. package/dest/config.js +43 -14
  8. package/dest/errors.d.ts +50 -2
  9. package/dest/errors.d.ts.map +1 -1
  10. package/dest/errors.js +74 -2
  11. package/dest/factory.d.ts +19 -7
  12. package/dest/factory.d.ts.map +1 -1
  13. package/dest/factory.js +67 -24
  14. package/dest/index.d.ts +11 -3
  15. package/dest/index.d.ts.map +1 -1
  16. package/dest/index.js +10 -2
  17. package/dest/l1/calldata_retriever.d.ts +9 -1
  18. package/dest/l1/calldata_retriever.d.ts.map +1 -1
  19. package/dest/l1/calldata_retriever.js +22 -11
  20. package/dest/l1/data_retrieval.d.ts +30 -13
  21. package/dest/l1/data_retrieval.d.ts.map +1 -1
  22. package/dest/l1/data_retrieval.js +36 -37
  23. package/dest/l1/trace_tx.d.ts +12 -66
  24. package/dest/l1/trace_tx.d.ts.map +1 -1
  25. package/dest/l1/validate_historical_logs.d.ts +23 -0
  26. package/dest/l1/validate_historical_logs.d.ts.map +1 -0
  27. package/dest/l1/validate_historical_logs.js +108 -0
  28. package/dest/modules/contract_data_source_adapter.d.ts +25 -0
  29. package/dest/modules/contract_data_source_adapter.d.ts.map +1 -0
  30. package/dest/modules/contract_data_source_adapter.js +32 -0
  31. package/dest/modules/data_source_base.d.ts +71 -48
  32. package/dest/modules/data_source_base.d.ts.map +1 -1
  33. package/dest/modules/data_source_base.js +250 -144
  34. package/dest/modules/data_store_updater.d.ts +30 -13
  35. package/dest/modules/data_store_updater.d.ts.map +1 -1
  36. package/dest/modules/data_store_updater.js +129 -111
  37. package/dest/modules/instrumentation.d.ts +26 -2
  38. package/dest/modules/instrumentation.d.ts.map +1 -1
  39. package/dest/modules/instrumentation.js +58 -9
  40. package/dest/modules/l1_synchronizer.d.ts +13 -8
  41. package/dest/modules/l1_synchronizer.d.ts.map +1 -1
  42. package/dest/modules/l1_synchronizer.js +463 -224
  43. package/dest/modules/outbox_trees_resolver.d.ts +62 -0
  44. package/dest/modules/outbox_trees_resolver.d.ts.map +1 -0
  45. package/dest/modules/outbox_trees_resolver.js +162 -0
  46. package/dest/modules/validation.d.ts +30 -7
  47. package/dest/modules/validation.d.ts.map +1 -1
  48. package/dest/modules/validation.js +35 -17
  49. package/dest/store/block_store.d.ts +175 -68
  50. package/dest/store/block_store.d.ts.map +1 -1
  51. package/dest/store/block_store.js +627 -239
  52. package/dest/store/contract_class_store.d.ts +17 -4
  53. package/dest/store/contract_class_store.d.ts.map +1 -1
  54. package/dest/store/contract_class_store.js +37 -67
  55. package/dest/store/contract_instance_store.d.ts +28 -1
  56. package/dest/store/contract_instance_store.d.ts.map +1 -1
  57. package/dest/store/contract_instance_store.js +49 -1
  58. package/dest/store/data_stores.d.ts +68 -0
  59. package/dest/store/data_stores.d.ts.map +1 -0
  60. package/dest/store/data_stores.js +54 -0
  61. package/dest/store/function_names_cache.d.ts +17 -0
  62. package/dest/store/function_names_cache.d.ts.map +1 -0
  63. package/dest/store/function_names_cache.js +30 -0
  64. package/dest/store/l2_tips_cache.d.ts +13 -7
  65. package/dest/store/l2_tips_cache.d.ts.map +1 -1
  66. package/dest/store/l2_tips_cache.js +13 -76
  67. package/dest/store/log_store.d.ts +42 -37
  68. package/dest/store/log_store.d.ts.map +1 -1
  69. package/dest/store/log_store.js +259 -443
  70. package/dest/store/log_store_codec.d.ts +78 -0
  71. package/dest/store/log_store_codec.d.ts.map +1 -0
  72. package/dest/store/log_store_codec.js +110 -0
  73. package/dest/store/message_store.d.ts +11 -1
  74. package/dest/store/message_store.d.ts.map +1 -1
  75. package/dest/store/message_store.js +50 -8
  76. package/dest/test/fake_l1_state.d.ts +8 -3
  77. package/dest/test/fake_l1_state.d.ts.map +1 -1
  78. package/dest/test/fake_l1_state.js +78 -21
  79. package/dest/test/mock_l2_block_source.d.ts +48 -50
  80. package/dest/test/mock_l2_block_source.d.ts.map +1 -1
  81. package/dest/test/mock_l2_block_source.js +228 -179
  82. package/dest/test/mock_structs.d.ts +1 -1
  83. package/dest/test/mock_structs.d.ts.map +1 -1
  84. package/dest/test/mock_structs.js +2 -2
  85. package/dest/test/noop_l1_archiver.d.ts +14 -6
  86. package/dest/test/noop_l1_archiver.d.ts.map +1 -1
  87. package/dest/test/noop_l1_archiver.js +26 -10
  88. package/package.json +15 -14
  89. package/src/archiver.ts +361 -77
  90. package/src/config.ts +51 -13
  91. package/src/errors.ts +117 -2
  92. package/src/factory.ts +81 -22
  93. package/src/index.ts +18 -2
  94. package/src/l1/calldata_retriever.ts +29 -11
  95. package/src/l1/data_retrieval.ts +60 -54
  96. package/src/l1/validate_historical_logs.ts +140 -0
  97. package/src/modules/contract_data_source_adapter.ts +46 -0
  98. package/src/modules/data_source_base.ts +325 -187
  99. package/src/modules/data_store_updater.ts +155 -139
  100. package/src/modules/instrumentation.ts +63 -10
  101. package/src/modules/l1_synchronizer.ts +630 -273
  102. package/src/modules/outbox_trees_resolver.ts +199 -0
  103. package/src/modules/validation.ts +80 -23
  104. package/src/store/block_store.ts +766 -290
  105. package/src/store/contract_class_store.ts +43 -101
  106. package/src/store/contract_instance_store.ts +61 -1
  107. package/src/store/data_stores.ts +104 -0
  108. package/src/store/function_names_cache.ts +37 -0
  109. package/src/store/l2_tips_cache.ts +16 -70
  110. package/src/store/log_store.ts +298 -609
  111. package/src/store/log_store_codec.ts +143 -0
  112. package/src/store/message_store.ts +59 -9
  113. package/src/structs/inbox_message.ts +1 -1
  114. package/src/test/fake_l1_state.ts +99 -32
  115. package/src/test/mock_l2_block_source.ts +285 -232
  116. package/src/test/mock_structs.ts +5 -2
  117. package/src/test/noop_l1_archiver.ts +54 -11
  118. package/dest/store/kv_archiver_store.d.ts +0 -362
  119. package/dest/store/kv_archiver_store.d.ts.map +0 -1
  120. package/dest/store/kv_archiver_store.js +0 -475
  121. package/src/store/kv_archiver_store.ts +0 -685
package/src/archiver.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { BlobClientInterface } from '@aztec/blob-client/client';
2
2
  import { EpochCache } from '@aztec/epoch-cache';
3
- import { BlockTagTooOldError, RollupContract } from '@aztec/ethereum/contracts';
3
+ import { BlockTagTooOldError, OutboxContract, RollupContract } from '@aztec/ethereum/contracts';
4
4
  import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
5
5
  import type { ViemPublicClient, ViemPublicDebugClient } from '@aztec/ethereum/types';
6
6
  import { BlockNumber, CheckpointNumber, EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
@@ -11,32 +11,41 @@ import { EthAddress } from '@aztec/foundation/eth-address';
11
11
  import { type Logger, createLogger } from '@aztec/foundation/log';
12
12
  import { type PromiseWithResolvers, promiseWithResolvers } from '@aztec/foundation/promise';
13
13
  import { RunningPromise, makeLoggingErrorHandler } from '@aztec/foundation/running-promise';
14
- import { DateProvider } from '@aztec/foundation/timer';
14
+ import { DateProvider, elapsed } from '@aztec/foundation/timer';
15
15
  import {
16
16
  type ArchiverEmitter,
17
+ type BlockHash,
17
18
  L2Block,
18
19
  type L2BlockSink,
20
+ L2BlockSourceEvents,
19
21
  type L2Tips,
20
22
  type ValidateCheckpointResult,
23
+ l2TipsEqual,
21
24
  } from '@aztec/stdlib/block';
22
- import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
25
+ import { type ProposedCheckpointInput, PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
23
26
  import {
24
27
  type L1RollupConstants,
25
28
  getEpochAtSlot,
26
29
  getSlotAtNextL1Block,
27
30
  getSlotRangeForEpoch,
31
+ getTimestampForSlot,
28
32
  getTimestampRangeForEpoch,
29
33
  } from '@aztec/stdlib/epoch-helpers';
34
+ import type { L2ToL1MembershipWitness } from '@aztec/stdlib/messaging';
35
+ import { ConsensusTimetable } from '@aztec/stdlib/timetable';
36
+ import type { BlockHeader, TxHash } from '@aztec/stdlib/tx';
30
37
  import { type TelemetryClient, type Traceable, type Tracer, trackSpan } from '@aztec/telemetry-client';
31
38
 
32
39
  import { type ArchiverConfig, mapArchiverConfig } from './config.js';
33
- import { BlockAlreadyCheckpointedError, NoBlobBodiesFoundError } from './errors.js';
40
+ import { BlockAlreadyCheckpointedError, BlockOrCheckpointSlotExpiredError, NoBlobBodiesFoundError } from './errors.js';
41
+ import { validateAndLogHistoricalLogsAvailability } from './l1/validate_historical_logs.js';
34
42
  import { validateAndLogTraceAvailability } from './l1/validate_trace.js';
35
43
  import { ArchiverDataSourceBase } from './modules/data_source_base.js';
36
44
  import { ArchiverDataStoreUpdater } from './modules/data_store_updater.js';
37
45
  import type { ArchiverInstrumentation } from './modules/instrumentation.js';
38
46
  import type { ArchiverL1Synchronizer } from './modules/l1_synchronizer.js';
39
- import type { KVArchiverDataStore } from './store/kv_archiver_store.js';
47
+ import { OutboxTreesResolver } from './modules/outbox_trees_resolver.js';
48
+ import { type ArchiverDataStores, backupArchiverDataStores, getArchiverSynchPoint } from './store/data_stores.js';
40
49
  import { L2TipsCache } from './store/l2_tips_cache.js';
41
50
 
42
51
  /** Export ArchiverEmitter for use in factory and tests. */
@@ -44,11 +53,20 @@ export type { ArchiverEmitter };
44
53
 
45
54
  /** Request to add a block to the archiver, queued for processing by the sync loop. */
46
55
  type AddBlockRequest = {
56
+ type: 'block';
47
57
  block: L2Block;
48
58
  resolve: () => void;
49
59
  reject: (err: Error) => void;
50
60
  };
51
61
 
62
+ /** Request to add a proposed checkpoint to the archiver, queued for processing by the sync loop. */
63
+ type AddProposedCheckpointRequest = {
64
+ type: 'checkpoint';
65
+ checkpoint: ProposedCheckpointInput;
66
+ resolve: () => void;
67
+ reject: (err: Error) => void;
68
+ };
69
+
52
70
  export type ArchiverDeps = {
53
71
  telemetry?: TelemetryClient;
54
72
  blobClient: BlobClientInterface;
@@ -56,6 +74,16 @@ export type ArchiverDeps = {
56
74
  dateProvider?: DateProvider;
57
75
  };
58
76
 
77
+ /** Minimal dependency for observing whether a checkpoint proposal was received for a slot. */
78
+ export type CheckpointProposalPresence = {
79
+ /** Returns true when a checkpoint proposal for `slot` has been retained locally. */
80
+ hasCheckpointProposalForSlot(slot: SlotNumber): Promise<boolean>;
81
+ };
82
+
83
+ const noCheckpointProposalPresence: CheckpointProposalPresence = {
84
+ hasCheckpointProposalForSlot: () => Promise.resolve(false),
85
+ };
86
+
59
87
  /**
60
88
  * Pulls checkpoints in a non-blocking manner and provides interface for their retrieval.
61
89
  * Responsible for handling robust L1 polling so that other components do not need to
@@ -71,11 +99,14 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
71
99
  /** L1 synchronizer that handles fetching checkpoints and messages from L1. */
72
100
  private readonly synchronizer: ArchiverL1Synchronizer;
73
101
 
102
+ /** Resolver for L2-to-L1 message membership witnesses, built over this archiver's read view. */
103
+ private readonly outboxTreesResolver: OutboxTreesResolver;
104
+
74
105
  private initialSyncComplete: boolean = false;
75
106
  private initialSyncPromise: PromiseWithResolvers<void>;
76
107
 
77
- /** Queue of blocks to be added to the store, processed by the sync loop. */
78
- private blockQueue: AddBlockRequest[] = [];
108
+ /** Queue of blocks and checkpoints to be added to the store, processed by the sync loop. */
109
+ private inboundQueue: (AddBlockRequest | AddProposedCheckpointRequest)[] = [];
79
110
 
80
111
  /** Helper to handle updates to the store */
81
112
  private readonly updater: ArchiverDataStoreUpdater;
@@ -83,39 +114,57 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
83
114
  /** In-memory cache for L2 chain tips. */
84
115
  private readonly l2TipsCache: L2TipsCache;
85
116
 
117
+ /** Consensus timing model used for proposed-checkpoint arrival expectations. */
118
+ private readonly timetable: ConsensusTimetable;
119
+
86
120
  public readonly tracer: Tracer;
87
121
 
122
+ private readonly instrumentation: ArchiverInstrumentation;
123
+
88
124
  /**
89
125
  * Creates a new instance of the Archiver.
90
126
  * @param publicClient - A client for interacting with the Ethereum node.
91
127
  * @param debugClient - A client for interacting with the Ethereum node for debug/trace methods.
92
128
  * @param rollup - Rollup contract instance.
129
+ * @param outbox - Outbox contract instance, used to read per-epoch L2-to-L1 message roots.
93
130
  * @param inbox - Inbox contract instance.
94
- * @param l1Addresses - L1 contract addresses (registry, governance proposer, slash factory, slashing proposer).
95
- * @param dataStore - An archiver data store for storage & retrieval of blocks, encrypted logs & contract data.
131
+ * @param l1Addresses - L1 contract addresses (registry, governance proposer, slashing proposer).
132
+ * @param dataStores - Archiver substores for storage & retrieval of blocks, encrypted logs & contract data.
96
133
  * @param config - Archiver configuration options.
97
134
  * @param blobClient - Client for retrieving blob data.
98
- * @param epochCache - Cache for epoch-related data.
99
- * @param dateProvider - Provider for current date/time.
100
135
  * @param instrumentation - Instrumentation for metrics and tracing.
101
136
  * @param l1Constants - L1 rollup constants.
137
+ * @param synchronizer - L1 synchronizer that handles fetching checkpoints and messages from L1.
138
+ * @param events - Event emitter shared with the synchronizer.
139
+ * @param initialHeader - Genesis block header.
140
+ * @param initialBlockHash - Precomputed hash of the genesis block header.
141
+ * @param l2TipsCache - In-memory cache for L2 chain tips.
142
+ * @param dateProvider - Provider for current date/time, used for wall-clock orphan-block pruning.
102
143
  * @param log - A logger.
103
144
  */
104
145
  constructor(
105
146
  private readonly publicClient: ViemPublicClient,
106
147
  private readonly debugClient: ViemPublicDebugClient,
107
148
  private readonly rollup: RollupContract,
149
+ private readonly outbox: OutboxContract,
108
150
  private readonly l1Addresses: Pick<
109
151
  L1ContractAddresses,
110
- 'registryAddress' | 'governanceProposerAddress' | 'slashFactoryAddress'
111
- > & { slashingProposerAddress: EthAddress },
112
- readonly dataStore: KVArchiverDataStore,
152
+ 'rollupAddress' | 'registryAddress' | 'inboxAddress' | 'governanceProposerAddress'
153
+ > & {
154
+ slashingProposerAddress: EthAddress;
155
+ },
156
+ readonly dataStores: ArchiverDataStores,
113
157
  private config: {
114
158
  pollingIntervalMs: number;
115
159
  batchSize: number;
116
160
  skipValidateCheckpointAttestations?: boolean;
117
161
  maxAllowedEthClientDriftSeconds: number;
118
162
  ethereumAllowNoDebugHosts?: boolean;
163
+ skipHistoricalLogsCheck?: boolean;
164
+ checkpointProposalSyncGrace: number;
165
+ orphanPruneNoProposalTolerance: number;
166
+ skipOrphanProposedBlockPruning: boolean;
167
+ blockDuration: number;
119
168
  },
120
169
  private readonly blobClient: BlobClientInterface,
121
170
  instrumentation: ArchiverInstrumentation,
@@ -125,20 +174,39 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
125
174
  },
126
175
  synchronizer: ArchiverL1Synchronizer,
127
176
  events: ArchiverEmitter,
128
- l2TipsCache?: L2TipsCache,
177
+ initialHeader: BlockHeader,
178
+ initialBlockHash: BlockHash,
179
+ l2TipsCache: L2TipsCache,
180
+ private readonly dateProvider: DateProvider,
181
+ private checkpointProposalPresence: CheckpointProposalPresence = noCheckpointProposalPresence,
129
182
  private readonly log: Logger = createLogger('archiver'),
130
183
  ) {
131
- super(dataStore, l1Constants);
184
+ super(dataStores, l1Constants, initialHeader, initialBlockHash, l1Constants.genesisArchiveRoot);
132
185
 
133
186
  this.tracer = instrumentation.tracer;
187
+ this.instrumentation = instrumentation;
134
188
  this.initialSyncPromise = promiseWithResolvers();
135
189
  this.synchronizer = synchronizer;
136
190
  this.events = events;
137
- this.l2TipsCache = l2TipsCache ?? new L2TipsCache(this.dataStore.blockStore);
138
- this.updater = new ArchiverDataStoreUpdater(this.dataStore, this.l2TipsCache, {
191
+ this.l2TipsCache = l2TipsCache;
192
+ this.timetable = new ConsensusTimetable({
193
+ l1Constants,
194
+ blockDuration: this.config.blockDuration,
195
+ checkpointProposalSyncGrace: this.config.checkpointProposalSyncGrace,
196
+ });
197
+ this.updater = new ArchiverDataStoreUpdater(this.dataStores, this.l2TipsCache, {
139
198
  rollupManaLimit: l1Constants.rollupManaLimit,
140
199
  });
141
200
 
201
+ // The resolver reads its witness data from this archiver and pins its lazy Outbox-root fetches
202
+ // to the archiver's synced L1 block. No method on `this` is invoked during construction.
203
+ this.outboxTreesResolver = new OutboxTreesResolver(
204
+ this.outbox,
205
+ this,
206
+ () => Promise.resolve(this.getL1BlockNumber()),
207
+ l1Constants.epochDuration,
208
+ );
209
+
142
210
  // Running promise starts with a small interval inbetween runs, so all iterations needed for the initial sync
143
211
  // are done as fast as possible. This then gets updated once the initial sync completes.
144
212
  this.runningPromise = new RunningPromise(
@@ -149,6 +217,27 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
149
217
  );
150
218
  }
151
219
 
220
+ /**
221
+ * Returns the L2-to-L1 membership witness for `message` emitted by tx `txHash`. The node selects
222
+ * the smallest partial-proof root on the Outbox that covers the tx's checkpoint and builds the
223
+ * witness against it.
224
+ *
225
+ * The node reads the Outbox roots lazily, pinned to its synced L1 block, so the witness reflects
226
+ * the node's synced view. Returns `undefined` if the tx isn't yet in a block/epoch or no covering
227
+ * root has landed on L1 as of the synced block.
228
+ *
229
+ * Caveat: roots are cached only for the current synced L1 block and re-fetched once the node
230
+ * advances, so a reorg is picked up on the next synced-block advance rather than re-validated per
231
+ * request.
232
+ */
233
+ public getL2ToL1MembershipWitness(
234
+ txHash: TxHash,
235
+ message: Fr,
236
+ messageIndexInTx?: number,
237
+ ): Promise<L2ToL1MembershipWitness | undefined> {
238
+ return this.outboxTreesResolver.getL2ToL1MembershipWitness(txHash, message, messageIndexInTx);
239
+ }
240
+
152
241
  /** Updates archiver config */
153
242
  public updateConfig(newConfig: Partial<ArchiverConfig>) {
154
243
  this.config = merge(this.config, mapArchiverConfig(newConfig));
@@ -171,11 +260,24 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
171
260
  this.config.ethereumAllowNoDebugHosts ?? false,
172
261
  this.log.getBindings(),
173
262
  );
263
+ await validateAndLogHistoricalLogsAvailability(
264
+ this.publicClient,
265
+ {
266
+ rollupAddress: this.l1Addresses.rollupAddress,
267
+ inboxAddress: this.l1Addresses.inboxAddress,
268
+ registryAddress: this.l1Addresses.registryAddress,
269
+ governanceProposerAddress: this.l1Addresses.governanceProposerAddress,
270
+ },
271
+ this.config.skipHistoricalLogsCheck ?? false,
272
+ this.log.getBindings(),
273
+ );
174
274
 
175
275
  // Log initial state for the archiver
176
276
  const { l1StartBlock } = this.l1Constants;
177
- const { blocksSynchedTo = l1StartBlock, messagesSynchedTo = l1StartBlock } = await this.store.getSynchPoint();
178
- const currentL2Checkpoint = await this.getSynchedCheckpointNumber();
277
+ const { blocksSynchedTo = l1StartBlock, messagesSynchedTo = l1StartBlock } = await getArchiverSynchPoint(
278
+ this.stores,
279
+ );
280
+ const currentL2Checkpoint = await this.getCheckpointNumber();
179
281
  this.log.info(
180
282
  `Starting archiver sync to rollup contract ${this.rollup.address} from L1 block ${blocksSynchedTo} and L2 checkpoint ${currentL2Checkpoint}`,
181
283
  { blocksSynchedTo, messagesSynchedTo, currentL2Checkpoint },
@@ -192,6 +294,19 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
192
294
  return this.runningPromise.trigger();
193
295
  }
194
296
 
297
+ /** Sets the proposal-presence provider used by orphan proposed-block pruning. */
298
+ public setCheckpointProposalPresence(checkpointProposalPresence: CheckpointProposalPresence): void {
299
+ this.checkpointProposalPresence = checkpointProposalPresence;
300
+ }
301
+
302
+ public trySyncImmediate() {
303
+ try {
304
+ return this.syncImmediate();
305
+ } catch (err) {
306
+ this.log.error(`Failed to trigger immediate archiver sync: ${err}`, err);
307
+ }
308
+ }
309
+
195
310
  /**
196
311
  * Queues a block to be added to the archiver store and triggers processing.
197
312
  * The block will be processed by the sync loop.
@@ -200,61 +315,92 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
200
315
  * @returns A promise that resolves when the block has been added to the store, or rejects on error.
201
316
  */
202
317
  public addBlock(block: L2Block): Promise<void> {
203
- return new Promise<void>((resolve, reject) => {
204
- this.blockQueue.push({ block, resolve, reject });
205
- this.log.debug(`Queued block ${block.number} for processing`);
206
- // Trigger an immediate sync, but don't wait for it - the promise resolves when the block is processed
207
- this.syncImmediate().catch(err => {
208
- this.log.error(`Sync immediate call failed: ${err}`);
209
- });
210
- });
318
+ const promise = promiseWithResolvers<void>();
319
+ this.inboundQueue.push({ block, ...promise, type: 'block' });
320
+ this.log.debug(`Queued block ${block.number} for processing`);
321
+ void this.trySyncImmediate();
322
+ return promise.promise;
323
+ }
324
+
325
+ /**
326
+ * Queues a new proposed checkpoint into the archiver store.
327
+ * Checks that the checkpoint is not for an L2 slot already synced from L1.
328
+ * Resolves once the checkpoint has been processed.
329
+ */
330
+ public addProposedCheckpoint(pending: ProposedCheckpointInput): Promise<void> {
331
+ const promise = promiseWithResolvers<void>();
332
+ this.inboundQueue.push({ checkpoint: pending, ...promise, type: 'checkpoint' });
333
+ this.log.debug(`Queued checkpoint ${pending.checkpointNumber} for processing`);
334
+ void this.trySyncImmediate();
335
+ return promise.promise;
211
336
  }
212
337
 
213
338
  /**
214
- * Processes all queued blocks, adding them to the store.
339
+ * Processes all queued blocks and checkpoints, adding them to the store.
215
340
  * Called at the beginning of each sync iteration.
216
- * Blocks are processed in the order they were queued.
341
+ * Items are processed in the order they were queued.
217
342
  */
218
- private async processQueuedBlocks(): Promise<void> {
219
- if (this.blockQueue.length === 0) {
220
- return;
343
+ private async processInboundQueue(): Promise<L2Block[]> {
344
+ const blocksAdded: L2Block[] = [];
345
+ if (this.inboundQueue.length === 0) {
346
+ return blocksAdded;
221
347
  }
222
348
 
223
- // Take all blocks from the queue
224
- const queuedItems = this.blockQueue.splice(0, this.blockQueue.length);
225
- this.log.debug(`Processing ${queuedItems.length} queued block(s)`);
349
+ // Take all items from the queue
350
+ const queuedItems = this.inboundQueue.splice(0, this.inboundQueue.length);
351
+ this.log.debug(`Processing ${queuedItems.length} queued inbound items`);
226
352
 
227
353
  // Calculate slot threshold for validation
228
354
  const l1Timestamp = this.synchronizer.getL1Timestamp();
229
355
  const slotAtNextL1Block =
230
356
  l1Timestamp === undefined ? undefined : getSlotAtNextL1Block(l1Timestamp, this.l1Constants);
231
357
 
232
- // Process each block individually to properly resolve/reject each promise
233
- for (const { block, resolve, reject } of queuedItems) {
234
- const blockSlot = block.header.globalVariables.slotNumber;
235
- if (slotAtNextL1Block !== undefined && blockSlot < slotAtNextL1Block) {
358
+ // Helpers for manipulating blocks and checkpoints in the queue
359
+ const getSlot: (item: AddBlockRequest | AddProposedCheckpointRequest) => SlotNumber = item =>
360
+ item.type === 'block' ? item.block.header.globalVariables.slotNumber : item.checkpoint.header.slotNumber;
361
+ const getNumber: (item: AddBlockRequest | AddProposedCheckpointRequest) => number = item =>
362
+ item.type === 'block' ? item.block.number : item.checkpoint.checkpointNumber;
363
+
364
+ // Process each item individually to properly resolve/reject each promise
365
+ for (const item of queuedItems) {
366
+ const { resolve, reject, type } = item;
367
+ const itemSlot = getSlot(item);
368
+ const itemNumber = getNumber(item);
369
+ if (slotAtNextL1Block !== undefined && itemSlot < slotAtNextL1Block) {
370
+ const nextSlotTimestamp = getTimestampForSlot(slotAtNextL1Block, this.l1Constants);
236
371
  this.log.warn(
237
- `Rejecting proposed block ${block.number} for past slot ${blockSlot} (current is ${slotAtNextL1Block})`,
238
- { block: block.toBlockInfo(), l1Timestamp, slotAtNextL1Block },
372
+ `Rejecting proposed ${type} ${itemNumber} for past slot ${itemSlot} (current ${slotAtNextL1Block})`,
373
+ { number: itemNumber, type, l1Timestamp, slotAtNextL1Block, nextSlotTimestamp },
239
374
  );
240
- reject(new Error(`Block ${block.number} is for past slot ${blockSlot} (current is ${slotAtNextL1Block})`));
375
+ reject(new BlockOrCheckpointSlotExpiredError(itemSlot, nextSlotTimestamp, l1Timestamp));
241
376
  continue;
242
377
  }
243
378
 
244
379
  try {
245
- await this.updater.addProposedBlock(block);
246
- this.log.debug(`Added block ${block.number} to store`);
380
+ if (type === 'block') {
381
+ const [durationMs] = await elapsed(() => this.updater.addProposedBlock(item.block));
382
+ this.instrumentation.processNewProposedBlock(durationMs, item.block);
383
+ blocksAdded.push(item.block);
384
+ } else {
385
+ await this.updater.addProposedCheckpoint(item.checkpoint);
386
+ }
387
+ this.log.debug(`Added ${type} ${itemNumber} to store`);
247
388
  resolve();
248
389
  } catch (err: any) {
249
390
  if (err instanceof BlockAlreadyCheckpointedError) {
250
- this.log.debug(`Proposed block ${block.number} matches already checkpointed block, ignoring late proposal`);
391
+ this.log.debug(`Proposed block ${itemNumber} matches already checkpointed block, ignoring late proposal`);
392
+ // A late proposal that matches an already-checkpointed block adds nothing new, so it is not appended.
251
393
  resolve();
252
394
  continue;
253
395
  }
254
- this.log.error(`Failed to add block ${block.number} to store: ${err.message}`);
396
+ this.log.error(`Failed to add ${type} ${itemNumber} to store: ${err.message}`, err, {
397
+ number: itemNumber,
398
+ type,
399
+ });
255
400
  reject(err);
256
401
  }
257
402
  }
403
+ return blocksAdded;
258
404
  }
259
405
 
260
406
  public waitForInitialSync() {
@@ -266,15 +412,136 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
266
412
  */
267
413
  @trackSpan('Archiver.sync')
268
414
  private async sync() {
415
+ // Capture the tips before any mutation so the aggregate event can report what moved this pass.
416
+ const fromTips = await this.getL2Tips();
417
+
418
+ // Accumulate the blocks added across the pass's sub-steps (queued proposals + L1 checkpoint payloads).
419
+ const blocksAdded: L2Block[] = [];
269
420
  // Process any queued blocks first, before doing L1 sync
270
- await this.processQueuedBlocks();
421
+ blocksAdded.push(...(await this.processInboundQueue()));
271
422
  // Now perform L1 sync
272
- await this.syncFromL1();
423
+ blocksAdded.push(...(await this.syncFromL1()));
424
+ // Prune proposed blocks with no corresponding proposed checkpoint after the appropriate materialization deadline.
425
+ await this.pruneOrphanProposedBlocks();
426
+
427
+ // Emit a single aggregate update event after all pass work has committed and the tips cache has refreshed,
428
+ // so `toTips` and the source state observed by listeners are consistent with the event payload. The pass
429
+ // mutated state if the tips moved (added blocks, a prune, or a thin tier movement) or blocks were added; a
430
+ // fully-synced no-op pass emits nothing.
431
+ const toTips = await this.getL2Tips();
432
+ if (!l2TipsEqual(fromTips, toTips) || blocksAdded.length > 0) {
433
+ this.events.emit(L2BlockSourceEvents.L2BlockSourceUpdated, {
434
+ type: L2BlockSourceEvents.L2BlockSourceUpdated,
435
+ fromTips,
436
+ toTips,
437
+ blocksAdded,
438
+ });
439
+ }
273
440
  }
274
441
 
275
- private async syncFromL1() {
442
+ /**
443
+ * Prunes a block-only local tip that was built atop a checkpoint that was never itself proposed.
444
+ *
445
+ * Under pipelining, a proposer publishes the blocks for a checkpoint (block-only proposals) before
446
+ * assembling and publishing the enclosing proposed checkpoint at the end of the build slot. A node
447
+ * that received those blocks but never the proposed checkpoint is left with an orphan tip it must not build on.
448
+ * If no checkpoint proposal was received for the orphan slot, we prune after the receive deadline plus local
449
+ * tolerance. If a checkpoint proposal was received but has not materialized into proposed archiver state,
450
+ * we prune after the consensus materialization deadline.
451
+ *
452
+ * The uncheckpointed suffix is scanned in order. Blocks covered by proposed checkpoints are left in
453
+ * place; the first block not covered by a proposed checkpoint starts the orphan suffix to prune.
454
+ */
455
+ private async pruneOrphanProposedBlocks(): Promise<void> {
456
+ if (this.config.skipOrphanProposedBlockPruning) {
457
+ return;
458
+ }
459
+ const tips = await this.getL2Tips();
460
+ const now = BigInt(this.dateProvider.nowInSeconds());
461
+
462
+ // Frontier block covered by a proposed (or, falling back, confirmed) checkpoint. Blocks beyond it
463
+ // have no enclosing checkpoint proposal and are the orphan-pruning candidates.
464
+ const proposedCheckpointBlockNumber = await this.stores.blocks.getProposedCheckpointL2BlockNumber();
465
+
466
+ // The proposed tip is a proposed-checkpointed block, so there are no orphan proposed blocks to prune
467
+ if (proposedCheckpointBlockNumber === tips.proposed.number) {
468
+ this.log.trace(`No orphan proposed blocks to prune: proposed tip ${tips.proposed.number} is checkpointed`, {
469
+ proposed: tips.proposed,
470
+ proposedCheckpointBlockNumber,
471
+ });
472
+ return;
473
+ }
474
+
475
+ // Load the blocks that are candidates for pruning (ie blocks without a proposed checkpoint covering them)
476
+ const blocksWithoutProposedCheckpoint = await this.stores.blocks.getBlocksData({
477
+ from: BlockNumber(proposedCheckpointBlockNumber + 1),
478
+ limit: tips.proposed.number - proposedCheckpointBlockNumber,
479
+ });
480
+
481
+ // Iterate through them in order, the first one with a slot that should have received a proposed checkpoint
482
+ // is the first orphan block, and all blocks after it are also orphaned and should be pruned.
483
+ let lastSlotChecked = undefined;
484
+ for (const blockData of blocksWithoutProposedCheckpoint) {
485
+ // No need to recheck if this block had the same slot as the previous one.
486
+ const blockSlot = blockData.header.getSlot();
487
+ const blockNumber = blockData.header.getBlockNumber();
488
+ if (lastSlotChecked !== undefined && blockSlot === lastSlotChecked) {
489
+ continue;
490
+ }
491
+ lastSlotChecked = blockSlot;
492
+
493
+ const hasCheckpointProposal = await this.checkpointProposalPresence.hasCheckpointProposalForSlot(blockSlot);
494
+ const deadlineType = hasCheckpointProposal ? 'checkpoint-proposal-synced' : 'checkpoint-proposal-received';
495
+ const selectedDeadline = BigInt(
496
+ hasCheckpointProposal
497
+ ? this.timetable.getCheckpointProposalSyncedDeadline(blockSlot)
498
+ : Math.ceil(
499
+ this.timetable.getCheckpointProposalReceiveDeadline(blockSlot) +
500
+ this.config.orphanPruneNoProposalTolerance,
501
+ ),
502
+ );
503
+
504
+ // If it's still not checkpointed once strictly past the selected deadline, prune it along with all blocks after
505
+ // it. A proposal may still legitimately arrive or materialize at exactly its deadline, so the tip is only
506
+ // orphaned once that instant has fully elapsed.
507
+ if (now > selectedDeadline) {
508
+ const pruneAfterBlockNumber = BlockNumber(blockNumber - 1);
509
+ this.log.warn(
510
+ `Pruning orphan blocks after block ${pruneAfterBlockNumber}: block at slot ${blockSlot} belongs to ` +
511
+ `checkpoint ${blockData.checkpointNumber} which has no matching proposed checkpoint`,
512
+ {
513
+ firstUncheckpointedBlockHeader: blockData.header.toInspect(),
514
+ blockCheckpointNumber: blockData.checkpointNumber,
515
+ blockNumber,
516
+ blockSlot,
517
+ hasCheckpointProposal,
518
+ deadlineType,
519
+ selectedDeadline,
520
+ now,
521
+ },
522
+ );
523
+
524
+ const prunedBlocks = await this.updater.removeBlocksWithoutProposedCheckpointAfter(pruneAfterBlockNumber);
525
+ if (prunedBlocks.length > 0) {
526
+ this.instrumentation.recordPrune('orphan');
527
+ this.events.emit(L2BlockSourceEvents.L2PruneUncheckpointed, {
528
+ type: L2BlockSourceEvents.L2PruneUncheckpointed,
529
+ slotNumber: blockSlot,
530
+ blocks: prunedBlocks,
531
+ });
532
+ }
533
+ return;
534
+ }
535
+ }
536
+
537
+ this.log.trace('No orphan proposed blocks to prune: all uncheckpointed blocks are still within deadline', {
538
+ blocksWithoutProposedCheckpoint: blocksWithoutProposedCheckpoint.map(b => b.header.toInspect()),
539
+ });
540
+ }
541
+
542
+ private async syncFromL1(): Promise<L2Block[]> {
276
543
  // Delegate to the L1 synchronizer
277
- await this.synchronizer.syncFromL1(this.initialSyncComplete);
544
+ const blocksAdded = await this.synchronizer.syncFromL1(this.initialSyncComplete);
278
545
 
279
546
  // Check if we've completed initial sync
280
547
  const currentL1BlockNumber = this.synchronizer.getL1BlockNumber();
@@ -283,7 +550,7 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
283
550
  if (currentL1BlockNumber + 1n >= l1BlockNumberAtEnd) {
284
551
  this.log.info(`Initial archiver sync to L1 block ${currentL1BlockNumber} complete`, {
285
552
  l1BlockNumber: currentL1BlockNumber,
286
- syncPoint: await this.store.getSynchPoint(),
553
+ syncPoint: await getArchiverSynchPoint(this.stores),
287
554
  ...(await this.getL2Tips()),
288
555
  });
289
556
  this.runningPromise.setPollingIntervalMS(this.config.pollingIntervalMs);
@@ -291,6 +558,7 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
291
558
  this.initialSyncPromise.resolve();
292
559
  }
293
560
  }
561
+ return blocksAdded;
294
562
  }
295
563
 
296
564
  /** Resumes the archiver after a stop. */
@@ -315,7 +583,7 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
315
583
  }
316
584
 
317
585
  public backupTo(destPath: string): Promise<string> {
318
- return this.dataStore.backupTo(destPath);
586
+ return backupArchiverDataStores(this.dataStores, destPath);
319
587
  }
320
588
 
321
589
  public getL1Constants(): Promise<L1RollupConstants> {
@@ -357,9 +625,9 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
357
625
  }
358
626
 
359
627
  let slotFromCheckpoint: SlotNumber | undefined;
360
- const latestCheckpointNumber = await this.store.getSynchedCheckpointNumber();
628
+ const latestCheckpointNumber = await this.stores.blocks.getLatestCheckpointNumber();
361
629
  if (latestCheckpointNumber > 0) {
362
- const checkpointData = await this.store.getCheckpointData(latestCheckpointNumber);
630
+ const checkpointData = await this.stores.blocks.getCheckpointData(latestCheckpointNumber);
363
631
  if (checkpointData) {
364
632
  slotFromCheckpoint = checkpointData.header.slotNumber;
365
633
  }
@@ -391,8 +659,7 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
391
659
  // The epoch is complete if the current checkpointed L2 block is the last one in the epoch (or later).
392
660
  // We use the checkpointed block number (synced from L1) instead of 'latest' to avoid returning true
393
661
  // prematurely when proposed blocks have been pushed to the archiver but not yet checkpointed on L1.
394
- const checkpointedBlockNumber = await this.getCheckpointedL2BlockNumber();
395
- const header = checkpointedBlockNumber > 0 ? await this.getBlockHeader(checkpointedBlockNumber) : undefined;
662
+ const header = (await this.getBlockData({ tag: 'checkpointed' }))?.header;
396
663
  const slot = header ? header.globalVariables.slotNumber : undefined;
397
664
  const [_startSlot, endSlot] = getSlotRangeForEpoch(epochNumber, this.l1Constants);
398
665
  if (slot && slot >= endSlot) {
@@ -427,6 +694,15 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
427
694
  return this.updater.removeCheckpointsAfter(checkpointNumber);
428
695
  }
429
696
 
697
+ /**
698
+ * Removes all uncheckpointed blocks strictly after `blockNumber`, along with the proposed checkpoints
699
+ * that referenced them. Used by the AutomineSequencer to undo a local insert whose propose tx failed
700
+ * to land on L1 (no reorg needed — nothing reached L1). Refuses to touch checkpointed blocks.
701
+ */
702
+ public removeUncheckpointedBlocksAfter(blockNumber: BlockNumber): Promise<L2Block[]> {
703
+ return this.updater.removeUncheckpointedBlocksAfter(blockNumber);
704
+ }
705
+
430
706
  /** Used by TXE to add checkpoints directly without syncing from L1. */
431
707
  public async addCheckpoints(
432
708
  checkpoints: PublishedCheckpoint[],
@@ -448,29 +724,34 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
448
724
  if (targetL2BlockNumber >= currentL2Block) {
449
725
  throw new Error(`Target L2 block ${targetL2BlockNumber} must be less than current L2 block ${currentL2Block}`);
450
726
  }
451
- const targetL2Block = await this.store.getCheckpointedBlock(targetL2BlockNumber);
452
- if (!targetL2Block) {
727
+ const checkpointedTip = await this.stores.blocks.getCheckpointedL2BlockNumber();
728
+ if (targetL2BlockNumber > checkpointedTip) {
729
+ throw new Error(`Target L2 block ${targetL2BlockNumber} is not checkpointed yet`);
730
+ }
731
+ const targetBlockData = await this.stores.blocks.getBlockData({ number: targetL2BlockNumber });
732
+ if (!targetBlockData) {
453
733
  throw new Error(`Target L2 block ${targetL2BlockNumber} not found`);
454
734
  }
455
- const targetCheckpointNumber = targetL2Block.checkpointNumber;
735
+ const targetCheckpointNumber = targetBlockData.checkpointNumber;
456
736
 
457
737
  // Rollback operates at checkpoint granularity: the target block must be the last block of its checkpoint.
458
- const checkpointData = await this.store.getCheckpointData(targetCheckpointNumber);
459
- if (checkpointData) {
460
- const lastBlockInCheckpoint = BlockNumber(checkpointData.startBlock + checkpointData.blockCount - 1);
461
- if (targetL2BlockNumber !== lastBlockInCheckpoint) {
462
- const previousCheckpointBoundary =
463
- checkpointData.startBlock > 1 ? BlockNumber(checkpointData.startBlock - 1) : BlockNumber(0);
464
- throw new Error(
465
- `Target L2 block ${targetL2BlockNumber} is not at a checkpoint boundary. ` +
466
- `Checkpoint ${targetCheckpointNumber} spans blocks ${checkpointData.startBlock} to ${lastBlockInCheckpoint}. ` +
467
- `Use block ${lastBlockInCheckpoint} to roll back to this checkpoint, ` +
468
- `or block ${previousCheckpointBoundary} to roll back to the previous one.`,
469
- );
470
- }
738
+ const checkpointData = await this.stores.blocks.getCheckpointData(targetCheckpointNumber);
739
+ if (!checkpointData) {
740
+ throw new Error(`Checkpoint ${targetCheckpointNumber} not found for block ${targetL2BlockNumber}`);
741
+ }
742
+ const lastBlockInCheckpoint = BlockNumber(checkpointData.startBlock + checkpointData.blockCount - 1);
743
+ if (targetL2BlockNumber !== lastBlockInCheckpoint) {
744
+ const previousCheckpointBoundary =
745
+ checkpointData.startBlock > 1 ? BlockNumber(checkpointData.startBlock - 1) : BlockNumber(0);
746
+ throw new Error(
747
+ `Target L2 block ${targetL2BlockNumber} is not at a checkpoint boundary. ` +
748
+ `Checkpoint ${targetCheckpointNumber} spans blocks ${checkpointData.startBlock} to ${lastBlockInCheckpoint}. ` +
749
+ `Use block ${lastBlockInCheckpoint} to roll back to this checkpoint, ` +
750
+ `or block ${previousCheckpointBoundary} to roll back to the previous one.`,
751
+ );
471
752
  }
472
753
 
473
- const targetL1BlockNumber = targetL2Block.l1.blockNumber;
754
+ const targetL1BlockNumber = checkpointData.l1.blockNumber;
474
755
  const targetL1Block = await this.publicClient.getBlock({
475
756
  blockNumber: targetL1BlockNumber,
476
757
  includeTransactions: false,
@@ -484,10 +765,13 @@ export class Archiver extends ArchiverDataSourceBase implements L2BlockSink, Tra
484
765
  );
485
766
  await this.updater.removeCheckpointsAfter(targetCheckpointNumber);
486
767
  this.log.info(`Rolling back L1 to L2 messages to checkpoint ${targetCheckpointNumber}`);
487
- await this.store.rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber);
768
+ await this.stores.messages.rollbackL1ToL2MessagesToCheckpoint(targetCheckpointNumber);
488
769
  this.log.info(`Setting L1 syncpoints to ${targetL1BlockNumber}`);
489
- await this.store.setCheckpointSynchedL1BlockNumber(targetL1BlockNumber);
490
- await this.store.setMessageSynchedL1Block({ l1BlockNumber: targetL1BlockNumber, l1BlockHash: targetL1BlockHash });
770
+ await this.stores.blocks.setSynchedL1BlockNumber(targetL1BlockNumber);
771
+ await this.stores.messages.setMessageSyncState(
772
+ { l1BlockNumber: targetL1BlockNumber, l1BlockHash: targetL1BlockHash },
773
+ undefined,
774
+ );
491
775
  if (targetL2BlockNumber < currentProvenBlock) {
492
776
  this.log.info(`Rolling back proven L2 checkpoint to ${targetCheckpointNumber}`);
493
777
  await this.updater.setProvenCheckpointNumber(targetCheckpointNumber);