@augustdigital/sdk 8.19.0 → 8.20.1

package/lib/core/helpers/web3.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getManagementFeePercent = exports.getSymbol = exports.getReceiptTokenAddress = exports.getReceiptTokenAddressOrThrow = exports.getWhitelistedAssets = exports.getDecimalsOrThrow = exports.getDecimals = exports.explorerLink = exports.getInfuraProvider = exports.createProvider = exports.getChainId = exports.determineBlockSkipInternal = exports.determineSecondsPerBlock = exports.determineBlockCutoff = void 0;
+exports.getManagementFeePercent = exports.getSymbol = exports.getReceiptTokenAddress = exports.getReceiptTokenAddressOrThrow = exports.getWhitelistedAssets = exports.getDecimalsOrThrow = exports.getDecimals = exports.explorerLink = exports.getInfuraProvider = exports.createProvider = exports.getChainId = exports.determineRpcBatchMaxCount = exports.determineBlockSkipInternal = exports.determineSecondsPerBlock = exports.determineBlockCutoff = void 0;
 exports.createContract = createContract;
 exports.getTokenMetadata = getTokenMetadata;
 exports.simulateTransaction = simulateTransaction;
@@ -87,10 +87,54 @@ const determineBlockSkipInternal = (chain) => {
         case 999: // HyperEVM — rpc.hypurrscan.io limits eth_getLogs to 1000 blocks
             return 1_000;
         default:
-            return 50_000;
+            // 10k blocks is the eth_getLogs range cap enforced by every mainstream
+            // provider (Alchemy, Infura, dRPC, QuickNode). The previous 50k default
+            // was rejected outright with JSON-RPC -32600 ("You can make eth_getLogs
+            // requests with up to a 10000 block range") on Ethereum mainnet, which
+            // failed `getVaultRedemptionHistory` for every vault on an unlisted
+            // chain. RPC-count impact: a 150k-block cutoff now costs 15 getLogs
+            // calls instead of 3, batched 20-concurrent, so still one round trip.
+            return 10_000;
     }
 };
 exports.determineBlockSkipInternal = determineBlockSkipInternal;
+/**
+ * Default batch cap. Chosen to stay under the smallest limit among the
+ * providers we route to by default (e.g. rpc.hypurrscan.io rejects > 20).
+ */
+const DEFAULT_RPC_BATCH_MAX_COUNT = 10;
+/**
+ * Maximum JSON-RPC calls ethers may coalesce into a single batched HTTP
+ * request for a given endpoint.
+ *
+ * Providers advertise wildly different batch limits and reject the whole batch
+ * — not the excess — when exceeded, so one oversized batch fails every call
+ * inside it. dRPC's free tier caps batches at 3, which made every Mezo read
+ * fail with `server response 500 … "Batch of more than 3 requests are not
+ * allowed"` (the single highest-volume SDK error in production).
+ *
+ * Detection is host-based rather than chain-based because the limit is a
+ * property of the endpoint, not the chain: the same chain served by a
+ * self-hosted node has no such cap.
+ *
+ * @param rpcUrl - The RPC endpoint URL. Unparseable values fall back to the
+ *   conservative default rather than throwing.
+ * @returns Batch size cap to pass to ethers as `batchMaxCount`.
+ */
+const determineRpcBatchMaxCount = (rpcUrl) => {
+    let host = '';
+    try {
+        host = new URL(rpcUrl).hostname.toLowerCase();
+    }
+    catch {
+        return DEFAULT_RPC_BATCH_MAX_COUNT;
+    }
+    // dRPC free tier: "Batch of more than 3 requests are not allowed".
+    if (host === 'drpc.org' || host.endsWith('.drpc.org'))
+        return 3;
+    return DEFAULT_RPC_BATCH_MAX_COUNT;
+};
+exports.determineRpcBatchMaxCount = determineRpcBatchMaxCount;
 /**
  * Retrieve chain ID from web3 provider.
  * Handles both initialized and uninitialized provider states.
@@ -152,14 +196,16 @@ const createProvider = (rpcUrl, chainId) => {
     const cacheKey = chainId ? `${rpcUrl}|${chainId}` : rpcUrl;
     if (cache_1.CACHE.has(cacheKey))
         return cache_1.CACHE.get(cacheKey);
-    // batchMaxCount caps server-side batch limits (e.g. rpc.hypurrscan.io > 20).
+    // batchMaxCount respects server-side batch limits — providers reject the
+    // entire batch when it is exceeded (see determineRpcBatchMaxCount).
+    const batchMaxCount = (0, exports.determineRpcBatchMaxCount)(rpcUrl);
     const provider = chainId
         ? new ethers_1.JsonRpcProvider(rpcUrl, ethers_1.Network.from(chainId), {
             staticNetwork: ethers_1.Network.from(chainId),
-            batchMaxCount: 10,
+            batchMaxCount,
         })
         : new ethers_1.JsonRpcProvider(rpcUrl, undefined, {
-            batchMaxCount: 10,
+            batchMaxCount,
         });
     cache_1.CACHE.set(cacheKey, provider);
     return provider;

package/lib/core/index.d.ts

@@ -15,6 +15,7 @@ export * from './helpers/web3';
 export * from './helpers/multicall';
 export * from './helpers/vaults';
 export * from './helpers/chain-error';
+export * from './helpers/chain-support';
 export * from './helpers/core';
 export * from './helpers/adapters';
 export * from './helpers/signer';

package/lib/core/index.js

@@ -31,6 +31,7 @@ __exportStar(require("./helpers/web3"), exports);
 __exportStar(require("./helpers/multicall"), exports);
 __exportStar(require("./helpers/vaults"), exports);
 __exportStar(require("./helpers/chain-error"), exports);
+__exportStar(require("./helpers/chain-support"), exports);
 __exportStar(require("./helpers/core"), exports);
 __exportStar(require("./helpers/adapters"), exports);
 __exportStar(require("./helpers/signer"), exports);

package/lib/modules/vaults/getters.js

@@ -352,6 +352,51 @@ async function getVaultSubaccountLoans(vault, options) {
         throw new Error(`#getVaultSubaccountLoans::${vault}:${e?.message}`);
     }
 }
+/**
+ * HTTP statuses that mean "no such record for this subaccount", not "something
+ * broke". The backend returns 404 for a subaccount with no CeFi/OTC position,
+ * which is the normal case for most vault borrowers.
+ */
+const EXPECTED_SUBACCOUNT_FETCH_STATUSES = new Set([204, 404]);
+/**
+ * Log a per-subaccount enrichment fetch failure at the right severity.
+ *
+ * Why: `getVaultAllocations` issues one CeFi and one OTC request per borrower
+ * on every call. Logging the "no record" responses at `error` level captured
+ * them as Sentry issues, producing thousands of `AugustServerError: Request
+ * failed: 404` events a day for a condition that is not a fault and that
+ * callers never need to act on. Expected statuses become breadcrumbs; genuine
+ * failures (5xx, auth, transport) stay at `error`.
+ *
+ * @param tag - Call-site tag, e.g. `getVaultAllocations:cefi`. Becomes the
+ *   `sdk.origin` Sentry tag for grouping.
+ * @param status - HTTP status, or `undefined` when the failure was a thrown
+ *   transport/typed error with no status attached.
+ * @param detail - Status text or error to attach as context.
+ * @param context - Identifiers scoping the failure (`vault`, `borrower`).
+ */
+function logSubaccountFetchFailure(tag, status, detail, context) {
+    if (status !== undefined && EXPECTED_SUBACCOUNT_FETCH_STATUSES.has(status)) {
+        core_1.Logger.log.warn(tag, { ...context, status, reason: 'no record' });
+        return;
+    }
+    core_1.Logger.log.error(tag, detail, { ...context, status });
+}
+/**
+ * Extract the HTTP status from a thrown fetch error, when it carries one.
+ *
+ * `fetchAugustWithKey` throws `AugustServerError`/`AugustAuthError` for non-2xx
+ * responses, so the status-code branch in the callers is unreachable for those
+ * — the status has to be recovered from the error to classify it.
+ *
+ * @param error - Any thrown value.
+ * @returns The HTTP status, or `undefined` for errors without one (network
+ *   failures, aborts, programming errors).
+ */
+function httpStatusFromError(error) {
+    const status = error?.status;
+    return typeof status === 'number' ? status : undefined;
+}
 /**
  * Vault Allocations
  */
@@ -485,22 +530,26 @@ async function getVaultAllocations(vault, options) {
                     }
                 }
                 else {
-                    core_1.Logger.log.error(`getVaultAllocations:no_fetcher`, new Error(`No portfolio fetcher for chain type: ${chainType}`), {
+                    // 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}`,
                     });
-                    debankErr = true;
                 }
             }
             // 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) {
-                    core_1.Logger.log.error('getVaultAllocations:cefi', cefiResponse.statusText, {
-                        borrower,
-                        status: cefiResponse.status,
-                    });
+                    // 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 (cefiResponse.status === 200) {
                     const cefiRes = (await cefiResponse.json());
@@ -508,16 +557,15 @@ async function getVaultAllocations(vault, options) {
                 }
             }
             catch (e) {
-                core_1.Logger.log.error('getVaultAllocations:cefi', e, { borrower });
+                logSubaccountFetchFailure('getVaultAllocations:cefi', httpStatusFromError(e), e, { vault, borrower });
             }
             // 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) {
-                    core_1.Logger.log.error('getVaultAllocations:otc', otcResponse.statusText, {
-                        borrower,
-                        status: otcResponse.status,
-                    });
+                    // 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());
@@ -525,7 +573,7 @@ async function getVaultAllocations(vault, options) {
                 }
             }
             catch (e) {
-                core_1.Logger.log.error('getVaultAllocations:otc', e, { borrower });
+                logSubaccountFetchFailure('getVaultAllocations:otc', httpStatusFromError(e), e, { vault, borrower });
             }
         }
     }
@@ -552,6 +600,34 @@ async function getVaultAllocations(vault, options) {
         unfilteredTokens: unfilteredTokens,
     };
 }
+/**
+ * Coerce a subgraph numeric field to `bigint`, treating absent fields as zero.
+ *
+ * Why: the evm-1 and evm-2 subgraphs expose different field names on
+ * `WithdrawalRequested` — evm-1 emits `assets` plus explicit `year`/`month`/
+ * `day`, evm-2 emits `shares` and a raw `timestamp_`. Reading the wrong one
+ * yields `undefined`, and bare `BigInt(undefined)` throws
+ * `TypeError: Cannot convert undefined to a BigInt`, which aborted the whole
+ * redemption scan and returned an empty list to the caller (the second
+ * highest-volume SDK error in production).
+ *
+ * `BigInt(x) || BigInt(0)` does **not** protect against this — the throw
+ * happens before `||` is ever evaluated.
+ *
+ * @param value - Subgraph field: decimal string, number, bigint, `null`, or
+ *   `undefined`.
+ * @returns The value as `bigint`, or `0n` when absent or non-numeric.
+ */
+function subgraphAmountToBigInt(value) {
+    if (value === undefined || value === null || value === '')
+        return BigInt(0);
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return BigInt(0);
+    }
+}
 async function getVaultAvailableRedemptions({ vault, wallet, options, prefetchedReads, }) {
     try {
         // Stellar vaults don't support on-chain redemptions yet
@@ -669,9 +745,12 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                             const redKey = (0, date_utils_1.formatDateKey)(redDate.getUTCFullYear(), redDate.getUTCMonth() + 1, redDate.getUTCDate());
                             return redKey === requestDateKey;
                         })
-                        : availableRedemptions.find((red) => BigInt(red.day.raw) === BigInt(ev.day) &&
-                            BigInt(red.month.raw) === BigInt(ev.month) &&
-                            BigInt(red.year.raw) === BigInt(ev.year));
+                        : availableRedemptions.find((red) => subgraphAmountToBigInt(red.day.raw) ===
+                            subgraphAmountToBigInt(ev.day) &&
+                            subgraphAmountToBigInt(red.month.raw) ===
+                                subgraphAmountToBigInt(ev.month) &&
+                            subgraphAmountToBigInt(red.year.raw) ===
+                                subgraphAmountToBigInt(ev.year));
                     if (!(foundRedemptionAgainstClaim && alreadyRedeemed)) {
                         // double check if user has already claimed
                         try {
@@ -692,7 +771,7 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                                             // Has passed lag duration - check if claim is not settled before adding to pending
                                             try {
                                                 const burnableAmount = (await vaultContract?.getBurnableAmountByReceiver?.(BigInt(year), BigInt(month), BigInt(day), (0, ethers_1.getAddress)(ev.receiverAddr))) || BigInt(0);
-                                                const claimAmount = BigInt(ev.shares) || BigInt(0);
+                                                const claimAmount = subgraphAmountToBigInt(ev.shares);
                                                 // If burnableAmount >= claimAmount, claim hasn't been settled by processAllClaims
                                                 // Only add to pending if it's still unsettled
                                                 if (burnableAmount >= claimAmount) {
@@ -704,7 +783,7 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                                                         day: (0, core_1.toNormalizedBn)(day, 0),
                                                         month: (0, core_1.toNormalizedBn)(month, 0),
                                                         year: (0, core_1.toNormalizedBn)(year, 0),
-                                                        amount: (0, core_1.toNormalizedBn)(BigInt(ev.shares) || BigInt(0), decimals),
+                                                        amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.shares), decimals),
                                                         date: fullDate,
                                                         vault,
                                                         status: types_1.VaultRedemptionStatus.READY_TO_CLAIM,
@@ -726,7 +805,7 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                                                 day: (0, core_1.toNormalizedBn)(day, 0),
                                                 month: (0, core_1.toNormalizedBn)(month, 0),
                                                 year: (0, core_1.toNormalizedBn)(year, 0),
-                                                amount: (0, core_1.toNormalizedBn)(BigInt(ev.shares), decimals),
+                                                amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.shares), decimals),
                                                 date: fullDate,
                                                 vault,
                                                 status: types_1.VaultRedemptionStatus.AWAITING_COOLDOWN,
@@ -736,7 +815,12 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                                     break;
                                 }
                                 default: {
-                                    const trueClaimableAmount = await vaultContract?.getClaimableAmountByReceiver?.(BigInt(ev.year), BigInt(ev.month), BigInt(ev.day), (0, ethers_1.getAddress)(wallet));
+                                    // Safe to read the raw subgraph dates here: the validation
+                                    // block above `continue`s for any non-evm-2 event missing
+                                    // `year`/`month`/`day`, so this path is only reached with all
+                                    // three present. The coercion below therefore never
+                                    // substitutes 0 for a real date.
+                                    const trueClaimableAmount = await vaultContract?.getClaimableAmountByReceiver?.(subgraphAmountToBigInt(ev.year), subgraphAmountToBigInt(ev.month), subgraphAmountToBigInt(ev.day), (0, ethers_1.getAddress)(wallet));
                                     if (trueClaimableAmount > BigInt(0)) {
                                         // Use computeClaimableDate for UTC-correct date with lag
                                         const v1Claimable = (0, date_utils_1.computeClaimableDate)(Number(ev.timestamp_), lagDuration);
@@ -809,7 +893,7 @@ async function getVaultAvailableRedemptions({ vault, wallet, options, prefetched
                         day: (0, core_1.toNormalizedBn)(ev.day, 0),
                         month: (0, core_1.toNormalizedBn)(ev.month, 0),
                         year: (0, core_1.toNormalizedBn)(ev.year, 0),
-                        amount: (0, core_1.toNormalizedBn)(BigInt(ev.assets) || BigInt(0), decimals),
+                        amount: (0, core_1.toNormalizedBn)(subgraphAmountToBigInt(ev.assets), decimals),
                         date: fullDate,
                         vault,
                         status: types_1.VaultRedemptionStatus.AWAITING_COOLDOWN,
@@ -910,7 +994,11 @@ async function getVaultRedemptionHistory({ vault, wallet, lookbackBlocks, option
                 const firstMessage = firstReason instanceof Error
                     ? firstReason.message
                     : String(firstReason);
-                core_1.Logger.log.error('getVaultRedemptionHistory', 'log fetch chunk(s) failed', {
+                // Breadcrumb only — the throw below is caught and logged by this
+                // function's own catch block, so capturing here duplicated every
+                // failure into a second Sentry issue ("log fetch chunk(s) failed").
+                core_1.Logger.log.warn('getVaultRedemptionHistory', {
+                    reason: 'log fetch chunk(s) failed',
                     failedChunks: failed.length,
                     totalChunks: batch.length,
                     firstReason: firstMessage,

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

@@ -107,6 +107,9 @@ export declare class AugustVaults extends AugustBase {
      * @param chainId Optional chain ID (uses active network if not provided)
      * @param options Enrichment and wallet options
      * @returns Single vault object with optional position data
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }: {
         vault: IAddress;
@@ -116,21 +119,39 @@ export declare class AugustVaults extends AugustBase {
         loadSnapshots?: boolean;
     }): Promise<import("../../types").IVault>;
     /**
-     *
+     * Fetch the active loans issued by a vault.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     getVaultLoans({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultLoan[]>;
     /**
-     *
+     * Fetch a vault's loans broken down by sub-account.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Sub-account loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     getVaultSubaccountLoans({ vault, chainId, }: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("../../types").IVaultLoan[]>;
     /**
-     *
+     * Fetch a vault's DeFi / CeFi / OTC allocation breakdown.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Allocation data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     getVaultAllocations({ vault, chainId, }: {
         vault: IAddress;

package/lib/modules/vaults/main.js

@@ -326,6 +326,9 @@ class AugustVaults extends core_1.AugustBase {
      * @param chainId Optional chain ID (uses active network if not provided)
      * @param options Enrichment and wallet options
      * @returns Single vault object with optional position data
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     async getVault({ vault, chainId, options, loadSubaccounts, loadSnapshots, }) {
         if (!vault)
@@ -334,12 +337,8 @@ class AugustVaults extends core_1.AugustBase {
         //   throw new Error(
         //     `Vault input parameter is not an address: ${String(vault)}`,
         //   );
-        if (typeof chainId !== 'undefined') {
-            if (!this.providers?.[chainId]) {
-                const error = new Error(`Missing RPC URL for chainId ${chainId}`);
-                core_1.Logger.log.error('getVault:missing_provider', error, { chainId });
-            }
-        }
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVault');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVault');
         // get vault data
         const vaultResponse = await (0, getters_1.getVault)({
             vault: vault,
@@ -398,7 +397,13 @@ class AugustVaults extends core_1.AugustBase {
         return vaultResponse;
     }
     /**
-     *
+     * Fetch the active loans issued by a vault.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     async getVaultLoans({ vault, chainId, }) {
         // Sanitize
@@ -407,12 +412,8 @@ class AugustVaults extends core_1.AugustBase {
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault))
             throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
-        if (typeof chainId !== 'undefined') {
-            if (!this.providers?.[chainId]) {
-                const error = new Error(`Missing RPC URL for chainId ${chainId}`);
-                core_1.Logger.log.error('getVaultLoans:missing_provider', error, { chainId });
-            }
-        }
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultLoans');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultLoans');
         // get vault loans data
         const vaultResponse = await (0, getters_1.getVaultLoans)(vault, {
             rpcUrl: chainId
@@ -429,7 +430,13 @@ class AugustVaults extends core_1.AugustBase {
         return vaultResponse;
     }
     /**
-     *
+     * Fetch a vault's loans broken down by sub-account.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Sub-account loan data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     async getVaultSubaccountLoans({ vault, chainId, }) {
         // Sanitize
@@ -437,14 +444,8 @@ class AugustVaults extends core_1.AugustBase {
             throw new Error('Vault input parameter is undefined.');
         if (!(0, ethers_1.isAddress)(vault))
             throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
-        if (typeof chainId !== 'undefined') {
-            if (!this.providers?.[chainId]) {
-                const error = new Error(`Missing RPC URL for chainId ${chainId}`);
-                core_1.Logger.log.error('getVaultSubaccountLoans:missing_provider', error, {
-                    chainId,
-                });
-            }
-        }
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultSubaccountLoans');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultSubaccountLoans');
         // get vault subaccount loans data
         const vaultResponse = await (0, getters_1.getVaultSubaccountLoans)(vault, {
             rpcUrl: chainId
@@ -461,7 +462,13 @@ class AugustVaults extends core_1.AugustBase {
         return vaultResponse;
     }
     /**
-     *
+     * Fetch a vault's DeFi / CeFi / OTC allocation breakdown.
+     * @param vault Vault contract address
+     * @param chainId Optional chain ID (uses active network if not provided)
+     * @returns Allocation data for the vault
+     * @throws {@link AugustValidationError} (`INVALID_CHAIN`) when `chainId` is
+     *   not a chain the SDK recognises, or is a supported EVM chain with no RPC
+     *   URL configured on this SDK instance.
      */
     async getVaultAllocations({ vault, chainId, }) {
         // Sanitize
@@ -472,14 +479,8 @@ class AugustVaults extends core_1.AugustBase {
             !utils_1.SolanaUtils.isSolanaAddress(vault) &&
             !(0, utils_2.isStellarAddress)(vault))
             throw new Error(`Vault input parameter is not an address: ${String(vault)}`);
-        if (typeof chainId !== 'undefined') {
-            if (!this.providers?.[chainId]) {
-                const error = new Error(`Missing RPC URL for chainId ${chainId}`);
-                core_1.Logger.log.error('getVaultAllocations:missing_provider', error, {
-                    chainId,
-                });
-            }
-        }
+        (0, core_1.assertKnownChainId)(chainId, this.providers, 'getVaultAllocations');
+        (0, core_1.assertEvmProviderConfigured)(chainId, this.providers, 'getVaultAllocations');
         // get vault allocations data
         try {
             const vaultResponse = await (0, getters_1.getVaultAllocations)(vault, {