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

package/src/config.ts

@@ -0,0 +1,116 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+} from '@aztec/foundation/config';
+
+/**
+ * Configuration for the slashing protection service
+ */
+export interface SlashingProtectionConfig {
+  /** Whether slashing protection is enabled */
+  enabled: 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 {
+  /**
+   * PostgreSQL connection string
+   * Format: postgresql://user:password@host:port/database
+   */
+  databaseUrl: string;
+  /**
+   * PostgreSQL connection pool configuration
+   */
+  /** Maximum number of clients in the pool (default: 10) */
+  poolMaxCount?: number;
+  /** Minimum number of clients in the pool (default: 0) */
+  poolMinCount?: number;
+  /** Idle timeout in milliseconds (default: 10000) */
+  poolIdleTimeoutMs?: number;
+  /** Connection timeout in milliseconds (default: 0, no timeout) */
+  poolConnectionTimeoutMs?: number;
+}
+
+export const createHASignerConfigMappings: ConfigMappingsType<CreateHASignerConfig> = {
+  ...slashingProtectionConfigMappings,
+  databaseUrl: {
+    env: 'VALIDATOR_HA_DATABASE_URL',
+    description:
+      'PostgreSQL connection string for validator HA signer (format: postgresql://user:password@host:port/database)',
+  },
+  poolMaxCount: {
+    env: 'VALIDATOR_HA_POOL_MAX',
+    description: 'Maximum number of clients in the pool',
+    ...numberConfigHelper(10),
+  },
+  poolMinCount: {
+    env: 'VALIDATOR_HA_POOL_MIN',
+    description: 'Minimum number of clients in the pool',
+    ...numberConfigHelper(0),
+  },
+  poolIdleTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS',
+    description: 'Idle timeout in milliseconds',
+    ...numberConfigHelper(10_000),
+  },
+  poolConnectionTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS',
+    description: 'Connection timeout in milliseconds (0 means no timeout)',
+    ...numberConfigHelper(0),
+  },
+};
+
+/**
+ * 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);
+}

package/src/db/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './schema.js';
+export * from './postgres.js';

package/src/db/migrations/1_initial-schema.ts

@@ -0,0 +1,26 @@
+/**
+ * Initial schema for validator HA slashing protection
+ *
+ * This migration imports SQL from the schema.ts file to ensure a single source of truth.
+ */
+import type { MigrationBuilder } from 'node-pg-migrate';
+
+import { DROP_SCHEMA_VERSION_TABLE, DROP_VALIDATOR_DUTIES_TABLE, SCHEMA_SETUP, SCHEMA_VERSION } from '../schema.js';
+
+export function up(pgm: MigrationBuilder): void {
+  for (const statement of SCHEMA_SETUP) {
+    pgm.sql(statement);
+  }
+
+  // Insert initial schema version
+  pgm.sql(`
+    INSERT INTO schema_version (version)
+    VALUES (${SCHEMA_VERSION})
+    ON CONFLICT (version) DO NOTHING;
+  `);
+}
+
+export function down(pgm: MigrationBuilder): void {
+  pgm.sql(DROP_VALIDATOR_DUTIES_TABLE);
+  pgm.sql(DROP_SCHEMA_VERSION_TABLE);
+}

package/src/db/postgres.ts

@@ -0,0 +1,202 @@
+/**
+ * PostgreSQL implementation of SlashingProtectionDatabase
+ */
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import type { Pool, QueryResult } from 'pg';
+
+import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
+import {
+  CLEANUP_OWN_STUCK_DUTIES,
+  DELETE_DUTY,
+  INSERT_OR_GET_DUTY,
+  SCHEMA_VERSION,
+  UPDATE_DUTY_SIGNED,
+} from './schema.js';
+import type { CheckAndRecordParams, DutyRow, DutyType, InsertOrGetRow, ValidatorDutyRecord } from './types.js';
+
+/**
+ * PostgreSQL implementation of the slashing protection database
+ */
+export class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
+  private readonly log: Logger;
+
+  constructor(private readonly pool: Pool) {
+    this.log = createLogger('slashing-protection:postgres');
+  }
+
+  /**
+   * Verify that database migrations have been run and schema version matches.
+   * Should be called once at startup.
+   *
+   * @throws Error if migrations haven't been run or schema version is outdated
+   */
+  async initialize(): Promise<void> {
+    let dbVersion: number;
+
+    try {
+      const result = await this.pool.query<{ version: number }>(
+        `SELECT version FROM schema_version ORDER BY version DESC LIMIT 1`,
+      );
+
+      if (result.rows.length === 0) {
+        throw new Error('No version found');
+      }
+
+      dbVersion = result.rows[0].version;
+    } catch {
+      throw new Error(
+        'Database schema not initialized. Please run migrations first: aztec migrate 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>`,
+      );
+    }
+
+    if (dbVersion > SCHEMA_VERSION) {
+      throw new Error(
+        `Database schema version ${dbVersion} is newer than expected (${SCHEMA_VERSION}). Please update your application.`,
+      );
+    }
+
+    this.log.info('Database schema verified', { version: dbVersion });
+  }
+
+  /**
+   * 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. lock_token is empty if the record already exists.
+   */
+  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,
+    ]);
+
+    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');
+    }
+
+    const row = result.rows[0];
+    return {
+      isNew: row.is_new,
+      record: this.rowToRecord(row),
+    };
+  }
+
+  /**
+   * 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
+   */
+  async updateDutySigned(
+    validatorAddress: EthAddress,
+    slot: bigint,
+    dutyType: DutyType,
+    signature: string,
+    lockToken: string,
+  ): Promise<boolean> {
+    const result = await this.pool.query(UPDATE_DUTY_SIGNED, [
+      signature,
+      validatorAddress.toString(),
+      slot.toString(),
+      dutyType,
+      lockToken,
+    ]);
+
+    if (result.rowCount === 0) {
+      this.log.warn('Failed to update duty to signed status: invalid token or duty not found', {
+        validatorAddress: validatorAddress.toString(),
+        slot: slot.toString(),
+        dutyType,
+      });
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * 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
+   */
+  async deleteDuty(
+    validatorAddress: EthAddress,
+    slot: bigint,
+    dutyType: DutyType,
+    lockToken: string,
+  ): Promise<boolean> {
+    const result = await this.pool.query(DELETE_DUTY, [
+      validatorAddress.toString(),
+      slot.toString(),
+      dutyType,
+      lockToken,
+    ]);
+
+    if (result.rowCount === 0) {
+      this.log.warn('Failed to delete duty: invalid token or duty not found', {
+        validatorAddress: validatorAddress.toString(),
+        slot: slot.toString(),
+        dutyType,
+      });
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Convert a database row to a ValidatorDutyRecord
+   */
+  private rowToRecord(row: DutyRow): ValidatorDutyRecord {
+    return {
+      validatorAddress: EthAddress.fromString(row.validator_address),
+      slot: BigInt(row.slot),
+      blockNumber: BigInt(row.block_number),
+      dutyType: row.duty_type,
+      status: row.status,
+      messageHash: row.message_hash,
+      signature: row.signature ?? undefined,
+      nodeId: row.node_id,
+      lockToken: row.lock_token,
+      startedAt: row.started_at,
+      completedAt: row.completed_at ?? undefined,
+      errorMessage: row.error_message ?? undefined,
+    };
+  }
+
+  /**
+   * Close the database connection pool
+   */
+  async close(): Promise<void> {
+    await this.pool.end();
+    this.log.info('Database connection pool closed');
+  }
+
+  /**
+   * Cleanup own stuck duties
+   * @returns the number of duties cleaned up
+   */
+  async cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number> {
+    const cutoff = new Date(Date.now() - maxAgeMs);
+    const result = await this.pool.query(CLEANUP_OWN_STUCK_DUTIES, [nodeId, cutoff]);
+    return result.rowCount ?? 0;
+  }
+}

package/src/db/schema.ts

@@ -0,0 +1,236 @@
+/**
+ * SQL schema for the validator_duties table
+ *
+ * This table is used for distributed locking and slashing protection across multiple validator nodes.
+ * The PRIMARY KEY constraint ensures that only one node can acquire the lock for a given validator,
+ * slot, and duty type combination.
+ */
+
+/**
+ * Current schema version
+ */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * SQL to create the validator_duties table
+ */
+export const CREATE_VALIDATOR_DUTIES_TABLE = `
+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')),
+  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed', 'failed')),
+  message_hash VARCHAR(66) NOT NULL,
+  signature VARCHAR(132),
+  node_id VARCHAR(255) NOT NULL,
+  lock_token VARCHAR(64) NOT NULL,
+  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  completed_at TIMESTAMP,
+  error_message TEXT,
+
+  PRIMARY KEY (validator_address, slot, duty_type),
+  CHECK (completed_at IS NULL OR completed_at >= started_at)
+);
+`;
+
+/**
+ * SQL to create index on status and started_at for cleanup queries
+ */
+export const CREATE_STATUS_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_status
+ON validator_duties(status, started_at);
+`;
+
+/**
+ * SQL to create index for querying duties by node
+ */
+export const CREATE_NODE_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_node
+ON validator_duties(node_id, started_at);
+`;
+
+/**
+ * SQL to create the schema_version table for tracking migrations
+ */
+export const CREATE_SCHEMA_VERSION_TABLE = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+`;
+
+/**
+ * SQL to initialize schema version
+ */
+export const INSERT_SCHEMA_VERSION = `
+INSERT INTO schema_version (version)
+VALUES ($1)
+ON CONFLICT (version) DO NOTHING;
+`;
+
+/**
+ * Complete schema setup - all statements in order
+ */
+export const SCHEMA_SETUP = [
+  CREATE_SCHEMA_VERSION_TABLE,
+  CREATE_VALIDATOR_DUTIES_TABLE,
+  CREATE_STATUS_INDEX,
+  CREATE_NODE_INDEX,
+] as const;
+
+/**
+ * Query to get current schema version
+ */
+export const GET_SCHEMA_VERSION = `
+SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;
+`;
+
+/**
+ * Atomic insert-or-get query.
+ * Tries to insert a new duty record. If a record already exists (conflict),
+ * returns the existing record instead.
+ *
+ * Returns the record with an `is_new` flag indicating whether we inserted or got existing.
+ */
+export const INSERT_OR_GET_DUTY = `
+WITH inserted AS (
+  INSERT INTO validator_duties (
+    validator_address,
+    slot,
+    block_number,
+    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
+  RETURNING
+    validator_address,
+    slot,
+    block_number,
+    duty_type,
+    status,
+    message_hash,
+    signature,
+    node_id,
+    lock_token,
+    started_at,
+    completed_at,
+    error_message,
+    TRUE as is_new
+)
+SELECT * FROM inserted
+UNION ALL
+SELECT
+  validator_address,
+  slot,
+  block_number,
+  duty_type,
+  status,
+  message_hash,
+  signature,
+  node_id,
+  '' as lock_token,
+  started_at,
+  completed_at,
+  error_message,
+  FALSE as is_new
+FROM validator_duties
+WHERE validator_address = $1
+  AND slot = $2
+  AND duty_type = $4
+  AND NOT EXISTS (SELECT 1 FROM inserted);
+`;
+
+/**
+ * Query to update a duty to 'signed' status
+ */
+export const UPDATE_DUTY_SIGNED = `
+UPDATE validator_duties
+SET status = 'signed',
+    signature = $1,
+    completed_at = CURRENT_TIMESTAMP
+WHERE validator_address = $2
+  AND slot = $3
+  AND duty_type = $4
+  AND status = 'signing'
+  AND lock_token = $5;
+`;
+
+/**
+ * Query to delete a duty
+ * Only deletes if the lockToken matches
+ */
+export const DELETE_DUTY = `
+DELETE FROM validator_duties
+WHERE validator_address = $1
+  AND slot = $2
+  AND duty_type = $3
+  AND status = 'signing'
+  AND lock_token = $4;
+`;
+
+/**
+ * Query to clean up old signed duties (for maintenance)
+ * Removes signed duties older than a specified timestamp
+ */
+export const CLEANUP_OLD_SIGNED_DUTIES = `
+DELETE FROM validator_duties
+WHERE status = 'signed'
+  AND completed_at < $1;
+`;
+
+/**
+ * Query to clean up old duties (for maintenance)
+ * Removes duties older than a specified timestamp
+ */
+export const CLEANUP_OLD_DUTIES = `
+DELETE FROM validator_duties
+WHERE status IN ('signing', 'signed', 'failed')
+  AND started_at < $1;
+`;
+
+/**
+ * Query to cleanup own stuck duties
+ * Removes duties in 'signing' status for a specific node that are older than maxAgeMs
+ */
+export const CLEANUP_OWN_STUCK_DUTIES = `
+DELETE FROM validator_duties
+WHERE node_id = $1
+  AND status = 'signing'
+  AND started_at < $2;
+`;
+
+/**
+ * SQL to drop the validator_duties table
+ */
+export const DROP_VALIDATOR_DUTIES_TABLE = `DROP TABLE IF EXISTS validator_duties;`;
+
+/**
+ * SQL to drop the schema_version table
+ */
+export const DROP_SCHEMA_VERSION_TABLE = `DROP TABLE IF EXISTS schema_version;`;
+
+/**
+ * Query to get stuck duties (for monitoring/alerting)
+ * Returns duties in 'signing' status that have been stuck for too long
+ */
+export const GET_STUCK_DUTIES = `
+SELECT
+  validator_address,
+  slot,
+  block_number,
+  duty_type,
+  status,
+  message_hash,
+  node_id,
+  started_at,
+  EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - started_at)) as age_seconds
+FROM validator_duties
+WHERE status = 'signing'
+  AND started_at < $1
+ORDER BY started_at ASC;
+`;

package/src/db/test_helper.ts

@@ -0,0 +1,17 @@
+/**
+ * Test helpers for database setup
+ */
+import type { PGlite } from '@electric-sql/pglite';
+
+import { INSERT_SCHEMA_VERSION, SCHEMA_SETUP, SCHEMA_VERSION } from './schema.js';
+
+/**
+ * Set up the database schema for testing.
+ * This runs the same SQL that migrations would apply.
+ */
+export async function setupTestSchema(pglite: PGlite): Promise<void> {
+  for (const statement of SCHEMA_SETUP) {
+    await pglite.query(statement);
+  }
+  await pglite.query(INSERT_SCHEMA_VERSION, [SCHEMA_VERSION]);
+}