@aztec/foundation 0.0.1-fake-c83136db25 → 0.0.2-commit.217f559981

package/src/config/env_var.ts

@@ -12,6 +12,9 @@ export type EnvVar =
   | 'ARCHIVER_VIEM_POLLING_INTERVAL_MS'
   | 'ARCHIVER_BATCH_SIZE'
   | 'AZTEC_ADMIN_PORT'
+  | 'AZTEC_ADMIN_API_KEY_HASH'
+  | 'AZTEC_DISABLE_ADMIN_API_KEY'
+  | 'AZTEC_RESET_ADMIN_API_KEY'
   | 'AZTEC_NODE_ADMIN_URL'
   | 'AZTEC_NODE_URL'
   | 'AZTEC_PORT'
@@ -21,12 +24,13 @@ export type EnvVar =
   | 'BB_NUM_IVC_VERIFIERS'
   | 'BB_IVC_CONCURRENCY'
   | 'BOOTSTRAP_NODES'
-  | 'BLOB_SINK_ARCHIVE_API_URL'
-  | 'BLOB_SINK_PORT'
-  | 'BLOB_SINK_URL'
+  | 'BLOB_ARCHIVE_API_URL'
+  | 'BLOB_FILE_STORE_URLS'
+  | 'BLOB_FILE_STORE_UPLOAD_URL'
+  | 'BLOB_HEALTHCHECK_UPLOAD_INTERVAL_MINUTES'
   | 'BOT_DA_GAS_LIMIT'
   | 'BOT_FEE_PAYMENT_METHOD'
-  | 'BOT_BASE_FEE_PADDING'
+  | 'BOT_MIN_FEE_PADDING'
   | 'BOT_FLUSH_SETUP_TRANSACTIONS'
   | 'BOT_FOLLOW_CHAIN'
   | 'BOT_L2_GAS_LIMIT'
@@ -46,7 +50,10 @@ export type EnvVar =
   | 'BOT_TX_MINED_WAIT_SECONDS'
   | 'BOT_MAX_CONSECUTIVE_ERRORS'
   | 'BOT_STOP_WHEN_UNHEALTHY'
-  | 'BOT_AMM_TXS'
+  | 'BOT_MODE'
+  | 'BOT_L2_TO_L1_MESSAGES_PER_TX'
+  | 'BOT_L1_TO_L2_SEED_COUNT'
+  | 'BOT_L1_TO_L2_SEED_INTERVAL'
   | 'COINBASE'
   | 'CRS_PATH'
   | 'DATA_DIRECTORY'
@@ -63,8 +70,10 @@ export type EnvVar =
   | 'PUBLIC_DATA_TREE_MAP_SIZE_KB'
   | 'DEBUG'
   | 'DEBUG_P2P_DISABLE_COLOCATION_PENALTY'
-  | 'DEPLOY_AZTEC_CONTRACTS_SALT'
+  | 'ENABLE_PROVER_NODE'
   | 'ETHEREUM_HOSTS'
+  | 'ETHEREUM_DEBUG_HOSTS'
+  | 'ETHEREUM_ALLOW_NO_DEBUG_HOSTS'
   | 'FEE_RECIPIENT'
   | 'FORCE_COLOR'
   | 'GOVERNANCE_PROPOSER_PAYLOAD_ADDRESS'
@@ -75,6 +84,7 @@ export type EnvVar =
   | 'L1_CONSENSUS_HOST_API_KEY_HEADERS'
   | 'LOG_JSON'
   | 'LOG_MULTILINE'
+  | 'LOG_NO_COLOR_PER_ACTOR'
   | 'LOG_LEVEL'
   | 'MNEMONIC'
   | 'NETWORK'
@@ -86,12 +96,18 @@ export type EnvVar =
   | 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT'
   | 'OTEL_COLLECT_INTERVAL_MS'
   | 'OTEL_EXCLUDE_METRICS'
+  | 'OTEL_INCLUDE_METRICS'
   | 'OTEL_EXPORT_TIMEOUT_MS'
   | 'PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT'
   | 'PUBLIC_OTEL_INCLUDE_METRICS'
   | 'PUBLIC_OTEL_COLLECT_FROM'
   | 'PUBLIC_OTEL_OPT_OUT'
+  | 'P2P_BATCH_TX_REQUESTER_SMART_PARALLEL_WORKER_COUNT'
+  | 'P2P_BATCH_TX_REQUESTER_DUMB_PARALLEL_WORKER_COUNT'
+  | 'P2P_BATCH_TX_REQUESTER_TX_BATCH_SIZE'
+  | 'P2P_BATCH_TX_REQUESTER_BAD_PEER_THRESHOLD'
   | 'P2P_BLOCK_CHECK_INTERVAL_MS'
+  | 'P2P_SLOT_CHECK_INTERVAL_MS'
   | 'P2P_BLOCK_REQUEST_BATCH_SIZE'
   | 'P2P_BOOTSTRAP_NODE_ENR_VERSION_CHECK'
   | 'P2P_BOOTSTRAP_NODES_AS_FULL_PEERS'
@@ -130,12 +146,12 @@ export type EnvVar =
   | 'P2P_TRUSTED_PEERS'
   | 'P2P_PRIVATE_PEERS'
   | 'P2P_PREFERRED_PEERS'
-  | 'P2P_MAX_TX_POOL_SIZE'
-  | 'P2P_TX_POOL_OVERFLOW_FACTOR'
+  | 'P2P_MAX_PENDING_TX_COUNT'
   | 'P2P_SEEN_MSG_CACHE_SIZE'
-  | 'P2P_DROP_TX'
   | 'P2P_DROP_TX_CHANCE'
   | 'P2P_TX_POOL_DELETE_TXS_AFTER_REORG'
+  | 'P2P_MIN_TX_POOL_AGE_MS'
+  | 'DEBUG_P2P_INSTRUMENT_MESSAGES'
   | 'PEER_ID_PRIVATE_KEY'
   | 'PEER_ID_PRIVATE_KEY_PATH'
   | 'PROVER_AGENT_COUNT'
@@ -148,7 +164,10 @@ export type EnvVar =
   | 'PROVER_BROKER_BATCH_INTERVAL_MS'
   | 'PROVER_BROKER_BATCH_SIZE'
   | 'PROVER_BROKER_MAX_EPOCHS_TO_KEEP_RESULTS_FOR'
+  | 'PROVER_BROKER_DEBUG_REPLAY_ENABLED'
+  | 'PROVER_CANCEL_JOBS_ON_STOP'
   | 'PROVER_COORDINATION_NODE_URLS'
+  | 'PROVER_PROOF_STORE'
   | 'PROVER_FAILED_PROOF_STORE'
   | 'PROVER_NODE_FAILED_EPOCH_STORE'
   | 'PROVER_NODE_DISABLE_PROOF_PUBLISH'
@@ -164,12 +183,15 @@ export type EnvVar =
   | 'PROVER_PUBLISHER_PRIVATE_KEYS'
   | 'PROVER_PUBLISHER_ADDRESSES'
   | 'PROVER_PUBLISHER_ALLOW_INVALID_STATES'
+  | 'PROVER_PUBLISHER_FORWARDER_ADDRESS'
   | 'PROVER_REAL_PROOFS'
   | 'PROVER_TEST_DELAY_FACTOR'
   | 'PROVER_TEST_DELAY_MS'
   | 'PROVER_TEST_DELAY_TYPE'
+  | 'PROVER_TEST_VERIFICATION_DELAY_MS'
   | 'PXE_L2_BLOCK_BATCH_SIZE'
   | 'PXE_PROVER_ENABLED'
+  | 'PXE_SYNC_CHAIN_TIP'
   | 'RPC_MAX_BATCH_SIZE'
   | 'RPC_MAX_BODY_SIZE'
   | 'RPC_SIMULATE_PUBLIC_MAX_GAS_LIMIT'
@@ -187,12 +209,17 @@ export type EnvVar =
   | 'SEQ_PUBLISHER_PRIVATE_KEYS'
   | 'SEQ_PUBLISHER_ADDRESSES'
   | 'SEQ_PUBLISHER_ALLOW_INVALID_STATES'
-  | 'SEQ_TX_POLLING_INTERVAL_MS'
+  | 'SEQ_PUBLISHER_FORWARDER_ADDRESS'
+  | 'SEQ_POLLING_INTERVAL_MS'
   | 'SEQ_ENFORCE_TIME_TABLE'
-  | 'SEQ_MAX_L1_TX_INCLUSION_TIME_INTO_SLOT'
+  | 'SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT'
   | 'SEQ_ATTESTATION_PROPAGATION_TIME'
+  | 'SEQ_BLOCK_DURATION_MS'
+  | 'SEQ_EXPECTED_BLOCK_PROPOSALS_PER_SLOT'
+  | 'SEQ_BUILD_CHECKPOINT_IF_EMPTY'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_COMMITTEE_MEMBER'
   | 'SEQ_SECONDS_BEFORE_INVALIDATING_BLOCK_AS_NON_COMMITTEE_MEMBER'
+  | 'SEQ_SKIP_CHECKPOINT_PUBLISH_PERCENT'
   | 'SLASH_MIN_PENALTY_PERCENTAGE'
   | 'SLASH_MAX_PENALTY_PERCENTAGE'
   | 'SLASH_VALIDATORS_ALWAYS'
@@ -203,6 +230,8 @@ export type EnvVar =
   | 'SLASH_INACTIVITY_TARGET_PERCENTAGE'
   | 'SLASH_INACTIVITY_CONSECUTIVE_EPOCH_THRESHOLD'
   | 'SLASH_INVALID_BLOCK_PENALTY'
+  | 'SLASH_DUPLICATE_PROPOSAL_PENALTY'
+  | 'SLASH_DUPLICATE_ATTESTATION_PENALTY'
   | 'SLASH_OVERRIDE_PAYLOAD'
   | 'SLASH_PROPOSE_INVALID_ATTESTATIONS_PENALTY'
   | 'SLASH_ATTEST_DESCENDANT_OF_INVALID_PENALTY'
@@ -227,6 +256,20 @@ export type EnvVar =
   | 'TX_COLLECTION_FAST_MAX_PARALLEL_REQUESTS_PER_NODE'
   | 'TX_COLLECTION_NODE_RPC_MAX_BATCH_SIZE'
   | 'TX_COLLECTION_NODE_RPC_URLS'
+  | 'TX_COLLECTION_MISSING_TXS_COLLECTOR_TYPE'
+  | 'TX_COLLECTION_FILE_STORE_URLS'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_DELAY_MS'
+  | 'TX_COLLECTION_FILE_STORE_FAST_DELAY_MS'
+  | 'TX_COLLECTION_FILE_STORE_FAST_WORKER_COUNT'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_WORKER_COUNT'
+  | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_BASE_MS'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_BASE_MS'
+  | 'TX_COLLECTION_FILE_STORE_FAST_BACKOFF_MAX_MS'
+  | 'TX_COLLECTION_FILE_STORE_SLOW_BACKOFF_MAX_MS'
+  | 'TX_FILE_STORE_URL'
+  | 'TX_FILE_STORE_UPLOAD_CONCURRENCY'
+  | 'TX_FILE_STORE_MAX_QUEUE_SIZE'
+  | 'TX_FILE_STORE_ENABLED'
   | 'TX_PUBLIC_SETUP_ALLOWLIST'
   | 'TXE_PORT'
   | 'TRANSACTIONS_DISABLED'
@@ -238,22 +281,25 @@ export type EnvVar =
   | 'VALIDATOR_ADDRESSES'
   | 'ROLLUP_VERSION'
   | 'WS_BLOCK_CHECK_INTERVAL_MS'
-  | 'WS_PROVEN_BLOCKS_ONLY'
   | 'WS_BLOCK_REQUEST_BATCH_SIZE'
   | 'L1_READER_VIEM_POLLING_INTERVAL_MS'
   | 'WS_DATA_DIRECTORY'
+  | 'WS_NUM_HISTORIC_CHECKPOINTS'
   | 'WS_NUM_HISTORIC_BLOCKS'
   | 'ETHEREUM_SLOT_DURATION'
   | 'AZTEC_SLOT_DURATION'
   | 'AZTEC_EPOCH_DURATION'
   | 'AZTEC_TARGET_COMMITTEE_SIZE'
-  | 'AZTEC_LAG_IN_EPOCHS'
+  | 'AZTEC_LAG_IN_EPOCHS_FOR_VALIDATOR_SET'
+  | 'AZTEC_LAG_IN_EPOCHS_FOR_RANDAO'
+  | 'AZTEC_INBOX_LAG'
   | 'AZTEC_PROOF_SUBMISSION_EPOCHS'
   | 'AZTEC_ACTIVATION_THRESHOLD'
   | 'AZTEC_EJECTION_THRESHOLD'
   | 'AZTEC_LOCAL_EJECTION_THRESHOLD'
   | 'AZTEC_MANA_TARGET'
   | 'AZTEC_PROVING_COST_PER_MANA'
+  | 'AZTEC_INITIAL_ETH_PER_FEE_ASSET'
   | 'AZTEC_SLASHING_QUORUM'
   | 'AZTEC_SLASHING_ROUND_SIZE_IN_EPOCHS'
   | 'AZTEC_SLASHING_LIFETIME_IN_ROUNDS'
@@ -267,13 +313,18 @@ export type EnvVar =
   | 'AZTEC_SLASHER_FLAVOR'
   | 'AZTEC_GOVERNANCE_PROPOSER_QUORUM'
   | 'AZTEC_GOVERNANCE_PROPOSER_ROUND_SIZE'
+  | 'AZTEC_GOVERNANCE_VOTING_DURATION'
   | 'AZTEC_EXIT_DELAY_SECONDS'
   | 'L1_GAS_LIMIT_BUFFER_PERCENTAGE'
   | 'L1_GAS_PRICE_MAX'
+  | 'L1_FEE_PER_GAS_GWEI_MAX'
   | 'L1_BLOB_FEE_PER_GAS_MAX'
+  | 'L1_BLOB_FEE_PER_GAS_GWEI_MAX'
   | 'L1_PRIORITY_FEE_BUMP_PERCENTAGE'
   | 'L1_PRIORITY_FEE_RETRY_BUMP_PERCENTAGE'
+  | 'L1_MINIMUM_PRIORITY_FEE_PER_GAS_GWEI'
   | 'L1_FIXED_PRIORITY_FEE_PER_GAS'
+  | 'L1_FIXED_PRIORITY_FEE_PER_GAS_GWEI'
   | 'L1_TX_MONITOR_MAX_ATTEMPTS'
   | 'L1_TX_MONITOR_CHECK_INTERVAL_MS'
   | 'L1_TX_MONITOR_STALL_TIME_MS'
@@ -289,9 +340,24 @@ export type EnvVar =
   | 'K8S_POD_UID'
   | 'K8S_NAMESPACE_NAME'
   | 'VALIDATOR_REEXECUTE_DEADLINE_MS'
-  | 'ALWAYS_REEXECUTE_BLOCK_PROPOSALS'
   | 'AUTO_UPDATE'
   | 'AUTO_UPDATE_URL'
   | 'WEB3_SIGNER_URL'
   | 'SKIP_ARCHIVER_INITIAL_SYNC'
-  | 'BLOB_ALLOW_EMPTY_SOURCES';
+  | 'BLOB_ALLOW_EMPTY_SOURCES'
+  | 'FISHERMAN_MODE'
+  | 'MAX_ALLOWED_ETH_CLIENT_DRIFT_SECONDS'
+  | 'LEGACY_BLS_CLI'
+  | 'DEBUG_FORCE_TX_PROOF_VERIFICATION'
+  | 'VALIDATOR_HA_SIGNING_ENABLED'
+  | 'VALIDATOR_HA_NODE_ID'
+  | 'VALIDATOR_HA_POLLING_INTERVAL_MS'
+  | 'VALIDATOR_HA_SIGNING_TIMEOUT_MS'
+  | 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS'
+  | 'VALIDATOR_HA_OLD_DUTIES_MAX_AGE_H'
+  | 'VALIDATOR_HA_DATABASE_URL'
+  | 'VALIDATOR_HA_RUN_MIGRATIONS'
+  | 'VALIDATOR_HA_POOL_MAX'
+  | 'VALIDATOR_HA_POOL_MIN'
+  | 'VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS'
+  | 'VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS';

package/src/config/index.ts

@@ -1,6 +1,8 @@
-import { Fq, Fr } from '../fields/fields.js';
+import { Fq, Fr } from '../curves/bn254/field.js';
+import { createConsoleLogger } from '../log/console.js';
 import type { EnvVar } from './env_var.js';
 import { type NetworkNames, getActiveNetworkName } from './network_name.js';
+import { parseBooleanEnv } from './parse-env.js';
 import { SecretValue } from './secret_value.js';
 
 export { SecretValue, getActiveNetworkName };
@@ -17,6 +19,11 @@ export interface ConfigMapping {
   isBoolean?: boolean;
   nested?: Record<string, ConfigMapping>;
   fallback?: EnvVar[];
+  /**
+   * List of deprecated env vars that are still supported but will log a warning.
+   * These should also be included in the fallback array for parsing.
+   */
+  deprecatedFallback?: { env: EnvVar; message?: string }[];
 }
 
 export function isBooleanConfigValue<T>(obj: T, key: keyof T): boolean {
@@ -72,12 +79,24 @@ export function getConfigFromMappings<T>(configMappings: ConfigMappingsType<T>):
   const config = {} as T;
 
   for (const key in configMappings) {
-    const { env, parseEnv, defaultValue, nested, fallback } = configMappings[key];
+    const { env, parseEnv, defaultValue, nested, fallback, deprecatedFallback } = configMappings[key];
     if (nested) {
       (config as any)[key] = getConfigFromMappings(nested);
     } else {
       // Use the shared utility function
       (config as any)[key] = getValueFromEnvWithFallback(env, parseEnv, defaultValue, fallback);
+
+      // Check for deprecated env vars and warn if logger is set
+      if (deprecatedFallback?.length) {
+        const userLog = createConsoleLogger('[DEPRECATED]');
+        for (const { env: deprecatedEnv, message } of deprecatedFallback) {
+          if (process.env[deprecatedEnv]) {
+            const warningMessage =
+              message ?? `Environment variable ${deprecatedEnv} is deprecated. Please use ${env} instead.`;
+            userLog(warningMessage, { deprecatedEnvVar: deprecatedEnv, newEnvVar: env });
+          }
+        }
+      }
     }
   }
 
@@ -130,6 +149,23 @@ export function floatConfigHelper(
   };
 }
 
+/**
+ * Parses an environment variable to a 0-1 percentage value
+ */
+export function percentageConfigHelper(defaultVal: number): Pick<ConfigMapping, 'parseEnv' | 'defaultValue'> {
+  return {
+    parseEnv: (val: string): number => {
+      const parsed = safeParseFloat(val, defaultVal);
+      if (parsed < 0 || parsed > 1) {
+        throw new TypeError(`Invalid percentage value: ${parsed} should be between 0 and 1`);
+      }
+
+      return parsed;
+    },
+    defaultValue: defaultVal,
+  };
+}
+
 /**
  * Generates parseEnv and default values for a numerical config value.
  * @param defaultVal - The default numerical value to use if the environment variable is not set or is invalid
@@ -213,10 +249,7 @@ export function secretValueConfigHelper<T>(parse: (val: string | undefined) => T
   };
 }
 
-/** Parses an env var as boolean. Returns true only if value is 1, true, or TRUE. */
-export function parseBooleanEnv(val: string | undefined): boolean {
-  return val !== undefined && ['1', 'true', 'TRUE'].includes(val);
-}
+export { parseBooleanEnv } from './parse-env.js';
 
 export function secretStringConfigHelper(): Required<
   Pick<ConfigMapping, 'parseEnv' | 'defaultValue' | 'isBoolean'> & {

package/src/config/network_config.ts

@@ -4,9 +4,11 @@ export const NetworkConfigSchema = z
   .object({
     bootnodes: z.array(z.string()),
     snapshots: z.array(z.string()),
+    blobFileStoreUrls: z.array(z.string()).optional(),
     registryAddress: z.string(),
     feeAssetHandlerAddress: z.string().optional(),
     l1ChainId: z.number(),
+    blockDurationMs: z.number().positive().optional(),
   })
   .passthrough(); // Allow additional unknown fields to pass through
 

package/src/config/network_name.ts

@@ -5,7 +5,8 @@ export type NetworkNames =
   | 'testnet'
   | 'mainnet'
   | 'next-net'
-  | 'devnet';
+  | 'devnet'
+  | `v${number}-devnet-${number}`;
 
 export function getActiveNetworkName(name?: string): NetworkNames {
   const network = name || process.env.NETWORK;
@@ -23,6 +24,8 @@ export function getActiveNetworkName(name?: string): NetworkNames {
     return 'next-net';
   } else if (network === 'devnet') {
     return 'devnet';
+  } else if (/^v\d+-devnet-\d+$/.test(network)) {
+    return network as `v${number}-devnet-${number}`;
   }
   throw new Error(`Unknown network: ${network}`);
 }

package/src/config/parse-env.ts

@@ -0,0 +1,4 @@
+/** Parses an env var as boolean. Returns true only if value is 1, true, or TRUE. */
+export function parseBooleanEnv(val: string | undefined): boolean {
+  return val !== undefined && ['1', 'true', 'TRUE'].includes(val);
+}

package/src/crypto/aes128/index.ts

@@ -22,7 +22,7 @@ export class Aes128 {
     paddingBuffer.fill(numPaddingBytes);
     const input = Buffer.concat([data, paddingBuffer]);
 
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.aesEncrypt({
       plaintext: input,
@@ -42,7 +42,7 @@ export class Aes128 {
    * @returns Decrypted data.
    */
   public async decryptBufferCBCKeepPadding(data: Uint8Array, iv: Uint8Array, key: Uint8Array): Promise<Buffer> {
-    await BarretenbergSync.initSingleton({ wasmPath: process.env.BB_WASM_PATH });
+    await BarretenbergSync.initSingleton();
     const api = BarretenbergSync.getSingleton();
     const response = api.aesDecrypt({
       ciphertext: data,

package/src/crypto/bls/bn254_keystore.ts

@@ -0,0 +1,287 @@
+import { randomBytes } from '@aztec/foundation/crypto/random';
+
+import { createCipheriv, createDecipheriv, createHash, pbkdf2Sync, randomUUID } from 'crypto';
+import { readFileSync } from 'fs';
+import { z } from 'zod';
+
+/**
+ * BN254 Keystore Format
+ *
+ * Implements encryption and decryption of keystores for BN254 BLS private keys
+ * using PBKDF2 and AES-128-CTR. This format is inspired by EIP-2335 but adapted
+ * for BN254 keys rather than BLS12-381.
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-2335
+ */
+
+/**
+ * Zod schema for validating BN254 keystore structure
+ */
+const bn254KeystoreSchema = z.object({
+  crypto: z.object({
+    kdf: z.object({
+      function: z.literal('pbkdf2'),
+      params: z.object({
+        dklen: z.number(),
+        c: z.number(),
+        prf: z.string(),
+        salt: z.string(),
+      }),
+      message: z.string(),
+    }),
+    checksum: z.object({
+      function: z.literal('sha256'),
+      params: z.object({}),
+      message: z.string(),
+    }),
+    cipher: z.object({
+      function: z.literal('aes-128-ctr'),
+      params: z.object({
+        iv: z.string(),
+      }),
+      message: z.string(),
+    }),
+  }),
+  description: z.string().optional(),
+  pubkey: z.string(),
+  path: z.string(),
+  uuid: z.string(),
+  version: z.number(),
+});
+
+/**
+ * Error thrown when BN254 keystore operations fail
+ */
+export class Bn254KeystoreError extends Error {
+  constructor(
+    message: string,
+    public override cause?: Error,
+  ) {
+    super(message);
+    this.name = 'Bn254KeystoreError';
+  }
+}
+
+export type Bn254Keystore = z.infer<typeof bn254KeystoreSchema>;
+
+/**
+ * The JSON structure of a BN254 keystore file.
+ * @deprecated Use the inferred type from bn254KeystoreSchema instead
+ */
+export interface Bn254KeystoreInterface {
+  crypto: {
+    kdf: {
+      function: 'pbkdf2';
+      params: {
+        dklen: number;
+        c: number;
+        prf: string;
+        salt: string;
+      };
+      message: string;
+    };
+    checksum: {
+      function: 'sha256';
+      params: Record<string, never>;
+      message: string;
+    };
+    cipher: {
+      function: 'aes-128-ctr';
+      params: {
+        iv: string;
+      };
+      message: string;
+    };
+  };
+  description: string;
+  pubkey: string;
+  path: string;
+  uuid: string;
+  version: number;
+}
+
+/**
+ * Creates a BN254 keystore object for a BN254 BLS private key.
+ *
+ * Uses PBKDF2 with SHA-256 for key derivation and AES-128-CTR for encryption,
+ * following the EIP-2335 specification format.
+ *
+ * @param password - Password for encrypting the private key
+ * @param privateKeyHex - Private key as 0x-prefixed hex string (32 bytes)
+ * @param pubkeyHex - Public key as hex string (compressed or uncompressed)
+ * @param derivationPath - BIP-44 style derivation path (e.g., "m/12381/3600/0/0/0")
+ * @returns BN254 keystore object ready to be serialized to JSON
+ * @throws Error if private key is not 32-byte hex
+ */
+export function createBn254Keystore(
+  password: string,
+  privateKeyHex: string,
+  pubkeyHex: string,
+  derivationPath: string,
+): Bn254Keystore {
+  const ensureHex = (hex: string) => hex.replace(/^0x/i, '');
+  const privHex = ensureHex(privateKeyHex);
+  if (!/^[0-9a-fA-F]{64}$/.test(privHex)) {
+    throw new Error('BLS private key must be 32-byte hex');
+  }
+
+  const salt = randomBytes(32);
+  const iv = randomBytes(16);
+  const dk = pbkdf2Sync(Buffer.from(password.normalize('NFKD'), 'utf8'), salt, 262144, 32, 'sha256');
+  const cipherKey = dk.subarray(0, 16);
+
+  const cipher = createCipheriv('aes-128-ctr', cipherKey, iv);
+  const plaintext = Buffer.from(privHex, 'hex');
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+
+  const checksum = createHash('sha256')
+    .update(Buffer.concat([dk.subarray(16, 32), ciphertext]))
+    .digest();
+
+  const uuid = randomUUID();
+
+  return {
+    crypto: {
+      kdf: {
+        function: 'pbkdf2',
+        params: { dklen: 32, c: 262144, prf: 'hmac-sha256', salt: salt.toString('hex') },
+        message: '',
+      },
+      checksum: {
+        function: 'sha256',
+        params: {},
+        message: checksum.toString('hex'),
+      },
+      cipher: {
+        function: 'aes-128-ctr',
+        params: { iv: iv.toString('hex') },
+        message: ciphertext.toString('hex'),
+      },
+    },
+    description: ensureHex(pubkeyHex),
+    pubkey: pubkeyHex,
+    path: derivationPath ?? '',
+    uuid,
+    version: 4,
+  };
+}
+
+/**
+ * Loads and validates a BN254 keystore file.
+ *
+ * @param filePath - Path to the BN254 keystore JSON file
+ * @returns Validated keystore object
+ * @throws Bn254KeystoreError if file cannot be read or validated
+ */
+export function loadBn254Keystore(filePath: string): Bn254Keystore {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const json = JSON.parse(content);
+    return bn254KeystoreSchema.parse(json);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Bn254KeystoreError(`Invalid JSON in keystore file: ${filePath}`, error);
+    }
+    if (error && typeof error === 'object' && 'issues' in error) {
+      const issues = (error as any).issues ?? [];
+      const message = issues.map((e: any) => `${e.message} at ${e.path?.join('.') ?? 'root'}`).join('; ');
+      throw new Bn254KeystoreError(`Invalid BN254 keystore format: ${message}`);
+    }
+    throw new Bn254KeystoreError(`Failed to load keystore from ${filePath}: ${String(error)}`, error as Error);
+  }
+}
+
+/**
+ * Decrypts a BN254 BLS private key from a keystore file.
+ *
+ * @param filePath - Path to the BN254 keystore JSON file
+ * @param password - Password to decrypt the keystore
+ * @returns Decrypted private key as 0x-prefixed hex string (32 bytes)
+ * @throws Bn254KeystoreError if decryption fails or checksum is invalid
+ */
+export function decryptBn254Keystore(filePath: string, password: string): string {
+  const keystore = loadBn254Keystore(filePath);
+  return decryptBn254KeystoreFromObject(keystore, password);
+}
+
+/**
+ * Decrypts a BN254 BLS private key from a keystore object.
+ *
+ * @param keystore - BN254 keystore object
+ * @param password - Password to decrypt the keystore
+ * @returns Decrypted private key as 0x-prefixed hex string (32 bytes)
+ * @throws Bn254KeystoreError if decryption fails or checksum is invalid
+ */
+export function decryptBn254KeystoreFromObject(keystore: Bn254Keystore, password: string): string {
+  try {
+    const { crypto } = keystore;
+
+    // Only support PBKDF2 + AES-128-CTR (as per our implementation)
+    if (crypto.kdf.function !== 'pbkdf2') {
+      throw new Bn254KeystoreError(`Unsupported KDF function: ${crypto.kdf.function}`);
+    }
+    if (crypto.cipher.function !== 'aes-128-ctr') {
+      throw new Bn254KeystoreError(`Unsupported cipher function: ${crypto.cipher.function}`);
+    }
+
+    // Derive decryption key using PBKDF2
+    const salt = Buffer.from(crypto.kdf.params.salt, 'hex');
+    const dk = pbkdf2Sync(
+      Buffer.from(password.normalize('NFKD'), 'utf8'),
+      salt,
+      crypto.kdf.params.c,
+      crypto.kdf.params.dklen,
+      'sha256',
+    );
+
+    const cipherKey = dk.subarray(0, 16);
+    const checksumKey = dk.subarray(16, 32);
+
+    // Decrypt the ciphertext
+    const iv = Buffer.from(crypto.cipher.params.iv, 'hex');
+    const ciphertext = Buffer.from(crypto.cipher.message, 'hex');
+    const decipher = createDecipheriv('aes-128-ctr', cipherKey, iv);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+    // Verify checksum
+    const computedChecksum = createHash('sha256')
+      .update(Buffer.concat([checksumKey, ciphertext]))
+      .digest();
+    const expectedChecksum = Buffer.from(crypto.checksum.message, 'hex');
+
+    if (!computedChecksum.equals(expectedChecksum)) {
+      throw new Bn254KeystoreError('Checksum verification failed - incorrect password or corrupted keystore');
+    }
+
+    // Return as 0x-prefixed hex
+    return '0x' + decrypted.toString('hex');
+  } catch (error) {
+    if (error instanceof Bn254KeystoreError) {
+      throw error;
+    }
+    throw new Bn254KeystoreError(`Failed to decrypt keystore: ${String(error)}`, error as Error);
+  }
+}
+
+/**
+ * Validates that a decrypted private key matches the public key in the keystore.
+ *
+ * @param privateKeyHex - Decrypted private key (0x-prefixed)
+ * @param expectedPubkey - Expected public key from keystore
+ * @param computePublicKey - Function to compute public key from private key
+ * @returns true if keys match, false otherwise
+ */
+export function verifyBn254Keypair(
+  privateKeyHex: string,
+  expectedPubkey: string,
+  computePublicKey: (privateKey: string) => string,
+): boolean {
+  try {
+    const computedPubkey = computePublicKey(privateKeyHex);
+    const normalizedExpected = expectedPubkey.toLowerCase().replace(/^0x/i, '');
+    const normalizedComputed = computedPubkey.toLowerCase().replace(/^0x/i, '');
+    return normalizedExpected === normalizedComputed;
+  } catch {
+    return false;
+  }
+}