augustdigital-sdk 8.20.1

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

@@ -0,0 +1,529 @@
+import { type Signer, type Wallet, type TransactionResponse } from 'ethers';
+import type { IAddress } from '../../types';
+import type { ISwapAndDepositOptions, ISwapRouterDirectDepositOptions, ISwapRouterNativeDepositOptions, ISwapRouterDepositOptions } from '../../types';
+export type IContractWriteOptions = {
+    target: IAddress;
+    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;
+    isNativeToken: boolean;
+    isMultiAssetVault: boolean;
+    vaultDecimals: number;
+    readErc20Decimals: (address: IAddress) => Promise<number>;
+}): Promise<number>;
+/** @internal */
+export declare function resolveSpender(args: {
+    target: IAddress;
+    isMultiAssetVault: boolean;
+    isAdapterDeposit: boolean;
+    adapterWrapperAddress?: IAddress;
+}): IAddress;
+/** @internal */
+export declare function validateAmountPrecision(amount: string | bigint | number): void;
+/** @internal */
+export declare function isNonceParsing(error: unknown): boolean;
+/**
+ * Await a broadcast transaction's receipt, surviving both malformed-nonce RPCs
+ * and transient transport faults while still reporting genuine on-chain
+ * failures.
+ *
+ * `tx.wait()` is tried first because it preserves ethers' replacement-tx
+ * detection and revert checks. Two recoverable failure modes are handled:
+ *
+ * 1. **Malformed nonce** ({@link isNonceParsing}) — Monad-style RPCs return
+ *    `nonce: "undefined"` on the pending tx and ethers throws while parsing.
+ *    One direct `provider.waitForTransaction()` recovers it (unchanged
+ *    behaviour).
+ * 2. **Transient transport fault** ({@link isRetryableRpcError}) — the provider
+ *    hiccups while polling `eth_getTransactionReceipt` and ethers surfaces
+ *    `could not coalesce error (… "code": -32603 …)`. This used to propagate
+ *    and make every write path report a **successfully mined** transaction as
+ *    failed, driving users to retry into `ERC20InsufficientBalance`. The hash
+ *    is already on the wire and receipt polling is idempotent, so we re-poll
+ *    with bounded exponential backoff instead of rethrowing.
+ *
+ * Everything else — notably a real revert — is rethrown untouched.
+ *
+ * Every error this function throws is stamped by {@link markBroadcast}: by the
+ * time `tx.wait()` can fail, the transaction is already on the wire, so the
+ * caller must never report it as "never sent". See
+ * {@link localTxBroadcastContext} for how that reaches
+ * `AugustSDKError.context`.
+ *
+ * @param tx - The broadcast transaction response to await.
+ * @returns The mined receipt (never `null` on the fallback paths; `tx.wait()`
+ *   itself may return `null` when the caller configured 0 confirmations).
+ * @throws {Error} `Transaction <hash> reverted on-chain` when the receipt
+ *   reports `status === 0`. Marked `confirmationUnknown: false` — the chain
+ *   answered.
+ * @throws {Error} `Transaction <hash> was not confirmed within <n>s` when the
+ *   overall wait times out with no receipt. Marked
+ *   `confirmationUnknown: true`.
+ * @throws The underlying transport error once receipt-poll retries are
+ *   exhausted, marked `confirmationUnknown: true`.
+ * @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>;
+/**
+ * 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>;
+/**
+ * Deposit into an August vault through the on-chain `SwapRouter`, selecting the
+ * correct router path from the deposit asset. This is the high-level, explicit
+ * counterpart to the SwapRouter branch inside {@link vaultDeposit}.
+ *
+ * Where `vaultDeposit` decides whether to use the SwapRouter from the
+ * `VAULTS_USING_SWAP_ROUTER` allowlist, this function always routes through the
+ * SwapRouter because the caller asked it to. Making the intent explicit is the
+ * point: a native-deposit vault (e.g. a multi-asset Tokenized Vault V2 whose
+ * non-reference assets are accepted directly) is never accidentally swapped —
+ * the regression that implicit, allowlist-driven routing caused. Use
+ * `vaultDeposit` for native / adapter deposits and this for SwapRouter deposits.
+ *
+ * The vault's reference asset and its decimals are read on-chain (never trusted
+ * from the caller — a wrong reference asset would mis-route the swap). The path
+ * is then chosen from `depositAsset`:
+ *  - equals the reference asset → direct router deposit, no swap
+ *    ({@link depositViaSwapRouter});
+ *  - the zero address → native-token deposit ({@link depositNativeViaSwapRouter}),
+ *    valid only when the reference asset is the chain's wrapped-native token;
+ *  - any other ERC-20 → a swap to the reference asset (Paraswap quote pinned to
+ *    the chain's whitelisted aggregator, fail-closed on router/selector drift)
+ *    bundled into {@link swapAndDeposit}.
+ *
+ * Side effects: reads tokenized-vault metadata, the vault's reference asset and
+ * decimals, and (on the swap path) one Paraswap quote; sends one ERC-20
+ * `approve` to the SwapRouter when allowance is short, then the deposit tx.
+ *
+ * @param signer - ethers `Signer` or `Wallet` that signs the approval + deposit.
+ * @param options - {@link ISwapRouterDepositOptions}.
+ * @returns The transaction hash of the router deposit call.
+ * @throws {@link AugustValidationError} for an unsupported chain (no SwapRouter
+ *   deployment), an invalid vault or deposit-asset address, a missing or zero
+ *   amount, a native deposit into a non-wrapped-native vault, or drift between
+ *   the aggregator quote and the on-chain router whitelist.
+ * @worstCaseRpcCalls 5 on the swap path — tokenized-vault metadata, reference
+ *   asset + decimals, deposit-token decimals, the quote, and the allowance read.
+ * @example
+ * ```ts
+ * // USDT deposited into a USDC-reference vault → swapped to USDC en route.
+ * const hash = await augustSdk.evm.swapRouterDeposit({
+ *   chainId: 1,
+ *   vault: '0xe9b725010a9e419412ed67d0fa5f3a5f40159d32',
+ *   depositAsset: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   amount: '100',
+ *   slippageBps: 50,
+ * });
+ * ```
+ */
+export declare function swapRouterDeposit(signer: Signer | Wallet, options: ISwapRouterDepositOptions): Promise<string>;