@augustdigital/sdk 8.3.2 → 8.6.0

package/README.md

@@ -1,6 +1,6 @@
 # August Digital SDK
 
-TypeScript SDK for interacting with August Digital vaults across EVM and Solana chains.
+TypeScript SDK for interacting with August Digital vaults across EVM, Solana, Stellar, and Sui chains.
 
 ## Installation
 
@@ -20,17 +20,15 @@ The SDK supports both ethers and wagmi/viem signers. If you're using wagmi in yo
 npm install viem
 ```
 
-The SDK will automatically detect and convert viem WalletClient to ethers-compatible signers.
+The SDK automatically converts viem `WalletClient` to an ethers-compatible signer.
 
 ## Quick Start
 
 ```typescript
-import { AugustSDK } from '@augustdigital/sdk';
+import AugustSDK from '@augustdigital/sdk';
 
-// Initialize with RPC providers
 const sdk = new AugustSDK({
-  // Required: a stable kebab-case slug identifying your application.
-  // See "App Name" below for what this is used for.
+  // Required: stable kebab-case slug identifying your application.
   appName: 'acme-trader',
   providers: {
     1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
@@ -38,7 +36,7 @@ const sdk = new AugustSDK({
     -1: 'https://api.mainnet-beta.solana.com', // Solana
   },
   keys: {
-    august: 'YOUR_API_KEY', // Optional: required for allocations, health factors, and subaccount operations
+    august: 'YOUR_API_KEY', // Optional: required for allocations, health factors, and sub-account operations
   },
   monitoring: {
     env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')
@@ -48,10 +46,10 @@ const sdk = new AugustSDK({
 // Fetch all vaults
 const vaults = await sdk.getVaults();
 
-// Fetch specific vault with loans and allocations
+// Fetch a specific vault with loans and allocations
 const vault = await sdk.getVault({
   vault: '0x...',
-  options: { loans: true, allocations: true }
+  options: { loans: true, allocations: true },
 });
 
 // Get user positions
@@ -63,57 +61,25 @@ const positions = await sdk.getVaultPositions({
 
 ### App Name
 
-`appName` is required on every `AugustSDK` constructor call. Pass a
-stable kebab-case slug identifying your application (e.g.
-`'acme-trader'`, `'my-defi-app'`):
-
-- **What it's used for.** August Digital tags outbound analytics events
-  with `app.name = <yourSlug>`. We use this to (a) reach out about
-  breaking changes that will affect you, (b) attribute error spikes to
-  the right consuming app, and (c) prioritize bug fixes by impact.
-- **What it is _not_.** It's not a secret, not a license key, not an
-  auth token, and despite the friendly name it's **not a display
-  label**. It's a self-issued identifier — pick a slug once and reuse
-  it across deployments.
-- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. Use a slug
-  like `'acme-trader'`, **not** a display name like `'Acme Trader'`
-  (spaces and special characters will throw). The SDK throws
-  synchronously from the constructor if the value is missing or
-  invalid, so a wrong value fails loudly at integration time rather
-  than silently in production.
+`appName` is required on every `AugustSDK` constructor call. Pass a stable kebab-case slug
+identifying your application (e.g. `'acme-trader'`, `'my-defi-app'`):
+
+- **What it's used for.** August Digital tags analytics events with `app.name = <yourSlug>` to
+  attribute error spikes and prioritize bug fixes by consuming app.
+- **What it is not.** Not a secret, not a license key, not a display label. Pick a slug once
+  and reuse it across deployments.
+- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. The SDK throws synchronously from
+  the constructor if the value is missing or invalid.
 
 ```typescript
 // Will throw — appName is required.
-new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-} as any);
+new AugustSDK({ providers: { /* ... */ } } as any);
 
-// Will throw — display name, not a slug. Use 'acme-trader' instead.
-new AugustSDK({
-  appName: 'Acme Trader',
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-});
+// Will throw — spaces not allowed. Use 'acme-trader'.
+new AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });
 
 // Correct.
-new AugustSDK({
-  appName: 'acme-trader',
-  providers: {
-    /* ... */
-  },
-  keys: {
-    /* ... */
-  },
-});
+new AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });
 ```
 
 ## Architecture
@@ -126,13 +92,15 @@ src.ts/
 │   ├── fetcher.ts       # API client with retry logic
 │   └── web3.helpers.ts  # Blockchain utilities
 ├── adapters/            # Chain-specific implementations
-│   ├── evm/             # EVM vault adapters (v1, v2)
-│   └── solana/          # Solana program adapters
+│   ├── evm/             # EVM adapter (approve, deposit, redeem, read helpers)
+│   ├── solana/          # Solana program adapters
+│   ├── stellar/         # Stellar vault adapters
+│   └── sui/             # Sui (Ember) vault adapters
+├── evm/                 # EVM cross-chain (LayerZero OVault)
 ├── modules/             # Feature modules
-│   └── vaults/          # Vault operations
-│       ├── main.ts      # AugustVaults class
-│       ├── getters.ts   # Data fetching functions
-│       └── utils.ts     # Helper utilities
+│   ├── vaults/          # Vault read operations
+│   ├── sub-accounts/    # Sub-account queries
+│   └── api/             # August backend API integration
 ├── services/            # External service integrations
 │   ├── debank/          # DeFi allocation data
 │   ├── coingecko/       # Token pricing
@@ -144,8 +112,10 @@ src.ts/
 
 ### Multi-Chain Support
 
-- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche
-- **Solana**: Native Solana program support
+- **EVM Chains**: Ethereum, Arbitrum, Base, BSC, Avalanche, and more — `wagmi/viem` and `ethers` signers supported
+- **Solana**: Native Solana program support with full vault functionality
+- **Stellar**: Stellar vault deposit, redeem, and position queries
+- **Sui**: Ember vault read operations
 - Unified interface across all chains
 
 ### Vault Versions
@@ -153,6 +123,7 @@ src.ts/
 - `evm-0/evm-1`: Legacy vault contracts
 - `evm-2`: Current EVM vault architecture (separate receipt tokens)
 - `sol-0`: Solana program-based vaults
+- `stellar-0`: Stellar-based vaults
 
 ### Data Enrichment
 
@@ -162,6 +133,154 @@ All vault queries support optional enrichment:
 - `allocations`: DeFi/CeFi/OTC position breakdowns
 - `wallet`: User-specific position data
 
+## API Reference
+
+### Vault Queries
+
+| Method | Description |
+| --- | --- |
+| `getVaults(options?)` | Fetch all vaults across chains |
+| `getVault({ vault, chainId?, options? })` | Get single vault details |
+| `getVaultLoans({ vault, chainId? })` | Fetch active loans |
+| `getVaultAllocations({ vault, chainId? })` | Get allocation breakdown |
+| `getVaultHistoricalTimeseries({ vault, chainId? })` | Historical APY and TVL timeseries |
+| `getVaultApy({ vault, historical? })` | **@deprecated** — use `getVaultHistoricalTimeseries` |
+| `getVaultTvl({ vault, historical? })` | Current/historical TVL |
+| `getVaultAnnualizedApy({ vault })` | Annualized APY for a vault |
+| `getVaultSummary({ vault })` | Aggregated vault summary |
+| `getVaultPnl({ vault, chainId? })` | Vault-level PnL |
+| `getVaultUnrealizedPnlHistory({ vault, chainId?, ... })` | Unrealized PnL timeseries |
+| `getLatestUnrealizedPnl()` | Latest unrealized PnL snapshot across all vaults |
+| `getYieldLastRealizedOn({ vault, chainId? })` | Timestamp of last yield realization |
+| `getTotalDeposited(options?)` | Total deposited across vaults |
+
+### User Positions
+
+| Method | Description |
+| --- | --- |
+| `getVaultPositions({ wallet?, vault?, chainId? })` | User vault positions |
+| `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose? })` | Claimable redemptions |
+| `getVaultRedemptionHistory({ vault, wallet?, chainId? })` | Historical redemptions |
+| `getVaultUserHistory({ wallet, vault?, chainId? })` | Transaction history |
+| `getVaultUserTransfers({ wallet, vault?, chainId? })` | Transfer history |
+| `getVaultUserLifetimePnl({ wallet, vault?, chainId? })` | Lifetime PnL for a wallet |
+| `getVaultStakingPositions({ wallet, chainId })` | Staking positions |
+| `getVaultBorrowerHealthFactor(props?)` | Borrower health factor |
+| `getVaultWithdrawals({ vault, chainId? })` | Pending withdrawals |
+
+### Points
+
+| Method | Description |
+| --- | --- |
+| `getUserPoints(userAddress)` | Points balance for a wallet |
+| `registerUserForPoints({ wallet, referral? })` | Register a wallet for the points program |
+| `fetchPointsLeaderboard(params?)` | Points leaderboard |
+
+### Write Operations (top-level)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(signer, options)` | Deposit into a vault |
+| `previewRedemption(props)` | Preview redemption output before broadcasting |
+
+### Cross-Chain (LayerZero)
+
+| Method | Description |
+| --- | --- |
+| `getLayerZeroDeposits({ wallet?, chainId? })` | LayerZero deposit history |
+| `getLayerZeroRedeems(props?)` | LayerZero redemption history |
+
+### Utilities
+
+| Method | Description |
+| --- | --- |
+| `getPrice(symbol)` | Token price in USD |
+| `switchNetwork(chainId)` | Change active chain |
+| `updateWallet(address)` | Set active wallet for tracking |
+
+### Sub-Accounts (`sdk.subAccountsModule`)
+
+| Method | Description |
+| --- | --- |
+| `getSubaccountHealthFactor(address)` | Health factor for a sub-account |
+| `getSubaccountLoans(address)` | Active loans for a sub-account |
+| `getSubaccountCefiPositions(address)` | CeFi positions |
+| `getSubaccountOtcPositions(address)` | OTC positions |
+| `getSubaccountSummary(address)` | Aggregated sub-account summary |
+
+### EVM Adapter (`sdk.evm`)
+
+Set a signer before calling write methods:
+
+```typescript
+// ethers
+import { JsonRpcProvider, Wallet } from 'ethers';
+const wallet = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));
+sdk.evm.setSigner(wallet);
+
+// wagmi/viem (browser)
+import { useWalletClient } from 'wagmi';
+const { data: walletClient } = useWalletClient();
+if (walletClient) sdk.evm.setSigner(walletClient);
+```
+
+**Write methods:**
+
+| Method | Description |
+| --- | --- |
+| `vaultApprove(options)` | Approve token spend for a vault |
+| `approve(options)` | Generic ERC-20 approve |
+| `vaultDeposit(options)` | Deposit assets into a vault |
+| `vaultRequestRedeem(options)` | Request a withdrawal/redemption |
+| `vaultRedeem(signer, options)` | Claim an available redemption |
+| `depositNative(options)` | Deposit native tokens (ETH, etc.) |
+| `swapAndDeposit(options)` | Swap and deposit in one call |
+| `depositViaSwapRouter(options)` | Deposit via the swap router |
+| `depositNativeViaSwapRouter(options)` | Deposit native via the swap router |
+
+**Read helpers (return raw `bigint`):**
+
+| Method | Description |
+| --- | --- |
+| `previewDeposit(options)` | Shares minted for a deposit amount |
+| `previewRedeem(options)` | Assets returned for a share amount |
+| `allowance(options)` | ERC-20 allowance granted to the vault |
+| `balanceOf(options)` | ERC-20 balance for any token/owner |
+| `maxDeposit(options)` | Maximum deposit accepted by the vault |
+| `vaultAllowance(options)` | Vault-specific allowance check |
+| `getDeposited(options)` | Current deposited balance |
+| `getRemainingAllocations(options)` | Remaining allocation capacity |
+| `isWhitelisted(options)` | Check whitelist status |
+
+### Solana Adapter (`sdk.solana`)
+
+| Method | Description |
+| --- | --- |
+| `getVaultState(...)` | Vault state from the Solana program |
+| `getVaultStateReadOnly(...)` | Read-only vault state |
+| `getToken(mintAddress)` | SPL token info |
+| `getTokenSymbol(mintAddress)` | Token symbol |
+| `fetchUserTokenBalance(publicKey, mint)` | User SPL token balance |
+| `fetchUserShareBalance(publicKey, vault)` | User share balance |
+| `fetchUserShareBalanceRaw(publicKey, vault)` | Raw share balance (bigint) |
+
+### Stellar Adapter (`sdk.stellar`)
+
+| Method | Description |
+| --- | --- |
+| `vaultDeposit(options)` | Deposit into a Stellar vault |
+| `vaultRedeem(options)` | Redeem from a Stellar vault |
+| `submitTransaction(signedXdr)` | Submit a signed XDR transaction |
+| `getUserPosition(options)` | User position in a Stellar vault |
+| `convertToShares(options)` | Convert an asset amount to shares |
+
+### Sui Adapter (`sdk.sui`)
+
+| Method | Description |
+| --- | --- |
+| `getEmberVaults()` | List all Ember (Sui) vaults |
+| `getEmberTVL(limit?)` | Total value locked across Ember vaults |
+
 ## Code Conventions
 
 ### Naming Patterns
@@ -170,9 +289,9 @@ All vault queries support optional enrichment:
 - **ABIs**: Prefixed with `ABI_` (e.g., `ABI_LENDING_POOL_V2`)
 - **Types**: Descriptive names (e.g., `IAddress`, `IChainId`)
 
-### Important Tags
+### Special Comment Tags
 
-Search codebase for these comments to find areas needing attention:
+Search the codebase for these to find important areas:
 
 - `@todo`: Planned improvements or missing features
 - `@hardcoded`: Hardcoded values that may need configuration
@@ -180,61 +299,34 @@ Search codebase for these comments to find areas needing attention:
 
 ### Error Handling
 
-- Automatic retry logic for network errors with exponential backoff
-- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)
-- Correlation IDs logged for debugging failed requests
-- Write actions throw errors instead of silent failures
-
-### Environment Configuration
+Every public method throws typed errors that subclass `AugustSDKError`:
 
 ```typescript
-// Development mode (enables console logging)
-const devSdk = new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  monitoring: {
-    env: 'DEV',
-  },
-});
-
-// Production mode (default - no console logs)
-const prodSdk = new AugustSDK({
-  providers: {
-    /* ... */
-  },
-  // monitoring is optional - defaults to PROD
-});
+import { AugustValidationError, AugustTimeoutError, AugustSDKError } from '@augustdigital/sdk';
+
+try {
+  await sdk.evm.vaultDeposit({ target: '0x...', wallet: owner, amount: '1' });
+} catch (err) {
+  if (err instanceof AugustValidationError) showFormError(err.message);
+  else if (err instanceof AugustTimeoutError) scheduleRetry(err.timeoutMs);
+  else if (err instanceof AugustSDKError) reportError(err.code, err.cause);
+  else throw err;
+}
 ```
 
-- `env: 'DEV'` - Enables console logging for debugging
-- `env: 'PROD'` or omitted - Disables console, uses custom logger only (safer default)
-
-## API Reference
-
-### Main Methods
-
-#### Vault Queries
-
-- `getVaults(options?)`: Fetch all vaults across chains
-- `getVault({ vault, chainId?, options? })`: Get single vault details
-- `getVaultLoans({ vault, chainId })`: Fetch active loans
-- `getVaultAllocations({ vault, chainId })`: Get allocation breakdown
-- `getVaultApy({ vault, historical? })`: Current/historical APY
-- `getVaultTvl({ vault, historical? })`: Current/historical TVL
-
-#### User Positions
+- Automatic retry with exponential backoff for network errors
+- 90-second request timeout (configurable via `REQUEST_TIMEOUT_MS`)
+- Correlation IDs in errors for debugging
 
-- `getVaultPositions({ wallet?, vault?, chainId? })`: User vault positions
-- `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose?})`: Claimable redemptions
-- `getVaultUserHistory({ wallet, vault?, chainId? })`: Transaction history
-- `getVaultStakingPositions({ wallet, chainId })`: Staking positions
+### Environment Configuration
 
-#### Utilities
+```typescript
+// Development mode — enables console logging
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ }, monitoring: { env: 'DEV' } });
 
-- `getPrice(symbol)`: Get token price in USD
-- `switchNetwork(chainId)`: Change active chain
-- `updateWallet(address)`: Set active wallet for tracking
+// Production mode — default, no console logs
+const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ } });
+```
 
 ## Development
 
@@ -250,10 +342,8 @@ pnpm test
 pnpm build
 ```
 
-### Type Checking
-
-All exports are fully typed. Use TypeScript for best developer experience.
-
 ## Support
 
-For issues or questions, refer to the [main repository](https://github.com/fractal-protocol/js-sdk) or contact the August Digital team.
+- **Issues**: [GitHub Issues](https://github.com/fractal-protocol/js-sdk/issues)
+- **Documentation**: [docs.augustdigital.io](https://docs.augustdigital.io/developers/javascript-sdk)
+- **Example App**: [starter.upshift.finance](https://starter.upshift.finance/)

package/lib/abis/ERC20_Bytes32.d.ts

@@ -1,3 +1,7 @@
+/**
+ * [bytes32-flavored ERC-20](https://docs.makerdao.com/smart-contract-modules/mkr-module#4.-gotchas-potential-source-of-user-error)
+ * for tokens (ie. Maker) that use bytes32 instead of string.
+ */
 export declare const ABI_ERC20_BYTES32: readonly [{
     readonly type: "event";
     readonly name: "Approval";

package/lib/abis/ERC20_Bytes32.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_ERC20_BYTES32 = void 0;
+/**
+ * [bytes32-flavored ERC-20](https://docs.makerdao.com/smart-contract-modules/mkr-module#4.-gotchas-potential-source-of-user-error)
+ * for tokens (ie. Maker) that use bytes32 instead of string.
+ */
 exports.ABI_ERC20_BYTES32 = [
     {
         type: 'event',

package/lib/abis/ERC4626.d.ts

@@ -1,3 +1,4 @@
+/** [ERC-4626 Tokenized Vaults Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626) */
 export declare const ABI_ERC4626: readonly [{
     readonly anonymous: false;
     readonly inputs: readonly [{

package/lib/abis/ERC4626.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_ERC4626 = void 0;
+/** [ERC-4626 Tokenized Vaults Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-4626) */
 exports.ABI_ERC4626 = [
     {
         anonymous: false,

package/lib/abis/ERC721.d.ts

@@ -1,3 +1,4 @@
+/** [ERC-721 Non-Fungible Token Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-721) */
 export declare const ABI_ERC721: readonly [{
     readonly type: "event";
     readonly name: "Approval";

package/lib/abis/ERC721.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_ERC721 = void 0;
+/** [ERC-721 Non-Fungible Token Standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-721) */
 exports.ABI_ERC721 = [
     {
         type: 'event',

package/lib/abis/FeeOracle.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_FEE_ORACLE = void 0;
+// export const ABI_FEE_ORACLE = [{"type":"constructor","inputs":[{"name":"ownerAddr","type":"address","internalType":"address"}],"stateMutability":"nonpayable"},{"type":"function","name":"FEES_DIVISOR","inputs":[],"outputs":[{"name":"","type":"uint256","internalType":"uint256"}],"stateMutability":"view"},{"type":"function","name":"getContextFeeAmount","inputs":[{"name":"amount","type":"uint256","internalType":"uint256"},{"name":"categoryId","type":"bytes32","internalType":"bytes32"},{"name":"specificAddr","type":"address","internalType":"address"}],"outputs":[{"name":"feePercent","type":"uint256","internalType":"uint256"},{"name":"feeAmount","type":"uint256","internalType":"uint256"}],"stateMutability":"view"},{"type":"function","name":"getContextFeeRate","inputs":[{"name":"categoryId","type":"bytes32","internalType":"bytes32"},{"name":"specificAddr","type":"address","internalType":"address"}],"outputs":[{"name":"","type":"uint256","internalType":"uint256"}],"stateMutability":"view"},{"type":"function","name":"owner","inputs":[],"outputs":[{"name":"","type":"address","internalType":"address"}],"stateMutability":"view"},{"type":"function","name":"setContextFeeRate","inputs":[{"name":"feePercent","type":"uint256","internalType":"uint256"},{"name":"categoryId","type":"bytes32","internalType":"bytes32"},{"name":"specificAddr","type":"address","internalType":"address"}],"outputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"transferOwnership","inputs":[{"name":"newOwner","type":"address","internalType":"address"}],"outputs":[],"stateMutability":"nonpayable"},{"type":"event","name":"OwnershipTransferred","inputs":[{"name":"previousOwner","type":"address","indexed":true,"internalType":"address"},{"name":"newOwner","type":"address","indexed":true,"internalType":"address"}],"anonymous":false}] as const;
 exports.ABI_FEE_ORACLE = [
     {
         inputs: [

package/lib/abis/LendingPool.js

@@ -1155,6 +1155,7 @@ exports.ABI_LENDING_POOLS = [
         type: 'function',
     },
     {
+        // TokenizedVaults only
         inputs: [],
         name: 'operator',
         outputs: [

package/lib/abis/LendingPoolV2.js

@@ -1168,6 +1168,7 @@ exports.ABI_LENDING_POOL_V2 = [
         type: 'function',
     },
     {
+        // Tokenized Vaults only
         inputs: [],
         name: 'operator',
         outputs: [

package/lib/abis/Multicall3.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_MULTICALL3 = void 0;
+/* [Multicall3](https://github.com/mds1/multicall) */
 exports.ABI_MULTICALL3 = [
     {
         inputs: [
@@ -44,6 +45,8 @@ exports.ABI_MULTICALL3 = [
         type: 'function',
     },
 ];
+// Universal resolver error definitions (reserved for future use)
+// @ts-expect-error - Reserved for future ENS integration
 const universalResolverErrors = [
     {
         inputs: [],

package/lib/abis/OFT.d.ts

@@ -1,3 +1,10 @@
+/**
+ * ABI fragments for OFT (Omnichain Fungible Token) and related contracts
+ * used in LayerZero cross-chain vault operations.
+ *
+ * @module ABIs/OFT
+ */
+/** ERC20 allowance + approve ABI for cross-chain approval checks */
 export declare const ABI_CROSS_CHAIN_ERC20: readonly [{
     readonly inputs: readonly [{
         readonly internalType: "address";
@@ -35,6 +42,11 @@ export declare const ABI_CROSS_CHAIN_ERC20: readonly [{
     readonly stateMutability: "nonpayable";
     readonly type: "function";
 }];
+/**
+ * Multi-asset vault previewDeposit ABI.
+ * Uses `previewDeposit(address, uint256)` instead of standard ERC4626's
+ * `previewDeposit(uint256)` to specify which asset is being deposited.
+ */
 export declare const ABI_MULTI_ASSET_PREVIEW_DEPOSIT: readonly [{
     readonly type: "function";
     readonly name: "previewDeposit";
@@ -58,6 +70,11 @@ export declare const ABI_MULTI_ASSET_PREVIEW_DEPOSIT: readonly [{
     }];
     readonly stateMutability: "view";
 }];
+/**
+ * Multi-asset vault previewRedemption ABI.
+ * Uses `previewRedemption(uint256, bool)` to preview redeem output
+ * with an `isInstant` flag.
+ */
 export declare const ABI_MULTI_ASSET_PREVIEW_REDEEM: readonly [{
     readonly type: "function";
     readonly name: "previewRedemption";
@@ -81,6 +98,9 @@ export declare const ABI_MULTI_ASSET_PREVIEW_REDEEM: readonly [{
     }];
     readonly stateMutability: "view";
 }];
+/**
+ * Standard ERC4626 previewRedeem ABI.
+ */
 export declare const ABI_STANDARD_PREVIEW_REDEEM: readonly [{
     readonly type: "function";
     readonly name: "previewRedeem";

package/lib/abis/OFT.js

@@ -1,6 +1,13 @@
 "use strict";
+/**
+ * ABI fragments for OFT (Omnichain Fungible Token) and related contracts
+ * used in LayerZero cross-chain vault operations.
+ *
+ * @module ABIs/OFT
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_STANDARD_PREVIEW_REDEEM = exports.ABI_MULTI_ASSET_PREVIEW_REDEEM = exports.ABI_MULTI_ASSET_PREVIEW_DEPOSIT = exports.ABI_CROSS_CHAIN_ERC20 = void 0;
+/** ERC20 allowance + approve ABI for cross-chain approval checks */
 exports.ABI_CROSS_CHAIN_ERC20 = [
     {
         inputs: [
@@ -23,6 +30,11 @@ exports.ABI_CROSS_CHAIN_ERC20 = [
         type: 'function',
     },
 ];
+/**
+ * Multi-asset vault previewDeposit ABI.
+ * Uses `previewDeposit(address, uint256)` instead of standard ERC4626's
+ * `previewDeposit(uint256)` to specify which asset is being deposited.
+ */
 exports.ABI_MULTI_ASSET_PREVIEW_DEPOSIT = [
     {
         type: 'function',
@@ -38,6 +50,11 @@ exports.ABI_MULTI_ASSET_PREVIEW_DEPOSIT = [
         stateMutability: 'view',
     },
 ];
+/**
+ * Multi-asset vault previewRedemption ABI.
+ * Uses `previewRedemption(uint256, bool)` to preview redeem output
+ * with an `isInstant` flag.
+ */
 exports.ABI_MULTI_ASSET_PREVIEW_REDEEM = [
     {
         type: 'function',
@@ -53,6 +70,9 @@ exports.ABI_MULTI_ASSET_PREVIEW_REDEEM = [
         stateMutability: 'view',
     },
 ];
+/**
+ * Standard ERC4626 previewRedeem ABI.
+ */
 exports.ABI_STANDARD_PREVIEW_REDEEM = [
     {
         type: 'function',

package/lib/abis/SmartAccount.d.ts

@@ -1,3 +1,4 @@
+/** @internal */
 export declare const ABI_SMART_ACCOUNT: readonly [{
     readonly name: "isValidSignature";
     readonly type: "function";

package/lib/abis/SmartAccount.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_SMART_ACCOUNT = void 0;
+// ERC-1271
+// isValidSignature(bytes32 hash, bytes signature) → bytes4 magicValue
+/** @internal */
 exports.ABI_SMART_ACCOUNT = [
     {
         name: 'isValidSignature',

package/lib/abis/SwapRouter.d.ts

@@ -1,3 +1,4 @@
+/** ABI for the August `SwapRouter` periphery contract. */
 export declare const ABI_SWAP_ROUTER: readonly [{
     readonly inputs: readonly [];
     readonly stateMutability: "nonpayable";

package/lib/abis/SwapRouter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_SWAP_ROUTER = void 0;
+/** ABI for the August `SwapRouter` periphery contract. */
 exports.ABI_SWAP_ROUTER = [
     { inputs: [], stateMutability: 'nonpayable', type: 'constructor' },
     { inputs: [], name: 'AlreadyConfigured', type: 'error' },

package/lib/abis/UniversalSignatureValidator.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ABI_UNIVERSAL_SIGNATURE_VALIDATOR = void 0;
+// ERC-6492 - universal deployless signature validator contract
+// constructor(address _signer, bytes32 _hash, bytes _signature) → bytes4 returnValue
+// returnValue is either 0x1 (valid) or 0x0 (invalid)
 exports.ABI_UNIVERSAL_SIGNATURE_VALIDATOR = [
     {
         inputs: [