@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/modules/vaults/write.actions.d.ts

@@ -6,21 +6,62 @@ export type IContractWriteOptions = {
     wallet: IAddress;
     amount?: string | bigint | number;
     wait?: boolean;
+    /**
+     * Optional: Token to deposit (defaults to vault's underlying asset)
+     * If different from underlying, will use adapter logic
+     */
     depositAsset?: IAddress;
+    /**
+     * Optional: Chain ID for the vault (used for adapter routing)
+     */
     chainId?: number;
+    /**
+     * Optional: Pool/vault name for adapter routing
+     */
     poolName?: string;
+    /**
+     * Optional: boolean for instant redeem
+     */
     isInstantRedeem?: boolean;
+    /**
+     * Optional: boolean for depositWithPermit
+     */
     isDepositWithPermit?: boolean;
+    /**
+     * Optional: address that receives the vault shares. Defaults to `wallet`.
+     * Only honored on the SwapRouter dispatch path; legacy adapters mint to `wallet`.
+     */
     receiver?: IAddress;
+    /**
+     * Optional: slippage tolerance in bps (1 bp = 0.01%) applied to any swap
+     * quote the SwapRouter dispatch path fetches when `depositAsset` differs
+     * from the vault's reference asset. Must be in `[0, 10_000)`. Defaults to
+     * `100` (1%). Ignored for same-asset deposits and legacy adapter paths.
+     */
     slippageBps?: number;
 };
 export type INativeDepositOptions = {
+    /**
+     * MultiAssetNativeDepositWrapper contract address
+     */
     wrapperAddress: IAddress;
+    /**
+     * Optional: Receiver address for the deposit (defaults to signer address)
+     * If not provided, uses the overload without receiver parameter
+     */
     receiver?: IAddress;
+    /**
+     * Amount of native token (ETH/AVAX/etc) to deposit
+     */
     amount: string | bigint | number;
+    /**
+     * Optional: Wait for transaction confirmation
+     */
     wait?: boolean;
 };
+/** @internal */
 export declare function safeBigInt(value: unknown, context?: string): bigint;
+/** @internal */
 export declare function resolveDepositTokenDecimals(args: {
     actualDepositAsset: IAddress;
     underlyingAsset: IAddress;
@@ -29,6 +70,7 @@ export declare function resolveDepositTokenDecimals(args: {
     vaultDecimals: number;
     readErc20Decimals: (address: IAddress) => Promise<number>;
 }): Promise<number>;
+/** @internal */
 export declare function resolveSpender(args: {
     target: IAddress;
     isMultiAssetVault: boolean;
@@ -36,45 +78,363 @@ export declare function resolveSpender(args: {
     adapterWrapperAddress?: IAddress;
     swapRouterAddress?: IAddress;
 }): IAddress;
+/** @internal */
 export declare function validateAmountPrecision(amount: string | bigint | number): void;
+/** @internal */
 export declare function isNonceParsing(error: unknown): boolean;
+/** @internal */
 export declare function safeWaitForTx(tx: TransactionResponse): Promise<import("ethers").TransactionReceipt>;
+/**
+ * Wraps an ethers contract call that returns a TransactionResponse.
+ * Some RPCs (e.g. Monad) return malformed pending tx fields like `nonce: "undefined"`,
+ * which causes ethers.js to throw during response parsing before safeWaitForTx runs.
+ * This wrapper catches that error, extracts the tx hash from the error context, and
+ * falls back to provider.waitForTransaction().
+ */
+/** @internal */
 export declare function safeSendTx(contractCall: () => Promise<TransactionResponse>, provider: Signer | Wallet, shouldWait?: boolean): Promise<{
     tx: TransactionResponse | null;
     hash: string;
 }>;
+/**
+ * Shared nonce-recovery helper for catch blocks. When an RPC returns a
+ * malformed nonce and ethers throws, try to extract the tx hash from the
+ * error payload. Optionally waits for confirmation (with status check).
+ *
+ * Returns the recovered hash, or null if this error is not a nonce-parse error
+ * or if no hash could be extracted (caller should re-throw the original error).
+ */
+/** @internal */
 export declare function tryRecoverTxHash(error: unknown, signer: Signer | Wallet, wait?: boolean): Promise<string | null>;
-export type ApproveResult = {
+/**
+ * Discriminated union returned by {@link approve}. Lets callers tell apart
+ * "we sent a tx" / "existing allowance already covers it" / "native token, no
+ * allowance applies" without re-reading on-chain state.
+ */
+export type ApproveResult = 
+/** An `approve` transaction was sent. `hash` is the tx hash. */
+{
     kind: 'sent';
     hash: string;
-} | {
+}
+/**
+ * Existing allowance already covers `amount`; no tx sent. `existing` is
+ * the on-chain allowance (raw bigint, in deposit-token units).
+ */
+ | {
     kind: 'sufficient';
     existing: bigint;
-} | {
+}
+/**
+ * The resolved deposit asset is the native token — it travels as
+ * `msg.value`, so no ERC-20 allowance applies. No tx sent.
+ */
+ | {
     kind: 'native';
 };
+/**
+ * Approve a vault (or the appropriate adapter wrapper) to spend a token
+ * ahead of a separate deposit call. Spender routing mirrors
+ * {@link vaultDeposit} (multi-asset → vault, adapter → wrapper, standard →
+ * vault). Returns `undefined` when the existing allowance already covers
+ * `amount` **or** when the deposit asset is native.
+ *
+ * @returns Transaction hash when an approval was sent, `undefined` when
+ *   the existing allowance already covers `amount` or the deposit asset is
+ *   native (no ERC-20 allowance applies). Use {@link approve} for a
+ *   discriminated `ApproveResult` if you need to tell those two cases apart.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultApprove({
+ *   target: '0x...',         // vault contract address
+ *   wallet: walletAddress,
+ *   amount: '100',           // 100 of the deposit token (UI units)
+ *   wait: true,              // wait for the approval to confirm
+ * });
+ * if (hash) console.log('approve tx', hash);
+ * // hash === undefined means the on-chain allowance already covers the
+ * // amount, or the deposit asset is native (msg.value, no allowance).
+ * ```
+ */
 export declare function vaultApprove(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string | undefined>;
+/**
+ * Same approval logic as {@link vaultApprove} but returns a discriminated
+ * union so callers can tell `sent` apart from `sufficient` and `native`
+ * without re-reading on-chain state. Preferred shape for new integrations.
+ *
+ * @example
+ * ```ts
+ * const r = await augustSdk.evm.approve({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '100',
+ *   wait: true,
+ * });
+ * switch (r.kind) {
+ *   case 'sent':
+ *     showToast('Approval submitted', r.hash);
+ *     break;
+ *   case 'sufficient':
+ *     // r.existing is the existing on-chain allowance (raw bigint)
+ *     break;
+ *   case 'native':
+ *     // No allowance needed; native token will travel as msg.value
+ *     break;
+ * }
+ * ```
+ *
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the approval submission fails.
+ */
 export declare function approve(signer: Signer | Wallet, options: IContractWriteOptions): Promise<ApproveResult>;
+/**
+ * Deposit underlying token into the specified vault. Auto-routes to the
+ * correct contract path (single-asset ERC-4626, EVM-2 multi-asset,
+ * Paraswap adapter, native-token wrapper, depositWithPermit) based on the
+ * vault version and `depositAsset`.
+ *
+ * Amounts are encoded against the **deposit token's** decimals, not the
+ * vault's share decimals. The SDK reads the appropriate decimals via the
+ * vault metadata and the asset's ERC-20.
+ *
+ * Approval is handled automatically: if the existing allowance doesn't
+ * cover `amount`, an `approve` is sent and **always waited for** (regardless
+ * of the caller's `wait` flag) so the deposit tx can't be re-ordered ahead
+ * of the approval on Monad-style RPCs.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `depositAsset` for
+ *   adapter routes, optional `wait` to wait for the deposit receipt.
+ * @returns Deposit transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount or missing
+ *   adapter config when `depositAsset` differs from the vault underlying.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultDeposit({
+ *   target: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32', // vault
+ *   wallet: walletAddress,
+ *   amount: '100',         // 100 USDC (UI units)
+ *   wait: true,            // wait for the deposit receipt
+ * });
+ * ```
+ *
+ * @example Adapter deposit (different deposit asset than the vault's underlying)
+ * ```ts
+ * await augustSdk.evm.vaultDeposit({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '0.5',
+ *   depositAsset: WETH_ADDRESS,   // swap WETH -> vault underlying via the adapter
+ *   chainId: 1,
+ * });
+ * ```
+ */
 export declare function vaultDeposit(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+/**
+ * Request to redeem vault shares. For EVM-1 vaults this queues a standard
+ * redemption (claimable later via `vaultRedeem`); for EVM-2 vaults this
+ * also handles the receipt-token allowance automatically. Pass
+ * `isInstantRedeem: true` for vaults that support instant settlement.
+ *
+ * Approval of the receipt token (EVM-2) is always waited on before the
+ * redeem call, regardless of the caller's `wait` flag.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `isInstantRedeem`,
+ *   optional `wait` to wait for the redeem receipt.
+ * @returns Redeem transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',           // 10 shares (UI units)
+ *   wait: true,
+ * });
+ * ```
+ *
+ * @example Instant redemption
+ * ```ts
+ * await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   isInstantRedeem: true,
+ * });
+ * ```
+ */
 export declare function vaultRequestRedeem(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+/**
+ * @TODO
+ * @description withdraw funds from the specified pool including accrued rewards
+ * @param signer signer / wallet object
+ * @param options object including pool contract address, user wallet address, and more
+ * @returns claim tx hash
+ */
 export declare function vaultRedeem(signer: Signer | Wallet, options: IContractWriteOptions & {
     year: string;
     month: string;
     day: string;
     receiverIndex: string;
 }): Promise<string>;
+/**
+ * Deposit a native token (ETH / AVAX / etc.) into a vault via the
+ * `MultiAssetNativeDepositWrapper`. The wrapper forwards `msg.value` to
+ * the vault as the deposit underlying — no allowance is required.
+ *
+ * `amount` is the **raw on-chain value in wei-equivalent** (18 decimals
+ * for ETH-family natives). If you have a UI-shaped amount in ether, scale
+ * it first.
+ *
+ * @param signer ethers Signer / Wallet
+ * @param options `wrapperAddress` is the deployed wrapper contract;
+ *   `receiver` defaults to the signer's address; `amount` is the native
+ *   amount in wei; `wait` waits for the deposit receipt.
+ * @returns Deposit transaction hash.
+ * @throws AugustValidationError on invalid wrapper / receiver / amount.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * import { parseEther } from 'ethers';
+ *
+ * await augustSdk.evm.depositNative({
+ *   wrapperAddress: nativeWrapperAddress,
+ *   amount: parseEther('0.5'),   // 0.5 ETH in wei
+ *   wait: true,
+ * });
+ * ```
+ */
 export declare function depositNative(signer: Signer | Wallet, options: INativeDepositOptions): Promise<string>;
 export type IRwaRedeemOptions = {
+    /** RwaRedeemSubaccount contract address */
     target: IAddress;
+    /** User wallet address */
     wallet: IAddress;
+    /** Redeemable asset address (e.g. USDC, USDT) */
     asset: IAddress;
+    /** Amount of vault shares to redeem */
     amount: string | bigint | number;
+    /** Minimum output amount (slippage protection), in output asset decimals */
     minOut: string | bigint | number;
+    /** Decimals of the vault share token */
     decimals: number;
+    /** Decimals of the output/redeemable asset */
     outputDecimals: number;
+    /** Wait for transaction confirmation */
     wait?: boolean;
 };
+/**
+ * Redeem vault shares for an underlying asset via the RwaRedeemSubaccount.
+ * Caller must approve the **vault share token** (not the output asset) to
+ * the subaccount beforehand — it pulls shares via `transferFrom`.
+ *
+ * Pass `minOut` to enforce slippage protection (in `outputDecimals` units).
+ * The SDK does not currently compute `minOut` from a slippage percentage —
+ * the caller is responsible for choosing a safe lower bound.
+ *
+ * @throws AugustValidationError on invalid addresses or amount inputs.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * // 1. Approve the vault share token to the subaccount first.
+ * await augustSdk.evm.vaultApprove({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   wait: true,
+ * });
+ *
+ * // 2. Redeem 10 shares for USDC, requiring at least 9.5 USDC out.
+ * await augustSdk.evm.rwaRedeemAsset({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   asset: USDC_ADDRESS,
+ *   amount: '10',
+ *   minOut: '9.5',
+ *   decimals: 18,            // vault share decimals
+ *   outputDecimals: 6,       // USDC decimals
+ *   wait: true,
+ * });
+ * ```
+ */
 export declare function rwaRedeemAsset(signer: Signer | Wallet, options: IRwaRedeemOptions): Promise<string>;
+/**
+ * Swap one or more whitelisted ERC-20s into a vault's reference asset via
+ * the on-chain SwapRouter, then deposit the proceeds into the vault.
+ *
+ * Approval is sent automatically when the caller's allowance on each
+ * `swaps[i].tokenIn` against the SwapRouter is below `amountIn`.
+ *
+ * @param signer - ethers `Signer` or `Wallet` with the EOA that holds the input tokens.
+ * @param options - {@link ISwapAndDepositOptions}.
+ * @returns The transaction hash of the `swapAndDeposit` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, empty/oversized swap arrays.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * const hash = await swapAndDeposit(signer, {
+ *   chainId: 1,
+ *   vault: '0x8AcA0841993ef4C87244d519166e767f49362C21',
+ *   receiver: wallet,
+ *   swaps: [{
+ *     tokenIn: WBTC,
+ *     tokenOut: USDC,
+ *     amountIn: 100_000_000n,
+ *     minAmountOut: quote.minAmountOut,
+ *     router: quote.router,
+ *     payload: quote.payload,
+ *   }],
+ * });
+ * ```
+ */
 export declare function swapAndDeposit(signer: Signer | Wallet, options: ISwapAndDepositOptions): Promise<string>;
+/**
+ * Deposit a vault's reference asset directly through the SwapRouter — no
+ * swap. Useful when the caller already holds the reference asset but wants
+ * the origin/referral fee accounting that only the SwapRouter path provides.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterDirectDepositOptions}.
+ * @returns The transaction hash of the `deposit` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
 export declare function depositViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterDirectDepositOptions): Promise<string>;
+/**
+ * Deposit native ETH (or chain-native equivalent) into a vault via the
+ * SwapRouter. The router wraps `amount` to the chain's wrapped-native token
+ * before depositing — only valid when the vault's reference asset equals
+ * the wrapped-native token.
+ *
+ * No ERC-20 approval is needed; `amount` travels as `msg.value`.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterNativeDepositOptions}.
+ * @returns The transaction hash of the `depositNativeToken` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
 export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterNativeDepositOptions): Promise<string>;