@aztec/validator-ha-signer 0.0.1-commit.0208eb9

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,101 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import { type ConfigMappingsType } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+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;
+    /** L1 contract addresses (rollup address required) */
+    l1Contracts: Pick<L1ContractAddresses, 'rollupAddress'>;
+    /** 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;
+    /** Optional: clean up old duties after this many hours (disabled if not set) */
+    cleanupOldDutiesAfterHours?: 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;
+    l1Contracts: z.ZodObject<{
+        rollupAddress: z.ZodType<EthAddress, z.ZodTypeDef, EthAddress>;
+    }, "strip", z.ZodTypeAny, {
+        rollupAddress: EthAddress;
+    }, {
+        rollupAddress: EthAddress;
+    }>;
+    nodeId: z.ZodString;
+    pollingIntervalMs: z.ZodNumber;
+    signingTimeoutMs: z.ZodNumber;
+    maxStuckDutiesAgeMs: z.ZodOptional<z.ZodNumber>;
+    cleanupOldDutiesAfterHours: 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;
+    l1Contracts: {
+        rollupAddress: EthAddress;
+    };
+    nodeId: string;
+    pollingIntervalMs: number;
+    signingTimeoutMs: number;
+    maxStuckDutiesAgeMs?: number | undefined;
+    cleanupOldDutiesAfterHours?: number | undefined;
+    databaseUrl?: string | undefined;
+    poolMaxCount?: number | undefined;
+    poolMinCount?: number | undefined;
+    poolIdleTimeoutMs?: number | undefined;
+    poolConnectionTimeoutMs?: number | undefined;
+}, {
+    haSigningEnabled: boolean;
+    l1Contracts: {
+        rollupAddress: EthAddress;
+    };
+    nodeId: string;
+    pollingIntervalMs: number;
+    signingTimeoutMs: number;
+    maxStuckDutiesAgeMs?: number | undefined;
+    cleanupOldDutiesAfterHours?: number | undefined;
+    databaseUrl?: string | undefined;
+    poolMaxCount?: number | undefined;
+    poolMinCount?: number | undefined;
+    poolIdleTimeoutMs?: number | undefined;
+    poolConnectionTimeoutMs?: number | undefined;
+}>;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uZmlnLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY29uZmlnLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sdUNBQXVDLENBQUM7QUFDakYsT0FBTyxFQUNMLEtBQUssa0JBQWtCLEVBTXhCLE1BQU0sMEJBQTBCLENBQUM7QUFDbEMsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBRzNELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEI7Ozs7O0dBS0c7QUFDSCxNQUFNLFdBQVcsdUJBQXVCO0lBQ3RDLDBEQUEwRDtJQUMxRCxnQkFBZ0IsRUFBRSxPQUFPLENBQUM7SUFDMUIsc0RBQXNEO0lBQ3RELFdBQVcsRUFBRSxJQUFJLENBQUMsbUJBQW1CLEVBQUUsZUFBZSxDQUFDLENBQUM7SUFDeEQsc0NBQXNDO0lBQ3RDLE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZixzRUFBc0U7SUFDdEUsaUJBQWlCLEVBQUUsTUFBTSxDQUFDO0lBQzFCLG9FQUFvRTtJQUNwRSxnQkFBZ0IsRUFBRSxNQUFNLENBQUM7SUFDekIsa0dBQWtHO0lBQ2xHLG1CQUFtQixDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQzdCLGdGQUFnRjtJQUNoRiwwQkFBMEIsQ0FBQyxFQUFFLE1BQU0sQ0FBQztJQUNwQzs7O09BR0c7SUFDSCxXQUFXLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDckI7O09BRUc7SUFDSCwwREFBMEQ7SUFDMUQsWUFBWSxDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQ3RCLHlEQUF5RDtJQUN6RCxZQUFZLENBQUMsRUFBRSxNQUFNLENBQUM7SUFDdEIsb0RBQW9EO0lBQ3BELGlCQUFpQixDQUFDLEVBQUUsTUFBTSxDQUFDO0lBQzNCLGtFQUFrRTtJQUNsRSx1QkFBdUIsQ0FBQyxFQUFFLE1BQU0sQ0FBQztDQUNsQztBQUVELGVBQU8sTUFBTSwrQkFBK0IsRUFBRSxrQkFBa0IsQ0FBQyx1QkFBdUIsQ0FpRXZGLENBQUM7QUFFRixlQUFPLE1BQU0sOEJBQThCLEVBQUUsdUJBRTVDLENBQUM7QUFFRjs7OztHQUlHO0FBQ0gsd0JBQWdCLGdCQUFnQixJQUFJLHVCQUF1QixDQUUxRDtBQUVELGVBQU8sTUFBTSw2QkFBNkI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7RUFlRSxDQUFDIn0=

package/dest/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,KAAK,kBAAkB,EAMxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAG3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,WAAW,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IACxD,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,gFAAgF;IAChF,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC;;;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,CAiEvF,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,uBAE5C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,uBAAuB,CAE1D;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeE,CAAC"}

package/dest/config.js

@@ -0,0 +1,92 @@
+import { booleanConfigHelper, getConfigFromMappings, getDefaultConfig, numberConfigHelper, optionalNumberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { z } from 'zod';
+export const validatorHASignerConfigMappings = {
+    haSigningEnabled: {
+        env: 'VALIDATOR_HA_SIGNING_ENABLED',
+        description: 'Whether HA signing / slashing protection is enabled',
+        ...booleanConfigHelper(false)
+    },
+    l1Contracts: {
+        description: 'L1 contract addresses (rollup address required)',
+        nested: {
+            rollupAddress: {
+                description: 'The Ethereum address of the rollup contract (must be set programmatically)',
+                parseEnv: (val)=>EthAddress.fromString(val)
+            }
+        }
+    },
+    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()
+    },
+    cleanupOldDutiesAfterHours: {
+        env: 'VALIDATOR_HA_OLD_DUTIES_MAX_AGE_H',
+        description: 'Optional: clean up old duties after this many hours (disabled if not set)',
+        ...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(),
+    l1Contracts: z.object({
+        rollupAddress: z.instanceof(EthAddress)
+    }),
+    nodeId: z.string(),
+    pollingIntervalMs: z.number().min(0),
+    signingTimeoutMs: z.number().min(0),
+    maxStuckDutiesAgeMs: z.number().min(0).optional(),
+    cleanupOldDutiesAfterHours: 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,84 @@
+/**
+ * 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(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>;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * Does not remove 'signing' duties as they may be in progress.
+     * @returns the number of duties cleaned up
+     */
+    cleanupOldDuties(maxAgeMs: number): Promise<number>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicG9zdGdyZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYi9wb3N0Z3Jlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE9BQU8sRUFBZSxVQUFVLEVBQUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUUxRSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFJM0QsT0FBTyxLQUFLLEVBQUUsV0FBVyxFQUFFLGNBQWMsRUFBRSxNQUFNLElBQUksQ0FBQztBQUV0RCxPQUFPLEtBQUssRUFBRSwwQkFBMEIsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQVVwRixPQUFPLEtBQUssRUFBRSxvQkFBb0IsRUFBVyxRQUFRLEVBQXVDLE1BQU0sWUFBWSxDQUFDO0FBRy9HOzs7R0FHRztBQUNILE1BQU0sV0FBVyxhQUFhO0lBQzVCLEtBQUssQ0FBQyxDQUFDLFNBQVMsY0FBYyxHQUFHLEdBQUcsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLE1BQU0sQ0FBQyxFQUFFLEdBQUcsRUFBRSxHQUFHLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztJQUM3RixHQUFHLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQUFDO0NBQ3RCO0FBRUQ7O0dBRUc7QUFDSCxxQkFBYSxrQ0FBbUMsWUFBVywwQkFBMEI7SUFHdkUsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJO0lBRmpDLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBRTdCLFlBQTZCLElBQUksRUFBRSxhQUFhLEVBRS9DO0lBRUQ7Ozs7O09BS0c7SUFDRyxVQUFVLElBQUksT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdDaEM7SUFFRDs7Ozs7Ozs7T0FRRztJQUNHLHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0FvRHhGO0lBRUQ7Ozs7O09BS0c7SUFDRyxnQkFBZ0IsQ0FDcEIsYUFBYSxFQUFFLFVBQVUsRUFDekIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixJQUFJLEVBQUUsVUFBVSxFQUNoQixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxFQUNqQixTQUFTLEVBQUUsTUFBTSxFQUNqQiwwQkFBMEIsRUFBRSxNQUFNLEdBQ2pDLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FzQmxCO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUNkLGFBQWEsRUFBRSxVQUFVLEVBQ3pCLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLFVBQVUsRUFDaEIsUUFBUSxFQUFFLFFBQVEsRUFDbEIsU0FBUyxFQUFFLE1BQU0sRUFDakIsMEJBQTBCLEVBQUUsTUFBTSxHQUNqQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBcUJsQjtJQUVEOztPQUVHO0lBQ0gsT0FBTyxDQUFDLFdBQVc7SUFtQm5COztPQUVHO0lBQ0csS0FBSyxJQUFJLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FHM0I7SUFFRDs7O09BR0c7SUFDRyxxQkFBcUIsQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUk3RTtJQUVEOzs7OztPQUtHO0lBQ0csMkJBQTJCLENBQUMsb0JBQW9CLEVBQUUsVUFBVSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FHbkY7SUFFRDs7Ozs7T0FLRztJQUNHLGdCQUFnQixDQUFDLFFBQVEsRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUl4RDtDQUNGIn0=

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;AAUpF,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,CAoDxF;IAED;;;;;OAKG;IACG,gBAAgB,CACpB,aAAa,EAAE,UAAU,EACzB,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,CAsBlB;IAED;;;;;;OAMG;IACG,UAAU,CACd,aAAa,EAAE,UAAU,EACzB,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,0BAA0B,EAAE,MAAM,GACjC,OAAO,CAAC,OAAO,CAAC,CAqBlB;IAED;;OAEG;IACH,OAAO,CAAC,WAAW;IAmBnB;;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;IAED;;;;;OAKG;IACG,2BAA2B,CAAC,oBAAoB,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnF;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxD;CACF"}