@lifi/sdk 4.0.0-beta.5 → 4.0.0-beta.7

package/dist/cjs/client/getClientStorage.js

@@ -28,7 +28,8 @@ const getClientStorage = (config) => {
 					_lifi_types.ChainType.EVM,
 					_lifi_types.ChainType.SVM,
 					_lifi_types.ChainType.UTXO,
-					_lifi_types.ChainType.MVM
+					_lifi_types.ChainType.MVM,
+					_lifi_types.ChainType.TVM
 				] });
 				_chainsUpdatedAt = Date.now();
 				updateRpcUrls();

package/dist/cjs/client/getClientStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"getClientStorage.js","names":["getRpcUrlsFromChains","ChainId","_getChains","ChainType"],"sources":["../../../src/client/getClientStorage.ts"],"sourcesContent":["import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'\nimport { _getChains } from '../actions/getChains.js'\nimport { getRpcUrlsFromChains } from '../core/utils.js'\nimport type { RPCUrls, SDKBaseConfig } from '../types/core.js'\n\n// 6 hours in milliseconds\nconst chainsRefreshInterval = 1000 * 60 * 60 * 6\n\nexport interface ClientStorage {\n  readonly needReset: boolean\n  setChains(chains: ExtendedChain[]): void\n  getChains(): Promise<ExtendedChain[]>\n  getRpcUrls(): Promise<RPCUrls>\n}\n\nexport const getClientStorage = (config: SDKBaseConfig): ClientStorage => {\n  let _chains = [] as ExtendedChain[]\n  let _rpcUrls = { ...config.rpcUrls } as RPCUrls\n  let _chainsUpdatedAt: number | undefined\n\n  const updateRpcUrls = () => {\n    _rpcUrls = { ...config.rpcUrls }\n    _rpcUrls = getRpcUrlsFromChains(_rpcUrls, _chains, [ChainId.SOL])\n  }\n\n  return {\n    get needReset() {\n      return (\n        !_chainsUpdatedAt ||\n        Date.now() - _chainsUpdatedAt >= chainsRefreshInterval\n      )\n    },\n    setChains(chains: ExtendedChain[]) {\n      _chains = chains\n      _chainsUpdatedAt = Date.now()\n      updateRpcUrls()\n    },\n    async getChains() {\n      // When preloadChains is false, SDK does not auto-fetch chains\n      // External consumer is responsible for calling setChains\n      if (!config.preloadChains) {\n        return _chains\n      }\n\n      if (this.needReset || !_chains.length) {\n        _chains = await _getChains(config, {\n          chainTypes: [\n            ChainType.EVM,\n            ChainType.SVM,\n            ChainType.UTXO,\n            ChainType.MVM,\n          ],\n        })\n        _chainsUpdatedAt = Date.now()\n        updateRpcUrls()\n      }\n      return _chains\n    },\n    async getRpcUrls() {\n      await this.getChains() // _rpcUrls is updated when needed\n      return _rpcUrls\n    },\n  }\n}\n"],"mappings":";;;;;AAMA,MAAM,wBAAwB,MAAO,KAAK,KAAK;AAS/C,MAAa,oBAAoB,WAAyC;CACxE,IAAI,UAAU,EAAE;CAChB,IAAI,WAAW,EAAE,GAAG,OAAO,SAAS;CACpC,IAAI;CAEJ,MAAM,sBAAsB;AAC1B,aAAW,EAAE,GAAG,OAAO,SAAS;AAChC,aAAWA,mBAAAA,qBAAqB,UAAU,SAAS,CAACC,YAAAA,QAAQ,IAAI,CAAC;;AAGnE,QAAO;EACL,IAAI,YAAY;AACd,UACE,CAAC,oBACD,KAAK,KAAK,GAAG,oBAAoB;;EAGrC,UAAU,QAAyB;AACjC,aAAU;AACV,sBAAmB,KAAK,KAAK;AAC7B,kBAAe;;EAEjB,MAAM,YAAY;AAGhB,OAAI,CAAC,OAAO,cACV,QAAO;AAGT,OAAI,KAAK,aAAa,CAAC,QAAQ,QAAQ;AACrC,cAAU,MAAMC,0BAAAA,WAAW,QAAQ,EACjC,YAAY;KACVC,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACX,EACF,CAAC;AACF,uBAAmB,KAAK,KAAK;AAC7B,mBAAe;;AAEjB,UAAO;;EAET,MAAM,aAAa;AACjB,SAAM,KAAK,WAAW;AACtB,UAAO;;EAEV"}
+{"version":3,"file":"getClientStorage.js","names":["getRpcUrlsFromChains","ChainId","_getChains","ChainType"],"sources":["../../../src/client/getClientStorage.ts"],"sourcesContent":["import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'\nimport { _getChains } from '../actions/getChains.js'\nimport { getRpcUrlsFromChains } from '../core/utils.js'\nimport type { RPCUrls, SDKBaseConfig } from '../types/core.js'\n\n// 6 hours in milliseconds\nconst chainsRefreshInterval = 1000 * 60 * 60 * 6\n\nexport interface ClientStorage {\n  readonly needReset: boolean\n  setChains(chains: ExtendedChain[]): void\n  getChains(): Promise<ExtendedChain[]>\n  getRpcUrls(): Promise<RPCUrls>\n}\n\nexport const getClientStorage = (config: SDKBaseConfig): ClientStorage => {\n  let _chains = [] as ExtendedChain[]\n  let _rpcUrls = { ...config.rpcUrls } as RPCUrls\n  let _chainsUpdatedAt: number | undefined\n\n  const updateRpcUrls = () => {\n    _rpcUrls = { ...config.rpcUrls }\n    _rpcUrls = getRpcUrlsFromChains(_rpcUrls, _chains, [ChainId.SOL])\n  }\n\n  return {\n    get needReset() {\n      return (\n        !_chainsUpdatedAt ||\n        Date.now() - _chainsUpdatedAt >= chainsRefreshInterval\n      )\n    },\n    setChains(chains: ExtendedChain[]) {\n      _chains = chains\n      _chainsUpdatedAt = Date.now()\n      updateRpcUrls()\n    },\n    async getChains() {\n      // When preloadChains is false, SDK does not auto-fetch chains\n      // External consumer is responsible for calling setChains\n      if (!config.preloadChains) {\n        return _chains\n      }\n\n      if (this.needReset || !_chains.length) {\n        _chains = await _getChains(config, {\n          chainTypes: [\n            ChainType.EVM,\n            ChainType.SVM,\n            ChainType.UTXO,\n            ChainType.MVM,\n            ChainType.TVM,\n          ],\n        })\n        _chainsUpdatedAt = Date.now()\n        updateRpcUrls()\n      }\n      return _chains\n    },\n    async getRpcUrls() {\n      await this.getChains() // _rpcUrls is updated when needed\n      return _rpcUrls\n    },\n  }\n}\n"],"mappings":";;;;;AAMA,MAAM,wBAAwB,MAAO,KAAK,KAAK;AAS/C,MAAa,oBAAoB,WAAyC;CACxE,IAAI,UAAU,EAAE;CAChB,IAAI,WAAW,EAAE,GAAG,OAAO,SAAS;CACpC,IAAI;CAEJ,MAAM,sBAAsB;AAC1B,aAAW,EAAE,GAAG,OAAO,SAAS;AAChC,aAAWA,mBAAAA,qBAAqB,UAAU,SAAS,CAACC,YAAAA,QAAQ,IAAI,CAAC;;AAGnE,QAAO;EACL,IAAI,YAAY;AACd,UACE,CAAC,oBACD,KAAK,KAAK,GAAG,oBAAoB;;EAGrC,UAAU,QAAyB;AACjC,aAAU;AACV,sBAAmB,KAAK,KAAK;AAC7B,kBAAe;;EAEjB,MAAM,YAAY;AAGhB,OAAI,CAAC,OAAO,cACV,QAAO;AAGT,OAAI,KAAK,aAAa,CAAC,QAAQ,QAAQ;AACrC,cAAU,MAAMC,0BAAAA,WAAW,QAAQ,EACjC,YAAY;KACVC,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACVA,YAAAA,UAAU;KACX,EACF,CAAC;AACF,uBAAmB,KAAK,KAAK;AAC7B,mBAAe;;AAEjB,UAAO;;EAET,MAAM,aAAa;AACjB,SAAM,KAAK,WAAW;AACtB,UAAO;;EAEV"}

package/dist/cjs/core/tasks/helpers/checkBalance.d.ts

@@ -2,7 +2,19 @@ import { SDKClient } from "../../../types/core.js";
 import { LiFiStep } from "@lifi/types";
 
 //#region src/core/tasks/helpers/checkBalance.d.ts
-declare const checkBalance: (client: SDKClient, walletAddress: string, step: LiFiStep, depth?: number) => Promise<void>;
+/**
+* Verifies that the wallet holds enough of every token required to execute
+* the step on its source chain — the source-token amount, any gas costs, and
+* any non-included fee costs. Reads all balances in one batched provider
+* call, retries within a bounded budget to absorb transient RPC failures and
+* post-confirmation propagation lag, and applies slippage to the source-token
+* portion only as a last resort (overhead is never trimmed).
+*
+* Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+* BalanceError("Could not read wallet balance.") if the balance can't be read
+* after retries.
+*/
+declare const checkBalance: (client: SDKClient, walletAddress: string, step: LiFiStep) => Promise<void>;
 //#endregion
 export { checkBalance };
 //# sourceMappingURL=checkBalance.d.ts.map

package/dist/cjs/core/tasks/helpers/checkBalance.js

@@ -1,26 +1,96 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_errors_errors = require("../../../errors/errors.js");
 const require_utils_sleep = require("../../../utils/sleep.js");
-const require_actions_getTokenBalance = require("../../../actions/getTokenBalance.js");
 const require_utils_formatUnits = require("../../../utils/formatUnits.js");
+const require_utils_withTimeout = require("../../../utils/withTimeout.js");
 //#region src/core/tasks/helpers/checkBalance.ts
-const checkBalance = async (client, walletAddress, step, depth = 0) => {
-	const token = await require_actions_getTokenBalance.getTokenBalance(client, walletAddress, step.action.fromToken);
-	if (token) {
-		const currentBalance = token.amount ?? 0n;
-		const neededBalance = BigInt(step.action.fromAmount);
-		if (currentBalance < neededBalance) if (depth <= 3) {
-			await require_utils_sleep.sleep(200);
-			await checkBalance(client, walletAddress, step, depth + 1);
-		} else if (neededBalance * BigInt((1 - (step.action.slippage ?? 0)) * 1e9) / 1000000000n <= currentBalance) step.action.fromAmount = currentBalance.toString();
-		else {
-			const needed = require_utils_formatUnits.formatUnits(neededBalance, token.decimals);
-			const current = require_utils_formatUnits.formatUnits(currentBalance, token.decimals);
-			let errorMessage = `Your ${token.symbol} balance is too low, you try to transfer ${needed} ${token.symbol}, but your wallet only holds ${current} ${token.symbol}. No funds have been sent.`;
-			if (currentBalance !== 0n) errorMessage += `If the problem consists, please delete this transfer and start a new one with a maximum of ${current} ${token.symbol}.`;
-			throw new require_errors_errors.BalanceError("The balance is too low.", new Error(errorMessage));
+const MAX_ATTEMPTS = 6;
+const BACKOFF_BASE_MS = 150;
+const OVERALL_TIMEOUT_MS = 1e4;
+const SLIPPAGE_PRECISION = 1000000000n;
+/**
+* Verifies that the wallet holds enough of every token required to execute
+* the step on its source chain — the source-token amount, any gas costs, and
+* any non-included fee costs. Reads all balances in one batched provider
+* call, retries within a bounded budget to absorb transient RPC failures and
+* post-confirmation propagation lag, and applies slippage to the source-token
+* portion only as a last resort (overhead is never trimmed).
+*
+* Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+* BalanceError("Could not read wallet balance.") if the balance can't be read
+* after retries.
+*/
+const checkBalance = async (client, walletAddress, step) => {
+	const fromChainId = step.action.fromChainId;
+	const requirements = /* @__PURE__ */ new Map();
+	const add = (token, amount, source) => {
+		if (token.chainId !== fromChainId || amount === 0n) return;
+		const key = token.address.toLowerCase();
+		const req = requirements.get(key) ?? {
+			token,
+			sourcePart: 0n,
+			overheadPart: 0n
+		};
+		if (source) req.sourcePart += amount;
+		else req.overheadPart += amount;
+		requirements.set(key, req);
+	};
+	add(step.action.fromToken, BigInt(step.action.fromAmount), true);
+	for (const gas of step.estimate?.gasCosts ?? []) add(gas.token, BigInt(gas.amount), false);
+	for (const fee of step.estimate?.feeCosts ?? []) if (!fee.included) add(fee.token, BigInt(fee.amount), false);
+	if (requirements.size === 0) return;
+	const provider = client.providers.find((p) => p.isAddress(walletAddress));
+	if (!provider) throw new Error(`SDK Token Provider for ${walletAddress} is not found.`);
+	const reqs = Array.from(requirements.values());
+	const tokens = reqs.map((r) => r.token);
+	const slippage = step.action.slippage ?? 0;
+	const slippageScaled = BigInt(Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION)));
+	await require_utils_withTimeout.withTimeout(async () => {
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			const isFinal = attempt === MAX_ATTEMPTS - 1;
+			let balances;
+			try {
+				balances = await provider.getBalance(client, walletAddress, tokens);
+			} catch (error) {
+				if (isFinal) throw new require_errors_errors.BalanceError("Could not read wallet balance.", error);
+				await require_utils_sleep.sleep(BACKOFF_BASE_MS * 2 ** attempt);
+				continue;
+			}
+			const balanceByAddress = new Map(balances.map((b) => [b.address.toLowerCase(), b.amount]));
+			const unknown = [];
+			const insufficient = [];
+			for (const req of reqs) {
+				const have = balanceByAddress.get(req.token.address.toLowerCase());
+				if (have === void 0) unknown.push(req.token);
+				else if (have < req.sourcePart + req.overheadPart) insufficient.push({
+					req,
+					have
+				});
+			}
+			if (unknown.length === 0 && insufficient.length === 0) return;
+			if (isFinal && unknown.length === 0 && insufficient.length === 1 && insufficient[0].req.sourcePart > 0n) {
+				const { req, have } = insufficient[0];
+				if (have >= req.sourcePart * slippageScaled / SLIPPAGE_PRECISION + req.overheadPart) {
+					step.action.fromAmount = (have - req.overheadPart).toString();
+					return;
+				}
+			}
+			if (isFinal) {
+				if (unknown.length > 0) throw new require_errors_errors.BalanceError("Could not read wallet balance.", /* @__PURE__ */ new Error(`Could not read balance for: ${unknown.map((t) => t.symbol || t.address).join(", ")}.`));
+				const lines = insufficient.map(({ req, have }) => {
+					const needed = require_utils_formatUnits.formatUnits(req.sourcePart + req.overheadPart, req.token.decimals);
+					const current = require_utils_formatUnits.formatUnits(have, req.token.decimals);
+					const symbol = req.token.symbol;
+					return req.sourcePart > 0n ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.` : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`;
+				});
+				throw new require_errors_errors.BalanceError("The balance is too low.", /* @__PURE__ */ new Error(`${lines.join(" ")} No funds have been sent.`));
+			}
+			await require_utils_sleep.sleep(BACKOFF_BASE_MS * 2 ** attempt);
 		}
-	}
+	}, {
+		timeout: OVERALL_TIMEOUT_MS,
+		errorInstance: new require_errors_errors.BalanceError("Could not read wallet balance.")
+	});
 };
 //#endregion
 exports.checkBalance = checkBalance;

package/dist/cjs/core/tasks/helpers/checkBalance.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkBalance.js","names":["getTokenBalance","sleep","formatUnits","BalanceError"],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"sourcesContent":["import type { LiFiStep } from '@lifi/types'\nimport { getTokenBalance } from '../../../actions/getTokenBalance.js'\nimport { BalanceError } from '../../../errors/errors.js'\nimport type { SDKClient } from '../../../types/core.js'\nimport { formatUnits } from '../../../utils/formatUnits.js'\nimport { sleep } from '../../../utils/sleep.js'\n\nexport const checkBalance = async (\n  client: SDKClient,\n  walletAddress: string,\n  step: LiFiStep,\n  depth = 0\n): Promise<void> => {\n  const token = await getTokenBalance(\n    client,\n    walletAddress,\n    step.action.fromToken\n  )\n  if (token) {\n    const currentBalance = token.amount ?? 0n\n    const neededBalance = BigInt(step.action.fromAmount)\n\n    if (currentBalance < neededBalance) {\n      if (depth <= 3) {\n        await sleep(200)\n        await checkBalance(client, walletAddress, step, depth + 1)\n      } else if (\n        (neededBalance *\n          BigInt((1 - (step.action.slippage ?? 0)) * 1_000_000_000)) /\n          1_000_000_000n <=\n        currentBalance\n      ) {\n        // adjust amount in slippage limits\n        step.action.fromAmount = currentBalance.toString()\n      } else {\n        const needed = formatUnits(neededBalance, token.decimals)\n        const current = formatUnits(currentBalance, token.decimals)\n        let errorMessage = `Your ${token.symbol} balance is too low, you try to transfer ${needed} ${token.symbol}, but your wallet only holds ${current} ${token.symbol}. No funds have been sent.`\n\n        if (currentBalance !== 0n) {\n          errorMessage += `If the problem consists, please delete this transfer and start a new one with a maximum of ${current} ${token.symbol}.`\n        }\n\n        throw new BalanceError(\n          'The balance is too low.',\n          new Error(errorMessage)\n        )\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;AAOA,MAAa,eAAe,OAC1B,QACA,eACA,MACA,QAAQ,MACU;CAClB,MAAM,QAAQ,MAAMA,gCAAAA,gBAClB,QACA,eACA,KAAK,OAAO,UACb;AACD,KAAI,OAAO;EACT,MAAM,iBAAiB,MAAM,UAAU;EACvC,MAAM,gBAAgB,OAAO,KAAK,OAAO,WAAW;AAEpD,MAAI,iBAAiB,cACnB,KAAI,SAAS,GAAG;AACd,SAAMC,oBAAAA,MAAM,IAAI;AAChB,SAAM,aAAa,QAAQ,eAAe,MAAM,QAAQ,EAAE;aAEzD,gBACC,QAAQ,KAAK,KAAK,OAAO,YAAY,MAAM,IAAc,GACzD,eACF,eAGA,MAAK,OAAO,aAAa,eAAe,UAAU;OAC7C;GACL,MAAM,SAASC,0BAAAA,YAAY,eAAe,MAAM,SAAS;GACzD,MAAM,UAAUA,0BAAAA,YAAY,gBAAgB,MAAM,SAAS;GAC3D,IAAI,eAAe,QAAQ,MAAM,OAAO,2CAA2C,OAAO,GAAG,MAAM,OAAO,+BAA+B,QAAQ,GAAG,MAAM,OAAO;AAEjK,OAAI,mBAAmB,GACrB,iBAAgB,8FAA8F,QAAQ,GAAG,MAAM,OAAO;AAGxI,SAAM,IAAIC,sBAAAA,aACR,2BACA,IAAI,MAAM,aAAa,CACxB"}
+{"version":3,"file":"checkBalance.js","names":["withTimeout","BalanceError","sleep","formatUnits"],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"sourcesContent":["import type { LiFiStep, Token, TokenAmount } from '@lifi/types'\nimport { BalanceError } from '../../../errors/errors.js'\nimport type { SDKClient } from '../../../types/core.js'\nimport { formatUnits } from '../../../utils/formatUnits.js'\nimport { sleep } from '../../../utils/sleep.js'\nimport { withTimeout } from '../../../utils/withTimeout.js'\n\nconst MAX_ATTEMPTS = 6\n// Exponential backoff: 150, 300, 600, 1200, 2400 → ≈4.65s of sleep total.\nconst BACKOFF_BASE_MS = 150\nconst OVERALL_TIMEOUT_MS = 10_000\nconst SLIPPAGE_PRECISION = 1_000_000_000n\n\ntype Requirement = {\n  token: Token\n  sourcePart: bigint // 0n for pure overhead tokens\n  overheadPart: bigint // gas + non-included fees in this token\n}\n\n/**\n * Verifies that the wallet holds enough of every token required to execute\n * the step on its source chain — the source-token amount, any gas costs, and\n * any non-included fee costs. Reads all balances in one batched provider\n * call, retries within a bounded budget to absorb transient RPC failures and\n * post-confirmation propagation lag, and applies slippage to the source-token\n * portion only as a last resort (overhead is never trimmed).\n *\n * Throws BalanceError(\"The balance is too low.\") on a genuine shortfall, or\n * BalanceError(\"Could not read wallet balance.\") if the balance can't be read\n * after retries.\n */\nexport const checkBalance = async (\n  client: SDKClient,\n  walletAddress: string,\n  step: LiFiStep\n): Promise<void> => {\n  const fromChainId = step.action.fromChainId\n  const requirements = new Map<string, Requirement>()\n  const add = (token: Token, amount: bigint, source: boolean): void => {\n    if (token.chainId !== fromChainId || amount === 0n) {\n      return\n    }\n    const key = token.address.toLowerCase()\n    const req = requirements.get(key) ?? {\n      token,\n      sourcePart: 0n,\n      overheadPart: 0n,\n    }\n    if (source) {\n      req.sourcePart += amount\n    } else {\n      req.overheadPart += amount\n    }\n    requirements.set(key, req)\n  }\n  add(step.action.fromToken, BigInt(step.action.fromAmount), true)\n  for (const gas of step.estimate?.gasCosts ?? []) {\n    add(gas.token, BigInt(gas.amount), false)\n  }\n  for (const fee of step.estimate?.feeCosts ?? []) {\n    // Included fees are already part of fromAmount — don't count twice.\n    if (!fee.included) {\n      add(fee.token, BigInt(fee.amount), false)\n    }\n  }\n  if (requirements.size === 0) {\n    return\n  }\n\n  // Provider is dispatched by wallet address; all requirements share the\n  // source chain, which matches this provider by virtue of the address.\n  const provider = client.providers.find((p) => p.isAddress(walletAddress))\n  if (!provider) {\n    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)\n  }\n\n  const reqs = Array.from(requirements.values())\n  const tokens = reqs.map((r) => r.token)\n  const slippage = step.action.slippage ?? 0\n  const slippageScaled = BigInt(\n    Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION))\n  )\n\n  await withTimeout(\n    async () => {\n      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {\n        const isFinal = attempt === MAX_ATTEMPTS - 1\n\n        let balances: TokenAmount[]\n        try {\n          balances = await provider.getBalance(client, walletAddress, tokens)\n        } catch (error) {\n          if (isFinal) {\n            throw new BalanceError(\n              'Could not read wallet balance.',\n              error as Error\n            )\n          }\n          await sleep(BACKOFF_BASE_MS * 2 ** attempt)\n          continue\n        }\n\n        const balanceByAddress = new Map(\n          balances.map((b) => [b.address.toLowerCase(), b.amount] as const)\n        )\n\n        const unknown: Token[] = []\n        const insufficient: { req: Requirement; have: bigint }[] = []\n        for (const req of reqs) {\n          const have = balanceByAddress.get(req.token.address.toLowerCase())\n          if (have === undefined) {\n            unknown.push(req.token)\n          } else if (have < req.sourcePart + req.overheadPart) {\n            insufficient.push({ req, have })\n          }\n        }\n\n        if (unknown.length === 0 && insufficient.length === 0) {\n          return\n        }\n\n        // Final-attempt slippage rescue: only when the sole shortfall is the\n        // source-token portion. Trim source down to (balance − overhead) so\n        // the overhead reserve is preserved.\n        if (\n          isFinal &&\n          unknown.length === 0 &&\n          insufficient.length === 1 &&\n          insufficient[0].req.sourcePart > 0n\n        ) {\n          const { req, have } = insufficient[0]\n          const minAcceptable =\n            (req.sourcePart * slippageScaled) / SLIPPAGE_PRECISION +\n            req.overheadPart\n          if (have >= minAcceptable) {\n            step.action.fromAmount = (have - req.overheadPart).toString()\n            return\n          }\n        }\n\n        if (isFinal) {\n          if (unknown.length > 0) {\n            throw new BalanceError(\n              'Could not read wallet balance.',\n              new Error(\n                `Could not read balance for: ${unknown\n                  .map((t) => t.symbol || t.address)\n                  .join(', ')}.`\n              )\n            )\n          }\n          const lines = insufficient.map(({ req, have }) => {\n            const needed = formatUnits(\n              req.sourcePart + req.overheadPart,\n              req.token.decimals\n            )\n            const current = formatUnits(have, req.token.decimals)\n            const symbol = req.token.symbol\n            return req.sourcePart > 0n\n              ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.`\n              : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`\n          })\n          throw new BalanceError(\n            'The balance is too low.',\n            new Error(`${lines.join(' ')} No funds have been sent.`)\n          )\n        }\n\n        await sleep(BACKOFF_BASE_MS * 2 ** attempt)\n      }\n    },\n    {\n      timeout: OVERALL_TIMEOUT_MS,\n      errorInstance: new BalanceError('Could not read wallet balance.'),\n    }\n  )\n}\n"],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -50,5 +50,6 @@ import { parseUnits } from "./utils/parseUnits.js";
 import { sleep } from "./utils/sleep.js";
 import { waitForResult } from "./utils/waitForResult.js";
 import { LruMap, withDedupe } from "./utils/withDedupe.js";
+import { withTimeout } from "./utils/withTimeout.js";
 export * from "@lifi/types";
-export { type AcceptExchangeRateUpdateHook, type AcceptSlippageUpdateHook, type AcceptSlippageUpdateHookParams, BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, type ContractCallParams, type ContractTool, type ErrorCode, ErrorMessage, ErrorName, type ExchangeRateUpdateParams, ExecuteStepRetryError, type ExecuteStepRetryParams, type Execution, type ExecutionAction, type ExecutionActionStatus, type ExecutionActionType, type ExecutionOptions, type ExecutionStatus, type GetContractCallsHook, type GetContractCallsResult, HTTPError, InMemoryStorage, type InteractionSettings, LiFiErrorCode, type LiFiStepExtended, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, type RPCUrls, type RequestInterceptor, type RouteExecutionData, type RouteExecutionDataDictionary, type RouteExecutionDictionary, type RouteExtended, type SDKBaseConfig, type SDKClient, type SDKConfig, SDKError, type SDKProvider, type SDKStorage, ServerError, StatusManager, type StepExecutor, type StepExecutorBaseContext, type StepExecutorContext, type StepExecutorOptions, type StepExtended, TaskPipeline, type TaskResult, type TaskStatus, TransactionError, type TransactionMethodType, type TransactionParameters, type TransactionRequestParameters, type TransactionRequestUpdateHook, UnknownError, type UpdateRouteHook, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe };
+export { type AcceptExchangeRateUpdateHook, type AcceptSlippageUpdateHook, type AcceptSlippageUpdateHookParams, BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, type ContractCallParams, type ContractTool, type ErrorCode, ErrorMessage, ErrorName, type ExchangeRateUpdateParams, ExecuteStepRetryError, type ExecuteStepRetryParams, type Execution, type ExecutionAction, type ExecutionActionStatus, type ExecutionActionType, type ExecutionOptions, type ExecutionStatus, type GetContractCallsHook, type GetContractCallsResult, HTTPError, InMemoryStorage, type InteractionSettings, LiFiErrorCode, type LiFiStepExtended, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, type RPCUrls, type RequestInterceptor, type RouteExecutionData, type RouteExecutionDataDictionary, type RouteExecutionDictionary, type RouteExtended, type SDKBaseConfig, type SDKClient, type SDKConfig, SDKError, type SDKProvider, type SDKStorage, ServerError, StatusManager, type StepExecutor, type StepExecutorBaseContext, type StepExecutorContext, type StepExecutorOptions, type StepExtended, TaskPipeline, type TaskResult, type TaskStatus, TransactionError, type TransactionMethodType, type TransactionParameters, type TransactionRequestParameters, type TransactionRequestUpdateHook, UnknownError, type UpdateRouteHook, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe, withTimeout };

package/dist/cjs/index.js

@@ -38,6 +38,7 @@ const require_core_execution = require("./core/execution.js");
 const require_core_storage = require("./core/storage.js");
 const require_core_TaskPipeline = require("./core/TaskPipeline.js");
 const require_utils_formatUnits = require("./utils/formatUnits.js");
+const require_utils_withTimeout = require("./utils/withTimeout.js");
 const require_core_tasks_helpers_checkBalance = require("./core/tasks/helpers/checkBalance.js");
 const require_core_tasks_CheckBalanceTask = require("./core/tasks/CheckBalanceTask.js");
 const require_core_tasks_helpers_getTransactionRequestData = require("./core/tasks/helpers/getTransactionRequestData.js");
@@ -117,6 +118,7 @@ exports.stopRouteExecution = require_core_execution.stopRouteExecution;
 exports.updateRouteExecution = require_core_execution.updateRouteExecution;
 exports.waitForResult = require_utils_waitForResult.waitForResult;
 exports.withDedupe = require_utils_withDedupe.withDedupe;
+exports.withTimeout = require_utils_withTimeout.withTimeout;
 var _lifi_types = require("@lifi/types");
 Object.keys(_lifi_types).forEach(function(k) {
 	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/dist/cjs/utils/checkPackageUpdates.js

@@ -5,7 +5,7 @@ const checkPackageUpdates = async (packageName, packageVersion) => {
 	try {
 		const pkgName = packageName ?? "@lifi/sdk";
 		const latestVersion = (await (await fetch(`https://registry.npmjs.org/${pkgName}/latest`)).json()).version;
-		const currentVersion = packageVersion ?? "4.0.0-beta.5";
+		const currentVersion = packageVersion ?? "4.0.0-beta.7";
 		if (latestVersion > currentVersion) console.warn(`${pkgName}: new package version is available. Please update as soon as possible to enjoy the newest features. Current version: ${currentVersion}. Latest version: ${latestVersion}.`);
 	} catch (_error) {}
 };

package/dist/cjs/utils/withTimeout.d.ts

@@ -0,0 +1,26 @@
+//#region src/utils/withTimeout.d.ts
+/**
+* Wraps a function in a timeout.
+* Based on viem's withTimeout implementation.
+* @param fn - The function to wrap.
+* @param timeout - The timeout in milliseconds.
+* @param errorInstance - The error instance to throw when the timeout is reached.
+* @param signal - Whether or not the timeout should use an abort signal.
+* @returns The result of the function.
+*/
+declare function withTimeout<T>(fn: ({
+  signal
+}: {
+  signal: AbortController["signal"] | null;
+}) => Promise<T>, {
+  errorInstance,
+  timeout,
+  signal
+}: {
+  errorInstance?: Error | undefined;
+  timeout: number;
+  signal?: boolean | undefined;
+}): Promise<T>;
+//#endregion
+export { withTimeout };
+//# sourceMappingURL=withTimeout.d.ts.map

package/dist/cjs/utils/withTimeout.js

@@ -0,0 +1,35 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils/withTimeout.ts
+/**
+* Wraps a function in a timeout.
+* Based on viem's withTimeout implementation.
+* @param fn - The function to wrap.
+* @param timeout - The timeout in milliseconds.
+* @param errorInstance - The error instance to throw when the timeout is reached.
+* @param signal - Whether or not the timeout should use an abort signal.
+* @returns The result of the function.
+*/
+function withTimeout(fn, { errorInstance = /* @__PURE__ */ new Error("Timed out after waiting for too long."), timeout, signal }) {
+	return new Promise((resolve, reject) => {
+		(async () => {
+			let timeoutId;
+			try {
+				const controller = new AbortController();
+				if (timeout > 0) timeoutId = setTimeout(() => {
+					if (signal) controller.abort();
+					else reject(errorInstance);
+				}, timeout);
+				resolve(await fn({ signal: controller?.signal || null }));
+			} catch (err) {
+				if (err?.name === "AbortError") reject(errorInstance);
+				reject(err);
+			} finally {
+				clearTimeout(timeoutId);
+			}
+		})();
+	});
+}
+//#endregion
+exports.withTimeout = withTimeout;
+
+//# sourceMappingURL=withTimeout.js.map

package/dist/cjs/utils/withTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTimeout.js","names":[],"sources":["../../../src/utils/withTimeout.ts"],"sourcesContent":["/**\n * Wraps a function in a timeout.\n * Based on viem's withTimeout implementation.\n * @param fn - The function to wrap.\n * @param timeout - The timeout in milliseconds.\n * @param errorInstance - The error instance to throw when the timeout is reached.\n * @param signal - Whether or not the timeout should use an abort signal.\n * @returns The result of the function.\n */\nexport function withTimeout<T>(\n  fn: ({ signal }: { signal: AbortController['signal'] | null }) => Promise<T>,\n  {\n    errorInstance = new Error('Timed out after waiting for too long.'),\n    timeout,\n    signal,\n  }: {\n    // The error instance to throw when the timeout is reached.\n    errorInstance?: Error | undefined\n    // The timeout (in ms).\n    timeout: number\n    // Whether or not the timeout should use an abort signal.\n    signal?: boolean | undefined\n  }\n): Promise<T> {\n  return new Promise((resolve, reject) => {\n    ;(async () => {\n      let timeoutId!: NodeJS.Timeout\n      try {\n        const controller = new AbortController()\n        if (timeout > 0) {\n          timeoutId = setTimeout(() => {\n            if (signal) {\n              controller.abort()\n            } else {\n              reject(errorInstance)\n            }\n          }, timeout) as NodeJS.Timeout // need to cast because bun globals.d.ts overrides @types/node\n        }\n        resolve(await fn({ signal: controller?.signal || null }))\n      } catch (err) {\n        if ((err as Error)?.name === 'AbortError') {\n          reject(errorInstance)\n        }\n        reject(err)\n      } finally {\n        clearTimeout(timeoutId)\n      }\n    })()\n  })\n}\n"],"mappings":";;;;;;;;;;;AASA,SAAgB,YACd,IACA,EACE,gCAAgB,IAAI,MAAM,wCAAwC,EAClE,SACA,UASU;AACZ,QAAO,IAAI,SAAS,SAAS,WAAW;AACrC,GAAC,YAAY;GACZ,IAAI;AACJ,OAAI;IACF,MAAM,aAAa,IAAI,iBAAiB;AACxC,QAAI,UAAU,EACZ,aAAY,iBAAiB;AAC3B,SAAI,OACF,YAAW,OAAO;SAElB,QAAO,cAAc;OAEtB,QAAQ;AAEb,YAAQ,MAAM,GAAG,EAAE,QAAQ,YAAY,UAAU,MAAM,CAAC,CAAC;YAClD,KAAK;AACZ,QAAK,KAAe,SAAS,aAC3B,QAAO,cAAc;AAEvB,WAAO,IAAI;aACH;AACR,iBAAa,UAAU;;MAEvB;GACJ"}

package/dist/cjs/version.d.ts

@@ -1,6 +1,6 @@
 //#region src/version.d.ts
 declare const name = "@lifi/sdk";
-declare const version = "4.0.0-beta.5";
+declare const version = "4.0.0-beta.7";
 //#endregion
 export { name, version };
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/version.js

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/version.ts
 const name = "@lifi/sdk";
-const version = "4.0.0-beta.5";
+const version = "4.0.0-beta.7";
 //#endregion
 exports.name = name;
 exports.version = version;

package/dist/cjs/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":[],"sources":["../../src/version.ts"],"sourcesContent":["export const name = '@lifi/sdk'\nexport const version = '4.0.0-beta.5'\n"],"mappings":";;AAAA,MAAa,OAAO;AACpB,MAAa,UAAU"}
+{"version":3,"file":"version.js","names":[],"sources":["../../src/version.ts"],"sourcesContent":["export const name = '@lifi/sdk'\nexport const version = '4.0.0-beta.7'\n"],"mappings":";;AAAA,MAAa,OAAO;AACpB,MAAa,UAAU"}

package/dist/esm/client/getClientStorage.js

@@ -27,7 +27,8 @@ const getClientStorage = (config) => {
 					ChainType.EVM,
 					ChainType.SVM,
 					ChainType.UTXO,
-					ChainType.MVM
+					ChainType.MVM,
+					ChainType.TVM
 				] });
 				_chainsUpdatedAt = Date.now();
 				updateRpcUrls();

package/dist/esm/client/getClientStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"getClientStorage.js","names":[],"sources":["../../../src/client/getClientStorage.ts"],"sourcesContent":["import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'\nimport { _getChains } from '../actions/getChains.js'\nimport { getRpcUrlsFromChains } from '../core/utils.js'\nimport type { RPCUrls, SDKBaseConfig } from '../types/core.js'\n\n// 6 hours in milliseconds\nconst chainsRefreshInterval = 1000 * 60 * 60 * 6\n\nexport interface ClientStorage {\n  readonly needReset: boolean\n  setChains(chains: ExtendedChain[]): void\n  getChains(): Promise<ExtendedChain[]>\n  getRpcUrls(): Promise<RPCUrls>\n}\n\nexport const getClientStorage = (config: SDKBaseConfig): ClientStorage => {\n  let _chains = [] as ExtendedChain[]\n  let _rpcUrls = { ...config.rpcUrls } as RPCUrls\n  let _chainsUpdatedAt: number | undefined\n\n  const updateRpcUrls = () => {\n    _rpcUrls = { ...config.rpcUrls }\n    _rpcUrls = getRpcUrlsFromChains(_rpcUrls, _chains, [ChainId.SOL])\n  }\n\n  return {\n    get needReset() {\n      return (\n        !_chainsUpdatedAt ||\n        Date.now() - _chainsUpdatedAt >= chainsRefreshInterval\n      )\n    },\n    setChains(chains: ExtendedChain[]) {\n      _chains = chains\n      _chainsUpdatedAt = Date.now()\n      updateRpcUrls()\n    },\n    async getChains() {\n      // When preloadChains is false, SDK does not auto-fetch chains\n      // External consumer is responsible for calling setChains\n      if (!config.preloadChains) {\n        return _chains\n      }\n\n      if (this.needReset || !_chains.length) {\n        _chains = await _getChains(config, {\n          chainTypes: [\n            ChainType.EVM,\n            ChainType.SVM,\n            ChainType.UTXO,\n            ChainType.MVM,\n          ],\n        })\n        _chainsUpdatedAt = Date.now()\n        updateRpcUrls()\n      }\n      return _chains\n    },\n    async getRpcUrls() {\n      await this.getChains() // _rpcUrls is updated when needed\n      return _rpcUrls\n    },\n  }\n}\n"],"mappings":";;;;AAMA,MAAM,wBAAwB,MAAO,KAAK,KAAK;AAS/C,MAAa,oBAAoB,WAAyC;CACxE,IAAI,UAAU,EAAE;CAChB,IAAI,WAAW,EAAE,GAAG,OAAO,SAAS;CACpC,IAAI;CAEJ,MAAM,sBAAsB;AAC1B,aAAW,EAAE,GAAG,OAAO,SAAS;AAChC,aAAW,qBAAqB,UAAU,SAAS,CAAC,QAAQ,IAAI,CAAC;;AAGnE,QAAO;EACL,IAAI,YAAY;AACd,UACE,CAAC,oBACD,KAAK,KAAK,GAAG,oBAAoB;;EAGrC,UAAU,QAAyB;AACjC,aAAU;AACV,sBAAmB,KAAK,KAAK;AAC7B,kBAAe;;EAEjB,MAAM,YAAY;AAGhB,OAAI,CAAC,OAAO,cACV,QAAO;AAGT,OAAI,KAAK,aAAa,CAAC,QAAQ,QAAQ;AACrC,cAAU,MAAM,WAAW,QAAQ,EACjC,YAAY;KACV,UAAU;KACV,UAAU;KACV,UAAU;KACV,UAAU;KACX,EACF,CAAC;AACF,uBAAmB,KAAK,KAAK;AAC7B,mBAAe;;AAEjB,UAAO;;EAET,MAAM,aAAa;AACjB,SAAM,KAAK,WAAW;AACtB,UAAO;;EAEV"}
+{"version":3,"file":"getClientStorage.js","names":[],"sources":["../../../src/client/getClientStorage.ts"],"sourcesContent":["import { ChainId, ChainType, type ExtendedChain } from '@lifi/types'\nimport { _getChains } from '../actions/getChains.js'\nimport { getRpcUrlsFromChains } from '../core/utils.js'\nimport type { RPCUrls, SDKBaseConfig } from '../types/core.js'\n\n// 6 hours in milliseconds\nconst chainsRefreshInterval = 1000 * 60 * 60 * 6\n\nexport interface ClientStorage {\n  readonly needReset: boolean\n  setChains(chains: ExtendedChain[]): void\n  getChains(): Promise<ExtendedChain[]>\n  getRpcUrls(): Promise<RPCUrls>\n}\n\nexport const getClientStorage = (config: SDKBaseConfig): ClientStorage => {\n  let _chains = [] as ExtendedChain[]\n  let _rpcUrls = { ...config.rpcUrls } as RPCUrls\n  let _chainsUpdatedAt: number | undefined\n\n  const updateRpcUrls = () => {\n    _rpcUrls = { ...config.rpcUrls }\n    _rpcUrls = getRpcUrlsFromChains(_rpcUrls, _chains, [ChainId.SOL])\n  }\n\n  return {\n    get needReset() {\n      return (\n        !_chainsUpdatedAt ||\n        Date.now() - _chainsUpdatedAt >= chainsRefreshInterval\n      )\n    },\n    setChains(chains: ExtendedChain[]) {\n      _chains = chains\n      _chainsUpdatedAt = Date.now()\n      updateRpcUrls()\n    },\n    async getChains() {\n      // When preloadChains is false, SDK does not auto-fetch chains\n      // External consumer is responsible for calling setChains\n      if (!config.preloadChains) {\n        return _chains\n      }\n\n      if (this.needReset || !_chains.length) {\n        _chains = await _getChains(config, {\n          chainTypes: [\n            ChainType.EVM,\n            ChainType.SVM,\n            ChainType.UTXO,\n            ChainType.MVM,\n            ChainType.TVM,\n          ],\n        })\n        _chainsUpdatedAt = Date.now()\n        updateRpcUrls()\n      }\n      return _chains\n    },\n    async getRpcUrls() {\n      await this.getChains() // _rpcUrls is updated when needed\n      return _rpcUrls\n    },\n  }\n}\n"],"mappings":";;;;AAMA,MAAM,wBAAwB,MAAO,KAAK,KAAK;AAS/C,MAAa,oBAAoB,WAAyC;CACxE,IAAI,UAAU,EAAE;CAChB,IAAI,WAAW,EAAE,GAAG,OAAO,SAAS;CACpC,IAAI;CAEJ,MAAM,sBAAsB;AAC1B,aAAW,EAAE,GAAG,OAAO,SAAS;AAChC,aAAW,qBAAqB,UAAU,SAAS,CAAC,QAAQ,IAAI,CAAC;;AAGnE,QAAO;EACL,IAAI,YAAY;AACd,UACE,CAAC,oBACD,KAAK,KAAK,GAAG,oBAAoB;;EAGrC,UAAU,QAAyB;AACjC,aAAU;AACV,sBAAmB,KAAK,KAAK;AAC7B,kBAAe;;EAEjB,MAAM,YAAY;AAGhB,OAAI,CAAC,OAAO,cACV,QAAO;AAGT,OAAI,KAAK,aAAa,CAAC,QAAQ,QAAQ;AACrC,cAAU,MAAM,WAAW,QAAQ,EACjC,YAAY;KACV,UAAU;KACV,UAAU;KACV,UAAU;KACV,UAAU;KACV,UAAU;KACX,EACF,CAAC;AACF,uBAAmB,KAAK,KAAK;AAC7B,mBAAe;;AAEjB,UAAO;;EAET,MAAM,aAAa;AACjB,SAAM,KAAK,WAAW;AACtB,UAAO;;EAEV"}

package/dist/esm/core/tasks/helpers/checkBalance.d.ts

@@ -2,7 +2,19 @@ import { SDKClient } from "../../../types/core.js";
 import { LiFiStep } from "@lifi/types";
 
 //#region src/core/tasks/helpers/checkBalance.d.ts
-declare const checkBalance: (client: SDKClient, walletAddress: string, step: LiFiStep, depth?: number) => Promise<void>;
+/**
+* Verifies that the wallet holds enough of every token required to execute
+* the step on its source chain — the source-token amount, any gas costs, and
+* any non-included fee costs. Reads all balances in one batched provider
+* call, retries within a bounded budget to absorb transient RPC failures and
+* post-confirmation propagation lag, and applies slippage to the source-token
+* portion only as a last resort (overhead is never trimmed).
+*
+* Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+* BalanceError("Could not read wallet balance.") if the balance can't be read
+* after retries.
+*/
+declare const checkBalance: (client: SDKClient, walletAddress: string, step: LiFiStep) => Promise<void>;
 //#endregion
 export { checkBalance };
 //# sourceMappingURL=checkBalance.d.ts.map

package/dist/esm/core/tasks/helpers/checkBalance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkBalance.d.ts","names":[],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"mappings":";;;;cAOa,YAAA,GACX,MAAA,EAAQ,SAAA,EACR,aAAA,UACA,IAAA,EAAM,QAAA,EACN,KAAA,cACC,OAAA"}
+{"version":3,"file":"checkBalance.d.ts","names":[],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"mappings":";;;;;;AA+BA;;;;;;;;;;cAAa,YAAA,GACX,MAAA,EAAQ,SAAA,EACR,aAAA,UACA,IAAA,EAAM,QAAA,KACL,OAAA"}

package/dist/esm/core/tasks/helpers/checkBalance.js

@@ -1,25 +1,95 @@
 import { BalanceError } from "../../../errors/errors.js";
 import { sleep } from "../../../utils/sleep.js";
-import { getTokenBalance } from "../../../actions/getTokenBalance.js";
 import { formatUnits } from "../../../utils/formatUnits.js";
+import { withTimeout } from "../../../utils/withTimeout.js";
 //#region src/core/tasks/helpers/checkBalance.ts
-const checkBalance = async (client, walletAddress, step, depth = 0) => {
-	const token = await getTokenBalance(client, walletAddress, step.action.fromToken);
-	if (token) {
-		const currentBalance = token.amount ?? 0n;
-		const neededBalance = BigInt(step.action.fromAmount);
-		if (currentBalance < neededBalance) if (depth <= 3) {
-			await sleep(200);
-			await checkBalance(client, walletAddress, step, depth + 1);
-		} else if (neededBalance * BigInt((1 - (step.action.slippage ?? 0)) * 1e9) / 1000000000n <= currentBalance) step.action.fromAmount = currentBalance.toString();
-		else {
-			const needed = formatUnits(neededBalance, token.decimals);
-			const current = formatUnits(currentBalance, token.decimals);
-			let errorMessage = `Your ${token.symbol} balance is too low, you try to transfer ${needed} ${token.symbol}, but your wallet only holds ${current} ${token.symbol}. No funds have been sent.`;
-			if (currentBalance !== 0n) errorMessage += `If the problem consists, please delete this transfer and start a new one with a maximum of ${current} ${token.symbol}.`;
-			throw new BalanceError("The balance is too low.", new Error(errorMessage));
+const MAX_ATTEMPTS = 6;
+const BACKOFF_BASE_MS = 150;
+const OVERALL_TIMEOUT_MS = 1e4;
+const SLIPPAGE_PRECISION = 1000000000n;
+/**
+* Verifies that the wallet holds enough of every token required to execute
+* the step on its source chain — the source-token amount, any gas costs, and
+* any non-included fee costs. Reads all balances in one batched provider
+* call, retries within a bounded budget to absorb transient RPC failures and
+* post-confirmation propagation lag, and applies slippage to the source-token
+* portion only as a last resort (overhead is never trimmed).
+*
+* Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+* BalanceError("Could not read wallet balance.") if the balance can't be read
+* after retries.
+*/
+const checkBalance = async (client, walletAddress, step) => {
+	const fromChainId = step.action.fromChainId;
+	const requirements = /* @__PURE__ */ new Map();
+	const add = (token, amount, source) => {
+		if (token.chainId !== fromChainId || amount === 0n) return;
+		const key = token.address.toLowerCase();
+		const req = requirements.get(key) ?? {
+			token,
+			sourcePart: 0n,
+			overheadPart: 0n
+		};
+		if (source) req.sourcePart += amount;
+		else req.overheadPart += amount;
+		requirements.set(key, req);
+	};
+	add(step.action.fromToken, BigInt(step.action.fromAmount), true);
+	for (const gas of step.estimate?.gasCosts ?? []) add(gas.token, BigInt(gas.amount), false);
+	for (const fee of step.estimate?.feeCosts ?? []) if (!fee.included) add(fee.token, BigInt(fee.amount), false);
+	if (requirements.size === 0) return;
+	const provider = client.providers.find((p) => p.isAddress(walletAddress));
+	if (!provider) throw new Error(`SDK Token Provider for ${walletAddress} is not found.`);
+	const reqs = Array.from(requirements.values());
+	const tokens = reqs.map((r) => r.token);
+	const slippage = step.action.slippage ?? 0;
+	const slippageScaled = BigInt(Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION)));
+	await withTimeout(async () => {
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			const isFinal = attempt === MAX_ATTEMPTS - 1;
+			let balances;
+			try {
+				balances = await provider.getBalance(client, walletAddress, tokens);
+			} catch (error) {
+				if (isFinal) throw new BalanceError("Could not read wallet balance.", error);
+				await sleep(BACKOFF_BASE_MS * 2 ** attempt);
+				continue;
+			}
+			const balanceByAddress = new Map(balances.map((b) => [b.address.toLowerCase(), b.amount]));
+			const unknown = [];
+			const insufficient = [];
+			for (const req of reqs) {
+				const have = balanceByAddress.get(req.token.address.toLowerCase());
+				if (have === void 0) unknown.push(req.token);
+				else if (have < req.sourcePart + req.overheadPart) insufficient.push({
+					req,
+					have
+				});
+			}
+			if (unknown.length === 0 && insufficient.length === 0) return;
+			if (isFinal && unknown.length === 0 && insufficient.length === 1 && insufficient[0].req.sourcePart > 0n) {
+				const { req, have } = insufficient[0];
+				if (have >= req.sourcePart * slippageScaled / SLIPPAGE_PRECISION + req.overheadPart) {
+					step.action.fromAmount = (have - req.overheadPart).toString();
+					return;
+				}
+			}
+			if (isFinal) {
+				if (unknown.length > 0) throw new BalanceError("Could not read wallet balance.", /* @__PURE__ */ new Error(`Could not read balance for: ${unknown.map((t) => t.symbol || t.address).join(", ")}.`));
+				const lines = insufficient.map(({ req, have }) => {
+					const needed = formatUnits(req.sourcePart + req.overheadPart, req.token.decimals);
+					const current = formatUnits(have, req.token.decimals);
+					const symbol = req.token.symbol;
+					return req.sourcePart > 0n ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.` : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`;
+				});
+				throw new BalanceError("The balance is too low.", /* @__PURE__ */ new Error(`${lines.join(" ")} No funds have been sent.`));
+			}
+			await sleep(BACKOFF_BASE_MS * 2 ** attempt);
 		}
-	}
+	}, {
+		timeout: OVERALL_TIMEOUT_MS,
+		errorInstance: new BalanceError("Could not read wallet balance.")
+	});
 };
 //#endregion
 export { checkBalance };

package/dist/esm/core/tasks/helpers/checkBalance.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkBalance.js","names":[],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"sourcesContent":["import type { LiFiStep } from '@lifi/types'\nimport { getTokenBalance } from '../../../actions/getTokenBalance.js'\nimport { BalanceError } from '../../../errors/errors.js'\nimport type { SDKClient } from '../../../types/core.js'\nimport { formatUnits } from '../../../utils/formatUnits.js'\nimport { sleep } from '../../../utils/sleep.js'\n\nexport const checkBalance = async (\n  client: SDKClient,\n  walletAddress: string,\n  step: LiFiStep,\n  depth = 0\n): Promise<void> => {\n  const token = await getTokenBalance(\n    client,\n    walletAddress,\n    step.action.fromToken\n  )\n  if (token) {\n    const currentBalance = token.amount ?? 0n\n    const neededBalance = BigInt(step.action.fromAmount)\n\n    if (currentBalance < neededBalance) {\n      if (depth <= 3) {\n        await sleep(200)\n        await checkBalance(client, walletAddress, step, depth + 1)\n      } else if (\n        (neededBalance *\n          BigInt((1 - (step.action.slippage ?? 0)) * 1_000_000_000)) /\n          1_000_000_000n <=\n        currentBalance\n      ) {\n        // adjust amount in slippage limits\n        step.action.fromAmount = currentBalance.toString()\n      } else {\n        const needed = formatUnits(neededBalance, token.decimals)\n        const current = formatUnits(currentBalance, token.decimals)\n        let errorMessage = `Your ${token.symbol} balance is too low, you try to transfer ${needed} ${token.symbol}, but your wallet only holds ${current} ${token.symbol}. No funds have been sent.`\n\n        if (currentBalance !== 0n) {\n          errorMessage += `If the problem consists, please delete this transfer and start a new one with a maximum of ${current} ${token.symbol}.`\n        }\n\n        throw new BalanceError(\n          'The balance is too low.',\n          new Error(errorMessage)\n        )\n      }\n    }\n  }\n}\n"],"mappings":";;;;;AAOA,MAAa,eAAe,OAC1B,QACA,eACA,MACA,QAAQ,MACU;CAClB,MAAM,QAAQ,MAAM,gBAClB,QACA,eACA,KAAK,OAAO,UACb;AACD,KAAI,OAAO;EACT,MAAM,iBAAiB,MAAM,UAAU;EACvC,MAAM,gBAAgB,OAAO,KAAK,OAAO,WAAW;AAEpD,MAAI,iBAAiB,cACnB,KAAI,SAAS,GAAG;AACd,SAAM,MAAM,IAAI;AAChB,SAAM,aAAa,QAAQ,eAAe,MAAM,QAAQ,EAAE;aAEzD,gBACC,QAAQ,KAAK,KAAK,OAAO,YAAY,MAAM,IAAc,GACzD,eACF,eAGA,MAAK,OAAO,aAAa,eAAe,UAAU;OAC7C;GACL,MAAM,SAAS,YAAY,eAAe,MAAM,SAAS;GACzD,MAAM,UAAU,YAAY,gBAAgB,MAAM,SAAS;GAC3D,IAAI,eAAe,QAAQ,MAAM,OAAO,2CAA2C,OAAO,GAAG,MAAM,OAAO,+BAA+B,QAAQ,GAAG,MAAM,OAAO;AAEjK,OAAI,mBAAmB,GACrB,iBAAgB,8FAA8F,QAAQ,GAAG,MAAM,OAAO;AAGxI,SAAM,IAAI,aACR,2BACA,IAAI,MAAM,aAAa,CACxB"}
+{"version":3,"file":"checkBalance.js","names":[],"sources":["../../../../../src/core/tasks/helpers/checkBalance.ts"],"sourcesContent":["import type { LiFiStep, Token, TokenAmount } from '@lifi/types'\nimport { BalanceError } from '../../../errors/errors.js'\nimport type { SDKClient } from '../../../types/core.js'\nimport { formatUnits } from '../../../utils/formatUnits.js'\nimport { sleep } from '../../../utils/sleep.js'\nimport { withTimeout } from '../../../utils/withTimeout.js'\n\nconst MAX_ATTEMPTS = 6\n// Exponential backoff: 150, 300, 600, 1200, 2400 → ≈4.65s of sleep total.\nconst BACKOFF_BASE_MS = 150\nconst OVERALL_TIMEOUT_MS = 10_000\nconst SLIPPAGE_PRECISION = 1_000_000_000n\n\ntype Requirement = {\n  token: Token\n  sourcePart: bigint // 0n for pure overhead tokens\n  overheadPart: bigint // gas + non-included fees in this token\n}\n\n/**\n * Verifies that the wallet holds enough of every token required to execute\n * the step on its source chain — the source-token amount, any gas costs, and\n * any non-included fee costs. Reads all balances in one batched provider\n * call, retries within a bounded budget to absorb transient RPC failures and\n * post-confirmation propagation lag, and applies slippage to the source-token\n * portion only as a last resort (overhead is never trimmed).\n *\n * Throws BalanceError(\"The balance is too low.\") on a genuine shortfall, or\n * BalanceError(\"Could not read wallet balance.\") if the balance can't be read\n * after retries.\n */\nexport const checkBalance = async (\n  client: SDKClient,\n  walletAddress: string,\n  step: LiFiStep\n): Promise<void> => {\n  const fromChainId = step.action.fromChainId\n  const requirements = new Map<string, Requirement>()\n  const add = (token: Token, amount: bigint, source: boolean): void => {\n    if (token.chainId !== fromChainId || amount === 0n) {\n      return\n    }\n    const key = token.address.toLowerCase()\n    const req = requirements.get(key) ?? {\n      token,\n      sourcePart: 0n,\n      overheadPart: 0n,\n    }\n    if (source) {\n      req.sourcePart += amount\n    } else {\n      req.overheadPart += amount\n    }\n    requirements.set(key, req)\n  }\n  add(step.action.fromToken, BigInt(step.action.fromAmount), true)\n  for (const gas of step.estimate?.gasCosts ?? []) {\n    add(gas.token, BigInt(gas.amount), false)\n  }\n  for (const fee of step.estimate?.feeCosts ?? []) {\n    // Included fees are already part of fromAmount — don't count twice.\n    if (!fee.included) {\n      add(fee.token, BigInt(fee.amount), false)\n    }\n  }\n  if (requirements.size === 0) {\n    return\n  }\n\n  // Provider is dispatched by wallet address; all requirements share the\n  // source chain, which matches this provider by virtue of the address.\n  const provider = client.providers.find((p) => p.isAddress(walletAddress))\n  if (!provider) {\n    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)\n  }\n\n  const reqs = Array.from(requirements.values())\n  const tokens = reqs.map((r) => r.token)\n  const slippage = step.action.slippage ?? 0\n  const slippageScaled = BigInt(\n    Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION))\n  )\n\n  await withTimeout(\n    async () => {\n      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {\n        const isFinal = attempt === MAX_ATTEMPTS - 1\n\n        let balances: TokenAmount[]\n        try {\n          balances = await provider.getBalance(client, walletAddress, tokens)\n        } catch (error) {\n          if (isFinal) {\n            throw new BalanceError(\n              'Could not read wallet balance.',\n              error as Error\n            )\n          }\n          await sleep(BACKOFF_BASE_MS * 2 ** attempt)\n          continue\n        }\n\n        const balanceByAddress = new Map(\n          balances.map((b) => [b.address.toLowerCase(), b.amount] as const)\n        )\n\n        const unknown: Token[] = []\n        const insufficient: { req: Requirement; have: bigint }[] = []\n        for (const req of reqs) {\n          const have = balanceByAddress.get(req.token.address.toLowerCase())\n          if (have === undefined) {\n            unknown.push(req.token)\n          } else if (have < req.sourcePart + req.overheadPart) {\n            insufficient.push({ req, have })\n          }\n        }\n\n        if (unknown.length === 0 && insufficient.length === 0) {\n          return\n        }\n\n        // Final-attempt slippage rescue: only when the sole shortfall is the\n        // source-token portion. Trim source down to (balance − overhead) so\n        // the overhead reserve is preserved.\n        if (\n          isFinal &&\n          unknown.length === 0 &&\n          insufficient.length === 1 &&\n          insufficient[0].req.sourcePart > 0n\n        ) {\n          const { req, have } = insufficient[0]\n          const minAcceptable =\n            (req.sourcePart * slippageScaled) / SLIPPAGE_PRECISION +\n            req.overheadPart\n          if (have >= minAcceptable) {\n            step.action.fromAmount = (have - req.overheadPart).toString()\n            return\n          }\n        }\n\n        if (isFinal) {\n          if (unknown.length > 0) {\n            throw new BalanceError(\n              'Could not read wallet balance.',\n              new Error(\n                `Could not read balance for: ${unknown\n                  .map((t) => t.symbol || t.address)\n                  .join(', ')}.`\n              )\n            )\n          }\n          const lines = insufficient.map(({ req, have }) => {\n            const needed = formatUnits(\n              req.sourcePart + req.overheadPart,\n              req.token.decimals\n            )\n            const current = formatUnits(have, req.token.decimals)\n            const symbol = req.token.symbol\n            return req.sourcePart > 0n\n              ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.`\n              : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`\n          })\n          throw new BalanceError(\n            'The balance is too low.',\n            new Error(`${lines.join(' ')} No funds have been sent.`)\n          )\n        }\n\n        await sleep(BACKOFF_BASE_MS * 2 ** attempt)\n      }\n    },\n    {\n      timeout: OVERALL_TIMEOUT_MS,\n      errorInstance: new BalanceError('Could not read wallet balance.'),\n    }\n  )\n}\n"],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -50,5 +50,6 @@ import { parseUnits } from "./utils/parseUnits.js";
 import { sleep } from "./utils/sleep.js";
 import { waitForResult } from "./utils/waitForResult.js";
 import { LruMap, withDedupe } from "./utils/withDedupe.js";
+import { withTimeout } from "./utils/withTimeout.js";
 export * from "@lifi/types";
-export { type AcceptExchangeRateUpdateHook, type AcceptSlippageUpdateHook, type AcceptSlippageUpdateHookParams, BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, type ContractCallParams, type ContractTool, type ErrorCode, ErrorMessage, ErrorName, type ExchangeRateUpdateParams, ExecuteStepRetryError, type ExecuteStepRetryParams, type Execution, type ExecutionAction, type ExecutionActionStatus, type ExecutionActionType, type ExecutionOptions, type ExecutionStatus, type GetContractCallsHook, type GetContractCallsResult, HTTPError, InMemoryStorage, type InteractionSettings, LiFiErrorCode, type LiFiStepExtended, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, type RPCUrls, type RequestInterceptor, type RouteExecutionData, type RouteExecutionDataDictionary, type RouteExecutionDictionary, type RouteExtended, type SDKBaseConfig, type SDKClient, type SDKConfig, SDKError, type SDKProvider, type SDKStorage, ServerError, StatusManager, type StepExecutor, type StepExecutorBaseContext, type StepExecutorContext, type StepExecutorOptions, type StepExtended, TaskPipeline, type TaskResult, type TaskStatus, TransactionError, type TransactionMethodType, type TransactionParameters, type TransactionRequestParameters, type TransactionRequestUpdateHook, UnknownError, type UpdateRouteHook, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe };
+export { type AcceptExchangeRateUpdateHook, type AcceptSlippageUpdateHook, type AcceptSlippageUpdateHookParams, BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, type ContractCallParams, type ContractTool, type ErrorCode, ErrorMessage, ErrorName, type ExchangeRateUpdateParams, ExecuteStepRetryError, type ExecuteStepRetryParams, type Execution, type ExecutionAction, type ExecutionActionStatus, type ExecutionActionType, type ExecutionOptions, type ExecutionStatus, type GetContractCallsHook, type GetContractCallsResult, HTTPError, InMemoryStorage, type InteractionSettings, LiFiErrorCode, type LiFiStepExtended, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, type RPCUrls, type RequestInterceptor, type RouteExecutionData, type RouteExecutionDataDictionary, type RouteExecutionDictionary, type RouteExtended, type SDKBaseConfig, type SDKClient, type SDKConfig, SDKError, type SDKProvider, type SDKStorage, ServerError, StatusManager, type StepExecutor, type StepExecutorBaseContext, type StepExecutorContext, type StepExecutorOptions, type StepExtended, TaskPipeline, type TaskResult, type TaskStatus, TransactionError, type TransactionMethodType, type TransactionParameters, type TransactionRequestParameters, type TransactionRequestUpdateHook, UnknownError, type UpdateRouteHook, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe, withTimeout };

package/dist/esm/index.js

@@ -37,6 +37,7 @@ import { executeRoute, getActiveRoute, getActiveRoutes, resumeRoute, stopRouteEx
 import { InMemoryStorage, LocalStorageAdapter, createDefaultStorage } from "./core/storage.js";
 import { TaskPipeline } from "./core/TaskPipeline.js";
 import { formatUnits } from "./utils/formatUnits.js";
+import { withTimeout } from "./utils/withTimeout.js";
 import { checkBalance } from "./core/tasks/helpers/checkBalance.js";
 import { CheckBalanceTask } from "./core/tasks/CheckBalanceTask.js";
 import { getTransactionRequestData } from "./core/tasks/helpers/getTransactionRequestData.js";
@@ -49,4 +50,4 @@ import { fetchTxErrorDetails } from "./utils/fetchTxErrorDetails.js";
 import { isHex } from "./utils/isHex.js";
 import { parseUnits } from "./utils/parseUnits.js";
 export * from "@lifi/types";
-export { BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, ErrorMessage, ErrorName, ExecuteStepRetryError, HTTPError, InMemoryStorage, LiFiErrorCode, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, SDKError, ServerError, StatusManager, TaskPipeline, TransactionError, UnknownError, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe };
+export { BalanceError, BaseError, BaseStepExecutionTask, BaseStepExecutor, CheckBalanceTask, ErrorMessage, ErrorName, ExecuteStepRetryError, HTTPError, InMemoryStorage, LiFiErrorCode, LocalStorageAdapter, LruMap, PrepareTransactionTask, ProviderError, RPCError, SDKError, ServerError, StatusManager, TaskPipeline, TransactionError, UnknownError, ValidationError, WaitForTransactionStatusTask, actions, checkBalance, checkPackageUpdates, convertQuoteToRoute, createClient, createDefaultStorage, executeRoute, fetchTxErrorDetails, formatUnits, getActionMessage, getActiveRoute, getActiveRoutes, getChains, getConnections, getContractCallsQuote, getGasRecommendation, getNameServiceAddress, getQuote, getRelayedTransactionStatus, getRelayerQuote, getRoutes, getStatus, getStepTransaction, getSubstatusMessage, getToken, getTokenBalance, getTokenBalances, getTokenBalancesByChain, getTokens, getTools, getTransactionHistory, getTransactionRequestData, getWalletBalances, isHex, parseUnits, patchContractCalls, relayTransaction, resumeRoute, sleep, stepComparison, stopRouteExecution, updateRouteExecution, waitForResult, withDedupe, withTimeout };

package/dist/esm/utils/checkPackageUpdates.js

@@ -4,7 +4,7 @@ const checkPackageUpdates = async (packageName, packageVersion) => {
 	try {
 		const pkgName = packageName ?? "@lifi/sdk";
 		const latestVersion = (await (await fetch(`https://registry.npmjs.org/${pkgName}/latest`)).json()).version;
-		const currentVersion = packageVersion ?? "4.0.0-beta.5";
+		const currentVersion = packageVersion ?? "4.0.0-beta.7";
 		if (latestVersion > currentVersion) console.warn(`${pkgName}: new package version is available. Please update as soon as possible to enjoy the newest features. Current version: ${currentVersion}. Latest version: ${latestVersion}.`);
 	} catch (_error) {}
 };

package/dist/esm/utils/withTimeout.d.ts

@@ -0,0 +1,26 @@
+//#region src/utils/withTimeout.d.ts
+/**
+* Wraps a function in a timeout.
+* Based on viem's withTimeout implementation.
+* @param fn - The function to wrap.
+* @param timeout - The timeout in milliseconds.
+* @param errorInstance - The error instance to throw when the timeout is reached.
+* @param signal - Whether or not the timeout should use an abort signal.
+* @returns The result of the function.
+*/
+declare function withTimeout<T>(fn: ({
+  signal
+}: {
+  signal: AbortController["signal"] | null;
+}) => Promise<T>, {
+  errorInstance,
+  timeout,
+  signal
+}: {
+  errorInstance?: Error | undefined;
+  timeout: number;
+  signal?: boolean | undefined;
+}): Promise<T>;
+//#endregion
+export { withTimeout };
+//# sourceMappingURL=withTimeout.d.ts.map

package/dist/esm/utils/withTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTimeout.d.ts","names":[],"sources":["../../../src/utils/withTimeout.ts"],"mappings":";;AASA;;;;;;;;iBAAgB,WAAA,GAAA,CACd,EAAA;EAAO;AAAA;EAAY,MAAA,EAAQ,eAAA;AAAA,MAAuC,OAAA,CAAQ,CAAA;EAExE,aAAA;EACA,OAAA;EACA;AAAA;EAGA,aAAA,GAAgB,KAAA;EAEhB,OAAA;EAEA,MAAA;AAAA,IAED,OAAA,CAAQ,CAAA"}

package/dist/esm/utils/withTimeout.js

@@ -0,0 +1,34 @@
+//#region src/utils/withTimeout.ts
+/**
+* Wraps a function in a timeout.
+* Based on viem's withTimeout implementation.
+* @param fn - The function to wrap.
+* @param timeout - The timeout in milliseconds.
+* @param errorInstance - The error instance to throw when the timeout is reached.
+* @param signal - Whether or not the timeout should use an abort signal.
+* @returns The result of the function.
+*/
+function withTimeout(fn, { errorInstance = /* @__PURE__ */ new Error("Timed out after waiting for too long."), timeout, signal }) {
+	return new Promise((resolve, reject) => {
+		(async () => {
+			let timeoutId;
+			try {
+				const controller = new AbortController();
+				if (timeout > 0) timeoutId = setTimeout(() => {
+					if (signal) controller.abort();
+					else reject(errorInstance);
+				}, timeout);
+				resolve(await fn({ signal: controller?.signal || null }));
+			} catch (err) {
+				if (err?.name === "AbortError") reject(errorInstance);
+				reject(err);
+			} finally {
+				clearTimeout(timeoutId);
+			}
+		})();
+	});
+}
+//#endregion
+export { withTimeout };
+
+//# sourceMappingURL=withTimeout.js.map

package/dist/esm/utils/withTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withTimeout.js","names":[],"sources":["../../../src/utils/withTimeout.ts"],"sourcesContent":["/**\n * Wraps a function in a timeout.\n * Based on viem's withTimeout implementation.\n * @param fn - The function to wrap.\n * @param timeout - The timeout in milliseconds.\n * @param errorInstance - The error instance to throw when the timeout is reached.\n * @param signal - Whether or not the timeout should use an abort signal.\n * @returns The result of the function.\n */\nexport function withTimeout<T>(\n  fn: ({ signal }: { signal: AbortController['signal'] | null }) => Promise<T>,\n  {\n    errorInstance = new Error('Timed out after waiting for too long.'),\n    timeout,\n    signal,\n  }: {\n    // The error instance to throw when the timeout is reached.\n    errorInstance?: Error | undefined\n    // The timeout (in ms).\n    timeout: number\n    // Whether or not the timeout should use an abort signal.\n    signal?: boolean | undefined\n  }\n): Promise<T> {\n  return new Promise((resolve, reject) => {\n    ;(async () => {\n      let timeoutId!: NodeJS.Timeout\n      try {\n        const controller = new AbortController()\n        if (timeout > 0) {\n          timeoutId = setTimeout(() => {\n            if (signal) {\n              controller.abort()\n            } else {\n              reject(errorInstance)\n            }\n          }, timeout) as NodeJS.Timeout // need to cast because bun globals.d.ts overrides @types/node\n        }\n        resolve(await fn({ signal: controller?.signal || null }))\n      } catch (err) {\n        if ((err as Error)?.name === 'AbortError') {\n          reject(errorInstance)\n        }\n        reject(err)\n      } finally {\n        clearTimeout(timeoutId)\n      }\n    })()\n  })\n}\n"],"mappings":";;;;;;;;;;AASA,SAAgB,YACd,IACA,EACE,gCAAgB,IAAI,MAAM,wCAAwC,EAClE,SACA,UASU;AACZ,QAAO,IAAI,SAAS,SAAS,WAAW;AACrC,GAAC,YAAY;GACZ,IAAI;AACJ,OAAI;IACF,MAAM,aAAa,IAAI,iBAAiB;AACxC,QAAI,UAAU,EACZ,aAAY,iBAAiB;AAC3B,SAAI,OACF,YAAW,OAAO;SAElB,QAAO,cAAc;OAEtB,QAAQ;AAEb,YAAQ,MAAM,GAAG,EAAE,QAAQ,YAAY,UAAU,MAAM,CAAC,CAAC;YAClD,KAAK;AACZ,QAAK,KAAe,SAAS,aAC3B,QAAO,cAAc;AAEvB,WAAO,IAAI;aACH;AACR,iBAAa,UAAU;;MAEvB;GACJ"}

package/dist/esm/version.d.ts

@@ -1,6 +1,6 @@
 //#region src/version.d.ts
 declare const name = "@lifi/sdk";
-declare const version = "4.0.0-beta.5";
+declare const version = "4.0.0-beta.7";
 //#endregion
 export { name, version };
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/version.js

@@ -1,6 +1,6 @@
 //#region src/version.ts
 const name = "@lifi/sdk";
-const version = "4.0.0-beta.5";
+const version = "4.0.0-beta.7";
 //#endregion
 export { name, version };
 

package/dist/esm/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":[],"sources":["../../src/version.ts"],"sourcesContent":["export const name = '@lifi/sdk'\nexport const version = '4.0.0-beta.5'\n"],"mappings":";AAAA,MAAa,OAAO;AACpB,MAAa,UAAU"}
+{"version":3,"file":"version.js","names":[],"sources":["../../src/version.ts"],"sourcesContent":["export const name = '@lifi/sdk'\nexport const version = '4.0.0-beta.7'\n"],"mappings":";AAAA,MAAa,OAAO;AACpB,MAAa,UAAU"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/sdk",
-  "version": "4.0.0-beta.5",
+  "version": "4.0.0-beta.7",
   "description": "LI.FI SDK for Any-to-Any Cross-Chain-Swap",
   "homepage": "https://github.com/lifinance/sdk",
   "bugs": {
@@ -28,7 +28,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@lifi/types": "17.75.0"
+    "@lifi/types": "17.76.0"
   },
   "publishConfig": {
     "access": "public"

package/src/client/getClientStorage.ts

@@ -49,6 +49,7 @@ export const getClientStorage = (config: SDKBaseConfig): ClientStorage => {
             ChainType.SVM,
             ChainType.UTXO,
             ChainType.MVM,
+            ChainType.TVM,
           ],
         })
         _chainsUpdatedAt = Date.now()

package/src/core/tasks/helpers/checkBalance.ts

@@ -1,51 +1,177 @@
-import type { LiFiStep } from '@lifi/types'
-import { getTokenBalance } from '../../../actions/getTokenBalance.js'
+import type { LiFiStep, Token, TokenAmount } from '@lifi/types'
 import { BalanceError } from '../../../errors/errors.js'
 import type { SDKClient } from '../../../types/core.js'
 import { formatUnits } from '../../../utils/formatUnits.js'
 import { sleep } from '../../../utils/sleep.js'
+import { withTimeout } from '../../../utils/withTimeout.js'
 
+const MAX_ATTEMPTS = 6
+// Exponential backoff: 150, 300, 600, 1200, 2400 → ≈4.65s of sleep total.
+const BACKOFF_BASE_MS = 150
+const OVERALL_TIMEOUT_MS = 10_000
+const SLIPPAGE_PRECISION = 1_000_000_000n
+
+type Requirement = {
+  token: Token
+  sourcePart: bigint // 0n for pure overhead tokens
+  overheadPart: bigint // gas + non-included fees in this token
+}
+
+/**
+ * Verifies that the wallet holds enough of every token required to execute
+ * the step on its source chain — the source-token amount, any gas costs, and
+ * any non-included fee costs. Reads all balances in one batched provider
+ * call, retries within a bounded budget to absorb transient RPC failures and
+ * post-confirmation propagation lag, and applies slippage to the source-token
+ * portion only as a last resort (overhead is never trimmed).
+ *
+ * Throws BalanceError("The balance is too low.") on a genuine shortfall, or
+ * BalanceError("Could not read wallet balance.") if the balance can't be read
+ * after retries.
+ */
 export const checkBalance = async (
   client: SDKClient,
   walletAddress: string,
-  step: LiFiStep,
-  depth = 0
+  step: LiFiStep
 ): Promise<void> => {
-  const token = await getTokenBalance(
-    client,
-    walletAddress,
-    step.action.fromToken
+  const fromChainId = step.action.fromChainId
+  const requirements = new Map<string, Requirement>()
+  const add = (token: Token, amount: bigint, source: boolean): void => {
+    if (token.chainId !== fromChainId || amount === 0n) {
+      return
+    }
+    const key = token.address.toLowerCase()
+    const req = requirements.get(key) ?? {
+      token,
+      sourcePart: 0n,
+      overheadPart: 0n,
+    }
+    if (source) {
+      req.sourcePart += amount
+    } else {
+      req.overheadPart += amount
+    }
+    requirements.set(key, req)
+  }
+  add(step.action.fromToken, BigInt(step.action.fromAmount), true)
+  for (const gas of step.estimate?.gasCosts ?? []) {
+    add(gas.token, BigInt(gas.amount), false)
+  }
+  for (const fee of step.estimate?.feeCosts ?? []) {
+    // Included fees are already part of fromAmount — don't count twice.
+    if (!fee.included) {
+      add(fee.token, BigInt(fee.amount), false)
+    }
+  }
+  if (requirements.size === 0) {
+    return
+  }
+
+  // Provider is dispatched by wallet address; all requirements share the
+  // source chain, which matches this provider by virtue of the address.
+  const provider = client.providers.find((p) => p.isAddress(walletAddress))
+  if (!provider) {
+    throw new Error(`SDK Token Provider for ${walletAddress} is not found.`)
+  }
+
+  const reqs = Array.from(requirements.values())
+  const tokens = reqs.map((r) => r.token)
+  const slippage = step.action.slippage ?? 0
+  const slippageScaled = BigInt(
+    Math.floor((1 - slippage) * Number(SLIPPAGE_PRECISION))
   )
-  if (token) {
-    const currentBalance = token.amount ?? 0n
-    const neededBalance = BigInt(step.action.fromAmount)
-
-    if (currentBalance < neededBalance) {
-      if (depth <= 3) {
-        await sleep(200)
-        await checkBalance(client, walletAddress, step, depth + 1)
-      } else if (
-        (neededBalance *
-          BigInt((1 - (step.action.slippage ?? 0)) * 1_000_000_000)) /
-          1_000_000_000n <=
-        currentBalance
-      ) {
-        // adjust amount in slippage limits
-        step.action.fromAmount = currentBalance.toString()
-      } else {
-        const needed = formatUnits(neededBalance, token.decimals)
-        const current = formatUnits(currentBalance, token.decimals)
-        let errorMessage = `Your ${token.symbol} balance is too low, you try to transfer ${needed} ${token.symbol}, but your wallet only holds ${current} ${token.symbol}. No funds have been sent.`
-
-        if (currentBalance !== 0n) {
-          errorMessage += `If the problem consists, please delete this transfer and start a new one with a maximum of ${current} ${token.symbol}.`
+
+  await withTimeout(
+    async () => {
+      for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const isFinal = attempt === MAX_ATTEMPTS - 1
+
+        let balances: TokenAmount[]
+        try {
+          balances = await provider.getBalance(client, walletAddress, tokens)
+        } catch (error) {
+          if (isFinal) {
+            throw new BalanceError(
+              'Could not read wallet balance.',
+              error as Error
+            )
+          }
+          await sleep(BACKOFF_BASE_MS * 2 ** attempt)
+          continue
         }
 
-        throw new BalanceError(
-          'The balance is too low.',
-          new Error(errorMessage)
+        const balanceByAddress = new Map(
+          balances.map((b) => [b.address.toLowerCase(), b.amount] as const)
         )
+
+        const unknown: Token[] = []
+        const insufficient: { req: Requirement; have: bigint }[] = []
+        for (const req of reqs) {
+          const have = balanceByAddress.get(req.token.address.toLowerCase())
+          if (have === undefined) {
+            unknown.push(req.token)
+          } else if (have < req.sourcePart + req.overheadPart) {
+            insufficient.push({ req, have })
+          }
+        }
+
+        if (unknown.length === 0 && insufficient.length === 0) {
+          return
+        }
+
+        // Final-attempt slippage rescue: only when the sole shortfall is the
+        // source-token portion. Trim source down to (balance − overhead) so
+        // the overhead reserve is preserved.
+        if (
+          isFinal &&
+          unknown.length === 0 &&
+          insufficient.length === 1 &&
+          insufficient[0].req.sourcePart > 0n
+        ) {
+          const { req, have } = insufficient[0]
+          const minAcceptable =
+            (req.sourcePart * slippageScaled) / SLIPPAGE_PRECISION +
+            req.overheadPart
+          if (have >= minAcceptable) {
+            step.action.fromAmount = (have - req.overheadPart).toString()
+            return
+          }
+        }
+
+        if (isFinal) {
+          if (unknown.length > 0) {
+            throw new BalanceError(
+              'Could not read wallet balance.',
+              new Error(
+                `Could not read balance for: ${unknown
+                  .map((t) => t.symbol || t.address)
+                  .join(', ')}.`
+              )
+            )
+          }
+          const lines = insufficient.map(({ req, have }) => {
+            const needed = formatUnits(
+              req.sourcePart + req.overheadPart,
+              req.token.decimals
+            )
+            const current = formatUnits(have, req.token.decimals)
+            const symbol = req.token.symbol
+            return req.sourcePart > 0n
+              ? `Your ${symbol} balance is too low, you try to transfer ${needed} ${symbol}, but your wallet only holds ${current} ${symbol}.`
+              : `Insufficient ${symbol} for fees: need ${needed} ${symbol}, have ${current} ${symbol}.`
+          })
+          throw new BalanceError(
+            'The balance is too low.',
+            new Error(`${lines.join(' ')} No funds have been sent.`)
+          )
+        }
+
+        await sleep(BACKOFF_BASE_MS * 2 ** attempt)
       }
+    },
+    {
+      timeout: OVERALL_TIMEOUT_MS,
+      errorInstance: new BalanceError('Could not read wallet balance.'),
     }
-  }
+  )
 }

package/src/index.ts

@@ -116,3 +116,4 @@ export { parseUnits } from './utils/parseUnits.js'
 export { sleep } from './utils/sleep.js'
 export { waitForResult } from './utils/waitForResult.js'
 export { LruMap, withDedupe } from './utils/withDedupe.js'
+export { withTimeout } from './utils/withTimeout.js'

package/src/utils/withTimeout.ts

@@ -0,0 +1,50 @@
+/**
+ * Wraps a function in a timeout.
+ * Based on viem's withTimeout implementation.
+ * @param fn - The function to wrap.
+ * @param timeout - The timeout in milliseconds.
+ * @param errorInstance - The error instance to throw when the timeout is reached.
+ * @param signal - Whether or not the timeout should use an abort signal.
+ * @returns The result of the function.
+ */
+export function withTimeout<T>(
+  fn: ({ signal }: { signal: AbortController['signal'] | null }) => Promise<T>,
+  {
+    errorInstance = new Error('Timed out after waiting for too long.'),
+    timeout,
+    signal,
+  }: {
+    // The error instance to throw when the timeout is reached.
+    errorInstance?: Error | undefined
+    // The timeout (in ms).
+    timeout: number
+    // Whether or not the timeout should use an abort signal.
+    signal?: boolean | undefined
+  }
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    ;(async () => {
+      let timeoutId!: NodeJS.Timeout
+      try {
+        const controller = new AbortController()
+        if (timeout > 0) {
+          timeoutId = setTimeout(() => {
+            if (signal) {
+              controller.abort()
+            } else {
+              reject(errorInstance)
+            }
+          }, timeout) as NodeJS.Timeout // need to cast because bun globals.d.ts overrides @types/node
+        }
+        resolve(await fn({ signal: controller?.signal || null }))
+      } catch (err) {
+        if ((err as Error)?.name === 'AbortError') {
+          reject(errorInstance)
+        }
+        reject(err)
+      } finally {
+        clearTimeout(timeoutId)
+      }
+    })()
+  })
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/sdk'
-export const version = '4.0.0-beta.5'
+export const version = '4.0.0-beta.7'