upshift-finance 1.0.0

package/lib/evm/methods/crossChainVault.js

@@ -0,0 +1,853 @@
+"use strict";
+/**
+ * Cross-Chain Vault Methods
+ *
+ * Implements LayerZero OVault cross-chain deposit and redemption operations.
+ * These functions are generic — callers provide their own ICrossChainVaultConfig
+ * rather than relying on hardcoded vault addresses.
+ *
+ * @module evm/methods/crossChainVault
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAYERZERO_ENDPOINT_IDS = void 0;
+exports.buildCrossChainVaultTx = buildCrossChainVaultTx;
+exports.quoteCrossChainDeposit = quoteCrossChainDeposit;
+exports.quoteCrossChainRedeem = quoteCrossChainRedeem;
+exports.needsCrossChainApproval = needsCrossChainApproval;
+exports.approveCrossChain = approveCrossChain;
+exports.crossChainVaultDeposit = crossChainVaultDeposit;
+exports.crossChainVaultRedeem = crossChainVaultRedeem;
+exports.isNoPeerError = isNoPeerError;
+exports.classifyCrossChainError = classifyCrossChainError;
+exports.canDepositFromChain = canDepositFromChain;
+exports.canRedeemFromChain = canRedeemFromChain;
+exports.isCrossChainOperation = isCrossChainOperation;
+exports.getAvailableChains = getAvailableChains;
+exports.formatCrossChainError = formatCrossChainError;
+exports.getLayerZeroScanUrl = getLayerZeroScanUrl;
+const attribution_1 = require("../../core/attribution");
+const core_1 = require("../../core");
+const crossChain_1 = require("../types/crossChain");
+const OFT_1 = require("../../abis/OFT");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * lzReceive option hex for 500,000 gas.
+ * The Agora OFT has no enforced options for SEND_AND_CALL, so we must provide
+ * lzReceive gas explicitly or the executor reverts with Executor_ZeroLzReceiveGasProvided.
+ */
+const LZ_RECEIVE_OPTION_HEX = '010011010000000000000000000000000007a120';
+/** Default fee buffer percentage applied to LayerZero native fees */
+const DEFAULT_FEE_BUFFER_PERCENT = 50;
+/** Default slippage in basis points (1%) */
+const DEFAULT_SLIPPAGE_BPS = 100;
+/** Default gas buffer for deposits (1.5x) */
+const DEFAULT_DEPOSIT_GAS_BUFFER_PERCENT = 150;
+/** Default gas buffer for redeems (2x) */
+const DEFAULT_REDEEM_GAS_BUFFER_PERCENT = 200;
+/** Default minimum gas limit for redeem operations */
+const DEFAULT_MIN_REDEEM_GAS = 5000000n;
+/** Default hub lzCompose gas limit */
+const DEFAULT_HUB_LZ_COMPOSE_GAS_LIMIT = 2000000n;
+// ---------------------------------------------------------------------------
+// Mutex for SDK monkey-patches
+//
+// Multi-asset and hub-redeem flows mutate the shared `OVaultSyncMessageBuilder`
+// — module-level bindings inside the SDK mean a shallow clone is unsafe, so we
+// serialize patched calls. The timeout THROWS rather than silently racing
+// concurrent callers' patches.
+// ---------------------------------------------------------------------------
+const PATCH_LOCK_TIMEOUT_MS = 30_000;
+let patchLock = Promise.resolve();
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Try available previewRedeem signatures, falling back to 1:1 if the vault
+ * does not expose a working preview function.
+ */
+async function redeemPreview(publicClient, vaultAddress, shares) {
+    // 1. previewRedemption(uint256, bool) — multi-asset vault
+    try {
+        const result = await publicClient.readContract({
+            address: vaultAddress,
+            abi: OFT_1.ABI_MULTI_ASSET_PREVIEW_REDEEM,
+            functionName: 'previewRedemption',
+            args: [shares, false],
+        });
+        const [, assetsAfterFee] = result;
+        return assetsAfterFee;
+    }
+    catch {
+        /* try next */
+    }
+    // 2. Standard ERC4626: previewRedeem(uint256)
+    try {
+        return (await publicClient.readContract({
+            address: vaultAddress,
+            abi: OFT_1.ABI_STANDARD_PREVIEW_REDEEM,
+            functionName: 'previewRedeem',
+            args: [shares],
+        }));
+    }
+    catch {
+        /* try next */
+    }
+    // 3. Fallback: 1:1 ratio. Slippage protects against discrepancy.
+    return shares;
+}
+/**
+ * Wraps generateOVaultInputs with monkey-patches for:
+ * 1. REDEEM from hub — skip quoteOFT (reverts for same-chain)
+ * 2. Multi-asset DEPOSIT — previewDeposit(address, uint256)
+ * 3. Multi-asset REDEEM — try previewRedeem variants, fallback to 1:1
+ * 4. Multi-asset composed messages — add lzReceive gas to SEND_AND_CALL
+ */
+async function generateOVaultInputsWithOverride(input, config, hubPublicClient, ovaultSdk) {
+    const OVaultSyncMessageBuilder = ovaultSdk.OVaultSyncMessageBuilder;
+    const OVaultSyncOperations = ovaultSdk.OVaultSyncOperations;
+    const isRedeemFromHub = input.operation === OVaultSyncOperations.REDEEM &&
+        input.srcEid === input.hubEid;
+    const isMultiAsset = !!config.multiAsset;
+    // Fast path — no patches needed
+    if (!isMultiAsset && !isRedeemFromHub) {
+        return OVaultSyncMessageBuilder.generateOVaultInputs(input);
+    }
+    // Serialize: wait for the prior holder or REJECT on timeout (silent races
+    // produced wrong cross-chain quotes).
+    const prev = patchLock;
+    let unlock;
+    patchLock = new Promise((r) => {
+        unlock = r;
+    });
+    let timeoutHandle;
+    try {
+        await Promise.race([
+            prev,
+            new Promise((_resolve, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error(`crossChainVault patch lock timed out after ${PATCH_LOCK_TIMEOUT_MS}ms — a prior call may be hung`)), PATCH_LOCK_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (err) {
+        unlock();
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        throw err;
+    }
+    if (timeoutHandle)
+        clearTimeout(timeoutHandle);
+    const Builder = OVaultSyncMessageBuilder;
+    const origGetOutputAmount = Builder.getOutputAmount;
+    const origQuoteOVaultOutput = Builder.quoteOVaultOutput;
+    const origBuildSendParams = Builder.buildSendParams;
+    const origBuildApproval = Builder.buildApproval;
+    try {
+        if (isRedeemFromHub) {
+            // Patch 1a: skip quoteOFT (reverts for same-chain calls).
+            Builder.getOutputAmount = async () => input.amount;
+            // Patch 1b: skip SDK's allowance check — multi-asset vault contracts
+            // may not implement ERC20. Caller handles approval directly.
+            Builder.buildApproval = async () => undefined;
+        }
+        if (isMultiAsset) {
+            const { hubAssetAddress } = config.multiAsset;
+            // Patch 2/3: Multi-asset quoteOVaultOutput
+            Builder.quoteOVaultOutput = async (quoteInput) => {
+                const getOutputAmount = Builder.getOutputAmount;
+                const sourceAmount = await getOutputAmount({
+                    ...quoteInput,
+                    dstAmount: 0n,
+                    minDstAmount: 0n,
+                    dstAddress: quoteInput.walletAddress,
+                    tokenAddress: quoteInput.tokenAddress ?? quoteInput.oftAddress,
+                });
+                let outputAmount;
+                if (quoteInput.operation === OVaultSyncOperations.REDEEM) {
+                    outputAmount = await redeemPreview(hubPublicClient, config.vaultAddress, sourceAmount);
+                }
+                else {
+                    const [depositOutput] = (await hubPublicClient.readContract({
+                        address: config.vaultAddress,
+                        abi: OFT_1.ABI_MULTI_ASSET_PREVIEW_DEPOSIT,
+                        functionName: 'previewDeposit',
+                        args: [hubAssetAddress, sourceAmount],
+                    }));
+                    outputAmount = depositOutput;
+                }
+                const slippageBps = BigInt(Math.round(quoteInput.slippage * 10000));
+                const slippageAmount = (outputAmount * slippageBps) / 10000n;
+                return {
+                    dstAmount: outputAmount,
+                    minDstAmount: outputAmount - slippageAmount,
+                };
+            };
+            // Patch 4: Ensure lzReceive gas in extraOptions for composed messages
+            Builder.buildSendParams = async (spInput) => {
+                const origFn = origBuildSendParams;
+                const result = await origFn.call(Builder, spInput);
+                if (result.composeMsg && result.composeMsg !== '0x') {
+                    const opts = result.extraOptions;
+                    if (opts && opts.length >= 6 && opts.startsWith('0x0003')) {
+                        const body = opts.slice(6);
+                        const hasLzReceive = body.startsWith('01001101');
+                        if (!hasLzReceive) {
+                            result.extraOptions = `0x0003${LZ_RECEIVE_OPTION_HEX}${body}`;
+                        }
+                    }
+                }
+                return result;
+            };
+        }
+        return (await OVaultSyncMessageBuilder.generateOVaultInputs(input));
+    }
+    finally {
+        Builder.getOutputAmount = origGetOutputAmount;
+        Builder.quoteOVaultOutput = origQuoteOVaultOutput;
+        Builder.buildSendParams = origBuildSendParams;
+        Builder.buildApproval = origBuildApproval;
+        unlock();
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API: Build
+// ---------------------------------------------------------------------------
+/**
+ * Build LayerZero OVault transaction inputs for cross-chain deposits and
+ * redemptions. Does NOT execute the transaction.
+ *
+ * Overridable defaults on `props`: `slippageBps` = 100 (range 1–10000),
+ * `feeBufferPercent` = 50% (added to LZ `nativeFee`),
+ * `hubLzComposeGasLimit` = 2_000_000n (multi-asset composed messages).
+ *
+ * @returns Transaction inputs or `{ success: false, error }`.
+ */
+async function buildCrossChainVaultTx(props) {
+    try {
+        const { config } = props;
+        // Validate slippage at the public boundary (BPS, not decimal)
+        const slippageBps = props.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+        if (slippageBps < 1 || slippageBps > 10000) {
+            return {
+                success: false,
+                error: `Slippage must be between 1 and 10000 basis points (got ${slippageBps})`,
+            };
+        }
+        // Validate chains
+        const hubChain = props.hubChain;
+        const sourceChain = props.sourceChain;
+        if (!hubChain || !sourceChain) {
+            return {
+                success: false,
+                error: 'Hub chain and source chain are required',
+            };
+        }
+        // Reject unknown chain IDs up front so a typo can't fall through to
+        // `|| hub` and route shares to a chain the user didn't pick.
+        const supportedChains = [
+            config.hubChainId,
+            ...Object.keys(config.layerZeroEids.spokes).map((k) => Number(k)),
+        ];
+        const supportedChainsList = supportedChains.join(', ');
+        if (props.destinationChainId !== undefined &&
+            props.destinationChainId !== config.hubChainId &&
+            !config.layerZeroEids.spokes[props.destinationChainId]) {
+            return {
+                success: false,
+                error: `Destination chain ${props.destinationChainId} is not configured for this vault. Supported chains: ${supportedChainsList}.`,
+            };
+        }
+        if (props.operation === 'DEPOSIT' &&
+            props.userChainId !== config.hubChainId &&
+            !config.layerZeroEids.spokes[props.userChainId]) {
+            return {
+                success: false,
+                error: `Source chain ${props.userChainId} is not configured for this vault. Supported chains: ${supportedChainsList}.`,
+            };
+        }
+        const resolveDstEid = (chainId) => {
+            if (chainId === undefined)
+                return undefined;
+            if (chainId === config.hubChainId)
+                return config.layerZeroEids.hub;
+            return config.layerZeroEids.spokes[chainId];
+        };
+        // Determine source and destination EIDs based on operation
+        let srcEid;
+        let dstEid;
+        let tokenAddress;
+        let oftAddress;
+        switch (props.operation) {
+            case 'DEPOSIT': {
+                const resolvedSrc = resolveDstEid(props.userChainId);
+                srcEid =
+                    resolvedSrc !== undefined ? resolvedSrc : config.layerZeroEids.hub;
+                const resolved = resolveDstEid(props.destinationChainId);
+                dstEid = resolved !== undefined ? resolved : srcEid;
+                tokenAddress = config.contracts.assetToken[props.userChainId];
+                oftAddress = config.contracts.assetOFT[props.userChainId];
+                if (!tokenAddress || !oftAddress) {
+                    return {
+                        success: false,
+                        error: `Chain ${props.userChainId} is not configured for deposits on this vault`,
+                    };
+                }
+                break;
+            }
+            case 'REDEEM': {
+                srcEid = config.layerZeroEids.hub;
+                const resolved = resolveDstEid(props.destinationChainId) ??
+                    resolveDstEid(props.userChainId);
+                dstEid = resolved !== undefined ? resolved : config.layerZeroEids.hub;
+                tokenAddress = config.vaultAddress;
+                oftAddress = config.contracts.shareOFTAdapter;
+                break;
+            }
+            default:
+                return {
+                    success: false,
+                    error: `Invalid operation: ${props.operation}`,
+                };
+        }
+        // Normalize amount
+        const normalizedAmount = (0, core_1.toNormalizedBn)(props.amount, props.decimals);
+        // Build LayerZero OVault inputs
+        const input = {
+            srcEid,
+            hubEid: config.layerZeroEids.hub,
+            dstEid,
+            dstAddress: props.recipientAddress || props.walletAddress,
+            walletAddress: props.walletAddress,
+            vaultAddress: config.vaultAddress,
+            composerAddress: config.contracts.composerSync,
+            hubChain: hubChain,
+            sourceChain: sourceChain,
+            operation: props.operation === 'DEPOSIT'
+                ? props.ovaultSdk.OVaultSyncOperations.DEPOSIT
+                : props.ovaultSdk.OVaultSyncOperations.REDEEM,
+            amount: BigInt(normalizedAmount.raw),
+            slippage: slippageBps / 10000,
+            tokenAddress,
+            oftAddress,
+            hubLzComposeGasLimit: props.hubLzComposeGasLimit ?? DEFAULT_HUB_LZ_COMPOSE_GAS_LIMIT,
+        };
+        // Create a minimal public client for hub chain reads (multi-asset patches)
+        const hubRpc = hubChain?.rpcUrls;
+        const hubRpcUrl = hubRpc?.default?.http?.[0];
+        let hubPublicClient;
+        try {
+            // Dynamic import to keep viem optional at the module level
+            const viem = await Promise.resolve().then(() => __importStar(require('viem')));
+            hubPublicClient = viem.createPublicClient({
+                chain: hubChain,
+                transport: viem.http(hubRpcUrl),
+            });
+        }
+        catch {
+            // If viem is not available, provide a stub that will fail on multi-asset only
+            hubPublicClient = {
+                readContract: async () => {
+                    throw new Error('viem is required for multi-asset vault operations. Install viem as a peer dependency.');
+                },
+            };
+        }
+        // Generate OVault transaction inputs (with monkey-patches for multi-asset)
+        const inputs = await generateOVaultInputsWithOverride(input, config, hubPublicClient, props.ovaultSdk);
+        // Apply fee buffer to LZ fees (post-hoc to avoid SDK double-compounding)
+        const feeBufferPercent = props.feeBufferPercent ?? DEFAULT_FEE_BUFFER_PERCENT;
+        const rawNativeFee = inputs.messageFee.nativeFee;
+        const rawMessageValue = inputs.messageValue;
+        const feeBuffer = (rawNativeFee * BigInt(feeBufferPercent)) / 100n;
+        inputs.messageFee.nativeFee = rawNativeFee + feeBuffer;
+        inputs.messageValue = rawMessageValue + feeBuffer;
+        // Patch fee into txArgs in place for OFT.send(); warn if the LayerZero
+        // SDK ever returns a different entry-point name (silent no-op would
+        // underpay the LZ fee).
+        if (inputs.contractFunctionName === 'send') {
+            const sendFee = inputs.txArgs[1];
+            sendFee.nativeFee = inputs.messageFee.nativeFee;
+        }
+        else {
+            core_1.Logger.log.warn('crossChainVault:fee-patch', `Unexpected contractFunctionName "${inputs.contractFunctionName}" from LayerZero SDK — fee buffer not applied to txArgs in-place`, { contractFunctionName: inputs.contractFunctionName });
+        }
+        return {
+            success: true,
+            data: {
+                contractAddress: inputs.contractAddress,
+                contractFunctionName: inputs.contractFunctionName,
+                abi: inputs.abi,
+                txArgs: inputs.txArgs,
+                messageValue: inputs.messageValue,
+                messageFee: {
+                    nativeFee: inputs.messageFee.nativeFee,
+                    lzTokenFee: inputs.messageFee.lzTokenFee,
+                },
+                dstAmount: inputs.dstAmount.amount,
+                minDstAmount: inputs.dstAmount.minAmount,
+                approval: inputs.approval
+                    ? {
+                        tokenAddress: inputs.approval.tokenAddress,
+                        spender: inputs.approval.spender,
+                        amount: inputs.approval.amount,
+                    }
+                    : undefined,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error occurred',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API: Quote
+// ---------------------------------------------------------------------------
+/**
+ * Estimate fees and expected shares for a cross-chain deposit. The returned
+ * quote carries `quotedAt`/`expiresAt`; re-quote via {@link isQuoteStale}
+ * before submitting.
+ */
+async function quoteCrossChainDeposit(props) {
+    const result = await buildCrossChainVaultTx({
+        ovaultSdk: props.ovaultSdk,
+        config: props.config,
+        operation: 'DEPOSIT',
+        amount: props.amount,
+        decimals: props.decimals,
+        userChainId: props.userChainId,
+        walletAddress: props.walletAddress,
+        destinationChainId: props.destinationChainId,
+        slippageBps: props.slippageBps,
+        feeBufferPercent: props.feeBufferPercent,
+        hubChain: props.hubChain,
+        sourceChain: props.sourceChain,
+    });
+    if (!result.success || !result.data)
+        return null;
+    const quotedAt = Date.now();
+    return {
+        nativeFee: result.data.messageFee.nativeFee,
+        dstAmount: result.data.dstAmount,
+        minDstAmount: result.data.minDstAmount,
+        quotedAt,
+        expiresAt: quotedAt + crossChain_1.CROSS_CHAIN_QUOTE_TTL_MS,
+    };
+}
+/**
+ * Estimate fees and expected assets for a cross-chain redeem. The returned
+ * quote carries `quotedAt`/`expiresAt`; re-quote via {@link isQuoteStale}
+ * before submitting.
+ */
+async function quoteCrossChainRedeem(props) {
+    const result = await buildCrossChainVaultTx({
+        ovaultSdk: props.ovaultSdk,
+        config: props.config,
+        operation: 'REDEEM',
+        amount: props.amount,
+        decimals: props.decimals,
+        userChainId: props.config.hubChainId,
+        walletAddress: props.walletAddress,
+        destinationChainId: props.destinationChainId,
+        slippageBps: props.slippageBps,
+        feeBufferPercent: props.feeBufferPercent,
+        hubChain: props.hubChain,
+        sourceChain: props.sourceChain,
+    });
+    if (!result.success || !result.data)
+        return null;
+    const quotedAt = Date.now();
+    return {
+        nativeFee: result.data.messageFee.nativeFee,
+        dstAmount: result.data.dstAmount,
+        minDstAmount: result.data.minDstAmount,
+        quotedAt,
+        expiresAt: quotedAt + crossChain_1.CROSS_CHAIN_QUOTE_TTL_MS,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API: Approval
+// ---------------------------------------------------------------------------
+/**
+ * Returns `true` when the wallet's ERC-20 allowance is insufficient for the
+ * cross-chain operation. On RPC failure also returns `true` (defensive
+ * default — better a redundant approval than a downstream revert).
+ */
+async function needsCrossChainApproval(tokenAddress, spenderAddress, walletAddress, amount, publicClient) {
+    try {
+        const allowance = (await publicClient.readContract({
+            address: tokenAddress,
+            abi: OFT_1.ABI_CROSS_CHAIN_ERC20,
+            functionName: 'allowance',
+            args: [walletAddress, spenderAddress],
+        }));
+        return allowance < amount;
+    }
+    catch {
+        // If we can't check allowance, assume approval is needed
+        return true;
+    }
+}
+/**
+ * Execute a token approval for a cross-chain operation.
+ *
+ * @returns Transaction hash of the approval
+ */
+async function approveCrossChain(tokenAddress, spenderAddress, amount, walletClient, publicClient) {
+    if (!walletClient.account) {
+        throw new Error('Wallet not ready — please reconnect your wallet');
+    }
+    const hash = await walletClient.writeContract({
+        account: walletClient.account,
+        address: tokenAddress,
+        abi: OFT_1.ABI_CROSS_CHAIN_ERC20,
+        functionName: 'approve',
+        args: [spenderAddress, amount],
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(),
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({
+        hash: hash,
+    });
+    if (receipt.status === 'reverted') {
+        throw new Error(`Approval transaction reverted on-chain (tx ${hash}). Check token allowance limits or that the token contract supports approve().`);
+    }
+    return hash;
+}
+// ---------------------------------------------------------------------------
+// Public API: Execute
+// ---------------------------------------------------------------------------
+/**
+ * Execute a cross-chain deposit via LayerZero OVault. Validates the source
+ * chain, ensures approval, estimates gas with a buffer, and waits for the
+ * on-chain receipt. Defaults: `slippageBps` 100, `feeBufferPercent` 50,
+ * `gasBufferPercent` 150 — all overridable on the request.
+ *
+ * @throws Error on unsupported chain, approval revert, gas-estimation
+ *   failure, or on-chain revert.
+ */
+async function crossChainVaultDeposit(props) {
+    if (props.userChainId !== props.config.hubChainId &&
+        !props.config.spokeChainIds.includes(props.userChainId)) {
+        throw new Error(`Chain ${props.userChainId} is not supported for deposits to this vault — switch to the hub (${props.config.hubChainId}) or a configured spoke (${props.config.spokeChainIds.join(', ')}).`);
+    }
+    const walletClient = props.walletClient;
+    const publicClient = props.publicClient;
+    // 1. Build transaction inputs
+    const result = await buildCrossChainVaultTx({
+        ovaultSdk: props.ovaultSdk,
+        config: props.config,
+        operation: 'DEPOSIT',
+        amount: props.amount,
+        decimals: props.decimals,
+        userChainId: props.userChainId,
+        walletAddress: props.walletAddress,
+        destinationChainId: props.destinationChainId,
+        slippageBps: props.slippageBps,
+        feeBufferPercent: props.feeBufferPercent,
+        hubChain: props.hubChain,
+        sourceChain: props.sourceChain,
+    });
+    if (!result.success || !result.data) {
+        throw new Error(result.error || 'Failed to build transaction');
+    }
+    const txInputs = result.data;
+    // 2. Check and execute approval if needed
+    if (!props.skipApprovalCheck) {
+        const tokenAddr = txInputs.approval?.tokenAddress ??
+            props.config.contracts.assetToken[props.userChainId];
+        const spenderAddr = txInputs.approval?.spender ?? txInputs.contractAddress;
+        const approvalAmount = txInputs.approval?.amount ??
+            BigInt((0, core_1.toNormalizedBn)(props.amount, props.decimals).raw);
+        const approvalNeeded = await needsCrossChainApproval(tokenAddr, spenderAddr, props.walletAddress, approvalAmount, publicClient);
+        if (approvalNeeded) {
+            await approveCrossChain(tokenAddr, spenderAddr, approvalAmount, walletClient, publicClient);
+        }
+    }
+    // 3. Estimate gas with buffer
+    if (!walletClient.account) {
+        throw new Error('Wallet not ready — please reconnect your wallet');
+    }
+    const gasBufferPercent = props.gasBufferPercent ?? DEFAULT_DEPOSIT_GAS_BUFFER_PERCENT;
+    let gasLimit;
+    try {
+        const estimated = await publicClient.estimateContractGas({
+            account: walletClient.account,
+            address: txInputs.contractAddress,
+            abi: txInputs.abi,
+            functionName: txInputs.contractFunctionName,
+            args: txInputs.txArgs,
+            value: txInputs.messageValue,
+        });
+        gasLimit = (estimated * BigInt(gasBufferPercent)) / 100n;
+    }
+    catch (estimateErr) {
+        throw new Error(`Gas estimation failed for cross-chain deposit. Ensure you have sufficient native tokens for the LayerZero fee (${txInputs.messageFee.nativeFee.toString()} wei). Original error: ${estimateErr instanceof Error ? estimateErr.message : String(estimateErr)}`);
+    }
+    // 4. Execute the transaction
+    const hash = await walletClient.writeContract({
+        account: walletClient.account,
+        address: txInputs.contractAddress,
+        abi: txInputs.abi,
+        functionName: txInputs.contractFunctionName,
+        args: txInputs.txArgs,
+        value: txInputs.messageValue,
+        gas: gasLimit,
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(props.userChainId),
+    });
+    // 5. Wait for confirmation
+    const receipt = await publicClient.waitForTransactionReceipt({
+        hash: hash,
+    });
+    if (receipt.status === 'reverted') {
+        throw new Error('Transaction reverted on-chain. This may be due to insufficient gas for the LayerZero compose call or a contract error.');
+    }
+    return {
+        transactionHash: hash,
+        success: true,
+    };
+}
+/**
+ * Execute a cross-chain redemption via LayerZero OVault. User must be on the
+ * hub chain. Defaults: `slippageBps` 100, `feeBufferPercent` 50,
+ * `gasBufferPercent` 200 (compose calls under-estimate on mainnet),
+ * `minGasLimit` 5_000_000n — all overridable on the request.
+ */
+async function crossChainVaultRedeem(props) {
+    // 1. Validate: redemptions must be from hub chain
+    if (props.userChainId !== props.config.hubChainId) {
+        throw new Error(`Redemptions must be executed from hub chain (${props.config.hubChainId}). ` +
+            `Please switch to the hub chain first.`);
+    }
+    const walletClient = props.walletClient;
+    const publicClient = props.publicClient;
+    // 2. Build transaction inputs
+    const result = await buildCrossChainVaultTx({
+        ovaultSdk: props.ovaultSdk,
+        config: props.config,
+        operation: 'REDEEM',
+        amount: props.amount,
+        decimals: props.decimals,
+        userChainId: props.userChainId,
+        walletAddress: props.walletAddress,
+        destinationChainId: props.destinationChainId ?? props.userChainId,
+        slippageBps: props.slippageBps,
+        feeBufferPercent: props.feeBufferPercent,
+        hubChain: props.hubChain,
+        sourceChain: props.sourceChain,
+    });
+    if (!result.success || !result.data) {
+        throw new Error(result.error || 'Failed to build transaction');
+    }
+    const txInputs = result.data;
+    // 3. Check and execute approval if needed
+    if (!props.skipApprovalCheck && txInputs.approval) {
+        const approvalNeeded = await needsCrossChainApproval(txInputs.approval.tokenAddress, txInputs.approval.spender, props.walletAddress, txInputs.approval.amount, publicClient);
+        if (approvalNeeded) {
+            await approveCrossChain(txInputs.approval.tokenAddress, txInputs.approval.spender, txInputs.approval.amount, walletClient, publicClient);
+        }
+    }
+    // 4. Estimate gas with buffer
+    if (!walletClient.account) {
+        throw new Error('Wallet account not available');
+    }
+    const gasBufferPercent = props.gasBufferPercent ?? DEFAULT_REDEEM_GAS_BUFFER_PERCENT;
+    const minGasLimit = props.minGasLimit ?? DEFAULT_MIN_REDEEM_GAS;
+    let gasLimit;
+    try {
+        const estimated = await publicClient.estimateContractGas({
+            account: walletClient.account,
+            address: txInputs.contractAddress,
+            abi: txInputs.abi,
+            functionName: txInputs.contractFunctionName,
+            args: txInputs.txArgs,
+            value: txInputs.messageValue,
+        });
+        const buffered = (estimated * BigInt(gasBufferPercent)) / 100n;
+        gasLimit = buffered > minGasLimit ? buffered : minGasLimit;
+    }
+    catch (estimateErr) {
+        throw new Error(`Gas estimation failed for cross-chain redeem. Ensure you have sufficient native tokens for the LayerZero fee (${txInputs.messageFee.nativeFee.toString()} wei). Original error: ${estimateErr instanceof Error ? estimateErr.message : String(estimateErr)}`);
+    }
+    // 5. Execute the transaction
+    const hash = await walletClient.writeContract({
+        account: walletClient.account,
+        address: txInputs.contractAddress,
+        abi: txInputs.abi,
+        functionName: txInputs.contractFunctionName,
+        args: txInputs.txArgs,
+        value: txInputs.messageValue,
+        gas: gasLimit,
+        dataSuffix: (0, attribution_1.getAttributionSuffix)(props.config.hubChainId),
+    });
+    // 6. Wait for confirmation
+    const receipt = await publicClient.waitForTransactionReceipt({
+        hash: hash,
+    });
+    if (receipt.status === 'reverted') {
+        throw new Error('Transaction reverted on-chain. This may be due to insufficient gas for the LayerZero compose call or a contract error.');
+    }
+    return {
+        transactionHash: hash,
+        success: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API: Error Classification
+// ---------------------------------------------------------------------------
+/**
+ * Check if an error indicates a missing LayerZero peer configuration.
+ */
+function isNoPeerError(errStr) {
+    return errStr.includes('0xf6ff4fb7') || errStr.includes('NoPeer');
+}
+/**
+ * Classify a cross-chain contract error into a known error type.
+ */
+function classifyCrossChainError(error) {
+    const err = error;
+    const msg = err?.message ?? String(error);
+    const lower = msg.toLowerCase();
+    if (msg.includes('0x79012fb2') || msg.includes('ERC4626ExceededMaxDeposit'))
+        return 'max-deposit';
+    if (lower.includes('nonce') || msg.includes('invalid nonce'))
+        return 'nonce';
+    if (lower.includes('user rejected') || msg.includes('User denied'))
+        return 'user-rejected';
+    if (isNoPeerError(msg))
+        return 'no-peer';
+    if (msg.includes('quoteSend') ||
+        lower.includes('layerzero') ||
+        lower.includes('lz fee') ||
+        lower.includes('oft') ||
+        lower.includes('unable to decode signature'))
+        return 'bridge-fee';
+    if (msg.includes('insufficient') || lower.includes('balance'))
+        return 'insufficient-balance';
+    if (lower.includes('gas'))
+        return 'gas';
+    if (lower.includes('network') || lower.includes('connection'))
+        return 'network';
+    return 'unknown';
+}
+// ---------------------------------------------------------------------------
+// Public API: Utility helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check if a user can deposit from their current chain.
+ */
+function canDepositFromChain(config, userChainId) {
+    return (userChainId === config.hubChainId ||
+        config.spokeChainIds.includes(userChainId));
+}
+/**
+ * Check if a user can redeem from their current chain (must be hub).
+ */
+function canRedeemFromChain(config, userChainId) {
+    return userChainId === config.hubChainId;
+}
+/**
+ * Check if an operation is cross-chain (needs LayerZero).
+ *
+ * An operation is cross-chain when:
+ * - The user's chain differs from the hub chain, OR
+ * - The destination chain differs from the hub chain
+ *   (e.g. deposit from hub but receive shares on a spoke)
+ */
+function isCrossChainOperation(config, userChainId, destinationChainId) {
+    if (userChainId !== config.hubChainId)
+        return true;
+    if (destinationChainId !== undefined &&
+        destinationChainId !== config.hubChainId)
+        return true;
+    return false;
+}
+/**
+ * Get all chain IDs that a vault supports (hub + all spokes).
+ */
+function getAvailableChains(config) {
+    return [config.hubChainId, ...config.spokeChainIds];
+}
+/**
+ * Format a cross-chain error into a user-friendly message.
+ *
+ * Mirrors the `classifyCrossChainDepositError` from upshift-app but is
+ * generic enough for any SDK consumer.
+ */
+function formatCrossChainError(errMsg) {
+    // If the error already contains specific gas fee info, show it directly
+    if (errMsg.includes('Cross-chain fee is') ||
+        errMsg.includes('Gas estimation failed'))
+        return errMsg;
+    const lower = errMsg.toLowerCase();
+    if (lower.includes('nonce') || errMsg.includes('invalid nonce'))
+        return 'Transaction nonce conflict. Please cancel any pending transactions and try again.';
+    if (errMsg.includes('quoteSend') ||
+        lower.includes('layerzero') ||
+        lower.includes('oft') ||
+        lower.includes('unable to decode signature'))
+        return 'Cross-chain fee estimation failed. The bridge may be temporarily unavailable — please try again.';
+    if (lower.includes('user rejected'))
+        return 'Transaction cancelled by user.';
+    if (lower.includes('hub chain'))
+        return errMsg; // Already descriptive
+    if (errMsg.includes('reverted'))
+        return 'Transaction reverted on-chain. This may be due to insufficient gas or a contract error.';
+    return 'Cross-chain transaction failed. Please try again.';
+}
+/**
+ * Get the LayerZero Scan URL for tracking a cross-chain message.
+ */
+function getLayerZeroScanUrl(txHash, testnet = false) {
+    const baseUrl = testnet
+        ? 'https://testnet.layerzeroscan.com'
+        : 'https://layerzeroscan.com';
+    return `${baseUrl}/tx/${txHash}`;
+}
+/**
+ * Well-known LayerZero Endpoint IDs for common chains.
+ * SDK consumers can use these when building their ICrossChainVaultConfig.
+ */
+exports.LAYERZERO_ENDPOINT_IDS = {
+    ETHEREUM: 30101,
+    ARBITRUM: 30110,
+    AVALANCHE: 30106,
+    BASE: 30184,
+    SONIC: 30332,
+    MONAD: 30390,
+};
+//# sourceMappingURL=crossChainVault.js.map