@aztec/stdlib 0.0.1-commit.bf2612ae → 0.0.1-commit.c0b82b2

package/src/contract/contract_class_id.ts

@@ -1,4 +1,4 @@
-import { GeneratorIndex, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS } from '@aztec/constants';
+import { DomainSeparator, MAX_PACKED_PUBLIC_BYTECODE_SIZE_IN_FIELDS } from '@aztec/constants';
 import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 
@@ -13,7 +13,7 @@ import { computePrivateFunctionsRoot } from './private_function.js';
  *
  * ```
  * version = 1
- * private_function_leaves = private_functions.map(fn => pedersen([fn.function_selector as Field, fn.vk_hash], GENERATOR__FUNCTION_LEAF))
+ * private_function_leaves = private_functions.map(fn => pedersen([fn.function_selector as Field, fn.vk_hash], GENERATOR__PRIVATE_FUNCTION_LEAF))
  * private_functions_root = merkleize(private_function_leaves)
  * bytecode_commitment = calculate_commitment(packed_bytecode)
  * contract_class_id = pedersen([version, artifact_hash, private_functions_root, bytecode_commitment], GENERATOR__CLASS_IDENTIFIER)
@@ -40,7 +40,7 @@ export async function computeContractClassIdWithPreimage(
       : await computePublicBytecodeCommitment(contractClass.packedBytecode);
   const id = await poseidon2HashWithSeparator(
     [artifactHash, privateFunctionsRoot, publicBytecodeCommitment],
-    GeneratorIndex.CONTRACT_CLASS_ID,
+    DomainSeparator.CONTRACT_CLASS_ID,
   );
   return { id, artifactHash, privateFunctionsRoot, publicBytecodeCommitment };
 }
@@ -60,7 +60,7 @@ export type ContractClassIdPreimage = {
 };
 
 export async function computePublicBytecodeCommitment(packedBytecode: Buffer) {
-  // Encode the buffer into field elements (chunked into 32 bytes each)
+  // Encode the buffer into field elements (chunked into 31 bytes each)
   // The first element is the length of the bytecode (in bytes)
   const [bytecodeLengthAsField, ...bytecodeAsFields] = bufferAsFields(
     packedBytecode,
@@ -72,5 +72,6 @@ export async function computePublicBytecodeCommitment(packedBytecode: Buffer) {
 
   // NOTE: hash the bytecode here only up to the actual length of the bytecode.
   // We do not hash the entire max bytecode length!
-  return await poseidon2HashWithSeparator(bytecodeAsFields.slice(0, bytecodeLength), GeneratorIndex.PUBLIC_BYTECODE);
+  const sep = BigInt(DomainSeparator.PUBLIC_BYTECODE) + (bytecodeLengthAsField.toBigInt() << 32n);
+  return await poseidon2HashWithSeparator(bytecodeAsFields.slice(0, bytecodeLength), new Fr(sep).toNumber());
 }

package/src/contract/interfaces/node-info.ts

@@ -19,6 +19,8 @@ export interface NodeInfo {
   l1ContractAddresses: L1ContractAddresses;
   /** Protocol contract addresses */
   protocolContractAddresses: ProtocolContractAddresses;
+  /** Whether the node requires real proofs for transaction submission. */
+  realProofs: boolean;
 }
 
 export const NodeInfoSchema: ZodFor<NodeInfo> = z
@@ -29,5 +31,6 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,
+    realProofs: z.boolean(),
   })
   .transform(obj => ({ enr: undefined, ...obj }));

package/src/contract/private_function.ts

@@ -1,4 +1,4 @@
-import { FUNCTION_TREE_HEIGHT, GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator, FUNCTION_TREE_HEIGHT } from '@aztec/constants';
 import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
@@ -31,7 +31,7 @@ function computePrivateFunctionLeaves(fns: PrivateFunction[]): Promise<Buffer[]>
 
 /** Returns the leaf for a given private function. */
 export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<Buffer> {
-  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], GeneratorIndex.FUNCTION_LEAF)).toBuffer();
+  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], DomainSeparator.PRIVATE_FUNCTION_LEAF)).toBuffer();
 }
 
 async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {

package/src/contract/private_function_membership_proof.ts

@@ -99,7 +99,7 @@ export async function createPrivateFunctionMembershipProof(
  * contract_class = db.get_contract_class(contract_class_id)
  *
  * // Compute function leaf and assert it belongs to the private functions tree
- * function_leaf = pedersen([selector as Field, vk_hash], GENERATOR__FUNCTION_LEAF)
+ * function_leaf = pedersen([selector as Field, vk_hash], GENERATOR__PRIVATE_FUNCTION_LEAF)
  * computed_private_function_tree_root = compute_root(function_leaf, private_function_tree_sibling_path)
  * assert computed_private_function_tree_root == contract_class.private_functions_root
  *

package/src/database-version/database_version.ts

@@ -0,0 +1,87 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
+
+import { z } from 'zod';
+
+/**
+ * Symbol for Node.js custom inspect. Using Symbol.for() is the documented way to
+ * reference this without importing node:util. In browsers, objects with this symbol
+ * simply won't have custom inspect behavior (which is fine).
+ * @see https://nodejs.org/api/util.html#utilinspectcustom
+ */
+const inspectCustomSymbol = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Represents a version record for storing in a version file.
+ */
+export class DatabaseVersion {
+  constructor(
+    /** The version of the data on disk. Used to perform upgrades */
+    public readonly schemaVersion: number,
+    /** The rollup the data pertains to */
+    public readonly rollupAddress: EthAddress,
+  ) {}
+
+  public toBuffer(): Buffer {
+    return Buffer.from(jsonStringify(this));
+  }
+
+  public static fromBuffer(buf: Buffer): DatabaseVersion {
+    try {
+      return jsonParseWithSchema(buf.toString('utf-8'), DatabaseVersion.schema);
+    } catch (err) {
+      throw new Error(`Failed to deserialize version information: ${err}`, { cause: err });
+    }
+  }
+
+  /**
+   * Compares two versions. If the rollups addresses are different then it returns undefined
+   */
+  public cmp(other: DatabaseVersion): undefined | -1 | 0 | 1 {
+    if (this.rollupAddress.equals(other.rollupAddress)) {
+      if (this.schemaVersion < other.schemaVersion) {
+        return -1;
+      } else if (this.schemaVersion > other.schemaVersion) {
+        return 1;
+      } else {
+        return 0;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Checks if two versions exactly match
+   */
+  public equals(other: DatabaseVersion): boolean {
+    return this.cmp(other) === 0;
+  }
+
+  /**
+   * Returns the schema for this class
+   */
+  static get schema() {
+    return z
+      .object({
+        schemaVersion: z.number(),
+        rollupAddress: EthAddress.schema,
+      })
+      .transform(({ schemaVersion, rollupAddress }) => new DatabaseVersion(schemaVersion, rollupAddress));
+  }
+
+  /** Allows for better introspection in Node.js console. Ignored in browser envs. */
+  public [inspectCustomSymbol](): string {
+    return this.toString();
+  }
+
+  public toString(): string {
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
+  }
+
+  /**
+   * Returns an empty instance
+   */
+  static empty() {
+    return new DatabaseVersion(0, EthAddress.ZERO);
+  }
+}

package/src/database-version/version_manager.ts

@@ -1,86 +1,10 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import fs from 'fs/promises';
-import { inspect } from 'node:util';
 import { join } from 'path';
-import { z } from 'zod';
 
-/**
- * Represents a version record for storing in a version file.
- */
-export class DatabaseVersion {
-  constructor(
-    /** The version of the data on disk. Used to perform upgrades */
-    public readonly schemaVersion: number,
-    /** The rollup the data pertains to */
-    public readonly rollupAddress: EthAddress,
-  ) {}
-
-  public toBuffer(): Buffer {
-    return Buffer.from(jsonStringify(this));
-  }
-
-  public static fromBuffer(buf: Buffer): DatabaseVersion {
-    try {
-      return jsonParseWithSchema(buf.toString('utf-8'), DatabaseVersion.schema);
-    } catch (err) {
-      throw new Error(`Failed to deserialize version information: ${err}`, { cause: err });
-    }
-  }
-
-  /**
-   * Compares two versions. If the rollups addresses are different then it returns undefined
-   */
-  public cmp(other: DatabaseVersion): undefined | -1 | 0 | 1 {
-    if (this.rollupAddress.equals(other.rollupAddress)) {
-      if (this.schemaVersion < other.schemaVersion) {
-        return -1;
-      } else if (this.schemaVersion > other.schemaVersion) {
-        return 1;
-      } else {
-        return 0;
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Checks if two versions exactly match
-   */
-  public equals(other: DatabaseVersion): boolean {
-    return this.cmp(other) === 0;
-  }
-
-  /**
-   * Returns the schema for this class
-   */
-  static get schema() {
-    return z
-      .object({
-        schemaVersion: z.number(),
-        rollupAddress: EthAddress.schema,
-      })
-      .transform(({ schemaVersion, rollupAddress }) => new DatabaseVersion(schemaVersion, rollupAddress));
-  }
-
-  /** Allows for better introspection. */
-  public [inspect.custom](): string {
-    return this.toString();
-  }
-
-  public toString(): string {
-    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
-  }
-
-  /**
-   * Returns an empty instance
-   */
-  static empty() {
-    return new DatabaseVersion(0, EthAddress.ZERO);
-  }
-}
+import { DatabaseVersion } from './database_version.js';
 
 export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
 

package/src/epoch-helpers/index.ts

@@ -11,6 +11,7 @@ export type L1RollupConstants = {
   epochDuration: number;
   ethereumSlotDuration: number;
   proofSubmissionEpochs: number;
+  targetCommitteeSize: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -20,6 +21,7 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   slotDuration: 1,
   ethereumSlotDuration: 1,
   proofSubmissionEpochs: 1,
+  targetCommitteeSize: 48,
 };
 
 export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
@@ -30,6 +32,7 @@ export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
     epochDuration: z.number(),
     ethereumSlotDuration: z.number(),
     proofSubmissionEpochs: z.number(),
+    targetCommitteeSize: z.number(),
   }),
 );
 
@@ -51,6 +54,15 @@ export function getSlotAtTimestamp(
     : SlotNumber.fromBigInt((ts - constants.l1GenesisTime) / BigInt(constants.slotDuration));
 }
 
+/** Returns the L2 slot number at the next L1 block based on the current timestamp. */
+export function getSlotAtNextL1Block(
+  currentL1Timestamp: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): SlotNumber {
+  const nextL1BlockTimestamp = currentL1Timestamp + BigInt(constants.ethereumSlotDuration);
+  return getSlotAtTimestamp(nextL1BlockTimestamp, constants);
+}
+
 /** Returns the epoch number for a given timestamp. */
 export function getEpochNumberAtTimestamp(
   ts: bigint,

package/src/file-store/local.ts

@@ -1,15 +1,21 @@
 import { access, mkdir, readFile, writeFile } from 'fs/promises';
 import { dirname, resolve } from 'path';
+import { promisify } from 'util';
+import { gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
-import type { FileStore } from './interface.js';
+import type { FileStore, FileStoreSaveOptions } from './interface.js';
+
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
 
 export class LocalFileStore implements FileStore {
   constructor(private readonly basePath: string) {}
 
-  public async save(path: string, data: Buffer): Promise<string> {
+  public async save(path: string, data: Buffer, opts?: FileStoreSaveOptions): Promise<string> {
     const fullPath = this.getFullPath(path);
     await mkdir(dirname(fullPath), { recursive: true });
-    await writeFile(fullPath, data);
+    const toWrite = opts?.compress ? await gzip(data) : data;
+    await writeFile(fullPath, toWrite);
     return `file://${fullPath}`;
   }
 
@@ -18,9 +24,13 @@ export class LocalFileStore implements FileStore {
     return this.save(destPath, data);
   }
 
-  public read(pathOrUrlStr: string): Promise<Buffer> {
+  public async read(pathOrUrlStr: string): Promise<Buffer> {
     const fullPath = this.getFullPath(pathOrUrlStr);
-    return readFile(fullPath);
+    const data = await readFile(fullPath);
+    if (data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b) {
+      return await gunzip(data);
+    }
+    return data;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/file-store/s3.ts

@@ -13,10 +13,14 @@ import { tmpdir } from 'os';
 import { basename, dirname, join } from 'path';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { createGzip } from 'zlib';
+import { promisify } from 'util';
+import { createGzip, gunzip as gunzipCb, gzip as gzipCb } from 'zlib';
 
 import type { FileStore, FileStoreSaveOptions } from './interface.js';
 
+const gzip = promisify(gzipCb);
+const gunzip = promisify(gunzipCb);
+
 function normalizeBasePath(path: string): string {
   return path?.replace(/^\/+|\/+$/g, '') ?? '';
 }
@@ -52,7 +56,7 @@ export class S3FileStore implements FileStore {
     const key = this.getFullPath(path);
     const shouldCompress = !!opts.compress;
 
-    const body = shouldCompress ? (await import('zlib')).gzipSync(data) : data;
+    const body = shouldCompress ? await gzip(data) : data;
     const contentLength = body.length;
     const contentType = this.detectContentType(key, shouldCompress);
     const put = new PutObjectCommand({
@@ -60,6 +64,7 @@ export class S3FileStore implements FileStore {
       Key: key,
       Body: body,
       ContentType: contentType,
+      ContentEncoding: shouldCompress ? 'gzip' : undefined,
       CacheControl: opts.metadata?.['Cache-control'],
       Metadata: this.extractUserMetadata(opts.metadata),
       ContentLength: contentLength,
@@ -134,7 +139,11 @@ export class S3FileStore implements FileStore {
     for await (const chunk of stream) {
       chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
     }
-    return Buffer.concat(chunks);
+    const buffer = Buffer.concat(chunks);
+    if (out.ContentEncoding === 'gzip') {
+      return await gunzip(buffer);
+    }
+    return buffer;
   }
 
   public async download(pathOrUrlStr: string, destPath: string): Promise<void> {

package/src/ha-signing/config.ts

@@ -0,0 +1,149 @@
+import type { L1ContractAddresses } from '@aztec/ethereum/l1-contract-addresses';
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  getDefaultConfig,
+  numberConfigHelper,
+  optionalNumberConfigHelper,
+} from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+/**
+ * Configuration for the Validator HA Signer
+ *
+ * This config is used for distributed locking and slashing protection
+ * when running multiple validator nodes in a high-availability setup.
+ */
+export interface ValidatorHASignerConfig {
+  /** Whether HA signing / slashing protection is enabled */
+  haSigningEnabled: boolean;
+  /** L1 contract addresses (rollup address required) */
+  l1Contracts: Pick<L1ContractAddresses, 'rollupAddress'>;
+  /** Unique identifier for this node */
+  nodeId: string;
+  /** How long to wait between polls when a duty is being signed (ms) */
+  pollingIntervalMs: number;
+  /** Maximum time to wait for a duty being signed to complete (ms) */
+  signingTimeoutMs: number;
+  /** Maximum age of a stuck duty in ms (defaults to 2x hardcoded Aztec slot duration if not set) */
+  maxStuckDutiesAgeMs?: number;
+  /** Optional: clean up old duties after this many hours (disabled if not set) */
+  cleanupOldDutiesAfterHours?: number;
+  /**
+   * PostgreSQL connection string
+   * Format: postgresql://user:password@host:port/database
+   */
+  databaseUrl?: string;
+  /**
+   * PostgreSQL connection pool configuration
+   */
+  /** Maximum number of clients in the pool (default: 10) */
+  poolMaxCount?: number;
+  /** Minimum number of clients in the pool (default: 0) */
+  poolMinCount?: number;
+  /** Idle timeout in milliseconds (default: 10000) */
+  poolIdleTimeoutMs?: number;
+  /** Connection timeout in milliseconds (default: 0, no timeout) */
+  poolConnectionTimeoutMs?: number;
+}
+
+export const validatorHASignerConfigMappings: ConfigMappingsType<ValidatorHASignerConfig> = {
+  haSigningEnabled: {
+    env: 'VALIDATOR_HA_SIGNING_ENABLED',
+    description: 'Whether HA signing / slashing protection is enabled',
+    ...booleanConfigHelper(false),
+  },
+  l1Contracts: {
+    description: 'L1 contract addresses (rollup address required)',
+    nested: {
+      rollupAddress: {
+        description: 'The Ethereum address of the rollup contract (must be set programmatically)',
+        parseEnv: (val: string) => EthAddress.fromString(val),
+      },
+    },
+  },
+  nodeId: {
+    env: 'VALIDATOR_HA_NODE_ID',
+    description: 'The unique identifier for this node',
+    defaultValue: '',
+  },
+  pollingIntervalMs: {
+    env: 'VALIDATOR_HA_POLLING_INTERVAL_MS',
+    description: 'The number of ms to wait between polls when a duty is being signed',
+    ...numberConfigHelper(100),
+  },
+  signingTimeoutMs: {
+    env: 'VALIDATOR_HA_SIGNING_TIMEOUT_MS',
+    description: 'The maximum time to wait for a duty being signed to complete',
+    ...numberConfigHelper(3_000),
+  },
+  maxStuckDutiesAgeMs: {
+    env: 'VALIDATOR_HA_MAX_STUCK_DUTIES_AGE_MS',
+    description: 'The maximum age of a stuck duty in ms (defaults to 2x Aztec slot duration)',
+    ...optionalNumberConfigHelper(),
+  },
+  cleanupOldDutiesAfterHours: {
+    env: 'VALIDATOR_HA_OLD_DUTIES_MAX_AGE_H',
+    description: 'Optional: clean up old duties after this many hours (disabled if not set)',
+    ...optionalNumberConfigHelper(),
+  },
+  databaseUrl: {
+    env: 'VALIDATOR_HA_DATABASE_URL',
+    description:
+      'PostgreSQL connection string for validator HA signer (format: postgresql://user:password@host:port/database)',
+  },
+  poolMaxCount: {
+    env: 'VALIDATOR_HA_POOL_MAX',
+    description: 'Maximum number of clients in the pool',
+    ...numberConfigHelper(10),
+  },
+  poolMinCount: {
+    env: 'VALIDATOR_HA_POOL_MIN',
+    description: 'Minimum number of clients in the pool',
+    ...numberConfigHelper(0),
+  },
+  poolIdleTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_IDLE_TIMEOUT_MS',
+    description: 'Idle timeout in milliseconds',
+    ...numberConfigHelper(10_000),
+  },
+  poolConnectionTimeoutMs: {
+    env: 'VALIDATOR_HA_POOL_CONNECTION_TIMEOUT_MS',
+    description: 'Connection timeout in milliseconds (0 means no timeout)',
+    ...numberConfigHelper(0),
+  },
+};
+
+export const defaultValidatorHASignerConfig: ValidatorHASignerConfig = getDefaultConfig(
+  validatorHASignerConfigMappings,
+);
+
+/**
+ * Returns the validator HA signer configuration from environment variables.
+ * Note: If an environment variable is not set, the default value is used.
+ * @returns The validator HA signer configuration.
+ */
+export function getConfigEnvVars(): ValidatorHASignerConfig {
+  return getConfigFromMappings<ValidatorHASignerConfig>(validatorHASignerConfigMappings);
+}
+
+export const ValidatorHASignerConfigSchema = z.object({
+  haSigningEnabled: z.boolean(),
+  l1Contracts: z.object({
+    rollupAddress: z.instanceof(EthAddress),
+  }),
+  nodeId: z.string(),
+  pollingIntervalMs: z.number().min(0),
+  signingTimeoutMs: z.number().min(0),
+  maxStuckDutiesAgeMs: z.number().min(0).optional(),
+  cleanupOldDutiesAfterHours: z.number().min(0).optional(),
+  databaseUrl: z.string().optional(),
+  poolMaxCount: z.number().min(0).optional(),
+  poolMinCount: z.number().min(0).optional(),
+  poolIdleTimeoutMs: z.number().min(0).optional(),
+  poolConnectionTimeoutMs: z.number().min(0).optional(),
+}) satisfies ZodFor<ValidatorHASignerConfig>;

package/src/ha-signing/index.ts

@@ -0,0 +1,18 @@
+export {
+  type ValidatorHASignerConfig,
+  ValidatorHASignerConfigSchema,
+  defaultValidatorHASignerConfig,
+  getConfigEnvVars,
+  validatorHASignerConfigMappings,
+} from './config.js';
+export {
+  DutyType,
+  type BlockProposalSigningContext,
+  type HAProtectedSigningContext,
+  type NoHAProtectionSigningContext,
+  type OtherSigningContext,
+  type SigningContext,
+  type VoteSigningContext,
+  getBlockNumberFromSigningContext,
+  isHAProtectedContext,
+} from './types.js';

package/src/ha-signing/types.ts

@@ -0,0 +1,112 @@
+import {
+  BlockNumber,
+  type CheckpointNumber,
+  type IndexWithinCheckpoint,
+  type SlotNumber,
+} from '@aztec/foundation/branded-types';
+
+/**
+ * Type of validator duty being performed
+ */
+export enum DutyType {
+  BLOCK_PROPOSAL = 'BLOCK_PROPOSAL',
+  CHECKPOINT_PROPOSAL = 'CHECKPOINT_PROPOSAL',
+  ATTESTATION = 'ATTESTATION',
+  ATTESTATIONS_AND_SIGNERS = 'ATTESTATIONS_AND_SIGNERS',
+  GOVERNANCE_VOTE = 'GOVERNANCE_VOTE',
+  SLASHING_VOTE = 'SLASHING_VOTE',
+  AUTH_REQUEST = 'AUTH_REQUEST',
+  TXS = 'TXS',
+}
+
+/**
+ * Base context for signing operations
+ */
+interface BaseSigningContext {
+  /** Slot number for this duty */
+  slot: SlotNumber;
+  /**
+   * Block or checkpoint number for this duty.
+   * For block proposals, this is the block number.
+   * For checkpoint proposals, this is the checkpoint number.
+   */
+  blockNumber: BlockNumber | CheckpointNumber;
+}
+
+/**
+ * Signing context for block proposals.
+ * blockIndexWithinCheckpoint is REQUIRED and must be >= 0.
+ */
+export interface BlockProposalSigningContext extends BaseSigningContext {
+  /** Block index within checkpoint (0, 1, 2...). Required for block proposals. */
+  blockIndexWithinCheckpoint: IndexWithinCheckpoint;
+  dutyType: DutyType.BLOCK_PROPOSAL;
+}
+
+/**
+ * Signing context for non-block-proposal duties that require HA protection.
+ * blockIndexWithinCheckpoint is not applicable (internally always -1).
+ */
+export interface OtherSigningContext extends BaseSigningContext {
+  dutyType: DutyType.CHECKPOINT_PROPOSAL | DutyType.ATTESTATION | DutyType.ATTESTATIONS_AND_SIGNERS;
+}
+
+/**
+ * Signing context for governance/slashing votes which only need slot for HA protection.
+ * blockNumber is not applicable (internally always 0).
+ */
+export interface VoteSigningContext {
+  slot: SlotNumber;
+  dutyType: DutyType.GOVERNANCE_VOTE | DutyType.SLASHING_VOTE;
+}
+
+/**
+ * Signing context for duties which don't require slot/blockNumber
+ * as they don't need HA protection (AUTH_REQUEST, TXS).
+ */
+export interface NoHAProtectionSigningContext {
+  dutyType: DutyType.AUTH_REQUEST | DutyType.TXS;
+}
+
+/**
+ * Signing contexts that require HA protection (excludes AUTH_REQUEST).
+ * Used by the HA signer's signWithProtection method.
+ */
+export type HAProtectedSigningContext = BlockProposalSigningContext | OtherSigningContext | VoteSigningContext;
+
+/**
+ * Context required for slashing protection during signing operations.
+ * Uses discriminated union to enforce type safety:
+ * - BLOCK_PROPOSAL duties MUST have blockIndexWithinCheckpoint >= 0
+ * - Other duty types do NOT have blockIndexWithinCheckpoint (internally -1)
+ * - Vote duties only need slot (blockNumber is internally 0)
+ * - AUTH_REQUEST and TXS duties don't need slot/blockNumber (no HA protection needed)
+ */
+export type SigningContext = HAProtectedSigningContext | NoHAProtectionSigningContext;
+
+/**
+ * Type guard to check if a SigningContext requires HA protection.
+ * Returns true for contexts that need HA protection, false for AUTH_REQUEST and TXS.
+ */
+export function isHAProtectedContext(context: SigningContext): context is HAProtectedSigningContext {
+  return context.dutyType !== DutyType.AUTH_REQUEST && context.dutyType !== DutyType.TXS;
+}
+
+/**
+ * Gets the block number from a signing context.
+ * - Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE): returns BlockNumber(0)
+ * - Other duties: returns the blockNumber from the context
+ */
+export function getBlockNumberFromSigningContext(context: HAProtectedSigningContext): BlockNumber | CheckpointNumber {
+  // Check for duty types that have blockNumber
+  if (
+    context.dutyType === DutyType.BLOCK_PROPOSAL ||
+    context.dutyType === DutyType.CHECKPOINT_PROPOSAL ||
+    context.dutyType === DutyType.ATTESTATION ||
+    context.dutyType === DutyType.ATTESTATIONS_AND_SIGNERS
+  ) {
+    return context.blockNumber;
+  }
+  // Vote duties (GOVERNANCE_VOTE, SLASHING_VOTE) don't have blockNumber
+  return BlockNumber(0);
+}