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

package/src/db/types.ts

@@ -1,3 +1,4 @@
+import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
 
@@ -5,9 +6,11 @@ import type { Signature } from '@aztec/foundation/eth-signature';
  * Row type from PostgreSQL query
  */
 export interface DutyRow {
+  rollup_address: string;
   validator_address: string;
   slot: string;
   block_number: string;
+  block_index_within_checkpoint: number;
   duty_type: DutyType;
   status: DutyStatus;
   message_hash: string;
@@ -31,8 +34,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',
 }
 
 /**
@@ -47,12 +55,16 @@ export enum DutyStatus {
  * Record of a validator duty in the database
  */
 export interface ValidatorDutyRecord {
+  /** Ethereum address of the rollup contract */
+  rollupAddress: EthAddress;
   /** 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 +86,121 @@ 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 {
+  rollupAddress: EthAddress;
   validatorAddress: EthAddress;
-  slot: bigint;
-  dutyType: DutyType;
+  slot: SlotNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  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 {
+  rollupAddress: EthAddress;
   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) {

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
@@ -133,9 +149,18 @@ export class SlashingProtectionService {
    * @returns true if the update succeeded, false if token didn't match
    */
   async recordSuccess(params: RecordSuccessParams): Promise<boolean> {
-    const { validatorAddress, slot, dutyType, signature, nodeId, lockToken } = params;
+    const { rollupAddress, validatorAddress, slot, dutyType, signature, nodeId, lockToken } = params;
+    const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
 
-    const success = await this.db.updateDutySigned(validatorAddress, slot, dutyType, signature.toString(), lockToken);
+    const success = await this.db.updateDutySigned(
+      rollupAddress,
+      validatorAddress,
+      slot,
+      dutyType,
+      signature.toString(),
+      lockToken,
+      blockIndexWithinCheckpoint,
+    );
 
     if (success) {
       this.log.info(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
@@ -160,9 +185,17 @@ export class SlashingProtectionService {
    * @returns true if the delete succeeded, false if token didn't match
    */
   async deleteDuty(params: DeleteDutyParams): Promise<boolean> {
-    const { validatorAddress, slot, dutyType, lockToken } = params;
+    const { rollupAddress, 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(
+      rollupAddress,
+      validatorAddress,
+      slot,
+      dutyType,
+      lockToken,
+      blockIndexWithinCheckpoint,
+    );
 
     if (success) {
       this.log.info(`Deleted duty ${dutyType} at slot ${slot} to allow retry`, {
@@ -201,15 +234,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,
       });
     }
   }