@ssv-labs/ssv-sdk 0.1.3 → 1.0.2

package/README.html

@@ -51,7 +51,7 @@
 <span class="token punctuation">}</span><span class="token punctuation">)</span>
 </code></pre><h3 id="cluster-management">Cluster management </h3>
 <pre data-role="codeBlock" data-info="typescript" class="language-typescript typescript"><code><span class="token comment">// Get cluster balance</span>
-<span class="token keyword keyword-import">import</span> <span class="token punctuation">{</span> getClusterSnapshot <span class="token punctuation">}</span> <span class="token keyword keyword-from">from</span> <span class="token string">'@/utils/cluster'</span>
+<span class="token keyword keyword-import">import</span> <span class="token punctuation">{</span> toSolidityCluster <span class="token punctuation">}</span> <span class="token keyword keyword-from">from</span> <span class="token string">'@/utils/cluster'</span>
 <span class="token keyword keyword-import">import</span> <span class="token punctuation">{</span> <span class="token constant">SSVSDK</span> <span class="token punctuation">}</span> <span class="token keyword keyword-from">from</span> <span class="token string">'ssv-sdk'</span>
 
 <span class="token comment">// Initialize with basic configuration</span>
@@ -66,7 +66,7 @@
 <span class="token punctuation">}</span><span class="token punctuation">)</span>
 
 <span class="token keyword keyword-const">const</span> balance <span class="token operator">=</span> <span class="token keyword keyword-await">await</span> sdk<span class="token punctuation">.</span>contract<span class="token punctuation">.</span>write<span class="token punctuation">.</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
-  cluster<span class="token operator">:</span> <span class="token function">getClusterSnapshot</span><span class="token punctuation">(</span>cluster<span class="token punctuation">)</span><span class="token punctuation">,</span>
+  cluster<span class="token operator">:</span> <span class="token function">toSolidityCluster</span><span class="token punctuation">(</span>cluster<span class="token punctuation">)</span><span class="token punctuation">,</span>
   clusterOwner<span class="token operator">:</span> <span class="token string">'0x'</span><span class="token punctuation">,</span>
   operatorIds<span class="token operator">:</span> operators<span class="token punctuation">.</span><span class="token function">map</span><span class="token punctuation">(</span><span class="token punctuation">(</span>o<span class="token punctuation">)</span> <span class="token operator">=&gt;</span> <span class="token function">BigInt</span><span class="token punctuation">(</span>o<span class="token punctuation">.</span>id<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
 <span class="token punctuation">}</span><span class="token punctuation">)</span>
@@ -76,11 +76,8 @@
 <span class="token keyword keyword-await">await</span> sdk<span class="token punctuation">.</span>clusters<span class="token punctuation">.</span><span class="token function">deposit</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
   id<span class="token operator">:</span> <span class="token string">'...'</span><span class="token punctuation">,</span>
   amount<span class="token operator">:</span> <span class="token function">parseEther</span><span class="token punctuation">(</span><span class="token string">'1.5'</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
-  options<span class="token operator">:</span> <span class="token punctuation">{</span>
-    approve<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span> <span class="token comment">// Automatically triggers token approval transaction if the allowance is lower than the deposit amount</span>
-  <span class="token punctuation">}</span><span class="token punctuation">,</span>
 <span class="token punctuation">}</span><span class="token punctuation">)</span>
-</code></pre><h3 id="environment-setup-for-testing">Environment Setup for Testing </h3>
+</code></pre><p><strong>Note:</strong> The current <code>sdk.clusters.deposit</code> path is payable and does not perform ERC-20 allowance checks or <code>approve</code> calls.</p><h3 id="environment-setup-for-testing">Environment Setup for Testing </h3>
 <p>To run tests, you'll need to set up your environment variables. Create a <code>.env</code> file in the root directory of your project using the provided <code>.env.example</code> as a template:</p>
 <pre data-role="codeBlock" data-info="bash" class="language-bash bash"><code><span class="token comment"># Copy the example env file</span>
 <span class="token function">cp</span> .env.example .env
@@ -99,4 +96,4 @@
     
     
   
-    </body></html>
+    </body></html>

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://ssv.network/wp-content/uploads/2024/06/full_logo_white.svg" alt="SSV Network" width="300"/>
+  <img src="https://framerusercontent.com/assets/SxrtOSpELBgEtirWSlWPnBE0cd4.png" alt="SSV Network" width="300"/>
 </p>
 
 <h1 align="center">SSV SDK</h1>
@@ -18,9 +18,10 @@ The SSV SDK is a TypeScript library for interacting with the SSV network, enabli
 
 ## Core Modules
 
-The SDK consists of four main modules:
+The SDK consists of five main modules:
 
 - **Clusters**: Manage validator clusters, handle deposits, and register validators
+- **DAO**: Manage DAO-related actions and values
 - **Operators**: Interact with network operators and manage operator relationships
 - **API**: Access network data, query states, and retrieve operational information
 - **Utils**: Helper functions for keyshare validation, share generation, and other utilities
@@ -43,79 +44,105 @@ pnpm install @ssv-labs/ssv-sdk
 ### Initialize the SDK
 
 ```typescript
-import { SSVSDK, chains } from '@ssv-labs/ssv-sdk'
-import { createPublicClient, createWalletClient, http } from 'viem'
-import { privateKeyToAccount } from 'viem/accounts'
+import { SSVSDK, chains } from '@ssv-labs/ssv-sdk';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
 
-const chain = chains.mainnet // or chains.holesky
-const transport = http()
+const chain = chains.mainnet; // or chains.hoodi
+const transport = http();
 
 const publicClient = createPublicClient({
   chain,
   transport,
-})
+});
 
-const account = privateKeyToAccount('0x...')
+const account = privateKeyToAccount('0x...');
 const walletClient = createWalletClient({
   account,
   chain,
   transport,
-})
+});
 
 const sdk = new SSVSDK({
   publicClient,
   walletClient,
-})
+});
 ```
 
 ### API Examples
 
 ```typescript
 // Query operators
-const operators = await sdk.api.getOperators({
+const { operators } = await sdk.api.getOperators({
   operatorIds: ['220', '221', '223', '224'],
-})
+});
 
 // Get owner nonce
-const nonce = await sdk.api.getOwnerNonce({
+const { nonce } = await sdk.api.getOwnerNonce({
   owner: 'your_wallet_address',
-})
+});
+
+// Export SDK-generated payloads into a webapp-ready keyshares JSON file (Node.js only)
+await sdk.utils.writeKeysharesFile({
+  path: './keyshares-webapp.json',
+  shares,
+  ownerAddress: 'your_wallet_address',
+  nonce,
+});
 ```
 
+### API Compatibility Notes
+
+`getClusterSnapshot` is the canonical cluster snapshot API.
+
+Snapshot-aware SDK read methods return the queried data together with the subgraph snapshot block number, for example:
+
+- `sdk.api.getOwnerNonce(...) -> { blockNumber, nonce }`
+- `sdk.api.getOperators(...) -> { blockNumber, operators }`
+- `sdk.api.getClusterSnapshot(...) -> { blockNumber, cluster }`
+
+| SDK version | Method name                          |
+| ----------- | ------------------------------------ |
+| `0.1.x`     | `sdk.api.getClusterSnapshot({ id })` |
+| `1.x`       | `sdk.api.getClusterSnapshot({ id })` |
+
+`sdk.api.toSolidityCluster` is no longer part of the public subgraph API. The internal utility `toSolidityCluster(...)` in `utils/cluster` still exists for converting cluster data into the Solidity struct shape used by contract calls.
+
+`sdk.utils.writeKeysharesFile(...)` is a Node.js utility and relies on filesystem access.
+
 ### Cluster Management
 
 ```typescript
-import { parseEther } from 'viem'
+import { parseEther } from 'viem';
 
 // Deposit to cluster
-await sdk.clusters.deposit(
-  {
-    id: 'your_cluster_id',
-    amount: parseEther('30'),
-  },
-  {
-    approve: true, // Auto-approve token if needed
-  },
-)
+await sdk.clusters.deposit({
+  id: 'your_cluster_id',
+  amount: parseEther('30'),
+});
 ```
 
+> Note: The current `sdk.clusters.deposit` path is payable and does not perform ERC-20 allowance checks or `approve` calls.
+
 ### Register Validators
+
 To register validators, you'll need to:
 
 1. Create shares from your keyshares JSON file
 2. Register the validator using the created shares
+
 ```typescript
-import { parseEther } from 'viem'
+import { parseEther } from 'viem';
 
 // Your keyshares JSON file containing the validator's data
-import keyshares from 'path/to/keyshares.json'
+import keyshares from 'path/to/keyshares.json';
 
 // First, validate and create shares from your keyshares
 try {
   const result = await sdk.utils.validateSharesPreRegistration({
     operatorIds: ['220', '221', '223', '224'],
     keyshares,
-  })
+  });
 
   // Register validators using the clusters API
   const receipt = await sdk.clusters
@@ -125,7 +152,7 @@ try {
         depositAmount: parseEther('2'),
       },
     })
-    .then((tx) => tx.wait())
+    .then((tx) => tx.wait());
 } catch (e) {
   // something went wrong
 }