@lendasat/lendaswap-sdk-pure 0.2.24 → 0.2.26

package/dist/client.js

@@ -1,13 +1,16 @@
 import { createApiClient, } from "./api/client.js";
 import { getVhtlcAmounts } from "./arkade.js";
 import { USDC_ADDRESSES } from "./cctp/constants.js";
+import { computeCctpFastFee, getCachedCctpFee } from "./cctp/fee.js";
+import { cctpMetaForChainId, isCctpOnlySource, } from "./cctp-inbound/chainMap.js";
+import { CctpInboundClient } from "./cctp-inbound/client.js";
 import { createArkadeToEvmSwapGeneric, createArkadeToLightningSwap, createBitcoinToArkadeSwap, createBitcoinToEvmSwap, createEvmToArkadeSwapGeneric, createEvmToBitcoinSwap, createEvmToLightningSwapGeneric, createLightningToArkadeSwap, createLightningToEvmSwapGeneric, } from "./create/index.js";
 import { delegateClaim, delegateRefund } from "./delegate.js";
 import { broadcastTransaction, findOutputByAddress } from "./esplora.js";
 import { buildCollabRefundEvmDigest, buildCollabRefundEvmTypedData, buildEip2612PermitDigest, buildPermit2FundingDigest, buildPermit2TypedData, deriveEvmAddress, encodeApproveCallData, encodeExecuteAndCreateWithPermit2, encodeHtlcErc20RefundCallData, PERMIT2_ADDRESS, signEvmDigest, } from "./evm/index.js";
 import { decodeUint256, encodeAllowanceCall, encodeBalanceOfCall, encodeMaxApproveData, getRevertReason, parseSignature, simulateTransaction, } from "./evm/wallet.js";
 import { buildArkadeClaim, continueArkadeClaim, claimViaGasless as gaslessClaim, claim as redeemClaim, } from "./redeem/index.js";
-import { buildArkadeRefund, buildOnchainClaimTransaction, buildOnchainRefundTransaction, collabRefundDelegate, collabRefundOffchain, verifyHtlcAddress, } from "./refund/index.js";
+import { buildArkadeRefund, buildOnchainClaimTransaction, buildOnchainRefundTransaction, collabRefundArkadeToEvmDelegate, collabRefundArkadeToEvmOffchain, collabRefundArkadeToLightningOffchain, verifyHtlcAddress, } from "./refund/index.js";
 import { bytesToHex, hexToBytes, Signer, } from "./signer/index.js";
 import { SWAP_STORAGE_VERSION, } from "./storage/index.js";
 import { isArkade, isBridgeOnlyChain, isBtcOnchain, isBtcPegged, isEvmToken, isLightning, isSourceEvmChain, toChainName, } from "./tokens.js";
@@ -60,6 +63,7 @@ export class ClientBuilder {
     #swapStorage;
     #mnemonic;
     #xprv;
+    #aa;
     /**
      * Sets the base URL for the API.
      * @param baseUrl - The base URL of the Lendaswap API.
@@ -176,6 +180,23 @@ export class ClientBuilder {
         this.#xprv = xprv;
         return this;
     }
+    /**
+     * Sets the account-abstraction config (bundler + Gas Manager policy).
+     *
+     * Required when using the CCTP-inbound swap flow (any non-Arbitrum
+     * EVM chain as the source). The settlement UserOp — `receiveMessage`
+     * + `USDC.approve(Permit2)` + `executeAndCreateWithPermit2` — is
+     * submitted via the Kernel smart account owned by the consumer's
+     * connected wallet, sponsored by the Gas Manager so users need no
+     * ETH on Arbitrum.
+     *
+     * @param aa - Bundler URL + paymaster policy id.
+     * @returns The builder instance for chaining.
+     */
+    withAa(aa) {
+        this.#aa = aa;
+        return this;
+    }
     /**
      * Builds and returns a fully initialized Client instance.
      *
@@ -231,6 +252,7 @@ export class ClientBuilder {
             defaultHeaders: this.#defaultHeaders,
             esploraUrl: this.#esploraUrl?.replace(/\/+$/, ""),
             arkadeServerUrl: this.#arkadeServerUrl?.replace(/\/+$/, ""),
+            aa: this.#aa,
         }, signer, this.#signerStorage, this.#swapStorage);
     }
 }
@@ -265,6 +287,7 @@ export class Client {
     #signerStorage;
     #swapStorage;
     #statusWatcher = null;
+    #cctpInbound = null;
     /**
      * Creates a new Client instance.
      *
@@ -326,6 +349,27 @@ export class Client {
     get baseUrl() {
         return this.#config.baseUrl;
     }
+    /**
+     * Namespace for CCTP-inbound swap primitives (source-chain burn,
+     * IRIS attestation, settlement UserOp). Requires `withAa(...)` on
+     * the builder — throws with a clear error otherwise.
+     *
+     * For simple integrations prefer `Client.fundSwap(swapId, signer)`
+     * which auto-dispatches to the CCTP path when needed; drop down to
+     * `client.cctpInbound.*` when you need step-by-step progress control.
+     */
+    get cctpInbound() {
+        if (!this.#cctpInbound) {
+            if (!this.#config.aa) {
+                throw new Error("CCTP-inbound flow requires AA config. Call `.withAa({ bundlerUrl, paymasterPolicyId })` on the ClientBuilder before `.build()`.");
+            }
+            this.#cctpInbound = new CctpInboundClient({
+                apiClient: this.#apiClient,
+                aa: this.#config.aa,
+            });
+        }
+        return this.#cctpInbound;
+    }
     /** The swap storage, if configured. */
     get swapStorage() {
         return this.#swapStorage;
@@ -573,19 +617,42 @@ export class Client {
                 ? USDT0_ADDRESSES.Arbitrum
                 : USDC_ADDRESSES.Arbitrum;
         }
+        // CCTP-only source (USDC on Optimism / Base / Linea / …): the quote
+        // endpoint expects the source chain/token the DEX actually runs on
+        // (Arbitrum + native USDC), plus `bridge_source_chain` + address so
+        // the backend can apply the CCTPv2 fast-transfer fee. All gross-vs-net
+        // math happens server-side.
+        let sourceChain = params.sourceChain;
+        let sourceToken = params.sourceToken;
+        let bridgeSourceChain;
+        let bridgeSourceTokenAddress;
+        const parsedSourceChainId = Number.parseInt(params.sourceChain, 10);
+        if (!Number.isNaN(parsedSourceChainId) &&
+            isCctpOnlySource(parsedSourceChainId)) {
+            const source = cctpMetaForChainId(parsedSourceChainId);
+            if (params.sourceToken.toLowerCase() !== source.usdc.toLowerCase()) {
+                throw new Error(`Quote on ${source.name} requires native USDC (${source.usdc}); got ${params.sourceToken}. Only USDC is bridgeable via CCTP.`);
+            }
+            bridgeSourceChain = source.name;
+            bridgeSourceTokenAddress = source.usdc;
+            sourceChain = "42161";
+            sourceToken = USDC_ADDRESSES.Arbitrum;
+        }
+        const query = {
+            source_chain: sourceChain,
+            source_token: sourceToken,
+            target_chain: targetChain,
+            target_token: targetToken,
+            source_amount: params.sourceAmount,
+            target_amount: params.targetAmount,
+            bridge_target_chain: bridgeTargetChain,
+            bridge_source_chain: bridgeSourceChain,
+            bridge_source_token_address: bridgeSourceTokenAddress,
+            bridge_recipient_setup: params.bridgeRecipientSetup,
+            ref: params.referralCode,
+        };
         const { data, error } = await this.#apiClient.GET("/quote", {
-            params: {
-                query: {
-                    source_chain: params.sourceChain,
-                    source_token: params.sourceToken,
-                    target_chain: targetChain,
-                    target_token: targetToken,
-                    source_amount: params.sourceAmount,
-                    target_amount: params.targetAmount,
-                    bridge_target_chain: bridgeTargetChain,
-                    ref: params.referralCode,
-                },
-            },
+            params: { query },
         });
         if (error) {
             throw new Error(`Failed to get quote: ${JSON.stringify(error)}`);
@@ -815,8 +882,17 @@ export class Client {
             swap.direction === "lightning_to_evm" ||
             swap.direction === "bitcoin_to_evm") {
             const evmSwap = swap;
-            // Use the stored target address - this was set when the swap was created
-            const destination = evmSwap.target_evm_address ?? evmSwap.client_evm_address;
+            // For Solana bridge targets the stored `target_evm_address` actually
+            // holds a base58 SPL pubkey, which can't satisfy the EIP-712
+            // `address destination` field. Fall back to `client_evm_address`
+            // (the user's EVM-side wallet at swap creation, used for refunds);
+            // the actual Solana destination rides on `bridgeRecipient`.
+            const bridgeTargetChain = evmSwap
+                .bridge_target_chain;
+            const isSolanaBridge = bridgeTargetChain === "Solana";
+            const destination = isSolanaBridge
+                ? evmSwap.client_evm_address
+                : (evmSwap.target_evm_address ?? evmSwap.client_evm_address);
             if (!destination) {
                 return {
                     success: false,
@@ -824,7 +900,17 @@ export class Client {
                         "This swap may have been created before target address storage was implemented.",
                 };
             }
-            const gaslessResult = await this.claimViaGasless(id, destination);
+            if (isSolanaBridge && !options?.bridgeRecipient) {
+                return {
+                    success: false,
+                    message: "Solana bridge claim requires `bridgeRecipient` (the recipient's USDC ATA) " +
+                        "in claim options. Derive it via `deriveSolanaUsdcAta` before calling claim.",
+                };
+            }
+            const gaslessResult = await this.claimViaGasless(id, destination, {
+                bridgeRecipient: options?.bridgeRecipient,
+                bridgeRecipientWallet: options?.bridgeRecipientWallet,
+            });
             return {
                 success: true,
                 message: gaslessResult.message,
@@ -898,7 +984,7 @@ export class Client {
      * console.log("Claimed! TX:", result.txHash);
      * ```
      */
-    async claimViaGasless(id, destination, { slippage = 1.0 } = {}) {
+    async claimViaGasless(id, destination, { slippage = 1.0, bridgeRecipient, bridgeRecipientWallet, } = {}) {
         if (!this.#swapStorage) {
             throw new Error("Swap storage is not configured. Cannot retrieve preimage needed for gasless claim.");
         }
@@ -917,10 +1003,20 @@ export class Client {
         }
         // Always fetch redeem calldata from the server to get calls_hash.
         // For non-WBTC targets this also returns DEX calldata.
+        // bridge_recipient is forwarded for non-EVM bridge targets (e.g.
+        // Solana) so the server's calls_hash matches what claim-gasless
+        // will rebuild below.
         const calldataResponse = await this.#apiClient.GET("/swap/{id}/redeem-and-swap-calldata", {
             params: {
                 path: { id },
-                query: { destination, slippage },
+                query: {
+                    destination,
+                    slippage,
+                    ...(bridgeRecipient ? { bridge_recipient: bridgeRecipient } : {}),
+                    ...(bridgeRecipientWallet
+                        ? { bridge_recipient_wallet: bridgeRecipientWallet }
+                        : {}),
+                },
             },
         });
         if (calldataResponse.error) {
@@ -948,6 +1044,8 @@ export class Client {
             destination,
             dexCalldata,
             callsHash,
+            bridgeRecipient,
+            bridgeRecipientWallet,
         });
     }
     /**
@@ -1011,9 +1109,9 @@ export class Client {
         }
         // Extract common VHTLC parameters
         const claimParams = this.#extractArkadeClaimParams(id, storedSwap);
-        // Query VTXO status to determine claim method
-        const amounts = await this.amountsForSwap(id);
-        const vtxoStatus = amounts.vtxoStatus;
+        // Query VTXO status to determine claim method, polling briefly while
+        // the Arkade indexer catches up if the funding tx hasn't been seen yet.
+        const vtxoStatus = await this.#waitForVtxoStatus(id, options.waitForVtxoMs ?? 30_000);
         if (vtxoStatus === "not_funded" || vtxoStatus === "spent") {
             return {
                 success: false,
@@ -1031,6 +1129,32 @@ export class Client {
         // recoverable or mixed → delegate
         return this.#claimArkadeDelegate(id, claimParams, options);
     }
+    /**
+     * Poll `amountsForSwap` until the VTXO status leaves `not_funded` or
+     * the timeout elapses. Returns the most recent status observed.
+     *
+     * Uses an exponential-ish backoff capped at 2s between probes so the
+     * usual case (indexer catches up within a few seconds) feels snappy
+     * without hammering the server.
+     */
+    async #waitForVtxoStatus(id, timeoutMs) {
+        const deadline = Date.now() + Math.max(0, timeoutMs);
+        let delayMs = 500;
+        // First probe is immediate; subsequent probes back off.
+        while (true) {
+            const amounts = await this.amountsForSwap(id);
+            if (amounts.vtxoStatus !== "not_funded")
+                return amounts.vtxoStatus;
+            if (Date.now() >= deadline)
+                return amounts.vtxoStatus;
+            const remaining = deadline - Date.now();
+            const sleepMs = Math.min(delayMs, remaining);
+            if (sleepMs <= 0)
+                return amounts.vtxoStatus;
+            await new Promise((resolve) => setTimeout(resolve, sleepMs));
+            delayMs = Math.min(delayMs * 2, 2_000);
+        }
+    }
     /**
      * Continue (finalize) a pending Arkade claim.
      *
@@ -1273,6 +1397,10 @@ export class Client {
             }
             return this.#buildEvmToLightningRefund(id, swap, settlement);
         }
+        // Arkade-to-Lightning: collaborative refund or locktime refund
+        if (direction === "arkade_to_lightning") {
+            return this.#buildArkadeToLightningRefund(id, swap, options);
+        }
         return {
             success: false,
             message: `Refund not supported for direction: ${direction}.`,
@@ -1768,7 +1896,7 @@ export class Client {
         };
         try {
             if (vtxoStatus === "spendable") {
-                const result = await collabRefundOffchain(collabParams);
+                const result = await collabRefundArkadeToEvmOffchain(collabParams);
                 return {
                     success: true,
                     message: "Arkade refund executed successfully via collaborative offchain spend!",
@@ -1778,7 +1906,7 @@ export class Client {
                 };
             }
             // recoverable or mixed → collab delegate
-            const result = await collabRefundDelegate(collabParams);
+            const result = await collabRefundArkadeToEvmDelegate(collabParams);
             return {
                 success: true,
                 message: "Arkade refund executed successfully via collaborative delegated settlement!",
@@ -1810,6 +1938,132 @@ export class Client {
         // recoverable or mixed → delegate
         return this.#refundArkadeDelegate(refundParams, options);
     }
+    /**
+     * Refund an Arkade-to-Lightning swap.
+     *
+     * Two paths:
+     * 1. **Collaborative refund** (instant) — available when status is `serverwontfund` or `clientinvalidfunded`
+     * 2. **Locktime refund** (after CLTV expiry) — fallback when the receiver doesn't cooperate
+     *
+     * For retrying with a new invoice, use {@link retryArkadeToLightningSwap} instead.
+     * @internal
+     */
+    async #buildArkadeToLightningRefund(id, swap, options) {
+        if (!options?.destinationAddress) {
+            return {
+                success: false,
+                message: "Destination address is required for Arkade refunds. " +
+                    'Provide it via the options parameter: { destinationAddress: "ark1..." }',
+            };
+        }
+        if (!this.#swapStorage) {
+            return {
+                success: false,
+                message: "Swap storage is not configured. Cannot retrieve the secret key needed for refund.",
+            };
+        }
+        const storedSwap = await this.#swapStorage.get(id);
+        if (!storedSwap) {
+            return {
+                success: false,
+                message: `Swap ${id} not found in local storage. The secret key is required to sign the refund transaction.`,
+            };
+        }
+        if (swap.direction !== "arkade_to_lightning") {
+            return {
+                success: false,
+                message: `Expected arkade_to_lightning swap, got ${swap.direction}`,
+            };
+        }
+        const s = swap;
+        const fullPubKey = storedSwap.publicKey;
+        const userPubKey = fullPubKey.length === 66 ? fullPubKey.slice(2) : fullPubKey;
+        const hashLock = s.hash_lock.startsWith("0x")
+            ? s.hash_lock.slice(2)
+            : s.hash_lock;
+        // Try collaborative refund first (instant)
+        try {
+            // TODO: Add collabRefundArkadeToLightningDelegate
+            const result = await collabRefundArkadeToLightningOffchain({
+                userSecretKey: storedSwap.secretKey,
+                userPubKey,
+                receiverPubKey: s.receiver_pk,
+                arkadeServerPubKey: s.arkade_server_pk,
+                hashLock,
+                vhtlcAddress: s.arkade_vhtlc_address,
+                refundLocktime: s.vhtlc_refund_locktime,
+                unilateralClaimDelay: s.unilateral_claim_delay,
+                unilateralRefundDelay: s.unilateral_refund_delay,
+                unilateralRefundWithoutReceiverDelay: s.unilateral_refund_without_receiver_delay,
+                destinationAddress: options.destinationAddress,
+                network: s.network,
+                arkadeServerUrl: options.arkadeServerUrl ?? this.#config.arkadeServerUrl,
+                swapId: id,
+                apiClient: this.#apiClient,
+            });
+            return {
+                success: true,
+                message: "Arkade-to-Lightning refund executed via collaborative refund!",
+                txId: result.txId,
+                refundAmount: result.refundAmount,
+                broadcast: true,
+            };
+        }
+        catch (collabError) {
+            const collabMsg = collabError instanceof Error
+                ? collabError.message
+                : String(collabError);
+            console.warn(`collaborative refund failed (${collabMsg}), checking locktime fallback`);
+        }
+        // Fallback: non-collaborative refund (requires locktime to have expired)
+        // TODO: Should use Bitcoin's MTP.
+        const now = Math.floor(Date.now() / 1000);
+        if (now < s.vhtlc_refund_locktime) {
+            const remainingSeconds = s.vhtlc_refund_locktime - now;
+            const remainingMinutes = Math.ceil(remainingSeconds / 60);
+            return {
+                success: false,
+                message: `collaborative refund failed and non-collaborative refund ` +
+                    `is not yet available. The VHTLC locktime expires in ${remainingMinutes} minutes ` +
+                    `(at ${new Date(s.vhtlc_refund_locktime * 1000).toISOString()}). ` +
+                    `Try again after the locktime expires, or use retryArkadeToLightningSwap() to ` +
+                    `retry with a new Lightning invoice.`,
+            };
+        }
+        // Locktime expired — use refund_without_receiver path (2-of-2: sender + server)
+        // This reuses the existing Arkade refund logic — lendaswapPubKey is set to
+        // the receiver key from this swap's VHTLC script.
+        // TODO: Not yet e2e-tested!
+        const refundParams = {
+            userSecretKey: storedSwap.secretKey,
+            userPubKey,
+            lendaswapPubKey: s.receiver_pk,
+            arkadeServerPubKey: s.arkade_server_pk,
+            hashLock,
+            vhtlcAddress: s.arkade_vhtlc_address,
+            refundLocktime: s.vhtlc_refund_locktime,
+            unilateralClaimDelay: s.unilateral_claim_delay,
+            unilateralRefundDelay: s.unilateral_refund_delay,
+            unilateralRefundWithoutReceiverDelay: s.unilateral_refund_without_receiver_delay,
+            destinationAddress: options.destinationAddress,
+            network: s.network,
+        };
+        // Query VTXO status to determine refund method
+        const amounts = await this.amountsForSwap(id);
+        const vtxoStatus = amounts.vtxoStatus;
+        if (vtxoStatus === "not_funded" || vtxoStatus === "spent") {
+            return {
+                success: false,
+                message: vtxoStatus === "not_funded"
+                    ? "No VTXOs found at the VHTLC address."
+                    : "All VTXOs have already been spent.",
+            };
+        }
+        if (vtxoStatus === "spendable") {
+            return this.#refundArkadeOffchain(refundParams, options);
+        }
+        return this.#refundArkadeDelegate(refundParams, options);
+    }
     /**
      * Refunds via the offchain submitTx/finalizeTx path (spendable VTXOs only).
      * @internal
@@ -2312,7 +2566,8 @@ export class Client {
         const targetAsset = "token_id" in tgt
             ? { chain: tgt.chain, token_id: tgt.token_id }
             : { chain: tgt.chain, token_id: tgt.tokenId };
-        const sourceChain = sourceAsset.chain;
+        let sourceChain = sourceAsset.chain;
+        let sourceTokenId = sourceAsset.token_id;
         let targetChain = targetAsset.chain;
         let tokenAddress = targetAsset.token_id;
         // If the target is a bridge-only chain (e.g. USDC on Base), automatically
@@ -2329,6 +2584,7 @@ export class Client {
                     targetTokenAddress: isUsdt0
                         ? USDT0_ADDRESSES[chainName]
                         : USDC_ADDRESSES[chainName],
+                    recipientSetup: options.bridgeRecipientSetup,
                 };
                 targetChain = "42161"; // Arbitrum
                 tokenAddress = isUsdt0
@@ -2336,6 +2592,37 @@ export class Client {
                     : USDC_ADDRESSES.Arbitrum;
             }
         }
+        else if (bridgeParams &&
+            options.bridgeRecipientSetup !== undefined &&
+            bridgeParams.recipientSetup === undefined) {
+            // Caller supplied `bridgeParams` without a `recipientSetup` but
+            // also passed the top-level hint — fold the hint in.
+            bridgeParams = {
+                ...bridgeParams,
+                recipientSetup: options.bridgeRecipientSetup,
+            };
+        }
+        // Mirror of the outbound remap for CCTP-inbound sources: when the user
+        // provides USDC on a chain the backend doesn't accept as a direct swap
+        // source (Optimism, Base, Linea, …), rewrite to Arbitrum USDC and
+        // populate `inboundBridgeParams` so the backend accounts for the
+        // CCTPv2 fast-transfer fee at quote + UserOp-calldata time.
+        let inboundBridgeParams = options.inboundBridgeParams;
+        const parsedSourceChainId = Number.parseInt(sourceChain, 10);
+        if (!inboundBridgeParams &&
+            !Number.isNaN(parsedSourceChainId) &&
+            isCctpOnlySource(parsedSourceChainId)) {
+            const source = cctpMetaForChainId(parsedSourceChainId);
+            if (sourceTokenId.toLowerCase() !== source.usdc.toLowerCase()) {
+                throw new Error(`createSwap on ${source.name} requires native USDC (${source.usdc}); got ${sourceTokenId}. Only USDC is bridgeable via CCTP.`);
+            }
+            inboundBridgeParams = {
+                sourceChain: source.name,
+                sourceTokenAddress: source.usdc,
+            };
+            sourceChain = "42161";
+            sourceTokenId = USDC_ADDRESSES.Arbitrum;
+        }
         // Arkade → EVM
         if (isArkade(sourceAsset) && isEvmToken(targetChain)) {
             return this.createArkadeToEvmSwapGeneric({
@@ -2430,7 +2717,7 @@ export class Client {
             }
             return this.createEvmToArkadeSwapGeneric({
                 targetAddress: options.targetAddress,
-                tokenAddress: sourceAsset.token_id,
+                tokenAddress: sourceTokenId,
                 evmChainId: Number(sourceChain),
                 userAddress: options.userAddress ?? "",
                 sourceAmount: options.sourceAmount
@@ -2439,6 +2726,7 @@ export class Client {
                 targetAmount: options.targetAmount,
                 referralCode: options.referralCode,
                 gasless: options.gasless,
+                inboundBridgeParams,
             });
         }
         // EVM → Bitcoin (on-chain)
@@ -2447,7 +2735,7 @@ export class Client {
                 throw new Error("userAddress is required for EVM → Bitcoin swaps (unless gasless)");
             }
             return this.createEvmToBitcoinSwap({
-                tokenAddress: sourceAsset.token_id,
+                tokenAddress: sourceTokenId,
                 evmChainId: Number(sourceChain),
                 userAddress: options.userAddress ?? "",
                 targetAddress: options.targetAddress,
@@ -2457,6 +2745,7 @@ export class Client {
                 targetAmount: options.targetAmount,
                 referralCode: options.referralCode,
                 gasless: options.gasless,
+                inboundBridgeParams,
             });
         }
         // EVM → Lightning
@@ -2480,10 +2769,11 @@ export class Client {
                         : { lnurl: options.targetAddress }),
                     amountSats: options.targetAmount,
                     evmChainId: Number(sourceChain),
-                    tokenAddress: sourceAsset.token_id,
+                    tokenAddress: sourceTokenId,
                     userAddress: options.userAddress ?? "",
                     referralCode: options.referralCode,
                     gasless: options.gasless,
+                    inboundBridgeParams,
                 });
             }
             if (isArkade(targetAsset) && isLightning(sourceAsset)) {
@@ -2499,10 +2789,11 @@ export class Client {
             return this.createEvmToLightningSwapGeneric({
                 lightningInvoice: options.targetAddress,
                 evmChainId: Number(sourceChain),
-                tokenAddress: sourceAsset.token_id,
+                tokenAddress: sourceTokenId,
                 userAddress: options.userAddress ?? "",
                 referralCode: options.referralCode,
                 gasless: options.gasless,
+                inboundBridgeParams,
             });
         }
         throw new Error(`Unsupported swap direction: ${sourceChain} → ${targetChain}`);
@@ -2600,7 +2891,7 @@ export class Client {
      * Creates a new Lightning to Arkade swap.
      *
      * The user pays a Lightning invoice and receives Arkade VTXOs
-     * after Boltz funds the Arkade VHTLC.
+     * after the server funds the Arkade VHTLC.
      *
      * @param options - The swap options.
      * @returns The swap response and parameters for storage.
@@ -2625,7 +2916,7 @@ export class Client {
      * Creates a new Arkade to Lightning swap.
      *
      * The user sends Arkade VTXOs and a Lightning invoice gets paid
-     * via a Boltz submarine swap.
+     * via the Lendaswap server.
      *
      * @param options - The swap options.
      * @returns The swap response and parameters for storage.
@@ -2644,6 +2935,183 @@ export class Client {
         return createArkadeToLightningSwap(options, this.#getCreateContext());
     }
     // =========================================================================
+    // Arkade-to-Lightning: Fee Estimation & Retry
+    // =========================================================================
+    /**
+     * Calculate the correct Lightning invoice amount for an Arkade→Lightning swap.
+     *
+     * Given the source amount in sats (what will be locked in the VHTLC), returns
+     * the target amount that the Lightning invoice should be for (after fees
+     * are deducted).
+     *
+     * Useful for:
+     * - Knowing what invoice amount to generate before creating a swap
+     * - Retrying a failed swap: the user's funds are locked in the old VHTLC at
+     *   `sourceAmountSats`, and the new invoice must match the expected target amount
+     *
+     * @param sourceAmountSats - Amount in sats that will fund the VHTLC
+     * @returns Quote with target amount, fee breakdown, and exchange rate
+     * @throws Error if the quote request fails or the amount is out of range
+     *
+     * @example
+     * ```ts
+     * const quote = await client.getArkadeToLightningQuote(100000);
+     * console.log(`Invoice should be for ${quote.target_amount} sats`);
+     * console.log(`Fees: ${quote.fee} sats`);
+     * ```
+     */
+    async getArkadeToLightningQuote(sourceAmountSats) {
+        const { data, error } = await this.#apiClient.GET("/quote", {
+            params: {
+                query: {
+                    source_chain: "Arkade",
+                    source_token: "btc",
+                    target_chain: "Lightning",
+                    target_token: "btc",
+                    source_amount: sourceAmountSats,
+                },
+            },
+        });
+        if (error) {
+            throw new Error(`Failed to get Arkade→Lightning quote: ${typeof error === "string" ? error : JSON.stringify(error)}`);
+        }
+        if (!data) {
+            throw new Error("No quote data returned");
+        }
+        return data;
+    }
+    /**
+     * Retry a failed Arkade→Lightning swap with a new Lightning invoice or LNURL.
+     *
+     * When an Arkade→Lightning swap fails (status `serverwontfund` or `clientinvalidfunded`),
+     * this method:
+     * 1. Creates a new Arkade→Lightning swap with the new invoice/LNURL
+     * 2. Collaboratively refunds the old VHTLC into the new swap's VHTLC
+     *
+     * The refund uses the collaborative `refund` script leaf (3-of-3: sender + receiver + Arkade),
+     * which is instant (no locktime wait). The receiver cooperates because the swap is in
+     * `invoice.failedToPay` state.
+     *
+     * **Invoice amount**: The new invoice must match the expected target amount for the
+     * source amount locked in the old VHTLC. Use {@link getArkadeToLightningQuote} to
+     * calculate the correct invoice amount, or use `lightningAddress` (LNURL) which
+     * handles amount negotiation automatically.
+     *
+     * @param swapId - ID of the failed swap (must be in `serverwontfund` or `clientinvalidfunded` status)
+     * @param options - New invoice or Lightning address for the retry
+     * @returns The new swap response and the refund transaction ID
+     * @throws Error if the swap is not in the right state, amount mismatch, or server refuses
+     *
+     * @example
+     * ```ts
+     * // With LNURL (recommended — handles amount automatically):
+     * const result = await client.retryArkadeToLightningSwap(swapId, {
+     *   lightningAddress: "user@speed.app",
+     * });
+     *
+     * // With invoice (must match expected amount):
+     * const quote = await client.getArkadeToLightningQuote(oldSwap.boltz_amount_sats);
+     * // Generate invoice for quote.target_amount sats, then:
+     * const result = await client.retryArkadeToLightningSwap(swapId, {
+     *   lightningInvoice: "lnbc...",
+     * });
+     * ```
+     */
+    async retryArkadeToLightningSwap(swapId, options) {
+        if (!this.#swapStorage) {
+            throw new Error("Swap storage not configured. Cannot retrieve keys needed for refund.");
+        }
+        if (!options.lightningInvoice && !options.lightningAddress) {
+            throw new Error("Provide either lightningInvoice or lightningAddress for retry");
+        }
+        if (options.lightningInvoice && options.lightningAddress) {
+            throw new Error("Provide either lightningInvoice or lightningAddress, not both");
+        }
+        // 1. Validate the old swap is in a retryable state
+        const oldSwap = await this.getSwap(swapId, {
+            updateStorage: true,
+        });
+        if (oldSwap.direction !== "arkade_to_lightning") {
+            throw new Error(`Expected arkade_to_lightning swap, got ${oldSwap.direction}`);
+        }
+        const retryableStatuses = ["serverwontfund", "clientinvalidfunded"];
+        if (!retryableStatuses.includes(oldSwap.status)) {
+            throw new Error(`Swap must be in serverwontfund or clientinvalidfunded status to retry ` +
+                `(current: ${oldSwap.status}). ` +
+                (oldSwap.status === "serverredeemed"
+                    ? "This swap completed successfully — no retry needed."
+                    : oldSwap.status === "clientrefunded"
+                        ? "This swap was already refunded."
+                        : "The swap may still be in progress."));
+        }
+        // 2. Get the source amount locked in the old VHTLC
+        const sourceAmountSats = oldSwap.boltz_amount_sats;
+        // 3. Build create-swap options
+        const createOptions = {};
+        if (options.lightningAddress) {
+            // LNURL: use the quote to determine the right amount
+            const quote = await this.getArkadeToLightningQuote(sourceAmountSats);
+            createOptions.lightningAddress = options.lightningAddress;
+            createOptions.amountSats = Number(quote.target_amount);
+        }
+        else if (options.lightningInvoice) {
+            createOptions.lightningInvoice = options.lightningInvoice;
+        }
+        // 4. Create the new swap
+        const newSwapResult = await this.createArkadeToLightningSwap(createOptions);
+        const newSwap = newSwapResult.response;
+        // 5. Verify the new swap's expected funding amount matches our old VHTLC
+        const newExpectedAmount = newSwap.boltz_amount_sats;
+        if (newExpectedAmount !== sourceAmountSats) {
+            const mismatchHint = newExpectedAmount > sourceAmountSats
+                ? "The invoice amount may be too high"
+                : "The invoice amount may be too low";
+            throw new Error(`Amount mismatch: new swap expects ${newExpectedAmount} sats in VHTLC ` +
+                `but old VHTLC has ${sourceAmountSats} sats. ` +
+                `${mismatchHint} — use getArkadeToLightningQuote(${sourceAmountSats}) ` +
+                `to calculate the correct invoice amount before retrying.`);
+        }
+        const storedSwap = await this.#swapStorage.get(swapId);
+        if (!storedSwap) {
+            throw new Error(`Swap ${swapId} not found in local storage. ` +
+                `The secret key is required to sign the collaborative refund.`);
+        }
+        const fullPubKey = storedSwap.publicKey;
+        const userPubKey = fullPubKey.length === 66 ? fullPubKey.slice(2) : fullPubKey;
+        const hashLock = oldSwap.hash_lock.startsWith("0x")
+            ? oldSwap.hash_lock.slice(2)
+            : oldSwap.hash_lock;
+        // Collaborative refund: old VHTLC → new VHTLC address
+        console.log("[retry] Starting collaborative refund", {
+            oldSwapId: swapId,
+            newSwapId: newSwap.id,
+            sourceAmount: sourceAmountSats,
+            network: oldSwap.network,
+        });
+        const refundResult = await collabRefundArkadeToLightningOffchain({
+            userSecretKey: storedSwap.secretKey,
+            userPubKey,
+            receiverPubKey: oldSwap.receiver_pk,
+            arkadeServerPubKey: oldSwap.arkade_server_pk,
+            hashLock,
+            vhtlcAddress: oldSwap.arkade_vhtlc_address,
+            refundLocktime: oldSwap.vhtlc_refund_locktime,
+            unilateralClaimDelay: oldSwap.unilateral_claim_delay,
+            unilateralRefundDelay: oldSwap.unilateral_refund_delay,
+            unilateralRefundWithoutReceiverDelay: oldSwap.unilateral_refund_without_receiver_delay,
+            destinationAddress: newSwap.arkade_vhtlc_address,
+            network: oldSwap.network,
+            arkadeServerUrl: this.#config.arkadeServerUrl,
+            swapId,
+            apiClient: this.#apiClient,
+        });
+        return {
+            newSwap,
+            refundTxId: refundResult.txId,
+            refundAmount: refundResult.refundAmount,
+        };
+    }
+    // =========================================================================
     // Swap Creation - EVM to Arkade
     // =========================================================================
     /**
@@ -2959,7 +3427,16 @@ export class Client {
      *
      * @param swapId - The UUID of the swap
      * @param signer - An {@link EvmSigner} wrapping the user's wallet
-     * @returns The funding transaction hash
+     * @param options - Optional CCTP-path tuning: `maxFee` caps the
+     *                  CCTP fast-transfer fee (defaults to the
+     *                  IRIS-quoted value); `onProgress` receives
+     *                  per-phase updates during the CCTP flow;
+     *                  `signal` aborts the attestation wait. All
+     *                  three are ignored when the swap takes the
+     *                  direct-Permit2 path.
+     * @returns The funding transaction hash, plus an optional `cctp`
+     *          object with `burnTxHash`, `userOpHash`, and
+     *          `smartAccountAddress` when the CCTP path ran.
      *
      * @example
      * ```ts
@@ -2977,7 +3454,63 @@ export class Client {
      * const { txHash } = await client.fundSwap(swapId, signer);
      * ```
      */
-    async fundSwap(swapId, signer) {
+    async fundSwap(swapId, signer, options) {
+        // Dispatch the CCTP-inbound path only for chains the backend does
+        // NOT accept as a direct swap source (Optimism, Base, Linea, …).
+        // Ethereum / Polygon / Arbitrum fund via Permit2 on the source
+        // chain even though they're CCTP-supported. Source asset must be
+        // native USDC for the chain — otherwise CCTP isn't viable and we
+        // surface a clear error instead of silently burning the wrong
+        // token through TokenMessenger.
+        if (isCctpOnlySource(signer.chainId)) {
+            const stored = await this.#swapStorage?.get(swapId);
+            const swapResponse = stored?.response ??
+                (await this.getSwap(swapId, { updateStorage: true }));
+            const source = cctpMetaForChainId(signer.chainId);
+            // CCTP-inbound swaps are stored against post-hop Arbitrum USDC
+            // (`source_token` reports the Arbitrum address), so we validate
+            // against the `bridge_source_*` fields the backend sets when the
+            // swap was created through the CCTP path. If those are missing
+            // the swap wasn't created for a CCTP-inbound flow — reject rather
+            // than silently burn USDC through the TokenMessenger.
+            const bridgeSourceChain = swapResponse.bridge_source_chain;
+            const bridgeSourceToken = swapResponse.bridge_source_token_address;
+            if (!bridgeSourceChain || !bridgeSourceToken) {
+                throw new Error(`fundSwap on chain ${signer.chainId} expects a CCTP-inbound swap but the swap has no bridge_source_chain set. ` +
+                    `Was the swap created against native USDC on a CCTP-only chain?`);
+            }
+            if (bridgeSourceChain !== source.name) {
+                throw new Error(`fundSwap signer is on ${source.name} but the swap was created for bridge source ${bridgeSourceChain}.`);
+            }
+            if (bridgeSourceToken.toLowerCase() !== source.usdc.toLowerCase()) {
+                throw new Error(`fundSwap on ${source.name} requires native USDC (${source.usdc}), but swap's bridge_source_token_address is ${bridgeSourceToken}. ` +
+                    `Only native USDC is bridgeable via CCTP.`);
+            }
+            const rawAmount = swapResponse
+                .source_amount;
+            if (rawAmount === undefined) {
+                throw new Error(`Swap ${swapId} has no source_amount — cannot route CCTP fund.`);
+            }
+            const amount = BigInt(rawAmount);
+            const destination = cctpMetaForChainId(42161);
+            const maxFee = options?.maxFee ??
+                computeCctpFastFee(await getCachedCctpFee({
+                    sourceDomain: source.domain,
+                    destinationDomain: destination.domain,
+                }), amount);
+            const cctp = await this.cctpInbound.fundSwap({
+                swapId,
+                signer,
+                amount,
+                maxFee,
+                onProgress: options?.onProgress,
+                signal: options?.signal,
+            });
+            return { txHash: cctp.transactionHash ?? cctp.userOpHash, cctp };
+        }
+        // Direct Permit2 path — Ethereum, Polygon, Arbitrum, or any other
+        // chain `signer.chainId` specifies. Unchanged from the original
+        // behaviour.
         // 1. Fetch Permit2 funding params
         const funding = await this.getPermit2FundingParamsUnsigned(swapId, signer.chainId);
         const tokenAddress = funding.sourceTokenAddress;