feat: add getIncentivesByAddress method to fetch incentives for a given address

src/index.ts

@@ -30,6 +30,7 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type OWRTranches,
+  type Incentives,
 } from './types.js';
 import { clusterConfigOrDefinitionHash } from './verification/common.js';
 import { validatePayload } from './ajv.js';
@@ -519,4 +520,19 @@ 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.
+   */
+  async getIncentivesByAddress(address: string): Promise<Incentives> {
+    const incentives: Incentives = await this.request(
+      `/${DEFAULT_BASE_VERSION}/address/incentives/${address}`,
+      {
+        method: 'GET',
+      },
+    );
+    return incentives;
+  }
 }

src/types.ts

@@ -284,6 +284,26 @@ export type ClusterLock = {
   node_signatures?: string[];
 };
 
+/**
+ * Incentives
+ */
+export type Incentives = {
+  /** Operator Address. */
+  operator_address: string;
+
+  /** The amount the recipient is entitled to. */
+  amount: string;
+
+  /** The recipient’s index in the Merkle tree. */
+  index: number;
+
+  /** The Merkle proof (an array of hashes) generated for the recipient. */
+  merkle_proof: string[];
+
+  /** The MerkleDistributor contract address. */
+  contract_address: string;
+};
+
 /**
  * String expected to be Ethereum Address
  */

test/methods.test.ts

@@ -539,3 +539,76 @@ describe('createObolTotalSplit', () => {
     });
   });
 });
+
+describe('getIncentivesByAddress', () => {
+  let mockSigner: ethers.Signer | ethers.Wallet | undefined,
+    clientInstance: Client;
+  beforeAll(() => {
+    jest
+      .spyOn(utils, 'isContractAvailable')
+      .mockImplementation(async () => await Promise.resolve(true));
+    jest
+      .spyOn(splitsHelpers, 'predictSplitterAddress')
+      .mockImplementation(
+        async () => await Promise.resolve('0xPredictedAddress'),
+      );
+    jest
+      .spyOn(splitsHelpers, 'deploySplitterContract')
+      .mockImplementation(
+        async () => await Promise.resolve('0xSplitterAddress'),
+      );
+
+    const mnemonic = ethers.Wallet.createRandom().mnemonic?.phrase ?? '';
+    const privateKey = ethers.Wallet.fromPhrase(mnemonic).privateKey;
+    const provider = new JsonRpcProvider(
+      'https://ethereum-holesky.publicnode.com',
+    );
+    const wallet = new ethers.Wallet(privateKey, provider);
+    mockSigner = wallet.connect(provider);
+
+    clientInstance = new Client(
+      { baseUrl: 'https://obol-api-dev.gcp.obol.tech', chainId: 17000 },
+      mockSigner,
+    );
+  });
+
+  test('should return incentives for a valid address', async () => {
+    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 = await clientInstance.getIncentivesByAddress(mockAddress);
+    expect(incentives).toEqual(mockIncentives);
+  });
+
+  test('should throw an error if address is not found', async () => {
+    const invalidAddress = '0x0000000000000000000000000000000000000000';
+    clientInstance['request'] = jest
+      .fn()
+      .mockRejectedValue(new Error('Not found'));
+
+    await expect(
+      clientInstance.getIncentivesByAddress(invalidAddress),
+    ).rejects.toThrow('Not found');
+  });
+
+  test('should throw an error if request fails', async () => {
+    const mockAddress = '0x1234567890abcdef1234567890abcdef12345678';
+    clientInstance['request'] = jest
+      .fn()
+      .mockRejectedValue(new Error('Network error'));
+
+    await expect(
+      clientInstance.getIncentivesByAddress(mockAddress),
+    ).rejects.toThrow('Network error');
+  });
+});