@aztec/node-keystore 4.0.0-nightly.20250907 → 4.0.0-nightly.20260107

package/src/loader.ts

@@ -3,10 +3,13 @@
  *
  * Handles loading and parsing keystore configuration files.
  */
+import { EthAddress } from '@aztec/foundation/eth-address';
 import { createLogger } from '@aztec/foundation/log';
+import type { Hex } from '@aztec/foundation/string';
 
 import { readFileSync, readdirSync, statSync } from 'fs';
 import { extname, join } from 'path';
+import { privateKeyToAddress } from 'viem/accounts';
 
 import { keystoreSchema } from './schemas.js';
 import type { EthAccounts, KeyStore } from './types.js';
@@ -39,7 +42,7 @@ export function loadKeystoreFile(filePath: string): KeyStore {
     const content = readFileSync(filePath, 'utf-8');
 
     // Parse JSON and validate with Zod schema (following Aztec patterns)
-    return keystoreSchema.parse(JSON.parse(content)) as KeyStore;
+    return keystoreSchema.parse(JSON.parse(content));
   } catch (error) {
     if (error instanceof SyntaxError) {
       throw new KeyStoreLoadError('Invalid JSON format', filePath, error);
@@ -205,12 +208,18 @@ export function mergeKeystores(keystores: KeyStore[]): KeyStore {
   // Track attester addresses to prevent duplicates
   const attesterAddresses = new Set<string>();
 
+  // Determine schema version: use v2 if any input is v2
+  const schemaVersion = keystores.some(ks => ks.schemaVersion === 2) ? 2 : 1;
+
   const merged: KeyStore = {
-    schemaVersion: 1,
+    schemaVersion,
     validators: [],
     slasher: undefined,
     remoteSigner: undefined,
     prover: undefined,
+    publisher: undefined,
+    coinbase: undefined,
+    feeRecipient: undefined,
   };
 
   for (let i = 0; i < keystores.length; i++) {
@@ -220,8 +229,9 @@ export function mergeKeystores(keystores: KeyStore[]): KeyStore {
     if (keystore.validators) {
       for (const validator of keystore.validators) {
         // Check for duplicate attester addresses
-        const attesterKeys = extractAttesterKeys(validator.attester);
-        for (const key of attesterKeys) {
+        const attesterKeys = extractAttesterAddresses(validator.attester);
+        for (let key of attesterKeys) {
+          key = key.toLowerCase();
           if (attesterAddresses.has(key)) {
             throw new KeyStoreLoadError(
               `Duplicate attester address ${key} found across keystore files`,
@@ -230,8 +240,18 @@ export function mergeKeystores(keystores: KeyStore[]): KeyStore {
           }
           attesterAddresses.add(key);
         }
+
+        // When merging v1 validators into a v2+ result, preserve original fallback behavior
+        // by explicitly setting publisher/coinbase/feeRecipient if they're missing
+        if (keystore.schemaVersion !== schemaVersion) {
+          throw new KeyStoreLoadError(
+            `Cannot merge keystores with different schema versions: ${keystore.schemaVersion} and ${schemaVersion}`,
+            `keystores[${i}].schemaVersion`,
+          );
+        } else {
+          merged.validators!.push(validator);
+        }
       }
-      merged.validators!.push(...keystore.validators);
     }
 
     // Merge slasher (accumulate all)
@@ -264,6 +284,45 @@ export function mergeKeystores(keystores: KeyStore[]): KeyStore {
       }
       merged.prover = keystore.prover;
     }
+
+    // Merge top-level publisher (accumulate all, unless conflicting MnemonicConfigs)
+    if (keystore.publisher) {
+      if (!merged.publisher) {
+        merged.publisher = keystore.publisher;
+      } else {
+        const isMnemonic = (accounts: EthAccounts): boolean =>
+          typeof accounts === 'object' && accounts !== null && 'mnemonic' in accounts;
+
+        // If either is a mnemonic, warn and use last one (can't merge mnemonics)
+        if (isMnemonic(merged.publisher) || isMnemonic(keystore.publisher)) {
+          logger.warn(
+            'Multiple default publisher configurations found with mnemonic, using the last one (cannot merge mnemonics)',
+          );
+          merged.publisher = keystore.publisher;
+        } else {
+          // Both are non-mnemonic, accumulate them
+          const toArray = (accounts: EthAccounts): unknown[] => (Array.isArray(accounts) ? accounts : [accounts]);
+          const combined = [...toArray(merged.publisher), ...toArray(keystore.publisher)];
+          merged.publisher = combined as unknown as EthAccounts;
+        }
+      }
+    }
+
+    // Merge top-level coinbase (last one wins, but warn about conflicts)
+    if (keystore.coinbase) {
+      if (merged.coinbase) {
+        logger.warn('Multiple default coinbase addresses found, using the last one');
+      }
+      merged.coinbase = keystore.coinbase;
+    }
+
+    // Merge top-level feeRecipient (last one wins, but warn about conflicts)
+    if (keystore.feeRecipient) {
+      if (merged.feeRecipient) {
+        logger.warn('Multiple default feeRecipient addresses found, using the last one');
+      }
+      merged.feeRecipient = keystore.feeRecipient;
+    }
   }
 
   // Clean up empty arrays
@@ -284,18 +343,43 @@ export function mergeKeystores(keystores: KeyStore[]): KeyStore {
  * @param attester The attester configuration in any supported shape.
  * @returns Array of string keys used to detect duplicates.
  */
-function extractAttesterKeys(attester: unknown): string[] {
+function extractAttesterAddresses(attester: unknown): string[] {
+  // String forms (private key or other) - return as-is for coarse uniqueness
   if (typeof attester === 'string') {
-    return [attester];
+    if (attester.length === 66) {
+      return [privateKeyToAddress(attester as Hex<32>)];
+    } else {
+      return [attester];
+    }
   }
 
+  // Arrays of attester items
   if (Array.isArray(attester)) {
-    return attester.map(a => (typeof a === 'string' ? a : JSON.stringify(a)));
+    const keys: string[] = [];
+    for (const item of attester) {
+      keys.push(...extractAttesterAddresses(item));
+    }
+    return keys;
   }
 
-  if (attester && typeof attester === 'object' && 'address' in attester) {
-    return [(attester as { address: string }).address];
+  if (attester && typeof attester === 'object') {
+    if (attester instanceof EthAddress) {
+      return [attester.toString()];
+    }
+
+    const obj = attester as Record<string, unknown>;
+
+    // New shape: { eth: EthAccount, bls?: BLSAccount }
+    if ('eth' in obj) {
+      return extractAttesterAddresses(obj.eth);
+    }
+
+    // Remote signer account object shape: { address, remoteSignerUrl?, ... }
+    if ('address' in obj) {
+      return [String((obj as any).address)];
+    }
   }
 
-  return [JSON.stringify(attester)];
+  // mnemonic, encrypted file just disable early duplicates checking
+  return [];
 }

package/src/schemas.ts

@@ -1,98 +1,175 @@
 /**
  * Zod schemas for keystore validation using Aztec's validation functions
  */
-import { EthAddress } from '@aztec/foundation/eth-address';
+import { optional, schemas } from '@aztec/foundation/schemas';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 
 import { z } from 'zod';
 
+import type { BLSPrivateKey, EthPrivateKey } from './types.js';
+
 // Use Aztec's validation functions but return string types to match our TypeScript interfaces
-const ethAddressSchema = z.string().refine(EthAddress.isAddress, 'Invalid Ethereum address');
-const ethPrivateKeySchema = z
+export const ethPrivateKeySchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid private key (must be 32 bytes with 0x prefix)')
+  .transform(s => s as EthPrivateKey);
+export const blsPrivateKeySchema = z
   .string()
-  .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid private key (must be 32 bytes with 0x prefix)');
-const aztecAddressSchema = z.string().refine(AztecAddress.isAddress, 'Invalid Aztec address');
+  .regex(/^0x[0-9a-fA-F]{64}$/, 'Invalid BLS private key (must be 32 bytes with 0x prefix)')
+  .transform(s => s as BLSPrivateKey);
 const urlSchema = z.string().url('Invalid URL');
 
 // Remote signer config schema
 const remoteSignerConfigSchema = z.union([
   urlSchema,
-  z.object({
-    remoteSignerUrl: urlSchema,
-    certPath: z.string().nullish(),
-    certPass: z.string().nullish(),
-  }),
+  z
+    .object({
+      remoteSignerUrl: urlSchema,
+      certPath: optional(z.string()),
+      certPass: optional(z.string()),
+    })
+    .strict(),
 ]);
 
 // Remote signer account schema
 const remoteSignerAccountSchema = z.union([
-  ethAddressSchema,
-  z.object({
-    address: ethAddressSchema,
-    remoteSignerUrl: urlSchema.nullish(),
-    certPath: z.string().nullish(),
-    certPass: z.string().nullish(),
-  }),
+  schemas.EthAddress,
+  z
+    .object({
+      address: schemas.EthAddress,
+      remoteSignerUrl: urlSchema,
+      certPath: optional(z.string()),
+      certPass: optional(z.string()),
+    })
+    .strict(),
 ]);
 
-// JSON V3 keystore schema
-const jsonKeyFileV3Schema = z.object({
-  path: z.string(),
-  password: z.string().nullish(),
-});
+// Encrypted keystore file schema (used for both JSON V3 ETH keys and EIP-2335 BLS keys)
+const encryptedKeyFileSchema = z
+  .object({
+    path: z.string(),
+    password: optional(z.string()),
+  })
+  .strict();
 
 // Mnemonic config schema
-const mnemonicConfigSchema = z.object({
-  mnemonic: z.string().min(1, 'Mnemonic cannot be empty'),
-  addressIndex: z.number().int().min(0).default(0),
-  accountIndex: z.number().int().min(0).default(0),
-  addressCount: z.number().int().min(1).default(1),
-  accountCount: z.number().int().min(1).default(1),
-});
+const mnemonicConfigSchema = z
+  .object({
+    mnemonic: z.string().min(1, 'Mnemonic cannot be empty'),
+    addressIndex: z.number().int().min(0).default(0),
+    accountIndex: z.number().int().min(0).default(0),
+    addressCount: z.number().int().min(1).default(1),
+    accountCount: z.number().int().min(1).default(1),
+  })
+  .strict();
 
 // EthAccount schema
-const ethAccountSchema = z.union([
-  ethPrivateKeySchema,
-  remoteSignerAccountSchema,
-  jsonKeyFileV3Schema,
-  mnemonicConfigSchema,
-]);
+const ethAccountSchema = z.union([ethPrivateKeySchema, remoteSignerAccountSchema, encryptedKeyFileSchema]);
 
 // EthAccounts schema
-const ethAccountsSchema = z.union([ethAccountSchema, z.array(ethAccountSchema)]);
+const ethAccountsSchema = z.union([ethAccountSchema, z.array(ethAccountSchema), mnemonicConfigSchema]);
+
+// BLSAccount schema
+const blsAccountSchema = z.union([blsPrivateKeySchema, encryptedKeyFileSchema]);
+
+// AttesterAccount schema: either EthAccount or { eth: EthAccount, bls?: BLSAccount }
+const attesterAccountSchema = z.union([
+  ethAccountSchema,
+  z
+    .object({
+      eth: ethAccountSchema,
+      bls: optional(blsAccountSchema),
+    })
+    .strict(),
+]);
+
+// AttesterAccounts schema: AttesterAccount | AttesterAccount[] | MnemonicConfig
+const attesterAccountsSchema = z.union([attesterAccountSchema, z.array(attesterAccountSchema), mnemonicConfigSchema]);
 
 // Prover keystore schema
 const proverKeyStoreSchema = z.union([
   ethAccountSchema,
-  z.object({
-    id: ethAddressSchema,
-    publisher: ethAccountsSchema,
-  }),
+  z
+    .object({
+      id: schemas.EthAddress,
+      publisher: ethAccountsSchema,
+    })
+    .strict(),
 ]);
 
-// Validator keystore schema
-const validatorKeyStoreSchema = z.object({
-  attester: ethAccountsSchema,
-  coinbase: ethAddressSchema.nullish(),
-  publisher: ethAccountsSchema.nullish(),
-  feeRecipient: aztecAddressSchema,
-  remoteSigner: remoteSignerConfigSchema.nullish(),
-  fundingAccount: ethAccountSchema.nullish(),
-});
-
-// Main keystore schema
-export const keystoreSchema = z
+// Validator keystore schema for v1 (feeRecipient required)
+const validatorKeyStoreSchemaV1 = z
+  .object({
+    attester: attesterAccountsSchema,
+    coinbase: optional(schemas.EthAddress),
+    publisher: optional(ethAccountsSchema),
+    feeRecipient: AztecAddress.schema,
+    remoteSigner: optional(remoteSignerConfigSchema),
+    fundingAccount: optional(ethAccountSchema),
+  })
+  .strict();
+
+// Validator keystore schema for v2 (feeRecipient optional, can fall back to top-level)
+const validatorKeyStoreSchemaV2 = z
+  .object({
+    attester: attesterAccountsSchema,
+    coinbase: optional(schemas.EthAddress),
+    publisher: optional(ethAccountsSchema),
+    feeRecipient: optional(AztecAddress.schema),
+    remoteSigner: optional(remoteSignerConfigSchema),
+    fundingAccount: optional(ethAccountSchema),
+  })
+  .strict();
+
+// Schema v1 - original format
+const keystoreSchemaV1 = z
   .object({
     schemaVersion: z.literal(1),
-    validators: z.array(validatorKeyStoreSchema).nullish(),
-    slasher: ethAccountsSchema.nullish(),
-    remoteSigner: remoteSignerConfigSchema.nullish(),
-    prover: proverKeyStoreSchema.nullish(),
-    fundingAccount: ethAccountSchema.nullish(),
+    validators: optional(z.array(validatorKeyStoreSchemaV1)),
+    slasher: optional(ethAccountsSchema),
+    remoteSigner: optional(remoteSignerConfigSchema),
+    prover: optional(proverKeyStoreSchema),
+    fundingAccount: optional(ethAccountSchema),
   })
+  .strict()
   .refine(data => data.validators || data.prover, {
     message: 'Keystore must have at least validators or prover configuration',
     path: ['root'],
   });
 
-export type KeyStoreSchema = z.infer<typeof keystoreSchema>;
+// Schema v2 - adds top-level publisher, coinbase, feeRecipient
+const keystoreSchemaV2 = z
+  .object({
+    schemaVersion: z.literal(2),
+    validators: optional(z.array(validatorKeyStoreSchemaV2)),
+    slasher: optional(ethAccountsSchema),
+    remoteSigner: optional(remoteSignerConfigSchema),
+    prover: optional(proverKeyStoreSchema),
+    fundingAccount: optional(ethAccountSchema),
+    publisher: optional(ethAccountsSchema),
+    coinbase: optional(schemas.EthAddress),
+    feeRecipient: optional(AztecAddress.schema),
+  })
+  .strict()
+  .refine(data => data.validators || data.prover, {
+    message: 'Keystore must have at least validators or prover configuration',
+    path: ['root'],
+  })
+  .refine(
+    data => {
+      // If validators are present, ensure each validator has a feeRecipient or there's a top-level feeRecipient
+      if (data.validators) {
+        const hasTopLevelFeeRecipient = !!data.feeRecipient;
+        const allValidatorsHaveFeeRecipient = data.validators.every(v => v.feeRecipient);
+        return hasTopLevelFeeRecipient || allValidatorsHaveFeeRecipient;
+      }
+      return true;
+    },
+    {
+      message: 'Each validator must have a feeRecipient, or a top-level feeRecipient must be set for all validators',
+      path: ['feeRecipient'],
+    },
+  );
+
+// Main keystore schema - accepts both v1 and v2
+export const keystoreSchema = z.union([keystoreSchemaV1, keystoreSchemaV2]);

package/src/signer.ts

@@ -3,13 +3,14 @@
  *
  * Common interface for different signing backends (local, remote, encrypted)
  */
-import type { EthSigner } from '@aztec/ethereum';
+import type { EthSigner } from '@aztec/ethereum/eth-signer';
 import { Buffer32 } from '@aztec/foundation/buffer';
-import { Secp256k1Signer, randomBytes, toRecoveryBit } from '@aztec/foundation/crypto';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import { Secp256k1Signer, toRecoveryBit } from '@aztec/foundation/crypto/secp256k1-signer';
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { Signature, type ViemTransactionSignature } from '@aztec/foundation/eth-signature';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
-import { withHexPrefix } from '@aztec/foundation/string';
+import { bufferToHex, withHexPrefix } from '@aztec/foundation/string';
 
 import {
   type TransactionSerializable,
@@ -104,6 +105,82 @@ export class RemoteSigner implements EthSigner {
     private fetch: typeof globalThis.fetch = globalThis.fetch,
   ) {}
 
+  /**
+   * Validates that a web3signer is accessible and that the given addresses are available.
+   * @param remoteSignerUrl - The URL of the web3signer (can be string or EthRemoteSignerConfig)
+   * @param addresses - The addresses to check for availability
+   * @param fetch - Optional fetch implementation for testing
+   * @throws Error if the web3signer is not accessible or if any address is not available
+   */
+  static async validateAccess(
+    remoteSignerUrl: EthRemoteSignerConfig,
+    addresses: string[],
+    fetch: typeof globalThis.fetch = globalThis.fetch,
+  ): Promise<void> {
+    const url = typeof remoteSignerUrl === 'string' ? remoteSignerUrl : remoteSignerUrl.remoteSignerUrl;
+
+    try {
+      // Check if the web3signer is reachable by calling eth_accounts
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'eth_accounts',
+          params: [],
+          id: 1,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new SignerError(
+          `Web3Signer validation failed: ${response.status} ${response.statusText} - ${errorText}`,
+          'eth_accounts',
+          url,
+          response.status,
+        );
+      }
+
+      const result = await response.json();
+
+      if (result.error) {
+        throw new SignerError(
+          `Web3Signer JSON-RPC error during validation: ${result.error.code} - ${result.error.message}`,
+          'eth_accounts',
+          url,
+          200,
+          result.error.code,
+        );
+      }
+
+      if (!result.result || !Array.isArray(result.result)) {
+        throw new Error('Invalid response from Web3Signer: expected array of accounts');
+      }
+
+      // Normalize addresses to lowercase for comparison
+      const availableAccounts: string[] = result.result.map((addr: string) => addr.toLowerCase());
+      const requestedAddresses = addresses.map(addr => addr.toLowerCase());
+
+      // Check if all requested addresses are available
+      const missingAddresses = requestedAddresses.filter(addr => !availableAccounts.includes(addr));
+
+      if (missingAddresses.length > 0) {
+        throw new Error(`The following addresses are not available in the web3signer: ${missingAddresses.join(', ')}`);
+      }
+    } catch (error: any) {
+      if (error instanceof SignerError) {
+        throw error;
+      }
+      if (error.code === 'ECONNREFUSED' || error.cause?.code === 'ECONNREFUSED') {
+        throw new Error(`Unable to connect to web3signer at ${url}. Please ensure it is running and accessible.`);
+      }
+      throw error;
+    }
+  }
+
   /**
    * Sign a message using eth_sign via remote JSON-RPC.
    */
@@ -167,10 +244,6 @@ export class RemoteSigner implements EthSigner {
    * Make a JSON-RPC eth_signTransaction request.
    */
   private async makeJsonRpcSignTransactionRequest(tx: TransactionSerializable): Promise<Signature> {
-    if (tx.type !== 'eip1559') {
-      throw new Error('This signer does not support tx type: ' + tx.type);
-    }
-
     const txObject: RemoteSignerTxObject = {
       from: this.address.toString(),
       to: tx.to ?? null,
@@ -184,10 +257,10 @@ export class RemoteSigner implements EthSigner {
           ? withHexPrefix(tx.maxPriorityFeePerGas.toString(16))
           : undefined,
 
-      // maxFeePerBlobGas:
-      //   typeof tx.maxFeePerBlobGas !== 'undefined' ? withHexPrefix(tx.maxFeePerBlobGas.toString(16)) : undefined,
-      // blobVersionedHashes: tx.blobVersionedHashes,
-      // blobs: tx.blobs?.map(blob => (typeof blob === 'string' ? blob : bufferToHex(Buffer.from(blob)))),
+      maxFeePerBlobGas:
+        typeof tx.maxFeePerBlobGas !== 'undefined' ? withHexPrefix(tx.maxFeePerBlobGas.toString(16)) : undefined,
+      blobVersionedHashes: tx.blobVersionedHashes,
+      blobs: tx.blobs?.map(blob => (typeof blob === 'string' ? blob : bufferToHex(Buffer.from(blob)))),
     };
 
     let rawTxHex = await this.makeJsonRpcRequest('eth_signTransaction', txObject);

package/src/types.ts

@@ -5,21 +5,23 @@
  * These types define the JSON structure for configuring validators, provers, and
  * their associated keys and addresses.
  */
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Hex } from '@aztec/foundation/string';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
 
-/** Parameterized hex string type for specific byte lengths */
-export type Hex<TByteLength extends number> = `0x${string}` & { readonly _length: TByteLength };
-
-/** A json keystore config points to a local file with the encrypted private key, and may require a password for decrypting it */
-export type EthJsonKeyFileV3Config = { path: string; password?: string };
+/**
+ * An encrypted keystore file config points to a local file with an encrypted private key.
+ * The file may be in different formats:
+ * - JSON V3 format for ETH keys (Ethereum wallet standard)
+ * - EIP-2335 format for BLS keys (Ethereum 2.0 validator standard)
+ */
+export type EncryptedKeyFileConfig = { path: string; password?: string };
 
 /** A private key is a 32-byte 0x-prefixed hex */
 export type EthPrivateKey = Hex<32>;
 
-/** An address is a 20-byte 0x-prefixed hex */
-export type EthAddressHex = Hex<20>;
-
-/** An Aztec address is a 32-byte 0x-prefixed hex */
-export type AztecAddressHex = Hex<32>;
+/** A BLS private key is a 32-byte 0x-prefixed hex */
+export type BLSPrivateKey = Hex<32>;
 
 /** URL type for remote signers */
 export type Url = string;
@@ -40,19 +42,19 @@ export type EthRemoteSignerConfig =
  * If only the address is set, then the default remote signer config from the parent config is used.
  */
 export type EthRemoteSignerAccount =
-  | EthAddressHex
+  | EthAddress
   | {
-      address: EthAddressHex;
-      remoteSignerUrl?: Url;
+      address: EthAddress;
+      remoteSignerUrl: Url;
       certPath?: string;
       certPass?: string;
     };
 
-/** An L1 account is a private key, a remote signer configuration, or a standard json key store file */
-export type EthAccount = EthPrivateKey | EthRemoteSignerAccount | EthJsonKeyFileV3Config;
+/** An L1 account is a private key, a remote signer configuration, or an encrypted keystore file (JSON V3 format) */
+export type EthAccount = EthPrivateKey | EthRemoteSignerAccount | EncryptedKeyFileConfig;
 
 /** A mnemonic can be used to define a set of accounts */
-export type EthMnemonicConfig = {
+export type MnemonicConfig = {
   mnemonic: string;
   addressIndex?: number;
   accountIndex?: number;
@@ -61,37 +63,47 @@ export type EthMnemonicConfig = {
 };
 
 /** One or more L1 accounts */
-export type EthAccounts = EthAccount | EthAccount[] | EthMnemonicConfig;
+export type EthAccounts = EthAccount | EthAccount[] | MnemonicConfig;
 
-export type ProverKeyStore =
-  | {
-      /** Address that identifies the prover. This address will receive the rewards. */
-      id: EthAddressHex;
-      /** One or more EOAs used for sending proof L1 txs. */
-      publisher: EthAccounts;
-    }
-  | EthAccount;
+export type ProverKeyStoreWithId = {
+  /** Address that identifies the prover. This address will receive the rewards. */
+  id: EthAddress;
+  /** One or more EOAs used for sending proof L1 txs. */
+  publisher: EthAccounts;
+};
+
+export type ProverKeyStore = ProverKeyStoreWithId | EthAccount;
+
+/** A BLS account is either a private key, or an EIP-2335 encrypted keystore file */
+export type BLSAccount = BLSPrivateKey | EncryptedKeyFileConfig;
+
+/** An AttesterAccount is a combined EthAccount and optional BLSAccount */
+export type AttesterAccount = { eth: EthAccount; bls?: BLSAccount } | EthAccount;
+
+/** One or more attester accounts combining ETH and BLS keys */
+export type AttesterAccounts = AttesterAccount | AttesterAccount[] | MnemonicConfig;
 
 export type ValidatorKeyStore = {
   /**
    * One or more validator attester keys to handle in this configuration block.
    * An attester address may only appear once across all configuration blocks across all keystore files.
    */
-  attester: EthAccounts;
+  attester: AttesterAccounts;
   /**
    * Coinbase address to use when proposing an L2 block as any of the validators in this configuration block.
-   * Falls back to the attester address if not set.
+   * Falls back to the keystore-level coinbase, then to the attester address if not set.
    */
-  coinbase?: EthAddressHex;
+  coinbase?: EthAddress;
   /**
    * One or more EOAs used for sending block proposal L1 txs for all validators in this configuration block.
-   * Falls back to the attester account if not set.
+   * Falls back to the keystore-level publisher, then to the attester account if not set.
    */
   publisher?: EthAccounts;
   /**
    * Fee recipient address to use when proposing an L2 block as any of the validators in this configuration block.
+   * Falls back to the keystore-level feeRecipient if not set.
    */
-  feeRecipient: AztecAddressHex;
+  feeRecipient?: AztecAddress;
   /**
    * Default remote signer for all accounts in this block.
    */
@@ -103,8 +115,8 @@ export type ValidatorKeyStore = {
 };
 
 export type KeyStore = {
-  /** Schema version of this keystore file (initially 1). */
-  schemaVersion: number;
+  /** Schema version of this keystore file (1 or 2). */
+  schemaVersion: 1 | 2;
   /** Validator configurations. */
   validators?: ValidatorKeyStore[];
   /** One or more accounts used for creating slash payloads on L1. Does not create slash payloads if not set. */
@@ -115,4 +127,10 @@ export type KeyStore = {
   prover?: ProverKeyStore;
   /** Used for automatically funding publisher accounts if there is none defined in the corresponding  ValidatorKeyStore*/
   fundingAccount?: EthAccount;
+  /** Default publisher accounts for all validators in this keystore. Can be overridden by individual validator configs. */
+  publisher?: EthAccounts;
+  /** Default coinbase address for all validators in this keystore. Can be overridden by individual validator configs. */
+  coinbase?: EthAddress;
+  /** Default fee recipient address for all validators in this keystore. Can be overridden by individual validator configs. */
+  feeRecipient?: AztecAddress;
 };