@obolnetwork/obol-sdk 2.3.0 → 2.4.1

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/constants.ts

@@ -1,6 +1,6 @@
 import { type TypedMessage } from '@metamask/eth-sig-util';
 import { type TypedDataDomain } from 'ethers';
-import * as pjson from '../package.json';
+import pjson from '../package.json';
 import { FORK_MAPPING } from './types';
 import {
   HOLESKY_MULTICALL_BYTECODE,

package/src/incentives.ts

@@ -0,0 +1,137 @@
+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 } from './types';
+import {
+  claimIncentivesFromMerkleDistributor,
+  isClaimedFromMerkleDistributor,
+} from './incentivesHalpers';
+import { DEFAULT_BASE_VERSION } from './constants';
+
+export class Incentives {
+  private readonly signer: Signer | JsonRpcSigner | undefined;
+  public readonly chainId: number;
+  private readonly request: (
+    endpoint: string,
+    options?: RequestInit,
+  ) => Promise<any>;
+
+  public 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,
+  ) {
+    this.signer = signer;
+    this.chainId = chainId;
+    this.request = request;
+    this.provider = provider;
+  }
+
+  /**
+   * 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,
+      this.provider,
+    );
+  }
+
+  /**
+   * @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;
+  }
+}

package/src/incentivesHalpers.ts

@@ -0,0 +1,65 @@
+import { type ETH_ADDRESS } from './types';
+import {
+  Contract,
+  type JsonRpcApiProvider,
+  type JsonRpcProvider,
+  type Provider,
+  type Signer,
+} from 'ethers';
+import { MerkleDistributorABI } from './abi/MerkleDistributorWithDeadline';
+import { getProvider } from './utils';
+
+export const claimIncentivesFromMerkleDistributor = async (incentivesData: {
+  signer: Signer;
+  contractAddress: ETH_ADDRESS;
+  index: number;
+  operatorAddress: ETH_ADDRESS;
+  amount: number;
+  merkleProof: string[];
+}): Promise<{ txHash: string }> => {
+  try {
+    const contract = new Contract(
+      incentivesData.contractAddress,
+      MerkleDistributorABI.abi,
+      incentivesData.signer,
+    );
+
+    const tx = await contract.claim(
+      BigInt(incentivesData.index),
+      incentivesData.operatorAddress,
+      BigInt(incentivesData.amount),
+      incentivesData.merkleProof,
+    );
+
+    const receipt = await tx.wait();
+
+    return { txHash: receipt.hash };
+  } catch (error: any) {
+    console.log('Error claiming incentives:', error);
+    throw new Error(`Failed to claim incentives: ${error.message}`);
+  }
+};
+
+export const isClaimedFromMerkleDistributor = async (
+  chainId: number,
+  contractAddress: ETH_ADDRESS,
+  index: number,
+  provider: Provider | JsonRpcProvider | JsonRpcApiProvider | undefined | null,
+): Promise<boolean> => {
+  try {
+    const clientProvider = provider ?? getProvider(chainId);
+
+    const contract = new Contract(
+      contractAddress,
+      MerkleDistributorABI.abi,
+      clientProvider,
+    );
+
+    const claimed = await contract.isClaimed(BigInt(index));
+
+    return claimed;
+  } catch (error: any) {
+    console.log('Error checking claim status:', error);
+    throw new Error(`Failed to check claim status: ${error.message}`);
+  }
+};

package/src/index.ts

@@ -1,4 +1,11 @@
-import { ZeroAddress, type Provider, type Signer } from 'ethers';
+import {
+  ZeroAddress,
+  type Provider,
+  type Signer,
+  type JsonRpcSigner,
+  type JsonRpcProvider,
+  type JsonRpcApiProvider,
+} from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import {
@@ -30,7 +37,6 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type OWRTranches,
-  type Incentives,
 } from './types.js';
 import { clusterConfigOrDefinitionHash } from './verification/common.js';
 import { validatePayload } from './ajv.js';
@@ -48,6 +54,7 @@ import {
   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';
@@ -57,7 +64,14 @@ export * from './verification/common.js';
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
  */
 export class Client extends Base {
-  private readonly signer: Signer | undefined;
+  private readonly signer: Signer | JsonRpcSigner | undefined;
+  public incentives: Incentives;
+  public provider:
+    | Provider
+    | JsonRpcProvider
+    | JsonRpcApiProvider
+    | undefined
+    | null;
 
   /**
    * @param config - Client configurations
@@ -69,9 +83,23 @@ export class Client extends Base {
    * An example of how to instantiate obol-sdk Client:
    * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L29)
    */
-  constructor(config: { baseUrl?: string; chainId?: number }, signer?: Signer) {
+  constructor(
+    config: { baseUrl?: string; chainId?: number },
+    signer?: Signer | JsonRpcSigner,
+    provider?: Provider | JsonRpcProvider,
+  ) {
     super(config);
     this.signer = signer;
+    // Use the provided provider, or fall back to signer.provider if available
+    this.provider =
+      provider ??
+      (signer && 'provider' in signer ? signer.provider : undefined);
+    this.incentives = new Incentives(
+      this.signer,
+      this.chainId,
+      this.request.bind(this),
+      (this.provider = provider),
+    );
   }
 
   /**
@@ -521,19 +549,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.
-   */
-  async getIncentivesByAddress(address: string): Promise<Incentives> {
-    const incentives: Incentives = await this.request(
-      `/${DEFAULT_BASE_VERSION}/address/incentives/${address}`,
-      {
-        method: 'GET',
-      },
-    );
-    return incentives;
-  }
 }

package/src/verification/signature-validator.ts

@@ -23,7 +23,7 @@ export const validateAddressSignature = async ({
   chainId: number;
 }): Promise<boolean> => {
   try {
-    const provider = getProvider(chainId);
+    const provider = getProvider(chainId); // [TODO Hanan], should expect it from signer.provider, or passed in client
     if (provider) {
       const contractAddress = await isContractAvailable(address, provider);
       if (contractAddress) {