@augustdigital/sdk 8.17.0 → 8.20.1

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

@@ -97,25 +97,233 @@ function isNonceParsing(error) {
     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) {
-        if (isNonceParsing(error)) {
-            const msg = error instanceof Error ? error.message : '';
-            core_1.Logger.log.warn('safeWaitForTx:fallback', msg, { hash: tx.hash });
-            const receipt = await tx.provider.waitForTransaction(tx.hash, 1, SAFE_WAIT_TIMEOUT_MS);
-            if (!receipt) {
-                throw new Error(`Transaction ${tx.hash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`);
-            }
-            if (receipt.status === 0) {
-                throw new Error(`Transaction ${tx.hash} reverted on-chain`);
-            }
-            return receipt;
+        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);
         }
-        throw error;
+        return receipt;
     }
 }
 /**
@@ -148,10 +356,10 @@ async function safeSendTx(contractCall, provider, shouldWait) {
             const signerProvider = 'provider' in provider ? provider.provider : provider;
             const receipt = await signerProvider.waitForTransaction(txHash, 1, SAFE_WAIT_TIMEOUT_MS);
             if (!receipt) {
-                throw new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`);
+                throw markBroadcast(new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`), txHash, true);
             }
             if (receipt.status === 0) {
-                throw new Error(`Transaction ${txHash} reverted on-chain`);
+                throw markBroadcast(new Error(`Transaction ${txHash} reverted on-chain`), txHash, false);
             }
         }
         return { tx: null, hash: txHash };
@@ -177,10 +385,10 @@ async function tryRecoverTxHash(error, signer, wait) {
         const provider = 'provider' in signer ? signer.provider : signer;
         const receipt = await provider.waitForTransaction(txHash, 1, SAFE_WAIT_TIMEOUT_MS);
         if (!receipt) {
-            throw new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`);
+            throw markBroadcast(new Error(`Transaction ${txHash} was not confirmed within ${SAFE_WAIT_TIMEOUT_MS / 1000}s`), txHash, true);
         }
         if (receipt.status === 0) {
-            throw new Error(`Transaction ${txHash} reverted on-chain`);
+            throw markBroadcast(new Error(`Transaction ${txHash} reverted on-chain`), txHash, false);
         }
     }
     return txHash;
@@ -252,23 +460,20 @@ async function approveCore(signer, options) {
         if (isMultiAssetVault) {
             const [asset, receiptTokenAddr] = await Promise.all([
                 poolContract.asset(),
-                poolContract.lpTokenAddress(),
+                // Retried on transport blips only; a misroute still throws. See
+                // getReceiptTokenAddressOrThrow.
+                (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultApprove:receiptToken'),
             ]);
             underlyingAsset = asset;
-            const receiptContract = (0, core_1.createContract)({
-                address: receiptTokenAddr,
-                provider: signer,
-                abi: abis_1.ABI_ERC20,
-            });
-            vaultDecimals = Number(await receiptContract.decimals());
+            vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultApprove:receiptDecimals');
         }
         else {
             const [asset, rawDecimals] = await Promise.all([
                 poolContract.asset(),
-                poolContract.decimals(),
+                (0, core_1.getDecimalsOrThrow)(signer, target, 'vaultApprove:poolDecimals'),
             ]);
             underlyingAsset = asset;
-            vaultDecimals = Number(rawDecimals);
+            vaultDecimals = rawDecimals;
         }
         const actualDepositAsset = (depositAsset || underlyingAsset);
         const isNativeToken = actualDepositAsset === ethers_1.ZeroAddress ||
@@ -289,14 +494,7 @@ async function approveCore(signer, options) {
             isNativeToken: false,
             isMultiAssetVault,
             vaultDecimals,
-            readErc20Decimals: async (addr) => {
-                const erc20 = (0, core_1.createContract)({
-                    address: addr,
-                    provider: signer,
-                    abi: abis_1.ABI_ERC20,
-                });
-                return Number(await erc20.decimals());
-            },
+            readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'vaultApprove:depositTokenDecimals'),
         });
         const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
         const needed = BigInt(normalizedAmt.raw);
@@ -324,18 +522,23 @@ async function approveCore(signer, options) {
     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 } });
+        throw new core_1.AugustSDKError('UNKNOWN', `Approval failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, ...broadcast } });
     }
 }
 /**
@@ -457,6 +660,10 @@ async function vaultDeposit(signer, options) {
         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);
@@ -474,15 +681,12 @@ async function vaultDeposit(signer, options) {
             });
             const [asset, receiptTokenAddr] = await Promise.all([
                 poolContract.asset(),
-                poolContract.lpTokenAddress(),
+                // Retried on transport blips only; a misroute still throws. See
+                // getReceiptTokenAddressOrThrow.
+                (0, core_1.getReceiptTokenAddressOrThrow)(signer, target, 'vaultDeposit:receiptToken'),
             ]);
             underlyingAsset = asset;
-            const receiptContract = (0, core_1.createContract)({
-                address: receiptTokenAddr,
-                provider: signer,
-                abi: abis_1.ABI_ERC20,
-            });
-            vaultDecimals = Number(await receiptContract.decimals());
+            vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'vaultDeposit:receiptDecimals');
         }
         else {
             poolContract = (0, core_1.createContract)({
@@ -492,9 +696,9 @@ async function vaultDeposit(signer, options) {
             });
             const [fetchedUnderlyingAsset, rawDecimals] = await Promise.all([
                 poolContract.asset(),
-                poolContract.decimals(),
+                (0, core_1.getDecimalsOrThrow)(signer, target, 'vaultDeposit:poolDecimals'),
             ]);
-            vaultDecimals = Number(rawDecimals);
+            vaultDecimals = rawDecimals;
             underlyingAsset = fetchedUnderlyingAsset;
         }
         const actualDepositAsset = depositAsset || underlyingAsset;
@@ -515,14 +719,7 @@ async function vaultDeposit(signer, options) {
             isNativeToken,
             isMultiAssetVault,
             vaultDecimals,
-            readErc20Decimals: async (addr) => {
-                const erc20 = (0, core_1.createContract)({
-                    address: addr,
-                    provider: signer,
-                    abi: abis_1.ABI_ERC20,
-                });
-                return Number(await erc20.decimals());
-            },
+            readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'vaultDeposit:depositTokenDecimals'),
         });
         const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
         if (!isNativeToken) {
@@ -546,7 +743,6 @@ async function vaultDeposit(signer, options) {
                 core_1.Logger.log.info('approve:tx_hash', approveHash);
             }
         }
-        let depositTx;
         // Route to appropriate deposit method
         if (isMultiAssetVault) {
             if (options?.isDepositWithPermit) {
@@ -638,19 +834,29 @@ async function vaultDeposit(signer, options) {
         }
         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 } });
+        throw new core_1.AugustSDKError('UNKNOWN', `Deposit failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, depositAsset, ...broadcast } });
     }
 }
 /**
@@ -702,6 +908,11 @@ async function vaultRequestRedeem(signer, options) {
         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];
@@ -717,14 +928,16 @@ async function vaultRequestRedeem(signer, options) {
                 provider: signer,
                 abi: abis_1.ABI_TOKENIZED_VAULT_V2,
             });
-            // Get receipt token for decimals
-            const receiptTokenAddr = (await vaultContract.lpTokenAddress());
+            // 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 = Number(await receiptContract.decimals());
+            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)
@@ -752,12 +965,11 @@ async function vaultRequestRedeem(signer, options) {
                     provider: signer,
                     abi: abis_1.ABI_LENDING_POOLS,
                 });
-            decimals = await poolContract.decimals();
+            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
-        let requestRedeemTx;
         if (options.isInstantRedeem) {
             if (vaultVersion === 'evm-2') {
                 // EVM-2: instantRedeem(uint256 shares, address receiverAddr) - 2 params
@@ -797,17 +1009,20 @@ async function vaultRequestRedeem(signer, options) {
         }
         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 } });
+        throw new core_1.AugustSDKError('UNKNOWN', `Request redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, amount, ...broadcast } });
     }
 }
 /**
@@ -849,6 +1064,8 @@ async function vaultRedeem(signer, options) {
         }
         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, {
@@ -857,6 +1074,7 @@ async function vaultRedeem(signer, options) {
             month,
             day,
             receiverIndex,
+            ...broadcast,
         });
         throwIfInsufficientFunds(insufficientFunds, 'Redeem', e, {
             target,
@@ -864,8 +1082,12 @@ async function vaultRedeem(signer, options) {
             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 },
         });
-        throw new core_1.AugustSDKError('UNKNOWN', `Redeem failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { target, year, month, day, receiverIndex } });
     }
 }
 /**
@@ -906,6 +1128,9 @@ async function depositNative(signer, options) {
         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)({
@@ -920,7 +1145,6 @@ async function depositNative(signer, options) {
             : typeof amount === 'string'
                 ? BigInt(amount)
                 : BigInt(amount);
-        let depositTx;
         // Connect the contract first, then get the function to disambiguate between overloads
         const connectedContract = wrapperContract.connect(signer);
         // Call depositNative with or without receiver parameter
@@ -955,19 +1179,22 @@ async function depositNative(signer, options) {
         }
         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 } });
+        throw new core_1.AugustSDKError('UNKNOWN', `Deposit native failed: ${e instanceof Error ? e.message : 'Unknown error'}`, { cause: e, context: { wrapperAddress, receiver, amount, ...broadcast } });
     }
 }
 /**
@@ -1040,6 +1267,8 @@ async function rwaRedeemAsset(signer, options) {
         }
         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, {
@@ -1047,14 +1276,16 @@ async function rwaRedeemAsset(signer, options) {
             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 } });
+        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 */
@@ -1099,12 +1330,7 @@ async function dispatchViaSwapRouter(args) {
     // (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 underlyingErc20 = (0, core_1.createContract)({
-        address: args.underlyingAsset,
-        provider: args.signer,
-        abi: abis_1.ABI_ERC20,
-    });
-    const underlyingDecimals = Number(await underlyingErc20.decimals());
+    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,
@@ -1470,15 +1696,12 @@ async function swapRouterDeposit(signer, options) {
         });
         const [asset, receiptTokenAddr] = await Promise.all([
             poolContract.asset(),
-            poolContract.lpTokenAddress(),
+            // Retried on transport blips only; a misroute still throws. See
+            // getReceiptTokenAddressOrThrow.
+            (0, core_1.getReceiptTokenAddressOrThrow)(signer, vault, 'swapRouterDeposit:receiptToken'),
         ]);
         underlyingAsset = asset;
-        const receiptContract = (0, core_1.createContract)({
-            address: receiptTokenAddr,
-            provider: signer,
-            abi: abis_1.ABI_ERC20,
-        });
-        vaultDecimals = Number(await receiptContract.decimals());
+        vaultDecimals = await (0, core_1.getDecimalsOrThrow)(signer, receiptTokenAddr, 'swapRouterDeposit:receiptDecimals');
     }
     else {
         const poolContract = (0, core_1.createContract)({
@@ -1488,10 +1711,10 @@ async function swapRouterDeposit(signer, options) {
         });
         const [asset, rawDecimals] = await Promise.all([
             poolContract.asset(),
-            poolContract.decimals(),
+            (0, core_1.getDecimalsOrThrow)(signer, vault, 'swapRouterDeposit:poolDecimals'),
         ]);
         underlyingAsset = asset;
-        vaultDecimals = Number(rawDecimals);
+        vaultDecimals = rawDecimals;
     }
     const isNativeToken = depositAsset === ethers_1.ZeroAddress ||
         depositAsset === '0x0000000000000000000000000000000000000000';
@@ -1501,14 +1724,7 @@ async function swapRouterDeposit(signer, options) {
         isNativeToken,
         isMultiAssetVault,
         vaultDecimals,
-        readErc20Decimals: async (addr) => {
-            const erc20 = (0, core_1.createContract)({
-                address: addr,
-                provider: signer,
-                abi: abis_1.ABI_ERC20,
-            });
-            return Number(await erc20.decimals());
-        },
+        readErc20Decimals: async (addr) => (0, core_1.getDecimalsOrThrow)(signer, addr, 'swapRouterDeposit:depositTokenDecimals'),
     });
     const normalizedAmt = (0, core_1.toNormalizedBn)(amount, depositTokenDecimals);
     if (BigInt(normalizedAmt.raw) === 0n) {