@augustdigital/sdk 8.25.0 → 9.0.0

package/lib/adapters/sui/getters.d.ts

@@ -1,6 +1,12 @@
 import type { IEmberVault, IFetchEmberVaultsOptions } from './types';
 /**
- * Fetch Ember vaults from API
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
  */
 export declare function getEmberVaults(options?: IFetchEmberVaultsOptions): Promise<IEmberVault[]>;
 /**

package/lib/adapters/sui/getters.js

@@ -4,9 +4,32 @@ exports.getEmberVaults = getEmberVaults;
 exports.getEmberTVL = getEmberTVL;
 const constants_1 = require("./constants");
 const core_1 = require("../../core");
+const cache_1 = require("../../core/cache");
 const logger_1 = require("../../core/logger");
 /**
- * Fetch Ember vaults from API
+ * Hard ceiling on the Ember (Bluefin) vaults request. The endpoint is a
+ * third-party API awaited on the `getVaults` hot path; without a bound, a
+ * hung connection stalls every vault-list consumer indefinitely (the fetch
+ * options carry no signal and no timeout). Measured latency is 0.24–1.02s,
+ * so 5s is ~5× the observed worst case while still failing fast enough for
+ * callers racing `getVaults` against their own budgets.
+ */
+const EMBER_FETCH_TIMEOUT_MS = 5_000;
+/**
+ * TTL for the cached Ember vaults payload. The set of active Ember vaults
+ * changes rarely (the SDK additionally filters it to a hardcoded allowlist),
+ * so 5 minutes matches the freshness of the other list-shaped caches without
+ * letting a stale payload outlive a delisting for long.
+ */
+const EMBER_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Fetch Ember vaults from API.
+ *
+ * Results are cached for {@link EMBER_CACHE_TTL_MS} (keyed by the full request
+ * URL, so different query options cache independently) and the request is
+ * aborted after {@link EMBER_FETCH_TIMEOUT_MS}. Failures — including timeouts —
+ * are never cached and resolve to `[]`, preserving the long-standing
+ * fail-tolerant contract of this getter.
  */
 async function getEmberVaults(options) {
     try {
@@ -19,12 +42,36 @@ async function getEmberVaults(options) {
             params.append('status', options.status);
         const queryString = params.toString();
         const url = `${constants_1.EMBER_API_BASE_URL}${queryString ? `?${queryString}` : ''}`;
-        const response = await fetch(url, core_1.DEFAULT_FETCH_OPTIONS);
-        if (!response.ok) {
-            throw new Error(`HTTP error! status: ${response.status}`);
+        const cacheKey = `ember-vaults-${url}`;
+        // The shared LRU is constructed with `allowStale: true`; opt out here so a
+        // payload past its TTL is refetched rather than served one last time —
+        // keeping the 5-minute bound above an exact contract.
+        const cached = cache_1.CACHE.get(cacheKey, { allowStale: false });
+        if (cached)
+            return cached;
+        // AbortController (not AbortSignal.timeout) for browser + older-Node parity.
+        // The timer stays armed through the body read: `fetch` resolves as soon as
+        // headers arrive, so clearing it there would leave a stalled `json()`
+        // unbounded — the exact hang the ceiling exists to prevent.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), EMBER_FETCH_TIMEOUT_MS);
+        let data;
+        try {
+            const response = await fetch(url, {
+                ...core_1.DEFAULT_FETCH_OPTIONS,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            data = await response.json();
+        }
+        finally {
+            clearTimeout(timer);
         }
-        const data = await response.json();
-        return Array.isArray(data) ? data : [];
+        const vaults = Array.isArray(data) ? data : [];
+        cache_1.CACHE.set(cacheKey, vaults, { ttl: EMBER_CACHE_TTL_MS });
+        return vaults;
     }
     catch (error) {
         logger_1.Logger.log.error('getEmberVaults', error);

package/lib/core/analytics/app-name.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validate an `appName` slug at SDK boundary points (the `AugustSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `AugustValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws AugustValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+export declare function validateAppName(value: unknown): string;

package/lib/core/analytics/app-name.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAppName = validateAppName;
+const errors_1 = require("../errors");
+/**
+ * Validate an `appName` slug at SDK boundary points (the `AugustSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `AugustValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws AugustValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+function validateAppName(value) {
+    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk#app-name';
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < 3 || trimmed.length > 64) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
+    }
+    if (/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` looks like a wallet address ("${trimmed}"). Pass an application slug like "acme-trader" — if you are calling initializeSentry directly, note that since v9 the argument order is (config, environment, appName, walletAddress?, apiKey?). ${docsHint}`);
+    }
+    return trimmed;
+}
+//# sourceMappingURL=app-name.js.map

package/lib/core/analytics/sentry.d.ts

@@ -12,16 +12,28 @@ export declare function resetErrorDedupe(): void;
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.
  *
+ * Breaking change in v9: `appName` moved from the optional fifth parameter
+ * to the required third parameter, so every telemetry stream carries an
+ * application identity (the `AugustSDK` constructor has required it since
+ * v5). Callers on the old positional order get a synchronous validation
+ * error rather than silently anonymous events.
+ *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
  *   override the default of `0.1`.
  * @param environment - Current environment (DEV or PROD).
+ * @param appName - App-name slug, required. Set as the global `app.name`
+ *   tag on every event and used to derive `partner.id`. Identifier-shaped:
+ *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+ *   rules the `AugustSDK` constructor enforces.
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).
- * @param appName - Optional app-name slug. Set as the global `app.name`
- *   tag on every event; falls back to `'unverified:anonymous'` when
- *   omitted.
+ * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+ *   missing, empty, mis-typed, out of the allowed length range, contains
+ *   disallowed characters, or is shaped like an EVM address. Thrown before
+ *   any analytics state mutates, even when analytics would be disabled by
+ *   config or environment gates.
  */
-export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
+export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, appName: string, walletAddress?: string, apiKey?: string): void;
 /**
  * Update the current user identity in Sentry.
  * Called when wallet address changes.

package/lib/core/analytics/sentry.js

@@ -9,6 +9,7 @@ exports.getSentry = getSentry;
 exports.resetAnalytics = resetAnalytics;
 exports.captureSdkException = captureSdkException;
 const logger_1 = require("../logger");
+const app_name_1 = require("./app-name");
 const constants_1 = require("./constants");
 const env_1 = require("./env");
 const sentry_runtime_1 = require("./sentry-runtime");
@@ -305,16 +306,32 @@ function createSentrySink() {
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.
  *
+ * Breaking change in v9: `appName` moved from the optional fifth parameter
+ * to the required third parameter, so every telemetry stream carries an
+ * application identity (the `AugustSDK` constructor has required it since
+ * v5). Callers on the old positional order get a synchronous validation
+ * error rather than silently anonymous events.
+ *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
  *   override the default of `0.1`.
  * @param environment - Current environment (DEV or PROD).
+ * @param appName - App-name slug, required. Set as the global `app.name`
+ *   tag on every event and used to derive `partner.id`. Identifier-shaped:
+ *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+ *   rules the `AugustSDK` constructor enforces.
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).
- * @param appName - Optional app-name slug. Set as the global `app.name`
- *   tag on every event; falls back to `'unverified:anonymous'` when
- *   omitted.
+ * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+ *   missing, empty, mis-typed, out of the allowed length range, contains
+ *   disallowed characters, or is shaped like an EVM address. Thrown before
+ *   any analytics state mutates, even when analytics would be disabled by
+ *   config or environment gates.
  */
-function initializeSentry(config, environment, walletAddress, apiKey, appName) {
+function initializeSentry(config, environment, appName, walletAddress, apiKey) {
+    // Enforce the identity contract before anything else — including the
+    // idempotency short-circuit and the disable gates — so a bad appName is
+    // equally loud on every call path and in every environment.
+    const validatedAppName = (0, app_name_1.validateAppName)(appName);
     // SDK construction runs this multiple times (base + adapter constructors).
     // Short-circuit so the disable-reason logs only once per process.
     if (isInitialized) {
@@ -473,11 +490,9 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         safeSetTag('sdk.runtime', (0, sentry_runtime_1.getSentryRuntime)());
         // `app.name` is the dimension we filter on in Sentry to attribute
         // events to a specific consuming application — see SDK quickstart docs.
-        if (appName) {
-            safeSetTag('app.name', appName);
-        }
+        safeSetTag('app.name', validatedAppName);
         // `unverified:` prefix until the backend API-key → partner-id endpoint exists.
-        safeSetTag('partner.id', appName ? `unverified:${appName}` : 'unverified:anonymous');
+        safeSetTag('partner.id', `unverified:${validatedAppName}`);
         safeSetTag('partner.tier', 'unverified');
         // Bridge the SDK's structured logger into Sentry now that the SDK is live.
         // Without this, Logger.log.error/warn are no-ops in production (no

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "8.25.0";
+export declare const SDK_VERSION = "9.0.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '8.25.0';
+exports.SDK_VERSION = '9.0.0';
 //# sourceMappingURL=version.js.map

package/lib/core/base.class.d.ts

@@ -25,7 +25,8 @@ export interface IAugustBase {
      * 3–64 characters, `[a-zA-Z0-9._-]` only. Use a slug ("acme-trader"),
      * not a display name ("Acme Trader").
      *
-     * @throws Throws synchronously from the constructor if missing or empty.
+     * @throws AugustValidationError synchronously from the constructor if
+     *   missing, empty, or malformed.
      *
      * @example
      * ```typescript
@@ -120,8 +121,8 @@ export declare class AugustBase {
      * Initialize base SDK with provider configuration and API keys.
      * Sets up the first provider as the active network by default.
      *
-     * @throws If `appName` is missing, malformed, or out of the allowed
-     *   length range — see {@link IAugustBase.appName}.
+     * @throws AugustValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IAugustBase.appName}.
      */
     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
     /**

package/lib/core/base.class.js

@@ -4,36 +4,10 @@ exports.AugustBase = void 0;
 const auth_1 = require("./auth");
 const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
+const app_name_1 = require("./analytics/app-name");
 const version_check_1 = require("./version-check");
 const fetcher_1 = require("./fetcher");
 const attribution_1 = require("./attribution");
-/**
- * Validate an appName at SDK construction time.
- *
- * Rules (kept intentionally narrow so the value is safe to use as a Sentry
- * tag, an HTTP header value, and a filesystem-safe identifier — this is
- * why we accept slugs only, not display names):
- *  - non-empty after trim
- *  - 3..64 characters
- *  - only `[a-zA-Z0-9._-]`
- *
- * Throws a descriptive Error that names the failed rule and includes a
- * remediation hint pointing at the docs link.
- */
-function validateAppName(value) {
-    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk#app-name';
-    if (typeof value !== 'string' || value.trim().length === 0) {
-        throw new Error(`August SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
-    }
-    const trimmed = value.trim();
-    if (trimmed.length < 3 || trimmed.length > 64) {
-        throw new Error(`August SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
-    }
-    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
-        throw new Error(`August SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
-    }
-    return trimmed;
-}
 /**
  * Base class providing core SDK functionality including provider management,
  * network switching, and authentication state.
@@ -53,13 +27,13 @@ class AugustBase {
      * Initialize base SDK with provider configuration and API keys.
      * Sets up the first provider as the active network by default.
      *
-     * @throws If `appName` is missing, malformed, or out of the allowed
-     *   length range — see {@link IAugustBase.appName}.
+     * @throws AugustValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IAugustBase.appName}.
      */
     constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }) {
         // Validate first so the failure mode is a clear, actionable error before
         // any provider / analytics side effects run.
-        this.appName = validateAppName(appName);
+        this.appName = (0, app_name_1.validateAppName)(appName);
         // TODO: change this to false later when august key is required
         this.authorized = true;
         this.providers = providers;
@@ -82,7 +56,7 @@ class AugustBase {
         logger_1.Logger.setDevMode(environment === 'DEV');
         // Initialize analytics (pass API key for hashed identification + the
         // appName so events can be filtered by consuming application).
-        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, monitoring?.['x-user-id'], keys?.august, this.appName);
+        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, this.appName, monitoring?.['x-user-id'], keys?.august);
         // Best-effort version nudge — fire-and-forget, never blocks init, no
         // network call in production. See `core/version-check.ts` for details.
         (0, version_check_1.runVersionCheck)(versionCheck);

package/lib/main.d.ts

@@ -7,9 +7,9 @@ import SolanaAdapter from './adapters/solana';
 import SuiAdapter from './adapters/sui';
 import StellarAdapter from './adapters/stellar';
 import EVMAdapter from './adapters/evm';
-import type { IAddress, IChainId, IVaultHistoricalParams, IWSMonitorHeaders } from './types';
+import type { IAddress, IChainId, IVaultHistoricalParams } from './types';
 import { AugustBase, type IAugustBase } from './core';
-import { AugustVaults, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
+import { AugustVaults, type IGetVaultsOptions, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
 import type { Signer, Wallet } from 'ethers';
 import type { IContractWriteOptions } from './modules/vaults/write.actions';
 import { AugustSubAccounts } from './modules/sub-accounts';
@@ -77,15 +77,12 @@ export declare class AugustSDK extends AugustBase {
     /**
      * Fetch all available vaults across configured networks.
      * Optionally filter by chain IDs and include loan/allocation data.
-     * @param options - Configuration for filtering and enriching vault data
+     * @param options - Configuration for filtering and enriching vault data —
+     * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+     * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
      * @returns Array of vault objects with metadata and optional position data
      */
-    getVaults(options?: {
-        chainIds?: number[];
-        headers?: IWSMonitorHeaders;
-        loadSubaccounts?: boolean;
-        loadSnapshots?: boolean;
-    } & IVaultCustomOptions): Promise<import("./types").IVault[]>;
+    getVaults(options?: IGetVaultsOptions): Promise<import("./types").IVault[]>;
     getTotalDeposited(options?: {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;

package/lib/main.js

@@ -207,7 +207,9 @@ class AugustSDK extends core_1.AugustBase {
     /**
      * Fetch all available vaults across configured networks.
      * Optionally filter by chain IDs and include loan/allocation data.
-     * @param options - Configuration for filtering and enriching vault data
+     * @param options - Configuration for filtering and enriching vault data —
+     * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+     * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
      * @returns Array of vault objects with metadata and optional position data
      */
     async getVaults(options) {

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

@@ -1,4 +1,4 @@
-import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
+import { type IAddress, type IHistoricalTimeseriesResponse, type INormalizedNumber, type ITokenizedVault, type ISubgraphWithdrawProccessed, type IVault, type IVaultAllocations, type IVaultAnnualizedApy, type IVaultAvailableRedemption, type IVaultLoan, type IVaultPosition, type IVaultRedemptionHistoryItem, type IVaultSummary, type IVaultWithdrawals, type IVaultPendingRedemptions, type IActiveStakingPosition, type IVaultHistoricalParams, type IVaultUserLifetimePnl, type IVaultBorrowerHealthFactor, type IVaultPnl, type VaultAddress } from '../../types';
 import type { IVaultBaseOptions } from './types';
 /**
  * Vault Data Getters
@@ -23,15 +23,22 @@ import type { IVaultBaseOptions } from './types';
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }: {
     vault: IAddress;
     loans?: boolean;
     allocations?: boolean;
     options: IVaultBaseOptions;
     loadSubaccounts?: boolean;
     loadSnapshots?: boolean;
+    tokenizedVault?: ITokenizedVault;
 }): Promise<IVault>;
 /**
  * Vault Loans

package/lib/modules/vaults/getters.js

@@ -112,13 +112,19 @@ const errors_1 = require("../../core/errors");
  * @param loans - Include active loan data
  * @param allocations - Include DeFi/CeFi allocation breakdowns
  * @param options - RPC and service configuration
+ * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+ *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+ *   call earlier), passing it skips this function's own
+ *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+ *   traffic. The row must have been fetched with the same
+ *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
  * @returns Complete vault object with optional enrichments
  */
-async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, }) {
+async function getVault({ vault, loans = false, allocations = false, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }) {
     let returnedVault;
     try {
-        const tokenizedVaultRaw = await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots);
-        const tokenizedVault = tokenizedVaultRaw?.[0];
+        const tokenizedVault = prefetchedRow ??
+            (await (0, core_1.fetchTokenizedVault)(vault, undefined, loadSubaccounts, loadSnapshots))?.[0];
         const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
         switch (vaultVersion) {
             case 'sol-0': {

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

@@ -13,8 +13,8 @@ import { AugustBase, type IAugustBase } from '../../core';
 import SuiAdapter from '../../adapters/sui';
 import { type IContractWriteOptions, type INativeDepositOptions } from './write.actions';
 import type { Signer, Wallet } from 'ethers';
-import type { IVaultBaseOptions, IVaultCustomOptions } from './types';
-export type { IVaultBaseOptions, IVaultCustomOptions } from './types';
+import type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions } from './types';
+export type { IGetVaultsOptions, IVaultBaseOptions, IVaultCustomOptions, } from './types';
 /**
  * Vault operations class handling multi-chain vault queries and user positions.
  * Supports both EVM and Solana vaults with unified interface.
@@ -64,32 +64,7 @@ export declare class AugustVaults extends AugustBase {
      * @param options Filtering and enrichment configuration
      * @returns Array of vault objects with optional loans/allocations/positions
      */
-    getVaults(options?: {
-        chainIds?: number[];
-        loadSubaccounts?: boolean;
-        loadSnapshots?: boolean;
-        /**
-         * Portfolio mode: include closed vaults in the result.
-         *
-         * By default (`false`) closed vaults are excluded, so marketplace /
-         * discovery callers never receive a `status: 'closed'` vault. When set,
-         * closed vaults are returned regardless of `is_visible` (closed +
-         * invisible vaults bucket as closed), so a consumer joining user
-         * positions can render a position held in a closed vault on the
-         * portfolio page.
-         *
-         * In this mode, loans/allocations enrichment is also skipped for closed
-         * vaults: they have none, and the per-vault enrichment
-         * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
-         * vault has no live strategy/debank data or no subaccounts, which would
-         * land the vault in the `failed` bucket and silently drop it before it
-         * reaches the filter. Skipping enrichment lets the vault survive on its
-         * backend metadata + base on-chain read.
-         *
-         * @default false
-         */
-        includeClosed?: boolean;
-    } & IVaultCustomOptions): Promise<import("../../types").IVault[]>;
+    getVaults(options?: IGetVaultsOptions): Promise<import("../../types").IVault[]>;
     /**
      * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
      * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.

package/lib/modules/vaults/main.js

@@ -53,6 +53,7 @@ __exportStar(require("./getters"), exports);
  * AugustVaults class
  */
 const fetcher_1 = require("./fetcher");
+const web3_1 = require("../../core/constants/web3");
 const ethers_1 = require("ethers");
 const getters_1 = require("./getters");
 const vaults_1 = require("../../services/subgraph/vaults");
@@ -152,22 +153,54 @@ class AugustVaults extends core_1.AugustBase {
         const vaultsPerChainId = options?.chainIds
             ? vaultsPerAvailableProviders.filter((v) => options.chainIds.includes(v.chain))
             : vaultsPerAvailableProviders;
-        // Fetch and transform (filter for active status)
-        const emberVaults = await this.suiService.getEmberVaults({
-            status: 'active',
+        // Skip vaults the post-enrichment filter (filterVaultsIntelligently +
+        // the includeClosed gate below) is guaranteed to drop, BEFORE paying
+        // their per-vault enrichment. `status` / `is_visible` land on the
+        // enriched vault verbatim from this backend row, so filtering on the row
+        // is exactly equivalent to filtering on the enriched result — it just
+        // saves the on-chain reads (and their retry backoff) for vaults that can
+        // never appear in the output. The post-filter below is kept unchanged as
+        // the authority on the final shape.
+        const enrichableVaults = vaultsPerChainId.filter((v) => {
+            const status = v?.status || 'unknown';
+            if (status === 'closed')
+                return !!options?.includeClosed;
+            if (status === 'active')
+                return true;
+            // Mirrors filterVaultsIntelligently: an unknown-status vault survives
+            // only through the invisible bucket; a visible one lands in `failed`.
+            return !(v?.is_visible ?? true);
         });
-        const activeEmberVaults = Array.isArray(emberVaults)
-            ? emberVaults.filter((v) => v?.status === 'active')
-            : [];
-        const whitelistedEmberVaults = activeEmberVaults.filter((v) => {
-            if (!v?.address)
-                return false;
-            const normalizedAddress = v.address.toLowerCase().trim();
-            return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
-        });
-        const transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        // The backend row for each vault about to be enriched. getVault re-uses
+        // it instead of re-fetching `GET /tokenized_vault/{address}` per vault —
+        // the row came from the same list response (same load flags), so this is
+        // a pure de-duplication of backend traffic, not a freshness change.
+        const vaultRowsByAddress = new Map(enrichableVaults.map((row) => [String(row.address).toLowerCase(), row]));
+        // Ember (Sui) vaults come from a third-party API and are appended to the
+        // non-wallet result. When the caller scopes the query with `chainIds` and
+        // that scope excludes Sui, skip the fetch entirely — previously it was
+        // awaited unconditionally, so a slow Bluefin endpoint stalled even
+        // EVM-only and Solana/Stellar-only queries.
+        const includeSuiVaults = !options?.chainIds || options.chainIds.includes(web3_1.SUI_CHAIN_ID);
+        let transformedVaults = [];
+        if (includeSuiVaults) {
+            // Fetch and transform (filter for active status)
+            const emberVaults = await this.suiService.getEmberVaults({
+                status: 'active',
+            });
+            const activeEmberVaults = Array.isArray(emberVaults)
+                ? emberVaults.filter((v) => v?.status === 'active')
+                : [];
+            const whitelistedEmberVaults = activeEmberVaults.filter((v) => {
+                if (!v?.address)
+                    return false;
+                const normalizedAddress = v.address.toLowerCase().trim();
+                return constants_1.ALLOWED_SUI_VAULT_ADDRESSES.includes(normalizedAddress);
+            });
+            transformedVaults = this.suiService.transformEmberVaultsToIVaults(whitelistedEmberVaults);
+        }
         // Use comprehensive vault fetching for maximum coverage
-        const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(vaultsPerChainId, async (vault) => {
+        const vaultFetchResult = await (0, fetcher_1.fetchVaultsComprehensive)(enrichableVaults, async (vault) => {
             // Handle fallback RPC if provided
             const rpcUrl = vault.fallbackRpc || this.providers?.[vault.chain];
             // Closed vaults have no live loans/allocations. In portfolio mode,
@@ -188,6 +221,9 @@ class AugustVaults extends core_1.AugustBase {
                 vault: vault.address,
                 loans: shouldFetchLoans,
                 allocations: shouldFetchAllocations,
+                // Re-use the backend row from the list response instead of letting
+                // getVault re-fetch it per vault (an N+1 against the backend).
+                tokenizedVault: vaultRowsByAddress.get(String(vault.address).toLowerCase()),
                 options: {
                     rpcUrl,
                     solanaService: this.solanaService,
@@ -204,8 +240,8 @@ class AugustVaults extends core_1.AugustBase {
             });
             return v;
         }, {
-            maxRetries: 5,
-            baseDelay: 2000,
+            maxRetries: options?.maxRetries ?? 5,
+            baseDelay: options?.baseDelay ?? 2000,
             batchSize: 15,
             parallelLimit: 8,
             includeClosed: true,
@@ -257,8 +293,8 @@ class AugustVaults extends core_1.AugustBase {
             ...(options?.includeClosed ? filteredResults.closed : []),
             ...filteredResults.invisible,
         ];
-        if ((options.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
-            (options.solanaWallet &&
+        if ((options?.wallet && (0, ethers_1.isAddress)(options.wallet)) ||
+            (options?.solanaWallet &&
                 utils_1.SolanaUtils.isSolanaAddress(options.solanaWallet))) {
             // Batch the per-vault balanceOf/lagDuration reads (Multicall3, grouped
             // by chain) before fanning out — vaults the batch couldn't serve fall
@@ -294,7 +330,7 @@ class AugustVaults extends core_1.AugustBase {
                 position: positions?.find((pos) => pos.vault?.toLowerCase() === r.address?.toLowerCase()) || null,
             }));
         }
-        if (options.wallet && !(0, ethers_1.isAddress)(options.wallet)) {
+        if (options?.wallet && !(0, ethers_1.isAddress)(options.wallet)) {
             core_1.Logger.log.warn('getVaults:invalid_wallet', options.wallet);
         }
         // console.log(`#getVaults:`, filteredResponses);

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

@@ -69,3 +69,55 @@ export interface IVaultCustomOptions {
     solanaWallet?: string;
     stellarWallet?: string;
 }
+/**
+ * Options accepted by `getVaults` — on both the `AugustSDK` facade and the
+ * underlying `AugustVaults` module. Defined once so the two signatures cannot
+ * drift (the facade previously declared a narrower inline type that rejected
+ * documented options like `includeClosed` at compile time).
+ */
+export interface IGetVaultsOptions extends IVaultCustomOptions {
+    chainIds?: number[];
+    headers?: IWSMonitorHeaders;
+    loadSubaccounts?: boolean;
+    loadSnapshots?: boolean;
+    /**
+     * Portfolio mode: include closed vaults in the result.
+     *
+     * By default (`false`) closed vaults are excluded, so marketplace /
+     * discovery callers never receive a `status: 'closed'` vault. When set,
+     * closed vaults are returned regardless of `is_visible` (closed +
+     * invisible vaults bucket as closed), so a consumer joining user
+     * positions can render a position held in a closed vault on the
+     * portfolio page.
+     *
+     * In this mode, loans/allocations enrichment is also skipped for closed
+     * vaults: they have none, and the per-vault enrichment
+     * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+     * vault has no live strategy/debank data or no subaccounts, which would
+     * land the vault in the `failed` bucket and silently drop it before it
+     * reaches the filter. Skipping enrichment lets the vault survive on its
+     * backend metadata + base on-chain read.
+     *
+     * @default false
+     */
+    includeClosed?: boolean;
+    /**
+     * Maximum primary-fetch attempts per vault before the fallback
+     * strategies (fallback RPCs, minimal fetch, extended retry) run.
+     * Attempt `n` waits `baseDelay * 2^(n-1)` ms before retrying, so the
+     * default (5 attempts, 2000 ms base) can spend up to 30s of backoff on
+     * a single persistently-failing vault. Callers racing this method
+     * against their own timeout should lower it (e.g. `2`) so one flaky
+     * vault cannot exhaust the whole budget.
+     *
+     * @default 5
+     */
+    maxRetries?: number;
+    /**
+     * Base backoff delay in **milliseconds** for the per-vault retry
+     * schedule (see `maxRetries`).
+     *
+     * @default 2000
+     */
+    baseDelay?: number;
+}

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

@@ -1,4 +1,4 @@
-import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness } from '../../types';
+import type { IAddress, IContractRunner, INormalizedNumber, IPoolFunctions, ITokenizedVault, IVault, IVaultFreshness, IVaultVersion } from '../../types';
 import { ethers } from 'ethers';
 import type { WalletClient } from 'viem';
 /**
@@ -50,9 +50,14 @@ export declare function getVaultRewards(tokenizedVault: ITokenizedVault): {
  * @param provider - The provider
  * @param vaultAddress - The vault address
  * @param totalAssets - The total assets of the vault
+ * @param knownVersion - Optional pre-resolved vault version. Callers that
+ *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+ *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+ *   API's default load flags at that, a heavier payload on a different cache
+ *   key than the caller's own fetch — just to dispatch on the version.
  * @returns The idle assets
  */
-export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber): Promise<bigint>;
+export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber, knownVersion?: IVaultVersion): Promise<bigint>;
 export declare function getYieldLastRealizedOn(provider: IContractRunner, vaultAddress: IAddress): Promise<number>;
 /**
  * Format APY data from backend tokenized vault into the unified IVaultApy shape.

package/lib/modules/vaults/utils.js

@@ -133,11 +133,16 @@ function getVaultRewards(tokenizedVault) {
  * @param provider - The provider
  * @param vaultAddress - The vault address
  * @param totalAssets - The total assets of the vault
+ * @param knownVersion - Optional pre-resolved vault version. Callers that
+ *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+ *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+ *   API's default load flags at that, a heavier payload on a different cache
+ *   key than the caller's own fetch — just to dispatch on the version.
  * @returns The idle assets
  */
-async function getIdleAssets(provider, vaultAddress, underlying, totalAssets) {
-    const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vaultAddress))?.[0];
-    const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);
+async function getIdleAssets(provider, vaultAddress, underlying, totalAssets, knownVersion) {
+    const version = knownVersion ??
+        (0, vaults_1.getVaultVersionV2)((await (0, core_1.fetchTokenizedVault)(vaultAddress))?.[0]);
     let idleAssets;
     switch (version) {
         case 'evm-0': {
@@ -522,7 +527,10 @@ async function buildFormattedVault(provider, tokenizedVault, contractCalls) {
         isDepositPaused: (0, vaults_1.isBadVault)(tokenizedVault.address),
         decimals: contractCalls.decimals,
         isWithdrawalPaused: contractCalls.withdrawalsPaused,
-        idleAssets: (0, core_1.toNormalizedBn)(await getIdleAssets(provider, tokenizedVault.address, contractCalls.asset, contractCalls.totalAssets), Number(contractCalls.decimals)),
+        idleAssets: (0, core_1.toNormalizedBn)(await getIdleAssets(provider, tokenizedVault.address, contractCalls.asset, contractCalls.totalAssets, 
+        // The row is already in hand — don't let getIdleAssets re-fetch it
+        // just to resolve the version.
+        (0, vaults_1.getVaultVersionV2)(tokenizedVault)), Number(contractCalls.decimals)),
     };
     // Version specific logic
     const version = (0, vaults_1.getVaultVersionV2)(tokenizedVault);

package/lib/sdk.d.ts

@@ -15822,8 +15822,8 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                    * Initialize base SDK with provider configuration and API keys.
                    * Sets up the first provider as the active network by default.
                    *
-                   * @throws If `appName` is missing, malformed, or out of the allowed
-                   *   length range — see {@link IAugustBase.appName}.
+                   * @throws AugustValidationError if `appName` is missing, malformed, or
+                   *   out of the allowed length range — see {@link IAugustBase.appName}.
                    */
                   constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
                   /**
@@ -15998,15 +15998,12 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                   /**
                    * Fetch all available vaults across configured networks.
                    * Optionally filter by chain IDs and include loan/allocation data.
-                   * @param options - Configuration for filtering and enriching vault data
+                   * @param options - Configuration for filtering and enriching vault data —
+                   * see {@link IGetVaultsOptions} for the full surface (`includeClosed`
+                   * portfolio mode, `maxRetries`/`baseDelay` retry tuning)
                    * @returns Array of vault objects with metadata and optional position data
                    */
-                  getVaults(options?: {
-                      chainIds?: number[];
-                      headers?: IWSMonitorHeaders;
-                      loadSubaccounts?: boolean;
-                      loadSnapshots?: boolean;
-                  } & IVaultCustomOptions): Promise<IVault[]>;
+                  getVaults(options?: IGetVaultsOptions): Promise<IVault[]>;
                   getTotalDeposited(options?: {
                       loadSubaccounts?: boolean;
                       loadSnapshots?: boolean;
@@ -16793,32 +16790,7 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                    * @param options Filtering and enrichment configuration
                    * @returns Array of vault objects with optional loans/allocations/positions
                    */
-                  getVaults(options?: {
-                      chainIds?: number[];
-                      loadSubaccounts?: boolean;
-                      loadSnapshots?: boolean;
-                      /**
-                       * Portfolio mode: include closed vaults in the result.
-                       *
-                       * By default (`false`) closed vaults are excluded, so marketplace /
-                       * discovery callers never receive a `status: 'closed'` vault. When set,
-                       * closed vaults are returned regardless of `is_visible` (closed +
-                       * invisible vaults bucket as closed), so a consumer joining user
-                       * positions can render a position held in a closed vault on the
-                       * portfolio page.
-                       *
-                       * In this mode, loans/allocations enrichment is also skipped for closed
-                       * vaults: they have none, and the per-vault enrichment
-                       * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
-                       * vault has no live strategy/debank data or no subaccounts, which would
-                       * land the vault in the `failed` bucket and silently drop it before it
-                       * reaches the filter. Skipping enrichment lets the vault survive on its
-                       * backend metadata + base on-chain read.
-                       *
-                       * @default false
-                       */
-                      includeClosed?: boolean;
-                  } & IVaultCustomOptions): Promise<IVault[]>;
+                  getVaults(options?: IGetVaultsOptions): Promise<IVault[]>;
                   /**
                    * Calculate total deposited across all tokenized vaults by summing latest_reported_tvl.
                    * Uses the /tokenized_vault endpoint which returns latest_reported_tvl in USD.
@@ -18830,9 +18802,14 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                  * @param provider - The provider
                                  * @param vaultAddress - The vault address
                                  * @param totalAssets - The total assets of the vault
+                                 * @param knownVersion - Optional pre-resolved vault version. Callers that
+                                 *   already hold the backend row (e.g. `buildFormattedVault`) pass it so this
+                                 *   function doesn't re-fetch `GET /tokenized_vault/{address}` — and with the
+                                 *   API's default load flags at that, a heavier payload on a different cache
+                                 *   key than the caller's own fetch — just to dispatch on the version.
                                  * @returns The idle assets
                                  */
-                                export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber): Promise<bigint>;
+                                export declare function getIdleAssets(provider: IContractRunner, vaultAddress: IAddress, underlying: IAddress, totalAssets: INormalizedNumber, knownVersion?: IVaultVersion): Promise<bigint>;
 
                                 /**
                                  * Create or reuse a cached Infura provider for the specified chain.
@@ -19348,15 +19325,22 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * @param loans - Include active loan data
                                   * @param allocations - Include DeFi/CeFi allocation breakdowns
                                   * @param options - RPC and service configuration
+                                  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
+                                  *   caller already holds the row (e.g. `getVaults` fetched the whole list one
+                                  *   call earlier), passing it skips this function's own
+                                  *   `GET /tokenized_vault/{address}` — a pure de-duplication of backend
+                                  *   traffic. The row must have been fetched with the same
+                                  *   `loadSubaccounts`/`loadSnapshots` flags the caller passes here.
                                   * @returns Complete vault object with optional enrichments
                                   */
-                                 export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, }: {
+                                 export declare function getVault({ vault, loans, allocations, options, loadSubaccounts, loadSnapshots, tokenizedVault: prefetchedRow, }: {
                                      vault: IAddress;
                                      loans?: boolean;
                                      allocations?: boolean;
                                      options: IVaultBaseOptions;
                                      loadSubaccounts?: boolean;
                                      loadSnapshots?: boolean;
+                                     tokenizedVault?: ITokenizedVault;
                                  }): Promise<IVault>;
 
                                  /**
@@ -19976,7 +19960,8 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                       * 3–64 characters, `[a-zA-Z0-9._-]` only. Use a slug ("acme-trader"),
                                       * not a display name ("Acme Trader").
                                       *
-                                      * @throws Throws synchronously from the constructor if missing or empty.
+                                      * @throws AugustValidationError synchronously from the constructor if
+                                      *   missing, empty, or malformed.
                                       *
                                       * @example
                                       * ```typescript
@@ -20756,6 +20741,59 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                      status?: string;
                                  }
 
+                                 /**
+                                  * Options accepted by `getVaults` — on both the `AugustSDK` facade and the
+                                  * underlying `AugustVaults` module. Defined once so the two signatures cannot
+                                  * drift (the facade previously declared a narrower inline type that rejected
+                                  * documented options like `includeClosed` at compile time).
+                                  */
+                                 export declare interface IGetVaultsOptions extends IVaultCustomOptions {
+                                     chainIds?: number[];
+                                     headers?: IWSMonitorHeaders;
+                                     loadSubaccounts?: boolean;
+                                     loadSnapshots?: boolean;
+                                     /**
+                                      * Portfolio mode: include closed vaults in the result.
+                                      *
+                                      * By default (`false`) closed vaults are excluded, so marketplace /
+                                      * discovery callers never receive a `status: 'closed'` vault. When set,
+                                      * closed vaults are returned regardless of `is_visible` (closed +
+                                      * invisible vaults bucket as closed), so a consumer joining user
+                                      * positions can render a position held in a closed vault on the
+                                      * portfolio page.
+                                      *
+                                      * In this mode, loans/allocations enrichment is also skipped for closed
+                                      * vaults: they have none, and the per-vault enrichment
+                                      * (`getVault` → `getVaultAllocations`) otherwise re-throws when a closed
+                                      * vault has no live strategy/debank data or no subaccounts, which would
+                                      * land the vault in the `failed` bucket and silently drop it before it
+                                      * reaches the filter. Skipping enrichment lets the vault survive on its
+                                      * backend metadata + base on-chain read.
+                                      *
+                                      * @default false
+                                      */
+                                     includeClosed?: boolean;
+                                     /**
+                                      * Maximum primary-fetch attempts per vault before the fallback
+                                      * strategies (fallback RPCs, minimal fetch, extended retry) run.
+                                      * Attempt `n` waits `baseDelay * 2^(n-1)` ms before retrying, so the
+                                      * default (5 attempts, 2000 ms base) can spend up to 30s of backoff on
+                                      * a single persistently-failing vault. Callers racing this method
+                                      * against their own timeout should lower it (e.g. `2`) so one flaky
+                                      * vault cannot exhaust the whole budget.
+                                      *
+                                      * @default 5
+                                      */
+                                     maxRetries?: number;
+                                     /**
+                                      * Base backoff delay in **milliseconds** for the per-vault retry
+                                      * schedule (see `maxRetries`).
+                                      *
+                                      * @default 2000
+                                      */
+                                     baseDelay?: number;
+                                 }
+
                                  /**
                                   * Table of Contents
                                   * 1) Subaccounts
@@ -20946,16 +20984,28 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
                                   * only refresh user identity and the cached API-key hash.
                                   *
+                                  * Breaking change in v9: `appName` moved from the optional fifth parameter
+                                  * to the required third parameter, so every telemetry stream carries an
+                                  * application identity (the `AugustSDK` constructor has required it since
+                                  * v5). Callers on the old positional order get a synchronous validation
+                                  * error rather than silently anonymous events.
+                                  *
                                   * @param config - Analytics configuration. Pass `tracesSampleRate` to
                                   *   override the default of `0.1`.
                                   * @param environment - Current environment (DEV or PROD).
+                                  * @param appName - App-name slug, required. Set as the global `app.name`
+                                  *   tag on every event and used to derive `partner.id`. Identifier-shaped:
+                                  *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+                                  *   rules the `AugustSDK` constructor enforces.
                                   * @param walletAddress - Optional wallet address for user identification.
                                   * @param apiKey - Optional API key (hashed for identification).
-                                  * @param appName - Optional app-name slug. Set as the global `app.name`
-                                  *   tag on every event; falls back to `'unverified:anonymous'` when
-                                  *   omitted.
+                                  * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+                                  *   missing, empty, mis-typed, out of the allowed length range, contains
+                                  *   disallowed characters, or is shaped like an EVM address. Thrown before
+                                  *   any analytics state mutates, even when analytics would be disabled by
+                                  *   config or environment gates.
                                   */
-                                 export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
+                                 export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, appName: string, walletAddress?: string, apiKey?: string): void;
 
                                  export declare type INormalizedNumber = {
                                      normalized: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.25.0",
+  "version": "9.0.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [