@aztec/validator-ha-signer 0.0.1-commit.023c3e5

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@aztec/validator-ha-signer",
+  "version": "0.0.1-commit.023c3e5",
+  "type": "module",
+  "exports": {
+    "./config": "./dest/config.js",
+    "./db": "./dest/db/index.js",
+    "./errors": "./dest/errors.js",
+    "./factory": "./dest/factory.js",
+    "./migrations": "./dest/migrations.js",
+    "./slashing-protection-service": "./dest/slashing_protection_service.js",
+    "./types": "./dest/types.js",
+    "./validator-ha-signer": "./dest/validator_ha_signer.js",
+    "./test": "./dest/test/pglite_pool.js"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/config.ts",
+      "./src/db/index.ts",
+      "./src/errors.ts",
+      "./src/factory.ts",
+      "./src/migrations.ts",
+      "./src/slashing_protection_service.ts",
+      "./src/types.ts",
+      "./src/validator_ha_signer.ts"
+    ],
+    "name": "Validator High-Availability Signer",
+    "tsconfig": "./tsconfig.json"
+  },
+  "scripts": {
+    "build": "yarn clean && ../scripts/tsc.sh",
+    "build:dev": "../scripts/tsc.sh --watch",
+    "clean": "rm -rf ./dest .tsbuildinfo",
+    "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
+  },
+  "inherits": [
+    "../package.common.json"
+  ],
+  "jest": {
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.[cm]?js$": "$1"
+    },
+    "testRegex": "./src/.*\\.test\\.(js|mjs|ts)$",
+    "rootDir": "./src",
+    "transform": {
+      "^.+\\.tsx?$": [
+        "@swc/jest",
+        {
+          "jsc": {
+            "parser": {
+              "syntax": "typescript",
+              "decorators": true
+            },
+            "transform": {
+              "decoratorVersion": "2022-03"
+            }
+          }
+        }
+      ]
+    },
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "reporters": [
+      "default"
+    ],
+    "testTimeout": 120000,
+    "setupFiles": [
+      "../../foundation/src/jest/setup.mjs"
+    ],
+    "testEnvironment": "../../foundation/src/jest/env.mjs",
+    "setupFilesAfterEnv": [
+      "../../foundation/src/jest/setupAfterEnv.mjs"
+    ]
+  },
+  "dependencies": {
+    "@aztec/foundation": "0.0.1-commit.023c3e5",
+    "node-pg-migrate": "^8.0.4",
+    "pg": "^8.11.3",
+    "tslib": "^2.4.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.3.14",
+    "@jest/globals": "^30.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.15.17",
+    "@types/node-pg-migrate": "^2.3.1",
+    "@types/pg": "^8.10.9",
+    "@typescript/native-preview": "7.0.0-dev.20260113.1",
+    "jest": "^30.0.0",
+    "jest-mock-extended": "^4.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.3.3"
+  },
+  "types": "./dest/types.d.ts",
+  "files": [
+    "dest",
+    "src",
+    "!*.test.*"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  }
+}

package/src/config.ts

@@ -0,0 +1,125 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+} from '@aztec/foundation/config';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+/**
+ * Configuration for the Validator HA Signer
+ *
+ * This config is used for distributed locking and slashing protection
+ * when running multiple validator nodes in a high-availability setup.
+ */
+export interface ValidatorHASignerConfig {
+  /** Whether HA signing / slashing protection is enabled */
+  haSigningEnabled: 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 (defaults to 2x hardcoded Aztec slot duration if not set) */
+  maxStuckDutiesAgeMs?: number;
+  /**
+   * 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 validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig> = {
+  haSigningEnabled: {
+    env: 'VALIDATOR_HA_SIGNING_ENABLED',
+    description: 'Whether HA signing / slashing protection is enabled',
+    ...booleanConfigHelper(false),
+  },
+  nodeId: {
+    env: 'VALIDATOR_HA_NODE_ID',
+    description: 'The unique identifier for this node',
+    defaultValue: '',
+  },
+  pollingIntervalMs: {
+    env: 'VALIDATOR_HA_POLLING_INTERVAL_MS',
+    description: 'The number of ms to wait between polls when a duty is being signed',
+    ...numberConfigHelper(100),
+  },
+  signingTimeoutMs: {
+    env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
+    description: 'The maximum time to wait for a duty being signed to complete',
+    ...numberConfigHelper(3_000),
+  },
+  maxStuckDutiesAgeMs: {
+    env: 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS',
+    description: 'The maximum age of a stuck duty in ms (defaults to 2x Aztec slot duration)',
+    ...optionalNumberConfigHelper(),
+  },
+  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),
+  },
+};
+
+export const defaultValidatorHASignerConfig: ValidatorHASignerConfig = getDefaultConfig(
+  validatorHASignerConfigMappings,
+);
+
+/**
+ * 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(): ValidatorHASignerConfig {
+  return getConfigFromMappings<ValidatorHASignerConfig>(validatorHASignerConfigMappings);
+}
+
+export const ValidatorHASignerConfigSchema = z.object({
+  haSigningEnabled: z.boolean(),
+  nodeId: z.string(),
+  pollingIntervalMs: z.number().min(0),
+  signingTimeoutMs: z.number().min(0),
+  maxStuckDutiesAgeMs: z.number().min(0).optional(),
+  databaseUrl: z.string().optional(),
+  poolMaxCount: z.number().min(0).optional(),
+  poolMinCount: z.number().min(0).optional(),
+  poolIdleTimeoutMs: z.number().min(0).optional(),
+  poolConnectionTimeoutMs: z.number().min(0).optional(),
+}) satisfies ZodFor<ValidatorHASignerConfig>;

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,251 @@
+/**
+ * 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';
+
+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';
+import { getBlockIndexFromDutyIdentifier } from './types.js';
+
+/**
+ * Minimal pool interface for database operations.
+ * Both pg.Pool and test adapters (e.g., PGlite) satisfy this interface.
+ */
+export interface QueryablePool {
+  query<R extends QueryResultRow = any>(text: string, values?: any[]): Promise<QueryResult<R>>;
+  end(): Promise<void>;
+}
+
+/**
+ * PostgreSQL implementation of the slashing protection database
+ */
+export class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
+  private readonly log: Logger;
+
+  constructor(private readonly pool: QueryablePool) {
+    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-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-ha-db 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.
+   *
+   * 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');
+
+    // 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 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];
+    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: 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,
+    ]);
+
+    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,
+        blockIndexWithinCheckpoint,
+      });
+      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: SlotNumber,
+    dutyType: DutyType,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): Promise<boolean> {
+    const result = await this.pool.query(DELETE_DUTY, [
+      validatorAddress.toString(),
+      slot.toString(),
+      dutyType,
+      blockIndexWithinCheckpoint,
+      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,
+        blockIndexWithinCheckpoint,
+      });
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Convert a database row to a ValidatorDutyRecord
+   */
+  private rowToRecord(row: DutyRow): ValidatorDutyRecord {
+    return {
+      validatorAddress: EthAddress.fromString(row.validator_address),
+      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,
+      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;
+  }
+}