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

package/dest/slashing_protection_service.d.ts

@@ -0,0 +1,74 @@
+import { type CheckAndRecordParams, type DeleteDutyParams, type RecordSuccessParams } from './db/types.js';
+import type { SlashingProtectionConfig, SlashingProtectionDatabase } from './types.js';
+/**
+ * Slashing Protection Service
+ *
+ * This service ensures that a validator only signs one block/attestation per slot,
+ * even when running multiple redundant nodes (HA setup).
+ *
+ * All nodes in the HA setup try to sign - the first one wins, others get
+ * DutyAlreadySignedError (normal) or SlashingProtectionError (if different data).
+ *
+ * Flow:
+ * 1. checkAndRecord() - Atomically try to acquire lock via tryInsertOrGetExisting
+ * 2. Caller performs the signing operation
+ * 3. recordSuccess() - Update to 'signed' status with signature
+ *    OR deleteDuty() - Delete the record to allow retry
+ */
+export declare class SlashingProtectionService {
+    private readonly db;
+    private readonly config;
+    private readonly log;
+    private readonly pollingIntervalMs;
+    private readonly signingTimeoutMs;
+    private cleanupRunningPromise;
+    constructor(db: SlashingProtectionDatabase, config: SlashingProtectionConfig);
+    /**
+     * Check if a duty can be performed and acquire the lock if so.
+     *
+     * This method uses an atomic insert-or-get operation.
+     * It will:
+     * 1. Try to insert a new record with 'signing' status
+     * 2. If insert succeeds, we acquired the lock - return the lockToken
+     * 3. If a record exists, handle based on status:
+     *    - SIGNED: Throw appropriate error (already signed or slashing protection)
+     *    - FAILED: Delete the failed record
+     *    - SIGNING: Wait and poll until status changes, then handle result
+     *
+     * @returns The lockToken that must be used for recordSuccess/deleteDuty
+     * @throws DutyAlreadySignedError if the duty was already completed
+     * @throws SlashingProtectionError if attempting to sign different data for same slot/duty
+     */
+    checkAndRecord(params: CheckAndRecordParams): Promise<string>;
+    /**
+     * Record a successful signing operation.
+     * Updates the duty status to 'signed' and stores 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
+     */
+    recordSuccess(params: RecordSuccessParams): Promise<boolean>;
+    /**
+     * Delete a duty record after a failed signing operation.
+     * Removes the record to allow another node/attempt to retry.
+     * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+     *
+     * @returns true if the delete succeeded, false if token didn't match
+     */
+    deleteDuty(params: DeleteDutyParams): Promise<boolean>;
+    /**
+     * Get the node ID for this service
+     */
+    get nodeId(): string;
+    /**
+     * Start running tasks.
+     * Cleanup runs immediately on start to recover from any previous crashes.
+     */
+    start(): void;
+    /**
+     * Stop the background cleanup task.
+     */
+    stop(): Promise<void>;
+    private cleanupStuckDuties;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2xhc2hpbmdfcHJvdGVjdGlvbl9zZXJ2aWNlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvc2xhc2hpbmdfcHJvdGVjdGlvbl9zZXJ2aWNlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQVVBLE9BQU8sRUFBRSxLQUFLLG9CQUFvQixFQUFFLEtBQUssZ0JBQWdCLEVBQWMsS0FBSyxtQkFBbUIsRUFBRSxNQUFNLGVBQWUsQ0FBQztBQUV2SCxPQUFPLEtBQUssRUFBRSx3QkFBd0IsRUFBRSwwQkFBMEIsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUV2Rjs7Ozs7Ozs7Ozs7Ozs7R0FjRztBQUNILHFCQUFhLHlCQUF5QjtJQVFsQyxPQUFPLENBQUMsUUFBUSxDQUFDLEVBQUU7SUFDbkIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxNQUFNO0lBUnpCLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBQzdCLE9BQU8sQ0FBQyxRQUFRLENBQUMsaUJBQWlCLENBQVM7SUFDM0MsT0FBTyxDQUFDLFFBQVEsQ0FBQyxnQkFBZ0IsQ0FBUztJQUUxQyxPQUFPLENBQUMscUJBQXFCLENBQWlCO0lBRTlDLFlBQ21CLEVBQUUsRUFBRSwwQkFBMEIsRUFDOUIsTUFBTSxFQUFFLHdCQUF3QixFQVdsRDtJQUVEOzs7Ozs7Ozs7Ozs7Ozs7T0FlRztJQUNHLGNBQWMsQ0FBQyxNQUFNLEVBQUUsb0JBQW9CLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQTBEbEU7SUFFRDs7Ozs7O09BTUc7SUFDRyxhQUFhLENBQUMsTUFBTSxFQUFFLG1CQUFtQixHQUFHLE9BQU8sQ0FBQyxPQUFPLENBQUMsQ0FrQmpFO0lBRUQ7Ozs7OztPQU1HO0lBQ0csVUFBVSxDQUFDLE1BQU0sRUFBRSxnQkFBZ0IsR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBZ0IzRDtJQUVEOztPQUVHO0lBQ0gsSUFBSSxNQUFNLElBQUksTUFBTSxDQUVuQjtJQUVEOzs7T0FHRztJQUNILEtBQUssU0FHSjtJQUVEOztPQUVHO0lBQ0csSUFBSSxrQkFHVDtZQUthLGtCQUFrQjtDQVNqQyJ9

package/dest/slashing_protection_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slashing_protection_service.d.ts","sourceRoot":"","sources":["../src/slashing_protection_service.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,gBAAgB,EAAc,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEvH,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEvF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAAyB;IAQlC,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,qBAAqB,CAAiB;IAE9C,YACmB,EAAE,EAAE,0BAA0B,EAC9B,MAAM,EAAE,wBAAwB,EAWlD;IAED;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DlE;IAED;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBjE;IAED;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgB3D;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,KAAK,SAGJ;IAED;;OAEG;IACG,IAAI,kBAGT;YAKa,kBAAkB;CASjC"}

package/dest/slashing_protection_service.js

@@ -0,0 +1,184 @@
+/**
+ * Slashing Protection Service
+ *
+ * Provides distributed locking and slashing protection for validator duties.
+ * Uses an external database to coordinate across multiple validator nodes.
+ */ import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+import { sleep } from '@aztec/foundation/sleep';
+import { DutyStatus } from './db/types.js';
+import { DutyAlreadySignedError, SlashingProtectionError } from './errors.js';
+/**
+ * Slashing Protection Service
+ *
+ * This service ensures that a validator only signs one block/attestation per slot,
+ * even when running multiple redundant nodes (HA setup).
+ *
+ * All nodes in the HA setup try to sign - the first one wins, others get
+ * DutyAlreadySignedError (normal) or SlashingProtectionError (if different data).
+ *
+ * Flow:
+ * 1. checkAndRecord() - Atomically try to acquire lock via tryInsertOrGetExisting
+ * 2. Caller performs the signing operation
+ * 3. recordSuccess() - Update to 'signed' status with signature
+ *    OR deleteDuty() - Delete the record to allow retry
+ */ export class SlashingProtectionService {
+    db;
+    config;
+    log;
+    pollingIntervalMs;
+    signingTimeoutMs;
+    cleanupRunningPromise;
+    constructor(db, config){
+        this.db = db;
+        this.config = config;
+        this.log = createLogger('slashing-protection');
+        this.pollingIntervalMs = config.pollingIntervalMs;
+        this.signingTimeoutMs = config.signingTimeoutMs;
+        this.cleanupRunningPromise = new RunningPromise(this.cleanupStuckDuties.bind(this), this.log, this.config.maxStuckDutiesAgeMs);
+    }
+    /**
+   * Check if a duty can be performed and acquire the lock if so.
+   *
+   * This method uses an atomic insert-or-get operation.
+   * It will:
+   * 1. Try to insert a new record with 'signing' status
+   * 2. If insert succeeds, we acquired the lock - return the lockToken
+   * 3. If a record exists, handle based on status:
+   *    - SIGNED: Throw appropriate error (already signed or slashing protection)
+   *    - FAILED: Delete the failed record
+   *    - SIGNING: Wait and poll until status changes, then handle result
+   *
+   * @returns The lockToken that must be used for recordSuccess/deleteDuty
+   * @throws DutyAlreadySignedError if the duty was already completed
+   * @throws SlashingProtectionError if attempting to sign different data for same slot/duty
+   */ async checkAndRecord(params) {
+        const { validatorAddress, slot, dutyType, messageHash, nodeId } = params;
+        const startTime = Date.now();
+        this.log.debug(`Checking duty: ${dutyType} for slot ${slot}`, {
+            validatorAddress: validatorAddress.toString(),
+            nodeId
+        });
+        while(true){
+            // insert if not present, get existing if present
+            const { isNew, record } = await this.db.tryInsertOrGetExisting(params);
+            if (isNew) {
+                // We successfully acquired the lock
+                this.log.info(`Acquired lock for duty ${dutyType} at slot ${slot}`, {
+                    validatorAddress: validatorAddress.toString(),
+                    nodeId
+                });
+                return record.lockToken;
+            }
+            // Record already exists - handle based on status
+            if (record.status === DutyStatus.SIGNED) {
+                // Duty was already signed - check if same or different data
+                if (record.messageHash !== messageHash) {
+                    this.log.verbose(`Slashing protection triggered for duty ${dutyType} at slot ${slot}`, {
+                        validatorAddress: validatorAddress.toString(),
+                        existingMessageHash: record.messageHash,
+                        attemptedMessageHash: messageHash,
+                        existingNodeId: record.nodeId,
+                        attemptingNodeId: nodeId
+                    });
+                    throw new SlashingProtectionError(slot, dutyType, record.messageHash, messageHash);
+                }
+                throw new DutyAlreadySignedError(slot, dutyType, record.nodeId);
+            } else if (record.status === DutyStatus.SIGNING) {
+                // Another node is currently signing - check for timeout
+                if (Date.now() - startTime > this.signingTimeoutMs) {
+                    this.log.warn(`Timeout waiting for signing to complete for duty ${dutyType} at slot ${slot}`, {
+                        validatorAddress: validatorAddress.toString(),
+                        timeoutMs: this.signingTimeoutMs,
+                        signingNodeId: record.nodeId
+                    });
+                    throw new DutyAlreadySignedError(slot, dutyType, 'unknown (timeout)');
+                }
+                // Wait and poll
+                this.log.debug(`Waiting for signing to complete for duty ${dutyType} at slot ${slot}`, {
+                    validatorAddress: validatorAddress.toString(),
+                    signingNodeId: record.nodeId
+                });
+                await sleep(this.pollingIntervalMs);
+            // Loop continues - next iteration will check status again
+            } else {
+                throw new Error(`Unknown duty status: ${record.status}`);
+            }
+        }
+    }
+    /**
+   * Record a successful signing operation.
+   * Updates the duty status to 'signed' and stores 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
+   */ async recordSuccess(params) {
+        const { validatorAddress, slot, dutyType, signature, nodeId, lockToken } = params;
+        const success = await this.db.updateDutySigned(validatorAddress, slot, dutyType, signature.toString(), lockToken);
+        if (success) {
+            this.log.info(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
+                validatorAddress: validatorAddress.toString(),
+                nodeId
+            });
+        } else {
+            this.log.warn(`Failed to record successful signing for duty ${dutyType} at slot ${slot}: invalid token`, {
+                validatorAddress: validatorAddress.toString(),
+                nodeId
+            });
+        }
+        return success;
+    }
+    /**
+   * Delete a duty record after a failed signing operation.
+   * Removes the record to allow another node/attempt to retry.
+   * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+   *
+   * @returns true if the delete succeeded, false if token didn't match
+   */ async deleteDuty(params) {
+        const { validatorAddress, slot, dutyType, lockToken } = params;
+        const success = await this.db.deleteDuty(validatorAddress, slot, dutyType, lockToken);
+        if (success) {
+            this.log.info(`Deleted duty ${dutyType} at slot ${slot} to allow retry`, {
+                validatorAddress: validatorAddress.toString()
+            });
+        } else {
+            this.log.warn(`Failed to delete duty ${dutyType} at slot ${slot}: invalid token`, {
+                validatorAddress: validatorAddress.toString()
+            });
+        }
+        return success;
+    }
+    /**
+   * Get the node ID for this service
+   */ get nodeId() {
+        return this.config.nodeId;
+    }
+    /**
+   * Start running tasks.
+   * Cleanup runs immediately on start to recover from any previous crashes.
+   */ start() {
+        this.cleanupRunningPromise.start();
+        this.log.info('Slashing protection service started', {
+            nodeId: this.config.nodeId
+        });
+    }
+    /**
+   * Stop the background cleanup task.
+   */ async stop() {
+        await this.cleanupRunningPromise.stop();
+        this.log.info('Slashing protection service stopped', {
+            nodeId: this.config.nodeId
+        });
+    }
+    /**
+   * Cleanup own stuck duties
+   */ async cleanupStuckDuties() {
+        const numDuties = await this.db.cleanupOwnStuckDuties(this.config.nodeId, this.config.maxStuckDutiesAgeMs);
+        if (numDuties > 0) {
+            this.log.info(`Cleaned up ${numDuties} stuck duties`, {
+                nodeId: this.config.nodeId,
+                maxStuckDutiesAgeMs: this.config.maxStuckDutiesAgeMs
+            });
+        }
+    }
+}

package/dest/types.d.ts

@@ -0,0 +1,75 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Pool } from 'pg';
+import type { CreateHASignerConfig, SlashingProtectionConfig } from './config.js';
+import type { CheckAndRecordParams, DeleteDutyParams, DutyIdentifier, DutyType, RecordSuccessParams, ValidatorDutyRecord } from './db/types.js';
+export type { CheckAndRecordParams, CreateHASignerConfig, DeleteDutyParams, DutyIdentifier, RecordSuccessParams, SlashingProtectionConfig, ValidatorDutyRecord, };
+export { DutyStatus, DutyType } from './db/types.js';
+/**
+ * Result of tryInsertOrGetExisting operation
+ */
+export interface TryInsertOrGetResult {
+    /** True if we inserted a new record, false if we got an existing record */
+    isNew: boolean;
+    /** The record (either newly inserted or existing) */
+    record: ValidatorDutyRecord;
+}
+/**
+ * deps for creating an HA signer
+ */
+export interface CreateHASignerDeps {
+    /**
+     * Optional PostgreSQL connection pool
+     * If provided, databaseUrl and poolConfig are ignored
+     */
+    pool?: Pool;
+}
+/**
+ * Context required for slashing protection during signing operations
+ */
+export interface SigningContext {
+    /** Slot number for this duty */
+    slot: bigint;
+    /** Block number for this duty */
+    blockNumber: bigint;
+    /** Type of duty being performed */
+    dutyType: DutyType;
+}
+/**
+ * Database interface for slashing protection operations
+ * This abstraction allows for different database implementations (PostgreSQL, SQLite, etc.)
+ *
+ * The interface is designed around 3 core operations:
+ * 1. tryInsertOrGetExisting - Atomically insert or get existing record (eliminates race conditions)
+ * 2. updateDutySigned - Update to signed status on success
+ * 3. deleteDuty - Delete a duty record on failure
+ */
+export interface SlashingProtectionDatabase {
+    /**
+     * Atomically try to insert a new duty record, or get the existing one if present.
+     *
+     * @returns { isNew: true, record } if we successfully inserted and acquired the lock
+     * @returns { isNew: false, record } if a record already exists (caller should handle based on status)
+     */
+    tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult>;
+    /**
+     * Update a duty to 'signed' status with the signature.
+     * Only succeeds if the lockToken matches (caller must be the one who created the duty).
+     *
+     * @returns true if the update succeeded, false if token didn't match or duty not found
+     */
+    updateDutySigned(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>;
+    /**
+     * Cleanup own stuck duties
+     * @returns the number of duties cleaned up
+     */
+    cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxVQUFVLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQUVoRSxPQUFPLEtBQUssRUFBRSxJQUFJLEVBQUUsTUFBTSxJQUFJLENBQUM7QUFFL0IsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsd0JBQXdCLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDbEYsT0FBTyxLQUFLLEVBQ1Ysb0JBQW9CLEVBQ3BCLGdCQUFnQixFQUNoQixjQUFjLEVBQ2QsUUFBUSxFQUNSLG1CQUFtQixFQUNuQixtQkFBbUIsRUFDcEIsTUFBTSxlQUFlLENBQUM7QUFFdkIsWUFBWSxFQUNWLG9CQUFvQixFQUNwQixvQkFBb0IsRUFDcEIsZ0JBQWdCLEVBQ2hCLGNBQWMsRUFDZCxtQkFBbUIsRUFDbkIsd0JBQXdCLEVBQ3hCLG1CQUFtQixHQUNwQixDQUFDO0FBQ0YsT0FBTyxFQUFFLFVBQVUsRUFBRSxRQUFRLEVBQUUsTUFBTSxlQUFlLENBQUM7QUFFckQ7O0dBRUc7QUFDSCxNQUFNLFdBQVcsb0JBQW9CO0lBQ25DLDJFQUEyRTtJQUMzRSxLQUFLLEVBQUUsT0FBTyxDQUFDO0lBQ2YscURBQXFEO0lBQ3JELE1BQU0sRUFBRSxtQkFBbUIsQ0FBQztDQUM3QjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGtCQUFrQjtJQUNqQzs7O09BR0c7SUFDSCxJQUFJLENBQUMsRUFBRSxJQUFJLENBQUM7Q0FDYjtBQUVEOztHQUVHO0FBQ0gsTUFBTSxXQUFXLGNBQWM7SUFDN0IsZ0NBQWdDO0lBQ2hDLElBQUksRUFBRSxNQUFNLENBQUM7SUFDYixpQ0FBaUM7SUFDakMsV0FBVyxFQUFFLE1BQU0sQ0FBQztJQUNwQixtQ0FBbUM7SUFDbkMsUUFBUSxFQUFFLFFBQVEsQ0FBQztDQUNwQjtBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxXQUFXLDBCQUEwQjtJQUN6Qzs7Ozs7T0FLRztJQUNILHNCQUFzQixDQUFDLE1BQU0sRUFBRSxvQkFBb0IsR0FBRyxPQUFPLENBQUMsb0JBQW9CLENBQUMsQ0FBQztJQUVwRjs7Ozs7T0FLRztJQUNILGdCQUFnQixDQUNkLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsSUFBSSxFQUFFLE1BQU0sRUFDWixRQUFRLEVBQUUsUUFBUSxFQUNsQixTQUFTLEVBQUUsTUFBTSxFQUNqQixTQUFTLEVBQUUsTUFBTSxHQUNoQixPQUFPLENBQUMsT0FBTyxDQUFDLENBQUM7SUFFcEI7Ozs7OztPQU1HO0lBQ0gsVUFBVSxDQUFDLGdCQUFnQixFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLFFBQVEsRUFBRSxRQUFRLEVBQUUsU0FBUyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLENBQUM7SUFFaEg7OztPQUdHO0lBQ0gscUJBQXFCLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxRQUFRLEVBQUUsTUFBTSxHQUFHLE9BQU8sQ0FBQyxNQUFNLENBQUMsQ0FBQztDQUMxRSJ9

package/dest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEhE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE/B,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,GACpB,CAAC;AACF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEpF;;;;;OAKG;IACH,gBAAgB,CACd,gBAAgB,EAAE,UAAU,EAC5B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;;;OAMG;IACH,UAAU,CAAC,gBAAgB,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhH;;;OAGG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1E"}

package/dest/types.js

@@ -0,0 +1 @@
+export { DutyStatus, DutyType } from './db/types.js';

package/dest/validator_ha_signer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Validator High Availability Signer
+ *
+ * Wraps signing operations with distributed locking and slashing protection.
+ * This ensures that even with multiple validator nodes running, only one
+ * node will sign for a given duty (slot + duty type).
+ */
+import type { Buffer32 } from '@aztec/foundation/buffer';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+import type { CreateHASignerConfig } from './config.js';
+import type { SigningContext, SlashingProtectionDatabase } from './types.js';
+/**
+ * Validator High Availability Signer
+ *
+ * Provides signing capabilities with distributed locking for validators
+ * in a high-availability setup.
+ *
+ * Usage:
+ * ```
+ * const signer = new ValidatorHASigner(db, config);
+ *
+ * // Sign with slashing protection
+ * const signature = await signer.signWithProtection(
+ *   validatorAddress,
+ *   messageHash,
+ *   { slot: 100n, blockNumber: 50n, dutyType: 'BLOCK_PROPOSAL' },
+ *   async (root) => localSigner.signMessage(root),
+ * );
+ * ```
+ */
+export declare class ValidatorHASigner {
+    private readonly config;
+    private readonly log;
+    private readonly slashingProtection;
+    constructor(db: SlashingProtectionDatabase, config: CreateHASignerConfig);
+    /**
+     * Sign a message with slashing protection.
+     *
+     * This method:
+     * 1. Acquires a distributed lock for (validator, slot, dutyType)
+     * 2. Calls the provided signing function
+     * 3. Records the result (success or failure)
+     *
+     * @param validatorAddress - The validator's Ethereum address
+     * @param messageHash - The hash to be signed
+     * @param context - The signing context (slot, block number, duty type)
+     * @param signFn - Function that performs the actual signing
+     * @returns The signature
+     *
+     * @throws DutyAlreadySignedError if the duty was already signed (expected in HA)
+     * @throws SlashingProtectionError if attempting to sign different data for same slot (expected in HA)
+     */
+    signWithProtection(validatorAddress: EthAddress, messageHash: Buffer32, context: SigningContext, signFn: (messageHash: Buffer32) => Promise<Signature>): Promise<Signature>;
+    /**
+     * Check if slashing protection is enabled
+     */
+    get isEnabled(): boolean;
+    /**
+     * Get the node ID for this signer
+     */
+    get nodeId(): string;
+    /**
+     * Start the HA signer background tasks (cleanup of stuck duties).
+     * Should be called after construction and before signing operations.
+     */
+    start(): void;
+    /**
+     * Stop the HA signer background tasks.
+     * Should be called during graceful shutdown.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdG9yX2hhX3NpZ25lci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3ZhbGlkYXRvcl9oYV9zaWduZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7OztHQU1HO0FBQ0gsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLEVBQUUsVUFBVSxFQUFFLE1BQU0sK0JBQStCLENBQUM7QUFDaEUsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0saUNBQWlDLENBQUM7QUFHakUsT0FBTyxLQUFLLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFFeEQsT0FBTyxLQUFLLEVBQUUsY0FBYyxFQUFFLDBCQUEwQixFQUFFLE1BQU0sWUFBWSxDQUFDO0FBRTdFOzs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FrQkc7QUFDSCxxQkFBYSxpQkFBaUI7SUFNMUIsT0FBTyxDQUFDLFFBQVEsQ0FBQyxNQUFNO0lBTHpCLE9BQU8sQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFTO0lBQzdCLE9BQU8sQ0FBQyxRQUFRLENBQUMsa0JBQWtCLENBQXdDO0lBRTNFLFlBQ0UsRUFBRSxFQUFFLDBCQUEwQixFQUNiLE1BQU0sRUFBRSxvQkFBb0IsRUFnQjlDO0lBRUQ7Ozs7Ozs7Ozs7Ozs7Ozs7T0FnQkc7SUFDRyxrQkFBa0IsQ0FDdEIsZ0JBQWdCLEVBQUUsVUFBVSxFQUM1QixXQUFXLEVBQUUsUUFBUSxFQUNyQixPQUFPLEVBQUUsY0FBYyxFQUN2QixNQUFNLEVBQUUsQ0FBQyxXQUFXLEVBQUUsUUFBUSxLQUFLLE9BQU8sQ0FBQyxTQUFTLENBQUMsR0FDcEQsT0FBTyxDQUFDLFNBQVMsQ0FBQyxDQW1EcEI7SUFFRDs7T0FFRztJQUNILElBQUksU0FBUyxJQUFJLE9BQU8sQ0FFdkI7SUFFRDs7T0FFRztJQUNILElBQUksTUFBTSxJQUFJLE1BQU0sQ0FFbkI7SUFFRDs7O09BR0c7SUFDSCxLQUFLLFNBRUo7SUFFRDs7O09BR0c7SUFDRyxJQUFJLGtCQUVUO0NBQ0YifQ==

package/dest/validator_ha_signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator_ha_signer.d.ts","sourceRoot":"","sources":["../src/validator_ha_signer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAGjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwC;IAE3E,YACE,EAAE,EAAE,0BAA0B,EACb,MAAM,EAAE,oBAAoB,EAgB9C;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,kBAAkB,CACtB,gBAAgB,EAAE,UAAU,EAC5B,WAAW,EAAE,QAAQ,EACrB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,CAAC,WAAW,EAAE,QAAQ,KAAK,OAAO,CAAC,SAAS,CAAC,GACpD,OAAO,CAAC,SAAS,CAAC,CAmDpB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,KAAK,SAEJ;IAED;;;OAGG;IACG,IAAI,kBAET;CACF"}

package/dest/validator_ha_signer.js

@@ -0,0 +1,131 @@
+/**
+ * Validator High Availability Signer
+ *
+ * Wraps signing operations with distributed locking and slashing protection.
+ * This ensures that even with multiple validator nodes running, only one
+ * node will sign for a given duty (slot + duty type).
+ */ import { createLogger } from '@aztec/foundation/log';
+import { SlashingProtectionService } from './slashing_protection_service.js';
+/**
+ * Validator High Availability Signer
+ *
+ * Provides signing capabilities with distributed locking for validators
+ * in a high-availability setup.
+ *
+ * Usage:
+ * ```
+ * const signer = new ValidatorHASigner(db, config);
+ *
+ * // Sign with slashing protection
+ * const signature = await signer.signWithProtection(
+ *   validatorAddress,
+ *   messageHash,
+ *   { slot: 100n, blockNumber: 50n, dutyType: 'BLOCK_PROPOSAL' },
+ *   async (root) => localSigner.signMessage(root),
+ * );
+ * ```
+ */ export class ValidatorHASigner {
+    config;
+    log;
+    slashingProtection;
+    constructor(db, config){
+        this.config = config;
+        this.log = createLogger('validator-ha-signer');
+        if (!config.enabled) {
+            // this shouldn't happen, the validator should use different signer for non-HA setups
+            throw new Error('Validator HA Signer is not enabled in config');
+        }
+        if (!config.nodeId || config.nodeId === '') {
+            throw new Error('NODE_ID is required for high-availability setups');
+        }
+        this.slashingProtection = new SlashingProtectionService(db, config);
+        this.log.info('Validator HA Signer initialized with slashing protection', {
+            nodeId: config.nodeId
+        });
+    }
+    /**
+   * Sign a message with slashing protection.
+   *
+   * This method:
+   * 1. Acquires a distributed lock for (validator, slot, dutyType)
+   * 2. Calls the provided signing function
+   * 3. Records the result (success or failure)
+   *
+   * @param validatorAddress - The validator's Ethereum address
+   * @param messageHash - The hash to be signed
+   * @param context - The signing context (slot, block number, duty type)
+   * @param signFn - Function that performs the actual signing
+   * @returns The signature
+   *
+   * @throws DutyAlreadySignedError if the duty was already signed (expected in HA)
+   * @throws SlashingProtectionError if attempting to sign different data for same slot (expected in HA)
+   */ async signWithProtection(validatorAddress, messageHash, context, signFn) {
+        // If slashing protection is disabled, just sign directly
+        if (!this.slashingProtection) {
+            this.log.info('Signing without slashing protection enabled', {
+                validatorAddress: validatorAddress.toString(),
+                nodeId: this.config.nodeId,
+                dutyType: context.dutyType,
+                slot: context.slot,
+                blockNumber: context.blockNumber
+            });
+            return await signFn(messageHash);
+        }
+        const { slot, blockNumber, dutyType } = context;
+        // Acquire lock and get the token for ownership verification
+        const lockToken = await this.slashingProtection.checkAndRecord({
+            validatorAddress,
+            slot,
+            blockNumber,
+            dutyType,
+            messageHash: messageHash.toString(),
+            nodeId: this.config.nodeId
+        });
+        // Perform signing
+        let signature;
+        try {
+            signature = await signFn(messageHash);
+        } catch (error) {
+            // Delete duty to allow retry (only succeeds if we own the lock)
+            await this.slashingProtection.deleteDuty({
+                validatorAddress,
+                slot,
+                dutyType,
+                lockToken
+            });
+            throw error;
+        }
+        // Record success (only succeeds if we own the lock)
+        await this.slashingProtection.recordSuccess({
+            validatorAddress,
+            slot,
+            dutyType,
+            signature,
+            nodeId: this.config.nodeId,
+            lockToken
+        });
+        return signature;
+    }
+    /**
+   * Check if slashing protection is enabled
+   */ get isEnabled() {
+        return this.slashingProtection !== undefined;
+    }
+    /**
+   * Get the node ID for this signer
+   */ get nodeId() {
+        return this.config.nodeId;
+    }
+    /**
+   * Start the HA signer background tasks (cleanup of stuck duties).
+   * Should be called after construction and before signing operations.
+   */ start() {
+        this.slashingProtection?.start();
+    }
+    /**
+   * Stop the HA signer background tasks.
+   * Should be called during graceful shutdown.
+   */ async stop() {
+        await this.slashingProtection?.stop();
+    }
+}

package/package.json

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