@obolnetwork/obol-sdk 2.4.4 → 2.4.6

package/README.md

@@ -19,7 +19,7 @@ If you're integrating this SDK with a **backend** (e.g., in Node.js), and you st
 
 ## ⚡️ Integration with Safe Wallet
 
-When integrating the Obol SDK with a **Safe Wallet**, you will need to provide the `RPC_MAINNET` or `RPC_HOLESKY` or `RPC_GNOSIS` or `RPC_SEPOLIA` environment variable, pointing to the correct network's RPC URL. This is required to interact with Safe kit.
+When integrating the Obol SDK with a **Safe Wallet**, you can either pass an RPC URL OR provide the `RPC_MAINNET` or `RPC_HOLESKY` or `RPC_GNOSIS` or `RPC_SEPOLIA` environment variable, pointing to the correct network's RPC URL. This is required to interact with Safe kit.
 
 
 ## Contributing

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.4",
+    "version": "2.4.6",
     "description": "A package for creating Distributed Validators using the Obol API.",
     "bugs": {
         "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -23,7 +23,8 @@
         "lint": "eslint \"{src,test}/**/*.{js,ts}\" --fix",
         "lint-ci": "eslint \"{src,test}/**/*.{js,ts}\"",
         "prettier-ci": "prettier --check \"{src,test}/**/*.{js,ts}\"",
-        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\""
+        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\"",
+        "docs": "typedoc"
     },
     "main": "./dist/cjs/src/index.js",
     "module": "./dist/esm/src/index.js",
@@ -55,7 +56,7 @@
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-n": "^16.6.2",
         "eslint-plugin-promise": "^6.1.1",
-        "ethers": "6.4.0",
+        "ethers": "^6.13.5",
         "nock": "^13.5.3",
         "pdf-parse": "^1.1.1",
         "semver": "^7.6.0",
@@ -79,8 +80,8 @@
         "release-it": "^17.2.1",
         "ts-jest": "^28.0.8",
         "tsup": "^6.7.0",
-        "typedoc": "^0.25.7",
-        "typedoc-plugin-markdown": "^4.0.0-next.50",
+        "typedoc": "^0.28.0",
+        "typedoc-plugin-markdown": "^4.5.2",
         "typescript": "~5.3.3"
     },
     "engines": {

package/dist/cjs/src/incentiveHelpers.js

@@ -12,7 +12,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isClaimedFromMerkleDistributor = exports.claimIncentivesFromMerkleDistributor = void 0;
 const ethers_1 = require("ethers");
 const MerkleDistributorWithDeadline_1 = require("./abi/MerkleDistributorWithDeadline");
-const utils_1 = require("./utils");
 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);
@@ -26,10 +25,9 @@ const claimIncentivesFromMerkleDistributor = (incentivesData) => __awaiter(void
     }
 });
 exports.claimIncentivesFromMerkleDistributor = claimIncentivesFromMerkleDistributor;
-const isClaimedFromMerkleDistributor = (chainId, contractAddress, index, provider) => __awaiter(void 0, void 0, void 0, function* () {
+const isClaimedFromMerkleDistributor = (contractAddress, index, provider) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const clientProvider = provider !== null && provider !== void 0 ? provider : (0, utils_1.getProvider)(chainId);
-        const contract = new ethers_1.Contract(contractAddress, MerkleDistributorWithDeadline_1.MerkleDistributorABI.abi, clientProvider);
+        const contract = new ethers_1.Contract(contractAddress, MerkleDistributorWithDeadline_1.MerkleDistributorABI.abi, provider);
         const claimed = yield contract.isClaimed(BigInt(index));
         return claimed;
     }

package/dist/cjs/src/incentives.js

@@ -14,6 +14,14 @@ const utils_1 = require("./utils");
 const types_1 = require("./types");
 const incentiveHelpers_1 = require("./incentiveHelpers");
 const constants_1 = require("./constants");
+/**
+ * Incentives can be used for fetching and claiming Obol incentives.
+ * @class
+ * @internal Access it through Client.incentives.
+ * @example
+ * const obolClient = new Client(config);
+ * await obolClient.incentives.claimIncentives(address);
+ */
 class Incentives {
     constructor(signer, chainId, request, provider) {
         this.signer = signer;
@@ -22,16 +30,23 @@ class Incentives {
         this.provider = provider;
     }
     /**
-     * Claims obol incentives from a Merkle Distributor contract using just an address.
-     * The method automatically fetches incentives data and checks if already claimed.
+     * Claims Obol incentives from a Merkle Distributor contract using an address.
+     *
+     * This method automatically fetches incentive data and verifies whether the incentives have already been claimed.
+     * If `txHash` is `null`, it indicates that the incentives were already claimed.
+     *
+     * Note: This method is not yet enabled and will throw an error if called.
      *
      * @remarks
      * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
      * and not pushed to version control.
      *
      * @param {string} address - The address to claim incentives for
-     * @returns {Promise<{ txHash: string } | { alreadyClaimed: true }>} The transaction hash or already claimed status
+     * @returns {Promise<ClaimIncentivesResponse>} The transaction hash or already claimed status
      * @throws Will throw an error if the incentives data is not found or the claim fails
+     *
+     * An example of how to use claimIncentives:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L281)
      */
     claimIncentives(address) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -49,7 +64,7 @@ class Incentives {
                 }
                 const claimed = yield this.isClaimed(incentivesData.contract_address, incentivesData.index);
                 if (claimed) {
-                    return { alreadyClaimed: true };
+                    return { txHash: null };
                 }
                 const { txHash } = yield (0, incentiveHelpers_1.claimIncentivesFromMerkleDistributor)({
                     signer: this.signer,
@@ -74,16 +89,22 @@ class Incentives {
      * @param {ETH_ADDRESS} index - operator index in merkle tree
      * @returns {Promise<boolean>} true if incentives are already claime
      *
+     *
+     * An example of how to use isClaimed:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L266)
      */
     isClaimed(contractAddress, index) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield (0, incentiveHelpers_1.isClaimedFromMerkleDistributor)(this.chainId, contractAddress, index, this.provider);
+            return yield (0, incentiveHelpers_1.isClaimedFromMerkleDistributor)(contractAddress, index, this.provider);
         });
     }
     /**
      * @param address - Operator address
      * @returns {Promise<IncentivesType>} The matched incentives from DB
      * @throws On not found if address not found.
+     *
+     * An example of how to use getIncentivesByAddress:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L250)
      */
     getIncentivesByAddress(address) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/cjs/src/index.js

@@ -23,7 +23,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = void 0;
+exports.Client = exports.Incentives = void 0;
 const ethers_1 = require("ethers");
 const uuid_1 = require("uuid");
 const base_js_1 = require("./base.js");
@@ -39,6 +39,8 @@ __exportStar(require("./types.js"), exports);
 __exportStar(require("./services.js"), exports);
 __exportStar(require("./verification/signature-validator.js"), exports);
 __exportStar(require("./verification/common.js"), exports);
+var incentives_js_2 = require("./incentives.js");
+Object.defineProperty(exports, "Incentives", { enumerable: true, get: function () { return incentives_js_2.Incentives; } });
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */

package/dist/cjs/src/services.js

@@ -14,15 +14,16 @@ const common_js_1 = require("./verification/common.js");
 /**
  * Verifies Cluster Lock's validity.
  * @param lock - cluster lock
+ * @param safeRpcUrl - optional safeRpcUrl for safe wallet verification
  * @returns {Promise<{ result: boolean }> } boolean result to indicate if lock is valid
  * @throws on missing keys or values.
  *
  * An example of how to use validateClusterLock:
  * [validateClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L127)
  */
-const validateClusterLock = (lock) => __awaiter(void 0, void 0, void 0, function* () {
+const validateClusterLock = (lock, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const isLockValid = yield (0, common_js_1.isValidClusterLock)(lock);
+        const isLockValid = yield (0, common_js_1.isValidClusterLock)(lock, safeRpcUrl);
         return isLockValid;
     }
     catch (err) {

package/dist/cjs/src/types.js

@@ -19,20 +19,11 @@ var FORK_MAPPING;
     /** Hoodi Chain. */
     FORK_MAPPING[FORK_MAPPING["0x10000910"] = 560048] = "0x10000910";
 })(FORK_MAPPING || (exports.FORK_MAPPING = FORK_MAPPING = {}));
-/**
- * Permitted Chain Names
- */
 exports.FORK_NAMES = {
-    /** Mainnet. */
     [FORK_MAPPING['0x00000000']]: 'mainnet',
-    /** Goerli/Prater. */
     [FORK_MAPPING['0x00001020']]: 'goerli',
-    /** Gnosis Chain. */
     [FORK_MAPPING['0x00000064']]: 'gnosis',
-    /** Holesky. */
     [FORK_MAPPING['0x01017000']]: 'holesky',
-    /** Sepolia. */
     [FORK_MAPPING['0x90000069']]: 'sepolia',
-    /** Hoodi. */
     [FORK_MAPPING['0x10000910']]: 'hoodi',
 };

package/dist/cjs/src/utils.js

@@ -67,11 +67,11 @@ const isContractAvailable = (contractAddress, provider, bytecode) => __awaiter(v
     return !!code && code !== '0x' && code !== '0x0';
 });
 exports.isContractAvailable = isContractAvailable;
-const getProvider = (chainId) => {
-    const rpcUrl = constants_1.PROVIDER_MAP[chainId];
-    if (!rpcUrl || rpcUrl === 'undefined') {
+const getProvider = (chainId, rpcUrl) => {
+    const resolvedRpcUrl = rpcUrl !== null && rpcUrl !== void 0 ? rpcUrl : constants_1.PROVIDER_MAP[chainId];
+    if (chainId && (!resolvedRpcUrl || resolvedRpcUrl === 'undefined')) {
         throw new Error(`No provider configured for ${types_1.FORK_NAMES[chainId]}`);
     }
-    return new ethers_1.ethers.JsonRpcProvider(rpcUrl);
+    return new ethers_1.ethers.JsonRpcProvider(resolvedRpcUrl);
 };
 exports.getProvider = getProvider;

package/dist/cjs/src/verification/common.js

@@ -131,7 +131,7 @@ const clusterLockHash = (clusterLock) => {
 exports.clusterLockHash = clusterLockHash;
 // Lock verification
 // cluster-definition signatures verification
-const validatePOSTConfigHashSigner = (address, signature, configHash, chainId) => __awaiter(void 0, void 0, void 0, function* () {
+const validatePOSTConfigHashSigner = (address, signature, configHash, chainId, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const data = (0, constants_js_1.signCreatorConfigHashPayload)({ creator_config_hash: configHash }, chainId);
         return yield (0, signature_validator_js_1.validateAddressSignature)({
@@ -139,13 +139,14 @@ const validatePOSTConfigHashSigner = (address, signature, configHash, chainId) =
             token: signature,
             data,
             chainId,
+            safeRpcUrl,
         });
     }
     catch (err) {
         throw err;
     }
 });
-const validatePUTConfigHashSigner = (address, signature, configHash, chainId) => __awaiter(void 0, void 0, void 0, function* () {
+const validatePUTConfigHashSigner = (address, signature, configHash, chainId, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const data = (0, constants_js_1.signOperatorConfigHashPayload)({ operator_config_hash: configHash }, chainId);
         return yield (0, signature_validator_js_1.validateAddressSignature)({
@@ -153,13 +154,14 @@ const validatePUTConfigHashSigner = (address, signature, configHash, chainId) =>
             token: signature,
             data,
             chainId,
+            safeRpcUrl,
         });
     }
     catch (err) {
         throw err;
     }
 });
-const validateEnrSigner = (address, signature, payload, chainId) => __awaiter(void 0, void 0, void 0, function* () {
+const validateEnrSigner = (address, signature, payload, chainId, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const data = (0, constants_js_1.signEnrPayload)({ enr: payload }, chainId);
         return yield (0, signature_validator_js_1.validateAddressSignature)({
@@ -167,18 +169,19 @@ const validateEnrSigner = (address, signature, payload, chainId) => __awaiter(vo
             token: signature,
             data,
             chainId,
+            safeRpcUrl,
         });
     }
     catch (err) {
         throw err;
     }
 });
-const verifyDefinitionSignatures = (clusterDefinition, definitionType) => __awaiter(void 0, void 0, void 0, function* () {
+const verifyDefinitionSignatures = (clusterDefinition, definitionType, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     if (definitionType === constants_js_1.DefinitionFlow.Charon) {
         return true;
     }
     else {
-        const isPOSTConfigHashSignerValid = yield validatePOSTConfigHashSigner(clusterDefinition.creator.address, clusterDefinition.creator.config_signature, clusterDefinition.config_hash, types_js_1.FORK_MAPPING[clusterDefinition.fork_version]);
+        const isPOSTConfigHashSignerValid = yield validatePOSTConfigHashSigner(clusterDefinition.creator.address, clusterDefinition.creator.config_signature, clusterDefinition.config_hash, types_js_1.FORK_MAPPING[clusterDefinition.fork_version], safeRpcUrl);
         if (!isPOSTConfigHashSignerValid) {
             return false;
         }
@@ -186,8 +189,8 @@ const verifyDefinitionSignatures = (clusterDefinition, definitionType) => __awai
             return true;
         }
         for (const operator of clusterDefinition.operators) {
-            const isPUTConfigHashSignerValid = yield validatePUTConfigHashSigner(operator.address, operator.config_signature, clusterDefinition.config_hash, types_js_1.FORK_MAPPING[clusterDefinition.fork_version]);
-            const isENRSignerValid = yield validateEnrSigner(operator.address, operator.enr_signature, operator.enr, types_js_1.FORK_MAPPING[clusterDefinition.fork_version]);
+            const isPUTConfigHashSignerValid = yield validatePUTConfigHashSigner(operator.address, operator.config_signature, clusterDefinition.config_hash, types_js_1.FORK_MAPPING[clusterDefinition.fork_version], safeRpcUrl);
+            const isENRSignerValid = yield validateEnrSigner(operator.address, operator.enr_signature, operator.enr, types_js_1.FORK_MAPPING[clusterDefinition.fork_version], safeRpcUrl);
             if (!isPUTConfigHashSignerValid || !isENRSignerValid) {
                 return false;
             }
@@ -322,13 +325,13 @@ const verifyLockData = (clusterLock) => __awaiter(void 0, void 0, void 0, functi
     }
     return false;
 });
-const isValidClusterLock = (clusterLock) => __awaiter(void 0, void 0, void 0, function* () {
+const isValidClusterLock = (clusterLock, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const definitionType = (0, utils_js_1.definitionFlow)(clusterLock.cluster_definition);
         if (definitionType == null) {
             return false;
         }
-        const isValidDefinitionData = yield verifyDefinitionSignatures(clusterLock.cluster_definition, definitionType);
+        const isValidDefinitionData = yield verifyDefinitionSignatures(clusterLock.cluster_definition, definitionType, safeRpcUrl);
         if (!isValidDefinitionData) {
             return false;
         }

package/dist/cjs/src/verification/signature-validator.js

@@ -20,9 +20,9 @@ const protocol_kit_1 = __importDefault(require("@safe-global/protocol-kit"));
 const constants_1 = require("../constants");
 const utils_1 = require("@safe-global/protocol-kit/dist/src/utils");
 const utils_2 = require("../utils");
-const validateAddressSignature = ({ address, token, data, chainId, }) => __awaiter(void 0, void 0, void 0, function* () {
+const validateAddressSignature = ({ address, token, data, chainId, safeRpcUrl, }) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const provider = (0, utils_2.getProvider)(chainId); // [TODO Hanan], should expect it from signer.provider, or passed in client
+        const provider = (0, utils_2.getProvider)(chainId, safeRpcUrl);
         if (provider) {
             const contractAddress = yield (0, utils_2.isContractAvailable)(address, provider);
             if (contractAddress) {
@@ -31,6 +31,7 @@ const validateAddressSignature = ({ address, token, data, chainId, }) => __await
                     data: data,
                     address,
                     chainId,
+                    safeRpcUrl,
                 });
             }
         }
@@ -54,11 +55,11 @@ const validateEOASignature = ({ token, data, address, }) => {
     }
 };
 exports.validateEOASignature = validateEOASignature;
-const validateSmartContractSignature = ({ token, data, address, chainId, }) => __awaiter(void 0, void 0, void 0, function* () {
+const validateSmartContractSignature = ({ token, data, address, chainId, safeRpcUrl, }) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const provider = constants_1.PROVIDER_MAP[chainId];
+        const safeProvider = safeRpcUrl !== null && safeRpcUrl !== void 0 ? safeRpcUrl : constants_1.PROVIDER_MAP[chainId];
         const protocolKit = yield protocol_kit_1.default.init({
-            provider,
+            provider: safeProvider,
             safeAddress: address,
         });
         const messageHash = (0, utils_1.hashTypedData)(data);

package/dist/cjs/test/incentives.test.js

@@ -104,13 +104,13 @@ global.fetch = globals_1.jest.fn();
             merkleProof: mockIncentivesData.merkle_proof,
         });
     }));
-    (0, globals_1.test)('claimIncentives should return alreadyClaimed when incentives are already claimed', () => __awaiter(void 0, void 0, void 0, function* () {
+    (0, globals_1.test)('claimIncentives should return txHash as null when incentives are already claimed', () => __awaiter(void 0, void 0, void 0, function* () {
         globals_1.jest
             .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
             .mockResolvedValue(mockIncentivesData);
         globals_1.jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(true);
         const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address);
-        (0, globals_1.expect)(result).toEqual({ alreadyClaimed: true });
+        (0, globals_1.expect)(result).toEqual({ txHash: null });
         (0, globals_1.expect)(incentivesHelpers.claimIncentivesFromMerkleDistributor).not.toHaveBeenCalled();
     }));
     (0, globals_1.test)('claimIncentives should throw an error if no incentives found for address', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -145,7 +145,7 @@ global.fetch = globals_1.jest.fn();
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
         const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
         (0, globals_1.expect)(result).toBe(true);
-        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, {});
+        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(mockIncentivesData.contract_address, mockIncentivesData.index, {});
     }));
     (0, globals_1.test)('isClaimed should return false when incentive is not claimed', () => __awaiter(void 0, void 0, void 0, function* () {
         globals_1.jest
@@ -172,7 +172,7 @@ global.fetch = globals_1.jest.fn();
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
         const result = yield clientWithoutSigner.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
         (0, globals_1.expect)(result).toBe(true);
-        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, provider);
+        (0, globals_1.expect)(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(mockIncentivesData.contract_address, mockIncentivesData.index, provider);
     }));
     (0, globals_1.test)('getIncentivesByAddress should make the correct API request', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';

package/dist/cjs/test/methods.test.js

@@ -165,6 +165,9 @@ describe('Cluster Client without a signer', () => {
     beforeAll(() => {
         jest.restoreAllMocks();
     });
+    beforeEach(() => {
+        jest.resetModules();
+    });
     test('createClusterDefinition should throw an error without signer', () => __awaiter(void 0, void 0, void 0, function* () {
         try {
             yield clientInstance.createClusterDefinition(fixtures_js_1.clusterConfigV1X8);
@@ -219,6 +222,14 @@ describe('Cluster Client without a signer', () => {
         const isValidLock = yield (0, index_1.validateClusterLock)(clusterLock);
         expect(isValidLock).toEqual(true);
     }));
+    test('should return true on verified cluster lock with Safe wallet and safe rpc url', () => __awaiter(void 0, void 0, void 0, function* () {
+        process.env.RPC_HOLESKY = undefined;
+        /* eslint-disable @typescript-eslint/no-var-requires */
+        const { validateClusterLock: validateLockWithRpcUrl, } = require('../src/index');
+        const safeRpcUrl = 'https://ethereum-holesky-rpc.publicnode.com';
+        const isValidLock = yield validateLockWithRpcUrl(fixtures_js_1.clusterLockWithSafe, safeRpcUrl);
+        expect(isValidLock).toEqual(true);
+    }));
     test('validateCluster should return false for cluster with null deposit_amounts and incorrect partial_deposits', () => __awaiter(void 0, void 0, void 0, function* () {
         const partialDeposit = fixtures_js_1.nullDepositAmountsClusterLockV1X8.distributed_validators[0]
             .partial_deposit_data[0];

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.4",
+    "version": "2.4.6",
     "description": "A package for creating Distributed Validators using the Obol API.",
     "bugs": {
         "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -23,7 +23,8 @@
         "lint": "eslint \"{src,test}/**/*.{js,ts}\" --fix",
         "lint-ci": "eslint \"{src,test}/**/*.{js,ts}\"",
         "prettier-ci": "prettier --check \"{src,test}/**/*.{js,ts}\"",
-        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\""
+        "prettier": "prettier --write \"{src,test}/**/*.{js,ts}\"",
+        "docs": "typedoc"
     },
     "main": "./dist/cjs/src/index.js",
     "module": "./dist/esm/src/index.js",
@@ -55,7 +56,7 @@
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-n": "^16.6.2",
         "eslint-plugin-promise": "^6.1.1",
-        "ethers": "6.4.0",
+        "ethers": "^6.13.5",
         "nock": "^13.5.3",
         "pdf-parse": "^1.1.1",
         "semver": "^7.6.0",
@@ -79,8 +80,8 @@
         "release-it": "^17.2.1",
         "ts-jest": "^28.0.8",
         "tsup": "^6.7.0",
-        "typedoc": "^0.25.7",
-        "typedoc-plugin-markdown": "^4.0.0-next.50",
+        "typedoc": "^0.28.0",
+        "typedoc-plugin-markdown": "^4.5.2",
         "typescript": "~5.3.3"
     },
     "engines": {

package/dist/esm/src/incentiveHelpers.js

@@ -7,9 +7,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Contract, } from 'ethers';
+import { Contract } from 'ethers';
 import { MerkleDistributorABI } from './abi/MerkleDistributorWithDeadline';
-import { getProvider } from './utils';
 export const claimIncentivesFromMerkleDistributor = (incentivesData) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const contract = new Contract(incentivesData.contractAddress, MerkleDistributorABI.abi, incentivesData.signer);
@@ -22,10 +21,9 @@ export const claimIncentivesFromMerkleDistributor = (incentivesData) => __awaite
         throw new Error(`Failed to claim incentives: ${error.message}`);
     }
 });
-export const isClaimedFromMerkleDistributor = (chainId, contractAddress, index, provider) => __awaiter(void 0, void 0, void 0, function* () {
+export const isClaimedFromMerkleDistributor = (contractAddress, index, provider) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const clientProvider = provider !== null && provider !== void 0 ? provider : getProvider(chainId);
-        const contract = new Contract(contractAddress, MerkleDistributorABI.abi, clientProvider);
+        const contract = new Contract(contractAddress, MerkleDistributorABI.abi, provider);
         const claimed = yield contract.isClaimed(BigInt(index));
         return claimed;
     }

package/dist/esm/src/incentives.js

@@ -11,6 +11,14 @@ import { isContractAvailable } from './utils';
 import { FORK_NAMES, } from './types';
 import { claimIncentivesFromMerkleDistributor, isClaimedFromMerkleDistributor, } from './incentiveHelpers';
 import { DEFAULT_BASE_VERSION } from './constants';
+/**
+ * Incentives can be used for fetching and claiming Obol incentives.
+ * @class
+ * @internal Access it through Client.incentives.
+ * @example
+ * const obolClient = new Client(config);
+ * await obolClient.incentives.claimIncentives(address);
+ */
 export class Incentives {
     constructor(signer, chainId, request, provider) {
         this.signer = signer;
@@ -19,16 +27,23 @@ export class Incentives {
         this.provider = provider;
     }
     /**
-     * Claims obol incentives from a Merkle Distributor contract using just an address.
-     * The method automatically fetches incentives data and checks if already claimed.
+     * Claims Obol incentives from a Merkle Distributor contract using an address.
+     *
+     * This method automatically fetches incentive data and verifies whether the incentives have already been claimed.
+     * If `txHash` is `null`, it indicates that the incentives were already claimed.
+     *
+     * Note: This method is not yet enabled and will throw an error if called.
      *
      * @remarks
      * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
      * and not pushed to version control.
      *
      * @param {string} address - The address to claim incentives for
-     * @returns {Promise<{ txHash: string } | { alreadyClaimed: true }>} The transaction hash or already claimed status
+     * @returns {Promise<ClaimIncentivesResponse>} The transaction hash or already claimed status
      * @throws Will throw an error if the incentives data is not found or the claim fails
+     *
+     * An example of how to use claimIncentives:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L281)
      */
     claimIncentives(address) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -46,7 +61,7 @@ export class Incentives {
                 }
                 const claimed = yield this.isClaimed(incentivesData.contract_address, incentivesData.index);
                 if (claimed) {
-                    return { alreadyClaimed: true };
+                    return { txHash: null };
                 }
                 const { txHash } = yield claimIncentivesFromMerkleDistributor({
                     signer: this.signer,
@@ -71,16 +86,22 @@ export class Incentives {
      * @param {ETH_ADDRESS} index - operator index in merkle tree
      * @returns {Promise<boolean>} true if incentives are already claime
      *
+     *
+     * An example of how to use isClaimed:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L266)
      */
     isClaimed(contractAddress, index) {
         return __awaiter(this, void 0, void 0, function* () {
-            return yield isClaimedFromMerkleDistributor(this.chainId, contractAddress, index, this.provider);
+            return yield isClaimedFromMerkleDistributor(contractAddress, index, this.provider);
         });
     }
     /**
      * @param address - Operator address
      * @returns {Promise<IncentivesType>} The matched incentives from DB
      * @throws On not found if address not found.
+     *
+     * An example of how to use getIncentivesByAddress:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L250)
      */
     getIncentivesByAddress(address) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/esm/src/index.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { ZeroAddress, } from 'ethers';
+import { ZeroAddress } from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import { CONFLICT_ERROR_MSG, CreatorConfigHashSigningTypes, Domain, DKG_ALGORITHM, CONFIG_VERSION, OperatorConfigHashSigningTypes, EnrSigningTypes, TERMS_AND_CONDITIONS_VERSION, TermsAndConditionsSigningTypes, DEFAULT_BASE_VERSION, TERMS_AND_CONDITIONS_HASH, AVAILABLE_SPLITTER_CHAINS, CHAIN_CONFIGURATION, DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT, DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT, OBOL_SDK_EMAIL, } from './constants.js';
@@ -22,6 +22,7 @@ export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
 export * from './verification/common.js';
+export { Incentives } from './incentives.js';
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */

package/dist/esm/src/services.js

@@ -11,15 +11,16 @@ import { isValidClusterLock } from './verification/common.js';
 /**
  * Verifies Cluster Lock's validity.
  * @param lock - cluster lock
+ * @param safeRpcUrl - optional safeRpcUrl for safe wallet verification
  * @returns {Promise<{ result: boolean }> } boolean result to indicate if lock is valid
  * @throws on missing keys or values.
  *
  * An example of how to use validateClusterLock:
  * [validateClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L127)
  */
-export const validateClusterLock = (lock) => __awaiter(void 0, void 0, void 0, function* () {
+export const validateClusterLock = (lock, safeRpcUrl) => __awaiter(void 0, void 0, void 0, function* () {
     try {
-        const isLockValid = yield isValidClusterLock(lock);
+        const isLockValid = yield isValidClusterLock(lock, safeRpcUrl);
         return isLockValid;
     }
     catch (err) {

package/dist/esm/src/splitHelpers.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { Contract, Interface, parseEther, ZeroAddress, } from 'ethers';
+import { Contract, Interface, parseEther, ZeroAddress } from 'ethers';
 import { OWRContract, OWRFactoryContract } from './abi/OWR';
 import { splitMainEthereumAbi } from './abi/SplitMain';
 import { MultiCallContract } from './abi/Multicall';

package/dist/esm/src/types.js

@@ -16,20 +16,11 @@ export var FORK_MAPPING;
     /** Hoodi Chain. */
     FORK_MAPPING[FORK_MAPPING["0x10000910"] = 560048] = "0x10000910";
 })(FORK_MAPPING || (FORK_MAPPING = {}));
-/**
- * Permitted Chain Names
- */
 export const FORK_NAMES = {
-    /** Mainnet. */
     [FORK_MAPPING['0x00000000']]: 'mainnet',
-    /** Goerli/Prater. */
     [FORK_MAPPING['0x00001020']]: 'goerli',
-    /** Gnosis Chain. */
     [FORK_MAPPING['0x00000064']]: 'gnosis',
-    /** Holesky. */
     [FORK_MAPPING['0x01017000']]: 'holesky',
-    /** Sepolia. */
     [FORK_MAPPING['0x90000069']]: 'sepolia',
-    /** Hoodi. */
     [FORK_MAPPING['0x10000910']]: 'hoodi',
 };

package/dist/esm/src/utils.js

@@ -59,10 +59,10 @@ export const isContractAvailable = (contractAddress, provider, bytecode) => __aw
     }
     return !!code && code !== '0x' && code !== '0x0';
 });
-export const getProvider = (chainId) => {
-    const rpcUrl = PROVIDER_MAP[chainId];
-    if (!rpcUrl || rpcUrl === 'undefined') {
+export const getProvider = (chainId, rpcUrl) => {
+    const resolvedRpcUrl = rpcUrl !== null && rpcUrl !== void 0 ? rpcUrl : PROVIDER_MAP[chainId];
+    if (chainId && (!resolvedRpcUrl || resolvedRpcUrl === 'undefined')) {
         throw new Error(`No provider configured for ${FORK_NAMES[chainId]}`);
     }
-    return new ethers.JsonRpcProvider(rpcUrl);
+    return new ethers.JsonRpcProvider(resolvedRpcUrl);
 };