@aztec/validator-client 0.0.1-commit.42ee6df9b → 0.0.1-commit.431c48d

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.
@@ -4,30 +4,50 @@ import { type Blob, encodeCheckpointBlobDataFromBlocks, getBlobsPerL1Block } fro
4
4
  import { INITIAL_L2_BLOCK_NUM } from '@aztec/constants';
5
5
  import type { EpochCache } from '@aztec/epoch-cache';
6
6
  import { validateFeeAssetPriceModifier } from '@aztec/ethereum/contracts';
7
- import { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
7
+ import {
8
+ BlockNumber,
9
+ CheckpointNumber,
10
+ type CheckpointProposalHash,
11
+ SlotNumber,
12
+ } from '@aztec/foundation/branded-types';
8
13
  import { pick } from '@aztec/foundation/collection';
9
14
  import { Fr } from '@aztec/foundation/curves/bn254';
10
15
  import { TimeoutError } from '@aztec/foundation/error';
16
+ import { FifoSet } from '@aztec/foundation/fifo-set';
11
17
  import type { LogData } from '@aztec/foundation/log';
12
18
  import { createLogger } from '@aztec/foundation/log';
13
19
  import { retryUntil } from '@aztec/foundation/retry';
14
20
  import { DateProvider, Timer } from '@aztec/foundation/timer';
21
+ import { isErrorClass } from '@aztec/foundation/types';
15
22
  import type { P2P, PeerId } from '@aztec/p2p';
16
- import { BlockProposalValidator } from '@aztec/p2p/msg_validators';
17
23
  import type { BlockData, L2Block, L2BlockSink, L2BlockSource } from '@aztec/stdlib/block';
18
- import { validateCheckpoint } from '@aztec/stdlib/checkpoint';
19
- import { getEpochAtSlot, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
24
+ import type { CheckpointReexecutionTracker, ReexecutionOutcome } from '@aztec/stdlib/checkpoint';
25
+ import { getPreviousCheckpointOutHashes, validateCheckpoint } from '@aztec/stdlib/checkpoint';
26
+ import { getEpochAtSlot } from '@aztec/stdlib/epoch-helpers';
20
27
  import { Gas } from '@aztec/stdlib/gas';
21
- import type { ITxProvider, ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
28
+ import type {
29
+ ITxProvider,
30
+ MerkleTreeWriteOperations,
31
+ ValidatorClientFullConfig,
32
+ WorldStateSynchronizer,
33
+ } from '@aztec/stdlib/interfaces/server';
22
34
  import {
23
35
  type L1ToL2MessageSource,
24
36
  accumulateCheckpointOutHashes,
25
37
  computeInHashFromL1ToL2Messages,
26
38
  } from '@aztec/stdlib/messaging';
27
- import type { BlockProposal, CheckpointAttestation, CheckpointProposalCore } from '@aztec/stdlib/p2p';
39
+ import type {
40
+ BlockProposal,
41
+ CheckpointAttestation,
42
+ CheckpointProposalCore,
43
+ ValidatedBlockProposal,
44
+ ValidatedCheckpointProposalCore,
45
+ } from '@aztec/stdlib/p2p';
46
+ import type { ConsensusTimetable } from '@aztec/stdlib/timetable';
28
47
  import { MerkleTreeId } from '@aztec/stdlib/trees';
29
- import type { CheckpointGlobalVariables, FailedTx, Tx } from '@aztec/stdlib/tx';
48
+ import type { CheckpointGlobalVariables, FailedTx, Tx, TxHash } from '@aztec/stdlib/tx';
30
49
  import {
50
+ InvalidBlockProposalTxsError,
31
51
  ReExFailedTxsError,
32
52
  ReExInitialStateMismatchError,
33
53
  ReExStateMismatchError,
@@ -40,18 +60,22 @@ import type { FullNodeCheckpointsBuilder } from './checkpoint_builder.js';
40
60
  import type { ValidatorMetrics } from './metrics.js';
41
61
 
42
62
  export type BlockProposalValidationFailureReason =
63
+ | 'invalid_signature'
43
64
  | 'invalid_proposal'
44
65
  | 'parent_block_not_found'
45
- | 'block_source_not_synced'
46
66
  | 'parent_block_wrong_slot'
47
67
  | 'in_hash_mismatch'
48
68
  | 'global_variables_mismatch'
49
69
  | 'block_number_already_exists'
50
70
  | 'txs_not_available'
71
+ | 'duplicate_txs'
72
+ | 'invalid_embedded_txs'
51
73
  | 'state_mismatch'
52
74
  | 'failed_txs'
53
75
  | 'initial_state_mismatch'
54
76
  | 'timeout'
77
+ | 'block_proposal_beyond_checkpoint'
78
+ | 'checkpoint_proposal_equivocation'
55
79
  | 'unknown_error';
56
80
 
57
81
  type ReexecuteTransactionsResult = {
@@ -76,39 +100,164 @@ export type BlockProposalValidationFailureResult = {
76
100
 
77
101
  export type BlockProposalValidationResult = BlockProposalValidationSuccessResult | BlockProposalValidationFailureResult;
78
102
 
79
- export type CheckpointProposalValidationResult = { isValid: true } | { isValid: false; reason: string };
103
+ export type CheckpointProposalValidationFailureReason =
104
+ | 'invalid_signature'
105
+ | 'invalid_fee_asset_price_modifier'
106
+ | 'last_block_not_found'
107
+ | 'block_fetch_error'
108
+ | 'world_state_not_synced'
109
+ | 'checkpoint_already_published'
110
+ | 'no_blocks_for_slot'
111
+ | 'last_block_archive_mismatch'
112
+ | 'too_many_blocks_in_checkpoint'
113
+ | 'initial_archive_mismatch'
114
+ | 'checkpoint_header_mismatch'
115
+ | 'archive_mismatch'
116
+ | 'out_hash_mismatch'
117
+ | 'checkpoint_validation_failed';
118
+
119
+ /**
120
+ * Mapping from a checkpoint-proposal validation failure reason to the tracker outcome that
121
+ * `handleCheckpointProposal` should record. `undefined` means do not record (signature
122
+ * couldn't be verified, or the checkpoint is already on L1 so the question is moot).
123
+ */
124
+ /* eslint-disable camelcase */
125
+ const CHECKPOINT_VALIDATION_REASON_TO_OUTCOME: Record<
126
+ CheckpointProposalValidationFailureReason,
127
+ ReexecutionOutcome | undefined
128
+ > = {
129
+ invalid_signature: undefined,
130
+ invalid_fee_asset_price_modifier: 'invalid',
131
+ checkpoint_already_published: undefined,
132
+ last_block_not_found: 'unvalidated',
133
+ block_fetch_error: 'unvalidated',
134
+ world_state_not_synced: 'unvalidated',
135
+ initial_archive_mismatch: 'unvalidated',
136
+ no_blocks_for_slot: 'unvalidated',
137
+ last_block_archive_mismatch: 'invalid',
138
+ too_many_blocks_in_checkpoint: 'invalid',
139
+ checkpoint_header_mismatch: 'invalid',
140
+ archive_mismatch: 'invalid',
141
+ out_hash_mismatch: 'invalid',
142
+ checkpoint_validation_failed: 'invalid',
143
+ };
144
+
145
+ export type CheckpointProposalValidationSuccessResult = {
146
+ isValid: true;
147
+ checkpointNumber: CheckpointNumber;
148
+ };
149
+
150
+ export type CheckpointProposalValidationFailureResult = {
151
+ isValid: false;
152
+ reason: CheckpointProposalValidationFailureReason;
153
+ checkpointNumber?: CheckpointNumber;
154
+ };
155
+
156
+ export type CheckpointProposalValidationResult =
157
+ | CheckpointProposalValidationSuccessResult
158
+ | CheckpointProposalValidationFailureResult;
159
+
160
+ export type CheckpointProposalValidationFailureCallback = (
161
+ proposal: CheckpointProposalCore,
162
+ result: CheckpointProposalValidationFailureResult,
163
+ proposalInfo: LogData,
164
+ ) => void | Promise<void>;
80
165
 
81
166
  type CheckpointComputationResult =
82
167
  | { checkpointNumber: CheckpointNumber; reason?: undefined }
83
168
  | { checkpointNumber?: undefined; reason: 'invalid_proposal' | 'global_variables_mismatch' };
84
169
 
85
- /** Handles block and checkpoint proposals for both validator and non-validator nodes. */
170
+ type BlockProposalSlotValidationResult =
171
+ | { isValid: true }
172
+ | { isValid: false; reason: 'block_proposal_beyond_checkpoint' | 'checkpoint_proposal_equivocation' };
173
+
174
+ const MAX_TRACKED_INVALID_PROPOSAL_SLOTS = 1000;
175
+
176
+ /** Block-proposal validation failures that constitute a slashable invalid-block offense. */
177
+ export const SLASHABLE_BLOCK_PROPOSAL_VALIDATION_RESULT: BlockProposalValidationFailureReason[] = [
178
+ 'state_mismatch',
179
+ 'failed_txs',
180
+ 'global_variables_mismatch',
181
+ 'invalid_proposal',
182
+ 'parent_block_wrong_slot',
183
+ 'in_hash_mismatch',
184
+ 'duplicate_txs',
185
+ 'invalid_embedded_txs',
186
+ ];
187
+
188
+ /** Checkpoint-proposal validation failures that constitute a slashable invalid-checkpoint offense. */
189
+ export const SLASHABLE_CHECKPOINT_PROPOSAL_VALIDATION_RESULT: Record<
190
+ CheckpointProposalValidationFailureReason,
191
+ boolean
192
+ > = {
193
+ // enabled
194
+ ['invalid_fee_asset_price_modifier']: true,
195
+ ['checkpoint_header_mismatch']: true,
196
+ // These late mismatches should normally be caught by earlier checks, but if reached after validating the local
197
+ // checkpoint inputs, the proposer-signed payload disagrees with deterministic recomputation.
198
+ ['archive_mismatch']: true,
199
+ ['out_hash_mismatch']: true,
200
+ ['no_blocks_for_slot']: true,
201
+ ['too_many_blocks_in_checkpoint']: true,
202
+ ['checkpoint_validation_failed']: true,
203
+ ['last_block_archive_mismatch']: true,
204
+
205
+ // disabled
206
+ ['invalid_signature']: false,
207
+ ['last_block_not_found']: false,
208
+ ['block_fetch_error']: false,
209
+ ['world_state_not_synced']: false,
210
+ // A reorg / divergent local chain, not a proposer offense (mirrors the block path's initial_state_mismatch).
211
+ ['initial_archive_mismatch']: false,
212
+ ['checkpoint_already_published']: false,
213
+ };
214
+
215
+ /**
216
+ * Handles block and checkpoint proposals for both validator and non-validator nodes. Also tracks which slots
217
+ * had a slashable invalid proposal or a proposal equivocation, exposing them via the
218
+ * `InvalidProposalSlotSource` interface consumed by the attested-invalid-proposal slashing watcher. The
219
+ * tracking is populated as a side effect of validating/re-executing proposals, so any node that re-executes
220
+ * proposals (the default) can serve it — not only validators.
221
+ */
86
222
  export class ProposalHandler {
87
223
  public readonly tracer: Tracer;
88
224
 
89
- /** Cached last checkpoint validation result to avoid double-validation on validator nodes. */
225
+ /** Cached last checkpoint validation result to avoid double-validation on validator nodes.
226
+ * Keyed by signed-payload hash so two proposals at the same (slot, archive) but with a
227
+ * different `feeAssetPriceModifier` (or any other signed field) are validated independently. */
90
228
  private lastCheckpointValidationResult?: {
91
- archive: Fr;
92
- slotNumber: SlotNumber;
229
+ payloadHash: CheckpointProposalHash;
93
230
  result: CheckpointProposalValidationResult;
94
231
  };
95
232
 
96
233
  /** Archiver reference for setting proposed checkpoints (pipelining). Set via register(). */
97
- private archiver?: Pick<Archiver, 'setProposedCheckpoint' | 'getL1Constants'>;
234
+ private archiver?: Pick<Archiver, 'addProposedCheckpoint' | 'getProposedCheckpointData'>;
98
235
 
99
236
  /** Returns current validator addresses for own-proposal detection. Set via register(). */
100
237
  private getOwnValidatorAddresses?: () => string[];
101
238
 
239
+ /** P2P proposal pool access for deciding when retained proposals should block archiver processing. */
240
+ private p2pClient?: Pick<P2P, 'getProposalsForSlot'>;
241
+
242
+ private checkpointProposalValidationFailureCallback?: CheckpointProposalValidationFailureCallback;
243
+
244
+ /** Slots at which a slashable invalid block or checkpoint proposal was observed. */
245
+ private readonly slotsWithInvalidProposals = FifoSet.withLimit<SlotNumber>(MAX_TRACKED_INVALID_PROPOSAL_SLOTS);
246
+
247
+ /** Slots at which a proposal equivocation was observed; suppresses attested-to-invalid-proposal slashing. */
248
+ private readonly slotsWithProposalEquivocation = FifoSet.withLimit<SlotNumber>(MAX_TRACKED_INVALID_PROPOSAL_SLOTS);
249
+
102
250
  constructor(
103
251
  private checkpointsBuilder: FullNodeCheckpointsBuilder,
104
252
  private worldState: WorldStateSynchronizer,
105
253
  private blockSource: L2BlockSource & L2BlockSink,
106
254
  private l1ToL2MessageSource: L1ToL2MessageSource,
107
255
  private txProvider: ITxProvider,
108
- private blockProposalValidator: BlockProposalValidator,
109
256
  private epochCache: EpochCache,
257
+ private timetable: ConsensusTimetable,
110
258
  private config: ValidatorClientFullConfig,
111
259
  private blobClient: BlobClientInterface,
260
+ private reexecutionTracker: CheckpointReexecutionTracker,
112
261
  private metrics?: ValidatorMetrics,
113
262
  private dateProvider: DateProvider = new DateProvider(),
114
263
  telemetry: TelemetryClient = getTelemetryClient(),
@@ -120,8 +269,52 @@ export class ProposalHandler {
120
269
  this.tracer = telemetry.getTracer('ProposalHandler');
121
270
  }
122
271
 
272
+ public updateConfig(config: Partial<ValidatorClientFullConfig>): void {
273
+ this.config = { ...this.config, ...config };
274
+ }
275
+
276
+ public setCheckpointProposalValidationFailureCallback(callback?: CheckpointProposalValidationFailureCallback): void {
277
+ this.checkpointProposalValidationFailureCallback = callback;
278
+ }
279
+
280
+ /**
281
+ * Records the proposer's own checkpoint proposal as a `valid` outcome in the re-execution
282
+ * tracker. Without this, the node's own checkpoint proposals never flow through
283
+ * `handleCheckpointProposal` (proposers don't validate their own proposals), so its sentinel
284
+ * sees no outcome for slots where it was the proposer and reports itself as inactive.
285
+ *
286
+ * `archive` should be the locally-computed archive (NOT the broadcast archive, which may have
287
+ * been deliberately corrupted in tests via `broadcastInvalidBlockProposal` /
288
+ * `broadcastInvalidCheckpointProposalOnly`). Recording the local archive correctly models the
289
+ * proposer's own view of its own work.
290
+ */
291
+ public recordOwnCheckpointProposalAsValid(slot: SlotNumber, archive: Fr, checkpointNumber: CheckpointNumber): void {
292
+ this.reexecutionTracker.recordOutcome(slot, archive, 'valid', checkpointNumber);
293
+ }
294
+
295
+ /** Whether a slashable invalid block or checkpoint proposal was observed at the given slot (InvalidProposalSlotSource). */
296
+ public hasInvalidProposals(slotNumber: SlotNumber): boolean {
297
+ return this.slotsWithInvalidProposals.has(slotNumber);
298
+ }
299
+
300
+ /** Whether a proposal equivocation was observed at the given slot (InvalidProposalSlotSource). */
301
+ public hasProposalEquivocation(slotNumber: SlotNumber): boolean {
302
+ return this.slotsWithProposalEquivocation.has(slotNumber);
303
+ }
304
+
305
+ /** Records a slot as having a slashable invalid proposal, for offense observers (sentinel/slasher watchers). */
306
+ public markInvalidProposalSlot(slotNumber: SlotNumber): void {
307
+ this.slotsWithInvalidProposals.add(slotNumber);
308
+ }
309
+
310
+ /** Records a slot as having a proposal equivocation, which suppresses attested-to-invalid-proposal slashing. */
311
+ public markProposalEquivocation(slotNumber: SlotNumber): void {
312
+ this.slotsWithProposalEquivocation.add(slotNumber);
313
+ }
314
+
123
315
  /**
124
316
  * Registers handlers for block and checkpoint proposals on the p2p client.
317
+ * Records the p2p client so validation can inspect retained proposals.
125
318
  * Block proposals are registered for non-validator nodes (validators register their own enhanced handler).
126
319
  * The all-nodes checkpoint proposal handler is always registered for validation, caching, and pipelining.
127
320
  * @param archiver - Archiver reference for setting proposed checkpoints (pipelining)
@@ -130,15 +323,16 @@ export class ProposalHandler {
130
323
  register(
131
324
  p2pClient: P2P,
132
325
  shouldReexecute: boolean,
133
- archiver?: Pick<Archiver, 'setProposedCheckpoint' | 'getL1Constants'>,
326
+ archiver?: Pick<Archiver, 'addProposedCheckpoint' | 'getProposedCheckpointData'>,
134
327
  getOwnValidatorAddresses?: () => string[],
135
328
  ): ProposalHandler {
329
+ this.p2pClient = p2pClient;
136
330
  this.archiver = archiver;
137
331
  this.getOwnValidatorAddresses = getOwnValidatorAddresses;
138
332
 
139
333
  // Non-validator handler that processes or re-executes for monitoring but does not attest.
140
334
  // Returns boolean indicating whether the proposal was valid.
141
- const blockHandler = async (proposal: BlockProposal, proposalSender: PeerId): Promise<boolean> => {
335
+ const blockHandler = async (proposal: ValidatedBlockProposal, proposalSender: PeerId): Promise<boolean> => {
142
336
  try {
143
337
  const { slotNumber, blockNumber } = proposal;
144
338
  const result = await this.handleBlockProposal(proposal, proposalSender, shouldReexecute);
@@ -153,6 +347,18 @@ export class ProposalHandler {
153
347
  });
154
348
  return true;
155
349
  } else {
350
+ // Track invalid proposals / equivocations so offense observers (the attested-invalid-proposal
351
+ // watcher) work on non-validator nodes too. Validators populate these via their own handlers.
352
+ // Skip invalid-proposal marking while the escape hatch is open, matching the validator path,
353
+ // which intentionally disables invalid-block slashing then.
354
+ if (result.reason === 'checkpoint_proposal_equivocation') {
355
+ this.markProposalEquivocation(slotNumber);
356
+ } else if (
357
+ SLASHABLE_BLOCK_PROPOSAL_VALIDATION_RESULT.includes(result.reason) &&
358
+ !(await this.epochCache.isEscapeHatchOpenAtSlot(slotNumber))
359
+ ) {
360
+ this.markInvalidProposalSlot(slotNumber);
361
+ }
156
362
  this.log.warn(
157
363
  `Non-validator block proposal ${blockNumber} at slot ${slotNumber} failed processing with ${result.reason}`,
158
364
  { blockNumber: result.blockNumber, slotNumber, reason: result.reason },
@@ -167,36 +373,71 @@ export class ProposalHandler {
167
373
 
168
374
  p2pClient.registerBlockProposalHandler(blockHandler);
169
375
 
376
+ // p2p detects duplicate (equivocated) proposals without routing them through the handlers above, so mark
377
+ // the slot as equivocated here. This suppresses false-positive attested-to-invalid-proposal slashing on
378
+ // non-validator offense collectors. Validators overwrite this with their own richer handler.
379
+ p2pClient.registerDuplicateProposalCallback(info => this.markProposalEquivocation(info.slot));
380
+
170
381
  // All-nodes checkpoint proposal handler: validates, caches, and sets proposed checkpoint for pipelining.
171
382
  // Runs for all nodes (validators and non-validators). Validators get the cached result in the
172
383
  // validator-specific callback (attestToCheckpointProposal) which runs after this one.
173
384
  const checkpointHandler = async (
174
- proposal: CheckpointProposalCore,
385
+ proposal: ValidatedCheckpointProposalCore,
175
386
  _sender: PeerId,
176
387
  ): Promise<CheckpointAttestation[] | undefined> => {
177
388
  try {
389
+ const pipeliningTimer = new Timer();
178
390
  const proposalInfo: LogData = {
179
391
  slot: proposal.slotNumber,
180
392
  archive: proposal.archive.toString(),
181
393
  proposer: proposal.getSender()?.toString(),
182
394
  };
183
395
 
184
- // For own proposals, skip validation — the proposer already built and validated the checkpoint
396
+ if (this.config.skipCheckpointProposalValidation) {
397
+ this.log.warn(`Skipping checkpoint proposal validation for slot ${proposal.slotNumber}`, proposalInfo);
398
+ return undefined;
399
+ }
400
+
401
+ if (await this.epochCache.isEscapeHatchOpenAtSlot(proposal.slotNumber)) {
402
+ this.log.warn(
403
+ `Escape hatch open for slot ${proposal.slotNumber}, skipping checkpoint proposal validation`,
404
+ proposalInfo,
405
+ );
406
+ return undefined;
407
+ }
408
+
409
+ // A proposal is "own" when it was signed by a validator key this node also owns. The true local
410
+ // proposer already built, validated, and stored this checkpoint before broadcasting, so a matching
411
+ // proposed checkpoint is already in its archiver — skip the redundant re-validation. An HA peer that
412
+ // shares the proposer's keys sees the same "own" proposal over gossip but never built it, so it has
413
+ // nothing stored; it falls through to the normal validate-and-persist path below to hydrate the
414
+ // proposed-checkpoint metadata it needs to build the next slot on top of this checkpoint.
185
415
  const proposer = proposal.getSender();
186
416
  const ownAddresses = this.getOwnValidatorAddresses?.();
187
417
  const isOwnProposal = proposer && ownAddresses?.some(addr => addr === proposer.toString());
188
418
 
189
419
  if (isOwnProposal) {
190
- this.log.debug(`Skipping validation for own checkpoint proposal at slot ${proposal.slotNumber}`);
191
- if (this.archiver && this.epochCache.isProposerPipeliningEnabled()) {
192
- await this.setProposedCheckpointFromBlocks(proposal);
420
+ const existing = await this.archiver?.getProposedCheckpointData({ slot: proposal.slotNumber });
421
+ if (existing?.archive.root.equals(proposal.archive)) {
422
+ this.log.debug(`Skipping sync for existing own checkpoint proposal at slot ${proposal.slotNumber}`);
423
+ return undefined;
193
424
  }
194
- return undefined;
195
425
  }
196
426
 
197
427
  const result = await this.handleCheckpointProposal(proposal, proposalInfo);
198
- if (result.isValid && this.archiver && this.epochCache.isProposerPipeliningEnabled()) {
199
- await this.setProposedCheckpointFromValidation(proposal);
428
+ if (!result.isValid) {
429
+ // Track invalid checkpoint proposals so offense observers (the attested-invalid-proposal watcher)
430
+ // work on non-validator nodes too. This handler runs for all nodes; validators also mark via the
431
+ // failure callback below (idempotent).
432
+ if (SLASHABLE_CHECKPOINT_PROPOSAL_VALIDATION_RESULT[result.reason]) {
433
+ this.markInvalidProposalSlot(proposal.slotNumber);
434
+ }
435
+ await this.checkpointProposalValidationFailureCallback?.(proposal, result, proposalInfo);
436
+ } else if (this.archiver) {
437
+ const set = await this.setProposedCheckpoint(proposal);
438
+ if (set) {
439
+ this.metrics?.recordCheckpointProposalToPipelinedStateDuration(pipeliningTimer.ms());
440
+ }
200
441
  }
201
442
  } catch (err) {
202
443
  this.log.warn(`Error handling checkpoint proposal for slot ${proposal.slotNumber}`, { err });
@@ -209,19 +450,25 @@ export class ProposalHandler {
209
450
  return this;
210
451
  }
211
452
 
453
+ /**
454
+ * Processes a block proposal: collects its txs and, if requested, re-executes them to check the resulting
455
+ * block against the proposal. Expects the proposal to have already passed p2p ingress validation (signature
456
+ * context, signature, expected proposer, index within checkpoint, tx field checks, and the receive-window
457
+ * timeliness check) — none of those are re-applied here, and only deterministic properties of the payload
458
+ * are validated before processing.
459
+ */
212
460
  async handleBlockProposal(
213
- proposal: BlockProposal,
461
+ proposal: ValidatedBlockProposal,
214
462
  proposalSender: PeerId,
215
463
  shouldReexecute: boolean,
216
464
  ): Promise<BlockProposalValidationResult> {
217
465
  const slotNumber = proposal.slotNumber;
218
466
  const proposer = proposal.getSender();
219
- const config = this.checkpointsBuilder.getConfig();
220
467
 
221
468
  // Reject proposals with invalid signatures
222
469
  if (!proposer) {
223
470
  this.log.warn(`Received proposal with invalid signature for slot ${slotNumber}`);
224
- return { isValid: false, reason: 'invalid_proposal' };
471
+ return { isValid: false, reason: 'invalid_signature' };
225
472
  }
226
473
 
227
474
  const proposalInfo = {
@@ -236,29 +483,38 @@ export class ProposalHandler {
236
483
  txHashes: proposal.txHashes.map(t => t.toString()),
237
484
  });
238
485
 
239
- // Check that the proposal is from the current proposer, or the next proposer
240
- // This should have been handled by the p2p layer, but we double check here out of caution
241
- const validationResult = await this.blockProposalValidator.validate(proposal);
242
- if (validationResult.result !== 'accept') {
243
- this.log.warn(`Proposal is not valid, skipping processing`, proposalInfo);
244
- return { isValid: false, reason: 'invalid_proposal' };
486
+ // The receive-window check from p2p ingress is deliberately not re-applied here: its outcome depends on
487
+ // the wall clock at evaluation time, so re-running it turned node-local processing latency into an
488
+ // invalid-proposal verdict against an honest proposer, which then fed the invalid-block slashing path.
489
+
490
+ // A tx can only appear once in a block: the second copy would emit nullifiers already emitted by the
491
+ // first. This is not a relaying-peer fault, so it passes gossip validation and is classified here as
492
+ // proposer misbehavior. Tx collection also reconciles a deduplicated hash set against the full list,
493
+ // so it must not be handed a proposal with repeated hashes.
494
+ const uniqueTxHashes = new Set(proposal.txHashes.map(txHash => txHash.toString()));
495
+ if (uniqueTxHashes.size !== proposal.txHashes.length) {
496
+ this.log.warn(`Proposal lists duplicate tx hashes, skipping processing`, {
497
+ ...proposalInfo,
498
+ txCount: proposal.txHashes.length,
499
+ uniqueTxCount: uniqueTxHashes.size,
500
+ });
501
+ return { isValid: false, reason: 'duplicate_txs' };
245
502
  }
246
503
 
247
- // Ensure the block source is synced before checking for existing blocks,
248
- // since a proposed checkpoint prune may remove blocks we'd otherwise find.
249
- // This affects mostly the block_number_already_exists check, since a pending
250
- // checkpoint prune could remove a block that would conflict with this proposal.
251
- // When pipelining is enabled, the proposer builds ahead of L1 submission, so the
252
- // block source won't have synced to the proposed slot yet. Skip the sync wait to
253
- // avoid eating into the attestation window.
254
- if (!this.epochCache.isProposerPipeliningEnabled()) {
255
- const blockSourceSync = await this.waitForBlockSourceSync(slotNumber);
256
- if (!blockSourceSync) {
257
- this.log.warn(`Block source is not synced, skipping processing`, proposalInfo);
258
- return { isValid: false, reason: 'block_source_not_synced' };
259
- }
504
+ const retainedSlotValidation = await this.validateNewBlockInSlot(proposal);
505
+ if (!retainedSlotValidation.isValid) {
506
+ this.log.info(`Block proposal conflicts with retained proposals, skipping archiver processing`, {
507
+ ...proposalInfo,
508
+ indexWithinCheckpoint: proposal.indexWithinCheckpoint,
509
+ reason: retainedSlotValidation.reason,
510
+ });
511
+ return { isValid: false, blockNumber: proposal.blockNumber, reason: retainedSlotValidation.reason };
260
512
  }
261
513
 
514
+ // The proposer builds ahead of L1 submission under pipelining, so the block source won't have
515
+ // synced to the proposed slot yet. We deliberately do not wait for it to sync here, to avoid
516
+ // eating into the attestation window.
517
+
262
518
  // Check that the parent proposal is a block we know, otherwise reexecution would fail.
263
519
  // If we don't find it immediately, we keep retrying for a while; it may be we still
264
520
  // need to process other block proposals to get to it.
@@ -285,8 +541,12 @@ export class ProposalHandler {
285
541
  : BlockNumber(parentBlock.header.getBlockNumber() + 1);
286
542
  proposalInfo.blockNumber = blockNumber;
287
543
 
288
- // Check that this block number does not exist already
289
- const existingBlock = await this.blockSource.getBlockHeader(blockNumber);
544
+ // Check that this block number does not exist already. During a reorg the archiver can still hold a
545
+ // stale block at this number (a different archive, about to be pruned) while the proposal carries the
546
+ // rebuilt replacement; resolveExistingBlockAtNumber waits for the local prune in that case so the
547
+ // rebuilt block is processed in time to attest, rather than being permanently dropped on a bare
548
+ // number collision.
549
+ const existingBlock = await this.resolveExistingBlockAtNumber(blockNumber, proposal.archive, slotNumber);
290
550
  if (existingBlock) {
291
551
  this.log.warn(`Block number ${blockNumber} already exists, skipping processing`, proposalInfo);
292
552
  return { isValid: false, blockNumber, reason: 'block_number_already_exists' };
@@ -294,10 +554,14 @@ export class ProposalHandler {
294
554
 
295
555
  // Collect txs from the proposal. We start doing this as early as possible,
296
556
  // and we do it even if we don't plan to re-execute the txs, so that we have them if another node needs them.
297
- const { txs, missingTxs } = await this.txProvider.getTxsForBlockProposal(proposal, blockNumber, {
298
- pinnedPeer: proposalSender,
299
- deadline: this.getReexecutionDeadline(slotNumber, config),
300
- });
557
+ const collected = await this.collectProposalTxs(proposal, blockNumber, proposalSender, proposalInfo);
558
+ if (collected === 'invalid_embedded_txs') {
559
+ return { isValid: false, blockNumber, reason: collected };
560
+ }
561
+ const { txs, missingTxs } = collected;
562
+
563
+ // Record the tx-collection outcome on the re-execution tracker
564
+ this.reexecutionTracker.recordTxsCollected(slotNumber, proposal.indexWithinCheckpoint, missingTxs.length === 0);
301
565
 
302
566
  // If reexecution is disabled, bail. We were just interested in triggering tx collection.
303
567
  if (!shouldReexecute) {
@@ -335,11 +599,18 @@ export class ProposalHandler {
335
599
  return { isValid: false, blockNumber, reason: 'txs_not_available' };
336
600
  }
337
601
 
338
- // Collect the out hashes of all the checkpoints before this one in the same epoch
602
+ // Collect the out hashes of all the checkpoints before this one in the same epoch.
603
+ // Mirror the proposer-side fallback: under pipelining the immediately-preceding cp may not
604
+ // yet be on L1, in which case the helper grafts the locally-known proposed cp's outHash.
339
605
  const epoch = getEpochAtSlot(slotNumber, this.epochCache.getL1Constants());
340
- const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
341
- .filter(c => c.checkpointNumber < checkpointNumber)
342
- .map(c => c.checkpointOutHash);
606
+ const previousCheckpointOutHashes = await getPreviousCheckpointOutHashes({
607
+ blockSource: this.blockSource,
608
+ epoch,
609
+ checkpointNumber,
610
+ l1Constants: this.epochCache.getL1Constants(),
611
+ pipeliningEnabled: true,
612
+ log: this.log,
613
+ });
343
614
 
344
615
  // Try re-executing the transactions in the proposal if needed
345
616
  let reexecutionResult;
@@ -360,7 +631,7 @@ export class ProposalHandler {
360
631
  }
361
632
 
362
633
  // If we succeeded, push this block into the archiver (unless disabled)
363
- if (reexecutionResult?.block && this.config.skipPushProposedBlocksToArchiver === false) {
634
+ if (reexecutionResult?.block && !this.config.skipPushProposedBlocksToArchiver) {
364
635
  await this.blockSource.addBlock(reexecutionResult.block);
365
636
  }
366
637
 
@@ -372,29 +643,77 @@ export class ProposalHandler {
372
643
  return { isValid: true, blockNumber, reexecutionResult };
373
644
  }
374
645
 
646
+ /**
647
+ * Collects the txs for a proposal, returning `invalid_embedded_txs` if the proposal carries a tx that fails
648
+ * minimum integrity validation. That is proposer misbehavior — the proposal signs both the tx hashes and the
649
+ * tx objects — so the caller turns it into an invalid-proposal result that reaches slashing and invalid-slot
650
+ * accounting, rather than letting it escape as an exception. Any other collection error is a local failure
651
+ * and keeps propagating.
652
+ */
653
+ private async collectProposalTxs(
654
+ proposal: BlockProposal,
655
+ blockNumber: BlockNumber,
656
+ proposalSender: PeerId,
657
+ proposalInfo: LogData,
658
+ ): Promise<{ txs: Tx[]; missingTxs: TxHash[] } | 'invalid_embedded_txs'> {
659
+ try {
660
+ return await this.txProvider.getTxsForBlockProposal(proposal, blockNumber, {
661
+ pinnedPeer: proposalSender,
662
+ deadline: this.getReexecutionDeadline(proposal.slotNumber),
663
+ });
664
+ } catch (error) {
665
+ if (!isErrorClass(error, InvalidBlockProposalTxsError)) {
666
+ throw error;
667
+ }
668
+ this.log.warn(`Block proposal carries ${error.invalidTxs.length} invalid txs`, {
669
+ ...proposalInfo,
670
+ invalidTxs: error.invalidTxs.map(({ txHash, reasons }) => ({ txHash: txHash.toString(), reasons })),
671
+ });
672
+ return 'invalid_embedded_txs';
673
+ }
674
+ }
675
+
676
+ private async validateNewBlockInSlot(blockProposal: BlockProposal): Promise<BlockProposalSlotValidationResult> {
677
+ if (!this.p2pClient) {
678
+ return { isValid: true };
679
+ }
680
+
681
+ const { blockProposals, checkpointProposals } = await this.p2pClient.getProposalsForSlot(blockProposal.slotNumber);
682
+
683
+ if (checkpointProposals.length === 0) {
684
+ return { isValid: true };
685
+ } else if (checkpointProposals.length > 1) {
686
+ return { isValid: false, reason: 'checkpoint_proposal_equivocation' };
687
+ } else {
688
+ const checkpointProposal = checkpointProposals[0];
689
+ const terminalBlock = blockProposals.find(block => block.archive.equals(checkpointProposal.archive));
690
+ return terminalBlock !== undefined && blockProposal.indexWithinCheckpoint > terminalBlock.indexWithinCheckpoint
691
+ ? { isValid: false, reason: 'block_proposal_beyond_checkpoint' }
692
+ : { isValid: true };
693
+ }
694
+ }
695
+
375
696
  private async getParentBlock(proposal: BlockProposal): Promise<'genesis' | BlockData | undefined> {
376
697
  const parentArchive = proposal.blockHeader.lastArchive.root;
377
- const slot = proposal.slotNumber;
378
- const config = this.checkpointsBuilder.getConfig();
379
698
  const { genesisArchiveRoot } = await this.blockSource.getGenesisValues();
380
699
 
381
700
  if (parentArchive.equals(genesisArchiveRoot)) {
382
701
  return 'genesis';
383
702
  }
384
703
 
385
- const deadline = this.getReexecutionDeadline(slot, config);
386
- const currentTime = this.dateProvider.now();
387
- const timeoutDurationMs = deadline.getTime() - currentTime;
704
+ const deadline = this.getReexecutionDeadline(proposal.slotNumber);
705
+ const timeoutDurationMs = deadline.getTime() - this.dateProvider.now();
388
706
 
389
707
  try {
390
708
  return (
391
- (await this.blockSource.getBlockDataByArchive(parentArchive)) ??
709
+ (await this.blockSource.getBlockData({ archive: parentArchive })) ??
392
710
  (timeoutDurationMs <= 0
393
711
  ? undefined
394
712
  : await retryUntil(
395
- () => this.blockSource.syncImmediate().then(() => this.blockSource.getBlockDataByArchive(parentArchive)),
713
+ () =>
714
+ this.blockSource.syncImmediate().then(() => this.blockSource.getBlockData({ archive: parentArchive })),
396
715
  'force archiver sync',
397
- timeoutDurationMs / 1000,
716
+ { deadline, dateProvider: this.dateProvider },
398
717
  0.5,
399
718
  ))
400
719
  );
@@ -408,6 +727,63 @@ export class ProposalHandler {
408
727
  }
409
728
  }
410
729
 
730
+ /**
731
+ * Resolves whether a block genuinely already exists at `blockNumber`. Returns the existing block only if
732
+ * it is a true duplicate of the proposal (matching archive). During a reorg the archiver can still hold a
733
+ * stale fork at this number (different archive) that is about to be pruned; in that case this forces L1
734
+ * sync and waits, bounded by the re-execution deadline, for the prune to land, then returns `undefined` so
735
+ * the rebuilt block proposal can be processed in time to attest. If the prune does not complete before the
736
+ * deadline it returns the stale block, so the caller falls back to the safe `block_number_already_exists`
737
+ * rejection.
738
+ */
739
+ private async resolveExistingBlockAtNumber(
740
+ blockNumber: BlockNumber,
741
+ proposalArchive: Fr,
742
+ slotNumber: SlotNumber,
743
+ ): Promise<BlockData | undefined> {
744
+ const existingBlock = await this.blockSource.getBlockData({ number: blockNumber });
745
+ if (!existingBlock || existingBlock.archive.root.equals(proposalArchive)) {
746
+ return existingBlock;
747
+ }
748
+
749
+ // A different block already occupies this number: it may be a stale fork being pruned during a reorg, not a
750
+ // genuine duplicate. Wait for the local prune rather than permanently rejecting the proposal.
751
+ const deadline = this.getReexecutionDeadline(slotNumber);
752
+ if (deadline.getTime() - this.dateProvider.now() <= 0) {
753
+ return existingBlock;
754
+ }
755
+
756
+ this.log.warn(`Block number ${blockNumber} already exists, awaiting potential prune`, {
757
+ blockNumber,
758
+ existingArchive: existingBlock.archive.root.toString(),
759
+ proposalArchive: proposalArchive.toString(),
760
+ });
761
+
762
+ try {
763
+ const { block } = await retryUntil(
764
+ async () => {
765
+ await this.blockSource.syncImmediate();
766
+ const block = await this.blockSource.getBlockData({ number: blockNumber });
767
+ // Resolve once the existing block is gone (pruned) or has been replaced by one matching the
768
+ // proposal — the same condition as the early return above. A matching block is returned so the
769
+ // caller still treats it as a genuine duplicate; an `undefined` (pruned) block lets the proposal
770
+ // be processed. Wrap in an object so the `undefined` case is still a truthy retry result.
771
+ return block === undefined || block.archive.root.equals(proposalArchive) ? { block } : undefined;
772
+ },
773
+ `prune of stale block ${blockNumber}`,
774
+ { deadline, dateProvider: this.dateProvider },
775
+ 0.5,
776
+ );
777
+ return block;
778
+ } catch (err) {
779
+ if (err instanceof TimeoutError) {
780
+ this.log.warn(`Timed out waiting for stale block ${blockNumber} to be pruned`, { blockNumber });
781
+ return existingBlock;
782
+ }
783
+ throw err;
784
+ }
785
+ }
786
+
411
787
  private computeCheckpointNumber(
412
788
  proposal: BlockProposal,
413
789
  parentBlock: 'genesis' | BlockData,
@@ -531,45 +907,14 @@ export class ProposalHandler {
531
907
  return undefined;
532
908
  }
533
909
 
534
- private getReexecutionDeadline(slot: SlotNumber, config: { l1GenesisTime: bigint; slotDuration: number }): Date {
535
- const nextSlotTimestampSeconds = Number(getTimestampForSlot(SlotNumber(slot + 1), config));
536
- return new Date(nextSlotTimestampSeconds * 1000);
537
- }
538
-
539
- /** Waits for the block source to sync L1 data up to at least the slot before the given one. */
540
- private async waitForBlockSourceSync(slot: SlotNumber): Promise<boolean> {
541
- const deadline = this.getReexecutionDeadline(slot, this.checkpointsBuilder.getConfig());
542
- const timeoutMs = deadline.getTime() - this.dateProvider.now();
543
- if (slot === 0) {
544
- return true;
545
- }
546
-
547
- // Make a quick check before triggering an archiver sync
548
- const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
549
- if (syncedSlot !== undefined && syncedSlot + 1 >= slot) {
550
- return true;
551
- }
552
-
553
- try {
554
- // Trigger an immediate sync of the block source, and wait until it reports being synced to the required slot
555
- return await retryUntil(
556
- async () => {
557
- await this.blockSource.syncImmediate();
558
- const syncedSlot = await this.blockSource.getSyncedL2SlotNumber();
559
- return syncedSlot !== undefined && syncedSlot + 1 >= slot;
560
- },
561
- 'wait for block source sync',
562
- timeoutMs / 1000,
563
- 0.5,
564
- );
565
- } catch (err) {
566
- if (err instanceof TimeoutError) {
567
- this.log.warn(`Timed out waiting for block source to sync to slot ${slot}`);
568
- return false;
569
- } else {
570
- throw err;
571
- }
572
- }
910
+ /**
911
+ * Hard re-execution/validation deadline for any block or checkpoint proposal targeting `slotNumber`:
912
+ * the single consensus `attestation_deadline` (`target_slot_start + S - 2E`). This is the latest the
913
+ * checkpoint can land on L1 in the target slot; all nodes agree on it. Loosened from the previous
914
+ * next-wall-clock-slot-boundary bound (see the timetable spec / refactor notes).
915
+ */
916
+ private getReexecutionDeadline(slotNumber: SlotNumber): Date {
917
+ return new Date(this.timetable.getAttestationDeadline(slotNumber) * 1000);
573
918
  }
574
919
 
575
920
  private getReexecuteFailureReason(err: any): BlockProposalValidationFailureReason {
@@ -601,7 +946,7 @@ export class ProposalHandler {
601
946
  // If we do not have all of the transactions, then we should fail
602
947
  if (txs.length !== txHashes.length) {
603
948
  const foundTxHashes = txs.map(tx => tx.getTxHash());
604
- const missingTxHashes = txHashes.filter(txHash => !foundTxHashes.includes(txHash));
949
+ const missingTxHashes = txHashes.filter(txHash => !foundTxHashes.some(h => h.equals(txHash)));
605
950
  throw new TransactionsNotAvailableError(missingTxHashes);
606
951
  }
607
952
 
@@ -649,7 +994,7 @@ export class ProposalHandler {
649
994
  );
650
995
 
651
996
  // Build the new block
652
- const deadline = this.getReexecutionDeadline(slot, config);
997
+ const deadline = this.getReexecutionDeadline(slot);
653
998
  const maxBlockGas =
654
999
  this.config.validateMaxL2BlockGas !== undefined || this.config.validateMaxDABlockGas !== undefined
655
1000
  ? new Gas(this.config.validateMaxDABlockGas ?? Infinity, this.config.validateMaxL2BlockGas ?? Infinity)
@@ -716,42 +1061,54 @@ export class ProposalHandler {
716
1061
  * Validates a checkpoint proposal, caches the result, and uploads blobs if configured.
717
1062
  * Returns a cached result if the same proposal (archive + slot) was already validated.
718
1063
  * Used by both the all-nodes callback (via register) and the validator client (via delegation).
1064
+ * Expects the proposal to have already passed p2p ingress validation (expected proposer and receive-window
1065
+ * timeliness); only deterministic properties of the signed payload are checked here.
719
1066
  */
720
1067
  async handleCheckpointProposal(
721
- proposal: CheckpointProposalCore,
1068
+ proposal: ValidatedCheckpointProposalCore,
722
1069
  proposalInfo: LogData,
723
1070
  ): Promise<CheckpointProposalValidationResult> {
724
1071
  const slot = proposal.slotNumber;
1072
+ const payloadHash = proposal.getPayloadHash();
725
1073
 
726
- // Check cache: same archive+slot means we already validated this proposal
727
- if (
728
- this.lastCheckpointValidationResult &&
729
- this.lastCheckpointValidationResult.archive.equals(proposal.archive) &&
730
- this.lastCheckpointValidationResult.slotNumber === slot
731
- ) {
1074
+ // Check cache: same signed-payload hash means we already validated this exact proposal.
1075
+ if (this.lastCheckpointValidationResult && this.lastCheckpointValidationResult.payloadHash === payloadHash) {
732
1076
  this.log.debug(`Returning cached validation result for checkpoint proposal at slot ${slot}`, proposalInfo);
733
1077
  return this.lastCheckpointValidationResult.result;
734
1078
  }
735
1079
 
736
1080
  const proposer = proposal.getSender();
1081
+ let result: CheckpointProposalValidationResult;
737
1082
  if (!proposer) {
738
1083
  this.log.warn(`Received checkpoint proposal with invalid signature for slot ${proposal.slotNumber}`);
739
- const result: CheckpointProposalValidationResult = { isValid: false, reason: 'invalid_signature' };
740
- this.lastCheckpointValidationResult = { archive: proposal.archive, slotNumber: slot, result };
741
- return result;
742
- }
743
-
744
- if (!validateFeeAssetPriceModifier(proposal.feeAssetPriceModifier)) {
1084
+ result = { isValid: false as const, reason: 'invalid_signature' };
1085
+ } else if (!validateFeeAssetPriceModifier(proposal.feeAssetPriceModifier)) {
745
1086
  this.log.warn(
746
1087
  `Received checkpoint proposal with invalid feeAssetPriceModifier ${proposal.feeAssetPriceModifier} for slot ${proposal.slotNumber}`,
747
1088
  );
748
- const result: CheckpointProposalValidationResult = { isValid: false, reason: 'invalid_fee_asset_price_modifier' };
749
- this.lastCheckpointValidationResult = { archive: proposal.archive, slotNumber: slot, result };
750
- return result;
1089
+ result = { isValid: false, reason: 'invalid_fee_asset_price_modifier' };
1090
+ } else {
1091
+ result = await this.validateCheckpointProposal(proposal, proposalInfo);
751
1092
  }
752
1093
 
753
- const result = await this.validateCheckpointProposal(proposal, proposalInfo);
754
- this.lastCheckpointValidationResult = { archive: proposal.archive, slotNumber: slot, result };
1094
+ this.lastCheckpointValidationResult = { payloadHash, result };
1095
+
1096
+ // Record the outcome on the re-execution tracker.
1097
+ const outcome = result.isValid ? ('valid' as const) : CHECKPOINT_VALIDATION_REASON_TO_OUTCOME[result.reason];
1098
+ if (outcome !== undefined) {
1099
+ this.reexecutionTracker.recordOutcome(slot, proposal.archive, outcome, result.checkpointNumber);
1100
+ }
1101
+
1102
+ // Drop tracker entries for checkpoints that have reached L1 finality.
1103
+ try {
1104
+ const tips = await this.blockSource.getL2Tips();
1105
+ const finalizedCheckpointNumber = tips.finalized.checkpoint.number;
1106
+ if (finalizedCheckpointNumber > 0) {
1107
+ this.reexecutionTracker.removeBefore(CheckpointNumber(finalizedCheckpointNumber + 1));
1108
+ }
1109
+ } catch (err) {
1110
+ this.log.error(`Error pruning reexecution tracker`, err, proposalInfo);
1111
+ }
755
1112
 
756
1113
  // Upload blobs to filestore if validation passed (fire and forget)
757
1114
  if (result.isValid) {
@@ -771,21 +1128,24 @@ export class ProposalHandler {
771
1128
  ): Promise<CheckpointProposalValidationResult> {
772
1129
  const slot = proposal.slotNumber;
773
1130
 
774
- // Timeout block syncing at the start of the next slot
775
- const config = this.checkpointsBuilder.getConfig();
776
- const nextSlotTimestampSeconds = Number(getTimestampForSlot(SlotNumber(slot + 1), config));
777
- const timeoutSeconds = Math.max(1, nextSlotTimestampSeconds - Math.floor(this.dateProvider.now() / 1000));
1131
+ // Block-sync/validation deadline = the single consensus attestation_deadline (target_slot_start + S
1132
+ // - 2E): the latest moment the proposer can submit this checkpoint and still have it land on L1 in
1133
+ // the target slot. Keeping validation/attestation alive until then lets validators keep attesting
1134
+ // right up to the proposer's real publish cutoff.
1135
+ const deadline = this.getReexecutionDeadline(slot);
778
1136
 
779
- // Wait for last block to sync by archive
780
- let lastBlockHeader;
1137
+ // Wait for last block to sync by archive. The deadline is passed to retryUntil as an absolute date so
1138
+ // the remaining budget is derived from the date provider; a deadline already in the past times out
1139
+ // after a single attempt instead of looping (the immediate-timeout semantics of the deadline overload).
1140
+ let lastBlockData;
781
1141
  try {
782
- lastBlockHeader = await retryUntil(
1142
+ lastBlockData = await retryUntil(
783
1143
  async () => {
784
1144
  await this.blockSource.syncImmediate();
785
- return this.blockSource.getBlockHeaderByArchive(proposal.archive);
1145
+ return await this.blockSource.getBlockData({ archive: proposal.archive });
786
1146
  },
787
1147
  `waiting for block with archive ${proposal.archive.toString()} for slot ${slot}`,
788
- timeoutSeconds,
1148
+ { deadline, dateProvider: this.dateProvider },
789
1149
  0.5,
790
1150
  );
791
1151
  } catch (err) {
@@ -797,22 +1157,55 @@ export class ProposalHandler {
797
1157
  return { isValid: false, reason: 'block_fetch_error' };
798
1158
  }
799
1159
 
800
- if (!lastBlockHeader) {
1160
+ if (!lastBlockData) {
801
1161
  this.log.warn(`Last block not found for checkpoint proposal`, proposalInfo);
802
1162
  return { isValid: false, reason: 'last_block_not_found' };
803
1163
  }
804
1164
 
1165
+ // Refuse to attest if the block's enclosing checkpoint has already been published to L1.
1166
+ const existingCheckpoint = await this.blockSource.getCheckpointData({ number: lastBlockData.checkpointNumber });
1167
+ if (existingCheckpoint) {
1168
+ this.log.warn(`Refusing to attest to checkpoint proposal whose checkpoint is already on L1`, {
1169
+ ...proposalInfo,
1170
+ checkpointNumber: lastBlockData.checkpointNumber,
1171
+ });
1172
+ return {
1173
+ isValid: false,
1174
+ reason: 'checkpoint_already_published',
1175
+ checkpointNumber: lastBlockData.checkpointNumber,
1176
+ };
1177
+ }
1178
+
805
1179
  // Get all full blocks for the slot and checkpoint
806
1180
  const blocks = await this.blockSource.getBlocksForSlot(slot);
807
1181
  if (blocks.length === 0) {
808
1182
  this.log.warn(`No blocks found for slot ${slot}`, proposalInfo);
809
- return { isValid: false, reason: 'no_blocks_for_slot' };
1183
+ return { isValid: false, reason: 'no_blocks_for_slot', checkpointNumber: lastBlockData.checkpointNumber };
810
1184
  }
811
1185
 
812
1186
  // Ensure the last block for this slot matches the archive in the checkpoint proposal
813
1187
  if (!blocks.at(-1)?.archive.root.equals(proposal.archive)) {
814
1188
  this.log.warn(`Last block archive mismatch for checkpoint proposal`, proposalInfo);
815
- return { isValid: false, reason: 'last_block_archive_mismatch' };
1189
+ return {
1190
+ isValid: false,
1191
+ reason: 'last_block_archive_mismatch',
1192
+ checkpointNumber: lastBlockData.checkpointNumber,
1193
+ };
1194
+ }
1195
+
1196
+ // Note this condition should never trigger, since we dont process block proposals that exceed indexWithinCheckpoint
1197
+ const maxBlocksPerCheckpoint = this.config.maxBlocksPerCheckpoint;
1198
+ if (maxBlocksPerCheckpoint !== undefined && blocks.length > maxBlocksPerCheckpoint) {
1199
+ this.log.warn(`Checkpoint proposal exceeds maxBlocksPerCheckpoint`, {
1200
+ ...proposalInfo,
1201
+ blocksInProposal: blocks.length,
1202
+ maxBlocksPerCheckpoint,
1203
+ });
1204
+ return {
1205
+ isValid: false,
1206
+ reason: 'too_many_blocks_in_checkpoint',
1207
+ checkpointNumber: lastBlockData.checkpointNumber,
1208
+ };
816
1209
  }
817
1210
 
818
1211
  this.log.debug(`Found ${blocks.length} blocks for slot ${slot}`, {
@@ -828,15 +1221,53 @@ export class ProposalHandler {
828
1221
  // Get L1-to-L2 messages for this checkpoint
829
1222
  const l1ToL2Messages = await this.l1ToL2MessageSource.getL1ToL2Messages(checkpointNumber);
830
1223
 
831
- // Collect the out hashes of all the checkpoints before this one in the same epoch
1224
+ // Collect the out hashes of all the checkpoints before this one in the same epoch.
1225
+ // See note on the analogous block-proposal site: the helper handles pipelining lag.
832
1226
  const epoch = getEpochAtSlot(slot, this.epochCache.getL1Constants());
833
- const previousCheckpointOutHashes = (await this.blockSource.getCheckpointsDataForEpoch(epoch))
834
- .filter(c => c.checkpointNumber < checkpointNumber)
835
- .map(c => c.checkpointOutHash);
1227
+ const previousCheckpointOutHashes = await getPreviousCheckpointOutHashes({
1228
+ blockSource: this.blockSource,
1229
+ epoch,
1230
+ checkpointNumber,
1231
+ l1Constants: this.epochCache.getL1Constants(),
1232
+ pipeliningEnabled: true,
1233
+ log: this.log,
1234
+ });
836
1235
 
837
- // Fork world state at the block before the first block
1236
+ // Fork world state at the block before the first block. getFork syncs world state to the parent block
1237
+ // first (see its doc): the block source (archiver) can already hold the block while world state still
1238
+ // trails it by one, and forking a not-yet-applied block throws a raw tree error that would otherwise
1239
+ // escape as an uncaught gossipsub error. We pass the parent's expected block hash so the sync detects a
1240
+ // world-state reorg (undefined for the genesis parent, where no block exists to pin). On failure we map
1241
+ // to a clean validation result rather than letting it escape.
838
1242
  const parentBlockNumber = BlockNumber(firstBlock.number - 1);
839
- await using fork = await this.checkpointsBuilder.getFork(parentBlockNumber);
1243
+ let forkResult: MerkleTreeWriteOperations;
1244
+ try {
1245
+ const parentBlockHash = (await this.blockSource.getBlockData({ number: parentBlockNumber }))?.blockHash;
1246
+ forkResult = await this.checkpointsBuilder.getFork(parentBlockNumber, parentBlockHash);
1247
+ } catch (err) {
1248
+ this.log.warn(`Failed to fork world state at block ${parentBlockNumber} for checkpoint proposal`, {
1249
+ ...proposalInfo,
1250
+ parentBlockNumber,
1251
+ err,
1252
+ });
1253
+ return { isValid: false, reason: 'world_state_not_synced', checkpointNumber };
1254
+ }
1255
+ await using fork = forkResult;
1256
+
1257
+ // Verify the fork's archive root matches the checkpoint's expected starting archive (the archive after
1258
+ // the parent block). A mismatch means world state forked from a different chain than the proposal was
1259
+ // built on (e.g. a reorg), so recomputing the checkpoint against it would be meaningless. This mirrors
1260
+ // the block-proposal re-execution check and fails fast with a clean, non-slashable result instead of a
1261
+ // confusing downstream mismatch.
1262
+ const forkArchiveRoot = new Fr((await fork.getTreeInfo(MerkleTreeId.ARCHIVE)).root);
1263
+ if (!forkArchiveRoot.equals(proposal.checkpointHeader.lastArchiveRoot)) {
1264
+ this.log.warn(`Fork archive root does not match checkpoint proposal's last archive`, {
1265
+ ...proposalInfo,
1266
+ forkArchiveRoot: forkArchiveRoot.toString(),
1267
+ expectedLastArchiveRoot: proposal.checkpointHeader.lastArchiveRoot.toString(),
1268
+ });
1269
+ return { isValid: false, reason: 'initial_archive_mismatch', checkpointNumber };
1270
+ }
840
1271
 
841
1272
  // Create checkpoint builder with all existing blocks
842
1273
  const checkpointBuilder = await this.checkpointsBuilder.openCheckpoint(
@@ -860,7 +1291,7 @@ export class ProposalHandler {
860
1291
  computed: computedCheckpoint.header.toInspect(),
861
1292
  proposal: proposal.checkpointHeader.toInspect(),
862
1293
  });
863
- return { isValid: false, reason: 'checkpoint_header_mismatch' };
1294
+ return { isValid: false, reason: 'checkpoint_header_mismatch', checkpointNumber };
864
1295
  }
865
1296
 
866
1297
  // Compare archive root with proposal
@@ -870,7 +1301,7 @@ export class ProposalHandler {
870
1301
  computed: computedCheckpoint.archive.root.toString(),
871
1302
  proposal: proposal.archive.toString(),
872
1303
  });
873
- return { isValid: false, reason: 'archive_mismatch' };
1304
+ return { isValid: false, reason: 'archive_mismatch', checkpointNumber };
874
1305
  }
875
1306
 
876
1307
  // Check that the accumulated epoch out hash matches the value in the proposal.
@@ -886,7 +1317,7 @@ export class ProposalHandler {
886
1317
  previousCheckpointOutHashes: previousCheckpointOutHashes.map(h => h.toString()),
887
1318
  ...proposalInfo,
888
1319
  });
889
- return { isValid: false, reason: 'out_hash_mismatch' };
1320
+ return { isValid: false, reason: 'out_hash_mismatch', checkpointNumber };
890
1321
  }
891
1322
 
892
1323
  // Final round of validations on the checkpoint, just in case.
@@ -900,11 +1331,12 @@ export class ProposalHandler {
900
1331
  });
901
1332
  } catch (err) {
902
1333
  this.log.warn(`Checkpoint validation failed: ${err}`, proposalInfo);
903
- return { isValid: false, reason: 'checkpoint_validation_failed' };
1334
+ return { isValid: false, reason: 'checkpoint_validation_failed', checkpointNumber };
904
1335
  }
905
1336
 
906
1337
  this.log.verbose(`Checkpoint proposal validation successful for slot ${slot}`, proposalInfo);
907
- return { isValid: true };
1338
+
1339
+ return { isValid: true, checkpointNumber };
908
1340
  }
909
1341
 
910
1342
  /** Extracts checkpoint global variables from a block. */
@@ -931,7 +1363,7 @@ export class ProposalHandler {
931
1363
  /** Uploads blobs for a checkpoint to the filestore. */
932
1364
  protected async uploadBlobsForCheckpoint(proposal: CheckpointProposalCore, proposalInfo: LogData): Promise<void> {
933
1365
  try {
934
- const lastBlockHeader = await this.blockSource.getBlockHeaderByArchive(proposal.archive);
1366
+ const lastBlockHeader = (await this.blockSource.getBlockData({ archive: proposal.archive }))?.header;
935
1367
  if (!lastBlockHeader) {
936
1368
  this.log.warn(`Failed to get last block header for blob upload`, proposalInfo);
937
1369
  return;
@@ -957,23 +1389,23 @@ export class ProposalHandler {
957
1389
  }
958
1390
 
959
1391
  /**
960
- * Derives proposed checkpoint data from validated blocks and sets it on the archiver.
961
- * Used after successful validation of a foreign proposal.
962
- * Does not retry since we already waited for the block during validation.
1392
+ * Derives proposed checkpoint data from validated blocks and sets it on the archiver, so this node can
1393
+ * pipeline building on top of the checkpoint. Does not retry, since validation already waited for the
1394
+ * last block to sync.
963
1395
  */
964
- private async setProposedCheckpointFromValidation(proposal: CheckpointProposalCore): Promise<void> {
1396
+ private async setProposedCheckpoint(proposal: CheckpointProposalCore): Promise<boolean> {
965
1397
  if (!this.archiver) {
966
- return;
1398
+ return false;
967
1399
  }
968
- const blockData = await this.blockSource.getBlockDataByArchive(proposal.archive);
1400
+ const blockData = await this.blockSource.getBlockData({ archive: proposal.archive });
969
1401
  if (!blockData) {
970
1402
  this.log.debug(`Block data not found for checkpoint proposal archive, cannot set proposed checkpoint`, {
971
1403
  archive: proposal.archive.toString(),
972
1404
  });
973
- return;
1405
+ return false;
974
1406
  }
975
1407
 
976
- await this.archiver.setProposedCheckpoint({
1408
+ await this.archiver.addProposedCheckpoint({
977
1409
  header: proposal.checkpointHeader,
978
1410
  checkpointNumber: blockData.checkpointNumber,
979
1411
  startBlock: BlockNumber(blockData.header.getBlockNumber() - blockData.indexWithinCheckpoint),
@@ -981,47 +1413,6 @@ export class ProposalHandler {
981
1413
  totalManaUsed: proposal.checkpointHeader.totalManaUsed.toBigInt(),
982
1414
  feeAssetPriceModifier: proposal.feeAssetPriceModifier,
983
1415
  });
984
- }
985
-
986
- /**
987
- * Sets proposed checkpoint from blocks for own proposals (skips full validation).
988
- * Retries fetching block data since the checkpoint proposal often arrives before the last block
989
- * finishes re-execution.
990
- */
991
- private async setProposedCheckpointFromBlocks(proposal: CheckpointProposalCore): Promise<void> {
992
- if (!this.archiver) {
993
- return;
994
- }
995
- let blockData = await this.blockSource.getBlockDataByArchive(proposal.archive);
996
-
997
- if (!blockData) {
998
- // The checkpoint proposal often arrives before the last block finishes re-execution.
999
- // Retry until we find the data or give up at the end of the slot.
1000
- const nextSlot = this.epochCache.getSlotNow() + 1;
1001
- const timeOfNextSlot = getTimestampForSlot(SlotNumber(nextSlot), await this.archiver.getL1Constants());
1002
- const timeoutSeconds = Math.max(1, Number(timeOfNextSlot) - Math.floor(this.dateProvider.now() / 1000));
1003
-
1004
- blockData = await retryUntil(
1005
- () => this.blockSource.getBlockDataByArchive(proposal.archive),
1006
- 'block data for own checkpoint proposal',
1007
- timeoutSeconds,
1008
- 0.25,
1009
- ).catch(() => undefined);
1010
- }
1011
-
1012
- if (blockData) {
1013
- await this.archiver.setProposedCheckpoint({
1014
- header: proposal.checkpointHeader,
1015
- checkpointNumber: blockData.checkpointNumber,
1016
- startBlock: BlockNumber(blockData.header.getBlockNumber() - blockData.indexWithinCheckpoint),
1017
- blockCount: blockData.indexWithinCheckpoint + 1,
1018
- totalManaUsed: proposal.checkpointHeader.totalManaUsed.toBigInt(),
1019
- feeAssetPriceModifier: proposal.feeAssetPriceModifier,
1020
- });
1021
- } else {
1022
- this.log.debug(`Block data not found for own checkpoint proposal archive, cannot set proposed checkpoint`, {
1023
- archive: proposal.archive.toString(),
1024
- });
1025
- }
1416
+ return true;
1026
1417
  }
1027
1418
  }