@aztec/validator-ha-signer 0.0.1-commit.001888fc

package/src/test/pglite_pool.ts

@@ -0,0 +1,256 @@
+/**
+ * Vendored pg-compatible Pool/Client wrapper for PGlite.
+ *
+ * Copied from @middle-management/pglite-pg-adapter v0.0.3
+ * https://www.npmjs.com/package/@middle-management/pglite-pg-adapter
+ *
+ * Modifications:
+ * - Converted to ESM and TypeScript
+ * - Uses PGliteInterface instead of PGlite class to avoid TypeScript
+ *   type mismatches from ESM/CJS dual package resolution with private fields
+ * - Simplified rowCount calculation to handle CTEs properly
+ */
+import type { PGliteInterface } from '@electric-sql/pglite';
+import { EventEmitter } from 'events';
+import type { QueryResult, QueryResultRow } from 'pg';
+import { Readable, Writable } from 'stream';
+
+export interface PoolConfig {
+  pglite: PGliteInterface;
+  max?: number;
+  min?: number;
+}
+
+interface ClientConfig {
+  pglite: PGliteInterface;
+  host?: string;
+  port?: number;
+  ssl?: boolean;
+}
+
+export class Client extends EventEmitter {
+  protected pglite: PGliteInterface;
+  protected _connected = false;
+  readonly host: string;
+  readonly port: number;
+  readonly ssl: boolean;
+  readonly connection: object;
+
+  // Stub implementations for pg compatibility
+  readonly copyFrom = (): Writable => new Writable();
+  readonly copyTo = (): Readable => new Readable();
+  readonly pauseDrain = (): void => {};
+  readonly resumeDrain = (): void => {};
+  readonly escapeLiteral = (str: string): string => `'${str.replace(/'/g, "''")}'`;
+  readonly escapeIdentifier = (str: string): string => `"${str.replace(/"/g, '""')}"`;
+  readonly setTypeParser = (): void => {};
+  readonly getTypeParser = (): ((value: string) => unknown) => (value: string) => value;
+
+  constructor(config: ClientConfig) {
+    super();
+    this.pglite = config.pglite;
+    this.host = config.host || 'localhost';
+    this.port = config.port || 5432;
+    this.ssl = typeof config.ssl === 'boolean' ? config.ssl : !!config.ssl;
+    this.connection = {};
+  }
+
+  connect(): Promise<void> {
+    if (this._connected) {
+      return Promise.resolve();
+    }
+    this._connected = true;
+    this.emit('connect');
+    return Promise.resolve();
+  }
+
+  end(): Promise<void> {
+    if (!this._connected) {
+      return Promise.resolve();
+    }
+    this._connected = false;
+    this.emit('end');
+    return Promise.resolve();
+  }
+
+  async query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>> {
+    if (!this._connected) {
+      throw new Error('Client is not connected');
+    }
+    const result = await this.pglite.query<R>(text, values);
+    return this.convertPGliteResult(result);
+  }
+
+  protected convertPGliteResult<R extends QueryResultRow>(result: {
+    rows: R[];
+    fields: Array<{ name: string; dataTypeID: number }>;
+    affectedRows?: number;
+  }): QueryResult<R> {
+    return {
+      command: '',
+      rowCount: 'affectedRows' in result ? (result.affectedRows ?? 0) : result.rows.length,
+      oid: 0,
+      fields: result.fields.map(field => ({
+        name: field.name,
+        tableID: 0,
+        columnID: 0,
+        dataTypeID: field.dataTypeID,
+        dataTypeSize: -1,
+        dataTypeModifier: -1,
+        format: 'text',
+      })),
+      rows: result.rows,
+    };
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+}
+
+export class Pool extends EventEmitter {
+  private clients: PoolClient[] = [];
+  private availableClients: PoolClient[] = [];
+  private waitingQueue: Array<(client: PoolClient) => void> = [];
+  private _ended = false;
+  private pglite: PGliteInterface;
+  private _config: PoolConfig;
+
+  readonly expiredCount = 0;
+  readonly options: PoolConfig;
+
+  constructor(config: PoolConfig) {
+    super();
+    this._config = { max: 10, min: 0, ...config };
+    this.pglite = config.pglite;
+    this.options = config;
+  }
+
+  get totalCount(): number {
+    return this.clients.length;
+  }
+
+  get idleCount(): number {
+    return this.availableClients.length;
+  }
+
+  get waitingCount(): number {
+    return this.waitingQueue.length;
+  }
+
+  get ending(): boolean {
+    return this._ended;
+  }
+
+  get ended(): boolean {
+    return this._ended;
+  }
+
+  connect(): Promise<PoolClient> {
+    if (this._ended) {
+      return Promise.reject(new Error('Pool is ended'));
+    }
+
+    if (this.availableClients.length > 0) {
+      const client = this.availableClients.pop()!;
+      client._markInUse();
+      return Promise.resolve(client);
+    }
+
+    if (this.clients.length < (this._config.max || 10)) {
+      const client = new PoolClient(this.pglite, this);
+      this.clients.push(client);
+      return Promise.resolve(client);
+    }
+
+    return new Promise(resolve => {
+      this.waitingQueue.push(resolve);
+    });
+  }
+
+  async query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>> {
+    const client = await this.connect();
+    try {
+      return await client.query<R>(text, values);
+    } finally {
+      client.release();
+    }
+  }
+
+  releaseClient(client: PoolClient): void {
+    const index = this.clients.indexOf(client);
+    if (index !== -1) {
+      client._markAvailable();
+      if (this.waitingQueue.length > 0) {
+        const resolve = this.waitingQueue.shift()!;
+        client._markInUse();
+        resolve(client);
+      } else {
+        this.availableClients.push(client);
+      }
+    }
+  }
+
+  end(): Promise<void> {
+    this._ended = true;
+    this.clients.forEach(client => client._markReleased());
+    this.clients = [];
+    this.availableClients = [];
+    this.emit('end');
+    return Promise.resolve();
+  }
+}
+
+export class PoolClient extends Client {
+  private pool: Pool;
+  private _released = false;
+  private _inUse = true;
+  private _userReleased = false;
+
+  constructor(pglite: PGliteInterface, pool: Pool) {
+    super({ pglite });
+    this.pool = pool;
+    this._connected = true;
+  }
+
+  override async query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>> {
+    if (this._userReleased && !this._inUse) {
+      throw new Error('Client has been released back to the pool');
+    }
+    const result = await this.pglite.query<R>(text, values);
+    return this.convertPGliteResult(result);
+  }
+
+  release(): void {
+    if (this._released || this._userReleased) {
+      return;
+    }
+    this._userReleased = true;
+    this.pool.releaseClient(this);
+  }
+
+  override end(): Promise<void> {
+    this.release();
+    return Promise.resolve();
+  }
+
+  _markInUse(): void {
+    this._inUse = true;
+    this._userReleased = false;
+  }
+
+  _markAvailable(): void {
+    this._inUse = false;
+    this._userReleased = false;
+  }
+
+  _markReleased(): void {
+    this._released = true;
+    this._inUse = false;
+    this._userReleased = true;
+  }
+
+  override get connected(): boolean {
+    return this._connected && !this._released;
+  }
+}

package/src/types.ts

@@ -0,0 +1,154 @@
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import { DateProvider } from '@aztec/foundation/timer';
+import {
+  DutyType,
+  type HAProtectedSigningContext,
+  type SigningContext,
+  type ValidatorHASignerConfig,
+  getBlockNumberFromSigningContext as getBlockNumberFromSigningContextFromStdlib,
+  isHAProtectedContext,
+} from '@aztec/stdlib/ha-signing';
+import type { TelemetryClient } from '@aztec/telemetry-client';
+
+import type { Pool } from 'pg';
+
+import type {
+  BlockProposalDutyIdentifier,
+  CheckAndRecordParams,
+  DeleteDutyParams,
+  DutyIdentifier,
+  DutyRow,
+  OtherDutyIdentifier,
+  RecordSuccessParams,
+  ValidatorDutyRecord,
+} from './db/types.js';
+
+export type {
+  BlockProposalDutyIdentifier,
+  CheckAndRecordParams,
+  DeleteDutyParams,
+  DutyIdentifier,
+  DutyRow,
+  HAProtectedSigningContext,
+  OtherDutyIdentifier,
+  RecordSuccessParams,
+  SigningContext,
+  ValidatorDutyRecord,
+  ValidatorHASignerConfig,
+};
+export { DutyStatus, DutyType, getBlockIndexFromDutyIdentifier, normalizeBlockIndex } from './db/types.js';
+export { isHAProtectedContext };
+export { getBlockNumberFromSigningContextFromStdlib as getBlockNumberFromSigningContext };
+
+/**
+ * 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;
+  /**
+   * Optional telemetry client for metrics
+   */
+  telemetryClient?: TelemetryClient;
+  /**
+   * Optional date provider for timestamps
+   */
+  dateProvider?: DateProvider;
+}
+
+/**
+ * deps for creating a local signing protection signer
+ */
+export type CreateLocalSignerWithProtectionDeps = Omit<CreateHASignerDeps, 'pool'>;
+
+/**
+ * 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(
+    rollupAddress: EthAddress,
+    validatorAddress: EthAddress,
+    slot: SlotNumber,
+    dutyType: DutyType,
+    signature: string,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): 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(
+    rollupAddress: EthAddress,
+    validatorAddress: EthAddress,
+    slot: SlotNumber,
+    dutyType: DutyType,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): Promise<boolean>;
+
+  /**
+   * Cleanup own stuck duties
+   * @returns the number of duties cleaned up
+   */
+  cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+
+  /**
+   * Cleanup duties with outdated rollup address.
+   * Removes all duties where the rollup address doesn't match the current one.
+   * Used after a rollup upgrade to clean up duties for the old rollup.
+   * @returns the number of duties cleaned up
+   */
+  cleanupOutdatedRollupDuties(currentRollupAddress: EthAddress): Promise<number>;
+
+  /**
+   * Cleanup old signed duties.
+   * Removes only signed duties older than the specified age.
+   * @returns the number of duties cleaned up
+   */
+  cleanupOldDuties(maxAgeMs: number): Promise<number>;
+
+  /**
+   * Close the database connection.
+   * Should be called during graceful shutdown.
+   */
+  close(): Promise<void>;
+}

package/src/validator_ha_signer.ts

@@ -0,0 +1,183 @@
+/**
+ * Validator High Availability Signer
+ *
+ * Wraps signing operations with distributed locking and slashing protection.
+ * This ensures that even with multiple validator nodes running, only one
+ * node will sign for a given duty (slot + duty type).
+ */
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+import {
+  type BaseSignerConfig,
+  DutyType,
+  type HAProtectedSigningContext,
+  getBlockNumberFromSigningContext,
+} from '@aztec/stdlib/ha-signing';
+
+import type { DutyIdentifier } from './db/types.js';
+import type { HASignerMetrics } from './metrics.js';
+import { SlashingProtectionService } from './slashing_protection_service.js';
+import type { SlashingProtectionDatabase } from './types.js';
+
+export interface ValidatorHASignerDeps {
+  metrics: HASignerMetrics;
+  dateProvider: DateProvider;
+}
+
+/**
+ * Validator High Availability Signer
+ *
+ * Provides signing capabilities with distributed locking for validators
+ * in a high-availability setup.
+ *
+ * Usage:
+ * ```
+ * const signer = new ValidatorHASigner(db, config);
+ *
+ * // Sign with slashing protection
+ * const signature = await signer.signWithProtection(
+ *   validatorAddress,
+ *   messageHash,
+ *   { slot: 100n, blockNumber: 50n, dutyType: 'BLOCK_PROPOSAL' },
+ *   async (root) => localSigner.signMessage(root),
+ * );
+ * ```
+ */
+export class ValidatorHASigner {
+  private readonly log: Logger;
+  private readonly slashingProtection: SlashingProtectionService;
+  private readonly rollupAddress: EthAddress;
+
+  private readonly dateProvider: DateProvider;
+  private readonly metrics: HASignerMetrics;
+
+  constructor(
+    db: SlashingProtectionDatabase,
+    private readonly config: BaseSignerConfig,
+    deps: ValidatorHASignerDeps,
+  ) {
+    this.log = createLogger('validator-ha-signer');
+
+    this.metrics = deps.metrics;
+    this.dateProvider = deps.dateProvider;
+
+    if (!config.nodeId || config.nodeId === '') {
+      throw new Error('NODE_ID is required for high-availability setups');
+    }
+    this.rollupAddress = config.l1Contracts.rollupAddress;
+    this.slashingProtection = new SlashingProtectionService(db, config, {
+      metrics: deps.metrics,
+      dateProvider: deps.dateProvider,
+    });
+    this.log.info('Validator HA Signer initialized with slashing protection', {
+      nodeId: config.nodeId,
+      rollupAddress: this.rollupAddress.toString(),
+    });
+  }
+
+  /**
+   * Sign a message with slashing protection.
+   *
+   * This method:
+   * 1. Acquires a distributed lock for (validator, slot, dutyType)
+   * 2. Calls the provided signing function
+   * 3. Records the result (success or failure)
+   *
+   * @param validatorAddress - The validator's Ethereum address
+   * @param messageHash - The hash to be signed
+   * @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: EthAddress,
+    messageHash: Buffer32,
+    context: HAProtectedSigningContext,
+    signFn: (messageHash: Buffer32) => Promise<Signature>,
+  ): Promise<Signature> {
+    const startTime = this.dateProvider.now();
+    const dutyType = context.dutyType;
+
+    let dutyIdentifier: DutyIdentifier;
+    if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+      dutyIdentifier = {
+        rollupAddress: this.rollupAddress,
+        validatorAddress,
+        slot: context.slot,
+        blockIndexWithinCheckpoint: context.blockIndexWithinCheckpoint,
+        dutyType: context.dutyType,
+      };
+    } else {
+      dutyIdentifier = {
+        rollupAddress: this.rollupAddress,
+        validatorAddress,
+        slot: context.slot,
+        dutyType: context.dutyType,
+      };
+    }
+
+    // Acquire lock and get the token for ownership verification
+    // DutyAlreadySignedError and SlashingProtectionError may be thrown here and are recorded in the service
+    const blockNumber = getBlockNumberFromSigningContext(context);
+    const lockToken = await this.slashingProtection.checkAndRecord({
+      ...dutyIdentifier,
+      blockNumber,
+      messageHash: messageHash.toString(),
+      nodeId: this.config.nodeId,
+    });
+
+    // Perform signing
+    let signature: Signature;
+    try {
+      signature = await signFn(messageHash);
+    } catch (error: any) {
+      // Delete duty to allow retry (only succeeds if we own the lock)
+      await this.slashingProtection.deleteDuty({ ...dutyIdentifier, lockToken });
+      this.metrics.recordSigningError(dutyType);
+      throw error;
+    }
+
+    // Record success (only succeeds if we own the lock)
+    await this.slashingProtection.recordSuccess({
+      ...dutyIdentifier,
+      signature,
+      nodeId: this.config.nodeId,
+      lockToken,
+    });
+
+    const duration = this.dateProvider.now() - startTime;
+    this.metrics.recordSigningSuccess(dutyType, duration);
+
+    return signature;
+  }
+
+  /**
+   * Get the node ID for this signer
+   */
+  get nodeId(): string {
+    return this.config.nodeId;
+  }
+
+  /**
+   * Start the HA signer background tasks (cleanup of stuck duties).
+   * Should be called after construction and before signing operations.
+   */
+  async start() {
+    await this.slashingProtection.start();
+  }
+
+  /**
+   * 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.close();
+  }
+}