@aztec/validator-ha-signer 4.0.0-nightly.20260115 → 4.0.0-nightly.20260117

package/src/db/postgres.ts

@@ -1,9 +1,11 @@
 /**
  * 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 { QueryResult, QueryResultRow } from 'pg';
 
@@ -16,6 +18,7 @@ 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.
@@ -57,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>`,
       );
     }
 
@@ -81,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];
@@ -116,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,
     ]);
 
@@ -134,6 +169,7 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
         validatorAddress: validatorAddress.toString(),
         slot: slot.toString(),
         dutyType,
+        blockIndexWithinCheckpoint,
       });
       return false;
     }
@@ -149,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,
     ]);
 
@@ -165,6 +203,7 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
         validatorAddress: validatorAddress.toString(),
         slot: slot.toString(),
         dutyType,
+        blockIndexWithinCheckpoint,
       });
       return false;
     }
@@ -177,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,

package/src/db/types.ts

@@ -1,3 +1,4 @@
+import type { BlockNumber, CheckpointNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
 
@@ -8,6 +9,7 @@ export interface DutyRow {
   validator_address: string;
   slot: string;
   block_number: string;
+  block_index_within_checkpoint: number;
   duty_type: DutyType;
   status: DutyStatus;
   message_hash: string;
@@ -31,8 +33,13 @@ export interface InsertOrGetRow extends DutyRow {
  */
 export enum DutyType {
   BLOCK_PROPOSAL = 'BLOCK_PROPOSAL',
+  CHECKPOINT_PROPOSAL = 'CHECKPOINT_PROPOSAL',
   ATTESTATION = 'ATTESTATION',
   ATTESTATIONS_AND_SIGNERS = 'ATTESTATIONS_AND_SIGNERS',
+  GOVERNANCE_VOTE = 'GOVERNANCE_VOTE',
+  SLASHING_VOTE = 'SLASHING_VOTE',
+  AUTH_REQUEST = 'AUTH_REQUEST',
+  TXS = 'TXS',
 }
 
 /**
@@ -50,9 +57,11 @@ export interface ValidatorDutyRecord {
   /** Ethereum address of the validator */
   validatorAddress: EthAddress;
   /** Slot number for this duty */
-  slot: bigint;
+  slot: SlotNumber;
   /** Block number for this duty */
-  blockNumber: bigint;
+  blockNumber: BlockNumber;
+  /** Block index within checkpoint (0, 1, 2... for block proposals, -1 for other duty types) */
+  blockIndexWithinCheckpoint: number;
   /** Type of duty being performed */
   dutyType: DutyType;
   /** Current status of the duty */
@@ -74,44 +83,119 @@ export interface ValidatorDutyRecord {
 }
 
 /**
- * Minimal info needed to identify a unique duty
+ * Duty identifier for block proposals.
+ * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
  */
-export interface DutyIdentifier {
+export interface BlockProposalDutyIdentifier {
   validatorAddress: EthAddress;
-  slot: bigint;
-  dutyType: DutyType;
+  slot: SlotNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: number;
+  dutyType: DutyType.BLOCK_PROPOSAL;
 }
 
 /**
- * Parameters for checking and recording a new duty
+ * Duty identifier for non-block-proposal duties.
+ * blockIndexWithinCheckpoint is not applicable (internally stored as -1).
  */
-export interface CheckAndRecordParams {
+export interface OtherDutyIdentifier {
   validatorAddress: EthAddress;
-  slot: bigint;
-  blockNumber: bigint;
-  dutyType: DutyType;
+  slot: SlotNumber;
+  dutyType:
+    | DutyType.CHECKPOINT_PROPOSAL
+    | DutyType.ATTESTATION
+    | DutyType.ATTESTATIONS_AND_SIGNERS
+    | DutyType.GOVERNANCE_VOTE
+    | DutyType.SLASHING_VOTE
+    | DutyType.AUTH_REQUEST
+    | DutyType.TXS;
+}
+
+/**
+ * Minimal info needed to identify a unique duty.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ */
+export type DutyIdentifier = BlockProposalDutyIdentifier | OtherDutyIdentifier;
+
+/**
+ * Validates and normalizes the block index for a duty.
+ * - BLOCK_PROPOSAL: validates blockIndexWithinCheckpoint is provided and >= 0
+ * - Other duty types: always returns -1
+ *
+ * @throws Error if BLOCK_PROPOSAL is missing blockIndexWithinCheckpoint or has invalid value
+ */
+export function normalizeBlockIndex(dutyType: DutyType, blockIndexWithinCheckpoint: number | undefined): number {
+  if (dutyType === DutyType.BLOCK_PROPOSAL) {
+    if (blockIndexWithinCheckpoint === undefined) {
+      throw new Error('BLOCK_PROPOSAL duties require blockIndexWithinCheckpoint to be specified');
+    }
+    if (blockIndexWithinCheckpoint < 0) {
+      throw new Error(
+        `BLOCK_PROPOSAL duties require blockIndexWithinCheckpoint >= 0, got ${blockIndexWithinCheckpoint}`,
+      );
+    }
+    return blockIndexWithinCheckpoint;
+  }
+  // For all other duty types, always use -1
+  return -1;
+}
+
+/**
+ * Gets the block index from a DutyIdentifier.
+ * - BLOCK_PROPOSAL: returns the blockIndexWithinCheckpoint
+ * - Other duty types: returns -1
+ */
+export function getBlockIndexFromDutyIdentifier(duty: DutyIdentifier): number {
+  if (duty.dutyType === DutyType.BLOCK_PROPOSAL) {
+    return duty.blockIndexWithinCheckpoint;
+  }
+  return -1;
+}
+
+/**
+ * Additional parameters for checking and recording a new duty
+ */
+interface CheckAndRecordExtra {
+  /** Block number for this duty */
+  blockNumber: BlockNumber | CheckpointNumber;
+  /** The signing root (hash) for this duty */
   messageHash: string;
+  /** Identifier for the node that acquired the lock */
   nodeId: string;
 }
 
 /**
- * Parameters for recording a successful signing
+ * Parameters for checking and recording a new duty.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
  */
-export interface RecordSuccessParams {
-  validatorAddress: EthAddress;
-  slot: bigint;
-  dutyType: DutyType;
+export type CheckAndRecordParams = DutyIdentifier & CheckAndRecordExtra;
+
+/**
+ * Additional parameters for recording a successful signing
+ */
+interface RecordSuccessExtra {
   signature: Signature;
   nodeId: string;
   lockToken: string;
 }
 
 /**
- * Parameters for deleting a duty
+ * Parameters for recording a successful signing.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
  */
-export interface DeleteDutyParams {
-  validatorAddress: EthAddress;
-  slot: bigint;
-  dutyType: DutyType;
+export type RecordSuccessParams = DutyIdentifier & RecordSuccessExtra;
+
+/**
+ * Additional parameters for deleting a duty
+ */
+interface DeleteDutyExtra {
   lockToken: string;
 }
+
+/**
+ * Parameters for deleting a duty.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
+ */
+export type DeleteDutyParams = DutyIdentifier & DeleteDutyExtra;

package/src/errors.ts

@@ -1,6 +1,8 @@
 /**
  * Custom errors for the validator HA signer
  */
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+
 import type { DutyType } from './db/types.js';
 
 /**
@@ -10,8 +12,9 @@ import type { DutyType } from './db/types.js';
  */
 export class DutyAlreadySignedError extends Error {
   constructor(
-    public readonly slot: bigint,
+    public readonly slot: SlotNumber,
     public readonly dutyType: DutyType,
+    public readonly blockIndexWithinCheckpoint: number,
     public readonly signedByNode: string,
   ) {
     super(`Duty ${dutyType} for slot ${slot} already signed by node ${signedByNode}`);
@@ -28,10 +31,12 @@ export class DutyAlreadySignedError extends Error {
  */
 export class SlashingProtectionError extends Error {
   constructor(
-    public readonly slot: bigint,
+    public readonly slot: SlotNumber,
     public readonly dutyType: DutyType,
+    public readonly blockIndexWithinCheckpoint: number,
     public readonly existingMessageHash: string,
     public readonly attemptedMessageHash: string,
+    public readonly signedByNode: string,
   ) {
     super(
       `Slashing protection: ${dutyType} for slot ${slot} was already signed with different data. ` +

package/src/factory.ts

@@ -3,7 +3,7 @@
  */
 import { Pool } from 'pg';
 
-import type { CreateHASignerConfig } from './config.js';
+import type { ValidatorHASignerConfig } from './config.js';
 import { PostgresSlashingProtectionDatabase } from './db/postgres.js';
 import type { CreateHASignerDeps, SlashingProtectionDatabase } from './types.js';
 import { ValidatorHASigner } from './validator_ha_signer.js';
@@ -23,7 +23,7 @@ import { ValidatorHASigner } from './validator_ha_signer.js';
  * ```typescript
  * const { signer, db } = await createHASigner({
  *   databaseUrl: process.env.DATABASE_URL,
- *   enabled: true,
+ *   haSigningEnabled: true,
  *   nodeId: 'validator-node-1',
  *   pollingIntervalMs: 100,
  *   signingTimeoutMs: 3000,
@@ -35,23 +35,15 @@ import { ValidatorHASigner } from './validator_ha_signer.js';
  * await signer.stop(); // On shutdown
  * ```
  *
- * Example with automatic migrations (simpler for dev/testing):
- * ```typescript
- * const { signer, db } = await createHASigner({
- *   databaseUrl: process.env.DATABASE_URL,
- *   enabled: true,
- *   nodeId: 'validator-node-1',
- *   runMigrations: true, // Auto-run migrations on startup
- * });
- * signer.start();
- * ```
+ * Note: Migrations must be run separately using `aztec migrate-ha-db up` before
+ * creating the signer. The factory will verify the schema is initialized via `db.initialize()`.
  *
  * @param config - Configuration for the HA signer
  * @param deps - Optional dependencies (e.g., for testing)
  * @returns An object containing the signer and database instances
  */
 export async function createHASigner(
-  config: CreateHASignerConfig,
+  config: ValidatorHASignerConfig,
   deps?: CreateHASignerDeps,
 ): Promise<{
   signer: ValidatorHASigner;
@@ -60,6 +52,9 @@ export async function createHASigner(
   const { databaseUrl, poolMaxCount, poolMinCount, poolIdleTimeoutMs, poolConnectionTimeoutMs, ...signerConfig } =
     config;
 
+  if (!databaseUrl) {
+    throw new Error('databaseUrl is required for createHASigner');
+  }
   // Create connection pool (or use provided pool)
   let pool: Pool;
   if (!deps?.pool) {

package/src/migrations.ts

@@ -3,6 +3,7 @@
  */
 import { createLogger } from '@aztec/foundation/log';
 
+import { readdirSync } from 'fs';
 import { runner } from 'node-pg-migrate';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -30,17 +31,32 @@ export async function runMigrations(databaseUrl: string, options: RunMigrationsO
 
   const log = createLogger('validator-ha-signer:migrations');
 
+  const migrationsDir = join(__dirname, 'db', 'migrations');
+
   try {
     log.info(`Running migrations ${direction}...`);
 
+    // Filter out .d.ts and .d.ts.map files - node-pg-migrate only needs .js files
+    const migrationFiles = readdirSync(migrationsDir);
+    const jsMigrationFiles = migrationFiles.filter(
+      file => file.endsWith('.js') && !file.endsWith('.d.ts') && !file.endsWith('.d.ts.map'),
+    );
+
+    if (jsMigrationFiles.length === 0) {
+      log.info('No migration files found');
+      return [];
+    }
+
     const appliedMigrations = await runner({
       databaseUrl,
-      dir: join(__dirname, 'db', 'migrations'),
+      dir: migrationsDir,
       direction,
       migrationsTable: 'pgmigrations',
       count: direction === 'down' ? 1 : Infinity,
       verbose,
       log: msg => (verbose ? log.info(msg) : log.debug(msg)),
+      // Ignore TypeScript declaration files - node-pg-migrate will try to import them otherwise
+      ignorePattern: '.*\\.d\\.(ts|js)$|.*\\.d\\.ts\\.map$',
     });
 
     if (appliedMigrations.length === 0) {