@obolnetwork/obol-sdk 2.6.0 → 2.8.0

package/src/splits/splits.ts

@@ -0,0 +1,355 @@
+import {
+  formatRecipientsForSplitV2,
+  predictSplitV2Address,
+  isSplitV2Deployed,
+  deployOVMContract,
+  deployOVMAndSplitV2,
+} from './splitHelpers';
+import {
+  CHAIN_CONFIGURATION,
+  SPLITS_V2_SALT,
+  DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
+  isChainSupportedForSplitters,
+} from '../constants';
+import {
+  ovmRewardsSplitPayloadSchema,
+  ovmTotalSplitPayloadSchema,
+} from '../schema';
+import { validatePayload } from '../ajv';
+import { isContractAvailable } from '../utils';
+import {
+  type ClusterValidator,
+  type ProviderType,
+  type SignerType,
+  type OVMRewardsSplitPayload,
+  type OVMTotalSplitPayload,
+} from '../types';
+
+/**
+ * ObolSplits can be used for creating and managing Obol splits.
+ * @class
+ * @internal Access it through Client.splits.
+ * @example
+ * const obolClient = new Client(config);
+ * await obolClient.splits.createValidatorManagerAndRewardsSplit(OVMRewardsSplitPayload);
+ */
+export class ObolSplits {
+  private readonly signer: SignerType | undefined;
+  public readonly chainId: number;
+  public readonly provider: ProviderType | undefined | null;
+
+  constructor(
+    signer: SignerType | undefined,
+    chainId: number,
+    provider: ProviderType | undefined | null,
+  ) {
+    this.signer = signer;
+    this.chainId = chainId;
+    this.provider = provider;
+  }
+
+  /**
+   * Creates an Obol OVM and Pull split configuration for rewards-only scenario.
+   *
+   * This method deploys OVM and SplitV2 contracts for managing validator rewards only.
+   * Principal is handled by a single address, while rewards are split among recipients.
+   *
+   * @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 {OVMRewardsSplitPayload} payload - Data needed to deploy OVM and SplitV2
+   * @returns {Promise<ClusterValidator>} OVM address as withdrawal address and splitter as fee recipient
+   * @throws Will throw an error if the splitter configuration is not supported or deployment fails
+   *
+   * An example of how to use createValidatorManagerAndRewardsSplit:
+   * [createValidatorManagerAndRewardsSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L333)
+   */
+  async createValidatorManagerAndRewardsSplit(
+    payload: OVMRewardsSplitPayload,
+  ): Promise<ClusterValidator> {
+    const salt = SPLITS_V2_SALT;
+    if (!this.signer) {
+      throw new Error(
+        'Signer is required in createValidatorManagerAndRewardsSplit',
+      );
+    }
+
+    const validatedPayload = validatePayload<Required<OVMRewardsSplitPayload>>(
+      payload,
+      ovmRewardsSplitPayloadSchema,
+    );
+
+    if (!isChainSupportedForSplitters(this.chainId)) {
+      throw new Error(
+        `Splitter configuration is not supported on ${this.chainId} chain`,
+      );
+    }
+
+    const chainConfig = CHAIN_CONFIGURATION[this.chainId];
+    if (!chainConfig?.OVM_FACTORY_ADDRESS) {
+      throw new Error(
+        `OVM contract factory is not configured for chain ${this.chainId}`,
+      );
+    }
+
+    if (!this.provider) {
+      throw new Error(
+        'Provider is required to check OVM factory contract availability',
+      );
+    }
+
+    const ovmFactoryConfig = chainConfig.OVM_FACTORY_ADDRESS;
+    if (!ovmFactoryConfig?.address || !ovmFactoryConfig?.bytecode) {
+      throw new Error(
+        `OVM factory contract configuration is incomplete for chain ${this.chainId}`,
+      );
+    }
+
+    const checkOVMFactoryAddress = await isContractAvailable(
+      ovmFactoryConfig.address,
+      this.provider,
+      ovmFactoryConfig.bytecode,
+    );
+
+    if (!checkOVMFactoryAddress) {
+      throw new Error(
+        `OVM factory contract is not deployed or available on chain ${this.chainId}`,
+      );
+    }
+
+    const retroActiveFundingRecipient = {
+      address: chainConfig.RETROACTIVE_FUNDING_ADDRESS.address,
+      percentAllocation: DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
+    };
+
+    const copiedRewardsSplitRecipients = [
+      ...validatedPayload.rewardSplitRecipients,
+    ];
+    copiedRewardsSplitRecipients.push(retroActiveFundingRecipient);
+
+    // Format recipients for SplitV2
+    const rewardRecipients = formatRecipientsForSplitV2(
+      copiedRewardsSplitRecipients,
+    );
+
+    const predictedSplitAddress = await predictSplitV2Address({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: rewardRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    const isRewardSplitterDeployed = await isSplitV2Deployed({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: rewardRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    if (isRewardSplitterDeployed) {
+      const ovmAddress = await deployOVMContract({
+        OVMOwnerAddress: validatedPayload.OVMOwnerAddress,
+        principalRecipient: validatedPayload.principalRecipient,
+        rewardRecipient: predictedSplitAddress,
+        principalThreshold: validatedPayload.principalThreshold,
+        signer: this.signer,
+        chainId: this.chainId,
+      });
+
+      return {
+        withdrawal_address: ovmAddress,
+        fee_recipient_address: predictedSplitAddress,
+      };
+    } else {
+      const ovmAddress = await deployOVMAndSplitV2({
+        ovmArgs: {
+          OVMOwnerAddress: validatedPayload.OVMOwnerAddress,
+          rewardRecipient: predictedSplitAddress,
+          principalRecipient: validatedPayload.principalRecipient,
+          principalThreshold: validatedPayload.principalThreshold,
+        },
+        rewardRecipients,
+        isRewardsSplitterDeployed: isRewardSplitterDeployed,
+        distributorFeePercent: validatedPayload.distributorFeePercent,
+        salt,
+        signer: this.signer,
+        chainId: this.chainId,
+        splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      });
+
+      return {
+        withdrawal_address: ovmAddress,
+        fee_recipient_address: predictedSplitAddress,
+      };
+    }
+  }
+
+  /**
+   * Creates an Obol OVM and Total split configuration for total split scenario.
+   *
+   * This method deploys OVM and SplitV2 contracts for managing both validator rewards and principal.
+   * Both rewards and principal are split among recipients, with rewards including RAF recipient.
+   *
+   * @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 {OVMTotalSplitPayload} payload - Data needed to deploy OVM and SplitV2
+   * @returns {Promise<ClusterValidator>} OVM address as withdrawal address and splitter as fee recipient
+   * @throws Will throw an error if the splitter configuration is not supported or deployment fails
+   *
+   * An example of how to use createValidatorManagerAndTotalSplit:
+   * [createValidatorManagerAndTotalSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#340)
+   */
+  async createValidatorManagerAndTotalSplit(
+    payload: OVMTotalSplitPayload,
+  ): Promise<ClusterValidator> {
+    const salt = SPLITS_V2_SALT;
+    if (!this.signer) {
+      throw new Error(
+        'Signer is required in createValidatorManagerAndTotalSplit',
+      );
+    }
+
+    const validatedPayload = validatePayload<Required<OVMTotalSplitPayload>>(
+      payload,
+      ovmTotalSplitPayloadSchema,
+    );
+
+    if (!isChainSupportedForSplitters(this.chainId)) {
+      throw new Error(
+        `Splitter configuration is not supported on ${this.chainId} chain`,
+      );
+    }
+
+    const chainConfig = CHAIN_CONFIGURATION[this.chainId];
+    if (!chainConfig?.OVM_FACTORY_ADDRESS) {
+      throw new Error(
+        `OVM contract factory is not configured for chain ${this.chainId}`,
+      );
+    }
+
+    if (!this.provider) {
+      throw new Error(
+        'Provider is required to check OVM factory contract availability',
+      );
+    }
+
+    const ovmFactoryConfig = chainConfig.OVM_FACTORY_ADDRESS;
+    if (!ovmFactoryConfig?.address || !ovmFactoryConfig?.bytecode) {
+      throw new Error(
+        `OVM factory contract configuration is incomplete for chain ${this.chainId}`,
+      );
+    }
+
+    const checkOVMFactoryAddress = await isContractAvailable(
+      ovmFactoryConfig.address,
+      this.provider,
+      ovmFactoryConfig.bytecode,
+    );
+
+    if (!checkOVMFactoryAddress) {
+      throw new Error(
+        `OVM factory contract is not deployed or available on chain ${this.chainId}`,
+      );
+    }
+
+    const retroActiveFundingRecipient = {
+      address: chainConfig.RETROACTIVE_FUNDING_ADDRESS.address,
+      percentAllocation: DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
+    };
+
+    const copiedRewardsSplitRecipients = [
+      ...validatedPayload.rewardSplitRecipients,
+    ];
+    copiedRewardsSplitRecipients.push(retroActiveFundingRecipient);
+
+    const rewardsRecipients = formatRecipientsForSplitV2(
+      copiedRewardsSplitRecipients,
+    );
+
+    const principalSplitRecipients = formatRecipientsForSplitV2(
+      validatedPayload.principalSplitRecipients,
+    );
+
+    const predictedRewardsSplitAddress = await predictSplitV2Address({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: rewardsRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    const predictedPrincipalSplitAddress = await predictSplitV2Address({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: principalSplitRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    const isRewardsSplitterDeployed = await isSplitV2Deployed({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: rewardsRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    const isPrincipalSplitterDeployed = await isSplitV2Deployed({
+      splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      recipients: principalSplitRecipients,
+      distributorFeePercent: validatedPayload.distributorFeePercent,
+      salt,
+      signer: this.signer,
+      chainId: this.chainId,
+    });
+
+    if (isRewardsSplitterDeployed && isPrincipalSplitterDeployed) {
+      const ovmAddress = await deployOVMContract({
+        OVMOwnerAddress: validatedPayload.OVMOwnerAddress,
+        principalRecipient: predictedPrincipalSplitAddress,
+        rewardRecipient: predictedRewardsSplitAddress,
+        principalThreshold: validatedPayload.principalThreshold,
+        signer: this.signer,
+        chainId: this.chainId,
+      });
+
+      return {
+        withdrawal_address: ovmAddress,
+        fee_recipient_address: predictedRewardsSplitAddress,
+      };
+    } else {
+      // Use multicall to deploy any contracts that aren't deployed
+      const ovmAddress = await deployOVMAndSplitV2({
+        ovmArgs: {
+          OVMOwnerAddress: validatedPayload.OVMOwnerAddress,
+          rewardRecipient: predictedRewardsSplitAddress,
+          principalRecipient: predictedPrincipalSplitAddress,
+          principalThreshold: validatedPayload.principalThreshold,
+        },
+        rewardRecipients: rewardsRecipients,
+        distributorFeePercent: validatedPayload.distributorFeePercent,
+        salt,
+        signer: this.signer,
+        chainId: this.chainId,
+        principalSplitRecipients,
+        isPrincipalSplitDeployed: isPrincipalSplitterDeployed,
+        splitOwnerAddress: validatedPayload.splitOwnerAddress,
+      });
+
+      return {
+        withdrawal_address: ovmAddress,
+        fee_recipient_address: predictedRewardsSplitAddress,
+      };
+    }
+  }
+}

package/src/types.ts

@@ -5,7 +5,6 @@ import {
   type JsonRpcProvider,
   type JsonRpcSigner,
   type Provider,
-  type Signer,
 } from 'ethers';
 
 /**
@@ -202,6 +201,58 @@ export interface RewardsSplitPayload extends TotalSplitPayload {
   recoveryAddress?: string;
 }
 
+/**
+ * OVM and SplitV2 Base Params
+ */
+export type OVMBaseSplitPayload = {
+  /** The split recipients addresses and splits. */
+  rewardSplitRecipients: SplitV2Recipient[];
+
+  /** Owner address for the OVM contract. */
+  OVMOwnerAddress: string;
+
+  /** Owner address for the splitter contracts. */
+  splitOwnerAddress?: string;
+
+  /** Principal threshold for OVM contract. */
+  principalThreshold?: number;
+
+  /** Distributor fee percentage (0-10). */
+  distributorFeePercent?: number;
+};
+
+/**
+ * OVM and SplitV2 Params for rewards-only split
+ */
+export type OVMRewardsSplitPayload = OVMBaseSplitPayload & {
+  /** Principal recipient address (single address for rewards-only split). */
+  principalRecipient: string;
+};
+
+/**
+ * OVM and SplitV2 Params for total split scenario
+ */
+export type OVMTotalSplitPayload = OVMBaseSplitPayload & {
+  /** Principal recipients addresses and splits (array for total split scenario). */
+  principalSplitRecipients: SplitV2Recipient[];
+};
+
+/**
+ * Union type for both OVM split scenarios
+ */
+export type OVMSplitPayload = OVMRewardsSplitPayload | OVMTotalSplitPayload;
+
+/**
+ * SplitV2 Recipient structure
+ */
+export type SplitV2Recipient = {
+  /** Recipient address. */
+  address: string;
+
+  /** Percentage allocation (0-100 with up to 4 decimals). */
+  percentAllocation: number;
+};
+
 /**
  * OWR Tranches
  */
@@ -346,7 +397,7 @@ export type SafeRpcUrl = string;
 /**
  * Signer Types
  */
-export type SignerType = Signer | JsonRpcSigner | Wallet;
+export type SignerType = JsonRpcSigner | Wallet;
 
 /**
  * claimIncentives Response
@@ -448,19 +499,54 @@ export interface ExitValidationPayload {
  * Represents the data structure for an already existing exit blob for exit validation.
  */
 export interface ExistingExitValidationBlobData {
-  /** The public key of the validator to exit. */
+  /**
+   * The BLS public key of the validator in hex format
+   */
   public_key: string;
-
-  /** The epoch at which the validator wishes to exit. */
+  /**
+   * The epoch number when the exit is scheduled to occur
+   */
   epoch: string;
-
-  /** The index of the validator in the beacon chain. */
+  /**
+   * The unique index of the validator in the beacon chain
+   */
   validator_index: string;
-
-  /** Collection of partial exit signatures from different shares. */
+  /**
+   * 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:
@@ -474,4 +560,46 @@ export type HttpRequestFunc = (
   config?: Record<string, any>,
 ) => Promise<any>;
 
-// Add other SDK-specific types below or import from other type files
+/**
+ * OVM Arguments for contract creation
+ */
+export type OVMArgs = {
+  /** Owner address for the OVM contract. */
+  OVMOwnerAddress: string;
+
+  /** Principal recipient address. */
+  principalRecipient: string;
+
+  /** Rewards recipient of the cluster. */
+  rewardRecipient: string;
+
+  /** Principal threshold for OVM contract. */
+  principalThreshold: number;
+};
+
+export type ChainConfig = {
+  SPLITMAIN_ADDRESS: {
+    address: string;
+    bytecode: string;
+  };
+  MULTICALL_ADDRESS: {
+    address: string;
+    bytecode: string;
+  };
+  OWR_FACTORY_ADDRESS: {
+    address: string;
+    bytecode: string;
+  };
+  RETROACTIVE_FUNDING_ADDRESS: {
+    address: string;
+    bytecode: string;
+  };
+  OVM_FACTORY_ADDRESS?: {
+    address: string;
+    bytecode: string;
+  };
+  WAREHOUSE_ADDRESS?: {
+    address: string;
+    bytecode: string;
+  };
+};