upshift-finance 1.0.0

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

@@ -0,0 +1,1749 @@
+"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.vaultApprove = vaultApprove;
+exports.approve = approve;
+exports.vaultDeposit = vaultDeposit;
+exports.vaultRequestRedeem = vaultRequestRedeem;
+exports.vaultRedeem = vaultRedeem;
+exports.depositNative = depositNative;
+exports.rwaRedeemAsset = rwaRedeemAsset;
+exports.swapAndDeposit = swapAndDeposit;
+exports.depositViaSwapRouter = depositViaSwapRouter;
+exports.depositNativeViaSwapRouter = depositNativeViaSwapRouter;
+exports.swapRouterDeposit = swapRouterDeposit;
+const ethers_1 = require("ethers");
+const abis_1 = require("../../abis");
+const core_1 = require("../../core");
+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.AugustValidationError('INVALID_INPUT', `amount must be finite, got ${amount}`);
+    }
+    if (amount < 0) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `amount must be non-negative, got ${amount}`);
+    }
+    if (Number.isInteger(amount) && !Number.isSafeInteger(amount)) {
+        throw new core_1.AugustValidationError('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 `AugustSDKError.context`,
+ * never these.
+ * @internal
+ */
+const BROADCAST_HASH_KEY = 'augustBroadcastTxHash';
+/** @internal */
+const BROADCAST_UNKNOWN_KEY = 'augustConfirmationUnknown';
+/**
+ * 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
+ * `AugustSDKError.context`.
+ *
+ * @param tx - The broadcast transaction response to await.
+ * @returns The mined receipt (never `null` on the fallback paths; `tx.wait()`
+ *   itself may return `null` when the caller configured 0 confirmations).
+ * @throws {Error} `Transaction <hash> reverted on-chain` when the receipt
+ *   reports `status === 0`. Marked `confirmationUnknown: false` — the chain
+ *   answered.
+ * @throws {Error} `Transaction <hash> was not confirmed within <n>s` when the
+ *   overall wait times out with no receipt. Marked
+ *   `confirmationUnknown: true`.
+ * @throws The underlying transport error once receipt-poll retries are
+ *   exhausted, marked `confirmationUnknown: true`.
+ * @internal
+ */
+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 AugustValidationError}
+ * 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 {AugustValidationError} with code `ACCOUNT_NOT_FUNDED` when
+ *   `isInsufficient` is `true`.
+ */
+function throwIfInsufficientFunds(isInsufficient, operation, error, context) {
+    if (!isInsufficient)
+        return;
+    throw new core_1.AugustValidationError('ACCOUNT_NOT_FUNDED', `${operation} failed: insufficient native balance to cover gas/network fees`, { cause: error, context });
+}
+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.AugustValidationError('INVALID_ADDRESS', `vaultApprove: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', 'vaultApprove: amount is required');
+    }
+    validateAmountPrecision(amount);
+    try {
+        const tokenizedVault = (await (0, core_1.fetchTokenizedVault)(target))?.[0];
+        const vaultVersion = (0, core_1.getVaultVersionV2)(tokenizedVault);
+        const adapterConfig = (0, core_1.getVaultAdapterConfig)(target);
+        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 isAdapterDeposit = actualDepositAsset.toLowerCase() !== underlyingAsset.toLowerCase();
+        const spenderAddress = resolveSpender({
+            target,
+            isMultiAssetVault,
+            isAdapterDeposit,
+            adapterWrapperAddress: adapterConfig?.wrapperAddress,
+        });
+        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.AugustSDKError)
+            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.AugustSDKError('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). Returns `undefined` when the existing allowance already covers
+ * `amount` **or** when the deposit asset is native.
+ *
+ * @returns Transaction hash when an approval was sent, `undefined` when
+ *   the existing allowance already covers `amount` or the deposit asset is
+ *   native (no ERC-20 allowance applies). Use {@link approve} for a
+ *   discriminated `ApproveResult` if you need to tell those two cases apart.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultApprove({
+ *   target: '0x...',         // vault contract address
+ *   wallet: walletAddress,
+ *   amount: '100',           // 100 of the deposit token (UI units)
+ *   wait: true,              // wait for the approval to confirm
+ * });
+ * if (hash) console.log('approve tx', hash);
+ * // hash === undefined means the on-chain allowance already covers the
+ * // amount, or the deposit asset is native (msg.value, no allowance).
+ * ```
+ */
+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 augustSdk.evm.approve({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '100',
+ *   wait: true,
+ * });
+ * switch (r.kind) {
+ *   case 'sent':
+ *     showToast('Approval submitted', r.hash);
+ *     break;
+ *   case 'sufficient':
+ *     // r.existing is the existing on-chain allowance (raw bigint)
+ *     break;
+ *   case 'native':
+ *     // No allowance needed; native token will travel as msg.value
+ *     break;
+ * }
+ * ```
+ *
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the approval submission fails.
+ */
+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`.
+ *
+ * Amounts are encoded against the **deposit token's** decimals, not the
+ * vault's share decimals. The SDK reads the appropriate decimals via the
+ * vault metadata and the asset's ERC-20.
+ *
+ * Approval is handled automatically: if the existing allowance doesn't
+ * cover `amount`, an `approve` is sent and **always waited for** (regardless
+ * of the caller's `wait` flag) so the deposit tx can't be re-ordered ahead
+ * of the approval on Monad-style RPCs.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `depositAsset` for
+ *   adapter routes, optional `wait` to wait for the deposit receipt.
+ * @returns Deposit transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount or missing
+ *   adapter config when `depositAsset` differs from the vault underlying.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultDeposit({
+ *   target: '0xE9B725010A9E419412ed67d0fA5f3A5f40159D32', // vault
+ *   wallet: walletAddress,
+ *   amount: '100',         // 100 USDC (UI units)
+ *   wait: true,            // wait for the deposit receipt
+ * });
+ * ```
+ *
+ * @example Adapter deposit (different deposit asset than the vault's underlying)
+ * ```ts
+ * await augustSdk.evm.vaultDeposit({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '0.5',
+ *   depositAsset: WETH_ADDRESS,   // swap WETH -> vault underlying via the adapter
+ *   chainId: 1,
+ * });
+ * ```
+ */
+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.AugustValidationError('INVALID_ADDRESS', `vaultDeposit: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.AugustValidationError('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))?.[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 is the NATIVE path only — it never routes through the
+        // SwapRouter. 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.
+        if (isAdapterDeposit && !isMultiAssetVault && !adapterConfig) {
+            throw new core_1.AugustValidationError('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.`);
+        }
+        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 = resolveSpender({
+                target,
+                isMultiAssetVault,
+                isAdapterDeposit,
+                adapterWrapperAddress: adapterConfig?.wrapperAddress,
+            });
+            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 (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 (swap or native wrapper)
+            if (adapterConfig.bridgeId === 2) {
+                // Paraswap bridge - build swap and deposit transaction
+                const adapterContract = await (0, adapter_helpers_1.buildSwapAndDepositTransaction)({
+                    signer,
+                    srcToken: actualDepositAsset,
+                    srcDecimals: depositTokenDecimals,
+                    destToken: underlyingAsset,
+                    destDecimals: vaultDecimals,
+                    amount: normalizedAmt.raw.toString(),
+                    network: chainId?.toString() || '1',
+                    adapterConfig,
+                    userAddress: wallet,
+                });
+                const swapAndDepositParams = {
+                    amountIn: normalizedAmt.raw,
+                    minAmountOut: 0,
+                    srcToken: actualDepositAsset,
+                    dstToken: underlyingAsset,
+                    bridgeId: adapterConfig.bridgeId,
+                    quoteData: '0x', // This will be populated by buildSwapAndDepositTransaction
+                };
+                depositTx = await adapterContract
+                    .connect(signer)
+                    .swapAndDeposit(swapAndDepositParams);
+            }
+            else {
+                // Native/wrapped token deposit via wrapper contract
+                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.AugustSDKError)
+            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.AugustSDKError('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 this
+ * also handles the receipt-token allowance automatically. Pass
+ * `isInstantRedeem: true` for vaults that support instant settlement.
+ *
+ * Approval of the receipt token (EVM-2) is always waited on before the
+ * redeem call, regardless of the caller's `wait` flag.
+ *
+ * @param signer ethers Signer / Wallet (or viem WalletClient via {@link setSigner})
+ * @param options Vault address, wallet, amount, optional `isInstantRedeem`,
+ *   optional `wait` to wait for the redeem receipt.
+ * @returns Redeem transaction hash.
+ * @throws AugustValidationError on invalid wallet/target/amount.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * const hash = await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',           // 10 shares (UI units)
+ *   wait: true,
+ * });
+ * ```
+ *
+ * @example Instant redemption
+ * ```ts
+ * await augustSdk.evm.vaultRequestRedeem({
+ *   target: vaultAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   isInstantRedeem: true,
+ * });
+ * ```
+ */
+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.AugustValidationError('INVALID_ADDRESS', `vaultRequestRedeem: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.AugustValidationError('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))?.[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');
+            const receiptContract = (0, core_1.createContract)({
+                address: receiptTokenAddr,
+                provider: signer,
+                abi: abis_1.ABI_ERC20,
+            });
+            decimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultRequestRedeem:receiptDecimals');
+            // Convert amount to bignumber
+            const normalizedAmt = (0, core_1.toNormalizedBn)(amount, decimals);
+            // EVM-2 lp/receipt token is a separate ERC-20: vault.transferFrom(lp)
+            // needs explicit allowance even on self-redeem (msg.sender on the lp
+            // token is the vault, not the user — no ERC-4626 owner-shortcut).
+            const allowance = await receiptContract.allowance(wallet, target);
+            if (safeBigInt(allowance, 'vaultRequestRedeem:allowance') <
+                BigInt(normalizedAmt.raw)) {
+                const { hash: approveHash } = await safeSendTx(() => receiptContract.connect(signer).approve(target, normalizedAmt.raw), signer, true);
+                core_1.Logger.log.info('approve:receipt_token:tx_hash', approveHash);
+            }
+            // For evm-2, use vaultContract for both instant and standard redeem
+            // ABI_TOKENIZED_VAULT_V2 has both instantRedeem (2 params) and requestRedeem
+            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.AugustSDKError)
+            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.AugustSDKError('UNKNOWN', `Request redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, ...broadcast } });
+    }
+}
+/**
+ * @TODO
+ * @description withdraw funds from the specified pool including accrued rewards
+ * @param signer signer / wallet object
+ * @param options object including pool contract address, user wallet address, and more
+ * @returns claim tx hash
+ */
+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.AugustValidationError('INVALID_ADDRESS', `vaultRedeem: invalid ${!goodWallet ? 'wallet' : 'target'} address`);
+    }
+    if (!year || !month || !day || !receiverIndex) {
+        throw new core_1.AugustValidationError('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.AugustSDKError)
+            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.AugustSDKError('UNKNOWN', `Redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, {
+            cause: e,
+            context: { target, year, month, day, receiverIndex, ...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 AugustValidationError on invalid wrapper / receiver / amount.
+ * @throws AugustSDKError when the deposit submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * import { parseEther } from 'ethers';
+ *
+ * await augustSdk.evm.depositNative({
+ *   wrapperAddress: nativeWrapperAddress,
+ *   amount: parseEther('0.5'),   // 0.5 ETH in wei
+ *   wait: true,
+ * });
+ * ```
+ */
+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.AugustValidationError('INVALID_ADDRESS', 'depositNative: invalid wrapper address');
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.AugustValidationError('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.AugustValidationError('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.AugustSDKError)
+            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.AugustSDKError('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 AugustValidationError on invalid addresses or amount inputs.
+ * @throws AugustSDKError when the redeem submission or on-chain call fails.
+ *
+ * @example
+ * ```ts
+ * // 1. Approve the vault share token to the subaccount first.
+ * await augustSdk.evm.vaultApprove({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   amount: '10',
+ *   wait: true,
+ * });
+ *
+ * // 2. Redeem 10 shares for USDC, requiring at least 9.5 USDC out.
+ * await augustSdk.evm.rwaRedeemAsset({
+ *   target: subaccountAddress,
+ *   wallet: walletAddress,
+ *   asset: USDC_ADDRESS,
+ *   amount: '10',
+ *   minOut: '9.5',
+ *   decimals: 18,            // vault share decimals
+ *   outputDecimals: 6,       // USDC decimals
+ *   wait: true,
+ * });
+ * ```
+ */
+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.AugustValidationError('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.AugustSDKError)
+            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.AugustSDKError('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;
+    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.AugustValidationError('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.`, {
+                context: {
+                    vault: args.target,
+                    underlying: args.underlyingAsset,
+                    chainId: args.chainId,
+                    wrappedNative,
+                },
+            });
+        }
+        return depositNativeViaSwapRouter(args.signer, {
+            chainId: args.chainId,
+            vault: args.target,
+            receiver: sharesReceiver,
+            amount: amountRaw,
+            wait: args.wait,
+        });
+    }
+    const isUnderlying = args.actualDepositAsset.toLowerCase() ===
+        args.underlyingAsset.toLowerCase();
+    if (isUnderlying) {
+        return depositViaSwapRouter(args.signer, {
+            chainId: args.chainId,
+            vault: args.target,
+            receiver: sharesReceiver,
+            asset: args.actualDepositAsset,
+            amount: amountRaw,
+            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.AugustValidationError('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.AugustValidationError('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,
+        receiver: sharesReceiver,
+        swaps: [
+            {
+                tokenIn: args.actualDepositAsset,
+                tokenOut: args.underlyingAsset,
+                amountIn: amountRaw,
+                minAmountOut: quote.minAmountOut,
+                router: quote.router,
+                payload: quote.payload,
+            },
+        ],
+        wait: args.wait,
+    });
+}
+/** @internal */
+function resolveSwapRouterOrThrow(chainId) {
+    const router = (0, core_1.getSwapRouterAddress)(chainId);
+    if (!router) {
+        throw new core_1.AugustValidationError('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.AugustValidationError('INVALID_INPUT', 'swapAndDeposit: at least one swap leg is required');
+    }
+    if (swaps.length > core_1.SWAP_ROUTER_MAX_SWAPS) {
+        throw new core_1.AugustValidationError('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.AugustValidationError('INVALID_ADDRESS', `${where}.tokenIn is not a valid address`);
+    }
+    if (!(0, core_1.checkAddress)(swap.tokenOut, console, 'contract')) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `${where}.tokenOut is not a valid address`);
+    }
+    if (!(0, core_1.checkAddress)(swap.router, console, 'contract')) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `${where}.router is not a valid address`);
+    }
+    if (swap.tokenIn.toLowerCase() === swap.tokenOut.toLowerCase()) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `${where}: tokenIn and tokenOut are identical — no swap needed`);
+    }
+    if (swap.amountIn <= 0n) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', `${where}.amountIn must be greater than zero`);
+    }
+    if (swap.minAmountOut <= 0n) {
+        throw new core_1.AugustValidationError('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.AugustValidationError('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.AugustValidationError('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.AugustValidationError('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 AugustValidationError} for unsupported chains, invalid
+ * addresses, empty/oversized swap arrays.
+ * @throws {@link AugustSDKError} on unrecoverable contract or RPC failure.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * const hash = await swapAndDeposit(signer, {
+ *   chainId: 1,
+ *   vault: '0x8AcA0841993ef4C87244d519166e767f49362C21',
+ *   receiver: wallet,
+ *   swaps: [{
+ *     tokenIn: WBTC,
+ *     tokenOut: USDC,
+ *     amountIn: 100_000_000n,
+ *     minAmountOut: quote.minAmountOut,
+ *     router: quote.router,
+ *     payload: quote.payload,
+ *   }],
+ * });
+ * ```
+ */
+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.AugustValidationError('INVALID_ADDRESS', `swapAndDeposit: invalid ${!goodVault ? 'vault' : 'receiver'} address`);
+    }
+    ensureSwapsValid(swaps);
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    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,
+    });
+    const { hash } = await safeSendTx(() => routerContract
+        .connect(signer)
+        .swapAndDeposit((0, core_1.resolveOriginCode)(originCode), vault, receiver, swaps), signer, wait);
+    core_1.Logger.log.info('swapAndDeposit:tx_hash', hash);
+    return hash;
+}
+/**
+ * Deposit a vault's reference asset directly through the SwapRouter — no
+ * swap. Useful when the caller already holds the reference asset but wants
+ * the origin/referral fee accounting that only the SwapRouter path provides.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterDirectDepositOptions}.
+ * @returns The transaction hash of the `deposit` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
+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.AugustValidationError('INVALID_ADDRESS', 'depositViaSwapRouter: invalid address');
+    }
+    if (amount === 0n) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', 'depositViaSwapRouter: amount must be greater than zero');
+    }
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    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,
+    });
+    const { hash } = await safeSendTx(() => routerContract
+        .connect(signer)
+        .deposit((0, core_1.resolveOriginCode)(originCode), amount, vault, asset, receiver), signer, wait);
+    core_1.Logger.log.info('depositViaSwapRouter:tx_hash', hash);
+    return hash;
+}
+/**
+ * Deposit native ETH (or chain-native equivalent) into a vault via the
+ * SwapRouter. The router wraps `amount` to the chain's wrapped-native token
+ * before depositing — only valid when the vault's reference asset equals
+ * the wrapped-native token.
+ *
+ * No ERC-20 approval is needed; `amount` travels as `msg.value`.
+ *
+ * @param signer - ethers `Signer` or `Wallet`.
+ * @param options - {@link ISwapRouterNativeDepositOptions}.
+ * @returns The transaction hash of the `depositNativeToken` call.
+ *
+ * @throws {@link AugustValidationError} for unsupported chains, invalid
+ * addresses, or zero amount.
+ */
+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.AugustValidationError('INVALID_ADDRESS', 'depositNativeViaSwapRouter: invalid address');
+    }
+    if (amount === 0n) {
+        throw new core_1.AugustValidationError('INVALID_INPUT', 'depositNativeViaSwapRouter: amount must be greater than zero');
+    }
+    const routerAddress = resolveSwapRouterOrThrow(chainId);
+    const routerContract = (0, core_1.createContract)({
+        address: routerAddress,
+        provider: signer,
+        abi: abis_1.ABI_SWAP_ROUTER,
+    });
+    const { hash } = await safeSendTx(() => routerContract
+        .connect(signer)
+        .depositNativeToken((0, core_1.resolveOriginCode)(originCode), vault, receiver, {
+        value: amount,
+    }), signer, wait);
+    core_1.Logger.log.info('depositNativeViaSwapRouter:tx_hash', hash);
+    return hash;
+}
+/**
+ * Deposit into an August vault through the on-chain `SwapRouter`, selecting the
+ * correct router path from the deposit asset. This is the high-level, explicit
+ * counterpart to the SwapRouter branch inside {@link vaultDeposit}.
+ *
+ * Where `vaultDeposit` decides whether to use the SwapRouter from the
+ * `VAULTS_USING_SWAP_ROUTER` allowlist, this function always routes through the
+ * SwapRouter because the caller asked it to. Making the intent explicit is the
+ * point: a native-deposit vault (e.g. a multi-asset Tokenized Vault V2 whose
+ * non-reference assets are accepted directly) is never accidentally swapped —
+ * the regression that implicit, allowlist-driven routing caused. Use
+ * `vaultDeposit` for native / adapter deposits and this for SwapRouter deposits.
+ *
+ * The vault's reference asset and its decimals are read on-chain (never trusted
+ * from the caller — a wrong reference asset would mis-route the swap). The path
+ * is then chosen from `depositAsset`:
+ *  - equals the reference asset → direct router deposit, no swap
+ *    ({@link depositViaSwapRouter});
+ *  - the zero address → native-token deposit ({@link depositNativeViaSwapRouter}),
+ *    valid only when the reference asset is the chain's wrapped-native token;
+ *  - any other ERC-20 → a swap to the reference asset (Paraswap quote pinned to
+ *    the chain's whitelisted aggregator, fail-closed on router/selector drift)
+ *    bundled into {@link swapAndDeposit}.
+ *
+ * Side effects: reads tokenized-vault metadata, the vault's reference asset and
+ * decimals, and (on the swap path) one Paraswap quote; sends one ERC-20
+ * `approve` to the SwapRouter when allowance is short, then the deposit tx.
+ *
+ * @param signer - ethers `Signer` or `Wallet` that signs the approval + deposit.
+ * @param options - {@link ISwapRouterDepositOptions}.
+ * @returns The transaction hash of the router deposit call.
+ * @throws {@link AugustValidationError} for an unsupported chain (no SwapRouter
+ *   deployment), an invalid vault or deposit-asset address, a missing or zero
+ *   amount, a native deposit into a non-wrapped-native vault, or drift between
+ *   the aggregator quote and the on-chain router whitelist.
+ * @worstCaseRpcCalls 5 on the swap path — tokenized-vault metadata, reference
+ *   asset + decimals, deposit-token decimals, the quote, and the allowance read.
+ * @example
+ * ```ts
+ * // USDT deposited into a USDC-reference vault → swapped to USDC en route.
+ * const hash = await augustSdk.evm.swapRouterDeposit({
+ *   chainId: 1,
+ *   vault: '0xe9b725010a9e419412ed67d0fa5f3a5f40159d32',
+ *   depositAsset: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
+ *   amount: '100',
+ *   slippageBps: 50,
+ * });
+ * ```
+ */
+async function swapRouterDeposit(signer, options) {
+    const { chainId, vault, depositAsset, amount, receiver, slippageBps, wait } = options;
+    if (!(0, core_1.checkAddress)(vault, console, 'contract')) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `swapRouterDeposit: invalid vault address "${vault}"`);
+    }
+    if (!(0, core_1.checkAddress)(depositAsset, console, 'contract')) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `swapRouterDeposit: invalid depositAsset address "${depositAsset}"`);
+    }
+    if (amount === undefined || amount === null) {
+        throw new core_1.AugustValidationError('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))?.[0];
+    const isMultiAssetVault = (0, core_1.getVaultVersionV2)(tokenizedVault) === '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.AugustValidationError('INVALID_INPUT', 'swapRouterDeposit: amount must be greater than zero');
+    }
+    return dispatchViaSwapRouter({
+        signer,
+        routerAddress,
+        chainId,
+        target: vault,
+        wallet: eoa,
+        receiver,
+        actualDepositAsset: depositAsset,
+        underlyingAsset,
+        isNativeToken,
+        depositTokenDecimals,
+        normalizedAmt,
+        slippageBps,
+        wait,
+    });
+}
+//# sourceMappingURL=write.actions.js.map