@obolnetwork/obol-sdk 2.5.1 → 2.6.0

package/dist/esm/test/exit/exit.spec.js

@@ -0,0 +1,303 @@
+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());
+    });
+};
+import { Exit } from '../../src/exits/exit';
+import * as ethUtils from '../../src/exits/ethUtils';
+import * as bls from '@chainsafe/bls';
+import { ENR } from '@chainsafe/discv5';
+import * as elliptic from 'elliptic';
+import { CAPELLA_FORK_MAPPING } from '../../src/constants';
+import { fromHexString } from '@chainsafe/ssz';
+import * as verificationHelpers from '../../src/exits/verificationHelpers';
+// --- Mocks ---
+jest.mock('../../src/exits/ethUtils');
+jest.mock('@chainsafe/bls', () => {
+    const actual = jest.requireActual('@chainsafe/bls');
+    return Object.assign(Object.assign({ __esModule: true }, actual), { init: jest.fn(), verify: jest.fn() });
+});
+// ENR and elliptic will be spied on, not fully mocked at module level for more flexibility
+const mockedEthUtils = ethUtils;
+const mockedBls = bls;
+// --- Test Data ---
+const MAINNET_BASE_FORK_VERSION = '0x00000000';
+const MAINNET_CAPELLA_FORK_VERSION = CAPELLA_FORK_MAPPING[MAINNET_BASE_FORK_VERSION];
+const MOCK_GENESIS_ROOT = '0x0000000000000000000000000000000000000000000000000000000000000001';
+const MOCK_BEACON_API_URL = 'http://localhost:5052';
+const mockOperatorEnr = 'enr:-LK4QFo_n0dUm4PKejSOXf8JkSWq5EINV0XhG1zY00d22QpYdyxSAyQNsGkYQyKR5Ohe2kEkmS0nS31tuqVfXDNf_vEAhGV0aAgQD___2iXChwcEChAgAAAAADg__________g2V0aMfLCGgohEAcNlBpLdCgAAAQAdIaENsZS0CAAAABAAAAAAAAAAAAAAAAAAAAACAAAAAAAAAAIAAAAAAAAAAIAAAAAAAAAYAAAAAAAAAAAAAAAAAAAIQA___________gmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKwrO7sVJzX4B2vW1bTqWCpGA93R2aZqa2ZCrqSrh8CYN1ZHCCIyg';
+const mockOperatorPublicKeyHex = '03ca0aceeec549cd7f8076bd6d5b4ea582a4603ddd1d9a66a6b6642aeaa4ae1f09';
+const mockExitMessage = {
+    epoch: '1',
+    validator_index: '10',
+};
+const mockSignedExitMessage = {
+    message: mockExitMessage,
+    signature: '0x' + 'ab'.repeat(96),
+};
+const mockExitBlob = {
+    public_key: '0x' + 'cd'.repeat(48),
+    signed_exit_message: mockSignedExitMessage,
+};
+const mockExitPayload = {
+    partial_exits: [mockExitBlob],
+    share_idx: 1,
+    signature: '0x' + 'ef'.repeat(65),
+};
+// Make mockClusterConfig directly ExitClusterConfig for easier use in tests
+const mockClusterConfig = {
+    definition: {
+        operators: [{ enr: mockOperatorEnr }],
+        fork_version: MAINNET_BASE_FORK_VERSION,
+        threshold: 1,
+    },
+    distributed_validators: [
+        {
+            distributed_public_key: mockExitBlob.public_key,
+            public_shares: ['0x' + 'aa'.repeat(48)],
+        },
+    ],
+};
+const mockExistingBlobData = {
+    public_key: mockExitBlob.public_key,
+    epoch: mockExitMessage.epoch,
+    validator_index: mockExitMessage.validator_index,
+    shares_exit_data: [],
+};
+describe('exit', () => {
+    let enrDecodeTxtSpy;
+    let ecVerifySpy;
+    let keyFromPublicSpy;
+    let exit;
+    beforeEach(() => {
+        jest.resetAllMocks();
+        exit = new Exit(1, null);
+        mockedBls.init.mockResolvedValue(undefined);
+        mockedBls.verify.mockReturnValue(true);
+        mockedEthUtils.getCapellaFork.mockResolvedValue(MAINNET_CAPELLA_FORK_VERSION);
+        mockedEthUtils.getGenesisValidatorsRoot.mockResolvedValue(MOCK_GENESIS_ROOT);
+        const mockDecodedENR = {
+            publicKey: Buffer.from(mockOperatorPublicKeyHex, 'hex'),
+        };
+        enrDecodeTxtSpy = jest
+            .spyOn(ENR, 'decodeTxt')
+            .mockReturnValue(mockDecodedENR);
+        ecVerifySpy = jest.fn().mockReturnValue(true);
+        keyFromPublicSpy = jest.spyOn(elliptic.ec.prototype, 'keyFromPublic');
+        keyFromPublicSpy.mockImplementation(function () {
+            return { verify: ecVerifySpy };
+        });
+    });
+    afterEach(() => {
+        if (enrDecodeTxtSpy)
+            enrDecodeTxtSpy.mockRestore();
+        jest.restoreAllMocks();
+    });
+    describe('verifyPartialExitSignature', () => {
+        const publicShareKey = mockClusterConfig.distributed_validators[0].public_shares[0];
+        it('should return true for a valid signature', () => __awaiter(void 0, void 0, void 0, function* () {
+            const isValid = yield exit.verifyPartialExitSignature(publicShareKey, mockSignedExitMessage, MAINNET_BASE_FORK_VERSION, MOCK_GENESIS_ROOT);
+            expect(isValid).toBe(true);
+            expect(mockedBls.init).toHaveBeenCalledWith('herumi');
+            expect(mockedBls.verify).toHaveBeenCalled();
+            expect(mockedEthUtils.getCapellaFork).toHaveBeenCalledWith(MAINNET_BASE_FORK_VERSION);
+        }));
+        it('should return false if BLS verification fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedBls.verify.mockReturnValue(false);
+            const isValid = yield exit.verifyPartialExitSignature(publicShareKey, mockSignedExitMessage, MAINNET_BASE_FORK_VERSION, MOCK_GENESIS_ROOT);
+            expect(isValid).toBe(false);
+        }));
+        it('should throw if getCapellaFork returns null', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedEthUtils.getCapellaFork.mockResolvedValue(null);
+            yield expect(exit.verifyPartialExitSignature(publicShareKey, mockSignedExitMessage, MAINNET_BASE_FORK_VERSION, MOCK_GENESIS_ROOT)).rejects.toThrow('Could not determine Capella fork version');
+        }));
+        it('should call computeDomain and signingRoot with correct parameters', () => __awaiter(void 0, void 0, void 0, function* () {
+            const computeDomainSpy = jest.spyOn(verificationHelpers, 'computeDomain');
+            const signingRootSpy = jest.spyOn(verificationHelpers, 'signingRoot');
+            yield exit.verifyPartialExitSignature(publicShareKey, mockSignedExitMessage, MAINNET_BASE_FORK_VERSION, MOCK_GENESIS_ROOT);
+            expect(computeDomainSpy).toHaveBeenCalledWith(fromHexString('04000000'), MAINNET_CAPELLA_FORK_VERSION, fromHexString(MOCK_GENESIS_ROOT.substring(2)));
+            expect(signingRootSpy).toHaveBeenCalled();
+            computeDomainSpy.mockRestore();
+            signingRootSpy.mockRestore();
+        }));
+    });
+    describe('verifyExitPayloadSignature', () => {
+        it('should return true for a valid ECDSA signature', () => __awaiter(void 0, void 0, void 0, function* () {
+            const isValid = yield exit.verifyExitPayloadSignature(mockOperatorEnr, mockExitPayload);
+            expect(isValid).toBe(true);
+            expect(enrDecodeTxtSpy).toHaveBeenCalledWith(mockOperatorEnr);
+            expect(ecVerifySpy).toHaveBeenCalled();
+        }));
+        it('should return false if ECDSA verification fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            ecVerifySpy.mockReturnValue(false);
+            const isValid = yield exit.verifyExitPayloadSignature(mockOperatorEnr, mockExitPayload);
+            expect(isValid).toBe(false);
+        }));
+        it('should throw if ENR is invalid', () => __awaiter(void 0, void 0, void 0, function* () {
+            enrDecodeTxtSpy.mockImplementation(() => {
+                throw new Error('Invalid ENR');
+            });
+            yield expect(exit.verifyExitPayloadSignature('invalid-enr', mockExitPayload)).rejects.toThrow('Invalid ENR string');
+        }));
+        it('should throw if signature hex is not 128 characters (excluding 0x)', () => __awaiter(void 0, void 0, void 0, function* () {
+            const payloadWithInvalidSig = Object.assign(Object.assign({}, mockExitPayload), { signature: '0x123456' });
+            yield expect(exit.verifyExitPayloadSignature(mockOperatorEnr, payloadWithInvalidSig)).rejects.toThrow('Invalid signature length');
+        }));
+    });
+    describe('validateExitBlobs', () => {
+        it('should successfully validate a new, valid exit blob', () => __awaiter(void 0, void 0, void 0, function* () {
+            const result = yield exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, null);
+            expect(result).toEqual([mockExitBlob]);
+            expect(ecVerifySpy).toHaveBeenCalled(); // Called by internal verifyExitPayloadSignature
+            expect(mockedBls.verify).toHaveBeenCalled(); // Called by internal verifyPartialExitSignature
+        }));
+        it('should throw if operatorIndex (from share_idx) is out of bounds', () => __awaiter(void 0, void 0, void 0, function* () {
+            const invalidPayload = Object.assign(Object.assign({}, mockExitPayload), { share_idx: 0 });
+            yield expect(exit.validateExitBlobs(mockClusterConfig, invalidPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Invalid share_idx');
+            const invalidPayload2 = Object.assign(Object.assign({}, mockExitPayload), { share_idx: mockClusterConfig.definition.operators.length + 1 });
+            yield expect(exit.validateExitBlobs(mockClusterConfig, invalidPayload2, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Invalid share_idx');
+        }));
+        it('should throw if payload signature is invalid', () => __awaiter(void 0, void 0, void 0, function* () {
+            ecVerifySpy.mockReturnValue(false);
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Incorrect payload signature');
+        }));
+        it('should throw if getGenesisValidatorsRoot returns null', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedEthUtils.getGenesisValidatorsRoot.mockResolvedValue(null);
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Could not retrieve genesis validators root');
+        }));
+        it('should throw if getCapellaFork returns null (unsupported network)', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedEthUtils.getCapellaFork.mockResolvedValue(null);
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Unsupported network: Could not determine Capella fork');
+        }));
+        it('should throw if a public key in an exit blob is not found in cluster config', () => __awaiter(void 0, void 0, void 0, function* () {
+            const blobWithUnknownKey = Object.assign(Object.assign({}, mockExitBlob), { public_key: '0x' + 'deadbeef'.repeat(12) });
+            const payloadWithUnknownKey = Object.assign(Object.assign({}, mockExitPayload), { partial_exits: [blobWithUnknownKey] });
+            yield expect(exit.validateExitBlobs(mockClusterConfig, payloadWithUnknownKey, MOCK_BEACON_API_URL, null)).rejects.toThrow("Public key 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef not found in the cluster's distributed validators.");
+        }));
+        it('should throw if a partial exit signature is invalid', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedBls.verify.mockReturnValue(false);
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, null)).rejects.toThrow('Invalid partial exit signature for validator 0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd by operator index 0.');
+        }));
+        it('should return an empty array if an exit blob has already been processed (epoch match)', () => __awaiter(void 0, void 0, void 0, function* () {
+            const result = yield exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData);
+            expect(result).toEqual([]);
+        }));
+        it('should throw if an exit blob has been processed with a different validator index', () => __awaiter(void 0, void 0, void 0, function* () {
+            const existingBlobWithDifferentIndex = {
+                public_key: mockExitBlob.public_key,
+                epoch: mockExitMessage.epoch,
+                validator_index: (parseInt(mockExitMessage.validator_index, 10) + 1).toString(), // Different index
+                shares_exit_data: [],
+            };
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, existingBlobWithDifferentIndex)).rejects.toThrow('Validator index mismatch for already processed exit for public key 0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd. Expected 11, got 10.');
+        }));
+        it('should throw if an exit blob has been processed with a higher epoch', () => __awaiter(void 0, void 0, void 0, function* () {
+            const existingBlobWithHigherEpoch = {
+                public_key: mockExitBlob.public_key,
+                epoch: (parseInt(mockExitMessage.epoch, 10) + 1).toString(), // Existing epoch is HIGHER (e.g. 2)
+                validator_index: mockExitMessage.validator_index,
+                shares_exit_data: [],
+            };
+            // currentExitBlob (from mockExitPayload) has mockExitMessage.epoch (e.g. '1')
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, existingBlobWithHigherEpoch)).rejects.toThrow('New exit epoch 1 is not greater than existing exit epoch 2 for validator 0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd.');
+        }));
+        it('should successfully validate if an exit blob has been processed with a lower epoch', () => __awaiter(void 0, void 0, void 0, function* () {
+            const existingBlobWithLowerEpoch = {
+                public_key: mockExitBlob.public_key,
+                epoch: (parseInt(mockExitMessage.epoch, 10) - 1).toString(),
+                validator_index: mockExitMessage.validator_index,
+                shares_exit_data: [],
+            };
+            const result = yield exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, existingBlobWithLowerEpoch);
+            expect(result).toEqual([mockExitBlob]);
+        }));
+        it('should throw on signature mismatch for existing blob with same epoch', () => __awaiter(void 0, void 0, void 0, function* () {
+            const operatorIndex = 0;
+            const operatorShareIndexString = String(operatorIndex);
+            const existingBlobWithDifferentSignature = {
+                public_key: mockExitBlob.public_key,
+                epoch: mockExitMessage.epoch,
+                validator_index: mockExitMessage.validator_index,
+                shares_exit_data: [
+                    {
+                        [operatorShareIndexString]: {
+                            partial_exit_signature: '0x' + 'different'.repeat(16),
+                        },
+                    },
+                ],
+            };
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, existingBlobWithDifferentSignature)).rejects.toThrow('Signature mismatch for validator 0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd, operator index 0 at epoch 1.');
+        }));
+        it('should handle multiple blobs, some new, some already processed', () => __awaiter(void 0, void 0, void 0, function* () {
+            const anotherMockExitBlob = {
+                public_key: '0x' + '11'.repeat(48),
+                signed_exit_message: {
+                    message: { epoch: '2', validator_index: '20' },
+                    signature: '0x' + 'bb'.repeat(96),
+                },
+            };
+            const payloadWithTwoBlobs = Object.assign(Object.assign({}, mockExitPayload), { partial_exits: [mockExitBlob, anotherMockExitBlob] });
+            const clusterConfigWithTwoValidators = Object.assign(Object.assign({}, mockClusterConfig), { distributed_validators: [
+                    ...mockClusterConfig.distributed_validators,
+                    {
+                        distributed_public_key: anotherMockExitBlob.public_key,
+                        public_shares: ['0x' + 'cc'.repeat(48)],
+                    },
+                ] });
+            // Only the first blob has existing data, second is new
+            const existingBlobDataForFirstOnly = {
+                public_key: mockExitBlob.public_key,
+                epoch: mockExitMessage.epoch,
+                validator_index: mockExitMessage.validator_index,
+                shares_exit_data: [],
+            };
+            const result = yield exit.validateExitBlobs(clusterConfigWithTwoValidators, payloadWithTwoBlobs, MOCK_BEACON_API_URL, existingBlobDataForFirstOnly);
+            expect(result.length).toBe(1);
+            expect(result[0]).toEqual(anotherMockExitBlob);
+        }));
+        it('should throw if getGenesisValidatorsRoot itself throws an error', () => __awaiter(void 0, void 0, void 0, function* () {
+            mockedEthUtils.getGenesisValidatorsRoot.mockRejectedValue(new Error('Beacon node unavailable'));
+            yield expect(exit.validateExitBlobs(mockClusterConfig, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Beacon node unavailable');
+        }));
+        // Additional test cases to match API service coverage
+        it('should handle public key format differences (with and without 0x prefix)', () => __awaiter(void 0, void 0, void 0, function* () {
+            const blobWithoutPrefix = Object.assign(Object.assign({}, mockExitBlob), { public_key: 'cd'.repeat(48) });
+            const payloadWithoutPrefix = Object.assign(Object.assign({}, mockExitPayload), { partial_exits: [blobWithoutPrefix] });
+            const clusterConfigWithoutPrefix = Object.assign(Object.assign({}, mockClusterConfig), { distributed_validators: [
+                    {
+                        distributed_public_key: '0x' + 'cd'.repeat(48), // With 0x prefix
+                        public_shares: ['0x' + 'aa'.repeat(48)],
+                    },
+                ] });
+            const result = yield exit.validateExitBlobs(clusterConfigWithoutPrefix, payloadWithoutPrefix, MOCK_BEACON_API_URL, null);
+            expect(result).toEqual([blobWithoutPrefix]);
+        }));
+        it('should handle public key case differences', () => __awaiter(void 0, void 0, void 0, function* () {
+            const blobWithUppercase = Object.assign(Object.assign({}, mockExitBlob), { public_key: '0x' + 'CD'.repeat(48) });
+            const payloadWithUppercase = Object.assign(Object.assign({}, mockExitPayload), { partial_exits: [blobWithUppercase] });
+            const clusterConfigWithLowercase = Object.assign(Object.assign({}, mockClusterConfig), { distributed_validators: [
+                    {
+                        distributed_public_key: '0x' + 'cd'.repeat(48), // Lowercase
+                        public_shares: ['0x' + 'aa'.repeat(48)],
+                    },
+                ] });
+            const result = yield exit.validateExitBlobs(clusterConfigWithLowercase, payloadWithUppercase, MOCK_BEACON_API_URL, null);
+            expect(result).toEqual([blobWithUppercase]);
+        }));
+        it('should throw if public share for operator index is not found', () => __awaiter(void 0, void 0, void 0, function* () {
+            const clusterConfigWithMissingShare = Object.assign(Object.assign({}, mockClusterConfig), { distributed_validators: [
+                    {
+                        distributed_public_key: mockExitBlob.public_key,
+                        public_shares: [], // Empty public shares array
+                    },
+                ] });
+            yield expect(exit.validateExitBlobs(clusterConfigWithMissingShare, mockExitPayload, MOCK_BEACON_API_URL, mockExistingBlobData)).rejects.toThrow('Public share for operator index 0 not found for validator 0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd');
+        }));
+    });
+    // Add other tests for different scenarios: epoch mismatch, already exited, etc.
+    // Consider testing the case where getExistingBlobData throws an error
+});

package/dist/esm/test/exit/verificationHelpers.spec.js

@@ -0,0 +1,66 @@
+import { computeDomain, signingRoot, GENESIS_VALIDATOR_ROOT_HEX_STRING, } from '../../src/exits/verificationHelpers';
+import { CAPELLA_FORK_MAPPING } from '../../src/constants'; // Assuming this contains fork versions
+import { fromHexString } from '@chainsafe/ssz';
+// Mock data similar to what's used in obol-api tests or common scenarios
+const DOMAIN_VOLUNTARY_EXIT_HEX = '0x04000000';
+const MAINNET_BASE_FORK_VERSION = '0x00000000';
+const MAINNET_CAPELLA_FORK_VERSION = CAPELLA_FORK_MAPPING[MAINNET_BASE_FORK_VERSION]; // '0x03000000'
+// Sample SSZ Object Root (32 bytes, replace with a realistic one if available from other tests)
+const MOCK_SSZ_OBJECT_ROOT_HEX = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+describe('verificationHelpers', () => {
+    describe('computeDomain', () => {
+        it('should compute a domain with default genesis root', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            const domain = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION);
+            expect(domain).toBeInstanceOf(Uint8Array);
+            expect(domain.length).toBe(32);
+            // Add more specific expectation if a known domain value exists for these inputs
+        });
+        it('should compute a domain with a custom genesis root', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            const customGenesisRoot = fromHexString(MOCK_SSZ_OBJECT_ROOT_HEX.substring(2)); // Using a mock root
+            const domain = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION, customGenesisRoot);
+            expect(domain).toBeInstanceOf(Uint8Array);
+            expect(domain.length).toBe(32);
+            // Add more specific expectation if a known domain value exists
+        });
+        it('should use GENESIS_VALIDATOR_ROOT_HEX_STRING when override is undefined', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            const domain1 = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION);
+            const domain2 = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION, fromHexString(GENESIS_VALIDATOR_ROOT_HEX_STRING.substring(2)));
+            expect(domain1).toEqual(domain2);
+        });
+        it('should throw an error for invalid fork version hex string (e.g. too short)', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            // Example of an invalid (too short) fork version string
+            const invalidForkVersion = '0x0300';
+            expect(() => computeDomain(domainType, invalidForkVersion)).toThrow();
+        });
+        it('should throw an error for invalid domainType (e.g. not 4 bytes)', () => {
+            const invalidDomainType = fromHexString('010203'); // 3 bytes
+            expect(() => computeDomain(invalidDomainType, MAINNET_CAPELLA_FORK_VERSION)).toThrow();
+        });
+    });
+    describe('signingRoot', () => {
+        it('should compute a signing root', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            const domain = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION);
+            const messageBuffer = Buffer.from(MOCK_SSZ_OBJECT_ROOT_HEX.substring(2), 'hex');
+            const root = signingRoot(domain, messageBuffer);
+            expect(root).toBeInstanceOf(Uint8Array);
+            expect(root.length).toBe(32);
+            // Add more specific expectation if a known signing root value exists
+        });
+        it('should throw if domain is not 32 bytes', () => {
+            const invalidDomain = new Uint8Array(31); // Not 32 bytes
+            const messageBuffer = Buffer.from(MOCK_SSZ_OBJECT_ROOT_HEX.substring(2), 'hex');
+            expect(() => signingRoot(invalidDomain, messageBuffer)).toThrow();
+        });
+        it('should throw if messageBuffer is not 32 bytes', () => {
+            const domainType = fromHexString(DOMAIN_VOLUNTARY_EXIT_HEX.substring(2));
+            const domain = computeDomain(domainType, MAINNET_CAPELLA_FORK_VERSION);
+            const invalidMessageBuffer = Buffer.from('0102030405060708', 'hex'); // Not 32 bytes
+            expect(() => signingRoot(domain, invalidMessageBuffer)).toThrow();
+        });
+    });
+});

package/dist/esm/test/{incentives.test.js → incentives/incentives.spec.js}

@@ -9,10 +9,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 var _a, _b;
 import { ethers, JsonRpcProvider } from 'ethers';
-import { Client } from '../src/index';
-import * as utils from '../src/utils';
-import * as incentivesHelpers from '../src/incentiveHelpers';
-import { DEFAULT_BASE_VERSION } from '../src/constants';
+import { Client } from '../../src/index';
+import * as utils from '../../src/utils';
+import * as incentivesHelpers from '../../src/incentives/incentiveHelpers';
+import { DEFAULT_BASE_VERSION } from '../../src/constants';
 import { jest, describe, beforeEach, test, expect } from '@jest/globals';
 const mnemonic = (_b = (_a = ethers.Wallet.createRandom().mnemonic) === null || _a === void 0 ? void 0 : _a.phrase) !== null && _b !== void 0 ? _b : '';
 const privateKey = ethers.Wallet.fromPhrase(mnemonic).privateKey;

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

@@ -111,3 +111,8 @@ export declare const DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT = 1;
 export declare const DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT = 0.1;
 export declare const OBOL_SDK_EMAIL = "sdk@dvlabs.tech";
 export declare const PROVIDER_MAP: Record<number, string>;
+/**
+ * Maps base fork versions to their corresponding Capella fork versions.
+ * Example: Mainnet Capella fork version.
+ */
+export declare const CAPELLA_FORK_MAPPING: Record<string, string>;

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

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function getCapellaFork(fork_version: string): Promise<string | 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 declare function getGenesisValidatorsRoot(beaconNodeApiUrl: string): Promise<string | null>;

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

@@ -0,0 +1,180 @@
+import type { ProviderType, ExitClusterConfig, ExitValidationPayload, ExitValidationBlob, SignedExitValidationMessage, ExistingExitValidationBlobData } 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[]>;
+}

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