feat: Add Single Validator RPC Method for Historical Data Retrieval (#16446)

This is a squash of #16177 by @StoneMac65, since the external PR and the
squash check seem to be causing issues with CI. Until we fix the
underlying issue, let's see if we can get this merged via this PR.

Author: spalladino

yarn-project/aztec-node/src/aztec-node/server.ts

@@ -95,7 +95,7 @@ import {
   type TxValidationResult,
 } from '@aztec/stdlib/tx';
 import { getPackageVersion } from '@aztec/stdlib/update-checker';
-import type { ValidatorsStats } from '@aztec/stdlib/validators';
+import type { SingleValidatorStats, ValidatorsStats } from '@aztec/stdlib/validators';
 import {
   Attributes,
   type TelemetryClient,
@@ -1125,6 +1125,14 @@ export class AztecNodeService implements AztecNode, AztecNodeAdmin, Traceable {
     return this.validatorsSentinel?.computeStats() ?? Promise.resolve({ stats: {}, slotWindow: 0 });
   }
 
+  public getValidatorStats(
+    validatorAddress: EthAddress,
+    fromSlot?: bigint,
+    toSlot?: bigint,
+  ): Promise<SingleValidatorStats | undefined> {
+    return this.validatorsSentinel?.getValidatorStats(validatorAddress, fromSlot, toSlot) ?? Promise.resolve(undefined);
+  }
+
   public async startSnapshotUpload(location: string): Promise<void> {
     // Note that we are forcefully casting the blocksource as an archiver
     // We break support for archiver running remotely to the node

yarn-project/aztec-node/src/sentinel/sentinel.test.ts

@@ -234,6 +234,149 @@ describe('sentinel', () => {
     });
   });
 
+  describe('slot range validation', () => {
+    let validator: EthAddress;
+
+    beforeEach(() => {
+      validator = EthAddress.random();
+      jest.spyOn(store, 'getHistoryLength').mockReturnValue(10);
+      jest.spyOn(store, 'getHistory').mockResolvedValue([
+        { slot: 1n, status: 'block-mined' },
+        { slot: 2n, status: 'attestation-sent' },
+      ]);
+      jest.spyOn(store, 'getHistories').mockResolvedValue({
+        [validator.toString()]: [
+          { slot: 1n, status: 'block-mined' },
+          { slot: 2n, status: 'attestation-sent' },
+        ],
+      });
+    });
+
+    describe('getValidatorStats', () => {
+      it('should throw when slot range exceeds history length', async () => {
+        await expect(sentinel.getValidatorStats(validator, 1n, 16n)).rejects.toThrow(
+          'Slot range (15) exceeds history length (10). Requested range: 1 to 16.',
+        );
+      });
+
+      it('should not throw when slot range equals history length', async () => {
+        await expect(sentinel.getValidatorStats(validator, 1n, 11n)).resolves.toBeDefined();
+      });
+
+      it('should not throw when slot range is less than history length', async () => {
+        await expect(sentinel.getValidatorStats(validator, 1n, 6n)).resolves.toBeDefined();
+      });
+
+      it('should return undefined when validator has no history', async () => {
+        jest.spyOn(store, 'getHistory').mockResolvedValue(undefined);
+        const result = await sentinel.getValidatorStats(validator, 1n, 6n);
+        expect(result).toBeUndefined();
+      });
+
+      it('should return undefined when validator has empty history', async () => {
+        jest.spyOn(store, 'getHistory').mockResolvedValue([]);
+        const result = await sentinel.getValidatorStats(validator, 1n, 6n);
+        expect(result).toBeUndefined();
+      });
+
+      it('should return expected mocked data structure', async () => {
+        const mockHistory: ValidatorStatusHistory = [
+          { slot: 1n, status: 'block-mined' },
+          { slot: 2n, status: 'attestation-sent' },
+        ];
+        const mockProvenPerformance = [
+          { epoch: 1n, missed: 2, total: 10 },
+          { epoch: 2n, missed: 1, total: 8 },
+        ];
+
+        jest.spyOn(store, 'getHistory').mockResolvedValue(mockHistory);
+        jest.spyOn(store, 'getProvenPerformance').mockResolvedValue(mockProvenPerformance);
+        jest.spyOn(sentinel, 'computeStatsForValidator').mockReturnValue({
+          address: validator,
+          totalSlots: 2,
+          missedProposals: { count: 0, currentStreak: 0, rate: 0 },
+          missedAttestations: { count: 0, currentStreak: 0, rate: 0 },
+          history: mockHistory,
+        });
+
+        const result = await sentinel.getValidatorStats(validator, 1n, 6n);
+
+        expect(result).toEqual({
+          validator: {
+            address: validator,
+            totalSlots: 2,
+            missedProposals: { count: 0, currentStreak: 0, rate: 0 },
+            missedAttestations: { count: 0, currentStreak: 0, rate: 0 },
+            history: mockHistory,
+          },
+          allTimeProvenPerformance: mockProvenPerformance,
+          lastProcessedSlot: sentinel.getLastProcessedSlot(),
+          initialSlot: sentinel.getInitialSlot(),
+          slotWindow: 10,
+        });
+      });
+
+      it('should call computeStatsForValidator with correct parameters', async () => {
+        const mockHistory: ValidatorStatusHistory = [{ slot: 5n, status: 'block-mined' }];
+        jest.spyOn(store, 'getHistory').mockResolvedValue(mockHistory);
+        jest.spyOn(store, 'getProvenPerformance').mockResolvedValue([]);
+        const computeStatsSpy = jest.spyOn(sentinel, 'computeStatsForValidator').mockReturnValue({
+          address: validator,
+          totalSlots: 1,
+          missedProposals: { count: 0, currentStreak: 0, rate: 0 },
+          missedAttestations: { count: 0, currentStreak: 0, rate: 0 },
+          history: mockHistory,
+        });
+
+        await sentinel.getValidatorStats(validator, 3n, 8n);
+
+        expect(computeStatsSpy).toHaveBeenCalledWith(validator.toString(), mockHistory, 3n, 8n);
+      });
+
+      it('should use default slot range when not provided', async () => {
+        const mockHistory: ValidatorStatusHistory = [{ slot: 5n, status: 'block-mined' }];
+        jest.spyOn(store, 'getHistory').mockResolvedValue(mockHistory);
+        jest.spyOn(store, 'getProvenPerformance').mockResolvedValue([]);
+        const computeStatsSpy = jest.spyOn(sentinel, 'computeStatsForValidator').mockReturnValue({
+          address: validator,
+          totalSlots: 1,
+          missedProposals: { count: 0, currentStreak: 0, rate: 0 },
+          missedAttestations: { count: 0, currentStreak: 0, rate: 0 },
+          history: mockHistory,
+        });
+
+        await sentinel.getValidatorStats(validator);
+
+        expect(computeStatsSpy).toHaveBeenCalledWith(validator.toString(), mockHistory, slot - BigInt(10), slot);
+      });
+
+      it('should return proven performance data from store', async () => {
+        const mockHistory: ValidatorStatusHistory = [{ slot: 1n, status: 'block-mined' }];
+        const mockProvenPerformance = [
+          { epoch: 5n, missed: 3, total: 12 },
+          { epoch: 6n, missed: 0, total: 15 },
+        ];
+
+        jest.spyOn(store, 'getHistory').mockResolvedValue(mockHistory);
+        const getProvenPerformanceSpy = jest
+          .spyOn(store, 'getProvenPerformance')
+          .mockResolvedValue(mockProvenPerformance);
+        jest.spyOn(sentinel, 'computeStatsForValidator').mockReturnValue({
+          address: validator,
+          totalSlots: 1,
+          missedProposals: { count: 0, currentStreak: 0, rate: 0 },
+          missedAttestations: { count: 0, currentStreak: 0, rate: 0 },
+          history: mockHistory,
+        });
+
+        const result = await sentinel.getValidatorStats(validator);
+
+        expect(getProvenPerformanceSpy).toHaveBeenCalledWith(validator);
+        expect(result?.allTimeProvenPerformance).toEqual(mockProvenPerformance);
+      });
+    });
+  });
+
   describe('handleChainProven', () => {
     it('calls inactivity watcher with performance data', async () => {
       const blockNumber = 15;
@@ -423,4 +566,16 @@ class TestSentinel extends Sentinel {
   public override updateProvenPerformance(epoch: bigint, performance: ValidatorsEpochPerformance) {
     return super.updateProvenPerformance(epoch, performance);
   }
+
+  public override getValidatorStats(validatorAddress: EthAddress, fromSlot?: bigint, toSlot?: bigint) {
+    return super.getValidatorStats(validatorAddress, fromSlot, toSlot);
+  }
+
+  public getLastProcessedSlot() {
+    return this.lastProcessedSlot;
+  }
+
+  public getInitialSlot() {
+    return this.initialSlot;
+  }
 }

yarn-project/aztec-node/src/sentinel/sentinel.ts

@@ -17,6 +17,7 @@ import {
 } from '@aztec/stdlib/block';
 import { getEpochAtSlot, getTimestampForSlot } from '@aztec/stdlib/epoch-helpers';
 import type {
+  SingleValidatorStats,
   ValidatorStats,
   ValidatorStatusHistory,
   ValidatorStatusInSlot,
@@ -379,6 +380,47 @@ export class Sentinel extends (EventEmitter as new () => WatcherEmitter) impleme
     };
   }
 
+  /** Computes stats for a single validator. */
+  public async getValidatorStats(
+    validatorAddress: EthAddress,
+    fromSlot?: bigint,
+    toSlot?: bigint,
+  ): Promise<SingleValidatorStats | undefined> {
+    const history = await this.store.getHistory(validatorAddress);
+
+    if (!history || history.length === 0) {
+      return undefined;
+    }
+
+    const slotNow = this.epochCache.getEpochAndSlotNow().slot;
+    const effectiveFromSlot = fromSlot ?? (this.lastProcessedSlot ?? slotNow) - BigInt(this.store.getHistoryLength());
+    const effectiveToSlot = toSlot ?? this.lastProcessedSlot ?? slotNow;
+
+    const historyLength = BigInt(this.store.getHistoryLength());
+    if (effectiveToSlot - effectiveFromSlot > historyLength) {
+      throw new Error(
+        `Slot range (${effectiveToSlot - effectiveFromSlot}) exceeds history length (${historyLength}). ` +
+          `Requested range: ${effectiveFromSlot} to ${effectiveToSlot}.`,
+      );
+    }
+
+    const validator = this.computeStatsForValidator(
+      validatorAddress.toString(),
+      history,
+      effectiveFromSlot,
+      effectiveToSlot,
+    );
+    const allTimeProvenPerformance = await this.store.getProvenPerformance(validatorAddress);
+
+    return {
+      validator,
+      allTimeProvenPerformance,
+      lastProcessedSlot: this.lastProcessedSlot,
+      initialSlot: this.initialSlot,
+      slotWindow: this.store.getHistoryLength(),
+    };
+  }
+
   protected computeStatsForValidator(
     address: `0x${string}`,
     allHistory: ValidatorStatusHistory,

yarn-project/aztec-node/src/sentinel/store.ts

@@ -101,7 +101,7 @@ export class SentinelStore {
     return histories;
   }
 
-  private async getHistory(address: EthAddress): Promise<ValidatorStatusHistory | undefined> {
+  public async getHistory(address: EthAddress): Promise<ValidatorStatusHistory | undefined> {
     const data = await this.historyMap.getAsync(address.toString());
     return data && this.deserializeHistory(data);
   }

yarn-project/stdlib/src/interfaces/aztec-node.test.ts

@@ -51,7 +51,7 @@ import { TxEffect } from '../tx/tx_effect.js';
 import { TxHash } from '../tx/tx_hash.js';
 import { TxReceipt } from '../tx/tx_receipt.js';
 import type { TxValidationResult } from '../tx/validator/tx_validator.js';
-import type { ValidatorsStats } from '../validators/types.js';
+import type { SingleValidatorStats, ValidatorsStats } from '../validators/types.js';
 import { MAX_RPC_LEN } from './api_limit.js';
 import { type AztecNode, AztecNodeApiSchema } from './aztec-node.js';
 import type { SequencerConfig } from './configs.js';
@@ -367,6 +367,51 @@ describe('AztecNodeApiSchema', () => {
     expect(response).toEqual(handler.validatorStats);
   });
 
+  it('getValidatorStats', async () => {
+    const validatorAddress = EthAddress.random();
+    handler.singleValidatorStats = {
+      validator: {
+        address: validatorAddress,
+        totalSlots: 5,
+        missedAttestations: { currentStreak: 0, count: 0 },
+        missedProposals: { currentStreak: 0, count: 0 },
+        history: [{ slot: 1n, status: 'block-mined' }],
+      },
+      allTimeProvenPerformance: [],
+      lastProcessedSlot: 10n,
+      initialSlot: 1n,
+      slotWindow: 100,
+    };
+
+    const response = await context.client.getValidatorStats(validatorAddress);
+    expect(response).toEqual(handler.singleValidatorStats);
+  });
+
+  it('getValidatorStats(non-existent)', async () => {
+    const response = await context.client.getValidatorStats(EthAddress.random());
+    expect(response).toBeUndefined();
+  });
+
+  it('getValidatorStats(with-time-range)', async () => {
+    const validatorAddress = EthAddress.random();
+    handler.singleValidatorStats = {
+      validator: {
+        address: validatorAddress,
+        totalSlots: 3,
+        missedAttestations: { currentStreak: 0, count: 0 },
+        missedProposals: { currentStreak: 0, count: 0 },
+        history: [{ slot: 5n, status: 'attestation-sent' }],
+      },
+      allTimeProvenPerformance: [],
+      lastProcessedSlot: 10n,
+      initialSlot: 5n,
+      slotWindow: 5,
+    };
+
+    const response = await context.client.getValidatorStats(validatorAddress, 5n, 10n);
+    expect(response).toEqual(handler.singleValidatorStats);
+  });
+
   it('simulatePublicCalls', async () => {
     const response = await context.client.simulatePublicCalls(Tx.random());
     expect(response).toBeInstanceOf(PublicSimulationOutput);
@@ -419,6 +464,7 @@ describe('AztecNodeApiSchema', () => {
 
 class MockAztecNode implements AztecNode {
   public validatorStats: ValidatorsStats | undefined;
+  public singleValidatorStats: SingleValidatorStats | undefined;
 
   constructor(private artifact: ContractArtifact) {}
 
@@ -655,6 +701,20 @@ class MockAztecNode implements AztecNode {
   getValidatorsStats(): Promise<ValidatorsStats> {
     return Promise.resolve(this.validatorStats!);
   }
+  getValidatorStats(
+    validatorAddress: EthAddress,
+    fromSlot?: bigint,
+    toSlot?: bigint,
+  ): Promise<SingleValidatorStats | undefined> {
+    expect(validatorAddress).toBeInstanceOf(EthAddress);
+    if (fromSlot !== undefined) {
+      expect(typeof fromSlot).toBe('bigint');
+    }
+    if (toSlot !== undefined) {
+      expect(typeof toSlot).toBe('bigint');
+    }
+    return Promise.resolve(this.singleValidatorStats);
+  }
   simulatePublicCalls(tx: Tx, _enforceFeePayment = false): Promise<PublicSimulationOutput> {
     expect(tx).toBeInstanceOf(Tx);
     return Promise.resolve(PublicSimulationOutput.random());

yarn-project/stdlib/src/interfaces/aztec-node.ts

@@ -7,6 +7,7 @@ import {
   PUBLIC_DATA_TREE_HEIGHT,
 } from '@aztec/constants';
 import { type L1ContractAddresses, L1ContractAddressesSchema } from '@aztec/ethereum/l1-contract-addresses';
+import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Fr } from '@aztec/foundation/fields';
 import { createSafeJsonRpcClient, makeFetch } from '@aztec/foundation/json-rpc/client';
 import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';
@@ -48,8 +49,8 @@ import {
   TxValidationResultSchema,
   indexedTxSchema,
 } from '../tx/index.js';
-import { ValidatorsStatsSchema } from '../validators/schemas.js';
-import type { ValidatorsStats } from '../validators/types.js';
+import { SingleValidatorStatsSchema, ValidatorsStatsSchema } from '../validators/schemas.js';
+import type { SingleValidatorStats, ValidatorsStats } from '../validators/types.js';
 import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 import { MAX_RPC_BLOCKS_LEN, MAX_RPC_LEN, MAX_RPC_TXS_LEN } from './api_limit.js';
 import {
@@ -397,6 +398,13 @@ export interface AztecNode
   /** Returns stats for validators if enabled. */
   getValidatorsStats(): Promise<ValidatorsStats>;
 
+  /** Returns stats for a single validator if enabled. */
+  getValidatorStats(
+    validatorAddress: EthAddress,
+    fromSlot?: bigint,
+    toSlot?: bigint,
+  ): Promise<SingleValidatorStats | undefined>;
+
   /**
    * Simulates the public part of a transaction with the current state.
    * This currently just checks that the transaction execution succeeds.
@@ -577,6 +585,11 @@ export const AztecNodeApiSchema: ApiSchemaFor<AztecNode> = {
 
   getValidatorsStats: z.function().returns(ValidatorsStatsSchema),
 
+  getValidatorStats: z
+    .function()
+    .args(schemas.EthAddress, optional(schemas.BigInt), optional(schemas.BigInt))
+    .returns(SingleValidatorStatsSchema.optional()),
+
   simulatePublicCalls: z.function().args(Tx.schema, optional(z.boolean())).returns(PublicSimulationOutput.schema),
 
   isValidTx: z