@obolnetwork/obol-sdk 2.4.4 → 2.4.6

package/src/incentives.ts

@@ -1,15 +1,11 @@
-import type {
-  JsonRpcApiProvider,
-  JsonRpcProvider,
-  JsonRpcSigner,
-  Provider,
-  Signer,
-} from 'ethers';
 import { isContractAvailable } from './utils';
 import {
-  type Incentives as IncentivesType,
+  type ClaimableIncentives,
   type ETH_ADDRESS,
   FORK_NAMES,
+  type ProviderType,
+  type SignerType,
+  type ClaimIncentivesResponse,
 } from './types';
 import {
   claimIncentivesFromMerkleDistributor,
@@ -17,31 +13,29 @@ import {
 } 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,20 +44,25 @@ export class Incentives {
   }
 
   /**
-   * Claims obol incentives from a Merkle Distributor contract using just an address.
-   * The method automatically fetches incentives data and checks if already claimed.
+   * 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 {string} address - The address to claim incentives for
-   * @returns {Promise<{ txHash: string } | { alreadyClaimed: true }>} The transaction hash or already claimed status
+   * @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(
-    address: string,
-  ): Promise<{ txHash: string } | { alreadyClaimed: true }> {
+  async claimIncentives(address: string): Promise<ClaimIncentivesResponse> {
     if (!this.signer) {
       throw new Error('Signer is required in claimIncentives');
     }
@@ -77,7 +76,7 @@ export class Incentives {
 
       const isContractDeployed = await isContractAvailable(
         incentivesData.contract_address,
-        this.provider as Provider,
+        this.provider as ProviderType,
       );
 
       if (!isContractDeployed) {
@@ -92,7 +91,7 @@ export class Incentives {
       );
 
       if (claimed) {
-        return { alreadyClaimed: true };
+        return { txHash: null };
       }
 
       const { txHash } = await claimIncentivesFromMerkleDistributor({
@@ -118,13 +117,15 @@ 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,
     index: number,
   ): Promise<boolean> {
     return await isClaimedFromMerkleDistributor(
-      this.chainId,
       contractAddress,
       index,
       this.provider,
@@ -135,10 +136,13 @@ 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> {
+  async getIncentivesByAddress(address: string): Promise<ClaimableIncentives> {
     const network = FORK_NAMES[this.chainId];
-    const incentives: IncentivesType = await this.request(
+    const incentives: ClaimableIncentives = await this.request(
       `/${DEFAULT_BASE_VERSION}/address/incentives/${network}/${address}`,
       {
         method: 'GET',

package/src/index.ts

@@ -1,11 +1,4 @@
-import {
-  ZeroAddress,
-  type Provider,
-  type Signer,
-  type JsonRpcSigner,
-  type JsonRpcProvider,
-  type JsonRpcApiProvider,
-} from 'ethers';
+import { ZeroAddress } from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import {
@@ -37,6 +30,8 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type OWRTranches,
+  type ProviderType,
+  type SignerType,
 } from './types.js';
 import { clusterConfigOrDefinitionHash } from './verification/common.js';
 import { validatePayload } from './ajv.js';
@@ -59,19 +54,28 @@ 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 class Client extends Base {
-  private readonly signer: Signer | JsonRpcSigner | undefined;
+  /**
+   * The signer used for signing transactions.
+   */
+  private readonly signer: SignerType | undefined;
+
+  /**
+   * The incentives module, responsible for managing Obol tokens distribution.
+   * @type {Incentives}
+   */
   public incentives: Incentives;
-  public 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.
+   */
+  public provider: ProviderType | undefined | null;
 
   /**
    * @param config - Client configurations
@@ -85,8 +89,8 @@ export class Client extends Base {
    */
   constructor(
     config: { baseUrl?: string; chainId?: number },
-    signer?: Signer | JsonRpcSigner,
-    provider?: Provider | JsonRpcProvider,
+    signer?: SignerType,
+    provider?: ProviderType,
   ) {
     super(config);
     this.signer = signer;
@@ -201,19 +205,19 @@ export class Client extends Base {
 
     const checkSplitMainAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.bytecode,
     );
 
     const checkMulticallAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].MULTICALL_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].MULTICALL_ADDRESS.bytecode,
     );
 
     const checkOWRFactoryAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].OWR_FACTORY_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].OWR_FACTORY_ADDRESS.bytecode,
     );
 
@@ -251,7 +255,7 @@ export class Client extends Base {
 
     const isSplitterDeployed = await isContractAvailable(
       predictedSplitterAddress,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
     );
 
     const { withdrawal_address, fee_recipient_address } =
@@ -316,7 +320,7 @@ export class Client extends Base {
 
     const checkSplitMainAddress = await isContractAvailable(
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.address,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
       CHAIN_CONFIGURATION[this.chainId].SPLITMAIN_ADDRESS.bytecode,
     );
 
@@ -349,7 +353,7 @@ export class Client extends Base {
 
     const isSplitterDeployed = await isContractAvailable(
       predictedSplitterAddress,
-      this.signer.provider as Provider,
+      this.signer.provider as ProviderType,
     );
 
     if (!isSplitterDeployed) {

package/src/services.ts

@@ -1,9 +1,10 @@
-import { type ClusterLock } from './types.js';
+import { type SafeRpcUrl, type ClusterLock } from './types.js';
 import { isValidClusterLock } from './verification/common.js';
 
 /**
  * Verifies Cluster Lock's validity.
  * @param lock - cluster lock
+ * @param safeRpcUrl - optional safeRpcUrl for safe wallet verification
  * @returns {Promise<{ result: boolean }> } boolean result to indicate if lock is valid
  * @throws on missing keys or values.
  *
@@ -12,9 +13,10 @@ import { isValidClusterLock } from './verification/common.js';
  */
 export const validateClusterLock = async (
   lock: ClusterLock,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   try {
-    const isLockValid = await isValidClusterLock(lock);
+    const isLockValid = await isValidClusterLock(lock, safeRpcUrl);
     return isLockValid;
   } catch (err: any) {
     throw err;

package/src/splitHelpers.ts

@@ -3,14 +3,9 @@ import {
   type ClusterValidator,
   type ETH_ADDRESS,
   type SplitRecipient,
+  type SignerType,
 } from './types';
-import {
-  Contract,
-  Interface,
-  parseEther,
-  ZeroAddress,
-  type Signer,
-} from 'ethers';
+import { Contract, Interface, parseEther, ZeroAddress } from 'ethers';
 import { OWRContract, OWRFactoryContract } from './abi/OWR';
 import { splitMainEthereumAbi } from './abi/SplitMain';
 import { MultiCallContract } from './abi/Multicall';
@@ -59,7 +54,7 @@ export const predictSplitterAddress = async ({
   distributorFee,
   controllerAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   accounts: ETH_ADDRESS[];
   percentAllocations: number[];
   chainId: number;
@@ -111,7 +106,7 @@ export const handleDeployOWRAndSplitter = async ({
   controllerAddress,
   recoveryAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   isSplitterDeployed: boolean;
   predictedSplitterAddress: ETH_ADDRESS;
   accounts: ETH_ADDRESS[];
@@ -174,7 +169,7 @@ const createOWRContract = async ({
   chainId,
 }: {
   owrArgs: OWRArgs;
-  signer: Signer;
+  signer: SignerType;
   chainId: number;
 }): Promise<ETH_ADDRESS> => {
   try {
@@ -209,7 +204,7 @@ export const deploySplitterContract = async ({
   distributorFee,
   controllerAddress,
 }: {
-  signer: Signer;
+  signer: SignerType;
   accounts: ETH_ADDRESS[];
   percentAllocations: number[];
   chainId: number;
@@ -247,7 +242,7 @@ export const deploySplitterAndOWRContracts = async ({
 }: {
   owrArgs: OWRArgs;
   splitterArgs: SplitArgs;
-  signer: Signer;
+  signer: SignerType;
   chainId: number;
 }): Promise<{ owrAddress: ETH_ADDRESS; splitterAddress: ETH_ADDRESS }> => {
   const executeCalls: Call[] = [];
@@ -304,7 +299,7 @@ export const getOWRTranches = async ({
   signer,
 }: {
   owrAddress: ETH_ADDRESS;
-  signer: Signer;
+  signer: SignerType;
 }): Promise<OWRTranches> => {
   const owrContract = new Contract(owrAddress, OWRContract.abi, signer);
   const res = await owrContract.getTranches();
@@ -318,7 +313,7 @@ export const getOWRTranches = async ({
 
 export const multicall = async (
   calls: Call[],
-  signer: Signer,
+  signer: SignerType,
   multicallAddress: string,
 ): Promise<any> => {
   const multiCallContractInstance = new Contract(

package/src/types.ts

@@ -1,3 +1,13 @@
+import {
+  type Wallet,
+  type ethers,
+  type JsonRpcApiProvider,
+  type JsonRpcProvider,
+  type JsonRpcSigner,
+  type Provider,
+  type Signer,
+} from 'ethers';
+
 /**
  * Permitted ChainID's
  */
@@ -21,28 +31,14 @@ export enum FORK_MAPPING {
   '0x10000910' = 560048,
 }
 
-/**
- * Permitted Chain Names
- */
 export const FORK_NAMES: Record<number, string> = {
-  /** Mainnet. */
   [FORK_MAPPING['0x00000000']]: 'mainnet',
-
-  /** Goerli/Prater. */
   [FORK_MAPPING['0x00001020']]: 'goerli',
-
-  /** Gnosis Chain. */
   [FORK_MAPPING['0x00000064']]: 'gnosis',
-
-  /** Holesky. */
   [FORK_MAPPING['0x01017000']]: 'holesky',
-
-  /** Sepolia. */
   [FORK_MAPPING['0x90000069']]: 'sepolia',
-
-  /** Hoodi. */
   [FORK_MAPPING['0x10000910']]: 'hoodi',
-};
+} as const;
 
 /**
  * Node operator data
@@ -300,9 +296,9 @@ export type ClusterLock = {
 };
 
 /**
- * Incentives
+ * Claimable Obol Incentives
  */
-export type Incentives = {
+export type ClaimableIncentives = {
   /** Operator Address. */
   operator_address: string;
 
@@ -323,3 +319,27 @@ export type Incentives = {
  * String expected to be Ethereum Address
  */
 export type ETH_ADDRESS = string;
+
+/**
+ * Provider Types
+ */
+export type ProviderType =
+  | Provider
+  | JsonRpcProvider
+  | JsonRpcApiProvider
+  | ethers.BrowserProvider;
+
+/**
+ * Safe Wallet Provider Types
+ */
+export type SafeRpcUrl = string;
+
+/**
+ * Signer Types
+ */
+export type SignerType = Signer | JsonRpcSigner | Wallet;
+
+/**
+ * claimIncentives Response
+ */
+export type ClaimIncentivesResponse = { txHash: string | null };

package/src/utils.ts

@@ -1,6 +1,6 @@
-import { ethers, type Provider } from 'ethers';
+import { ethers } from 'ethers';
 import { DefinitionFlow, PROVIDER_MAP } from './constants';
-import { FORK_NAMES, type ClusterDefinition } from './types';
+import { FORK_NAMES, type ProviderType, type ClusterDefinition } from './types';
 
 export const hexWithout0x = (hex: string): string => {
   return hex.slice(2, hex.length);
@@ -58,14 +58,14 @@ export const definitionFlow = (
 
 export const findDeployedBytecode = async (
   contractAddress: string,
-  provider: Provider,
+  provider: ProviderType,
 ): Promise<string> => {
   return await provider?.getCode(contractAddress);
 };
 
 export const isContractAvailable = async (
   contractAddress: string,
-  provider: Provider,
+  provider: ProviderType,
   bytecode?: string,
 ): Promise<boolean> => {
   const code = await findDeployedBytecode(contractAddress, provider);
@@ -76,10 +76,13 @@ export const isContractAvailable = async (
   return !!code && code !== '0x' && code !== '0x0';
 };
 
-export const getProvider = (chainId: number): ethers.Provider => {
-  const rpcUrl = PROVIDER_MAP[chainId];
-  if (!rpcUrl || rpcUrl === 'undefined') {
+export const getProvider = (
+  chainId: number,
+  rpcUrl?: string,
+): ethers.JsonRpcProvider => {
+  const resolvedRpcUrl = rpcUrl ?? PROVIDER_MAP[chainId];
+  if (chainId && (!resolvedRpcUrl || resolvedRpcUrl === 'undefined')) {
     throw new Error(`No provider configured for ${FORK_NAMES[chainId]}`);
   }
-  return new ethers.JsonRpcProvider(rpcUrl);
+  return new ethers.JsonRpcProvider(resolvedRpcUrl);
 };

package/src/verification/common.ts

@@ -1,7 +1,6 @@
 import { fromHexString } from '@chainsafe/ssz';
 import elliptic from 'elliptic';
 import { init } from '@chainsafe/bls';
-
 import {
   FORK_MAPPING,
   type ClusterDefinition,
@@ -9,6 +8,7 @@ import {
   type DepositData,
   type BuilderRegistrationMessage,
   type DistributedValidator,
+  type SafeRpcUrl,
 } from '../types.js';
 import * as semver from 'semver';
 import {
@@ -167,6 +167,7 @@ const validatePOSTConfigHashSigner = async (
   signature: string,
   configHash: string,
   chainId: FORK_MAPPING,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   try {
     const data = signCreatorConfigHashPayload(
@@ -179,6 +180,7 @@ const validatePOSTConfigHashSigner = async (
       token: signature,
       data,
       chainId,
+      safeRpcUrl,
     });
   } catch (err) {
     throw err;
@@ -190,6 +192,7 @@ const validatePUTConfigHashSigner = async (
   signature: string,
   configHash: string,
   chainId: number,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   try {
     const data = signOperatorConfigHashPayload(
@@ -201,6 +204,7 @@ const validatePUTConfigHashSigner = async (
       token: signature,
       data,
       chainId,
+      safeRpcUrl,
     });
   } catch (err) {
     throw err;
@@ -212,6 +216,7 @@ const validateEnrSigner = async (
   signature: string,
   payload: string,
   chainId: number,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   try {
     const data = signEnrPayload({ enr: payload }, chainId);
@@ -221,6 +226,7 @@ const validateEnrSigner = async (
       token: signature,
       data,
       chainId,
+      safeRpcUrl,
     });
   } catch (err) {
     throw err;
@@ -230,6 +236,7 @@ const validateEnrSigner = async (
 const verifyDefinitionSignatures = async (
   clusterDefinition: ClusterDefinition,
   definitionType: DefinitionFlow,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   if (definitionType === DefinitionFlow.Charon) {
     return true;
@@ -239,6 +246,7 @@ const verifyDefinitionSignatures = async (
       clusterDefinition.creator.config_signature as string,
       clusterDefinition.config_hash,
       FORK_MAPPING[clusterDefinition.fork_version as keyof typeof FORK_MAPPING],
+      safeRpcUrl,
     );
 
     if (!isPOSTConfigHashSignerValid) {
@@ -256,6 +264,7 @@ const verifyDefinitionSignatures = async (
         FORK_MAPPING[
           clusterDefinition.fork_version as keyof typeof FORK_MAPPING
         ],
+        safeRpcUrl,
       );
 
       const isENRSignerValid = await validateEnrSigner(
@@ -265,6 +274,7 @@ const verifyDefinitionSignatures = async (
         FORK_MAPPING[
           clusterDefinition.fork_version as keyof typeof FORK_MAPPING
         ],
+        safeRpcUrl,
       );
 
       if (!isPUTConfigHashSignerValid || !isENRSignerValid) {
@@ -485,6 +495,7 @@ const verifyLockData = async (clusterLock: ClusterLock): Promise<boolean> => {
 
 export const isValidClusterLock = async (
   clusterLock: ClusterLock,
+  safeRpcUrl?: SafeRpcUrl,
 ): Promise<boolean> => {
   try {
     const definitionType = definitionFlow(clusterLock.cluster_definition);
@@ -494,6 +505,7 @@ export const isValidClusterLock = async (
     const isValidDefinitionData = await verifyDefinitionSignatures(
       clusterLock.cluster_definition,
       definitionType,
+      safeRpcUrl,
     );
     if (!isValidDefinitionData) {
       return false;

package/src/verification/signature-validator.ts

@@ -10,20 +10,23 @@ import { PROVIDER_MAP } from '../constants';
 import { hashTypedData } from '@safe-global/protocol-kit/dist/src/utils';
 import { type EIP712TypedData } from '@safe-global/safe-core-sdk-types';
 import { isContractAvailable, getProvider } from '../utils';
+import { type SafeRpcUrl } from '../types';
 
 export const validateAddressSignature = async ({
   address,
   token,
   data,
   chainId,
+  safeRpcUrl,
 }: {
   address: string;
   token: string;
   data: TypedMessage<any>;
   chainId: number;
+  safeRpcUrl?: SafeRpcUrl;
 }): Promise<boolean> => {
   try {
-    const provider = getProvider(chainId); // [TODO Hanan], should expect it from signer.provider, or passed in client
+    const provider = getProvider(chainId, safeRpcUrl);
     if (provider) {
       const contractAddress = await isContractAvailable(address, provider);
       if (contractAddress) {
@@ -32,6 +35,7 @@ export const validateAddressSignature = async ({
           data: data as unknown as EIP712TypedData,
           address,
           chainId,
+          safeRpcUrl,
         });
       }
     }
@@ -69,16 +73,19 @@ export const validateSmartContractSignature = async ({
   data,
   address,
   chainId,
+  safeRpcUrl,
 }: {
   token: string;
   data: EIP712TypedData;
   address: string;
   chainId: number;
+  safeRpcUrl?: SafeRpcUrl;
 }): Promise<boolean> => {
   try {
-    const provider = PROVIDER_MAP[chainId];
+    const safeProvider = safeRpcUrl ?? PROVIDER_MAP[chainId];
+
     const protocolKit = await Safe.init({
-      provider,
+      provider: safeProvider,
       safeAddress: address,
     });
     const messageHash = hashTypedData(data);