@aztec/validator-ha-signer 4.0.0-nightly.20260110

package/src/db/types.ts

@@ -0,0 +1,117 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+
+/**
+ * Row type from PostgreSQL query
+ */
+export interface DutyRow {
+  validator_address: string;
+  slot: string;
+  block_number: string;
+  duty_type: DutyType;
+  status: DutyStatus;
+  message_hash: string;
+  signature: string | null;
+  node_id: string;
+  lock_token: string;
+  started_at: Date;
+  completed_at: Date | null;
+  error_message: string | null;
+}
+
+/**
+ * Row type from INSERT_OR_GET_DUTY query (includes is_new flag)
+ */
+export interface InsertOrGetRow extends DutyRow {
+  is_new: boolean;
+}
+
+/**
+ * Type of validator duty being performed
+ */
+export enum DutyType {
+  BLOCK_PROPOSAL = 'BLOCK_PROPOSAL',
+  ATTESTATION = 'ATTESTATION',
+  ATTESTATIONS_AND_SIGNERS = 'ATTESTATIONS_AND_SIGNERS',
+}
+
+/**
+ * Status of a duty in the database
+ */
+export enum DutyStatus {
+  SIGNING = 'signing',
+  SIGNED = 'signed',
+}
+
+/**
+ * Record of a validator duty in the database
+ */
+export interface ValidatorDutyRecord {
+  /** Ethereum address of the validator */
+  validatorAddress: EthAddress;
+  /** Slot number for this duty */
+  slot: bigint;
+  /** Block number for this duty */
+  blockNumber: bigint;
+  /** Type of duty being performed */
+  dutyType: DutyType;
+  /** Current status of the duty */
+  status: DutyStatus;
+  /** The signing root (hash) for this duty */
+  messageHash: string;
+  /** The signature (populated after successful signing) */
+  signature?: string;
+  /** Unique identifier for the node that acquired the lock */
+  nodeId: string;
+  /** Secret token for verifying ownership of the duty lock */
+  lockToken: string;
+  /** When the duty signing was started */
+  startedAt: Date;
+  /** When the duty signing was completed (success or failure) */
+  completedAt?: Date;
+  /** Error message if status is 'failed' */
+  errorMessage?: string;
+}
+
+/**
+ * Minimal info needed to identify a unique duty
+ */
+export interface DutyIdentifier {
+  validatorAddress: EthAddress;
+  slot: bigint;
+  dutyType: DutyType;
+}
+
+/**
+ * Parameters for checking and recording a new duty
+ */
+export interface CheckAndRecordParams {
+  validatorAddress: EthAddress;
+  slot: bigint;
+  blockNumber: bigint;
+  dutyType: DutyType;
+  messageHash: string;
+  nodeId: string;
+}
+
+/**
+ * Parameters for recording a successful signing
+ */
+export interface RecordSuccessParams {
+  validatorAddress: EthAddress;
+  slot: bigint;
+  dutyType: DutyType;
+  signature: Signature;
+  nodeId: string;
+  lockToken: string;
+}
+
+/**
+ * Parameters for deleting a duty
+ */
+export interface DeleteDutyParams {
+  validatorAddress: EthAddress;
+  slot: bigint;
+  dutyType: DutyType;
+  lockToken: string;
+}

package/src/errors.ts

@@ -0,0 +1,42 @@
+/**
+ * Custom errors for the validator HA signer
+ */
+import type { DutyType } from './db/types.js';
+
+/**
+ * Thrown when a duty has already been signed (by any node).
+ * This is expected behavior in an HA setup - all nodes try to sign,
+ * the first one wins, and subsequent attempts get this error.
+ */
+export class DutyAlreadySignedError extends Error {
+  constructor(
+    public readonly slot: bigint,
+    public readonly dutyType: DutyType,
+    public readonly signedByNode: string,
+  ) {
+    super(`Duty ${dutyType} for slot ${slot} already signed by node ${signedByNode}`);
+    this.name = 'DutyAlreadySignedError';
+  }
+}
+
+/**
+ * Thrown when attempting to sign data that conflicts with an already-signed duty.
+ * This means the same validator tried to sign DIFFERENT data for the same slot.
+ *
+ * This is expected in HA setups where nodes may build different blocks
+ * (e.g., different transaction ordering) - the protection prevents double-signing.
+ */
+export class SlashingProtectionError extends Error {
+  constructor(
+    public readonly slot: bigint,
+    public readonly dutyType: DutyType,
+    public readonly existingMessageHash: string,
+    public readonly attemptedMessageHash: string,
+  ) {
+    super(
+      `Slashing protection: ${dutyType} for slot ${slot} was already signed with different data. ` +
+        `Existing: ${existingMessageHash.slice(0, 10)}..., Attempted: ${attemptedMessageHash.slice(0, 10)}...`,
+    );
+    this.name = 'SlashingProtectionError';
+  }
+}

package/src/factory.ts

@@ -0,0 +1,87 @@
+/**
+ * Factory functions for creating validator HA signers
+ */
+import { Pool } from 'pg';
+
+import type { CreateHASignerConfig } from './config.js';
+import { PostgresSlashingProtectionDatabase } from './db/postgres.js';
+import type { CreateHASignerDeps, SlashingProtectionDatabase } from './types.js';
+import { ValidatorHASigner } from './validator_ha_signer.js';
+
+/**
+ * Create a validator HA signer with PostgreSQL backend
+ *
+ * After creating the signer, call `signer.start()` to begin background
+ * cleanup tasks. Call `signer.stop()` during graceful shutdown.
+ *
+ * Example with manual migrations (recommended for production):
+ * ```bash
+ * # Run migrations separately
+ * yarn migrate:up
+ * ```
+ *
+ * ```typescript
+ * const { signer, db } = await createHASigner({
+ *   databaseUrl: process.env.DATABASE_URL,
+ *   enabled: true,
+ *   nodeId: 'validator-node-1',
+ *   pollingIntervalMs: 100,
+ *   signingTimeoutMs: 3000,
+ * });
+ * signer.start(); // Start background cleanup
+ *
+ * // ... use signer ...
+ *
+ * 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();
+ * ```
+ *
+ * @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,
+  deps?: CreateHASignerDeps,
+): Promise<{
+  signer: ValidatorHASigner;
+  db: SlashingProtectionDatabase;
+}> {
+  const { databaseUrl, poolMaxCount, poolMinCount, poolIdleTimeoutMs, poolConnectionTimeoutMs, ...signerConfig } =
+    config;
+
+  // Create connection pool (or use provided pool)
+  let pool: Pool;
+  if (!deps?.pool) {
+    pool = new Pool({
+      connectionString: databaseUrl,
+      max: poolMaxCount ?? 10,
+      min: poolMinCount ?? 0,
+      idleTimeoutMillis: poolIdleTimeoutMs ?? 10_000,
+      connectionTimeoutMillis: poolConnectionTimeoutMs ?? 0,
+    });
+  } else {
+    pool = deps.pool;
+  }
+
+  // Create database instance
+  const db = new PostgresSlashingProtectionDatabase(pool);
+
+  // Verify database schema is initialized and version matches
+  await db.initialize();
+
+  // Create signer
+  const signer = new ValidatorHASigner(db, { ...signerConfig, databaseUrl });
+
+  return { signer, db };
+}

package/src/migrations.ts

@@ -0,0 +1,59 @@
+/**
+ * Programmatic migration runner
+ */
+import { createLogger } from '@aztec/foundation/log';
+
+import { runner } from 'node-pg-migrate';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export interface RunMigrationsOptions {
+  /** Migration direction ('up' to apply, 'down' to rollback). Defaults to 'up'. */
+  direction?: 'up' | 'down';
+  /** Enable verbose output. Defaults to false. */
+  verbose?: boolean;
+}
+
+/**
+ * Run database migrations programmatically
+ *
+ * @param databaseUrl - PostgreSQL connection string
+ * @param options - Migration options (direction, verbose)
+ * @returns Array of applied migration names
+ */
+export async function runMigrations(databaseUrl: string, options: RunMigrationsOptions = {}): Promise<string[]> {
+  const direction = options.direction ?? 'up';
+  const verbose = options.verbose ?? false;
+
+  const log = createLogger('validator-ha-signer:migrations');
+
+  try {
+    log.info(`Running migrations ${direction}...`);
+
+    const appliedMigrations = await runner({
+      databaseUrl,
+      dir: join(__dirname, 'db', 'migrations'),
+      direction,
+      migrationsTable: 'pgmigrations',
+      count: direction === 'down' ? 1 : Infinity,
+      verbose,
+      log: msg => (verbose ? log.info(msg) : log.debug(msg)),
+    });
+
+    if (appliedMigrations.length === 0) {
+      log.info('No migrations to apply - schema is up to date');
+    } else {
+      log.info(`Applied ${appliedMigrations.length} migration(s)`, {
+        migrations: appliedMigrations.map(m => m.name),
+      });
+    }
+
+    return appliedMigrations.map(m => m.name);
+  } catch (error: any) {
+    log.error('Migration failed', error);
+    throw error;
+  }
+}

package/src/slashing_protection_service.ts

@@ -0,0 +1,216 @@
+/**
+ * Slashing Protection Service
+ *
+ * Provides distributed locking and slashing protection for validator duties.
+ * Uses an external database to coordinate across multiple validator nodes.
+ */
+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 { DutyAlreadySignedError, SlashingProtectionError } from './errors.js';
+import type { SlashingProtectionConfig, SlashingProtectionDatabase } from './types.js';
+
+/**
+ * Slashing Protection Service
+ *
+ * This service ensures that a validator only signs one block/attestation per slot,
+ * even when running multiple redundant nodes (HA setup).
+ *
+ * All nodes in the HA setup try to sign - the first one wins, others get
+ * DutyAlreadySignedError (normal) or SlashingProtectionError (if different data).
+ *
+ * Flow:
+ * 1. checkAndRecord() - Atomically try to acquire lock via tryInsertOrGetExisting
+ * 2. Caller performs the signing operation
+ * 3. recordSuccess() - Update to 'signed' status with signature
+ *    OR deleteDuty() - Delete the record to allow retry
+ */
+export class SlashingProtectionService {
+  private readonly log: Logger;
+  private readonly pollingIntervalMs: number;
+  private readonly signingTimeoutMs: number;
+
+  private cleanupRunningPromise: RunningPromise;
+
+  constructor(
+    private readonly db: SlashingProtectionDatabase,
+    private readonly config: SlashingProtectionConfig,
+  ) {
+    this.log = createLogger('slashing-protection');
+    this.pollingIntervalMs = config.pollingIntervalMs;
+    this.signingTimeoutMs = config.signingTimeoutMs;
+
+    this.cleanupRunningPromise = new RunningPromise(
+      this.cleanupStuckDuties.bind(this),
+      this.log,
+      this.config.maxStuckDutiesAgeMs,
+    );
+  }
+
+  /**
+   * Check if a duty can be performed and acquire the lock if so.
+   *
+   * This method uses an atomic insert-or-get operation.
+   * It will:
+   * 1. Try to insert a new record with 'signing' status
+   * 2. If insert succeeds, we acquired the lock - return the lockToken
+   * 3. If a record exists, handle based on status:
+   *    - SIGNED: Throw appropriate error (already signed or slashing protection)
+   *    - FAILED: Delete the failed record
+   *    - SIGNING: Wait and poll until status changes, then handle result
+   *
+   * @returns The lockToken that must be used for recordSuccess/deleteDuty
+   * @throws DutyAlreadySignedError if the duty was already completed
+   * @throws SlashingProtectionError if attempting to sign different data for same slot/duty
+   */
+  async checkAndRecord(params: CheckAndRecordParams): Promise<string> {
+    const { validatorAddress, slot, dutyType, messageHash, nodeId } = params;
+    const startTime = Date.now();
+
+    this.log.debug(`Checking duty: ${dutyType} for slot ${slot}`, {
+      validatorAddress: validatorAddress.toString(),
+      nodeId,
+    });
+
+    while (true) {
+      // insert if not present, get existing if present
+      const { isNew, record } = await this.db.tryInsertOrGetExisting(params);
+
+      if (isNew) {
+        // We successfully acquired the lock
+        this.log.info(`Acquired lock for duty ${dutyType} at slot ${slot}`, {
+          validatorAddress: validatorAddress.toString(),
+          nodeId,
+        });
+        return record.lockToken;
+      }
+
+      // Record already exists - handle based on status
+      if (record.status === DutyStatus.SIGNED) {
+        // Duty was already signed - check if same or different data
+        if (record.messageHash !== messageHash) {
+          this.log.verbose(`Slashing protection triggered for duty ${dutyType} at slot ${slot}`, {
+            validatorAddress: validatorAddress.toString(),
+            existingMessageHash: record.messageHash,
+            attemptedMessageHash: messageHash,
+            existingNodeId: record.nodeId,
+            attemptingNodeId: nodeId,
+          });
+          throw new SlashingProtectionError(slot, dutyType, record.messageHash, messageHash);
+        }
+        throw new DutyAlreadySignedError(slot, dutyType, record.nodeId);
+      } else if (record.status === DutyStatus.SIGNING) {
+        // Another node is currently signing - check for timeout
+        if (Date.now() - startTime > this.signingTimeoutMs) {
+          this.log.warn(`Timeout waiting for signing to complete for duty ${dutyType} at slot ${slot}`, {
+            validatorAddress: validatorAddress.toString(),
+            timeoutMs: this.signingTimeoutMs,
+            signingNodeId: record.nodeId,
+          });
+          throw new DutyAlreadySignedError(slot, dutyType, 'unknown (timeout)');
+        }
+
+        // Wait and poll
+        this.log.debug(`Waiting for signing to complete for duty ${dutyType} at slot ${slot}`, {
+          validatorAddress: validatorAddress.toString(),
+          signingNodeId: record.nodeId,
+        });
+        await sleep(this.pollingIntervalMs);
+        // Loop continues - next iteration will check status again
+      } else {
+        throw new Error(`Unknown duty status: ${record.status}`);
+      }
+    }
+  }
+
+  /**
+   * Record a successful signing operation.
+   * Updates the duty status to 'signed' and stores the signature.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   *
+   * @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 success = await this.db.updateDutySigned(validatorAddress, slot, dutyType, signature.toString(), lockToken);
+
+    if (success) {
+      this.log.info(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
+        validatorAddress: validatorAddress.toString(),
+        nodeId,
+      });
+    } else {
+      this.log.warn(`Failed to record successful signing for duty ${dutyType} at slot ${slot}: invalid token`, {
+        validatorAddress: validatorAddress.toString(),
+        nodeId,
+      });
+    }
+
+    return success;
+  }
+
+  /**
+   * Delete a duty record after a failed signing operation.
+   * Removes the record to allow another node/attempt to retry.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   *
+   * @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 success = await this.db.deleteDuty(validatorAddress, slot, dutyType, lockToken);
+
+    if (success) {
+      this.log.info(`Deleted duty ${dutyType} at slot ${slot} to allow retry`, {
+        validatorAddress: validatorAddress.toString(),
+      });
+    } else {
+      this.log.warn(`Failed to delete duty ${dutyType} at slot ${slot}: invalid token`, {
+        validatorAddress: validatorAddress.toString(),
+      });
+    }
+
+    return success;
+  }
+
+  /**
+   * Get the node ID for this service
+   */
+  get nodeId(): string {
+    return this.config.nodeId;
+  }
+
+  /**
+   * Start running tasks.
+   * Cleanup runs immediately on start to recover from any previous crashes.
+   */
+  start() {
+    this.cleanupRunningPromise.start();
+    this.log.info('Slashing protection service started', { nodeId: this.config.nodeId });
+  }
+
+  /**
+   * Stop the background cleanup task.
+   */
+  async stop() {
+    await this.cleanupRunningPromise.stop();
+    this.log.info('Slashing protection service stopped', { nodeId: this.config.nodeId });
+  }
+
+  /**
+   * Cleanup own stuck duties
+   */
+  private async cleanupStuckDuties() {
+    const numDuties = await this.db.cleanupOwnStuckDuties(this.config.nodeId, this.config.maxStuckDutiesAgeMs);
+    if (numDuties > 0) {
+      this.log.info(`Cleaned up ${numDuties} stuck duties`, {
+        nodeId: this.config.nodeId,
+        maxStuckDutiesAgeMs: this.config.maxStuckDutiesAgeMs,
+      });
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,105 @@
+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,
+  DutyType,
+  RecordSuccessParams,
+  ValidatorDutyRecord,
+} from './db/types.js';
+
+export type {
+  CheckAndRecordParams,
+  CreateHASignerConfig,
+  DeleteDutyParams,
+  DutyIdentifier,
+  RecordSuccessParams,
+  SlashingProtectionConfig,
+  ValidatorDutyRecord,
+};
+export { DutyStatus, DutyType } from './db/types.js';
+
+/**
+ * Result of tryInsertOrGetExisting operation
+ */
+export interface TryInsertOrGetResult {
+  /** True if we inserted a new record, false if we got an existing record */
+  isNew: boolean;
+  /** The record (either newly inserted or existing) */
+  record: ValidatorDutyRecord;
+}
+
+/**
+ * deps for creating an HA signer
+ */
+export interface CreateHASignerDeps {
+  /**
+   * Optional PostgreSQL connection pool
+   * If provided, databaseUrl and poolConfig are ignored
+   */
+  pool?: Pool;
+}
+
+/**
+ * Context required for slashing protection during signing operations
+ */
+export interface SigningContext {
+  /** Slot number for this duty */
+  slot: bigint;
+  /** Block number for this duty */
+  blockNumber: bigint;
+  /** Type of duty being performed */
+  dutyType: DutyType;
+}
+
+/**
+ * Database interface for slashing protection operations
+ * This abstraction allows for different database implementations (PostgreSQL, SQLite, etc.)
+ *
+ * The interface is designed around 3 core operations:
+ * 1. tryInsertOrGetExisting - Atomically insert or get existing record (eliminates race conditions)
+ * 2. updateDutySigned - Update to signed status on success
+ * 3. deleteDuty - Delete a duty record on failure
+ */
+export interface SlashingProtectionDatabase {
+  /**
+   * Atomically try to insert a new duty record, or get the existing one if present.
+   *
+   * @returns { isNew: true, record } if we successfully inserted and acquired the lock
+   * @returns { isNew: false, record } if a record already exists (caller should handle based on status)
+   */
+  tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult>;
+
+  /**
+   * Update a duty to 'signed' status with the signature.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   *
+   * @returns true if the update succeeded, false if token didn't match or duty not found
+   */
+  updateDutySigned(
+    validatorAddress: EthAddress,
+    slot: bigint,
+    dutyType: DutyType,
+    signature: string,
+    lockToken: string,
+  ): Promise<boolean>;
+
+  /**
+   * Delete a duty record.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   * Used when signing fails to allow another node/attempt to retry.
+   *
+   * @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>;
+
+  /**
+   * Cleanup own stuck duties
+   * @returns the number of duties cleaned up
+   */
+  cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+}