@obolnetwork/obol-sdk 2.5.1 → 2.7.0

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()),
+  ]);
+};

package/src/types.ts

@@ -352,3 +352,161 @@ export type SignerType = Signer | JsonRpcSigner | Wallet;
  * claimIncentives Response
  */
 export type ClaimIncentivesResponse = { txHash: string | null };
+
+/**
+ * Represents the structure of an Ethereum operator for exit validation, primarily their ENR.
+ */
+export interface ExitOperator {
+  /** The operator's Ethereum Node Record (ENR). */
+  enr: string;
+}
+
+/**
+ * Represents the core definition of a cluster relevant for exit validation.
+ */
+export interface ExitClusterDefinition {
+  /** The cluster nodes operators with their ENRs. */
+  operators: ExitOperator[];
+
+  /** The cluster fork version. */
+  fork_version: string;
+
+  /** The distributed validator threshold. */
+  threshold: number;
+}
+
+/**
+ * Represents a distributed validator's information relevant for exit validation.
+ */
+export interface ExitDistributedValidator {
+  /** The public key of the distributed validator. */
+  distributed_public_key: string;
+
+  /** The public key shares of the distributed validator. */
+  public_shares: string[];
+}
+
+/**
+ * Combined cluster information needed for exit validation in the SDK.
+ */
+export interface ExitClusterConfig {
+  /** The cluster definition with operators, fork version and threshold. */
+  definition: ExitClusterDefinition;
+
+  /** The cluster distributed validators. */
+  distributed_validators: ExitDistributedValidator[];
+}
+
+/**
+ * Represents the message part of a signed exit for exit validation.
+ */
+export interface ExitValidationMessage {
+  /** The epoch at which the validator wishes to exit. */
+  epoch: string;
+
+  /** The index of the validator in the beacon chain. */
+  validator_index: string;
+}
+
+/**
+ * Represents a signed exit message for exit validation.
+ */
+export interface SignedExitValidationMessage {
+  /** The exit message containing epoch and validator index. */
+  message: ExitValidationMessage;
+
+  /** BLS signature of the exit message. */
+  signature: string;
+}
+
+/**
+ * Represents a single partial exit blob for exit validation.
+ */
+export interface ExitValidationBlob {
+  /** The public key of the validator to exit. */
+  public_key: string;
+
+  /** The signed exit message for the validator. */
+  signed_exit_message: SignedExitValidationMessage;
+}
+
+/**
+ * Represents the overall exit payload structure for exit validation.
+ */
+export interface ExitValidationPayload {
+  /** Array of partial exits for validators. */
+  partial_exits: ExitValidationBlob[];
+
+  /** Operator's share index (1-based). */
+  share_idx: number;
+
+  /** Signature of the ExitValidationPayload by the operator. */
+  signature: string;
+}
+
+/**
+ * Represents the data structure for an already existing exit blob for exit validation.
+ */
+export interface ExistingExitValidationBlobData {
+  /**
+   * The BLS public key of the validator in hex format
+   */
+  public_key: string;
+  /**
+   * The epoch number when the exit is scheduled to occur
+   */
+  epoch: string;
+  /**
+   * The unique index of the validator in the beacon chain
+   */
+  validator_index: string;
+  /**
+   * Array of distributed validator shares exit data, where each share contains
+   * the partial exit signature from each operator in the cluster
+   */
+  shares_exit_data: Array<Record<string, { partial_exit_signature: string }>>;
+}
+
+// ExitBlob is an exit message alongside its BLS12-381 hex-encoded signature.
+export interface FullExitBlob {
+  /**
+   * The signed voluntary exit message containing the exit details and signature
+   */
+  signed_exit_message: {
+    /**
+     * The voluntary exit message details
+     */
+    message: {
+      /**
+       * The epoch number when the validator exit will be processed
+       */
+      epoch: string;
+      /**
+       * The unique index of the validator requesting to exit
+       */
+      validator_index: string;
+    };
+    /**
+     * The BLS12-381 hex-encoded signature of the exit message
+     */
+    signature: string;
+  };
+
+  /** The public key of the validator to exit. */
+  public_key: string;
+}
+
+/**
+ * Generic HTTP request function type.
+ * Args:
+ *  url: string - The URL to request.
+ *  config?: Record<string, any> - Optional request configuration (e.g., method, headers, body for POST).
+ * Returns:
+ *  Promise<any> - The response data.
+ */
+export type HttpRequestFunc = (
+  url: string,
+  config?: Record<string, any>,
+) => Promise<any>;
+
+// Add other SDK-specific types below or import from other type files