@aztec/validator-client 0.0.0-test.1 → 0.0.1-commit.023c3e5

package/src/factory.ts

@@ -1,28 +1,82 @@
+import type { BlobClientInterface } from '@aztec/blob-client/client';
 import type { EpochCache } from '@aztec/epoch-cache';
 import type { DateProvider } from '@aztec/foundation/timer';
-import type { P2P } from '@aztec/p2p';
+import type { KeystoreManager } from '@aztec/node-keystore';
+import { BlockProposalValidator, type P2PClient } from '@aztec/p2p';
+import type { L2BlockSink, L2BlockSource } from '@aztec/stdlib/block';
+import type { ValidatorClientFullConfig, WorldStateSynchronizer } from '@aztec/stdlib/interfaces/server';
+import type { L1ToL2MessageSource } from '@aztec/stdlib/messaging';
 import type { TelemetryClient } from '@aztec/telemetry-client';
 
-import { generatePrivateKey } from 'viem/accounts';
-
-import type { ValidatorClientConfig } from './config.js';
+import { BlockProposalHandler } from './block_proposal_handler.js';
+import type { FullNodeCheckpointsBuilder } from './checkpoint_builder.js';
+import { ValidatorMetrics } from './metrics.js';
 import { ValidatorClient } from './validator.js';
 
+export function createBlockProposalHandler(
+  config: ValidatorClientFullConfig,
+  deps: {
+    checkpointsBuilder: FullNodeCheckpointsBuilder;
+    worldState: WorldStateSynchronizer;
+    blockSource: L2BlockSource & L2BlockSink;
+    l1ToL2MessageSource: L1ToL2MessageSource;
+    p2pClient: P2PClient;
+    epochCache: EpochCache;
+    dateProvider: DateProvider;
+    telemetry: TelemetryClient;
+  },
+) {
+  const metrics = new ValidatorMetrics(deps.telemetry);
+  const blockProposalValidator = new BlockProposalValidator(deps.epochCache, {
+    txsPermitted: !config.disableTransactions,
+  });
+  return new BlockProposalHandler(
+    deps.checkpointsBuilder,
+    deps.worldState,
+    deps.blockSource,
+    deps.l1ToL2MessageSource,
+    deps.p2pClient.getTxProvider(),
+    blockProposalValidator,
+    deps.epochCache,
+    config,
+    metrics,
+    deps.dateProvider,
+    deps.telemetry,
+  );
+}
+
 export function createValidatorClient(
-  config: ValidatorClientConfig,
+  config: ValidatorClientFullConfig,
   deps: {
-    p2pClient: P2P;
+    checkpointsBuilder: FullNodeCheckpointsBuilder;
+    worldState: WorldStateSynchronizer;
+    p2pClient: P2PClient;
+    blockSource: L2BlockSource & L2BlockSink;
+    l1ToL2MessageSource: L1ToL2MessageSource;
     telemetry: TelemetryClient;
     dateProvider: DateProvider;
     epochCache: EpochCache;
+    keyStoreManager: KeystoreManager | undefined;
+    blobClient: BlobClientInterface;
   },
 ) {
-  if (config.disableValidator) {
+  if (config.disableValidator || !deps.keyStoreManager) {
     return undefined;
   }
-  if (config.validatorPrivateKey === undefined || config.validatorPrivateKey === '') {
-    config.validatorPrivateKey = generatePrivateKey();
-  }
 
-  return ValidatorClient.new(config, deps.epochCache, deps.p2pClient, deps.dateProvider, deps.telemetry);
+  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.dateProvider,
+    deps.telemetry,
+  );
 }

package/src/index.ts

@@ -1,3 +1,7 @@
+export * from './block_proposal_handler.js';
+export * from './checkpoint_builder.js';
 export * from './config.js';
-export * from './validator.js';
 export * from './factory.js';
+export * from './validator.js';
+export * from './key_store/index.js';
+export * from './tx_validator/index.js';

package/src/key_store/ha_key_store.ts

@@ -0,0 +1,269 @@
+/**
+ * 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/foundation/buffer';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Signature } from '@aztec/foundation/eth-signature';
+import { createLogger } from '@aztec/foundation/log';
+import type { EthRemoteSignerConfig } from '@aztec/node-keystore';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { DutyAlreadySignedError, SlashingProtectionError } from '@aztec/validator-ha-signer/errors';
+import {
+  type HAProtectedSigningContext,
+  type SigningContext,
+  isHAProtectedContext,
+} from '@aztec/validator-ha-signer/types';
+import type { ValidatorHASigner } from '@aztec/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.warn(`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 start(): Promise<void> {
+    return Promise.resolve(this.haSigner.start());
+  }
+
+  /**
+   * Stop the high-availability key store
+   */
+  public async stop() {
+    await this.haSigner.stop();
+  }
+}

package/src/key_store/index.ts

@@ -1,2 +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';

package/src/key_store/interface.ts

@@ -1,6 +1,11 @@
 import type { Buffer32 } from '@aztec/foundation/buffer';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
+import type { EthRemoteSignerConfig } from '@aztec/node-keystore';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { SigningContext } from '@aztec/validator-ha-signer/types';
+
+import type { TypedDataDefinition } from 'viem';
 
 /** Key Store
  *
@@ -8,19 +13,109 @@ import type { Signature } from '@aztec/foundation/eth-signature';
  */
 export interface ValidatorKeyStore {
   /**
-   * Get the address of the signer
+   * Get the address of a signer by index
    *
+   * @param index - The index of the signer
    * @returns the address
    */
-  getAddress(): EthAddress;
+  getAddress(index: number): EthAddress;
+
+  /**
+   * Get all addresses
+   *
+   * @returns all addresses
+   */
+  getAddresses(): EthAddress[];
+
+  /**
+   * Sign typed data with all keystore private keys
+   * @param typedData - The complete EIP-712 typed data structure
+   * @param context - Signing context for HA slashing protection
+   * @returns signatures (when context provided with HA, only successfully claimed signatures are returned)
+   */
+  signTypedData(typedData: TypedDataDefinition, context: SigningContext): Promise<Signature[]>;
+
+  /**
+   * Sign typed data with a specific address's private key
+   * @param address - The address of the signer to use
+   * @param typedData - The complete EIP-712 typed data structure
+   * @param context - Signing context for HA slashing protection
+   * @returns signature
+   */
+  signTypedDataWithAddress(
+    address: EthAddress,
+    typedData: TypedDataDefinition,
+    context: SigningContext,
+  ): Promise<Signature>;
 
-  sign(message: Buffer32): Promise<Signature>;
   /**
    * Flavor of sign message that followed EIP-712 eth signed message prefix
    * Note: this is only required when we are using ecdsa signatures over secp256k1
    *
    * @param message - The message to sign.
-   * @returns The signature.
+   * @param context - Signing context for HA slashing protection
+   * @returns The signatures (when context provided with HA, only successfully claimed signatures are returned).
+   */
+  signMessage(message: Buffer32, context: SigningContext): Promise<Signature[]>;
+
+  /**
+   * Sign a message with a specific address's private key
+   * @param address - The address of the signer to use
+   * @param message - The message to sign
+   * @param context - Signing context for HA slashing protection
+   * @returns signature
+   */
+  signMessageWithAddress(address: EthAddress, message: Buffer32, context: SigningContext): Promise<Signature>;
+}
+
+/**
+ * Extended ValidatorKeyStore interface that supports the new keystore configuration model
+ * with role-based address management (attester, coinbase, publisher, fee recipient)
+ */
+export interface ExtendedValidatorKeyStore extends ValidatorKeyStore {
+  /**
+   * Get all attester addresses (maps to existing getAddresses())
+   * @returns all attester addresses
+   */
+  getAttesterAddresses(): EthAddress[];
+
+  /**
+   * Get the coinbase address for a specific attester
+   * Falls back to the attester address if not set
+   * @param attesterAddress - The attester address to find the coinbase for
+   * @returns the coinbase address
+   */
+  getCoinbaseAddress(attesterAddress: EthAddress): EthAddress;
+
+  /**
+   * Get all publisher addresses for a specific attester (EOAs used for sending block proposal L1 txs)
+   * Falls back to the attester addresses if not set
+   * @param attesterAddress - The attester address to find the publishers for
+   * @returns all publisher addresses for this validator
+   */
+  getPublisherAddresses(attesterAddress: EthAddress): EthAddress[];
+
+  /**
+   * Get the fee recipient address for a specific attester
+   * @param attesterAddress - The attester address to find the fee recipient for
+   * @returns the fee recipient address
+   */
+  getFeeRecipient(attesterAddress: EthAddress): AztecAddress;
+
+  /**
+   * Get the remote signer configuration for a specific attester if available
+   * @param attesterAddress - The attester address to find the remote signer config for
+   * @returns the remote signer configuration or undefined
+   */
+  getRemoteSignerConfig(attesterAddress: EthAddress): EthRemoteSignerConfig | undefined;
+
+  /**
+   * Start the key store
+   */
+  start(): Promise<void>;
+
+  /**
+   * Stop the key store
    */
-  signMessage(message: Buffer32): Promise<Signature>;
+  stop(): Promise<void>;
 }

package/src/key_store/local_key_store.ts

@@ -1,46 +1,105 @@
-import type { Buffer32 } from '@aztec/foundation/buffer';
-import { Secp256k1Signer } from '@aztec/foundation/crypto';
+import { Buffer32 } from '@aztec/foundation/buffer';
+import { Secp256k1Signer } from '@aztec/foundation/crypto/secp256k1-signer';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import type { Signature } from '@aztec/foundation/eth-signature';
+import type { SigningContext } from '@aztec/validator-ha-signer/types';
+
+import { type TypedDataDefinition, hashTypedData } from 'viem';
 
 import type { ValidatorKeyStore } from './interface.js';
 
 /**
  * Local Key Store
  *
- * An implementation of the Key store using an in memory private key.
+ * An implementation of the Key store using in memory private keys.
  */
 export class LocalKeyStore implements ValidatorKeyStore {
-  private signer: Secp256k1Signer;
+  private signers: Secp256k1Signer[];
+  private signersByAddress: Map<`0x${string}`, Secp256k1Signer>;
 
-  constructor(privateKey: Buffer32) {
-    this.signer = new Secp256k1Signer(privateKey);
+  constructor(privateKeys: Buffer32[]) {
+    this.signers = privateKeys.map(privateKey => new Secp256k1Signer(privateKey));
+    this.signersByAddress = new Map(this.signers.map(signer => [signer.address.toString(), signer]));
   }
 
   /**
-   * Get the address of the signer
+   * Get the address of a signer by index
    *
+   * @param index - The index of the signer
    * @returns the address
    */
-  public getAddress(): EthAddress {
-    return this.signer.address;
+  public getAddress(index: number): EthAddress {
+    if (index >= this.signers.length) {
+      throw new Error(`Index ${index} is out of bounds.`);
+    }
+    return this.signers[index].address;
   }
 
   /**
-   * Sign a message with the keystore private key
+   * Get the addresses of all signers
    *
-   * @param messageBuffer - The message buffer to sign
+   * @returns the addresses
+   */
+  public getAddresses(): EthAddress[] {
+    return this.signers.map(signer => signer.address);
+  }
+
+  /**
+   * Sign a message with all keystore private keys
+   * @param typedData - The complete EIP-712 typed data structure (domain, types, primaryType, message)
+   * @param _context - Signing context (ignored by LocalKeyStore, used for HA protection)
    * @return signature
    */
-  public sign(digest: Buffer32): Promise<Signature> {
-    const signature = this.signer.sign(digest);
+  public signTypedData(typedData: TypedDataDefinition, _context: SigningContext): Promise<Signature[]> {
+    const digest = hashTypedData(typedData);
+    return Promise.all(this.signers.map(signer => signer.sign(Buffer32.fromString(digest))));
+  }
 
-    return Promise.resolve(signature);
+  /**
+   * Sign a message with a specific address's private key
+   * @param address - The address of the signer to use
+   * @param typedData - The complete EIP-712 typed data structure (domain, types, primaryType, message)
+   * @param _context - Signing context (ignored by LocalKeyStore, used for HA protection)
+   * @returns signature for the specified address
+   * @throws Error if the address is not found in the keystore
+   */
+  public signTypedDataWithAddress(
+    address: EthAddress,
+    typedData: TypedDataDefinition,
+    _context: SigningContext,
+  ): Promise<Signature> {
+    const signer = this.signersByAddress.get(address.toString());
+    if (!signer) {
+      throw new Error(`No signer found for address ${address.toString()}`);
+    }
+    const digest = hashTypedData(typedData);
+    return Promise.resolve(signer.sign(Buffer32.fromString(digest)));
   }
 
-  public signMessage(message: Buffer32): Promise<Signature> {
-    // Sign message adds eth sign prefix and hashes before signing
-    const signature = this.signer.signMessage(message);
-    return Promise.resolve(signature);
+  /**
+   * Sign a message using eth_sign with all keystore private keys
+   *
+   * @param message - The message to sign
+   * @param _context - Signing context (ignored by LocalKeyStore, used for HA protection)
+   * @return signatures
+   */
+  public signMessage(message: Buffer32, _context: SigningContext): Promise<Signature[]> {
+    return Promise.all(this.signers.map(signer => signer.signMessage(message)));
+  }
+
+  /**
+   * Sign a message using eth_sign with a specific address's private key
+   * @param address - The address of the signer to use
+   * @param message - The message to sign
+   * @param _context - Signing context (ignored by LocalKeyStore, used for HA protection)
+   * @returns signature for the specified address
+   * @throws Error if the address is not found in the keystore
+   */
+  public signMessageWithAddress(address: EthAddress, message: Buffer32, _context: SigningContext): Promise<Signature> {
+    const signer = this.signersByAddress.get(address.toString());
+    if (!signer) {
+      throw new Error(`No signer found for address ${address.toString()}`);
+    }
+    return Promise.resolve(signer.signMessage(message));
   }
 }