Add getValidatorStats RPC method to AztecNode server

Co-authored-by: 0x4r45h <[email protected]>

Author: 2 people

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