@obolnetwork/obol-sdk 1.0.8 → 1.0.11

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;
+    }
+}

package/src/types.ts

@@ -0,0 +1,211 @@
+/**
+ * Permitted ChainID's
+ */
+export enum FORK_MAPPING {
+
+  /** Mainnet. */
+  "0x00000000" = 1,
+
+  /** Goerli/Prater. */
+  "0x00001020" = 5,
+
+  /** Gnosis Chain. */
+  "0x00000064" = 100,
+
+  /** Holesky. */
+  "0x01017000" = 17000
+}
+
+/**
+ * Node operator data
+ */
+export type ClusterOperator = {
+
+  /** The operator address. */
+  address: string;
+
+  /** The operator ethereum node record. */
+  enr?: string;
+
+  /** The cluster fork_version. */
+  fork_version?: string;
+
+  /** The cluster version. */
+  version?: string;
+
+  /** The operator enr signature. */
+  enr_signature?: string;
+
+  /** The operator configuration signature. */
+  config_signature?: string;
+}
+
+/**
+ * A partial view of `ClusterOperator` with `enr` and `version` as required properties.
+ */
+export type OperatorPayload =  Partial<ClusterOperator> & Required<Pick<ClusterOperator, 'enr' | 'version'>>;
+
+/**
+ * Cluster creator data
+ */
+export type ClusterCreator = {
+
+  /** The creator address. */
+  address: string;
+  /** The cluster configuration signature. */
+  config_signature?: string;
+}
+
+/**
+ * Validator withdrawal configuration
+ */
+export type ClusterValidator = {
+
+  /** The validator fee recipient address. */
+  fee_recipient_address: string;
+
+  /** The validator reward address. */
+  withdrawal_address: string;
+}
+
+/**
+ * Cluster configuration
+ */
+export type ClusterPayload = {
+
+  /** The cluster name. */
+  name: string;
+
+  /** The cluster nodes operators addresses. */
+  operators: ClusterOperator[];
+
+  /** The clusters validators information. */
+  validators: ClusterValidator[];
+};
+
+/**
+ * Cluster definition data needed for dkg
+ */
+export interface ClusterDefintion extends ClusterPayload {
+
+  /** The creator of the cluster. */
+  creator: ClusterCreator;
+
+  /** The cluster configuration version. */
+  version: string;
+
+  /** The cluster dkg algorithm. */
+  dkg_algorithm: string;
+
+  /** The cluster fork version. */
+  fork_version: string;
+
+  /** The cluster uuid. */
+  uuid: string;
+
+  /** The cluster creation timestamp. */
+  timestamp: string;
+
+  /** The cluster configuration hash. */
+  config_hash: string;
+
+  /** The distributed validator threshold. */
+  threshold: number;
+
+  /** The number of distributed validators in the cluster. */
+  num_validators: number;
+
+  /** The hash of the cluster definition. */
+  definition_hash?: string;
+};
+
+/**
+ * Unsigned DV Builder Registration Message
+ */
+export type BuilderRegistrationMessage = {
+
+  /** The DV fee recipient. */
+  fee_recipient: string;
+
+  /** Default is 30000000. */
+  gas_limit: number;
+
+  /** Timestamp when generating cluster lock file. */
+  timestamp: number;
+
+  /** The public key of the DV. */
+  pubkey: string;
+}
+
+/**
+ * Pre-generated Signed Validator Builder Registration
+ */
+export type BuilderRegistration = {
+
+  /** Builder registration message. */
+  message: BuilderRegistrationMessage;
+
+  /** BLS signature of the builder registration message. */
+  signature: string;
+}
+
+/**
+ * Required deposit data for validator activation
+ */
+export type DepositData = {
+
+  /** The public key of the distributed validator. */
+  pubkey: string;
+
+  /** The 0x01 withdrawal address of the DV. */
+  withdrawal_credentials: string;
+
+  /** 32 ethers. */
+  amount: string;
+
+  /** A checksum for DepositData fields . */
+  deposit_data_root: string;
+
+  /** BLS signature of the deposit message. */
+  signature: string;
+}
+
+/**
+ * Required deposit data for validator activation
+ */
+export type DistributedValidator = {
+
+  /** The public key of the distributed validator. */
+  distributed_public_key: string;
+
+  /** The public key of the node distributed validator share. */
+  public_shares: string[];
+
+  /** The required deposit data for activating the DV. */
+  deposit_data: Partial<DepositData>;
+
+  /** pre-generated signed validator builder registration to be sent to builder network. */
+  builder_registration: BuilderRegistration;
+}
+
+/**
+ * Cluster Details after DKG is complete
+ */
+export type ClusterLock = {
+  
+  /** The cluster definition. */
+  cluster_definition: ClusterDefintion;
+
+  /** The cluster distributed validators. */
+  distributed_validators: DistributedValidator[];
+
+  /** The cluster bls signature aggregate. */
+  signature_aggregate: string;
+
+  /** The hash of the cluster lock. */
+  lock_hash: string;
+
+  /** Node Signature for the lock hash by the node secp256k1 key. */
+  node_signatures: string[];
+};
+

package/src/utils.ts

@@ -0,0 +1,7 @@
+export const hexWithout0x = (hex: string): string => {
+    return hex.slice(2, hex.length);
+};
+
+export const strToUint8Array = (str: string): Uint8Array => {
+    return new TextEncoder().encode(str);
+  };