@aztec/aztec-node 0.0.1-commit.42ee6df9b → 0.0.1-commit.431c48d

package/src/modules/node_world_state_queries.ts

@@ -0,0 +1,376 @@
+import { ARCHIVE_HEIGHT, type L1_TO_L2_MSG_TREE_HEIGHT, type NOTE_HASH_TREE_HEIGHT } from '@aztec/constants';
+import { BlockNumber, type CheckpointNumber, type EpochNumber } from '@aztec/foundation/branded-types';
+import { chunkBy } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { sleep } from '@aztec/foundation/sleep';
+import { MembershipWitness, type SiblingPath } from '@aztec/foundation/trees';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import {
+  type BlockHash,
+  type BlockParameter,
+  type DataInBlock,
+  type L2BlockSource,
+  type NormalizedBlockParameter,
+  inspectBlockParameter,
+} from '@aztec/stdlib/block';
+import { computePublicDataTreeLeafSlot } from '@aztec/stdlib/hash';
+import type { WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import { InboxLeaf, type L1ToL2MessageSource, type L2ToL1MembershipWitness } from '@aztec/stdlib/messaging';
+import {
+  MerkleTreeId,
+  type NullifierLeafPreimage,
+  NullifierMembershipWitness,
+  type PublicDataTreeLeafPreimage,
+  PublicDataWitness,
+} from '@aztec/stdlib/trees';
+import type { TxHash } from '@aztec/stdlib/tx';
+import { WorldStateSynchronizerError } from '@aztec/world-state';
+
+import { normalizeBlockParameter } from './block_parameter.js';
+import type { UnseenBlockHoldOff, UnseenBlockHoldOffOptions } from './unseen_block_hold_off.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;
+  holdOff: UnseenBlockHoldOff;
+  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 holdOff: UnseenBlockHoldOff;
+  private readonly log: Logger;
+
+  constructor(deps: NodeWorldStateQueriesDeps) {
+    this.worldStateSynchronizer = deps.worldStateSynchronizer;
+    this.blockSource = deps.blockSource;
+    this.l1ToL2MessageSource = deps.l1ToL2MessageSource;
+    this.holdOff = deps.holdOff;
+    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 { blockNumber: referenceBlockNumber } = await this.#resolveBlockNumberAndHash(
+      normalizeBlockParameter(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 async getL1ToL2MessageCheckpoint(l1ToL2Message: Fr): Promise<CheckpointNumber | undefined> {
+    const messageIndex = await this.l1ToL2MessageSource.getL1ToL2MessageIndex(l1ToL2Message);
+    return messageIndex !== undefined ? InboxLeaf.checkpointNumberFromIndex(messageIndex) : undefined;
+  }
+
+  /**
+   * 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 sync 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 — a query that resolves to no block, 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);
+
+    // 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, so the sync can be driven to a concrete
+    // (number, hash). Resolving after the sync races the block source: the resolved tip can advance past what world
+    // state synced while the sync is in flight. Resolving here rather than inside the retry loop also keeps a
+    // retry from re-entering the hold-off, which would multiply the wait a client experiences by the attempt count.
+    let resolved = await this.#resolveBlockNumberAndHash(query);
+
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return await this.#resolveWorldState(resolved);
+      } 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);
+        resolved = await this.#resolveBlockNumberAndHash(query, { holdOff: false });
+      }
+    }
+  }
+
+  /**
+   * Syncs world state to the resolved fork and returns the fork-verified snapshot at that block. 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.
+   */
+  async #resolveWorldState({ blockNumber, blockHash }: { blockNumber: BlockNumber; blockHash: BlockHash }) {
+    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)`, holding the query
+   * briefly (unless the caller opts out) when it references a block the node is about to see.
+   */
+  async #resolveBlockNumberAndHash(
+    query: NormalizedBlockParameter,
+    opts: UnseenBlockHoldOffOptions = {},
+  ): Promise<{ blockNumber: BlockNumber; blockHash: BlockHash }> {
+    const blockData = await this.holdOff.getBlockData(query, opts);
+    if (blockData === undefined) {
+      this.#throwOnUndefinedBlockData(query);
+    }
+    return { blockNumber: blockData.header.getBlockNumber(), blockHash: blockData.blockHash };
+  }
+
+  /**
+   * Hash and archive misses report an unknown block (likely a reorg); tag and number misses report a transient
+   * condition — the block may have been pruned, or may simply not have arrived yet — and are distinguished to the
+   * caller as a {@link WorldStateSynchronizerError}.
+   */
+  #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/modules/unseen_block_hold_off.ts

@@ -0,0 +1,199 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import { InterruptibleSleep } from '@aztec/foundation/sleep';
+import { Timer } from '@aztec/foundation/timer';
+import {
+  type BlockData,
+  type BlockHash,
+  type L2Block,
+  type L2BlockSource,
+  type L2BlockSourceEventEmitter,
+  L2BlockSourceEvents,
+  type NormalizedBlockParameter,
+  getBlockSourceEmitter,
+  inspectBlockParameter,
+} from '@aztec/stdlib/block';
+
+/**
+ * Longest a held request sleeps before re-reading the block source anyway. Held requests are woken by the source
+ * reporting an update, so this only bounds how long one waits when it misses the update that added its block: the
+ * source can commit between a request's read and its sleep, and a request that is not sleeping yet is not woken.
+ */
+const MAX_SLEEP_MS = 1000;
+
+/** Max requests held simultaneously. Beyond this, misses fail fast as if the hold-off were disabled. */
+export const MAX_CONCURRENT_HOLDS = 100;
+
+/** Wait budgets for {@link UnseenBlockHoldOff}, in milliseconds. Zero (or negative) disables a budget. */
+export type UnseenBlockHoldOffConfig = {
+  /** Budget for a query anchored on the block number right after the node's proposed tip. */
+  byNumberWaitMs: number;
+  /** Budget for a query anchored on a block hash or archive root the node does not know. */
+  byHashWaitMs: number;
+};
+
+/** Options for a single {@link UnseenBlockHoldOff} query. */
+export type UnseenBlockHoldOffOptions = {
+  /** Set to false to resolve without ever waiting (used by callers that already spent their budget). */
+  holdOff?: boolean;
+};
+
+/**
+ * Resolves RPC block anchors against the block source, briefly holding a request whose anchor the node is about to
+ * see instead of failing it immediately.
+ *
+ * Behind a load balancer a client can sync to block N+1 through one node and then anchor follow-up queries against
+ * another node that is still at block N. Failing those queries aborts a whole client flow over a skew that resolves
+ * in under a block time, so a miss on an anchor that plausibly lies just ahead of the tip is retried for a bounded
+ * budget. Everything else — a tag, a number far past the tip, a budget of zero, or too many requests already held —
+ * resolves exactly as the bare block source would.
+ *
+ * Held requests do not poll at a rate of their own choosing: they all sleep on one wake-up that the block source
+ * triggers when it reports it moved, so the source is read when there is something new to read and, failing that, at
+ * most once per {@link MAX_SLEEP_MS}. A source that reports no updates cannot wake them, so it never holds anything
+ * off.
+ */
+export class UnseenBlockHoldOff {
+  private activeHolds = 0;
+  private readonly log: Logger;
+  /** Shared by every held request; interrupted on a source update. Undefined for a source that reports none. */
+  private readonly wakeup: InterruptibleSleep | undefined;
+
+  constructor(
+    private readonly blockSource: L2BlockSource | L2BlockSourceEventEmitter,
+    private readonly config: UnseenBlockHoldOffConfig,
+    log?: Logger,
+  ) {
+    this.log = log ?? createLogger('node:unseen-block-hold-off');
+    const emitter = getBlockSourceEmitter(blockSource);
+    if (emitter === undefined) {
+      this.log.verbose(`Block source reports no updates, queries for unseen blocks will not be held off`);
+    } else {
+      const wakeup = new InterruptibleSleep();
+      this.wakeup = wakeup;
+      emitter.on(L2BlockSourceEvents.L2BlockSourceUpdated, () => wakeup.interrupt());
+    }
+  }
+
+  /** Number of requests currently held waiting for their anchor block. Exposed for tests and diagnostics. */
+  public get holds(): number {
+    return this.activeHolds;
+  }
+
+  /**
+   * Resolves `query` to block metadata, holding off briefly when it references a block the node is about to see.
+   * Returns undefined on a miss, so callers keep whatever behavior they had before (throwing or returning
+   * undefined) — the hold-off only delays that outcome.
+   */
+  public getBlockData(
+    query: NormalizedBlockParameter,
+    opts: UnseenBlockHoldOffOptions = {},
+  ): Promise<BlockData | undefined> {
+    return this.#readWithHoldOff(query, q => this.blockSource.getBlockData(q), opts);
+  }
+
+  /** Resolves `query` to a full block with its transactions, holding off as {@link getBlockData} does. */
+  public getBlock(query: NormalizedBlockParameter, opts: UnseenBlockHoldOffOptions = {}): Promise<L2Block | undefined> {
+    return this.#readWithHoldOff(query, q => this.blockSource.getBlock(q), opts);
+  }
+
+  /**
+   * Reads `query` through `read`, and on a miss waits for the block it names before reading once more. Subject to the
+   * concurrent-hold cap: once it is saturated a miss resolves without waiting, as it would with the hold-off
+   * disabled.
+   */
+  async #readWithHoldOff<T>(
+    query: NormalizedBlockParameter,
+    read: (query: NormalizedBlockParameter) => Promise<T | undefined>,
+    opts: UnseenBlockHoldOffOptions,
+  ): Promise<T | undefined> {
+    const value = await read(query);
+    if (value !== undefined || opts.holdOff === false) {
+      return value;
+    }
+    const arrived = await this.#waitForBlock(query, await this.#resolveWaitBudgetMs(query));
+    return arrived ? await read(query) : undefined;
+  }
+
+  /**
+   * Waits for the block `query` names to show up on the block source, for at most `waitMs`, and reports whether it
+   * did. Returns false without waiting when the source reports no updates, when the budget is empty, or when the
+   * concurrent-hold cap is saturated, so a miss fails as fast as it would with the hold-off disabled.
+   *
+   * Arrival is checked on block metadata rather than through the caller's read, so a held request costs a metadata
+   * read per wake-up whatever it asked for: a held `getBlock` would otherwise reconstruct a whole block with its
+   * transactions on every wake-up only to find it is not the one it is waiting for.
+   *
+   * A budget is approximate: the deadline is only re-checked after a sleep, so the actual wait can exceed it by the
+   * read's own latency.
+   */
+  async #waitForBlock(query: NormalizedBlockParameter, waitMs: number): Promise<boolean> {
+    const wakeup = this.wakeup;
+    if (wakeup === undefined || !Number.isFinite(waitMs) || waitMs <= 0) {
+      return false;
+    }
+    const blockParameter = inspectBlockParameter(query);
+    if (this.activeHolds >= MAX_CONCURRENT_HOLDS) {
+      this.log.verbose(`Not holding off query for unseen block, too many requests already held`, {
+        blockParameter,
+        holds: this.activeHolds,
+      });
+      return false;
+    }
+
+    this.activeHolds++;
+    const timer = new Timer();
+    try {
+      this.log.verbose(`Holding off query for unseen block`, { blockParameter, waitMs, holds: this.activeHolds });
+      while (timer.ms() < waitMs) {
+        await wakeup.sleep(Math.min(waitMs - timer.ms(), MAX_SLEEP_MS));
+        const data = await this.blockSource.getBlockData(query);
+        if (data !== undefined) {
+          this.log.verbose(`Unseen block arrived after ${timer.ms()}ms`, {
+            blockParameter,
+            blockNumber: data.header.getBlockNumber(),
+            elapsedMs: timer.ms(),
+          });
+          return true;
+        }
+      }
+      this.log.verbose(`Gave up waiting for unseen block after ${timer.ms()}ms`, {
+        blockParameter,
+        waitMs,
+        elapsedMs: timer.ms(),
+      });
+      return false;
+    } finally {
+      this.activeHolds--;
+    }
+  }
+
+  /**
+   * Budget for waiting on a missing anchor, decided once on entry rather than per wake-up. A tag always resolves
+   * against the current tip, so a tag miss is never a skew. A number is only worth waiting on when it is the very
+   * next block: further ahead the client is not merely one block in front, and at or below the tip the block was
+   * pruned or reorged away. A hash or archive root carries no height, so "one ahead" and "reorged away" are
+   * indistinguishable and both get the shorter hash budget.
+   *
+   * The genesis block hash is the one hash never worth waiting on: a client anchors on it before it has synced any
+   * block (as a PXE does for its first tagged-log queries), and the block is synthetic, so a source that does not
+   * answer for it now never will.
+   */
+  async #resolveWaitBudgetMs(query: NormalizedBlockParameter): Promise<number> {
+    if ('tag' in query) {
+      return 0;
+    }
+    if ('number' in query) {
+      const tip = await this.blockSource.getBlockNumber();
+      return query.number === tip + 1 ? this.config.byNumberWaitMs : 0;
+    }
+    if ('hash' in query && this.#isGenesisBlockHash(query.hash)) {
+      return 0;
+    }
+    return this.config.byHashWaitMs;
+  }
+
+  /** True when `hash` names the synthetic genesis block, which never arrives and so is never waited for. */
+  #isGenesisBlockHash(hash: BlockHash): boolean {
+    return hash.equals(this.blockSource.getGenesisBlockHash());
+  }
+}

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