@augustdigital/sdk 8.19.0 → 8.20.1

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

@@ -1,4 +1,4 @@
-export declare const SUI_CHAIN_ID = 101;
+export { SUI_CHAIN_ID } from '../../core/constants/web3';
 export declare const EMBER_API_BASE_URL = "https://vaults.api.sui-prod.bluefin.io/api/v1/vaults";
 export declare const EMBER_ENDPOINTS: {
     readonly VAULTS: "/";

package/lib/adapters/sui/constants.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALLOWED_SUI_VAULT_ADDRESSES = exports.EMBER_DEFAULTS = exports.EMBER_ENDPOINTS = exports.EMBER_API_BASE_URL = exports.SUI_CHAIN_ID = void 0;
-exports.SUI_CHAIN_ID = 101;
+// Canonical definition lives in `core/constants/web3.ts` so `core/` can
+// recognise the Sui chain ID without importing the adapter layer. Re-exported
+// here to keep `adapters/sui/constants` import sites (and the published API)
+// unchanged.
+var web3_1 = require("../../core/constants/web3");
+Object.defineProperty(exports, "SUI_CHAIN_ID", { enumerable: true, get: function () { return web3_1.SUI_CHAIN_ID; } });
 exports.EMBER_API_BASE_URL = 'https://vaults.api.sui-prod.bluefin.io/api/v1/vaults';
 exports.EMBER_ENDPOINTS = {
     VAULTS: '/',

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

@@ -1,6 +1,13 @@
 import type * as Sentry from '@sentry/browser';
 import type { IEnv } from '../../types';
 import type { IAnalyticsConfig } from './types';
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+export declare function resetErrorDedupe(): void;
 /**
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.

package/lib/core/analytics/sentry.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetErrorDedupe = resetErrorDedupe;
 exports.initializeSentry = initializeSentry;
 exports.updateUser = updateUser;
 exports.clearUser = clearUser;
@@ -78,6 +79,164 @@ function safeSetUser(user) {
         // Silently fail - analytics should never break SDK
     }
 }
+/**
+ * Chains whose errors are dropped before reaching Sentry.
+ *
+ * Mezo is muted by request: its public dRPC endpoint is unreliable enough that
+ * its failures dominated the error stream without ever describing an SDK
+ * defect. This is a deliberate blind spot — Mezo bugs (bad vault data, reverts,
+ * decode failures) are silenced along with the transport noise. Remove the
+ * entry to restore reporting; nothing else needs to change.
+ *
+ * Keyed by both the `chainIdToTagValue` slug and the numeric chain ID, because
+ * the two arrive on different events.
+ */
+const MUTED_CHAIN_SLUGS = new Set(['mezo']);
+/** Numeric chain IDs matching {@link MUTED_CHAIN_SLUGS}. */
+const MUTED_CHAIN_IDS = new Set(['31612']);
+/**
+ * Substrings that identify an event as Mezo-related regardless of tags.
+ *
+ * Tag-based matching alone is not enough: `sdk.chain` / `sdk.last_chainId`
+ * record the last *instrumented method's* chain, not the chain of the RPC that
+ * actually failed — the production Mezo batch-rejection events are tagged
+ * `sdk.chain: ethereum` while carrying `"requestUrl": "https://mezo.drpc.org"`
+ * in the message. Matching the message body catches those.
+ */
+const MUTED_CHAIN_MESSAGE_PATTERNS = [/mezo/i];
+/**
+ * Whether an event belongs to a muted chain and must not be sent.
+ *
+ * Checks, in order: the chain tags, then the event message and every exception
+ * value/type in the chain (an RPC failure's identifying detail often lives in a
+ * wrapped inner error rather than the top-level message).
+ *
+ * @param event - The Sentry event about to be sent.
+ * @returns `true` when the event should be dropped.
+ */
+function isMutedChainEvent(event) {
+    const chainTag = event.tags?.['sdk.chain'];
+    if (typeof chainTag === 'string' && MUTED_CHAIN_SLUGS.has(chainTag)) {
+        return true;
+    }
+    const chainIdTag = event.tags?.['sdk.last_chainId'];
+    if (typeof chainIdTag === 'string' && MUTED_CHAIN_IDS.has(chainIdTag)) {
+        return true;
+    }
+    const haystacks = [];
+    if (typeof event.message === 'string')
+        haystacks.push(event.message);
+    for (const exception of event.exception?.values ?? []) {
+        if (typeof exception.value === 'string')
+            haystacks.push(exception.value);
+        if (typeof exception.type === 'string')
+            haystacks.push(exception.type);
+    }
+    return haystacks.some((text) => MUTED_CHAIN_MESSAGE_PATTERNS.some((pattern) => pattern.test(text)));
+}
+/**
+ * Rolling window, in milliseconds, over which identical errors are counted.
+ */
+const ERROR_DEDUPE_WINDOW_MS = 60_000;
+/**
+ * Maximum captures of one error signature per {@link ERROR_DEDUPE_WINDOW_MS}.
+ * Chosen so a genuine, ongoing failure is still visible (and its rate
+ * observable via `sdk.suppressed_since_last`) while a hot loop hammering a
+ * broken RPC or a 404-per-borrower fan-out cannot bill thousands of identical
+ * events. Beyond this, further captures in the window are dropped.
+ */
+const ERROR_DEDUPE_MAX_PER_WINDOW = 3;
+/** Hard cap on tracked signatures, so the map cannot grow without bound. */
+const ERROR_DEDUPE_MAX_KEYS = 500;
+/**
+ * Per-signature capture bookkeeping for the dedupe window.
+ *
+ * Deliberately process-global, matching the Sentry client it feeds: the client
+ * is a singleton, so every `AugustSDK` instance in the process shares one
+ * event stream and one quota. The signature intentionally omits partner/app
+ * identity — a host serving several partners reports an identical upstream
+ * failure ≤{@link ERROR_DEDUPE_MAX_PER_WINDOW} times per window in aggregate,
+ * not per partner, because the failure is one event regardless of how many
+ * tenants observed it. Per-tenant attribution comes from the `partner.id` tag
+ * on the events that are sent, and `sdk.suppressed_since_last` preserves the
+ * true rate. `resetAnalytics()` clears this map for the whole process.
+ */
+const errorDedupeState = new Map();
+/**
+ * Build a low-cardinality signature for an error.
+ *
+ * Message tails carry the variable parts (addresses, block ranges, response
+ * bodies), so only the leading 120 characters participate — enough to separate
+ * distinct failure modes without splitting one failure mode into thousands of
+ * unique keys.
+ *
+ * @param error - The normalized error being captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns A stable key identifying this class of failure.
+ */
+function errorSignature(error, origin) {
+    const tag = typeof origin === 'string' ? origin : '';
+    return `${tag}|${error.name}|${(error.message || '').slice(0, 120)}`;
+}
+/**
+ * Decide whether an error should be sent to Sentry, applying a per-signature
+ * rolling rate limit.
+ *
+ * Why this exists: the SDK is called from server-rendered pages that fan out
+ * per vault and per borrower, so a single upstream condition (a 502 from the
+ * backend, an RPC rejecting a batch) reproduces on every iteration of every
+ * request. Those are the same event, and paying Sentry per copy buys no extra
+ * signal.
+ *
+ * Side effect: mutates {@link errorDedupeState}.
+ *
+ * @param error - The normalized error about to be captured.
+ * @param origin - The `sdk.origin` call-site tag, when present.
+ * @returns `send: false` to drop the event. When `send: true`, `suppressed` is
+ *   the number of copies dropped since the last event that was sent, and is
+ *   attached to the outgoing event so the true rate stays recoverable.
+ */
+function admitError(error, origin) {
+    const key = errorSignature(error, origin);
+    const now = Date.now();
+    const entry = errorDedupeState.get(key);
+    // Touch the key on every access so iteration order is true
+    // least-recently-used, not first-inserted: a Map's `set` on an existing key
+    // does NOT reorder it, so without the delete a signature that keeps
+    // recurring would hold its original position and be evicted ahead of a stale
+    // one-shot signature registered after it — silently handing the hot
+    // signature a fresh allowance every time it churned out of the map.
+    errorDedupeState.delete(key);
+    if (!entry || now - entry.windowStart >= ERROR_DEDUPE_WINDOW_MS) {
+        // Bound the map: drop the least-recently-used signature before inserting.
+        if (errorDedupeState.size >= ERROR_DEDUPE_MAX_KEYS) {
+            const oldest = errorDedupeState.keys().next();
+            if (!oldest.done)
+                errorDedupeState.delete(oldest.value);
+        }
+        const suppressed = entry?.suppressed ?? 0;
+        errorDedupeState.set(key, { windowStart: now, captured: 1, suppressed: 0 });
+        return { send: true, suppressed };
+    }
+    errorDedupeState.set(key, entry);
+    if (entry.captured < ERROR_DEDUPE_MAX_PER_WINDOW) {
+        // `suppressed` can only be non-zero once the allowance is exhausted, so
+        // inside the allowance there is never a carried count to report.
+        entry.captured += 1;
+        return { send: true, suppressed: 0 };
+    }
+    entry.suppressed += 1;
+    return { send: false, suppressed: entry.suppressed };
+}
+/**
+ * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
+ * lifetime state and would otherwise leak between test cases.
+ *
+ * @internal
+ */
+function resetErrorDedupe() {
+    errorDedupeState.clear();
+}
 /**
  * Build the SDK's internal Sentry sink — the bridge that forwards
  * `Logger.log.*` output to the resolved Sentry SDK. Errors are captured as
@@ -95,6 +254,12 @@ function createSentrySink() {
                 const sdk = (0, sentry_runtime_1.getSentrySDK)();
                 if (!sdk)
                     return;
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                // Rate-limit identical failures before touching Sentry at all — the
+                // scope work and the event payload are both wasted if it is dropped.
+                const admission = admitError(normalized, context?.tag);
+                if (!admission.send)
+                    return;
                 sdk.withScope((scope) => {
                     // `beforeSend` drops any event not tagged as ours; the tag is global
                     // already, but set it on the scope defensively in case a future
@@ -115,7 +280,10 @@ function createSentrySink() {
                             }
                         }
                     }
-                    const normalized = error instanceof Error ? error : new Error(String(error));
+                    // Preserve the true failure rate even though copies were dropped.
+                    if (admission.suppressed > 0) {
+                        scope.setExtra('sdk.suppressed_since_last', admission.suppressed);
+                    }
                     sdk.captureException(normalized);
                 });
             }
@@ -243,12 +411,22 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
                 // Local dev/test node leaking into a prod DSN: :8545 is the canonical
                 // Anvil/Hardhat port and is never a production RPC endpoint.
                 /ECONNREFUSED .*:8545/,
+                // AugustHistoryUnavailableError is a designed, documented outcome:
+                // the getter refuses to return a fabricated number when the indexer
+                // has no deposit/withdrawal history. It is thrown to the caller, who
+                // renders "temporarily unavailable" — the SDK is behaving correctly,
+                // so it is not an SDK issue. Indexer health is monitored separately.
+                /transaction history unavailable/i,
             ],
             beforeSend(event) {
                 // Only send events tagged as SDK-related
                 if (event.tags?.sdk !== 'august-digital') {
                     return null;
                 }
+                // Muted chains (see MUTED_CHAIN_SLUGS) are dropped wholesale.
+                if (isMutedChainEvent(event)) {
+                    return null;
+                }
                 return event;
             },
             beforeSendTransaction(transaction) {
@@ -383,6 +561,9 @@ function resetAnalytics() {
     cachedApiKey = undefined;
     logger_1.Logger.setSentrySink(null);
     (0, sentry_runtime_1.resetSentryRuntime)();
+    // The error rate limiter is process-lifetime state; a reset analytics layer
+    // must not inherit a half-full dedupe window from the previous one.
+    resetErrorDedupe();
 }
 /**
  * Capture an exception into Sentry with SDK-specific context. Use from

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.19.0";
+export declare const SDK_VERSION = "8.20.1";

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.19.0';
+exports.SDK_VERSION = '8.20.1';
 //# sourceMappingURL=version.js.map

package/lib/core/constants/core.js

@@ -5,6 +5,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_FETCH_OPTIONS = exports.WEBSERVER_ENDPOINTS = exports.WEBSERVER_URL = exports.PRICE_SERVER_URL = exports.REQUEST_TIMEOUT_MS = void 0;
 const ethers_1 = require("ethers");
+/**
+ * Build the path segment for a subaccount identifier.
+ *
+ * Why this exists: subaccounts are not EVM-only. Vault operators and loan
+ * borrowers can be Solana base58 keys or Stellar `G…`/`C…` addresses, and the
+ * backend keys those records by their native string form. Calling ethers'
+ * `getAddress()` on them throws `INVALID_ARGUMENT` before the request is ever
+ * made — which is how a Solana borrower turned every
+ * `getVaultAllocations` call for a mixed-chain vault into a
+ * `TypeError: invalid address` (see `getVaultAllocations:cefi` /
+ * `:otc` in Sentry).
+ *
+ * EVM addresses are still checksummed, because the backend expects the
+ * checksummed form for those and case-normalising avoids cache misses.
+ * Everything else is passed through URL-encoded so a malformed value can never
+ * inject extra path segments.
+ *
+ * @param subaccount - Subaccount identifier: EVM hex address, Solana base58
+ *   public key, or Stellar strkey. Not validated beyond the EVM branch — the
+ *   backend is the authority on whether a non-EVM identifier exists.
+ * @returns A single URL path segment safe to interpolate into an endpoint.
+ */
+function subaccountSegment(subaccount) {
+    return (0, ethers_1.isAddress)(subaccount)
+        ? (0, ethers_1.getAddress)(subaccount)
+        : encodeURIComponent(subaccount);
+}
 /**
  * Request timeout in milliseconds.
  * Set to 90 seconds to accommodate slow API responses.
@@ -34,22 +61,22 @@ exports.WEBSERVER_ENDPOINTS = {
     },
     subaccount: {
         list: (offset = 0, limit = 100) => `/subaccount?offset=${offset}&limit=${limit}`,
-        rewards: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/rewards`,
-        tokens: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/tokens`,
+        rewards: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/rewards`,
+        tokens: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tokens`,
         twap: {
-            create: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap`,
-            stop: (subaccount, id) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap/${id}/stop`,
-            fills: (subaccount, id) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/twap/${id}/fills`,
+            create: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/twap`,
+            stop: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/stop`,
+            fills: (subaccount, id) => `/subaccount/${subaccountSegment(subaccount)}/twap/${id}/fills`,
         },
-        debank: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/debank`,
-        health_factor: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/health_factor`,
-        summary: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/summary`,
-        batch: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/tx_batcher_integrations`,
-        loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/loans?side=${side}&active=${active}`,
-        cefi: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/cefi_position`,
-        otc_positions: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}/otc_positions`,
+        debank: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/debank`,
+        health_factor: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/health_factor`,
+        summary: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/summary`,
+        batch: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tx_batcher_integrations`,
+        loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${subaccountSegment(subaccount)}/loans?side=${side}&active=${active}`,
+        cefi: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/cefi_position`,
+        otc_positions: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/otc_positions`,
         loanByAddress: (loanAddress, chainId) => `/subaccount/loans/${encodeURIComponent(loanAddress)}?chain_id=${chainId}`,
-        _: (subaccount) => `/subaccount/${(0, ethers_1.getAddress)(subaccount)}`,
+        _: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}`,
     },
     transactions: {
         v2: (subaccount, startTime, endTime) => {
@@ -108,7 +135,7 @@ exports.WEBSERVER_ENDPOINTS = {
     },
     prices: (symbol) => `/prices/${symbol}`,
     metrics: {
-        pnl: (subaccount, startTime, endTime) => `/metrics/pnl?subaccount_address=${(0, ethers_1.getAddress)(subaccount)}${startTime && endTime ? `&start=${startTime}&end=${endTime}` : ''}`,
+        pnl: (subaccount, startTime, endTime) => `/metrics/pnl?subaccount_address=${subaccountSegment(subaccount)}${startTime && endTime ? `&start=${startTime}&end=${endTime}` : ''}`,
         vaultPerformanceFees: (params) => {
             const q = new URLSearchParams({
                 vault_address: params.vaultAddress,
@@ -126,7 +153,7 @@ exports.WEBSERVER_ENDPOINTS = {
     public: {
         integrations: {
             morpho: {
-                apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${(0, ethers_1.getAddress)(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,
+                apy: (subaccount, vaultAddress) => `/integrations/morpho/apy?subaccount_address=${subaccountSegment(subaccount)}&vault_address=${(0, ethers_1.getAddress)(vaultAddress)}`,
             },
         },
         tokenizedVault: {

package/lib/core/constants/web3.d.ts

@@ -11,6 +11,23 @@ export declare const SPECIAL_CHAINS: {
         explorer: string;
     };
 };
+/**
+ * Chain ID used to address Sui vaults.
+ *
+ * Unlike Solana (`-1`) and Stellar (`-3`), Sui does not use a synthetic
+ * negative ID — `101` is the SLIP-44-derived value the Sui adapter has always
+ * used. It lives here rather than in `adapters/sui/constants.ts` so that
+ * `core/` can recognise it without importing the adapter layer (which would
+ * create a `core → adapters` back-edge); the adapter re-exports it.
+ */
+export declare const SUI_CHAIN_ID = 101;
+/**
+ * Chain IDs the SDK understands that are **not** served by an EVM JSON-RPC
+ * provider. Callers may legitimately pass these to vault methods without a
+ * matching entry in the `providers` map — the request routes through the
+ * Solana / Stellar / Sui adapter instead.
+ */
+export declare const NON_EVM_CHAIN_IDS: ReadonlySet<number>;
 export declare const NATIVE_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
 /**
  * Decimal precision of the native gas token on every EVM chain this SDK

package/lib/core/constants/web3.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FALLBACK_RPC_URLS = exports.FALLBACK_CHAINID = exports.FALLBACK_DECIMALS = exports.MULTICALL3_VERIFIED_CHAINS = exports.MULTICALL3_ADDRESS = exports.AVAILABLE_CHAINS = exports.NETWORKS = exports.ORACLE_CONTRACTS = exports.MIN_ABIS = exports.EVM_NATIVE_DECIMALS = exports.NATIVE_ADDRESS = exports.SPECIAL_CHAINS = void 0;
+exports.FALLBACK_RPC_URLS = exports.FALLBACK_CHAINID = exports.FALLBACK_DECIMALS = exports.MULTICALL3_VERIFIED_CHAINS = exports.MULTICALL3_ADDRESS = exports.AVAILABLE_CHAINS = exports.NETWORKS = exports.ORACLE_CONTRACTS = exports.MIN_ABIS = exports.EVM_NATIVE_DECIMALS = exports.NATIVE_ADDRESS = exports.NON_EVM_CHAIN_IDS = exports.SUI_CHAIN_ID = exports.SPECIAL_CHAINS = void 0;
 // Special Chains
 exports.SPECIAL_CHAINS = {
     solana: {
@@ -14,6 +14,27 @@ exports.SPECIAL_CHAINS = {
         explorer: 'https://stellar.expert',
     },
 };
+/**
+ * Chain ID used to address Sui vaults.
+ *
+ * Unlike Solana (`-1`) and Stellar (`-3`), Sui does not use a synthetic
+ * negative ID — `101` is the SLIP-44-derived value the Sui adapter has always
+ * used. It lives here rather than in `adapters/sui/constants.ts` so that
+ * `core/` can recognise it without importing the adapter layer (which would
+ * create a `core → adapters` back-edge); the adapter re-exports it.
+ */
+exports.SUI_CHAIN_ID = 101;
+/**
+ * Chain IDs the SDK understands that are **not** served by an EVM JSON-RPC
+ * provider. Callers may legitimately pass these to vault methods without a
+ * matching entry in the `providers` map — the request routes through the
+ * Solana / Stellar / Sui adapter instead.
+ */
+exports.NON_EVM_CHAIN_IDS = new Set([
+    exports.SPECIAL_CHAINS.solana.chainId,
+    exports.SPECIAL_CHAINS.stellar.chainId,
+    exports.SUI_CHAIN_ID,
+]);
 // General
 exports.NATIVE_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 /**

package/lib/core/helpers/chain-support.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+export declare function isEvmChainId(chainId: number): boolean;
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+export declare function isKnownChainId(chainId: number): boolean;
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-2, undefined, 'getVault');
+ * // AugustValidationError: getVault: unknown chainId -2.
+ * ```
+ */
+export declare function assertKnownChainId(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // AugustValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+export declare function assertEvmProviderConfigured(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;

package/lib/core/helpers/chain-support.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEvmChainId = isEvmChainId;
+exports.isKnownChainId = isKnownChainId;
+exports.assertKnownChainId = assertKnownChainId;
+exports.assertEvmProviderConfigured = assertEvmProviderConfigured;
+const web3_1 = require("../constants/web3");
+const errors_1 = require("../errors");
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+function isEvmChainId(chainId) {
+    return Object.hasOwn(web3_1.NETWORKS, chainId);
+}
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+function isKnownChainId(chainId) {
+    return isEvmChainId(chainId) || web3_1.NON_EVM_CHAIN_IDS.has(chainId);
+}
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-2, undefined, 'getVault');
+ * // AugustValidationError: getVault: unknown chainId -2.
+ * ```
+ */
+function assertKnownChainId(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (isKnownChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    throw new errors_1.AugustValidationError('INVALID_CHAIN', `${method}: unknown chainId ${chainId}. ` +
+        'Pass a supported EVM chain ID (see NETWORKS) or a non-EVM chain ID ' +
+        '(-1 Solana, -3 Stellar, 101 Sui).', { context: { method, chainId } });
+}
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link AugustValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // AugustValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+function assertEvmProviderConfigured(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (!isEvmChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    const name = web3_1.NETWORKS[chainId]?.name;
+    throw new errors_1.AugustValidationError('INVALID_CHAIN', `${method}: no RPC URL configured for chainId ${chainId}` +
+        `${name ? ` (${name})` : ''}. ` +
+        'Pass one when constructing AugustSDK: ' +
+        `new AugustSDK({ providers: { ${chainId}: '<rpc-url>' } }).`, { context: { method, chainId } });
+}
+//# sourceMappingURL=chain-support.js.map

package/lib/core/helpers/web3.d.ts

@@ -33,7 +33,26 @@ export declare const determineSecondsPerBlock: (chain: number) => number;
  * @param chain Chain ID
  * @returns Block interval for pagination
  */
-export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 50000;
+export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 10000;
+/**
+ * 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`.
+ */
+export declare const determineRpcBatchMaxCount: (rpcUrl: string) => number;
 /**
  * Retrieve chain ID from web3 provider.
  * Handles both initialized and uninitialized provider states.