@aztec/validator-ha-signer 4.0.0-nightly.20260116 → 4.0.0-nightly.20260118

package/src/slashing_protection_service.ts

@@ -8,9 +8,15 @@ import { type Logger, createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/promise';
 import { sleep } from '@aztec/foundation/sleep';
 
-import { type CheckAndRecordParams, type DeleteDutyParams, DutyStatus, type RecordSuccessParams } from './db/types.js';
+import {
+  type CheckAndRecordParams,
+  type DeleteDutyParams,
+  DutyStatus,
+  type RecordSuccessParams,
+  getBlockIndexFromDutyIdentifier,
+} from './db/types.js';
 import { DutyAlreadySignedError, SlashingProtectionError } from './errors.js';
-import type { SlashingProtectionConfig, SlashingProtectionDatabase } from './types.js';
+import type { SlashingProtectionDatabase, ValidatorHASignerConfig } from './types.js';
 
 /**
  * Slashing Protection Service
@@ -31,21 +37,24 @@ export class SlashingProtectionService {
   private readonly log: Logger;
   private readonly pollingIntervalMs: number;
   private readonly signingTimeoutMs: number;
+  private readonly maxStuckDutiesAgeMs: number;
 
   private cleanupRunningPromise: RunningPromise;
 
   constructor(
     private readonly db: SlashingProtectionDatabase,
-    private readonly config: SlashingProtectionConfig,
+    private readonly config: ValidatorHASignerConfig,
   ) {
     this.log = createLogger('slashing-protection');
     this.pollingIntervalMs = config.pollingIntervalMs;
     this.signingTimeoutMs = config.signingTimeoutMs;
+    // Default to 144s (2x 72s Aztec slot duration) if not explicitly configured
+    this.maxStuckDutiesAgeMs = config.maxStuckDutiesAgeMs ?? 144_000;
 
     this.cleanupRunningPromise = new RunningPromise(
       this.cleanupStuckDuties.bind(this),
       this.log,
-      this.config.maxStuckDutiesAgeMs,
+      this.maxStuckDutiesAgeMs,
     );
   }
 
@@ -98,9 +107,16 @@ export class SlashingProtectionService {
             existingNodeId: record.nodeId,
             attemptingNodeId: nodeId,
           });
-          throw new SlashingProtectionError(slot, dutyType, record.messageHash, messageHash);
+          throw new SlashingProtectionError(
+            slot,
+            dutyType,
+            record.blockIndexWithinCheckpoint,
+            record.messageHash,
+            messageHash,
+            record.nodeId,
+          );
         }
-        throw new DutyAlreadySignedError(slot, dutyType, record.nodeId);
+        throw new DutyAlreadySignedError(slot, dutyType, record.blockIndexWithinCheckpoint, record.nodeId);
       } else if (record.status === DutyStatus.SIGNING) {
         // Another node is currently signing - check for timeout
         if (Date.now() - startTime > this.signingTimeoutMs) {
@@ -109,7 +125,7 @@ export class SlashingProtectionService {
             timeoutMs: this.signingTimeoutMs,
             signingNodeId: record.nodeId,
           });
-          throw new DutyAlreadySignedError(slot, dutyType, 'unknown (timeout)');
+          throw new DutyAlreadySignedError(slot, dutyType, record.blockIndexWithinCheckpoint, 'unknown (timeout)');
         }
 
         // Wait and poll
@@ -134,8 +150,16 @@ export class SlashingProtectionService {
    */
   async recordSuccess(params: RecordSuccessParams): Promise<boolean> {
     const { validatorAddress, slot, dutyType, signature, nodeId, lockToken } = params;
-
-    const success = await this.db.updateDutySigned(validatorAddress, slot, dutyType, signature.toString(), lockToken);
+    const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
+
+    const success = await this.db.updateDutySigned(
+      validatorAddress,
+      slot,
+      dutyType,
+      signature.toString(),
+      lockToken,
+      blockIndexWithinCheckpoint,
+    );
 
     if (success) {
       this.log.info(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
@@ -161,8 +185,9 @@ export class SlashingProtectionService {
    */
   async deleteDuty(params: DeleteDutyParams): Promise<boolean> {
     const { validatorAddress, slot, dutyType, lockToken } = params;
+    const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
 
-    const success = await this.db.deleteDuty(validatorAddress, slot, dutyType, lockToken);
+    const success = await this.db.deleteDuty(validatorAddress, slot, dutyType, lockToken, blockIndexWithinCheckpoint);
 
     if (success) {
       this.log.info(`Deleted duty ${dutyType} at slot ${slot} to allow retry`, {
@@ -201,15 +226,24 @@ export class SlashingProtectionService {
     this.log.info('Slashing protection service stopped', { nodeId: this.config.nodeId });
   }
 
+  /**
+   * Close the database connection.
+   * Should be called after stop() during graceful shutdown.
+   */
+  async close() {
+    await this.db.close();
+    this.log.info('Slashing protection database connection closed');
+  }
+
   /**
    * Cleanup own stuck duties
    */
   private async cleanupStuckDuties() {
-    const numDuties = await this.db.cleanupOwnStuckDuties(this.config.nodeId, this.config.maxStuckDutiesAgeMs);
+    const numDuties = await this.db.cleanupOwnStuckDuties(this.config.nodeId, this.maxStuckDutiesAgeMs);
     if (numDuties > 0) {
       this.log.info(`Cleaned up ${numDuties} stuck duties`, {
         nodeId: this.config.nodeId,
-        maxStuckDutiesAgeMs: this.config.maxStuckDutiesAgeMs,
+        maxStuckDutiesAgeMs: this.maxStuckDutiesAgeMs,
       });
     }
   }

package/src/types.ts

@@ -1,27 +1,31 @@
+import { BlockNumber, type CheckpointNumber, type SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 
 import type { Pool } from 'pg';
 
-import type { CreateHASignerConfig, SlashingProtectionConfig } from './config.js';
-import type {
-  CheckAndRecordParams,
-  DeleteDutyParams,
-  DutyIdentifier,
+import type { ValidatorHASignerConfig } from './config.js';
+import {
+  type BlockProposalDutyIdentifier,
+  type CheckAndRecordParams,
+  type DeleteDutyParams,
+  type DutyIdentifier,
   DutyType,
-  RecordSuccessParams,
-  ValidatorDutyRecord,
+  type OtherDutyIdentifier,
+  type RecordSuccessParams,
+  type ValidatorDutyRecord,
 } from './db/types.js';
 
 export type {
+  BlockProposalDutyIdentifier,
   CheckAndRecordParams,
-  CreateHASignerConfig,
   DeleteDutyParams,
   DutyIdentifier,
+  OtherDutyIdentifier,
   RecordSuccessParams,
-  SlashingProtectionConfig,
   ValidatorDutyRecord,
+  ValidatorHASignerConfig,
 };
-export { DutyStatus, DutyType } from './db/types.js';
+export { DutyStatus, DutyType, getBlockIndexFromDutyIdentifier, normalizeBlockIndex } from './db/types.js';
 
 /**
  * Result of tryInsertOrGetExisting operation
@@ -45,17 +49,97 @@ export interface CreateHASignerDeps {
 }
 
 /**
- * Context required for slashing protection during signing operations
+ * Base context for signing operations
  */
-export interface SigningContext {
+interface BaseSigningContext {
   /** Slot number for this duty */
-  slot: bigint;
-  /** Block number for this duty */
-  blockNumber: bigint;
-  /** Type of duty being performed */
-  dutyType: DutyType;
+  slot: SlotNumber;
+  /**
+   * Block or checkpoint number for this duty.
+   * For block proposals, this is the block number.
+   * For checkpoint proposals, this is the checkpoint number.
+   */
+  blockNumber: BlockNumber | CheckpointNumber;
+}
+
+/**
+ * Signing context for block proposals.
+ * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
+ */
+export interface BlockProposalSigningContext extends BaseSigningContext {
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: number;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Signing context for non-block-proposal duties that require HA protection.
+ * blockIndexWithinCheckpoint is not applicable (internally always -1).
+ */
+export interface OtherSigningContext extends BaseSigningContext {
+  dutyType: DutyType.CHECKPOINT_PROPOSAL | DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ * blockNumber is not applicable (internally always 0).
+ */
+export interface VoteSigningContext {
+  slot: SlotNumber;
+  dutyType: DutyType.GOVERNANCE_VOTE | DutyType.SLASHING_VOTE;
+}
+
+/**
+ * Signing context for duties which don't require slot/blockNumber
+ * as they don't need HA protection (AUTH_REQUEST, TXS).
+ */
+export interface NoHAProtectionSigningContext {
+  dutyType: DutyType.AUTH_REQUEST | DutyType.TXS;
+}
+
+/**
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext = BlockProposalSigningContext | OtherSigningContext | VoteSigningContext;
+
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */
+export function isHAProtectedContext(context: SigningContext): context is HAProtectedSigningContext {
+  return context.dutyType !== DutyType.AUTH_REQUEST && context.dutyType !== DutyType.TXS;
+}
+
+/**
+ * Gets the block number from a signing context.
+ * - Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE): returns BlockNumber(0)
+ * - Other duties: returns the blockNumber from the context
+ */
+export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber | CheckpointNumber {
+  // Check for duty types that have blockNumber
+  if (
+    context.dutyType === DutyType.BLOCK_PROPOSAL ||
+    context.dutyType === DutyType.CHECKPOINT_PROPOSAL ||
+    context.dutyType === DutyType.ATTESTATION ||
+    context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS
+  ) {
+    return context.blockNumber;
+  }
+  // Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE) don't have blockNumber
+  return BlockNumber(0);
 }
 
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ * - Vote duties only need slot (blockNumber is internally 0)
+ * - AUTH_REQUEST and TXS duties don't need slot/blockNumber (no HA protection needed)
+ */
+export type SigningContext = HAProtectedSigningContext | NoHAProtectionSigningContext;
+
 /**
  * Database interface for slashing protection operations
  * This abstraction allows for different database implementations (PostgreSQL, SQLite, etc.)
@@ -82,10 +166,11 @@ export interface SlashingProtectionDatabase {
    */
   updateDutySigned(
     validatorAddress: EthAddress,
-    slot: bigint,
+    slot: SlotNumber,
     dutyType: DutyType,
     signature: string,
     lockToken: string,
+    blockIndexWithinCheckpoint: number,
   ): Promise<boolean>;
 
   /**
@@ -95,11 +180,23 @@ export interface SlashingProtectionDatabase {
    *
    * @returns true if the delete succeeded, false if token didn't match or duty not found
    */
-  deleteDuty(validatorAddress: EthAddress, slot: bigint, dutyType: DutyType, lockToken: string): Promise<boolean>;
+  deleteDuty(
+    validatorAddress: EthAddress,
+    slot: SlotNumber,
+    dutyType: DutyType,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): Promise<boolean>;
 
   /**
    * Cleanup own stuck duties
    * @returns the number of duties cleaned up
    */
   cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+
+  /**
+   * Close the database connection.
+   * Should be called during graceful shutdown.
+   */
+  close(): Promise<void>;
 }

package/src/validator_ha_signer.ts

@@ -10,9 +10,14 @@ import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 
-import type { CreateHASignerConfig } from './config.js';
+import type { ValidatorHASignerConfig } from './config.js';
+import { type DutyIdentifier, DutyType } from './db/types.js';
 import { SlashingProtectionService } from './slashing_protection_service.js';
-import type { SigningContext, SlashingProtectionDatabase } from './types.js';
+import {
+  type HAProtectedSigningContext,
+  type SlashingProtectionDatabase,
+  getBlockNumberFromSigningContext,
+} from './types.js';
 
 /**
  * Validator High Availability Signer
@@ -35,15 +40,15 @@ import type { SigningContext, SlashingProtectionDatabase } from './types.js';
  */
 export class ValidatorHASigner {
   private readonly log: Logger;
-  private readonly slashingProtection: SlashingProtectionService | undefined;
+  private readonly slashingProtection: SlashingProtectionService;
 
   constructor(
     db: SlashingProtectionDatabase,
-    private readonly config: CreateHASignerConfig,
+    private readonly config: ValidatorHASignerConfig,
   ) {
     this.log = createLogger('validator-ha-signer');
 
-    if (!config.enabled) {
+    if (!config.haSigningEnabled) {
       // this shouldn't happen, the validator should use different signer for non-HA setups
       throw new Error('Validator HA Signer is not enabled in config');
     }
@@ -67,7 +72,7 @@ export class ValidatorHASigner {
    *
    * @param validatorAddress - The validator's Ethereum address
    * @param messageHash - The hash to be signed
-   * @param context - The signing context (slot, block number, duty type)
+   * @param context - The signing context (HA-protected duty types only)
    * @param signFn - Function that performs the actual signing
    * @returns The signature
    *
@@ -77,29 +82,30 @@ export class ValidatorHASigner {
   async signWithProtection(
     validatorAddress: EthAddress,
     messageHash: Buffer32,
-    context: SigningContext,
+    context: HAProtectedSigningContext,
     signFn: (messageHash: Buffer32) => Promise<Signature>,
   ): Promise<Signature> {
-    // If slashing protection is disabled, just sign directly
-    if (!this.slashingProtection) {
-      this.log.info('Signing without slashing protection enabled', {
-        validatorAddress: validatorAddress.toString(),
-        nodeId: this.config.nodeId,
+    let dutyIdentifier: DutyIdentifier;
+    if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+      dutyIdentifier = {
+        validatorAddress,
+        slot: context.slot,
+        blockIndexWithinCheckpoint: context.blockIndexWithinCheckpoint,
         dutyType: context.dutyType,
+      };
+    } else {
+      dutyIdentifier = {
+        validatorAddress,
         slot: context.slot,
-        blockNumber: context.blockNumber,
-      });
-      return await signFn(messageHash);
+        dutyType: context.dutyType,
+      };
     }
 
-    const { slot, blockNumber, dutyType } = context;
-
     // Acquire lock and get the token for ownership verification
+    const blockNumber = getBlockNumberFromSigningContext(context);
     const lockToken = await this.slashingProtection.checkAndRecord({
-      validatorAddress,
-      slot,
+      ...dutyIdentifier,
       blockNumber,
-      dutyType,
       messageHash: messageHash.toString(),
       nodeId: this.config.nodeId,
     });
@@ -110,20 +116,13 @@ export class ValidatorHASigner {
       signature = await signFn(messageHash);
     } catch (error: any) {
       // Delete duty to allow retry (only succeeds if we own the lock)
-      await this.slashingProtection.deleteDuty({
-        validatorAddress,
-        slot,
-        dutyType,
-        lockToken,
-      });
+      await this.slashingProtection.deleteDuty({ ...dutyIdentifier, lockToken });
       throw error;
     }
 
     // Record success (only succeeds if we own the lock)
     await this.slashingProtection.recordSuccess({
-      validatorAddress,
-      slot,
-      dutyType,
+      ...dutyIdentifier,
       signature,
       nodeId: this.config.nodeId,
       lockToken,
@@ -132,13 +131,6 @@ export class ValidatorHASigner {
     return signature;
   }
 
-  /**
-   * Check if slashing protection is enabled
-   */
-  get isEnabled(): boolean {
-    return this.slashingProtection !== undefined;
-  }
-
   /**
    * Get the node ID for this signer
    */
@@ -151,14 +143,15 @@ export class ValidatorHASigner {
    * Should be called after construction and before signing operations.
    */
   start() {
-    this.slashingProtection?.start();
+    this.slashingProtection.start();
   }
 
   /**
-   * Stop the HA signer background tasks.
+   * Stop the HA signer background tasks and close database connection.
    * Should be called during graceful shutdown.
    */
   async stop() {
-    await this.slashingProtection?.stop();
+    await this.slashingProtection.stop();
+    await this.slashingProtection.close();
   }
 }