@obolnetwork/obol-sdk 2.5.1 → 2.7.0

package/dist/types/src/exits/exit.d.ts

@@ -0,0 +1,200 @@
+import type { ProviderType, ExitClusterConfig, ExitValidationPayload, ExitValidationBlob, SignedExitValidationMessage, ExistingExitValidationBlobData, FullExitBlob } from '../types';
+/**
+ * Exit validation and verification class for Obol distributed validators.
+ *
+ * This class provides functionality to validate and verify voluntary exit signatures
+ * for distributed validators in an Obol cluster. It handles both partial exit signatures
+ * from individual operators and payload signatures that authorize exit operations.
+ *
+ * The class supports:
+ * - Verification of BLS signatures for partial exit messages
+ * - Verification of ECDSA signatures for exit payload authorization
+ * - Validation of exit blobs against cluster configuration
+ * - Duplicate detection and epoch validation
+ *
+ * @example
+ * ```typescript
+ * const exit = new Exit(1, provider); // Mainnet with provider
+ *
+ * // Verify a partial exit signature
+ * const isValid = await exit.verifyPartialExitSignature(
+ *   publicShareKey,
+ *   signedExitMessage,
+ *   forkVersion,
+ *   genesisValidatorsRoot
+ * );
+ *
+ * // Validate exit blobs for a cluster
+ * const validBlobs = await exit.validateExitBlobs(
+ *   clusterConfig,
+ *   exitsPayload,
+ *   beaconNodeApiUrl,
+ *   existingBlobData
+ * );
+ * ```
+ */
+export declare class Exit {
+    readonly chainId: number;
+    readonly provider: ProviderType | undefined | null;
+    /**
+     * Creates a new Exit instance for validator exit operations.
+     *
+     * @param chainId - The Ethereum chain ID (e.g., 1 for mainnet, 5 for goerli)
+     * @param provider - Optional Ethereum provider for blockchain interactions
+     *
+     * @example
+     * ```typescript
+     * // For mainnet with a provider
+     * const exit = new Exit(1, provider);
+     *
+     * // For goerli testnet without provider
+     * const exit = new Exit(5, null);
+     * ```
+     */
+    constructor(chainId: number, provider: ProviderType | undefined | null);
+    /**
+     * Safely parse a string integer to number, using BigInt to avoid precision loss
+     * for large values beyond JavaScript's safe integer limit (2^53 - 1).
+     * Throws an error if the value exceeds the safe range for a 64-bit unsigned integer.
+     */
+    private static safeParseInt;
+    private static computePartialExitMessageRoot;
+    private static computeExitPayloadRoot;
+    /**
+     * Verifies a partial exit signature from a distributed validator operator.
+     *
+     * This method validates that a partial exit signature was correctly signed by the
+     * operator's share of the distributed validator's private key. It performs BLS
+     * signature verification using the appropriate fork version and genesis validators root.
+     *
+     * @param publicShareKey - The operator's public share key (BLS public key, hex string with or without 0x prefix)
+     * @param signedExitMessage - The signed exit message containing the exit details and signature
+     * @param forkVersion - The Ethereum fork version (e.g., "0x00000000" for mainnet)
+     * @param genesisValidatorsRootString - The genesis validators root for the network (hex string)
+     *
+     * @returns Promise resolving to true if the signature is valid, false otherwise
+     *
+     * @throws {Error} When unable to determine the Capella fork version for the given network
+     * @throws {Error} When BLS library initialization or verification fails
+     *
+     * @example
+     * ```typescript
+     * const isValid = await exit.verifyPartialExitSignature(
+     *   "0x1234...abcd", // operator's public share key
+     *   {
+     *     message: { epoch: "12345", validator_index: "67890" },
+     *     signature: "0xabcd...1234"
+     *   },
+     *   "0x00000000", // mainnet fork version
+     *   "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95"
+     * );
+     * ```
+     */
+    verifyPartialExitSignature(publicShareKey: string, signedExitMessage: SignedExitValidationMessage, forkVersion: string, genesisValidatorsRootString: string): Promise<boolean>;
+    /**
+     * Verifies the exit payload signature using the operator's ENR.
+     *
+     * This method validates that an exit payload was signed by the correct operator
+     * using ECDSA signature verification. The signature is verified against the
+     * operator's public key extracted from their ENR (Ethereum Node Record).
+     *
+     * @param enrString - The operator's ENR string containing their identity and public key
+     * @param exitsPayload - The exit validation payload containing partial exits and operator signature
+     *
+     * @returns Promise resolving to true if the payload signature is valid, false otherwise
+     *
+     * @throws {Error} When the ENR string is invalid or cannot be decoded
+     * @throws {Error} When the signature format is invalid (must be 130 hex characters)
+     * @throws {Error} When signature verification encounters an error
+     *
+     * @example
+     * ```typescript
+     * const isValid = await exit.verifyExitPayloadSignature(
+     *   "enr:-LK4QFo_n0dUm4PKejSOXf8JkSWq5EINV0XhG1zY00d...", // operator ENR
+     *   {
+     *     partial_exits: [exitBlob1, exitBlob2],
+     *     share_idx: 1,
+     *     signature: "0x1234...abcd" // ECDSA signature (130 hex chars)
+     *   }
+     * );
+     * ```
+     */
+    verifyExitPayloadSignature(enrString: string, exitsPayload: ExitValidationPayload): Promise<boolean>;
+    private validateOperatorAndPayload;
+    private getNetworkParameters;
+    private findValidatorInCluster;
+    private validateExistingBlobData;
+    private processExitBlob;
+    /**
+     * Validates exit blobs against cluster configuration and existing data.
+     *
+     * This method performs comprehensive validation of exit blobs including:
+     * - Operator authorization and payload signature verification
+     * - Network parameter validation (genesis root, fork version)
+     * - Public key validation against cluster configuration
+     * - Partial signature verification for each exit blob
+     * - Duplicate detection and epoch progression validation
+     * - Signature consistency checks for existing exits
+     *
+     * @param clusterConfig - The cluster configuration containing operators and distributed validators
+     * @param exitsPayload - The exit validation payload with partial exits and operator info
+     * @param beaconNodeApiUrl - The beacon node API URL for network parameter retrieval
+     * @param existingBlobData - Existing exit blob data for duplicate detection, or null if none exists
+     *
+     * @returns Promise resolving to an array of validated, non-duplicate exit blobs
+     *
+     * @throws {Error} When share_idx is invalid or out of bounds for the cluster operators
+     * @throws {Error} When payload signature verification fails
+     * @throws {Error} When network parameters cannot be retrieved or are invalid
+     * @throws {Error} When a public key is not found in the cluster's distributed validators
+     * @throws {Error} When a partial exit signature is invalid
+     * @throws {Error} When exit epoch validation fails (new epoch not greater than existing)
+     * @throws {Error} When validator index mismatches with existing data
+     * @throws {Error} When signature mismatches for the same epoch and operator
+     *
+     * @example
+     * ```typescript
+     * const validExitBlobs = await exit.validateExitBlobs(
+     *   {
+     *     definition: {
+     *       operators: [{ enr: "enr:-LK4Q..." }],
+     *       fork_version: "0x00000000",
+     *       threshold: 1
+     *     },
+     *     distributed_validators: [{
+     *       distributed_public_key: "0x1234...abcd",
+     *       public_shares: ["0x5678...efgh"]
+     *     }]
+     *   },
+     *   {
+     *     partial_exits: [exitBlob],
+     *     share_idx: 1,
+     *     signature: "0x1234...abcd"
+     *   },
+     *   "http://localhost:5052",
+     *   existingBlobData // or null for new exits
+     * );
+     * ```
+     */
+    validateExitBlobs(clusterConfig: ExitClusterConfig, exitsPayload: ExitValidationPayload, beaconNodeApiUrl: string, existingBlobData: ExistingExitValidationBlobData | null): Promise<ExitValidationBlob[]>;
+    /**
+     * Recombines exit blobs into a single exit blob.
+     *
+     * This method aggregates partial exit signatures from multiple operators into a single exit blob.
+     * It ensures that the signatures are properly ordered and aggregated according to the operator indices.
+     *
+     * @param exitBlob - The existing exit blob data containing partial exit signatures
+     *
+     * @returns Promise resolving to a single exit blob with aggregated signatures
+     *
+     * @throws {Error} When no valid signatures are found for aggregation
+     * @throws {Error} When signature length is invalid
+     * @throws {Error} When signature parsing fails
+     *
+     * @example
+     * ```typescript
+     * const aggregatedExitBlob = await exit.recombineExitBlobs(existingBlobData);
+     * ```
+     */
+    recombineExitBlobs(exitBlob: ExistingExitValidationBlobData): Promise<FullExitBlob>;
+}

package/dist/types/src/exits/verificationHelpers.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+export declare const GENESIS_VALIDATOR_ROOT_HEX_STRING = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * Computes the domain for a given domain type, fork version, and genesis state.
+ * https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#compute_domain
+ * @param domainType - Uint8Array representing the domain type (e.g., DOMAIN_VOLUNTARY_EXIT).
+ * @param forkVersionString - Hex string of the fork version (e.g., Capella fork version).
+ * @param genesisValidatorsRootOverride - Optional Uint8Array to override the default genesis validators root.
+ * @returns Uint8Array - The 32-byte domain.
+ */
+export declare function computeDomain(domainType: Uint8Array, // Should be 4 bytes
+forkVersionString: string, // Hex string, e.g., '0x03000000'
+genesisValidatorsRootOverride?: Uint8Array): Uint8Array;
+/**
+ * Convenience wrapper for computeSigningRoot.
+ * @param domain - Uint8Array of the domain.
+ * @param messageBuffer - Buffer of the message (SSZ object root).
+ * @returns Uint8Array - The signing root.
+ */
+export declare function signingRoot(domain: Uint8Array, messageBuffer: Buffer): Uint8Array;

package/dist/types/src/{incentiveHelpers.d.ts → incentives/incentiveHelpers.d.ts}

@@ -1,4 +1,4 @@
-import { type ProviderType, type SignerType, type ETH_ADDRESS } from './types';
+import { type ProviderType, type SignerType, type ETH_ADDRESS } from '../types';
 export declare const claimIncentivesFromMerkleDistributor: (incentivesData: {
     signer: SignerType;
     contractAddress: ETH_ADDRESS;

package/dist/types/src/{incentives.d.ts → incentives/incentives.d.ts}

@@ -1,4 +1,4 @@
-import { type ClaimableIncentives, type ETH_ADDRESS, type ProviderType, type SignerType, type ClaimIncentivesResponse } from './types';
+import { type ClaimableIncentives, type ETH_ADDRESS, type ProviderType, type SignerType, type ClaimIncentivesResponse } from '../types';
 /**
  * Incentives can be used for fetching and claiming Obol incentives.
  * @class

package/dist/types/src/index.d.ts

@@ -1,12 +1,14 @@
 import { Base } from './base.js';
 import { type RewardsSplitPayload, type ClusterDefinition, type ClusterLock, type ClusterPayload, type OperatorPayload, type TotalSplitPayload, type ClusterValidator, type ETH_ADDRESS, type OWRTranches, type ProviderType, type SignerType } from './types.js';
-import { Incentives } from './incentives.js';
+import { Incentives } from './incentives/incentives.js';
+import { Exit } from './exits/exit.js';
 export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
 export * from './verification/common.js';
 export * from './constants.js';
-export { Incentives } from './incentives.js';
+export { Incentives } from './incentives/incentives.js';
+export { Exit } from './exits/exit.js';
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */
@@ -20,6 +22,11 @@ export declare class Client extends Base {
      * @type {Incentives}
      */
     incentives: Incentives;
+    /**
+     * The exit module, responsible for managing exit validation.
+     * @type {Exit}
+     */
+    exit: Exit;
     /**
      * The blockchain provider, used to interact with the network.
      * It can be null, undefined, or a valid provider instance and defaults to the Signer provider if Signer is passed.
@@ -127,4 +134,11 @@ export declare class Client extends Base {
      * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L89)
      */
     getClusterLock(configHash: string): Promise<ClusterLock>;
+    /**
+     * @param lockHash - The configuration hash in cluster-definition
+     * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
+     * @throws On not found cluster definition or lock.
+     *
+     */
+    getClusterLockByHash(lockHash: string): Promise<ClusterLock>;
 }

package/dist/types/src/{splitHelpers.d.ts → splits/splitHelpers.d.ts}

@@ -1,4 +1,4 @@
-import { type OWRTranches, type ClusterValidator, type ETH_ADDRESS, type SplitRecipient, type SignerType } from './types';
+import { type OWRTranches, type ClusterValidator, type ETH_ADDRESS, type SplitRecipient, type SignerType } from '../types';
 type Call = {
     target: ETH_ADDRESS;
     callData: string;

package/dist/types/src/types.d.ts

@@ -254,3 +254,136 @@ export type SignerType = Signer | JsonRpcSigner | Wallet;
 export type ClaimIncentivesResponse = {
     txHash: string | null;
 };
+/**
+ * Represents the structure of an Ethereum operator for exit validation, primarily their ENR.
+ */
+export interface ExitOperator {
+    /** The operator's Ethereum Node Record (ENR). */
+    enr: string;
+}
+/**
+ * Represents the core definition of a cluster relevant for exit validation.
+ */
+export interface ExitClusterDefinition {
+    /** The cluster nodes operators with their ENRs. */
+    operators: ExitOperator[];
+    /** The cluster fork version. */
+    fork_version: string;
+    /** The distributed validator threshold. */
+    threshold: number;
+}
+/**
+ * Represents a distributed validator's information relevant for exit validation.
+ */
+export interface ExitDistributedValidator {
+    /** The public key of the distributed validator. */
+    distributed_public_key: string;
+    /** The public key shares of the distributed validator. */
+    public_shares: string[];
+}
+/**
+ * Combined cluster information needed for exit validation in the SDK.
+ */
+export interface ExitClusterConfig {
+    /** The cluster definition with operators, fork version and threshold. */
+    definition: ExitClusterDefinition;
+    /** The cluster distributed validators. */
+    distributed_validators: ExitDistributedValidator[];
+}
+/**
+ * Represents the message part of a signed exit for exit validation.
+ */
+export interface ExitValidationMessage {
+    /** The epoch at which the validator wishes to exit. */
+    epoch: string;
+    /** The index of the validator in the beacon chain. */
+    validator_index: string;
+}
+/**
+ * Represents a signed exit message for exit validation.
+ */
+export interface SignedExitValidationMessage {
+    /** The exit message containing epoch and validator index. */
+    message: ExitValidationMessage;
+    /** BLS signature of the exit message. */
+    signature: string;
+}
+/**
+ * Represents a single partial exit blob for exit validation.
+ */
+export interface ExitValidationBlob {
+    /** The public key of the validator to exit. */
+    public_key: string;
+    /** The signed exit message for the validator. */
+    signed_exit_message: SignedExitValidationMessage;
+}
+/**
+ * Represents the overall exit payload structure for exit validation.
+ */
+export interface ExitValidationPayload {
+    /** Array of partial exits for validators. */
+    partial_exits: ExitValidationBlob[];
+    /** Operator's share index (1-based). */
+    share_idx: number;
+    /** Signature of the ExitValidationPayload by the operator. */
+    signature: string;
+}
+/**
+ * Represents the data structure for an already existing exit blob for exit validation.
+ */
+export interface ExistingExitValidationBlobData {
+    /**
+     * The BLS public key of the validator in hex format
+     */
+    public_key: string;
+    /**
+     * The epoch number when the exit is scheduled to occur
+     */
+    epoch: string;
+    /**
+     * The unique index of the validator in the beacon chain
+     */
+    validator_index: string;
+    /**
+     * Array of distributed validator shares exit data, where each share contains
+     * the partial exit signature from each operator in the cluster
+     */
+    shares_exit_data: Array<Record<string, {
+        partial_exit_signature: string;
+    }>>;
+}
+export interface FullExitBlob {
+    /**
+     * The signed voluntary exit message containing the exit details and signature
+     */
+    signed_exit_message: {
+        /**
+         * The voluntary exit message details
+         */
+        message: {
+            /**
+             * The epoch number when the validator exit will be processed
+             */
+            epoch: string;
+            /**
+             * The unique index of the validator requesting to exit
+             */
+            validator_index: string;
+        };
+        /**
+         * The BLS12-381 hex-encoded signature of the exit message
+         */
+        signature: string;
+    };
+    /** The public key of the validator to exit. */
+    public_key: string;
+}
+/**
+ * Generic HTTP request function type.
+ * Args:
+ *  url: string - The URL to request.
+ *  config?: Record<string, any> - Optional request configuration (e.g., method, headers, body for POST).
+ * Returns:
+ *  Promise<any> - The response data.
+ */
+export type HttpRequestFunc = (url: string, config?: Record<string, any>) => Promise<any>;

package/dist/types/test/exit/verificationHelpers.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/incentives/incentives.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "A package for creating Distributed Validators using the Obol API.",
   "bugs": {
     "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -15,7 +15,7 @@
     "compile": "tsc -b ./tsconfig.cjs.json ./tsconfig.esm.json ./tsconfig.types.json",
     "build:clean": "rm -rf ./dist",
     "build": "npm-run-all build:clean compile",
-    "test": "jest ./test/*.test.ts",
+    "test": "jest test/**/*.spec.ts --testPathIgnorePatterns=test/sdk-package/",
     "generate-typedoc": "typedoc",
     "npm:publish": "npm publish --tag latest",
     "release": "release-it",
@@ -130,7 +130,7 @@
       "^bn.js$": "<rootDir>/node_modules/bn.js",
       "^asn1.js$": "<rootDir>/node_modules/asn1.js",
       "^hash.js$": "<rootDir>/node_modules/hash.js",
-      "(.+)\\.js": "$1"
+      "^(\\.\\.?\\/.+)\\.js$": "$1"
     },
     "extensionsToTreatAsEsm": [
       ".ts"

package/src/constants.ts

@@ -205,3 +205,16 @@ export const PROVIDER_MAP: Record<number, string> = {
   11155111: `${process.env.RPC_SEPOLIA}`, // Sepolia
   100: `${process.env.RPC_GNOSIS}`, // Gnosis
 };
+
+/**
+ * Maps base fork versions to their corresponding Capella fork versions.
+ * Example: Mainnet Capella fork version.
+ */
+export const CAPELLA_FORK_MAPPING: Record<string, string> = {
+  '0x00000000': '0x03000000', // Mainnet
+  '0x00001020': '0x03001020', // Goerli
+  '0x00000064': '0x03000064', // Gnosis
+  '0x90000069': '0x90000072', // Sepolia
+  '0x01017000': '0x04017000', // Holesky
+  '0x10000910': '0x40000910', // Hoodi
+};

package/src/exits/ethUtils.ts

@@ -0,0 +1,49 @@
+import { CAPELLA_FORK_MAPPING } from '../constants';
+
+/**
+ * Retrieves the Capella fork version for a given base fork version.
+ * @param fork_version - The base fork version string (e.g., '0x00000000' for mainnet).
+ * @returns A promise that resolves to the Capella fork version string, or null if not found.
+ */
+export async function getCapellaFork(
+  fork_version: string,
+): Promise<string | null> {
+  // Ensure the CAPELLA_FORK_MAPPING uses the base fork_version as key
+  if (CAPELLA_FORK_MAPPING[fork_version]) {
+    return CAPELLA_FORK_MAPPING[fork_version];
+  }
+  return null;
+}
+
+/**
+ * Fetches the genesis validators root from a beacon node.
+ * @param beaconNodeApiUrl - The base URL of the beacon node API (e.g., http://localhost:5052).
+ * @returns A promise that resolves to the genesis_validators_root string, or null on error.
+ * @throws Will throw an error if the network corresponding to the fork_version is not supported or if the HTTP request fails.
+ */
+export async function getGenesisValidatorsRoot(
+  beaconNodeApiUrl: string,
+): Promise<string | null> {
+  const genesisEndpoint = `${beaconNodeApiUrl}/eth/v1/beacon/genesis`;
+
+  try {
+    const response = await fetch(genesisEndpoint, {
+      method: 'GET',
+    });
+
+    const json = await response.json();
+
+    if (json.data?.genesis_validators_root) {
+      return json.data.genesis_validators_root;
+    }
+    console.error('Invalid response structure from genesis endpoint', json);
+    return null;
+  } catch (e: any) {
+    console.error(
+      `Error fetching genesis validators root from ${genesisEndpoint}:`,
+      e,
+    );
+    const errorMessage = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to fetch genesis validators root: ${errorMessage}`);
+  }
+}