@aztec/validator-ha-signer 0.0.1-commit.96dac018d → 0.0.1-commit.993d240

package/src/db/types.ts

@@ -1,5 +1,5 @@
-import type { BlockNumber, CheckpointNumber, IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
-import type { EthAddress } from '@aztec/foundation/eth-address';
+import { BlockNumber, CheckpointNumber, type IndexWithinCheckpoint, SlotNumber } from '@aztec/foundation/branded-types';
+import { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
 import { DutyType } from '@aztec/stdlib/ha-signing';
 
@@ -11,6 +11,7 @@ export interface DutyRow {
   validator_address: string;
   slot: string;
   block_number: string;
+  checkpoint_number: string;
   block_index_within_checkpoint: number;
   duty_type: DutyType;
   status: DutyStatus;
@@ -23,6 +24,31 @@ export interface DutyRow {
   error_message: string | null;
 }
 
+/**
+ * Plain-primitive representation of a duty record suitable for serialization
+ * (e.g. msgpackr for LMDB). All domain types are stored as their string/number
+ * equivalents. Timestamps are Unix milliseconds.
+ */
+export interface StoredDutyRecord {
+  rollupAddress: string;
+  validatorAddress: string;
+  slot: string;
+  blockNumber: string;
+  checkpointNumber: string;
+  blockIndexWithinCheckpoint: number;
+  dutyType: DutyType;
+  status: DutyStatus;
+  messageHash: string;
+  signature?: string;
+  nodeId: string;
+  lockToken: string;
+  /** Unix timestamp in milliseconds when signing started */
+  startedAtMs: number;
+  /** Unix timestamp in milliseconds when signing completed */
+  completedAtMs?: number;
+  errorMessage?: string;
+}
+
 /**
  * Row type from INSERT_OR_GET_DUTY query (includes is_new flag)
  */
@@ -42,7 +68,8 @@ export enum DutyStatus {
 export { DutyType };
 
 /**
- * Record of a validator duty in the database
+ * Rich representation of a validator duty, with branded types and Date objects.
+ * This is the common output type returned by all SlashingProtectionDatabase implementations.
  */
 export interface ValidatorDutyRecord {
   /** Ethereum address of the rollup contract */
@@ -51,8 +78,10 @@ export interface ValidatorDutyRecord {
   validatorAddress: EthAddress;
   /** Slot number for this duty */
   slot: SlotNumber;
-  /** Block number for this duty */
+  /** Block number for this duty (0 for non-block-proposal duties) */
   blockNumber: BlockNumber;
+  /** Checkpoint number for this duty (0 for attestation and vote duties) */
+  checkpointNumber: CheckpointNumber;
   /** Block index within checkpoint (0, 1, 2... for block proposals, -1 for other duty types) */
   blockIndexWithinCheckpoint: number;
   /** Type of duty being performed */
@@ -75,6 +104,32 @@ export interface ValidatorDutyRecord {
   errorMessage?: string;
 }
 
+/**
+ * Convert a {@link StoredDutyRecord} (plain-primitive wire format) to a
+ * {@link ValidatorDutyRecord} (rich domain type).
+ *
+ * Shared by LMDB and any future non-Postgres backend implementations.
+ */
+export function recordFromFields(stored: StoredDutyRecord): ValidatorDutyRecord {
+  return {
+    rollupAddress: EthAddress.fromString(stored.rollupAddress),
+    validatorAddress: EthAddress.fromString(stored.validatorAddress),
+    slot: SlotNumber.fromString(stored.slot),
+    blockNumber: BlockNumber.fromString(stored.blockNumber),
+    checkpointNumber: CheckpointNumber.fromString(stored.checkpointNumber),
+    blockIndexWithinCheckpoint: stored.blockIndexWithinCheckpoint,
+    dutyType: stored.dutyType,
+    status: stored.status,
+    messageHash: stored.messageHash,
+    signature: stored.signature,
+    nodeId: stored.nodeId,
+    lockToken: stored.lockToken,
+    startedAt: new Date(stored.startedAtMs),
+    completedAt: stored.completedAtMs !== undefined ? new Date(stored.completedAtMs) : undefined,
+    errorMessage: stored.errorMessage,
+  };
+}
+
 /**
  * Duty identifier for block proposals.
  * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
@@ -153,8 +208,10 @@ export function getBlockIndexFromDutyIdentifier(duty: DutyIdentifier): number {
  * Additional parameters for checking and recording a new duty
  */
 interface CheckAndRecordExtra {
-  /** Block number for this duty */
-  blockNumber: BlockNumber | CheckpointNumber;
+  /** Block number for this duty (0 for non-block-proposal duties) */
+  blockNumber: BlockNumber;
+  /** Checkpoint number for this duty (0 for attestation and vote duties) */
+  checkpointNumber: CheckpointNumber;
   /** The signing root (hash) for this duty */
   messageHash: string;
   /** Identifier for the node that acquired the lock */

package/src/factory.ts

@@ -2,14 +2,16 @@
  * Factory functions for creating validator HA signers
  */
 import { DateProvider } from '@aztec/foundation/timer';
-import type { ValidatorHASignerConfig } from '@aztec/stdlib/ha-signing';
+import { createStore } from '@aztec/kv-store/lmdb-v2';
+import type { LocalSignerConfig, ValidatorHASignerConfig } from '@aztec/stdlib/ha-signing';
 import { getTelemetryClient } from '@aztec/telemetry-client';
 
 import { Pool } from 'pg';
 
+import { LmdbSlashingProtectionDatabase, migrateLmdbSlashingProtectionDatabase } from './db/lmdb.js';
 import { PostgresSlashingProtectionDatabase } from './db/postgres.js';
 import { HASignerMetrics } from './metrics.js';
-import type { CreateHASignerDeps, SlashingProtectionDatabase } from './types.js';
+import type { CreateHASignerDeps, CreateLocalSignerWithProtectionDeps, SlashingProtectionDatabase } from './types.js';
 import { ValidatorHASigner } from './validator_ha_signer.js';
 
 /**
@@ -27,7 +29,6 @@ import { ValidatorHASigner } from './validator_ha_signer.js';
  * ```typescript
  * const { signer, db } = await createHASigner({
  *   databaseUrl: process.env.DATABASE_URL,
- *   haSigningEnabled: true,
  *   nodeId: 'validator-node-1',
  *   pollingIntervalMs: 100,
  *   signingTimeoutMs: 3000,
@@ -56,7 +57,8 @@ export async function createHASigner(
   const { databaseUrl, poolMaxCount, poolMinCount, poolIdleTimeoutMs, poolConnectionTimeoutMs, ...signerConfig } =
     config;
 
-  if (!databaseUrl) {
+  const databaseUrlValue = databaseUrl?.getValue();
+  if (!databaseUrlValue) {
     throw new Error('databaseUrl is required for createHASigner');
   }
 
@@ -67,7 +69,7 @@ export async function createHASigner(
   let pool: Pool;
   if (!deps?.pool) {
     pool = new Pool({
-      connectionString: databaseUrl,
+      connectionString: databaseUrlValue,
       max: poolMaxCount ?? 10,
       min: poolMinCount ?? 0,
       idleTimeoutMillis: poolIdleTimeoutMs ?? 10_000,
@@ -87,7 +89,99 @@ export async function createHASigner(
   const metrics = new HASignerMetrics(telemetryClient, signerConfig.nodeId);
 
   // Create signer
-  const signer = new ValidatorHASigner(db, { ...signerConfig, databaseUrl }, { metrics, dateProvider });
+  const signer = new ValidatorHASigner(db, signerConfig, { metrics, dateProvider });
 
   return { signer, db };
 }
+
+/**
+ * Create a local (single-node) signing protection signer backed by LMDB.
+ *
+ * This provides double-signing protection for nodes that are NOT running in a
+ * high-availability (multi-node) setup. It prevents a proposer from sending two
+ * proposals for the same slot if the node crashes and restarts mid-proposal.
+ *
+ * When `config.dataDirectory` is set, the protection database is persisted to disk
+ * and survives crashes/restarts. When unset, an ephemeral in-memory store is
+ * used which protects within a single run but not across restarts.
+ *
+ * @param config - Local signer config
+ * @param deps - Optional dependencies (telemetry, date provider).
+ * @returns An object containing the signer and database instances.
+ */
+export async function createLocalSignerWithProtection(
+  config: LocalSignerConfig,
+  deps?: CreateLocalSignerWithProtectionDeps,
+): Promise<{
+  signer: ValidatorHASigner;
+  db: SlashingProtectionDatabase;
+}> {
+  const telemetryClient = deps?.telemetryClient ?? getTelemetryClient();
+  const dateProvider = deps?.dateProvider ?? new DateProvider();
+
+  const kvStore = await createStore(
+    'signing-protection',
+    LmdbSlashingProtectionDatabase.SCHEMA_VERSION,
+    {
+      dataDirectory: config.dataDirectory,
+      dataStoreMapSizeKb: config.signingProtectionMapSizeKb ?? config.dataStoreMapSizeKb,
+      rollupAddress: config.rollupAddress,
+    },
+    undefined,
+    {
+      onUpgrade: (dataDirectory, currentVersion, latestVersion) =>
+        migrateLmdbSlashingProtectionDatabase(
+          dataDirectory,
+          currentVersion,
+          latestVersion,
+          config.signingProtectionMapSizeKb ?? config.dataStoreMapSizeKb,
+        ),
+      schemaVersionMismatchPolicy: 'throw',
+    },
+  );
+
+  const db = new LmdbSlashingProtectionDatabase(kvStore, dateProvider);
+
+  const signerConfig = {
+    ...config,
+    nodeId: config.nodeId || 'local',
+  };
+
+  const metrics = new HASignerMetrics(telemetryClient, signerConfig.nodeId, 'LocalSigningProtectionMetrics');
+
+  const signer = new ValidatorHASigner(db, signerConfig, { metrics, dateProvider });
+
+  return { signer, db };
+}
+
+/**
+ * Create an in-memory LMDB-backed SlashingProtectionDatabase that can be shared across
+ * multiple validator nodes in the same process. Used for testing HA setups.
+ */
+export async function createSharedSlashingProtectionDb(
+  dateProvider: DateProvider = new DateProvider(),
+): Promise<SlashingProtectionDatabase> {
+  const kvStore = await createStore('shared-signing-protection', LmdbSlashingProtectionDatabase.SCHEMA_VERSION, {
+    dataStoreMapSizeKb: 1024 * 1024,
+  });
+  return new LmdbSlashingProtectionDatabase(kvStore, dateProvider);
+}
+
+/**
+ * Create a ValidatorHASigner backed by a pre-existing SlashingProtectionDatabase.
+ * Used for testing HA setups where multiple nodes share the same protection database.
+ */
+export function createSignerFromSharedDb(
+  db: SlashingProtectionDatabase,
+  config: Pick<
+    ValidatorHASignerConfig,
+    'nodeId' | 'pollingIntervalMs' | 'signingTimeoutMs' | 'maxStuckDutiesAgeMs' | 'rollupAddress'
+  >,
+  deps?: CreateLocalSignerWithProtectionDeps,
+): { signer: ValidatorHASigner; db: SlashingProtectionDatabase } {
+  const telemetryClient = deps?.telemetryClient ?? getTelemetryClient();
+  const dateProvider = deps?.dateProvider ?? new DateProvider();
+  const metrics = new HASignerMetrics(telemetryClient, config.nodeId, 'SharedSigningProtectionMetrics');
+  const signer = new ValidatorHASigner(db, config, { metrics, dateProvider });
+  return { signer, db };
+}

package/src/slashing_protection_service.ts

@@ -8,7 +8,7 @@ import { type Logger, createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/promise';
 import { sleep } from '@aztec/foundation/sleep';
 import type { DateProvider } from '@aztec/foundation/timer';
-import type { ValidatorHASignerConfig } from '@aztec/stdlib/ha-signing';
+import type { BaseSignerConfig } from '@aztec/stdlib/ha-signing';
 
 import {
   type CheckAndRecordParams,
@@ -55,7 +55,7 @@ export class SlashingProtectionService {
 
   constructor(
     private readonly db: SlashingProtectionDatabase,
-    private readonly config: ValidatorHASignerConfig,
+    private readonly config: BaseSignerConfig,
     deps: SlashingProtectionServiceDeps,
   ) {
     this.log = createLogger('slashing-protection');
@@ -99,7 +99,7 @@ export class SlashingProtectionService {
 
       if (isNew) {
         // We successfully acquired the lock
-        this.log.info(`Acquired lock for duty ${dutyType} at slot ${slot}`, {
+        this.log.verbose(`Acquired lock for duty ${dutyType} at slot ${slot}`, {
           validatorAddress: validatorAddress.toString(),
           nodeId,
         });
@@ -177,7 +177,7 @@ export class SlashingProtectionService {
     );
 
     if (success) {
-      this.log.info(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
+      this.log.verbose(`Recorded successful signing for duty ${dutyType} at slot ${slot}`, {
         validatorAddress: validatorAddress.toString(),
         nodeId,
       });
@@ -241,10 +241,10 @@ export class SlashingProtectionService {
    */
   async start() {
     // One-time cleanup at startup: remove duties from previous rollup versions
-    const numOutdatedRollupDuties = await this.db.cleanupOutdatedRollupDuties(this.config.l1Contracts.rollupAddress);
+    const numOutdatedRollupDuties = await this.db.cleanupOutdatedRollupDuties(this.config.rollupAddress);
     if (numOutdatedRollupDuties > 0) {
       this.log.info(`Cleaned up ${numOutdatedRollupDuties} duties with outdated rollup address at startup`, {
-        currentRollupAddress: this.config.l1Contracts.rollupAddress.toString(),
+        currentRollupAddress: this.config.rollupAddress.toString(),
       });
       this.metrics.recordCleanup('outdated_rollup', numOutdatedRollupDuties);
     }

package/src/types.ts

@@ -2,11 +2,14 @@ import { SlotNumber } from '@aztec/foundation/branded-types';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { DateProvider } from '@aztec/foundation/timer';
 import {
+  type AttestationSigningContext,
+  type CheckpointProposalSigningContext,
   DutyType,
   type HAProtectedSigningContext,
   type SigningContext,
   type ValidatorHASignerConfig,
   getBlockNumberFromSigningContext as getBlockNumberFromSigningContextFromStdlib,
+  getCheckpointNumberFromSigningContext as getCheckpointNumberFromSigningContextFromStdlib,
   isHAProtectedContext,
 } from '@aztec/stdlib/ha-signing';
 import type { TelemetryClient } from '@aztec/telemetry-client';
@@ -25,8 +28,10 @@ import type {
 } from './db/types.js';
 
 export type {
+  AttestationSigningContext,
   BlockProposalDutyIdentifier,
   CheckAndRecordParams,
+  CheckpointProposalSigningContext,
   DeleteDutyParams,
   DutyIdentifier,
   DutyRow,
@@ -40,6 +45,7 @@ export type {
 export { DutyStatus, DutyType, getBlockIndexFromDutyIdentifier, normalizeBlockIndex } from './db/types.js';
 export { isHAProtectedContext };
 export { getBlockNumberFromSigningContextFromStdlib as getBlockNumberFromSigningContext };
+export { getCheckpointNumberFromSigningContextFromStdlib as getCheckpointNumberFromSigningContext };
 
 /**
  * Result of tryInsertOrGetExisting operation
@@ -70,6 +76,11 @@ export interface CreateHASignerDeps {
   dateProvider?: DateProvider;
 }
 
+/**
+ * deps for creating a local signing protection signer
+ */
+export type CreateLocalSignerWithProtectionDeps = Omit<CreateHASignerDeps, 'pool'>;
+
 /**
  * Database interface for slashing protection operations
  * This abstraction allows for different database implementations (PostgreSQL, SQLite, etc.)

package/src/validator_ha_signer.ts

@@ -11,10 +11,11 @@ import type { Signature } from '@aztec/foundation/eth-signature';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 import type { DateProvider } from '@aztec/foundation/timer';
 import {
+  type BaseSignerConfig,
   DutyType,
   type HAProtectedSigningContext,
-  type ValidatorHASignerConfig,
   getBlockNumberFromSigningContext,
+  getCheckpointNumberFromSigningContext,
 } from '@aztec/stdlib/ha-signing';
 
 import type { DutyIdentifier } from './db/types.js';
@@ -56,7 +57,7 @@ export class ValidatorHASigner {
 
   constructor(
     db: SlashingProtectionDatabase,
-    private readonly config: ValidatorHASignerConfig,
+    private readonly config: BaseSignerConfig,
     deps: ValidatorHASignerDeps,
   ) {
     this.log = createLogger('validator-ha-signer');
@@ -64,15 +65,10 @@ export class ValidatorHASigner {
     this.metrics = deps.metrics;
     this.dateProvider = deps.dateProvider;
 
-    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.rollupAddress = config.rollupAddress;
     this.slashingProtection = new SlashingProtectionService(db, config, {
       metrics: deps.metrics,
       dateProvider: deps.dateProvider,
@@ -130,9 +126,11 @@ export class ValidatorHASigner {
     // Acquire lock and get the token for ownership verification
     // DutyAlreadySignedError and SlashingProtectionError may be thrown here and are recorded in the service
     const blockNumber = getBlockNumberFromSigningContext(context);
+    const checkpointNumber = getCheckpointNumberFromSigningContext(context);
     const lockToken = await this.slashingProtection.checkAndRecord({
       ...dutyIdentifier,
       blockNumber,
+      checkpointNumber,
       messageHash: messageHash.toString(),
       nodeId: this.config.nodeId,
     });