@aztec-labs/validator-client 6.0.0-nightly.20260829

package/src/duties/validation_service.ts

@@ -0,0 +1,224 @@
+import { type CheckpointNumber, IndexWithinCheckpoint, type SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { Signature } from '@aztec-labs/foundation/eth-signature';
+import { createLogger } from '@aztec-labs/foundation/log';
+import { CommitteeAttestationsAndSigners } from '@aztec-labs/stdlib/block';
+import type { InboxBucketRef } from '@aztec-labs/stdlib/messaging';
+import {
+  BlockProposal,
+  type BlockProposalOptions,
+  CheckpointAttestation,
+  CheckpointProposal,
+  type CheckpointProposalCore,
+  type CheckpointProposalOptions,
+  ConsensusPayload,
+  type CoordinationSignatureContext,
+  getCoordinationSignatureTypedData,
+} from '@aztec-labs/stdlib/p2p';
+import { CheckpointHeader } from '@aztec-labs/stdlib/rollup';
+import type { BlockHeader, Tx } from '@aztec-labs/stdlib/tx';
+import { DutyAlreadySignedError, SlashingProtectionError } from '@aztec-labs/validator-ha-signer/errors';
+import { DutyType, type SigningContext } from '@aztec-labs/validator-ha-signer/types';
+
+import type { ValidatorKeyStore } from '../key_store/interface.js';
+
+export class ValidationService {
+  constructor(
+    private keyStore: ValidatorKeyStore,
+    private signatureContext: CoordinationSignatureContext,
+    private log = createLogger('validator:validation-service'),
+  ) {}
+
+  /**
+   * Create a block proposal with the given header, archive, and transactions
+   *
+   * @param blockHeader - The block header
+   * @param blockIndexWithinCheckpoint - The block index within checkpoint for HA signing context
+   * @param archive - The archive of the current block
+   * @param txs - Ordered list of transactions (Tx[])
+   * @param proposerAttesterAddress - The address of the proposer/attester, or undefined
+   * @param options - Block proposal options (including broadcastInvalidBlockProposal for testing)
+   *
+   * @returns A block proposal signing the above information
+   * @throws DutyAlreadySignedError if HA signer indicates duty already signed by another node
+   * @throws SlashingProtectionError if attempting to sign different data for same slot
+   */
+  public createBlockProposal(
+    blockHeader: BlockHeader,
+    checkpointNumber: CheckpointNumber,
+    blockIndexWithinCheckpoint: IndexWithinCheckpoint,
+    archive: Fr,
+    txs: Tx[],
+    proposerAttesterAddress: EthAddress | undefined,
+    options: BlockProposalOptions,
+    bucketRef?: InboxBucketRef,
+  ): Promise<BlockProposal> {
+    // For testing: change the new archive to trigger state_mismatch validation failure
+    if (options.broadcastInvalidBlockProposal) {
+      archive = Fr.random();
+      this.log.warn(`Creating INVALID block proposal for slot ${blockHeader.globalVariables.slotNumber}`);
+    }
+
+    // Create a signer that uses the appropriate address
+    const address = proposerAttesterAddress ?? this.keyStore.getAddress(0);
+    const payloadSigner = (
+      typedData: Parameters<ValidatorKeyStore['signTypedDataWithAddress']>[1],
+      context: SigningContext,
+    ) => this.keyStore.signTypedDataWithAddress(address, typedData, context);
+    const txsSigner = (
+      typedData: Parameters<ValidatorKeyStore['signTypedDataWithAddress']>[1],
+      context: SigningContext,
+    ) => this.keyStore.signTypedDataWithAddress(address, typedData, context);
+
+    return BlockProposal.createProposalFromSigner(
+      blockHeader,
+      checkpointNumber,
+      blockIndexWithinCheckpoint,
+      archive,
+      txs.map(tx => tx.getTxHash()),
+      options.publishFullTxs ? txs : undefined,
+      this.signatureContext,
+      payloadSigner,
+      txsSigner,
+      bucketRef,
+    );
+  }
+
+  /**
+   * Create a checkpoint proposal with the last block header and checkpoint header
+   *
+   * @param checkpointHeader - The checkpoint header containing aggregated data
+   * @param archive - The archive of the checkpoint
+   * @param lastBlockProposal - Signed block proposal for the last block in the checkpoint, or undefined
+   * @param proposerAttesterAddress - The address of the proposer
+   * @param options - Checkpoint proposal options
+   *
+   * @returns A checkpoint proposal signing the above information
+   */
+  public createCheckpointProposal(
+    checkpointHeader: CheckpointHeader,
+    archive: Fr,
+    checkpointNumber: CheckpointNumber,
+    feeAssetPriceModifier: bigint,
+    lastBlockProposal: BlockProposal | undefined,
+    proposerAttesterAddress: EthAddress | undefined,
+    options: CheckpointProposalOptions,
+  ): Promise<CheckpointProposal> {
+    // For testing: corrupt the checkpoint so observers' checkpoint validation fails.
+    //
+    // Keep `archive` aligned with `lastBlockProposal.archiveRoot` so the archive-based lookup
+    // in `validateCheckpointProposal` (`getBlockData({ archive })`) still succeeds
+    if (options.broadcastInvalidCheckpointProposal) {
+      archive = lastBlockProposal?.archiveRoot ?? Fr.random();
+      checkpointHeader = CheckpointHeader.from({
+        ...checkpointHeader,
+        epochOutHash: Fr.random(),
+      });
+      this.log.warn(`Creating INVALID checkpoint proposal for slot ${checkpointHeader.slotNumber}`);
+    }
+
+    // Create a signer that takes payload and context, and uses the appropriate address
+    const payloadSigner = (
+      typedData: Parameters<ValidatorKeyStore['signTypedDataWithAddress']>[1],
+      context: SigningContext,
+    ) => {
+      const address = proposerAttesterAddress ?? this.keyStore.getAddress(0);
+      return this.keyStore.signTypedDataWithAddress(address, typedData, context);
+    };
+
+    return CheckpointProposal.createProposalFromSigner(
+      checkpointHeader,
+      archive,
+      checkpointNumber,
+      feeAssetPriceModifier,
+      lastBlockProposal,
+      this.signatureContext,
+      payloadSigner,
+    );
+  }
+
+  /**
+   * Attest with selection of validators to the given checkpoint proposal
+   *
+   * NOTE: This is just a blind signing.
+   *       We assume that the proposal is valid and DA guarantees have been checked previously.
+   *
+   * @param proposal - The checkpoint proposal (core version without lastBlock) to attest to
+   * @param attestors - The validators to attest with
+   * @returns checkpoint attestations
+   */
+  async attestToCheckpointProposal(
+    proposal: CheckpointProposalCore,
+    attestors: EthAddress[],
+    checkpointNumber: CheckpointNumber,
+  ): Promise<CheckpointAttestation[]> {
+    // Create the attestation payload from the checkpoint proposal
+    const payload = new ConsensusPayload(
+      proposal.checkpointHeader,
+      proposal.archive,
+      proposal.feeAssetPriceModifier,
+      this.signatureContext,
+    );
+    const typedData = getCoordinationSignatureTypedData(payload);
+
+    const context: SigningContext = {
+      slot: proposal.slotNumber,
+      checkpointNumber,
+      dutyType: DutyType.ATTESTATION,
+    };
+
+    // Sign each attestor in parallel, catching HA errors per-attestor
+    const results = await Promise.allSettled(
+      attestors.map(async attestor => {
+        const sig = await this.keyStore.signTypedDataWithAddress(attestor, typedData, context);
+        return new CheckpointAttestation(payload, sig, proposal.signature);
+      }),
+    );
+
+    const attestations: CheckpointAttestation[] = [];
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      if (result.status === 'fulfilled') {
+        attestations.push(result.value);
+      } else {
+        const error = result.reason;
+        if (error instanceof DutyAlreadySignedError || error instanceof SlashingProtectionError) {
+          this.log.verbose(
+            `Attestation for slot ${proposal.slotNumber} by ${attestors[i]} already signed by another High-Availability node`,
+          );
+          // Continue with remaining attestors
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    return attestations;
+  }
+
+  /**
+   * Sign attestations and signers payload
+   * @param attestationsAndSigners - The attestations and signers to sign
+   * @param proposer - The proposer address to sign with
+   * @param slot - The slot number for HA signing context
+   * @returns signature
+   * @throws DutyAlreadySignedError if already signed by another HA node
+   * @throws SlashingProtectionError if attempting to sign different data for same slot
+   */
+  signAttestationsAndSigners(
+    attestationsAndSigners: CommitteeAttestationsAndSigners,
+    proposer: EthAddress,
+    slot: SlotNumber,
+    checkpointNumber: CheckpointNumber,
+  ): Promise<Signature> {
+    const context: SigningContext = {
+      slot,
+      checkpointNumber,
+      dutyType: DutyType.ATTESTATIONS_AND_SIGNERS,
+    };
+
+    const typedData = getCoordinationSignatureTypedData(attestationsAndSigners);
+    return this.keyStore.signTypedDataWithAddress(proposer, typedData, context);
+  }
+}

package/src/factory.ts

@@ -0,0 +1,95 @@
+import type { BlobClientInterface } from '@aztec-labs/blob-client/client';
+import type { EpochCache } from '@aztec-labs/epoch-cache';
+import type { DateProvider } from '@aztec-labs/foundation/timer';
+import type { KeystoreManager } from '@aztec-labs/node-keystore';
+import type { P2PClient } from '@aztec-labs/p2p';
+import type { L2BlockSink, L2BlockSource } from '@aztec-labs/stdlib/block';
+import type { CheckpointReexecutionTracker } from '@aztec-labs/stdlib/checkpoint';
+import type { ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec-labs/stdlib/interfaces/server';
+import type { L1ToL2MessageSource } from '@aztec-labs/stdlib/messaging';
+import { ConsensusTimetable } from '@aztec-labs/stdlib/timetable';
+import type { TelemetryClient } from '@aztec-labs/telemetry-client';
+import type { SlashingProtectionDatabase } from '@aztec-labs/validator-ha-signer/types';
+
+import type { FullNodeCheckpointsBuilder } from './checkpoint_builder.js';
+import { ValidatorMetrics } from './metrics.js';
+import { ProposalHandler } from './proposal_handler.js';
+import { ValidatorClient } from './validator.js';
+
+export function createProposalHandler(
+  config: ValidatorClientFullConfig,
+  deps: {
+    checkpointsBuilder: FullNodeCheckpointsBuilder;
+    worldState: WorldStateSynchronizer;
+    blockSource: L2BlockSource & L2BlockSink;
+    l1ToL2MessageSource: L1ToL2MessageSource;
+    p2pClient: P2PClient;
+    epochCache: EpochCache;
+    blobClient: BlobClientInterface;
+    dateProvider: DateProvider;
+    telemetry: TelemetryClient;
+    reexecutionTracker: CheckpointReexecutionTracker;
+  },
+) {
+  const metrics = new ValidatorMetrics(deps.telemetry);
+  const consensusTimetable = new ConsensusTimetable({
+    l1Constants: deps.epochCache.getL1Constants(),
+    blockDuration: config.blockDurationMs / 1000,
+  });
+  return new ProposalHandler(
+    deps.checkpointsBuilder,
+    deps.worldState,
+    deps.blockSource,
+    deps.l1ToL2MessageSource,
+    deps.p2pClient.getTxProvider(),
+    deps.epochCache,
+    consensusTimetable,
+    config,
+    deps.blobClient,
+    deps.reexecutionTracker,
+    metrics,
+    deps.dateProvider,
+    deps.telemetry,
+    undefined,
+  );
+}
+
+export function createValidatorClient(
+  config: ValidatorClientFullConfig,
+  deps: {
+    checkpointsBuilder: FullNodeCheckpointsBuilder;
+    worldState: WorldStateSynchronizer;
+    p2pClient: P2PClient;
+    blockSource: L2BlockSource & L2BlockSink;
+    l1ToL2MessageSource: L1ToL2MessageSource;
+    telemetry: TelemetryClient;
+    dateProvider: DateProvider;
+    epochCache: EpochCache;
+    keyStoreManager: KeystoreManager | undefined;
+    blobClient: BlobClientInterface;
+    reexecutionTracker: CheckpointReexecutionTracker;
+    slashingProtectionDb?: SlashingProtectionDatabase;
+  },
+) {
+  if (config.disableValidator || !deps.keyStoreManager) {
+    return undefined;
+  }
+
+  const txProvider = deps.p2pClient.getTxProvider();
+  return ValidatorClient.new(
+    config,
+    deps.checkpointsBuilder,
+    deps.worldState,
+    deps.epochCache,
+    deps.p2pClient,
+    deps.blockSource,
+    deps.l1ToL2MessageSource,
+    txProvider,
+    deps.keyStoreManager,
+    deps.blobClient,
+    deps.reexecutionTracker,
+    deps.dateProvider,
+    deps.telemetry,
+    deps.slashingProtectionDb,
+  );
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './proposal_handler.js';
+export * from './checkpoint_builder.js';
+export * from './config.js';
+export * from './factory.js';
+export * from './validator.js';
+export * from './key_store/index.js';

package/src/key_store/ha_key_store.ts

@@ -0,0 +1,268 @@
+/**
+ * High Availability Key Store
+ *
+ * A ValidatorKeyStore wrapper that adds slashing protection for HA validator setups.
+ * When multiple validator nodes are running, only one node will sign for a given duty.
+ */
+import { Buffer32 } from '@aztec-labs/foundation/buffer';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { Signature } from '@aztec-labs/foundation/eth-signature';
+import { createLogger } from '@aztec-labs/foundation/log';
+import type { EthRemoteSignerConfig } from '@aztec-labs/node-keystore';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { DutyAlreadySignedError, SlashingProtectionError } from '@aztec-labs/validator-ha-signer/errors';
+import {
+  type HAProtectedSigningContext,
+  type SigningContext,
+  isHAProtectedContext,
+} from '@aztec-labs/validator-ha-signer/types';
+import type { ValidatorHASigner } from '@aztec-labs/validator-ha-signer/validator-ha-signer';
+import { type TypedDataDefinition, hashTypedData } from 'viem';
+
+import type { ExtendedValidatorKeyStore } from './interface.js';
+
+/**
+ * High Availability Key Store
+ *
+ * Wraps a base ExtendedValidatorKeyStore and ValidatorHASigner to provide
+ * HA-protected signing operations (when context is provided).
+ *
+ * The extended interface methods (getAttesterAddresses, getCoinbaseAddress, etc.)
+ * are pure pass-through since they don't require HA coordination.
+ *
+ * Usage:
+ * ```typescript
+ * const baseKeyStore = NodeKeystoreAdapter.fromPrivateKeys(privateKeys);
+ * const haSigner = new ValidatorHASigner(db, config);
+ * const haKeyStore = new HAKeyStore(baseKeyStore, haSigner);
+ *
+ * // Without context - signs directly (no HA protection)
+ * const sig = await haKeyStore.signMessageWithAddress(addr, msg);
+ *
+ * // With context - HA protected, throws DutyAlreadySignedError if already signed
+ * const result = await haKeyStore.signMessageWithAddress(addr, msg, {
+ *   slot: 100n,
+ *   blockNumber: 50n,
+ *   dutyType: DutyType.BLOCK_PROPOSAL,
+ * });
+ * ```
+ */
+export class HAKeyStore implements ExtendedValidatorKeyStore {
+  private readonly log = createLogger('ha-key-store');
+
+  constructor(
+    private readonly baseKeyStore: ExtendedValidatorKeyStore,
+    private readonly haSigner: ValidatorHASigner,
+  ) {
+    this.log.info('HAKeyStore initialized', {
+      nodeId: haSigner.nodeId,
+    });
+  }
+
+  /**
+   * Sign typed data with all addresses.
+   * Coordinates across nodes to prevent double-signing for most duty types.
+   * AUTH_REQUEST and TXS duties bypass HA protection since signing multiple times is safe.
+   * Returns only signatures that were successfully claimed by this node.
+   */
+  async signTypedData(typedData: TypedDataDefinition, context: SigningContext): Promise<Signature[]> {
+    // no need for HA protection on auth request and txs signatures
+    if (!isHAProtectedContext(context)) {
+      return this.baseKeyStore.signTypedData(typedData, context);
+    }
+
+    // Sign each address with HA protection
+    const addresses = this.getAddresses();
+    const results = await Promise.allSettled(
+      addresses.map(addr => this.signTypedDataWithAddress(addr, typedData, context)),
+    );
+
+    // Filter out failures (already signed by other nodes or other errors)
+    return results
+      .filter((result): result is PromiseFulfilledResult<Signature> => {
+        if (result.status === 'fulfilled') {
+          return true;
+        }
+        // Log expected HA errors (already signed) at debug level
+        if (result.reason instanceof DutyAlreadySignedError) {
+          this.log.debug(`Duty already signed by another node`, {
+            dutyType: context.dutyType,
+            slot: context.slot,
+            signedByNode: result.reason.signedByNode,
+          });
+          return false;
+        }
+        // Re-throw unexpected errors
+        throw result.reason;
+      })
+      .map(result => result.value);
+  }
+
+  /**
+   * Sign a message with all addresses.
+   * Coordinates across nodes to prevent double-signing for most duty types.
+   * AUTH_REQUEST and TXS duties bypass HA protection since signing multiple times is safe.
+   * Returns only signatures that were successfully claimed by this node.
+   */
+  async signMessage(message: Buffer32, context: SigningContext): Promise<Signature[]> {
+    // no need for HA protection on auth request and txs signatures
+    if (!isHAProtectedContext(context)) {
+      return this.baseKeyStore.signMessage(message, context);
+    }
+
+    // Sign each address with HA protection
+    const addresses = this.getAddresses();
+    const results = await Promise.allSettled(
+      addresses.map(addr => this.signMessageWithAddress(addr, message, context)),
+    );
+
+    // Filter out failures (already signed by other nodes or other errors)
+    return results
+      .filter((result): result is PromiseFulfilledResult<Signature> => {
+        if (result.status === 'fulfilled') {
+          return true;
+        }
+        // Log expected HA errors (already signed) at debug level
+        if (result.reason instanceof DutyAlreadySignedError) {
+          this.log.debug(`Duty already signed by another node`, {
+            dutyType: context.dutyType,
+            slot: context.slot,
+            signedByNode: result.reason.signedByNode,
+          });
+          return false;
+        }
+        // Re-throw unexpected errors
+        throw result.reason;
+      })
+      .map(result => result.value);
+  }
+
+  /**
+   * Sign typed data with a specific address.
+   * Coordinates across nodes to prevent double-signing for most duty types.
+   * AUTH_REQUEST and TXS duties bypass HA protection since signing multiple times is safe.
+   * @throws DutyAlreadySignedError if the duty was already signed by another node
+   * @throws SlashingProtectionError if attempting to sign different data for the same slot
+   */
+  async signTypedDataWithAddress(
+    address: EthAddress,
+    typedData: TypedDataDefinition,
+    context: SigningContext,
+  ): Promise<Signature> {
+    // AUTH_REQUEST and TXS bypass HA protection - multiple signatures are safe
+    if (!isHAProtectedContext(context)) {
+      return this.baseKeyStore.signTypedDataWithAddress(address, typedData, context);
+    }
+
+    // Compute signing root from typed data for HA tracking
+    const digest = hashTypedData(typedData);
+    const messageHash = Buffer32.fromString(digest);
+
+    try {
+      return await this.haSigner.signWithProtection(address, messageHash, context, () =>
+        this.baseKeyStore.signTypedDataWithAddress(address, typedData, context),
+      );
+    } catch (error) {
+      this.processSigningError(error, context);
+      throw error;
+    }
+  }
+
+  /**
+   * Sign a message with a specific address.
+   * Coordinates across nodes to prevent double-signing for most duty types.
+   * AUTH_REQUEST and TXS duties bypass HA protection since signing multiple times is safe.
+   * @throws DutyAlreadySignedError if the duty was already signed by another node
+   * @throws SlashingProtectionError if attempting to sign different data for the same slot
+   */
+  async signMessageWithAddress(address: EthAddress, message: Buffer32, context: SigningContext): Promise<Signature> {
+    // no need for HA protection on auth request and txs signatures
+    if (!isHAProtectedContext(context)) {
+      return this.baseKeyStore.signMessageWithAddress(address, message, context);
+    }
+
+    try {
+      return await this.haSigner.signWithProtection(address, message, context, messageHash =>
+        this.baseKeyStore.signMessageWithAddress(address, messageHash, context),
+      );
+    } catch (error) {
+      this.processSigningError(error, context);
+      throw error;
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // pass-through methods (no HA logic needed)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  getAddress(index: number): EthAddress {
+    return this.baseKeyStore.getAddress(index);
+  }
+
+  getAddresses(): EthAddress[] {
+    return this.baseKeyStore.getAddresses();
+  }
+
+  getAttesterAddresses(): EthAddress[] {
+    return this.baseKeyStore.getAttesterAddresses();
+  }
+
+  getCoinbaseAddress(attesterAddress: EthAddress): EthAddress {
+    return this.baseKeyStore.getCoinbaseAddress(attesterAddress);
+  }
+
+  getPublisherAddresses(attesterAddress: EthAddress): EthAddress[] {
+    return this.baseKeyStore.getPublisherAddresses(attesterAddress);
+  }
+
+  getFeeRecipient(attesterAddress: EthAddress): AztecAddress {
+    return this.baseKeyStore.getFeeRecipient(attesterAddress);
+  }
+
+  getRemoteSignerConfig(attesterAddress: EthAddress): EthRemoteSignerConfig | undefined {
+    return this.baseKeyStore.getRemoteSignerConfig(attesterAddress);
+  }
+
+  /**
+   * Process signing errors from the HA signer.
+   * Logs expected HA errors (already signed) at appropriate levels.
+   * Re-throws unexpected errors.
+   */
+  private processSigningError(error: unknown, context: HAProtectedSigningContext) {
+    if (error instanceof DutyAlreadySignedError) {
+      this.log.debug(`Duty already signed by another node with the same payload`, {
+        dutyType: context.dutyType,
+        slot: context.slot,
+        signedByNode: error.signedByNode,
+      });
+      return;
+    }
+
+    if (error instanceof SlashingProtectionError) {
+      this.log.info(`Duty already signed by another node with different payload`, {
+        dutyType: context.dutyType,
+        slot: context.slot,
+        existingMessageHash: error.existingMessageHash,
+        attemptedMessageHash: error.attemptedMessageHash,
+      });
+      return;
+    }
+
+    // Re-throw errors
+    throw error;
+  }
+
+  /**
+   * Start the high-availability key store
+   */
+  public async start() {
+    await this.haSigner.start();
+  }
+
+  /**
+   * Stop the high-availability key store
+   */
+  public async stop() {
+    await this.haSigner.stop();
+  }
+}

package/src/key_store/index.ts

@@ -0,0 +1,5 @@
+export * from './interface.js';
+export * from './local_key_store.js';
+export * from './node_keystore_adapter.js';
+export * from './web3signer_key_store.js';
+export * from './ha_key_store.js';