@obolnetwork/obol-sdk 1.0.14 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "A package for creating Distributed Validators using the Obol API.",
   "bugs": {
     "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -42,6 +42,7 @@
     "@chainsafe/discv5": "^0.5.1",
     "@chainsafe/ssz": "^0.14.0",
     "@metamask/eth-sig-util": "^7.0.1",
+    "@types/pdf-parse": "^1.1.4",
     "ajv": "^8.12.0",
     "cross-fetch": "^3.1.5",
     "elliptic": "^6.5.4",
@@ -49,9 +50,9 @@
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-n": "^16.6.2",
     "eslint-plugin-promise": "^6.1.1",
-    "ethers": "^6.4.0",
+    "ethers": "6.4.0",
     "nock": "^13.5.3",
-    "release-it": "^17.1.1",
+    "pdf-parse": "^1.1.1",
     "semver": "^7.6.0",
     "typescript-eslint": "^7.1.0",
     "uuid": "^9.0.0"
@@ -61,11 +62,13 @@
     "@types/elliptic": "^6.4.18",
     "@types/jest": "^28.1.8",
     "@types/node": "^20.2.5",
+    "@types/semver": "^7.5.8",
     "@types/uuid": "^9.0.1",
     "eslint": "^8.57.0",
     "jest": "^28.1.3",
     "msw": "^2.2.1",
     "npm-run-all": "^4.1.5",
+    "release-it": "^17.2.1",
     "ts-jest": "^28.0.8",
     "tsup": "^6.7.0",
     "typedoc": "^0.25.7",

package/src/base.ts

@@ -39,9 +39,11 @@ export abstract class Base {
       const response = await fetch(url, config)
       if (response.ok) {
         return await response.json()
+      } else {
+        const errorResponse = await response.json()
+        throw errorResponse
       }
-      throw new Error(response.statusText)
-    } catch (e) {
+    } catch (e: any) {
       throw e
     }
   }

package/src/constants.ts

@@ -9,6 +9,12 @@ export const EIP712_DOMAIN_VERSION = '1'
 export const CreatorConfigHashSigningTypes = {
   CreatorConfigHash: [{ name: 'creator_config_hash', type: 'string' }],
 }
+export const TermsAndConditionsSigningTypes = {
+  TermsAndConditions: [
+    { name: 'terms_and_conditions_hash', type: 'string' },
+    { name: 'version', type: 'uint256' },
+  ]
+}
 
 const EIP712Domain = [
   { name: 'name', type: 'string' },
@@ -16,12 +22,15 @@ const EIP712Domain = [
   { name: 'chainId', type: 'uint256' },
 ]
 
-export const Domain = (chainId: number): TypedDataDomain => {
-  return {
+export const Domain = (chainId?: number): TypedDataDomain => {
+  const typeDataDomain: any = {
     name: EIP712_DOMAIN_NAME,
     version: EIP712_DOMAIN_VERSION,
-    chainId,
   }
+  if (chainId) {
+    typeDataDomain.chainId = chainId
+  }
+  return typeDataDomain
 }
 
 export const CreatorTypedMessage = {
@@ -107,7 +116,7 @@ export const DOMAIN_DEPOSIT = '03000000'
 export const GENESIS_VALIDATOR_ROOT =
   '0000000000000000000000000000000000000000000000000000000000000000'
 
-// Flow used to create defintion
+// Flow used to create definition
 export enum DefinitionFlow {
   Group = 'LP-Group',
   Solo = 'LP-Solo',
@@ -118,3 +127,6 @@ export const DEFAULT_BASE_URL = 'https://api.obol.tech'
 export const DEFAULT_CHAIN_ID = 17000
 
 export const ETHER_TO_GWEI = 10 ** 9
+
+export const TERMS_AND_CONDITIONS_VERSION = 1
+export const TERMS_AND_CONDITIONS_URL = (TERMS_AND_CONDITIONS_VERSION === 1) ? 'https://obol.tech/terms.pdf' : `https://obol.tech/${TERMS_AND_CONDITIONS_VERSION as number}/terms.pdf`

package/src/index.ts

@@ -9,10 +9,12 @@ import {
   CONFIG_VERSION,
   OperatorConfigHashSigningTypes,
   EnrSigningTypes,
+  TERMS_AND_CONDITIONS_VERSION,
+  TermsAndConditionsSigningTypes,
 } from './constants.js'
 import { ConflictError } from './errors.js'
 import {
-  type ClusterDefintion,
+  type ClusterDefinition,
   type ClusterLock,
   type ClusterPayload,
   type OperatorPayload,
@@ -20,6 +22,7 @@ import {
 import { clusterConfigOrDefinitionHash } from './verification/common.js'
 import { validatePayload } from './ajv.js'
 import { definitionSchema, operatorPayloadSchema } from './schema.js'
+import { hashTermsAndConditions } from './verification/termsAndConditions.js'
 export * from './types.js'
 export * from './services.js'
 
@@ -47,6 +50,51 @@ export class Client extends Base {
     this.signer = signer
   }
 
+  /**
+   * Accepts Obol terms and conditions to be able to create or update data.
+   * @returns {Promise<string>} terms and conditions acceptance success message.
+   * @throws On unverified signature or wrong hash.
+   *
+   * An example of how to use acceptObolLatestTermsAndConditions:
+   * [acceptObolLatestTermsAndConditions](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L44)
+   */
+  async acceptObolLatestTermsAndConditions (): Promise<string> {
+    if (!this.signer) { throw new Error('Signer is required in acceptObolTermsAndConditions') }
+
+    try {
+      const termsAndConditionsHash = await hashTermsAndConditions()
+      const address = await this.signer.getAddress()
+      const termsAndConditionsPayload = {
+        address,
+        version: TERMS_AND_CONDITIONS_VERSION,
+        terms_and_conditions_hash: termsAndConditionsHash
+      }
+
+      const termsAndConditionsSignature = await this.signer.signTypedData(
+        Domain(),
+        TermsAndConditionsSigningTypes,
+        {
+          terms_and_conditions_hash: termsAndConditionsHash,
+          version: TERMS_AND_CONDITIONS_VERSION,
+        },
+      )
+
+      const termsAndConditionsResponse: { message: string, success: boolean } = await this.request('/termsAndConditions', {
+        method: 'POST',
+        body: JSON.stringify(termsAndConditionsPayload),
+        headers: {
+          Authorization: `Bearer ${termsAndConditionsSignature}`,
+        },
+      })
+      return termsAndConditionsResponse?.message
+    } catch (err: any) {
+      if (err?.message === CONFLICT_ERROR_MSG) {
+        throw new ConflictError()
+      }
+      throw err
+    }
+  }
+
   /**
    * Creates a cluster definition which contains cluster configuration.
    * @param {ClusterPayload} newCluster - The new unique cluster.
@@ -54,14 +102,14 @@ export class Client extends Base {
    * @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)
+   * [createObolCluster](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L59)
    */
   async createClusterDefinition (newCluster: ClusterPayload): Promise<string> {
     if (!this.signer) { throw new Error('Signer is required in createClusterDefinition') }
 
     validatePayload(newCluster, definitionSchema)
 
-    const clusterConfig: Partial<ClusterDefintion> = {
+    const clusterConfig: Partial<ClusterDefinition> = {
       ...newCluster,
       fork_version: this.fork_version,
       dkg_algorithm: DKG_ALGORITHM,
@@ -77,7 +125,7 @@ export class Client extends Base {
 
       clusterConfig.creator = { address }
       clusterConfig.config_hash = clusterConfigOrDefinitionHash(
-        clusterConfig as ClusterDefintion,
+        clusterConfig as ClusterDefinition,
         true,
       )
 
@@ -87,7 +135,7 @@ export class Client extends Base {
         { creator_config_hash: clusterConfig.config_hash },
       )
 
-      const clusterDefinition: ClusterDefintion = await this.request('/dv', {
+      const clusterDefinition: ClusterDefinition = await this.request('/v1/definition', {
         method: 'POST',
         body: JSON.stringify(clusterConfig),
         headers: {
@@ -108,16 +156,16 @@ export class Client extends Base {
    * 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.
+   * @returns {Promise<ClusterDefinition>} 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)
+   * [acceptClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L106)
    */
   async acceptClusterDefinition (
     operatorPayload: OperatorPayload,
     configHash: string,
-  ): Promise<ClusterDefintion> {
+  ): Promise<ClusterDefinition> {
     if (!this.signer) { throw new Error('Signer is required in acceptClusterDefinition') }
 
     validatePayload(operatorPayload, operatorPayloadSchema)
@@ -142,8 +190,8 @@ export class Client extends Base {
         enr_signature: operatorENRSignature,
         fork_version: this.fork_version,
       }
-      const clusterDefinition: ClusterDefintion = await this.request(
-        `/dv/${configHash}`,
+      const clusterDefinition: ClusterDefinition = await this.request(
+        `/v1/definition/${configHash}`,
         {
           method: 'PUT',
           body: JSON.stringify(operatorData),
@@ -160,14 +208,14 @@ export class Client extends Base {
 
   /**
    * @param configHash - The configuration hash returned in createClusterDefinition
-   * @returns {Promise<ClusterDefintion>} The  cluster definition for config hash
+   * @returns {Promise<ClusterDefinition>} 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)
+   * [getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L74)
    */
-  async getClusterDefinition (configHash: string): Promise<ClusterDefintion> {
-    const clusterDefinition: ClusterDefintion = await this.request(
+  async getClusterDefinition (configHash: string): Promise<ClusterDefinition> {
+    const clusterDefinition: ClusterDefinition = await this.request(
       `/dv/${configHash}`,
       {
         method: 'GET',
@@ -183,7 +231,7 @@ export class Client extends Base {
    * @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)
+   * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L89)
    */
   async getClusterLock (configHash: string): Promise<ClusterLock> {
     const lock: ClusterLock = await this.request(

package/src/services.ts

@@ -8,7 +8,7 @@ import { isValidClusterLock } from './verification/common.js'
  * @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)
+ * [validateClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L127)
  */
 export const validateClusterLock = async (
   lock: ClusterLock,

package/src/types.ts

@@ -85,7 +85,7 @@ export interface ClusterPayload {
 /**
  * Cluster definition data needed for dkg
  */
-export interface ClusterDefintion extends ClusterPayload {
+export interface ClusterDefinition extends ClusterPayload {
   /** The creator of the cluster. */
   creator: ClusterCreator
 
@@ -193,7 +193,7 @@ export interface DistributedValidator {
  */
 export interface ClusterLock {
   /** The cluster definition. */
-  cluster_definition: ClusterDefintion
+  cluster_definition: ClusterDefinition
 
   /** The cluster distributed validators. */
   distributed_validators: DistributedValidator[]

package/src/utils.ts

@@ -1,5 +1,5 @@
 import { DefinitionFlow } from './constants'
-import { type ClusterDefintion } from './types'
+import { type ClusterDefinition } from './types'
 
 export const hexWithout0x = (hex: string): string => {
   return hex.slice(2, hex.length)
@@ -10,7 +10,7 @@ export const strToUint8Array = (str: string): Uint8Array => {
 }
 
 export const definitionFlow = (
-  clusterDefinition: ClusterDefintion,
+  clusterDefinition: ClusterDefinition,
 ): DefinitionFlow | null => {
   if (
     clusterDefinition.creator.address &&

package/src/verification/common.ts

@@ -6,7 +6,7 @@ import {
     init,
 } from '@chainsafe/bls'
 
-import { FORK_MAPPING, type ClusterDefintion, type ClusterLock, type DepositData, type BuilderRegistrationMessage, type DistributedValidator } from '../types.js'
+import { FORK_MAPPING, type ClusterDefinition, type ClusterLock, type DepositData, type BuilderRegistrationMessage, type DistributedValidator } from '../types.js'
 import * as semver from 'semver'
 import { clusterDefinitionContainerTypeV1X6, hashClusterDefinitionV1X6, hashClusterLockV1X6, verifyDVV1X6 } from './v1.6.0.js'
 import { clusterDefinitionContainerTypeV1X7, hashClusterDefinitionV1X7, hashClusterLockV1X7, verifyDVV1X7 } from './v1.7.0.js'
@@ -26,7 +26,7 @@ import { clusterDefinitionContainerTypeV1X8, hashClusterDefinitionV1X8, hashClus
  * @returns The config hash or the definition hash in of the corresponding cluster
  */
 export const clusterConfigOrDefinitionHash = (
-    cluster: ClusterDefintion,
+    cluster: ClusterDefinition,
     configOnly: boolean,
 ): string => {
     let definitionType, val
@@ -142,7 +142,7 @@ const getEnrSigner = (
 }
 
 const verifyDefinitionSignatures = (
-    clusterDefinition: ClusterDefintion,
+    clusterDefinition: ClusterDefinition,
     definitionType: DefinitionFlow,
 ): boolean => {
     if (definitionType === DefinitionFlow.Charon) {

package/src/verification/termsAndConditions.ts

@@ -0,0 +1,30 @@
+import pdf from 'pdf-parse'
+import { ByteListType, ContainerType } from '@chainsafe/ssz'
+import { TERMS_AND_CONDITIONS_URL } from '../constants'
+import { strToUint8Array } from '../utils'
+
+export const hashTermsAndConditions = async (): Promise<string | null> => {
+  try {
+    // read the pdf
+    const response = await fetch(TERMS_AND_CONDITIONS_URL)
+    const pdfBuffarrayBuffer = await response.arrayBuffer()
+    const pdfBuffer = Buffer.from(pdfBuffarrayBuffer)
+    const data = await pdf(pdfBuffer)
+
+    // ssz hash
+    const termsType = new ContainerType({
+      terms_and_conditions_hash: new ByteListType(Number.MAX_SAFE_INTEGER),
+    })
+
+    const termsHasVal = termsType.defaultValue()
+
+    termsHasVal.terms_and_conditions_hash = strToUint8Array(data?.text)
+
+    return (
+      '0x' +
+      Buffer.from(termsType.hashTreeRoot(termsHasVal).buffer).toString('hex')
+    )
+  } catch (err) {
+    return null
+  }
+}

package/src/verification/v1.6.0.ts

@@ -3,7 +3,7 @@ import { strToUint8Array } from '../utils'
 import { type creatorAddressWrapperType, type creatorContainerType, newCreatorContainerType, newOperatorContainerType, type operatorAddressWrapperType, type operatorContainerType, validatorsContainerType } from './sszTypes'
 import { ByteListType, ByteVectorType, ContainerType, ListCompositeType, fromHexString } from '@chainsafe/ssz'
 import { type ValueOfFields } from '@chainsafe/ssz/lib/view/container'
-import { type ClusterDefintion, type ClusterLock, type DepositData } from '../types'
+import { type ClusterDefinition, type ClusterLock, type DepositData } from '../types'
 import { verifyDepositData } from './common'
 import { aggregateSignatures, verifyAggregate, verifyMultiple } from '@chainsafe/bls'
 
@@ -61,7 +61,7 @@ export const clusterDefinitionContainerTypeV1X6 = (
 }
 
 export const hashClusterDefinitionV1X6 = (
-    cluster: ClusterDefintion,
+    cluster: ClusterDefinition,
     configOnly: boolean,
 ): ValueOfFields<DefinitionFieldsV1X6> => {
     const definitionType = clusterDefinitionContainerTypeV1X6(configOnly)

package/src/verification/v1.7.0.ts

@@ -3,7 +3,7 @@ import { strToUint8Array } from '../utils'
 import { builderRegistrationContainer, type creatorAddressWrapperType, type creatorContainerType, depositDataContainer, newCreatorContainerType, newOperatorContainerType, type operatorAddressWrapperType, type operatorContainerType, validatorsContainerType } from './sszTypes'
 import { ByteListType, ByteVectorType, ContainerType, ListCompositeType, fromHexString } from '@chainsafe/ssz'
 import { type ValueOfFields } from '@chainsafe/ssz/lib/view/container'
-import { type ClusterDefintion, type ClusterLock, type DepositData } from '../types'
+import { type ClusterDefinition, type ClusterLock, type DepositData } from '../types'
 import { verifyBuilderRegistration, verifyDepositData, verifyNodeSignatures } from './common'
 import { aggregateSignatures, verifyAggregate, verifyMultiple } from '@chainsafe/bls'
 
@@ -61,7 +61,7 @@ export const clusterDefinitionContainerTypeV1X7 = (
 }
 
 export const hashClusterDefinitionV1X7 = (
-    cluster: ClusterDefintion,
+    cluster: ClusterDefinition,
     configOnly: boolean,
 ): ValueOfFields<DefinitionFieldsV1X7> => {
     const definitionType = clusterDefinitionContainerTypeV1X7(configOnly)

package/src/verification/v1.8.0.ts

@@ -3,7 +3,7 @@ import { strToUint8Array } from '../utils'
 import { builderRegistrationContainer, type creatorAddressWrapperType, type creatorContainerType, depositDataContainer, newCreatorContainerType, newOperatorContainerType, type operatorAddressWrapperType, type operatorContainerType, validatorsContainerType } from './sszTypes'
 import { ByteListType, ByteVectorType, ContainerType, ListBasicType, ListCompositeType, fromHexString } from '@chainsafe/ssz'
 import { type ValueOfFields } from '@chainsafe/ssz/lib/view/container'
-import { type ClusterDefintion, type ClusterLock, type DepositData } from '../types'
+import { type ClusterDefinition, type ClusterLock, type DepositData } from '../types'
 import { verifyBuilderRegistration, verifyDepositData, verifyNodeSignatures } from './common'
 import { aggregateSignatures, verifyAggregate, verifyMultiple } from '@chainsafe/bls'
 
@@ -65,7 +65,7 @@ export const clusterDefinitionContainerTypeV1X8 = (
 }
 
 export const hashClusterDefinitionV1X8 = (
-    cluster: ClusterDefintion,
+    cluster: ClusterDefinition,
     configOnly: boolean,
 ): ValueOfFields<DefinitionFieldsV1X8> => {
     const definitionType = clusterDefinitionContainerTypeV1X8(configOnly)
@@ -205,7 +205,7 @@ export const verifyDVV1X8 = (clusterLock: ClusterLock): boolean => {
 
         // Deposit Data Verification
         for (let j = 0; j < (validator.partial_deposit_data as DepositData[]).length; j++) {
-            const depositData = (validator.partial_deposit_data as DepositData[])[i]
+            const depositData = (validator.partial_deposit_data as DepositData[])[j]
             const { isValidDepositData, depositDataMsg } = verifyDepositData(
                 distributedPublicKey,
                 depositData as Partial<DepositData>,