@upshiftfinance/sdk 0.0.0-stage → 0.2.0

package/lib/modules/vaults/write.actions.js

@@ -0,0 +1,2377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeBigInt = safeBigInt;
+exports.resolveDepositTokenDecimals = resolveDepositTokenDecimals;
+exports.resolveSpender = resolveSpender;
+exports.validateAmountPrecision = validateAmountPrecision;
+exports.isNonceParsing = isNonceParsing;
+exports.safeWaitForTx = safeWaitForTx;
+exports.safeSendTx = safeSendTx;
+exports.tryRecoverTxHash = tryRecoverTxHash;
+exports.getDepositRoute = getDepositRoute;
+exports.vaultApprove = vaultApprove;
+exports.approve = approve;
+exports.vaultDeposit = vaultDeposit;
+exports.vaultRequestRedeem = vaultRequestRedeem;
+exports.vaultRedeem = vaultRedeem;
+exports.claimWithdrawal = claimWithdrawal;
+exports.depositNative = depositNative;
+exports.rwaRedeemAsset = rwaRedeemAsset;
+exports.swapAndDeposit = swapAndDeposit;
+exports.depositViaSwapRouter = depositViaSwapRouter;
+exports.depositNativeViaSwapRouter = depositNativeViaSwapRouter;
+exports.isNativeSwapRouterDepositSupported = isNativeSwapRouterDepositSupported;
+exports.swapRouterDeposit = swapRouterDeposit;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+const core_1 = require("../../core");
+const types_1 = require("../../types");
+const swap_quotes_1 = require("../../services/swap-quotes");
+const adapter_helpers_1 = require("./adapter.helpers");
+const utils_1 = require("./utils");
+// Treat unparseable RPC payloads (bare "0x", etc.) as 0n with a warn log —
+// the defensive default is "approve again," and the log surfaces flaky RPCs
+// before they cause silent gas waste from spurious approvals.
+/** @internal */
+function safeBigInt(value, context = 'safeBigInt') {
+    if (value === null || value === undefined)
+        return 0n;
+    const s = String(value);
+    if (s === '' || s === '0x') {
+        if (s === '0x') {
+            core_1.Logger.log.warn(context, 'RPC returned bare "0x"; treating as 0', {
+                raw: s,
+            });
+        }
+        return 0n;
+    }
+    try {
+        return BigInt(s);
+    }
+    catch (err) {
+        core_1.Logger.log.warn(context, 'Could not parse RPC value as BigInt; treating as 0', { raw: s, error: String(err) });
+        return 0n;
+    }
+}
+// EVM-0/1 single-asset underlying deposits reuse vaultDecimals (vault and
+// underlying decimals match under ERC-4626 inheritance), saving one RPC.
+// Multi-asset / adapter / non-underlying paths must read from the deposit
+// asset's own ERC-20 — using share decimals there silently misencodes amounts.
+/** @internal */
+async function resolveDepositTokenDecimals(args) {
+    const { actualDepositAsset, underlyingAsset, isNativeToken, isMultiAssetVault, vaultDecimals, readErc20Decimals, } = args;
+    if (isNativeToken)
+        return 18;
+    const isUnderlying = actualDepositAsset.toLowerCase() === underlyingAsset.toLowerCase();
+    if (isUnderlying && !isMultiAssetVault)
+        return vaultDecimals;
+    return readErc20Decimals(actualDepositAsset);
+}
+/** @internal */
+function resolveSpender(args) {
+    if (args.isMultiAssetVault)
+        return args.target;
+    if (args.isAdapterDeposit && args.adapterWrapperAddress)
+        return args.adapterWrapperAddress;
+    return args.target;
+}
+// Reject JS-number amounts past Number.MAX_SAFE_INTEGER — any larger
+// integer the caller passes is already wrong before we hit toNormalizedBn.
+/** @internal */
+function validateAmountPrecision(amount) {
+    if (typeof amount === 'string' || typeof amount === 'bigint')
+        return;
+    if (!Number.isFinite(amount)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `amount must be finite, got ${amount}`);
+    }
+    if (amount < 0) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `amount must be non-negative, got ${amount}`);
+    }
+    if (Number.isInteger(amount) && !Number.isSafeInteger(amount)) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `amount ${amount} exceeds Number.MAX_SAFE_INTEGER; pass a string or bigint to preserve precision`);
+    }
+}
+// Tries tx.wait() first (preserves replacement detection & revert checks), then falls back to
+// provider.waitForTransaction() for RPCs (e.g. Monad) that return malformed pending tx fields.
+const SAFE_WAIT_TIMEOUT_MS = 120_000;
+/** @internal */
+function isNonceParsing(error) {
+    const code = error?.code;
+    const msg = String(error).toLowerCase();
+    return ((code === 'INVALID_ARGUMENT' || code === 'BAD_DATA') &&
+        msg.includes('nonce'));
+}
+/**
+ * Own-properties stamped onto an error describing a transaction that already
+ * reached the network. Prefixed to avoid colliding with the `hash` /
+ * `transaction` / `receipt` fields ethers puts on its own errors.
+ *
+ * These are an internal wire format between the tx-wait helpers and the write
+ * paths' catch blocks — consumers read the *sanitized* form
+ * (`txHash` / `broadcast` / `confirmationUnknown`) off `UpshiftSDKError.context`,
+ * never these.
+ * @internal
+ */
+const BROADCAST_HASH_KEY = 'upshiftBroadcastTxHash';
+/** @internal */
+const BROADCAST_UNKNOWN_KEY = 'upshiftConfirmationUnknown';
+/**
+ * Stamp "this transaction was broadcast" onto an error, in place.
+ *
+ * Mutating rather than wrapping is deliberate: callers up the stack compare
+ * error identity (and ethers' own typed fields matter for downstream
+ * classification), so replacing the error object would lose information.
+ *
+ * Annotating is strictly best-effort. A frozen or sealed error, or one with a
+ * getter-only property of the same name, must never turn a *recoverable
+ * transport failure* into a `TypeError` thrown from inside the error handler —
+ * that would be a strictly worse outcome than losing the hash. Each write is
+ * therefore attempted independently and failures are swallowed; the caller then
+ * simply reports the transaction as un-annotated (no `txHash` in the error
+ * context), which is the same conservative state as "never broadcast".
+ *
+ * @param error - The error about to be thrown. Non-objects pass through
+ *   untouched — there is nowhere to put the marker.
+ * @param txHash - Hash of the transaction that reached the network.
+ * @param confirmationUnknown - `true` when the transaction is on the wire but
+ *   its outcome could not be determined (transport retries exhausted, or the
+ *   wait timed out). `false` when the chain gave a definitive answer, e.g. a
+ *   receipt with `status === 0`.
+ * @returns The same error instance (identity preserved), for
+ *   `throw markBroadcast(...)`.
+ * @internal
+ */
+function markBroadcast(error, txHash, confirmationUnknown) {
+    if (!error || typeof error !== 'object')
+        return error;
+    // `defineProperty` with configurable/writable keeps the marker invisible to
+    // JSON.stringify and to spreads of the error, so it can't leak into a
+    // serialized crash report as a mystery field.
+    const stamp = (key, value) => {
+        try {
+            Object.defineProperty(error, key, {
+                value,
+                enumerable: false,
+                writable: true,
+                configurable: true,
+            });
+        }
+        catch {
+            // Frozen/sealed error, or a non-configurable same-named property. The
+            // hash is a nice-to-have; never let annotation failure mask the real
+            // transport error we are in the middle of reporting.
+        }
+    };
+    stamp(BROADCAST_HASH_KEY, txHash);
+    stamp(BROADCAST_UNKNOWN_KEY, confirmationUnknown);
+    return error;
+}
+/**
+ * Read back the markers {@link markBroadcast} stamped, if any.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns The recovered hash and confirmation state; both `undefined` when the
+ *   error never passed through a tx-wait helper.
+ * @internal
+ */
+function readBroadcastMarkers(error) {
+    if (!error || typeof error !== 'object')
+        return {};
+    const e = error;
+    const txHash = e[BROADCAST_HASH_KEY];
+    const confirmationUnknown = e[BROADCAST_UNKNOWN_KEY];
+    return {
+        txHash: typeof txHash === 'string' ? txHash : undefined,
+        confirmationUnknown: typeof confirmationUnknown === 'boolean'
+            ? confirmationUnknown
+            : undefined,
+    };
+}
+/**
+ * Build the broadcast half of a failed write's structured error context, for a
+ * path that holds its main transaction in a local variable.
+ *
+ * The distinction this encodes, and which consumers branch on:
+ *
+ * - **no `txHash` key at all** — the write never reached the network. Nothing
+ *   is pending; it is safe to tell the user it failed and safe to retry.
+ * - **`txHash` + `broadcast: true` + `confirmationUnknown: true`** — the
+ *   transaction *is* on-chain (or in the mempool) and only the confirmation was
+ *   lost. Render a pending state against `txHash`; **do not** prompt a retry,
+ *   that is exactly how users double-spend a redeem.
+ * - **`txHash` + `broadcast: true` + `confirmationUnknown: false`** — the
+ *   transaction reached the chain and definitively failed (reverted). A real
+ *   error, with a hash the user can inspect on an explorer.
+ *
+ * `tx` is the gate on purpose. Several write paths broadcast an inner approval
+ * before the main call; if that approval's wait fails, the caught error carries
+ * *its* marker. Falling back to the error's marker here would make
+ * "Request redeem failed" report the approve hash and claim the redeem is
+ * pending when it was never sent.
+ *
+ * @param tx - The path's main transaction, or `undefined`/`null` when it was
+ *   never sent.
+ * @param error - The caught value, used only for the confirmation state.
+ * @returns A context fragment to spread into the thrown error's `context`.
+ *   Empty when nothing was broadcast.
+ * @internal
+ */
+function localTxBroadcastContext(tx, error) {
+    const txHash = tx?.hash;
+    if (!txHash)
+        return {};
+    const markers = readBroadcastMarkers(error);
+    return {
+        txHash,
+        broadcast: true,
+        // Only trust the marker when it describes *this* transaction.
+        confirmationUnknown: markers.txHash === txHash && markers.confirmationUnknown === true,
+    };
+}
+/**
+ * Same contract as {@link localTxBroadcastContext}, for write paths whose only
+ * transaction is sent through {@link safeSendTx} — there the hash never comes
+ * back to the caller on the failure path, so the error's own marker is the only
+ * source. Safe precisely because those paths send exactly one transaction, so
+ * the marker cannot belong to a different one.
+ *
+ * @param error - The caught value, of unknown type.
+ * @returns A context fragment to spread into the thrown error's `context`.
+ *   Empty when nothing was broadcast.
+ * @internal
+ */
+function errorTxBroadcastContext(error) {
+    const { txHash, confirmationUnknown } = readBroadcastMarkers(error);
+    if (!txHash)
+        return {};
+    return {
+        txHash,
+        broadcast: true,
+        confirmationUnknown: confirmationUnknown === true,
+    };
+}
+/**
+ * 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
+ */
+async function safeWaitForTx(tx) {
+    try {
+        return await tx.wait();
+    }
+    catch (error) {
+        const nonceParse = isNonceParsing(error);
+        // Not a shape we know how to recover from — surface it unchanged, but the
+        // tx is still on-chain (ethers reports a revert here), so keep the hash.
+        if (!nonceParse && !(0, core_1.isRetryableRpcError)(error)) {
+            throw markBroadcast(error, tx.hash, false);
+        }
+        const msg = error instanceof Error ? error.message : '';
+        core_1.Logger.log.warn(nonceParse
+            ? 'safeWaitForTx:fallback'
+            : 'safeWaitForTx:transport-fallback', msg, { hash: tx.hash });
+        // The nonce path keeps its original single-shot behaviour: the RPC is
+        // responsive, it just mis-serialized the pending tx. The transport path
+        // re-polls, because the provider itself is the thing that failed.
+        let receipt;
+        try {
+            receipt = nonceParse
+                ? await tx.provider.waitForTransaction(tx.hash, 1, SAFE_WAIT_TIMEOUT_MS)
+                : await (0, core_1.retryOnTransientRpc)('safeWaitForTx:transport-retry', () => tx.provider.waitForTransaction(tx.hash, 1, SAFE_WAIT_TIMEOUT_MS), { hash: tx.hash });
+        }
+        catch (pollError) {
+            // Retries exhausted. The transaction is on the wire and very likely
+            // mined; we simply could not read its receipt.
+            throw markBroadcast(pollError, tx.hash, true);
+        }
+        if (!receipt) {
+            throw markBroadcast(new Error(`Transaction ${tx.hash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`), tx.hash, true);
+        }
+        if (receipt.status === 0) {
+            // Definitive: the chain executed it and it failed. Not pending.
+            throw markBroadcast(new Error(`Transaction ${tx.hash} reverted on-chain`), tx.hash, false);
+        }
+        return receipt;
+    }
+}
+/**
+ * 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 */
+async function safeSendTx(contractCall, provider, shouldWait) {
+    try {
+        const tx = await contractCall();
+        if (shouldWait)
+            await safeWaitForTx(tx);
+        return { tx, hash: tx.hash };
+    }
+    catch (error) {
+        if (!isNonceParsing(error))
+            throw error;
+        // The tx was sent but ethers couldn't parse the response.
+        // Try to extract the hash from the error payload.
+        const errStr = String(error);
+        const hashMatch = errStr.match(/"hash"\s*:\s*"(0x[0-9a-fA-F]{64})"/);
+        if (!hashMatch?.[1])
+            throw error;
+        const txHash = hashMatch[1];
+        core_1.Logger.log.warn('safeSendTx:nonce-fallback', { txHash });
+        if (shouldWait) {
+            const signerProvider = 'provider' in provider ? provider.provider : provider;
+            const receipt = await signerProvider.waitForTransaction(txHash, 1, SAFE_WAIT_TIMEOUT_MS);
+            if (!receipt) {
+                throw markBroadcast(new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`), txHash, true);
+            }
+            if (receipt.status === 0) {
+                throw markBroadcast(new Error(`Transaction ${txHash} reverted on-chain`), txHash, false);
+            }
+        }
+        return { tx: null, hash: txHash };
+    }
+}
+/**
+ * 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 */
+async function tryRecoverTxHash(error, signer, wait) {
+    if (!isNonceParsing(error))
+        return null;
+    const hashMatch = String(error).match(/"hash"\s*:\s*"(0x[0-9a-fA-F]{64})"/);
+    if (!hashMatch?.[1])
+        return null;
+    const txHash = hashMatch[1];
+    if (wait) {
+        const provider = 'provider' in signer ? signer.provider : signer;
+        const receipt = await provider.waitForTransaction(txHash, 1, SAFE_WAIT_TIMEOUT_MS);
+        if (!receipt) {
+            throw markBroadcast(new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`), txHash, true);
+        }
+        if (receipt.status === 0) {
+            throw markBroadcast(new Error(`Transaction ${txHash} reverted on-chain`), txHash, false);
+        }
+    }
+    return txHash;
+}
+/**
+ * Rethrow a caught write-path error as a typed {@link UpshiftValidationError}
+ * when it is the chain node reporting the sender can't afford the transaction's
+ * gas/fee (see {@link isInsufficientFundsError}).
+ *
+ * Why: for an underfunded account ethers surfaces an opaque `CALL_EXCEPTION` /
+ * "missing revert data" that gives the caller no stable way to tell "user needs
+ * gas" apart from a genuine on-chain failure. Converting it to the
+ * `ACCOUNT_NOT_FUNDED` code lets a consuming UI branch on `err.code` (e.g. show
+ * a "top up to cover network fees" prompt) instead of string-matching. Every
+ * write path shares this so the classification is identical across
+ * deposit/redeem/approve rather than drifting per call site.
+ *
+ * A no-op when `isInsufficient` is `false`, so callers fall through to their
+ * existing handling unchanged. The caller passes the already-computed
+ * classification (it also feeds the telemetry-demotion decision) so
+ * {@link isInsufficientFundsError} runs once per catch, not twice.
+ *
+ * @param isInsufficient - Result of {@link isInsufficientFundsError} for
+ *   `error`, computed once by the caller and shared with the benign-log flag.
+ * @param operation - Human-readable label for the attempted write (e.g.
+ *   `'Request redeem'`), used verbatim in the thrown error's message.
+ * @param error - The caught value, of unknown type, preserved as the thrown
+ *   error's `cause`.
+ * @param context - Structured context attached to the thrown error for logging.
+ * @throws {UpshiftValidationError} with code `ACCOUNT_NOT_FUNDED` when
+ *   `isInsufficient` is `true`.
+ */
+function throwIfInsufficientFunds(isInsufficient, operation, error, context) {
+    if (!isInsufficient)
+        return;
+    throw new core_1.UpshiftValidationError('ACCOUNT_NOT_FUNDED', `${operation} failed: insufficient native balance to cover gas/network fees`, { cause: error, context });
+}
+/**
+ * Shared catch path for the SwapRouter write methods, with the same recovery
+ * and classification as `vaultDeposit`: recover a nonce-parse hash, pass typed
+ * SDK errors through, log (demoting user rejections and unfunded accounts),
+ * map insufficient funds to `ACCOUNT_NOT_FUNDED`, and wrap the rest.
+ * @internal
+ */
+async function handleSwapRouterWriteError(e, tx, signer, wait, operation, label, context) {
+    const recovered = await tryRecoverTxHash(e, signer, wait);
+    if (recovered) {
+        core_1.Logger.log.warn(`${operation}:nonce-fallback`, { hash: recovered });
+        return recovered;
+    }
+    if (e instanceof core_1.UpshiftSDKError)
+        throw e;
+    const ctx = { ...context, ...localTxBroadcastContext(tx, e) };
+    const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+    (0, core_1.logChainError)(operation, e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, ctx);
+    throwIfInsufficientFunds(insufficientFunds, label, e, ctx);
+    throw new core_1.UpshiftSDKError('UNKNOWN', `${label} failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: ctx });
+}
+/**
+ * The router vault type for an EVM vault: a multi-asset vault (`evm-2`) is a
+ * Tokenized Vault V2, any other EVM vault takes the ERC-4626
+ * `deposit(uint256, address)` interface.
+ * @internal
+ */
+function toSwapRouterVaultType(isMultiAssetVault) {
+    return isMultiAssetVault
+        ? types_1.SwapRouterVaultType.TokenizedVaultV2
+        : types_1.SwapRouterVaultType.ERC4626;
+}
+/**
+ * Whether a vault takes `asset` as-is: its reference asset (`asset()`), or,
+ * for a multi-asset Tokenized Vault V2, an asset on the vault's assets
+ * whitelist. Shared by the deposit-route resolver and the `swapRouterDeposit`
+ * dispatch so neither swaps an asset the vault accepts.
+ * @internal
+ */
+async function isAcceptedDirectly(signer, target, asset, underlyingAsset, isMultiAssetVault) {
+    const lower = asset.toLowerCase();
+    return (lower === underlyingAsset.toLowerCase() ||
+        (isMultiAssetVault &&
+            (await (0, core_1.getWhitelistedAssets)(signer, await (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+            }).assetsWhitelistAddress())).some((a) => a.toLowerCase() === lower)));
+}
+/** @internal */
+async function resolveDepositRoute(signer, args) {
+    const { target, chainId, actualDepositAsset, isMultiAssetVault } = args;
+    const asset = actualDepositAsset.toLowerCase();
+    const isNativeToken = actualDepositAsset === ethers_1.ZeroAddress;
+    const isAdapterDeposit = asset !== args.underlyingAsset.toLowerCase();
+    const wrapper = (0, core_1.getVaultAdapterConfig)(target)?.wrapperAddress;
+    const native = (reason) => ({
+        via: 'native',
+        spender: isNativeToken
+            ? null
+            : resolveSpender({
+                target,
+                isMultiAssetVault,
+                isAdapterDeposit,
+                adapterWrapperAddress: wrapper,
+            }),
+        reason,
+    });
+    const router = chainId ? (0, core_1.getSwapRouterAddress)(chainId) : undefined;
+    if (!chainId || !router)
+        return native('no-router');
+    if (args.isDepositWithPermit)
+        return native('permit');
+    if (isNativeToken)
+        return native('native-token');
+    if (isAdapterDeposit && !isMultiAssetVault && wrapper) {
+        return native('adapter');
+    }
+    if (args.vaultVersion === 'evm-0')
+        return native('legacy-pool');
+    if (!(await isAcceptedDirectly(signer, target, actualDepositAsset, args.underlyingAsset, isMultiAssetVault))) {
+        return native('asset-not-accepted');
+    }
+    if (isMultiAssetVault &&
+        (await (0, core_1.readVaultHasSendersWhitelist)(signer, chainId, target))) {
+        return native('kyc-vault');
+    }
+    // After the cached gates, so only a deposit that would otherwise route pays
+    // the short-TTL read; before the origin check, so a paused router falls back
+    // to native instead of throwing under strictOrigin.
+    if (await (0, core_1.readSwapRouterPaused)(signer, chainId)) {
+        return native('router-paused');
+    }
+    const route = {
+        via: 'router',
+        spender: router,
+        originCode: (0, core_1.resolveOriginCode)(undefined, chainId),
+        vaultType: toSwapRouterVaultType(isMultiAssetVault),
+    };
+    // The router reverts `InvalidOrigin` on a non-zero code that is not
+    // registered, so an unregistered instance code is replaced by the zero code
+    // and the deposit still routes.
+    if (route.originCode !== core_1.ORIGIN_CODES.default &&
+        !(await (0, core_1.readOriginInfo)(chainId, route.originCode, () => signer)).registered) {
+        if ((0, core_1.isStrictOrigin)()) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `attribution.originCode is not registered on the SwapRouter for chain ${chainId} and attribution.strictOrigin is set. Register it with addOrigin, or unset strictOrigin to deposit with the zero origin code.`, { context: { chainId, target } });
+        }
+        route.originCode = core_1.ORIGIN_CODES.default;
+        route.reason = 'origin-not-registered';
+    }
+    return route;
+}
+/**
+ * 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);
+ * ```
+ */
+async function getDepositRoute(signer, options) {
+    const { target, depositAsset } = options;
+    if (!(0, core_1.checkAddress)(target, console)) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'getDepositRoute: invalid target address');
+    }
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target, undefined, false, false))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const isMultiAssetVault = vaultVersion === 'evm-2';
+        const underlyingAsset = (await (0, core_1.createContract)({
+            address: target,
+            provider: signer,
+            abi: isMultiAssetVault ? abis_1.ABI_TOKENIZED_VAULT_V2 : abis_1.ABI_LENDING_POOLS,
+        }).asset());
+        return await resolveDepositRoute(signer, {
+            target,
+            chainId: tokenizedVault?.chain ?? options.chainId,
+            actualDepositAsset: depositAsset || underlyingAsset,
+            underlyingAsset,
+            isMultiAssetVault,
+            vaultVersion,
+            isDepositWithPermit: options.isDepositWithPermit,
+        });
+    }
+    catch (e) {
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        throw new core_1.UpshiftSDKError('UNKNOWN', `getDepositRoute failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, chainId: options.chainId } });
+    }
+}
+/**
+ * Report whether a deposit carried the instance origin code: the bounded
+ * `sdk.attribution.origin` tag (`applied` | `skipped` | `none`), the code only
+ * as a span attribute, and — when a configured code was not applied — a
+ * warning with the resolver's reason, which the logger also forwards to
+ * Sentry as a breadcrumb.
+ * @internal
+ */
+function trackOriginAttribution(route, context, operation = 'vaultDeposit') {
+    // A router route can carry the zero code (no code configured, or an
+    // unregistered one replaced), so attribution is `applied` only when a real
+    // code was sent, and `skipped` only when a configured code was not.
+    const configured = (0, core_1.resolveOriginCode)(undefined, context.chainId) !== core_1.ORIGIN_CODES.default;
+    const status = route.via === 'router' &&
+        route.originCode !== undefined &&
+        route.originCode !== core_1.ORIGIN_CODES.default
+        ? 'applied'
+        : configured
+            ? 'skipped'
+            : 'none';
+    if (status === 'skipped') {
+        core_1.Logger.log.warn(`${operation}:attribution-skipped`, {
+            reason: route.reason,
+            ...context,
+        });
+    }
+    if (!(0, core_1.isAnalyticsEnabled)())
+        return;
+    const sentry = (0, core_1.getSentrySDK)();
+    sentry?.setTag('sdk.attribution.origin', status);
+    if (status === 'applied') {
+        sentry
+            ?.getActiveSpan()
+            ?.setAttribute('sdk.attribution.origin_code', route.originCode);
+    }
+}
+async function approveCore(signer, options) {
+    const { wallet, target, wait, amount, depositAsset } = options;
+    const [goodWallet, goodPool] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodPool) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `vaultApprove: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'vaultApprove: amount is required');
+    }
+    validateAmountPrecision(amount);
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target, undefined, false, false))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const isMultiAssetVault = vaultVersion === 'evm-2';
+        const poolContract = isMultiAssetVault
+            ? (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+            })
+            : (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: abis_1.ABI_LENDING_POOLS,
+            });
+        let underlyingAsset;
+        let vaultDecimals;
+        if (isMultiAssetVault) {
+            const [asset, receiptTokenAddr] = await Promise.all([
+                poolContract.asset(),
+                // Retried on transport blips only; a misroute still throws. See
+                // getReceiptTokenAddressOrThrow.
+                (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultApprove:receiptToken'),
+            ]);
+            underlyingAsset = asset;
+            vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultApprove:receiptDecimals');
+        }
+        else {
+            const [asset, rawDecimals] = await Promise.all([
+                poolContract.asset(),
+                (0, core_1.getDecimalsOrThrow)(signer, target, 'vaultApprove:poolDecimals'),
+            ]);
+            underlyingAsset = asset;
+            vaultDecimals = rawDecimals;
+        }
+        const actualDepositAsset = (depositAsset || underlyingAsset);
+        const isNativeToken = actualDepositAsset === ethers_1.ZeroAddress ||
+            actualDepositAsset === '0x0000000000000000000000000000000000000000';
+        // Native tokens travel as msg.value — no ERC-20 allowance to grant.
+        if (isNativeToken)
+            return { kind: 'native' };
+        const spenderAddress = (await resolveDepositRoute(signer, {
+            target,
+            chainId: tokenizedVault?.chain ?? options.chainId,
+            actualDepositAsset,
+            underlyingAsset,
+            isMultiAssetVault,
+            vaultVersion,
+            isDepositWithPermit: options.isDepositWithPermit,
+        })).spender;
+        const depositTokenDecimals = await resolveDepositTokenDecimals({
+            actualDepositAsset,
+            underlyingAsset,
+            isNativeToken: false,
+            isMultiAssetVault,
+            vaultDecimals,
+            readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'vaultApprove:depositTokenDecimals'),
+        });
+        const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
+        const needed = BigInt(normalizedAmt.raw);
+        const tokenContract = (0, core_1.createContract)({
+            address: actualDepositAsset,
+            abi: abis_1.ABI_ERC20,
+            provider: signer,
+        });
+        const currentAllowance = await tokenContract.allowance(wallet, spenderAddress);
+        const existing = safeBigInt(currentAllowance, 'vaultApprove:allowance');
+        if (existing >= needed) {
+            core_1.Logger.log.info('approve:allowance-sufficient', {
+                target,
+                spender: spenderAddress,
+                amount,
+            });
+            return { kind: 'sufficient', existing };
+        }
+        const { hash: approvalHash } = await safeSendTx(() => tokenContract
+            .connect(signer)
+            .approve(spenderAddress, normalizedAmt.raw), signer, wait);
+        core_1.Logger.log.info('approve:tx_hash', approvalHash);
+        return { kind: 'sent', hash: approvalHash };
+    }
+    catch (e) {
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        // Only one tx is sent on this path, so any broadcast marker on the error
+        // necessarily describes the approval itself.
+        const broadcast = errorTxBroadcastContext(e);
+        // A user declining the approval in their wallet is product behaviour, not
+        // an SDK fault — demote it to a breadcrumb so it doesn't bill as an issue.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('vaultApprove', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Approval', e, {
+            target,
+            amount,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Approval failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, ...broadcast } });
+    }
+}
+/**
+ * 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).
+ * ```
+ */
+async function vaultApprove(signer, options) {
+    const result = await approveCore(signer, options);
+    return result.kind === 'sent' ? result.hash : 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.
+ */
+async function approve(signer, options) {
+    return approveCore(signer, options);
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function vaultDeposit(signer, options) {
+    const { wallet, target, wait, amount, depositAsset, chainId, poolName } = options;
+    const [goodWallet, goodPool] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodPool) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `vaultDeposit: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'vaultDeposit: amount is required');
+    }
+    validateAmountPrecision(amount);
+    // Hoisted out of the try so the catch can tell "the deposit was broadcast and
+    // we lost the confirmation" from "the deposit never left". Any inner approval
+    // tx is deliberately NOT tracked here — see localTxBroadcastContext.
+    let depositTx;
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target, undefined, false, false))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const adapterConfig = (0, core_1.getVaultAdapterConfig)(target);
+        let poolContract;
+        let underlyingAsset;
+        let vaultDecimals;
+        if (vaultVersion === 'evm-2') {
+            poolContract = (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: options?.isDepositWithPermit
+                    ? abis_1.ABI_TOKENIZED_VAULT_V2_DEPOSIT_WITH_PERMIT
+                    : abis_1.ABI_TOKENIZED_VAULT_V2,
+            });
+            const [asset, receiptTokenAddr] = await Promise.all([
+                poolContract.asset(),
+                // Retried on transport blips only; a misroute still throws. See
+                // getReceiptTokenAddressOrThrow.
+                (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultDeposit:receiptToken'),
+            ]);
+            underlyingAsset = asset;
+            vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultDeposit:receiptDecimals');
+        }
+        else {
+            poolContract = (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: abis_1.ABI_LENDING_POOLS,
+            });
+            const [fetchedUnderlyingAsset, rawDecimals] = await Promise.all([
+                poolContract.asset(),
+                (0, core_1.getDecimalsOrThrow)(signer, target, 'vaultDeposit:poolDecimals'),
+            ]);
+            vaultDecimals = rawDecimals;
+            underlyingAsset = fetchedUnderlyingAsset;
+        }
+        const actualDepositAsset = depositAsset || underlyingAsset;
+        const isNativeToken = actualDepositAsset === ethers_1.ZeroAddress ||
+            actualDepositAsset === '0x0000000000000000000000000000000000000000';
+        const isAdapterDeposit = actualDepositAsset.toLowerCase() !== underlyingAsset.toLowerCase();
+        const isMultiAssetVault = vaultVersion === 'evm-2';
+        // vaultDeposit never swaps. Any-token swap deposits are the explicit,
+        // opt-in job of {@link swapRouterDeposit}; keeping them out of here is what
+        // stops a natively-accepted asset from being silently swapped. The only
+        // SwapRouter use is a direct deposit of an asset the vault accepts.
+        if (isAdapterDeposit && !isMultiAssetVault && !adapterConfig) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `vaultDeposit: depositAsset ${actualDepositAsset} differs from vault underlying ${underlyingAsset} but no adapter is configured for vault ${target}. For an any-token deposit into a SwapRouter-eligible vault, use swapRouterDeposit instead.`);
+        }
+        // The Paraswap bridge adapter (`bridgeId === 2`) has no working deposit
+        // path in vaultDeposit: the SDK never built the Paraswap calldata, so the
+        // old branch sent `swapAndDeposit` with an empty quote and a zero
+        // `minAmountOut` — a transaction that could only revert, after an ERC-20
+        // approval had already been paid for. Refuse here, before the allowance
+        // check / approval below, so no on-chain write ever happens for this
+        // route. Callers wanting an any-token deposit use swapRouterDeposit.
+        if (isAdapterDeposit && adapterConfig?.bridgeId === 2) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `vaultDeposit: vault ${target} routes depositAsset ${actualDepositAsset} through a Paraswap bridge adapter, which vaultDeposit does not support. Use swapRouterDeposit for an any-token swap deposit, or deposit the vault's underlying asset ${underlyingAsset} directly.`);
+        }
+        const routeChainId = tokenizedVault?.chain ?? chainId;
+        const route = await resolveDepositRoute(signer, {
+            target,
+            chainId: routeChainId,
+            actualDepositAsset,
+            underlyingAsset,
+            isMultiAssetVault,
+            vaultVersion,
+            isDepositWithPermit: options?.isDepositWithPermit,
+        });
+        trackOriginAttribution(route, { chainId: routeChainId, target });
+        const depositTokenDecimals = await resolveDepositTokenDecimals({
+            actualDepositAsset,
+            underlyingAsset,
+            isNativeToken,
+            isMultiAssetVault,
+            vaultDecimals,
+            readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'vaultDeposit:depositTokenDecimals'),
+        });
+        const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
+        if (!isNativeToken) {
+            const spenderAddress = route.spender;
+            const depositTokenContract = (0, core_1.createContract)({
+                address: actualDepositAsset,
+                provider: signer,
+                abi: abis_1.ABI_ERC20,
+            });
+            const currentAllowance = await depositTokenContract.allowance(wallet, spenderAddress);
+            if (safeBigInt(currentAllowance, 'vaultDeposit:allowance') <
+                BigInt(normalizedAmt.raw)) {
+                const { hash: approveHash } = await safeSendTx(() => depositTokenContract
+                    .connect(signer)
+                    .approve(spenderAddress, normalizedAmt.raw), signer, true);
+                core_1.Logger.log.info('approve:tx_hash', approveHash);
+            }
+        }
+        // Route to appropriate deposit method
+        if (route.via === 'router') {
+            depositTx = await (0, core_1.createContract)({
+                address: route.spender,
+                provider: signer,
+                abi: abis_1.ABI_SWAP_ROUTER,
+            })
+                .connect(signer)
+                .deposit(route.originCode, normalizedAmt.raw, target, route.vaultType, actualDepositAsset, wallet);
+        }
+        else if (isMultiAssetVault) {
+            if (options?.isDepositWithPermit) {
+                // depositWithPermit flow
+                // build structure hash of permit off chain
+                const deadline = (0, utils_1.createDeadline)();
+                //sign the hash with private key of depositor
+                const { v, r, s } = await (0, utils_1.generatePermitSignature)(actualDepositAsset, wallet, await poolContract.getAddress(), normalizedAmt.raw, deadline, signer, tokenizedVault.chain);
+                //actually call depositWithPermit func
+                const { hash: permitHash } = await safeSendTx(() => poolContract
+                    .connect(signer)
+                    .depositWithPermit(actualDepositAsset, normalizedAmt.raw, wallet, deadline, r, s, v), signer, wait);
+                core_1.Logger.log.info('deposit:tx_hash', permitHash);
+                return permitHash;
+            }
+            // Multi-asset vault deposit (EVM-2)
+            depositTx = await poolContract
+                .connect(signer)
+                .deposit(actualDepositAsset, normalizedAmt.raw, wallet);
+        }
+        else if (isAdapterDeposit && adapterConfig) {
+            // Adapter deposit: native/wrapped token deposit via wrapper contract.
+            // (The Paraswap bridge route was rejected above, before any approval.)
+            const nativeDepositConfig = await (0, adapter_helpers_1.buildNativeDepositTransaction)({
+                signer,
+                srcToken: actualDepositAsset,
+                amount: normalizedAmt.raw.toString(),
+                poolName,
+                adapterConfig,
+                userAddress: wallet,
+            });
+            depositTx = await nativeDepositConfig.contract
+                .connect(signer)[nativeDepositConfig.functionName](...nativeDepositConfig.args, nativeDepositConfig.value ? { value: nativeDepositConfig.value } : {});
+        }
+        else {
+            // Standard deposit
+            if (isNativeToken) {
+                // Native ETH/AVAX deposit
+                depositTx = await poolContract
+                    .connect(signer)
+                    .deposit(normalizedAmt.raw, wallet, { value: normalizedAmt.raw });
+            }
+            else {
+                // Standard ERC20 deposit
+                depositTx = await poolContract
+                    .connect(signer)
+                    .deposit(normalizedAmt.raw, wallet);
+            }
+        }
+        if (wait)
+            await safeWaitForTx(depositTx);
+        core_1.Logger.log.info('deposit:tx_hash', depositTx?.hash);
+        return depositTx?.hash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('deposit:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        // depositTx is only ever unset here when the depositWithPermit sub-path
+        // threw — that branch sends its single main tx through safeSendTx and
+        // never assigns depositTx, so the error's own markBroadcast marker is the
+        // only place the broadcast hash survives. Every other sub-path assigns
+        // depositTx before this catch can run.
+        const broadcast = depositTx
+            ? localTxBroadcastContext(depositTx, e)
+            : errorTxBroadcastContext(e);
+        // User-cancelled deposits are normal; only genuine failures stay at error.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('deposit', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+            depositAsset,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Deposit', e, {
+            target,
+            amount,
+            depositAsset,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Deposit failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, depositAsset, ...broadcast } });
+    }
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function vaultRequestRedeem(signer, options) {
+    const { wallet, target, wait, amount } = options;
+    const [goodWallet, goodPool] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodPool) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `vaultRequestRedeem: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'vaultRequestRedeem: amount is required');
+    }
+    validateAmountPrecision(amount);
+    // Hoisted out of the try so the catch can tell "the redeem was broadcast and
+    // we lost the confirmation" from "the redeem never left". The EVM-2 receipt
+    // token approval sent earlier in the try is deliberately NOT tracked here:
+    // a failed approval means the redeem itself was never sent.
+    let requestRedeemTx;
+    try {
+        // Get vault version to determine correct ABI
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target, undefined, false, false))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        let poolContract;
+        let decimals;
+        // Handle different vault versions
+        if (vaultVersion === 'evm-2') {
+            // For evm-2, always use ABI_TOKENIZED_VAULT_V2 to get lpTokenAddress
+            // even for instant redeem, we need lpTokenAddress for receipt token decimals
+            const vaultContract = (0, core_1.createContract)({
+                address: target,
+                provider: signer,
+                abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+            });
+            // Get receipt token for decimals. Retried on transport blips only; a
+            // misroute (a non-evm-2 vault reaching this branch) still throws the
+            // original error. See getReceiptTokenAddressOrThrow.
+            const receiptTokenAddr = await (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultRequestRedeem:receiptToken');
+            decimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultRequestRedeem:receiptDecimals');
+            // Queued requestRedeem escrows the shares in the vault through
+            // receipt.transferFrom(user → vault): the vault is the spender, so it
+            // needs an explicit allowance even on self-redeem (without it the call
+            // reverts with ERC20InsufficientAllowance). instantRedeem burns the
+            // caller's shares directly and needs none.
+            if (!options.isInstantRedeem) {
+                const receiptContract = (0, core_1.createContract)({
+                    address: receiptTokenAddr,
+                    provider: signer,
+                    abi: abis_1.ABI_ERC20,
+                });
+                const sharesRaw = (0, core_1.toNormalizedBn)(amount, decimals).raw;
+                const allowance = await receiptContract.allowance(wallet, target);
+                if (safeBigInt(allowance, 'vaultRequestRedeem:allowance') <
+                    BigInt(sharesRaw)) {
+                    const { hash: approveHash } = await safeSendTx(() => receiptContract.connect(signer).approve(target, sharesRaw), signer, true);
+                    core_1.Logger.log.info('approve:receipt_token:tx_hash', approveHash);
+                }
+            }
+            poolContract = vaultContract;
+        }
+        else {
+            poolContract = options.isInstantRedeem
+                ? (0, core_1.createContract)({
+                    address: target,
+                    provider: signer,
+                    abi: abis_1.ABI_LENDING_POOL_V3,
+                })
+                : (0, core_1.createContract)({
+                    address: target,
+                    provider: signer,
+                    abi: abis_1.ABI_LENDING_POOLS,
+                });
+            decimals = await (0, core_1.getDecimalsOrThrow)(signer, target, 'vaultRequestRedeem:poolDecimals');
+        }
+        // Convert amount to bignumber (for non-evm-2 vaults)
+        const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
+        // Withdraw from vault - EVM-2 uses 2 params, others use 3 params
+        if (options.isInstantRedeem) {
+            if (vaultVersion === 'evm-2') {
+                // EVM-2: instantRedeem(uint256 shares, address receiverAddr) - 2 params
+                requestRedeemTx = await poolContract
+                    .connect(signer)
+                    .instantRedeem(BigInt(normalizedAmt.raw), wallet);
+            }
+            else {
+                // EVM-0/EVM-1: instantRedeem(uint256 shares, address receiverAddr, address holderAddr) - 3 params
+                requestRedeemTx = await poolContract
+                    .connect(signer)
+                    .instantRedeem(BigInt(normalizedAmt.raw), wallet, wallet);
+            }
+        }
+        else if (vaultVersion === 'evm-2') {
+            // EVM-2: requestRedeem(uint256 shares, address receiverAddr)
+            requestRedeemTx = await poolContract
+                .connect(signer)
+                .requestRedeem(BigInt(normalizedAmt.raw), wallet);
+        }
+        else {
+            // EVM-0/EVM-1: requestRedeem(uint256 shares, address receiver, address owner)
+            requestRedeemTx = await poolContract
+                .connect(signer)
+                .requestRedeem(BigInt(normalizedAmt.raw), wallet, wallet);
+        }
+        if (wait)
+            await safeWaitForTx(requestRedeemTx);
+        core_1.Logger.log.info('requestRedeem:tx_hash', requestRedeemTx?.hash);
+        return requestRedeemTx?.hash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('requestRedeem:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        const broadcast = localTxBroadcastContext(requestRedeemTx, e);
+        // User-cancelled redeem requests are normal; only genuine failures stay at error.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('requestRedeem', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            amount,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Request redeem', e, {
+            target,
+            amount,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Request redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, ...broadcast } });
+    }
+}
+/**
+ * @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
+ */
+async function vaultRedeem(signer, options) {
+    const { wallet, target, wait, year, day, month, receiverIndex } = options;
+    const [goodWallet, goodPool] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodPool) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `vaultRedeem: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (!year || !month || !day || !receiverIndex) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'vaultRedeem: year, month, day, and receiverIndex are required');
+    }
+    try {
+        const poolContract = (0, core_1.createContract)({
+            address: target,
+            provider: signer,
+            abi: abis_1.ABI_LENDING_POOLS,
+        });
+        const { hash: redeemHash } = await safeSendTx(() => poolContract
+            .connect(signer)
+            .redeem(year, month, day, receiverIndex, wallet), signer, wait);
+        core_1.Logger.log.info('redeem:tx_hash', redeemHash);
+        return redeemHash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('redeem:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        // Single tx on this path, so the error's own marker can only be the redeem.
+        const broadcast = errorTxBroadcastContext(e);
+        // User-cancelled redeems are normal; only genuine failures stay at error.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('redeem', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            year,
+            month,
+            day,
+            receiverIndex,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Redeem', e, {
+            target,
+            year,
+            month,
+            day,
+            receiverIndex,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+            cause: e,
+            context: { target, year, month, day, receiverIndex, ...broadcast },
+        });
+    }
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function claimWithdrawal(signer, options) {
+    const { wallet, target, wait, year, month, day, receiver } = options;
+    const [goodWallet, goodTarget] = [
+        (0, core_1.checkAddress)(wallet, console, 'wallet'),
+        (0, core_1.checkAddress)(target, console),
+    ];
+    if (!goodWallet || !goodTarget) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `claimWithdrawal: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (receiver !== undefined && !(0, core_1.checkAddress)(receiver, console, 'wallet')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'claimWithdrawal: invalid receiver address');
+    }
+    if (year === undefined || month === undefined || day === undefined) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'claimWithdrawal: year, month, and day are required');
+    }
+    const yearRaw = (0, core_1.toRawBigInt)(year, 'claimWithdrawal', 'year');
+    const monthRaw = (0, core_1.toRawBigInt)(month, 'claimWithdrawal', 'month');
+    const dayRaw = (0, core_1.toRawBigInt)(day, 'claimWithdrawal', 'day');
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target, undefined, false, false))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        if (vaultVersion !== 'evm-2') {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `claimWithdrawal: only EVM-2 (Tokenized Vault V2) vaults expose claim() — ${target} resolved to ${vaultVersion}`);
+        }
+        const vaultContract = (0, core_1.createContract)({
+            address: target,
+            provider: signer,
+            abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const { hash: claimHash } = await safeSendTx(() => vaultContract
+            .connect(signer)
+            .claim(yearRaw, monthRaw, dayRaw, receiver ?? wallet), signer, wait);
+        core_1.Logger.log.info('claim:tx_hash', claimHash);
+        return claimHash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('claim:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        const broadcast = errorTxBroadcastContext(e);
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('claim', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            year,
+            month,
+            day,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Claim withdrawal', e, {
+            target,
+            year,
+            month,
+            day,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Claim withdrawal failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+            cause: e,
+            context: { target, year, month, day, ...broadcast },
+        });
+    }
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function depositNative(signer, options) {
+    const { wrapperAddress, receiver, amount, wait } = options;
+    const goodWrapper = (0, core_1.checkAddress)(wrapperAddress, console, 'contract');
+    if (!goodWrapper) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'depositNative: invalid wrapper address');
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'depositNative: amount is required');
+    }
+    validateAmountPrecision(amount);
+    // Hoisted so the catch can distinguish "broadcast, confirmation lost" from
+    // "never sent" — see localTxBroadcastContext.
+    let depositTx;
+    try {
+        // Create wrapper contract instance
+        const wrapperContract = (0, core_1.createContract)({
+            address: wrapperAddress,
+            provider: signer,
+            abi: abis_1.ABI_MULTI_ASSET_NATIVE_DEPOSIT_WRAPPER,
+        }); // TODO: provide typed interface
+        // Convert amount to bigint (native tokens use 18 decimals typically)
+        // For native deposits, amount should be in wei/smallest unit
+        const amountBigInt = typeof amount === 'bigint'
+            ? amount
+            : typeof amount === 'string'
+                ? BigInt(amount)
+                : BigInt(amount);
+        // Connect the contract first, then get the function to disambiguate between overloads
+        const connectedContract = wrapperContract.connect(signer);
+        // Call depositNative with or without receiver parameter
+        if (receiver) {
+            const goodReceiver = (0, core_1.checkAddress)(receiver, console, 'wallet');
+            if (!goodReceiver) {
+                throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'depositNative: invalid receiver address');
+            }
+            // depositNative(address receiver) - with receiver
+            const depositNativeWithReceiver = connectedContract.getFunction('depositNative(address)');
+            depositTx = await depositNativeWithReceiver(receiver, {
+                value: amountBigInt,
+            });
+        }
+        else {
+            // depositNative() - without receiver (uses msg.sender as receiver)
+            const depositNativeNoParams = connectedContract.getFunction('depositNative()');
+            depositTx = await depositNativeNoParams({
+                value: amountBigInt,
+            });
+        }
+        if (wait)
+            await safeWaitForTx(depositTx);
+        core_1.Logger.log.info('depositNative:tx_hash', depositTx?.hash);
+        return depositTx?.hash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('depositNative:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        const broadcast = localTxBroadcastContext(depositTx, e);
+        // User-cancelled native deposits are normal; only genuine failures stay at error.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('depositNative', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            wrapperAddress,
+            receiver,
+            amount,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'Deposit native', e, {
+            wrapperAddress,
+            receiver,
+            amount,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `Deposit native failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { wrapperAddress, receiver, amount, ...broadcast } });
+    }
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function rwaRedeemAsset(signer, options) {
+    const { target, wallet, asset, amount, minOut, decimals, outputDecimals, wait, } = options;
+    const goodTarget = (0, core_1.checkAddress)(target, console, 'contract');
+    const goodAsset = (0, core_1.checkAddress)(asset, console, 'contract');
+    const goodWallet = (0, core_1.checkAddress)(wallet, console, 'wallet');
+    if (!goodTarget || !goodAsset || !goodWallet) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `rwaRedeemAsset: invalid ${!goodTarget ? 'target' : !goodAsset ? 'asset' : 'wallet'} address`);
+    }
+    validateAmountPrecision(amount);
+    validateAmountPrecision(minOut);
+    try {
+        const subaccountContract = (0, core_1.createContract)({
+            address: target,
+            provider: signer,
+            abi: abis_1.RWA_REDEEM_SUBACCOUNT,
+        });
+        if (!subaccountContract) {
+            throw new Error(`rwaRedeemAsset: failed to instantiate subaccount contract at ${target}`);
+        }
+        const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
+        const normalizedMinOut = (0, core_1.toNormalizedBn)(minOut, outputDecimals);
+        const { hash: redeemHash } = await safeSendTx(() => subaccountContract
+            .connect(signer)
+            .redeemAsset(asset, BigInt(normalizedAmt.raw), BigInt(normalizedMinOut.raw)), signer, wait);
+        core_1.Logger.log.info('rwaRedeemAsset:tx_hash', redeemHash);
+        return redeemHash;
+    }
+    catch (e) {
+        const recovered = await tryRecoverTxHash(e, signer, wait);
+        if (recovered) {
+            core_1.Logger.log.warn('rwaRedeemAsset:nonce-fallback', { hash: recovered });
+            return recovered;
+        }
+        if (e instanceof core_1.UpshiftSDKError)
+            throw e;
+        // Single tx on this path, so the error's own marker can only be the redeem.
+        const broadcast = errorTxBroadcastContext(e);
+        // User-cancelled RWA redeems are normal; only genuine failures stay at error.
+        const insufficientFunds = (0, core_1.isInsufficientFundsError)(e);
+        (0, core_1.logChainError)('rwaRedeemAsset', e, (0, core_1.isUserRejectionError)(e) || insufficientFunds, {
+            target,
+            asset,
+            amount,
+            minOut,
+            ...broadcast,
+        });
+        throwIfInsufficientFunds(insufficientFunds, 'RWA redeem', e, {
+            target,
+            asset,
+            amount,
+            minOut,
+            ...broadcast,
+        });
+        throw new core_1.UpshiftSDKError('UNKNOWN', `RWA redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, asset, amount, minOut, ...broadcast } });
+    }
+}
+/** @internal */
+async function dispatchViaSwapRouter(args) {
+    const amountRaw = BigInt(args.normalizedAmt.raw);
+    const sharesReceiver = args.receiver ?? args.wallet;
+    const vaultType = toSwapRouterVaultType(args.isMultiAssetVault);
+    if (args.isNativeToken) {
+        // SwapRouter native path requires underlying === wrapped native.
+        const wrappedNative = core_1.SWAP_ROUTER_WRAPPED_NATIVE[args.chainId];
+        if (!wrappedNative ||
+            args.underlyingAsset.toLowerCase() !== wrappedNative.toLowerCase()) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `vaultDeposit (SwapRouter): native deposit is only supported when the vault's reference asset is the chain's wrapped-native token. Vault ${args.target} underlying ${args.underlyingAsset} is not. Wrap to ${wrappedNative ?? 'WETH'} first and call again with depositAsset = the wrapped token. Check isNativeSwapRouterDepositSupported(chainId, vault, options) before offering this path to avoid hitting this error.`, {
+                context: {
+                    vault: args.target,
+                    underlying: args.underlyingAsset,
+                    chainId: args.chainId,
+                    wrappedNative,
+                },
+            });
+        }
+        return depositNativeViaSwapRouter(args.signer, {
+            chainId: args.chainId,
+            vault: args.target,
+            vaultType,
+            receiver: sharesReceiver,
+            amount: amountRaw,
+            originCode: args.originCode,
+            wait: args.wait,
+        });
+    }
+    const isUnderlying = args.actualDepositAsset.toLowerCase() ===
+        args.underlyingAsset.toLowerCase();
+    if (isUnderlying ||
+        (args.isMultiAssetVault &&
+            (await isAcceptedDirectly(args.signer, args.target, args.actualDepositAsset, args.underlyingAsset, true)))) {
+        return depositViaSwapRouter(args.signer, {
+            chainId: args.chainId,
+            vault: args.target,
+            vaultType,
+            receiver: sharesReceiver,
+            asset: args.actualDepositAsset,
+            amount: amountRaw,
+            originCode: args.originCode,
+            wait: args.wait,
+        });
+    }
+    // Vault share decimals can diverge from the underlying asset decimals
+    // (e.g. an 18-decimal share token over an 8-decimal WBTC underlying on
+    // a multi-asset v2 vault). The swap quote must use the underlying's
+    // on-chain decimals so Paraswap's /prices interprets the route correctly.
+    const underlyingDecimals = await (0, core_1.getDecimalsOrThrow)(args.signer, args.underlyingAsset, 'dispatchViaSwapRouter:underlyingDecimals');
+    // The on-chain SwapRouter only authorizes a specific (router, selector) pair
+    // per chain (see SWAP_ROUTER_DEX_AGGREGATOR). Pin the aggregator to that
+    // router's single generic method so the calldata selector is deterministic,
+    // then reject any quote that would not match — otherwise the deposit reverts
+    // on-chain with InvalidRouter() / InvalidNotWhitelisted() after the user has
+    // already paid gas.
+    const aggregator = core_1.SWAP_ROUTER_DEX_AGGREGATOR[args.chainId];
+    if (!aggregator) {
+        throw new core_1.UpshiftValidationError('INVALID_CHAIN', `vaultDeposit (SwapRouter): no DEX aggregator is configured for chainId ${args.chainId}, but a swap is required because the deposit asset (${args.actualDepositAsset}) differs from the vault's reference asset (${args.underlyingAsset}). Deposit the reference asset directly, or add a SWAP_ROUTER_DEX_AGGREGATOR entry once the router is whitelisted on-chain.`, {
+            context: {
+                chainId: args.chainId,
+                depositAsset: args.actualDepositAsset,
+                underlyingAsset: args.underlyingAsset,
+            },
+        });
+    }
+    const quote = await (0, swap_quotes_1.fetchSwapQuote)({
+        chainId: args.chainId,
+        srcToken: args.actualDepositAsset,
+        srcDecimals: args.depositTokenDecimals,
+        destToken: args.underlyingAsset,
+        destDecimals: underlyingDecimals,
+        amount: amountRaw,
+        receiver: args.routerAddress,
+        slippageBps: args.slippageBps,
+        contractMethod: aggregator.contractMethod,
+    });
+    // Fail closed on off-chain/on-chain config drift: if the aggregator's quote
+    // targets a router or selector the deployed SwapRouter has not whitelisted,
+    // the swapAndDeposit call would revert. Surfacing it here turns a wasted gas
+    // burn into an actionable SDK error.
+    const quotedSelector = quote.payload.slice(0, 10).toLowerCase();
+    if (quote.router.toLowerCase() !== aggregator.router.toLowerCase() ||
+        quotedSelector !== aggregator.selector.toLowerCase()) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `vaultDeposit (SwapRouter): the aggregator quote (router ${quote.router}, selector ${quotedSelector}) does not match the router whitelisted on chain ${args.chainId} (router ${aggregator.router}, selector ${aggregator.selector}); the on-chain SwapRouter would revert. This signals drift between the SDK's SWAP_ROUTER_DEX_AGGREGATOR and the deployed router's enableRouter config.`, {
+            context: {
+                chainId: args.chainId,
+                quotedRouter: quote.router,
+                quotedSelector,
+                expectedRouter: aggregator.router,
+                expectedSelector: aggregator.selector,
+            },
+        });
+    }
+    return swapAndDeposit(args.signer, {
+        chainId: args.chainId,
+        vault: args.target,
+        vaultType,
+        receiver: sharesReceiver,
+        swaps: [
+            {
+                tokenIn: args.actualDepositAsset,
+                tokenOut: args.underlyingAsset,
+                amountIn: amountRaw,
+                minAmountOut: quote.minAmountOut,
+                router: quote.router,
+                payload: quote.payload,
+            },
+        ],
+        originCode: args.originCode,
+        wait: args.wait,
+    });
+}
+/**
+ * Resolve the origin code a SwapRouter write method sends and check its
+ * registration before any approval or transaction, so an unregistered code
+ * never costs the user a reverted deposit. A code passed to the call must be
+ * registered or the call throws. An unregistered instance code falls back to
+ * the zero sentinel with the same `attribution-skipped` signal as
+ * `vaultDeposit`, or throws under `attribution.strictOrigin`. The zero
+ * sentinel is sent without a read.
+ * @internal
+ */
+async function resolveRouterOriginCode(signer, operation, chainId, vault, provided) {
+    const code = (0, core_1.resolveOriginCode)(provided, chainId);
+    if (code === core_1.ORIGIN_CODES.default ||
+        (await (0, core_1.readOriginInfo)(chainId, code, () => signer)).registered) {
+        return code;
+    }
+    if (provided !== undefined) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: originCode is not registered on the SwapRouter for chain ${chainId}. Register it with addOrigin (check it with getOriginInfo), or pass a registered code.`, { context: { chainId, vault } });
+    }
+    if ((0, core_1.isStrictOrigin)()) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: attribution.originCode is not registered on the SwapRouter for chain ${chainId} and attribution.strictOrigin is set. Register it with addOrigin, or unset strictOrigin to deposit without an origin code.`, { context: { chainId, vault } });
+    }
+    trackOriginAttribution({ via: 'native', spender: null, reason: 'origin-not-registered' }, { chainId, target: vault }, operation);
+    return core_1.ORIGIN_CODES.default;
+}
+/**
+ * Throw before any approval when the chain's SwapRouter is paused. Every
+ * router entry point reverts with `ContractIsPaused` while it is paused, so an
+ * approval sent first would only cost the user gas. Unlike `vaultDeposit`,
+ * these methods have no native path to fall back to: the caller asked for the
+ * router.
+ * @internal
+ */
+async function assertSwapRouterNotPaused(signer, operation, chainId, vault) {
+    if (!(await (0, core_1.readSwapRouterPaused)(signer, chainId)))
+        return;
+    throw new core_1.UpshiftSDKError('UNKNOWN', `${operation}: the SwapRouter on chain ${chainId} is paused and rejects every deposit. Deposit into the vault directly with vaultDeposit, or retry once the router is unpaused.`, { context: { chainId, vault, reason: 'router-paused' } });
+}
+/**
+ * Reject a legacy `evm-0` lending pool on an explicit SwapRouter path. The v2
+ * router has no vault registry to keep such pools off it, and they were never
+ * tested against its ERC-4626 deposit call, so {@link getDepositRoute} keeps
+ * them native (`legacy-pool`) and the explicit methods refuse them up front.
+ *
+ * @param operation - Calling method, used in the error message.
+ * @param vault - Vault the deposit targets.
+ * @param vaultVersion - The vault's version from {@link getVaultVersionV2}.
+ * @throws {@link UpshiftValidationError} when `vaultVersion` is `evm-0`.
+ * @internal
+ */
+function assertNotLegacyPool(operation, vault, vaultVersion) {
+    if (vaultVersion === 'evm-0') {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: vault ${vault} is a legacy lending pool, which the SwapRouter does not support. Deposit with vaultDeposit instead.`, { context: { vault } });
+    }
+}
+/**
+ * The vault type a SwapRouter write sends, after checking the router can
+ * deposit into the vault: the caller's `vaultType` when given, else derived
+ * from the vault's version in the Upshift API (`evm-2` → Tokenized Vault V2,
+ * any other EVM vault → ERC-4626).
+ *
+ * Runs before any approval, so a vault the router cannot serve is refused
+ * without the user paying for an approval and a reverting deposit. The v2
+ * router has no vault registry, so this replaces the registration gate: a
+ * legacy `evm-0` pool is refused, and so is a Tokenized Vault V2 with a
+ * senders whitelist (KYC), whose deposit would revert because the router is
+ * not a whitelisted sender.
+ *
+ * @param signer - Signer or provider used for the senders-whitelist read.
+ * @param operation - Calling method, used in error messages.
+ * @param chainId - Chain the vault is on.
+ * @param vault - Vault the deposit targets.
+ * @param provided - Optional caller-supplied vault type.
+ * @returns The vault type to send to the router.
+ * @throws {@link UpshiftValidationError} when `provided` is not a known vault
+ *   type; when it is omitted and the vault is not in the Upshift API (pass
+ *   `vaultType` explicitly for such a vault) or is a legacy `evm-0` pool; or
+ *   when a Tokenized Vault V2 has a senders whitelist.
+ * @worstCaseRpcCalls 2 — one Upshift API read when `provided` is omitted, and
+ *   one `sendersWhitelistAddress()` read for a Tokenized Vault V2 (cached for
+ *   5 minutes).
+ * @internal
+ */
+async function resolveRouterVaultType(signer, operation, chainId, vault, provided) {
+    let vaultType;
+    if (provided !== undefined) {
+        if (provided !== types_1.SwapRouterVaultType.ERC4626 &&
+            provided !== types_1.SwapRouterVaultType.TokenizedVaultV2) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: vaultType must be ${types_1.SwapRouterVaultType.ERC4626} (ERC4626) or ${types_1.SwapRouterVaultType.TokenizedVaultV2} (TokenizedVaultV2), got ${provided}`, { context: { vault, vaultType: provided } });
+        }
+        vaultType = provided;
+    }
+    else {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, undefined, false, false))?.[0];
+        if (!tokenizedVault) {
+            throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: vault ${vault} is not in the Upshift API, so its SwapRouter vault type cannot be derived. Pass vaultType explicitly.`, { context: { vault } });
+        }
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        assertNotLegacyPool(operation, vault, vaultVersion);
+        vaultType = toSwapRouterVaultType(vaultVersion === 'evm-2');
+    }
+    if (vaultType === types_1.SwapRouterVaultType.TokenizedVaultV2 &&
+        (await (0, core_1.readVaultHasSendersWhitelist)(signer, chainId, vault))) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${operation}: vault ${vault} has a senders whitelist (KYC), so the SwapRouter cannot deposit into it. Deposit with vaultDeposit instead.`, { context: { vault, chainId } });
+    }
+    return vaultType;
+}
+/** @internal */
+function resolveSwapRouterOrThrow(chainId) {
+    const router = (0, core_1.getSwapRouterAddress)(chainId);
+    if (!router) {
+        throw new core_1.UpshiftValidationError('INVALID_CHAIN', `SwapRouter: no deployment registered for chainId ${chainId}`, { context: { chainId } });
+    }
+    return router;
+}
+/** @internal */
+async function ensureAllowance(signer, token, owner, spender, amount) {
+    const tokenContract = (0, core_1.createContract)({
+        address: token,
+        provider: signer,
+        abi: abis_1.ABI_ERC20,
+    });
+    const current = safeBigInt(await tokenContract.allowance(owner, spender), 'swapRouter:allowance');
+    if (current >= amount)
+        return;
+    const { hash } = await safeSendTx(() => tokenContract.connect(signer).approve(spender, amount), signer, true);
+    core_1.Logger.log.info('swapRouter:approve:tx_hash', hash);
+}
+/** @internal */
+function ensureSwapsValid(swaps) {
+    if (swaps.length === 0) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'swapAndDeposit: at least one swap leg is required');
+    }
+    if (swaps.length > core_1.SWAP_ROUTER_MAX_SWAPS) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `swapAndDeposit: too many swaps (${swaps.length} > ${core_1.SWAP_ROUTER_MAX_SWAPS})`, { context: { count: swaps.length, max: core_1.SWAP_ROUTER_MAX_SWAPS } });
+    }
+    for (let i = 0; i < swaps.length; i += 1) {
+        validateSwapParams(swaps[i], i);
+    }
+}
+/** @internal */
+function validateSwapParams(swap, index) {
+    const where = `swapAndDeposit: swaps[${index}]`;
+    if (!(0, core_1.checkAddress)(swap.tokenIn, console, 'contract')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `${where}.tokenIn is not a valid address`);
+    }
+    if (!(0, core_1.checkAddress)(swap.tokenOut, console, 'contract')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `${where}.tokenOut is not a valid address`);
+    }
+    if (!(0, core_1.checkAddress)(swap.router, console, 'contract')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `${where}.router is not a valid address`);
+    }
+    if (swap.tokenIn.toLowerCase() === swap.tokenOut.toLowerCase()) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${where}: tokenIn and tokenOut are identical — no swap needed`);
+    }
+    if (swap.amountIn <= 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${where}.amountIn must be greater than zero`);
+    }
+    if (swap.minAmountOut <= 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${where}.minAmountOut must be greater than zero — slippage protection cannot be disabled`);
+    }
+    if (!/^0x[0-9a-fA-F]+$/.test(swap.payload) || swap.payload.length < 10) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${where}.payload must be ABI-encoded calldata (got "${swap.payload.slice(0, 12)}…")`);
+    }
+}
+/** @internal */
+function totalInputPerToken(swaps) {
+    const totals = new Map();
+    for (const swap of swaps) {
+        const key = swap.tokenIn.toLowerCase();
+        totals.set(key, (totals.get(key) ?? 0n) + swap.amountIn);
+    }
+    return totals;
+}
+// Allowance owner must equal msg.sender (contract uses transferFrom(msg.sender, ...));
+// smart-account wallets need explicit handling outside the SDK.
+/** @internal */
+async function resolveSignerEOA(signer, callerContext) {
+    const getAddress = signer.getAddress;
+    if (typeof getAddress !== 'function') {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', `${callerContext}: signer must implement getAddress(); got ${typeof getAddress}`);
+    }
+    const eoa = await getAddress.call(signer);
+    if (!eoa || !(0, core_1.checkAddress)(eoa, console, 'wallet')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `${callerContext}: signer.getAddress() returned an invalid address: ${String(eoa)}`);
+    }
+    return eoa;
+}
+/**
+ * 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,
+ *   }],
+ * });
+ * ```
+ */
+async function swapAndDeposit(signer, options) {
+    const { chainId, vault, receiver, swaps, originCode, wait } = options;
+    const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');
+    const goodReceiver = (0, core_1.checkAddress)(receiver, console, 'wallet');
+    if (!goodVault || !goodReceiver) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `swapAndDeposit: invalid ${!goodVault ? 'vault' : 'receiver'} address`);
+    }
+    ensureSwapsValid(swaps);
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    let tx;
+    try {
+        await assertSwapRouterNotPaused(signer, 'swapAndDeposit', chainId, vault);
+        const vaultType = await resolveRouterVaultType(signer, 'swapAndDeposit', chainId, vault, options.vaultType);
+        const origin = await resolveRouterOriginCode(signer, 'swapAndDeposit', chainId, vault, originCode);
+        const eoa = await resolveSignerEOA(signer, 'swapAndDeposit');
+        for (const [tokenIn, totalIn] of totalInputPerToken(swaps)) {
+            await ensureAllowance(signer, tokenIn, eoa, routerAddress, totalIn);
+        }
+        const routerContract = (0, core_1.createContract)({
+            address: routerAddress,
+            provider: signer,
+            abi: abis_1.ABI_SWAP_ROUTER,
+        });
+        tx = (await routerContract
+            .connect(signer)
+            .swapAndDeposit(origin, vault, vaultType, receiver, swaps));
+        if (wait)
+            await safeWaitForTx(tx);
+        core_1.Logger.log.info('swapAndDeposit:tx_hash', tx.hash);
+        return tx.hash;
+    }
+    catch (e) {
+        return handleSwapRouterWriteError(e, tx, signer, wait, 'swapAndDeposit', 'Swap and deposit', { chainId, vault });
+    }
+}
+/**
+ * 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.
+ */
+async function depositViaSwapRouter(signer, options) {
+    const { chainId, vault, receiver, asset, amount, originCode, wait } = options;
+    const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');
+    const goodReceiver = (0, core_1.checkAddress)(receiver, console, 'wallet');
+    const goodAsset = (0, core_1.checkAddress)(asset, console, 'contract');
+    if (!goodVault || !goodReceiver || !goodAsset) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'depositViaSwapRouter: invalid address');
+    }
+    if (amount === 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'depositViaSwapRouter: amount must be greater than zero');
+    }
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    let tx;
+    try {
+        await assertSwapRouterNotPaused(signer, 'depositViaSwapRouter', chainId, vault);
+        const vaultType = await resolveRouterVaultType(signer, 'depositViaSwapRouter', chainId, vault, options.vaultType);
+        const origin = await resolveRouterOriginCode(signer, 'depositViaSwapRouter', chainId, vault, originCode);
+        const eoa = await resolveSignerEOA(signer, 'depositViaSwapRouter');
+        await ensureAllowance(signer, asset, eoa, routerAddress, amount);
+        const routerContract = (0, core_1.createContract)({
+            address: routerAddress,
+            provider: signer,
+            abi: abis_1.ABI_SWAP_ROUTER,
+        });
+        tx = (await routerContract
+            .connect(signer)
+            .deposit(origin, amount, vault, vaultType, asset, receiver));
+        if (wait)
+            await safeWaitForTx(tx);
+        core_1.Logger.log.info('depositViaSwapRouter:tx_hash', tx.hash);
+        return tx.hash;
+    }
+    catch (e) {
+        return handleSwapRouterWriteError(e, tx, signer, wait, 'depositViaSwapRouter', 'SwapRouter deposit', { chainId, vault });
+    }
+}
+/**
+ * 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.
+ */
+async function depositNativeViaSwapRouter(signer, options) {
+    const { chainId, vault, receiver, amount, originCode, wait } = options;
+    const goodVault = (0, core_1.checkAddress)(vault, console, 'contract');
+    const goodReceiver = (0, core_1.checkAddress)(receiver, console, 'wallet');
+    if (!goodVault || !goodReceiver) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', 'depositNativeViaSwapRouter: invalid address');
+    }
+    if (amount === 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'depositNativeViaSwapRouter: amount must be greater than zero');
+    }
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    let tx;
+    try {
+        await assertSwapRouterNotPaused(signer, 'depositNativeViaSwapRouter', chainId, vault);
+        const vaultType = await resolveRouterVaultType(signer, 'depositNativeViaSwapRouter', chainId, vault, options.vaultType);
+        const origin = await resolveRouterOriginCode(signer, 'depositNativeViaSwapRouter', chainId, vault, originCode);
+        const routerContract = (0, core_1.createContract)({
+            address: routerAddress,
+            provider: signer,
+            abi: abis_1.ABI_SWAP_ROUTER,
+        });
+        tx = (await routerContract
+            .connect(signer)
+            .depositNativeToken(origin, vault, vaultType, receiver, {
+            value: amount,
+        }));
+        if (wait)
+            await safeWaitForTx(tx);
+        core_1.Logger.log.info('depositNativeViaSwapRouter:tx_hash', tx.hash);
+        return tx.hash;
+    }
+    catch (e) {
+        return handleSwapRouterWriteError(e, tx, signer, wait, 'depositNativeViaSwapRouter', 'SwapRouter native deposit', { chainId, vault });
+    }
+}
+/**
+ * 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
+ * ```
+ */
+async function isNativeSwapRouterDepositSupported(chainId, vault, options) {
+    const wrappedNative = core_1.SWAP_ROUTER_WRAPPED_NATIVE[chainId];
+    const routerAddress = (0, core_1.getSwapRouterAddress)(chainId);
+    if (!wrappedNative || !routerAddress)
+        return false;
+    try {
+        const provider = (0, core_1.createProvider)(options.rpcUrl, chainId);
+        const vaultContract = (0, core_1.createContract)({
+            address: vault,
+            provider,
+            abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const asset = (await vaultContract.asset());
+        return asset.toLowerCase() === wrappedNative.toLowerCase();
+    }
+    catch (error) {
+        core_1.Logger.log.warn('isNativeSwapRouterDepositSupported', 'vault read failed — treating as unsupported', { vault, chainId, error });
+        return false;
+    }
+}
+/**
+ * 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,
+ * });
+ * ```
+ */
+async function swapRouterDeposit(signer, options) {
+    try {
+        return await swapRouterDepositCore(signer, options);
+    }
+    catch (e) {
+        return handleSwapRouterWriteError(e, undefined, signer, options.wait, 'swapRouterDeposit', 'Swap router deposit', { chainId: options.chainId, vault: options.vault });
+    }
+}
+/** @internal */
+async function swapRouterDepositCore(signer, options) {
+    const { chainId, vault, depositAsset, amount, receiver, slippageBps, originCode, wait, } = options;
+    if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `swapRouterDeposit: invalid vault address "${vault}"`);
+    }
+    if (!(0, core_1.checkAddress)(depositAsset, console, 'contract')) {
+        throw new core_1.UpshiftValidationError('INVALID_ADDRESS', `swapRouterDeposit: invalid depositAsset address "${depositAsset}"`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'swapRouterDeposit: amount is required');
+    }
+    validateAmountPrecision(amount);
+    // Explicit opt-in: resolve the router straight from chainId rather than
+    // consulting VAULTS_USING_SWAP_ROUTER, so this path never depends on the
+    // implicit allowlist that could route a native-deposit vault through a swap.
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    const eoa = await resolveSignerEOA(signer, 'swapRouterDeposit');
+    // Reference asset + decimals from the vault on-chain. Mirrors vaultDeposit's
+    // metadata resolution so the deposit-token decimals (and therefore the raw
+    // amount) match exactly; kept separate to leave the vaultDeposit money path
+    // untouched.
+    const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(vault, undefined, false, false))?.[0];
+    const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+    assertNotLegacyPool('swapRouterDeposit', vault, vaultVersion);
+    const isMultiAssetVault = vaultVersion === 'evm-2';
+    let underlyingAsset;
+    let vaultDecimals;
+    if (isMultiAssetVault) {
+        const poolContract = (0, core_1.createContract)({
+            address: vault,
+            provider: signer,
+            abi: abis_1.ABI_TOKENIZED_VAULT_V2,
+        });
+        const [asset, receiptTokenAddr] = await Promise.all([
+            poolContract.asset(),
+            // Retried on transport blips only; a misroute still throws. See
+            // getReceiptTokenAddressOrThrow.
+            (0, core_1.getReceiptTokenAddressOrThrow)(signer, vault, 'swapRouterDeposit:receiptToken'),
+        ]);
+        underlyingAsset = asset;
+        vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'swapRouterDeposit:receiptDecimals');
+    }
+    else {
+        const poolContract = (0, core_1.createContract)({
+            address: vault,
+            provider: signer,
+            abi: abis_1.ABI_LENDING_POOLS,
+        });
+        const [asset, rawDecimals] = await Promise.all([
+            poolContract.asset(),
+            (0, core_1.getDecimalsOrThrow)(signer, vault, 'swapRouterDeposit:poolDecimals'),
+        ]);
+        underlyingAsset = asset;
+        vaultDecimals = rawDecimals;
+    }
+    const isNativeToken = depositAsset === ethers_1.ZeroAddress ||
+        depositAsset === '0x0000000000000000000000000000000000000000';
+    const depositTokenDecimals = await resolveDepositTokenDecimals({
+        actualDepositAsset: depositAsset,
+        underlyingAsset,
+        isNativeToken,
+        isMultiAssetVault,
+        vaultDecimals,
+        readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'swapRouterDeposit:depositTokenDecimals'),
+    });
+    const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
+    if (BigInt(normalizedAmt.raw) === 0n) {
+        throw new core_1.UpshiftValidationError('INVALID_INPUT', 'swapRouterDeposit: amount must be greater than zero');
+    }
+    return dispatchViaSwapRouter({
+        signer,
+        routerAddress,
+        chainId,
+        target: vault,
+        wallet: eoa,
+        receiver,
+        actualDepositAsset: depositAsset,
+        underlyingAsset,
+        isNativeToken,
+        isMultiAssetVault,
+        depositTokenDecimals,
+        normalizedAmt,
+        slippageBps,
+        originCode,
+        wait,
+    });
+}
+//# sourceMappingURL=write.actions.js.map