@aztec/validator-client 3.0.3-rc.3 → 3.9.9-nightly.20260312

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 (57) hide show
  1. package/README.md +328 -0
  2. package/dest/block_proposal_handler.d.ts +23 -12
  3. package/dest/block_proposal_handler.d.ts.map +1 -1
  4. package/dest/block_proposal_handler.js +423 -107
  5. package/dest/checkpoint_builder.d.ts +76 -0
  6. package/dest/checkpoint_builder.d.ts.map +1 -0
  7. package/dest/checkpoint_builder.js +237 -0
  8. package/dest/config.d.ts +1 -1
  9. package/dest/config.d.ts.map +1 -1
  10. package/dest/config.js +36 -8
  11. package/dest/duties/validation_service.d.ts +41 -12
  12. package/dest/duties/validation_service.d.ts.map +1 -1
  13. package/dest/duties/validation_service.js +103 -26
  14. package/dest/factory.d.ts +13 -8
  15. package/dest/factory.d.ts.map +1 -1
  16. package/dest/factory.js +4 -3
  17. package/dest/index.d.ts +2 -1
  18. package/dest/index.d.ts.map +1 -1
  19. package/dest/index.js +1 -0
  20. package/dest/key_store/ha_key_store.d.ts +99 -0
  21. package/dest/key_store/ha_key_store.d.ts.map +1 -0
  22. package/dest/key_store/ha_key_store.js +208 -0
  23. package/dest/key_store/index.d.ts +2 -1
  24. package/dest/key_store/index.d.ts.map +1 -1
  25. package/dest/key_store/index.js +1 -0
  26. package/dest/key_store/interface.d.ts +36 -6
  27. package/dest/key_store/interface.d.ts.map +1 -1
  28. package/dest/key_store/local_key_store.d.ts +10 -5
  29. package/dest/key_store/local_key_store.d.ts.map +1 -1
  30. package/dest/key_store/local_key_store.js +8 -4
  31. package/dest/key_store/node_keystore_adapter.d.ts +18 -5
  32. package/dest/key_store/node_keystore_adapter.d.ts.map +1 -1
  33. package/dest/key_store/node_keystore_adapter.js +18 -4
  34. package/dest/key_store/web3signer_key_store.d.ts +10 -5
  35. package/dest/key_store/web3signer_key_store.d.ts.map +1 -1
  36. package/dest/key_store/web3signer_key_store.js +8 -4
  37. package/dest/metrics.d.ts +12 -3
  38. package/dest/metrics.d.ts.map +1 -1
  39. package/dest/metrics.js +46 -30
  40. package/dest/validator.d.ts +75 -21
  41. package/dest/validator.d.ts.map +1 -1
  42. package/dest/validator.js +478 -57
  43. package/package.json +21 -11
  44. package/src/block_proposal_handler.ts +355 -77
  45. package/src/checkpoint_builder.ts +398 -0
  46. package/src/config.ts +35 -7
  47. package/src/duties/validation_service.ts +154 -31
  48. package/src/factory.ts +18 -8
  49. package/src/index.ts +1 -0
  50. package/src/key_store/ha_key_store.ts +269 -0
  51. package/src/key_store/index.ts +1 -0
  52. package/src/key_store/interface.ts +44 -5
  53. package/src/key_store/local_key_store.ts +13 -4
  54. package/src/key_store/node_keystore_adapter.ts +27 -4
  55. package/src/key_store/web3signer_key_store.ts +17 -4
  56. package/src/metrics.ts +63 -33
  57. package/src/validator.ts +648 -85
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aztec/validator-client",
3
- "version": "3.0.3-rc.3",
3
+ "version": "3.9.9-nightly.20260312",
4
4
  "main": "dest/index.js",
5
5
  "type": "module",
6
6
  "exports": {
@@ -64,25 +64,35 @@
64
64
  ]
65
65
  },
66
66
  "dependencies": {
67
- "@aztec/constants": "3.0.3-rc.3",
68
- "@aztec/epoch-cache": "3.0.3-rc.3",
69
- "@aztec/ethereum": "3.0.3-rc.3",
70
- "@aztec/foundation": "3.0.3-rc.3",
71
- "@aztec/node-keystore": "3.0.3-rc.3",
72
- "@aztec/p2p": "3.0.3-rc.3",
73
- "@aztec/slasher": "3.0.3-rc.3",
74
- "@aztec/stdlib": "3.0.3-rc.3",
75
- "@aztec/telemetry-client": "3.0.3-rc.3",
67
+ "@aztec/blob-client": "3.9.9-nightly.20260312",
68
+ "@aztec/blob-lib": "3.9.9-nightly.20260312",
69
+ "@aztec/constants": "3.9.9-nightly.20260312",
70
+ "@aztec/epoch-cache": "3.9.9-nightly.20260312",
71
+ "@aztec/ethereum": "3.9.9-nightly.20260312",
72
+ "@aztec/foundation": "3.9.9-nightly.20260312",
73
+ "@aztec/node-keystore": "3.9.9-nightly.20260312",
74
+ "@aztec/noir-protocol-circuits-types": "3.9.9-nightly.20260312",
75
+ "@aztec/p2p": "3.9.9-nightly.20260312",
76
+ "@aztec/protocol-contracts": "3.9.9-nightly.20260312",
77
+ "@aztec/prover-client": "3.9.9-nightly.20260312",
78
+ "@aztec/simulator": "3.9.9-nightly.20260312",
79
+ "@aztec/slasher": "3.9.9-nightly.20260312",
80
+ "@aztec/stdlib": "3.9.9-nightly.20260312",
81
+ "@aztec/telemetry-client": "3.9.9-nightly.20260312",
82
+ "@aztec/validator-ha-signer": "3.9.9-nightly.20260312",
76
83
  "koa": "^2.16.1",
77
84
  "koa-router": "^13.1.1",
78
85
  "tslib": "^2.4.0",
79
86
  "viem": "npm:@aztec/viem@2.38.2"
80
87
  },
81
88
  "devDependencies": {
89
+ "@aztec/archiver": "3.9.9-nightly.20260312",
90
+ "@aztec/world-state": "3.9.9-nightly.20260312",
91
+ "@electric-sql/pglite": "^0.3.14",
82
92
  "@jest/globals": "^30.0.0",
83
93
  "@types/jest": "^30.0.0",
84
94
  "@types/node": "^22.15.17",
85
- "@typescript/native-preview": "7.0.0-dev.20251126.1",
95
+ "@typescript/native-preview": "7.0.0-dev.20260113.1",
86
96
  "jest": "^30.0.0",
87
97
  "jest-mock-extended": "^4.0.0",
88
98
  "ts-node": "^10.9.1",
@@ -1,38 +1,46 @@
1
1
  import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
2
+ import type { EpochCache } from '@aztec/epoch-cache';
2
3
  import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
4
+ import { pick } from '@aztec/foundation/collection';
3
5
  import { Fr } from '@aztec/foundation/curves/bn254';
4
6
  import { TimeoutError } from '@aztec/foundation/error';
5
7
  import { createLogger } from '@aztec/foundation/log';
6
8
  import { retryUntil } from '@aztec/foundation/retry';
7
9
  import { DateProvider, Timer } from '@aztec/foundation/timer';
8
10
  import type { P2P, PeerId } from '@aztec/p2p';
9
- import { TxProvider } from '@aztec/p2p';
10
11
  import { BlockProposalValidator } from '@aztec/p2p/msg_validators';
11
- import type { L2Block, L2BlockSource } from '@aztec/stdlib/block';
12
- import { getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
13
- import type { IFullNodeBlockBuilder, ValidatorClientFullConfig } from '@aztec/stdlib/interfaces/server';
12
+ import type { BlockData, L2Block, L2BlockSink, L2BlockSource } from '@aztec/stdlib/block';
13
+ import { getEpochAtSlot, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
14
+ import { Gas } from '@aztec/stdlib/gas';
15
+ import type { ITxProvider, ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
14
16
  import { type L1ToL2MessageSource, computeInHashFromL1ToL2Messages } from '@aztec/stdlib/messaging';
15
- import { type BlockProposal, ConsensusPayload } from '@aztec/stdlib/p2p';
16
- import { BlockHeader, type FailedTx, GlobalVariables, type Tx } from '@aztec/stdlib/tx';
17
+ import type { BlockProposal } from '@aztec/stdlib/p2p';
18
+ import { MerkleTreeId } from '@aztec/stdlib/trees';
19
+ import type { CheckpointGlobalVariables, FailedTx, Tx } from '@aztec/stdlib/tx';
17
20
  import {
18
21
  ReExFailedTxsError,
22
+ ReExInitialStateMismatchError,
19
23
  ReExStateMismatchError,
20
24
  ReExTimeoutError,
21
25
  TransactionsNotAvailableError,
22
26
  } from '@aztec/stdlib/validators';
23
27
  import { type TelemetryClient, type Tracer, getTelemetryClient } from '@aztec/telemetry-client';
24
28
 
29
+ import type { FullNodeCheckpointsBuilder } from './checkpoint_builder.js';
25
30
  import type { ValidatorMetrics } from './metrics.js';
26
31
 
27
32
  export type BlockProposalValidationFailureReason =
28
33
  | 'invalid_proposal'
29
34
  | 'parent_block_not_found'
35
+ | 'block_source_not_synced'
30
36
  | 'parent_block_wrong_slot'
31
37
  | 'in_hash_mismatch'
38
+ | 'global_variables_mismatch'
32
39
  | 'block_number_already_exists'
33
40
  | 'txs_not_available'
34
41
  | 'state_mismatch'
35
42
  | 'failed_txs'
43
+ | 'initial_state_mismatch'
36
44
  | 'timeout'
37
45
  | 'unknown_error';
38
46
 
@@ -58,15 +66,21 @@ export type BlockProposalValidationFailureResult = {
58
66
 
59
67
  export type BlockProposalValidationResult = BlockProposalValidationSuccessResult | BlockProposalValidationFailureResult;
60
68
 
69
+ type CheckpointComputationResult =
70
+ | { checkpointNumber: CheckpointNumber; reason?: undefined }
71
+ | { checkpointNumber?: undefined; reason: 'invalid_proposal' | 'global_variables_mismatch' };
72
+
61
73
  export class BlockProposalHandler {
62
74
  public readonly tracer: Tracer;
63
75
 
64
76
  constructor(
65
- private blockBuilder: IFullNodeBlockBuilder,
66
- private blockSource: L2BlockSource,
77
+ private checkpointsBuilder: FullNodeCheckpointsBuilder,
78
+ private worldState: WorldStateSynchronizer,
79
+ private blockSource: L2BlockSource & L2BlockSink,
67
80
  private l1ToL2MessageSource: L1ToL2MessageSource,
68
- private txProvider: TxProvider,
81
+ private txProvider: ITxProvider,
69
82
  private blockProposalValidator: BlockProposalValidator,
83
+ private epochCache: EpochCache,
70
84
  private config: ValidatorClientFullConfig,
71
85
  private metrics?: ValidatorMetrics,
72
86
  private dateProvider: DateProvider = new DateProvider(),
@@ -79,27 +93,34 @@ export class BlockProposalHandler {
79
93
  this.tracer = telemetry.getTracer('BlockProposalHandler');
80
94
  }
81
95
 
82
- registerForReexecution(p2pClient: P2P): BlockProposalHandler {
83
- const handler = async (proposal: BlockProposal, proposalSender: PeerId) => {
96
+ register(p2pClient: P2P, shouldReexecute: boolean): BlockProposalHandler {
97
+ // Non-validator handler that processes or re-executes for monitoring but does not attest.
98
+ // Returns boolean indicating whether the proposal was valid.
99
+ const handler = async (proposal: BlockProposal, proposalSender: PeerId): Promise<boolean> => {
84
100
  try {
85
- const result = await this.handleBlockProposal(proposal, proposalSender, true);
101
+ const { slotNumber, blockNumber } = proposal;
102
+ const result = await this.handleBlockProposal(proposal, proposalSender, shouldReexecute);
86
103
  if (result.isValid) {
87
- this.log.info(`Non-validator reexecution completed for slot ${proposal.slotNumber}`, {
104
+ this.log.info(`Non-validator block proposal ${blockNumber} at slot ${slotNumber} handled`, {
88
105
  blockNumber: result.blockNumber,
106
+ slotNumber,
89
107
  reexecutionTimeMs: result.reexecutionResult?.reexecutionTimeMs,
90
108
  totalManaUsed: result.reexecutionResult?.totalManaUsed,
91
109
  numTxs: result.reexecutionResult?.block?.body?.txEffects?.length ?? 0,
110
+ reexecuted: shouldReexecute,
92
111
  });
112
+ return true;
93
113
  } else {
94
- this.log.warn(`Non-validator reexecution failed for slot ${proposal.slotNumber}`, {
95
- blockNumber: result.blockNumber,
96
- reason: result.reason,
97
- });
114
+ this.log.warn(
115
+ `Non-validator block proposal ${blockNumber} at slot ${slotNumber} failed processing with ${result.reason}`,
116
+ { blockNumber: result.blockNumber, slotNumber, reason: result.reason },
117
+ );
118
+ return false;
98
119
  }
99
120
  } catch (error) {
100
121
  this.log.error('Error processing block proposal in non-validator handler', error);
122
+ return false;
101
123
  }
102
- return undefined; // Non-validator nodes don't return attestations
103
124
  };
104
125
 
105
126
  p2pClient.registerBlockProposalHandler(handler);
@@ -113,7 +134,7 @@ export class BlockProposalHandler {
113
134
  ): Promise<BlockProposalValidationResult> {
114
135
  const slotNumber = proposal.slotNumber;
115
136
  const proposer = proposal.getSender();
116
- const config = this.blockBuilder.getConfig();
137
+ const config = this.checkpointsBuilder.getConfig();
117
138
 
118
139
  // Reject proposals with invalid signatures
119
140
  if (!proposer) {
@@ -121,7 +142,13 @@ export class BlockProposalHandler {
121
142
  return { isValid: false, reason: 'invalid_proposal' };
122
143
  }
123
144
 
124
- const proposalInfo = { ...proposal.toBlockInfo(), proposer: proposer.toString() };
145
+ const proposalInfo = {
146
+ ...proposal.toBlockInfo(),
147
+ proposer: proposer.toString(),
148
+ blockNumber: undefined as BlockNumber | undefined,
149
+ checkpointNumber: undefined as CheckpointNumber | undefined,
150
+ };
151
+
125
152
  this.log.info(`Processing proposal for slot ${slotNumber}`, {
126
153
  ...proposalInfo,
127
154
  txHashes: proposal.txHashes.map(t => t.toString()),
@@ -129,23 +156,36 @@ export class BlockProposalHandler {
129
156
 
130
157
  // Check that the proposal is from the current proposer, or the next proposer
131
158
  // This should have been handled by the p2p layer, but we double check here out of caution
132
- const invalidProposal = await this.blockProposalValidator.validate(proposal);
133
- if (invalidProposal) {
159
+ const validationResult = await this.blockProposalValidator.validate(proposal);
160
+ if (validationResult.result !== 'accept') {
134
161
  this.log.warn(`Proposal is not valid, skipping processing`, proposalInfo);
135
162
  return { isValid: false, reason: 'invalid_proposal' };
136
163
  }
137
164
 
138
- // Check that the parent proposal is a block we know, otherwise reexecution would fail
139
- const parentBlockHeader = await this.getParentBlock(proposal);
140
- if (parentBlockHeader === undefined) {
165
+ // Ensure the block source is synced before checking for existing blocks,
166
+ // since a pending checkpoint prune may remove blocks we'd otherwise find.
167
+ // This affects mostly the block_number_already_exists check, since a pending
168
+ // checkpoint prune could remove a block that would conflict with this proposal.
169
+ // TODO(@Maddiaa0): This may break staggered slots.
170
+ const blockSourceSync = await this.waitForBlockSourceSync(slotNumber);
171
+ if (!blockSourceSync) {
172
+ this.log.warn(`Block source is not synced, skipping processing`, proposalInfo);
173
+ return { isValid: false, reason: 'block_source_not_synced' };
174
+ }
175
+
176
+ // Check that the parent proposal is a block we know, otherwise reexecution would fail.
177
+ // If we don't find it immediately, we keep retrying for a while; it may be we still
178
+ // need to process other block proposals to get to it.
179
+ const parentBlock = await this.getParentBlock(proposal);
180
+ if (parentBlock === undefined) {
141
181
  this.log.warn(`Parent block for proposal not found, skipping processing`, proposalInfo);
142
182
  return { isValid: false, reason: 'parent_block_not_found' };
143
183
  }
144
184
 
145
- // Check that the parent block's slot is less than the proposal's slot (should not happen, but we check anyway)
146
- if (parentBlockHeader !== 'genesis' && parentBlockHeader.getSlot() >= slotNumber) {
147
- this.log.warn(`Parent block slot is greater than or equal to proposal slot, skipping processing`, {
148
- parentBlockSlot: parentBlockHeader.getSlot().toString(),
185
+ // Check that the parent block's slot is not greater than the proposal's slot.
186
+ if (parentBlock !== 'genesis' && parentBlock.header.getSlot() > slotNumber) {
187
+ this.log.warn(`Parent block slot is greater than proposal slot, skipping processing`, {
188
+ parentBlockSlot: parentBlock.header.getSlot().toString(),
149
189
  proposalSlot: slotNumber.toString(),
150
190
  ...proposalInfo,
151
191
  });
@@ -154,9 +194,10 @@ export class BlockProposalHandler {
154
194
 
155
195
  // Compute the block number based on the parent block
156
196
  const blockNumber =
157
- parentBlockHeader === 'genesis'
197
+ parentBlock === 'genesis'
158
198
  ? BlockNumber(INITIAL_L2_BLOCK_NUM)
159
- : BlockNumber(parentBlockHeader.getBlockNumber() + 1);
199
+ : BlockNumber(parentBlock.header.getBlockNumber() + 1);
200
+ proposalInfo.blockNumber = blockNumber;
160
201
 
161
202
  // Check that this block number does not exist already
162
203
  const existingBlock = await this.blockSource.getBlockHeader(blockNumber);
@@ -172,12 +213,27 @@ export class BlockProposalHandler {
172
213
  deadline: this.getReexecutionDeadline(slotNumber, config),
173
214
  });
174
215
 
216
+ // If reexecution is disabled, bail. We were just interested in triggering tx collection.
217
+ if (!shouldReexecute) {
218
+ this.log.info(
219
+ `Received valid block ${blockNumber} proposal at index ${proposal.indexWithinCheckpoint} on slot ${slotNumber}`,
220
+ proposalInfo,
221
+ );
222
+ return { isValid: true, blockNumber };
223
+ }
224
+
225
+ // Compute the checkpoint number for this block and validate checkpoint consistency
226
+ const checkpointResult = this.computeCheckpointNumber(proposal, parentBlock, proposalInfo);
227
+ if (checkpointResult.reason) {
228
+ return { isValid: false, blockNumber, reason: checkpointResult.reason };
229
+ }
230
+ const checkpointNumber = checkpointResult.checkpointNumber;
231
+ proposalInfo.checkpointNumber = checkpointNumber;
232
+
175
233
  // Check that I have the same set of l1ToL2Messages as the proposal
176
- const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(
177
- CheckpointNumber.fromBlockNumber(blockNumber),
178
- );
234
+ const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(checkpointNumber);
179
235
  const computedInHash = computeInHashFromL1ToL2Messages(l1ToL2Messages);
180
- const proposalInHash = proposal.payload.header.contentCommitment.inHash;
236
+ const proposalInHash = proposal.inHash;
181
237
  if (!computedInHash.equals(proposalInHash)) {
182
238
  this.log.warn(`L1 to L2 messages in hash mismatch, skipping processing`, {
183
239
  proposalInHash: proposalInHash.toString(),
@@ -193,27 +249,47 @@ export class BlockProposalHandler {
193
249
  return { isValid: false, blockNumber, reason: 'txs_not_available' };
194
250
  }
195
251
 
252
+ // Collect the out hashes of all the checkpoints before this one in the same epoch
253
+ const epoch = getEpochAtSlot(slotNumber, this.epochCache.getL1Constants());
254
+ const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
255
+ .filter(c => c.checkpointNumber < checkpointNumber)
256
+ .map(c => c.checkpointOutHash);
257
+
196
258
  // Try re-executing the transactions in the proposal if needed
197
259
  let reexecutionResult;
198
- if (shouldReexecute) {
199
- try {
200
- this.log.verbose(`Re-executing transactions in the proposal`, proposalInfo);
201
- reexecutionResult = await this.reexecuteTransactions(proposal, blockNumber, txs, l1ToL2Messages);
202
- } catch (error) {
203
- this.log.error(`Error reexecuting txs while processing block proposal`, error, proposalInfo);
204
- const reason = this.getReexecuteFailureReason(error);
205
- return { isValid: false, blockNumber, reason, reexecutionResult };
206
- }
260
+ try {
261
+ this.log.verbose(`Re-executing transactions in the proposal`, proposalInfo);
262
+ reexecutionResult = await this.reexecuteTransactions(
263
+ proposal,
264
+ blockNumber,
265
+ checkpointNumber,
266
+ txs,
267
+ l1ToL2Messages,
268
+ previousCheckpointOutHashes,
269
+ );
270
+ } catch (error) {
271
+ this.log.error(`Error reexecuting txs while processing block proposal`, error, proposalInfo);
272
+ const reason = this.getReexecuteFailureReason(error);
273
+ return { isValid: false, blockNumber, reason, reexecutionResult };
274
+ }
275
+
276
+ // If we succeeded, push this block into the archiver (unless disabled)
277
+ if (reexecutionResult?.block && this.config.skipPushProposedBlocksToArchiver === false) {
278
+ await this.blockSource.addBlock(reexecutionResult?.block);
207
279
  }
208
280
 
209
- this.log.info(`Successfully processed proposal for slot ${slotNumber}`, proposalInfo);
281
+ this.log.info(
282
+ `Successfully re-executed block ${blockNumber} proposal at index ${proposal.indexWithinCheckpoint} on slot ${slotNumber}`,
283
+ { ...proposalInfo, ...pick(reexecutionResult, 'reexecutionTimeMs', 'totalManaUsed') },
284
+ );
285
+
210
286
  return { isValid: true, blockNumber, reexecutionResult };
211
287
  }
212
288
 
213
- private async getParentBlock(proposal: BlockProposal): Promise<'genesis' | BlockHeader | undefined> {
214
- const parentArchive = proposal.payload.header.lastArchiveRoot;
289
+ private async getParentBlock(proposal: BlockProposal): Promise<'genesis' | BlockData | undefined> {
290
+ const parentArchive = proposal.blockHeader.lastArchive.root;
215
291
  const slot = proposal.slotNumber;
216
- const config = this.blockBuilder.getConfig();
292
+ const config = this.checkpointsBuilder.getConfig();
217
293
  const { genesisArchiveRoot } = await this.blockSource.getGenesisValues();
218
294
 
219
295
  if (parentArchive.equals(genesisArchiveRoot)) {
@@ -226,12 +302,11 @@ export class BlockProposalHandler {
226
302
 
227
303
  try {
228
304
  return (
229
- (await this.blockSource.getBlockHeaderByArchive(parentArchive)) ??
305
+ (await this.blockSource.getBlockDataByArchive(parentArchive)) ??
230
306
  (timeoutDurationMs <= 0
231
307
  ? undefined
232
308
  : await retryUntil(
233
- () =>
234
- this.blockSource.syncImmediate().then(() => this.blockSource.getBlockHeaderByArchive(parentArchive)),
309
+ () => this.blockSource.syncImmediate().then(() => this.blockSource.getBlockDataByArchive(parentArchive)),
235
310
  'force archiver sync',
236
311
  timeoutDurationMs / 1000,
237
312
  0.5,
@@ -247,14 +322,174 @@ export class BlockProposalHandler {
247
322
  }
248
323
  }
249
324
 
325
+ private computeCheckpointNumber(
326
+ proposal: BlockProposal,
327
+ parentBlock: 'genesis' | BlockData,
328
+ proposalInfo: object,
329
+ ): CheckpointComputationResult {
330
+ if (parentBlock === 'genesis') {
331
+ // First block is in checkpoint 1
332
+ if (proposal.indexWithinCheckpoint !== 0) {
333
+ this.log.warn(`First block proposal has non-zero indexWithinCheckpoint`, proposalInfo);
334
+ return { reason: 'invalid_proposal' };
335
+ }
336
+ return { checkpointNumber: CheckpointNumber.INITIAL };
337
+ }
338
+
339
+ if (proposal.indexWithinCheckpoint === 0) {
340
+ // If this is the first block in a new checkpoint, increment the checkpoint number
341
+ if (!(proposal.blockHeader.getSlot() > parentBlock.header.getSlot())) {
342
+ this.log.warn(`Slot should be greater than parent block slot for first block in checkpoint`, proposalInfo);
343
+ return { reason: 'invalid_proposal' };
344
+ }
345
+ return { checkpointNumber: CheckpointNumber(parentBlock.checkpointNumber + 1) };
346
+ }
347
+
348
+ // Otherwise it should follow the previous block in the same checkpoint
349
+ if (proposal.indexWithinCheckpoint !== parentBlock.indexWithinCheckpoint + 1) {
350
+ this.log.warn(`Non-sequential indexWithinCheckpoint`, proposalInfo);
351
+ return { reason: 'invalid_proposal' };
352
+ }
353
+ if (proposal.blockHeader.getSlot() !== parentBlock.header.getSlot()) {
354
+ this.log.warn(`Slot should be equal to parent block slot for non-first block in checkpoint`, proposalInfo);
355
+ return { reason: 'invalid_proposal' };
356
+ }
357
+
358
+ // For non-first blocks in a checkpoint, validate global variables match parent (except blockNumber)
359
+ const validationResult = this.validateNonFirstBlockInCheckpoint(proposal, parentBlock, proposalInfo);
360
+ if (validationResult) {
361
+ return validationResult;
362
+ }
363
+
364
+ return { checkpointNumber: parentBlock.checkpointNumber };
365
+ }
366
+
367
+ /**
368
+ * Validates that a non-first block in a checkpoint has consistent global variables with its parent.
369
+ * For blocks with indexWithinCheckpoint > 0, all global variables except blockNumber must match the parent.
370
+ * @returns A failure result if validation fails, undefined if validation passes
371
+ */
372
+ private validateNonFirstBlockInCheckpoint(
373
+ proposal: BlockProposal,
374
+ parentBlock: BlockData,
375
+ proposalInfo: object,
376
+ ): CheckpointComputationResult | undefined {
377
+ const proposalGlobals = proposal.blockHeader.globalVariables;
378
+ const parentGlobals = parentBlock.header.globalVariables;
379
+
380
+ // All global variables except blockNumber should match the parent
381
+ // blockNumber naturally increments between blocks
382
+ if (!proposalGlobals.chainId.equals(parentGlobals.chainId)) {
383
+ this.log.warn(`Non-first block in checkpoint has mismatched chainId`, {
384
+ ...proposalInfo,
385
+ proposalChainId: proposalGlobals.chainId.toString(),
386
+ parentChainId: parentGlobals.chainId.toString(),
387
+ });
388
+ return { reason: 'global_variables_mismatch' };
389
+ }
390
+
391
+ if (!proposalGlobals.version.equals(parentGlobals.version)) {
392
+ this.log.warn(`Non-first block in checkpoint has mismatched version`, {
393
+ ...proposalInfo,
394
+ proposalVersion: proposalGlobals.version.toString(),
395
+ parentVersion: parentGlobals.version.toString(),
396
+ });
397
+ return { reason: 'global_variables_mismatch' };
398
+ }
399
+
400
+ if (proposalGlobals.slotNumber !== parentGlobals.slotNumber) {
401
+ this.log.warn(`Non-first block in checkpoint has mismatched slotNumber`, {
402
+ ...proposalInfo,
403
+ proposalSlotNumber: proposalGlobals.slotNumber,
404
+ parentSlotNumber: parentGlobals.slotNumber,
405
+ });
406
+ return { reason: 'global_variables_mismatch' };
407
+ }
408
+
409
+ if (proposalGlobals.timestamp !== parentGlobals.timestamp) {
410
+ this.log.warn(`Non-first block in checkpoint has mismatched timestamp`, {
411
+ ...proposalInfo,
412
+ proposalTimestamp: proposalGlobals.timestamp.toString(),
413
+ parentTimestamp: parentGlobals.timestamp.toString(),
414
+ });
415
+ return { reason: 'global_variables_mismatch' };
416
+ }
417
+
418
+ if (!proposalGlobals.coinbase.equals(parentGlobals.coinbase)) {
419
+ this.log.warn(`Non-first block in checkpoint has mismatched coinbase`, {
420
+ ...proposalInfo,
421
+ proposalCoinbase: proposalGlobals.coinbase.toString(),
422
+ parentCoinbase: parentGlobals.coinbase.toString(),
423
+ });
424
+ return { reason: 'global_variables_mismatch' };
425
+ }
426
+
427
+ if (!proposalGlobals.feeRecipient.equals(parentGlobals.feeRecipient)) {
428
+ this.log.warn(`Non-first block in checkpoint has mismatched feeRecipient`, {
429
+ ...proposalInfo,
430
+ proposalFeeRecipient: proposalGlobals.feeRecipient.toString(),
431
+ parentFeeRecipient: parentGlobals.feeRecipient.toString(),
432
+ });
433
+ return { reason: 'global_variables_mismatch' };
434
+ }
435
+
436
+ if (!proposalGlobals.gasFees.equals(parentGlobals.gasFees)) {
437
+ this.log.warn(`Non-first block in checkpoint has mismatched gasFees`, {
438
+ ...proposalInfo,
439
+ proposalGasFees: proposalGlobals.gasFees.toInspect(),
440
+ parentGasFees: parentGlobals.gasFees.toInspect(),
441
+ });
442
+ return { reason: 'global_variables_mismatch' };
443
+ }
444
+
445
+ return undefined;
446
+ }
447
+
250
448
  private getReexecutionDeadline(slot: SlotNumber, config: { l1GenesisTime: bigint; slotDuration: number }): Date {
251
449
  const nextSlotTimestampSeconds = Number(getTimestampForSlot(SlotNumber(slot + 1), config));
252
- const msNeededForPropagationAndPublishing = this.config.validatorReexecuteDeadlineMs;
253
- return new Date(nextSlotTimestampSeconds * 1000 - msNeededForPropagationAndPublishing);
450
+ return new Date(nextSlotTimestampSeconds * 1000);
254
451
  }
255
452
 
256
- private getReexecuteFailureReason(err: any) {
257
- if (err instanceof ReExStateMismatchError) {
453
+ /** Waits for the block source to sync L1 data up to at least the slot before the given one. */
454
+ private async waitForBlockSourceSync(slot: SlotNumber): Promise<boolean> {
455
+ const deadline = this.getReexecutionDeadline(slot, this.checkpointsBuilder.getConfig());
456
+ const timeoutMs = deadline.getTime() - this.dateProvider.now();
457
+ if (slot === 0) {
458
+ return true;
459
+ }
460
+
461
+ // Make a quick check before triggering an archiver sync
462
+ const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
463
+ if (syncedSlot !== undefined && syncedSlot + 1 >= slot) {
464
+ return true;
465
+ }
466
+
467
+ try {
468
+ // Trigger an immediate sync of the block source, and wait until it reports being synced to the required slot
469
+ return await retryUntil(
470
+ async () => {
471
+ await this.blockSource.syncImmediate();
472
+ const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
473
+ return syncedSlot !== undefined && syncedSlot + 1 >= slot;
474
+ },
475
+ 'wait for block source sync',
476
+ timeoutMs / 1000,
477
+ 0.5,
478
+ );
479
+ } catch (err) {
480
+ if (err instanceof TimeoutError) {
481
+ this.log.warn(`Timed out waiting for block source to sync to slot ${slot}`);
482
+ return false;
483
+ } else {
484
+ throw err;
485
+ }
486
+ }
487
+ }
488
+
489
+ private getReexecuteFailureReason(err: any): BlockProposalValidationFailureReason {
490
+ if (err instanceof ReExInitialStateMismatchError) {
491
+ return 'initial_state_mismatch';
492
+ } else if (err instanceof ReExStateMismatchError) {
258
493
  return 'state_mismatch';
259
494
  } else if (err instanceof ReExFailedTxsError) {
260
495
  return 'failed_txs';
@@ -268,11 +503,12 @@ export class BlockProposalHandler {
268
503
  async reexecuteTransactions(
269
504
  proposal: BlockProposal,
270
505
  blockNumber: BlockNumber,
506
+ checkpointNumber: CheckpointNumber,
271
507
  txs: Tx[],
272
508
  l1ToL2Messages: Fr[],
509
+ previousCheckpointOutHashes: Fr[],
273
510
  ): Promise<ReexecuteTransactionsResult> {
274
- const { header } = proposal.payload;
275
- const { txHashes } = proposal;
511
+ const { blockHeader, txHashes } = proposal;
276
512
 
277
513
  // If we do not have all of the transactions, then we should fail
278
514
  if (txs.length !== txHashes.length) {
@@ -281,32 +517,70 @@ export class BlockProposalHandler {
281
517
  throw new TransactionsNotAvailableError(missingTxHashes);
282
518
  }
283
519
 
284
- // Use the sequencer's block building logic to re-execute the transactions
285
520
  const timer = new Timer();
286
- const config = this.blockBuilder.getConfig();
287
-
288
- // We source most global variables from the proposal
289
- const globalVariables = GlobalVariables.from({
290
- slotNumber: proposal.payload.header.slotNumber, // checked in the block proposal validator
291
- coinbase: proposal.payload.header.coinbase, // set arbitrarily by the proposer
292
- feeRecipient: proposal.payload.header.feeRecipient, // set arbitrarily by the proposer
293
- gasFees: proposal.payload.header.gasFees, // validated by the rollup contract
294
- blockNumber, // computed from the parent block and checked it does not exist in archiver
295
- timestamp: header.timestamp, // checked in the rollup contract against the slot number
521
+ const slot = proposal.slotNumber;
522
+ const config = this.checkpointsBuilder.getConfig();
523
+
524
+ // Get prior blocks in this checkpoint (same slot before current block)
525
+ const allBlocksInSlot = await this.blockSource.getBlocksForSlot(slot);
526
+ const priorBlocks = allBlocksInSlot.filter(b => b.number < blockNumber && b.header.getSlot() === slot);
527
+
528
+ // Fork before the block to be built
529
+ const parentBlockNumber = BlockNumber(blockNumber - 1);
530
+ await this.worldState.syncImmediate(parentBlockNumber);
531
+ await using fork = await this.worldState.fork(parentBlockNumber);
532
+
533
+ // Verify the fork's archive root matches the proposal's expected last archive.
534
+ // If they don't match, our world state synced to a different chain and reexecution would fail.
535
+ const forkArchiveRoot = new Fr((await fork.getTreeInfo(MerkleTreeId.ARCHIVE)).root);
536
+ if (!forkArchiveRoot.equals(proposal.blockHeader.lastArchive.root)) {
537
+ throw new ReExInitialStateMismatchError(proposal.blockHeader.lastArchive.root, forkArchiveRoot);
538
+ }
539
+
540
+ // Build checkpoint constants from proposal (excludes blockNumber which is per-block)
541
+ const constants: CheckpointGlobalVariables = {
296
542
  chainId: new Fr(config.l1ChainId),
297
543
  version: new Fr(config.rollupVersion),
298
- });
544
+ slotNumber: slot,
545
+ timestamp: blockHeader.globalVariables.timestamp,
546
+ coinbase: blockHeader.globalVariables.coinbase,
547
+ feeRecipient: blockHeader.globalVariables.feeRecipient,
548
+ gasFees: blockHeader.globalVariables.gasFees,
549
+ };
299
550
 
300
- const { block, failedTxs } = await this.blockBuilder.buildBlock(txs, l1ToL2Messages, globalVariables, {
301
- deadline: this.getReexecutionDeadline(proposal.payload.header.slotNumber, config),
551
+ // Create checkpoint builder with prior blocks
552
+ const checkpointBuilder = await this.checkpointsBuilder.openCheckpoint(
553
+ checkpointNumber,
554
+ constants,
555
+ 0n, // only takes effect in the following checkpoint.
556
+ l1ToL2Messages,
557
+ previousCheckpointOutHashes,
558
+ fork,
559
+ priorBlocks,
560
+ this.log.getBindings(),
561
+ );
562
+
563
+ // Build the new block
564
+ const deadline = this.getReexecutionDeadline(slot, config);
565
+ const maxBlockGas =
566
+ this.config.validateMaxL2BlockGas !== undefined || this.config.validateMaxDABlockGas !== undefined
567
+ ? new Gas(this.config.validateMaxDABlockGas ?? Infinity, this.config.validateMaxL2BlockGas ?? Infinity)
568
+ : undefined;
569
+ const result = await checkpointBuilder.buildBlock(txs, blockNumber, blockHeader.globalVariables.timestamp, {
570
+ deadline,
571
+ expectedEndState: blockHeader.state,
572
+ maxTransactions: this.config.validateMaxTxsPerBlock,
573
+ maxBlockGas,
302
574
  });
303
575
 
576
+ const { block, failedTxs } = result;
304
577
  const numFailedTxs = failedTxs.length;
305
- const slot = proposal.slotNumber;
306
- this.log.verbose(`Transaction re-execution complete for slot ${slot}`, {
578
+
579
+ this.log.verbose(`Block proposal ${blockNumber} at slot ${slot} transaction re-execution complete`, {
307
580
  numFailedTxs,
308
581
  numProposalTxs: txHashes.length,
309
582
  numProcessedTxs: block.body.txEffects.length,
583
+ blockNumber,
310
584
  slot,
311
585
  });
312
586
 
@@ -321,11 +595,15 @@ export class BlockProposalHandler {
321
595
  }
322
596
 
323
597
  // Throw a ReExStateMismatchError error if state updates do not match
324
- const blockPayload = ConsensusPayload.fromBlock(block);
325
- if (!blockPayload.equals(proposal.payload)) {
598
+ // Compare the full block structure (archive and header) from the built block with the proposal
599
+ const archiveMatches = proposal.archive.equals(block.archive.root);
600
+ const headerMatches = proposal.blockHeader.equals(block.header);
601
+ if (!archiveMatches || !headerMatches) {
326
602
  this.log.warn(`Re-execution state mismatch for slot ${slot}`, {
327
- expected: blockPayload.toInspect(),
328
- actual: proposal.payload.toInspect(),
603
+ expectedArchive: block.archive.root.toString(),
604
+ actualArchive: proposal.archive.toString(),
605
+ expectedHeader: block.header.toInspect(),
606
+ actualHeader: proposal.blockHeader.toInspect(),
329
607
  });
330
608
  this.metrics?.recordFailedReexecution(proposal);
331
609
  throw new ReExStateMismatchError(proposal.archive, block.archive.root);