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

package/README.md

@@ -0,0 +1,182 @@
+# 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
+
+## Quick Start
+
+### Option 1: Automatic Migrations (Simplest)
+
+```typescript
+import { createHASigner } from '@aztec/validator-ha-signer/factory';
+
+// Migrations run automatically on startup
+const { signer, db } = await createHASigner({
+  databaseUrl: process.env.DATABASE_URL,
+  enabled: 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, dutyType: 'BLOCK_PROPOSAL' },
+  async root => localSigner.signMessage(root),
+);
+
+// Cleanup on shutdown
+await signer.stop();
+await db.close();
+```
+
+### Option 2: Manual Migrations (Recommended for Production)
+
+```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,
+  enabled: true,
+  nodeId: 'validator-node-1',
+  pollingIntervalMs: 100,
+  signingTimeoutMs: 3000,
+});
+
+// Start background cleanup tasks
+signer.start();
+
+// 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 [Option 2](#option-2-manual-migrations-recommended-for-production) above.
+
+```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, {
+  enabled: true,
+  nodeId: 'validator-node-1',
+  pollingIntervalMs: 100,
+  signingTimeoutMs: 3000,
+  maxStuckDutiesAgeMs: 72000,
+});
+
+// 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`)
+- `SLASHING_PROTECTION_ENABLED`: Whether slashing protection is enabled (default: true)
+- `SLASHING_PROTECTION_NODE_ID`: Unique identifier for this validator node
+- `SLASHING_PROTECTION_POLLING_INTERVAL_MS`: How often to check duty status (default: 100)
+- `SLASHING_PROTECTION_SIGNING_TIMEOUT_MS`: Max wait for in-progress signing (default: 3000)
+- `SLASHING_PROTECTION_MAX_STUCK_DUTIES_AGE_MS`: Max age of stuck duties before cleanup (default: 72000)
+
+## 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` (likely for block builder signing)
+4. Failed attempts are auto-cleaned, allowing retry
+
+## Development
+
+```bash
+yarn build    # Build package
+yarn test     # Run tests
+yarn clean    # Clean build artifacts
+```

package/dest/config.d.ts

@@ -0,0 +1,47 @@
+import { type ConfigMappingsType } 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 declare const slashingProtectionConfigMappings: ConfigMappingsType<SlashingProtectionConfig>;
+export declare const defaultSlashingProtectionConfig: SlashingProtectionConfig;
+/**
+ * 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 declare const createHASignerConfigMappings: ConfigMappingsType<CreateHASignerConfig>;
+/**
+ * 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(): CreateHASignerConfig;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uZmlnLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY29uZmlnLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFDTCxLQUFLLGtCQUFrQixFQUt4QixNQUFNLDBCQUEwQixDQUFDO0FBRWxDOztHQUVHO0FBQ0gsTUFBTSxXQUFXLHdCQUF3QjtJQUN2Qyw2Q0FBNkM7SUFDN0MsT0FBTyxFQUFFLE9BQU8sQ0FBQztJQUNqQixzQ0FBc0M7SUFDdEMsTUFBTSxFQUFFLE1BQU0sQ0FBQztJQUNmLHNFQUFzRTtJQUN0RSxpQkFBaUIsRUFBRSxNQUFNLENBQUM7SUFDMUIsb0VBQW9FO0lBQ3BFLGdCQUFnQixFQUFFLE1BQU0sQ0FBQztJQUN6Qix3Q0FBd0M7SUFDeEMsbUJBQW1CLEVBQUUsTUFBTSxDQUFDO0NBQzdCO0FBRUQsZUFBTyxNQUFNLGdDQUFnQyxFQUFFLGtCQUFrQixDQUFDLHdCQUF3QixDQTJCekYsQ0FBQztBQUVGLGVBQU8sTUFBTSwrQkFBK0IsRUFBRSx3QkFFN0MsQ0FBQztBQUVGOztHQUVHO0FBQ0gsTUFBTSxXQUFXLG9CQUFxQixTQUFRLHdCQUF3QjtJQUNwRTs7O09BR0c7SUFDSCxXQUFXLEVBQUUsTUFBTSxDQUFDO0lBQ3BCOztPQUVHO0lBQ0gsMERBQTBEO0lBQzFELFlBQVksQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUN0Qix5REFBeUQ7SUFDekQsWUFBWSxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ3RCLG9EQUFvRDtJQUNwRCxpQkFBaUIsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUMzQixrRUFBa0U7SUFDbEUsdUJBQXVCLENBQUMsRUFBRSxNQUFNLENBQUM7Q0FDbEM7QUFFRCxlQUFPLE1BQU0sNEJBQTRCLEVBQUUsa0JBQWtCLENBQUMsb0JBQW9CLENBMkJqRixDQUFDO0FBRUY7Ozs7R0FJRztBQUNILHdCQUFnQixnQkFBZ0IsSUFBSSxvQkFBb0IsQ0FFdkQifQ==

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,EAKxB,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,gCAAgC,EAAE,kBAAkB,CAAC,wBAAwB,CA2BzF,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,wBAE7C,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,wBAAwB;IACpE;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;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,4BAA4B,EAAE,kBAAkB,CAAC,oBAAoB,CA2BjF,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,CAEvD"}

package/dest/config.js

@@ -0,0 +1,64 @@
+import { booleanConfigHelper, getConfigFromMappings, getDefaultConfig, numberConfigHelper } from '@aztec/foundation/config';
+export const slashingProtectionConfigMappings = {
+    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 = getDefaultConfig(slashingProtectionConfigMappings);
+export const createHASignerConfigMappings = {
+    ...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() {
+    return getConfigFromMappings(createHASignerConfigMappings);
+}

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,55 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { Pool } from 'pg';
+import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
+import type { CheckAndRecordParams, DutyType } from './types.js';
+/**
+ * PostgreSQL implementation of the slashing protection database
+ */
+export declare class PostgresSlashingProtectionDatabase implements SlashingProtectionDatabase {
+    private readonly pool;
+    private readonly log;
+    constructor(pool: Pool);
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * 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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9zdGdyZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9wb3N0Z3Jlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFJQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFHM0QsT0FBTyxLQUFLLEVBQUUsSUFBSSxFQUFlLE1BQU0sSUFBSSxDQUFDO0FBRTVDLE9BQU8sS0FBSyxFQUFFLDBCQUEwQixFQUFFLG9CQUFvQixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBUXBGLE9BQU8sS0FBSyxFQUFFLG9CQUFvQixFQUFXLFFBQVEsRUFBdUMsTUFBTSxZQUFZLENBQUM7QUFFL0c7O0dBRUc7QUFDSCxxQkFBYSxrQ0FBbUMsWUFBVywwQkFBMEI7SUFHdkUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJO0lBRmpDLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQTZCLElBQUksRUFBRSxJQUFJLEVBRXRDO0lBRUQ7Ozs7O09BS0c7SUFDRyxVQUFVLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdDaEM7SUFFRDs7Ozs7T0FLRztJQUNHLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0F3QnhGO0lBRUQ7Ozs7O09BS0c7SUFDRyxnQkFBZ0IsQ0FDcEIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixJQUFJLEVBQUUsTUFBTSxFQUNaLFFBQVEsRUFBRSxRQUFRLEVBQ2xCLFNBQVMsRUFBRSxNQUFNLEVBQ2pCLFNBQVMsRUFBRSxNQUFNLEdBQ2hCLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FrQmxCO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUNkLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLE1BQU0sRUFDWixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxHQUNoQixPQUFPLENBQUMsT0FBTyxDQUFDLENBaUJsQjtJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFdBQVc7SUFpQm5COztPQUVHO0lBQ0csS0FBSyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHM0I7SUFFRDs7O09BR0c7SUFDRyxxQkFBcUIsQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUk3RTtDQUNGIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/db/postgres.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAG3D,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,IAAI,CAAC;AAE5C,OAAO,KAAK,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQpF,OAAO,KAAK,EAAE,oBAAoB,EAAW,QAAQ,EAAuC,MAAM,YAAY,CAAC;AAE/G;;GAEG;AACH,qBAAa,kCAAmC,YAAW,0BAA0B;IAGvE,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAE7B,YAA6B,IAAI,EAAE,IAAI,EAEtC;IAED;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChC;IAED;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAwBxF;IAED;;;;;OAKG;IACG,gBAAgB,CACpB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAkBlB;IAED;;;;;;OAMG;IACG,UAAU,CACd,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAiBlB;IAED;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;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,150 @@
+/**
+ * PostgreSQL implementation of SlashingProtectionDatabase
+ */ import { randomBytes } from '@aztec/foundation/crypto/random';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { createLogger } from '@aztec/foundation/log';
+import { CLEANUP_OWN_STUCK_DUTIES, DELETE_DUTY, INSERT_OR_GET_DUTY, SCHEMA_VERSION, UPDATE_DUTY_SIGNED } from './schema.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 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) {
+        // create a token for ownership verification
+        const lockToken = randomBytes(16).toString('hex');
+        const result = 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, slot, dutyType, signature, lockToken) {
+        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, slot, dutyType, lockToken) {
+        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
+   */ rowToRecord(row) {
+        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() {
+        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;
+    }
+}

package/dest/db/schema.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 declare const SCHEMA_VERSION = 1;
+/**
+ * SQL to create the validator_duties table
+ */
+export declare const CREATE_VALIDATOR_DUTIES_TABLE = "\nCREATE TABLE IF NOT EXISTS validator_duties (\n  validator_address VARCHAR(42) NOT NULL,\n  slot BIGINT NOT NULL,\n  block_number BIGINT NOT NULL,\n  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS')),\n  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed', 'failed')),\n  message_hash VARCHAR(66) NOT NULL,\n  signature VARCHAR(132),\n  node_id VARCHAR(255) NOT NULL,\n  lock_token VARCHAR(64) NOT NULL,\n  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  completed_at TIMESTAMP,\n  error_message TEXT,\n\n  PRIMARY KEY (validator_address, slot, duty_type),\n  CHECK (completed_at IS NULL OR completed_at >= started_at)\n);\n";
+/**
+ * SQL to create index on status and started_at for cleanup queries
+ */
+export declare const CREATE_STATUS_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_status\nON validator_duties(status, started_at);\n";
+/**
+ * SQL to create index for querying duties by node
+ */
+export declare const CREATE_NODE_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_node\nON validator_duties(node_id, started_at);\n";
+/**
+ * SQL to create the schema_version table for tracking migrations
+ */
+export declare const CREATE_SCHEMA_VERSION_TABLE = "\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n";
+/**
+ * SQL to initialize schema version
+ */
+export declare const INSERT_SCHEMA_VERSION = "\nINSERT INTO schema_version (version)\nVALUES ($1)\nON CONFLICT (version) DO NOTHING;\n";
+/**
+ * Complete schema setup - all statements in order
+ */
+export declare const SCHEMA_SETUP: readonly ["\nCREATE TABLE IF NOT EXISTS schema_version (\n  version INTEGER PRIMARY KEY,\n  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP\n);\n", "\nCREATE TABLE IF NOT EXISTS validator_duties (\n  validator_address VARCHAR(42) NOT NULL,\n  slot BIGINT NOT NULL,\n  block_number BIGINT NOT NULL,\n  duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS')),\n  status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed', 'failed')),\n  message_hash VARCHAR(66) NOT NULL,\n  signature VARCHAR(132),\n  node_id VARCHAR(255) NOT NULL,\n  lock_token VARCHAR(64) NOT NULL,\n  started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,\n  completed_at TIMESTAMP,\n  error_message TEXT,\n\n  PRIMARY KEY (validator_address, slot, duty_type),\n  CHECK (completed_at IS NULL OR completed_at >= started_at)\n);\n", "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_status\nON validator_duties(status, started_at);\n", "\nCREATE INDEX IF NOT EXISTS idx_validator_duties_node\nON validator_duties(node_id, started_at);\n"];
+/**
+ * Query to get current schema version
+ */
+export declare const GET_SCHEMA_VERSION = "\nSELECT version FROM schema_version ORDER BY version DESC LIMIT 1;\n";
+/**
+ * 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 declare const INSERT_OR_GET_DUTY = "\nWITH inserted AS (\n  INSERT INTO validator_duties (\n    validator_address,\n    slot,\n    block_number,\n    duty_type,\n    status,\n    message_hash,\n    node_id,\n    lock_token,\n    started_at\n  ) VALUES ($1, $2, $3, $4, 'signing', $5, $6, $7, CURRENT_TIMESTAMP)\n  ON CONFLICT (validator_address, slot, duty_type) DO NOTHING\n  RETURNING\n    validator_address,\n    slot,\n    block_number,\n    duty_type,\n    status,\n    message_hash,\n    signature,\n    node_id,\n    lock_token,\n    started_at,\n    completed_at,\n    error_message,\n    TRUE as is_new\n)\nSELECT * FROM inserted\nUNION ALL\nSELECT\n  validator_address,\n  slot,\n  block_number,\n  duty_type,\n  status,\n  message_hash,\n  signature,\n  node_id,\n  '' as lock_token,\n  started_at,\n  completed_at,\n  error_message,\n  FALSE as is_new\nFROM validator_duties\nWHERE validator_address = $1\n  AND slot = $2\n  AND duty_type = $4\n  AND NOT EXISTS (SELECT 1 FROM inserted);\n";
+/**
+ * Query to update a duty to 'signed' status
+ */
+export declare const UPDATE_DUTY_SIGNED = "\nUPDATE validator_duties\nSET status = 'signed',\n    signature = $1,\n    completed_at = CURRENT_TIMESTAMP\nWHERE validator_address = $2\n  AND slot = $3\n  AND duty_type = $4\n  AND status = 'signing'\n  AND lock_token = $5;\n";
+/**
+ * Query to delete a duty
+ * Only deletes if the lockToken matches
+ */
+export declare const DELETE_DUTY = "\nDELETE FROM validator_duties\nWHERE validator_address = $1\n  AND slot = $2\n  AND duty_type = $3\n  AND status = 'signing'\n  AND lock_token = $4;\n";
+/**
+ * Query to clean up old signed duties (for maintenance)
+ * Removes signed duties older than a specified timestamp
+ */
+export declare const CLEANUP_OLD_SIGNED_DUTIES = "\nDELETE FROM validator_duties\nWHERE status = 'signed'\n  AND completed_at < $1;\n";
+/**
+ * Query to clean up old duties (for maintenance)
+ * Removes duties older than a specified timestamp
+ */
+export declare const CLEANUP_OLD_DUTIES = "\nDELETE FROM validator_duties\nWHERE status IN ('signing', 'signed', 'failed')\n  AND started_at < $1;\n";
+/**
+ * Query to cleanup own stuck duties
+ * Removes duties in 'signing' status for a specific node that are older than maxAgeMs
+ */
+export declare const CLEANUP_OWN_STUCK_DUTIES = "\nDELETE FROM validator_duties\nWHERE node_id = $1\n  AND status = 'signing'\n  AND started_at < $2;\n";
+/**
+ * SQL to drop the validator_duties table
+ */
+export declare const DROP_VALIDATOR_DUTIES_TABLE = "DROP TABLE IF EXISTS validator_duties;";
+/**
+ * SQL to drop the schema_version table
+ */
+export declare 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 declare const GET_STUCK_DUTIES = "\nSELECT\n  validator_address,\n  slot,\n  block_number,\n  duty_type,\n  status,\n  message_hash,\n  node_id,\n  started_at,\n  EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - started_at)) as age_seconds\nFROM validator_duties\nWHERE status = 'signing'\n  AND started_at < $1\nORDER BY started_at ASC;\n";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2NoZW1hLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGIvc2NoZW1hLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7R0FNRztBQUVIOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGNBQWMsSUFBSSxDQUFDO0FBRWhDOztHQUVHO0FBQ0gsZUFBTyxNQUFNLDZCQUE2QixpdEJBa0J6QyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sbUJBQW1CLHlHQUcvQixDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0saUJBQWlCLHdHQUc3QixDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sMkJBQTJCLG1KQUt2QyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0scUJBQXFCLDZGQUlqQyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sWUFBWSw0akNBS2YsQ0FBQztBQUVYOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGtCQUFrQiwwRUFFOUIsQ0FBQztBQUVGOzs7Ozs7R0FNRztBQUNILGVBQU8sTUFBTSxrQkFBa0IsMDhCQWtEOUIsQ0FBQztBQUVGOztHQUVHO0FBQ0gsZUFBTyxNQUFNLGtCQUFrQiwwT0FVOUIsQ0FBQztBQUVGOzs7R0FHRztBQUNILGVBQU8sTUFBTSxXQUFXLDRKQU92QixDQUFDO0FBRUY7OztHQUdHO0FBQ0gsZUFBTyxNQUFNLHlCQUF5Qix3RkFJckMsQ0FBQztBQUVGOzs7R0FHRztBQUNILGVBQU8sTUFBTSxrQkFBa0IsOEdBSTlCLENBQUM7QUFFRjs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sd0JBQXdCLDJHQUtwQyxDQUFDO0FBRUY7O0dBRUc7QUFDSCxlQUFPLE1BQU0sMkJBQTJCLDJDQUEyQyxDQUFDO0FBRXBGOztHQUVHO0FBQ0gsZUFBTyxNQUFNLHlCQUF5Qix5Q0FBeUMsQ0FBQztBQUVoRjs7O0dBR0c7QUFDSCxlQUFPLE1BQU0sZ0JBQWdCLDZTQWU1QixDQUFDIn0=

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;GAEG;AACH,eAAO,MAAM,6BAA6B,itBAkBzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,yGAG/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,wGAG7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,mJAKvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,6FAIjC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,4jCAKf,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,kBAAkB,0EAE9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,08BAkD9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,0OAU9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,4JAOvB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,wFAIrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,8GAI9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,2GAKpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,2CAA2C,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,yBAAyB,yCAAyC,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,6SAe5B,CAAC"}