@obolnetwork/obol-sdk 2.5.0 → 2.6.0

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,101 @@ 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 public key of the validator to exit. */
+    public_key: string;
+    /** The epoch at which the validator wishes to exit. */
+    epoch: string;
+    /** The index of the validator in the beacon chain. */
+    validator_index: string;
+    /** Collection of partial exit signatures from different shares. */
+    shares_exit_data: Array<Record<string, {
+        partial_exit_signature: 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.0",
+  "version": "2.6.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}`);
+  }
+}