@aztec/aztec-node 5.0.0-private.20260319 → 5.0.0-rc.1

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 (47) 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 -4
  5. package/dest/aztec-node/config.d.ts.map +1 -1
  6. package/dest/aztec-node/config.js +10 -5
  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/register_node_rpc_handlers.d.ts +10 -0
  11. package/dest/aztec-node/register_node_rpc_handlers.d.ts.map +1 -0
  12. package/dest/aztec-node/register_node_rpc_handlers.js +31 -0
  13. package/dest/aztec-node/server.d.ts +91 -100
  14. package/dest/aztec-node/server.d.ts.map +1 -1
  15. package/dest/aztec-node/server.js +1073 -492
  16. package/dest/bin/index.js +14 -9
  17. package/dest/index.d.ts +2 -1
  18. package/dest/index.d.ts.map +1 -1
  19. package/dest/index.js +1 -0
  20. package/dest/sentinel/config.d.ts +3 -2
  21. package/dest/sentinel/config.d.ts.map +1 -1
  22. package/dest/sentinel/config.js +15 -5
  23. package/dest/sentinel/factory.d.ts +4 -2
  24. package/dest/sentinel/factory.d.ts.map +1 -1
  25. package/dest/sentinel/factory.js +4 -4
  26. package/dest/sentinel/sentinel.d.ts +133 -9
  27. package/dest/sentinel/sentinel.d.ts.map +1 -1
  28. package/dest/sentinel/sentinel.js +212 -70
  29. package/dest/sentinel/store.d.ts +8 -8
  30. package/dest/sentinel/store.d.ts.map +1 -1
  31. package/dest/sentinel/store.js +25 -17
  32. package/dest/test/index.d.ts +3 -3
  33. package/dest/test/index.d.ts.map +1 -1
  34. package/package.json +27 -26
  35. package/src/aztec-node/block_response_helpers.ts +161 -0
  36. package/src/aztec-node/config.ts +23 -7
  37. package/src/aztec-node/public_data_overrides.ts +35 -0
  38. package/src/aztec-node/register_node_rpc_handlers.ts +29 -0
  39. package/src/aztec-node/server.ts +1190 -625
  40. package/src/bin/index.ts +13 -11
  41. package/src/index.ts +1 -0
  42. package/src/sentinel/README.md +103 -0
  43. package/src/sentinel/config.ts +18 -6
  44. package/src/sentinel/factory.ts +7 -4
  45. package/src/sentinel/sentinel.ts +267 -82
  46. package/src/sentinel/store.ts +26 -18
  47. 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,16 @@ 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
+
39
57
  /** Maps a validator status to its category: proposer or attestation. */
40
58
  function statusToCategory(status: ValidatorStatusInSlot): ValidatorStatusType {
41
59
  switch (status) {
@@ -47,6 +65,76 @@ function statusToCategory(status: ValidatorStatusInSlot): ValidatorStatusType {
47
65
  }
48
66
  }
49
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
+ */
50
138
  export class Sentinel extends (EventEmitter as new () => WatcherEmitter) implements L2BlockStreamEventHandler, Watcher {
51
139
  protected runningPromise: RunningPromise;
52
140
  protected blockStream!: L2BlockStream;
@@ -54,10 +142,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
54
142
 
55
143
  protected initialSlot: SlotNumber | undefined;
56
144
  protected lastProcessedSlot: SlotNumber | undefined;
57
- // 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;
58
147
  protected slotNumberToCheckpoint: Map<
59
148
  SlotNumber,
60
- { 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
+ }
61
156
  > = new Map();
62
157
 
63
158
  constructor(
@@ -65,18 +160,23 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
65
160
  protected archiver: L2BlockSource,
66
161
  protected p2p: P2PClient,
67
162
  protected store: SentinelStore,
68
- protected config: Pick<
69
- SlasherConfig,
70
- 'slashInactivityTargetPercentage' | 'slashInactivityPenalty' | 'slashInactivityConsecutiveEpochThreshold'
71
- >,
163
+ protected reexecutionTracker: CheckpointReexecutionTracker,
164
+ protected config: SentinelRuntimeConfig,
72
165
  protected logger = createLogger('node:sentinel'),
73
166
  ) {
74
167
  super();
75
- this.l2TipsStore = new L2TipsMemoryStore();
168
+ this.l2TipsStore = new L2TipsMemoryStore(archiver.getGenesisBlockHash());
76
169
  const interval = (epochCache.getL1Constants().ethereumSlotDuration * 1000) / 4;
77
170
  this.runningPromise = new RunningPromise(this.work.bind(this), logger, interval);
78
171
  }
79
172
 
173
+ private getSignatureContext(): CoordinationSignatureContext {
174
+ return {
175
+ chainId: this.config.l1ChainId,
176
+ rollupAddress: this.config.rollupAddress,
177
+ };
178
+ }
179
+
80
180
  public updateConfig(config: Partial<SlasherConfig>) {
81
181
  this.config = { ...this.config, ...config };
82
182
  }
@@ -86,14 +186,31 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
86
186
  this.runningPromise.start();
87
187
  }
88
188
 
89
- /** 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
+ */
90
196
  protected async init() {
91
- this.initialSlot = this.epochCache.getSlotNow();
197
+ this.initialSlot = await this.getCurrentSlot();
92
198
  const startingBlock = BlockNumber(await this.archiver.getBlockNumber());
93
199
  this.logger.info(`Starting validator sentinel with initial slot ${this.initialSlot} and block ${startingBlock}`);
94
200
  this.blockStream = new L2BlockStream(this.archiver, this.l2TipsStore, this, this.logger, { startingBlock });
95
201
  }
96
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
+
97
214
  public stop() {
98
215
  return this.runningPromise.stop();
99
216
  }
@@ -102,8 +219,6 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
102
219
  await this.l2TipsStore.handleBlockStreamEvent(event);
103
220
  if (event.type === 'chain-checkpointed') {
104
221
  this.handleCheckpoint(event);
105
- } else if (event.type === 'chain-proven') {
106
- await this.handleChainProven(event);
107
222
  }
108
223
  }
109
224
 
@@ -113,11 +228,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
113
228
  }
114
229
  const checkpoint = event.checkpoint;
115
230
 
116
- // 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
+ );
117
237
  this.slotNumberToCheckpoint.set(checkpoint.checkpoint.header.slotNumber, {
118
238
  checkpointNumber: checkpoint.checkpoint.number,
119
239
  archive: checkpoint.checkpoint.archive.root.toString(),
120
- attestors: getAttestationInfoFromPublishedCheckpoint(checkpoint)
240
+ proposalPayloadHash,
241
+ attestors: getAttestationInfoFromPublishedCheckpoint(checkpoint, signatureContext)
121
242
  .filter(a => a.status === 'recovered-from-signature')
122
243
  .map(a => a.address!),
123
244
  });
@@ -134,33 +255,25 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
134
255
  }
135
256
  }
136
257
 
137
- protected async handleChainProven(event: L2BlockStreamEvent) {
138
- if (event.type !== 'chain-proven') {
139
- return;
140
- }
141
- const blockNumber = event.block.number;
142
- const header = await this.archiver.getBlockHeader(blockNumber);
143
- if (!header) {
144
- this.logger.error(`Failed to get block header ${blockNumber}`);
145
- return;
146
- }
147
-
148
- // TODO(palla/slash): We should only be computing proven performance if this is
149
- // a full proof epoch and not a partial one, otherwise we'll end up with skewed stats.
150
- const epoch = getEpochAtSlot(header.getSlot(), this.epochCache.getL1Constants());
151
- this.logger.debug(`Computing proven performance for epoch ${epoch}`);
152
- const performance = await this.computeProvenPerformance(epoch);
153
- 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);
154
267
 
155
- await this.store.updateProvenPerformance(epoch, performance);
156
- await this.handleProvenPerformance(epoch, performance);
268
+ await this.store.updateEpochPerformance(epoch, performance);
269
+ await this.handleEpochPerformance(epoch, performance);
157
270
  }
158
271
 
159
- protected async computeProvenPerformance(epoch: EpochNumber): Promise<ValidatorsEpochPerformance> {
272
+ protected async computeEpochPerformance(epoch: EpochNumber): Promise<ValidatorsEpochPerformance> {
160
273
  const [fromSlot, toSlot] = getSlotRangeForEpoch(epoch, this.epochCache.getL1Constants());
161
274
  const { committee, isEscapeHatchOpen } = await this.epochCache.getCommittee(fromSlot);
162
275
  if (isEscapeHatchOpen) {
163
- this.logger.info(`Skipping proven performance for epoch ${epoch} - escape hatch is open`);
276
+ this.logger.info(`Skipping epoch performance for epoch ${epoch} - escape hatch is open`);
164
277
  return {};
165
278
  }
166
279
  if (!committee) {
@@ -202,8 +315,8 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
202
315
  return true;
203
316
  }
204
317
 
205
- // Get all historical performance for this validator
206
- 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);
207
320
 
208
321
  // Sort by epoch descending to get most recent first, keep only epochs strictly before the current one, and get the first N
209
322
  const pastEpochs = allPerformance.sort((a, b) => Number(b.epoch - a.epoch)).filter(p => p.epoch < currentEpoch);
@@ -219,16 +332,12 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
219
332
  // Check that we have at least requiredConsecutiveEpochs and that all of them are above the inactivity threshold
220
333
  return pastEpochs
221
334
  .slice(0, requiredConsecutiveEpochs)
222
- .every(p => p.missed / p.total >= this.config.slashInactivityTargetPercentage);
335
+ .every(p => (p.total === 0 ? false : p.missed / p.total >= this.config.slashInactivityTargetPercentage));
223
336
  }
224
337
 
225
- protected async handleProvenPerformance(epoch: EpochNumber, performance: ValidatorsEpochPerformance) {
226
- if (this.config.slashInactivityPenalty === 0n) {
227
- return;
228
- }
229
-
338
+ protected async handleEpochPerformance(epoch: EpochNumber, performance: ValidatorsEpochPerformance) {
230
339
  const inactiveValidators = getEntries(performance)
231
- .filter(([_, { missed, total }]) => missed / total >= this.config.slashInactivityTargetPercentage)
340
+ .filter(([_, { missed, total }]) => total > 0 && missed / total >= this.config.slashInactivityTargetPercentage)
232
341
  .map(([address]) => address);
233
342
 
234
343
  this.logger.debug(`Found ${inactiveValidators.length} inactive validators in epoch ${epoch}`, {
@@ -250,9 +359,17 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
250
359
  }));
251
360
 
252
361
  if (criminals.length > 0) {
253
- this.logger.verbose(
254
- `Identified ${criminals.length} validators to slash due to inactivity in at least ${epochThreshold} consecutive epochs`,
255
- { ...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
+ },
256
373
  );
257
374
  this.emit(WANT_TO_SLASH_EVENT, args);
258
375
  }
@@ -262,26 +379,72 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
262
379
  * Process data for two L2 slots ago.
263
380
  * Note that we do not process historical data, since we rely on p2p data for processing,
264
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.
265
386
  */
266
387
  public async work() {
267
- const currentSlot = this.epochCache.getSlotNow();
388
+ const currentSlot = await this.getCurrentSlot();
268
389
  try {
269
390
  // Manually sync the block stream to ensure we have the latest data.
270
391
  // Note we never `start` the blockstream, so it loops at the same pace as we do.
271
392
  await this.blockStream.sync();
272
393
 
273
- // 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).
274
395
  const targetSlot = await this.isReadyToProcess(currentSlot);
275
-
276
- // And process it if we are.
277
396
  if (targetSlot !== false) {
278
397
  await this.processSlot(targetSlot);
279
398
  }
399
+
400
+ // End-of-epoch evaluation (lag = sentinelEpochEndBufferSlots beyond the epoch's last slot).
401
+ await this.processEpochEnds(currentSlot);
280
402
  } catch (err) {
281
403
  this.logger.error(`Failed to process slot ${currentSlot}`, err);
282
404
  }
283
405
  }
284
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
+
285
448
  /**
286
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.
287
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.
@@ -350,49 +513,68 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
350
513
  this.lastProcessedSlot = slot;
351
514
  }
352
515
 
353
- /** 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
+ */
354
533
  protected async getSlotActivity(slot: SlotNumber, epoch: EpochNumber, proposer: EthAddress, committee: EthAddress[]) {
355
534
  this.logger.debug(`Computing stats for slot ${slot} at epoch ${epoch}`, { slot, epoch, proposer, committee });
356
535
 
357
- // Check if there is an L2 block in L1 for this L2 slot
358
-
359
- // Here we get all checkpoint attestations for the checkpoint at the given slot,
360
- // or all checkpoint attestations for all proposals in the slot if no checkpoint was mined.
361
- // We gather from both p2p (contains the ones seen on the p2p layer) and archiver
362
- // (contains the ones synced from mined checkpoints, which we may have missed from p2p).
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.
363
538
  const checkpoint = this.slotNumberToCheckpoint.get(slot);
364
- const p2pAttested = await this.p2p.getCheckpointAttestationsForSlot(slot, checkpoint?.archive);
365
- // Filter out attestations with invalid signatures
539
+ const p2pAttested = await this.p2p.getCheckpointAttestationsForSlot(slot, checkpoint?.proposalPayloadHash);
366
540
  const p2pAttestors = p2pAttested.map(a => a.getSender()).filter((s): s is EthAddress => s !== undefined);
367
541
  const attestors = new Set(
368
542
  [...p2pAttestors.map(a => a.toString()), ...(checkpoint?.attestors.map(a => a.toString()) ?? [])].filter(
369
- addr => proposer.toString() !== addr, // Exclude the proposer from the attestors
543
+ addr => proposer.toString() !== addr,
370
544
  ),
371
545
  );
372
546
 
373
- // We assume that there was a block proposal if at least one of the validators (other than the proposer) attested to it.
374
- // It could be the case that every single validator failed, and we could differentiate it by having
375
- // this node re-execute every block proposal it sees and storing it in the attestation pool.
376
- // But we'll leave that corner case out to reduce pressure on the node.
377
- // TODO(palla/slash): This breaks if a given node has more than one validator in the current committee,
378
- // since they will attest to their own proposal it even if it's not re-executable.
379
- let status: 'checkpoint-mined' | 'checkpoint-proposed' | 'checkpoint-missed' | 'blocks-missed';
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';
380
556
  if (checkpoint) {
381
557
  status = 'checkpoint-mined';
382
- } else if (attestors.size > 0) {
383
- status = 'checkpoint-proposed';
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';
384
564
  } else {
385
- // No checkpoint on L1 and no checkpoint attestations seen. Check if block proposals were sent for this slot.
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".
386
567
  const hasBlockProposals = await this.p2p.hasBlockProposalsForSlot(slot);
387
568
  status = hasBlockProposals ? 'checkpoint-missed' : 'blocks-missed';
388
569
  }
389
570
  this.logger.debug(`Checkpoint status for slot ${slot}: ${status}`, { ...checkpoint, slot });
390
571
 
391
- // Get attestors that failed their checkpoint attestation duties, but only if there was a checkpoint proposed or mined
572
+ // Missing-attestor faults only apply when we have positive evidence the proposal was valid.
573
+ const attestorsExpected = status === 'checkpoint-mined' || status === 'checkpoint-valid';
392
574
  const missedAttestors = new Set(
393
- status === 'blocks-missed' || status === 'checkpoint-missed'
394
- ? []
395
- : 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
+ : [],
396
578
  );
397
579
 
398
580
  this.logger.debug(`Retrieved ${attestors.size} attestors out of ${committee.length} for slot ${slot}`, {
@@ -436,7 +618,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
436
618
  ? fromEntries(await Promise.all(validators.map(async v => [v.toString(), await this.store.getHistory(v)])))
437
619
  : await this.store.getHistories();
438
620
 
439
- const slotNow = this.epochCache.getSlotNow();
621
+ const slotNow = await this.getCurrentSlot();
440
622
  fromSlot ??= SlotNumber(Math.max((this.lastProcessedSlot ?? slotNow) - this.store.getHistoryLength(), 0));
441
623
  toSlot ??= this.lastProcessedSlot ?? slotNow;
442
624
 
@@ -464,7 +646,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
464
646
  return undefined;
465
647
  }
466
648
 
467
- const slotNow = this.epochCache.getSlotNow();
649
+ const slotNow = await this.getCurrentSlot();
468
650
  const effectiveFromSlot =
469
651
  fromSlot ?? SlotNumber(Math.max((this.lastProcessedSlot ?? slotNow) - this.store.getHistoryLength(), 0));
470
652
  const effectiveToSlot = toSlot ?? this.lastProcessedSlot ?? slotNow;
@@ -486,7 +668,7 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
486
668
 
487
669
  return {
488
670
  validator,
489
- allTimeProvenPerformance: await this.store.getProvenPerformance(validatorAddress),
671
+ allTimeEpochPerformance: await this.store.getEpochPerformance(validatorAddress),
490
672
  lastProcessedSlot: this.lastProcessedSlot,
491
673
  initialSlot: this.initialSlot,
492
674
  slotWindow: this.store.getHistoryLength(),
@@ -501,16 +683,19 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
501
683
  ): ValidatorStats {
502
684
  let history = fromSlot ? allHistory.filter(h => BigInt(h.slot) >= fromSlot) : allHistory;
503
685
  history = toSlot ? history.filter(h => BigInt(h.slot) <= toSlot) : history;
504
- const lastProposal = history
505
- .filter(h => h.status === 'checkpoint-proposed' || h.status === 'checkpoint-mined')
506
- .at(-1);
686
+ const lastProposal = history.filter(h => h.status === 'checkpoint-valid' || h.status === 'checkpoint-mined').at(-1);
507
687
  const lastAttestation = history.filter(h => h.status === 'attestation-sent').at(-1);
508
688
  return {
509
689
  address: EthAddress.fromString(address),
510
690
  lastProposal: this.computeFromSlot(lastProposal?.slot),
511
691
  lastAttestation: this.computeFromSlot(lastAttestation?.slot),
512
692
  totalSlots: history.length,
513
- missedProposals: this.computeMissed(history, 'proposer', ['checkpoint-missed', 'blocks-missed']),
693
+ missedProposals: this.computeMissed(history, 'proposer', [
694
+ 'checkpoint-missed',
695
+ 'blocks-missed',
696
+ 'checkpoint-invalid',
697
+ 'checkpoint-unvalidated',
698
+ ]),
514
699
  missedAttestations: this.computeMissed(history, 'attestation', ['attestation-missed']),
515
700
  history,
516
701
  };