@obolnetwork/obol-sdk 2.11.9 → 2.11.12

package/dist/types/src/exits/exit.d.ts

@@ -1,35 +1,35 @@
 import type { ProviderType, ExitClusterConfig, ExitValidationPayload, ExitValidationBlob, SignedExitValidationMessage, ExistingExitValidationBlobData, FullExitBlob } from '../types.js';
 /**
- * Exit validation and verification class for Obol distributed validators.
+ * Validates and verifies voluntary exit signatures for Obol distributed validators.
  *
- * This class provides functionality to validate and verify voluntary exit signatures
- * for distributed validators in an Obol cluster. It handles both partial exit signatures
- * from individual operators and payload signatures that authorize exit operations.
+ * Do not instantiate directly; access via `client.exit`.
  *
- * The class supports:
- * - Verification of BLS signatures for partial exit messages
- * - Verification of ECDSA signatures for exit payload authorization
- * - Validation of exit blobs against cluster configuration
- * - Duplicate detection and epoch validation
+ * Available methods:
+ * - {@link Exit.verifyPartialExitSignature} – verify a BLS partial exit signature
+ * - {@link Exit.verifyExitPayloadSignature} – verify an ECDSA exit payload signature
+ * - {@link Exit.validateExitBlobs} – validate exit blobs against cluster config
+ * - {@link Exit.recombineExitBlobs} – aggregate partial signatures into a full exit blob
+ *
+ * All methods are read-only (no on-chain transactions). No signer is required.
  *
  * @example
  * ```typescript
- * const exit = new Exit(1, provider); // Mainnet with provider
+ * const client = new Client({ chainId: 1 }, signer, provider);
  *
  * // Verify a partial exit signature
- * const isValid = await exit.verifyPartialExitSignature(
+ * const isValid = await client.exit.verifyPartialExitSignature(
  *   publicShareKey,
  *   signedExitMessage,
  *   forkVersion,
- *   genesisValidatorsRoot
+ *   genesisValidatorsRoot,
  * );
  *
  * // Validate exit blobs for a cluster
- * const validBlobs = await exit.validateExitBlobs(
+ * const validBlobs = await client.exit.validateExitBlobs(
  *   clusterConfig,
  *   exitsPayload,
  *   beaconNodeApiUrl,
- *   existingBlobData
+ *   existingBlobData,
  * );
  * ```
  */
@@ -44,11 +44,8 @@ export declare class Exit {
      *
      * @example
      * ```typescript
-     * // For mainnet with a provider
-     * const exit = new Exit(1, provider);
-     *
-     * // For goerli testnet without provider
-     * const exit = new Exit(5, null);
+     * const client = new Client({ chainId: 1 }, signer, provider);
+     * const exit = client.exit; // Access via client, do not instantiate directly
      * ```
      */
     constructor(chainId: number, provider: ProviderType | undefined | null);

package/dist/types/src/incentives/incentives.d.ts

@@ -1,11 +1,23 @@
 import { type ClaimableIncentives, type ETH_ADDRESS, type ProviderType, type SignerType, type ClaimIncentivesResponse } from '../types.js';
 /**
- * Incentives can be used for fetching and claiming Obol incentives.
- * @class
- * @internal Access it through Client.incentives.
+ * Manages Obol incentive rewards – querying eligibility and claiming from
+ * on-chain Merkle Distributor contracts.
+ *
+ * Do not instantiate directly; access via `client.incentives`.
+ *
  * @example
- * const obolClient = new Client(config);
- * await obolClient.incentives.claimIncentives(address);
+ * ```typescript
+ * const client = new Client({ chainId: 560048 }, signer);
+ *
+ * // Check claimable incentives
+ * const data = await client.incentives.getIncentivesByAddress("0xOperator...");
+ *
+ * // Check if already claimed
+ * const claimed = await client.incentives.isClaimed(data.contract_address, data.index);
+ *
+ * // Claim (sends on-chain transaction)
+ * const { txHash } = await client.incentives.claimIncentives("0xOperator...");
+ * ```
  */
 export declare class Incentives {
     private readonly signer;
@@ -14,44 +26,61 @@ export declare class Incentives {
     readonly provider: ProviderType | undefined | null;
     constructor(signer: SignerType | undefined, chainId: number, request: (endpoint: string, options?: RequestInit) => Promise<any>, provider: ProviderType | undefined | null);
     /**
-     * Claims Obol incentives from a Merkle Distributor contract using an address.
+     * Claims Obol incentives from a Merkle Distributor contract for the given address.
      *
-     * This method automatically fetches incentive data and verifies whether the incentives have already been claimed.
-     * If `txHash` is `null`, it indicates that the incentives were already claimed.
+     * Automatically fetches incentive data, checks if already claimed, and submits
+     * the on-chain claim transaction. Returns `{ txHash: null }` if incentives were
+     * already claimed (idempotent).
      *
-     * Note: This method is not yet enabled and will throw an error if called.
+     * @param address - The operator's Ethereum address to claim incentives for.
+     * @returns The transaction hash, or `{ txHash: null }` if already claimed.
+     * @throws {SignerRequiredError} If no signer was provided.
+     * @throws {Error} If no incentives are found for the address.
      *
-     * @remarks
-     * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
-     * and not pushed to version control.
-     *
-     * @param {string} address - The address to claim incentives for
-     * @returns {Promise<ClaimIncentivesResponse>} The transaction hash or already claimed status
-     * @throws Will throw an error if the incentives data is not found or the claim fails
-     *
-     * An example of how to use claimIncentives:
-     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L281)
+     * @example
+     * ```typescript
+     * const { txHash } = await client.incentives.claimIncentives("0xOperator...");
+     * if (txHash) {
+     *   console.log("Claimed:", txHash);
+     * } else {
+     *   console.log("Already claimed");
+     * }
+     * ```
      */
     claimIncentives(address: string): Promise<ClaimIncentivesResponse>;
     /**
-     * Read isClaimed.
+     * Checks whether incentives have already been claimed for a given operator index.
      *
-     * @param {ETH_ADDRESS} contractAddress - Address of the Merkle Distributor Contract
-     * @param {ETH_ADDRESS} index - operator index in merkle tree
-     * @returns {Promise<boolean>} true if incentives are already claime
+     * Read-only on-chain call – no transaction sent.
      *
+     * @param contractAddress - Address of the Merkle Distributor contract.
+     * @param index - The operator's index in the Merkle tree (from {@link Incentives.getIncentivesByAddress}).
+     * @returns `true` if the incentives at that index have already been claimed.
      *
-     * An example of how to use isClaimed:
-     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L266)
+     * @example
+     * ```typescript
+     * const claimed = await client.incentives.isClaimed(
+     *   "0xMerkleDistributor...",
+     *   42,
+     * );
+     * ```
      */
     isClaimed(contractAddress: ETH_ADDRESS, index: number): Promise<boolean>;
     /**
-     * @param address - Operator address
-     * @returns {Promise<IncentivesType>} The matched incentives from DB
-     * @throws On not found if address not found.
+     * Fetches claimable incentive data for an operator address from the Obol API.
+     *
+     * The returned data includes the Merkle proof, amount, and contract address
+     * needed to claim on-chain. This is a read-only API call.
+     *
+     * @param address - The operator's Ethereum address.
+     * @returns Claimable incentive data including amount, Merkle proof, and contract address.
+     * @throws {Error} If no incentives are found for the given address (404).
      *
-     * An example of how to use getIncentivesByAddress:
-     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L250)
+     * @example
+     * ```typescript
+     * const incentives = await client.incentives.getIncentivesByAddress("0xOperator...");
+     * console.log(incentives.amount, incentives.contract_address);
+     * ```
      */
     getIncentivesByAddress(address: string): Promise<ClaimableIncentives>;
 }

package/dist/types/src/index.d.ts

@@ -9,150 +9,337 @@ export * from './services.js';
 export * from './verification/signature-validator.js';
 export * from './verification/common.js';
 export * from './constants.js';
+export { ConflictError, SignerRequiredError, UnsupportedChainError, } from './errors.js';
 export { Incentives } from './incentives/incentives.js';
 export { Exit } from './exits/exit.js';
 export { ObolSplits } from './splits/splits.js';
 export { EOA } from './eoa/eoa.js';
+export { blsVerify } from './blsUtils.js';
 /**
- * Obol sdk Client can be used for creating, managing and activating distributed validators.
+ * Primary entrypoint for the Obol SDK. Use this class to create, manage,
+ * and activate Distributed Validators via the Obol API.
+ *
+ * All operations are namespaced under the client instance:
+ * - `client.incentives.*`  – claim and query Obol incentives
+ * - `client.exit.*`        – validate and recombine voluntary exit signatures
+ * - `client.splits.*`      – deploy OVM / SplitV2 reward-splitting contracts
+ * - `client.eoa.*`         – EOA withdrawals and batch deposits
+ *
+ * Cluster lifecycle helpers live directly on the client:
+ * - {@link Client.acceptObolLatestTermsAndConditions}
+ * - {@link Client.createClusterDefinition}
+ * - {@link Client.acceptClusterDefinition}
+ * - {@link Client.getClusterDefinition}
+ * - {@link Client.getClusterLock}
+ * - {@link Client.getClusterLockByHash}
+ * - {@link Client.createObolRewardsSplit}
+ * - {@link Client.createObolTotalSplit}
+ * - {@link Client.getOWRTranches}
+ *
+ * Supported networks (by `chainId`): Mainnet (1), Hoodi (560048),
+ * Gnosis (100), Sepolia (11155111).
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@obolnetwork/obol-sdk";
+ * import { Wallet } from "ethers";
+ *
+ * const signer = new Wallet(process.env.PRIVATE_KEY!);
+ * const client = new Client({ chainId: 560048 }, signer);
+ *
+ * // 1. Accept terms (required once before creating/updating data)
+ * await client.acceptObolLatestTermsAndConditions();
+ *
+ * // 2. Create a cluster definition
+ * const configHash = await client.createClusterDefinition({
+ *   name: "my-cluster",
+ *   operators: [{ address: "0x..." }],
+ *   validators: [{
+ *     fee_recipient_address: "0x...",
+ *     withdrawal_address: "0x...",
+ *   }],
+ * });
+ *
+ * // 3. Retrieve the definition
+ * const def = await client.getClusterDefinition(configHash);
+ * ```
  */
 export declare class Client extends Base {
-    /**
-     * The signer used for signing transactions.
-     */
     private readonly signer;
     /**
-     * The incentives module, responsible for managing Obol tokens distribution.
-     * @type {Incentives}
+     * Incentives module – claim and query Obol incentive rewards.
+     *
+     * @see {@link Incentives}
      */
     incentives: Incentives;
     /**
-     * The exit module, responsible for managing exit validation.
-     * @type {Exit}
+     * Exit module – verify partial exit signatures and recombine exit blobs
+     * for distributed validator voluntary exits.
+     *
+     * @see {@link Exit}
      */
     exit: Exit;
     /**
-     * The splits module, responsible for managing splits.
-     * @type {ObolSplits}
+     * Splits module – deploy OVM and SplitV2 contracts for reward/principal
+     * splitting, request withdrawals, and deposit to OVM contracts.
+     *
+     * @see {@link ObolSplits}
      */
     splits: ObolSplits;
     /**
-     * The eoa module, responsible for managing EOA operations.
-     * @type {EOA}
+     * EOA module – request withdrawals and batch-deposit validators
+     * via Externally Owned Account contracts.
+     *
+     * @see {@link EOA}
      */
     eoa: EOA;
     /**
-     * The blockchain provider, used to interact with the network.
-     * It can be null, undefined, or a valid provider instance and defaults to the Signer provider if Signer is passed.
+     * The blockchain provider used for on-chain reads.
+     * Defaults to `signer.provider` when a signer is supplied.
      */
     provider: ProviderType | undefined | null;
     /**
-     * @param config - Client configurations
-     * @param config.baseUrl - obol-api url
-     * @param config.chainId - Blockchain network ID
-     * @param signer - ethersJS Signer
-     * @returns Obol-SDK Client instance
-     *
-     * An example of how to instantiate obol-sdk Client:
-     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L29)
+     * Creates a new Obol SDK client.
+     *
+     * @param config - Client configuration object.
+     * @param config.baseUrl - Obol API base URL. Defaults to `https://api.obol.tech`.
+     * @param config.chainId - Target chain ID. Defaults to `560048` (Hoodi).
+     *   Supported: 1 (Mainnet), 560048 (Hoodi), 100 (Gnosis), 11155111 (Sepolia).
+     * @param signer - An ethers `Wallet` or `JsonRpcSigner`. Required for any
+     *   write operation (creating clusters, deploying splits, claiming incentives).
+     *   Read-only operations (`getClusterDefinition`, `getClusterLock`) work without a signer.
+     * @param provider - An ethers `Provider`. If omitted, falls back to `signer.provider`.
+     *
+     * @example
+     * ```typescript
+     * // Minimal read-only client (no signer)
+     * const readClient = new Client({ chainId: 1 });
+     * const def = await readClient.getClusterDefinition(configHash);
+     *
+     * // Full client with signer for write operations
+     * const client = new Client({ chainId: 560048 }, signer);
+     * ```
      */
     constructor(config: {
         baseUrl?: string;
         chainId?: number;
     }, signer?: SignerType, provider?: ProviderType);
     /**
-     * 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.
+     * Accepts the latest Obol terms and conditions.
+     *
+     * **Must be called once** before any write operation
+     * (`createClusterDefinition`, `acceptClusterDefinition`, etc.).
+     * Calling it again after acceptance throws a {@link ConflictError}.
+     *
+     * - Requires a `signer` to be provided at client construction.
+     * - Signs an EIP-712 typed-data message; no on-chain transaction is sent.
+     * - Idempotent per signer address: once accepted, subsequent calls throw `ConflictError`.
      *
-     * An example of how to use acceptObolLatestTermsAndConditions:
-     * [acceptObolLatestTermsAndConditions](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L44)
+     * @returns A success message string from the Obol API.
+     * @throws {SignerRequiredError} If no signer was provided to the client.
+     * @throws {ConflictError} If the terms were already accepted by this address.
+     *
+     * @example
+     * ```typescript
+     * const message = await client.acceptObolLatestTermsAndConditions();
+     * console.log(message); // "Terms and conditions accepted successfully"
+     * ```
      */
     acceptObolLatestTermsAndConditions(): Promise<string>;
     /**
-     * Deploys OWR and Splitter Proxy.
+     * Deploys an Optimistic Withdrawal Recipient (OWR) and a Splitter Proxy contract.
+     *
+     * Use this when the **principal** goes to a single address and only **rewards**
+     * are split among recipients. For splitting both principal and rewards, see
+     * {@link Client.createObolTotalSplit}.
      *
-     * @remarks
-     * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
-     * and not pushed to version control.
+     * - Requires a `signer` with ETH to pay deployment gas.
+     * - Sends one or more on-chain transactions (irreversible).
+     * - Automatically appends the Obol Retroactive Funding (RAF) recipient at the
+     *   configured percentage (default 1%).
+     * - Only supported on Mainnet (1) and Hoodi (560048).
      *
-     * @param {RewardsSplitPayload} rewardsSplitPayload - Data needed to deploy owr and splitter.
-     * @returns {Promise<ClusterValidator>} owr address as withdrawal address and splitter as fee recipient
+     * @param rewardsSplitPayload - Configuration for the OWR and splitter deployment.
+     * @returns The deployed OWR address as `withdrawal_address` and the
+     *   splitter proxy address as `fee_recipient_address`.
+     * @throws {SignerRequiredError} If no signer was provided.
+     * @throws {UnsupportedChainError} If the chain does not support splitters.
      *
-     * An example of how to use createObolRewardsSplit:
-     * [createObolRewardsSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L141)
+     * @example
+     * ```typescript
+     * const { withdrawal_address, fee_recipient_address } =
+     *   await client.createObolRewardsSplit({
+     *     splitRecipients: [
+     *       { account: "0xOperator1...", percentAllocation: 50 },
+     *       { account: "0xOperator2...", percentAllocation: 49 },
+     *     ],
+     *     principalRecipient: "0xPrincipalAddress...",
+     *     etherAmount: 32,
+     *   });
+     * ```
      */
     createObolRewardsSplit({ splitRecipients, principalRecipient, etherAmount, ObolRAFSplit, distributorFee, controllerAddress, recoveryAddress, }: RewardsSplitPayload): Promise<ClusterValidator>;
     /**
-     * Deploys Splitter Proxy.
+     * Deploys a Splitter Proxy contract that splits **both principal and rewards**.
+     *
+     * Unlike {@link Client.createObolRewardsSplit}, this method does not deploy an
+     * OWR – the splitter address is used as both `withdrawal_address` and
+     * `fee_recipient_address`.
      *
-     * @remarks
-     * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
-     * and not pushed to version control.
+     * - Requires a `signer` with ETH to pay deployment gas.
+     * - Sends an on-chain transaction if the splitter is not already deployed (irreversible).
+     * - If the predicted splitter is already deployed, returns the existing address without
+     *   sending a transaction (idempotent).
+     * - Automatically appends the Obol RAF recipient.
+     * - Only supported on Mainnet (1) and Hoodi (560048).
      *
-     * @param {TotalSplitPayload} totalSplitPayload - Data needed to deploy splitter if it doesnt exist.
-     * @returns {Promise<ClusterValidator>} splitter address as withdrawal address and splitter as fee recipient too
+     * @param totalSplitPayload - Configuration for the splitter deployment.
+     * @returns The splitter address as both `withdrawal_address` and `fee_recipient_address`.
+     * @throws {SignerRequiredError} If no signer was provided.
+     * @throws {UnsupportedChainError} If the chain does not support splitters.
+     * @throws {Error} If required on-chain factory contracts are unavailable.
      *
-     * An example of how to use createObolTotalSplit:
-     * [createObolTotalSplit](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L168)
+     * @example
+     * ```typescript
+     * const { withdrawal_address, fee_recipient_address } =
+     *   await client.createObolTotalSplit({
+     *     splitRecipients: [
+     *       { account: "0xOperator1...", percentAllocation: 50 },
+     *       { account: "0xOperator2...", percentAllocation: 49.9 },
+     *     ],
+     *   });
+     * // withdrawal_address === fee_recipient_address (same splitter)
+     * ```
      */
     createObolTotalSplit({ splitRecipients, ObolRAFSplit, distributorFee, controllerAddress, }: TotalSplitPayload): Promise<ClusterValidator>;
     /**
-     * Read OWR Tranches.
+     * Reads the tranches of a deployed Optimistic Withdrawal Recipient (OWR) contract.
      *
-     * @remarks
-     * **⚠️ Important:**  If you're storing the private key in an `.env` file, ensure it is securely managed
-     * and not pushed to version control.
+     * Returns the principal recipient, reward recipient, and staked principal amount
+     * configured in the OWR. This is a read-only on-chain call (no transaction sent).
      *
-     * @param {ETH_ADDRESS} owrAddress - Address of the Deployed OWR Contract
-     * @returns {Promise<OWRTranches>} owr tranch information about principal and reward reciepient, as well as the principal amount
+     * - Requires a `signer` (for provider access).
      *
+     * @param owrAddress - The Ethereum address of the deployed OWR contract.
+     * @returns The OWR tranche data: `principalRecipient`, `rewardRecipient`, and `amountOfPrincipalStake`.
+     * @throws {SignerRequiredError} If no signer was provided.
+     *
+     * @example
+     * ```typescript
+     * const tranches = await client.getOWRTranches("0xOWRAddress...");
+     * console.log(tranches.principalRecipient);
+     * console.log(tranches.rewardRecipient);
+     * console.log(tranches.amountOfPrincipalStake);
+     * ```
      */
     getOWRTranches(owrAddress: ETH_ADDRESS): Promise<OWRTranches>;
     /**
-     * Creates a cluster definition which contains cluster configuration.
-     * @param {ClusterPayload} newCluster - The new unique cluster.
-     * @returns {Promise<string>} config_hash.
-     * @throws On duplicate entries, missing or wrong cluster keys.
+     * Creates a new cluster definition and registers it with the Obol API.
+     *
+     * A cluster definition describes the operators, validators, and configuration
+     * for a Distributed Key Generation (DKG) ceremony. After creation, each operator
+     * must call {@link Client.acceptClusterDefinition} to join.
+     *
+     * - Requires {@link Client.acceptObolLatestTermsAndConditions} to have been called first.
+     * - Requires a `signer`.
+     * - The `config_hash` returned is the unique identifier for this cluster.
+     * - Threshold is automatically set to `ceil(2/3 * operators.length)`.
+     * - Creating a duplicate cluster throws a {@link ConflictError}.
+     *
+     * @param newCluster - The cluster configuration payload.
+     * @returns The `config_hash` string that uniquely identifies this cluster definition.
+     * @throws {SignerRequiredError} If no signer was provided.
+     * @throws {ConflictError} If an identical cluster definition already exists.
      *
-     * An example of how to use createClusterDefinition:
-     * [createObolCluster](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L59)
+     * @example
+     * ```typescript
+     * const configHash = await client.createClusterDefinition({
+     *   name: "my-dvt-cluster",
+     *   operators: [{ address: "0xOp1..." }, { address: "0xOp2..." }],
+     *   validators: [{
+     *     fee_recipient_address: "0xFeeRecipient...",
+     *     withdrawal_address: "0xWithdrawal...",
+     *   }],
+     * });
+     * console.log("Cluster created:", configHash);
+     * ```
      */
     createClusterDefinition(newCluster: ClusterPayload): Promise<string>;
     /**
-     * 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<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#L106)
+     * Accepts (joins) an existing cluster definition as an operator.
+     *
+     * Each operator in the cluster must call this method with their ENR and the
+     * cluster's `config_hash` to signal readiness for the DKG ceremony.
+     *
+     * - Requires a `signer` (the operator's address is derived from it).
+     * - Signs two EIP-712 messages: one for the config hash, one for the ENR.
+     * - The operator must be listed in the cluster definition's `operators` array.
+     *
+     * @param operatorPayload - Operator data. Must include `enr` (Ethereum Node Record)
+     *   and `version` at minimum.
+     * @param configHash - The `config_hash` returned by {@link Client.createClusterDefinition}.
+     * @returns The updated cluster definition with the operator's acceptance recorded.
+     * @throws {SignerRequiredError} If no signer was provided.
+     *
+     * @example
+     * ```typescript
+     * const updatedDef = await client.acceptClusterDefinition(
+     *   { enr: "enr:-LK4Q...", version: "v1.10.0" },
+     *   configHash,
+     * );
+     * ```
      */
     acceptClusterDefinition(operatorPayload: OperatorPayload, configHash: string): Promise<ClusterDefinition>;
     /**
-     * @param configHash - The configuration hash returned in createClusterDefinition
-     * @returns {Promise<ClusterDefinition>} The  cluster definition for config hash
-     * @throws On not found config hash.
+     * Retrieves a cluster definition by its configuration hash.
+     *
+     * This is a read-only API call – no signer is required.
      *
-     * An example of how to use getClusterDefinition:
-     * [getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L74)
+     * @param configHash - The `config_hash` returned by {@link Client.createClusterDefinition}.
+     * @returns The full cluster definition including operators, validators, and metadata.
+     * @throws {Error} If no cluster definition exists for the given hash (404).
+     *
+     * @example
+     * ```typescript
+     * const definition = await client.getClusterDefinition(configHash);
+     * console.log(definition.name, definition.operators.length);
+     * ```
      */
     getClusterDefinition(configHash: string): Promise<ClusterDefinition>;
     /**
-     * @param configHash - The configuration hash in cluster-definition
-     * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
-     * @throws On not found cluster definition or lock.
+     * Retrieves a cluster lock by the cluster's configuration hash.
+     *
+     * A cluster lock is generated after a successful DKG ceremony and contains
+     * the distributed validators, their public key shares, and deposit data.
+     * This is a read-only API call – no signer is required.
      *
-     * An example of how to use getClusterLock:
-     * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L89)
+     * @param configHash - The `config_hash` from the cluster definition.
+     * @returns The cluster lock including distributed validators and deposit data.
+     * @throws {Error} If no lock exists for the given config hash (DKG not yet complete, or not found).
+     *
+     * @example
+     * ```typescript
+     * const lock = await client.getClusterLock(configHash);
+     * console.log(lock.distributed_validators.length);
+     * console.log(lock.lock_hash);
+     * ```
      */
     getClusterLock(configHash: string): Promise<ClusterLock>;
     /**
-     * @param lockHash - The configuration hash in cluster-definition
-     * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
-     * @throws On not found cluster definition or lock.
+     * Retrieves a cluster lock by its lock hash (as opposed to config hash).
+     *
+     * Use this when you have the `lock_hash` directly rather than the `config_hash`.
+     * This is a read-only API call – no signer is required.
+     *
+     * @param lockHash - The `lock_hash` from a cluster lock.
+     * @returns The cluster lock including distributed validators and deposit data.
+     * @throws {Error} If no lock exists for the given lock hash (not found).
      *
+     * @example
+     * ```typescript
+     * const lock = await client.getClusterLockByHash(lockHash);
+     * console.log(lock.cluster_definition.name);
+     * ```
      */
     getClusterLockByHash(lockHash: string): Promise<ClusterLock>;
 }

package/dist/types/src/services.d.ts

@@ -1,12 +1,31 @@
 import { type SafeRpcUrl, type ClusterLock } from './types.js';
 /**
- * Verifies Cluster Lock's validity.
- * @param lock - cluster lock
- * @param safeRpcUrl - optional safeRpcUrl for safe wallet verification
- * @returns {Promise<{ result: 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#L127)
+ * Verifies the cryptographic validity of a cluster lock.
+ *
+ * Checks all operator signatures, config hashes, and definition hashes within
+ * the lock. Supports both EOA and Safe Wallet signatures.
+ *
+ * This is a standalone utility – it does **not** require a `Client` instance.
+ *
+ * **Charon:** this covers cryptographic and structural checks in this SDK only.
+ * Charon adds further runtime/protocol rules. `true` here does not guarantee
+ * Charon will accept the lock; use Charon or its supported tooling as the
+ * final gate before operating a cluster.
+ *
+ * @param lock - The cluster lock object (e.g. from {@link Client.getClusterLock}).
+ * @param safeRpcUrl - Optional RPC URL for Safe Wallet signature verification.
+ *   If omitted, falls back to the `RPC_MAINNET` / `RPC_HOODI` / etc. env vars.
+ * @returns `true` if the lock is cryptographically valid; `false` if invalid
+ *   (e.g. missing keys, invalid signatures, hash mismatches) or on any error.
+ *
+ * @example
+ * ```typescript
+ * import { validateClusterLock, Client } from "@obolnetwork/obol-sdk";
+ *
+ * const configHash = "0x..."; // your cluster config hash
+ * const client = new Client({ chainId: 560048 });
+ * const lock = await client.getClusterLock(configHash);
+ * const isValid = await validateClusterLock(lock);
+ * ```
  */
 export declare const validateClusterLock: (lock: ClusterLock, safeRpcUrl?: SafeRpcUrl) => Promise<boolean>;