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

package/dest/types.d.ts

@@ -0,0 +1,152 @@
+import { BlockNumber, type CheckpointNumber, type IndexWithinCheckpoint, type SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Pool } from 'pg';
+import type { ValidatorHASignerConfig } from './config.js';
+import { type BlockProposalDutyIdentifier, type CheckAndRecordParams, type DeleteDutyParams, type DutyIdentifier, type DutyRow, DutyType, type OtherDutyIdentifier, type RecordSuccessParams, type ValidatorDutyRecord } from './db/types.js';
+export type { BlockProposalDutyIdentifier, CheckAndRecordParams, DeleteDutyParams, DutyIdentifier, DutyRow, OtherDutyIdentifier, RecordSuccessParams, ValidatorDutyRecord, ValidatorHASignerConfig, };
+export { DutyStatus, DutyType, getBlockIndexFromDutyIdentifier, normalizeBlockIndex } 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;
+}
+/**
+ * Base context for signing operations
+ */
+interface BaseSigningContext {
+    /** Slot number for this duty */
+    slot: SlotNumber;
+    /**
+     * Block or checkpoint number for this duty.
+     * For block proposals, this is the block number.
+     * For checkpoint proposals, this is the checkpoint number.
+     */
+    blockNumber: BlockNumber | CheckpointNumber;
+}
+/**
+ * Signing context for block proposals.
+ * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
+ */
+export interface BlockProposalSigningContext extends BaseSigningContext {
+    /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+    blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+    dutyType: DutyType.BLOCK_PROPOSAL;
+}
+/**
+ * Signing context for non-block-proposal duties that require HA protection.
+ * blockIndexWithinCheckpoint is not applicable (internally always -1).
+ */
+export interface OtherSigningContext extends BaseSigningContext {
+    dutyType: DutyType.CHECKPOINT_PROPOSAL | DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ * blockNumber is not applicable (internally always 0).
+ */
+export interface VoteSigningContext {
+    slot: SlotNumber;
+    dutyType: DutyType.GOVERNANCE_VOTE | DutyType.SLASHING_VOTE;
+}
+/**
+ * Signing context for duties which don't require slot/blockNumber
+ * as they don't need HA protection (AUTH_REQUEST, TXS).
+ */
+export interface NoHAProtectionSigningContext {
+    dutyType: DutyType.AUTH_REQUEST | DutyType.TXS;
+}
+/**
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext = BlockProposalSigningContext | OtherSigningContext | VoteSigningContext;
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */
+export declare function isHAProtectedContext(context: SigningContext): context is HAProtectedSigningContext;
+/**
+ * Gets the block number from a signing context.
+ * - Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE): returns BlockNumber(0)
+ * - Other duties: returns the blockNumber from the context
+ */
+export declare function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber | CheckpointNumber;
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ * - Vote duties only need slot (blockNumber is internally 0)
+ * - AUTH_REQUEST and TXS duties don't need slot/blockNumber (no HA protection needed)
+ */
+export type SigningContext = HAProtectedSigningContext | NoHAProtectionSigningContext;
+/**
+ * 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(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>;
+    /**
+     * 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.
+     * @returns the number of duties cleaned up
+     */
+    cleanupOldDuties(maxAgeMs: number): Promise<number>;
+    /**
+     * Close the database connection.
+     * Should be called during graceful shutdown.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsV0FBVyxFQUNYLEtBQUssZ0JBQWdCLEVBQ3JCLEtBQUsscUJBQXFCLEVBQzFCLEtBQUssVUFBVSxFQUNoQixNQUFNLGlDQUFpQyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxFQUFFLFVBQVUsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBRWhFLE9BQU8sS0FBSyxFQUFFLElBQUksRUFBRSxNQUFNLElBQUksQ0FBQztBQUUvQixPQUFPLEtBQUssRUFBRSx1QkFBdUIsRUFBRSxNQUFNLGFBQWEsQ0FBQztBQUMzRCxPQUFPLEVBQ0wsS0FBSywyQkFBMkIsRUFDaEMsS0FBSyxvQkFBb0IsRUFDekIsS0FBSyxnQkFBZ0IsRUFDckIsS0FBSyxjQUFjLEVBQ25CLEtBQUssT0FBTyxFQUNaLFFBQVEsRUFDUixLQUFLLG1CQUFtQixFQUN4QixLQUFLLG1CQUFtQixFQUN4QixLQUFLLG1CQUFtQixFQUN6QixNQUFNLGVBQWUsQ0FBQztBQUV2QixZQUFZLEVBQ1YsMkJBQTJCLEVBQzNCLG9CQUFvQixFQUNwQixnQkFBZ0IsRUFDaEIsY0FBYyxFQUNkLE9BQU8sRUFDUCxtQkFBbUIsRUFDbkIsbUJBQW1CLEVBQ25CLG1CQUFtQixFQUNuQix1QkFBdUIsR0FDeEIsQ0FBQztBQUNGLE9BQU8sRUFBRSxVQUFVLEVBQUUsUUFBUSxFQUFFLCtCQUErQixFQUFFLG1CQUFtQixFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTNHOztHQUVHO0FBQ0gsTUFBTSxXQUFXLG9CQUFvQjtJQUNuQywyRUFBMkU7SUFDM0UsS0FBSyxFQUFFLE9BQU8sQ0FBQztJQUNmLHFEQUFxRDtJQUNyRCxNQUFNLEVBQUUsbUJBQW1CLENBQUM7Q0FDN0I7QUFFRDs7R0FFRztBQUNILE1BQU0sV0FBVyxrQkFBa0I7SUFDakM7OztPQUdHO0lBQ0gsSUFBSSxD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

package/dest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dest/types.js

@@ -0,0 +1,21 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { DutyType } from './db/types.js';
+export { DutyStatus, DutyType, getBlockIndexFromDutyIdentifier, normalizeBlockIndex } from './db/types.js';
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */ export function isHAProtectedContext(context) {
+    return context.dutyType !== DutyType.AUTH_REQUEST && context.dutyType !== DutyType.TXS;
+}
+/**
+ * Gets the block number from a signing context.
+ * - Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE): returns BlockNumber(0)
+ * - Other duties: returns the blockNumber from the context
+ */ export function getBlockNumberFromSigningContext(context) {
+    // Check for duty types that have blockNumber
+    if (context.dutyType === DutyType.BLOCK_PROPOSAL || context.dutyType === DutyType.CHECKPOINT_PROPOSAL || context.dutyType === DutyType.ATTESTATION || context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS) {
+        return context.blockNumber;
+    }
+    // Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE) don't have blockNumber
+    return BlockNumber(0);
+}

package/dest/validator_ha_signer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+import type { ValidatorHASignerConfig } from './config.js';
+import { type HAProtectedSigningContext, type 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;
+    private readonly rollupAddress;
+    constructor(db: SlashingProtectionDatabase, config: ValidatorHASignerConfig);
+    /**
+     * 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 (HA-protected duty types only)
+     * @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: HAProtectedSigningContext, signFn: (messageHash: Buffer32) => Promise<Signature>): Promise<Signature>;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Stop the HA signer background tasks and close database connection.
+     * Should be called during graceful shutdown.
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdG9yX2hhX3NpZ25lci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3ZhbGlkYXRvcl9oYV9zaWduZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7OztHQU1HO0FBQ0gsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBQzNELE9BQU8sS0FBSyxFQUFFLFNBQVMsRUFBRSxNQUFNLGlDQUFpQyxDQUFDO0FBR2pFLE9BQU8sS0FBSyxFQUFFLHVCQUF1QixFQUFFLE1BQU0sYUFBYSxDQUFDO0FBRzNELE9BQU8sRUFDTCxLQUFLLHlCQUF5QixFQUM5QixLQUFLLDBCQUEwQixFQUVoQyxNQUFNLFlBQVksQ0FBQztBQUVwQjs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBa0JHO0FBQ0gscUJBQWEsaUJBQWlCO0lBTzFCLE9BQU8sQ0FBQyxRQUFRLENBQUMsTUFBTTtJQU56QixPQUFPLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBUztJQUM3QixPQUFPLENBQUMsUUFBUSxDQUFDLGtCQUFrQixDQUE0QjtJQUMvRCxPQUFPLENBQUMsUUFBUSxDQUFDLGFBQWEsQ0FBYTtJQUUzQyxZQUNFLEVBQUUsRUFBRSwwQkFBMEIsRUFDYixNQUFNLEVBQUUsdUJBQXVCLEVBa0JqRDtJQUVEOzs7Ozs7Ozs7Ozs7Ozs7O09BZ0JHO0lBQ0csa0JBQWtCLENBQ3RCLGdCQUFnQixFQUFFLFVBQVUsRUFDNUIsV0FBVyxFQUFFLFFBQVEsRUFDckIsT0FBTyxFQUFFLHlCQUF5QixFQUNsQyxNQUFNLEVBQUUsQ0FBQyxXQUFXLEVBQUUsUUFBUSxLQUFLLE9BQU8sQ0FBQyxTQUFTLENBQUMsR0FDcEQsT0FBTyxDQUFDLFNBQVMsQ0FBQyxDQStDcEI7SUFFRDs7T0FFRztJQUNILElBQUksTUFBTSxJQUFJLE1BQU0sQ0FFbkI7SUFFRDs7O09BR0c7SUFDRyxLQUFLLGtCQUVWO0lBRUQ7OztPQUdHO0lBQ0csSUFBSSxrQkFHVDtDQUNGIn0=

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,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAGjE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAEhC,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;IAC/D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAa;IAE3C,YACE,EAAE,EAAE,0BAA0B,EACb,MAAM,EAAE,uBAAuB,EAkBjD;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,kBAAkB,CACtB,gBAAgB,EAAE,UAAU,EAC5B,WAAW,EAAE,QAAQ,EACrB,OAAO,EAAE,yBAAyB,EAClC,MAAM,EAAE,CAAC,WAAW,EAAE,QAAQ,KAAK,OAAO,CAAC,SAAS,CAAC,GACpD,OAAO,CAAC,SAAS,CAAC,CA+CpB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACG,KAAK,kBAEV;IAED;;;OAGG;IACG,IAAI,kBAGT;CACF"}

package/dest/validator_ha_signer.js

@@ -0,0 +1,132 @@
+/**
+ * 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 { DutyType } from './db/types.js';
+import { SlashingProtectionService } from './slashing_protection_service.js';
+import { getBlockNumberFromSigningContext } 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 class ValidatorHASigner {
+    config;
+    log;
+    slashingProtection;
+    rollupAddress;
+    constructor(db, config){
+        this.config = config;
+        this.log = createLogger('validator-ha-signer');
+        if (!config.haSigningEnabled) {
+            // 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.rollupAddress = config.l1Contracts.rollupAddress;
+        this.slashingProtection = new SlashingProtectionService(db, config);
+        this.log.info('Validator HA Signer initialized with slashing protection', {
+            nodeId: config.nodeId,
+            rollupAddress: this.rollupAddress.toString()
+        });
+    }
+    /**
+   * 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 (HA-protected duty types only)
+   * @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) {
+        let dutyIdentifier;
+        if (context.dutyType === DutyType.BLOCK_PROPOSAL) {
+            dutyIdentifier = {
+                rollupAddress: this.rollupAddress,
+                validatorAddress,
+                slot: context.slot,
+                blockIndexWithinCheckpoint: context.blockIndexWithinCheckpoint,
+                dutyType: context.dutyType
+            };
+        } else {
+            dutyIdentifier = {
+                rollupAddress: this.rollupAddress,
+                validatorAddress,
+                slot: context.slot,
+                dutyType: context.dutyType
+            };
+        }
+        // Acquire lock and get the token for ownership verification
+        const blockNumber = getBlockNumberFromSigningContext(context);
+        const lockToken = await this.slashingProtection.checkAndRecord({
+            ...dutyIdentifier,
+            blockNumber,
+            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({
+                ...dutyIdentifier,
+                lockToken
+            });
+            throw error;
+        }
+        // Record success (only succeeds if we own the lock)
+        await this.slashingProtection.recordSuccess({
+            ...dutyIdentifier,
+            signature,
+            nodeId: this.config.nodeId,
+            lockToken
+        });
+        return signature;
+    }
+    /**
+   * 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.
+   */ async start() {
+        await this.slashingProtection.start();
+    }
+    /**
+   * Stop the HA signer background tasks and close database connection.
+   * Should be called during graceful shutdown.
+   */ async stop() {
+        await this.slashingProtection.stop();
+        await this.slashingProtection.close();
+    }
+}

package/package.json

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

package/src/config.ts

@@ -0,0 +1,149 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+} from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+/**
+ * Configuration for the Validator HA Signer
+ *
+ * This config is used for distributed locking and slashing protection
+ * when running multiple validator nodes in a high-availability setup.
+ */
+export interface ValidatorHASignerConfig {
+  /** Whether HA signing / slashing protection is enabled */
+  haSigningEnabled: boolean;
+  /** 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 const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig> = {
+  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: string) => 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: ValidatorHASignerConfig = getDefaultConfig(
+  validatorHASignerConfigMappings,
+);
+
+/**
+ * Returns the validator HA signer configuration from environment variables.
+ * Note: If an environment variable is not set, the default value is used.
+ * @returns The validator HA signer configuration.
+ */
+export function getConfigEnvVars(): ValidatorHASignerConfig {
+  return getConfigFromMappings<ValidatorHASignerConfig>(validatorHASignerConfigMappings);
+}
+
+export const ValidatorHASignerConfigSchema = z.object({
+  haSigningEnabled: z.boolean(),
+  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(),
+}) satisfies ZodFor<ValidatorHASignerConfig>;

package/src/db/index.ts

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