@obolnetwork/obol-sdk 2.12.2 → 2.12.5

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

@@ -1,7 +1,9 @@
 import {
   isValidClusterLock
-} from "../chunk-T74RX3N2.js";
-import "../chunk-YSXFCSVK.js";
+} from "../chunk-L2GZF5CQ.js";
+import {
+  ClusterLockValidationTimeoutError
+} from "../chunk-BJWBUH75.js";
 import "../chunk-LOSYOJC3.js";
 
 // src/verification/clusterLockValidationWorker.ts
@@ -11,7 +13,11 @@ if (parentPort) {
   const port = parentPort;
   void isValidClusterLock(input.lock, input.safeRpcUrl).then((ok) => {
     port.postMessage(ok);
-  }).catch(() => {
+  }).catch((err) => {
+    if (err instanceof ClusterLockValidationTimeoutError) {
+      port.postMessage({ validationTimeoutMs: err.timeoutMs });
+      return;
+    }
     port.postMessage(false);
   });
 }

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

@@ -1 +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":[]}
+{"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 { ClusterLockValidationTimeoutError } from '../errors.js';\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(err => {\n      if (err instanceof ClusterLockValidationTimeoutError) {\n        port.postMessage({ validationTimeoutMs: err.timeoutMs });\n        return;\n      }\n      port.postMessage(false);\n    });\n}\n"],"mappings":";;;;;;;;;AACA,SAAS,YAAY,kBAAkB;AAKvC,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,SAAO;AACZ,QAAI,eAAe,mCAAmC;AACpD,WAAK,YAAY,EAAE,qBAAqB,IAAI,UAAU,CAAC;AACvD;AAAA,IACF;AACA,SAAK,YAAY,KAAK;AAAA,EACxB,CAAC;AACL;","names":[]}

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

@@ -4,7 +4,7 @@ import {
   verifyBatchParallel,
   verifyBlsChecksParallel,
   verifySharesBinding
-} from "../chunk-YSXFCSVK.js";
+} from "../chunk-BJWBUH75.js";
 import "../chunk-LOSYOJC3.js";
 export {
   validateClusterLockInWorker,

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

@@ -25,24 +25,34 @@ 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**).
- */
 /**
  * Thrown when {@link Client} is constructed with a baseUrl that is not an
- * an allowed Obol API base URL (see {@link ALLOWED_OBOL_API_BASE_URLS}).
+ * allowed Obol API base URL (see {@link ALLOWED_OBOL_API_BASE_URLS}).
  */
 export declare class InvalidBaseUrlError extends Error {
     name: string;
     constructor(message: string);
 }
+/**
+ * Thrown when lock validation exceeds a worker time limit (large clusters).
+ * HTTP gateways should respond with **504**; distinct from crypto failure
+ * (`validateClusterLock` returning **false** → **400**).
+ */
 export declare class ClusterLockValidationTimeoutError extends Error {
     readonly timeoutMs: number;
     name: string;
     /**
-     * @param timeoutMs - Same value as SDK whole-lock validation worker timeout.
+     * @param timeoutMs - Worker deadline that was exceeded (`VALIDATION_WORKER_TIMEOUT_MS`
+     *   for the whole-lock worker, `WORKER_TIMEOUT_MS` for per-chunk BLS workers).
      */
     constructor(timeoutMs: number);
 }
+/**
+ * Thrown when too many `validateClusterLock` calls are already in flight.
+ * HTTP gateways should respond with **503**; clients should retry with backoff.
+ */
+export declare class ClusterLockValidationBusyError extends Error {
+    readonly maxConcurrent: number;
+    name: string;
+    constructor(maxConcurrent: 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, ClusterLockValidationTimeoutError, InvalidBaseUrlError, SignerRequiredError, UnsupportedChainError, } from './errors.js';
+export { ConflictError, ClusterLockValidationBusyError, ClusterLockValidationTimeoutError, InvalidBaseUrlError, SignerRequiredError, UnsupportedChainError, } from './errors.js';
 export { ALLOWED_OBOL_API_BASE_URLS } from './base.js';
 export { Incentives } from './incentives/incentives.js';
 export { Exit } from './exits/exit.js';

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

@@ -17,9 +17,12 @@ import { type SafeRpcUrl, type ClusterLock } from './types.js';
  *   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).
- * @throws `ClusterLockValidationTimeoutError` when whole-lock validation
- *   exceeds the SDK worker deadline (typically large clusters). HTTP APIs should map
- *   this to **504 Gateway Timeout**.
+ * @throws {@link ClusterLockValidationTimeoutError} when validation exceeds a
+ *   worker deadline (whole-lock or per-chunk BLS workers on large clusters).
+ *   HTTP APIs should map this to **504 Gateway Timeout**, not **400**.
+ * @throws {@link ClusterLockValidationBusyError} when concurrent validations exceed
+ *   `OBOL_SDK_MAX_CONCURRENT_LOCK_VALIDATIONS` (default **2**; set `0` for unlimited).
+ *   HTTP APIs should map this to **503 Service Unavailable**.
  *
  * @example
  * ```typescript

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

@@ -1,4 +1,8 @@
 import type { BlsSignatureCheck, ClusterLock, SafeRpcUrl } from '../types.js';
+/** Posted from clusterLockValidationWorker when a nested BLS worker times out. */
+export type LockValidationWorkerTimeoutReply = {
+    validationTimeoutMs: number;
+};
 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>;

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

@@ -0,0 +1,11 @@
+/**
+ * Max in-flight `validateClusterLock` calls per process.
+ * `0` = unlimited (e.g. tests: `OBOL_SDK_MAX_CONCURRENT_LOCK_VALIDATIONS=0`).
+ * Default `2` — tune via env for host CPU (obol-api should set in `.env`).
+ */
+export declare function getMaxConcurrentLockValidations(): number;
+/**
+ * Limits parallel lock validation CPU/worker usage process-wide.
+ * Rejects immediately when at capacity (no queue — avoids memory growth under flood).
+ */
+export declare function withLockValidationConcurrency<T>(fn: () => Promise<T>): Promise<T>;

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/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/baseUrl.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"}
+{"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","../../src/verification/validationConcurrency.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obolnetwork/obol-sdk",
-  "version": "2.12.2",
+  "version": "2.12.5",
   "description": "A package for creating Distributed Validators using the Obol API.",
   "bugs": {
     "url": "https://github.com/obolnetwork/obol-sdk/issues"
@@ -15,7 +15,7 @@
     "build:clean": "rm -rf ./dist",
     "build": "npm-run-all build:clean build:tsup",
     "build:tsup": "tsup && tsc -b ./tsconfig.types.json",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest test/**/**.spec.ts --testPathIgnorePatterns=test/sdk-package/",
+    "test": "NODE_OPTIONS=--experimental-vm-modules OBOL_SDK_MAX_CONCURRENT_LOCK_VALIDATIONS=0 jest test/**/**.spec.ts --testPathIgnorePatterns=test/sdk-package/",
     "generate-typedoc": "typedoc",
     "npm:publish": "npm publish --tag latest",
     "npm:publish:next": "npm publish --tag next",