@upshiftfinance/sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,812 @@
+import { type Signer, type Wallet, type TransactionResponse } from 'ethers';
+import { type IAddress, SwapRouterVaultType } 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;
+    /**
+     * @deprecated Ignored — `vaultDeposit` mints to `wallet`. Use
+     * {@link swapRouterDeposit}'s `receiver` instead.
+     */
+    receiver?: IAddress;
+    /**
+     * @deprecated Ignored — `vaultDeposit` never swaps. Use
+     * {@link swapRouterDeposit}'s `slippageBps` instead.
+     */
+    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
+ * `UpshiftSDKError.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';
+};
+/**
+ * Why {@link getDepositRoute} kept a deposit on the vault's native path, or,
+ * on the router route, why the configured origin code was not sent.
+ *
+ * Native-path reasons: `no-router` (no SwapRouter on the chain), `permit`,
+ * `native-token`, `adapter`, `legacy-pool` (an `evm-0` lending pool, never
+ * tested against the router), `asset-not-accepted`, `kyc-vault` (the vault has
+ * a senders whitelist, so the router cannot deposit for the user) and
+ * `router-paused` (the owner paused the router; the deposit goes straight to
+ * the vault, even under `attribution.strictOrigin`, until it is unpaused).
+ *
+ * Router-route reason: `origin-not-registered` (the configured code is not
+ * registered on the router, so the deposit sends the zero code instead).
+ *
+ * `no-origin-code`, `chain-not-supported`, `vault-not-registered` and
+ * `router-token-not-whitelisted` are no longer returned: since SwapRouter v2 a
+ * deposit routes without an origin code and the router has no vault registry,
+ * and the router's direct deposit takes any asset the vault accepts. They stay
+ * in the union so integrator code that switches on them keeps compiling.
+ */
+export type DepositRouteReason = 'no-router' | 'permit' | 'native-token' | 'adapter' | 'legacy-pool' | 'asset-not-accepted' | 'kyc-vault' | 'router-paused' | 'origin-not-registered'
+/** @deprecated Not returned since SwapRouter v2: a deposit routes without an origin code. */
+ | 'no-origin-code'
+/** @deprecated Not returned since SwapRouter v2: routing no longer depends on the attribution chain list. */
+ | 'chain-not-supported'
+/** @deprecated Not returned since SwapRouter v2: the router has no vault registry. */
+ | 'vault-not-registered'
+/** @deprecated Not returned: the router's direct deposit takes any asset the vault accepts. */
+ | 'router-token-not-whitelisted';
+/** A deposit's route — the SwapRouter or the vault's native path — and the address to approve. */
+export type IDepositRoute = {
+    /**
+     * `router`: `SwapRouter.deposit` (a direct deposit, never a swap) carrying
+     * `originCode`. `native`: the vault's own deposit path.
+     */
+    via: 'native' | 'router';
+    /** Address to approve for the deposit token; `null` for a native-token deposit (`msg.value`). */
+    spender: IAddress | null;
+    /**
+     * Why the deposit stays native. On the router route it is set only to
+     * `origin-not-registered`, when the configured code was replaced by the zero
+     * code.
+     */
+    reason?: DepositRouteReason;
+    /**
+     * Router route only: the 32-byte origin code the deposit sends. The
+     * instance `attribution.originCode` when it is registered, else the all-zero
+     * code ({@link ORIGIN_CODES.default}, no origin fee).
+     */
+    originCode?: `0x${string}`;
+    /** Router route only: the vault type the deposit sends to the router. */
+    vaultType?: SwapRouterVaultType;
+};
+/** Options for {@link getDepositRoute} — the same fields `vaultDeposit` reads. */
+export type IGetDepositRouteOptions = Pick<IContractWriteOptions, 'target' | 'depositAsset' | 'chainId' | 'isDepositWithPermit'>;
+/**
+ * Resolve whether a deposit goes through the SwapRouter (`router`) or takes
+ * the vault's native path (`native`), and which address to approve.
+ * Read-only. `vaultDeposit` and `approve` follow this route, so integrators
+ * that manage approvals themselves must approve `route.spender`, not the
+ * vault.
+ *
+ * Since SwapRouter v2 a normal deposit routes whether or not an origin code is
+ * configured: the route is `router` when the chain has a SwapRouter, the
+ * vault accepts the asset directly (its reference asset, or a Tokenized
+ * Vault V2 whitelisted asset — deposited as-is, never swapped), the vault has
+ * no senders whitelist (KYC), the router is not paused, and the deposit is not
+ * a permit, native-token, adapter or legacy lending-pool deposit. Otherwise it
+ * is `native` with a `reason`. The router's token whitelist does not apply: it
+ * only gates swaps.
+ *
+ * The router route carries the instance `attribution.originCode` when it is
+ * registered, else the zero code (with `reason: 'origin-not-registered'` when
+ * a configured code was dropped). A paused router gives `router-paused` even
+ * under `attribution.strictOrigin`.
+ *
+ * @param signer - ethers `Signer` / `Wallet` used for the reads.
+ * @param options - {@link IGetDepositRouteOptions}; `depositAsset` defaults
+ *   to the vault's underlying.
+ * @returns {@link IDepositRoute}.
+ * @throws UpshiftValidationError on an invalid `target`, or an unregistered
+ *   code under `attribution.strictOrigin` while the router is not paused.
+ * @throws UpshiftSDKError when a backend, vault or router read fails.
+ * @worstCaseRpcCalls 7 — the backend vault row, `asset()`, the vault's
+ *   `assetsWhitelistAddress()` and `getWhitelistedAssets()` (Tokenized Vault
+ *   V2 non-reference asset only), its `sendersWhitelistAddress()` (Tokenized
+ *   Vault V2 only), the router's `isPaused()` and `origins` (non-zero code
+ *   only). Every read except `asset()` is cached for 5 minutes, `isPaused()`
+ *   for 15 seconds. No router read on a chain without a SwapRouter.
+ * @example
+ * ```ts
+ * const route = await upshiftSdk.evm.getDepositRoute({ target: vault, depositAsset: usdt });
+ * if (route.spender) await approveToken(usdt, route.spender, amount);
+ * ```
+ */
+export declare function getDepositRoute(signer: Signer | Wallet, options: IGetDepositRouteOptions): Promise<IDepositRoute>;
+/**
+ * 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, SwapRouter when {@link getDepositRoute} routes there). 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 UpshiftValidationError on invalid wallet/target/amount.
+ * @throws UpshiftValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter (the spender
+ *   follows {@link getDepositRoute}).
+ *
+ * @example
+ * ```ts
+ * const hash = await upshiftSdk.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 upshiftSdk.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 UpshiftValidationError on invalid wallet/target/amount.
+ * @throws UpshiftValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter (the spender
+ *   follows {@link getDepositRoute}).
+ * @throws UpshiftSDKError 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`.
+ *
+ * A deposit the SwapRouter can take directly goes through `SwapRouter.deposit`
+ * with or without an origin code, and the router is approved instead of the
+ * vault — see {@link getDepositRoute} for the rules and the fallback reasons.
+ * It carries the instance `attribution.originCode` when that code is
+ * registered, else the zero code.
+ *
+ * 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 UpshiftValidationError on invalid wallet/target/amount or missing
+ *   adapter config when `depositAsset` differs from the vault underlying.
+ * @throws UpshiftValidationError (`INVALID_INPUT`) when the vault's adapter is
+ *   the Paraswap bridge (`bridgeId === 2`): that route is not supported here
+ *   and is refused before any approval or deposit transaction is sent — use
+ *   {@link swapRouterDeposit} or deposit the underlying asset directly.
+ * @throws UpshiftValidationError when `attribution.strictOrigin` is set and the
+ *   configured origin code is not registered on the SwapRouter.
+ * @throws UpshiftSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await upshiftSdk.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 upshiftSdk.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 the queued
+ * `requestRedeem` escrows the shares in the vault via `transferFrom`, so this
+ * also approves the receipt token when its allowance is short; the instant
+ * path (`isInstantRedeem: true`) burns the caller's shares directly and sends
+ * no approval.
+ *
+ * The receipt-token approval (EVM-2 queued path) 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 UpshiftValidationError on invalid wallet/target/amount.
+ * @throws UpshiftSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await upshiftSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',           // 10 shares (UI units)
+ *   wait: true,
+ * });
+ * ```
+ *
+ * @example Instant redemption
+ * ```ts
+ * await upshiftSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   isInstantRedeem: true,
+ * });
+ * ```
+ */
+export declare function vaultRequestRedeem(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+/**
+ * @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>;
+/** Options for {@link claimWithdrawal}. */
+export type IClaimWithdrawalOptions = {
+    /** EVM-2 (Tokenized Vault V2) vault contract address. */
+    target: IAddress;
+    /**
+     * Wallet initiating the claim. Not a signer, but it is the default
+     * `receiver` of the withdrawn assets when `receiver` is omitted.
+     */
+    wallet: IAddress;
+    /**
+     * Withdrawal-epoch year to settle, from the `(claimableEpoch, year, month,
+     * day)` tuple `vaultRequestRedeem`/`requestRedeem` returned for this
+     * withdrawal — do not re-derive it from a timestamp.
+     */
+    year: string | bigint | number;
+    /** Withdrawal-epoch month, same source as `year`. */
+    month: string | bigint | number;
+    /** Withdrawal-epoch day, same source as `year`. */
+    day: string | bigint | number;
+    /** Address receiving the withdrawn assets. Defaults to `wallet`. */
+    receiver?: IAddress;
+    /** Wait for transaction confirmation. */
+    wait?: boolean;
+};
+/**
+ * Claim a previously-requested queued withdrawal on an EVM-2 (Tokenized
+ * Vault V2) vault, once its withdrawal epoch has passed.
+ *
+ * EVM-2 only — v1/v0 vaults use a different claim path ({@link vaultRedeem}).
+ * The vault's on-chain `claim(year, month, day, receiverAddr)` reverts if the
+ * epoch has not yet elapsed, or if the vault's idle reserve has not been
+ * refilled from subaccounts to cover the queue for that date; neither
+ * condition is checked client-side before sending.
+ *
+ * @param signer ethers Signer / Wallet.
+ * @param options.target EVM-2 vault contract address.
+ * @param options.wallet Wallet initiating the claim; receives the withdrawn assets unless `receiver` is set.
+ * @param options.year Withdrawal-epoch year (see `getWithdrawalRequestsWithStatus` / `getWithdrawalEpoch`).
+ * @param options.month Withdrawal-epoch month.
+ * @param options.day Withdrawal-epoch day.
+ * @param options.receiver Address receiving the withdrawn assets. Defaults to `wallet`.
+ * @param options.wait Wait for transaction confirmation.
+ * @returns Claim transaction hash.
+ * @throws UpshiftValidationError on invalid address input, missing or non-integer date fields, or a non-EVM-2 vault.
+ * @throws UpshiftSDKError when the on-chain claim call fails.
+ *
+ * @worstCaseRpcCalls 2 — one vault-version lookup, one claim transaction.
+ *
+ * @example
+ * ```ts
+ * // vaultRequestRedeem returns the request tx hash, not the epoch. Read the
+ * // epoch of each queued request (and whether it is claimable yet) from
+ * // getWithdrawalRequestsWithStatus (exported from '@upshiftfinance/sdk').
+ * await upshiftSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ * });
+ * const requests = await getWithdrawalRequestsWithStatus({
+ *   vault: vaultAddress,
+ *   receiver: walletAddress,
+ *   options: { rpcUrl },
+ * });
+ * const ready = requests.find((r) => r.status === 'ready_to_claim');
+ * if (!ready) return;
+ * const { year, month, day } = ready.claimableDate;
+ * await upshiftSdk.evm.claimWithdrawal({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   year,
+ *   month,
+ *   day,
+ *   wait: true,
+ * });
+ * ```
+ */
+export declare function claimWithdrawal(signer: Signer | Wallet, options: IClaimWithdrawalOptions): 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 UpshiftValidationError on invalid wrapper / receiver / amount.
+ * @throws UpshiftSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * import { parseEther } from 'ethers';
+ *
+ * await upshiftSdk.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 UpshiftValidationError on invalid addresses or amount inputs.
+ * @throws UpshiftSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * // 1. Approve the vault share token to the subaccount first.
+ * await upshiftSdk.evm.vaultApprove({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   wait: true,
+ * });
+ *
+ * // 2. Redeem 10 shares for USDC, requiring at least 9.5 USDC out.
+ * await upshiftSdk.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 UpshiftValidationError} for unsupported chains, invalid
+ * addresses, empty/oversized swap arrays, a vault the router cannot deposit
+ * into (a legacy `evm-0` pool, or a Tokenized Vault V2 with a senders
+ * whitelist), or an origin code not registered on the router (a per-call
+ * code, or the instance code under `attribution.strictOrigin`), before any
+ * approval.
+ * @throws {@link UpshiftSDKError} while the SwapRouter is paused (checked before
+ * any approval), or 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 UpshiftValidationError} for unsupported chains, invalid
+ * addresses, zero amount, a vault the router cannot deposit into (a legacy
+ * `evm-0` pool, or a Tokenized Vault V2 with a senders whitelist), or an
+ * origin code not registered on the router (a per-call code, or the instance
+ * code under `attribution.strictOrigin`), before any approval; with code
+ * `ACCOUNT_NOT_FUNDED` when the account cannot cover gas.
+ * @throws {@link UpshiftSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
+ */
+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.
+ *
+ * **Wrap-only limitation**: the on-chain SwapRouter has no ETH→other-asset
+ * swap leg, so this only ever reaches a WETH-accepting vault (see
+ * {@link SWAP_ROUTER_WRAPPED_NATIVE}). There is no atomic native-ETH deposit
+ * into a non-WETH-reference vault (e.g. a USDC vault) — deposit the wrapped
+ * native token instead (already whitelisted, routes through the swap leg for
+ * a non-reference-asset vault). Use {@link isNativeSwapRouterDepositSupported}
+ * to check eligibility before offering this path in a UI.
+ *
+ * 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 UpshiftValidationError} for unsupported chains, invalid
+ * addresses, zero amount, a vault the router cannot deposit into (a legacy
+ * `evm-0` pool, or a Tokenized Vault V2 with a senders whitelist), or an
+ * origin code not registered on the router (a per-call code, or the instance
+ * code under `attribution.strictOrigin`), before any approval; with code
+ * `ACCOUNT_NOT_FUNDED` when the account cannot cover gas.
+ * @throws {@link UpshiftSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
+ */
+export declare function depositNativeViaSwapRouter(signer: Signer | Wallet, options: ISwapRouterNativeDepositOptions): Promise<string>;
+/**
+ * Whether a vault can take a native-ETH (chain-native token) SwapRouter
+ * deposit — the pre-flight check for {@link depositNativeViaSwapRouter} and
+ * {@link swapRouterDeposit} with a zero-address `depositAsset`.
+ *
+ * The on-chain SwapRouter only wraps native ETH to the chain's wrapped-native
+ * token and deposits that — it has no ETH→other-asset swap leg (see
+ * {@link SWAP_ROUTER_WRAPPED_NATIVE}). So a native deposit needs both: a
+ * SwapRouter deployed on `chainId`, and the vault's own on-chain `asset()`
+ * equal to that chain's wrapped-native token. The v2 router has no vault
+ * registry, so no router read is needed. Use this to gate a
+ * "deposit ETH" UI option before the user picks it, instead of discovering
+ * the answer via a thrown {@link UpshiftValidationError} or an on-chain revert.
+ *
+ * It checks configuration only — a deposit that passes this check can still
+ * fail on balance, gas, a paused vault, or a deposit cap.
+ *
+ * Read-only and provider-agnostic (no signer required) — safe to call before
+ * a wallet is connected. Makes no backend call.
+ *
+ * @param chainId - EVM chain ID the vault is deployed on.
+ * @param vault - Upshift vault address to check.
+ * @param options - `rpcUrl` for `chainId`, passed to `createProvider`.
+ * @returns `true` iff a SwapRouter exists on `chainId` and the vault's
+ *   `asset()` is the chain's wrapped-native token. `false` — never throws —
+ *   for a chain with no SwapRouter deployment, a missing/invalid `rpcUrl`, an
+ *   unreadable vault, or a vault whose reference asset isn't the
+ *   wrapped-native token.
+ * @worstCaseRpcCalls 1 — the vault's `asset()`. None on a chain with no
+ *   SwapRouter.
+ * @example
+ * ```ts
+ * const canDepositEth = await isNativeSwapRouterDepositSupported(
+ *   1,
+ *   '0x1234000000000000000000000000000000005678',
+ *   { rpcUrl: 'https://eth-mainnet.example/v2/KEY' },
+ * );
+ * // true only if that vault's asset is WETH and mainnet has a SwapRouter
+ * ```
+ */
+export declare function isNativeSwapRouterDepositSupported(chainId: number, vault: IAddress, options: {
+    rpcUrl: string;
+}): Promise<boolean>;
+/**
+ * Deposit into an Upshift vault through the on-chain `SwapRouter`, selecting the
+ * correct router path from the deposit asset.
+ *
+ * {@link vaultDeposit} never swaps; this function always routes through the
+ * SwapRouter, because the caller asked it to. Keeping swaps opt-in 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 inside `vaultDeposit`
+ * caused before it was removed. 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, or is an asset a Tokenized Vault V2 accepts
+ *    as-is (e.g. USDT into Sentora USD) → direct router deposit, no swap and
+ *    no swap fee
+ *    ({@link depositViaSwapRouter});
+ *  - the zero address → native-token deposit ({@link depositNativeViaSwapRouter}),
+ *    valid only when the reference asset is the chain's wrapped-native token —
+ *    the router only wraps ETH, it never swaps it, so this throws for any
+ *    other reference asset (see {@link SWAP_ROUTER_WRAPPED_NATIVE} for why, and
+ *    {@link isNativeSwapRouterDepositSupported} to check first);
+ *  - 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}.
+ *
+ * The origin code — the per-call `originCode`, else the SDK instance's
+ * `attribution.originCode` on Ethereum mainnet, else the all-zero sentinel
+ * ("no origin fee") — is forwarded to whichever of those three entry points
+ * runs, so a partner's origin fee accrues on every path.
+ *
+ * Side effects: reads tokenized-vault metadata, the vault's reference asset and
+ * decimals, for a Tokenized Vault V2 non-reference asset the vault's assets
+ * whitelist, the origin code's registration, 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 UpshiftValidationError} for an unsupported chain (no SwapRouter
+ *   deployment), an invalid vault or deposit-asset address, a missing or zero
+ *   amount, a vault the router cannot deposit into (a legacy `evm-0` pool, or
+ *   a Tokenized Vault V2 with a senders whitelist), a native deposit into a
+ *   non-wrapped-native vault, drift between
+ *   the aggregator quote and the on-chain router whitelist, or an origin code
+ *   not registered on the router (a per-call code, or the instance code under
+ *   `attribution.strictOrigin`), before any approval; with code
+ *   `ACCOUNT_NOT_FUNDED` when the account cannot cover gas.
+ * @throws {@link UpshiftSDKError} while the SwapRouter is paused (checked before
+ * any approval), or on unrecoverable contract or RPC failure.
+ * @worstCaseRpcCalls 10 on the swap path into a Tokenized Vault V2 —
+ *   tokenized-vault metadata, reference asset + decimals, deposit-token
+ *   decimals, the vault's `assetsWhitelistAddress()`, `getWhitelistedAssets()`
+ *   and `sendersWhitelistAddress()`, the quote, the router's `isPaused()`,
+ *   the origin code's `origins` (none for the zero sentinel), and the
+ *   allowance read. The router reads, `getWhitelistedAssets()` and
+ *   `sendersWhitelistAddress()` are cached for 5 minutes, except `isPaused()`
+ *   (15 seconds).
+ * @example
+ * ```ts
+ * // USDT deposited into a USDC-reference vault → swapped to USDC en route.
+ * const hash = await upshiftSdk.evm.swapRouterDeposit({
+ *   chainId: 1,
+ *   vault: '0xe9b725010a9e419412ed67d0fa5f3a5f40159d32',
+ *   depositAsset: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   amount: '100',
+ *   slippageBps: 50,
+ * });
+ * ```
+ */
+export declare function swapRouterDeposit(signer: Signer | Wallet, options: ISwapRouterDepositOptions): Promise<string>;