@augustdigital/sdk 9.3.0 → 9.4.0

package/lib/modules/vaults/getters.js

@@ -69,6 +69,7 @@ const types_1 = require("../../types");
 const core_1 = require("../../core");
 const ethers_1 = require("ethers");
 const cache_1 = require("../../core/cache");
+const concurrency_1 = require("../../core/helpers/concurrency");
 const utils_1 = require("./utils");
 const subgraph_1 = require("../../services/subgraph");
 const vaults_1 = require("../../services/subgraph/vaults");
@@ -127,9 +128,13 @@ const errors_1 = require("../../core/errors");
  */
 async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }) {
     let returnedVault;
+    // Hoisted out of the try so the allocations enrichment below can reuse the
+    // row instead of re-fetching it.
+    let tokenizedVault;
     try {
-        const tokenizedVault = prefetchedRow ??
-            (await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots))?.[0];
+        tokenizedVault =
+            prefetchedRow ??
+                (await (0, core_1.fetchTokenizedVault)(vault, options?.headers, loadSubaccounts, loadSnapshots))?.[0];
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         switch (vaultVersion) {
             case 'sol-0': {
@@ -175,12 +180,24 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
         core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for this vault — skipping', { vault, version: returnedVault.version });
     }
     if (!(0, core_1.isBadVault)(vault) && (readLoans || readAllocations)) {
+        // `getVaultAllocations` reads `.subaccounts`/`.eoa_operators` off the row to
+        // discover borrowers, so the row is withheld unless it can carry them and
+        // the getter fetches a full one itself. Both guards matter: `loadSubaccounts:
+        // false` can answer with the keys present but empty, and a row threaded in
+        // from `getVaults` comes from the list endpoint rather than this one. Getting
+        // either wrong resolves zero borrowers with no error — the silent-empty
+        // failure this de-duplication exists to avoid.
+        const allocationsRow = loadSubaccounts !== false &&
+            tokenizedVault?.subaccounts &&
+            tokenizedVault?.eoa_operators
+            ? tokenizedVault
+            : undefined;
         const [loansResult, allocationsResult] = await Promise.allSettled([
             readLoans
                 ? getVaultLoans(returnedVault, options)
                 : Promise.resolve(undefined),
             readAllocations
-                ? getVaultAllocations(vault, options)
+                ? getVaultAllocations(vault, options, allocationsRow)
                 : Promise.resolve(undefined),
         ]);
         if (readLoans) {
@@ -401,6 +418,125 @@ async function getVaultSubaccountLoans(vault, options) {
  * the backend distinguish the two cases with a status of its own.
  */
 const EXPECTED_SUBACCOUNT_FETCH_STATUSES = new Set([204, 400, 404]);
+/**
+ * How long a per-borrower CeFi/OTC enrichment result stays cached, in ms.
+ *
+ * `getVaultAllocations` asks for the same borrowers on every call, and a vault
+ * page re-renders far more often than a CeFi balance changes. Without a cache
+ * each render re-issued one request per borrower — together, the two endpoints
+ * accounted for ~15.7k of the weekly `AugustTimeoutError` events in production.
+ *
+ * A `null` answer ("this borrower has no CeFi/OTC record") is cached alongside
+ * real data: it is the common case and just as worth remembering as a hit.
+ * Failures are NOT cached — they leave the key absent so the next call retries.
+ *
+ * 60s keeps a burst of renders on a single request while staying well inside
+ * the freshness any allocation view needs. Entries live in the shared process
+ * `CACHE`, so `CACHE.clear()` drops them along with everything else.
+ */
+const SUBACCOUNT_ENRICHMENT_TTL_MS = 1000 * 60;
+/** Shared-cache key for a borrower's CeFi positions. */
+const cefiCacheKey = (borrower) => `subaccount-cefi-${borrower}`;
+/** Shared-cache key for a borrower's OTC positions. */
+const otcCacheKey = (borrower) => `subaccount-otc-${borrower}`;
+/**
+ * Maximum simultaneous subaccount enrichment requests.
+ *
+ * Each borrower costs 2 requests (CeFi + OTC), so a window of 5 means at most
+ * 5 open connections to the August API from one `getVaultAllocations` call.
+ * Worst-case RPC/HTTP volume for a 40-borrower vault: 80 requests, 5 at a time,
+ * versus 80 sequential before — and versus 80 simultaneous had this been a bare
+ * `Promise.all`.
+ */
+const SUBACCOUNT_FETCH_CONCURRENCY = 5;
+/**
+ * Fetch one borrower's CeFi positions, memoized for
+ * {@link SUBACCOUNT_ENRICHMENT_TTL_MS}.
+ *
+ * @param borrower - Subaccount/borrower address.
+ * @param options - Vault options carrying `augustKey` and monitoring headers.
+ * @param vault - Vault address, for log context only.
+ * @returns The borrower's CeFi positions, or `null` when the backend has no
+ *   record (or the fetch failed — this is best-effort enrichment and never
+ *   throws).
+ */
+async function fetchSubaccountCefi(borrower, options, vault) {
+    const key = cefiCacheKey(borrower);
+    // `has` rather than a truthiness check: `null` is a cached answer ("no
+    // record for this borrower"), not a miss.
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    try {
+        const cefiResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.cefi(borrower), { headers: options?.headers });
+        if (cefiResponse.status === 200) {
+            const cefiRes = (await cefiResponse.json());
+            cache_1.CACHE.set(key, cefiRes, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+            return cefiRes;
+        }
+        // 404 means "this subaccount has no CeFi position", which is the common
+        // case for most borrowers — a breadcrumb, not an exception.
+        logSubaccountFetchFailure('getVaultAllocations:cefi', cefiResponse.status, cefiResponse.statusText, { vault, borrower });
+        if (EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(cefiResponse.status)) {
+            // A known "no record" answer is a stable fact about this borrower; cache
+            // it so the next render does not re-ask.
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+    catch (e) {
+        const status = httpStatusFromError(e);
+        logSubaccountFetchFailure('getVaultAllocations:cefi', status, e, {
+            vault,
+            borrower,
+        });
+        if (status !== undefined &&
+            EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+}
+/**
+ * Fetch one borrower's OTC positions, memoized for
+ * {@link SUBACCOUNT_ENRICHMENT_TTL_MS}. Mirrors {@link fetchSubaccountCefi}.
+ *
+ * @param borrower - Subaccount/borrower address.
+ * @param options - Vault options carrying `augustKey` and monitoring headers.
+ * @param vault - Vault address, for log context only.
+ * @returns The borrower's OTC position, or `null` when absent or unfetchable.
+ */
+async function fetchSubaccountOtc(borrower, options, vault) {
+    const key = otcCacheKey(borrower);
+    if (cache_1.CACHE.has(key))
+        return cache_1.CACHE.get(key);
+    try {
+        const otcResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.otc_positions(borrower), { headers: options?.headers });
+        if (otcResponse.status === 200) {
+            const otcRes = (await otcResponse.json());
+            cache_1.CACHE.set(key, otcRes, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+            return otcRes;
+        }
+        // 404 means "this subaccount has no OTC positions" — expected for nearly
+        // every borrower. See logSubaccountFetchFailure.
+        logSubaccountFetchFailure('getVaultAllocations:otc', otcResponse.status, otcResponse.statusText, { vault, borrower });
+        if (EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(otcResponse.status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+    catch (e) {
+        const status = httpStatusFromError(e);
+        logSubaccountFetchFailure('getVaultAllocations:otc', status, e, {
+            vault,
+            borrower,
+        });
+        if (status !== undefined &&
+            EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+            cache_1.CACHE.set(key, null, { ttl: SUBACCOUNT_ENRICHMENT_TTL_MS });
+        }
+        return null;
+    }
+}
 /**
  * Log a per-subaccount enrichment fetch failure at the right severity.
  *
@@ -458,9 +594,16 @@ function httpStatusFromError(error) {
  *
  * @param vault - Vault address
  * @param options - RPC configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVault` fetched it one call earlier),
+ *   passing it skips this function's own `GET /tokenized_vault/{address}` — a
+ *   pure de-duplication of backend traffic. The row must carry the subaccount
+ *   data this function reads (`.subaccounts`, `.eoa_operators`), so it must not
+ *   have been fetched with `loadSubaccounts: false`; a row fetched that way
+ *   would silently resolve zero borrowers.
  * @returns Detailed allocation data with exposure categorization
  */
-async function getVaultAllocations(vault, options) {
+async function getVaultAllocations(vault, options, tokenizedVault) {
     // to be used on upshift UI
     const protocolExposure = [];
     const tokenExposure = [];
@@ -500,18 +643,19 @@ async function getVaultAllocations(vault, options) {
     };
     // Determine wallets to fetch allocation responses from
     let uniqueBorrowers = [];
-    const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
+    const vaultRow = tokenizedVault ??
+        (await (0, core_1.fetchTokenizedVault)(vault, options?.headers))?.[0];
     // fetch all vault unique subaccounts/loan borrowers
     try {
-        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const vaultVersion = (0, core_1.getVaultVersionV2)(vaultRow);
         if (vaultVersion === 'evm-0') {
             const loans = await getVaultLoans(vault, options);
             uniqueBorrowers = [...new Set(loans.map((l) => l.borrower))];
         }
         else {
-            const eoa_operators = tokenizedVault.eoa_operators.map((s) => s.address);
+            const eoa_operators = vaultRow.eoa_operators.map((s) => s.address);
             uniqueBorrowers = [
-                ...tokenizedVault.subaccounts.map((s) => s.address),
+                ...vaultRow.subaccounts.map((s) => s.address),
                 ...eoa_operators,
             ];
         }
@@ -583,76 +727,66 @@ async function getVaultAllocations(vault, options) {
             }
         }
         // Fetch portfolio data for non-EVM borrowers (EVM handled by fetchVaultDebankResponse above).
-        // CeFi and OTC fetches below run for ALL borrowers regardless of chain type.
+        // Sequential by design: this branch only runs for non-EVM borrowers (a
+        // handful per vault) and each parser call mutates the shared accumulators
+        // below, which are not safe to interleave.
         for (const borrower of uniqueBorrowers) {
             const chainType = (0, core_1.getAddressChainType)(borrower);
-            if (chainType !== 'evm') {
-                const fetcher = borrowerPortfolioFetchers[chainType];
-                if (fetcher) {
-                    try {
-                        const debankRes = await fetcher(borrower);
-                        if (debankRes) {
-                            (0, debank_1.parseVaultLevelDebank)(debankRes, protocolExposure, tokenExposure, borrower, exposurePerCategory, netValue);
-                            unfilteredTokens = debankRes?.subaccount?.tokens;
-                            defiPerBorrower[borrower] = (0, debank_1.parseLoanLevelDebank)(debankRes);
-                        }
-                        else {
-                            debankErr = true;
-                        }
-                    }
-                    catch (error) {
-                        core_1.Logger.log.error(`getVaultAllocations:${chainType}`, error, {
-                            vault,
-                            borrower,
-                        });
-                        debankErr = true;
-                    }
-                }
-                else {
-                    // Not an error: portfolio providers simply have no coverage for this
-                    // chain type yet (Stellar, Sui). Reporting it as an exception filled
-                    // Sentry with a known, permanent gap, and setting `debankErr` made
-                    // every Stellar vault throw `failure to fetch debank response`
-                    // instead of returning the CeFi/OTC/loan allocations it did resolve.
-                    core_1.Logger.log.warn(`getVaultAllocations:no_fetcher`, {
-                        vault,
-                        borrower,
-                        chainType,
-                        reason: `No portfolio fetcher for chain type: ${chainType}`,
-                    });
-                }
+            if (chainType === 'evm')
+                continue;
+            const fetcher = borrowerPortfolioFetchers[chainType];
+            if (!fetcher) {
+                // Not an error: portfolio providers simply have no coverage for this
+                // chain type yet (Stellar, Sui). Reporting it as an exception filled
+                // Sentry with a known, permanent gap, and setting `debankErr` made
+                // every Stellar vault throw `failure to fetch debank response`
+                // instead of returning the CeFi/OTC/loan allocations it did resolve.
+                core_1.Logger.log.warn(`getVaultAllocations:no_fetcher`, {
+                    vault,
+                    borrower,
+                    chainType,
+                    reason: `No portfolio fetcher for chain type: ${chainType}`,
+                });
+                continue;
             }
-            // fetch cefi_positions
             try {
-                const cefiResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.cefi(borrower), { headers: options?.headers });
-                if (cefiResponse.status !== 200) {
-                    // 404 means "this subaccount has no CeFi position", which is the
-                    // common case for most borrowers — a breadcrumb, not an exception.
-                    logSubaccountFetchFailure('getVaultAllocations:cefi', cefiResponse.status, cefiResponse.statusText, { vault, borrower });
+                const debankRes = await fetcher(borrower);
+                if (debankRes) {
+                    (0, debank_1.parseVaultLevelDebank)(debankRes, protocolExposure, tokenExposure, borrower, exposurePerCategory, netValue);
+                    unfilteredTokens = debankRes?.subaccount?.tokens;
+                    defiPerBorrower[borrower] = (0, debank_1.parseLoanLevelDebank)(debankRes);
                 }
-                if (cefiResponse.status === 200) {
-                    const cefiRes = (await cefiResponse.json());
-                    cefiExposure = [...cefiExposure, ...cefiRes];
+                else {
+                    debankErr = true;
                 }
             }
-            catch (e) {
-                logSubaccountFetchFailure('getVaultAllocations:cefi', httpStatusFromError(e), e, { vault, borrower });
+            catch (error) {
+                core_1.Logger.log.error(`getVaultAllocations:${chainType}`, error, {
+                    vault,
+                    borrower,
+                });
+                debankErr = true;
             }
-            // fetch otc_positions
-            try {
-                const otcResponse = await (0, core_1.fetchAugustWithKey)(options.augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.otc_positions(borrower), { headers: options?.headers });
-                if (otcResponse.status !== 200) {
-                    // 404 means "this subaccount has no OTC positions" — expected for
-                    // nearly every borrower. See logSubaccountFetchFailure.
-                    logSubaccountFetchFailure('getVaultAllocations:otc', otcResponse.status, otcResponse.statusText, { vault, borrower });
-                }
-                if (otcResponse.status === 200) {
-                    const otcRes = (await otcResponse.json());
-                    otcPositions[borrower] = otcRes;
-                }
+        }
+        // CeFi and OTC enrichment runs for ALL borrowers regardless of chain type.
+        // Previously sequential — one borrower's slow (or timing-out) request
+        // delayed every borrower behind it, so a vault with N borrowers serialised
+        // 2N requests. Now cached per borrower and run through a bounded window:
+        // fewer requests, and the ones that remain overlap without stampeding the
+        // API. Both fetchers swallow their own failures, so no result is rejected.
+        const subaccountPositions = await (0, concurrency_1.mapWithConcurrency)(uniqueBorrowers, SUBACCOUNT_FETCH_CONCURRENCY, async (borrower) => ({
+            borrower,
+            cefi: await fetchSubaccountCefi(borrower, options, vault),
+            otc: await fetchSubaccountOtc(borrower, options, vault),
+        }));
+        // Fold sequentially so the accumulated order stays deterministic and
+        // independent of which request finished first.
+        for (const { borrower, cefi, otc } of subaccountPositions) {
+            if (cefi) {
+                cefiExposure = [...cefiExposure, ...cefi];
             }
-            catch (e) {
-                logSubaccountFetchFailure('getVaultAllocations:otc', httpStatusFromError(e), e, { vault, borrower });
+            if (otc) {
+                otcPositions[borrower] = otc;
             }
         }
     }
@@ -2106,7 +2240,7 @@ async function getYieldLastRealizedOn({ vault, options, }) {
     }
 }
 /**
- * Guard against the 2026-07-09 lifetime-PnL over-inflation failure mode.
+ * Guard against lifetime-PnL over-inflation when the deposit history fails to load.
  *
  * Lifetime PnL is `currentPosition + totalWithdrawn - totalDeposited`. When the
  * deposit/withdrawal history fails to load it collapses to empty, so both
@@ -2714,7 +2848,7 @@ async function getVaultHistoricalTimeseries({ vault, nDays, options, }) {
  * Supported Vaults: cUSDO, tETH, wstETH, rsETH
  *
  * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
- * These fields will be removed on 2026-01-01.
+ * These fields will be removed in the next major release.
  * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
  *
  * @param vault - Vault contract address

package/lib/modules/vaults/main.d.ts

@@ -55,8 +55,8 @@ export declare class AugustVaults extends AugustBase {
      * `balanceOf`/`lagDuration` reads are aggregated into chunked Multicall3
      * `aggregate3` batches per chain (10 calls per chunk) on chains where the
      * canonical Multicall3 deployment is verified; other chains (e.g. Citrea
-     * 4114) keep one `eth_call` per read. Measured with
-     * `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * 4114) keep one `eth_call` per read. Measured on a
+     * cold cache for a wallet with 62
      * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
      * 54 after (~35% fewer; 124 per-vault `eth_call`s collapse into ~13
      * `aggregate3` calls — the remaining requests are the per-vault cached
@@ -217,7 +217,7 @@ export declare class AugustVaults extends AugustBase {
      * Multicall3 `aggregate3` batches per chain (10 calls per chunk) on chains
      * where the canonical deployment is verified; unverified chains (e.g.
      * Citrea 4114) and non-EVM vaults keep one `eth_call` per read. Measured
-     * with `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * on a cold cache for a wallet with 62
      * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
      * 54 after (~35% fewer). A vault whose batched read fails (e.g. paused)
      * falls back to its own per-vault reads — never to a zeroed balance.
@@ -469,7 +469,7 @@ export declare class AugustVaults extends AugustBase {
      * Supported Vaults: cUSDO, tETH, wstETH, rsETH
      *
      * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
-     * These fields will be removed on 2026-01-01.
+     * These fields will be removed in the next major release.
      * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
      *
      * @param vault Vault address

package/lib/modules/vaults/main.js

@@ -127,8 +127,8 @@ class AugustVaults extends core_1.AugustBase {
      * `balanceOf`/`lagDuration` reads are aggregated into chunked Multicall3
      * `aggregate3` batches per chain (10 calls per chunk) on chains where the
      * canonical Multicall3 deployment is verified; other chains (e.g. Citrea
-     * 4114) keep one `eth_call` per read. Measured with
-     * `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * 4114) keep one `eth_call` per read. Measured on a
+     * cold cache for a wallet with 62
      * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
      * 54 after (~35% fewer; 124 per-vault `eth_call`s collapse into ~13
      * `aggregate3` calls — the remaining requests are the per-vault cached
@@ -392,6 +392,9 @@ class AugustVaults extends core_1.AugustBase {
                 augustKey: this.keys?.august,
                 subgraphKey: this.keys?.graph,
                 headers: this.headers,
+                // Rebuilding these options previously dropped this, making the flag
+                // unreachable on the per-address path.
+                includeClosed: options?.includeClosed,
             },
             loadSubaccounts,
             loadSnapshots,
@@ -675,7 +678,7 @@ class AugustVaults extends core_1.AugustBase {
      * Multicall3 `aggregate3` batches per chain (10 calls per chunk) on chains
      * where the canonical deployment is verified; unverified chains (e.g.
      * Citrea 4114) and non-EVM vaults keep one `eth_call` per read. Measured
-     * with `benchmarks/request-counter.js` on a cold cache for a wallet with 62
+     * on a cold cache for a wallet with 62
      * vaults across Ethereum + Avalanche: 83 RPC HTTP requests before batching,
      * 54 after (~35% fewer). A vault whose batched read fails (e.g. paused)
      * falls back to its own per-vault reads — never to a zeroed balance.
@@ -1386,7 +1389,7 @@ class AugustVaults extends core_1.AugustBase {
      * Supported Vaults: cUSDO, tETH, wstETH, rsETH
      *
      * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
-     * These fields will be removed on 2026-01-01.
+     * These fields will be removed in the next major release.
      * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
      *
      * @param vault Vault address

package/lib/modules/vaults/read.actions.d.ts

@@ -223,3 +223,184 @@ export declare function balanceOf(signer: IContractRunner, options: IBalanceOfOp
  * ```
  */
 export declare function maxDeposit(signer: IContractRunner, options: IMaxDepositOptions): Promise<bigint>;
+/** Options for {@link getIdleLiquidity}. */
+export type IGetIdleLiquidityOptions = {
+    /** EVM-2 (Tokenized Vault V2) vault contract address. */
+    vault: IAddress;
+};
+/**
+ * Read an EVM-2 vault's idle (uncommitted) liquidity — the balance available
+ * to satisfy an instant redemption without a synchronous recall from the
+ * settlement module, computed as `getTotalAssets() - externalAssets()`.
+ *
+ * EVM-2 only. Two on-chain reads with no caching — call it immediately
+ * before sizing an instant redemption rather than reusing a stale value, and
+ * size the redemption against the result rather than against total assets.
+ *
+ * @returns Idle liquidity, in the vault's reference-asset raw units.
+ * @throws AugustValidationError on invalid vault address or a non-EVM-2 vault.
+ * @throws AugustSDKError when either underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 3 — vault-version lookup, `getTotalAssets`, `externalAssets`.
+ *
+ * @example
+ * ```ts
+ * const idle = await augustSdk.evm.getIdleLiquidity({ vault: vaultAddress });
+ * if (redeemAmount > idle) {
+ *   // fall back to a queued withdrawal instead of an instant one
+ * }
+ * ```
+ */
+export declare function getIdleLiquidity(signer: IContractRunner, options: IGetIdleLiquidityOptions): Promise<bigint>;
+/** Options for {@link lagDuration}. */
+export type ILagDurationOptions = {
+    /** EVM-2 (Tokenized Vault V2) vault contract address. */
+    vault: IAddress;
+};
+/**
+ * Read an EVM-2 vault's queued-withdrawal lag — the delay, in seconds,
+ * between `requestRedeem` and the withdrawal epoch becoming claimable.
+ *
+ * EVM-2 only. This value is per-vault (259,200s / 3 days on sentUSD, but
+ * shorter on other deployments) and can change after launch — read it live
+ * rather than hardcoding it.
+ *
+ * @returns Lag duration, in seconds.
+ * @throws AugustValidationError on invalid vault address or a non-EVM-2 vault.
+ * @throws AugustSDKError when the underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 2 — vault-version lookup, `lagDuration`.
+ *
+ * @example
+ * ```ts
+ * const seconds = await augustSdk.evm.lagDuration({ vault: vaultAddress });
+ * ```
+ */
+export declare function lagDuration(signer: IContractRunner, options: ILagDurationOptions): Promise<bigint>;
+/** Options for {@link getWithdrawalEpoch}. */
+export type IGetWithdrawalEpochOptions = {
+    /** EVM-2 (Tokenized Vault V2) vault contract address. */
+    vault: IAddress;
+};
+/** An EVM-2 vault's current withdrawal epoch, as read from `getWithdrawalEpoch()`. */
+export type IWithdrawalEpoch = {
+    year: bigint;
+    month: bigint;
+    day: bigint;
+    /** Unix timestamp at which the current epoch's queued withdrawals become claimable. */
+    claimableEpoch: bigint;
+};
+/**
+ * Read an EVM-2 vault's current withdrawal epoch.
+ *
+ * The on-chain return order is `(year, month, day, claimableEpoch)` —
+ * `claimableEpoch` last, not first. This is the opposite order from what
+ * `requestRedeem` returns (`(claimableEpoch, year, month, day)`, epoch
+ * first); treat that call's return value, not this one, as the source of
+ * truth for a specific withdrawal's claim date.
+ *
+ * @returns The vault's current withdrawal epoch, by named field.
+ * @throws AugustValidationError on invalid vault address or a non-EVM-2 vault.
+ * @throws AugustSDKError when the underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 2 — vault-version lookup, `getWithdrawalEpoch`.
+ *
+ * @example
+ * ```ts
+ * const { year, month, day, claimableEpoch } = await augustSdk.evm.getWithdrawalEpoch({
+ *   vault: vaultAddress,
+ * });
+ * ```
+ */
+export declare function getWithdrawalEpoch(signer: IContractRunner, options: IGetWithdrawalEpochOptions): Promise<IWithdrawalEpoch>;
+/** Options shared by the EVM-2 queued-withdrawal-date reads. */
+type IWithdrawalDateOptions = {
+    /** EVM-2 (Tokenized Vault V2) vault contract address. */
+    vault: IAddress;
+    /** Withdrawal-epoch year, as returned by `requestRedeem`/`getWithdrawalEpoch`. */
+    year: string | bigint | number;
+    /** Withdrawal-epoch month, same source as `year`. */
+    month: string | bigint | number;
+    /** Withdrawal-epoch day, same source as `year`. */
+    day: string | bigint | number;
+};
+/** Options for {@link getBurnableAmountByReceiver}. */
+export type IGetBurnableAmountByReceiverOptions = IWithdrawalDateOptions & {
+    /** Address whose claimable amount for this date is being queried. */
+    receiver: IAddress;
+};
+/**
+ * Read how much of a withdrawal-epoch date's queue a given receiver can
+ * currently claim via `claim`, before sending the claim transaction.
+ *
+ * EVM-2 only.
+ *
+ * @returns The claimable amount, in share-token raw units.
+ * @throws AugustValidationError on invalid address input or a non-EVM-2 vault.
+ * @throws AugustSDKError when the underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 2 — vault-version lookup, `getBurnableAmountByReceiver`.
+ *
+ * @example
+ * ```ts
+ * const claimable = await augustSdk.evm.getBurnableAmountByReceiver({
+ *   vault: vaultAddress,
+ *   receiver: walletAddress,
+ *   year, month, day,
+ * });
+ * ```
+ */
+export declare function getBurnableAmountByReceiver(signer: IContractRunner, options: IGetBurnableAmountByReceiverOptions): Promise<bigint>;
+/** Options for {@link getRequirementByDate}. */
+export type IGetRequirementByDateOptions = IWithdrawalDateOptions;
+/**
+ * Read the total shares required to settle a withdrawal-epoch date's entire
+ * queue.
+ *
+ * EVM-2 only.
+ *
+ * @returns Required shares, in share-token raw units.
+ * @throws AugustValidationError on invalid vault address or a non-EVM-2 vault.
+ * @throws AugustSDKError when the underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 2 — vault-version lookup, `getRequirementByDate`.
+ *
+ * @example
+ * ```ts
+ * const shares = await augustSdk.evm.getRequirementByDate({
+ *   vault: vaultAddress,
+ *   year, month, day,
+ * });
+ * ```
+ */
+export declare function getRequirementByDate(signer: IContractRunner, options: IGetRequirementByDateOptions): Promise<bigint>;
+/** Options for {@link getScheduledTransactionsByDate}. */
+export type IGetScheduledTransactionsByDateOptions = IWithdrawalDateOptions;
+/** Scheduled queued-withdrawal volume for a withdrawal-epoch date. */
+export type IScheduledTransactionsByDate = {
+    totalTransactions: bigint;
+    /** Unix timestamp this date's queue is scheduled to execute. */
+    executionEpoch: bigint;
+};
+/**
+ * Read the scheduled queued-withdrawal volume for a withdrawal-epoch date.
+ *
+ * EVM-2 only.
+ *
+ * @returns Total scheduled transactions and their execution epoch.
+ * @throws AugustValidationError on invalid vault address or a non-EVM-2 vault.
+ * @throws AugustSDKError when the underlying contract read fails.
+ *
+ * @worstCaseRpcCalls 2 — vault-version lookup, `getScheduledTransactionsByDate`.
+ *
+ * @example
+ * ```ts
+ * const { totalTransactions, executionEpoch } =
+ *   await augustSdk.evm.getScheduledTransactionsByDate({
+ *     vault: vaultAddress,
+ *     year, month, day,
+ *   });
+ * ```
+ */
+export declare function getScheduledTransactionsByDate(signer: IContractRunner, options: IGetScheduledTransactionsByDateOptions): Promise<IScheduledTransactionsByDate>;
+export {};