@obolnetwork/obol-sdk 2.4.4 → 2.4.5

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.4",
+    "version": "2.4.5",
     "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",
@@ -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/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,6 +89,9 @@ 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* () {
@@ -84,6 +102,9 @@ class Incentives {
      * @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/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/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* () {

package/dist/esm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@obolnetwork/obol-sdk",
-    "version": "2.4.4",
+    "version": "2.4.5",
     "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",
@@ -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,7 +7,7 @@ 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* () {

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,6 +86,9 @@ 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* () {
@@ -81,6 +99,9 @@ export class Incentives {
      * @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/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/test/incentives.test.js

@@ -79,13 +79,13 @@ describe('Client.incentives', () => {
             merkleProof: mockIncentivesData.merkle_proof,
         });
     }));
-    test('claimIncentives should return alreadyClaimed when incentives are already claimed', () => __awaiter(void 0, void 0, void 0, function* () {
+    test('claimIncentives should return txHash as null when incentives are already claimed', () => __awaiter(void 0, void 0, void 0, function* () {
         jest
             .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
             .mockResolvedValue(mockIncentivesData);
         jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(true);
         const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address);
-        expect(result).toEqual({ alreadyClaimed: true });
+        expect(result).toEqual({ txHash: null });
         expect(incentivesHelpers.claimIncentivesFromMerkleDistributor).not.toHaveBeenCalled();
     }));
     test('claimIncentives should throw an error if no incentives found for address', () => __awaiter(void 0, void 0, void 0, function* () {

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

@@ -1,7 +1,6 @@
-import { type ETH_ADDRESS } from './types';
-import { type JsonRpcApiProvider, type JsonRpcProvider, type Provider, type Signer } from 'ethers';
+import { type ProviderType, type SignerType, type ETH_ADDRESS } from './types';
 export declare const claimIncentivesFromMerkleDistributor: (incentivesData: {
-    signer: Signer;
+    signer: SignerType;
     contractAddress: ETH_ADDRESS;
     index: number;
     operatorAddress: ETH_ADDRESS;
@@ -10,4 +9,4 @@ export declare const claimIncentivesFromMerkleDistributor: (incentivesData: {
 }) => Promise<{
     txHash: string;
 }>;
-export declare const isClaimedFromMerkleDistributor: (chainId: number, contractAddress: ETH_ADDRESS, index: number, provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null) => Promise<boolean>;
+export declare const isClaimedFromMerkleDistributor: (chainId: number, contractAddress: ETH_ADDRESS, index: number, provider: ProviderType | undefined | null) => Promise<boolean>;

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

@@ -1,28 +1,38 @@
-import type { JsonRpcApiProvider, JsonRpcProvider, JsonRpcSigner, Provider, Signer } from 'ethers';
-import { type Incentives as IncentivesType, type ETH_ADDRESS } from './types';
+import { type Incentives as IncentivesType, type ETH_ADDRESS, type ProviderType, type SignerType, type ClaimIncentivesResponse } from './types';
+/**
+ * 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 declare class Incentives {
     private readonly signer;
     readonly chainId: number;
     private readonly request;
-    readonly provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null;
-    constructor(signer: Signer | JsonRpcSigner | undefined, chainId: number, request: (endpoint: string, options?: RequestInit) => Promise<any>, provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null);
+    readonly provider: ProviderType | undefined | null;
+    constructor(signer: SignerType | undefined, chainId: number, request: (endpoint: string, options?: RequestInit) => Promise<any>, provider: ProviderType | undefined | null);
     /**
-     * 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: string): Promise<{
-        txHash: string;
-    } | {
-        alreadyClaimed: true;
-    }>;
+    claimIncentives(address: string): Promise<ClaimIncentivesResponse>;
     /**
      * Read isClaimed.
      *
@@ -30,12 +40,18 @@ export declare 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: ETH_ADDRESS, index: number): Promise<boolean>;
     /**
      * @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: string): Promise<IncentivesType>;
 }

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

@@ -1,18 +1,29 @@
-import { type Provider, type Signer, type JsonRpcSigner, type JsonRpcProvider, type JsonRpcApiProvider } from 'ethers';
 import { Base } from './base.js';
-import { type RewardsSplitPayload, type ClusterDefinition, type ClusterLock, type ClusterPayload, type OperatorPayload, type TotalSplitPayload, type ClusterValidator, type ETH_ADDRESS, type OWRTranches } from './types.js';
+import { type RewardsSplitPayload, type ClusterDefinition, type ClusterLock, type ClusterPayload, type OperatorPayload, type TotalSplitPayload, type ClusterValidator, type ETH_ADDRESS, type OWRTranches, type ProviderType, type SignerType } from './types.js';
 import { Incentives } from './incentives.js';
 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.
  */
 export declare class Client extends Base {
+    /**
+     * The signer used for signing transactions.
+     */
     private readonly signer;
+    /**
+     * The incentives module, responsible for managing Obol tokens distribution.
+     * @type {Incentives}
+     */
     incentives: Incentives;
-    provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null;
+    /**
+     * The blockchain provider, used to interact with the network.
+     * It can be null, undefined, or a valid provider instance and defaults to the Signer provider if Signer is passed.
+     */
+    provider: ProviderType | undefined | null;
     /**
      * @param config - Client configurations
      * @param config.baseUrl - obol-api url
@@ -26,7 +37,7 @@ export declare class Client extends Base {
     constructor(config: {
         baseUrl?: string;
         chainId?: number;
-    }, signer?: Signer | JsonRpcSigner, provider?: Provider | JsonRpcProvider);
+    }, signer?: SignerType, provider?: ProviderType);
     /**
      * Accepts Obol terms and conditions to be able to create or update data.
      * @returns {Promise<string>} terms and conditions acceptance success message.

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

@@ -1,5 +1,4 @@
-import { type OWRTranches, type ClusterValidator, type ETH_ADDRESS, type SplitRecipient } from './types';
-import { type Signer } from 'ethers';
+import { type OWRTranches, type ClusterValidator, type ETH_ADDRESS, type SplitRecipient, type SignerType } from './types';
 type Call = {
     target: ETH_ADDRESS;
     callData: string;
@@ -21,7 +20,7 @@ export declare const formatSplitRecipients: (recipients: SplitRecipient[]) => {
     percentAllocations: number[];
 };
 export declare const predictSplitterAddress: ({ signer, accounts, percentAllocations, chainId, distributorFee, controllerAddress, }: {
-    signer: Signer;
+    signer: SignerType;
     accounts: ETH_ADDRESS[];
     percentAllocations: number[];
     chainId: number;
@@ -29,7 +28,7 @@ export declare const predictSplitterAddress: ({ signer, accounts, percentAllocat
     controllerAddress: ETH_ADDRESS;
 }) => Promise<ETH_ADDRESS>;
 export declare const handleDeployOWRAndSplitter: ({ signer, isSplitterDeployed, predictedSplitterAddress, accounts, percentAllocations, etherAmount, principalRecipient, chainId, distributorFee, controllerAddress, recoveryAddress, }: {
-    signer: Signer;
+    signer: SignerType;
     isSplitterDeployed: boolean;
     predictedSplitterAddress: ETH_ADDRESS;
     accounts: ETH_ADDRESS[];
@@ -42,7 +41,7 @@ export declare const handleDeployOWRAndSplitter: ({ signer, isSplitterDeployed,
     recoveryAddress: ETH_ADDRESS;
 }) => Promise<ClusterValidator>;
 export declare const deploySplitterContract: ({ signer, accounts, percentAllocations, chainId, distributorFee, controllerAddress, }: {
-    signer: Signer;
+    signer: SignerType;
     accounts: ETH_ADDRESS[];
     percentAllocations: number[];
     chainId: number;
@@ -52,7 +51,7 @@ export declare const deploySplitterContract: ({ signer, accounts, percentAllocat
 export declare const deploySplitterAndOWRContracts: ({ owrArgs, splitterArgs, signer, chainId, }: {
     owrArgs: OWRArgs;
     splitterArgs: SplitArgs;
-    signer: Signer;
+    signer: SignerType;
     chainId: number;
 }) => Promise<{
     owrAddress: ETH_ADDRESS;
@@ -60,7 +59,7 @@ export declare const deploySplitterAndOWRContracts: ({ owrArgs, splitterArgs, si
 }>;
 export declare const getOWRTranches: ({ owrAddress, signer, }: {
     owrAddress: ETH_ADDRESS;
-    signer: Signer;
+    signer: SignerType;
 }) => Promise<OWRTranches>;
-export declare const multicall: (calls: Call[], signer: Signer, multicallAddress: string) => Promise<any>;
+export declare const multicall: (calls: Call[], signer: SignerType, multicallAddress: string) => Promise<any>;
 export {};

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

@@ -1,3 +1,4 @@
+import { type ethers, type JsonRpcApiProvider, type JsonRpcProvider, type JsonRpcSigner, type Provider, type Signer } from 'ethers';
 /**
  * Permitted ChainID's
  */
@@ -15,9 +16,6 @@ export declare enum FORK_MAPPING {
     /** Hoodi Chain. */
     '0x10000910' = 560048
 }
-/**
- * Permitted Chain Names
- */
 export declare const FORK_NAMES: Record<number, string>;
 /**
  * Node operator data
@@ -232,3 +230,17 @@ export type Incentives = {
  * String expected to be Ethereum Address
  */
 export type ETH_ADDRESS = string;
+/**
+ * Provider Types
+ */
+export type ProviderType = Provider | JsonRpcProvider | JsonRpcApiProvider | ethers.BrowserProvider;
+/**
+ * Signer Types
+ */
+export type SignerType = Signer | JsonRpcSigner;
+/**
+ * claimIncentives Response
+ */
+export type ClaimIncentivesResponse = {
+    txHash: string | null;
+};

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

@@ -1,9 +1,9 @@
-import { ethers, type Provider } from 'ethers';
+import { ethers } from 'ethers';
 import { DefinitionFlow } from './constants';
-import { type ClusterDefinition } from './types';
+import { type ProviderType, type ClusterDefinition } from './types';
 export declare const hexWithout0x: (hex: string) => string;
 export declare const strToUint8Array: (str: string) => Uint8Array;
 export declare const definitionFlow: (clusterDefinition: ClusterDefinition) => DefinitionFlow | null;
-export declare const findDeployedBytecode: (contractAddress: string, provider: Provider) => Promise<string>;
-export declare const isContractAvailable: (contractAddress: string, provider: Provider, bytecode?: string) => Promise<boolean>;
-export declare const getProvider: (chainId: number) => ethers.Provider;
+export declare const findDeployedBytecode: (contractAddress: string, provider: ProviderType) => Promise<string>;
+export declare const isContractAvailable: (contractAddress: string, provider: ProviderType, bytecode?: string) => Promise<boolean>;
+export declare const getProvider: (chainId: number) => ethers.JsonRpcProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "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",
@@ -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/src/incentiveHelpers.ts

@@ -1,16 +1,10 @@
-import { type ETH_ADDRESS } from './types';
-import {
-  Contract,
-  type JsonRpcApiProvider,
-  type JsonRpcProvider,
-  type Provider,
-  type Signer,
-} from 'ethers';
+import { type ProviderType, type SignerType, type ETH_ADDRESS } from './types';
+import { Contract } from 'ethers';
 import { MerkleDistributorABI } from './abi/MerkleDistributorWithDeadline';
 import { getProvider } from './utils';
 
 export const claimIncentivesFromMerkleDistributor = async (incentivesData: {
-  signer: Signer;
+  signer: SignerType;
   contractAddress: ETH_ADDRESS;
   index: number;
   operatorAddress: ETH_ADDRESS;
@@ -44,7 +38,7 @@ export const isClaimedFromMerkleDistributor = async (
   chainId: number,
   contractAddress: ETH_ADDRESS,
   index: number,
-  provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null,
+  provider: ProviderType | undefined | null,
 ): Promise<boolean> => {
   try {
     const clientProvider = provider ?? getProvider(chainId);

package/src/incentives.ts

@@ -1,15 +1,11 @@
-import type {
-  JsonRpcApiProvider,
-  JsonRpcProvider,
-  JsonRpcSigner,
-  Provider,
-  Signer,
-} from 'ethers';
 import { isContractAvailable } from './utils';
 import {
   type Incentives as IncentivesType,
   type ETH_ADDRESS,
   FORK_NAMES,
+  type ProviderType,
+  type SignerType,
+  type ClaimIncentivesResponse,
 } from './types';
 import {
   claimIncentivesFromMerkleDistributor,
@@ -17,31 +13,29 @@ import {
 } 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 {
-  private readonly signer: Signer | JsonRpcSigner | undefined;
+  private readonly signer: SignerType | undefined;
   public readonly chainId: number;
   private readonly request: (
     endpoint: string,
     options?: RequestInit,
   ) => Promise<any>;
 
-  public readonly provider:
-    | Provider
-    | JsonRpcProvider
-    | JsonRpcApiProvider
-    | undefined
-    | null;
+  public readonly provider: ProviderType | undefined | null;
 
   constructor(
-    signer: Signer | JsonRpcSigner | undefined,
+    signer: SignerType | undefined,
     chainId: number,
     request: (endpoint: string, options?: RequestInit) => Promise<any>,
-    provider:
-      | Provider
-      | JsonRpcProvider
-      | JsonRpcApiProvider
-      | undefined
-      | null,
+    provider: ProviderType | undefined | null,
   ) {
     this.signer = signer;
     this.chainId = chainId;
@@ -50,20 +44,25 @@ export class Incentives {
   }
 
   /**
-   * 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)
    */
-  async claimIncentives(
-    address: string,
-  ): Promise<{ txHash: string } | { alreadyClaimed: true }> {
+  async claimIncentives(address: string): Promise<ClaimIncentivesResponse> {
     if (!this.signer) {
       throw new Error('Signer is required in claimIncentives');
     }
@@ -77,7 +76,7 @@ export class Incentives {
 
       const isContractDeployed = await isContractAvailable(
         incentivesData.contract_address,
-        this.provider as Provider,
+        this.provider as ProviderType,
       );
 
       if (!isContractDeployed) {
@@ -92,7 +91,7 @@ export class Incentives {
       );
 
       if (claimed) {
-        return { alreadyClaimed: true };
+        return { txHash: null };
       }
 
       const { txHash } = await claimIncentivesFromMerkleDistributor({
@@ -118,6 +117,9 @@ 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)
    */
   async isClaimed(
     contractAddress: ETH_ADDRESS,
@@ -135,6 +137,9 @@ export class Incentives {
    * @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)
    */
   async getIncentivesByAddress(address: string): Promise<IncentivesType> {
     const network = FORK_NAMES[this.chainId];

package/src/index.ts

@@ -1,11 +1,4 @@
-import {
-  ZeroAddress,
-  type Provider,
-  type Signer,
-  type JsonRpcSigner,
-  type JsonRpcProvider,
-  type JsonRpcApiProvider,
-} from 'ethers';
+import { ZeroAddress } from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import {
@@ -37,6 +30,8 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type OWRTranches,
+  type ProviderType,
+  type SignerType,
 } from './types.js';
 import { clusterConfigOrDefinitionHash } from './verification/common.js';
 import { validatePayload } from './ajv.js';
@@ -59,19 +54,28 @@ 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.
  */
 export class Client extends Base {
-  private readonly signer: Signer | JsonRpcSigner | undefined;
+  /**
+   * The signer used for signing transactions.
+   */
+  private readonly signer: SignerType | undefined;
+
+  /**
+   * The incentives module, responsible for managing Obol tokens distribution.
+   * @type {Incentives}
+   */
   public incentives: Incentives;
-  public provider:
-    | Provider
-    | JsonRpcProvider
-    | JsonRpcApiProvider
-    | undefined
-    | null;
+
+  /**
+   * The blockchain provider, used to interact with the network.
+   * It can be null, undefined, or a valid provider instance and defaults to the Signer provider if Signer is passed.
+   */
+  public provider: ProviderType | undefined | null;
 
   /**
    * @param config - Client configurations
@@ -85,8 +89,8 @@ export class Client extends Base {
    */
   constructor(
     config: { baseUrl?: string; chainId?: number },
-    signer?: Signer | JsonRpcSigner,
-    provider?: Provider | JsonRpcProvider,
+    signer?: SignerType,
+    provider?: ProviderType,
   ) {
     super(config);
     this.signer = signer;
@@ -201,19 +205,19 @@ export class Client extends Base {
 
     const checkSplitMainAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.bytecode,
     );
 
     const checkMulticallAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].MULTICALL_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].MULTICALL_ADDRESS.bytecode,
     );
 
     const checkOWRFactoryAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].OWR_FACTORY_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].OWR_FACTORY_ADDRESS.bytecode,
     );
 
@@ -251,7 +255,7 @@ export class Client extends Base {
 
     const isSplitterDeployed = await isContractAvailable(
       predictedSplitterAddress,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
     );
 
     const { withdrawal_address, fee_recipient_address } =
@@ -316,7 +320,7 @@ export class Client extends Base {
 
     const checkSplitMainAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.bytecode,
     );
 
@@ -349,7 +353,7 @@ export class Client extends Base {
 
     const isSplitterDeployed = await isContractAvailable(
       predictedSplitterAddress,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
     );
 
     if (!isSplitterDeployed) {

package/src/splitHelpers.ts

@@ -3,14 +3,9 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type SplitRecipient,
+  type SignerType,
 } from './types';
-import {
-  Contract,
-  Interface,
-  parseEther,
-  ZeroAddress,
-  type Signer,
-} 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';
@@ -59,7 +54,7 @@ export const predictSplitterAddress = async ({
   distributorFee,
   controllerAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   accounts: ETH_ADDRESS[];
   percentAllocations: number[];
   chainId: number;
@@ -111,7 +106,7 @@ export const handleDeployOWRAndSplitter = async ({
   controllerAddress,
   recoveryAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   isSplitterDeployed: boolean;
   predictedSplitterAddress: ETH_ADDRESS;
   accounts: ETH_ADDRESS[];
@@ -174,7 +169,7 @@ const createOWRContract = async ({
   chainId,
 }: {
   owrArgs: OWRArgs;
-  signer: Signer;
+  signer: SignerType;
   chainId: number;
 }): Promise<ETH_ADDRESS> => {
   try {
@@ -209,7 +204,7 @@ export const deploySplitterContract = async ({
   distributorFee,
   controllerAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   accounts: ETH_ADDRESS[];
   percentAllocations: number[];
   chainId: number;
@@ -247,7 +242,7 @@ export const deploySplitterAndOWRContracts = async ({
 }: {
   owrArgs: OWRArgs;
   splitterArgs: SplitArgs;
-  signer: Signer;
+  signer: SignerType;
   chainId: number;
 }): Promise<{ owrAddress: ETH_ADDRESS; splitterAddress: ETH_ADDRESS }> => {
   const executeCalls: Call[] = [];
@@ -304,7 +299,7 @@ export const getOWRTranches = async ({
   signer,
 }: {
   owrAddress: ETH_ADDRESS;
-  signer: Signer;
+  signer: SignerType;
 }): Promise<OWRTranches> => {
   const owrContract = new Contract(owrAddress, OWRContract.abi, signer);
   const res = await owrContract.getTranches();
@@ -318,7 +313,7 @@ export const getOWRTranches = async ({
 
 export const multicall = async (
   calls: Call[],
-  signer: Signer,
+  signer: SignerType,
   multicallAddress: string,
 ): Promise<any> => {
   const multiCallContractInstance = new Contract(

package/src/types.ts

@@ -1,3 +1,12 @@
+import {
+  type ethers,
+  type JsonRpcApiProvider,
+  type JsonRpcProvider,
+  type JsonRpcSigner,
+  type Provider,
+  type Signer,
+} from 'ethers';
+
 /**
  * Permitted ChainID's
  */
@@ -21,28 +30,14 @@ export enum FORK_MAPPING {
   '0x10000910' = 560048,
 }
 
-/**
- * Permitted Chain Names
- */
 export const FORK_NAMES: Record<number, string> = {
-  /** 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',
-};
+} as const;
 
 /**
  * Node operator data
@@ -323,3 +318,22 @@ export type Incentives = {
  * String expected to be Ethereum Address
  */
 export type ETH_ADDRESS = string;
+
+/**
+ * Provider Types
+ */
+export type ProviderType =
+  | Provider
+  | JsonRpcProvider
+  | JsonRpcApiProvider
+  | ethers.BrowserProvider;
+
+/**
+ * Signer Types
+ */
+export type SignerType = Signer | JsonRpcSigner;
+
+/**
+ * claimIncentives Response
+ */
+export type ClaimIncentivesResponse = { txHash: string | null };

package/src/utils.ts

@@ -1,6 +1,6 @@
-import { ethers, type Provider } from 'ethers';
+import { ethers } from 'ethers';
 import { DefinitionFlow, PROVIDER_MAP } from './constants';
-import { FORK_NAMES, type ClusterDefinition } from './types';
+import { FORK_NAMES, type ProviderType, type ClusterDefinition } from './types';
 
 export const hexWithout0x = (hex: string): string => {
   return hex.slice(2, hex.length);
@@ -58,14 +58,14 @@ export const definitionFlow = (
 
 export const findDeployedBytecode = async (
   contractAddress: string,
-  provider: Provider,
+  provider: ProviderType,
 ): Promise<string> => {
   return await provider?.getCode(contractAddress);
 };
 
 export const isContractAvailable = async (
   contractAddress: string,
-  provider: Provider,
+  provider: ProviderType,
   bytecode?: string,
 ): Promise<boolean> => {
   const code = await findDeployedBytecode(contractAddress, provider);
@@ -76,7 +76,7 @@ export const isContractAvailable = async (
   return !!code && code !== '0x' && code !== '0x0';
 };
 
-export const getProvider = (chainId: number): ethers.Provider => {
+export const getProvider = (chainId: number): ethers.JsonRpcProvider => {
   const rpcUrl = PROVIDER_MAP[chainId];
   if (!rpcUrl || rpcUrl === 'undefined') {
     throw new Error(`No provider configured for ${FORK_NAMES[chainId]}`);