@aztec/validator-ha-signer 0.0.1-commit.0b941701

package/README.md

@@ -0,0 +1,187 @@
+# Validator HA Signer
+
+Distributed locking and slashing protection for Aztec validators running in high-availability configurations.
+
+## Features
+
+- **Distributed Locking**: Prevents multiple validator nodes from signing the same duty
+- **Slashing Protection**: Blocks attempts to sign conflicting data for the same slot
+- **Automatic Retry**: Failed signing attempts are cleared, allowing other nodes to retry
+- **PostgreSQL Backend**: Shared database for coordination across nodes
+
+## Integration with Validator Client
+
+The HA signer is automatically integrated into the validator client when `VALIDATOR_HA_SIGNING_ENABLED=true` is set. The validator client will:
+
+1. Create the HA signer using `createHASigner()` from the factory
+2. Wrap the base keystore with `HAKeyStore` to provide HA-protected signing
+3. Automatically start/stop the signer lifecycle
+
+No manual integration is required when using the validator client.
+
+## Manual Usage
+
+For advanced use cases or testing, you can use the HA signer directly. **Note**: Database migrations must be run separately before creating the signer (see [Database Migrations](#database-migrations) below).
+
+### Basic Usage
+
+```bash
+# 1. Run migrations separately (once per deployment)
+aztec migrate-ha-db up --database-url postgresql://user:pass@host:port/db
+```
+
+```typescript
+// 2. Create signer (migrations already applied)
+import { createHASigner } from '@aztec/validator-ha-signer/factory';
+
+const { signer, db } = await createHASigner({
+  databaseUrl: process.env.DATABASE_URL,
+  haSigningEnabled: true,
+  nodeId: 'validator-node-1',
+  pollingIntervalMs: 100,
+  signingTimeoutMs: 3000,
+});
+
+// Start background cleanup tasks
+signer.start();
+
+// Sign with protection
+const signature = await signer.signWithProtection(
+  validatorAddress,
+  messageHash,
+  { slot: 100n, blockNumber: 50n, blockIndexWithinCheckpoint: 0, dutyType: 'BLOCK_PROPOSAL' },
+  async root => localSigner.signMessage(root),
+);
+
+// On shutdown
+await signer.stop();
+await db.close();
+```
+
+### Advanced: Custom Connection Pool
+
+If you need custom pool configuration (e.g., max connections, idle timeout) or want to share a connection pool across multiple components:
+
+> **Note**: You still need to run migrations separately before using this approach.
+> See [Database Migrations](#database-migrations) below.
+
+```typescript
+import { PostgresSlashingProtectionDatabase } from '@aztec/validator-ha-signer/db';
+import { ValidatorHASigner } from '@aztec/validator-ha-signer/validator-ha-signer';
+
+import { Pool } from 'pg';
+
+// Custom pool configuration
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 20, // Maximum connections
+  idleTimeoutMillis: 30000,
+});
+const db = new PostgresSlashingProtectionDatabase(pool);
+await db.initialize();
+
+const signer = new ValidatorHASigner(db, {
+  haSigningEnabled: true,
+  nodeId: 'validator-node-1',
+  pollingIntervalMs: 100,
+  signingTimeoutMs: 3000,
+  maxStuckDutiesAgeMs: 144000,
+});
+
+// Start background cleanup tasks
+signer.start();
+
+// On shutdown
+await signer.stop();
+await pool.end(); // You manage the pool lifecycle
+```
+
+## Configuration
+
+Set via environment variables or config object:
+
+- `VALIDATOR_HA_DATABASE_URL`: PostgreSQL connection string (e.g., `postgresql://user:pass@host:port/db`)
+- `VALIDATOR_HA_SIGNING_ENABLED`: Whether HA signing / slashing protection is enabled (default: false)
+- `VALIDATOR_HA_NODE_ID`: Unique identifier for this validator node (required when enabled)
+- `VALIDATOR_HA_POLLING_INTERVAL_MS`: How often to check duty status (default: 100)
+- `VALIDATOR_HA_SIGNING_TIMEOUT_MS`: Max wait for in-progress signing (default: 3000)
+- `VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS`: Max age of stuck duties before cleanup (default: 2 \* aztecSlotDuration)
+- `VALIDATOR_HA_POOL_MAX`: Maximum number of connections in the pool (default: 10)
+- `VALIDATOR_HA_POOL_MIN`: Minimum number of connections in the pool (default: 0)
+- `VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS`: Idle timeout for pool connections (default: 10000)
+- `VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS`: Connection timeout (default: 0, no timeout)
+
+## Database Migrations
+
+This package uses `node-pg-migrate` for database schema management.
+
+### Migration Commands
+
+```bash
+# Run pending migrations
+aztec migrate-ha-db up --database-url postgresql://...
+
+# Rollback last migration
+aztec migrate-ha-db down --database-url postgresql://...
+```
+
+### Creating New Migrations
+
+```bash
+# Generate a new migration file
+npx node-pg-migrate create my-migration-name
+```
+
+### Production Deployment
+
+Run migrations before starting your application:
+
+```yaml
+# Kubernetes example
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: validator-db-migrate
+spec:
+  template:
+    spec:
+      containers:
+        - name: migrate
+          image: aztecprotocol/aztec:<image_tag>
+          command: ['node', '--no-warnings', '/usr/src/yarn-project/aztec/dest/bin/index.js', 'migrate-ha-db', 'up']
+          env:
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: db-secret
+                  key: url
+      restartPolicy: OnFailure
+```
+
+## How It Works
+
+When multiple validator nodes attempt to sign:
+
+1. First node acquires lock and signs
+2. Other nodes receive `DutyAlreadySignedError` (expected)
+3. If different data detected: `SlashingProtectionError` (prevents slashing)
+4. Failed attempts are auto-cleaned, allowing retry
+
+### Signing Context
+
+All signing operations require a `SigningContext` that includes:
+
+- `slot`: The slot number
+- `blockNumber`: The block number within the checkpoint
+- `blockIndexWithinCheckpoint`: The index of the block within the checkpoint (use `-1` for N/A contexts)
+- `dutyType`: The type of duty (e.g., `BLOCK_PROPOSAL`, `CHECKPOINT_ATTESTATION`, `AUTH_REQUEST`)
+
+Note: `AUTH_REQUEST` duties bypass HA protection since signing multiple times is safe for authentication requests.
+
+## Development
+
+```bash
+yarn build    # Build package
+yarn test     # Run tests
+yarn clean    # Clean build artifacts
+```

package/dest/config.d.ts

@@ -0,0 +1,79 @@
+import { type ConfigMappingsType } from '@aztec/foundation/config';
+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 declare const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig>;
+export declare const defaultValidatorHASignerConfig: ValidatorHASignerConfig;
+/**
+ * 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 declare function getConfigEnvVars(): ValidatorHASignerConfig;
+export declare const ValidatorHASignerConfigSchema: z.ZodObject<{
+    haSigningEnabled: z.ZodBoolean;
+    nodeId: z.ZodString;
+    pollingIntervalMs: z.ZodNumber;
+    signingTimeoutMs: z.ZodNumber;
+    maxStuckDutiesAgeMs: z.ZodOptional<z.ZodNumber>;
+    databaseUrl: z.ZodOptional<z.ZodString>;
+    poolMaxCount: z.ZodOptional<z.ZodNumber>;
+    poolMinCount: z.ZodOptional<z.ZodNumber>;
+    poolIdleTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    poolConnectionTimeoutMs: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    haSigningEnabled: boolean;
+    nodeId: string;
+    pollingIntervalMs: number;
+    signingTimeoutMs: number;
+    maxStuckDutiesAgeMs?: number | undefined;
+    databaseUrl?: string | undefined;
+    poolMaxCount?: number | undefined;
+    poolMinCount?: number | undefined;
+    poolIdleTimeoutMs?: number | undefined;
+    poolConnectionTimeoutMs?: number | undefined;
+}, {
+    haSigningEnabled: boolean;
+    nodeId: string;
+    pollingIntervalMs: number;
+    signingTimeoutMs: number;
+    maxStuckDutiesAgeMs?: number | undefined;
+    databaseUrl?: string | undefined;
+    poolMaxCount?: number | undefined;
+    poolMinCount?: number | undefined;
+    poolIdleTimeoutMs?: number | undefined;
+    poolConnectionTimeoutMs?: number | undefined;
+}>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uZmlnLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY29uZmlnLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFDTCxLQUFLLGtCQUFrQixFQU14QixNQUFNLDBCQUEwQixDQUFDO0FBR2xDLE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEI7Ozs7O0dBS0c7QUFDSCxNQUFNLFdBQVcsdUJBQXVCO0lBQ3RDLDBEQUEwRDtJQUMxRCxnQkFBZ0IsRUFBRSxPQUFPLENBQUM7SUFDMUIsc0NBQXNDO0lBQ3RDLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZixzRUFBc0U7SUFDdEUsaUJBQWlCLEVBQUUsTUFBTSxDQUFDO0lBQzFCLG9FQUFvRTtJQUNwRSxnQkFBZ0IsRUFBRSxNQUFNLENBQUM7SUFDekIsa0dBQWtHO0lBQ2xHLG1CQUFtQixDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQzdCOzs7T0FHRztJQUNILFdBQVcsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNyQjs7T0FFRztJQUNILDBEQUEwRDtJQUMxRCxZQUFZLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDdEIseURBQXlEO0lBQ3pELFlBQVksQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUN0QixvREFBb0Q7SUFDcEQsaUJBQWlCLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDM0Isa0VBQWtFO0lBQ2xFLHVCQUF1QixDQUFDLEVBQUUsTUFBTSxDQUFDO0NBQ2xDO0FBRUQsZUFBTyxNQUFNLCtCQUErQixFQUFFLGtCQUFrQixDQUFDLHVCQUF1QixDQW1EdkYsQ0FBQztBQUVGLGVBQU8sTUFBTSw4QkFBOEIsRUFBRSx1QkFFNUMsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCx3QkFBZ0IsZ0JBQWdCLElBQUksdUJBQXVCLENBRTFEO0FBRUQsZUFBTyxNQUFNLDZCQUE2Qjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0VBV0UsQ0FBQyJ9

package/dest/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EAMxB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,+BAA+B,EAAE,kBAAkB,CAAC,uBAAuB,CAmDvF,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,uBAE5C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,uBAAuB,CAE1D;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWE,CAAC"}

package/dest/config.js

@@ -0,0 +1,73 @@
+import { booleanConfigHelper, getConfigFromMappings, getDefaultConfig, numberConfigHelper, optionalNumberConfigHelper } from '@aztec/foundation/config';
+import { z } from 'zod';
+export const validatorHASignerConfigMappings = {
+    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 = 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() {
+    return getConfigFromMappings(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()
+});

package/dest/db/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './schema.js';
+export * from './postgres.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGVBQWUsQ0FBQyJ9

package/dest/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dest/db/index.js

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

package/dest/db/migrations/1_initial-schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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';
+export declare function up(pgm: MigrationBuilder): void;
+export declare function down(pgm: MigrationBuilder): void;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMV9pbml0aWFsLXNjaGVtYS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2RiL21pZ3JhdGlvbnMvMV9pbml0aWFsLXNjaGVtYS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7OztHQUlHO0FBQ0gsT0FBTyxLQUFLLEVBQUUsZ0JBQWdCLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUl4RCx3QkFBZ0IsRUFBRSxDQUFDLEdBQUcsRUFBRSxnQkFBZ0IsR0FBRyxJQUFJLENBVzlDO0FBRUQsd0JBQWdCLElBQUksQ0FBQyxHQUFHLEVBQUUsZ0JBQWdCLEdBQUcsSUFBSSxDQUdoRCJ9

package/dest/db/migrations/1_initial-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"1_initial-schema.d.ts","sourceRoot":"","sources":["../../../src/db/migrations/1_initial-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD,wBAAgB,EAAE,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAW9C;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAGhD"}

package/dest/db/migrations/1_initial-schema.js

@@ -0,0 +1,20 @@
+/**
+ * Initial schema for validator HA slashing protection
+ *
+ * This migration imports SQL from the schema.ts file to ensure a single source of truth.
+ */ import { DROP_SCHEMA_VERSION_TABLE, DROP_VALIDATOR_DUTIES_TABLE, SCHEMA_SETUP, SCHEMA_VERSION } from '../schema.js';
+export function up(pgm) {
+    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) {
+    pgm.sql(DROP_VALIDATOR_DUTIES_TABLE);
+    pgm.sql(DROP_SCHEMA_VERSION_TABLE);
+}

package/dest/db/postgres.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PostgreSQL implementation of SlashingProtectionDatabase
+ */
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { QueryResult, QueryResultRow } from 'pg';
+import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
+import type { CheckAndRecordParams, DutyType } 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 declare class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
+    private readonly pool;
+    private readonly log;
+    constructor(pool: QueryablePool);
+    /**
+     * 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
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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.
+     */
+    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: 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(validatorAddress: EthAddress, slot: SlotNumber, dutyType: DutyType, lockToken: string, blockIndexWithinCheckpoint: number): Promise<boolean>;
+    /**
+     * Convert a database row to a ValidatorDutyRecord
+     */
+    private rowToRecord;
+    /**
+     * Close the database connection pool
+     */
+    close(): Promise<void>;
+    /**
+     * Cleanup own stuck duties
+     * @returns the number of duties cleaned up
+     */
+    cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9zdGdyZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9wb3N0Z3Jlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE9BQU8sRUFBZSxVQUFVLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUUxRSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFJM0QsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLGNBQWMsRUFBRSxNQUFNLElBQUksQ0FBQztBQUV0RCxPQUFPLEtBQUssRUFBRSwwQkFBMEIsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQVFwRixPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBVyxRQUFRLEVBQXVDLE1BQU0sWUFBWSxDQUFDO0FBRy9HOzs7R0FHRztBQUNILE1BQU0sV0FBVyxhQUFhO0lBQzVCLEtBQUssQ0FBQyxDQUFDLFNBQVMsY0FBYyxHQUFHLEdBQUcsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxFQUFFLEdBQUcsRUFBRSxHQUFHLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUM3RixHQUFHLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxxQkFBYSxrQ0FBbUMsWUFBVywwQkFBMEI7SUFHdkUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJO0lBRmpDLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQTZCLElBQUksRUFBRSxhQUFhLEVBRS9DO0lBRUQ7Ozs7O09BS0c7SUFDRyxVQUFVLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdDaEM7SUFFRDs7Ozs7Ozs7T0FRRztJQUNHLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0FtRHhGO0lBRUQ7Ozs7O09BS0c7SUFDRyxnQkFBZ0IsQ0FDcEIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixJQUFJLEVBQUUsVUFBVSxFQUNoQixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxFQUNqQixTQUFTLEVBQUUsTUFBTSxFQUNqQiwwQkFBMEIsRUFBRSxNQUFNLEdBQ2pDLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FvQmxCO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUNkLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLFVBQVUsRUFDaEIsUUFBUSxFQUFFLFFBQVEsRUFDbEIsU0FBUyxFQUFFLE1BQU0sRUFDakIsMEJBQTBCLEVBQUUsTUFBTSxHQUNqQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBbUJsQjtJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFdBQVc7SUFrQm5COztPQUVHO0lBQ0csS0FBSyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHM0I7SUFFRDs7O09BR0c7SUFDRyxxQkFBcUIsQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUk3RTtDQUNGIn0=

package/dest/db/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAe,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAI3D,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEtD,OAAO,KAAK,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAW,QAAQ,EAAuC,MAAM,YAAY,CAAC;AAG/G;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,kCAAmC,YAAW,0BAA0B;IAGvE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAA6B,IAAI,EAAE,aAAa,EAE/C;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChC;IAED;;;;;;;;OAQG;IACG,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmDxF;IAED;;;;;OAKG;IACG,gBAAgB,CACpB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAoBlB;IAED;;;;;;OAMG;IACG,UAAU,CACd,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAmBlB;IAED;;OAEG;IACH,OAAO,CAAC,WAAW;IAkBnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED;;;OAGG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;CACF"}

package/dest/db/postgres.js

@@ -0,0 +1,181 @@
+/**
+ * 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 { createLogger } from '@aztec/foundation/log';
+import { makeBackoff, retry } from '@aztec/foundation/retry';
+import { CLEANUP_OWN_STUCK_DUTIES, DELETE_DUTY, INSERT_OR_GET_DUTY, SCHEMA_VERSION, UPDATE_DUTY_SIGNED } from './schema.js';
+import { getBlockIndexFromDutyIdentifier } from './types.js';
+/**
+ * PostgreSQL implementation of the slashing protection database
+ */ export class PostgresSlashingProtectionDatabase {
+    pool;
+    log;
+    constructor(pool){
+        this.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() {
+        let dbVersion;
+        try {
+            const result = await this.pool.query(`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) {
+        // 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(async ()=>{
+            const queryResult = 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, slot, dutyType, signature, lockToken, blockIndexWithinCheckpoint) {
+        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, slot, dutyType, lockToken, blockIndexWithinCheckpoint) {
+        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
+   */ rowToRecord(row) {
+        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() {
+        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, maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs);
+        const result = await this.pool.query(CLEANUP_OWN_STUCK_DUTIES, [
+            nodeId,
+            cutoff
+        ]);
+        return result.rowCount ?? 0;
+    }
+}