@aztec-labs/validator-client 6.0.0-rc.3 → 6.0.0-rc.4

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.
@@ -27,7 +27,7 @@ import { DateProvider, Timer, execWithSignal } from '@aztec-labs/foundation/time
27
27
  import { isErrorClass } from '@aztec-labs/foundation/types';
28
28
  import type { P2P, PeerId } from '@aztec-labs/p2p';
29
29
  import type { BlockData, BlockHash, L2Block, L2BlockSink, L2BlockSource } from '@aztec-labs/stdlib/block';
30
- import type { CheckpointReexecutionTracker, ReexecutionOutcome } from '@aztec-labs/stdlib/checkpoint';
30
+ import type { Checkpoint, CheckpointReexecutionTracker, ReexecutionOutcome } from '@aztec-labs/stdlib/checkpoint';
31
31
  import {
32
32
  getPreviousCheckpointInboxRollingHash,
33
33
  getPreviousCheckpointOutHashes,
@@ -68,6 +68,7 @@ import {
68
68
  type InboxEndpointReader,
69
69
  checkInboxEndpoint,
70
70
  } from './checkpoint_endpoint_check.js';
71
+ import { warnCommitteeNotStable } from './committee_not_stable.js';
71
72
  import type { ValidatorMetrics } from './metrics.js';
72
73
  import {
73
74
  type StreamingBlockCheckReason,
@@ -163,6 +164,18 @@ type CheckpointInboxPrefixReason = Extract<
163
164
  'inbox_prefix_unavailable' | 'inbox_prefix_mismatch'
164
165
  >;
165
166
 
167
+ /** The L1-to-L2 messages a checkpoint consumed, read and authenticated against its header, or why they were not. */
168
+ type CheckpointConsumedMessagesResult =
169
+ | { accepted: true; messages: Fr[] }
170
+ | { accepted: false; reason: CheckpointInboxPrefixReason };
171
+
172
+ /** Whether a streaming-Inbox block check was rejected for a local-view reason that a forced archiver sync may clear. */
173
+ function isRetryableStreamingBlockRejection<T extends StreamingBlockMetadataCheckResult | StreamingBlockCheckResult>(
174
+ result: T,
175
+ ): result is Extract<T, { accepted: false }> {
176
+ return !result.accepted && isRetryableStreamingBlockCheckReason(result.reason);
177
+ }
178
+
166
179
  /**
167
180
  * Maps an archiver insert rejection to the matching per-block validation reason, or undefined when the error is not
168
181
  * an Inbox prefix rejection and must keep propagating.
@@ -250,6 +263,29 @@ export type CheckpointProposalValidationFailureCallback = (
250
263
  /** The blocks of a checkpoint proposal's slot, read in one go, and the index of the block carrying the signed archive. */
251
264
  type CheckpointBlocksSnapshot = { blocks: L2Block[]; lastBlockIndex: number };
252
265
 
266
+ /** A checkpoint proposal's blocks, from one snapshot of its slot ending at the block carrying the signed archive. */
267
+ type LocatedCheckpointBlocks = {
268
+ blocks: L2Block[];
269
+ firstBlock: L2Block;
270
+ /** The first block's checkpoint number, which every failure after the blocks are located reports. */
271
+ checkpointNumber: CheckpointNumber;
272
+ };
273
+
274
+ /** Everything the checkpoint rebuild consumes besides the fork: the arguments `openCheckpoint` takes. */
275
+ type CheckpointRebuildInputs = LocatedCheckpointBlocks & {
276
+ constants: CheckpointGlobalVariables;
277
+ l1ToL2Messages: Fr[];
278
+ previousCheckpointOutHashes: Fr[];
279
+ previousInboxRollingHash: Fr;
280
+ };
281
+
282
+ /** Distinguishes a checkpoint validation stage's failure result from the value it otherwise produces. */
283
+ function isCheckpointValidationFailure<T extends object>(
284
+ result: T | CheckpointProposalValidationFailureResult,
285
+ ): result is CheckpointProposalValidationFailureResult {
286
+ return 'isValid' in result && result.isValid === false;
287
+ }
288
+
253
289
  type CheckpointComputationResult =
254
290
  | { checkpointNumber: CheckpointNumber; reason?: undefined }
255
291
  | { checkpointNumber?: undefined; reason: 'invalid_proposal' | 'global_variables_mismatch' };
@@ -637,7 +673,7 @@ export class ProposalHandler {
637
673
  * @param archiver - Archiver reference for setting proposed checkpoints (pipelining)
638
674
  * @param getOwnValidatorAddresses - Returns current validator addresses for own-proposal detection
639
675
  */
640
- register(
676
+ public register(
641
677
  p2pClient: P2P,
642
678
  shouldReexecute: boolean,
643
679
  archiver?: Pick<Archiver, 'addProposedCheckpoint' | 'getProposedCheckpointData'>,
@@ -671,11 +707,15 @@ export class ProposalHandler {
671
707
  // which intentionally disables invalid-block slashing then.
672
708
  if (result.reason === 'checkpoint_proposal_equivocation') {
673
709
  this.markProposalEquivocation(slotNumber);
674
- } else if (
675
- isSlashableBlockProposalResult(result) &&
676
- !(await this.epochCache.isEscapeHatchOpenAtSlot(slotNumber))
677
- ) {
678
- this.markInvalidProposalSlot(slotNumber);
710
+ } else if (isSlashableBlockProposalResult(result)) {
711
+ const escapeHatch = await this.epochCache.lookupEscapeHatchAtSlot(slotNumber);
712
+ if (escapeHatch.state === 'unstable') {
713
+ warnCommitteeNotStable(this.log, escapeHatch, slotNumber, 'block proposal');
714
+ return false;
715
+ }
716
+ if (!escapeHatch.isEscapeHatchOpen) {
717
+ this.markInvalidProposalSlot(slotNumber);
718
+ }
679
719
  }
680
720
  this.log.warn(
681
721
  `Non-validator block proposal ${blockNumber} at slot ${slotNumber} failed processing with ${result.reason}`,
@@ -720,7 +760,12 @@ export class ProposalHandler {
720
760
  return undefined;
721
761
  }
722
762
 
723
- if (await this.epochCache.isEscapeHatchOpenAtSlot(proposal.slotNumber)) {
763
+ const escapeHatch = await this.epochCache.lookupEscapeHatchAtSlot(proposal.slotNumber);
764
+ if (escapeHatch.state === 'unstable') {
765
+ warnCommitteeNotStable(this.log, escapeHatch, proposal.slotNumber, 'checkpoint proposal');
766
+ return undefined;
767
+ }
768
+ if (escapeHatch.isEscapeHatchOpen) {
724
769
  this.log.warn(
725
770
  `Escape hatch open for slot ${proposal.slotNumber}, skipping checkpoint proposal validation`,
726
771
  proposalInfo,
@@ -785,7 +830,7 @@ export class ProposalHandler {
785
830
  * timeliness check) — none of those are re-applied here, and only deterministic properties of the payload
786
831
  * are validated before processing.
787
832
  */
788
- async handleBlockProposal(
833
+ public async handleBlockProposal(
789
834
  proposal: ValidatedBlockProposal,
790
835
  proposalSender: PeerId,
791
836
  shouldReexecute: boolean,
@@ -995,24 +1040,10 @@ export class ProposalHandler {
995
1040
  return { isValid: false, blockNumber, reason: 'txs_not_available' };
996
1041
  }
997
1042
 
998
- // Collect the out hashes of all the checkpoints before this one in the same epoch.
999
- // Mirror the proposer-side fallback: under pipelining the immediately-preceding cp may not
1000
- // yet be on L1, in which case the helper grafts the locally-known proposed cp's outHash.
1001
- const epoch = getEpochAtSlot(slotNumber, this.epochCache.getL1Constants());
1002
- const previousCheckpointOutHashes = await getPreviousCheckpointOutHashes({
1003
- blockSource: this.blockSource,
1004
- epoch,
1043
+ const { previousCheckpointOutHashes, previousInboxRollingHash } = await this.getCheckpointAncestryInputs(
1044
+ slotNumber,
1005
1045
  checkpointNumber,
1006
- l1Constants: this.epochCache.getL1Constants(),
1007
- pipeliningEnabled: true,
1008
- log: this.log,
1009
- });
1010
-
1011
- const previousInboxRollingHash = await getPreviousCheckpointInboxRollingHash({
1012
- blockSource: this.blockSource,
1013
- checkpointNumber,
1014
- log: this.log,
1015
- });
1046
+ );
1016
1047
 
1017
1048
  // Try re-executing the transactions in the proposal if needed
1018
1049
  let reexecutionResult;
@@ -1109,6 +1140,36 @@ export class ProposalHandler {
1109
1140
  }
1110
1141
  }
1111
1142
 
1143
+ /**
1144
+ * Given the first result of a local-view check, keeps re-running the check after forced archiver syncs while its
1145
+ * result is a local-view outcome, until it is not or the slot's attestation deadline passes. On a timeout the
1146
+ * caller's fallback decides what is reported; every caller builds it from the first result, so the reason it
1147
+ * reports is the one it saw before waiting.
1148
+ */
1149
+ private async awaitLocalViewCheck<T extends object, R extends T>(opts: {
1150
+ slot: SlotNumber;
1151
+ what: string;
1152
+ first: T;
1153
+ check: () => Promise<T>;
1154
+ isRetryable: (result: T) => result is R;
1155
+ /** Logs the "awaiting archiver sync" line; called before the wait's timer starts. */
1156
+ onWait: (first: R) => void;
1157
+ /** Logs the timeout and returns the result to report. */
1158
+ onTimeout: (first: R, waitedMs: number) => T;
1159
+ }): Promise<T> {
1160
+ const { first } = opts;
1161
+ if (!opts.isRetryable(first)) {
1162
+ return first;
1163
+ }
1164
+ opts.onWait(first);
1165
+ const timer = new Timer();
1166
+ const resolved = await this.awaitLocalSync(opts.slot, opts.what, async () => {
1167
+ const result = await opts.check();
1168
+ return opts.isRetryable(result) ? undefined : result;
1169
+ });
1170
+ return resolved ?? opts.onTimeout(first, timer.ms());
1171
+ }
1172
+
1112
1173
  /**
1113
1174
  * Re-runs `resolve` against this node's local view, forcing an archiver L1 sync before every attempt, until it
1114
1175
  * yields a value or the slot's attestation deadline passes. Returns `undefined` when the deadline had already
@@ -1281,7 +1342,7 @@ export class ProposalHandler {
1281
1342
  const parentGlobals = parentBlock.header.globalVariables;
1282
1343
 
1283
1344
  // All global variables except blockNumber should match the parent
1284
- // blockNumber naturally increments between blocks
1345
+ // blockNumber naturally increments between blocks, and the caller has already compared the slot
1285
1346
  if (!proposalGlobals.chainId.equals(parentGlobals.chainId)) {
1286
1347
  this.log.warn(`Non-first block in checkpoint has mismatched chainId`, {
1287
1348
  ...proposalInfo,
@@ -1300,15 +1361,6 @@ export class ProposalHandler {
1300
1361
  return { reason: 'global_variables_mismatch' };
1301
1362
  }
1302
1363
 
1303
- if (proposalGlobals.slotNumber !== parentGlobals.slotNumber) {
1304
- this.log.warn(`Non-first block in checkpoint has mismatched slotNumber`, {
1305
- ...proposalInfo,
1306
- proposalSlotNumber: proposalGlobals.slotNumber,
1307
- parentSlotNumber: parentGlobals.slotNumber,
1308
- });
1309
- return { reason: 'global_variables_mismatch' };
1310
- }
1311
-
1312
1364
  if (proposalGlobals.timestamp !== parentGlobals.timestamp) {
1313
1365
  this.log.warn(`Non-first block in checkpoint has mismatched timestamp`, {
1314
1366
  ...proposalInfo,
@@ -1445,36 +1497,33 @@ export class ProposalHandler {
1445
1497
  return result;
1446
1498
  };
1447
1499
 
1448
- const first = await readBundle();
1449
- if (first.accepted || !isRetryableStreamingBlockCheckReason(first.reason)) {
1450
- return first;
1451
- }
1452
-
1453
1500
  const slotNumber = proposal.slotNumber;
1454
- this.log.info(`Inbox bundle read did not confirm the signed prefix, awaiting archiver sync`, {
1455
- reason: first.reason,
1456
- ...proposalInfo,
1457
- });
1458
- const timer = new Timer();
1459
- const resolved = await this.awaitLocalSync(slotNumber, `inbox bundle for block ${blockNumber}`, async () => {
1460
- const result = await readBundle();
1461
- return !result.accepted && isRetryableStreamingBlockCheckReason(result.reason) ? undefined : result;
1501
+ return await this.awaitLocalViewCheck({
1502
+ slot: slotNumber,
1503
+ what: `inbox bundle for block ${blockNumber}`,
1504
+ first: await readBundle(),
1505
+ check: readBundle,
1506
+ isRetryable: isRetryableStreamingBlockRejection<StreamingBlockCheckResult>,
1507
+ onWait: first =>
1508
+ this.log.info(`Inbox bundle read did not confirm the signed prefix, awaiting archiver sync`, {
1509
+ reason: first.reason,
1510
+ ...proposalInfo,
1511
+ }),
1512
+ onTimeout: (first, waitedMs) => {
1513
+ this.log.warn(`Timed out reading a consistent Inbox bundle, rejecting proposal`, {
1514
+ reason: 'inbox_prefix_sync_timeout',
1515
+ firstReason: first.reason,
1516
+ // Set only when the message source failed for a reason the checks did not anticipate, rather than sync lag.
1517
+ // The latest such failure, since a later store fault says more about why this node gave up than the first
1518
+ // attempt's lag does.
1519
+ error: latestUnexpectedError,
1520
+ slot: slotNumber,
1521
+ waitedMs,
1522
+ ...proposalInfo,
1523
+ });
1524
+ return { ...first, error: latestUnexpectedError };
1525
+ },
1462
1526
  });
1463
- if (resolved === undefined) {
1464
- this.log.warn(`Timed out reading a consistent Inbox bundle, rejecting proposal`, {
1465
- reason: 'inbox_prefix_sync_timeout',
1466
- firstReason: first.reason,
1467
- // Set only when the message source failed for a reason the checks did not anticipate, rather than sync lag.
1468
- // The latest such failure, since a later store fault says more about why this node gave up than the first
1469
- // attempt's lag does.
1470
- error: latestUnexpectedError,
1471
- slot: slotNumber,
1472
- waitedMs: timer.ms(),
1473
- ...proposalInfo,
1474
- });
1475
- return { ...first, error: latestUnexpectedError };
1476
- }
1477
- return resolved;
1478
1527
  }
1479
1528
 
1480
1529
  /**
@@ -1508,34 +1557,33 @@ export class ProposalHandler {
1508
1557
  reason: first.accepted ? undefined : first.reason,
1509
1558
  });
1510
1559
  }
1511
- if (first.accepted || !isRetryableStreamingBlockCheckReason(first.reason)) {
1512
- return first;
1513
- }
1514
1560
 
1515
1561
  const slotNumber = proposal.slotNumber;
1516
1562
  const inboxRollingHash = proposal.inboxPrefixRef.inboxRollingHash.toString();
1517
- this.log.info(`Referenced Inbox prefix ${inboxRollingHash} unconfirmed locally, awaiting archiver sync`, {
1518
- reason: first.reason,
1519
- inboxRollingHash,
1520
- ...proposalInfo,
1521
- });
1522
- const timer = new Timer();
1523
- const resolved = await this.awaitLocalSync(slotNumber, `inbox prefix ${inboxRollingHash}`, async () => {
1524
- const result = await this.checkStreamingBlockMetadata(proposal, blockNumber, parentBlock);
1525
- return !result.accepted && isRetryableStreamingBlockCheckReason(result.reason) ? undefined : result;
1563
+ return await this.awaitLocalViewCheck({
1564
+ slot: slotNumber,
1565
+ what: `inbox prefix ${inboxRollingHash}`,
1566
+ first,
1567
+ check: () => this.checkStreamingBlockMetadata(proposal, blockNumber, parentBlock),
1568
+ isRetryable: isRetryableStreamingBlockRejection<StreamingBlockMetadataCheckResult>,
1569
+ onWait: firstRejection =>
1570
+ this.log.info(`Referenced Inbox prefix ${inboxRollingHash} unconfirmed locally, awaiting archiver sync`, {
1571
+ reason: firstRejection.reason,
1572
+ inboxRollingHash,
1573
+ ...proposalInfo,
1574
+ }),
1575
+ onTimeout: (firstRejection, waitedMs) => {
1576
+ this.log.warn(`Timed out waiting for Inbox prefix ${inboxRollingHash} to sync, rejecting proposal`, {
1577
+ reason: 'inbox_prefix_sync_timeout',
1578
+ firstReason: firstRejection.reason,
1579
+ slot: slotNumber,
1580
+ inboxRollingHash,
1581
+ waitedMs,
1582
+ ...proposalInfo,
1583
+ });
1584
+ return firstRejection;
1585
+ },
1526
1586
  });
1527
- if (resolved === undefined) {
1528
- this.log.warn(`Timed out waiting for Inbox prefix ${inboxRollingHash} to sync, rejecting proposal`, {
1529
- reason: 'inbox_prefix_sync_timeout',
1530
- firstReason: first.reason,
1531
- slot: slotNumber,
1532
- inboxRollingHash,
1533
- waitedMs: timer.ms(),
1534
- ...proposalInfo,
1535
- });
1536
- return first;
1537
- }
1538
- return resolved;
1539
1587
  }
1540
1588
 
1541
1589
  /**
@@ -1614,6 +1662,33 @@ export class ProposalHandler {
1614
1662
  return preBlock === undefined ? undefined : this.blockLeafCount(preBlock);
1615
1663
  }
1616
1664
 
1665
+ /**
1666
+ * The out hashes of the checkpoints before `checkpointNumber` in its epoch, and the Inbox rolling hash the parent
1667
+ * checkpoint ended at, which a checkpoint's rebuild starts from. Mirrors the proposer-side fallback: under
1668
+ * pipelining the immediately-preceding checkpoint may not be on L1 yet, in which case the helpers graft in the
1669
+ * locally-known proposed checkpoint's values.
1670
+ */
1671
+ private async getCheckpointAncestryInputs(
1672
+ slot: SlotNumber,
1673
+ checkpointNumber: CheckpointNumber,
1674
+ ): Promise<{ previousCheckpointOutHashes: Fr[]; previousInboxRollingHash: Fr }> {
1675
+ const epoch = getEpochAtSlot(slot, this.epochCache.getL1Constants());
1676
+ const previousCheckpointOutHashes = await getPreviousCheckpointOutHashes({
1677
+ blockSource: this.blockSource,
1678
+ epoch,
1679
+ checkpointNumber,
1680
+ l1Constants: this.epochCache.getL1Constants(),
1681
+ pipeliningEnabled: true,
1682
+ log: this.log,
1683
+ });
1684
+ const previousInboxRollingHash = await getPreviousCheckpointInboxRollingHash({
1685
+ blockSource: this.blockSource,
1686
+ checkpointNumber,
1687
+ log: this.log,
1688
+ });
1689
+ return { previousCheckpointOutHashes, previousInboxRollingHash };
1690
+ }
1691
+
1617
1692
  /**
1618
1693
  * Reads the ordered list of L1-to-L2 messages a checkpoint consumed across its blocks, the compact message-count
1619
1694
  * range between the parent checkpoint's consumed position and the checkpoint's last block, and confirms that the
@@ -1631,7 +1706,7 @@ export class ProposalHandler {
1631
1706
  checkpointStartTotal: bigint,
1632
1707
  lastBlockTotal: bigint,
1633
1708
  checkpointInboxRollingHash: Fr,
1634
- ): Promise<{ accepted: true; messages: Fr[] } | { accepted: false; reason: CheckpointInboxPrefixReason }> {
1709
+ ): Promise<CheckpointConsumedMessagesResult> {
1635
1710
  if (lastBlockTotal < checkpointStartTotal) {
1636
1711
  return { accepted: false, reason: 'inbox_prefix_mismatch' };
1637
1712
  }
@@ -1694,37 +1769,37 @@ export class ProposalHandler {
1694
1769
  lastBlockTotal: bigint,
1695
1770
  checkpointInboxRollingHash: Fr,
1696
1771
  proposalInfo: LogData,
1697
- ): Promise<{ accepted: true; messages: Fr[] } | { accepted: false; reason: CheckpointInboxPrefixReason }> {
1772
+ ): Promise<CheckpointConsumedMessagesResult> {
1698
1773
  const read = () =>
1699
1774
  this.readCheckpointConsumedMessages(checkpointStartTotal, lastBlockTotal, checkpointInboxRollingHash);
1700
- const first = await read();
1701
- if (first.accepted) {
1702
- return first;
1703
- }
1704
- this.log.info(`Checkpoint's consumed Inbox prefix unconfirmed locally, awaiting archiver sync`, {
1705
- reason: first.reason,
1706
- checkpointStartTotal,
1707
- lastBlockTotal,
1708
- ...proposalInfo,
1709
- });
1710
- const resolved = await this.awaitLocalSync(slot, `inbox prefix for checkpoint at slot ${slot}`, async () => {
1711
- const result = await read();
1712
- return result.accepted ? result : undefined;
1775
+ return await this.awaitLocalViewCheck({
1776
+ slot,
1777
+ what: `inbox prefix for checkpoint at slot ${slot}`,
1778
+ first: await read(),
1779
+ check: read,
1780
+ isRetryable: (result): result is Extract<CheckpointConsumedMessagesResult, { accepted: false }> =>
1781
+ !result.accepted,
1782
+ onWait: first =>
1783
+ this.log.info(`Checkpoint's consumed Inbox prefix unconfirmed locally, awaiting archiver sync`, {
1784
+ reason: first.reason,
1785
+ checkpointStartTotal,
1786
+ lastBlockTotal,
1787
+ ...proposalInfo,
1788
+ }),
1789
+ onTimeout: first => {
1790
+ this.log.warn(`Timed out waiting for the checkpoint's consumed Inbox prefix to sync, refusing to attest`, {
1791
+ reason: 'inbox_prefix_sync_timeout',
1792
+ firstReason: first.reason,
1793
+ checkpointStartTotal,
1794
+ lastBlockTotal,
1795
+ ...proposalInfo,
1796
+ });
1797
+ return first;
1798
+ },
1713
1799
  });
1714
- if (resolved === undefined) {
1715
- this.log.warn(`Timed out waiting for the checkpoint's consumed Inbox prefix to sync, refusing to attest`, {
1716
- reason: 'inbox_prefix_sync_timeout',
1717
- firstReason: first.reason,
1718
- checkpointStartTotal,
1719
- lastBlockTotal,
1720
- ...proposalInfo,
1721
- });
1722
- return first;
1723
- }
1724
- return resolved;
1725
1800
  }
1726
1801
 
1727
- async reexecuteTransactions(
1802
+ public async reexecuteTransactions(
1728
1803
  proposal: BlockProposal,
1729
1804
  blockNumber: BlockNumber,
1730
1805
  checkpointNumber: CheckpointNumber,
@@ -1853,13 +1928,14 @@ export class ProposalHandler {
1853
1928
  }
1854
1929
 
1855
1930
  /**
1856
- * Validates a checkpoint proposal, caches the result, and uploads blobs if configured.
1857
- * Returns a cached result if the same proposal (archive + slot) was already validated.
1931
+ * Validates a checkpoint proposal's content, caches the verdict by signed-payload hash and uploads blobs if
1932
+ * configured, then gates a valid verdict on the live Inbox endpoint and records the outcome on the re-execution
1933
+ * tracker. A cached valid verdict is reused only while the checkpoint's last block is still local.
1858
1934
  * Used by both the all-nodes callback (via register) and the validator client (via delegation).
1859
1935
  * Expects the proposal to have already passed p2p ingress validation (expected proposer and receive-window
1860
- * timeliness); only deterministic properties of the signed payload are checked here.
1936
+ * timeliness), which is not re-applied here.
1861
1937
  */
1862
- async handleCheckpointProposal(
1938
+ public async handleCheckpointProposal(
1863
1939
  proposal: ValidatedCheckpointProposalCore,
1864
1940
  proposalInfo: LogData,
1865
1941
  ): Promise<CheckpointProposalValidationResult> {
@@ -1899,22 +1975,7 @@ export class ProposalHandler {
1899
1975
  }
1900
1976
 
1901
1977
  if (result === undefined) {
1902
- const proposer = proposal.getSender();
1903
- if (!proposer) {
1904
- this.log.warn(`Received checkpoint proposal with invalid signature for slot ${proposal.slotNumber}`);
1905
- result = { isValid: false as const, reason: 'invalid_signature' };
1906
- } else if (!validateFeeAssetPriceModifier(proposal.feeAssetPriceModifier)) {
1907
- this.log.warn(
1908
- `Received checkpoint proposal with invalid feeAssetPriceModifier ${proposal.feeAssetPriceModifier} for slot ${proposal.slotNumber}`,
1909
- );
1910
- result = { isValid: false, reason: 'invalid_fee_asset_price_modifier' };
1911
- } else {
1912
- const validation = await this.validateCheckpointProposal(proposal, proposalInfo);
1913
- result = isSlashableCheckpointProposalResult(validation)
1914
- ? await this.checkLastBlockStillLocal(proposal, validation, proposalInfo)
1915
- : validation;
1916
- }
1917
-
1978
+ result = await this.validateCheckpointProposal(proposal, proposalInfo);
1918
1979
  this.lastCheckpointValidationResult = { payloadHash, result };
1919
1980
  if (result.isValid) {
1920
1981
  lastBlock = await this.blockSource.getBlockData({ archive: proposal.archive });
@@ -2105,15 +2166,124 @@ export class ProposalHandler {
2105
2166
  }
2106
2167
 
2107
2168
  /**
2108
- * Validates a checkpoint proposal by building the full checkpoint and comparing it with the proposal.
2109
- * @returns Validation result with isValid flag and reason if invalid.
2169
+ * The verdict on a checkpoint proposal's signed content, before the live Inbox endpoint gate: the signature and fee
2170
+ * modifier checks on the payload, then the checkpoint rebuilt from this node's blocks and compared with it. A
2171
+ * slashable rebuild verdict is demoted when the checkpoint's last block was pruned while it was computed; the two
2172
+ * payload checks do not read the local chain, so their rejections never are.
2173
+ */
2174
+ public async validateCheckpointProposal(
2175
+ proposal: CheckpointProposalCore,
2176
+ proposalInfo: LogData,
2177
+ ): Promise<CheckpointProposalValidationResult> {
2178
+ if (!proposal.getSender()) {
2179
+ this.log.warn(`Received checkpoint proposal with invalid signature for slot ${proposal.slotNumber}`);
2180
+ return { isValid: false, reason: 'invalid_signature' };
2181
+ }
2182
+ if (!validateFeeAssetPriceModifier(proposal.feeAssetPriceModifier)) {
2183
+ this.log.warn(
2184
+ `Received checkpoint proposal with invalid feeAssetPriceModifier ${proposal.feeAssetPriceModifier} for slot ${proposal.slotNumber}`,
2185
+ );
2186
+ return { isValid: false, reason: 'invalid_fee_asset_price_modifier' };
2187
+ }
2188
+ // The rebuild's fork is disposed when it returns, before the demotion reads the local chain again.
2189
+ const content = await this.validateCheckpointContent(proposal, proposalInfo);
2190
+ return isSlashableCheckpointProposalResult(content)
2191
+ ? await this.checkLastBlockStillLocal(proposal, content, proposalInfo)
2192
+ : content;
2193
+ }
2194
+
2195
+ /**
2196
+ * Validates a checkpoint proposal's content by building the full checkpoint and comparing it with the proposal. The
2197
+ * stages run in order, each on the previous one's output; the fork stays here so its disposal waits for the
2198
+ * comparisons, and so the errors its narrow `try` turns into a verdict stay next to the ones that must escape.
2110
2199
  */
2111
- async validateCheckpointProposal(
2200
+ private async validateCheckpointContent(
2112
2201
  proposal: CheckpointProposalCore,
2113
2202
  proposalInfo: LogData,
2114
2203
  ): Promise<CheckpointProposalValidationResult> {
2115
2204
  const slot = proposal.slotNumber;
2116
2205
 
2206
+ const located = await this.locateCheckpointBlocks(proposal, proposalInfo);
2207
+ if (isCheckpointValidationFailure(located)) {
2208
+ return located;
2209
+ }
2210
+ const inputs = await this.awaitCheckpointRebuildInputs(proposal, located, proposalInfo);
2211
+ if (isCheckpointValidationFailure(inputs)) {
2212
+ return inputs;
2213
+ }
2214
+ const { checkpointNumber } = inputs;
2215
+
2216
+ // Fork world state at the block before the first block. getFork syncs world state to the parent block
2217
+ // first (see its doc): the block source (archiver) can already hold the block while world state still
2218
+ // trails it by one, and forking a not-yet-applied block throws a raw tree error that would otherwise
2219
+ // escape as an uncaught gossipsub error. We pass the parent's expected block hash so the sync detects a
2220
+ // world-state reorg (undefined for the genesis parent, where no block exists to pin). On failure we map
2221
+ // to a clean validation result rather than letting it escape.
2222
+ const parentBlockNumber = BlockNumber(inputs.firstBlock.number - 1);
2223
+ let forkResult: MerkleTreeWriteOperations;
2224
+ try {
2225
+ const parentBlockHash = (await this.blockSource.getBlockData({ number: parentBlockNumber }))?.blockHash;
2226
+ forkResult = await this.checkpointsBuilder.getFork(parentBlockNumber, parentBlockHash);
2227
+ } catch (err) {
2228
+ this.log.warn(`Failed to fork world state at block ${parentBlockNumber} for checkpoint proposal`, {
2229
+ ...proposalInfo,
2230
+ parentBlockNumber,
2231
+ err,
2232
+ });
2233
+ return { isValid: false, reason: 'world_state_not_synced', checkpointNumber };
2234
+ }
2235
+ await using fork = forkResult;
2236
+
2237
+ // World state must be on the same chain as the archiver blocks being rebuilt; otherwise the rebuild would disagree
2238
+ // with an honest proposal. This is a local race (e.g. a reorg between the hash-pinned sync and the fork), never a
2239
+ // proposer offense. It mirrors the block-proposal re-execution check.
2240
+ const expectedLastArchiveRoot = inputs.firstBlock.header.lastArchive.root;
2241
+ const forkArchiveRoot = new Fr((await fork.getTreeInfo(MerkleTreeId.ARCHIVE)).root);
2242
+ if (!forkArchiveRoot.equals(expectedLastArchiveRoot)) {
2243
+ this.log.warn(`Fork archive root does not match the checkpoint's first block last archive`, {
2244
+ ...proposalInfo,
2245
+ forkArchiveRoot: forkArchiveRoot.toString(),
2246
+ expectedLastArchiveRoot: expectedLastArchiveRoot.toString(),
2247
+ });
2248
+ return { isValid: false, reason: 'initial_archive_mismatch', checkpointNumber };
2249
+ }
2250
+
2251
+ // Create checkpoint builder with all existing blocks
2252
+ const checkpointBuilder = await this.checkpointsBuilder.openCheckpoint(
2253
+ checkpointNumber,
2254
+ inputs.constants,
2255
+ proposal.feeAssetPriceModifier,
2256
+ inputs.l1ToL2Messages,
2257
+ inputs.previousCheckpointOutHashes,
2258
+ inputs.previousInboxRollingHash,
2259
+ fork,
2260
+ inputs.blocks,
2261
+ this.log.getBindings(),
2262
+ );
2263
+
2264
+ // Complete the checkpoint to get computed values
2265
+ const computedCheckpoint = await checkpointBuilder.completeCheckpoint();
2266
+
2267
+ const mismatch = this.compareRebuiltCheckpoint(computedCheckpoint, proposal, inputs, proposalInfo);
2268
+ if (mismatch) {
2269
+ return mismatch;
2270
+ }
2271
+
2272
+ this.log.verbose(`Checkpoint proposal validation successful for slot ${slot}`, proposalInfo);
2273
+
2274
+ return { isValid: true, checkpointNumber };
2275
+ }
2276
+
2277
+ /**
2278
+ * Waits for the checkpoint's blocks to sync, forcing archiver syncs until the slot's attestation deadline, then
2279
+ * rejects a checkpoint already on L1, one that leaves later blocks of its own slot out, and one over the block cap.
2280
+ */
2281
+ private async locateCheckpointBlocks(
2282
+ proposal: CheckpointProposalCore,
2283
+ proposalInfo: LogData,
2284
+ ): Promise<LocatedCheckpointBlocks | CheckpointProposalValidationFailureResult> {
2285
+ const slot = proposal.slotNumber;
2286
+
2117
2287
  // Block-sync/validation deadline = the single consensus attestation_deadline (target_slot_start + S
2118
2288
  // - 2E): the latest moment the proposer can submit this checkpoint and still have it land on L1 in
2119
2289
  // the target slot. Keeping validation/attestation alive until then lets validators keep attesting
@@ -2128,7 +2298,7 @@ export class ProposalHandler {
2128
2298
  // The deadline is passed to retryUntil as an absolute date so the remaining budget is derived from the date
2129
2299
  // provider; a deadline already in the past times out after a single attempt instead of looping (the
2130
2300
  // immediate-timeout semantics of the deadline overload).
2131
- let snapshot: CheckpointBlocksSnapshot | undefined;
2301
+ let snapshot: CheckpointBlocksSnapshot;
2132
2302
  try {
2133
2303
  snapshot = await retryUntil(
2134
2304
  async () => {
@@ -2148,10 +2318,6 @@ export class ProposalHandler {
2148
2318
  return { isValid: false, reason: 'block_fetch_error' };
2149
2319
  }
2150
2320
 
2151
- if (!snapshot) {
2152
- this.log.warn(`Last block not found for checkpoint proposal`, proposalInfo);
2153
- return { isValid: false, reason: 'last_block_not_found' };
2154
- }
2155
2321
  const { blocks, lastBlockIndex } = snapshot;
2156
2322
  const lastBlock = blocks[lastBlockIndex];
2157
2323
 
@@ -2210,13 +2376,11 @@ export class ProposalHandler {
2210
2376
  blockNumbers: blocks.map(b => b.number),
2211
2377
  });
2212
2378
 
2213
- // Get checkpoint constants from first block
2214
2379
  const firstBlock = blocks[0];
2215
- const constants = this.extractCheckpointConstants(firstBlock);
2216
2380
  const checkpointNumber = firstBlock.checkpointNumber;
2217
2381
 
2218
2382
  // The rebuild derives the header's lastArchiveRoot from the first block's lastArchive (as does the checkpoint
2219
- // circuit), so any other claimed value is an unprovable header; reject it before paying for the rebuild.
2383
+ // circuit), so any other claimed value is an unprovable header; reject it before the Inbox waits and the rebuild.
2220
2384
  const expectedLastArchiveRoot = firstBlock.header.lastArchive.root;
2221
2385
  if (!proposal.checkpointHeader.lastArchiveRoot.equals(expectedLastArchiveRoot)) {
2222
2386
  this.log.warn(`Checkpoint proposal's last archive root does not match its first block`, {
@@ -2227,6 +2391,25 @@ export class ProposalHandler {
2227
2391
  return { isValid: false, reason: 'last_archive_root_mismatch', checkpointNumber };
2228
2392
  }
2229
2393
 
2394
+ return { blocks, firstBlock, checkpointNumber };
2395
+ }
2396
+
2397
+ /**
2398
+ * Gathers what the checkpoint rebuild consumes besides the fork: the checkpoint constants, the consumed L1-to-L2
2399
+ * messages (waiting out a local sync lag through forced archiver syncs) and the parent checkpoints' out hashes and
2400
+ * Inbox rolling hash. Reads that fail unexpectedly propagate.
2401
+ */
2402
+ private async awaitCheckpointRebuildInputs(
2403
+ proposal: CheckpointProposalCore,
2404
+ located: LocatedCheckpointBlocks,
2405
+ proposalInfo: LogData,
2406
+ ): Promise<CheckpointRebuildInputs | CheckpointProposalValidationFailureResult> {
2407
+ const slot = proposal.slotNumber;
2408
+ const { blocks, firstBlock, checkpointNumber } = located;
2409
+
2410
+ // Get checkpoint constants from first block
2411
+ const constants = this.extractCheckpointConstants(firstBlock);
2412
+
2230
2413
  // The checkpoint's Inbox consumption starts at the leaf count of the block before its first block. Without that
2231
2414
  // block the consumed bundle cannot be derived; an empty bundle would make a valid proposal fail its rolling-hash
2232
2415
  // recomputation and be classified as a proposer offense, so a missing parent is a local fetch failure instead.
@@ -2259,75 +2442,26 @@ export class ProposalHandler {
2259
2442
  });
2260
2443
  return { isValid: false, reason: consumed.reason, checkpointNumber };
2261
2444
  }
2262
- const l1ToL2Messages = consumed.messages;
2263
-
2264
- // Collect the out hashes of all the checkpoints before this one in the same epoch.
2265
- // See note on the analogous block-proposal site: the helper handles pipelining lag.
2266
- const epoch = getEpochAtSlot(slot, this.epochCache.getL1Constants());
2267
- const previousCheckpointOutHashes = await getPreviousCheckpointOutHashes({
2268
- blockSource: this.blockSource,
2269
- epoch,
2270
- checkpointNumber,
2271
- l1Constants: this.epochCache.getL1Constants(),
2272
- pipeliningEnabled: true,
2273
- log: this.log,
2274
- });
2275
-
2276
- const previousInboxRollingHash = await getPreviousCheckpointInboxRollingHash({
2277
- blockSource: this.blockSource,
2278
- checkpointNumber,
2279
- log: this.log,
2280
- });
2281
-
2282
- // Fork world state at the block before the first block. getFork syncs world state to the parent block
2283
- // first (see its doc): the block source (archiver) can already hold the block while world state still
2284
- // trails it by one, and forking a not-yet-applied block throws a raw tree error that would otherwise
2285
- // escape as an uncaught gossipsub error. We pass the parent's expected block hash so the sync detects a
2286
- // world-state reorg (undefined for the genesis parent, where no block exists to pin). On failure we map
2287
- // to a clean validation result rather than letting it escape.
2288
- const parentBlockNumber = BlockNumber(firstBlock.number - 1);
2289
- let forkResult: MerkleTreeWriteOperations;
2290
- try {
2291
- const parentBlockHash = (await this.blockSource.getBlockData({ number: parentBlockNumber }))?.blockHash;
2292
- forkResult = await this.checkpointsBuilder.getFork(parentBlockNumber, parentBlockHash);
2293
- } catch (err) {
2294
- this.log.warn(`Failed to fork world state at block ${parentBlockNumber} for checkpoint proposal`, {
2295
- ...proposalInfo,
2296
- parentBlockNumber,
2297
- err,
2298
- });
2299
- return { isValid: false, reason: 'world_state_not_synced', checkpointNumber };
2300
- }
2301
- await using fork = forkResult;
2302
2445
 
2303
- // World state must be on the same chain as the archiver blocks being rebuilt; otherwise the rebuild would disagree
2304
- // with an honest proposal. This is a local race (e.g. a reorg between the hash-pinned sync and the fork), never a
2305
- // proposer offense. It mirrors the block-proposal re-execution check.
2306
- const forkArchiveRoot = new Fr((await fork.getTreeInfo(MerkleTreeId.ARCHIVE)).root);
2307
- if (!forkArchiveRoot.equals(expectedLastArchiveRoot)) {
2308
- this.log.warn(`Fork archive root does not match the checkpoint's first block last archive`, {
2309
- ...proposalInfo,
2310
- forkArchiveRoot: forkArchiveRoot.toString(),
2311
- expectedLastArchiveRoot: expectedLastArchiveRoot.toString(),
2312
- });
2313
- return { isValid: false, reason: 'initial_archive_mismatch', checkpointNumber };
2314
- }
2315
-
2316
- // Create checkpoint builder with all existing blocks
2317
- const checkpointBuilder = await this.checkpointsBuilder.openCheckpoint(
2318
- checkpointNumber,
2446
+ return {
2447
+ ...located,
2319
2448
  constants,
2320
- proposal.feeAssetPriceModifier,
2321
- l1ToL2Messages,
2322
- previousCheckpointOutHashes,
2323
- previousInboxRollingHash,
2324
- fork,
2325
- blocks,
2326
- this.log.getBindings(),
2327
- );
2449
+ l1ToL2Messages: consumed.messages,
2450
+ ...(await this.getCheckpointAncestryInputs(slot, checkpointNumber)),
2451
+ };
2452
+ }
2328
2453
 
2329
- // Complete the checkpoint to get computed values
2330
- const computedCheckpoint = await checkpointBuilder.completeCheckpoint();
2454
+ /**
2455
+ * Compares the rebuilt checkpoint with the proposal: header, archive root and epoch out hash, then the checkpoint's
2456
+ * own limits. Returns the first mismatch, or undefined when everything matches.
2457
+ */
2458
+ private compareRebuiltCheckpoint(
2459
+ computedCheckpoint: Checkpoint,
2460
+ proposal: CheckpointProposalCore,
2461
+ inputs: CheckpointRebuildInputs,
2462
+ proposalInfo: LogData,
2463
+ ): CheckpointProposalValidationFailureResult | undefined {
2464
+ const { checkpointNumber, previousCheckpointOutHashes } = inputs;
2331
2465
 
2332
2466
  // Compare checkpoint header with proposal
2333
2467
  if (!computedCheckpoint.header.equals(proposal.checkpointHeader)) {
@@ -2379,23 +2513,21 @@ export class ProposalHandler {
2379
2513
  return { isValid: false, reason: 'checkpoint_validation_failed', checkpointNumber };
2380
2514
  }
2381
2515
 
2382
- this.log.verbose(`Checkpoint proposal validation successful for slot ${slot}`, proposalInfo);
2383
-
2384
- return { isValid: true, checkpointNumber };
2516
+ return undefined;
2385
2517
  }
2386
2518
 
2387
2519
  /** Extracts checkpoint global variables from a block. */
2388
2520
  private extractCheckpointConstants(block: L2Block): CheckpointGlobalVariables {
2389
- const gv = block.header.globalVariables;
2390
- return {
2391
- chainId: gv.chainId,
2392
- version: gv.version,
2393
- slotNumber: gv.slotNumber,
2394
- timestamp: gv.timestamp,
2395
- coinbase: gv.coinbase,
2396
- feeRecipient: gv.feeRecipient,
2397
- gasFees: gv.gasFees,
2398
- };
2521
+ return pick(
2522
+ block.header.globalVariables,
2523
+ 'chainId',
2524
+ 'version',
2525
+ 'slotNumber',
2526
+ 'timestamp',
2527
+ 'coinbase',
2528
+ 'feeRecipient',
2529
+ 'gasFees',
2530
+ );
2399
2531
  }
2400
2532
 
2401
2533
  /** Triggers blob upload for a checkpoint if the blob client can upload (fire and forget). */
@@ -2457,6 +2589,7 @@ export class ProposalHandler {
2457
2589
  blockCount: blockData.indexWithinCheckpoint + 1,
2458
2590
  totalManaUsed: proposal.checkpointHeader.totalManaUsed.toBigInt(),
2459
2591
  feeAssetPriceModifier: proposal.feeAssetPriceModifier,
2592
+ signer: proposal.getSender(),
2460
2593
  });
2461
2594
  return true;
2462
2595
  }