@obolnetwork/obol-sdk 2.4.5 → 2.5.0

package/src/ajv.ts

@@ -1,78 +1,117 @@
-import Ajv, { type ErrorObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import addKeywords from 'ajv-keywords';
 import { parseUnits } from 'ethers';
 import {
   type RewardsSplitPayload,
   type SplitRecipient,
   type TotalSplitPayload,
 } from './types';
+import Ajv from 'ajv';
 import {
   DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
   DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
 } from './constants';
 
-const validDepositAmounts = (data: boolean, deposits: string[]): boolean => {
-  let sum = 0;
-  // from ether togwei is same as from gwei to wei
-  const maxDeposit = Number(parseUnits('32', 'gwei'));
-  const minDeposit = Number(parseUnits('1', 'gwei'));
+export const VALID_DEPOSIT_AMOUNTS = [
+  parseUnits('1', 'gwei').toString(),
+  parseUnits('32', 'gwei').toString(),
+  parseUnits('8', 'gwei').toString(),
+  parseUnits('256', 'gwei').toString(),
+];
 
-  for (const element of deposits) {
-    const amountInGWei = Number(element);
+export const VALID_NON_COMPOUNDING_AMOUNTS = [
+  parseUnits('1', 'gwei').toString(),
+  parseUnits('32', 'gwei').toString(),
+];
 
-    if (
-      !Number.isInteger(amountInGWei) ||
-      amountInGWei > maxDeposit ||
-      amountInGWei < minDeposit
-    ) {
-      return false;
-    }
-    sum += amountInGWei;
-  }
-  if (sum / minDeposit !== 32) {
-    return false;
-  } else {
-    return true;
-  }
+// They dont see defaults set in schema
+const validateRewardsSplitRecipients = (
+  _: boolean,
+  data: RewardsSplitPayload,
+): boolean => {
+  const obolRAFSplit =
+    data.ObolRAFSplit ?? DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT;
+  const splitPercentage = data.splitRecipients.reduce(
+    (acc: number, curr: SplitRecipient) => acc + curr.percentAllocation,
+    0,
+  );
+  return splitPercentage + obolRAFSplit === 100;
 };
 
-const validateSplitRecipients = (
+const validateTotalSplitRecipients = (
   _: boolean,
-  data: RewardsSplitPayload | TotalSplitPayload,
+  data: TotalSplitPayload,
 ): boolean => {
+  const obolRAFSplit =
+    data.ObolRAFSplit ?? DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT;
   const splitPercentage = data.splitRecipients.reduce(
     (acc: number, curr: SplitRecipient) => acc + curr.percentAllocation,
     0,
   );
-  const ObolRAFSplitParam = data.ObolRAFSplit
-    ? data.ObolRAFSplit
-    : 'principalRecipient' in data
-      ? DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT
-      : DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT;
-  return splitPercentage + ObolRAFSplitParam === 100;
+  return splitPercentage + obolRAFSplit === 100;
 };
 
-export function validatePayload(
-  data: any,
-  schema: any,
-): ErrorObject[] | undefined | null | boolean {
-  const ajv = new Ajv();
-  ajv.addKeyword({
-    keyword: 'validDepositAmounts',
-    validate: validDepositAmounts,
-    errors: true,
-  });
+const validateUniqueAddresses = (
+  _: boolean,
+  operators: Array<{ address: string }>,
+): boolean => {
+  if (!operators) {
+    return false;
+  }
+
+  if (operators.length < 4) {
+    return false;
+  }
+
+  if (operators.every(op => op.address === '')) {
+    return true;
+  }
+
+  if (operators.some(op => op.address.length !== 42)) {
+    return false;
+  }
+
+  const addresses = operators.map(op => op.address);
+  const uniqueAddresses = new Set(addresses);
+  const isUnique = uniqueAddresses.size === addresses.length;
+  return isUnique;
+};
+
+const ajv = new Ajv({
+  allErrors: true,
+  useDefaults: true,
+  strict: false,
+  $data: true,
+});
+addFormats(ajv);
+addKeywords(ajv, ['patternRequired']);
+
+ajv.addKeyword({
+  keyword: 'validateRewardsSplitRecipients',
+  validate: validateRewardsSplitRecipients,
+  schemaType: 'boolean',
+});
+
+ajv.addKeyword({
+  keyword: 'validateTotalSplitRecipients',
+  validate: validateTotalSplitRecipients,
+  schemaType: 'boolean',
+});
+
+ajv.addKeyword({
+  keyword: 'validateUniqueAddresses',
+  validate: validateUniqueAddresses,
+  schemaType: 'boolean',
+});
 
-  ajv.addKeyword({
-    keyword: 'validateSplitRecipients',
-    validate: validateSplitRecipients,
-    errors: true,
-  });
-  const validate = ajv.compile(schema);
-  const isValid = validate(data);
-  if (!isValid) {
-    throw new Error(
-      `Schema compilation errors', ${validate.errors?.[0].message}`,
-    );
+export function validatePayload<T>(data: unknown, schema: object): T {
+  const validate = ajv.compile<T>(schema);
+  const valid = validate(data);
+  if (!valid) {
+    const errors = validate.errors
+      ?.map(e => `${e.instancePath} ${e.message}`)
+      .join(', ');
+    throw new Error(`Validation failed: ${errors}`);
   }
-  return isValid;
+  return data;
 }

package/src/constants.ts

@@ -119,7 +119,7 @@ export const signEnrPayload = (
 
 export const DKG_ALGORITHM = 'default';
 
-export const CONFIG_VERSION = 'v1.8.0';
+export const CONFIG_VERSION = 'v1.10.0';
 
 export const SDK_VERSION = pjson.version;
 

package/src/incentiveHelpers.ts

@@ -1,7 +1,6 @@
 import { type ProviderType, type SignerType, type ETH_ADDRESS } from './types';
 import { Contract } from 'ethers';
 import { MerkleDistributorABI } from './abi/MerkleDistributorWithDeadline';
-import { getProvider } from './utils';
 
 export const claimIncentivesFromMerkleDistributor = async (incentivesData: {
   signer: SignerType;
@@ -35,18 +34,15 @@ export const claimIncentivesFromMerkleDistributor = async (incentivesData: {
 };
 
 export const isClaimedFromMerkleDistributor = async (
-  chainId: number,
   contractAddress: ETH_ADDRESS,
   index: number,
   provider: ProviderType | undefined | null,
 ): Promise<boolean> => {
   try {
-    const clientProvider = provider ?? getProvider(chainId);
-
     const contract = new Contract(
       contractAddress,
       MerkleDistributorABI.abi,
-      clientProvider,
+      provider,
     );
 
     const claimed = await contract.isClaimed(BigInt(index));

package/src/incentives.ts

@@ -1,6 +1,6 @@
 import { isContractAvailable } from './utils';
 import {
-  type Incentives as IncentivesType,
+  type ClaimableIncentives,
   type ETH_ADDRESS,
   FORK_NAMES,
   type ProviderType,
@@ -126,7 +126,6 @@ export class Incentives {
     index: number,
   ): Promise<boolean> {
     return await isClaimedFromMerkleDistributor(
-      this.chainId,
       contractAddress,
       index,
       this.provider,
@@ -141,9 +140,9 @@ export class Incentives {
    * 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,4 +1,3 @@
-import { ZeroAddress } from 'ethers';
 import { v4 as uuidv4 } from 'uuid';
 import { Base } from './base.js';
 import {
@@ -16,7 +15,6 @@ import {
   AVAILABLE_SPLITTER_CHAINS,
   CHAIN_CONFIGURATION,
   DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
-  DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
   OBOL_SDK_EMAIL,
 } from './constants.js';
 import { ConflictError } from './errors.js';
@@ -54,6 +52,7 @@ 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';
 
 /**
@@ -174,16 +173,16 @@ export class Client extends Base {
     principalRecipient,
     etherAmount,
     ObolRAFSplit = DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
-    distributorFee = 0,
-    controllerAddress = ZeroAddress,
-    recoveryAddress = ZeroAddress,
+    distributorFee,
+    controllerAddress,
+    recoveryAddress,
   }: RewardsSplitPayload): Promise<ClusterValidator> {
     // This method doesnt require T&C signature
     if (!this.signer) {
       throw new Error('Signer is required in createObolRewardsSplit');
     }
 
-    validatePayload(
+    const validatedPayload = validatePayload<Required<RewardsSplitPayload>>(
       {
         splitRecipients,
         principalRecipient,
@@ -234,10 +233,10 @@ export class Client extends Base {
     const retroActiveFundingRecipient = {
       account:
         CHAIN_CONFIGURATION[this.chainId].RETROACTIVE_FUNDING_ADDRESS.address,
-      percentAllocation: ObolRAFSplit,
+      percentAllocation: validatedPayload.ObolRAFSplit,
     };
 
-    const copiedSplitRecipients = [...splitRecipients];
+    const copiedSplitRecipients = [...validatedPayload.splitRecipients];
     copiedSplitRecipients.push(retroActiveFundingRecipient);
 
     const { accounts, percentAllocations } = formatSplitRecipients(
@@ -249,8 +248,8 @@ export class Client extends Base {
       accounts,
       percentAllocations,
       chainId: this.chainId,
-      distributorFee,
-      controllerAddress,
+      distributorFee: validatedPayload.distributorFee,
+      controllerAddress: validatedPayload.controllerAddress,
     });
 
     const isSplitterDeployed = await isContractAvailable(
@@ -265,12 +264,12 @@ export class Client extends Base {
         predictedSplitterAddress,
         accounts,
         percentAllocations,
-        principalRecipient,
-        etherAmount,
+        principalRecipient: validatedPayload.principalRecipient,
+        etherAmount: validatedPayload.etherAmount,
         chainId: this.chainId,
-        distributorFee,
-        controllerAddress,
-        recoveryAddress,
+        distributorFee: validatedPayload.distributorFee,
+        controllerAddress: validatedPayload.controllerAddress,
+        recoveryAddress: validatedPayload.recoveryAddress,
       });
 
     return { withdrawal_address, fee_recipient_address };
@@ -292,16 +291,16 @@ export class Client extends Base {
   // add the example reference
   async createObolTotalSplit({
     splitRecipients,
-    ObolRAFSplit = DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
-    distributorFee = 0,
-    controllerAddress = ZeroAddress,
+    ObolRAFSplit,
+    distributorFee,
+    controllerAddress,
   }: TotalSplitPayload): Promise<ClusterValidator> {
     // This method doesnt require T&C signature
     if (!this.signer) {
       throw new Error('Signer is required in createObolTotalSplit');
     }
 
-    validatePayload(
+    const validatedPayload = validatePayload<Required<TotalSplitPayload>>(
       {
         splitRecipients,
         ObolRAFSplit,
@@ -333,10 +332,10 @@ export class Client extends Base {
     const retroActiveFundingRecipient = {
       account:
         CHAIN_CONFIGURATION[this.chainId].RETROACTIVE_FUNDING_ADDRESS.address,
-      percentAllocation: ObolRAFSplit,
+      percentAllocation: validatedPayload.ObolRAFSplit,
     };
 
-    const copiedSplitRecipients = [...splitRecipients];
+    const copiedSplitRecipients = [...validatedPayload.splitRecipients];
     copiedSplitRecipients.push(retroActiveFundingRecipient);
 
     const { accounts, percentAllocations } = formatSplitRecipients(
@@ -347,8 +346,8 @@ export class Client extends Base {
       accounts,
       percentAllocations,
       chainId: this.chainId,
-      distributorFee,
-      controllerAddress,
+      distributorFee: validatedPayload.distributorFee,
+      controllerAddress: validatedPayload.controllerAddress,
     });
 
     const isSplitterDeployed = await isContractAvailable(
@@ -362,8 +361,8 @@ export class Client extends Base {
         accounts,
         percentAllocations,
         chainId: this.chainId,
-        distributorFee,
-        controllerAddress,
+        distributorFee: validatedPayload.distributorFee,
+        controllerAddress: validatedPayload.controllerAddress,
       });
       return {
         withdrawal_address: splitterAddress,
@@ -411,20 +410,20 @@ export class Client extends Base {
       throw new Error('Signer is required in createClusterDefinition');
     }
 
-    validatePayload(newCluster, definitionSchema);
+    const validatedCluster = validatePayload<ClusterPayload>(
+      newCluster,
+      definitionSchema,
+    );
 
     const clusterConfig: Partial<ClusterDefinition> = {
-      ...newCluster,
+      ...validatedCluster,
       fork_version: this.fork_version,
       dkg_algorithm: DKG_ALGORITHM,
       version: CONFIG_VERSION,
       uuid: uuidv4(),
       timestamp: new Date().toISOString(),
-      threshold: Math.ceil((2 * newCluster.operators.length) / 3),
-      num_validators: newCluster.validators.length,
-      deposit_amounts: newCluster.deposit_amounts
-        ? newCluster.deposit_amounts
-        : ['32000000000'],
+      threshold: Math.ceil((2 * validatedCluster.operators.length) / 3),
+      num_validators: validatedCluster.validators.length,
     };
     try {
       const address = await this.signer.getAddress();
@@ -479,7 +478,10 @@ export class Client extends Base {
       throw new Error('Signer is required in acceptClusterDefinition');
     }
 
-    validatePayload(operatorPayload, operatorPayloadSchema);
+    const validatedPayload = validatePayload<OperatorPayload>(
+      operatorPayload,
+      operatorPayloadSchema,
+    );
 
     try {
       const address = await this.signer.getAddress();
@@ -492,11 +494,11 @@ export class Client extends Base {
       const operatorENRSignature = await this.signer.signTypedData(
         Domain(this.chainId),
         EnrSigningTypes,
-        { enr: operatorPayload.enr },
+        { enr: validatedPayload.enr },
       );
 
       const operatorData: OperatorPayload = {
-        ...operatorPayload,
+        ...validatedPayload,
         address,
         enr_signature: operatorENRSignature,
         fork_version: this.fork_version,

package/src/schema.ts

@@ -1,17 +1,15 @@
+import { ZeroAddress } from 'ethers';
 import {
   DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
   DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
 } from './constants';
+import { VALID_DEPOSIT_AMOUNTS, VALID_NON_COMPOUNDING_AMOUNTS } from './ajv';
 
 export const operatorPayloadSchema = {
   type: 'object',
   properties: {
-    version: {
-      type: 'string',
-    },
-    enr: {
-      type: 'string',
-    },
+    version: { type: 'string' },
+    enr: { type: 'string' },
   },
   required: ['version', 'enr'],
 };
@@ -19,24 +17,20 @@ export const operatorPayloadSchema = {
 export const definitionSchema = {
   type: 'object',
   properties: {
-    name: {
-      type: 'string',
-    },
+    name: { type: 'string' },
     operators: {
       type: 'array',
       minItems: 4,
-      uniqueItems: true,
       items: {
         type: 'object',
         properties: {
           address: {
             type: 'string',
-            minLength: 42,
-            maxLength: 42,
           },
         },
         required: ['address'],
       },
+      validateUniqueAddresses: true,
     },
     validators: {
       type: 'array',
@@ -57,12 +51,39 @@ export const definitionSchema = {
       },
     },
     deposit_amounts: {
-      type: 'array',
+      type: ['array', 'null'],
       items: {
         type: 'string',
         pattern: '^[0-9]+$',
       },
-      validDepositAmounts: true,
+      if: {
+        $data: '1/compounding',
+      },
+      then: {
+        items: {
+          enum: VALID_DEPOSIT_AMOUNTS,
+        },
+      },
+      else: {
+        items: {
+          enum: VALID_NON_COMPOUNDING_AMOUNTS,
+        },
+      },
+      default: null,
+    },
+    compounding: {
+      type: 'boolean',
+      default: true,
+    },
+    target_gas_limit: {
+      type: 'number',
+      minimum: 1,
+      default: 36000000,
+    },
+    consensus_protocol: {
+      type: 'string',
+      enum: ['qbft', ''],
+      default: '',
     },
   },
   required: ['name', 'operators', 'validators'],
@@ -80,9 +101,7 @@ export const totalSplitterPayloadSchema = {
             type: 'string',
             pattern: '^0x[a-fA-F0-9]{40}$',
           },
-          percentAllocation: {
-            type: 'number',
-          },
+          percentAllocation: { type: 'number' },
         },
         required: ['account', 'percentAllocation'],
       },
@@ -90,40 +109,44 @@ export const totalSplitterPayloadSchema = {
     ObolRAFSplit: {
       type: 'number',
       minimum: DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
+      default: DEFAULT_RETROACTIVE_FUNDING_TOTAL_SPLIT,
     },
     distributorFee: {
       type: 'number',
       maximum: 10,
       multipleOf: 0.01,
+      default: 0,
     },
     controllerAddress: {
       type: 'string',
       pattern: '^0x[a-fA-F0-9]{40}$',
+      default: ZeroAddress,
     },
-    validateSplitRecipients: true,
   },
+  validateTotalSplitRecipients: true,
   required: ['splitRecipients'],
 };
 
 export const rewardsSplitterPayloadSchema = {
-  ...totalSplitterPayloadSchema,
+  type: 'object',
   properties: {
     ...totalSplitterPayloadSchema.properties,
     ObolRAFSplit: {
       type: 'number',
       minimum: DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
+      default: DEFAULT_RETROACTIVE_FUNDING_REWARDS_ONLY_SPLIT,
     },
     recoveryAddress: {
       type: 'string',
       pattern: '^0x[a-fA-F0-9]{40}$',
+      default: ZeroAddress,
     },
-    etherAmount: {
-      type: 'number',
-    },
+    etherAmount: { type: 'number' },
     principalRecipient: {
       type: 'string',
       pattern: '^0x[a-fA-F0-9]{40}$',
     },
   },
+  validateRewardsSplitRecipients: true,
   required: ['splitRecipients', 'principalRecipient', 'etherAmount'],
 };

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/types.ts

@@ -1,4 +1,5 @@
 import {
+  type Wallet,
   type ethers,
   type JsonRpcApiProvider,
   type JsonRpcProvider,
@@ -104,6 +105,15 @@ export type ClusterPayload = {
 
   /** The cluster partial deposits in gwei or 32000000000. */
   deposit_amounts?: string[] | null;
+
+  /** A withdrawal mechanism with 0x02 withdrawal credentials. */
+  compounding?: boolean;
+
+  /** The target gas limit where default is 36M. */
+  target_gas_limit?: number;
+
+  /** The consensus protocol e.g qbft. */
+  consensus_protocol?: string;
 };
 
 /**
@@ -143,7 +153,7 @@ export interface ClusterDefinition extends ClusterPayload {
   /** The consensus protocol e.g qbft. */
   consensus_protocol?: string;
 
-  /** The target gas limit where default is 30M. */
+  /** The target gas limit where default is 36M. */
   target_gas_limit?: number;
 
   /** A withdrawal mechanism with 0x02 withdrawal credentials. */
@@ -295,16 +305,16 @@ export type ClusterLock = {
 };
 
 /**
- * Incentives
+ * Claimable Obol Incentives
  */
-export type Incentives = {
+export type ClaimableIncentives = {
   /** Operator Address. */
   operator_address: string;
 
   /** The amount the recipient is entitled to. */
   amount: string;
 
-  /** The recipient’s index in the Merkle tree. */
+  /** The recipient's index in the Merkle tree. */
   index: number;
 
   /** The Merkle proof (an array of hashes) generated for the recipient. */
@@ -328,10 +338,15 @@ export type ProviderType =
   | JsonRpcApiProvider
   | ethers.BrowserProvider;
 
+/**
+ * Safe Wallet Provider Types
+ */
+export type SafeRpcUrl = string;
+
 /**
  * Signer Types
  */
-export type SignerType = Signer | JsonRpcSigner;
+export type SignerType = Signer | JsonRpcSigner | Wallet;
 
 /**
  * claimIncentives Response

package/src/utils.ts

@@ -76,10 +76,13 @@ export const isContractAvailable = async (
   return !!code && code !== '0x' && code !== '0x0';
 };
 
-export const getProvider = (chainId: number): ethers.JsonRpcProvider => {
-  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);
 };