@aztec/aztec-node 0.0.1-commit.86469d5 → 0.0.1-commit.8655d4a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dest/aztec-node/block_response_helpers.d.ts +25 -0
  2. package/dest/aztec-node/block_response_helpers.d.ts.map +1 -0
  3. package/dest/aztec-node/block_response_helpers.js +112 -0
  4. package/dest/aztec-node/config.d.ts +14 -8
  5. package/dest/aztec-node/config.d.ts.map +1 -1
  6. package/dest/aztec-node/config.js +16 -8
  7. package/dest/aztec-node/public_data_overrides.d.ts +13 -0
  8. package/dest/aztec-node/public_data_overrides.d.ts.map +1 -0
  9. package/dest/aztec-node/public_data_overrides.js +21 -0
  10. package/dest/aztec-node/server.d.ts +78 -106
  11. package/dest/aztec-node/server.d.ts.map +1 -1
  12. package/dest/aztec-node/server.js +1099 -474
  13. package/dest/sentinel/config.d.ts +3 -2
  14. package/dest/sentinel/config.d.ts.map +1 -1
  15. package/dest/sentinel/config.js +15 -5
  16. package/dest/sentinel/factory.d.ts +5 -3
  17. package/dest/sentinel/factory.d.ts.map +1 -1
  18. package/dest/sentinel/factory.js +4 -4
  19. package/dest/sentinel/sentinel.d.ts +134 -10
  20. package/dest/sentinel/sentinel.d.ts.map +1 -1
  21. package/dest/sentinel/sentinel.js +252 -84
  22. package/dest/sentinel/store.d.ts +8 -8
  23. package/dest/sentinel/store.d.ts.map +1 -1
  24. package/dest/sentinel/store.js +33 -21
  25. package/dest/test/index.d.ts +3 -3
  26. package/dest/test/index.d.ts.map +1 -1
  27. package/package.json +27 -25
  28. package/src/aztec-node/block_response_helpers.ts +161 -0
  29. package/src/aztec-node/config.ts +36 -16
  30. package/src/aztec-node/public_data_overrides.ts +35 -0
  31. package/src/aztec-node/server.ts +1221 -595
  32. package/src/sentinel/README.md +103 -0
  33. package/src/sentinel/config.ts +18 -6
  34. package/src/sentinel/factory.ts +8 -5
  35. package/src/sentinel/sentinel.ts +307 -89
  36. package/src/sentinel/store.ts +35 -27
  37. package/src/test/index.ts +2 -2
@@ -1,5 +1,11 @@
1
1
  import type { EpochCache } from '@aztec/epoch-cache';
2
- import { BlockNumber, CheckpointNumber, EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
2
+ import {
3
+ BlockNumber,
4
+ CheckpointNumber,
5
+ CheckpointProposalHash,
6
+ EpochNumber,
7
+ SlotNumber,
8
+ } from '@aztec/foundation/branded-types';
3
9
  import { countWhile, filterAsync, fromEntries, getEntries, mapValues } from '@aztec/foundation/collection';
4
10
  import { EthAddress } from '@aztec/foundation/eth-address';
5
11
  import { createLogger } from '@aztec/foundation/log';
@@ -12,6 +18,7 @@ import {
12
18
  type WantToSlashArgs,
13
19
  type Watcher,
14
20
  type WatcherEmitter,
21
+ getOffenseTypeName,
15
22
  } from '@aztec/slasher';
16
23
  import type { SlasherConfig } from '@aztec/slasher/config';
17
24
  import {
@@ -21,7 +28,10 @@ import {
21
28
  type L2BlockStreamEventHandler,
22
29
  getAttestationInfoFromPublishedCheckpoint,
23
30
  } from '@aztec/stdlib/block';
31
+ import type { CheckpointReexecutionTracker } from '@aztec/stdlib/checkpoint';
32
+ import type { ChainConfig } from '@aztec/stdlib/config';
24
33
  import { getEpochAtSlot, getSlotRangeForEpoch, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
34
+ import { ConsensusPayload, type CoordinationSignatureContext } from '@aztec/stdlib/p2p';
25
35
  import type {
26
36
  SingleValidatorStats,
27
37
  ValidatorStats,
@@ -34,8 +44,97 @@ import type {
34
44
 
35
45
  import EventEmitter from 'node:events';
36
46
 
47
+ import type { SentinelConfig } from './config.js';
37
48
  import { SentinelStore } from './store.js';
38
49
 
50
+ export type SentinelRuntimeConfig = Pick<
51
+ SlasherConfig,
52
+ 'slashInactivityTargetPercentage' | 'slashInactivityPenalty' | 'slashInactivityConsecutiveEpochThreshold'
53
+ > &
54
+ Pick<SentinelConfig, 'sentinelEpochEndBufferSlots'> &
55
+ Pick<ChainConfig, 'l1ChainId' | 'rollupAddress'>;
56
+
57
+ /** Maps a validator status to its category: proposer or attestation. */
58
+ function statusToCategory(status: ValidatorStatusInSlot): ValidatorStatusType {
59
+ switch (status) {
60
+ case 'attestation-sent':
61
+ case 'attestation-missed':
62
+ return 'attestation';
63
+ default:
64
+ return 'proposer';
65
+ }
66
+ }
67
+
68
+ /**
69
+ * The Sentinel observes validator behaviour every L2 slot, classifies it into a per-slot status,
70
+ * aggregates those statuses into per-epoch performance once each epoch is fully observed, and
71
+ * emits inactivity slash payloads when a validator has been inactive for the configured number
72
+ * of consecutive epochs.
73
+ *
74
+ * ## Two cadences
75
+ *
76
+ * The sentinel runs `work()` every quarter L2 slot and drives two independent pipelines:
77
+ *
78
+ * 1. **Per-slot activity recording.** `processSlot(currentSlot - 2)` runs once per slot, with a
79
+ * two-slot lag to let P2P attestations settle and the archiver catch up. It classifies each
80
+ * committee member's behaviour for that slot via `getSlotActivity` and persists the result to
81
+ * `SentinelStore.historyMap` (sliding window of `sentinelHistoryLengthInEpochs * epochDuration`
82
+ * slots, default 24 epochs).
83
+ *
84
+ * 2. **Per-epoch evaluation.** `processEpochEnds(currentSlot)` runs every tick too. Once
85
+ * `sentinelEpochEndBufferSlots` (default 2) has elapsed past an epoch's last slot AND the
86
+ * per-slot recorder has covered that last slot, the sentinel calls `handleEpochEnd(epoch)`.
87
+ * That aggregates the slot-level statuses for the epoch into per-validator `{missed, total}`,
88
+ * persists it to `SentinelStore.epochMap` (default 2000-epoch window), and runs the slashing
89
+ * decision.
90
+ *
91
+ * Triggering per-epoch evaluation off local L2 state — rather than waiting for L1 proof
92
+ * publication — decouples slashing from prover availability.
93
+ *
94
+ * ## Six-case taxonomy in `getSlotActivity`
95
+ *
96
+ * For each slot, the sentinel assigns the proposer one of six statuses, ranked highest-confidence
97
+ * first:
98
+ *
99
+ * - `checkpoint-mined` — a checkpoint covering this slot has landed on L1
100
+ * (`slotNumberToCheckpoint` populated from `chain-checkpointed`).
101
+ * - `checkpoint-valid` — the local node re-executed a checkpoint proposal for this slot
102
+ * successfully (consulted via `CheckpointReexecutionTracker`).
103
+ * - `checkpoint-invalid` — the local node re-executed a checkpoint proposal for this slot
104
+ * and rejected it (e.g. header/archive/out-hash mismatch, limit
105
+ * breach). Proposer-fault.
106
+ * - `checkpoint-unvalidated` — the local node observed a checkpoint proposal but could not
107
+ * validate it (missing blocks/txs, timeouts). Treated as
108
+ * proposer-fault for slashing.
109
+ * - `checkpoint-missed` — block proposals seen on P2P but no checkpoint proposal at all.
110
+ * - `blocks-missed` — no block proposals seen for this slot.
111
+ *
112
+ * Missing-attestor faults are recorded only in `checkpoint-mined` and `checkpoint-valid`, where
113
+ * the local node has positive evidence the checkpoint was canonical or valid. In the other four
114
+ * cases the proposer is at fault and no attestor penalty applies.
115
+ *
116
+ * ## Re-execution tracker
117
+ *
118
+ * `CheckpointReexecutionTracker` is populated by the validator client's checkpoint proposal
119
+ * handler. Every early return in `validateCheckpointProposal` records an outcome
120
+ * (`valid` / `invalid` / `unvalidated`) keyed by slot.
121
+ *
122
+ * ## Inactivity slashing
123
+ *
124
+ * `handleEpochPerformance` filters the epoch's per-validator stats by
125
+ * `slashInactivityTargetPercentage` and then calls `checkPastInactivity` to require
126
+ * `slashInactivityConsecutiveEpochThreshold` consecutive past epochs over the same threshold
127
+ * (read from `SentinelStore.epochMap`). Only validators meeting both conditions are emitted as
128
+ * `WANT_TO_SLASH_EVENT` with `OffenseType.INACTIVITY`. The slot-level counters that feed this —
129
+ * `missedProposals` and `missedAttestations` — include the four proposer-fault statuses plus
130
+ * `attestation-missed`.
131
+ *
132
+ * ## Escape hatch
133
+ *
134
+ * If `epochCache.getCommittee(slot)` reports `isEscapeHatchOpen`, per-slot recording is skipped
135
+ * (no history entries for that slot) and per-epoch evaluation writes an empty performance map
136
+ * (no slashing).
137
+ */
39
138
  export class Sentinel extends (EventEmitter as new () => WatcherEmitter) implements L2BlockStreamEventHandler, Watcher {
40
139
  protected runningPromise: RunningPromise;
41
140
  protected blockStream!: L2BlockStream;
@@ -43,10 +142,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
43
142
 
44
143
  protected initialSlot: SlotNumber | undefined;
45
144
  protected lastProcessedSlot: SlotNumber | undefined;
46
- // eslint-disable-next-line aztec-custom/no-non-primitive-in-collections
145
+ /** Largest epoch number for which the end-of-epoch aggregator has run. */
146
+ protected lastEvaluatedEpoch: EpochNumber | undefined;
47
147
  protected slotNumberToCheckpoint: Map<
48
148
  SlotNumber,
49
- { checkpointNumber: CheckpointNumber; archive: string; attestors: EthAddress[] }
149
+ {
150
+ checkpointNumber: CheckpointNumber;
151
+ archive: string;
152
+ /** Hex keccak256 of the consensus payload bytes; used to fetch matching p2p attestations. */
153
+ proposalPayloadHash: CheckpointProposalHash;
154
+ attestors: EthAddress[];
155
+ }
50
156
  > = new Map();
51
157
 
52
158
  constructor(
@@ -54,18 +160,23 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
54
160
  protected archiver: L2BlockSource,
55
161
  protected p2p: P2PClient,
56
162
  protected store: SentinelStore,
57
- protected config: Pick<
58
- SlasherConfig,
59
- 'slashInactivityTargetPercentage' | 'slashInactivityPenalty' | 'slashInactivityConsecutiveEpochThreshold'
60
- >,
163
+ protected reexecutionTracker: CheckpointReexecutionTracker,
164
+ protected config: SentinelRuntimeConfig,
61
165
  protected logger = createLogger('node:sentinel'),
62
166
  ) {
63
167
  super();
64
- this.l2TipsStore = new L2TipsMemoryStore();
168
+ this.l2TipsStore = new L2TipsMemoryStore(archiver.getGenesisBlockHash());
65
169
  const interval = (epochCache.getL1Constants().ethereumSlotDuration * 1000) / 4;
66
170
  this.runningPromise = new RunningPromise(this.work.bind(this), logger, interval);
67
171
  }
68
172
 
173
+ private getSignatureContext(): CoordinationSignatureContext {
174
+ return {
175
+ chainId: this.config.l1ChainId,
176
+ rollupAddress: this.config.rollupAddress,
177
+ };
178
+ }
179
+
69
180
  public updateConfig(config: Partial<SlasherConfig>) {
70
181
  this.config = { ...this.config, ...config };
71
182
  }
@@ -75,14 +186,31 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
75
186
  this.runningPromise.start();
76
187
  }
77
188
 
78
- /** Loads initial slot and initializes blockstream. We will not process anything at or before the initial slot. */
189
+ /**
190
+ * Loads initial slot and initializes blockstream. We will not process anything at or before
191
+ * the initial slot. Floors at the archiver's synced L2 slot so the sentinel keeps making
192
+ * forward progress when L1 is advancing but L2 has no activity (the synced slot is driven by
193
+ * L1 sync, not by L2 blocks). Falls back to the wallclock if the archiver isn't ready yet
194
+ * (cold start).
195
+ */
79
196
  protected async init() {
80
- this.initialSlot = this.epochCache.getEpochAndSlotNow().slot;
197
+ this.initialSlot = await this.getCurrentSlot();
81
198
  const startingBlock = BlockNumber(await this.archiver.getBlockNumber());
82
199
  this.logger.info(`Starting validator sentinel with initial slot ${this.initialSlot} and block ${startingBlock}`);
83
200
  this.blockStream = new L2BlockStream(this.archiver, this.l2TipsStore, this, this.logger, { startingBlock });
84
201
  }
85
202
 
203
+ /**
204
+ * Returns the L2 slot the sentinel should treat as "current": the archiver's last fully
205
+ * synced L2 slot, falling back to the wallclock slot when the archiver isn't ready yet
206
+ * (cold start). Anchoring to the synced slot keeps timing arithmetic (initial floor,
207
+ * per-slot lag, end-of-epoch buffer, stats-range fallback) from speculating ahead of where
208
+ * L1 actually is.
209
+ */
210
+ protected async getCurrentSlot(): Promise<SlotNumber> {
211
+ return (await this.archiver.getSyncedL2SlotNumber()) ?? this.epochCache.getSlotNow();
212
+ }
213
+
86
214
  public stop() {
87
215
  return this.runningPromise.stop();
88
216
  }
@@ -91,8 +219,6 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
91
219
  await this.l2TipsStore.handleBlockStreamEvent(event);
92
220
  if (event.type === 'chain-checkpointed') {
93
221
  this.handleCheckpoint(event);
94
- } else if (event.type === 'chain-proven') {
95
- await this.handleChainProven(event);
96
222
  }
97
223
  }
98
224
 
@@ -102,11 +228,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
102
228
  }
103
229
  const checkpoint = event.checkpoint;
104
230
 
105
- // Store mapping from slot to archive, checkpoint number, and attestors
231
+ // Store mapping from slot to archive, checkpoint number, attestors, and the consensus payload
232
+ // hash (used to query matching p2p attestations regardless of feeAssetPriceModifier variants).
233
+ const signatureContext = this.getSignatureContext();
234
+ const proposalPayloadHash = CheckpointProposalHash.fromBuffer(
235
+ ConsensusPayload.fromCheckpoint(checkpoint.checkpoint, signatureContext).getPayloadHash(),
236
+ );
106
237
  this.slotNumberToCheckpoint.set(checkpoint.checkpoint.header.slotNumber, {
107
238
  checkpointNumber: checkpoint.checkpoint.number,
108
239
  archive: checkpoint.checkpoint.archive.root.toString(),
109
- attestors: getAttestationInfoFromPublishedCheckpoint(checkpoint)
240
+ proposalPayloadHash,
241
+ attestors: getAttestationInfoFromPublishedCheckpoint(checkpoint, signatureContext)
110
242
  .filter(a => a.status === 'recovered-from-signature')
111
243
  .map(a => a.address!),
112
244
  });
@@ -123,31 +255,27 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
123
255
  }
124
256
  }
125
257
 
126
- protected async handleChainProven(event: L2BlockStreamEvent) {
127
- if (event.type !== 'chain-proven') {
128
- return;
129
- }
130
- const blockNumber = event.block.number;
131
- const block = await this.archiver.getL2Block(blockNumber);
132
- if (!block) {
133
- this.logger.error(`Failed to get block ${blockNumber}`, { block });
134
- return;
135
- }
136
-
137
- // TODO(palla/slash): We should only be computing proven performance if this is
138
- // a full proof epoch and not a partial one, otherwise we'll end up with skewed stats.
139
- const epoch = getEpochAtSlot(block.header.getSlot(), this.epochCache.getL1Constants());
140
- this.logger.debug(`Computing proven performance for epoch ${epoch}`);
141
- const performance = await this.computeProvenPerformance(epoch);
142
- this.logger.info(`Computed proven performance for epoch ${epoch}`, performance);
258
+ /**
259
+ * Called once per epoch, after the configured end-of-epoch buffer has elapsed beyond the
260
+ * epoch's last slot. Computes per-epoch performance from the slot-level history collected
261
+ * by `processSlot` and emits any inactivity slash payloads.
262
+ */
263
+ protected async handleEpochEnd(epoch: EpochNumber) {
264
+ this.logger.debug(`Computing epoch performance for epoch ${epoch}`);
265
+ const performance = await this.computeEpochPerformance(epoch);
266
+ this.logger.info(`Computed epoch performance for epoch ${epoch}`, performance);
143
267
 
144
- await this.store.updateProvenPerformance(epoch, performance);
145
- await this.handleProvenPerformance(epoch, performance);
268
+ await this.store.updateEpochPerformance(epoch, performance);
269
+ await this.handleEpochPerformance(epoch, performance);
146
270
  }
147
271
 
148
- protected async computeProvenPerformance(epoch: EpochNumber): Promise<ValidatorsEpochPerformance> {
272
+ protected async computeEpochPerformance(epoch: EpochNumber): Promise<ValidatorsEpochPerformance> {
149
273
  const [fromSlot, toSlot] = getSlotRangeForEpoch(epoch, this.epochCache.getL1Constants());
150
- const { committee } = await this.epochCache.getCommittee(fromSlot);
274
+ const { committee, isEscapeHatchOpen } = await this.epochCache.getCommittee(fromSlot);
275
+ if (isEscapeHatchOpen) {
276
+ this.logger.info(`Skipping epoch performance for epoch ${epoch} - escape hatch is open`);
277
+ return {};
278
+ }
151
279
  if (!committee) {
152
280
  this.logger.trace(`No committee found for slot ${fromSlot}`);
153
281
  return {};
@@ -187,8 +315,8 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
187
315
  return true;
188
316
  }
189
317
 
190
- // Get all historical performance for this validator
191
- const allPerformance = await this.store.getProvenPerformance(validator);
318
+ // Get all historical per-epoch performance for this validator
319
+ const allPerformance = await this.store.getEpochPerformance(validator);
192
320
 
193
321
  // Sort by epoch descending to get most recent first, keep only epochs strictly before the current one, and get the first N
194
322
  const pastEpochs = allPerformance.sort((a, b) => Number(b.epoch - a.epoch)).filter(p => p.epoch < currentEpoch);
@@ -204,16 +332,12 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
204
332
  // Check that we have at least requiredConsecutiveEpochs and that all of them are above the inactivity threshold
205
333
  return pastEpochs
206
334
  .slice(0, requiredConsecutiveEpochs)
207
- .every(p => p.missed / p.total >= this.config.slashInactivityTargetPercentage);
335
+ .every(p => (p.total === 0 ? false : p.missed / p.total >= this.config.slashInactivityTargetPercentage));
208
336
  }
209
337
 
210
- protected async handleProvenPerformance(epoch: EpochNumber, performance: ValidatorsEpochPerformance) {
211
- if (this.config.slashInactivityPenalty === 0n) {
212
- return;
213
- }
214
-
338
+ protected async handleEpochPerformance(epoch: EpochNumber, performance: ValidatorsEpochPerformance) {
215
339
  const inactiveValidators = getEntries(performance)
216
- .filter(([_, { missed, total }]) => missed / total >= this.config.slashInactivityTargetPercentage)
340
+ .filter(([_, { missed, total }]) => total > 0 && missed / total >= this.config.slashInactivityTargetPercentage)
217
341
  .map(([address]) => address);
218
342
 
219
343
  this.logger.debug(`Found ${inactiveValidators.length} inactive validators in epoch ${epoch}`, {
@@ -235,9 +359,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
235
359
  }));
236
360
 
237
361
  if (criminals.length > 0) {
238
- this.logger.verbose(
239
- `Identified ${criminals.length} validators to slash due to inactivity in at least ${epochThreshold} consecutive epochs`,
240
- { ...args, epochThreshold },
362
+ this.logger.info(
363
+ `Identified ${criminals.length} inactivity offenses in at least ${epochThreshold} consecutive epochs`,
364
+ {
365
+ offenses: args.map(arg => ({
366
+ validator: arg.validator.toString(),
367
+ amount: arg.amount,
368
+ offenseType: getOffenseTypeName(arg.offenseType),
369
+ epochOrSlot: arg.epochOrSlot,
370
+ })),
371
+ epochThreshold,
372
+ },
241
373
  );
242
374
  this.emit(WANT_TO_SLASH_EVENT, args);
243
375
  }
@@ -247,26 +379,72 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
247
379
  * Process data for two L2 slots ago.
248
380
  * Note that we do not process historical data, since we rely on p2p data for processing,
249
381
  * and we don't have that data if we were offline during the period.
382
+ *
383
+ * `currentSlot` is anchored to the archiver's last synced L2 slot rather than the wallclock,
384
+ * so the per-slot lag (`isReadyToProcess`) and the end-of-epoch buffer (`processEpochEnds`)
385
+ * advance with archiver.
250
386
  */
251
387
  public async work() {
252
- const { slot: currentSlot } = this.epochCache.getEpochAndSlotNow();
388
+ const currentSlot = await this.getCurrentSlot();
253
389
  try {
254
390
  // Manually sync the block stream to ensure we have the latest data.
255
391
  // Note we never `start` the blockstream, so it loops at the same pace as we do.
256
392
  await this.blockStream.sync();
257
393
 
258
- // Check if we are ready to process data for two L2 slots ago.
394
+ // Per-slot activity recording (lag = 2 slots for P2P attestation settlement).
259
395
  const targetSlot = await this.isReadyToProcess(currentSlot);
260
-
261
- // And process it if we are.
262
396
  if (targetSlot !== false) {
263
397
  await this.processSlot(targetSlot);
264
398
  }
399
+
400
+ // End-of-epoch evaluation (lag = sentinelEpochEndBufferSlots beyond the epoch's last slot).
401
+ await this.processEpochEnds(currentSlot);
265
402
  } catch (err) {
266
403
  this.logger.error(`Failed to process slot ${currentSlot}`, err);
267
404
  }
268
405
  }
269
406
 
407
+ /**
408
+ * After the configured buffer has elapsed past an epoch's last slot, runs the end-of-epoch
409
+ * aggregator for that epoch. Catches up if multiple epochs become eligible at once.
410
+ */
411
+ protected async processEpochEnds(currentSlot: SlotNumber) {
412
+ const constants = this.epochCache.getL1Constants();
413
+ const buffer = this.config.sentinelEpochEndBufferSlots;
414
+ if (currentSlot < buffer) {
415
+ return;
416
+ }
417
+ if (this.initialSlot === undefined) {
418
+ return;
419
+ }
420
+
421
+ // We can close epoch E iff:
422
+ // - the per-slot recorder has covered the epoch's last slot (lastProcessedSlot ≥ toSlot(E))
423
+ // - the buffer has elapsed past the epoch's last slot (currentSlot − buffer ≥ toSlot(E))
424
+ // - the epoch is not in the past relative to when the sentinel started (toSlot(E) > initialSlot)
425
+ if (this.lastProcessedSlot === undefined) {
426
+ return;
427
+ }
428
+ const slotForBuffer = SlotNumber(currentSlot - buffer);
429
+
430
+ // First eligible epoch to close is the one after lastEvaluatedEpoch, or the epoch containing
431
+ // the initial slot if we haven't evaluated any yet (the initialSlot epoch may be partial — we
432
+ // don't try to evaluate it, we start from initialSlot's epoch + 1).
433
+ const startEpoch =
434
+ this.lastEvaluatedEpoch !== undefined
435
+ ? EpochNumber(this.lastEvaluatedEpoch + 1)
436
+ : EpochNumber(getEpochAtSlot(this.initialSlot, constants) + 1);
437
+
438
+ for (let epoch = startEpoch; ; epoch = EpochNumber(epoch + 1)) {
439
+ const [, toSlot] = getSlotRangeForEpoch(epoch, constants);
440
+ if (toSlot > this.lastProcessedSlot || toSlot > slotForBuffer) {
441
+ break;
442
+ }
443
+ await this.handleEpochEnd(epoch);
444
+ this.lastEvaluatedEpoch = epoch;
445
+ }
446
+ }
447
+
270
448
  /**
271
449
  * Check if we are ready to process data for two L2 slots ago, so we allow plenty of time for p2p to process all in-flight attestations.
272
450
  * We also don't move past the archiver last synced L2 slot, as we don't want to process data that is not yet available.
@@ -294,9 +472,9 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
294
472
  return false;
295
473
  }
296
474
 
297
- const archiverSlot = await this.archiver.getL2SlotNumber();
298
- if (archiverSlot === undefined || archiverSlot < targetSlot) {
299
- this.logger.debug(`Waiting for archiver to sync with L2 slot ${targetSlot}`, { archiverSlot, targetSlot });
475
+ const syncedSlot = await this.archiver.getSyncedL2SlotNumber();
476
+ if (syncedSlot === undefined || syncedSlot < targetSlot) {
477
+ this.logger.debug(`Waiting for archiver to sync with L2 slot ${targetSlot}`, { syncedSlot, targetSlot });
300
478
  return false;
301
479
  }
302
480
 
@@ -316,7 +494,12 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
316
494
  * and updates overall stats.
317
495
  */
318
496
  protected async processSlot(slot: SlotNumber) {
319
- const { epoch, seed, committee } = await this.epochCache.getCommittee(slot);
497
+ const { epoch, seed, committee, isEscapeHatchOpen } = await this.epochCache.getCommittee(slot);
498
+ if (isEscapeHatchOpen) {
499
+ this.logger.info(`Skipping slot ${slot} at epoch ${epoch} - escape hatch is open`);
500
+ this.lastProcessedSlot = slot;
501
+ return;
502
+ }
320
503
  if (!committee || committee.length === 0) {
321
504
  this.logger.trace(`No committee found for slot ${slot} at epoch ${epoch}`);
322
505
  this.lastProcessedSlot = slot;
@@ -330,46 +513,74 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
330
513
  this.lastProcessedSlot = slot;
331
514
  }
332
515
 
333
- /** Computes activity for a given slot. */
516
+ /**
517
+ * Computes activity for a given slot using the six-case taxonomy.
518
+ *
519
+ * Proposer status:
520
+ * - case 6 `checkpoint-mined` — a checkpoint covering this slot has landed on L1.
521
+ * - case 5 `checkpoint-valid` — the local node re-executed a checkpoint proposal for this
522
+ * slot successfully.
523
+ * - case 4 `checkpoint-invalid` — the local node re-executed a checkpoint proposal for this
524
+ * slot and rejected it.
525
+ * - case 3 `checkpoint-unvalidated` — the local node observed a checkpoint proposal for this
526
+ * slot but could not validate it (missing data, timeouts).
527
+ * - case 2 `checkpoint-missed` — block proposals seen on P2P but no checkpoint proposal.
528
+ * - case 1 `blocks-missed` — no block proposals seen for this slot.
529
+ *
530
+ * Missing-attestor penalties apply only in cases 5 and 6, where the local node has positive
531
+ * evidence the checkpoint was valid or has been canonicalised on L1.
532
+ */
334
533
  protected async getSlotActivity(slot: SlotNumber, epoch: EpochNumber, proposer: EthAddress, committee: EthAddress[]) {
335
534
  this.logger.debug(`Computing stats for slot ${slot} at epoch ${epoch}`, { slot, epoch, proposer, committee });
336
535
 
337
- // Check if there is an L2 block in L1 for this L2 slot
338
-
339
- // Here we get all attestations for the block mined at the given slot,
340
- // or all attestations for all proposals in the slot if no block was mined.
341
- // We gather from both p2p (contains the ones seen on the p2p layer) and archiver
342
- // (contains the ones synced from mined blocks, which we may have missed from p2p).
343
- const block = this.slotNumberToCheckpoint.get(slot);
344
- const p2pAttested = await this.p2p.getCheckpointAttestationsForSlot(slot, block?.archive);
345
- // Filter out attestations with invalid signatures
536
+ // Gather attestors from both p2p (live attestations) and the archiver (signers on the
537
+ // checkpoint if one has landed on L1). Used regardless of which case applies.
538
+ const checkpoint = this.slotNumberToCheckpoint.get(slot);
539
+ const p2pAttested = await this.p2p.getCheckpointAttestationsForSlot(slot, checkpoint?.proposalPayloadHash);
346
540
  const p2pAttestors = p2pAttested.map(a => a.getSender()).filter((s): s is EthAddress => s !== undefined);
347
541
  const attestors = new Set(
348
- [...p2pAttestors.map(a => a.toString()), ...(block?.attestors.map(a => a.toString()) ?? [])].filter(
349
- addr => proposer.toString() !== addr, // Exclude the proposer from the attestors
542
+ [...p2pAttestors.map(a => a.toString()), ...(checkpoint?.attestors.map(a => a.toString()) ?? [])].filter(
543
+ addr => proposer.toString() !== addr,
350
544
  ),
351
545
  );
352
546
 
353
- // We assume that there was a block proposal if at least one of the validators (other than the proposer) attested to it.
354
- // It could be the case that every single validator failed, and we could differentiate it by having
355
- // this node re-execute every block proposal it sees and storing it in the attestation pool.
356
- // But we'll leave that corner case out to reduce pressure on the node.
357
- // TODO(palla/slash): This breaks if a given node has more than one validator in the current committee,
358
- // since they will attest to their own proposal it even if it's not re-executable.
359
- const blockStatus = block ? 'mined' : attestors.size > 0 ? 'proposed' : 'missed';
360
- this.logger.debug(`Block for slot ${slot} was ${blockStatus}`, { ...block, slot });
547
+ // Determine the proposer status from the six-case taxonomy.
548
+ const reexecutionOutcome = this.reexecutionTracker.getOutcomeForSlot(slot);
549
+ let status:
550
+ | 'checkpoint-mined'
551
+ | 'checkpoint-valid'
552
+ | 'checkpoint-invalid'
553
+ | 'checkpoint-unvalidated'
554
+ | 'checkpoint-missed'
555
+ | 'blocks-missed';
556
+ if (checkpoint) {
557
+ status = 'checkpoint-mined';
558
+ } else if (reexecutionOutcome === 'valid') {
559
+ status = 'checkpoint-valid';
560
+ } else if (reexecutionOutcome === 'invalid') {
561
+ status = 'checkpoint-invalid';
562
+ } else if (reexecutionOutcome === 'unvalidated') {
563
+ status = 'checkpoint-unvalidated';
564
+ } else {
565
+ // No L1 checkpoint, no local re-execution outcome for this slot. Distinguish "proposer
566
+ // sent block proposals but never made a checkpoint" from "proposer sent nothing".
567
+ const hasBlockProposals = await this.p2p.hasBlockProposalsForSlot(slot);
568
+ status = hasBlockProposals ? 'checkpoint-missed' : 'blocks-missed';
569
+ }
570
+ this.logger.debug(`Checkpoint status for slot ${slot}: ${status}`, { ...checkpoint, slot });
361
571
 
362
- // Get attestors that failed their duties for this block, but only if there was a block proposed
572
+ // Missing-attestor faults only apply when we have positive evidence the proposal was valid.
573
+ const attestorsExpected = status === 'checkpoint-mined' || status === 'checkpoint-valid';
363
574
  const missedAttestors = new Set(
364
- blockStatus === 'missed'
365
- ? []
366
- : committee.filter(v => !attestors.has(v.toString()) && !proposer.equals(v)).map(v => v.toString()),
575
+ attestorsExpected
576
+ ? committee.filter(v => !attestors.has(v.toString()) && !proposer.equals(v)).map(v => v.toString())
577
+ : [],
367
578
  );
368
579
 
369
580
  this.logger.debug(`Retrieved ${attestors.size} attestors out of ${committee.length} for slot ${slot}`, {
370
- blockStatus,
581
+ status,
371
582
  proposer: proposer.toString(),
372
- ...block,
583
+ ...checkpoint,
373
584
  slot,
374
585
  attestors: [...attestors],
375
586
  missedAttestors: [...missedAttestors],
@@ -379,7 +590,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
379
590
  // Compute the status for each validator in the committee
380
591
  const statusFor = (who: `0x${string}`): ValidatorStatusInSlot | undefined => {
381
592
  if (who === proposer.toString()) {
382
- return `block-${blockStatus}`;
593
+ return status;
383
594
  } else if (attestors.has(who)) {
384
595
  return 'attestation-sent';
385
596
  } else if (missedAttestors.has(who)) {
@@ -407,7 +618,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
407
618
  ? fromEntries(await Promise.all(validators.map(async v => [v.toString(), await this.store.getHistory(v)])))
408
619
  : await this.store.getHistories();
409
620
 
410
- const slotNow = this.epochCache.getEpochAndSlotNow().slot;
621
+ const slotNow = await this.getCurrentSlot();
411
622
  fromSlot ??= SlotNumber(Math.max((this.lastProcessedSlot ?? slotNow) - this.store.getHistoryLength(), 0));
412
623
  toSlot ??= this.lastProcessedSlot ?? slotNow;
413
624
 
@@ -435,7 +646,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
435
646
  return undefined;
436
647
  }
437
648
 
438
- const slotNow = this.epochCache.getEpochAndSlotNow().slot;
649
+ const slotNow = await this.getCurrentSlot();
439
650
  const effectiveFromSlot =
440
651
  fromSlot ?? SlotNumber(Math.max((this.lastProcessedSlot ?? slotNow) - this.store.getHistoryLength(), 0));
441
652
  const effectiveToSlot = toSlot ?? this.lastProcessedSlot ?? slotNow;
@@ -457,7 +668,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
457
668
 
458
669
  return {
459
670
  validator,
460
- allTimeProvenPerformance: await this.store.getProvenPerformance(validatorAddress),
671
+ allTimeEpochPerformance: await this.store.getEpochPerformance(validatorAddress),
461
672
  lastProcessedSlot: this.lastProcessedSlot,
462
673
  initialSlot: this.initialSlot,
463
674
  slotWindow: this.store.getHistoryLength(),
@@ -472,14 +683,19 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
472
683
  ): ValidatorStats {
473
684
  let history = fromSlot ? allHistory.filter(h => BigInt(h.slot) >= fromSlot) : allHistory;
474
685
  history = toSlot ? history.filter(h => BigInt(h.slot) <= toSlot) : history;
475
- const lastProposal = history.filter(h => h.status === 'block-proposed' || h.status === 'block-mined').at(-1);
686
+ const lastProposal = history.filter(h => h.status === 'checkpoint-valid' || h.status === 'checkpoint-mined').at(-1);
476
687
  const lastAttestation = history.filter(h => h.status === 'attestation-sent').at(-1);
477
688
  return {
478
689
  address: EthAddress.fromString(address),
479
690
  lastProposal: this.computeFromSlot(lastProposal?.slot),
480
691
  lastAttestation: this.computeFromSlot(lastAttestation?.slot),
481
692
  totalSlots: history.length,
482
- missedProposals: this.computeMissed(history, 'block', ['block-missed']),
693
+ missedProposals: this.computeMissed(history, 'proposer', [
694
+ 'checkpoint-missed',
695
+ 'blocks-missed',
696
+ 'checkpoint-invalid',
697
+ 'checkpoint-unvalidated',
698
+ ]),
483
699
  missedAttestations: this.computeMissed(history, 'attestation', ['attestation-missed']),
484
700
  history,
485
701
  };
@@ -487,10 +703,12 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
487
703
 
488
704
  protected computeMissed(
489
705
  history: ValidatorStatusHistory,
490
- computeOverPrefix: ValidatorStatusType | undefined,
706
+ computeOverCategory: ValidatorStatusType | undefined,
491
707
  filter: ValidatorStatusInSlot[],
492
708
  ) {
493
- const relevantHistory = history.filter(h => !computeOverPrefix || h.status.startsWith(computeOverPrefix));
709
+ const relevantHistory = history.filter(
710
+ h => !computeOverCategory || statusToCategory(h.status) === computeOverCategory,
711
+ );
494
712
  const filteredHistory = relevantHistory.filter(h => filter.includes(h.status));
495
713
  return {
496
714
  currentStreak: countWhile([...relevantHistory].reverse(), h => filter.includes(h.status)),