@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/core/analytics/user-identity.js

@@ -7,11 +7,21 @@ exports.createUserIdentity = createUserIdentity;
 exports.getUserId = getUserId;
 const crypto_1 = require("crypto");
 const uuid_1 = require("uuid");
+/** Session ID persists for SDK instance lifetime */
 let sessionId = null;
+/** Cached masked API key */
 let cachedMaskedApiKey = null;
+/**
+ * Mask an API key, keeping only the last 5 characters visible.
+ * Example: "abcdefghij12345" -> "**********12345"
+ *
+ * @param apiKey - The raw API key to mask
+ * @returns Masked API key with last 5 characters visible
+ */
 function hashApiKey(apiKey) {
     if (!apiKey)
         return '';
+    // Use cached masked key if available
     if (cachedMaskedApiKey)
         return cachedMaskedApiKey;
     const visibleChars = 5;
@@ -25,14 +35,27 @@ function hashApiKey(apiKey) {
     }
     return cachedMaskedApiKey;
 }
+/**
+ * Generate a session ID that persists for the SDK instance lifetime.
+ * Provides user continuity even when wallet is not connected.
+ *
+ * @returns UUID v4 session identifier
+ */
 function getSessionId() {
     if (!sessionId) {
         sessionId = (0, uuid_1.v4)();
     }
     return sessionId;
 }
+/**
+ * Generate a browser/environment fingerprint for cross-session tracking.
+ * Falls back gracefully in different environments.
+ *
+ * @returns Base64 encoded fingerprint string or undefined if unavailable
+ */
 function generateFingerprint() {
     try {
+        // Browser environment
         if (typeof window !== 'undefined' && typeof navigator !== 'undefined') {
             const components = [
                 navigator.userAgent,
@@ -42,11 +65,13 @@ function generateFingerprint() {
                 typeof screen !== 'undefined' ? screen.height?.toString() : '',
                 typeof screen !== 'undefined' ? screen.colorDepth?.toString() : '',
             ].filter(Boolean);
+            // Create a simple hash from components
             const hash = (0, crypto_1.createHash)('sha256')
                 .update(components.join('|'))
                 .digest('hex');
             return hash.substring(0, 32);
         }
+        // Node.js environment
         if (typeof process !== 'undefined' && process.platform) {
             const components = [process.platform, process.arch, process.version];
             const hash = (0, crypto_1.createHash)('sha256')
@@ -56,10 +81,19 @@ function generateFingerprint() {
         }
     }
     catch {
+        // Silently fail if fingerprinting is not possible
         return undefined;
     }
     return undefined;
 }
+/**
+ * Create a composite user identity for analytics.
+ *
+ * @param apiKey - Optional API key (will be hashed, never stored raw)
+ * @param walletAddress - Optional wallet address
+ * @param environment - Current environment (DEV or PROD)
+ * @returns User identity object
+ */
 function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
     let domain = undefined;
     try {
@@ -71,6 +105,7 @@ function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
         }
     }
     catch {
+        // Silently fail - domain is optional
     }
     return {
         apiKeyHash: apiKey ? hashApiKey(apiKey) : undefined,
@@ -81,6 +116,13 @@ function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
         domain,
     };
 }
+/**
+ * Generate a unique user ID for Sentry from identity components.
+ * Priority: apiKeyHash > wallet > fingerprint > session
+ *
+ * @param identity - User identity object
+ * @returns Prefixed user ID string
+ */
 function getUserId(identity) {
     if (identity.domain) {
         return `domain:${identity.domain}`;

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

@@ -1 +1,6 @@
-export declare const SDK_VERSION = "8.3.1";
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated during publish from package.json version
+ * This file is gitignored and created at publish time
+ */
+export declare const SDK_VERSION = "8.5.0";

package/lib/core/analytics/version.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = '8.3.1';
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ * Generated during publish from package.json version
+ * This file is gitignored and created at publish time
+ */
+exports.SDK_VERSION = '8.5.0';
 //# sourceMappingURL=version.js.map

package/lib/core/auth/verify.js

@@ -13,6 +13,9 @@ async function verifyInfuraKey(key) {
     return true;
 }
 async function verifyAugustKey(key) {
+    // Fast path: no key means no verification possible. Returning false here
+    // preserves the historical contract (`init()` throws a generic "API key is invalid")
+    // and avoids letting an AUTH_MISSING_KEY error bubble up from the fetcher.
     if (!key)
         return false;
     try {
@@ -20,6 +23,8 @@ async function verifyAugustKey(key) {
         return verify.status === 200;
     }
     catch {
+        // Network errors, timeouts, and any future thrown auth errors all
+        // resolve to "key not verified" here. Callers handle this as a boolean.
         return false;
     }
 }

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

@@ -11,31 +11,106 @@ interface IMonitoring extends IWSMonitorHeaders {
     env?: IEnv;
 }
 export interface IAugustBase {
+    /**
+     * Identifier-shaped name for the integrating application. Required.
+     *
+     * Pick a stable, kebab-case slug that identifies your product (e.g.
+     * `"acme-trader"`, `"my-defi-app"`). The SDK includes it on outbound
+     * analytics events so August Digital can see who's hitting which methods
+     * and reach out about breaking changes or critical bugs.
+     *
+     * Despite the friendly `appName` label, the value is used as a Sentry
+     * tag and HTTP header, so it must be identifier-shaped:
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * const sdk = new AugustSDK({
+     *   appName: 'acme-trader',
+     *   providers: { 1: 'https://...' },
+     *   keys: { august: '...' },
+     * });
+     * ```
+     */
     appName: string;
     providers?: IProvidersConfig;
     solana?: ISolanaConfig;
     keys: IKeys;
     monitoring?: IMonitoring;
+    /** Analytics configuration. Enabled by default (opt-out model). */
     analytics?: IAnalyticsConfig;
+    /**
+     * Best-effort npm-registry version check. Enabled by default in
+     * non-production environments; never runs in `NODE_ENV=production`.
+     * Set `enabled: false` to disable entirely (or set the
+     * `AUGUST_SDK_DISABLE_VERSION_CHECK` env var).
+     */
     versionCheck?: IVersionCheckConfig;
+    /**
+     * Default request timeout (in milliseconds) for backend API calls made by
+     * this SDK instance. Falls back to the SDK's compiled-in
+     * `REQUEST_TIMEOUT_MS` (90 s) when omitted.
+     *
+     * Per-call `timeoutMs` (when threaded through to the fetcher) still wins
+     * over this value. Setting this only changes the default that's used when
+     * no per-call value is supplied.
+     *
+     * Note: this is a process-global override on the underlying fetcher
+     * helpers, so the last `AugustSDK` instantiated wins if you create several
+     * with different timeouts in the same process.
+     */
     timeoutMs?: number;
 }
 interface IActiveNetwork {
     chainId: IChainId;
     rpcUrl: string;
 }
+/**
+ * Base class providing core SDK functionality including provider management,
+ * network switching, and authentication state.
+ */
 export declare class AugustBase {
     keys: IKeys;
     monitoring: IMonitoring;
     authorized: boolean;
     activeNetwork?: IActiveNetwork;
     providers: IProvidersConfig;
+    /** Validated app-name slug from the constructor. */
     appName: string;
+    /**
+     * 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}.
+     */
     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, }: IAugustBase);
+    /**
+     * Verify API keys and authorize SDK usage.
+     * TODO: initialize class with appropriate keys and verify august key
+     */
     init(): Promise<void>;
+    /**
+     * Return the active network or throw a clear error.
+     * Use this in methods that require an EVM provider.
+     */
     protected requireActiveNetwork(): IActiveNetwork;
+    /**
+     * Switch the active blockchain network.
+     * Updates both chain ID and RPC URL for subsequent operations.
+     */
     switchNetwork(chainId: IChainId): void;
+    /**
+     * Set active wallet address and update monitoring headers.
+     * Preserves existing environment setting.
+     */
     updateWallet(address: IAddress): void;
+    /**
+     * Remove wallet address from SDK state and monitoring headers.
+     */
     clearWallet(): void;
 }
 export {};

package/lib/core/base.class.js

@@ -6,6 +6,19 @@ const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
 const version_check_1 = require("./version-check");
 const fetcher_1 = require("./fetcher");
+/**
+ * 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) {
@@ -20,15 +33,31 @@ function validateAppName(value) {
     }
     return trimmed;
 }
+/**
+ * Base class providing core SDK functionality including provider management,
+ * network switching, and authentication state.
+ */
 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}.
+     */
     constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, }) {
         this.monitoring = {
             'x-user-id': undefined,
             'x-environment': undefined,
         };
+        // Validate first so the failure mode is a clear, actionable error before
+        // any provider / analytics side effects run.
         this.appName = validateAppName(appName);
+        // TODO: change this to false later when august key is required
         this.authorized = true;
         this.providers = providers;
+        // Set active network from the first provider (if any).
+        // An empty providers map is valid for backend-only chains (e.g. Stellar).
         if (Object.keys(providers).length > 0) {
             this.activeNetwork = {
                 chainId: Number(Object.keys(providers)[0]),
@@ -36,18 +65,28 @@ class AugustBase {
             };
         }
         this.keys = keys;
+        // Set environment (defaults to PROD for safety)
         const environment = monitoring?.env || monitoring?.['x-environment'] || 'PROD';
         this.monitoring = {
             ...monitoring,
             'x-environment': environment,
         };
+        // Set dev mode for logging (only true if explicitly set to DEV)
         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);
+        // 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);
         if (typeof timeoutMs === 'number') {
             (0, fetcher_1.setSdkRequestTimeout)(timeoutMs);
         }
     }
+    /**
+     * Verify API keys and authorize SDK usage.
+     * TODO: initialize class with appropriate keys and verify august key
+     */
     async init() {
         const [augustCheck] = await Promise.all([
             (0, auth_1.verifyAugustKey)(this.keys?.august),
@@ -58,6 +97,10 @@ class AugustBase {
         logger_1.Logger.log.info('init', 'August Digital SDK successfully initialized');
         return;
     }
+    /**
+     * Return the active network or throw a clear error.
+     * Use this in methods that require an EVM provider.
+     */
     requireActiveNetwork() {
         if (!this.activeNetwork) {
             throw new Error('No active network configured. This operation requires an EVM provider. ' +
@@ -65,6 +108,10 @@ class AugustBase {
         }
         return this.activeNetwork;
     }
+    /**
+     * Switch the active blockchain network.
+     * Updates both chain ID and RPC URL for subsequent operations.
+     */
     switchNetwork(chainId) {
         if (!this.providers[chainId]) {
             throw new Error(`No provider configured for chainId ${chainId}. Available chains: ${Object.keys(this.providers).join(', ')}`);
@@ -74,6 +121,10 @@ class AugustBase {
             rpcUrl: this.providers[chainId],
         };
     }
+    /**
+     * Set active wallet address and update monitoring headers.
+     * Preserves existing environment setting.
+     */
     updateWallet(address) {
         if (!address)
             return;
@@ -82,8 +133,12 @@ class AugustBase {
             ...this.monitoring,
             'x-user-id': lowercasedAddress,
         };
+        // Update analytics user identity
         (0, analytics_1.updateUser)(lowercasedAddress, this.monitoring['x-environment']);
     }
+    /**
+     * Remove wallet address from SDK state and monitoring headers.
+     */
     clearWallet() {
         if (this.monitoring) {
             this.monitoring = {
@@ -91,6 +146,7 @@ class AugustBase {
                 'x-user-id': undefined,
             };
         }
+        // Clear wallet from analytics user identity
         (0, analytics_1.clearUser)();
     }
 }

package/lib/core/cache.d.ts

@@ -1,4 +1,9 @@
 import { LRUCache } from 'lru-cache';
+/**
+ * Process-wide LRU used by core helpers for memoizing RPC / fetch results.
+ * Kept in a leaf module so importers don't pull in the broader `core/fetcher.ts`
+ * graph (which would cycle through `core/helpers/web3.ts`).
+ */
 export declare const CACHE: LRUCache<string, any, unknown>;
 export declare const getSafeCache: <T>(key: string) => Promise<T | null>;
 export declare const setSafeCache: <T>(key: string, value: T) => Promise<void>;

package/lib/core/cache.js

@@ -2,6 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setSafeCache = exports.getSafeCache = exports.CACHE = void 0;
 const lru_cache_1 = require("lru-cache");
+/**
+ * Process-wide LRU used by core helpers for memoizing RPC / fetch results.
+ * Kept in a leaf module so importers don't pull in the broader `core/fetcher.ts`
+ * graph (which would cycle through `core/helpers/web3.ts`).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: shared heterogeneous cache keyed by string; a concrete value type would force casts at every call site and risk a dependency cycle through core/helpers/web3.ts.
 exports.CACHE = new lru_cache_1.LRUCache({
     max: 1000,
     ttl: 1000 * 60 * 60 * 24,

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

@@ -1,9 +1,21 @@
+/**
+ * Adapter Configurations for Vaults
+ *
+ * This file contains configurations for vaults that support deposits with alternative tokens
+ * through wrapper contracts, swap adapters, or native token deposits.
+ */
 import { IVaultAdapterConfig, IAddress } from '../../types';
+/**
+ * Pool/Vault names for adapter routing
+ */
 export declare const POOL_NAMES: {
     readonly ETH_TREEHOUSE_GROWTH: "Treehouse Growth";
     readonly AVAX_AVAX: "AVAX Strategy";
     readonly ETH_KELP_TAC_RSETH: "Kelp TAC rsETH";
 };
+/**
+ * Adapter ABIs for wrapper contracts
+ */
 export declare const ADAPTER_ABIS: {
     readonly NATIVE_DEPOSIT_AVAX: readonly [{
         readonly inputs: readonly [];
@@ -85,4 +97,7 @@ export declare const ADAPTER_ABIS: {
         readonly type: "function";
     }];
 };
+/**
+ * Vault adapter configurations mapping vault addresses to their adapter settings
+ */
 export declare const VAULT_ADAPTER_CONFIGS: Record<IAddress, IVaultAdapterConfig>;

package/lib/core/constants/adapters.js

@@ -1,12 +1,24 @@
 "use strict";
+/**
+ * Adapter Configurations for Vaults
+ *
+ * This file contains configurations for vaults that support deposits with alternative tokens
+ * through wrapper contracts, swap adapters, or native token deposits.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VAULT_ADAPTER_CONFIGS = exports.ADAPTER_ABIS = exports.POOL_NAMES = void 0;
 const ethers_1 = require("ethers");
+/**
+ * Pool/Vault names for adapter routing
+ */
 exports.POOL_NAMES = {
     ETH_TREEHOUSE_GROWTH: 'Treehouse Growth',
     AVAX_AVAX: 'AVAX Strategy',
     ETH_KELP_TAC_RSETH: 'Kelp TAC rsETH',
 };
+/**
+ * Adapter ABIs for wrapper contracts
+ */
 exports.ADAPTER_ABIS = {
     NATIVE_DEPOSIT_AVAX: [
         {
@@ -97,13 +109,18 @@ exports.ADAPTER_ABIS = {
         },
     ],
 };
+/**
+ * Vault adapter configurations mapping vault addresses to their adapter settings
+ */
 exports.VAULT_ADAPTER_CONFIGS = {
+    // Multi-asset vault with view adapter
     '0x18EE038C114a07f4B08b420fb1E4149a4F357249': {
         viewAdapter: '0x72f3cf0d87e9688fad77711d02d86c68334fb275',
         lpTokenAddress: '0xeF866BfbD0eEc6D6b42C37d8acC0D5fd26828376',
         isNativeTokenDeposit: false,
         isWrappedTokenDeposit: false,
     },
+    // BTC multi-token vault with Paraswap bridge
     '0x8AcA0841993ef4C87244d519166e767f49362C21': {
         isNativeTokenDeposit: false,
         isWrappedTokenDeposit: false,
@@ -112,11 +129,12 @@ exports.VAULT_ADAPTER_CONFIGS = {
         bridgeId: 2,
         abi: [],
         tokens: [
-            '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
-            '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf',
+            '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599', // WBTC
+            '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf', // cbBTC
             '0x18084fbA666a33d37592fA2633fD49a74DD93a88',
         ],
     },
+    // AVAX native deposit vault
     '0xB2bFb52cfc40584AC4e9e2B36a5B8d6554A56e0b': {
         isNativeTokenDeposit: true,
         isWrappedTokenDeposit: false,
@@ -124,10 +142,11 @@ exports.VAULT_ADAPTER_CONFIGS = {
         wrapperAddress: '0xb2C57614B93c41A7Ec3B91980C0Bb7453904c6e8',
         abi: exports.ADAPTER_ABIS.NATIVE_DEPOSIT_AVAX,
         tokens: [
-            '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7',
+            '0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7', // WAVAX
             ethers_1.ZeroAddress,
         ],
     },
+    // ETH Treehouse Growth - native deposit with referral
     '0x5Fde59415625401278c4d41C6beFCe3790eb357f': {
         isNativeTokenDeposit: true,
         isWrappedTokenDeposit: true,
@@ -136,11 +155,12 @@ exports.VAULT_ADAPTER_CONFIGS = {
         wrapperAddress: '0x6B6b27F08B84c186626D5A64614B5192a8ef71a9',
         abi: exports.ADAPTER_ABIS.NATIVE_DEPOSIT_ETH_WITH_REFERRAL,
         tokens: [
-            '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0',
-            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+            '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0', // wstETH
+            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
             ethers_1.ZeroAddress,
         ],
     },
+    // Kelp TAC rsETH - native deposit with custom adapter
     '0x419386E3Ef42368e602720CC458e00c0B28c47A7': {
         isNativeTokenDeposit: true,
         isWrappedTokenDeposit: true,
@@ -150,9 +170,9 @@ exports.VAULT_ADAPTER_CONFIGS = {
         viewAdapter: '0x036676389e48133B63a802f8635AD39E752D375D',
         abi: exports.ADAPTER_ABIS.KELP_RSETH_ADAPTER,
         tokens: [
-            '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84',
-            '0xA35b1B31Ce002FBF2058D22F30f95D405200A15b',
-            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+            '0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84', // stETH
+            '0xA35b1B31Ce002FBF2058D22F30f95D405200A15b', // ETHx
+            '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
             ethers_1.ZeroAddress,
         ],
     },

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

@@ -1,4 +1,11 @@
-import { IAddress, VaultAddress } from '../../types';
+/**
+ * August Digital
+ */
+import type { IAddress, VaultAddress } from '../../types';
+/**
+ * Request timeout in milliseconds.
+ * Set to 90 seconds to accommodate slow API responses.
+ */
 export declare const REQUEST_TIMEOUT_MS = 90000;
 export declare const PRICE_SERVER_URL = "https://prices.augustdigital.io";
 export declare const WEBSERVER_URL: {
@@ -72,6 +79,10 @@ export declare const WEBSERVER_ENDPOINTS: {
         vaults: {
             pendingRedemptions: (vaultAddress: IAddress) => string;
         };
+        pnl: {
+            unrealizedHistory: (vaultAddress: VaultAddress, limit?: number) => string;
+            unrealizedLatest: string;
+        };
     };
     upshift: {
         vaults: {

package/lib/core/constants/core.js

@@ -1,7 +1,14 @@
 "use strict";
+/**
+ * August Digital
+ */
 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");
+/**
+ * Request timeout in milliseconds.
+ * Set to 90 seconds to accommodate slow API responses.
+ */
 exports.REQUEST_TIMEOUT_MS = 90000;
 exports.PRICE_SERVER_URL = 'https://prices.augustdigital.io';
 exports.WEBSERVER_URL = {
@@ -75,12 +82,17 @@ exports.WEBSERVER_ENDPOINTS = {
         vaults: {
             pendingRedemptions: (vaultAddress) => `/vaults/${vaultAddress}/pending-redemptions`,
         },
+        pnl: {
+            unrealizedHistory: (vaultAddress, limit) => `/upshift/unrealized_pnl?vault_address=${vaultAddress}${limit !== undefined ? `&limit=${limit}` : ''}`,
+            unrealizedLatest: '/upshift/unrealized_pnl/latest',
+        },
     },
     upshift: {
         vaults: {
             metadata: `/api/sdk/vaults-metadata`,
         },
     },
+    // TODO: add remaining endpoints
 };
 exports.DEFAULT_FETCH_OPTIONS = {
     method: 'GET',

package/lib/core/constants/swap-router.d.ts

@@ -1,8 +1,54 @@
 import { IAddress } from '../../types';
+/**
+ * Address of the `SwapRouter` periphery contract on each supported chain.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain — callers
+ * should fall back to legacy adapter paths.
+ *
+ * @see {@link getSwapRouterAddress} for the typed lookup helper.
+ */
 export declare const SWAP_ROUTER_ADDRESSES: Readonly<Record<number, IAddress>>;
+/**
+ * Vault addresses registered on a `SwapRouter` via `enableVault`. The
+ * presence of a vault here is the signal to route its deposits through the
+ * SwapRouter rather than the legacy adapter path.
+ *
+ * Entries mirror the on-chain `vaultInfo[addr].referenceAsset != 0` state of
+ * the `SwapRouter` deployment. Verify against the deployed contract before
+ * adding a new entry — a vault that is not registered on-chain will revert
+ * with `InvalidVault` at deposit time.
+ *
+ * Lowercase comparison is required when checking — use
+ * {@link vaultUsesSwapRouter} rather than reading this set directly.
+ */
 export declare const VAULTS_USING_SWAP_ROUTER: ReadonlySet<string>;
+/**
+ * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
+ * Drives origin/referral-fee accrual. The on-chain admin must register a
+ * code before it can be used — calls with an unknown code revert with
+ * `InvalidOrigin`.
+ *
+ * `default` is the all-zero sentinel — the SwapRouter treats it as "no
+ * origin fee" and skips the origin-fee transfer.
+ */
 export declare const ORIGIN_CODES: {
+    /** All-zero sentinel — no origin fee. */
     readonly default: `0x${string}`;
 };
+/**
+ * Maximum number of swap legs the contract accepts in a single
+ * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading
+ * the on-chain value at call time would add an RPC for no gain.
+ *
+ * Kept here so the SDK can reject oversize inputs at the boundary rather
+ * than wait for the on-chain `TooManySwaps` revert.
+ */
 export declare const SWAP_ROUTER_MAX_SWAPS = 9;
+/**
+ * Wrapped-native ERC-20 per chain that has a SwapRouter deployment. Mirrors
+ * the on-chain `wrappedNativeTokenAddress()` view to avoid an extra RPC on
+ * every dispatch. Used to validate that native-token deposits target a
+ * vault whose reference asset is the wrapped native — the only configuration
+ * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ */
 export declare const SWAP_ROUTER_WRAPPED_NATIVE: Readonly<Record<number, IAddress>>;