@gauntlet-xyz/sdk 2.5.0 → 3.1.1

package/src/evm/deposit.ts

@@ -8,6 +8,7 @@ import {
   VaultNotFoundError,
   UnsupportedAssetError,
   InvalidSlippageBPSError,
+  InvalidSyncDepositBoundError,
 } from '../errors';
 import {
   resolveAeraRuntimeContracts,
@@ -40,13 +41,16 @@ export interface EvmDepositParams {
   solverTip?: bigint;
   /** Maximum price age passed to async Aera provisioner requests. Defaults to 10 days. */
   maxPriceAge?: bigint;
+  /** Caller-reviewed minimum output for an explicit Aera synchronous deposit. */
+  minUnitsOut?: bigint;
 }
 
 /**
  * Builds the ordered list of EVM transactions required to deposit into a Gauntlet vault.
  *
- * Returns one or two transactions: an ERC-20 approval (only if the current allowance is
- * insufficient) followed by the deposit or async deposit request. Each transaction is
+ * Returns ordered transactions: ERC-20 approvals (if the allowance is insufficient),
+ * followed by the deposit or async deposit request. Some tokens require an approval
+ * of zero before a new nonzero approval. Each transaction is
  * returned as a `PreparedTx` object ready to be signed and sent.
  *
  * @param client - A configured `GauntletClient` instance with an EVM public client and wallet.
@@ -74,13 +78,16 @@ export async function getDepositTx(
   client: GauntletClient,
   params: EvmDepositParams
 ): Promise<PreparedTx[]> {
+  params = structuredClone(params);
+  const slippageBps = params.slippageBps ?? DEFAULT_BPS;
+  if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > Number(MAX_BPS)) {
+    throw new InvalidSlippageBPSError(slippageBps);
+  }
   if (
-    params.slippageBps !== undefined &&
-    (!Number.isInteger(params.slippageBps) ||
-      params.slippageBps < 0 ||
-      params.slippageBps > Number(MAX_BPS))
+    params.minUnitsOut !== undefined &&
+    (typeof params.minUnitsOut !== 'bigint' || params.minUnitsOut <= 0n)
   ) {
-    throw new InvalidSlippageBPSError(params.slippageBps);
+    throw new InvalidSyncDepositBoundError();
   }
 
   const resolved = await resolveVault(client, params.vaultId, params.chainId);
@@ -105,6 +112,12 @@ export async function getDepositTx(
   }
 
   const requestedDepositMode = parseOperationMode(params.vaultId, params.depositMode);
+  if (
+    params.minUnitsOut !== undefined &&
+    (protocol !== 'aera' || requestedDepositMode !== 'sync')
+  ) {
+    throw new InvalidSyncDepositBoundError();
+  }
   let modifiedDepositMode: OperationMode;
   let aeraRuntime: AeraRuntimeContracts | undefined;
 
@@ -130,7 +143,7 @@ export async function getDepositTx(
       : vault.vaultAddress;
 
   // NOTE: this could be moved to the buildDeposit level
-  const { sufficient } = await adapter.checkAllowance({
+  const { sufficient, current } = await adapter.checkAllowance({
     publicClient,
     token: token.address,
     owner: account,
@@ -141,14 +154,43 @@ export async function getDepositTx(
   const steps: EvmTxStep[] = [];
 
   if (!sufficient) {
-    steps.push(
-      adapter.buildApproval({
-        token: token.address,
-        spender,
-        amount: params.amount,
-        account,
-      })
-    );
+    const approval = adapter.buildApproval({
+      token: token.address,
+      spender,
+      amount: params.amount,
+      account,
+    });
+    if (current > 0n && params.amount > 0n) {
+      try {
+        await publicClient.estimateContractGas({
+          address: approval.address,
+          abi: approval.abi,
+          functionName: 'approve',
+          args: approval.args,
+          account,
+        });
+      } catch (approvalError) {
+        const reset = adapter.buildApproval({
+          token: token.address,
+          spender,
+          amount: 0n,
+          account,
+        });
+        try {
+          await publicClient.estimateContractGas({
+            address: reset.address,
+            abi: reset.abi,
+            functionName: 'approve',
+            args: reset.args,
+            account,
+          });
+        } catch {
+          throw approvalError;
+        }
+        steps.push(reset);
+      }
+    }
+    steps.push(approval);
   }
 
   const depositSteps = await adapter.buildDeposit({
@@ -159,12 +201,13 @@ export async function getDepositTx(
     async: modifiedDepositMode === 'async',
     asset: token,
     publicClient,
-    slippageBps: params.slippageBps ?? DEFAULT_BPS,
+    slippageBps,
     solverTip: params.solverTip,
     maxPriceAge: params.maxPriceAge,
     aeraRuntime,
+    minUnitsOut: params.minUnitsOut,
   });
   steps.push(...depositSteps);
 
-  return await Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step)));
+  return Promise.all(steps.map((step) => encodeTransactionWithAttribution(client, step, chainId)));
 }

package/src/evm/depositQuote.ts

@@ -0,0 +1,138 @@
+import type { GauntletClient } from '../client';
+import { DEFAULT_BPS, MAX_BPS } from '../constants';
+import {
+  InvalidSlippageBPSError,
+  InvalidSyncDepositBoundError,
+  UnsupportedAssetError,
+  UnsupportedFeatureError,
+  VaultNotFoundError,
+} from '../errors';
+import {
+  applySlippageDown,
+  resolveAeraRuntimeContracts,
+  resolveAeraTokenModeSupport,
+} from './aeraContracts';
+import { getSyncDepositFeeBps, getSyncDepositQuoteValues } from './aeraContracts/v2';
+import { resolveOperationMode } from './operationMode';
+import { ContractVersion } from './types';
+import { resolveVault } from './vaults';
+
+export type SyncDepositQuote = Readonly<{
+  unitsOut: bigint;
+  minUnitsOut: bigint;
+  /** Deposit amount converted to the vault's numeraire, after the Instant Supply fee. */
+  numeraireOut: bigint;
+  /** Instant Supply fee applied to the deposited token amount, in basis points. */
+  feeBps: bigint;
+  /** Slippage tolerance used to derive `minUnitsOut`, in basis points. */
+  slippageBps: number;
+}>;
+
+export type SyncDepositQuoteParams = {
+  vaultId: string;
+  chainId?: number;
+  assetSymbol?: string;
+  amount: bigint;
+  slippageBps?: number;
+};
+
+export type SyncDepositRateParams = {
+  vaultId: string;
+  chainId?: number;
+  assetSymbol?: string;
+};
+
+export type SyncDepositRate = Readonly<{
+  /** Instant Supply fee, in basis points. Independent of the deposit amount. */
+  feeBps: bigint;
+}>;
+
+async function resolveSyncDepositContext(
+  client: GauntletClient,
+  params: SyncDepositRateParams,
+  readKind: 'quote' | 'rate'
+) {
+  const resolved = await resolveVault(client, params.vaultId, params.chainId);
+  if (!resolved) throw new VaultNotFoundError(params.vaultId, params.chainId);
+  if (resolved.protocol !== 'aera') {
+    throw new UnsupportedFeatureError(
+      readKind === 'quote'
+        ? 'Sync deposit quote is only available for Aera vaults'
+        : 'Sync deposit rate is only available for Aera vaults'
+    );
+  }
+
+  const { vault } = resolved;
+  const token =
+    vault.supplyToken.length > 1
+      ? vault.supplyToken.find(({ symbol }) => symbol === params.assetSymbol)
+      : vault.supplyToken[0];
+  if (!token) throw new UnsupportedAssetError(params.assetSymbol ?? 'unknown', params.vaultId);
+
+  const publicClient = client.getPublicClient(params.chainId ?? vault.chainId);
+  const runtime = await resolveAeraRuntimeContracts(publicClient, vault);
+  if (runtime.provisioner.version !== ContractVersion.V2) {
+    throw new UnsupportedFeatureError(
+      readKind === 'quote'
+        ? 'Sync deposit quote requires an Aera V2 provisioner'
+        : 'Sync deposit rate requires an Aera V2 provisioner'
+    );
+  }
+
+  const tokenModeSupport = await resolveAeraTokenModeSupport(publicClient, runtime, token.address, {
+    includeSyncModes: true,
+  });
+  resolveOperationMode(params.vaultId, 'sync', {
+    async: tokenModeSupport.asyncDeposit,
+    sync: tokenModeSupport.syncDeposit,
+  });
+
+  return { publicClient, vault, token, runtime };
+}
+
+/** Quotes an Aera synchronous deposit and its execution bounds. */
+export async function getSyncDepositQuote(
+  client: GauntletClient,
+  params: SyncDepositQuoteParams
+): Promise<SyncDepositQuote> {
+  params = structuredClone(params);
+  const slippageBps = params.slippageBps ?? DEFAULT_BPS;
+  if (!Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > Number(MAX_BPS)) {
+    throw new InvalidSlippageBPSError(slippageBps);
+  }
+
+  const { publicClient, vault, token, runtime } = await resolveSyncDepositContext(
+    client,
+    params,
+    'quote'
+  );
+
+  const { unitsOut, feeBps, numeraireOut } = await getSyncDepositQuoteValues(
+    publicClient,
+    runtime.provisioner.address,
+    runtime.feeCalculator.address,
+    runtime.feeCalculator.version,
+    vault.vaultAddress,
+    token.address,
+    params.amount
+  );
+  const minUnitsOut = applySlippageDown(unitsOut, slippageBps);
+  if (minUnitsOut <= 0n) throw new InvalidSyncDepositBoundError();
+
+  return { unitsOut, minUnitsOut, numeraireOut, feeBps, slippageBps };
+}
+
+/** Reads the live Instant Supply fee for a vault token, without requiring a deposit amount. */
+export async function getSyncDepositRate(
+  client: GauntletClient,
+  params: SyncDepositRateParams
+): Promise<SyncDepositRate> {
+  const { publicClient, runtime, token } = await resolveSyncDepositContext(client, params, 'rate');
+
+  const feeBps = await getSyncDepositFeeBps(
+    publicClient,
+    runtime.provisioner.address,
+    token.address
+  );
+  return { feeBps };
+}

package/src/evm/depositReceiverApproval.ts

@@ -25,6 +25,7 @@ export async function getDepositReceiverApprovalTx(
   client: GauntletClient,
   params: EvmDepositReceiverApprovalParams
 ): Promise<PreparedTx> {
+  params = { ...params };
   const resolved = await resolveVault(client, params.vaultId, params.chainId);
   if (!resolved) throw new VaultNotFoundError(params.vaultId);
 
@@ -39,13 +40,17 @@ export async function getDepositReceiverApprovalTx(
     throw new UnsupportedFeatureError('Aera: deposit receiver approval on V1');
   }
 
-  return encodeTransactionWithAttribution(client, {
-    type: 'setDepositReceiverApproval',
-    ...provisionerV2.setDepositReceiverApprovalTxRequest(
-      runtime.provisioner.address,
-      params.depositor,
-      params.approved ?? true,
-      receiver
-    ),
-  });
+  return encodeTransactionWithAttribution(
+    client,
+    {
+      type: 'setDepositReceiverApproval',
+      ...provisionerV2.setDepositReceiverApprovalTxRequest(
+        runtime.provisioner.address,
+        params.depositor,
+        params.approved ?? true,
+        receiver
+      ),
+    },
+    chainId
+  );
 }

package/src/evm/index.ts

@@ -1,7 +1,8 @@
 export { getDepositTx } from './deposit';
 export { getDepositReceiverApprovalTx } from './depositReceiverApproval';
+export { getSyncDepositQuote, getSyncDepositRate } from './depositQuote';
 export { getWithdrawTx } from './withdraw';
-export { getSyncWithdrawQuote } from './withdrawQuote';
+export { getSyncWithdrawQuote, getSyncWithdrawRate } from './withdrawQuote';
 export { getAeraTokenModeSupport } from './tokenModes';
 export { getUserCurrentBalance } from './userCurrentBalance';
 export { getVaults, VaultId } from './vaults';
@@ -14,6 +15,7 @@ export {
   ChainMismatchError,
   InvalidSlippageBPSError,
   InvalidSolverTipError,
+  InvalidSyncDepositBoundError,
   InvalidSyncWithdrawBoundError,
   InvalidWithdrawParamsError,
   RpcNotConfiguredError,
@@ -38,6 +40,12 @@ export {
 
 export type { EvmDepositParams } from './deposit';
 export type { EvmDepositReceiverApprovalParams } from './depositReceiverApproval';
+export type {
+  SyncDepositQuote,
+  SyncDepositQuoteParams,
+  SyncDepositRate,
+  SyncDepositRateParams,
+} from './depositQuote';
 export type { EvmWithdrawParams } from './withdraw';
 export type {
   SyncWithdrawQuote,
@@ -46,6 +54,7 @@ export type {
   SyncWithdrawQuoteContext,
   SyncWithdrawQuoteRequest,
   SyncWithdrawQuoteBounds,
+  SyncWithdrawRateParams,
 } from './withdrawQuote';
 export type { AeraTokenModeSupportParams } from './tokenModes';
 export type { SyncRedeemRate } from './aeraContracts/v2';

package/src/evm/userCurrentBalance.ts

@@ -1,12 +1,28 @@
 import { parseAbi, type Address } from 'viem';
 import type { GauntletClient } from '../client';
 import type { EvmVaultDeployment } from './types';
-import { ChainMismatchError, UnsupportedProtocolError, VaultNotFoundError } from '../errors';
+import {
+  ChainMismatchError,
+  GauntletSDKError,
+  UnsupportedAssetError,
+  UnsupportedProtocolError,
+  VaultNotFoundError,
+} from '../errors';
 import { getMultiDepositorVault, resolveAeraRuntimeContracts } from './aeraContracts';
 import { convertUnitsToToken } from './aeraContracts/priceAndFeeCalculator';
+import { getUserUnitsRefundableUntil } from './aeraContracts/v2';
 import { provisionerV2Abi } from './abis/provisionerV2';
 import { ContractVersion } from './types';
-import { BLOCKS_3_DAYS, CHAIN_NAMES, DEFAULT_BLOCKS_3_DAYS, LOG_PAGE_SIZE } from '../constants';
+import {
+  BLOCKS_3_DAYS,
+  CHAIN_NAMES,
+  DAY,
+  DEFAULT_BLOCKS_3_DAYS,
+  LOG_PAGE_SIZE,
+} from '../constants';
+
+// Log chunks fetched at once per event type.
+const LOG_CHUNK_CONCURRENCY = 16;
 
 // Inline as-const ABI items give viem full type inference for args and return types.
 const DEPOSIT_REQUESTED_V1_ABI = [
@@ -54,11 +70,24 @@ export interface UserCurrentBalanceParams {
   vaultId: string;
   address: Address;
   chainId?: number;
+  /** Required for deployments that support multiple assets, ignored otherwise. */
+  assetSymbol?: string;
+  /**
+   * Scan from this block, including expired requests that still hold escrow.
+   * Requires `chainId` for a vault with more than one deployment.
+   */
+  fromBlock?: bigint;
 }
 
 export interface UserCurrentBalance {
+  /** Block used for balances, conversions, and request state. */
+  blockNumber: bigint;
+  /** First block included in the request scan. Older escrow is outside this result. */
+  fromBlock: bigint;
   /** Chain identifier, e.g. "base" */
   chain: string;
+  /** EVM chain id of the deployment, e.g. 8453 */
+  chainId: number;
   token: Address;
   decimals: number;
   /** Assets queued via async deposit, not yet earning */
@@ -67,6 +96,8 @@ export interface UserCurrentBalance {
   balance: bigint;
   /** Assets queued via async withdraw, not yet claimable */
   pendingWithdraw: bigint;
+  /** Timestamp until which this account cannot redeem vault units. */
+  unitsLockedUntil?: bigint;
 }
 
 // V2 legacy wrapper calls can emit both receiver-aware and legacy events for one request.
@@ -86,21 +117,78 @@ function dedupeByRequestHash<TLog extends { args: { [key: string]: unknown } }>(
   });
 }
 
+/** Step back by the expected block count, and widen until the block predates the cutoff. */
+async function requestScanStart(
+  publicClient: ReturnType<GauntletClient['getPublicClient']>,
+  chainId: number,
+  blockNumber: bigint,
+  days: number,
+  cutoff: bigint
+): Promise<bigint> {
+  let span = ((BLOCKS_3_DAYS[chainId] ?? DEFAULT_BLOCKS_3_DAYS) * BigInt(days)) / 3n;
+  for (;;) {
+    if (span >= blockNumber) return 0n;
+    const start = blockNumber - span;
+    const block = await publicClient.getBlock({ blockNumber: start });
+    if (block.timestamp <= cutoff) return start;
+    span *= 2n;
+  }
+}
+
+async function mapInBatches<T, P extends Promise<unknown>>(
+  items: T[],
+  size: number,
+  fn: (item: T) => P
+): Promise<Awaited<P>[]> {
+  const results: Awaited<P>[] = [];
+  for (let i = 0; i < items.length; i += size) {
+    results.push(...(await Promise.all(items.slice(i, i + size).map(fn))));
+  }
+  return results;
+}
+
 async function queryDeploymentBalance(
   client: GauntletClient,
   deployment: EvmVaultDeployment,
-  address: Address
+  params: UserCurrentBalanceParams
 ): Promise<UserCurrentBalance> {
   const publicClient = client.getPublicClient(deployment.chainId);
-  const token = deployment.supplyToken[0];
+  const { address } = params;
+  const token =
+    deployment.supplyToken.length > 1
+      ? deployment.supplyToken.find((candidate) => candidate.symbol === params.assetSymbol)
+      : deployment.supplyToken[0];
+  if (token === undefined)
+    throw new UnsupportedAssetError(params.assetSymbol ?? 'unknown', params.vaultId);
+  const snapshot = await publicClient.getBlock({ blockTag: 'latest' });
+  if (snapshot.number === null) {
+    throw new GauntletSDKError('The balance snapshot has no block number');
+  }
+  const blockNumber = snapshot.number;
+  const readOptions = { blockNumber };
+  const expirationDays = deployment.expirationDays ?? 3;
+  if (!Number.isSafeInteger(expirationDays) || expirationDays <= 0) {
+    throw new GauntletSDKError('The request expiration must be a positive integer number of days');
+  }
+  const scanDays = Math.max(3, expirationDays);
+  const cutoff = snapshot.timestamp - BigInt(DAY) * BigInt(scanDays);
+  const fromBlock =
+    params.fromBlock ??
+    (await requestScanStart(publicClient, deployment.chainId, blockNumber, scanDays, cutoff));
+  if (fromBlock < 0n || fromBlock > blockNumber) {
+    throw new GauntletSDKError('The request scan range is invalid');
+  }
 
   const vaultContract = getMultiDepositorVault(publicClient, deployment.vaultAddress);
   const [runtime, units] = await Promise.all([
-    resolveAeraRuntimeContracts(publicClient, deployment),
-    vaultContract.read.balanceOf([address]),
+    resolveAeraRuntimeContracts(publicClient, deployment, readOptions),
+    vaultContract.read.balanceOf([address], readOptions),
   ]);
   const provisionerAddress = runtime.provisioner.address;
   const isV2 = runtime.provisioner.version === ContractVersion.V2;
+  const unitsLockedUntilPromise = isV2
+    ? getUserUnitsRefundableUntil(publicClient, provisionerAddress, address, readOptions)
+    : Promise.resolve(undefined);
 
   const balance = await convertUnitsToToken(
     publicClient,
@@ -108,63 +196,56 @@ async function queryDeploymentBalance(
     runtime.feeCalculator.version,
     deployment.vaultAddress,
     token.address,
-    units
+    units,
+    readOptions
   );
 
-  // Look back ~3 days for pending async requests
-  const currentBlock = await publicClient.getBlockNumber();
-  const lookback = BLOCKS_3_DAYS[deployment.chainId] ?? DEFAULT_BLOCKS_3_DAYS;
-  const fromBlock = currentBlock > lookback ? currentBlock - lookback : 0n;
-
-  // Compute block-range chunks to stay within the 10,000-block RPC limit, then fetch in parallel
+  // Compute block-range chunks to stay within the 10,000-block RPC limit, then fetch in bounded batches
   const chunks: [bigint, bigint][] = [];
-  for (let cursor = fromBlock; cursor <= currentBlock; cursor += LOG_PAGE_SIZE + 1n) {
-    const end = cursor + LOG_PAGE_SIZE <= currentBlock ? cursor + LOG_PAGE_SIZE : currentBlock;
+  for (let cursor = fromBlock; cursor <= blockNumber; cursor += LOG_PAGE_SIZE + 1n) {
+    const end = cursor + LOG_PAGE_SIZE <= blockNumber ? cursor + LOG_PAGE_SIZE : blockNumber;
     chunks.push([cursor, end]);
   }
 
+  // Each map keeps LOG_CHUNK_CONCURRENCY queries in flight.
   const [depositPages, redeemPages] = await Promise.all([
-    Promise.all(
-      chunks.map(([from, to]) =>
-        isV2
-          ? publicClient.getContractEvents({
-              address: provisionerAddress,
-              abi: provisionerV2Abi,
-              eventName: 'DepositRequested',
-              args: { receiver: address },
-              fromBlock: from,
-              toBlock: to,
-            })
-          : publicClient.getContractEvents({
-              address: provisionerAddress,
-              abi: DEPOSIT_REQUESTED_V1_ABI,
-              eventName: 'DepositRequested',
-              args: { user: address },
-              fromBlock: from,
-              toBlock: to,
-            })
-      )
+    mapInBatches(chunks, LOG_CHUNK_CONCURRENCY, ([from, to]) =>
+      isV2
+        ? publicClient.getContractEvents({
+            address: provisionerAddress,
+            abi: provisionerV2Abi,
+            eventName: 'DepositRequested',
+            args: { receiver: address, token: token.address },
+            fromBlock: from,
+            toBlock: to,
+          })
+        : publicClient.getContractEvents({
+            address: provisionerAddress,
+            abi: DEPOSIT_REQUESTED_V1_ABI,
+            eventName: 'DepositRequested',
+            args: { user: address, token: token.address },
+            fromBlock: from,
+            toBlock: to,
+          })
     ),
-    Promise.all(
-      chunks.map(([from, to]) =>
-        isV2
-          ? publicClient.getContractEvents({
-              address: provisionerAddress,
-              abi: provisionerV2Abi,
-              eventName: 'RedeemRequested',
-              args: { user: address },
-              fromBlock: from,
-              toBlock: to,
-            })
-          : publicClient.getContractEvents({
-              address: provisionerAddress,
-              abi: REDEEM_REQUESTED_V1_ABI,
-              eventName: 'RedeemRequested',
-              args: { user: address },
-              fromBlock: from,
-              toBlock: to,
-            })
-      )
+    mapInBatches(chunks, LOG_CHUNK_CONCURRENCY, ([from, to]) =>
+      isV2
+        ? publicClient.getContractEvents({
+            address: provisionerAddress,
+            abi: provisionerV2Abi,
+            eventName: 'RedeemRequested',
+            args: { user: address, token: token.address },
+            fromBlock: from,
+            toBlock: to,
+          })
+        : publicClient.getContractEvents({
+            address: provisionerAddress,
+            abi: REDEEM_REQUESTED_V1_ABI,
+            eventName: 'RedeemRequested',
+            args: { user: address, token: token.address },
+            fromBlock: from,
+            toBlock: to,
+          })
     ),
   ]);
 
@@ -188,6 +269,7 @@ async function queryDeploymentBalance(
       })),
     ],
     allowFailure: false,
+    blockNumber,
   });
 
   const depositChecks = pendingChecks.slice(0, depositLogs.length);
@@ -215,17 +297,23 @@ async function queryDeploymentBalance(
           runtime.feeCalculator.version,
           deployment.vaultAddress,
           token.address,
-          pendingWithdrawUnits
+          pendingWithdrawUnits,
+          readOptions
         )
       : 0n;
+  const unitsLockedUntil = await unitsLockedUntilPromise;
 
   return {
+    blockNumber,
+    fromBlock,
     chain: CHAIN_NAMES[deployment.chainId] ?? `chain-${deployment.chainId}`,
+    chainId: deployment.chainId,
     token: token.address,
     decimals: token.decimals,
     pendingDeposit,
     balance,
     pendingWithdraw,
+    ...(unitsLockedUntil !== undefined ? { unitsLockedUntil } : {}),
   };
 }
 
@@ -238,7 +326,9 @@ async function queryDeploymentBalance(
  * - `pendingWithdraw` — vault units locked in a pending async redeem request (converted to tokens).
  *
  * Only supported for Aera multi-depositor vaults. Pending amounts are detected by scanning
- * the last ~3 days of provisioner events and cross-checking hash existence on-chain.
+ * the configured request lifetime, with a minimum of three days. Set `fromBlock` (with `chainId`
+ * on a multi-chain vault) for older escrow.
+ * All state reads use one block. The returned range identifies the scanned history.
  *
  * @param client - A configured `GauntletClient` instance with an EVM public client for each
  *   chain the vault is deployed on.
@@ -249,6 +339,7 @@ async function queryDeploymentBalance(
  * @throws {VaultNotFoundError} If the vault ID is not found in the manifest.
  * @throws {UnsupportedProtocolError} If the vault is not an Aera multi-depositor vault.
  * @throws {ChainMismatchError} If `chainId` is specified but no deployment exists for that chain.
+ * @throws {UnsupportedAssetError} If a multi-asset deployment gets no matching `assetSymbol`.
  *
  * @example
  * ```ts
@@ -256,13 +347,14 @@ async function queryDeploymentBalance(
  *   vaultId: 'baseUsdcPrime',
  *   address: '0xYourWalletAddress',
  * });
- * // [{ chain: 'base', token: '0x...', decimals: 6, balance: 100_000_000n, pendingDeposit: 0n, pendingWithdraw: 0n }]
+ * // [{ chain: 'base', chainId: 8453, token: '0x...', decimals: 6, balance: 100_000_000n, pendingDeposit: 0n, pendingWithdraw: 0n }]
  * ```
  */
 export async function getUserCurrentBalance(
   client: GauntletClient,
   params: UserCurrentBalanceParams
 ): Promise<UserCurrentBalance[]> {
+  params = { ...params };
   const manifest = await client.manifest;
   const vaultInfo = manifest.vaults.find((v) => v.vaultId === params.vaultId);
   if (!vaultInfo) throw new VaultNotFoundError(params.vaultId);
@@ -283,8 +375,11 @@ export async function getUserCurrentBalance(
         evmDeployments.map((d) => `${d.chainId}`).join(', ')
       );
     }
-    return [await queryDeploymentBalance(client, deployment, params.address)];
+    return [await queryDeploymentBalance(client, deployment, params)];
+  }
+  if (params.fromBlock !== undefined && evmDeployments.length > 1) {
+    throw new GauntletSDKError('fromBlock requires chainId for a vault with several deployments');
   }
 
-  return Promise.all(evmDeployments.map((d) => queryDeploymentBalance(client, d, params.address)));
+  return Promise.all(evmDeployments.map((d) => queryDeploymentBalance(client, d, params)));
 }