@obolnetwork/obol-sdk 2.11.13 → 2.12.1

package/dist/esm/src/verification/clusterLockValidationWorker.js

@@ -0,0 +1,18 @@
+import {
+  isValidClusterLock
+} from "../chunk-5ASVONSJ.js";
+import "../chunk-RYTIXFRX.js";
+import "../chunk-LOSYOJC3.js";
+
+// src/verification/clusterLockValidationWorker.ts
+import { parentPort, workerData } from "worker_threads";
+var input = workerData;
+if (parentPort) {
+  const port = parentPort;
+  void isValidClusterLock(input.lock, input.safeRpcUrl).then((ok) => {
+    port.postMessage(ok);
+  }).catch(() => {
+    port.postMessage(false);
+  });
+}
+//# sourceMappingURL=clusterLockValidationWorker.js.map

package/dist/esm/src/verification/clusterLockValidationWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/verification/clusterLockValidationWorker.ts"],"sourcesContent":["// Runs isValidClusterLock in a worker thread so obol-api's main thread stays responsive.\nimport { parentPort, workerData } from 'node:worker_threads';\nimport type { ClusterLock, SafeRpcUrl } from '../types.js';\nimport { isValidClusterLock } from './common.js';\n\nconst input = workerData as {\n  lock: ClusterLock;\n  safeRpcUrl?: SafeRpcUrl;\n};\n\nif (parentPort) {\n  const port = parentPort;\n  void isValidClusterLock(input.lock, input.safeRpcUrl)\n    .then(ok => {\n      port.postMessage(ok);\n    })\n    .catch(() => {\n      port.postMessage(false);\n    });\n}\n"],"mappings":";;;;;;;AACA,SAAS,YAAY,kBAAkB;AAIvC,IAAM,QAAQ;AAKd,IAAI,YAAY;AACd,QAAM,OAAO;AACb,OAAK,mBAAmB,MAAM,MAAM,MAAM,UAAU,EACjD,KAAK,QAAM;AACV,SAAK,YAAY,EAAE;AAAA,EACrB,CAAC,EACA,MAAM,MAAM;AACX,SAAK,YAAY,KAAK;AAAA,EACxB,CAAC;AACL;","names":[]}

package/dist/esm/src/verification/lockWorker.js

@@ -0,0 +1,55 @@
+import {
+  blsAggregatePublicKeys,
+  blsAggregateSignatures,
+  blsRecoverDistributedPubkeyFromShares,
+  blsVerifyExtraShares,
+  blsVerifyMultiple
+} from "../chunk-LOSYOJC3.js";
+
+// src/verification/lockWorker.ts
+import { parentPort, workerData } from "worker_threads";
+import { fromHexString } from "@chainsafe/ssz";
+function verifyShareBindingChunk(input) {
+  const { shares, distributedKeys, threshold } = input;
+  if (shares.length !== distributedKeys.length) return false;
+  for (let i = 0; i < shares.length; i++) {
+    const sharesBytes = shares[i].map((s) => fromHexString(s));
+    const dkBytes = fromHexString(distributedKeys[i]);
+    const recovered = blsRecoverDistributedPubkeyFromShares(
+      sharesBytes,
+      threshold
+    );
+    if (!recovered) return false;
+    if (recovered.length !== dkBytes.length) return false;
+    for (let j = 0; j < recovered.length; j++) {
+      if (recovered[j] !== dkBytes[j]) return false;
+    }
+    if (!blsVerifyExtraShares(sharesBytes, threshold, dkBytes)) {
+      return false;
+    }
+  }
+  return true;
+}
+function verifyBatchChunk(input) {
+  return blsVerifyMultiple(
+    input.pubkeys,
+    input.messages,
+    blsAggregateSignatures(input.signatures)
+  );
+}
+function dispatch(input) {
+  if (input.mode === "shareBinding") return verifyShareBindingChunk(input);
+  if (input.mode === "verifyBatch") return verifyBatchChunk(input);
+  if (input.mode === "aggregatePubkeys") {
+    return blsAggregatePublicKeys(input.pubkeys);
+  }
+  return false;
+}
+if (parentPort) {
+  try {
+    parentPort.postMessage(dispatch(workerData));
+  } catch (e) {
+    parentPort.postMessage(false);
+  }
+}
+//# sourceMappingURL=lockWorker.js.map

package/dist/esm/src/verification/lockWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/verification/lockWorker.ts"],"sourcesContent":["// Worker entry point loaded by parallelPool via Node's worker_threads.\n//\n// Two modes (dispatched on workerData.mode):\n//   'shareBinding' — Lagrange + extra-share verification for a validator chunk.\n//   'verifyBatch'  — blsVerifyMultiple on a (pubkeys, messages, aggregateSig)\n//                    chunk of the deposit+builder batch.\n//   'aggregatePubkeys' — partial G1 aggregate of a pubkey chunk (for lock sig).\n//\n// shareBinding / verifyBatch return boolean; aggregatePubkeys returns bytes.\n\nimport { parentPort, workerData } from 'node:worker_threads';\nimport { fromHexString } from '@chainsafe/ssz';\nimport {\n  blsAggregatePublicKeys,\n  blsAggregateSignatures,\n  blsRecoverDistributedPubkeyFromShares,\n  blsVerifyExtraShares,\n  blsVerifyMultiple,\n} from '../blsUtils.js';\n\nexport interface ShareBindingInput {\n  mode: 'shareBinding';\n  shares: string[][];\n  distributedKeys: string[];\n  threshold: number;\n}\n\nexport interface VerifyBatchInput {\n  mode: 'verifyBatch';\n  pubkeys: Uint8Array[];\n  messages: Uint8Array[];\n  signatures: Uint8Array[];\n}\n\nexport interface AggregatePubkeysInput {\n  mode: 'aggregatePubkeys';\n  pubkeys: Uint8Array[];\n}\n\nexport type WorkerInput =\n  | ShareBindingInput\n  | VerifyBatchInput\n  | AggregatePubkeysInput;\n\nexport type WorkerResult = boolean | Uint8Array;\n\nfunction verifyShareBindingChunk(input: ShareBindingInput): boolean {\n  const { shares, distributedKeys, threshold } = input;\n  if (shares.length !== distributedKeys.length) return false;\n\n  for (let i = 0; i < shares.length; i++) {\n    const sharesBytes = shares[i].map(s => fromHexString(s));\n    const dkBytes = fromHexString(distributedKeys[i]);\n\n    const recovered = blsRecoverDistributedPubkeyFromShares(\n      sharesBytes,\n      threshold,\n    );\n    if (!recovered) return false;\n    if (recovered.length !== dkBytes.length) return false;\n    for (let j = 0; j < recovered.length; j++) {\n      if (recovered[j] !== dkBytes[j]) return false;\n    }\n    if (!blsVerifyExtraShares(sharesBytes, threshold, dkBytes)) {\n      return false;\n    }\n  }\n  return true;\n}\n\nfunction verifyBatchChunk(input: VerifyBatchInput): boolean {\n  return blsVerifyMultiple(\n    input.pubkeys,\n    input.messages,\n    blsAggregateSignatures(input.signatures),\n  );\n}\n\nfunction dispatch(input: WorkerInput): WorkerResult {\n  if (input.mode === 'shareBinding') return verifyShareBindingChunk(input);\n  if (input.mode === 'verifyBatch') return verifyBatchChunk(input);\n  if (input.mode === 'aggregatePubkeys') {\n    return blsAggregatePublicKeys(input.pubkeys);\n  }\n  return false;\n}\n\nif (parentPort) {\n  try {\n    parentPort.postMessage(dispatch(workerData as WorkerInput));\n  } catch {\n    parentPort.postMessage(false);\n  }\n}\n"],"mappings":";;;;;;;;;AAUA,SAAS,YAAY,kBAAkB;AACvC,SAAS,qBAAqB;AAmC9B,SAAS,wBAAwB,OAAmC;AAClE,QAAM,EAAE,QAAQ,iBAAiB,UAAU,IAAI;AAC/C,MAAI,OAAO,WAAW,gBAAgB,OAAQ,QAAO;AAErD,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,cAAc,OAAO,CAAC,EAAE,IAAI,OAAK,cAAc,CAAC,CAAC;AACvD,UAAM,UAAU,cAAc,gBAAgB,CAAC,CAAC;AAEhD,UAAM,YAAY;AAAA,MAChB;AAAA,MACA;AAAA,IACF;AACA,QAAI,CAAC,UAAW,QAAO;AACvB,QAAI,UAAU,WAAW,QAAQ,OAAQ,QAAO;AAChD,aAAS,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK;AACzC,UAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,EAAG,QAAO;AAAA,IAC1C;AACA,QAAI,CAAC,qBAAqB,aAAa,WAAW,OAAO,GAAG;AAC1D,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAkC;AAC1D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM;AAAA,IACN,uBAAuB,MAAM,UAAU;AAAA,EACzC;AACF;AAEA,SAAS,SAAS,OAAkC;AAClD,MAAI,MAAM,SAAS,eAAgB,QAAO,wBAAwB,KAAK;AACvE,MAAI,MAAM,SAAS,cAAe,QAAO,iBAAiB,KAAK;AAC/D,MAAI,MAAM,SAAS,oBAAoB;AACrC,WAAO,uBAAuB,MAAM,OAAO;AAAA,EAC7C;AACA,SAAO;AACT;AAEA,IAAI,YAAY;AACd,MAAI;AACF,eAAW,YAAY,SAAS,UAAyB,CAAC;AAAA,EAC5D,SAAQ;AACN,eAAW,YAAY,KAAK;AAAA,EAC9B;AACF;","names":[]}

package/dist/esm/src/verification/parallelPool.js

@@ -0,0 +1,16 @@
+import {
+  validateClusterLockInWorker,
+  verifyAggregateParallel,
+  verifyBatchParallel,
+  verifyBlsChecksParallel,
+  verifySharesBinding
+} from "../chunk-RYTIXFRX.js";
+import "../chunk-LOSYOJC3.js";
+export {
+  validateClusterLockInWorker,
+  verifyAggregateParallel,
+  verifyBatchParallel,
+  verifyBlsChecksParallel,
+  verifySharesBinding
+};
+//# sourceMappingURL=parallelPool.js.map

package/dist/esm/src/verification/parallelPool.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -1,4 +1,9 @@
 export declare function blsVerify(pubkey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+export declare function blsAggregatePublicKeys(pubkeys: Uint8Array[]): Uint8Array;
 export declare function blsVerifyAggregate(pubkeys: Uint8Array[], message: Uint8Array, signature: Uint8Array): boolean;
+/** Verify when the pubkey set is already aggregated to a single G1 key. */
+export declare function blsVerifyWithAggregatedPubkey(aggregatedPubkey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
 export declare function blsVerifyMultiple(pubkeys: Uint8Array[], messages: Uint8Array[], signature: Uint8Array): boolean;
 export declare function blsAggregateSignatures(signatures: Uint8Array[]): Uint8Array;
+export declare function blsRecoverDistributedPubkeyFromShares(pubshares: Uint8Array[], threshold: number): Uint8Array | null;
+export declare function blsVerifyExtraShares(pubshares: Uint8Array[], threshold: number, distributedPubkey: Uint8Array): boolean;

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

@@ -25,3 +25,16 @@ export declare class UnsupportedChainError extends Error {
     name: string;
     constructor(chainId: number, operation: string);
 }
+/**
+ * Thrown when full lock validation (`validateClusterLock` worker path) exceeds
+ * the worker time limit (large clusters). HTTP gateways should respond with
+ * **504**; this is distinct from cryptographic failure (**false** → **400**).
+ */
+export declare class ClusterLockValidationTimeoutError extends Error {
+    readonly timeoutMs: number;
+    name: string;
+    /**
+     * @param timeoutMs - Same value as SDK whole-lock validation worker timeout.
+     */
+    constructor(timeoutMs: number);
+}

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

@@ -9,7 +9,7 @@ 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 { ConflictError, ClusterLockValidationTimeoutError, SignerRequiredError, UnsupportedChainError, } from './errors.js';
 export { Incentives } from './incentives/incentives.js';
 export { Exit } from './exits/exit.js';
 export { ObolSplits } from './splits/splits.js';

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

@@ -16,7 +16,10 @@ import { type SafeRpcUrl, type ClusterLock } from './types.js';
  * @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.
+ *   (e.g. missing keys, invalid signatures, hash mismatches).
+ * @throws `ClusterLockValidationTimeoutError` when whole-lock validation
+ *   exceeds the SDK worker deadline (typically large clusters). HTTP APIs should map
+ *   this to **504 Gateway Timeout**.
  *
  * @example
  * ```typescript

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

@@ -241,6 +241,12 @@ export type BuilderRegistration = {
     /** BLS signature of the builder registration message. */
     signature: string;
 };
+/** Pubkey + message + signature checked together in batch BLS verification. */
+export type BlsSignatureCheck = {
+    pubkey: Uint8Array;
+    message: Uint8Array;
+    signature: Uint8Array;
+};
 /**
  * Required deposit data for validator activation
  */

package/dist/types/src/verification/clusterLockValidationWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/verification/common.d.ts

@@ -1,4 +1,4 @@
-import { type ClusterDefinition, type ClusterLock, type DepositData, type DistributedValidator, type SafeRpcUrl } from '../types.js';
+import { type BlsSignatureCheck, type ClusterDefinition, type ClusterLock, type DepositData, type DistributedValidator, type SafeRpcUrl } from '../types.js';
 /**
  * @param cluster The cluster configuration or the cluster definition
  * @param configOnly a boolean to indicate config hash or definition hash
@@ -11,21 +11,40 @@ export declare const clusterConfigOrDefinitionHash: (cluster: ClusterDefinition,
  * @returns The cluster lock hash in of the corresponding cluster lock
  */
 export declare const clusterLockHash: (clusterLock: ClusterLock) => string;
+export declare const depositDomainForFork: (forkVersion: string) => Uint8Array;
+export declare const builderDomainForFork: (forkVersion: string) => Uint8Array;
 /**
- * Verify deposit data withdrawal credintials and signature
- * @param {string} forkVersion - fork version in definition file.
- * @param {DistributedValidatorDto} validator - distributed validator.
- * @param {string} withdrawalAddress - withdrawal address in definition file.
- * @returns {boolean} - return if deposit data is valid.
+ * Structural deposit checks + signing root (no BLS). Used before batch BLS verify.
+ */
+export declare const validateDepositDataStructure: (distributedPublicKey: string, depositData: Partial<DepositData>, withdrawalAddress: string, forkVersion: string, compounding?: boolean, precomputedDepositDomain?: Uint8Array) => {
+    valid: boolean;
+    message: Uint8Array;
+};
+/** Deposit fields + BLS triple for batch verification. Returns null if structure is invalid. */
+export declare const depositBlsCheck: (distributedPublicKey: string, depositData: Partial<DepositData>, withdrawalAddress: string, forkVersion: string, compounding?: boolean, precomputedDepositDomain?: Uint8Array) => BlsSignatureCheck | null;
+/**
+ * Verify deposit data withdrawal credintials and signature (structure + BLS in one call).
+ * Prefer `depositBlsCheck` + batch verify in lock validation for large locks.
  */
 export declare const verifyDepositData: (distributedPublicKey: string, depositData: Partial<DepositData>, withdrawalAddress: string, forkVersion: string, compounding?: boolean) => {
     isValidDepositData: boolean;
     depositDataMsg: Uint8Array;
 };
-export declare const verifyBuilderRegistration: (validator: DistributedValidator, feeRecipientAddress: string, forkVersion: string) => {
+export declare const verifyBuilderRegistration: (validator: DistributedValidator, feeRecipientAddress: string, forkVersion: string, precomputedBuilderDomain?: Uint8Array) => {
     isValidBuilderRegistration: boolean;
     builderRegistrationMsg: Uint8Array;
 };
+/** Builder registration BLS triple for batch verification. Returns null if structure is invalid. */
+export declare const builderBlsCheck: (validator: DistributedValidator, feeRecipientAddress: string, forkVersion: string, precomputedBuilderDomain?: Uint8Array) => BlsSignatureCheck | null;
 export declare const verifyNodeSignatures: (clusterLock: ClusterLock) => boolean;
 export declare const signingRoot: (domain: Uint8Array, messageBuffer: Buffer) => Uint8Array;
+/**
+ * Returns true iff every validator's distributed_public_key is unique across
+ * the lock. Normalizes hex case (charon emits lowercase today, but mixed-case
+ * copies shouldn't sneak through). Exported so it can be unit-tested
+ * independently of the rest of validateClusterLock — a tampered lock that
+ * trips a downstream check (signature_aggregate, node sigs) cannot isolate
+ * this branch.
+ */
+export declare const hasUniqueDistributedKeys: (clusterLock: ClusterLock) => boolean;
 export declare const isValidClusterLock: (clusterLock: ClusterLock, safeRpcUrl?: SafeRpcUrl) => Promise<boolean>;

package/dist/types/src/verification/lockWorker.d.ts

@@ -0,0 +1,18 @@
+export interface ShareBindingInput {
+    mode: 'shareBinding';
+    shares: string[][];
+    distributedKeys: string[];
+    threshold: number;
+}
+export interface VerifyBatchInput {
+    mode: 'verifyBatch';
+    pubkeys: Uint8Array[];
+    messages: Uint8Array[];
+    signatures: Uint8Array[];
+}
+export interface AggregatePubkeysInput {
+    mode: 'aggregatePubkeys';
+    pubkeys: Uint8Array[];
+}
+export type WorkerInput = ShareBindingInput | VerifyBatchInput | AggregatePubkeysInput;
+export type WorkerResult = boolean | Uint8Array;

package/dist/types/src/verification/parallelPool.d.ts

@@ -0,0 +1,11 @@
+import type { BlsSignatureCheck, ClusterLock, SafeRpcUrl } from '../types.js';
+export declare function verifySharesBinding(shares: string[][], distributedKeys: string[], threshold: number): Promise<boolean>;
+/** Verify deposit + builder BLS signatures collected from `depositBlsCheck` / `builderBlsCheck`. */
+export declare function verifyBlsChecksParallel(checks: BlsSignatureCheck[]): Promise<boolean>;
+export declare function verifyBatchParallel(pubkeys: Uint8Array[], messages: Uint8Array[], signatures: Uint8Array[]): Promise<boolean>;
+export declare function verifyAggregateParallel(pubkeys: Uint8Array[], message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+/**
+ * Large locks: run full validation off the main thread (obol-api stays responsive).
+ * Returns null when workers are unavailable — caller should use sync validation.
+ */
+export declare function validateClusterLockInWorker(lock: ClusterLock, safeRpcUrl?: SafeRpcUrl): Promise<boolean | null>;

package/dist/types/test/verification/parallelPool.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tsconfig.types.tsbuildinfo

@@ -1 +1 @@
-{"root":["../../tsup.config.ts","../../src/ajv.ts","../../src/base.ts","../../src/blsUtils.ts","../../src/bytecodes.ts","../../src/constants.ts","../../src/errors.ts","../../src/index.ts","../../src/schema.ts","../../src/services.ts","../../src/types.ts","../../src/utils.ts","../../src/abi/BatchDeposit.ts","../../src/abi/MerkleDistributorWithDeadline.ts","../../src/abi/Multicall3.ts","../../src/abi/OVM.ts","../../src/abi/OWR.ts","../../src/abi/SplitMain.ts","../../src/abi/splitV2FactoryAbi.ts","../../src/eoa/eoa.ts","../../src/eoa/eoaHelpers.ts","../../src/exits/ethUtils.ts","../../src/exits/exit.ts","../../src/exits/verificationHelpers.ts","../../src/incentives/incentiveHelpers.ts","../../src/incentives/incentives.ts","../../src/splits/splitHelpers.ts","../../src/splits/splits.ts","../../src/verification/common.ts","../../src/verification/signature-validator.ts","../../src/verification/sszTypes.ts","../../src/verification/v1.10.0.ts","../../src/verification/v1.6.0.ts","../../src/verification/v1.7.0.ts","../../src/verification/v1.8.0.ts","../../test/fixtures.ts","../../test/client/ajv.spec.ts","../../test/client/methods.spec.ts","../../test/eoa/eoa.spec.ts","../../test/exit/ethUtils.spec.ts","../../test/exit/exit.spec.ts","../../test/exit/verificationHelpers.spec.ts","../../test/incentives/incentives.spec.ts","../../test/splits/splits.spec.ts"],"version":"5.9.3"}
+{"root":["../../tsup.config.ts","../../src/ajv.ts","../../src/base.ts","../../src/blsUtils.ts","../../src/bytecodes.ts","../../src/constants.ts","../../src/errors.ts","../../src/index.ts","../../src/schema.ts","../../src/services.ts","../../src/types.ts","../../src/utils.ts","../../src/abi/BatchDeposit.ts","../../src/abi/MerkleDistributorWithDeadline.ts","../../src/abi/Multicall3.ts","../../src/abi/OVM.ts","../../src/abi/OWR.ts","../../src/abi/SplitMain.ts","../../src/abi/splitV2FactoryAbi.ts","../../src/eoa/eoa.ts","../../src/eoa/eoaHelpers.ts","../../src/exits/ethUtils.ts","../../src/exits/exit.ts","../../src/exits/verificationHelpers.ts","../../src/incentives/incentiveHelpers.ts","../../src/incentives/incentives.ts","../../src/splits/splitHelpers.ts","../../src/splits/splits.ts","../../src/verification/clusterLockValidationWorker.ts","../../src/verification/common.ts","../../src/verification/lockWorker.ts","../../src/verification/parallelPool.ts","../../src/verification/signature-validator.ts","../../src/verification/sszTypes.ts","../../src/verification/v1.10.0.ts","../../src/verification/v1.6.0.ts","../../src/verification/v1.7.0.ts","../../src/verification/v1.8.0.ts","../../test/fixtures.ts","../../test/client/ajv.spec.ts","../../test/client/methods.spec.ts","../../test/eoa/eoa.spec.ts","../../test/exit/ethUtils.spec.ts","../../test/exit/exit.spec.ts","../../test/exit/verificationHelpers.spec.ts","../../test/incentives/incentives.spec.ts","../../test/splits/splits.spec.ts","../../test/verification/parallelPool.spec.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "2.11.13",
+  "version": "2.12.1",
   "description": "A package for creating Distributed Validators using the Obol API.",
   "bugs": {
     "url": "https://github.com/obolnetwork/obol-sdk/issues"