@aztec-labs/aztec-node 6.0.0-nightly.20260829

package/src/modules/node_world_state_queries.ts

@@ -0,0 +1,373 @@
+import { ARCHIVE_HEIGHT, type L1_TO_L2_MSG_TREE_HEIGHT, type NOTE_HASH_TREE_HEIGHT } from '@aztec-labs/constants';
+import { BlockNumber, type EpochNumber } from '@aztec-labs/foundation/branded-types';
+import { chunkBy } from '@aztec-labs/foundation/collection';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { sleep } from '@aztec-labs/foundation/sleep';
+import { MembershipWitness, type SiblingPath } from '@aztec-labs/foundation/trees';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import {
+  type BlockHash,
+  type BlockParameter,
+  type DataInBlock,
+  type L2BlockSource,
+  type NormalizedBlockParameter,
+  inspectBlockParameter,
+} from '@aztec-labs/stdlib/block';
+import { computePublicDataTreeLeafSlot } from '@aztec-labs/stdlib/hash';
+import type { WorldStateSynchronizer } from '@aztec-labs/stdlib/interfaces/server';
+import type { L1ToL2MessageSource, L2ToL1MembershipWitness } from '@aztec-labs/stdlib/messaging';
+import {
+  MerkleTreeId,
+  type NullifierLeafPreimage,
+  NullifierMembershipWitness,
+  type PublicDataTreeLeafPreimage,
+  PublicDataWitness,
+} from '@aztec-labs/stdlib/trees';
+import type { TxHash } from '@aztec-labs/stdlib/tx';
+import { WorldStateSynchronizerError } from '@aztec-labs/world-state';
+
+import { normalizeBlockParameter } from './block_parameter.js';
+
+/** Attempts at resolving a query and syncing world state to it before giving up (see {@link NodeWorldStateQueries.getWorldState}). */
+const WORLD_STATE_SYNC_ATTEMPTS = 3;
+
+/** Delay between world-state sync attempts. */
+const WORLD_STATE_SYNC_RETRY_DELAY_MS = 100;
+
+/** Dependencies required to build a {@link NodeWorldStateQueries}. */
+export interface NodeWorldStateQueriesDeps {
+  worldStateSynchronizer: WorldStateSynchronizer;
+  blockSource: L2BlockSource;
+  l1ToL2MessageSource: L1ToL2MessageSource;
+  log?: Logger;
+}
+
+/**
+ * Serves the node's Merkle-tree and membership-witness queries against committed world-state at a
+ * requested block. Extracted from `AztecNodeService` so the block-resolution and reorg-aware sync logic
+ * can be unit-tested without standing up the whole node, and to keep `server.ts` smaller.
+ */
+export class NodeWorldStateQueries {
+  private readonly worldStateSynchronizer: WorldStateSynchronizer;
+  private readonly blockSource: L2BlockSource;
+  private readonly l1ToL2MessageSource: L1ToL2MessageSource;
+  private readonly log: Logger;
+
+  constructor(deps: NodeWorldStateQueriesDeps) {
+    this.worldStateSynchronizer = deps.worldStateSynchronizer;
+    this.blockSource = deps.blockSource;
+    this.l1ToL2MessageSource = deps.l1ToL2MessageSource;
+    this.log = deps.log ?? createLogger('node:world-state-queries');
+  }
+
+  public async findLeavesIndexes(
+    referenceBlock: BlockParameter,
+    treeId: MerkleTreeId,
+    leafValues: Fr[],
+  ): Promise<(DataInBlock<bigint> | undefined)[]> {
+    const committedDb = await this.getWorldState(referenceBlock);
+    const maybeIndices = await committedDb.findLeafIndices(
+      treeId,
+      leafValues.map(x => x.toBuffer()),
+    );
+    // Filter out undefined values to query block numbers only for found leaves
+    const definedIndices = maybeIndices.filter(x => x !== undefined);
+
+    // Now we find the block numbers for the defined indices
+    const blockNumbers = await committedDb.getBlockNumbersForLeafIndices(treeId, definedIndices);
+
+    // Build a map from leaf index to block number
+    const indexToBlockNumber = new Map<bigint, BlockNumber>();
+    for (let i = 0; i < definedIndices.length; i++) {
+      const blockNumber = blockNumbers[i];
+      if (blockNumber === undefined) {
+        throw new Error(
+          `Block number is undefined for leaf index ${definedIndices[i]} in tree ${MerkleTreeId[treeId]}`,
+        );
+      }
+      indexToBlockNumber.set(definedIndices[i], blockNumber);
+    }
+
+    // Get unique block numbers in order to optimize num calls to getLeafValue function.
+    const uniqueBlockNumbers = [...new Set(indexToBlockNumber.values())];
+
+    // Now we obtain the block hashes from the archive tree (block number = leaf index in archive tree).
+    const blockHashes = await Promise.all(
+      uniqueBlockNumbers.map(blockNumber => {
+        return committedDb.getLeafValue(MerkleTreeId.ARCHIVE, BigInt(blockNumber));
+      }),
+    );
+
+    // Build a map from block number to block hash
+    const blockNumberToHash = new Map<BlockNumber, BlockHash>();
+    for (let i = 0; i < uniqueBlockNumbers.length; i++) {
+      const blockHash = blockHashes[i];
+      if (blockHash === undefined) {
+        throw new Error(`Block hash is undefined for block number ${uniqueBlockNumbers[i]}`);
+      }
+      blockNumberToHash.set(uniqueBlockNumbers[i], blockHash);
+    }
+
+    // Create DataInBlock objects by combining indices, blockNumbers and blockHashes and return them.
+    return maybeIndices.map(index => {
+      if (index === undefined) {
+        return undefined;
+      }
+      const blockNumber = indexToBlockNumber.get(index);
+      if (blockNumber === undefined) {
+        throw new Error(`Block number not found for leaf index ${index} in tree ${MerkleTreeId[treeId]}`);
+      }
+      const l2BlockHash = blockNumberToHash.get(blockNumber);
+      if (l2BlockHash === undefined) {
+        throw new Error(`Block hash not found for block number ${blockNumber}`);
+      }
+      return {
+        l2BlockNumber: blockNumber,
+        l2BlockHash,
+        data: index,
+      };
+    });
+  }
+
+  public async getBlockHashMembershipWitness(
+    referenceBlock: BlockParameter,
+    blockHash: BlockHash,
+  ): Promise<MembershipWitness<typeof ARCHIVE_HEIGHT> | undefined> {
+    // The Noir circuit checks the archive membership proof against `anchor_block_header.last_archive.root`,
+    // which is the archive tree root BEFORE the anchor block was added (i.e. the state after block N-1).
+    // So we need the world state at block N-1, not block N, to produce a sibling path matching that root.
+    const referenceBlockNumber = await this.#resolveBlockNumber(referenceBlock);
+    if (referenceBlockNumber === BlockNumber.ZERO) {
+      // Block 0 (the initial block) has an empty archive, so no membership witness can exist.
+      return undefined;
+    }
+    const committedDb = await this.getWorldState(BlockNumber(referenceBlockNumber - 1));
+    const [pathAndIndex] = await committedDb.findSiblingPaths<MerkleTreeId.ARCHIVE>(MerkleTreeId.ARCHIVE, [blockHash]);
+    return pathAndIndex === undefined
+      ? undefined
+      : MembershipWitness.fromSiblingPath(pathAndIndex.index, pathAndIndex.path);
+  }
+
+  public async getNoteHashMembershipWitness(
+    referenceBlock: BlockParameter,
+    noteHash: Fr,
+  ): Promise<MembershipWitness<typeof NOTE_HASH_TREE_HEIGHT> | undefined> {
+    const committedDb = await this.getWorldState(referenceBlock);
+    const [pathAndIndex] = await committedDb.findSiblingPaths<MerkleTreeId.NOTE_HASH_TREE>(
+      MerkleTreeId.NOTE_HASH_TREE,
+      [noteHash],
+    );
+    return pathAndIndex === undefined
+      ? undefined
+      : MembershipWitness.fromSiblingPath(pathAndIndex.index, pathAndIndex.path);
+  }
+
+  public async getL1ToL2MessageMembershipWitness(
+    referenceBlock: BlockParameter,
+    l1ToL2Message: Fr,
+  ): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] | undefined> {
+    const db = await this.getWorldState(referenceBlock);
+    const [witness] = await db.findSiblingPaths(MerkleTreeId.L1_TO_L2_MESSAGE_TREE, [l1ToL2Message]);
+    if (!witness) {
+      return undefined;
+    }
+
+    // REFACTOR: Return a MembershipWitness object
+    return [witness.index, witness.path];
+  }
+
+  public getL1ToL2MessageIndex(l1ToL2Message: Fr): Promise<bigint | undefined> {
+    return this.l1ToL2MessageSource.getL1ToL2MessageIndex(l1ToL2Message);
+  }
+
+  /**
+   * Returns all the L2 to L1 messages in an epoch (empty array if the epoch is not found). The public
+   * `AztecNodeService.getL2ToL1Messages` that delegates here is deprecated in favor of
+   * {@link getL2ToL1MembershipWitness}.
+   * @param epoch - The epoch at which to get the data.
+   */
+  public async getL2ToL1Messages(epoch: EpochNumber): Promise<Fr[][][][]> {
+    const blocks = await this.blockSource.getBlocks({ epoch, onlyCheckpointed: true });
+    const blocksInCheckpoints = chunkBy(blocks, block => block.header.globalVariables.slotNumber);
+    return blocksInCheckpoints.map(slotBlocks =>
+      slotBlocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs)),
+    );
+  }
+
+  /**
+   * Returns the L2-to-L1 membership witness for a message in `txHash`. Passthrough to the
+   * archiver's locally-cached resolver — see {@link Archiver.getL2ToL1MembershipWitness}.
+   */
+  public getL2ToL1MembershipWitness(
+    txHash: TxHash,
+    message: Fr,
+    messageIndexInTx?: number,
+  ): Promise<L2ToL1MembershipWitness | undefined> {
+    return this.blockSource.getL2ToL1MembershipWitness(txHash, message, messageIndexInTx);
+  }
+
+  public async getNullifierMembershipWitness(
+    referenceBlock: BlockParameter,
+    nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    const db = await this.getWorldState(referenceBlock);
+    const [witness] = await db.findSiblingPaths(MerkleTreeId.NULLIFIER_TREE, [nullifier.toBuffer()]);
+    if (!witness) {
+      return undefined;
+    }
+
+    const { index, path } = witness;
+    const leafPreimage = await db.getLeafPreimage(MerkleTreeId.NULLIFIER_TREE, index);
+    if (!leafPreimage) {
+      return undefined;
+    }
+
+    return new NullifierMembershipWitness(index, leafPreimage as NullifierLeafPreimage, path);
+  }
+
+  public async getLowNullifierMembershipWitness(
+    referenceBlock: BlockParameter,
+    nullifier: Fr,
+  ): Promise<NullifierMembershipWitness | undefined> {
+    const committedDb = await this.getWorldState(referenceBlock);
+    const findResult = await committedDb.getPreviousValueIndex(MerkleTreeId.NULLIFIER_TREE, nullifier.toBigInt());
+    if (!findResult) {
+      return undefined;
+    }
+    const { index, alreadyPresent } = findResult;
+    if (alreadyPresent) {
+      throw new Error(
+        `Cannot prove nullifier non-inclusion: nullifier ${nullifier.toBigInt()} already exists in the tree`,
+      );
+    }
+    const preimageData = (await committedDb.getLeafPreimage(MerkleTreeId.NULLIFIER_TREE, index))!;
+
+    const siblingPath = await committedDb.getSiblingPath(MerkleTreeId.NULLIFIER_TREE, BigInt(index));
+    return new NullifierMembershipWitness(BigInt(index), preimageData as NullifierLeafPreimage, siblingPath);
+  }
+
+  async getPublicDataWitness(referenceBlock: BlockParameter, leafSlot: Fr): Promise<PublicDataWitness | undefined> {
+    const committedDb = await this.getWorldState(referenceBlock);
+    const lowLeafResult = await committedDb.getPreviousValueIndex(MerkleTreeId.PUBLIC_DATA_TREE, leafSlot.toBigInt());
+    if (!lowLeafResult) {
+      return undefined;
+    } else {
+      const preimage = (await committedDb.getLeafPreimage(
+        MerkleTreeId.PUBLIC_DATA_TREE,
+        lowLeafResult.index,
+      )) as PublicDataTreeLeafPreimage;
+      const path = await committedDb.getSiblingPath(MerkleTreeId.PUBLIC_DATA_TREE, lowLeafResult.index);
+      return new PublicDataWitness(lowLeafResult.index, preimage, path);
+    }
+  }
+
+  public async getPublicStorageAt(referenceBlock: BlockParameter, contract: AztecAddress, slot: Fr): Promise<Fr> {
+    const committedDb = await this.getWorldState(referenceBlock);
+    const leafSlot = await computePublicDataTreeLeafSlot(contract, slot);
+
+    const lowLeafResult = await committedDb.getPreviousValueIndex(MerkleTreeId.PUBLIC_DATA_TREE, leafSlot.toBigInt());
+    if (!lowLeafResult || !lowLeafResult.alreadyPresent) {
+      return Fr.ZERO;
+    }
+    const preimage = (await committedDb.getLeafPreimage(
+      MerkleTreeId.PUBLIC_DATA_TREE,
+      lowLeafResult.index,
+    )) as PublicDataTreeLeafPreimage;
+    return preimage.leaf.value;
+  }
+
+  /**
+   * Returns an instance of MerkleTreeOperations having first ensured the world state is synced to the requested
+   * block on the correct fork. Every query variant is resolved to a concrete (block number, block hash), which is
+   * threaded through both the sync and the snapshot read so a reorg that replaced the block at that height is
+   * detected rather than served silently. Transient failures — a prune landing between resolution and sync, or a
+   * fork flip caught at either the sync or the snapshot stage — are retried a few times, re-resolving the query
+   * against the updated chain each time; terminal failures — an unknown block hash at resolution, or a block whose
+   * history world state has pruned away — are thrown immediately.
+   * @param block - The block parameter (block number, block hash, or tag) at which to get the data.
+   * @returns An instance of a committed MerkleTreeOperations
+   */
+  public async getWorldState(block: BlockParameter) {
+    const query = normalizeBlockParameter(block);
+
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.#resolveWorldState(query);
+      } catch (err) {
+        if (attempt >= WORLD_STATE_SYNC_ATTEMPTS || !(err instanceof WorldStateSynchronizerError)) {
+          throw err;
+        }
+        this.log.verbose(`Retrying world state query after sync failure: ${err.message}`, {
+          attempt,
+          block: inspectBlockParameter(block),
+        });
+        await sleep(WORLD_STATE_SYNC_RETRY_DELAY_MS);
+      }
+    }
+  }
+
+  /**
+   * Resolves `query` to a concrete (block number, block hash), syncs world state to that exact fork, and returns
+   * the committed db (for `proposed` queries) or the fork-verified snapshot at the resolved block.
+   */
+  async #resolveWorldState(query: NormalizedBlockParameter) {
+    // User requests 'latest on the current fork', so the committed db is returned unverified
+    if ('tag' in query && query.tag === 'proposed') {
+      this.log.debug(`Using committed db for latest block`);
+      await this.worldStateSynchronizer.syncImmediate();
+      return this.worldStateSynchronizer.getCommitted();
+    }
+
+    // Resolve the query against the block source BEFORE syncing to a concrete (number, hash), and drive the sync to
+    // that exact fork. Resolving after the sync races the block source: the resolved tip can advance past what world
+    // state synced while the sync is in flight. Passing the hash makes the sync reorg-aware — it barriers until the
+    // archive-tree commit for that block has landed and verifies it matches the requested fork, throwing otherwise.
+    const { blockNumber, blockHash } = await this.#resolveBlockNumberAndHash(query);
+    const blockSyncedTo = await this.worldStateSynchronizer.syncImmediate(blockNumber, blockHash);
+
+    // The fork could flip between it returning and the snapshot being read, so getVerifiedSnapshot pins the
+    // returned view to the resolved fork (re-resolved by the retry loop on mismatch).
+    this.log.debug(`Using verified snapshot for block ${blockNumber}, world state synced upto ${blockSyncedTo}`);
+    return await this.worldStateSynchronizer.getVerifiedSnapshot(blockNumber, blockHash);
+  }
+
+  /** Resolves any {@link BlockParameter} variant to its concrete `(blockNumber, blockHash)` via the block source. */
+  async #resolveBlockNumberAndHash(
+    query: NormalizedBlockParameter,
+  ): Promise<{ blockNumber: BlockNumber; blockHash: BlockHash }> {
+    const blockData = await this.blockSource.getBlockData(query);
+    if (blockData === undefined) {
+      this.#throwOnUndefinedBlockData(query);
+    }
+    return { blockNumber: blockData.header.getBlockNumber(), blockHash: blockData.blockHash };
+  }
+
+  /** Resolves any {@link BlockParameter} variant to a concrete block number. */
+  async #resolveBlockNumber(block: BlockParameter): Promise<BlockNumber> {
+    const blockQuery = normalizeBlockParameter(block);
+    const blockNumber = await this.blockSource.getBlockNumber(blockQuery);
+    if (blockNumber === undefined) {
+      this.#throwOnUndefinedBlockData(blockQuery);
+    }
+    return blockNumber;
+  }
+
+  /**
+   * Hash and archive misses are terminal (an unknown block, likely a reorg); tag and number misses are transient —
+   * the block may have been pruned between the tag->number resolution and this data read, or may simply not have
+   * arrived yet — and surface as {@link WorldStateSynchronizerError} so the retry loop re-resolves against the
+   * current chain.
+   */
+  #throwOnUndefinedBlockData(query: NormalizedBlockParameter): never {
+    if ('hash' in query) {
+      throw new Error(
+        `Block hash ${query.hash.toString()} not found when resolving query. If the node API has been queried with anchor block hash possibly a reorg has occurred.`,
+      );
+    }
+    if ('archive' in query) {
+      throw new Error(`Block with archive ${query.archive.toString()} not found when resolving query.`);
+    }
+    throw new WorldStateSynchronizerError(`Block not found for ${inspectBlockParameter(query)} when resolving query.`);
+  }
+}

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, `getCheckpoint({ slot })`, `getL2Tips()`, 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-confirmed checkpoints | Fetched on demand per slot via `archiver.getCheckpoint({ slot })`, yielding 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` | `archiver.getCheckpoint({ slot })` returns a checkpoint (one 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

@@ -0,0 +1,49 @@
+import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec-labs/foundation/config';
+
+export type SentinelConfig = {
+  sentinelHistoryLengthInEpochs: number;
+  sentinelHistoricEpochPerformanceLengthInEpochs: number;
+  sentinelEnabled: boolean;
+  sentinelEpochEndBufferSlots: number;
+};
+
+export const sentinelConfigMappings: ConfigMappingsType<SentinelConfig> = {
+  sentinelHistoryLengthInEpochs: {
+    description: 'The number of L2 epochs kept of history for each validator for computing their stats.',
+    env: 'SENTINEL_HISTORY_LENGTH_IN_EPOCHS',
+    ...numberConfigHelper(24),
+  },
+  /**
+   * 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.
+   * After n draws, count ~ Binomial(n, 0.0048). We want P(X >= 3).
+   * Results (exact binomial):
+   * - 90% chance: n = 1108
+   * - 95% chance: n = 1310
+   * - 99% chance: n = 1749
+   */
+  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: {
+    description: 'Whether the sentinel is enabled or not.',
+    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

@@ -0,0 +1,46 @@
+import type { EpochCache } from '@aztec-labs/epoch-cache';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { createStore } from '@aztec-labs/kv-store/lmdb-v2';
+import type { P2PClient } from '@aztec-labs/p2p';
+import type { L2BlockSource } from '@aztec-labs/stdlib/block';
+import type { CheckpointReexecutionTracker } from '@aztec-labs/stdlib/checkpoint';
+import type { ChainConfig } from '@aztec-labs/stdlib/config';
+import type { SlasherConfig, ValidatorClientConfig } from '@aztec-labs/stdlib/interfaces/server';
+import type { DataStoreConfig } from '@aztec-labs/stdlib/kv-store';
+
+import type { SentinelConfig } from './config.js';
+import { Sentinel } from './sentinel.js';
+import { SentinelStore } from './store.js';
+
+export async function createSentinel(
+  epochCache: EpochCache,
+  archiver: L2BlockSource,
+  p2p: P2PClient,
+  reexecutionTracker: CheckpointReexecutionTracker,
+  config: SentinelConfig &
+    DataStoreConfig &
+    SlasherConfig &
+    Pick<ChainConfig, 'l1ChainId' | 'rollupAddress'> &
+    Pick<ValidatorClientConfig, 'disableValidator'>,
+  logger = createLogger('node:sentinel'),
+): Promise<Sentinel | undefined> {
+  const runsValidator = !config.disableValidator;
+  if (!runsValidator && !config.sentinelEnabled) {
+    logger.verbose('Sentinel is disabled');
+    return undefined;
+  }
+  if (runsValidator) {
+    logger.info('Enabling sentinel since this node runs a validator');
+  } else {
+    logger.info('Enabling sentinel from SENTINEL_ENABLED configuration');
+  }
+
+  const kvStore = await createStore('sentinel', SentinelStore.SCHEMA_VERSION, config, logger.getBindings());
+  const storeHistoryLength = config.sentinelHistoryLengthInEpochs * epochCache.getL1Constants().epochDuration;
+  const storeHistoricEpochPerformanceLength = config.sentinelHistoricEpochPerformanceLengthInEpochs;
+  const sentinelStore = new SentinelStore(kvStore, {
+    historyLength: storeHistoryLength,
+    historicEpochPerformanceLength: storeHistoricEpochPerformanceLength,
+  });
+  return new Sentinel(epochCache, archiver, p2p, sentinelStore, reexecutionTracker, config, logger);
+}

package/src/sentinel/index.ts

@@ -0,0 +1,8 @@
+export { Sentinel } from './sentinel.js';
+
+export type {
+  ValidatorsStats,
+  ValidatorStats,
+  ValidatorStatusHistory,
+  ValidatorStatusInSlot,
+} from '@aztec-labs/stdlib/validators';