@aztec/aztec-node 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

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