@obolnetwork/obol-sdk 2.12.1 → 2.12.4

package/README.md

@@ -39,11 +39,13 @@ Checkout our [docs](https://docs.obol.org/docs/advanced/quickstart-sdk), [exampl
 ## Terms and Conditions
 To use obol-sdk and in order to be able to create a cluster definition or accept an invite to join a cluster, you must accept the [latest Obol terms and conditions](https://obol.org/terms.pdf) by calling acceptObolLatestTermsAndConditions.
 
-## ⚠️ Important Security Notice:
-If you're integrating this SDK with a **backend** (e.g., in Node.js), and you store a private key for executing splitter transactions, handle it with extreme caution. Ensure that:
+## Security
 
-- The private key is securely stored (e.g., in an `.env` file).
-- Never commit or push your `.env` file containing the private key to version control.
+**API host:** `baseUrl` must be one of `https://api.obol.tech`, `https://obol-api-nonprod-dev.dev.obol.tech`, or `https://obol-api-nonprod-qa.dev.obol.tech` (no path suffix). Endpoints are still called as `/v1/...` as before. Any other value throws `InvalidBaseUrlError`.
+
+**RPC URLs:** Set `RPC_MAINNET`, `RPC_HOODI`, etc. in your own app or pass an explicit provider/RPC to the client. The SDK does not load a `.env` file on import.
+
+**Private keys:** If you use a backend signer, store keys securely (KMS, HSM, or env vars your app loads explicitly). Never commit secrets to version control.
 
 ## ⚡️ Integration with Safe Wallet
 

package/dist/browser/src/index.js

@@ -98,7 +98,7 @@ import { v4 as uuidv4 } from "uuid";
 // package.json
 var package_default = {
   name: "@obolnetwork/obol-sdk",
-  version: "2.12.1",
+  version: "2.12.4",
   description: "A package for creating Distributed Validators using the Obol API.",
   bugs: {
     url: "https://github.com/obolnetwork/obol-sdk/issues"
@@ -113,7 +113,7 @@ var package_default = {
     "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",
@@ -176,7 +176,6 @@ var package_default = {
     "ajv-formats": "3.0.1",
     "ajv-keywords": "5.1.0",
     "cross-fetch": "4.1.0",
-    dotenv: "17.4.2",
     elliptic: "6.6.1",
     ethers: "6.16.0",
     semver: "7.7.4",
@@ -189,6 +188,7 @@ var package_default = {
     "@types/node": "24.12.2",
     "@types/semver": "7.7.1",
     "@types/uuid": "9.0.8",
+    dotenv: "17.4.2",
     "@typescript-eslint/eslint-plugin": "6.21.0",
     "@typescript-eslint/parser": "6.21.0",
     eslint: "8.57.1",
@@ -316,8 +316,6 @@ var MAINNET_SPLIT_V2_FACTORY_BYTECODE = "0x6080604090808252600480361015610015575
 var HOODI_SPLIT_V2_FACTORY_BYTECODE = "0x6080604090808252600480361015610015575f80fd5b5f3560e01c9182632556fa391461043c5750816380ebf0ab146102be5781639e317f121461027a578163cd6bc1211461023f578163e9889edd1461016d578163f79918b0146100de575063fc6119b11461006d575f80fd5b346100da575f7ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc3601126100da576020905173ffffffffffffffffffffffffffffffffffffffff7f000000000000000000000000f9c25250523df26343222fc46de932355b850c97168152f35b5f80fd5b82346100da577ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc916080833601126100da5780359267ffffffffffffffff84116100da5760809084360301126100da5761016573ffffffffffffffffffffffffffffffffffffffff916020946101526105e7565b61015a61060a565b91606435930161090f565b915191168152f35b82346100da5760209073ffffffffffffffffffffffffffffffffffffffff6101656101a061019a3661062d565b91610b37565b309061023a7f000000000000000000000000f9c25250523df26343222fc46de932355b850c9790604051916c5af43d3d93803e605757fd5bf36051526044526f593da1005b3d3d3d3d363d3d37363d736030527f9e4ac34f21c619cefc926c8bd93b54bf5a39c7ab2127a895af1cc0691d7e3dff6020527060593d8160093d39f336602c57343d527f5f526071600f20916040525f606052565b610b7a565b82346100da576102546101a061019a3661062d565b803b151573ffffffffffffffffffffffffffffffffffffffff8351921682526020820152f35b82346100da5760207ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc3601126100da57602091355f525f8252805f20549051908152f35b82346100da577ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc9181833601126100da5780359267ffffffffffffffff84116100da5760809084360301126100da5761016561039c73ffffffffffffffffffffffffffffffffffffffff9261034a6103766103376105e7565b875192839160209a8b84019601866107c7565b037fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe08101835282610858565b519020805f525f8652845f205490855191878301528682526103978261083c565b6108c2565b848151910120309061023a7f000000000000000000000000f9c25250523df26343222fc46de932355b850c9790604051916c5af43d3d93803e605757fd5bf36051526044526f593da1005b3d3d3d3d363d3d37363d736030527f9e4ac34f21c619cefc926c8bd93b54bf5a39c7ab2127a895af1cc0691d7e3dff6020527060593d8160093d39f336602c57343d527f5f526071600f20916040525f606052565b9083346100da577ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc6060813601126100da5782359067ffffffffffffffff82116100da5760809082850192360301126100da576104976105e7565b6105286104a261060a565b6104e4602097888101906104bb8161034a888a866107c7565b519020805f525f8952865f20908154916001830190558751918a8301528982526103978261083c565b73ffffffffffffffffffffffffffffffffffffffff9281898593519101207f000000000000000000000000f9c25250523df26343222fc46de932355b850c97610aae565b1695863b156100da575f858592610569895194859384937fbaa7fda400000000000000000000000000000000000000000000000000000000855284016107c7565b0381838b5af180156105dd57928795927fb3ec24e9259e438f9917b49f27c0dd89a11b7626cb63e6fc977863c0b26a681b95926105ba956105ce575b508188519586956060875260608701906106f5565b93168a85015216868301520390a251908152f35b6105d7906107fb565b8a6105a5565b86513d5f823e3d90fd5b6024359073ffffffffffffffffffffffffffffffffffffffff821682036100da57565b6044359073ffffffffffffffffffffffffffffffffffffffff821682036100da57565b7ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc906060828201126100da576004359167ffffffffffffffff83116100da57826080920301126100da576004019060243573ffffffffffffffffffffffffffffffffffffffff811681036100da579060443590565b90357fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe1823603018112156100da57016020813591019167ffffffffffffffff82116100da578160051b360383136100da57565b6080820161070382806106a2565b608085529182905260a08401915f905b80821061078f5750505061072a60208301836106a2565b909284830360208601528183527f07ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff82116100da5760609160051b8094602085013760408101356040860152013561ffff81168091036100da5760606020940152010190565b90919283359073ffffffffffffffffffffffffffffffffffffffff82168092036100da57600191815260208091019401920190610713565b9073ffffffffffffffffffffffffffffffffffffffff6107f46020929594956040855260408501906106f5565b9416910152565b67ffffffffffffffff811161080f57604052565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b6040810190811067ffffffffffffffff82111761080f57604052565b90601f7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0910116810190811067ffffffffffffffff82111761080f57604052565b908151915f5b8381106108af575050015f815290565b806020809284010151818501520161089f565b61090d909291926108e160405194859260208401526040830190610899565b037fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe08101845283610858565b565b93929161091d838387610b37565b7f000000000000000000000000f9c25250523df26343222fc46de932355b850c976109bb308361023a8490604051916c5af43d3d93803e605757fd5bf36051526044526f593da1005b3d3d3d3d363d3d37363d736030527f9e4ac34f21c619cefc926c8bd93b54bf5a39c7ab2127a895af1cc0691d7e3dff6020527060593d8160093d39f336602c57343d527f5f526071600f20916040525f606052565b803b610aa55750906109cc91610aae565b9473ffffffffffffffffffffffffffffffffffffffff9283871694853b156100da57604051947fbaa7fda40000000000000000000000000000000000000000000000000000000086525f8680610a268688600484016107c7565b0381838b5af1948515610a9a577fc4cec5a1846f5c98dc275670618bfecffec4da2e7cba63760ef46f38c75d236e96610a7496610a8b575b50816040519687966080885260808801906106f5565b9416602086015216604084015260608301520390a2565b610a94906107fb565b5f610a5e565b6040513d5f823e3d90fd5b96505050505050565b9190604051926c5af43d3d93803e605757fd5bf36051526044526f593da1005b3d3d3d3d363d3d37363d736030527f9e4ac34f21c619cefc926c8bd93b54bf5a39c7ab2127a895af1cc0691d7e3dff6020527060593d8160093d39f336602c57343d527f5f526071600f5ff5916040525f6060528115610b2a57565b63301164255f526004601cfd5b6040519291610b4f9184916108e191602084016107c7565b610b7460206040518093610b668383018097610899565b908152038084520182610858565b51902090565b91909160ff5f5360355260601b60015260155260555f20905f60355256fea2646970667358221220edd55753c55f257991df670fc562cdf54adb62d710125933fc4a0a7afddbc02564736f6c63430008170033";
 
 // src/constants.ts
-import * as dotenv from "dotenv";
-dotenv.config();
 var CONFLICT_ERROR_MSG = "Conflict";
 var EIP712_DOMAIN_NAME = "Obol";
 var EIP712_DOMAIN_VERSION = "1";
@@ -526,40 +524,6 @@ var CAPELLA_FORK_MAPPING = {
   // Hoodi
 };
 
-// src/base.ts
-var Base = class {
-  constructor({
-    baseUrl = DEFAULT_BASE_URL,
-    chainId = DEFAULT_CHAIN_ID
-  }) {
-    this.baseUrl = baseUrl;
-    this.chainId = chainId;
-    this.fork_version = FORK_MAPPING[this.chainId];
-  }
-  request(endpoint, options) {
-    return __async(this, null, function* () {
-      const url = `${this.baseUrl}${endpoint}`;
-      const config2 = __spreadProps(__spreadValues({}, options), {
-        headers: __spreadValues({
-          "Content-Type": "application/json",
-          "User-Agent": `Obol-SDK/${SDK_VERSION}`
-        }, options == null ? void 0 : options.headers)
-      });
-      try {
-        const response = yield fetch(url, config2);
-        if (response.ok) {
-          return yield response.json();
-        } else {
-          const errorResponse = yield response.json();
-          throw errorResponse;
-        }
-      } catch (e) {
-        throw e;
-      }
-    });
-  }
-};
-
 // src/errors.ts
 var ConflictError = class _ConflictError extends Error {
   constructor() {
@@ -582,9 +546,17 @@ var UnsupportedChainError = class _UnsupportedChainError extends Error {
     Object.setPrototypeOf(this, _UnsupportedChainError.prototype);
   }
 };
+var InvalidBaseUrlError = class _InvalidBaseUrlError extends Error {
+  constructor(message2) {
+    super(message2);
+    this.name = "InvalidBaseUrlError";
+    Object.setPrototypeOf(this, _InvalidBaseUrlError.prototype);
+  }
+};
 var ClusterLockValidationTimeoutError = class _ClusterLockValidationTimeoutError extends Error {
   /**
-   * @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) {
     super(
@@ -595,6 +567,68 @@ var ClusterLockValidationTimeoutError = class _ClusterLockValidationTimeoutError
     Object.setPrototypeOf(this, _ClusterLockValidationTimeoutError.prototype);
   }
 };
+var ClusterLockValidationBusyError = class _ClusterLockValidationBusyError extends Error {
+  constructor(maxConcurrent) {
+    super(
+      `Too many cluster lock validations in progress (limit: ${maxConcurrent}). Retry later.`
+    );
+    this.maxConcurrent = maxConcurrent;
+    this.name = "ClusterLockValidationBusyError";
+    Object.setPrototypeOf(this, _ClusterLockValidationBusyError.prototype);
+  }
+};
+
+// src/base.ts
+var ALLOWED_OBOL_API_BASE_URLS = [
+  DEFAULT_BASE_URL,
+  "https://obol-api-nonprod-dev.dev.obol.tech",
+  "https://obol-api-nonprod-qa.dev.obol.tech"
+];
+var ALLOWED_BASE_URLS = new Set(ALLOWED_OBOL_API_BASE_URLS);
+function assertAllowedBaseUrl(baseUrl) {
+  let candidate = baseUrl.trim();
+  while (candidate.endsWith("/")) {
+    candidate = candidate.slice(0, -1);
+  }
+  if (!ALLOWED_BASE_URLS.has(candidate)) {
+    throw new InvalidBaseUrlError(
+      `baseUrl must be one of: ${ALLOWED_OBOL_API_BASE_URLS.join(", ")}`
+    );
+  }
+  return candidate;
+}
+var Base = class {
+  constructor({
+    baseUrl = DEFAULT_BASE_URL,
+    chainId = DEFAULT_CHAIN_ID
+  }) {
+    this.baseUrl = assertAllowedBaseUrl(baseUrl);
+    this.chainId = chainId;
+    this.fork_version = FORK_MAPPING[this.chainId];
+  }
+  request(endpoint, options) {
+    return __async(this, null, function* () {
+      const url = `${this.baseUrl}${endpoint}`;
+      const config = __spreadProps(__spreadValues({}, options), {
+        headers: __spreadValues({
+          "Content-Type": "application/json",
+          "User-Agent": `Obol-SDK/${SDK_VERSION}`
+        }, options == null ? void 0 : options.headers)
+      });
+      try {
+        const response = yield fetch(url, config);
+        if (response.ok) {
+          return yield response.json();
+        } else {
+          const errorResponse = yield response.json();
+          throw errorResponse;
+        }
+      } catch (e) {
+        throw e;
+      }
+    });
+  }
+};
 
 // src/verification/common.ts
 import { fromHexString as fromHexString6 } from "@chainsafe/ssz";
@@ -5254,6 +5288,9 @@ var MIN_KEYS_PER_WORKER_AGG = 100;
 var MIN_VALIDATORS_FOR_VALIDATION_WORKER = 50;
 var VALIDATION_WORKER_TIMEOUT_MS = 12e4;
 var WORKER_TIMEOUT_MS = 6e4;
+function isValidationTimeoutReply(msg) {
+  return typeof msg === "object" && msg !== null && "validationTimeoutMs" in msg && typeof msg.validationTimeoutMs === "number";
+}
 var MAX_CONCURRENT_WORKERS_CAP = 8;
 function maxConcurrentWorkers(numWorkers) {
   return Math.min(numWorkers, MAX_CONCURRENT_WORKERS_CAP);
@@ -5350,7 +5387,7 @@ function verifySharesSync(shares, distributedKeys, threshold) {
 }
 function runWorkerAggregatePubkeys(wt, workerFile, data) {
   return __async(this, null, function* () {
-    return yield new Promise((resolve) => {
+    return yield new Promise((resolve, reject) => {
       let settled = false;
       const worker = new wt.Worker(workerFile, { workerData: data });
       const finish = (result) => {
@@ -5361,7 +5398,11 @@ function runWorkerAggregatePubkeys(wt, workerFile, data) {
         resolve(result);
       };
       const timer = setTimeout(() => {
-        finish(null);
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        worker.terminate();
+        reject(new ClusterLockValidationTimeoutError(WORKER_TIMEOUT_MS));
       }, WORKER_TIMEOUT_MS);
       worker.once("message", (msg) => {
         finish(msg instanceof Uint8Array ? msg : null);
@@ -5377,7 +5418,7 @@ function runWorkerAggregatePubkeys(wt, workerFile, data) {
 }
 function runWorker(wt, workerFile, data) {
   return __async(this, null, function* () {
-    return yield new Promise((resolve) => {
+    return yield new Promise((resolve, reject) => {
       let settled = false;
       const worker = new wt.Worker(workerFile, { workerData: data });
       const finish = (result) => {
@@ -5388,7 +5429,11 @@ function runWorker(wt, workerFile, data) {
         resolve(result);
       };
       const timer = setTimeout(() => {
-        finish(false);
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        worker.terminate();
+        reject(new ClusterLockValidationTimeoutError(WORKER_TIMEOUT_MS));
       }, WORKER_TIMEOUT_MS);
       worker.once("message", (msg) => {
         finish(msg === true);
@@ -5532,15 +5577,7 @@ function validateClusterLockInWorker(lock, safeRpcUrl) {
       const worker = new wt.Worker(workerFile, {
         workerData: { lock, safeRpcUrl }
       });
-      let timer;
-      const finish = (result) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        worker.terminate();
-        resolve(result);
-      };
-      timer = setTimeout(() => {
+      const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
@@ -5549,7 +5586,22 @@ function validateClusterLockInWorker(lock, safeRpcUrl) {
           new ClusterLockValidationTimeoutError(VALIDATION_WORKER_TIMEOUT_MS)
         );
       }, VALIDATION_WORKER_TIMEOUT_MS);
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        worker.terminate();
+        resolve(result);
+      };
       worker.once("message", (msg) => {
+        if (isValidationTimeoutReply(msg)) {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          worker.terminate();
+          reject(new ClusterLockValidationTimeoutError(msg.validationTimeoutMs));
+          return;
+        }
         finish(msg === true);
       });
       worker.once("error", () => {
@@ -16174,6 +16226,9 @@ var isValidClusterLock = (clusterLock, safeRpcUrl) => __async(null, null, functi
     }
     return true;
   } catch (err) {
+    if (err instanceof ClusterLockValidationTimeoutError) {
+      throw err;
+    }
     return false;
   }
 });
@@ -19532,11 +19587,11 @@ var encodeCreateSplitV2DeterministicTxData = (splitParams, splitOwnerAddress, sa
   );
 };
 var getChainConfig = (chainId) => {
-  const config2 = CHAIN_CONFIGURATION[chainId];
-  if (!config2) {
+  const config = CHAIN_CONFIGURATION[chainId];
+  if (!config) {
     throw new Error(`Chain configuration not found for chain ID ${chainId}`);
   }
-  return config2;
+  return config;
 };
 var requestWithdrawalFromOVM = (_0) => __async(null, [_0], function* ({
   ovmAddress,
@@ -21114,15 +21169,40 @@ var EOA = class {
   }
 };
 
+// src/verification/validationConcurrency.ts
+function getMaxConcurrentLockValidations() {
+  const raw = define_process_env_default.OBOL_SDK_MAX_CONCURRENT_LOCK_VALIDATIONS;
+  if (raw === "0") return 0;
+  if (raw !== void 0 && raw !== "") {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 2;
+}
+var activeValidations = 0;
+function withLockValidationConcurrency(fn) {
+  return __async(this, null, function* () {
+    const max = getMaxConcurrentLockValidations();
+    if (max === 0) return yield fn();
+    if (activeValidations >= max) {
+      throw new ClusterLockValidationBusyError(max);
+    }
+    activeValidations++;
+    try {
+      return yield fn();
+    } finally {
+      activeValidations--;
+    }
+  });
+}
+
 // src/services.ts
 var validateClusterLock = (lock, safeRpcUrl) => __async(null, null, function* () {
-  try {
+  return yield withLockValidationConcurrency(() => __async(null, null, function* () {
     const inWorker = yield validateClusterLockInWorker(lock, safeRpcUrl);
     if (inWorker !== null) return inWorker;
     return yield isValidClusterLock(lock, safeRpcUrl);
-  } catch (err) {
-    throw err;
-  }
+  }));
 });
 
 // src/index.ts
@@ -21132,6 +21212,7 @@ var Client = class extends Base {
    *
    * @param config - Client configuration object.
    * @param config.baseUrl - Obol API base URL. Defaults to `https://api.obol.tech`.
+   *   Must match one of {@link ALLOWED_OBOL_API_BASE_URLS} (API paths use `/v1/...` separately).
    * @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
@@ -21149,8 +21230,8 @@ var Client = class extends Base {
    * const client = new Client({ chainId: 560048 }, signer);
    * ```
    */
-  constructor(config2, signer, provider) {
-    super(config2);
+  constructor(config, signer, provider) {
+    super(config);
     this.signer = signer;
     this.provider = provider != null ? provider : signer && "provider" in signer ? signer.provider : void 0;
     this.incentives = new Incentives(
@@ -21712,12 +21793,14 @@ var Client = class extends Base {
   }
 };
 export {
+  ALLOWED_OBOL_API_BASE_URLS,
   AVAILABLE_SPLITTER_CHAINS,
   CAPELLA_FORK_MAPPING,
   CHAIN_CONFIGURATION,
   CONFIG_VERSION,
   CONFLICT_ERROR_MSG,
   Client,
+  ClusterLockValidationBusyError,
   ClusterLockValidationTimeoutError,
   ConflictError,
   CreatorConfigHashSigningTypes,
@@ -21744,6 +21827,7 @@ export {
   FORK_NAMES,
   GENESIS_VALIDATOR_ROOT,
   Incentives,
+  InvalidBaseUrlError,
   OBOL_SDK_EMAIL,
   ObolSplits,
   OperatorConfigHashSigningTypes,