@aztec/validator-ha-signer 0.0.1-commit.001888fc

package/src/db/schema.ts

@@ -0,0 +1,267 @@
+/**
+ * SQL schema for the validator_duties table
+ *
+ * This table is used for distributed locking and slashing protection across multiple validator nodes.
+ * The PRIMARY KEY constraint ensures that only one node can acquire the lock for a given validator,
+ * slot, and duty type combination.
+ */
+
+/**
+ * Current schema version
+ */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * SQL to create the validator_duties table
+ */
+export const CREATE_VALIDATOR_DUTIES_TABLE = `
+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)
+);
+`;
+
+/**
+ * SQL to create index on status and started_at for cleanup queries
+ */
+export const CREATE_STATUS_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_status
+ON validator_duties(status, started_at);
+`;
+
+/**
+ * SQL to create index for querying duties by node
+ */
+export const CREATE_NODE_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_validator_duties_node
+ON validator_duties(node_id, started_at);
+`;
+
+/**
+ * SQL to create the schema_version table for tracking migrations
+ */
+export const CREATE_SCHEMA_VERSION_TABLE = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+`;
+
+/**
+ * SQL to initialize schema version
+ */
+export const INSERT_SCHEMA_VERSION = `
+INSERT INTO schema_version (version)
+VALUES ($1)
+ON CONFLICT (version) DO NOTHING;
+`;
+
+/**
+ * Complete schema setup - all statements in order
+ */
+export const SCHEMA_SETUP = [
+  CREATE_SCHEMA_VERSION_TABLE,
+  CREATE_VALIDATOR_DUTIES_TABLE,
+  CREATE_STATUS_INDEX,
+  CREATE_NODE_INDEX,
+] as const;
+
+/**
+ * Query to get current schema version
+ */
+export const GET_SCHEMA_VERSION = `
+SELECT version FROM schema_version ORDER BY version DESC LIMIT 1;
+`;
+
+/**
+ * Atomic insert-or-get query.
+ * Tries to insert a new duty record. If a record already exists (conflict),
+ * returns the existing record instead.
+ *
+ * Returns the record with an `is_new` flag indicating whether we inserted or got existing.
+ *
+ * Note: In high concurrency scenarios, if the INSERT conflicts and another transaction
+ * just committed the row, there's a small window where the SELECT might not see it yet.
+ * The application layer should retry if no rows are returned.
+ */
+export const INSERT_OR_GET_DUTY = `
+WITH inserted AS (
+  INSERT INTO validator_duties (
+    rollup_address,
+    validator_address,
+    slot,
+    block_number,
+    block_index_within_checkpoint,
+    duty_type,
+    status,
+    message_hash,
+    node_id,
+    lock_token,
+    started_at
+  ) VALUES ($1, $2, $3, $4, $5, $6, 'signing', $7, $8, $9, 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,
+    block_index_within_checkpoint,
+    duty_type,
+    status,
+    message_hash,
+    signature,
+    node_id,
+    lock_token,
+    started_at,
+    completed_at,
+    error_message,
+    TRUE as is_new
+)
+SELECT * FROM inserted
+UNION ALL
+SELECT
+  rollup_address,
+  validator_address,
+  slot,
+  block_number,
+  block_index_within_checkpoint,
+  duty_type,
+  status,
+  message_hash,
+  signature,
+  node_id,
+  '' as lock_token,
+  started_at,
+  completed_at,
+  error_message,
+  FALSE as is_new
+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 NOT EXISTS (SELECT 1 FROM inserted);
+`;
+
+/**
+ * Query to update a duty to 'signed' status
+ */
+export const UPDATE_DUTY_SIGNED = `
+UPDATE validator_duties
+SET status = 'signed',
+    signature = $1,
+    completed_at = CURRENT_TIMESTAMP
+WHERE rollup_address = $2
+  AND validator_address = $3
+  AND slot = $4
+  AND duty_type = $5
+  AND block_index_within_checkpoint = $6
+  AND status = 'signing'
+  AND lock_token = $7;
+`;
+
+/**
+ * Query to delete a duty
+ * Only deletes if the lockToken matches
+ */
+export const DELETE_DUTY = `
+DELETE FROM validator_duties
+WHERE rollup_address = $1
+  AND validator_address = $2
+  AND slot = $3
+  AND duty_type = $4
+  AND block_index_within_checkpoint = $5
+  AND status = 'signing'
+  AND lock_token = $6;
+`;
+
+/**
+ * Query to clean up old signed duties (for maintenance)
+ * Removes signed duties older than a specified timestamp
+ */
+export const CLEANUP_OLD_SIGNED_DUTIES = `
+DELETE FROM validator_duties
+WHERE status = 'signed'
+  AND completed_at < $1;
+`;
+
+/**
+ * Query to clean up old duties (for maintenance)
+ * Removes SIGNED duties older than a specified age (in milliseconds)
+ */
+export const CLEANUP_OLD_DUTIES = `
+DELETE FROM validator_duties
+WHERE status = 'signed'
+  AND started_at < CURRENT_TIMESTAMP - ($1 || ' milliseconds')::INTERVAL;
+`;
+
+/**
+ * Query to cleanup own stuck duties
+ * Removes duties in 'signing' status for a specific node that are older than maxAgeMs
+ * Uses DB's CURRENT_TIMESTAMP to avoid clock skew issues between nodes
+ */
+export const CLEANUP_OWN_STUCK_DUTIES = `
+DELETE FROM validator_duties
+WHERE node_id = $1
+  AND status = 'signing'
+  AND started_at < CURRENT_TIMESTAMP - ($2 || ' milliseconds')::INTERVAL;
+`;
+
+/**
+ * Query to 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
+ */
+export const CLEANUP_OUTDATED_ROLLUP_DUTIES = `
+DELETE FROM validator_duties
+WHERE rollup_address != $1;
+`;
+
+/**
+ * SQL to drop the validator_duties table
+ */
+export const DROP_VALIDATOR_DUTIES_TABLE = `DROP TABLE IF EXISTS validator_duties;`;
+
+/**
+ * SQL to drop the schema_version table
+ */
+export const DROP_SCHEMA_VERSION_TABLE = `DROP TABLE IF EXISTS schema_version;`;
+
+/**
+ * Query to get stuck duties (for monitoring/alerting)
+ * Returns duties in 'signing' status that have been stuck for too long
+ */
+export const GET_STUCK_DUTIES = `
+SELECT
+  rollup_address,
+  validator_address,
+  slot,
+  block_number,
+  block_index_within_checkpoint,
+  duty_type,
+  status,
+  message_hash,
+  node_id,
+  started_at,
+  EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - started_at)) as age_seconds
+FROM validator_duties
+WHERE status = 'signing'
+  AND started_at < $1
+ORDER BY started_at ASC;
+`;

package/src/db/test_helper.ts

@@ -0,0 +1,17 @@
+/**
+ * Test helpers for database setup
+ */
+import type { PGlite } from '@electric-sql/pglite';
+
+import { INSERT_SCHEMA_VERSION, SCHEMA_SETUP, SCHEMA_VERSION } from './schema.js';
+
+/**
+ * Set up the database schema for testing.
+ * This runs the same SQL that migrations would apply.
+ */
+export async function setupTestSchema(pglite: PGlite): Promise<void> {
+  for (const statement of SCHEMA_SETUP) {
+    await pglite.query(statement);
+  }
+  await pglite.query(INSERT_SCHEMA_VERSION, [SCHEMA_VERSION]);
+}

package/src/db/types.ts

@@ -0,0 +1,251 @@
+import {
+  BlockNumber,
+  type 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';
+
+/**
+ * Row type from PostgreSQL query
+ */
+export interface DutyRow {
+  rollup_address: string;
+  validator_address: string;
+  slot: string;
+  block_number: string;
+  block_index_within_checkpoint: number;
+  duty_type: DutyType;
+  status: DutyStatus;
+  message_hash: string;
+  signature: string | null;
+  node_id: string;
+  lock_token: string;
+  started_at: Date;
+  completed_at: Date | null;
+  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;
+  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)
+ */
+export interface InsertOrGetRow extends DutyRow {
+  is_new: boolean;
+}
+
+/**
+ * Status of a duty in the database
+ */
+export enum DutyStatus {
+  SIGNING = 'signing',
+  SIGNED = 'signed',
+}
+
+// Re-export DutyType from stdlib
+export { DutyType };
+
+/**
+ * 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 */
+  rollupAddress: EthAddress;
+  /** Ethereum address of the validator */
+  validatorAddress: EthAddress;
+  /** Slot number for this duty */
+  slot: SlotNumber;
+  /** Block number for this duty */
+  blockNumber: BlockNumber;
+  /** Block index within checkpoint (0, 1, 2... for block proposals, -1 for other duty types) */
+  blockIndexWithinCheckpoint: number;
+  /** Type of duty being performed */
+  dutyType: DutyType;
+  /** Current status of the duty */
+  status: DutyStatus;
+  /** The signing root (hash) for this duty */
+  messageHash: string;
+  /** The signature (populated after successful signing) */
+  signature?: string;
+  /** Unique identifier for the node that acquired the lock */
+  nodeId: string;
+  /** Secret token for verifying ownership of the duty lock */
+  lockToken: string;
+  /** When the duty signing was started */
+  startedAt: Date;
+  /** When the duty signing was completed (success or failure) */
+  completedAt?: Date;
+  /** Error message (currently unused) */
+  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),
+    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.
+ */
+export interface BlockProposalDutyIdentifier {
+  rollupAddress: EthAddress;
+  validatorAddress: EthAddress;
+  slot: SlotNumber;
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Duty identifier for non-block-proposal duties.
+ * blockIndexWithinCheckpoint is not applicable (internally stored as -1).
+ */
+export interface OtherDutyIdentifier {
+  rollupAddress: EthAddress;
+  validatorAddress: EthAddress;
+  slot: SlotNumber;
+  dutyType:
+    | DutyType.CHECKPOINT_PROPOSAL
+    | DutyType.ATTESTATION
+    | DutyType.ATTESTATIONS_AND_SIGNERS
+    | DutyType.GOVERNANCE_VOTE
+    | DutyType.SLASHING_VOTE
+    | DutyType.AUTH_REQUEST
+    | DutyType.TXS;
+}
+
+/**
+ * Minimal info needed to identify a unique duty.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ */
+export type DutyIdentifier = BlockProposalDutyIdentifier | OtherDutyIdentifier;
+
+/**
+ * Validates and normalizes the block index for a duty.
+ * - BLOCK_PROPOSAL: validates blockIndexWithinCheckpoint is provided and >= 0
+ * - Other duty types: always returns -1
+ *
+ * @throws Error if BLOCK_PROPOSAL is missing blockIndexWithinCheckpoint or has invalid value
+ */
+export function normalizeBlockIndex(dutyType: DutyType, blockIndexWithinCheckpoint: number | undefined): number {
+  if (dutyType === DutyType.BLOCK_PROPOSAL) {
+    if (blockIndexWithinCheckpoint === undefined) {
+      throw new Error('BLOCK_PROPOSAL duties require blockIndexWithinCheckpoint to be specified');
+    }
+    if (blockIndexWithinCheckpoint < 0) {
+      throw new Error(
+        `BLOCK_PROPOSAL duties require blockIndexWithinCheckpoint >= 0, got ${blockIndexWithinCheckpoint}`,
+      );
+    }
+    return blockIndexWithinCheckpoint;
+  }
+  // For all other duty types, always use -1
+  return -1;
+}
+
+/**
+ * Gets the block index from a DutyIdentifier.
+ * - BLOCK_PROPOSAL: returns the blockIndexWithinCheckpoint
+ * - Other duty types: returns -1
+ */
+export function getBlockIndexFromDutyIdentifier(duty: DutyIdentifier): number {
+  if (duty.dutyType === DutyType.BLOCK_PROPOSAL) {
+    return duty.blockIndexWithinCheckpoint;
+  }
+  return -1;
+}
+
+/**
+ * Additional parameters for checking and recording a new duty
+ */
+interface CheckAndRecordExtra {
+  /** Block number for this duty */
+  blockNumber: BlockNumber | CheckpointNumber;
+  /** The signing root (hash) for this duty */
+  messageHash: string;
+  /** Identifier for the node that acquired the lock */
+  nodeId: string;
+}
+
+/**
+ * Parameters for checking and recording a new duty.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
+ */
+export type CheckAndRecordParams = DutyIdentifier & CheckAndRecordExtra;
+
+/**
+ * Additional parameters for recording a successful signing
+ */
+interface RecordSuccessExtra {
+  signature: Signature;
+  nodeId: string;
+  lockToken: string;
+}
+
+/**
+ * Parameters for recording a successful signing.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
+ */
+export type RecordSuccessParams = DutyIdentifier & RecordSuccessExtra;
+
+/**
+ * Additional parameters for deleting a duty
+ */
+interface DeleteDutyExtra {
+  lockToken: string;
+}
+
+/**
+ * Parameters for deleting a duty.
+ * Uses intersection with DutyIdentifier to preserve the discriminated union.
+ */
+export type DeleteDutyParams = DutyIdentifier & DeleteDutyExtra;

package/src/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * Custom errors for the validator HA signer
+ */
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+
+import type { DutyType } from './db/types.js';
+
+/**
+ * Thrown when a duty has already been signed (by any node).
+ * This is expected behavior in an HA setup - all nodes try to sign,
+ * the first one wins, and subsequent attempts get this error.
+ */
+export class DutyAlreadySignedError extends Error {
+  constructor(
+    public readonly slot: SlotNumber,
+    public readonly dutyType: DutyType,
+    public readonly blockIndexWithinCheckpoint: number,
+    public readonly signedByNode: string,
+  ) {
+    super(`Duty ${dutyType} for slot ${slot} already signed by node ${signedByNode}`);
+    this.name = 'DutyAlreadySignedError';
+  }
+}
+
+/**
+ * Thrown when attempting to sign data that conflicts with an already-signed duty.
+ * This means the same validator tried to sign DIFFERENT data for the same slot.
+ *
+ * This is expected in HA setups where nodes may build different blocks
+ * (e.g., different transaction ordering) - the protection prevents double-signing.
+ */
+export class SlashingProtectionError extends Error {
+  constructor(
+    public readonly slot: SlotNumber,
+    public readonly dutyType: DutyType,
+    public readonly blockIndexWithinCheckpoint: number,
+    public readonly existingMessageHash: string,
+    public readonly attemptedMessageHash: string,
+    public readonly signedByNode: string,
+  ) {
+    super(
+      `Slashing protection: ${dutyType} for slot ${slot} was already signed with different data. ` +
+        `Existing: ${existingMessageHash.slice(0, 10)}..., Attempted: ${attemptedMessageHash.slice(0, 10)}...`,
+    );
+    this.name = 'SlashingProtectionError';
+  }
+}