Hanan/udate sdk docs (#322)

* update sdk docs to include validateClusterLock * revert some changes
ObolNetwork · Mar 8, 2024 · 41f31a2 · 41f31a2
1 parent 38bc231
commit 41f31a2
Show file tree

Hide file tree

Showing 23 changed files with 305 additions and 172 deletions.
diff --git a/docs/sdk/classes/Client.md b/docs/sdk/classes/Client.md
@@ -1,9 +1,4 @@
----
-description: The client object of the Obol SDK
-sidebar_position: 6
-sidebar_label: Client
----
-Obol SDK `Client` can be used for creating, managing and activating distributed validators.
+Obol sdk Client can be used for creating, managing and activating distributed validators.
 
 ## Extends
 
@@ -19,9 +14,9 @@ Obol SDK `Client` can be used for creating, managing and activating distributed
 
 | Parameter | Type | Description |
 | :------ | :------ | :------ |
-| `config` | `Object` |  |
-| `config.baseUrl`? | `string` | - |
-| `config.chainId`? | `number` | - |
+| `config` | `Object` | Client configurations |
+| `config.baseUrl`? | `string` | obol-api url |
+| `config.chainId`? | `number` | Blockchain network ID |
 | `signer`? | `Signer` | ethersJS Signer |
 
 #### Returns
@@ -39,16 +34,7 @@ An example of how to instantiate obol-sdk Client:
 
 #### Source
 
-index.ts:27
-
-## Properties
-
-| Property | Modifier | Type | Inherited from |
-| :------ | :------ | :------ | :------ |
-| `baseUrl` | `public` | `string` | `Base.baseUrl` |
-| `chainId` | `public` | `number` | `Base.chainId` |
-| `fork_version` | `public` | `string` | `Base.fork_version` |
-| `signer` | `private` | `undefined` \| `Signer` | - |
+index.ts:30
 
 ## Methods
 
@@ -62,7 +48,7 @@ Creates a cluster definition which contains cluster configuration.
 
 | Parameter | Type | Description |
 | :------ | :------ | :------ |
-| `newCluster` | [`ClusterPayload`](../interfaces/ClusterPayload.md) | The new unique cluster. |
+| `newCluster` | [`ClusterPayload`](../type-aliases/ClusterPayload.md) | The new unique cluster. |
 
 #### Returns
 
@@ -79,125 +65,94 @@ An example of how to use createClusterDefinition:
 
 #### Source
 
-index.ts:42
+index.ts:45
 
 ***
 
-### getClusterDefinition()
+### acceptClusterDefinition()
 
-> **getClusterDefinition**(`configHash`): `Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
+> **acceptClusterDefinition**(`operatorPayload`, `configHash`): `Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
+
+Approves joining a cluster with specific configuration.
 
 #### Parameters
 
-| Parameter | Type |
-| :------ | :------ |
-| `configHash` | `string` |
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `operatorPayload` | [`OperatorPayload`](../type-aliases/OperatorPayload.md) | The operator data including signatures. |
+| `configHash` | `string` | The config hash of the cluster which the operator confirms joining to. |
 
 #### Returns
 
 `Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
 
-The  cluster definition for config hash
+The cluster definition.
 
 #### Throws
 
-On not found config hash.
+On unauthorized, duplicate entries, missing keys, not found cluster or invalid data.
 
-An example of how to use getClusterDefinition:
-[getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+An example of how to use acceptClusterDefinition:
+[acceptClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
 
 #### Source
 
-index.ts:132
+index.ts:96
 
 ***
 
-### getClusterLock()
+### getClusterDefinition()
 
-> **getClusterLock**(`configHash`): `Promise`< [`ClusterLock`](../interfaces/ClusterLock.md) \>
+> **getClusterDefinition**(`configHash`): `Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
 
 #### Parameters
 
-| Parameter | Type |
-| :------ | :------ |
-| `configHash` | `string` |
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `configHash` | `string` | The configuration hash returned in createClusterDefinition |
 
 #### Returns
 
-`Promise`< [`ClusterLock`](../interfaces/ClusterLock.md) \>
+`Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
 
-The matched cluster details (lock) from DB
+The  cluster definition for config hash
 
 #### 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)
-
-#### Source
-
-index.ts:148
-
-***
-
-### request()
-
-> **`protected`** **request**<`T`\>(`endpoint`, `options`?): `Promise`< `T` \>
-
-#### Type parameters
-
-| Type parameter |
-| :------ |
-| `T` |
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `endpoint` | `string` |
-| `options`? | `RequestInit` |
-
-#### Returns
-
-`Promise`< `T` \>
-
-#### Inherited from
+On not found config hash.
 
-`Base.request`
+An example of how to use getClusterDefinition:
+[getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
 
 #### Source
 
-base.ts:23
+index.ts:136
 
 ***
 
-### updateClusterDefinition()
+### getClusterLock()
 
-> **updateClusterDefinition**(`operatorPayload`, `configHash`): `Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
-
-Approves joining a cluster with specific configuration.
+> **getClusterLock**(`configHash`): `Promise`< [`ClusterLock`](../type-aliases/ClusterLock.md) \>
 
 #### Parameters
 
 | Parameter | Type | Description |
 | :------ | :------ | :------ |
-| `operatorPayload` | [`OperatorPayload`](../type-aliases/OperatorPayload.md) | The operator data including signatures. |
-| `configHash` | `string` | The config hash of the cluster which the operator confirms joining to. |
+| `configHash` | `string` | The configuration hash in cluster-definition |
 
 #### Returns
 
-`Promise`< [`ClusterDefintion`](../interfaces/ClusterDefintion.md) \>
+`Promise`< [`ClusterLock`](../type-aliases/ClusterLock.md) \>
 
-The cluster definition.
+The matched cluster details (lock) from DB
 
 #### Throws
 
-On unauthorized, duplicate entries, missing keys, not found cluster or invalid data.
+On not found cluster definition or lock.
 
-An example of how to use updateClusterDefinition:
-[updateClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+An example of how to use getClusterLock:
+[getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
 
 #### Source
 
-index.ts:93
+index.ts:152
diff --git a/docs/sdk/classes/_category_.json b/docs/sdk/classes/_category_.json
diff --git a/docs/sdk/enumerations/FORK_MAPPING.md b/docs/sdk/enumerations/FORK_MAPPING.md
@@ -1,10 +1,10 @@
-Permitted `chainId`s for the [Client](../classes/Client.md) `config` constructor parameter. 
+Permitted ChainID's
 
 ## Enumeration Members
 
 | Enumeration Member | Value | Description |
 | :------ | :------ | :------ |
 | `0x00000000` | `1` | Mainnet. |
-| `0x00000064` | `100` | Gnosis Chain. |
 | `0x00001020` | `5` | Goerli/Prater. |
+| `0x00000064` | `100` | Gnosis Chain. |
 | `0x01017000` | `17000` | Holesky. |
diff --git a/docs/sdk/enumerations/_category_.json b/docs/sdk/enumerations/_category_.json
diff --git a/docs/sdk/functions/validateClusterLock.md b/docs/sdk/functions/validateClusterLock.md
@@ -0,0 +1,26 @@
+> **validateClusterLock**(`lock`): `Promise`< `boolean` \>
+
+Verifies Cluster Lock's validity.
+
+## Parameters
+
+| Parameter | Type | Description |
+| :------ | :------ | :------ |
+| `lock` | [`ClusterLock`](../type-aliases/ClusterLock.md) | cluster lock |
+
+## Returns
+
+`Promise`< `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)
+
+## Source
+
+services.ts:13
diff --git a/docs/sdk/index.md b/docs/sdk/index.md
@@ -1,16 +1,16 @@
 ---
-sidebar_position: 1
-description: Obol SDK
-title: Obol SDK Reference
-sidebar_label: Intro
+hide_title: true
 ---
+
 ![Obol Logo](https://obol.tech/obolnetwork.png)
 
-This is the reference for the Obol Software Development Kit, for creating Distributed Validators with the help of the [Obol API](/api). 
+<h1 align="center">Obol SDK</h1>
+
+This repo contains the Obol Software Development Kit, for creating Distributed Validators with the help of the [Obol API](https://docs.obol.tech/api). 
 
 ## Getting Started
 
-Checkout our [docs](https://docs.obol.tech/docs/int/quickstart/advanced/quickstart-sdk), [examples](https://github.com/ObolNetwork/obol-sdk-examples/), and SDK [reference](https://obolnetwork.github.io/obol-packages). Further guides and walkthroughs coming soon.
+Checkout our [docs](https://docs.obol.tech/docs/advanced/quickstart-sdk), [examples](https://github.com/ObolNetwork/obol-sdk-examples/), and SDK [reference](https://obolnetwork.github.io/obol-packages). Further guides and walkthroughs coming soon.
 
 ## Enumerations
 
@@ -23,16 +23,20 @@ Checkout our [docs](https://docs.obol.tech/docs/int/quickstart/advanced/quicksta
 ## Interfaces
 
 - [ClusterDefintion](interfaces/ClusterDefintion.md)
-- [ClusterLock](interfaces/ClusterLock.md)
-- [ClusterPayload](interfaces/ClusterPayload.md)
 
 ## Type Aliases
 
-- [BuilderRegistration](type-aliases/BuilderRegistration.md)
-- [BuilderRegistrationMessage](type-aliases/BuilderRegistrationMessage.md)
-- [ClusterCreator](type-aliases/ClusterCreator.md)
 - [ClusterOperator](type-aliases/ClusterOperator.md)
+- [OperatorPayload](type-aliases/OperatorPayload.md)
+- [ClusterCreator](type-aliases/ClusterCreator.md)
 - [ClusterValidator](type-aliases/ClusterValidator.md)
+- [ClusterPayload](type-aliases/ClusterPayload.md)
+- [BuilderRegistrationMessage](type-aliases/BuilderRegistrationMessage.md)
+- [BuilderRegistration](type-aliases/BuilderRegistration.md)
 - [DepositData](type-aliases/DepositData.md)
 - [DistributedValidator](type-aliases/DistributedValidator.md)
-- [OperatorPayload](type-aliases/OperatorPayload.md)
+- [ClusterLock](type-aliases/ClusterLock.md)
+
+## Functions
+
+- [validateClusterLock](functions/validateClusterLock.md)
diff --git a/docs/sdk/interfaces/ClusterDefintion.md b/docs/sdk/interfaces/ClusterDefintion.md
@@ -1,23 +1,23 @@
-Cluster Definition
+Cluster definition data needed for dkg
 
 ## Extends
 
-- [`ClusterPayload`](ClusterPayload.md)
+- [`ClusterPayload`](../type-aliases/ClusterPayload.md)
 
 ## Properties
 
 | Property | Type | Description | Inherited from |
 | :------ | :------ | :------ | :------ |
-| `config_hash` | `string` | The cluster configuration hash. | - |
+| `name` | `string` | The cluster name. | `ClusterPayload.name` |
+| `operators` | [`ClusterOperator`](../type-aliases/ClusterOperator.md)[] | The cluster nodes operators addresses. | `ClusterPayload.operators` |
+| `validators` | [`ClusterValidator`](../type-aliases/ClusterValidator.md)[] | The clusters validators information. | `ClusterPayload.validators` |
 | `creator` | [`ClusterCreator`](../type-aliases/ClusterCreator.md) | The creator of the cluster. | - |
-| `definition_hash?` | `string` | The hash of the cluster definition. | - |
+| `version` | `string` | The cluster configuration version. | - |
 | `dkg_algorithm` | `string` | The cluster dkg algorithm. | - |
 | `fork_version` | `string` | The cluster fork version. | - |
-| `name` | `string` | The cluster name. | [`ClusterPayload`](ClusterPayload.md).`name` |
-| `num_validators` | `number` | The number of distributed validators in the cluster. | - |
-| `operators` | [`ClusterOperator`](../type-aliases/ClusterOperator.md)[] | The cluster nodes operators addresses. | [`ClusterPayload`](ClusterPayload.md).`operators` |
-| `threshold` | `number` | The distributed validator threshold. | - |
-| `timestamp` | `string` | The cluster creation timestamp. | - |
 | `uuid` | `string` | The cluster uuid. | - |
-| `validators` | [`ClusterValidator`](../type-aliases/ClusterValidator.md)[] | The clusters validators information. | [`ClusterPayload`](ClusterPayload.md).`validators` |
-| `version` | `string` | The cluster configuration version. | - |
+| `timestamp` | `string` | The cluster creation timestamp. | - |
+| `config_hash` | `string` | The cluster configuration hash. | - |
+| `threshold` | `number` | The distributed validator threshold. | - |
+| `num_validators` | `number` | The number of distributed validators in the cluster. | - |
+| `definition_hash?` | `string` | The hash of the cluster definition. | - |
diff --git a/docs/sdk/interfaces/ClusterLock.md b/docs/sdk/interfaces/ClusterLock.md
diff --git a/docs/sdk/interfaces/ClusterPayload.md b/docs/sdk/interfaces/ClusterPayload.md
diff --git a/docs/sdk/interfaces/_category_.json b/docs/sdk/interfaces/_category_.json
diff --git a/docs/sdk/type-aliases/BuilderRegistrationMessage.md b/docs/sdk/type-aliases/BuilderRegistrationMessage.md
@@ -8,8 +8,8 @@ Unsigned DV Builder Registration Message
 | :------ | :------ | :------ |
 | `fee_recipient` | `string` | The DV fee recipient. |
 | `gas_limit` | `number` | Default is 30000000. |
-| `pubkey` | `string` | The public key of the DV. |
 | `timestamp` | `number` | Timestamp when generating cluster lock file. |
+| `pubkey` | `string` | The public key of the DV. |
 
 ## Source