@obolnetwork/obol-sdk 2.2.4 → 2.4.0

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;
+  }
+}

package/src/incentivesHalpers.ts

@@ -0,0 +1,58 @@
+import { type ETH_ADDRESS } from './types';
+import { Contract, 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,
+): Promise<boolean> => {
+  try {
+    const provider = getProvider(chainId);
+
+    const contract = new Contract(
+      contractAddress,
+      MerkleDistributorABI.abi,
+      provider,
+    );
+
+    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

@@ -47,6 +47,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,6 +58,7 @@ export * from './verification/common.js';
  */
 export class Client extends Base {
   private readonly signer: Signer | undefined;
+  public incentives: Incentives;
 
   /**
    * @param config - Client configurations
@@ -71,6 +73,11 @@ export class Client extends Base {
   constructor(config: { baseUrl?: string; chainId?: number }, signer?: Signer) {
     super(config);
     this.signer = signer;
+    this.incentives = new Incentives(
+      this.signer,
+      this.chainId,
+      this.request.bind(this),
+    );
   }
 
   /**

package/src/types.ts

@@ -293,6 +293,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
  */