@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/evm/methods/crossChainVaultRegistry.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * Cross-Chain Vault Registry
+ *
+ * Address-keyed registry of August's LayerZero OVault deployments plus the
+ * resolver helpers that turn a vault address into the
+ * {@link ICrossChainVaultConfig} consumed by `buildCrossChainVaultTx`,
+ * `crossChainVaultDeposit`, and `quoteCrossChainDeposit`.
+ *
+ * This is the cross-chain analogue of the SwapRouter registry
+ * (`VAULTS_USING_SWAP_ROUTER` / `getSwapRouterAddress`): consumers resolve a
+ * full config by vault address instead of hand-assembling the per-chain
+ * contract maps and LayerZero EIDs. Without it, every consuming app would
+ * re-encode the same address book.
+ *
+ * Addresses are ported verbatim from upshift-app `src/config/ovault.ts` and
+ * cross-checked against the read-side `LAYERZERO_VAULTS` registry in
+ * `services/layerzero/deposits.ts`. Verify against the deployed contracts
+ * before adding or editing an entry — a wrong address silently routes funds
+ * to the wrong chain.
+ *
+ * Return convention (deliberate, mirrors the SwapRouter helpers): lookups that
+ * resolve a single optional value (`getCrossChainVaultConfig`,
+ * `getOVaultChains`) return `undefined` for an unregistered vault, while
+ * list-returning helpers (`getWithdrawDestinationChains`) return `[]` so
+ * callers can iterate without a null-check.
+ *
+ * @module evm/methods/crossChainVaultRegistry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CROSS_CHAIN_VAULT_CONFIGS = void 0;
+exports.getCrossChainVaultConfig = getCrossChainVaultConfig;
+exports.isCrossChainVault = isCrossChainVault;
+exports.getOVaultChains = getOVaultChains;
+exports.isHubOnlyReceipt = isHubOnlyReceipt;
+exports.getWithdrawDestinationChains = getWithdrawDestinationChains;
+const crossChainVault_1 = require("./crossChainVault");
+// EVM chain IDs for the chains carrying OVault deployments. Plain literals
+// (not `viem/chains`) keep viem an optional peer dependency — importing viem
+// at module load would break SDK consumers that do not install it.
+const ETHEREUM = 1;
+const ARBITRUM = 42161;
+const AVALANCHE = 43114;
+const BASE = 8453;
+const SONIC = 146;
+const MONAD = 143;
+const CONFIGS = [
+    {
+        vaultName: 'Upshift Core USDC',
+        vaultSymbol: 'coreUSDC',
+        hubChainId: ETHEREUM,
+        vaultAddress: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32',
+        spokeChainIds: [ARBITRUM, AVALANCHE, BASE, SONIC],
+        contracts: {
+            assetToken: {
+                [ETHEREUM]: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+                [ARBITRUM]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+                [AVALANCHE]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+                [BASE]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+                [SONIC]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+            },
+            assetOFT: {
+                [ETHEREUM]: '0xc026395860Db2d07ee33e05fE50ed7bD583189C7',
+                [ARBITRUM]: '0xe8CDF27AcD73a434D661C84887215F7598e7d0d3',
+                [AVALANCHE]: '0x5634c4a5FEd09819E3c46D86A965Dd9447d86e47',
+                [BASE]: '0x27a16dc786820B16E5c9028b75B99F6f604b5d26',
+                [SONIC]: '0xA272fFe20cFfe769CdFc4b63088DCD2C82a2D8F9',
+            },
+            shareOFTAdapter: '0x4a21dcba38c3816c78144f33bb42d8fa17f38067',
+            composerSync: '0xc2637d7721791cc9cb196628d1e5e06887b1d4b9',
+            shareOFT: {
+                [ARBITRUM]: '0x50a31ff4d57841681011837c17aa201c6a34203c',
+                [AVALANCHE]: '0x1FA931Bf85248aD2eDf0004DD9A284698358e708',
+                [BASE]: '0x1fa931bf85248ad2edf0004dd9a284698358e708',
+                [SONIC]: '0x4bdd224fe59a3ae0b249125ad4c5b3126074c71b',
+            },
+        },
+        layerZeroEids: {
+            hub: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.ETHEREUM,
+            spokes: {
+                [ARBITRUM]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.ARBITRUM,
+                [AVALANCHE]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.AVALANCHE,
+                [BASE]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.BASE,
+                [SONIC]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.SONIC,
+            },
+        },
+        hubOnlyReceipt: true,
+    },
+    {
+        vaultName: 'Upshift USDC',
+        vaultSymbol: 'upUSDC',
+        hubChainId: ETHEREUM,
+        vaultAddress: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
+        spokeChainIds: [ARBITRUM, AVALANCHE, BASE, SONIC],
+        contracts: {
+            assetToken: {
+                [ETHEREUM]: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+                [ARBITRUM]: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+                [AVALANCHE]: '0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E',
+                [BASE]: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+                [SONIC]: '0x29219dd400f2Bf60E5a23d13Be72B486D4038894',
+            },
+            assetOFT: {
+                [ETHEREUM]: '0xc026395860Db2d07ee33e05fE50ed7bD583189C7',
+                [ARBITRUM]: '0xe8CDF27AcD73a434D661C84887215F7598e7d0d3',
+                [AVALANCHE]: '0x5634c4a5FEd09819E3c46D86A965Dd9447d86e47',
+                [BASE]: '0x27a16dc786820B16E5c9028b75B99F6f604b5d26',
+                [SONIC]: '0xA272fFe20cFfe769CdFc4b63088DCD2C82a2D8F9',
+            },
+            shareOFTAdapter: '0x81971a3c359cfe74259cff1b46fb5f2112ddde34',
+            composerSync: '0xbe82134b95a8e9370e6759f3c8f44087cd9a52be',
+            shareOFT: {
+                [ARBITRUM]: '0x81971a3c359cfe74259cff1b46fb5f2112ddde34',
+                [AVALANCHE]: '0x81971A3C359cFE74259CfF1b46FB5f2112ddDE34',
+                [BASE]: '0x81971a3c359cfe74259cff1b46fb5f2112ddde34',
+                [SONIC]: '0x81971a3c359cfe74259cff1b46fb5f2112ddde34',
+            },
+        },
+        layerZeroEids: {
+            hub: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.ETHEREUM,
+            spokes: {
+                [ARBITRUM]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.ARBITRUM,
+                [AVALANCHE]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.AVALANCHE,
+                [BASE]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.BASE,
+                [SONIC]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.SONIC,
+            },
+        },
+        hubOnlyReceipt: true,
+    },
+    {
+        vaultName: 'earnAUSD',
+        vaultSymbol: 'earnAUSD',
+        hubChainId: MONAD,
+        vaultAddress: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA',
+        spokeChainIds: [ETHEREUM],
+        contracts: {
+            assetToken: {
+                [MONAD]: '0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a',
+                [ETHEREUM]: '0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a',
+            },
+            assetOFT: {
+                [MONAD]: '0x9CaB7Ede13dc56652E44D2404E969C212f22689b',
+                [ETHEREUM]: '0x9CaB7Ede13dc56652E44D2404E969C212f22689b',
+            },
+            shareOFTAdapter: '0x9549Fa3DF579Cca9F3e328695382675F7f1f0F34',
+            composerSync: '0xd1B1b12533E12BADB8ea6D63AeDd11922cAE5580',
+            shareOFT: {
+                [ETHEREUM]: '0xa6916b65c5e3fEdf46c0a2F59bff776e872C8992',
+            },
+        },
+        layerZeroEids: {
+            hub: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.MONAD,
+            spokes: {
+                [ETHEREUM]: crossChainVault_1.LAYERZERO_ENDPOINT_IDS.ETHEREUM,
+            },
+        },
+        multiAsset: {
+            hubAssetAddress: '0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a',
+        },
+    },
+];
+/**
+ * August's LayerZero OVault deployments, keyed by lowercase hub-chain vault
+ * address. Resolve entries with {@link getCrossChainVaultConfig} rather than
+ * indexing directly — the helper handles address-casing for you.
+ *
+ * @see {@link getCrossChainVaultConfig} for the typed, case-insensitive lookup.
+ */
+exports.CROSS_CHAIN_VAULT_CONFIGS = Object.freeze(Object.fromEntries(CONFIGS.map((config) => [config.vaultAddress.toLowerCase(), config])));
+/**
+ * Resolve the full cross-chain config for a vault. Address comparison is
+ * case-insensitive.
+ *
+ * @param vault - Hub-chain vault contract address.
+ * @returns The {@link ICrossChainVaultConfig} to pass to
+ *   `crossChainVaultDeposit` / `quoteCrossChainDeposit`, or `undefined` when
+ *   the vault is not a registered OVault deployment.
+ * @example
+ * ```ts
+ * const config = getCrossChainVaultConfig('0xE9B725010A9E419412ed67d0fA5f3A5f40159D32');
+ * if (config) await quoteCrossChainDeposit({ config, ...rest });
+ * ```
+ */
+function getCrossChainVaultConfig(vault) {
+    return exports.CROSS_CHAIN_VAULT_CONFIGS[vault.toLowerCase()];
+}
+/**
+ * Whether a vault is a registered LayerZero OVault and should route deposits
+ * through the cross-chain flow. Address comparison is case-insensitive.
+ *
+ * @param vault - Vault contract address.
+ * @returns `true` when the vault has an entry in
+ *   {@link CROSS_CHAIN_VAULT_CONFIGS}.
+ */
+function isCrossChainVault(vault) {
+    return getCrossChainVaultConfig(vault) !== undefined;
+}
+/**
+ * Get the hub and spoke chain IDs a vault is deployed across — the set of
+ * chains a user can deposit from.
+ *
+ * @param vault - Vault contract address.
+ * @returns `{ hub, spokes }` chain IDs, or `undefined` when the vault is not a
+ *   registered OVault deployment.
+ */
+function getOVaultChains(vault) {
+    const config = getCrossChainVaultConfig(vault);
+    if (!config)
+        return undefined;
+    return { hub: config.hubChainId, spokes: config.spokeChainIds };
+}
+/**
+ * Whether a vault's receipt token is hub-only (no cross-chain withdraw).
+ * The deposit UI must not offer a spoke share destination for these vaults.
+ *
+ * @param vault - Vault contract address.
+ * @returns `true` for vaults whose shares cannot leave the hub chain
+ *   (AUGUST-6300).
+ */
+function isHubOnlyReceipt(vault) {
+    return getCrossChainVaultConfig(vault)?.hubOnlyReceipt === true;
+}
+/**
+ * Chains a user can receive the underlying asset on when withdrawing.
+ * Hub-only-receipt vaults redeem to the hub chain only (AUGUST-6300); all
+ * other OVault vaults can redeem to the hub or any spoke.
+ *
+ * @param vault - Vault contract address.
+ * @returns Destination chain IDs, or an empty array when the vault is not a
+ *   registered OVault deployment.
+ */
+function getWithdrawDestinationChains(vault) {
+    const config = getCrossChainVaultConfig(vault);
+    if (!config)
+        return [];
+    if (isHubOnlyReceipt(vault))
+        return [config.hubChainId];
+    return [config.hubChainId, ...config.spokeChainIds];
+}
+//# sourceMappingURL=crossChainVaultRegistry.js.map

package/lib/evm/methods/index.d.ts

@@ -1 +1,2 @@
 export * from './crossChainVault';
+export * from './crossChainVaultRegistry';

package/lib/evm/methods/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./crossChainVault"), exports);
+__exportStar(require("./crossChainVaultRegistry"), exports);
 //# sourceMappingURL=index.js.map

package/lib/evm/types/crossChain.d.ts

@@ -1,4 +1,31 @@
+/**
+ * Cross-Chain Vault Type Definitions
+ *
+ * Defines all request/response interfaces for LayerZero OVault cross-chain
+ * vault operations. These types are generic and not tied to any specific
+ * vault configuration — SDK consumers provide their own config.
+ *
+ * @module evm/types/crossChain
+ */
 import type { IAddress } from '../../types';
+/**
+ * Injected dependency for the `@layerzerolabs/ovault-evm` SDK.
+ *
+ * Because the `@layerzerolabs/ovault-evm` package has broken ESM exports
+ * (bare directory imports in a `"type": "module"` package), the SDK cannot
+ * `require()` it internally. Instead, the consuming application imports it
+ * in its own bundler context and passes it to SDK functions via this type.
+ *
+ * @example
+ * ```ts
+ * import { OVaultSyncMessageBuilder, OVaultSyncOperations } from '@layerzerolabs/ovault-evm';
+ *
+ * await buildCrossChainVaultTx({
+ *   ovaultSdk: { OVaultSyncMessageBuilder, OVaultSyncOperations },
+ *   // ...other params
+ * });
+ * ```
+ */
 export interface IOVaultSdkDependency {
     OVaultSyncMessageBuilder: {
         generateOVaultInputs: (input: unknown) => Promise<unknown>;
@@ -9,58 +36,131 @@ export interface IOVaultSdkDependency {
         REDEEM: string;
     };
 }
+/**
+ * Cross-chain vault configuration provided by SDK consumers.
+ *
+ * Each vault deployment requires 5 contract types:
+ * 1. AssetOFT — OFT wrapper for the underlying asset (e.g., USDC) on hub + spoke chains
+ * 2. ERC4626 Vault — The actual vault contract on the hub chain
+ * 3. ShareOFTAdapter — Wraps vault shares for cross-chain transport (hub chain)
+ * 4. ComposerSync — Orchestrates cross-chain operations (hub chain)
+ * 5. ShareOFT — Share token representation on spoke chains
+ */
 export interface ICrossChainVaultConfig {
+    /** Human-readable vault name */
     vaultName: string;
+    /** Vault receipt token symbol */
     vaultSymbol: string;
+    /** Chain ID where the ERC4626 vault lives */
     hubChainId: number;
+    /** Address of the ERC4626 vault on the hub chain */
     vaultAddress: IAddress;
+    /** Chain IDs where users can deposit from (spoke chains) */
     spokeChainIds: number[];
+    /** Contract addresses for the OVault deployment */
     contracts: {
+        /** Underlying asset token addresses per chain (e.g., native USDC) */
         assetToken: Record<number, IAddress>;
+        /** AssetOFT (OFT wrapper for the asset) addresses per chain */
         assetOFT: Record<number, IAddress>;
+        /** ShareOFTAdapter address on the hub chain */
         shareOFTAdapter: IAddress;
+        /** VaultComposerSync address on the hub chain */
         composerSync: IAddress;
+        /** ShareOFT addresses on spoke chains */
         shareOFT: Record<number, IAddress>;
     };
+    /** LayerZero Endpoint IDs (NOT chain IDs) */
     layerZeroEids: {
+        /** Hub chain LayerZero EID */
         hub: number;
+        /** Spoke chain LayerZero EIDs keyed by chain ID */
         spokes: Record<number, number>;
     };
+    /**
+     * Multi-asset vault support.
+     * When set, the vault uses `previewDeposit(address, uint256)` instead of
+     * the standard ERC4626 `previewDeposit(uint256)`.
+     */
     multiAsset?: {
+        /** Asset address on hub chain used for previewDeposit calls */
         hubAssetAddress: IAddress;
     };
+    /**
+     * When `true`, the vault's receipt token cannot leave the hub chain: there
+     * is no OFT/bridge for it, so minting shares on a spoke would strand the
+     * user (AUGUST-6300). Withdraw UIs must offer the hub chain only. Defaults
+     * to `false` when omitted. Drives `getWithdrawDestinationChains`.
+     */
+    hubOnlyReceipt?: boolean;
 }
+/** Operation type for cross-chain vault transactions */
 export type CrossChainOperation = 'DEPOSIT' | 'REDEEM';
+/**
+ * Parameters for building a cross-chain vault transaction.
+ * Used internally by `buildCrossChainVaultTx`.
+ */
 export interface ICrossChainBuildRequest {
+    /** Injected `@layerzerolabs/ovault-evm` SDK dependency */
     ovaultSdk: IOVaultSdkDependency;
+    /** Cross-chain vault configuration */
     config: ICrossChainVaultConfig;
+    /** Operation to perform */
     operation: CrossChainOperation;
+    /** Amount to deposit/redeem (human-readable string, raw bigint, or number) */
     amount: string | number | bigint;
+    /** Decimals of the token being deposited/redeemed */
     decimals: number;
+    /** Chain ID the user is currently on */
     userChainId: number;
+    /** User's wallet address */
     walletAddress: IAddress;
+    /** Chain to receive shares (deposit) or assets (redeem). Defaults to user's chain */
     destinationChainId?: number;
+    /** Recipient address. Defaults to walletAddress */
     recipientAddress?: IAddress;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
     slippageBps?: number;
+    /**
+     * viem Chain object for the hub chain (with RPC URLs configured).
+     * Required for SDK to create a public client for on-chain reads.
+     */
     hubChain: unknown;
+    /**
+     * viem Chain object for the user's source chain (with RPC URLs configured).
+     */
     sourceChain: unknown;
+    /** Fee buffer percentage applied to LZ native fees (default: 50) */
     feeBufferPercent?: number;
+    /** Gas limit for lzCompose on hub chain (default: 2_000_000n) */
     hubLzComposeGasLimit?: bigint;
 }
+/**
+ * Result from building a cross-chain vault transaction.
+ */
 export interface ICrossChainBuildResult {
     success: boolean;
     data?: {
+        /** Contract address to call */
         contractAddress: IAddress;
+        /** Function name to call on the contract */
         contractFunctionName: string;
+        /** ABI for the contract call */
         abi: readonly unknown[];
+        /** Arguments for the contract function */
         txArgs: readonly unknown[];
+        /** Native value to send with the transaction (includes LZ fees) */
         messageValue: bigint;
+        /** LayerZero messaging fee breakdown */
         messageFee: {
             nativeFee: bigint;
             lzTokenFee: bigint;
         };
+        /** Expected output amount on destination */
         dstAmount: bigint;
+        /** Minimum output amount (after slippage) */
         minDstAmount: bigint;
+        /** Approval info if token approval is required */
         approval?: {
             tokenAddress: IAddress;
             spender: IAddress;
@@ -69,93 +169,195 @@ export interface ICrossChainBuildResult {
     };
     error?: string;
 }
+/**
+ * Request parameters for executing a cross-chain deposit.
+ */
 export interface ICrossChainDepositRequest {
+    /** Injected `@layerzerolabs/ovault-evm` SDK dependency */
     ovaultSdk: IOVaultSdkDependency;
+    /** Cross-chain vault configuration */
     config: ICrossChainVaultConfig;
+    /** Amount to deposit (human-readable) */
     amount: string;
+    /** Decimals of the deposit token */
     decimals: number;
+    /** Chain ID the user is depositing from */
     userChainId: number;
+    /** User's wallet address */
     walletAddress: IAddress;
+    /** viem WalletClient for signing transactions */
     walletClient: unknown;
+    /** viem PublicClient for reading chain state */
     publicClient: unknown;
+    /** viem Chain object for the hub chain (with RPC URLs) */
     hubChain: unknown;
+    /** viem Chain object for the source chain (with RPC URLs) */
     sourceChain: unknown;
+    /** Chain to receive shares on. Defaults to user's chain */
     destinationChainId?: number;
+    /** Skip the internal approval check (set true when caller handles approval) */
     skipApprovalCheck?: boolean;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
     slippageBps?: number;
+    /** Fee buffer percentage (default: 50) */
     feeBufferPercent?: number;
+    /** Gas buffer multiplier as percentage (default: 150 = 1.5x) */
     gasBufferPercent?: number;
 }
+/**
+ * Result from a cross-chain deposit execution.
+ */
 export interface ICrossChainDepositResult {
+    /** Transaction hash */
     transactionHash: string;
+    /** Whether the on-chain receipt shows success */
     success: boolean;
 }
+/**
+ * Request parameters for executing a cross-chain redemption.
+ */
 export interface ICrossChainRedeemRequest {
+    /** Injected `@layerzerolabs/ovault-evm` SDK dependency */
     ovaultSdk: IOVaultSdkDependency;
+    /** Cross-chain vault configuration */
     config: ICrossChainVaultConfig;
+    /** Amount of shares to redeem (human-readable) */
     amount: string;
+    /** Decimals of the share token */
     decimals: number;
+    /** Chain ID the user is on (must be hub chain) */
     userChainId: number;
+    /** User's wallet address */
     walletAddress: IAddress;
+    /** viem WalletClient for signing transactions */
     walletClient: unknown;
+    /** viem PublicClient for reading chain state */
     publicClient: unknown;
+    /** viem Chain object for the hub chain (with RPC URLs) */
     hubChain: unknown;
+    /** viem Chain object for the source chain (with RPC URLs) */
     sourceChain: unknown;
+    /** Chain to receive assets on. Defaults to user's chain */
     destinationChainId?: number;
+    /** Skip the internal approval check (set true when caller handles approval) */
     skipApprovalCheck?: boolean;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
     slippageBps?: number;
+    /** Fee buffer percentage (default: 50) */
     feeBufferPercent?: number;
+    /** Gas buffer multiplier as percentage (default: 200 = 2x) */
     gasBufferPercent?: number;
+    /** Minimum gas limit for redeem operations (default: 5_000_000n) */
     minGasLimit?: bigint;
 }
+/**
+ * Result from a cross-chain redeem execution.
+ */
 export interface ICrossChainRedeemResult {
+    /** Transaction hash */
     transactionHash: string;
+    /** Whether the on-chain receipt shows success */
     success: boolean;
 }
+/**
+ * Request parameters for quoting a cross-chain deposit.
+ */
 export interface IQuoteCrossChainDepositRequest {
+    /** Injected `@layerzerolabs/ovault-evm` SDK dependency */
     ovaultSdk: IOVaultSdkDependency;
+    /** Cross-chain vault configuration */
     config: ICrossChainVaultConfig;
+    /** Amount to deposit (human-readable) */
     amount: string;
+    /** Decimals of the deposit token */
     decimals: number;
+    /** Chain ID the user would deposit from */
     userChainId: number;
+    /** User's wallet address */
     walletAddress: IAddress;
+    /** viem Chain object for the hub chain (with RPC URLs) */
     hubChain: unknown;
+    /** viem Chain object for the source chain (with RPC URLs) */
     sourceChain: unknown;
+    /** Destination chain for shares */
     destinationChainId?: number;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
     slippageBps?: number;
+    /** Fee buffer percentage (default: 50) */
     feeBufferPercent?: number;
 }
+/**
+ * Request parameters for quoting a cross-chain redeem.
+ */
 export interface IQuoteCrossChainRedeemRequest {
+    /** Injected `@layerzerolabs/ovault-evm` SDK dependency */
     ovaultSdk: IOVaultSdkDependency;
+    /** Cross-chain vault configuration */
     config: ICrossChainVaultConfig;
+    /** Amount of shares to redeem (human-readable) */
     amount: string;
+    /** Decimals of the share token */
     decimals: number;
+    /** User's wallet address */
     walletAddress: IAddress;
+    /** viem Chain object for the hub chain (with RPC URLs) */
     hubChain: unknown;
+    /** viem Chain object for the source chain (with RPC URLs) */
     sourceChain: unknown;
+    /** Destination chain for assets */
     destinationChainId?: number;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
     slippageBps?: number;
+    /** Fee buffer percentage (default: 50) */
     feeBufferPercent?: number;
 }
+/**
+ * Result from a cross-chain fee/output quote.
+ */
 export interface IQuoteCrossChainResult {
+    /** Native fee in wei (includes buffer) */
     nativeFee: bigint;
+    /** Expected output amount on destination */
     dstAmount: bigint;
+    /** Minimum output amount (after slippage) */
     minDstAmount: bigint;
+    /** Unix epoch (ms) when this quote was generated. */
     quotedAt: number;
+    /** Unix epoch (ms) after which this quote is stale. */
     expiresAt: number;
 }
+/** Default validity window for a cross-chain quote (30s). */
 export declare const CROSS_CHAIN_QUOTE_TTL_MS = 30000;
+/** Returns `true` when the quote should be refreshed before submitting. */
 export declare function isQuoteStale(quote: Pick<IQuoteCrossChainResult, 'expiresAt'>, now?: number): boolean;
+/**
+ * Cross-chain operation status for tracking LayerZero messages.
+ */
 export interface ICrossChainOperationStatus {
+    /** Source chain transaction hash */
     srcTxHash: string;
+    /** Current status of the cross-chain message */
     status: 'PENDING' | 'INFLIGHT' | 'DELIVERED' | 'FAILED';
+    /** Source chain ID */
     srcChainId: number;
+    /** Destination chain ID */
     dstChainId: number;
 }
+/**
+ * Refund status for failed cross-chain operations.
+ * LayerZero may refund assets if delivery fails.
+ */
 export interface IRefundStatus {
+    /** Whether a refund has been initiated */
     refunded: boolean;
+    /** Refund transaction hash (if available) */
     refundTxHash?: string;
+    /** Amount refunded in the source token's smallest unit */
     refundAmount?: bigint;
+    /** Chain ID where the refund was issued */
     refundChainId?: number;
 }
+/**
+ * Error classification for cross-chain operations.
+ */
 export type CrossChainErrorType = 'max-deposit' | 'nonce' | 'no-peer' | 'bridge-fee' | 'insufficient-balance' | 'user-rejected' | 'gas' | 'network' | 'unknown';

package/lib/evm/types/crossChain.js

@@ -1,8 +1,19 @@
 "use strict";
+/**
+ * Cross-Chain Vault Type Definitions
+ *
+ * Defines all request/response interfaces for LayerZero OVault cross-chain
+ * vault operations. These types are generic and not tied to any specific
+ * vault configuration — SDK consumers provide their own config.
+ *
+ * @module evm/types/crossChain
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CROSS_CHAIN_QUOTE_TTL_MS = void 0;
 exports.isQuoteStale = isQuoteStale;
+/** Default validity window for a cross-chain quote (30s). */
 exports.CROSS_CHAIN_QUOTE_TTL_MS = 30000;
+/** Returns `true` when the quote should be refreshed before submitting. */
 function isQuoteStale(quote, now = Date.now()) {
     return now >= quote.expiresAt;
 }

package/lib/index.d.ts

@@ -1,4 +1,7 @@
 import './polyfills';
+/**
+ * Export other packages
+ */
 export * from './types';
 export * from './core';
 export * from './abis';
@@ -6,9 +9,22 @@ export * from './services/debank';
 export * from './services/swap-quotes';
 export * from './modules/vaults';
 export * from './modules/sub-accounts';
+export * from './modules/api';
+/**
+ * EVM cross-chain (LayerZero OVault) exports
+ */
 export * from './evm';
+/**
+ * Solana export
+ */
 export * from './adapters/solana';
+/**
+ * Stellar export
+ */
 export * from './adapters/stellar';
 export declare const VAULT_ADDRESSES: Record<"musd" | "predlp" | "sentusd" | "pregrid" | "repouscc" | "earnxrp" | "tivkbtc" | "tivusdt0" | "supermon" | "earnmon" | "k3europ" | "wmon/ausd" | "wbtc/ausd" | "earnausd_monad" | "sausd" | "farmbold" | "sentuscc" | "sentbtc" | "svusdc" | "apusdc" | "testwethtsa" | "tacusr" | "upinjusdt" | "tac-teth" | "upausd" | "taccbbtc" | "xupusdc" | "uptbtc" | "gteth" | "ageth" | "upusdc" | "hgeth" | "upssylva" | "hbbtc" | "hbhype" | "upazt" | "susdt" | "upedge" | "coreusdc" | "upcusdo" | "shifteth" | "upsusde" | "uplbtc" | "upavax" | "tacrseth" | "earnausd" | "alpineusdcflagship" | "alpinecoinshiftusdc" | "upbtc" | "upstrbtc" | "maxiusr" | "upgammausdc" | "xhype" | "wildusd" | "alpinebtc" | "prenusd" | "upyzusd" | "upnusd" | "hlpe" | "nemo eth yield", `0x${string}`>;
+/**
+ * Export the SDK class as default
+ */
 import { AugustSDK } from './main';
 export default AugustSDK;