@aztec/validator-ha-signer 0.0.1-commit.85d7d01 → 0.0.1-commit.8655d4a

package/dest/validator_ha_signer.js

@@ -5,7 +5,7 @@
  * 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, getBlockNumberFromSigningContext } from '@aztec/stdlib/ha-signing';
+import { DutyType, getBlockNumberFromSigningContext, getCheckpointNumberFromSigningContext } from '@aztec/stdlib/ha-signing';
 import { SlashingProtectionService } from './slashing_protection_service.js';
 /**
  * Validator High Availability Signer
@@ -37,14 +37,10 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
         this.log = createLogger('validator-ha-signer');
         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
@@ -93,9 +89,11 @@ import { SlashingProtectionService } from './slashing_protection_service.js';
         // 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
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/validator-ha-signer",
-  "version": "0.0.1-commit.85d7d01",
+  "version": "0.0.1-commit.8655d4a",
   "type": "module",
   "exports": {
     "./db": "./dest/db/index.js",
@@ -11,7 +11,8 @@
     "./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"
+    "./test": "./dest/test/pglite_pool.js",
+    "./db/lmdb": "./dest/db/lmdb.js"
   },
   "typedocOptions": {
     "entryPoints": [
@@ -74,14 +75,15 @@
     ]
   },
   "dependencies": {
-    "@aztec/ethereum": "0.0.1-commit.85d7d01",
-    "@aztec/foundation": "0.0.1-commit.85d7d01",
-    "@aztec/stdlib": "0.0.1-commit.85d7d01",
-    "@aztec/telemetry-client": "0.0.1-commit.85d7d01",
+    "@aztec/ethereum": "0.0.1-commit.8655d4a",
+    "@aztec/foundation": "0.0.1-commit.8655d4a",
+    "@aztec/kv-store": "0.0.1-commit.8655d4a",
+    "@aztec/stdlib": "0.0.1-commit.8655d4a",
+    "@aztec/telemetry-client": "0.0.1-commit.8655d4a",
     "node-pg-migrate": "^8.0.4",
     "pg": "^8.11.3",
     "tslib": "^2.4.0",
-    "zod": "^3.23.8"
+    "zod": "^4"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.3.14",

package/src/db/index.ts

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

package/src/db/lmdb.ts

@@ -0,0 +1,308 @@
+/**
+ * LMDB implementation of SlashingProtectionDatabase
+ *
+ * Provides local (single-node) double-signing protection using LMDB as the backend.
+ * Suitable for nodes that do NOT run in a high-availability multi-node setup.
+ *
+ * The LMDB store is single-writer, making setIfNotExists inherently atomic.
+ * This means we get crash-restart protection without needing an external database.
+ */
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { DateProvider } from '@aztec/foundation/timer';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec/kv-store';
+import { openStoreAt } from '@aztec/kv-store/lmdb-v2';
+
+import type { SlashingProtectionDatabase, TryInsertOrGetResult } from '../types.js';
+import {
+  type CheckAndRecordParams,
+  DutyStatus,
+  DutyType,
+  type StoredDutyRecord,
+  getBlockIndexFromDutyIdentifier,
+  recordFromFields,
+} from './types.js';
+
+const DUTIES_MAP_NAME = 'signing-protection-duties';
+const LEGACY_CHECKPOINT_NUMBER = '0';
+
+type StoredDutyRecordV1 = Omit<StoredDutyRecord, 'checkpointNumber'> & { checkpointNumber?: undefined };
+type MigratableStoredDutyRecord = StoredDutyRecord | StoredDutyRecordV1;
+
+function needsCheckpointNumberMigration(record: MigratableStoredDutyRecord): record is StoredDutyRecordV1 {
+  return record.checkpointNumber === undefined;
+}
+
+/**
+ * Migrates local slashing-protection duties from schema 1 to schema 2.
+ */
+export async function migrateLmdbSlashingProtectionDatabase(
+  dataDirectory: string,
+  currentVersion: number,
+  latestVersion: number,
+  dbMapSizeKb?: number,
+): Promise<void> {
+  if (currentVersion !== 1 || latestVersion !== LmdbSlashingProtectionDatabase.SCHEMA_VERSION) {
+    throw new Error(`Unsupported LMDB slashing-protection migration ${currentVersion} -> ${latestVersion}`);
+  }
+
+  const store = await openStoreAt(dataDirectory, dbMapSizeKb);
+  try {
+    const duties = store.openMap<string, MigratableStoredDutyRecord>(DUTIES_MAP_NAME);
+    const migratedRecords: { key: string; value: StoredDutyRecord }[] = [];
+
+    for await (const [key, record] of duties.entriesAsync()) {
+      if (needsCheckpointNumberMigration(record)) {
+        migratedRecords.push({ key, value: { ...record, checkpointNumber: LEGACY_CHECKPOINT_NUMBER } });
+      }
+    }
+
+    if (migratedRecords.length > 0) {
+      await duties.setMany(migratedRecords);
+    }
+  } finally {
+    await store.close();
+  }
+}
+
+function dutyKey(
+  rollupAddress: string,
+  validatorAddress: string,
+  slot: string,
+  dutyType: string,
+  blockIndexWithinCheckpoint: number,
+): string {
+  return `${rollupAddress}:${validatorAddress}:${slot}:${dutyType}:${blockIndexWithinCheckpoint}`;
+}
+
+/**
+ * LMDB-backed implementation of SlashingProtectionDatabase.
+ *
+ * Provides single-node double-signing protection that survives crashes and restarts.
+ * Does not provide cross-node coordination (that requires the PostgreSQL implementation).
+ */
+export class LmdbSlashingProtectionDatabase implements SlashingProtectionDatabase {
+  public static readonly SCHEMA_VERSION = 2;
+
+  private readonly duties: AztecAsyncMap<string, StoredDutyRecord>;
+  private readonly log: Logger;
+
+  constructor(
+    private readonly store: AztecAsyncKVStore,
+    private readonly dateProvider: DateProvider,
+  ) {
+    this.log = createLogger('slashing-protection:lmdb');
+    this.duties = store.openMap<string, StoredDutyRecord>(DUTIES_MAP_NAME);
+  }
+
+  /**
+   * Atomically try to insert a new duty record, or get the existing one if present.
+   *
+   * LMDB is single-writer so the read-then-write inside transactionAsync is naturally atomic.
+   */
+  public async tryInsertOrGetExisting(params: CheckAndRecordParams): Promise<TryInsertOrGetResult> {
+    const blockIndexWithinCheckpoint = getBlockIndexFromDutyIdentifier(params);
+    const key = dutyKey(
+      params.rollupAddress.toString(),
+      params.validatorAddress.toString(),
+      params.slot.toString(),
+      params.dutyType,
+      blockIndexWithinCheckpoint,
+    );
+
+    const lockToken = randomBytes(16).toString('hex');
+    const now = this.dateProvider.now();
+
+    const result = await this.store.transactionAsync(async () => {
+      const existing = await this.duties.getAsync(key);
+      if (existing) {
+        return { isNew: false as const, record: { ...existing, lockToken: '' } };
+      }
+
+      const newRecord: StoredDutyRecord = {
+        rollupAddress: params.rollupAddress.toString(),
+        validatorAddress: params.validatorAddress.toString(),
+        slot: params.slot.toString(),
+        blockNumber: params.blockNumber.toString(),
+        checkpointNumber: params.checkpointNumber.toString(),
+        blockIndexWithinCheckpoint,
+        dutyType: params.dutyType,
+        status: DutyStatus.SIGNING,
+        messageHash: params.messageHash,
+        nodeId: params.nodeId,
+        lockToken,
+        startedAtMs: now,
+      };
+      await this.duties.set(key, newRecord);
+      return { isNew: true as const, record: newRecord };
+    });
+
+    if (result.isNew) {
+      this.log.debug(`Acquired lock for duty ${params.dutyType} at slot ${params.slot}`, {
+        validatorAddress: params.validatorAddress.toString(),
+        nodeId: params.nodeId,
+      });
+    }
+
+    return { isNew: result.isNew, record: recordFromFields(result.record) };
+  }
+
+  /**
+   * Update a duty to 'signed' status with the signature.
+   * Only succeeds if the lockToken matches.
+   */
+  public updateDutySigned(
+    rollupAddress: EthAddress,
+    validatorAddress: EthAddress,
+    slot: SlotNumber,
+    dutyType: DutyType,
+    signature: string,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): Promise<boolean> {
+    const key = dutyKey(
+      rollupAddress.toString(),
+      validatorAddress.toString(),
+      slot.toString(),
+      dutyType,
+      blockIndexWithinCheckpoint,
+    );
+
+    return this.store.transactionAsync(async () => {
+      const existing = await this.duties.getAsync(key);
+      if (!existing) {
+        this.log.warn('Failed to update duty to signed: duty not found', {
+          rollupAddress: rollupAddress.toString(),
+          validatorAddress: validatorAddress.toString(),
+          slot: slot.toString(),
+          dutyType,
+          blockIndexWithinCheckpoint,
+        });
+        return false;
+      }
+
+      if (existing.lockToken !== lockToken) {
+        this.log.warn('Failed to update duty to signed: invalid token', {
+          rollupAddress: rollupAddress.toString(),
+          validatorAddress: validatorAddress.toString(),
+          slot: slot.toString(),
+          dutyType,
+          blockIndexWithinCheckpoint,
+        });
+        return false;
+      }
+
+      await this.duties.set(key, {
+        ...existing,
+        status: DutyStatus.SIGNED,
+        signature,
+        completedAtMs: this.dateProvider.now(),
+      });
+
+      return true;
+    });
+  }
+
+  /**
+   * Delete a duty record.
+   * Only succeeds if the lockToken matches.
+   */
+  public deleteDuty(
+    rollupAddress: EthAddress,
+    validatorAddress: EthAddress,
+    slot: SlotNumber,
+    dutyType: DutyType,
+    lockToken: string,
+    blockIndexWithinCheckpoint: number,
+  ): Promise<boolean> {
+    const key = dutyKey(
+      rollupAddress.toString(),
+      validatorAddress.toString(),
+      slot.toString(),
+      dutyType,
+      blockIndexWithinCheckpoint,
+    );
+
+    return this.store.transactionAsync(async () => {
+      const existing = await this.duties.getAsync(key);
+      if (!existing || existing.lockToken !== lockToken) {
+        this.log.warn('Failed to delete duty: invalid token or duty not found', {
+          rollupAddress: rollupAddress.toString(),
+          validatorAddress: validatorAddress.toString(),
+          slot: slot.toString(),
+          dutyType,
+          blockIndexWithinCheckpoint,
+        });
+        return false;
+      }
+
+      await this.duties.delete(key);
+      return true;
+    });
+  }
+
+  /**
+   * Cleanup own stuck duties (SIGNING status older than maxAgeMs).
+   */
+  public cleanupOwnStuckDuties(nodeId: string, maxAgeMs: number): Promise<number> {
+    const cutoffMs = this.dateProvider.now() - maxAgeMs;
+
+    return this.store.transactionAsync(async () => {
+      const keysToDelete: string[] = [];
+      for await (const [key, record] of this.duties.entriesAsync()) {
+        if (record.nodeId === nodeId && record.status === DutyStatus.SIGNING && record.startedAtMs < cutoffMs) {
+          keysToDelete.push(key);
+        }
+      }
+      for (const key of keysToDelete) {
+        await this.duties.delete(key);
+      }
+      return keysToDelete.length;
+    });
+  }
+
+  /**
+   * Cleanup duties with outdated rollup address.
+   *
+   * This is always a no-op for the LMDB implementation: the underlying store is created via
+   * DatabaseVersionManager (in factory.ts), which already resets the entire data directory at
+   * startup whenever the rollup address changes.
+   */
+  public cleanupOutdatedRollupDuties(_currentRollupAddress: EthAddress): Promise<number> {
+    return Promise.resolve(0);
+  }
+
+  /**
+   * Cleanup old signed duties older than maxAgeMs.
+   */
+  public cleanupOldDuties(maxAgeMs: number): Promise<number> {
+    const cutoffMs = this.dateProvider.now() - maxAgeMs;
+
+    return this.store.transactionAsync(async () => {
+      const keysToDelete: string[] = [];
+      for await (const [key, record] of this.duties.entriesAsync()) {
+        if (
+          record.status === DutyStatus.SIGNED &&
+          record.completedAtMs !== undefined &&
+          record.completedAtMs < cutoffMs
+        ) {
+          keysToDelete.push(key);
+        }
+      }
+      for (const key of keysToDelete) {
+        await this.duties.delete(key);
+      }
+      return keysToDelete.length;
+    });
+  }
+
+  /**
+   * Close the underlying LMDB store.
+   */
+  public async close(): Promise<void> {
+    await this.store.close();
+    this.log.debug('LMDB slashing protection database closed');
+  }
+}

package/src/db/migrations/1_initial-schema.ts

@@ -1,21 +1,52 @@
 /**
  * Initial schema for validator HA slashing protection
  *
- * This migration imports SQL from the schema.ts file to ensure a single source of truth.
+ * Note: this migration contains a fixed snapshot of the schema at the time it was created.
+ * It must NOT import from schema.ts, which evolves over time and would cause this migration
+ * to produce different results on fresh runs vs. re-runs.
  */
 import type { MigrationBuilder } from 'node-pg-migrate';
 
-import { DROP_SCHEMA_VERSION_TABLE, DROP_VALIDATOR_DUTIES_TABLE, SCHEMA_SETUP, SCHEMA_VERSION } from '../schema.js';
+import { DROP_SCHEMA_VERSION_TABLE, DROP_VALIDATOR_DUTIES_TABLE } from '../schema.js';
+
+// Snapshot of the initial schema — does NOT include checkpoint_number (added in migration 2).
+const INITIAL_SCHEMA_SETUP = [
+  `CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY,
+    applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+  );`,
+  `CREATE TABLE IF NOT EXISTS validator_duties (
+    rollup_address VARCHAR(42) NOT NULL,
+    validator_address VARCHAR(42) NOT NULL,
+    slot BIGINT NOT NULL,
+    block_number BIGINT NOT NULL,
+    block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,
+    duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),
+    status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed')),
+    message_hash VARCHAR(66) NOT NULL,
+    signature VARCHAR(132),
+    node_id VARCHAR(255) NOT NULL,
+    lock_token VARCHAR(64) NOT NULL,
+    started_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    completed_at TIMESTAMP,
+    error_message TEXT,
+
+    PRIMARY KEY (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint),
+    CHECK (completed_at IS NULL OR completed_at >= started_at)
+  );`,
+  `CREATE INDEX IF NOT EXISTS idx_validator_duties_status ON validator_duties(status, started_at);`,
+  `CREATE INDEX IF NOT EXISTS idx_validator_duties_node ON validator_duties(node_id, started_at);`,
+] as const;
 
 export function up(pgm: MigrationBuilder): void {
-  for (const statement of SCHEMA_SETUP) {
+  for (const statement of INITIAL_SCHEMA_SETUP) {
     pgm.sql(statement);
   }
 
   // Insert initial schema version
   pgm.sql(`
     INSERT INTO schema_version (version)
-    VALUES (${SCHEMA_VERSION})
+    VALUES (1)
     ON CONFLICT (version) DO NOTHING;
   `);
 }

package/src/db/migrations/2_add-checkpoint-number.ts

@@ -0,0 +1,19 @@
+/**
+ * Add checkpoint_number column to validator_duties table
+ */
+import type { MigrationBuilder } from 'node-pg-migrate';
+
+export function up(pgm: MigrationBuilder): void {
+  pgm.addColumn('validator_duties', {
+    // eslint-disable-next-line camelcase
+    checkpoint_number: { type: 'bigint', notNull: true, default: 0 },
+  });
+
+  pgm.sql(`UPDATE schema_version SET version = 2 WHERE version = 1`);
+}
+
+export function down(pgm: MigrationBuilder): void {
+  pgm.dropColumn('validator_duties', 'checkpoint_number');
+
+  pgm.sql(`UPDATE schema_version SET version = 1 WHERE version = 2`);
+}

package/src/db/postgres.ts

@@ -1,7 +1,7 @@
 /**
  * PostgreSQL implementation of SlashingProtectionDatabase
  */
-import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { SlotNumber } from '@aztec/foundation/branded-types';
 import { randomBytes } from '@aztec/foundation/crypto/random';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
@@ -20,7 +20,7 @@ import {
   UPDATE_DUTY_SIGNED,
 } from './schema.js';
 import type { CheckAndRecordParams, DutyRow, DutyType, InsertOrGetRow, ValidatorDutyRecord } from './types.js';
-import { getBlockIndexFromDutyIdentifier } from './types.js';
+import { getBlockIndexFromDutyIdentifier, recordFromFields } from './types.js';
 
 /**
  * Minimal pool interface for database operations.
@@ -107,6 +107,7 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
           params.validatorAddress.toString(),
           params.slot.toString(),
           params.blockNumber.toString(),
+          params.checkpointNumber.toString(),
           blockIndexWithinCheckpoint,
           params.dutyType,
           params.messageHash,
@@ -220,14 +221,17 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
   }
 
   /**
-   * Convert a database row to a ValidatorDutyRecord
+   * Convert a database row to a ValidatorDutyRecord.
+   * Maps snake_case column names to StoredDutyRecord (camelCase, ms timestamps),
+   * then delegates to the shared recordFromFields() converter.
    */
   private rowToRecord(row: DutyRow): ValidatorDutyRecord {
-    return {
-      rollupAddress: EthAddress.fromString(row.rollup_address),
-      validatorAddress: EthAddress.fromString(row.validator_address),
-      slot: SlotNumber.fromString(row.slot),
-      blockNumber: BlockNumber.fromString(row.block_number),
+    return recordFromFields({
+      rollupAddress: row.rollup_address,
+      validatorAddress: row.validator_address,
+      slot: row.slot,
+      blockNumber: row.block_number,
+      checkpointNumber: row.checkpoint_number,
       blockIndexWithinCheckpoint: row.block_index_within_checkpoint,
       dutyType: row.duty_type,
       status: row.status,
@@ -235,10 +239,10 @@ export class PostgresSlashingProtectionDatabase implements SlashingProtectionDat
       signature: row.signature ?? undefined,
       nodeId: row.node_id,
       lockToken: row.lock_token,
-      startedAt: row.started_at,
-      completedAt: row.completed_at ?? undefined,
+      startedAtMs: row.started_at.getTime(),
+      completedAtMs: row.completed_at?.getTime(),
       errorMessage: row.error_message ?? undefined,
-    };
+    });
   }
 
   /**

package/src/db/schema.ts

@@ -9,7 +9,7 @@
 /**
  * Current schema version
  */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 /**
  * SQL to create the validator_duties table
@@ -20,6 +20,7 @@ CREATE TABLE IF NOT EXISTS validator_duties (
   validator_address VARCHAR(42) NOT NULL,
   slot BIGINT NOT NULL,
   block_number BIGINT NOT NULL,
+  checkpoint_number BIGINT NOT NULL DEFAULT 0,
   block_index_within_checkpoint INTEGER NOT NULL DEFAULT 0,
   duty_type VARCHAR(30) NOT NULL CHECK (duty_type IN ('BLOCK_PROPOSAL', 'CHECKPOINT_PROPOSAL', 'ATTESTATION', 'ATTESTATIONS_AND_SIGNERS', 'GOVERNANCE_VOTE', 'SLASHING_VOTE')),
   status VARCHAR(20) NOT NULL CHECK (status IN ('signing', 'signed')),
@@ -106,6 +107,7 @@ WITH inserted AS (
     validator_address,
     slot,
     block_number,
+    checkpoint_number,
     block_index_within_checkpoint,
     duty_type,
     status,
@@ -113,13 +115,14 @@ WITH inserted AS (
     node_id,
     lock_token,
     started_at
-  ) VALUES ($1, $2, $3, $4, $5, $6, 'signing', $7, $8, $9, CURRENT_TIMESTAMP)
+  ) VALUES ($1, $2, $3, $4, $5, $6, $7, 'signing', $8, $9, $10, CURRENT_TIMESTAMP)
   ON CONFLICT (rollup_address, validator_address, slot, duty_type, block_index_within_checkpoint) DO NOTHING
   RETURNING
     rollup_address,
     validator_address,
     slot,
     block_number,
+    checkpoint_number,
     block_index_within_checkpoint,
     duty_type,
     status,
@@ -139,6 +142,7 @@ SELECT
   validator_address,
   slot,
   block_number,
+  checkpoint_number,
   block_index_within_checkpoint,
   duty_type,
   status,
@@ -154,8 +158,8 @@ FROM validator_duties
 WHERE rollup_address = $1
   AND validator_address = $2
   AND slot = $3
-  AND duty_type = $6
-  AND block_index_within_checkpoint = $5
+  AND duty_type = $7
+  AND block_index_within_checkpoint = $6
   AND NOT EXISTS (SELECT 1 FROM inserted);
 `;
 
@@ -253,6 +257,7 @@ SELECT
   validator_address,
   slot,
   block_number,
+  checkpoint_number,
   block_index_within_checkpoint,
   duty_type,
   status,