@obolnetwork/obol-sdk 2.3.0 → 2.4.0

package/dist/esm/src/incentivesHalpers.js

@@ -0,0 +1,36 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { 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);
+        const tx = yield contract.claim(BigInt(incentivesData.index), incentivesData.operatorAddress, BigInt(incentivesData.amount), incentivesData.merkleProof);
+        const receipt = yield tx.wait();
+        return { txHash: receipt.hash };
+    }
+    catch (error) {
+        console.log('Error claiming incentives:', error);
+        throw new Error(`Failed to claim incentives: ${error.message}`);
+    }
+});
+export const isClaimedFromMerkleDistributor = (chainId, contractAddress, index) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const provider = getProvider(chainId);
+        const contract = new Contract(contractAddress, MerkleDistributorABI.abi, provider);
+        const claimed = yield contract.isClaimed(BigInt(index));
+        return claimed;
+    }
+    catch (error) {
+        console.log('Error checking claim status:', error);
+        throw new Error(`Failed to check claim status: ${error.message}`);
+    }
+});

package/dist/esm/src/index.js

@@ -17,6 +17,7 @@ import { validatePayload } from './ajv.js';
 import { definitionSchema, operatorPayloadSchema, rewardsSplitterPayloadSchema, totalSplitterPayloadSchema, } from './schema.js';
 import { deploySplitterContract, formatSplitRecipients, handleDeployOWRAndSplitter, predictSplitterAddress, getOWRTranches, } from './splitHelpers.js';
 import { isContractAvailable } from './utils.js';
+import { Incentives } from './incentives.js';
 export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
@@ -38,6 +39,7 @@ export class Client extends Base {
     constructor(config, signer) {
         super(config);
         this.signer = signer;
+        this.incentives = new Incentives(this.signer, this.chainId, this.request.bind(this));
     }
     /**
      * Accepts Obol terms and conditions to be able to create or update data.
@@ -353,17 +355,4 @@ export class Client extends Base {
             return lock;
         });
     }
-    /**
-     * @param address - Operator address
-     * @returns {Promise<Incentives>} The matched incentives from DB
-     * @throws On not found if address not found.
-     */
-    getIncentivesByAddress(address) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const incentives = yield this.request(`/${DEFAULT_BASE_VERSION}/address/incentives/${address}`, {
-                method: 'GET',
-            });
-            return incentives;
-        });
-    }
 }

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

@@ -0,0 +1,149 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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 { DEFAULT_BASE_VERSION } from '../src/constants';
+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';
+global.fetch = jest.fn();
+describe('Client.incentives', () => {
+    let clientInstance;
+    const mockIncentivesData = {
+        contractAddress: '0x1234567890abcdef1234567890abcdef12345678',
+        index: 5,
+        operatorAddress: '0xabcdef1234567890abcdef1234567890abcdef12',
+        amount: 1000000000000000000,
+        merkleProof: [
+            '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+            '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
+        ],
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        clientInstance = new Client({ baseUrl, chainId: 17000 }, mockSigner);
+        global.fetch.mockReset();
+    });
+    test('claimIncentives should throw an error without signer', () => __awaiter(void 0, void 0, void 0, function* () {
+        const clientWithoutSigner = new Client({
+            baseUrl,
+            chainId: 17000,
+        });
+        yield expect(clientWithoutSigner.incentives.claimIncentives(mockIncentivesData)).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(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}`);
+    }));
+    test('claimIncentives should return txHash on successful claim', () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockTxHash = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+        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);
+        expect(result).toEqual({ txHash: mockTxHash });
+        expect(incentivesHelpers.claimIncentivesFromMerkleDistributor).toHaveBeenCalledWith({
+            signer: mockSigner,
+            contractAddress: mockIncentivesData.contractAddress,
+            index: mockIncentivesData.index,
+            operatorAddress: mockIncentivesData.operatorAddress,
+            amount: mockIncentivesData.amount,
+            merkleProof: mockIncentivesData.merkleProof,
+        });
+    }));
+    test('claimIncentives should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        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* () {
+            throw new Error('Helper function error');
+        }));
+        yield expect(clientInstance.incentives.claimIncentives(mockIncentivesData)).rejects.toThrow('Failed to claim incentives: Helper function error');
+    }));
+    test('incentives should be initialized with the same chainId as client', () => {
+        const customChainId = 5;
+        const clientWithCustomChain = new Client({ baseUrl, chainId: customChainId }, mockSigner);
+        expect(clientWithCustomChain.incentives.chainId).toBe(customChainId);
+    });
+    test('isClaimed should return true when incentive is 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(true); }));
+        const result = yield clientInstance.incentives.isClaimed(mockIncentivesData.contractAddress, mockIncentivesData.index);
+        expect(result).toBe(true);
+        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientInstance.incentives.chainId, mockIncentivesData.contractAddress, 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);
+        expect(result).toBe(false);
+    }));
+    test('isClaimed should throw an error if helper function fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        jest
+            .spyOn(incentivesHelpers, 'isClaimedFromMerkleDistributor')
+            .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');
+    }));
+    test('isClaimed should work with a client without signer', () => __awaiter(void 0, void 0, void 0, function* () {
+        // Create a client without a signer
+        const clientWithoutSigner = new Client({
+            baseUrl,
+            chainId: 17000,
+        });
+        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);
+        expect(result).toBe(true);
+        expect(incentivesHelpers.isClaimedFromMerkleDistributor).toHaveBeenCalledWith(clientWithoutSigner.incentives.chainId, mockIncentivesData.contractAddress, mockIncentivesData.index);
+    }));
+    test('getIncentivesByAddress should make the correct API request', () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
+        const mockIncentives = {
+            operator_address: '0x8c00157cae72c4ed6a1f8bfb60205601f0252e26',
+            amount: '100',
+            index: 1,
+            merkle_proof: ['hash1', 'hash2'],
+            contract_address: '0xContract',
+        };
+        global.fetch.mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: () => __awaiter(void 0, void 0, void 0, function* () { return mockIncentives; }),
+            headers: new Headers(),
+        });
+        const result = yield clientInstance.incentives.getIncentivesByAddress(mockAddress);
+        expect(result).toEqual(mockIncentives);
+        expect(global.fetch).toHaveBeenCalledWith(`${baseUrl}/${DEFAULT_BASE_VERSION}/address/incentives/${mockAddress}`, expect.objectContaining({ method: 'GET' }));
+    }));
+    test('getIncentivesByAddress should handle API errors', () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
+        global.fetch.mockRejectedValue(new Error('Network error'));
+        yield expect(clientInstance.incentives.getIncentivesByAddress(mockAddress)).rejects.toThrow();
+        expect(global.fetch).toHaveBeenCalled();
+    }));
+});

package/dist/esm/test/methods.test.js

@@ -386,47 +386,3 @@ describe('createObolTotalSplit', () => {
         });
     }));
 });
-describe('getIncentivesByAddress', () => {
-    let clientInstance;
-    beforeAll(() => {
-        jest
-            .spyOn(utils, 'isContractAvailable')
-            .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve(true); }));
-        jest
-            .spyOn(splitsHelpers, 'predictSplitterAddress')
-            .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve('0xPredictedAddress'); }));
-        jest
-            .spyOn(splitsHelpers, 'deploySplitterContract')
-            .mockImplementation(() => __awaiter(void 0, void 0, void 0, function* () { return yield Promise.resolve('0xSplitterAddress'); }));
-        clientInstance = new Client({ baseUrl: 'https://obol-api-dev.gcp.obol.tech', chainId: 17000 }, mockSigner);
-    });
-    test('should return incentives for a valid address', () => __awaiter(void 0, void 0, void 0, function* () {
-        const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
-        const mockIncentives = {
-            operator_address: '0x8c00157cae72c4ed6a1f8bfb60205601f0252e26',
-            amount: '100',
-            index: 1,
-            merkle_proof: ['hash1', 'hash2'],
-            contract_address: '0xContract',
-        };
-        clientInstance['request'] = jest
-            .fn()
-            .mockReturnValue(Promise.resolve(mockIncentives));
-        const incentives = yield clientInstance.getIncentivesByAddress(mockAddress);
-        expect(incentives).toEqual(mockIncentives);
-    }));
-    test('should throw an error if address is not found', () => __awaiter(void 0, void 0, void 0, function* () {
-        const invalidAddress = '0x0000000000000000000000000000000000000000';
-        clientInstance['request'] = jest
-            .fn()
-            .mockRejectedValue(new Error('Not found'));
-        yield expect(clientInstance.getIncentivesByAddress(invalidAddress)).rejects.toThrow('Not found');
-    }));
-    test('should throw an error if request fails', () => __awaiter(void 0, void 0, void 0, function* () {
-        const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
-        clientInstance['request'] = jest
-            .fn()
-            .mockRejectedValue(new Error('Network error'));
-        yield expect(clientInstance.getIncentivesByAddress(mockAddress)).rejects.toThrow('Network error');
-    }));
-});

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

@@ -0,0 +1,91 @@
+export declare const MerkleDistributorABI: {
+    abi: readonly [{
+        readonly inputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "token_";
+            readonly type: "address";
+        }, {
+            readonly internalType: "bytes32";
+            readonly name: "merkleRoot_";
+            readonly type: "bytes32";
+        }];
+        readonly stateMutability: "nonpayable";
+        readonly type: "constructor";
+    }, {
+        readonly anonymous: false;
+        readonly inputs: readonly [{
+            readonly indexed: false;
+            readonly internalType: "uint256";
+            readonly name: "index";
+            readonly type: "uint256";
+        }, {
+            readonly indexed: false;
+            readonly internalType: "address";
+            readonly name: "account";
+            readonly type: "address";
+        }, {
+            readonly indexed: false;
+            readonly internalType: "uint256";
+            readonly name: "amount";
+            readonly type: "uint256";
+        }];
+        readonly name: "Claimed";
+        readonly type: "event";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "index";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "address";
+            readonly name: "account";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "amount";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "bytes32[]";
+            readonly name: "merkleProof";
+            readonly type: "bytes32[]";
+        }];
+        readonly name: "claim";
+        readonly outputs: readonly [];
+        readonly stateMutability: "nonpayable";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [{
+            readonly internalType: "uint256";
+            readonly name: "index";
+            readonly type: "uint256";
+        }];
+        readonly name: "isClaimed";
+        readonly outputs: readonly [{
+            readonly internalType: "bool";
+            readonly name: "";
+            readonly type: "bool";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [];
+        readonly name: "merkleRoot";
+        readonly outputs: readonly [{
+            readonly internalType: "bytes32";
+            readonly name: "";
+            readonly type: "bytes32";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }, {
+        readonly inputs: readonly [];
+        readonly name: "token";
+        readonly outputs: readonly [{
+            readonly internalType: "address";
+            readonly name: "";
+            readonly type: "address";
+        }];
+        readonly stateMutability: "view";
+        readonly type: "function";
+    }];
+};

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

@@ -0,0 +1,49 @@
+import { type Signer } from 'ethers';
+import { type Incentives as IncentivesType, type ETH_ADDRESS } from './types';
+export declare class Incentives {
+    private readonly signer;
+    chainId: number;
+    private readonly request;
+    constructor(signer: Signer | undefined, chainId: number, request: (endpoint: string, options?: RequestInit) => Promise<any>);
+    /**
+     * Claims obol incentives from a Merkle Distributor contract.
+     *
+     * @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.
+     *
+     */
+    claimIncentives(incentivesData: {
+        contractAddress: ETH_ADDRESS;
+        index: number;
+        operatorAddress: ETH_ADDRESS;
+        amount: number;
+        merkleProof: string[];
+    }): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Read isClaimed.
+     *
+     * @param {ETH_ADDRESS} contractAddress - Address of the Merkle Distributor Contract
+     * @param {ETH_ADDRESS} index - operator index in merkle tree
+     * @returns {Promise<boolean>} true if incentives are already claime
+     *
+     */
+    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.
+     */
+    getIncentivesByAddress(address: string): Promise<IncentivesType>;
+}

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

@@ -0,0 +1,13 @@
+import { type ETH_ADDRESS } from './types';
+import { type Signer } from 'ethers';
+export declare const claimIncentivesFromMerkleDistributor: (incentivesData: {
+    signer: Signer;
+    contractAddress: ETH_ADDRESS;
+    index: number;
+    operatorAddress: ETH_ADDRESS;
+    amount: number;
+    merkleProof: string[];
+}) => Promise<{
+    txHash: string;
+}>;
+export declare const isClaimedFromMerkleDistributor: (chainId: number, contractAddress: ETH_ADDRESS, index: number) => Promise<boolean>;

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

@@ -1,6 +1,7 @@
 import { type Signer } 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, type Incentives } from './types.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 { Incentives } from './incentives.js';
 export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
@@ -10,6 +11,7 @@ export * from './verification/common.js';
  */
 export declare class Client extends Base {
     private readonly signer;
+    incentives: Incentives;
     /**
      * @param config - Client configurations
      * @param config.baseUrl - obol-api url
@@ -112,10 +114,4 @@ export declare class Client extends Base {
      * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L89)
      */
     getClusterLock(configHash: string): Promise<ClusterLock>;
-    /**
-     * @param address - Operator address
-     * @returns {Promise<Incentives>} The matched incentives from DB
-     * @throws On not found if address not found.
-     */
-    getIncentivesByAddress(address: string): Promise<Incentives>;
 }

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

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A package for creating Distributed Validators using the Obol API.",
   "bugs": {
     "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -15,7 +15,7 @@
     "compile": "tsc -b ./tsconfig.cjs.json ./tsconfig.esm.json ./tsconfig.types.json",
     "build:clean": "rm -rf ./dist",
     "build": "npm-run-all build:clean compile",
-    "test": "jest ./test/methods.test.ts",
+    "test": "jest ./test/*.test.ts",
     "generate-typedoc": "typedoc",
     "npm:publish": "npm publish --tag latest",
     "release": "release-it",

package/src/abi/MerkleDistributorWithDeadline.ts

@@ -0,0 +1,70 @@
+export const MerkleDistributorABI = {
+  abi: [
+    {
+      inputs: [
+        { internalType: 'address', name: 'token_', type: 'address' },
+        { internalType: 'bytes32', name: 'merkleRoot_', type: 'bytes32' },
+      ],
+      stateMutability: 'nonpayable',
+      type: 'constructor',
+    },
+    {
+      anonymous: false,
+      inputs: [
+        {
+          indexed: false,
+          internalType: 'uint256',
+          name: 'index',
+          type: 'uint256',
+        },
+        {
+          indexed: false,
+          internalType: 'address',
+          name: 'account',
+          type: 'address',
+        },
+        {
+          indexed: false,
+          internalType: 'uint256',
+          name: 'amount',
+          type: 'uint256',
+        },
+      ],
+      name: 'Claimed',
+      type: 'event',
+    },
+    {
+      inputs: [
+        { internalType: 'uint256', name: 'index', type: 'uint256' },
+        { internalType: 'address', name: 'account', type: 'address' },
+        { internalType: 'uint256', name: 'amount', type: 'uint256' },
+        { internalType: 'bytes32[]', name: 'merkleProof', type: 'bytes32[]' },
+      ],
+      name: 'claim',
+      outputs: [],
+      stateMutability: 'nonpayable',
+      type: 'function',
+    },
+    {
+      inputs: [{ internalType: 'uint256', name: 'index', type: 'uint256' }],
+      name: 'isClaimed',
+      outputs: [{ internalType: 'bool', name: '', type: 'bool' }],
+      stateMutability: 'view',
+      type: 'function',
+    },
+    {
+      inputs: [],
+      name: 'merkleRoot',
+      outputs: [{ internalType: 'bytes32', name: '', type: 'bytes32' }],
+      stateMutability: 'view',
+      type: 'function',
+    },
+    {
+      inputs: [],
+      name: 'token',
+      outputs: [{ internalType: 'address', name: '', type: 'address' }],
+      stateMutability: 'view',
+      type: 'function',
+    },
+  ] as const,
+};

package/src/incentives.ts

@@ -0,0 +1,116 @@
+import { type Provider, type Signer } from 'ethers';
+import { isContractAvailable } from './utils';
+import { type Incentives as IncentivesType, type ETH_ADDRESS } from './types';
+import {
+  claimIncentivesFromMerkleDistributor,
+  isClaimedFromMerkleDistributor,
+} from './incentivesHalpers';
+import { DEFAULT_BASE_VERSION } from './constants';
+
+export class Incentives {
+  private readonly signer: Signer | undefined;
+  public chainId: number;
+  private readonly request: (
+    endpoint: string,
+    options?: RequestInit,
+  ) => Promise<any>;
+
+  constructor(
+    signer: Signer | undefined,
+    chainId: number,
+    request: (endpoint: string, options?: RequestInit) => Promise<any>,
+  ) {
+    this.signer = signer;
+    this.chainId = chainId;
+    this.request = request;
+  }
+
+  /**
+   * Claims obol incentives from a Merkle Distributor contract.
+   *
+   * @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.
+   *
+   */
+  async claimIncentives(incentivesData: {
+    contractAddress: ETH_ADDRESS;
+    index: number;
+    operatorAddress: ETH_ADDRESS;
+    amount: number;
+    merkleProof: string[];
+  }): Promise<{ txHash: string }> {
+    if (!this.signer) {
+      throw new Error('Signer is required in claimIncentives');
+    }
+    try {
+      const isContractDeployed = await isContractAvailable(
+        incentivesData.contractAddress,
+        this.signer.provider as Provider,
+      );
+
+      if (!isContractDeployed) {
+        throw new Error(
+          `Merkle Distributor contract is not available at address ${incentivesData.contractAddress}`,
+        );
+      }
+
+      const { txHash } = await claimIncentivesFromMerkleDistributor({
+        signer: this.signer,
+        contractAddress: incentivesData.contractAddress,
+        index: incentivesData.index,
+        operatorAddress: incentivesData.operatorAddress,
+        amount: incentivesData.amount,
+        merkleProof: incentivesData.merkleProof,
+      });
+
+      return { txHash };
+    } catch (error: any) {
+      console.log('Error claiming incentives:', error);
+      throw new Error(`Failed to claim incentives: ${error.message}`);
+    }
+  }
+
+  /**
+   * Read isClaimed.
+   *
+   * @param {ETH_ADDRESS} contractAddress - Address of the Merkle Distributor Contract
+   * @param {ETH_ADDRESS} index - operator index in merkle tree
+   * @returns {Promise<boolean>} true if incentives are already claime
+   *
+   */
+  async isClaimed(
+    contractAddress: ETH_ADDRESS,
+    index: number,
+  ): Promise<boolean> {
+    return await isClaimedFromMerkleDistributor(
+      this.chainId,
+      contractAddress,
+      index,
+    );
+  }
+
+  /**
+   * @param address - Operator address
+   * @returns {Promise<IncentivesType>} The matched incentives from DB
+   * @throws On not found if address not found.
+   */
+  async getIncentivesByAddress(address: string): Promise<IncentivesType> {
+    const incentives: IncentivesType = await this.request(
+      `/${DEFAULT_BASE_VERSION}/address/incentives/${address}`,
+      {
+        method: 'GET',
+      },
+    );
+    return incentives;
+  }
+}