@obolnetwork/obol-sdk 2.5.1 → 2.6.0

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.5.1",
+    "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/dist/cjs/src/constants.js

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROVIDER_MAP = exports.OBOL_SDK_EMAIL = exports.DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT = exports.DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT = exports.CHAIN_CONFIGURATION = exports.AVAILABLE_SPLITTER_CHAINS = exports.TERMS_AND_CONDITIONS_HASH = exports.TERMS_AND_CONDITIONS_URL = exports.TERMS_AND_CONDITIONS_VERSION = exports.ETHER_TO_GWEI = exports.DEFAULT_CHAIN_ID = exports.DEFAULT_BASE_VERSION = exports.DEFAULT_BASE_URL = exports.DefinitionFlow = exports.GENESIS_VALIDATOR_ROOT = exports.DOMAIN_DEPOSIT = exports.DOMAIN_APPLICATION_BUILDER = exports.SDK_VERSION = exports.CONFIG_VERSION = exports.DKG_ALGORITHM = exports.signEnrPayload = exports.signOperatorConfigHashPayload = exports.signCreatorConfigHashPayload = exports.ENRTypedMessage = exports.OperatorTypedMessage = exports.OperatorConfigHashSigningTypes = exports.EnrSigningTypes = exports.CreatorTypedMessage = exports.Domain = exports.TermsAndConditionsSigningTypes = exports.CreatorConfigHashSigningTypes = exports.EIP712_DOMAIN_VERSION = exports.EIP712_DOMAIN_NAME = exports.CONFLICT_ERROR_MSG = void 0;
+exports.CAPELLA_FORK_MAPPING = exports.PROVIDER_MAP = exports.OBOL_SDK_EMAIL = exports.DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT = exports.DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT = exports.CHAIN_CONFIGURATION = exports.AVAILABLE_SPLITTER_CHAINS = exports.TERMS_AND_CONDITIONS_HASH = exports.TERMS_AND_CONDITIONS_URL = exports.TERMS_AND_CONDITIONS_VERSION = exports.ETHER_TO_GWEI = exports.DEFAULT_CHAIN_ID = exports.DEFAULT_BASE_VERSION = exports.DEFAULT_BASE_URL = exports.DefinitionFlow = exports.GENESIS_VALIDATOR_ROOT = exports.DOMAIN_DEPOSIT = exports.DOMAIN_APPLICATION_BUILDER = exports.SDK_VERSION = exports.CONFIG_VERSION = exports.DKG_ALGORITHM = exports.signEnrPayload = exports.signOperatorConfigHashPayload = exports.signCreatorConfigHashPayload = exports.ENRTypedMessage = exports.OperatorTypedMessage = exports.OperatorConfigHashSigningTypes = exports.EnrSigningTypes = exports.CreatorTypedMessage = exports.Domain = exports.TermsAndConditionsSigningTypes = exports.CreatorConfigHashSigningTypes = exports.EIP712_DOMAIN_VERSION = exports.EIP712_DOMAIN_NAME = exports.CONFLICT_ERROR_MSG = void 0;
 const package_json_1 = __importDefault(require("../package.json"));
 const types_1 = require("./types");
 const bytecodes_1 = require("./bytecodes");
@@ -182,3 +182,15 @@ exports.PROVIDER_MAP = {
     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.
+ */
+exports.CAPELLA_FORK_MAPPING = {
+    '0x00000000': '0x03000000', // Mainnet
+    '0x00001020': '0x03001020', // Goerli
+    '0x00000064': '0x03000064', // Gnosis
+    '0x90000069': '0x90000072', // Sepolia
+    '0x01017000': '0x04017000', // Holesky
+    '0x10000910': '0x40000910', // Hoodi
+};

package/dist/cjs/src/exits/ethUtils.js

@@ -0,0 +1,57 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGenesisValidatorsRoot = exports.getCapellaFork = void 0;
+const constants_1 = require("../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.
+ */
+function getCapellaFork(fork_version) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Ensure the CAPELLA_FORK_MAPPING uses the base fork_version as key
+        if (constants_1.CAPELLA_FORK_MAPPING[fork_version]) {
+            return constants_1.CAPELLA_FORK_MAPPING[fork_version];
+        }
+        return null;
+    });
+}
+exports.getCapellaFork = getCapellaFork;
+/**
+ * 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.
+ */
+function getGenesisValidatorsRoot(beaconNodeApiUrl) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const genesisEndpoint = `${beaconNodeApiUrl}/eth/v1/beacon/genesis`;
+        try {
+            const response = yield fetch(genesisEndpoint, {
+                method: 'GET',
+            });
+            const json = yield response.json();
+            if ((_a = json.data) === null || _a === void 0 ? void 0 : _a.genesis_validators_root) {
+                return json.data.genesis_validators_root;
+            }
+            console.error('Invalid response structure from genesis endpoint', json);
+            return null;
+        }
+        catch (e) {
+            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}`);
+        }
+    });
+}
+exports.getGenesisValidatorsRoot = getGenesisValidatorsRoot;

package/dist/cjs/src/exits/exit.js

@@ -0,0 +1,420 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Exit = void 0;
+const discv5_1 = require("@chainsafe/discv5");
+const elliptic = __importStar(require("elliptic"));
+const bls_1 = require("@chainsafe/bls");
+const ssz_1 = require("@chainsafe/ssz");
+const ethUtils_1 = require("./ethUtils");
+const verificationHelpers_1 = require("./verificationHelpers");
+// Constants from obol-api/src/verification/exit.ts (assuming these might be needed or were in the original context)
+const DOMAIN_VOLUNTARY_EXIT = '0x04000000';
+// SSZ Type Definitions (adapted from obol-api/src/verification/exit.ts)
+const SSZExitMessageType = new ssz_1.ContainerType({
+    epoch: new ssz_1.UintNumberType(8),
+    validator_index: new ssz_1.UintNumberType(8),
+});
+const SSZPartialExitsPayloadType = new ssz_1.ContainerType({
+    partial_exits: new ssz_1.ListCompositeType(new ssz_1.ContainerType({
+        public_key: new ssz_1.ByteVectorType(48),
+        signed_exit_message: new ssz_1.ContainerType({
+            message: new ssz_1.ContainerType({
+                epoch: new ssz_1.UintNumberType(8),
+                validator_index: new ssz_1.UintNumberType(8),
+            }),
+            signature: new ssz_1.ByteVectorType(96),
+        }),
+    }), 65536),
+    share_idx: new ssz_1.UintNumberType(8),
+});
+/**
+ * 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
+ * );
+ * ```
+ */
+class Exit {
+    /**
+     * 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, provider) {
+        this.chainId = chainId;
+        this.provider = provider;
+    }
+    /**
+     * 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.
+     */
+    static safeParseInt(value) {
+        const bigIntValue = BigInt(value);
+        // Check if value is within the range of a 64-bit unsigned integer
+        const MAX_UINT64 = BigInt('0xFFFFFFFFFFFFFFFF');
+        if (bigIntValue < 0 || bigIntValue > MAX_UINT64) {
+            throw new Error(`Value ${value} is outside the valid range for a 64-bit unsigned integer`);
+        }
+        // Convert to number - SSZ library should handle values even if they exceed JS safe integer limits
+        return Number(bigIntValue);
+    }
+    static computePartialExitMessageRoot(msg) {
+        const sszValue = SSZExitMessageType.defaultValue();
+        sszValue.epoch = Exit.safeParseInt(msg.epoch);
+        sszValue.validator_index = Exit.safeParseInt(msg.validator_index);
+        return Buffer.from(SSZExitMessageType.hashTreeRoot(sszValue).buffer);
+    }
+    static computeExitPayloadRoot(exits) {
+        // Remove sorting since SSZ list ordering guarantees order
+        // This eliminates the O(n log n) sort and improves performance
+        const sszValue = SSZPartialExitsPayloadType.defaultValue();
+        sszValue.partial_exits = exits.partial_exits.map(pe => ({
+            public_key: (0, ssz_1.fromHexString)(pe.public_key),
+            signed_exit_message: {
+                message: {
+                    epoch: Exit.safeParseInt(pe.signed_exit_message.message.epoch),
+                    validator_index: Exit.safeParseInt(pe.signed_exit_message.message.validator_index),
+                },
+                signature: (0, ssz_1.fromHexString)(pe.signed_exit_message.signature),
+            },
+        }));
+        sszValue.share_idx = exits.share_idx;
+        return Buffer.from(SSZPartialExitsPayloadType.hashTreeRoot(sszValue).buffer).toString('hex');
+    }
+    /**
+     * 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, signedExitMessage, forkVersion, genesisValidatorsRootString) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (0, bls_1.init)('herumi');
+            const capellaForkVersionString = yield (0, ethUtils_1.getCapellaFork)(forkVersion);
+            if (!capellaForkVersionString) {
+                throw new Error(`Could not determine Capella fork version for base fork: ${forkVersion}`);
+            }
+            const partialExitMessageBuffer = Exit.computePartialExitMessageRoot(signedExitMessage.message);
+            const exitDomain = (0, verificationHelpers_1.computeDomain)((0, ssz_1.fromHexString)(DOMAIN_VOLUNTARY_EXIT), capellaForkVersionString, (0, ssz_1.fromHexString)(genesisValidatorsRootString));
+            const messageSigningRoot = (0, verificationHelpers_1.signingRoot)(exitDomain, partialExitMessageBuffer);
+            return (0, bls_1.verify)((0, ssz_1.fromHexString)(publicShareKey), messageSigningRoot, (0, ssz_1.fromHexString)(signedExitMessage.signature));
+        });
+    }
+    /**
+     * 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, exitsPayload) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const partialExitsDtoHashRoot = Exit.computeExitPayloadRoot(exitsPayload);
+            const ec = new elliptic.ec('secp256k1');
+            let pubKeyHex;
+            try {
+                pubKeyHex = discv5_1.ENR.decodeTxt(enrString).publicKey.toString('hex');
+            }
+            catch (e) {
+                throw new Error(`Invalid ENR string: ${enrString}. Error: ${(_a = e.message) !== null && _a !== void 0 ? _a : String(e)}`);
+            }
+            const sigHex = exitsPayload.signature.startsWith('0x')
+                ? exitsPayload.signature.substring(2)
+                : exitsPayload.signature;
+            if (sigHex.length !== 130) {
+                throw new Error(`Invalid signature length. Expected 130 hex chars (r + s), got ${sigHex.length}`);
+            }
+            const r = sigHex.slice(0, 64);
+            const s = sigHex.slice(64, 128);
+            const enrSignature = { r, s };
+            try {
+                return ec
+                    .keyFromPublic(pubKeyHex, 'hex')
+                    .verify(partialExitsDtoHashRoot, enrSignature);
+            }
+            catch (e) {
+                throw new Error(`Signature verification failed: ${(_b = e.message) !== null && _b !== void 0 ? _b : String(e)}`);
+            }
+        });
+    }
+    validateOperatorAndPayload(clusterConfig, exitsPayload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const operatorIndex = exitsPayload.share_idx - 1;
+            if (operatorIndex < 0 ||
+                operatorIndex >= clusterConfig.definition.operators.length) {
+                throw new Error(`Invalid share_idx ${exitsPayload.share_idx} for ${clusterConfig.definition.operators.length} operators.`);
+            }
+            const operatorEnr = clusterConfig.definition.operators[operatorIndex].enr;
+            const isPayloadSignatureValid = yield this.verifyExitPayloadSignature(operatorEnr, exitsPayload);
+            if (!isPayloadSignatureValid) {
+                throw new Error('Incorrect payload signature for partial exits.');
+            }
+            return operatorEnr;
+        });
+    }
+    getNetworkParameters(forkVersion, beaconNodeApiUrl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const genesisValidatorsRootString = yield (0, ethUtils_1.getGenesisValidatorsRoot)(beaconNodeApiUrl);
+            if (!genesisValidatorsRootString) {
+                throw new Error('Could not retrieve genesis validators root.');
+            }
+            const capellaForkVersionString = yield (0, ethUtils_1.getCapellaFork)(forkVersion);
+            if (!capellaForkVersionString) {
+                throw new Error(`Unsupported network: Could not determine Capella fork for ${forkVersion}`);
+            }
+            return {
+                genesisValidatorsRoot: genesisValidatorsRootString,
+                capellaForkVersion: capellaForkVersionString,
+            };
+        });
+    }
+    findValidatorInCluster(clusterConfig, publicKey, operatorIndex) {
+        const validatorInCluster = clusterConfig.distributed_validators.find(dv => (dv.distributed_public_key.startsWith('0x')
+            ? dv.distributed_public_key
+            : '0x' + dv.distributed_public_key).toLowerCase() ===
+            (publicKey.startsWith('0x')
+                ? publicKey
+                : '0x' + publicKey).toLowerCase());
+        if (!validatorInCluster) {
+            throw new Error(`Public key ${publicKey} not found in the cluster's distributed validators.`);
+        }
+        const publicShareForOperator = validatorInCluster.public_shares[operatorIndex];
+        if (!publicShareForOperator) {
+            throw new Error(`Public share for operator index ${operatorIndex} not found for validator ${publicKey}`);
+        }
+        return {
+            validator: validatorInCluster,
+            publicShare: publicShareForOperator,
+        };
+    }
+    validateExistingBlobData(exitBlob, existingBlob, operatorIndex) {
+        var _a, _b, _c;
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!existingBlob) {
+                return false;
+            }
+            // Check if existing blob data is for this public key
+            const normalizeKey = (key) => (key.startsWith('0x') ? key : '0x' + key).toLowerCase();
+            if (normalizeKey(existingBlob.public_key) !==
+                normalizeKey(exitBlob.public_key)) {
+                return false; // Existing blob data is for a different validator
+            }
+            if (existingBlob.validator_index !==
+                exitBlob.signed_exit_message.message.validator_index) {
+                throw new Error(`Validator index mismatch for already processed exit for public key ${exitBlob.public_key}. Expected ${existingBlob.validator_index}, got ${exitBlob.signed_exit_message.message.validator_index}.`);
+            }
+            const currentEpoch = Exit.safeParseInt(exitBlob.signed_exit_message.message.epoch);
+            const existingEpoch = Exit.safeParseInt(existingBlob.epoch);
+            if (currentEpoch < existingEpoch) {
+                throw new Error(`New exit epoch ${currentEpoch} is not greater than existing exit epoch ${existingEpoch} for validator ${exitBlob.public_key}.`);
+            }
+            else if (currentEpoch === existingEpoch) {
+                const operatorShareIndexString = String(operatorIndex);
+                if (((_c = (_b = (_a = existingBlob.shares_exit_data) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b[operatorShareIndexString]) === null || _c === void 0 ? void 0 : _c.partial_exit_signature) &&
+                    existingBlob.shares_exit_data[0][operatorShareIndexString]
+                        .partial_exit_signature !== exitBlob.signed_exit_message.signature) {
+                    throw new Error(`Signature mismatch for validator ${exitBlob.public_key}, operator index ${operatorIndex} at epoch ${currentEpoch}. Received different signature than existing.`);
+                }
+                return true; // Already processed
+            }
+            return false;
+        });
+    }
+    processExitBlob(exitBlob, clusterConfig, operatorIndex, genesisValidatorsRoot, existingBlobData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { publicShare } = this.findValidatorInCluster(clusterConfig, exitBlob.public_key, operatorIndex);
+            const alreadyProcessed = yield this.validateExistingBlobData(exitBlob, existingBlobData, operatorIndex);
+            if (alreadyProcessed) {
+                return null;
+            }
+            const isPartialSignatureValid = yield this.verifyPartialExitSignature(publicShare, exitBlob.signed_exit_message, clusterConfig.definition.fork_version, genesisValidatorsRoot);
+            if (!isPartialSignatureValid) {
+                throw new Error(`Invalid partial exit signature for validator ${exitBlob.public_key} by operator index ${operatorIndex}.`);
+            }
+            return exitBlob;
+        });
+    }
+    /**
+     * 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, exitsPayload, beaconNodeApiUrl, existingBlobData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.validateOperatorAndPayload(clusterConfig, exitsPayload);
+            const { genesisValidatorsRoot } = yield this.getNetworkParameters(clusterConfig.definition.fork_version, beaconNodeApiUrl);
+            const operatorIndex = exitsPayload.share_idx - 1;
+            const validNonDuplicateBlobs = [];
+            for (const currentExitBlob of exitsPayload.partial_exits) {
+                const processedBlob = yield this.processExitBlob(currentExitBlob, clusterConfig, operatorIndex, genesisValidatorsRoot, existingBlobData);
+                if (processedBlob) {
+                    validNonDuplicateBlobs.push(processedBlob);
+                }
+            }
+            return validNonDuplicateBlobs;
+        });
+    }
+}
+exports.Exit = Exit;

package/dist/cjs/src/exits/verificationHelpers.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signingRoot = exports.computeDomain = exports.GENESIS_VALIDATOR_ROOT_HEX_STRING = void 0;
+const ssz_1 = require("@chainsafe/ssz");
+// From obol-api/src/verification/common.ts
+exports.GENESIS_VALIDATOR_ROOT_HEX_STRING = '0x0000000000000000000000000000000000000000000000000000000000000000'; // Added 0x prefix
+const ForkDataType = new ssz_1.ContainerType({
+    currentVersion: new ssz_1.ByteVectorType(4),
+    genesisValidatorsRoot: new ssz_1.ByteVectorType(32),
+});
+const SigningRootType = new ssz_1.ContainerType({
+    objectRoot: new ssz_1.ByteVectorType(32),
+    domain: new ssz_1.ByteVectorType(32),
+});
+/**
+ * https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#compute_fork_data_root
+ * @param currentVersion - Uint8Array of the current fork version.
+ * @param genesisValidatorsRoot - Uint8Array of the genesis validators root.
+ * @returns Uint8Array - The 32-byte fork data root.
+ */
+function computeForkDataRoot(currentVersion, genesisValidatorsRoot) {
+    const forkDataVal = ForkDataType.defaultValue();
+    forkDataVal.currentVersion = currentVersion;
+    forkDataVal.genesisValidatorsRoot = genesisValidatorsRoot;
+    return Buffer.from(ForkDataType.hashTreeRoot(forkDataVal).buffer);
+}
+/**
+ * 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.
+ */
+function computeDomain(domainType, // Should be 4 bytes
+forkVersionString, // Hex string, e.g., '0x03000000'
+genesisValidatorsRootOverride) {
+    const forkVersionBytes = (0, ssz_1.fromHexString)(forkVersionString.substring(2, forkVersionString.length));
+    if (forkVersionBytes.length !== 4) {
+        throw new Error('Fork version must be 4 bytes');
+    }
+    if (domainType.length !== 4) {
+        throw new Error('Domain type must be 4 bytes');
+    }
+    const actualGenesisValidatorsRoot = genesisValidatorsRootOverride !== null && genesisValidatorsRootOverride !== void 0 ? genesisValidatorsRootOverride : (0, ssz_1.fromHexString)(exports.GENESIS_VALIDATOR_ROOT_HEX_STRING.substring(2));
+    if (actualGenesisValidatorsRoot.length !== 32) {
+        throw new Error('genesisValidatorsRoot must be 32 bytes');
+    }
+    const forkDataRoot = computeForkDataRoot(forkVersionBytes, actualGenesisValidatorsRoot);
+    const domain = new Uint8Array(32);
+    domain.set(domainType);
+    domain.set(forkDataRoot.subarray(0, 28), 4); // Set the remaining 28 bytes from forkDataRoot
+    return domain;
+}
+exports.computeDomain = computeDomain;
+/**
+ * Computes the signing root for an SSZ object and a domain.
+ * https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#compute_signing_root
+ * @param sszObjectRoot - Uint8Array of the hash tree root of the SSZ object.
+ * @param domain - Uint8Array of the domain.
+ * @returns Uint8Array - The 32-byte signing root.
+ */
+function computeSigningRoot(sszObjectRoot, // Should be 32 bytes
+domain) {
+    if (sszObjectRoot.length !== 32) {
+        throw new Error('SSZ object root must be 32 bytes');
+    }
+    if (domain.length !== 32) {
+        throw new Error('Domain must be 32 bytes');
+    }
+    const val = SigningRootType.defaultValue();
+    val.objectRoot = sszObjectRoot;
+    val.domain = domain;
+    return Buffer.from(SigningRootType.hashTreeRoot(val).buffer);
+}
+/**
+ * Convenience wrapper for computeSigningRoot.
+ * @param domain - Uint8Array of the domain.
+ * @param messageBuffer - Buffer of the message (SSZ object root).
+ * @returns Uint8Array - The signing root.
+ */
+function signingRoot(domain, messageBuffer) {
+    const sszObjectRootU8 = Uint8Array.from(messageBuffer);
+    return computeSigningRoot(sszObjectRootU8, domain);
+}
+exports.signingRoot = signingRoot;

package/dist/cjs/src/{incentiveHelpers.js → incentives/incentiveHelpers.js}

@@ -11,7 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isClaimedFromMerkleDistributor = exports.claimIncentivesFromMerkleDistributor = void 0;
 const ethers_1 = require("ethers");
-const MerkleDistributorWithDeadline_1 = require("./abi/MerkleDistributorWithDeadline");
+const MerkleDistributorWithDeadline_1 = require("../abi/MerkleDistributorWithDeadline");
 const claimIncentivesFromMerkleDistributor = (incentivesData) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const contract = new ethers_1.Contract(incentivesData.contractAddress, MerkleDistributorWithDeadline_1.MerkleDistributorABI.abi, incentivesData.signer);

package/dist/cjs/src/{incentives.js → incentives/incentives.js}

@@ -10,10 +10,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Incentives = void 0;
-const utils_1 = require("./utils");
-const types_1 = require("./types");
+const utils_1 = require("../utils");
+const types_1 = require("../types");
 const incentiveHelpers_1 = require("./incentiveHelpers");
-const constants_1 = require("./constants");
+const constants_1 = require("../constants");
 /**
  * Incentives can be used for fetching and claiming Obol incentives.
  * @class