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

package/src/bin/index.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env -S node --no-warnings
+import {
+  type NamespacedApiHandlers,
+  createNamespacedSafeJsonRpcServer,
+  startHttpRpcServer,
+} from '@aztec/foundation/json-rpc/server';
 import { createLogger } from '@aztec/foundation/log';
-import { AztecNodeApiSchema } from '@aztec/stdlib/interfaces/client';
-import { createTracedJsonRpcServer } from '@aztec/telemetry-client';
+import { getOtelJsonRpcPropagationMiddleware } from '@aztec/telemetry-client';
 
-import http from 'http';
-
-import { type AztecNodeConfig, AztecNodeService, getConfigEnvVars } from '../index.js';
+import { type AztecNodeConfig, AztecNodeService, getConfigEnvVars, registerAztecNodeRpcHandlers } from '../index.js';
 
 const { AZTEC_NODE_PORT = 8081, API_PREFIX = '' } = process.env;
 
@@ -39,12 +41,12 @@ async function main() {
   // eslint-disable-next-line @typescript-eslint/no-misused-promises
   process.once('SIGTERM', shutdown);
 
-  const rpcServer = createTracedJsonRpcServer(aztecNode, AztecNodeApiSchema);
-  const app = rpcServer.getApp(API_PREFIX);
-
-  // eslint-disable-next-line @typescript-eslint/no-misused-promises
-  const httpServer = http.createServer(app.callback());
-  httpServer.listen(+AZTEC_NODE_PORT);
+  const services: NamespacedApiHandlers = {};
+  registerAztecNodeRpcHandlers(aztecNode, services);
+  const rpcServer = createNamespacedSafeJsonRpcServer(services, {
+    middlewares: [getOtelJsonRpcPropagationMiddleware()],
+  });
+  await startHttpRpcServer(rpcServer, { port: +AZTEC_NODE_PORT, apiPrefix: API_PREFIX });
   logger.info(`Aztec Node JSON-RPC Server listening on port ${AZTEC_NODE_PORT}`);
 }
 

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './aztec-node/config.js';
+export * from './aztec-node/register_node_rpc_handlers.js';
 export * from './aztec-node/server.js';

package/src/sentinel/README.md

@@ -0,0 +1,103 @@
+# Sentinel
+
+The Sentinel watches every committee member's behaviour each L2 slot, aggregates it into per-epoch performance once each epoch is fully observed, and emits inactivity slash payloads to the slasher.
+
+## Responsibilities
+
+- Classify per-slot proposer/attestor behaviour from local node observations.
+- Persist a sliding window of per-slot history per validator.
+- Roll up that history into per-epoch performance after each epoch ends.
+- Decide which validators have been inactive for `slashInactivityConsecutiveEpochThreshold` consecutive epochs and emit `WANT_TO_SLASH_EVENT` with `OffenseType.INACTIVITY`.
+- Expose validator stats to RPC consumers (`getValidatorStats`, `computeStats`).
+
+The sentinel is one of several watchers registered with the slasher; it does not vote or publish to L1 itself.
+
+## Inputs
+
+| Source | What it provides |
+|---|---|
+| `EpochCache` | Slot/epoch helpers, committee + proposer for a slot, escape-hatch state |
+| `L2BlockSource` (archiver) | Synced slot, `chain-checkpointed` events, block headers |
+| `P2PClient` | `getCheckpointAttestationsForSlot(slot, payloadHash)`, `hasBlockProposalsForSlot(slot)` |
+| `CheckpointReexecutionTracker` | Local re-execution outcome for the proposal at each slot (`valid` / `invalid` / `unvalidated`) — populated by the validator client's `ProposalHandler` |
+| L1-checkpointed events | `chain-checkpointed` populates `slotNumberToCheckpoint` with the canonical attestor set |
+
+## Two cadences
+
+`Sentinel.work()` runs every quarter L2 slot and drives two pipelines that operate independently:
+
+### 1. Per-slot recording (lag = 2 slots)
+
+`processSlot(currentSlot - 2)` runs once per slot. The 2-slot lag gives P2P attestations time to settle and lets the archiver catch up. It calls `getSlotActivity(slot, epoch, proposer, committee)` and writes per-validator statuses to `SentinelStore.historyMap`. History is a sliding window of `sentinelHistoryLengthInEpochs * epochDuration` slots (default 24 epochs).
+
+If `EpochCache.getCommittee(slot)` reports `isEscapeHatchOpen`, the slot is recorded as processed without writing any per-validator entries.
+
+### 2. Per-epoch evaluation (lag = `sentinelEpochEndBufferSlots` past the epoch's last slot)
+
+`processEpochEnds(currentSlot)` checks whether any epoch is now fully observable and not yet evaluated. An epoch is eligible once both:
+
+- the buffer has elapsed: `currentSlot − sentinelEpochEndBufferSlots ≥ lastSlotOfEpoch`, and
+- per-slot recording has reached the epoch's last slot: `lastProcessedSlot ≥ lastSlotOfEpoch`.
+
+When eligible, `handleEpochEnd(epoch)` aggregates the slot-level statuses for that epoch into per-validator `{missed, total}`, persists the result to `SentinelStore.epochMap` (default 2000-epoch window), and runs the inactivity check.
+
+The aggregator catches up if multiple epochs become eligible at once (e.g. after a long backoff).
+
+## Six-case taxonomy
+
+For each slot, the proposer is assigned one of six statuses, ranked highest-confidence first:
+
+| # | Status | Trigger | Inactive party |
+|---|---|---|---|
+| 6 | `checkpoint-mined` | `slotNumberToCheckpoint.has(slot)` (a checkpoint covering this slot has landed on L1) | Attestors who didn't attest |
+| 5 | `checkpoint-valid` | `tracker.getOutcomeForSlot(slot) === 'valid'` | Attestors who didn't attest |
+| 4 | `checkpoint-invalid` | `tracker.getOutcomeForSlot(slot) === 'invalid'` (re-executed and rejected) | Proposer |
+| 3 | `checkpoint-unvalidated` | `tracker.getOutcomeForSlot(slot) === 'unvalidated'` (validation aborted: missing data, timeout, etc.) | Proposer |
+| 2 | `checkpoint-missed` | `p2p.hasBlockProposalsForSlot(slot)` true (blocks seen but no checkpoint proposal observed) | Proposer |
+| 1 | `blocks-missed` | None of the above (no block proposals observed) | Proposer |
+
+Missing-attestor faults are only recorded in cases 5 and 6 — where the local node has positive evidence the checkpoint was valid or canonical. In cases 1–4 the proposer is at fault and no attestor penalty applies.
+
+Each non-proposer committee member is tagged:
+
+- `attestation-sent` — attestation seen on P2P (with valid signature) or in the L1 checkpoint's attestor set
+- `attestation-missed` — only when proposer status is case 5 or 6 and the validator's attestation was not seen
+- none — otherwise
+
+## Inactivity slashing
+
+`handleEpochPerformance(epoch, performance)`:
+
+1. Filter validators where `missed / total ≥ slashInactivityTargetPercentage`.
+2. For each, call `checkPastInactivity` to require `slashInactivityConsecutiveEpochThreshold − 1` past epochs (from `SentinelStore.epochMap`) over the same threshold. Epochs where the validator was not on a committee are skipped, not counted against the streak.
+3. Emit a single `WANT_TO_SLASH_EVENT` with one `WantToSlashArgs` per qualifying validator.
+
+`{missed, total}` only counts slots that had something happen (a proposal, an attestation, or a missed proposal opportunity). Slots where the validator was on the committee but no proposal occurred and they were not the proposer don't show up in either count — that prevents an offline validator from appearing as "5/10 missed" simply because half the epoch had no proposals.
+
+## Storage
+
+`SentinelStore` is an LMDB-backed KV store with two maps:
+
+- `historyMap` — validator address → serialized `[(slot, status)]` rolling window
+- `epochMap` — validator address → serialized `[{epoch, missed, total}]` rolling window
+
+`SCHEMA_VERSION` controls on-disk compatibility; bumping it wipes the store on next open. The encoded status numbers live in `SentinelStore.statusToNumber`/`statusFromNumber`.
+
+## Configuration
+
+| Key | Env var | Default | Purpose |
+|---|---|---|---|
+| `sentinelEnabled` | `SENTINEL_ENABLED` | `false` | Master switch |
+| `sentinelHistoryLengthInEpochs` | `SENTINEL_HISTORY_LENGTH_IN_EPOCHS` | `24` | Slot-history window, in epochs |
+| `sentinelHistoricEpochPerformanceLengthInEpochs` | `SENTINEL_HISTORIC_EPOCH_PERFORMANCE_LENGTH_IN_EPOCHS` | `2000` | Per-epoch performance window |
+| `sentinelEpochEndBufferSlots` | `SENTINEL_EPOCH_END_BUFFER_SLOTS` | `2` | Slots to wait past an epoch's last slot before evaluating it |
+
+The sentinel also reads slashing thresholds and L1 chain identifiers from `SentinelRuntimeConfig` (see `sentinel.ts`).
+
+## Files
+
+- `sentinel.ts` — main class
+- `store.ts` — KV-backed persistence
+- `config.ts` — `SentinelConfig` and env-var mappings
+- `factory.ts` — `createSentinel` factory used by `AztecNodeService`
+- `sentinel.test.ts` / `store.test.ts` — unit tests

package/src/sentinel/config.ts

@@ -2,8 +2,9 @@ import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from
 
 export type SentinelConfig = {
   sentinelHistoryLengthInEpochs: number;
-  sentinelHistoricProvenPerformanceLengthInEpochs: number;
+  sentinelHistoricEpochPerformanceLengthInEpochs: number;
   sentinelEnabled: boolean;
+  sentinelEpochEndBufferSlots: number;
 };
 
 export const sentinelConfigMappings: ConfigMappingsType<SentinelConfig> = {
@@ -13,8 +14,9 @@ export const sentinelConfigMappings: ConfigMappingsType<SentinelConfig> = {
     ...numberConfigHelper(24),
   },
   /**
-   * The number of L2 epochs kept of proven performance history for each validator.
-   * This value must be large enough so that we have proven performance for every validator
+   * The number of L2 epochs kept of per-epoch performance history for each validator. End-of-epoch
+   * activity is recorded here and used to decide consecutive-epoch inactivity slashing.
+   * This value must be large enough so that we have epoch performance for every validator
    * for at least slashInactivityConsecutiveEpochThreshold. Assuming this value is 3,
    * and the committee size is 48, and we have 10k validators, then we pick 48 out of 10k each draw.
    * For any fixed element, per-draw prob = 48/10000 = 0.0048.
@@ -24,9 +26,9 @@ export const sentinelConfigMappings: ConfigMappingsType<SentinelConfig> = {
    * - 95% chance: n = 1310
    * - 99% chance: n = 1749
    */
-  sentinelHistoricProvenPerformanceLengthInEpochs: {
-    description: 'The number of L2 epochs kept of proven performance history for each validator.',
-    env: 'SENTINEL_HISTORIC_PROVEN_PERFORMANCE_LENGTH_IN_EPOCHS',
+  sentinelHistoricEpochPerformanceLengthInEpochs: {
+    description: 'The number of L2 epochs kept of per-epoch performance history for each validator.',
+    env: 'SENTINEL_HISTORIC_EPOCH_PERFORMANCE_LENGTH_IN_EPOCHS',
     ...numberConfigHelper(2000),
   },
   sentinelEnabled: {
@@ -34,4 +36,14 @@ export const sentinelConfigMappings: ConfigMappingsType<SentinelConfig> = {
     env: 'SENTINEL_ENABLED',
     ...booleanConfigHelper(false),
   },
+  /**
+   * Number of L2 slots to wait after the end of an epoch before computing the epoch's performance.
+   * The buffer allows P2P attestations and the local archiver to settle. Higher values reduce the
+   * risk of misjudging late-arriving activity at the cost of delayed slashing.
+   */
+  sentinelEpochEndBufferSlots: {
+    description: 'Number of L2 slots after the end of an epoch before the sentinel evaluates it.',
+    env: 'SENTINEL_EPOCH_END_BUFFER_SLOTS',
+    ...numberConfigHelper(2),
+  },
 };

package/src/sentinel/factory.ts

@@ -3,6 +3,8 @@ import { createLogger } from '@aztec/foundation/log';
 import { createStore } from '@aztec/kv-store/lmdb-v2';
 import type { P2PClient } from '@aztec/p2p';
 import type { L2BlockSource } from '@aztec/stdlib/block';
+import type { CheckpointReexecutionTracker } from '@aztec/stdlib/checkpoint';
+import type { ChainConfig } from '@aztec/stdlib/config';
 import type { SlasherConfig } from '@aztec/stdlib/interfaces/server';
 import type { DataStoreConfig } from '@aztec/stdlib/kv-store';
 
@@ -14,7 +16,8 @@ export async function createSentinel(
   epochCache: EpochCache,
   archiver: L2BlockSource,
   p2p: P2PClient,
-  config: SentinelConfig & DataStoreConfig & SlasherConfig,
+  reexecutionTracker: CheckpointReexecutionTracker,
+  config: SentinelConfig & DataStoreConfig & SlasherConfig & Pick<ChainConfig, 'l1ChainId' | 'rollupAddress'>,
   logger = createLogger('node:sentinel'),
 ): Promise<Sentinel | undefined> {
   if (!config.sentinelEnabled) {
@@ -22,10 +25,10 @@ export async function createSentinel(
   }
   const kvStore = await createStore('sentinel', SentinelStore.SCHEMA_VERSION, config, logger.getBindings());
   const storeHistoryLength = config.sentinelHistoryLengthInEpochs * epochCache.getL1Constants().epochDuration;
-  const storeHistoricProvenPerformanceLength = config.sentinelHistoricProvenPerformanceLengthInEpochs;
+  const storeHistoricEpochPerformanceLength = config.sentinelHistoricEpochPerformanceLengthInEpochs;
   const sentinelStore = new SentinelStore(kvStore, {
     historyLength: storeHistoryLength,
-    historicProvenPerformanceLength: storeHistoricProvenPerformanceLength,
+    historicEpochPerformanceLength: storeHistoricEpochPerformanceLength,
   });
-  return new Sentinel(epochCache, archiver, p2p, sentinelStore, config, logger);
+  return new Sentinel(epochCache, archiver, p2p, sentinelStore, reexecutionTracker, config, logger);
 }