SSV SDK

⚠️ Development Notice: This SDK is currently under active development and testing. It is not recommended for production use at this time. For updates and documentation, please refer to our official documentation.

Overview

The SSV SDK is a TypeScript library for interacting with the SSV network, enabling distributed validator operations on Ethereum.

Core 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

Installation

# Using npm
npm i @ssv-labs/ssv-sdk

# Using yarn
yarn add @ssv-labs/ssv-sdk

# Using pnpm
pnpm install @ssv-labs/ssv-sdk

Quick Start

Initialize the SDK

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.hoodi
const transport = http();

const publicClient = createPublicClient({
  chain,
  transport,
});

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain,
  transport,
});

const sdk = new SSVSDK({
  publicClient,
  walletClient,
});

API Examples

// Query operators
const { operators } = await sdk.api.getOperators({
  operatorIds: ['220', '221', '223', '224'],
});

// Get owner nonce
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

import { parseEther } from 'viem';

// Deposit to cluster
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

import { parseEther } from 'viem';

// Your keyshares JSON file containing the validator's data
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
    .registerValidators({
      args: {
        keyshares: result.available,
        depositAmount: parseEther('2'),
      },
    })
    .then((tx) => tx.wait());
} catch (e) {
  // something went wrong
}

Documentation

For detailed documentation and examples, visit our official documentation.