@obolnetwork/obol-sdk 1.0.9 → 1.0.12

package/src/constants.ts

@@ -0,0 +1,118 @@
+import { TypedMessage } from "@metamask/eth-sig-util";
+
+export const CONFLICT_ERROR_MSG = "Conflict"
+
+export const EIP712_DOMAIN_NAME = "Obol";
+export const EIP712_DOMAIN_VERSION = "1";
+export const CreatorConfigHashSigningTypes = {
+    CreatorConfigHash: [{ name: "creator_config_hash", type: "string" }],
+};
+
+const EIP712Domain = [
+    { name: 'name', type: 'string' },
+    { name: 'version', type: 'string' },
+    { name: 'chainId', type: 'uint256' },
+]
+
+export const Domain = (chainId: number) => {
+    return {
+        name: EIP712_DOMAIN_NAME,
+        version: EIP712_DOMAIN_VERSION,
+        chainId,
+    }
+}
+
+export const CreatorTypedMessage = {
+    EIP712Domain,
+    ...CreatorConfigHashSigningTypes
+};
+
+//A conflict once updateDefinition is merged
+export const EnrSigningTypes = {
+    ENR: [{ name: "enr", type: "string" }],
+};
+
+export const OperatorConfigHashSigningTypes = {
+    OperatorConfigHash: [{ name: "operator_config_hash", type: "string" }],
+};
+
+export const OperatorTypedMessage = {
+    EIP712Domain,
+    ...OperatorConfigHashSigningTypes
+};
+
+export const ENRTypedMessage = {
+    EIP712Domain,
+    ...EnrSigningTypes
+};
+
+export const signCreatorConfigHashPayload = (
+    payload: { creator_config_hash: string },
+    chainId: number,
+): TypedMessage<typeof CreatorTypedMessage> => {
+    return {
+        types: CreatorTypedMessage,
+        primaryType: 'CreatorConfigHash',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+}
+
+export const signOperatorConfigHashPayload = (
+    payload: { operator_config_hash: string },
+    chainId: number,
+): TypedMessage<typeof OperatorTypedMessage> => {
+    return {
+        types: OperatorTypedMessage,
+        primaryType: 'OperatorConfigHash',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+}
+
+export const signEnrPayload = (
+    payload: { enr: string },
+    chainId: number,
+): TypedMessage<typeof ENRTypedMessage> => {
+    return {
+        types: ENRTypedMessage,
+        primaryType: 'ENR',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+}
+
+
+export const dkg_algorithm = "default";
+
+export const config_version = "v1.7.0";
+
+export const SDK_VERSION = "1.0.7";
+
+export const DOMAIN_APPLICATION_BUILDER = '00000001';
+export const DOMAIN_DEPOSIT = '03000000';
+export const GENESIS_VALIDATOR_ROOT =
+    '0000000000000000000000000000000000000000000000000000000000000000';
+
+// Flow used to create defintion
+export enum DefinitionFlow {
+    Group = 'LP-Group',
+    Solo = 'LP-Solo',
+    Charon = 'Charon-Command',
+
+}
+
+export const DEFAULT_BASE_URL = "https://api.obol.tech";
+export const DEFAULT_CHAIN_ID = 1;

package/src/errors.ts

@@ -0,0 +1,11 @@
+export class ConflictError extends Error {
+    name = 'ConflictError'
+  
+    constructor() {
+      super(
+        `This Cluster has been already posted.`,
+      )
+      Object.setPrototypeOf(this, ConflictError.prototype)
+    }
+  }
+  

package/src/hash.ts

@@ -0,0 +1,250 @@
+import {
+  ContainerType,
+  ByteVectorType,
+  UintNumberType,
+  ListCompositeType,
+  ByteListType,
+  fromHexString,
+} from '@chainsafe/ssz';
+import { UintNumberByteLen } from '@chainsafe/ssz/lib/type/uint.js';
+import { ValueOfFields } from '@chainsafe/ssz/lib/view/container.js';
+import { ClusterDefintion, ClusterLock } from './types.js';
+import { strToUint8Array } from './utils.js';
+
+//cluster-definition
+
+/**
+ * @param cluster The cluster configuration or the cluster definition
+ * @param configOnly a boolean to indicate config hash or definition hash
+ * @returns The config hash or the definition hash in of the corresponding cluster
+ */
+export const clusterConfigOrDefinitionHash = (
+  cluster: ClusterDefintion,
+  configOnly: boolean,
+): string => {
+
+  const definitionType = clusterDefinitionContainerType(configOnly);
+  const val = hashClusterDefinition(cluster, configOnly);
+  return (
+    '0x' + Buffer.from(definitionType.hashTreeRoot(val).buffer).toString('hex')
+  );
+};
+
+export const hashClusterDefinition = (
+  cluster: ClusterDefintion,
+  configOnly: boolean,
+): ValueOfFields<DefinitionFields> => {
+  const definitionType = clusterDefinitionContainerType(configOnly);
+
+  const val = definitionType.defaultValue();
+
+  //order should be same as charon https://github.com/ObolNetwork/charon/blob/d00b31e6465a260a43ce40f15c47fb5a5b009042/cluster/ssz.go#L285
+  val.uuid = strToUint8Array(cluster.uuid);
+  val.name = strToUint8Array(cluster.name);
+  val.version = strToUint8Array(cluster.version);
+  val.timestamp = strToUint8Array(cluster.timestamp);
+  val.num_validators = cluster.num_validators;
+  val.threshold = cluster.threshold;
+  val.dkg_algorithm = strToUint8Array(cluster.dkg_algorithm);
+  val.fork_version = fromHexString(cluster.fork_version);
+  val.operators = cluster.operators.map((operator) => {
+    return configOnly
+      ? { address: fromHexString(operator.address) }
+      : {
+        address: fromHexString(operator.address),
+        enr: strToUint8Array(operator.enr as string),
+        config_signature: fromHexString(operator.config_signature as string),
+        enr_signature: fromHexString(operator.enr_signature as string),
+      };
+  });
+  val.creator = configOnly
+    ? { address: fromHexString(cluster.creator.address) }
+    : {
+      address: fromHexString(cluster.creator.address),
+      config_signature: fromHexString(cluster.creator.config_signature as string),
+    };
+  val.validators = cluster.validators.map((validator: { fee_recipient_address: string; withdrawal_address: string; }) => {
+    return {
+      fee_recipient_address: fromHexString(validator.fee_recipient_address),
+      withdrawal_address: fromHexString(validator.withdrawal_address),
+    };
+  });
+
+  if (!configOnly) {
+    val.config_hash = fromHexString(cluster.config_hash);
+  }
+  return val;
+};
+
+const operatorAddressWrapperType = new ContainerType({
+  address: new ByteVectorType(20),
+});
+
+const creatorAddressWrapperType = new ContainerType({
+  address: new ByteVectorType(20),
+});
+
+export const operatorContainerType = new ContainerType({
+  address: new ByteVectorType(20),
+  enr: new ByteListType(1024), // This needs to be dynamic, since ENRs do not have a fixed length.
+  config_signature: new ByteVectorType(65),
+  enr_signature: new ByteVectorType(65),
+});
+
+export const creatorContainerType = new ContainerType({
+  address: new ByteVectorType(20),
+  config_signature: new ByteVectorType(65),
+});
+
+export const validatorsContainerType = new ContainerType({
+  fee_recipient_address: new ByteVectorType(20),
+  withdrawal_address: new ByteVectorType(20),
+});
+
+const newCreatorContainerType = (configOnly: boolean) => {
+  return configOnly ? creatorAddressWrapperType : creatorContainerType;
+};
+
+const newOperatorContainerType = (configOnly: boolean) => {
+  return configOnly ? operatorAddressWrapperType : operatorContainerType;
+};
+
+type DefinitionFields = {
+  uuid: ByteListType;
+  name: ByteListType;
+  version: ByteListType;
+  timestamp: ByteListType;
+  num_validators: UintNumberType;
+  threshold: UintNumberType;
+  dkg_algorithm: ByteListType;
+  fork_version: ByteVectorType;
+  operators: ListCompositeType<
+    typeof operatorContainerType | typeof operatorAddressWrapperType
+  >;
+  creator: typeof creatorContainerType | typeof creatorAddressWrapperType;
+  validators: ListCompositeType<typeof validatorsContainerType>;
+  config_hash?: ByteVectorType;
+};
+
+export type DefinitionContainerType =
+  ContainerType<DefinitionFields>;
+
+/**
+ * @param configOnly a boolean to indicate config hash or definition hash
+ * @returns SSZ Containerized type of cluster definition
+ */
+export const clusterDefinitionContainerType = (
+  configOnly: boolean,
+): DefinitionContainerType => {
+  let returnedContainerType: DefinitionFields = {
+    uuid: new ByteListType(64),
+    name: new ByteListType(256),
+    version: new ByteListType(16),
+    timestamp: new ByteListType(32),
+    num_validators: new UintNumberType(8 as UintNumberByteLen),
+    threshold: new UintNumberType(8 as UintNumberByteLen),
+    dkg_algorithm: new ByteListType(32),
+    fork_version: new ByteVectorType(4),
+    operators: new ListCompositeType(newOperatorContainerType(configOnly), 256),
+    creator: newCreatorContainerType(configOnly),
+    validators: new ListCompositeType(validatorsContainerType, 65536),
+  };
+
+  if (!configOnly) {
+    returnedContainerType = {
+      ...returnedContainerType,
+      config_hash: new ByteVectorType(32),
+    };
+  }
+
+  return new ContainerType(returnedContainerType);
+};
+
+//cluster-lock
+
+/**
+ * @param cluster The published cluster lock 
+ * @returns The lock hash in of the corresponding cluster
+ */
+export const clusterLockHash = (cluster: ClusterLock): string => {
+  const lockType = clusterLockContainerType();
+
+  const val = lockType.defaultValue();
+
+  //Check if we can replace with definition_hash 
+  val.cluster_definition = hashClusterDefinition(
+    cluster.cluster_definition,
+    false,
+  );
+  val.distributed_validators = cluster.distributed_validators.map(dVaidator => {
+    return {
+      distributed_public_key: fromHexString(dVaidator.distributed_public_key),
+      public_shares: dVaidator.public_shares.map(publicShare =>
+        fromHexString(publicShare),
+      ),
+      deposit_data: {
+        pubkey: fromHexString(dVaidator.deposit_data.pubkey as string),
+        withdrawal_credentials: fromHexString(
+          dVaidator.deposit_data.withdrawal_credentials as string
+        ),
+        amount: parseInt(dVaidator.deposit_data.amount as string),
+        signature: fromHexString(dVaidator.deposit_data.signature as string),
+      },
+      builder_registration: {
+        message: {
+          fee_recipient: fromHexString(
+            dVaidator.builder_registration.message.fee_recipient,
+          ),
+          gas_limit: dVaidator.builder_registration.message.gas_limit,
+          timestamp: dVaidator.builder_registration.message.timestamp,
+          pubkey: fromHexString(dVaidator.builder_registration.message.pubkey),
+        },
+        signature: fromHexString(dVaidator.builder_registration.signature),
+      },
+    };
+  });
+
+  return '0x' + Buffer.from(lockType.hashTreeRoot(val).buffer).toString('hex');
+};
+
+const depositDataContainer = new ContainerType({
+  pubkey: new ByteVectorType(48),
+  withdrawal_credentials: new ByteVectorType(32),
+  amount: new UintNumberType(8 as UintNumberByteLen),
+  signature: new ByteVectorType(96),
+});
+
+
+const builderRegistrationMessageContainer = new ContainerType({
+  fee_recipient: new ByteVectorType(20),
+  gas_limit: new UintNumberType(8 as UintNumberByteLen),
+  timestamp: new UintNumberType(8 as UintNumberByteLen),
+  pubkey: new ByteVectorType(48),
+});
+
+const builderRegistrationContainer = new ContainerType({
+  message: builderRegistrationMessageContainer,
+  signature: new ByteVectorType(96),
+});
+
+const dvContainerType = new ContainerType({
+  distributed_public_key: new ByteVectorType(48),
+  public_shares: new ListCompositeType(new ByteVectorType(48), 256),
+  deposit_data: depositDataContainer,
+  builder_registration: builderRegistrationContainer,
+});
+
+type LockContainerType = ContainerType<{
+  cluster_definition: DefinitionContainerType;
+  distributed_validators: ListCompositeType<typeof dvContainerType>;
+}>;
+
+/**
+ * @returns SSZ Containerized type of cluster lock
+ */
+const clusterLockContainerType = (): LockContainerType => {
+  return new ContainerType({
+    cluster_definition: clusterDefinitionContainerType(false),
+    distributed_validators: new ListCompositeType(dvContainerType, 65536),
+  });
+};

package/src/index.ts

@@ -0,0 +1,160 @@
+import { Signer } from "ethers";
+import { v4 as uuidv4 } from "uuid";
+import { Base } from './base.js';
+import { CONFLICT_ERROR_MSG, CreatorConfigHashSigningTypes, Domain, dkg_algorithm, config_version, OperatorConfigHashSigningTypes, EnrSigningTypes } from './constants.js';
+import { ConflictError } from './errors.js';
+import { ClusterDefintion, ClusterLock, ClusterPayload, OperatorPayload } from './types.js';
+import { clusterConfigOrDefinitionHash } from './hash.js';
+import { validatePayload } from './ajv.js';
+import { definitionSchema, operatorPayloadSchema } from './schema.js';
+export * from "./types.js";
+export * from "./services.js";
+
+
+/**
+ * Obol sdk Client can be used for creating, managing and activating distributed validators.
+ */
+export class Client extends Base {
+  private signer: Signer | undefined;
+
+  /**
+   * @param config - Client configurations
+   * @param config.baseUrl - obol-api url
+   * @param config.chainId - Blockchain network ID
+   * @param signer - ethersJS Signer 
+   * @returns Obol-SDK Client instance
+   * 
+   * An example of how to instantiate obol-sdk Client:
+   * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L29)
+   */
+  constructor(config: { baseUrl?: string | undefined; chainId?: number | undefined }, signer?: Signer) {
+
+    super(config)
+    this.signer = signer
+  }
+
+  /**
+   * Creates a cluster definition which contains cluster configuration.
+   * @param {ClusterPayload} newCluster - The new unique cluster.
+   * @returns {Promise<string>} config_hash.
+   * @throws On duplicate entries, missing or wrong cluster keys.
+   * 
+   * An example of how to use createClusterDefinition:
+   * [createObolCluster](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+   */
+  async createClusterDefinition(newCluster: ClusterPayload): Promise<string> {
+    if (!this.signer) throw "Signer is required in createClusterDefinition"
+
+    validatePayload(newCluster, definitionSchema);
+
+    const clusterConfig: Partial<ClusterDefintion> = {
+      ...newCluster,
+      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
+    }
+
+    try {
+      const address = await this.signer.getAddress();
+
+      clusterConfig.creator = { address };
+      clusterConfig.config_hash = clusterConfigOrDefinitionHash(clusterConfig as ClusterDefintion, true);
+
+      const creatorConfigSignature = await this.signer.signTypedData(Domain(this.chainId), CreatorConfigHashSigningTypes, { creator_config_hash: clusterConfig.config_hash });
+
+      const clusterDefinition: ClusterDefintion = await this.request(`/dv`, {
+        method: 'POST',
+        body: JSON.stringify(clusterConfig),
+        headers: {
+          Authorization: `Bearer ${creatorConfigSignature}`,
+          "fork-version": this.fork_version,
+        }
+
+      });
+      return clusterDefinition?.config_hash;
+    } catch (err: any) {
+      if (err?.message == CONFLICT_ERROR_MSG)
+        throw new ConflictError();
+      throw err;
+    }
+  }
+
+  /**
+  * Approves joining a cluster with specific configuration.
+  * @param {OperatorPayload} operatorPayload - The operator data including signatures.
+  * @param {string} configHash - The config hash of the cluster which the operator confirms joining to.
+  * @returns {Promise<ClusterDefintion>} The cluster definition.
+  * @throws On unauthorized, duplicate entries, missing keys, not found cluster or invalid data.
+  * 
+  * An example of how to use acceptClusterDefinition:
+  * [acceptClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+  */
+  async acceptClusterDefinition(operatorPayload: OperatorPayload, configHash: string): Promise<ClusterDefintion> {
+    if (!this.signer) throw "Signer is required in acceptClusterDefinition"
+
+    validatePayload(operatorPayload, operatorPayloadSchema);
+
+    try {
+      const address = await this.signer.getAddress();
+
+      const operatorConfigSignature = await this.signer.signTypedData(Domain(this.chainId), OperatorConfigHashSigningTypes, { operator_config_hash: configHash });
+      const operatorENRSignature = await this.signer.signTypedData(Domain(this.chainId), EnrSigningTypes, { enr: operatorPayload.enr });
+
+      const operatorData: OperatorPayload = {
+        ...operatorPayload,
+        address,
+        enr_signature: operatorENRSignature,
+        fork_version: this.fork_version
+      }
+      const clusterDefinition: ClusterDefintion = await this.request(`/dv/${configHash}`, {
+        method: 'PUT',
+        body: JSON.stringify(operatorData),
+        headers: {
+          Authorization: `Bearer ${operatorConfigSignature}`,
+        }
+
+      });
+      return clusterDefinition;
+    } catch (err: any) {
+      throw err;
+    }
+  }
+
+
+  /** 
+   * @param configHash - The configuration hash returned in createClusterDefinition
+   * @returns {Promise<ClusterDefintion>} The  cluster definition for config hash
+   * @throws On not found config hash.
+   * 
+   * An example of how to use getClusterDefinition:
+   * [getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+   */
+  async getClusterDefinition(configHash: string): Promise<ClusterDefintion> {
+      const clusterDefinition: ClusterDefintion = await this.request(`/dv/${configHash}`, {
+        method: 'GET',
+      })
+
+      return clusterDefinition
+  }
+
+  /** 
+   * @param configHash - The configuration hash in cluster-definition 
+   * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
+   * @throws On not found cluster definition or lock.
+   * 
+   * An example of how to use getClusterLock:
+   * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+   */
+  async getClusterLock(configHash: string): Promise<ClusterLock> {
+
+      const lock: ClusterLock = await this.request(`/lock/configHash/${configHash}`, {
+        method: 'GET',
+      })
+      return lock
+  }
+}
+

package/src/schema.ts

@@ -0,0 +1,70 @@
+export const operatorPayloadSchema = {
+  type: "object",
+  properties: {
+    version: {
+      type: "string"
+    },
+    enr: {
+      type: "string"
+    },
+  },
+  required: [
+    "version",
+    "enr",
+  ]
+}
+
+export const definitionSchema = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string"
+    },
+    operators: {
+      type: "array",
+      minItems: 4,
+      uniqueItems: true,
+      items: {
+        type: "object",
+        properties: {
+          address: {
+            type: "string",
+            minLength: 42,
+            maxLength: 42
+          }
+        },
+        required: [
+          "address"
+        ]
+      }
+    },
+    validators: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        properties: {
+          fee_recipient_address: {
+            type: "string",
+            minLength: 42,
+            maxLength: 42
+          },
+          withdrawal_address: {
+            type: "string",
+            minLength: 42,
+            maxLength: 42
+          }
+        },
+        required: [
+          "fee_recipient_address",
+          "withdrawal_address"
+        ]
+      }
+    }
+  },
+  required: [
+    "name",
+    "operators",
+    "validators"
+  ]
+}

package/src/services.ts

@@ -0,0 +1,20 @@
+import { ClusterLock } from "./types.js";
+import { isValidClusterLock } from "./verify.js";
+
+/** 
+ * Verifies Cluster Lock's validity.
+ * @param lock - cluster lock
+ * @returns {Promise<{ result: boolean }> } boolean result to indicate if lock is valid  
+ * @throws on missing keys or values.
+ * 
+ * An example of how to use validateClusterLock:
+ * [validateClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+ */
+export const validateClusterLock = async (lock: ClusterLock): Promise<boolean> => {
+    try {
+        const isLockValid = await isValidClusterLock(lock);
+        return isLockValid
+    } catch (err: any) {
+        throw err;
+    }
+}