@obolnetwork/obol-sdk 2.5.1 → 2.6.0

package/src/index.ts

@@ -45,15 +45,17 @@ import {
   handleDeployOWRAndSplitter,
   predictSplitterAddress,
   getOWRTranches,
-} from './splitHelpers.js';
+} from './splits/splitHelpers.js';
 import { isContractAvailable } from './utils.js';
-import { Incentives } from './incentives.js';
+import { Incentives } from './incentives/incentives.js';
+import { Exit } from './exits/exit.js';
 export * from './types.js';
 export * from './services.js';
 export * from './verification/signature-validator.js';
 export * from './verification/common.js';
 export * from './constants.js';
-export { Incentives } from './incentives.js';
+export { Incentives } from './incentives/incentives.js';
+export { Exit } from './exits/exit.js';
 
 /**
  * Obol sdk Client can be used for creating, managing and activating distributed validators.
@@ -70,6 +72,12 @@ export class Client extends Base {
    */
   public incentives: Incentives;
 
+  /**
+   * The exit module, responsible for managing exit validation.
+   * @type {Exit}
+   */
+  public exit: Exit;
+
   /**
    * 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.
@@ -103,6 +111,7 @@ export class Client extends Base {
       this.request.bind(this),
       this.provider,
     );
+    this.exit = new Exit(this.chainId, this.provider);
   }
 
   /**
@@ -341,6 +350,7 @@ export class Client extends Base {
     const { accounts, percentAllocations } = formatSplitRecipients(
       copiedSplitRecipients,
     );
+
     const predictedSplitterAddress = await predictSplitterAddress({
       signer: this.signer,
       accounts,
@@ -555,4 +565,20 @@ export class Client extends Base {
     );
     return lock;
   }
+
+  /**
+   * @param lockHash - The configuration hash in cluster-definition
+   * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
+   * @throws On not found cluster definition or lock.
+   *
+   */
+  async getClusterLockByHash(lockHash: string): Promise<ClusterLock> {
+    const lock: ClusterLock = await this.request(
+      `/${DEFAULT_BASE_VERSION}/lock/${lockHash}`,
+      {
+        method: 'GET',
+      },
+    );
+    return lock;
+  }
 }

package/src/splits/splitHelpers.ts

@@ -0,0 +1,557 @@
+import {
+  type OWRTranches,
+  type ClusterValidator,
+  type ETH_ADDRESS,
+  type SplitRecipient,
+  type SignerType,
+} from '../types';
+import { Contract, Interface, parseEther, ZeroAddress } from 'ethers';
+import { OWRContract, OWRFactoryContract } from '../abi/OWR';
+import { splitMainEthereumAbi } from '../abi/SplitMain';
+import { MultiCallContract } from '../abi/Multicall';
+import { CHAIN_CONFIGURATION } from '../constants';
+
+const splitMainContractInterface = new Interface(splitMainEthereumAbi);
+const owrFactoryContractInterface = new Interface(OWRFactoryContract.abi);
+
+type Call = {
+  target: ETH_ADDRESS;
+  callData: string;
+};
+
+type OWRArgs = {
+  recoveryAddress: ETH_ADDRESS;
+  principalRecipient: ETH_ADDRESS;
+  amountOfPrincipalStake: number;
+  predictedSplitterAddress: ETH_ADDRESS;
+};
+
+type SplitArgs = {
+  accounts: ETH_ADDRESS[];
+  percentAllocations: number[];
+  distributorFee: number;
+  controllerAddress: ETH_ADDRESS;
+};
+
+export const formatSplitRecipients = (
+  recipients: SplitRecipient[],
+): { accounts: ETH_ADDRESS[]; percentAllocations: number[] } => {
+  // Has to be sorted when passed
+  recipients.sort((a, b) => a.account.localeCompare(b.account));
+  const accounts = recipients.map(item => item.account);
+  const percentAllocations = recipients.map(recipient => {
+    const splitTostring = (recipient.percentAllocation * 1e4).toFixed(0);
+    return parseInt(splitTostring);
+  });
+  return { accounts, percentAllocations };
+};
+
+export const predictSplitterAddress = async ({
+  signer,
+  accounts,
+  percentAllocations,
+  chainId,
+  distributorFee,
+  controllerAddress,
+}: {
+  signer: SignerType;
+  accounts: ETH_ADDRESS[];
+  percentAllocations: number[];
+  chainId: number;
+  distributorFee: number;
+  controllerAddress: ETH_ADDRESS;
+}): Promise<ETH_ADDRESS> => {
+  try {
+    const splitMainContractInstance = new Contract(
+      CHAIN_CONFIGURATION[chainId].SPLITMAIN_ADDRESS.address,
+      splitMainEthereumAbi,
+      signer,
+    );
+
+    let predictedSplitterAddress: string;
+
+    if (controllerAddress === ZeroAddress) {
+      try {
+        predictedSplitterAddress =
+          await splitMainContractInstance.predictImmutableSplitAddress(
+            accounts,
+            percentAllocations,
+            distributorFee,
+          );
+      } catch (error: any) {
+        throw new Error(
+          `Failed to predict immutable splitter address: ${error.message ?? 'Contract call failed'}`,
+        );
+      }
+    } else {
+      try {
+        // It throws on deployed Immutable splitter
+        predictedSplitterAddress =
+          await splitMainContractInstance.createSplit.staticCall(
+            accounts,
+            percentAllocations,
+            distributorFee,
+            controllerAddress,
+          );
+      } catch (error: any) {
+        throw new Error(
+          `Failed to predict mutable splitter address via static call: ${error.message ?? 'Static call failed'}`,
+        );
+      }
+    }
+
+    return predictedSplitterAddress;
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (error.message.includes('Failed to predict')) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in predictSplitterAddress: ${error.message ?? 'Unknown contract interaction error'}`,
+    );
+  }
+};
+
+export const handleDeployOWRAndSplitter = async ({
+  signer,
+  isSplitterDeployed,
+  predictedSplitterAddress,
+  accounts,
+  percentAllocations,
+  etherAmount,
+  principalRecipient,
+  chainId,
+  distributorFee,
+  controllerAddress,
+  recoveryAddress,
+}: {
+  signer: SignerType;
+  isSplitterDeployed: boolean;
+  predictedSplitterAddress: ETH_ADDRESS;
+  accounts: ETH_ADDRESS[];
+  percentAllocations: number[];
+  etherAmount: number;
+  principalRecipient: ETH_ADDRESS;
+  chainId: number;
+  distributorFee: number;
+  controllerAddress: ETH_ADDRESS;
+  recoveryAddress: ETH_ADDRESS;
+}): Promise<ClusterValidator> => {
+  try {
+    if (isSplitterDeployed) {
+      let owrAddress: ETH_ADDRESS;
+      try {
+        owrAddress = await createOWRContract({
+          owrArgs: {
+            principalRecipient,
+            amountOfPrincipalStake: etherAmount,
+            predictedSplitterAddress,
+            recoveryAddress,
+          },
+          signer,
+          chainId,
+        });
+      } catch (error: any) {
+        throw new Error(
+          `Failed to create OWR contract with existing splitter: ${error.message ?? 'OWR contract creation failed'}`,
+        );
+      }
+      return {
+        withdrawal_address: owrAddress,
+        fee_recipient_address: predictedSplitterAddress,
+      };
+    } else {
+      let owrAddress: ETH_ADDRESS;
+      let splitterAddress: ETH_ADDRESS;
+      try {
+        const result = await deploySplitterAndOWRContracts({
+          owrArgs: {
+            principalRecipient,
+            amountOfPrincipalStake: etherAmount,
+            predictedSplitterAddress,
+            recoveryAddress,
+          },
+          splitterArgs: {
+            accounts,
+            percentAllocations,
+            distributorFee,
+            controllerAddress,
+          },
+          signer,
+          chainId,
+        });
+        owrAddress = result.owrAddress;
+        splitterAddress = result.splitterAddress;
+      } catch (error: any) {
+        throw new Error(
+          `Failed to deploy both splitter and OWR contracts: ${error.message ?? 'Multicall contract deployment failed'}`,
+        );
+      }
+
+      return {
+        withdrawal_address: owrAddress,
+        fee_recipient_address: splitterAddress,
+      };
+    }
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (error.message.includes('Failed to')) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in handleDeployOWRAndSplitter: ${error.message ?? 'Unknown error during contract deployment orchestration'}`,
+    );
+  }
+};
+
+const createOWRContract = async ({
+  owrArgs,
+  signer,
+  chainId,
+}: {
+  owrArgs: OWRArgs;
+  signer: SignerType;
+  chainId: number;
+}): Promise<ETH_ADDRESS> => {
+  try {
+    const OWRFactoryInstance = new Contract(
+      CHAIN_CONFIGURATION[chainId].OWR_FACTORY_ADDRESS.address,
+      OWRFactoryContract.abi,
+      signer,
+    );
+
+    let tx;
+    try {
+      tx = await OWRFactoryInstance.createOWRecipient(
+        owrArgs.recoveryAddress,
+        owrArgs.principalRecipient,
+        owrArgs.predictedSplitterAddress,
+        parseEther(owrArgs.amountOfPrincipalStake.toString()),
+      );
+    } catch (error: any) {
+      throw new Error(
+        `Failed to submit OWR contract creation transaction: ${error.message ?? 'Transaction submission failed'}`,
+      );
+    }
+
+    let receipt;
+    try {
+      receipt = await tx.wait();
+    } catch (error: any) {
+      throw new Error(
+        `OWR contract creation transaction failed or was reverted: ${error.message ?? 'Transaction execution failed'}`,
+      );
+    }
+
+    if (!receipt?.logs?.length) {
+      throw new Error(
+        'OWR contract creation transaction succeeded but no events were emitted - unable to determine contract address',
+      );
+    }
+
+    const OWRAddressData = receipt.logs[0]?.topics[1];
+    if (!OWRAddressData) {
+      throw new Error(
+        'OWR contract creation transaction succeeded but contract address could not be extracted from events',
+      );
+    }
+
+    const formattedOWRAddress = '0x' + OWRAddressData.slice(26, 66);
+
+    // Basic address validation
+    if (
+      formattedOWRAddress.length !== 42 ||
+      !formattedOWRAddress.startsWith('0x')
+    ) {
+      throw new Error(
+        `Invalid OWR contract address format: ${formattedOWRAddress}`,
+      );
+    }
+
+    return formattedOWRAddress;
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (
+      error.message.includes('Failed to') ||
+      error.message.includes('OWR contract') ||
+      error.message.includes('Invalid OWR')
+    ) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in createOWRContract: ${error.message ?? 'Unknown error during OWR contract creation'}`,
+    );
+  }
+};
+
+export const deploySplitterContract = async ({
+  signer,
+  accounts,
+  percentAllocations,
+  chainId,
+  distributorFee,
+  controllerAddress,
+}: {
+  signer: SignerType;
+  accounts: ETH_ADDRESS[];
+  percentAllocations: number[];
+  chainId: number;
+  distributorFee: number;
+  controllerAddress: ETH_ADDRESS;
+}): Promise<ETH_ADDRESS> => {
+  try {
+    const splitMainContractInstance = new Contract(
+      CHAIN_CONFIGURATION[chainId].SPLITMAIN_ADDRESS.address,
+      splitMainEthereumAbi,
+      signer,
+    );
+
+    let tx;
+    try {
+      tx = await splitMainContractInstance.createSplit(
+        accounts,
+        percentAllocations,
+        distributorFee,
+        controllerAddress,
+      );
+    } catch (error: any) {
+      throw new Error(
+        `Failed to submit splitter contract creation transaction: ${error.message ?? 'Transaction submission failed'}`,
+      );
+    }
+
+    let receipt;
+    try {
+      receipt = await tx.wait();
+    } catch (error: any) {
+      throw new Error(
+        `Splitter contract creation transaction failed or was reverted: ${error.message ?? 'Transaction execution failed'}`,
+      );
+    }
+
+    if (!receipt?.logs?.length) {
+      throw new Error(
+        'Splitter contract creation transaction succeeded but no events were emitted - unable to determine contract address',
+      );
+    }
+
+    const splitterAddressData = receipt.logs[0]?.topics[1];
+    if (!splitterAddressData) {
+      throw new Error(
+        'Splitter contract creation transaction succeeded but contract address could not be extracted from events',
+      );
+    }
+
+    const formattedSplitterAddress = '0x' + splitterAddressData.slice(26, 66);
+
+    // Basic address validation
+    if (
+      formattedSplitterAddress.length !== 42 ||
+      !formattedSplitterAddress.startsWith('0x')
+    ) {
+      throw new Error(
+        `Invalid splitter contract address format: ${formattedSplitterAddress}`,
+      );
+    }
+
+    return formattedSplitterAddress;
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (
+      error.message.includes('Failed to') ||
+      error.message.includes('Splitter contract') ||
+      error.message.includes('Invalid splitter')
+    ) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in deploySplitterContract: ${error.message ?? 'Unknown error during splitter contract creation'}`,
+    );
+  }
+};
+
+export const deploySplitterAndOWRContracts = async ({
+  owrArgs,
+  splitterArgs,
+  signer,
+  chainId,
+}: {
+  owrArgs: OWRArgs;
+  splitterArgs: SplitArgs;
+  signer: SignerType;
+  chainId: number;
+}): Promise<{ owrAddress: ETH_ADDRESS; splitterAddress: ETH_ADDRESS }> => {
+  const executeCalls: Call[] = [];
+
+  const splitTxData = encodeCreateSplitTxData(
+    splitterArgs.accounts,
+    splitterArgs.percentAllocations,
+    splitterArgs.distributorFee,
+    splitterArgs.controllerAddress,
+  );
+
+  const owrTxData = encodeCreateOWRecipientTxData(
+    owrArgs.recoveryAddress,
+    owrArgs.principalRecipient,
+    owrArgs.predictedSplitterAddress,
+    owrArgs.amountOfPrincipalStake,
+  );
+
+  executeCalls.push(
+    {
+      target: CHAIN_CONFIGURATION[chainId].SPLITMAIN_ADDRESS.address,
+      callData: splitTxData,
+    },
+    {
+      target: CHAIN_CONFIGURATION[chainId].OWR_FACTORY_ADDRESS.address,
+      callData: owrTxData,
+    },
+  );
+  const multicallAddess =
+    CHAIN_CONFIGURATION[chainId].MULTICALL_ADDRESS.address;
+
+  const executeMultiCalls = await multicall(
+    executeCalls,
+    signer,
+    multicallAddess,
+  );
+
+  const splitAddressData = executeMultiCalls?.logs[0]?.topics[1];
+  const formattedSplitterAddress = '0x' + splitAddressData?.slice(26, 66);
+  const owrAddressData = executeMultiCalls?.logs[1]?.topics[1];
+  const formattedOwrAddress = '0x' + owrAddressData?.slice(26, 66);
+
+  return {
+    owrAddress: formattedOwrAddress,
+    splitterAddress: formattedSplitterAddress,
+  };
+};
+
+export const getOWRTranches = async ({
+  owrAddress,
+  signer,
+}: {
+  owrAddress: ETH_ADDRESS;
+  signer: SignerType;
+}): Promise<OWRTranches> => {
+  try {
+    const owrContract = new Contract(owrAddress, OWRContract.abi, signer);
+
+    let res;
+    try {
+      res = await owrContract.getTranches();
+    } catch (error: any) {
+      throw new Error(
+        `Failed to call getTranches on OWR contract at ${owrAddress}: ${error.message ?? 'Contract call failed'}`,
+      );
+    }
+
+    if (!res) {
+      throw new Error(
+        `OWR contract at ${owrAddress} returned empty result for getTranches()`,
+      );
+    }
+
+    return {
+      principalRecipient: res.principalRecipient,
+      rewardRecipient: res.rewardRecipient,
+      amountOfPrincipalStake: res.amountOfPrincipalStake,
+    };
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (
+      error.message.includes('Failed to') ||
+      error.message.includes('OWR contract')
+    ) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in getOWRTranches: ${error.message ?? 'Unknown error while fetching OWR tranche data'}`,
+    );
+  }
+};
+
+export const multicall = async (
+  calls: Call[],
+  signer: SignerType,
+  multicallAddress: string,
+): Promise<any> => {
+  try {
+    const multiCallContractInstance = new Contract(
+      multicallAddress,
+      MultiCallContract.abi,
+      signer,
+    );
+
+    let tx;
+    try {
+      tx = await multiCallContractInstance.aggregate(calls);
+    } catch (error: any) {
+      throw new Error(
+        `Failed to submit multicall transaction: ${error.message ?? 'Transaction submission failed'}`,
+      );
+    }
+
+    let receipt;
+    try {
+      receipt = await tx.wait();
+    } catch (error: any) {
+      throw new Error(
+        `Multicall transaction failed or was reverted: ${error.message ?? 'Transaction execution failed'}`,
+      );
+    }
+
+    if (!receipt) {
+      throw new Error(
+        'Multicall transaction succeeded but no receipt was returned',
+      );
+    }
+
+    return receipt;
+  } catch (error: any) {
+    // Re-throw if it's already our custom error
+    if (
+      error.message.includes('Failed to') ||
+      error.message.includes('Multicall transaction')
+    ) {
+      throw error;
+    }
+    // Handle unexpected errors
+    throw new Error(
+      `Unexpected error in multicall: ${error.message ?? 'Unknown error during multicall execution'}`,
+    );
+  }
+};
+
+const encodeCreateSplitTxData = (
+  accounts: ETH_ADDRESS[],
+  percentAllocations: number[],
+  distributorFee: number,
+  controller: ETH_ADDRESS,
+): ETH_ADDRESS => {
+  return splitMainContractInterface.encodeFunctionData('createSplit', [
+    accounts,
+    percentAllocations,
+    distributorFee,
+    controller,
+  ]);
+};
+
+const encodeCreateOWRecipientTxData = (
+  recoveryAddress: ETH_ADDRESS,
+  principalRecipient: ETH_ADDRESS,
+  rewardRecipient: ETH_ADDRESS,
+  amountOfPrincipalStake: number,
+): ETH_ADDRESS => {
+  return owrFactoryContractInterface.encodeFunctionData('createOWRecipient', [
+    recoveryAddress,
+    principalRecipient,
+    rewardRecipient,
+    parseEther(amountOfPrincipalStake.toString()),
+  ]);
+};