@augustdigital/sdk 8.6.1 → 8.7.1

package/lib/services/subgraph/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which field-naming schema a deployed August vault subgraph uses:
+ * - `'old'` — snake_case fields (`block_number`, `timestamp_`, `transactionHash_`).
+ * - `'new'` — camelCase fields (`blockNumber`, `blockTimestamp`, `transactionHash`).
+ *
+ * The two templates are otherwise equivalent; the SDK aliases new-schema fields
+ * back to the old internal names when querying, so the rest of the code only ever
+ * sees the old (snake_case) shape.
+ */
+export type SubgraphSchema = 'old' | 'new';
+/**
+ * True when a GraphQL error array reports an unknown field on the queried type
+ * (message contains "has no field") — the signature of a schema mismatch.
+ *
+ * @param errors - GraphQL `errors` array from a subgraph response (may be undefined).
+ * @returns `true` if any error message indicates an unknown field, else `false`.
+ */
+export declare function isSubgraphSchemaFieldError(errors: {
+    message?: string;
+}[] | undefined): boolean;
+/**
+ * Detects whether a deployed subgraph uses the old or new field schema by probing
+ * a single field (`blockTimestamp`) that exists only on the new template.
+ *
+ * This replaces the previous heuristic — "vault symbol present in the deprecated
+ * `SUBGRAPH_VAULT_URLS` map ⇒ old schema, else new" — which mis-guessed any
+ * newly-added vault whose subgraph shipped on the old template (e.g.
+ * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
+ * non-existent field names, so the subgraph returned GraphQL errors with no
+ * `data` and the SDK silently returned empty sets — emptying the Pending
+ * Withdrawals and History tabs for that vault (AUGUST-6568).
+ *
+ * Because the schema is immutable for a fixed subgraph deployment, the result is
+ * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/
+ * withdrawals reads this amounts to a single extra lightweight query per subgraph.
+ *
+ * Side effects: at most one HTTP POST to the subgraph per URL per TTL window.
+ *
+ * @param goldskyUrl - Fully-qualified subgraph GraphQL endpoint.
+ * @param apiKey - Optional Goldsky API key sent as a Bearer token.
+ * @returns `'old'` or `'new'`. Defaults to `'new'` when the URL is empty or the
+ *   probe is inconclusive (network error / unexpected response) — the schema the
+ *   majority of current vaults use.
+ */
+export declare function resolveSubgraphSchema(goldskyUrl: string, apiKey?: string): Promise<SubgraphSchema>;

package/lib/services/subgraph/schema.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSubgraphSchemaFieldError = isSubgraphSchemaFieldError;
+exports.resolveSubgraphSchema = resolveSubgraphSchema;
+const core_1 = require("../../core");
+const fetcher_1 = require("./fetcher");
+const SCHEMA_CACHE_PREFIX = 'subgraph-schema-';
+// A subgraph's schema is fixed for a given deployment/version, so one probe can
+// serve every subsequent read for a long time. Cache generously.
+const SCHEMA_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * True when a GraphQL error array reports an unknown field on the queried type
+ * (message contains "has no field") — the signature of a schema mismatch.
+ *
+ * @param errors - GraphQL `errors` array from a subgraph response (may be undefined).
+ * @returns `true` if any error message indicates an unknown field, else `false`.
+ */
+function isSubgraphSchemaFieldError(errors) {
+    return Boolean(errors?.some((e) => e?.message?.includes('has no field')));
+}
+/**
+ * Detects whether a deployed subgraph uses the old or new field schema by probing
+ * a single field (`blockTimestamp`) that exists only on the new template.
+ *
+ * This replaces the previous heuristic — "vault symbol present in the deprecated
+ * `SUBGRAPH_VAULT_URLS` map ⇒ old schema, else new" — which mis-guessed any
+ * newly-added vault whose subgraph shipped on the old template (e.g.
+ * `august-citrea-earn-ctusd`). A wrong guess made every subgraph read query
+ * non-existent field names, so the subgraph returned GraphQL errors with no
+ * `data` and the SDK silently returned empty sets — emptying the Pending
+ * Withdrawals and History tabs for that vault (AUGUST-6568).
+ *
+ * Because the schema is immutable for a fixed subgraph deployment, the result is
+ * cached per URL ({@link SCHEMA_TTL_MS}); across a page's positions/history/
+ * withdrawals reads this amounts to a single extra lightweight query per subgraph.
+ *
+ * Side effects: at most one HTTP POST to the subgraph per URL per TTL window.
+ *
+ * @param goldskyUrl - Fully-qualified subgraph GraphQL endpoint.
+ * @param apiKey - Optional Goldsky API key sent as a Bearer token.
+ * @returns `'old'` or `'new'`. Defaults to `'new'` when the URL is empty or the
+ *   probe is inconclusive (network error / unexpected response) — the schema the
+ *   majority of current vaults use.
+ */
+async function resolveSubgraphSchema(goldskyUrl, apiKey) {
+    if (!goldskyUrl)
+        return 'new';
+    const key = `${SCHEMA_CACHE_PREFIX}${goldskyUrl}`;
+    const cached = core_1.CACHE.get(key);
+    if (cached)
+        return cached;
+    try {
+        // `blockTimestamp` is a new-schema-only field. If the subgraph rejects it
+        // with an unknown-field error, the deployment is old-schema. Schema
+        // validation is static, so this is authoritative even when the entity has
+        // zero rows.
+        const result = await (0, fetcher_1.fetchSubgraph)(goldskyUrl, `{ withdrawalRequesteds(first: 1) { blockTimestamp } }`, apiKey);
+        let schema = 'new';
+        if (result.status === 200) {
+            const json = (await result.json());
+            if (isSubgraphSchemaFieldError(json?.errors)) {
+                schema = 'old';
+            }
+        }
+        core_1.CACHE.set(key, schema, { ttl: SCHEMA_TTL_MS });
+        return schema;
+    }
+    catch (e) {
+        // Don't cache an inconclusive probe — let the next call retry. Default to
+        // 'new' so freshly-deployed vaults keep working when the probe is flaky.
+        core_1.Logger.log.warn('resolveSubgraphSchema', `probe failed for ${goldskyUrl}, defaulting to new schema: ${e instanceof Error ? e.message : 'unknown error'}`);
+        return 'new';
+    }
+}
+//# sourceMappingURL=schema.js.map

package/lib/services/subgraph/vaults.d.ts

@@ -19,5 +19,7 @@ export declare function getSubgraphAllWithdrawals(pool: IAddress, provider: ICon
     withdrawalProcesseds: ISubgraphWithdrawProccessed[];
 }>;
 export declare function getSubgraphUserHistory(user: IAddress, provider: IContractRunner, pool: IAddress, slackWebookUrl?: string): Promise<ISubgraphUserHistoryItem[]>;
-export declare function getSubgraphVaultHistory(provider: IContractRunner, pool: IAddress, slackWebookUrl?: string): Promise<ISubgraphUserHistoryItem[]>;
+export declare function getSubgraphVaultHistory(provider: IContractRunner, pool: IAddress, slackWebookUrl?: string, opts?: {
+    sinceTs?: number;
+}): Promise<ISubgraphUserHistoryItem[]>;
 export declare function getSubgraphUserTransfers(user: IAddress, provider: IContractRunner, pool: IAddress, slackWebookUrl?: string): Promise<ISubgraphTransfer[]>;

package/lib/services/subgraph/vaults.js

@@ -7,14 +7,46 @@ exports.getSubgraphAllWithdrawals = getSubgraphAllWithdrawals;
 exports.getSubgraphUserHistory = getSubgraphUserHistory;
 exports.getSubgraphVaultHistory = getSubgraphVaultHistory;
 exports.getSubgraphUserTransfers = getSubgraphUserTransfers;
+const ethers_1 = require("ethers");
 const slack_1 = require("../../core/logger/slack");
 const fetcher_1 = require("./fetcher");
+const schema_1 = require("./schema");
 const core_1 = require("../../core");
 const fetcher_2 = require("../../modules/vaults/fetcher");
 /**
  * Utils
  */
 const GOLDSKY_API_KEY = 'cmd0lz6qf35lg01ty7u20aijy';
+// Dedupe window for "Missing Subgraph" alerts (per pool).
+const MISSING_SUBGRAPH_ALERT_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Emit a "Missing Subgraph" Slack alert at most once per pool per TTL.
+ *
+ * `getDefaultSubgraphUrl` now returns `undefined` for vaults with no metadata or
+ * hardcoded subgraph URL, which makes the readers' `if (!goldskyUrl)` branches
+ * reachable (previously the fabricated URL was always truthy, so they were dead
+ * code). Portfolio/history flows loop over every vault, so alerting on each read
+ * would flood the webhook for every metadata-less vault. Deduping per pool
+ * surfaces a genuinely-missing subgraph without the flood.
+ *
+ * @param args.source - Reader function name, for the alert body.
+ * @param args.pool - Vault address (used as the dedupe key, lowercased).
+ * @param args.chainId - Chain id for the alert context.
+ * @param args.slackWebookUrl - Optional override webhook URL.
+ */
+function alertMissingSubgraphOnce(args) {
+    const key = `missing-subgraph-alert-${args.pool.toLowerCase()}`;
+    if (core_1.CACHE.has(key))
+        return;
+    core_1.CACHE.set(key, true, { ttl: MISSING_SUBGRAPH_ALERT_TTL_MS });
+    slack_1.SLACK.error({
+        title: 'Missing Subgraph',
+        error: `#${args.source}: goldsky url is undefined`,
+        poolAddress: args.pool,
+        chainId: args.chainId,
+        slackWebookUrl: args.slackWebookUrl || '',
+    });
+}
 /**
  * earnAUSD exists on both Ethereum and Monad, so it needs a _monad suffix
  * to distinguish its Monad subgraph from the Ethereum one.
@@ -269,18 +301,21 @@ async function getSubgraphWithdrawRequests(pool, provider, slackWebookUrl = slac
     if (!goldskyUrl) {
         const chainId = await (0, core_1.getChainId)(provider);
         core_1.Logger.log.warn('getSubgraphWithdrawRequests', `goldsky url is undefined: ${vaultSymbol}::${pool}`);
-        slack_1.SLACK.error({
-            title: 'Missing Subgraph',
-            error: '#getSubgraphWithdrawRequests: goldsky url is undefined',
-            poolAddress: pool,
-            chainId: chainId,
-            slackWebookUrl: slackWebookUrl || '',
+        alertMissingSubgraphOnce({
+            source: 'getSubgraphWithdrawRequests',
+            pool,
+            chainId,
+            slackWebookUrl,
         });
         return [];
     }
     const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(pool))?.[0];
     const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
-    const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+    // Probe the deployed subgraph to learn its actual field schema (cached per
+    // URL) instead of guessing from the vault symbol. See resolveSubgraphSchema —
+    // the old symbol-map heuristic silently emptied this set for vaults deployed
+    // on the old template but absent from SUBGRAPH_VAULT_URLS (AUGUST-6568).
+    const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
     const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
     const withdrawalRequestedProps = useOldSchema
         ? version === 'evm-2'
@@ -331,18 +366,19 @@ async function getSubgraphWithdrawProccessed(pool, provider, slackWebookUrl = sl
         if (!goldskyUrl) {
             const chainId = await (0, core_1.getChainId)(provider);
             core_1.Logger.log.error('getSubgraphWithdrawProccessed.missing-subgraph-url', new Error('goldsky url is undefined'), { chainId, vaultSymbol, pool });
-            slack_1.SLACK.error({
-                title: 'Missing Subgraph',
-                error: '#getSubgraphWithdrawProccessed: goldsky url is undefined',
-                poolAddress: pool,
-                chainId: chainId,
-                slackWebookUrl: slackWebookUrl || '',
+            alertMissingSubgraphOnce({
+                source: 'getSubgraphWithdrawProccessed',
+                pool,
+                chainId,
+                slackWebookUrl,
             });
             return [];
         }
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(pool))?.[0];
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
-        const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+        // Probe the deployed subgraph's actual field schema (cached per URL) rather
+        // than guessing from the vault symbol — see resolveSubgraphSchema (AUGUST-6568).
+        const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
         const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
         const withdrawalProcessedProps = useOldSchema
             ? version === 'evm-2'
@@ -408,18 +444,19 @@ async function getSubgraphAllWithdrawals(pool, provider, slackWebookUrl = slack_
         if (!goldskyUrl) {
             const chainId = await (0, core_1.getChainId)(provider);
             core_1.Logger.log.error('getSubgraphAllWithdrawals', `goldsky url is undefined: ${vaultSymbol}::${pool}`);
-            slack_1.SLACK.error({
-                title: 'Missing Subgraph',
-                error: '#getSubgraphAllWithdrawals: goldsky url is undefined',
-                poolAddress: pool,
-                chainId: chainId,
-                slackWebookUrl: slackWebookUrl || '',
+            alertMissingSubgraphOnce({
+                source: 'getSubgraphAllWithdrawals',
+                pool,
+                chainId,
+                slackWebookUrl,
             });
             return errorReturnObj;
         }
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(pool))?.[0];
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
-        const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+        // Probe the deployed subgraph's actual field schema (cached per URL) rather
+        // than guessing from the vault symbol — see resolveSubgraphSchema (AUGUST-6568).
+        const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
         const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
         const withdrawalRequestedProps = useOldSchema
             ? version === 'evm-2'
@@ -540,6 +577,15 @@ async function getArchivedVaultUserHistory(user, provider, pool) {
 }
 async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
     try {
+        // This path is EVM-only: it reads chain id and network from an EVM
+        // JsonRpcProvider (eth_chainId / getNetwork) and queries an EVM subgraph.
+        // A non-EVM (Solana / Stellar) vault address routed here would call
+        // eth_chainId against a Solana/Stellar RPC and fail with a 400
+        // ("eth_chainId is not available on SOLANA_MAINNET"). Bail early so non-EVM
+        // vaults are simply skipped rather than throwing on every history fetch.
+        if (!(0, ethers_1.isAddress)(pool)) {
+            return [];
+        }
         // Archived vaults: serve history from the backend Mongo snapshot instead of
         // the (retired) subgraph. The archived set is fetched from the backend (the
         // routing source of truth) so a vault is only rerouted once its history is
@@ -573,18 +619,19 @@ async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = sla
             (0, core_1.getDefaultSubgraphUrl)(networkValue.name, vaultSymbol);
         if (!goldskyUrl) {
             core_1.Logger.log.error('getSubgraphUserHistory', `goldsky url is undefined: ${vaultSymbol}::${pool}`);
-            slack_1.SLACK.error({
-                title: 'Missing Subgraph',
-                error: '#getSubgraphUserHistory: goldsky url is undefined',
-                poolAddress: pool,
-                chainId: chainId,
-                slackWebookUrl: slackWebookUrl || '',
+            alertMissingSubgraphOnce({
+                source: 'getSubgraphUserHistory',
+                pool,
+                chainId,
+                slackWebookUrl,
             });
             return requests;
         }
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(pool))?.[0];
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
-        const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+        // Probe the deployed subgraph's actual field schema (cached per URL) rather
+        // than guessing from the vault symbol — see resolveSubgraphSchema (AUGUST-6568).
+        const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
         const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
         const depositProps = useOldSchema
             ? version === 'evm-2'
@@ -670,7 +717,7 @@ async function getSubgraphUserHistory(user, provider, pool, slackWebookUrl = sla
         return [];
     }
 }
-async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL) {
+async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.DEFAULT_SLACK_WEBHOOK_URL, opts = {}) {
     try {
         // setup
         const requests = [];
@@ -695,18 +742,19 @@ async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.
         if (!goldskyUrl) {
             const chainId = await (0, core_1.getChainId)(provider);
             core_1.Logger.log.error('getSubgraphVaultHistory', `goldsky url is undefined: ${vaultSymbol}::${pool}`);
-            slack_1.SLACK.error({
-                title: 'Missing Subgraph',
-                error: '#getSubgraphVaultHistory: goldsky url is undefined',
-                poolAddress: pool,
-                chainId: chainId,
-                slackWebookUrl: slackWebookUrl || '',
+            alertMissingSubgraphOnce({
+                source: 'getSubgraphVaultHistory',
+                pool,
+                chainId,
+                slackWebookUrl,
             });
             return requests;
         }
         const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(pool))?.[0];
         const version = (0, core_1.getVaultVersionV2)(tokenizedVault);
-        const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+        // Probe the deployed subgraph's actual field schema (cached per URL) rather
+        // than guessing from the vault symbol — see resolveSubgraphSchema (AUGUST-6568).
+        const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
         const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
         const withdrawProps = useOldSchema
             ? version === 'evm-2'
@@ -728,45 +776,91 @@ async function getSubgraphVaultHistory(provider, pool, slackWebookUrl = slack_1.
                 ? EVM_V2_DEPOSIT_QUERY_PROPS
                 : DEPOSIT_QUERY_PROPS
             : NEW_DEPOSIT_QUERY_PROPS;
-        const result = await (0, fetcher_1.fetchSubgraph)(goldskyUrl, `{
+        // Each of the four event entities is capped at 1000 rows per request, so
+        // a busy vault would silently truncate. Page all four in lockstep on a
+        // shared `skip` cursor (rows are ordered newest-first) and keep going while
+        // any entity returned a full page. When `sinceTs` is set we can stop early:
+        // once an entity's oldest row in the page predates the window, no later
+        // page can contain in-window rows for it.
+        const PAGE_SIZE = 1000;
+        const accumulated = {
+            withdraws: [],
+            withdrawalRequesteds: [],
+            withdrawalProcesseds: [],
+            deposits: [],
+        };
+        let skip = 0;
+        for (;;) {
+            const result = await (0, fetcher_1.fetchSubgraph)(goldskyUrl, `{
       withdraws (
-        first: 1000,
+        first: ${PAGE_SIZE},
+        skip: ${skip},
         orderBy: ${orderByTimestamp},
         orderDirection: desc,
     ) {
          ${withdrawProps}
         }
       withdrawalRequesteds (
-        first: 1000,
+        first: ${PAGE_SIZE},
+        skip: ${skip},
         orderBy: ${orderByTimestamp},
         orderDirection: desc,
       ) {
         ${withdrawalRequestedProps}
       }
       withdrawalProcesseds (
-        first: 1000,
+        first: ${PAGE_SIZE},
+        skip: ${skip},
         orderBy: ${orderByTimestamp},
         orderDirection: desc,
       ) {
         ${withdrawalProcessedProps}
       }
       deposits (
-        first: 1000,
+        first: ${PAGE_SIZE},
+        skip: ${skip},
         orderBy: ${orderByTimestamp},
         orderDirection: desc,
       ) {
         ${depositProps}
       }
     }`, GOLDSKY_API_KEY);
-        if (result.status !== 200) {
-            core_1.Logger.log.error('getSubgraphVaultHistory', new Error(`HTTP ${result.status} ${result.statusText}`), { status: result.status, statusText: result.statusText });
-            return requests;
+            if (result.status !== 200) {
+                core_1.Logger.log.error('getSubgraphVaultHistory', new Error(`HTTP ${result.status} ${result.statusText}`), { status: result.status, statusText: result.statusText, skip });
+                // First page failed → nothing to return. A later page failing still
+                // yields whatever earlier pages accumulated.
+                if (skip === 0)
+                    return requests;
+                break;
+            }
+            const json = (await result.json());
+            const page = json.data;
+            accumulated.withdraws.push(...(page?.withdraws ?? []));
+            accumulated.withdrawalRequesteds.push(...(page?.withdrawalRequesteds ?? []));
+            accumulated.withdrawalProcesseds.push(...(page?.withdrawalProcesseds ?? []));
+            accumulated.deposits.push(...(page?.deposits ?? []));
+            const entities = [
+                page?.withdraws,
+                page?.withdrawalRequesteds,
+                page?.withdrawalProcesseds,
+                page?.deposits,
+            ];
+            const needMore = entities.some((rows) => {
+                if ((rows?.length ?? 0) < PAGE_SIZE)
+                    return false;
+                if (opts.sinceTs === undefined)
+                    return true;
+                const oldest = Number(rows?.[rows.length - 1]?.timestamp_);
+                return !Number.isFinite(oldest) || oldest >= opts.sinceTs;
+            });
+            if (!needMore)
+                break;
+            skip += PAGE_SIZE;
         }
-        const json = (await result.json());
         // Format data
         const chainId = await (0, core_1.getChainId)(provider);
         const decimals = await (0, core_1.getDecimals)(provider, pool);
-        const formattedRequests = sortUserHistory(json.data, chainId, decimals, pool);
+        const formattedRequests = sortUserHistory(accumulated, chainId, decimals, pool);
         return formattedRequests;
     }
     catch (e) {
@@ -804,16 +898,17 @@ async function getSubgraphUserTransfers(user, provider, pool, slackWebookUrl = s
         if (!goldskyUrl) {
             const chainId = await (0, core_1.getChainId)(provider);
             core_1.Logger.log.error('getSubgraphUserTransfers', `goldsky url is undefined: ${vaultSymbol}::${pool}`);
-            slack_1.SLACK.error({
-                title: 'Missing Subgraph',
-                error: '#getSubgraphUserTransfers: goldsky url is undefined',
-                poolAddress: pool,
-                chainId: chainId,
-                slackWebookUrl: slackWebookUrl || '',
+            alertMissingSubgraphOnce({
+                source: 'getSubgraphUserTransfers',
+                pool,
+                chainId,
+                slackWebookUrl,
             });
             return userTransfers;
         }
-        const useOldSchema = isOldSubgraphSchema(vaultSymbol);
+        // Probe the deployed subgraph's actual field schema (cached per URL) rather
+        // than guessing from the vault symbol — see resolveSubgraphSchema (AUGUST-6568).
+        const useOldSchema = (await (0, schema_1.resolveSubgraphSchema)(goldskyUrl, GOLDSKY_API_KEY)) === 'old';
         const orderByTimestamp = useOldSchema ? 'timestamp_' : 'blockTimestamp';
         const transferProps = useOldSchema
             ? TRANSFER_QUERY_PROPS

package/lib/types/vaults.d.ts

@@ -524,3 +524,40 @@ export interface ISwapRouterNativeDepositOptions extends ISwapRouterBaseOptions
     /** Native token amount in wei. Sent as `msg.value`. */
     amount: bigint;
 }
+/**
+ * Options for {@link swapRouterDeposit} — the high-level, explicit SwapRouter
+ * deposit entry point. It reads the vault's reference asset and decimals
+ * on-chain, then picks the correct router path from `depositAsset`, so callers
+ * do not hand-build swap legs or pre-resolve decimals themselves.
+ *
+ * Prefer this over relying on the implicit routing inside `vaultDeposit`: here
+ * the caller opts into the SwapRouter deliberately, so a vault is never
+ * silently routed through a swap it does not need — the failure mode that broke
+ * native multi-asset deposits when a multi-asset vault was added to
+ * `VAULTS_USING_SWAP_ROUTER`.
+ *
+ * Unlike {@link ISwapRouterBaseOptions}, `receiver` is optional here and
+ * defaults to the signer's resolved EOA.
+ */
+export interface ISwapRouterDepositOptions extends Omit<ISwapRouterBaseOptions, 'receiver'> {
+    /**
+     * Token being deposited, held by the signer. Its relationship to the vault's
+     * reference asset selects the router path:
+     *  - equals the reference asset → direct router deposit (no swap);
+     *  - the zero address → native-token deposit (only when the reference asset
+     *    is the chain's wrapped-native token);
+     *  - any other ERC-20 → a swap to the reference asset via the chain's
+     *    whitelisted DEX aggregator, bundled into the deposit.
+     */
+    depositAsset: IAddress;
+    /** Amount in `depositAsset`'s smallest unit (decimal string or bigint). */
+    amount: string | bigint;
+    /** Address that receives the minted shares. Defaults to the signer's EOA. */
+    receiver?: IAddress;
+    /**
+     * Max slippage in basis points for the swap leg. Only used when `depositAsset`
+     * differs from the reference asset; passed through to the swap quote, whose
+     * own default applies when omitted.
+     */
+    slippageBps?: number;
+}

package/package.json

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