sdk v2.1.0 (#430)

* sdk v2.1.1 * fix version
ObolNetwork · Oct 10, 2024 · 05ecad9 · 05ecad9
1 parent cbc7972
commit 05ecad9
Show file tree

Hide file tree

Showing 21 changed files with 478 additions and 336 deletions.
diff --git a/docs/sdk/classes/Client.md b/docs/sdk/classes/Client.md
@@ -13,7 +13,7 @@ Obol sdk Client can be used for creating, managing and activating distributed va
 #### Parameters
 
 | Parameter | Type | Description |
-| :------ | :------ | :------ |
+| ------ | ------ | ------ |
 | `config` | `object` | Client configurations |
 | `config.baseUrl`? | `string` | obol-api url |
 | `config.chainId`? | `number` | Blockchain network ID |
@@ -32,9 +32,9 @@ An example of how to instantiate obol-sdk Client:
 
 `Base.constructor`
 
-#### Source
+#### Defined in
 
-index.ts:45
+index.ts:66
 
 ## Methods
 
@@ -57,9 +57,73 @@ 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)
 
-#### Source
+#### Defined in
 
-index.ts:61
+index.ts:79
+
+***
+
+### createObolRewardsSplit()
+
+> **createObolRewardsSplit**(`rewardsSplitPayload`): `Promise`\<[`ClusterValidator`](../type-aliases/ClusterValidator.md)\>
+
+Deploys OWR and Splitter Proxy.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `rewardsSplitPayload` | [`RewardsSplitPayload`](../interfaces/RewardsSplitPayload.md) | Data needed to deploy owr and splitter. |
+
+#### Returns
+
+`Promise`\<[`ClusterValidator`](../type-aliases/ClusterValidator.md)\>
+
+owr address as withdrawal address and splitter as fee recipient
+
+An example of how to use createObolRewardsSplit:
+[createObolRewardsSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L141)
+
+#### Remarks
+
+**⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed 
+and not pushed to version control.
+
+#### Defined in
+
+index.ts:133
+
+***
+
+### createObolTotalSplit()
+
+> **createObolTotalSplit**(`totalSplitPayload`): `Promise`\<[`ClusterValidator`](../type-aliases/ClusterValidator.md)\>
+
+Deploys Splitter Proxy.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `totalSplitPayload` | [`TotalSplitPayload`](../type-aliases/TotalSplitPayload.md) | Data needed to deploy splitter if it doesnt exist. |
+
+#### Returns
+
+`Promise`\<[`ClusterValidator`](../type-aliases/ClusterValidator.md)\>
+
+splitter address as withdrawal address and splitter as fee recipient too
+
+An example of how to use createObolTotalSplit:
+[createObolTotalSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L168)
+
+#### Remarks
+
+**⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed 
+and not pushed to version control.
+
+#### Defined in
+
+index.ts:254
 
 ***
 
@@ -72,7 +136,7 @@ Creates a cluster definition which contains cluster configuration.
 #### Parameters
 
 | Parameter | Type | Description |
-| :------ | :------ | :------ |
+| ------ | ------ | ------ |
 | `newCluster` | [`ClusterPayload`](../type-aliases/ClusterPayload.md) | The new unique cluster. |
 
 #### Returns
@@ -88,28 +152,28 @@ 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#L59)
 
-#### Source
+#### Defined in
 
-index.ts:107
+index.ts:350
 
 ***
 
 ### acceptClusterDefinition()
 
-> **acceptClusterDefinition**(`operatorPayload`, `configHash`): `Promise` \<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
+> **acceptClusterDefinition**(`operatorPayload`, `configHash`): `Promise`\<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
 
 Approves joining a cluster with specific configuration.
 
 #### 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. |
 
 #### Returns
 
-`Promise` \<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
+`Promise`\<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
 
 The cluster definition.
 
@@ -120,25 +184,25 @@ On unauthorized, duplicate entries, missing keys, not found cluster or invalid d
 An example of how to use acceptClusterDefinition:
 [acceptClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L106)
 
-#### Source
+#### Defined in
 
-index.ts:165
+index.ts:415
 
 ***
 
 ### getClusterDefinition()
 
-> **getClusterDefinition**(`configHash`): `Promise` \<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
+> **getClusterDefinition**(`configHash`): `Promise`\<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
 
 #### Parameters
 
 | Parameter | Type | Description |
-| :------ | :------ | :------ |
+| ------ | ------ | ------ |
 | `configHash` | `string` | The configuration hash returned in createClusterDefinition |
 
 #### Returns
 
-`Promise` \<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
+`Promise`\<[`ClusterDefinition`](../interfaces/ClusterDefinition.md)\>
 
 The  cluster definition for config hash
 
@@ -149,25 +213,25 @@ 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#L74)
 
-#### Source
+#### Defined in
 
-index.ts:217
+index.ts:469
 
 ***
 
 ### getClusterLock()
 
-> **getClusterLock**(`configHash`): `Promise` \<[`ClusterLock`](../type-aliases/ClusterLock.md)\>
+> **getClusterLock**(`configHash`): `Promise`\<[`ClusterLock`](../type-aliases/ClusterLock.md)\>
 
 #### Parameters
 
 | Parameter | Type | Description |
-| :------ | :------ | :------ |
+| ------ | ------ | ------ |
 | `configHash` | `string` | The configuration hash in cluster-definition |
 
 #### Returns
 
-`Promise` \<[`ClusterLock`](../type-aliases/ClusterLock.md)\>
+`Promise`\<[`ClusterLock`](../type-aliases/ClusterLock.md)\>
 
 The matched cluster details (lock) from DB
 
@@ -178,6 +242,6 @@ 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#L89)
 
-#### Source
+#### Defined in
 
-index.ts:236
+index.ts:488
diff --git a/docs/sdk/enumerations/FORK_MAPPING.md b/docs/sdk/enumerations/FORK_MAPPING.md
@@ -2,9 +2,9 @@ Permitted ChainID's
 
 ## Enumeration Members
 
-| Enumeration Member | Value | Description |
-| :------ | :------ | :------ |
-| `0x00000000` | `1` | Mainnet. |
-| `0x00001020` | `5` | Goerli/Prater. |
-| `0x00000064` | `100` | Gnosis Chain. |
-| `0x01017000` | `17000` | Holesky. |
+| Enumeration Member | Value | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| `0x00000000` | `1` | Mainnet. | types.ts:6 |
+| `0x00001020` | `5` | Goerli/Prater. | types.ts:9 |
+| `0x00000064` | `100` | Gnosis Chain. | types.ts:12 |
+| `0x01017000` | `17000` | Holesky. | types.ts:15 |
diff --git a/docs/sdk/functions/validateClusterLock.md b/docs/sdk/functions/validateClusterLock.md
@@ -5,7 +5,7 @@ Verifies Cluster Lock's validity.
 ## Parameters
 
 | Parameter | Type | Description |
-| :------ | :------ | :------ |
+| ------ | ------ | ------ |
 | `lock` | [`ClusterLock`](../type-aliases/ClusterLock.md) | cluster lock |
 
 ## Returns
@@ -21,6 +21,6 @@ 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#L127)
 
-## Source
+## Defined in
 
 services.ts:13
diff --git a/docs/sdk/index.md b/docs/sdk/index.md
@@ -3,21 +3,27 @@ hide_title: true
 ---
 
 <span className="theme-doc-version-badge badge badge--secondary">
-      <strong>SDK Version:</strong> v1.0.17
+      <strong>SDK Version:</strong> v2.1.0
 </span>
 
-![Obol Logo](https://obol.tech/obolnetwork.png)
+![Obol Logo](https://obol.org/obolnetwork.png)
 
 <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).
+This repo contains the Obol Software Development Kit, for creating Distributed Validators with the help of the [Obol API](https://docs.obol.org/api).
 
 ## Getting Started
 
-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-sdk). Further guides and walkthroughs coming soon.
+Checkout our [docs](https://docs.obol.org/docs/advanced/quickstart-sdk), [examples](https://github.com/ObolNetwork/obol-sdk-examples/), and SDK [reference](https://obolnetwork.github.io/obol-sdk). Further guides and walkthroughs coming soon.
 
 ## Terms and Conditions
-To use obol-sdk and in order to be able to create a cluster definition or accept an invite to join a cluster, you must accept the [latest Obol terms and conditions](https://obol.tech/terms.pdf) by calling acceptObolLatestTermsAndConditions.
+To use obol-sdk and in order to be able to create a cluster definition or accept an invite to join a cluster, you must accept the [latest Obol terms and conditions](https://obol.org/terms.pdf) by calling acceptObolLatestTermsAndConditions.
+
+## ⚠️ Important Security Notice:
+If you're integrating this SDK with a **backend** (e.g., in Node.js), and you store a private key for executing splitter transactions, handle it with extreme caution. Ensure that:
+
+- The private key is securely stored (e.g., in an `.env` file).
+- Never commit or push your `.env` file containing the private key to version control.
 
 ## Contributing
 
@@ -50,33 +56,35 @@ All contributions are reviewed before they are merged into the main branch. Plea
 
 Thank you for contributing to Obol-SDK!
 
-## API Index
-
-### Enumerations
+## Enumerations
 
 - [FORK\_MAPPING](enumerations/FORK_MAPPING.md)
 
-### Classes
+## Classes
 
 - [Client](classes/Client.md)
 
-### Interfaces
+## Interfaces
 
 - [ClusterDefinition](interfaces/ClusterDefinition.md)
+- [RewardsSplitPayload](interfaces/RewardsSplitPayload.md)
 
-### Type Aliases
+## Type Aliases
 
 - [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)
+- [SplitRecipient](type-aliases/SplitRecipient.md)
+- [TotalSplitPayload](type-aliases/TotalSplitPayload.md)
 - [BuilderRegistrationMessage](type-aliases/BuilderRegistrationMessage.md)
 - [BuilderRegistration](type-aliases/BuilderRegistration.md)
 - [DepositData](type-aliases/DepositData.md)
 - [DistributedValidator](type-aliases/DistributedValidator.md)
 - [ClusterLock](type-aliases/ClusterLock.md)
+- [ETH\_ADDRESS](type-aliases/ETH_ADDRESS.md)
 
-### Functions
+## Functions
 
 - [validateClusterLock](functions/validateClusterLock.md)
diff --git a/docs/sdk/interfaces/ClusterDefinition.md b/docs/sdk/interfaces/ClusterDefinition.md
@@ -6,19 +6,19 @@ Cluster definition data needed for dkg
 
 ## Properties
 
-| Property | Type | Description | Overrides | Inherited from |
-| :------ | :------ | :------ | :------ | :------ |
-| `name` | `string` | The cluster name. | `ClusterPayload.name` | `ClusterPayload.name` |
-| `operators` | [`ClusterOperator`](../type-aliases/ClusterOperator.md)[] | The cluster nodes operators addresses. | `ClusterPayload.operators` | `ClusterPayload.operators` |
-| `validators` | [`ClusterValidator`](../type-aliases/ClusterValidator.md)[] | The cluster validators information. | `ClusterPayload.validators` | `ClusterPayload.validators` |
-| `creator` | [`ClusterCreator`](../type-aliases/ClusterCreator.md) | The creator of the cluster. | - | - |
-| `version` | `string` | The cluster configuration version. | - | - |
-| `dkg_algorithm` | `string` | The cluster dkg algorithm. | - | - |
-| `fork_version` | `string` | The cluster fork version. | - | - |
-| `uuid` | `string` | The cluster uuid. | - | - |
-| `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. | - | - |
-| `deposit_amounts?` | `string`[] | The cluster partial deposits in gwei or 32000000000. | `ClusterPayload.deposit_amounts` | `ClusterPayload.deposit_amounts` |
-| `definition_hash?` | `string` | The hash of the cluster definition. | - | - |
+| Property | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| `name` | `string` | The cluster name. | `ClusterPayload.name` | types.ts:73 |
+| `operators` | [`ClusterOperator`](../type-aliases/ClusterOperator.md)[] | The cluster nodes operators addresses. | `ClusterPayload.operators` | types.ts:76 |
+| `validators` | [`ClusterValidator`](../type-aliases/ClusterValidator.md)[] | The cluster validators information. | `ClusterPayload.validators` | types.ts:79 |
+| `deposit_amounts?` | `null` \| `string`[] | The cluster partial deposits in gwei or 32000000000. | `ClusterPayload.deposit_amounts` | types.ts:82 |
+| `creator` | [`ClusterCreator`](../type-aliases/ClusterCreator.md) | The creator of the cluster. | - | types.ts:90 |
+| `version` | `string` | The cluster configuration version. | - | types.ts:93 |
+| `dkg_algorithm` | `string` | The cluster dkg algorithm. | - | types.ts:96 |
+| `fork_version` | `string` | The cluster fork version. | - | types.ts:99 |
+| `uuid` | `string` | The cluster uuid. | - | types.ts:102 |
+| `timestamp` | `string` | The cluster creation timestamp. | - | types.ts:105 |
+| `config_hash` | `string` | The cluster configuration hash. | - | types.ts:108 |
+| `threshold` | `number` | The distributed validator threshold. | - | types.ts:111 |
+| `num_validators` | `number` | The number of distributed validators in the cluster. | - | types.ts:114 |
+| `definition_hash?` | `string` | The hash of the cluster definition. | - | types.ts:117 |
diff --git a/docs/sdk/interfaces/RewardsSplitPayload.md b/docs/sdk/interfaces/RewardsSplitPayload.md
@@ -0,0 +1,17 @@
+OWR and Split Proxy Params
+
+## Extends
+
+- [`TotalSplitPayload`](../type-aliases/TotalSplitPayload.md)
+
+## Properties
+
+| Property | Type | Description | Inherited from | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| `splitRecipients` | [`SplitRecipient`](../type-aliases/SplitRecipient.md)[] | The split recipients addresses and splits. | `TotalSplitPayload.splitRecipients` | types.ts:136 |
+| `ObolRAFSplit?` | `number` | Split percentageNumber allocated for obol retroactive funding, minimum is 1%. | `TotalSplitPayload.ObolRAFSplit` | types.ts:139 |
+| `distributorFee?` | `number` | The percentageNumber of accrued rewards that is paid to the caller of the distribution function to compensate them for the gas costs of doing so. Cannot be greater than 10%. For example, 5 represents 5%. | `TotalSplitPayload.distributorFee` | types.ts:142 |
+| `controllerAddress?` | `string` | Address that can mutate the split, should be ZeroAddress for immutable split. | `TotalSplitPayload.controllerAddress` | types.ts:145 |
+| `principalRecipient` | `string` | Address that will reclaim validator principal after exit. | - | types.ts:153 |
+| `etherAmount` | `number` | Amount needed to deploy all validators expected for the OWR/Splitter configuration. | - | types.ts:156 |
+| `recoveryAddress?` | `string` | Address that can control where the owr erc-20 tokens can be pushed, if set to zero it goes to splitter or principal address. | - | types.ts:159 |
diff --git a/docs/sdk/type-aliases/BuilderRegistration.md b/docs/sdk/type-aliases/BuilderRegistration.md
@@ -4,11 +4,11 @@ Pre-generated Signed Validator Builder Registration
 
 ## Type declaration
 
-| Member | Type | Description |
-| :------ | :------ | :------ |
-| `message` | [`BuilderRegistrationMessage`](BuilderRegistrationMessage.md) | Builder registration message. |
-| `signature` | `string` | BLS signature of the builder registration message. |
+| Name | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| `message` | [`BuilderRegistrationMessage`](BuilderRegistrationMessage.md) | Builder registration message. | types.ts:184 |
+| `signature` | `string` | BLS signature of the builder registration message. | types.ts:187 |
 
-## Source
+## Defined in
 
-types.ts:143
+types.ts:182