@obolnetwork/obol-sdk 2.4.3 → 2.4.5

package/dist/esm/test/incentives.test.js

@@ -11,23 +11,25 @@ var _a, _b;
 import { ethers, JsonRpcProvider } from 'ethers';
 import { Client } from '../src/index';
 import * as utils from '../src/utils';
-import * as incentivesHelpers from '../src/incentivesHalpers';
+import * as incentivesHelpers from '../src/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;
 const provider = new JsonRpcProvider('https://ethereum-holesky.publicnode.com');
 const wallet = new ethers.Wallet(privateKey, provider);
 const mockSigner = wallet.connect(provider);
 const baseUrl = 'https://obol-api-dev.gcp.obol.tech';
+// Fix the type error by properly typing the mock function
 global.fetch = jest.fn();
 describe('Client.incentives', () => {
     let clientInstance;
     const mockIncentivesData = {
-        contractAddress: '0x1234567890abcdef1234567890abcdef12345678',
+        contract_address: '0x1234567890abcdef1234567890abcdef12345678',
         index: 5,
-        operatorAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
-        amount: 1000000000000000000,
-        merkleProof: [
+        operator_address: '0xabcdef1234567890abcdef1234567890abcdef12',
+        amount: '1000000000000000000',
+        merkle_proof: [
             '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
             '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
         ],
@@ -42,34 +44,61 @@ describe('Client.incentives', () => {
             baseUrl,
             chainId: 17000,
         });
-        yield expect(clientWithoutSigner.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow('Signer is required in claimIncentives');
+        yield expect(clientWithoutSigner.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Signer is required in claimIncentives');
     }));
     test('claimIncentives should throw an error if contract is not available', () => __awaiter(void 0, void 0, void 0, function* () {
+        jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
         jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(false); }));
-        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow(`Merkle Distributor contract is not available at address ${mockIncentivesData.contractAddress}`);
+        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow(`Merkle Distributor contract is not available at address ${mockIncentivesData.contract_address}`);
     }));
     test('claimIncentives should return txHash on successful claim', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockTxHash = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+        jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
         jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
         jest
             .spyOn(incentivesHelpers, 'claimIncentivesFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve({ txHash: mockTxHash }); }));
-        const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData);
+        const result = yield clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address);
         expect(result).toEqual({ txHash: mockTxHash });
         expect(incentivesHelpers.claimIncentivesFromMerkleDistributor).toHaveBeenCalledWith({
             signer: mockSigner,
-            contractAddress: mockIncentivesData.contractAddress,
+            contractAddress: mockIncentivesData.contract_address,
             index: mockIncentivesData.index,
-            operatorAddress: mockIncentivesData.operatorAddress,
+            operatorAddress: mockIncentivesData.operator_address,
             amount: mockIncentivesData.amount,
-            merkleProof: mockIncentivesData.merkleProof,
+            merkleProof: mockIncentivesData.merkle_proof,
         });
     }));
+    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({ 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* () {
+        jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockRejectedValue(new Error('No incentives found for address'));
+        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Failed to claim incentives: No incentives found for address');
+    }));
     test('claimIncentives should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        jest
+            .spyOn(clientInstance.incentives, 'getIncentivesByAddress')
+            .mockResolvedValue(mockIncentivesData);
+        jest.spyOn(clientInstance.incentives, 'isClaimed').mockResolvedValue(false);
         jest
             .spyOn(utils, 'isContractAvailable')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
@@ -78,7 +107,7 @@ describe('Client.incentives', () => {
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () {
             throw new Error('Helper function error');
         }));
-        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow('Failed to claim incentives: Helper function error');
+        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData.operator_address)).rejects.toThrow('Failed to claim incentives: Helper function error');
     }));
     test('incentives should be initialized with the same chainId as client', () => {
         const customChainId = 5;
@@ -89,15 +118,15 @@ describe('Client.incentives', () => {
         jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
+        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
         expect(result).toBe(true);
-        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contractAddress, mockIncentivesData.index, undefined);
+        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, {});
     }));
     test('isClaimed should return false when incentive is not claimed', () => __awaiter(void 0, void 0, void 0, function* () {
         jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(false); }));
-        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
+        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
         expect(result).toBe(false);
     }));
     test('isClaimed should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -106,10 +135,9 @@ describe('Client.incentives', () => {
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () {
             throw new Error('Helper function error');
         }));
-        yield expect(clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index)).rejects.toThrow('Helper function error');
+        yield expect(clientInstance.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index)).rejects.toThrow('Helper function error');
     }));
     test('isClaimed should work with a provider and a without signer', () => __awaiter(void 0, void 0, void 0, function* () {
-        // Create a client without a signer
         const clientWithoutSigner = new Client({
             baseUrl,
             chainId: 17000,
@@ -117,9 +145,9 @@ describe('Client.incentives', () => {
         jest
             .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
             .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        const result = yield clientWithoutSigner.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
+        const result = yield clientWithoutSigner.incentives.isClaimed(mockIncentivesData.contract_address, mockIncentivesData.index);
         expect(result).toBe(true);
-        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contractAddress, mockIncentivesData.index, provider);
+        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contract_address, mockIncentivesData.index, provider);
     }));
     test('getIncentivesByAddress should make the correct API request', () => __awaiter(void 0, void 0, void 0, function* () {
         const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';

package/dist/types/src/{incentivesHalpers.d.ts → incentiveHelpers.d.ts}

@@ -1,13 +1,12 @@
-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;
-    amount: number;
+    amount: string;
     merkleProof: string[];
 }) => 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,37 +1,38 @@
-import { type JsonRpcApiProvider, type JsonRpcProvider, type JsonRpcSigner, type Provider, type 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.
+     * 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 {Object} incentivesData - The incentives data needed for claiming.
-     * @param {string} incentivesData.contractAddress - The address of the Merkle Distributor contract.
-     * @param {number} incentivesData.index - The index in the Merkle tree.
-     * @param {string} incentivesData.operatorAddress - The address of the operator.
-     * @param {number} incentivesData.amount - The amount to claim.
-     * @param {string[]} incentivesData.merkleProof - The Merkle proof.
-     * @returns {Promise<{ txHash: string }>} The transaction hash of the claim transaction.
-     * @throws Will throw an error if the contract is not available or the claim fails.
+     * @param {string} address - The address to claim incentives for
+     * @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(incentivesData: {
-        contractAddress: ETH_ADDRESS;
-        index: number;
-        operatorAddress: ETH_ADDRESS;
-        amount: number;
-        merkleProof: string[];
-    }): Promise<{
-        txHash: string;
-    }>;
+    claimIncentives(address: string): Promise<ClaimIncentivesResponse>;
     /**
      * Read isClaimed.
      *
@@ -39,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.3",
+  "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/{incentivesHalpers.ts → incentiveHelpers.ts}

@@ -1,20 +1,14 @@
-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;
-  amount: number;
+  amount: string;
   merkleProof: string[];
 }): Promise<{ txHash: string }> => {
   try {
@@ -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,47 +1,41 @@
-import {
-  type JsonRpcApiProvider,
-  type JsonRpcProvider,
-  type JsonRpcSigner,
-  type Provider,
-  type 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,
   isClaimedFromMerkleDistributor,
-} from './incentivesHalpers';
+} 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,51 +44,63 @@ export class Incentives {
   }
 
   /**
-   * Claims obol incentives from a Merkle Distributor contract.
+   * 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 {Object} incentivesData - The incentives data needed for claiming.
-   * @param {string} incentivesData.contractAddress - The address of the Merkle Distributor contract.
-   * @param {number} incentivesData.index - The index in the Merkle tree.
-   * @param {string} incentivesData.operatorAddress - The address of the operator.
-   * @param {number} incentivesData.amount - The amount to claim.
-   * @param {string[]} incentivesData.merkleProof - The Merkle proof.
-   * @returns {Promise<{ txHash: string }>} The transaction hash of the claim transaction.
-   * @throws Will throw an error if the contract is not available or the claim fails.
+   * @param {string} address - The address to claim incentives for
+   * @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(incentivesData: {
-    contractAddress: ETH_ADDRESS;
-    index: number;
-    operatorAddress: ETH_ADDRESS;
-    amount: number;
-    merkleProof: string[];
-  }): Promise<{ txHash: string }> {
+  async claimIncentives(address: string): Promise<ClaimIncentivesResponse> {
     if (!this.signer) {
       throw new Error('Signer is required in claimIncentives');
     }
+
     try {
+      const incentivesData = await this.getIncentivesByAddress(address);
+
+      if (!incentivesData?.contract_address) {
+        throw new Error(`No incentives found for address ${address}`);
+      }
+
       const isContractDeployed = await isContractAvailable(
-        incentivesData.contractAddress,
-        this.signer.provider as Provider,
+        incentivesData.contract_address,
+        this.provider as ProviderType,
       );
 
       if (!isContractDeployed) {
         throw new Error(
-          `Merkle Distributor contract is not available at address ${incentivesData.contractAddress}`,
+          `Merkle Distributor contract is not available at address ${incentivesData.contract_address}`,
         );
       }
 
+      const claimed = await this.isClaimed(
+        incentivesData.contract_address,
+        incentivesData.index,
+      );
+
+      if (claimed) {
+        return { txHash: null };
+      }
+
       const { txHash } = await claimIncentivesFromMerkleDistributor({
         signer: this.signer,
-        contractAddress: incentivesData.contractAddress,
+        contractAddress: incentivesData.contract_address,
         index: incentivesData.index,
-        operatorAddress: incentivesData.operatorAddress,
+        operatorAddress: incentivesData.operator_address,
         amount: incentivesData.amount,
-        merkleProof: incentivesData.merkleProof,
+        merkleProof: incentivesData.merkle_proof,
       });
 
       return { txHash };
@@ -111,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,
@@ -128,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];