@aztec/validator-ha-signer 0.0.1-commit.7d4e6cd → 0.0.1-commit.d1f2d6c

package/dest/validator_ha_signer.js

@@ -5,7 +5,9 @@
  * This ensures that even with multiple validator nodes running, only one
  * node will sign for a given duty (slot + duty type).
  */ import { createLogger } from '@aztec/foundation/log';
+import { DutyType } from './db/types.js';
 import { SlashingProtectionService } from './slashing_protection_service.js';
+import { getBlockNumberFromSigningContext } from './types.js';
 /**
  * Validator High Availability Signer
  *
@@ -31,7 +33,7 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
     constructor(db, config){
         this.config = config;
         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');
         }
@@ -53,31 +55,33 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
    *
    * @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
    *
    * @throws DutyAlreadySignedError if the duty was already signed (expected in HA)
    * @throws SlashingProtectionError if attempting to sign different data for same slot (expected in HA)
    */ async signWithProtection(validatorAddress, messageHash, context, signFn) {
-        // 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,
-                dutyType: context.dutyType,
+        let dutyIdentifier;
+        if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+            dutyIdentifier = {
+                validatorAddress,
                 slot: context.slot,
-                blockNumber: context.blockNumber
-            });
-            return await signFn(messageHash);
+                blockIndexWithinCheckpoint: context.blockIndexWithinCheckpoint,
+                dutyType: context.dutyType
+            };
+        } else {
+            dutyIdentifier = {
+                validatorAddress,
+                slot: context.slot,
+                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
         });
@@ -88,18 +92,14 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
         } catch (error) {
             // Delete duty to allow retry (only succeeds if we own the lock)
             await this.slashingProtection.deleteDuty({
-                validatorAddress,
-                slot,
-                dutyType,
+                ...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
@@ -107,11 +107,6 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
         return signature;
     }
     /**
-   * Check if slashing protection is enabled
-   */ get isEnabled() {
-        return this.slashingProtection !== undefined;
-    }
-    /**
    * Get the node ID for this signer
    */ get nodeId() {
         return this.config.nodeId;
@@ -120,12 +115,13 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
    * Start the HA signer background tasks (cleanup of stuck duties).
    * 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();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/validator-ha-signer",
-  "version": "0.0.1-commit.7d4e6cd",
+  "version": "0.0.1-commit.d1f2d6c",
   "type": "module",
   "exports": {
     "./config": "./dest/config.js",
@@ -10,7 +10,8 @@
     "./migrations": "./dest/migrations.js",
     "./slashing-protection-service": "./dest/slashing_protection_service.js",
     "./types": "./dest/types.js",
-    "./validator-ha-signer": "./dest/validator_ha_signer.js"
+    "./validator-ha-signer": "./dest/validator_ha_signer.js",
+    "./test": "./dest/test/pglite_pool.js"
   },
   "typedocOptions": {
     "entryPoints": [
@@ -73,21 +74,20 @@
     ]
   },
   "dependencies": {
-    "@aztec/foundation": "0.0.1-commit.7d4e6cd",
-    "@aztec/node-keystore": "0.0.1-commit.7d4e6cd",
+    "@aztec/foundation": "0.0.1-commit.d1f2d6c",
     "node-pg-migrate": "^8.0.4",
     "pg": "^8.11.3",
-    "tslib": "^2.4.0"
+    "tslib": "^2.4.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.2.17",
+    "@electric-sql/pglite": "^0.3.14",
     "@jest/globals": "^30.0.0",
-    "@middle-management/pglite-pg-adapter": "^0.0.3",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.15.17",
     "@types/node-pg-migrate": "^2.3.1",
     "@types/pg": "^8.10.9",
-    "@typescript/native-preview": "7.0.0-dev.20251126.1",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
     "jest": "^30.0.0",
     "jest-mock-extended": "^4.0.0",
     "ts-node": "^10.9.1",

package/src/config.ts

@@ -4,66 +4,34 @@ import {
   getConfigFromMappings,
   getDefaultConfig,
   numberConfigHelper,
+  optionalNumberConfigHelper,
 } from '@aztec/foundation/config';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
 
 /**
- * Configuration for the slashing protection service
+ * Configuration for the Validator HA Signer
+ *
+ * This config is used for distributed locking and slashing protection
+ * when running multiple validator nodes in a high-availability setup.
  */
-export interface SlashingProtectionConfig {
-  /** Whether slashing protection is enabled */
-  enabled: boolean;
+export interface ValidatorHASignerConfig {
+  /** Whether HA signing / slashing protection is enabled */
+  haSigningEnabled: boolean;
   /** Unique identifier for this node */
   nodeId: string;
   /** How long to wait between polls when a duty is being signed (ms) */
   pollingIntervalMs: number;
   /** Maximum time to wait for a duty being signed to complete (ms) */
   signingTimeoutMs: number;
-  /** Maximum age of a stuck duty in ms */
-  maxStuckDutiesAgeMs: number;
-}
-
-export const slashingProtectionConfigMappings: ConfigMappingsType<SlashingProtectionConfig> = {
-  enabled: {
-    env: 'SLASHING_PROTECTION_ENABLED',
-    description: 'Whether slashing protection is enabled',
-    ...booleanConfigHelper(true),
-  },
-  nodeId: {
-    env: 'SLASHING_PROTECTION_NODE_ID',
-    description: 'The unique identifier for this node',
-    defaultValue: '',
-  },
-  pollingIntervalMs: {
-    env: 'SLASHING_PROTECTION_POLLING_INTERVAL_MS',
-    description: 'The number of ms to wait between polls when a duty is being signed',
-    ...numberConfigHelper(100),
-  },
-  signingTimeoutMs: {
-    env: 'SLASHING_PROTECTION_SIGNING_TIMEOUT_MS',
-    description: 'The maximum time to wait for a duty being signed to complete',
-    ...numberConfigHelper(3_000),
-  },
-  maxStuckDutiesAgeMs: {
-    env: 'SLASHING_PROTECTION_MAX_STUCK_DUTIES_AGE_MS',
-    description: 'The maximum age of a stuck duty in ms',
-    // hard-coding at current 2 slot duration. This should be set by the validator on init
-    ...numberConfigHelper(72_000),
-  },
-};
-
-export const defaultSlashingProtectionConfig: SlashingProtectionConfig = getDefaultConfig(
-  slashingProtectionConfigMappings,
-);
-
-/**
- * Configuration for creating an HA signer with PostgreSQL backend
- */
-export interface CreateHASignerConfig extends SlashingProtectionConfig {
+  /** Maximum age of a stuck duty in ms (defaults to 2x hardcoded Aztec slot duration if not set) */
+  maxStuckDutiesAgeMs?: number;
   /**
    * PostgreSQL connection string
    * Format: postgresql://user:password@host:port/database
    */
-  databaseUrl: string;
+  databaseUrl?: string;
   /**
    * PostgreSQL connection pool configuration
    */
@@ -77,8 +45,32 @@ export interface CreateHASignerConfig extends SlashingProtectionConfig {
   poolConnectionTimeoutMs?: number;
 }
 
-export const createHASignerConfigMappings: ConfigMappingsType<CreateHASignerConfig> = {
-  ...slashingProtectionConfigMappings,
+export const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig> = {
+  haSigningEnabled: {
+    env: 'VALIDATOR_HA_SIGNING_ENABLED',
+    description: 'Whether HA signing / slashing protection is enabled',
+    ...booleanConfigHelper(false),
+  },
+  nodeId: {
+    env: 'VALIDATOR_HA_NODE_ID',
+    description: 'The unique identifier for this node',
+    defaultValue: '',
+  },
+  pollingIntervalMs: {
+    env: 'VALIDATOR_HA_POLLING_INTERVAL_MS',
+    description: 'The number of ms to wait between polls when a duty is being signed',
+    ...numberConfigHelper(100),
+  },
+  signingTimeoutMs: {
+    env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
+    description: 'The maximum time to wait for a duty being signed to complete',
+    ...numberConfigHelper(3_000),
+  },
+  maxStuckDutiesAgeMs: {
+    env: 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS',
+    description: 'The maximum age of a stuck duty in ms (defaults to 2x Aztec slot duration)',
+    ...optionalNumberConfigHelper(),
+  },
   databaseUrl: {
     env: 'VALIDATOR_HA_DATABASE_URL',
     description:
@@ -106,11 +98,28 @@ export const createHASignerConfigMappings: ConfigMappingsType<CreateHASignerConf
   },
 };
 
+export const defaultValidatorHASignerConfig: ValidatorHASignerConfig = getDefaultConfig(
+  validatorHASignerConfigMappings,
+);
+
 /**
  * Returns the validator HA signer configuration from environment variables.
  * Note: If an environment variable is not set, the default value is used.
  * @returns The validator HA signer configuration.
  */
-export function getConfigEnvVars(): CreateHASignerConfig {
-  return getConfigFromMappings<CreateHASignerConfig>(createHASignerConfigMappings);
+export function getConfigEnvVars(): ValidatorHASignerConfig {
+  return getConfigFromMappings<ValidatorHASignerConfig>(validatorHASignerConfigMappings);
 }
+
+export const ValidatorHASignerConfigSchema = z.object({
+  haSigningEnabled: z.boolean(),
+  nodeId: z.string(),
+  pollingIntervalMs: z.number().min(0),
+  signingTimeoutMs: z.number().min(0),
+  maxStuckDutiesAgeMs: z.number().min(0).optional(),
+  databaseUrl: z.string().optional(),
+  poolMaxCount: z.number().min(0).optional(),
+  poolMinCount: z.number().min(0).optional(),
+  poolIdleTimeoutMs: z.number().min(0).optional(),
+  poolConnectionTimeoutMs: z.number().min(0).optional(),
+}) satisfies ZodFor<ValidatorHASignerConfig>;

package/src/db/postgres.ts

@@ -1,11 +1,13 @@
 /**
  * PostgreSQL implementation of SlashingProtectionDatabase
  */
+import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { randomBytes } from '@aztec/foundation/crypto/random';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
+import { makeBackoff, retry } from '@aztec/foundation/retry';
 
-import type { Pool, QueryResult } from 'pg';
+import type { QueryResult, QueryResultRow } from 'pg';
 
 import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
 import {
@@ -16,6 +18,16 @@ import {
   UPDATE_DUTY_SIGNED,
 } from './schema.js';
 import type { CheckAndRecordParams, DutyRow, DutyType, InsertOrGetRow, ValidatorDutyRecord } from './types.js';
+import { getBlockIndexFromDutyIdentifier } from './types.js';
+
+/**
+ * Minimal pool interface for database operations.
+ * Both pg.Pool and test adapters (e.g., PGlite) satisfy this interface.
+ */
+export interface QueryablePool {
+  query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>>;
+  end(): Promise<void>;
+}
 
 /**
  * PostgreSQL implementation of the slashing protection database
@@ -23,7 +35,7 @@ import type { CheckAndRecordParams, DutyRow, DutyType, InsertOrGetRow, Validator
 export class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
   private readonly log: Logger;
 
-  constructor(private readonly pool: Pool) {
+  constructor(private readonly pool: QueryablePool) {
     this.log = createLogger('slashing-protection:postgres');
   }
 
@@ -48,13 +60,13 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
       dbVersion = result.rows[0].version;
     } catch {
       throw new Error(
-        'Database schema not initialized. Please run migrations first: aztec migrate up --database-url <url>',
+        'Database schema not initialized. Please run migrations first: aztec migrate-ha-db up --database-url <url>',
       );
     }
 
     if (dbVersion < SCHEMA_VERSION) {
       throw new Error(
-        `Database schema version ${dbVersion} is outdated (expected ${SCHEMA_VERSION}). Please run migrations: aztec migrate up --database-url <url>`,
+        `Database schema version ${dbVersion} is outdated (expected ${SCHEMA_VERSION}). Please run migrations: aztec migrate-ha-db up --database-url <url>`,
       );
     }
 
@@ -72,24 +84,54 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
    *
    * @returns { isNew: true, record } if we successfully inserted and acquired the lock
    * @returns { isNew: false, record } if a record already exists. lock_token is empty if the record already exists.
+   *
+   * Retries if no rows are returned, which can happen under high concurrency
+   * when another transaction just committed the row but it's not yet visible.
    */
   async tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult> {
     // create a token for ownership verification
     const lockToken = randomBytes(16).toString('hex');
 
-    const result: QueryResult<InsertOrGetRow> = await this.pool.query(INSERT_OR_GET_DUTY, [
-      params.validatorAddress.toString(),
-      params.slot.toString(),
-      params.blockNumber.toString(),
-      params.dutyType,
-      params.messageHash,
-      params.nodeId,
-      lockToken,
-    ]);
+    // Use fast retries with custom backoff: 10ms, 20ms, 30ms (then stop)
+    const fastBackoff = makeBackoff([0.01, 0.02, 0.03]);
+
+    // Get the normalized block index using type-safe helper
+    const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
+
+    const result = await retry<QueryResult<InsertOrGetRow>>(
+      async () => {
+        const queryResult: QueryResult<InsertOrGetRow> = await this.pool.query(INSERT_OR_GET_DUTY, [
+          params.validatorAddress.toString(),
+          params.slot.toString(),
+          params.blockNumber.toString(),
+          blockIndexWithinCheckpoint,
+          params.dutyType,
+          params.messageHash,
+          params.nodeId,
+          lockToken,
+        ]);
+
+        // Throw error if no rows to trigger retry
+        if (queryResult.rows.length === 0) {
+          throw new Error('INSERT_OR_GET_DUTY returned no rows');
+        }
+
+        return queryResult;
+      },
+      `INSERT_OR_GET_DUTY for node ${params.nodeId}`,
+      fastBackoff,
+      this.log,
+      true,
+    );
 
     if (result.rows.length === 0) {
-      // This shouldn't happen - the query always returns either the inserted or existing row
-      throw new Error('INSERT_OR_GET_DUTY returned no rows');
+      // this should never happen as the retry function should throw if it still fails after retries
+      throw new Error('INSERT_OR_GET_DUTY returned no rows after retries');
+    }
+
+    if (result.rows.length > 1) {
+      // this should never happen if database constraints are correct (PRIMARY KEY should prevent duplicates)
+      throw new Error(`INSERT_OR_GET_DUTY returned ${result.rows.length} rows (expected exactly 1).`);
     }
 
     const row = result.rows[0];
@@ -107,16 +149,18 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
    */
   async updateDutySigned(
     validatorAddress: EthAddress,
-    slot: bigint,
+    slot: SlotNumber,
     dutyType: DutyType,
     signature: string,
     lockToken: string,
+    blockIndexWithinCheckpoint: number,
   ): Promise<boolean> {
     const result = await this.pool.query(UPDATE_DUTY_SIGNED, [
       signature,
       validatorAddress.toString(),
       slot.toString(),
       dutyType,
+      blockIndexWithinCheckpoint,
       lockToken,
     ]);
 
@@ -125,6 +169,7 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
         validatorAddress: validatorAddress.toString(),
         slot: slot.toString(),
         dutyType,
+        blockIndexWithinCheckpoint,
       });
       return false;
     }
@@ -140,14 +185,16 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
    */
   async deleteDuty(
     validatorAddress: EthAddress,
-    slot: bigint,
+    slot: SlotNumber,
     dutyType: DutyType,
     lockToken: string,
+    blockIndexWithinCheckpoint: number,
   ): Promise<boolean> {
     const result = await this.pool.query(DELETE_DUTY, [
       validatorAddress.toString(),
       slot.toString(),
       dutyType,
+      blockIndexWithinCheckpoint,
       lockToken,
     ]);
 
@@ -156,6 +203,7 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
         validatorAddress: validatorAddress.toString(),
         slot: slot.toString(),
         dutyType,
+        blockIndexWithinCheckpoint,
       });
       return false;
     }
@@ -168,8 +216,9 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
   private rowToRecord(row: DutyRow): ValidatorDutyRecord {
     return {
       validatorAddress: EthAddress.fromString(row.validator_address),
-      slot: BigInt(row.slot),
-      blockNumber: BigInt(row.block_number),
+      slot: SlotNumber.fromString(row.slot),
+      blockNumber: BlockNumber.fromString(row.block_number),
+      blockIndexWithinCheckpoint: row.block_index_within_checkpoint,
       dutyType: row.duty_type,
       status: row.status,
       messageHash: row.message_hash,

package/src/db/schema.ts

@@ -19,7 +19,8 @@ CREATE TABLE IF NOT EXISTS validator_duties (
   validator_address VARCHAR(42) NOT NULL,
   slot BIGINT NOT NULL,
   block_number BIGINT NOT NULL,
-  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS')),
+  block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,
+  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),
   status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed', 'failed')),
   message_hash VARCHAR(66) NOT NULL,
   signature VARCHAR(132),
@@ -29,7 +30,7 @@ CREATE TABLE IF NOT EXISTS validator_duties (
   completed_at TIMESTAMP,
   error_message TEXT,
 
-  PRIMARY KEY (validator_address, slot, duty_type),
+  PRIMARY KEY (validator_address, slot, duty_type, block_index_within_checkpoint),
   CHECK (completed_at IS NULL OR completed_at >= started_at)
 );
 `;
@@ -92,6 +93,10 @@ SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;
  * returns the existing record instead.
  *
  * Returns the record with an `is_new` flag indicating whether we inserted or got existing.
+ *
+ * Note: In high concurrency scenarios, if the INSERT conflicts and another transaction
+ * just committed the row, there's a small window where the SELECT might not see it yet.
+ * The application layer should retry if no rows are returned.
  */
 export const INSERT_OR_GET_DUTY = `
 WITH inserted AS (
@@ -99,18 +104,20 @@ WITH inserted AS (
     validator_address,
     slot,
     block_number,
+    block_index_within_checkpoint,
     duty_type,
     status,
     message_hash,
     node_id,
     lock_token,
     started_at
-  ) VALUES ($1, $2, $3, $4, 'signing', $5, $6, $7, CURRENT_TIMESTAMP)
-  ON CONFLICT (validator_address, slot, duty_type) DO NOTHING
+  ) VALUES ($1, $2, $3, $4, $5, 'signing', $6, $7, $8, CURRENT_TIMESTAMP)
+  ON CONFLICT (validator_address, slot, duty_type, block_index_within_checkpoint) DO NOTHING
   RETURNING
     validator_address,
     slot,
     block_number,
+    block_index_within_checkpoint,
     duty_type,
     status,
     message_hash,
@@ -128,6 +135,7 @@ SELECT
   validator_address,
   slot,
   block_number,
+  block_index_within_checkpoint,
   duty_type,
   status,
   message_hash,
@@ -141,7 +149,8 @@ SELECT
 FROM validator_duties
 WHERE validator_address = $1
   AND slot = $2
-  AND duty_type = $4
+  AND duty_type = $5
+  AND block_index_within_checkpoint = $4
   AND NOT EXISTS (SELECT 1 FROM inserted);
 `;
 
@@ -156,8 +165,9 @@ SET status = 'signed',
 WHERE validator_address = $2
   AND slot = $3
   AND duty_type = $4
+  AND block_index_within_checkpoint = $5
   AND status = 'signing'
-  AND lock_token = $5;
+  AND lock_token = $6;
 `;
 
 /**
@@ -169,8 +179,9 @@ DELETE FROM validator_duties
 WHERE validator_address = $1
   AND slot = $2
   AND duty_type = $3
+  AND block_index_within_checkpoint = $4
   AND status = 'signing'
-  AND lock_token = $4;
+  AND lock_token = $5;
 `;
 
 /**
@@ -223,6 +234,7 @@ SELECT
   validator_address,
   slot,
   block_number,
+  block_index_within_checkpoint,
   duty_type,
   status,
   message_hash,