@xswap-link/sdk 0.15.1 → 0.15.2

package/src/components/Swap/SwapView/ConfirmationView/TxResult/index.tsx

@@ -4,25 +4,95 @@ import {
   RedirectThinIcon,
 } from "@src/assets/icons";
 import { useSwapContext, useTxUIWrapper } from "@src/context";
+import { CrossChainDelivery } from "@src/hooks";
+import { Ecosystem } from "@src/models";
+import { useMemo } from "react";
 import { TokenTiles } from "../TokenTiles";
 
 type Props = {
   onCloseClick: () => void;
+  /**
+   * How the transfer actually settled. Absent for the flows whose delivery is not
+   * tracked — a single-chain swap, a non-EVM source, or a standalone transaction run
+   * through this modal — where the source receipt is the whole story.
+   */
+  delivery?: CrossChainDelivery;
 };
 
-export const TxResult = ({ onCloseClick }: Props) => {
+export const TxResult = ({ onCloseClick, delivery }: Props) => {
   const { txError, txExplorerUrl, txMsg } = useTxUIWrapper();
-  const { isExpressDeliveryActive, srcChain, dstChain } = useSwapContext();
+  const { isExpressDeliveryActive, srcChain, dstChain, supportedChains } =
+    useSwapContext();
+
+  const isCrossChain =
+    !!srcChain && !!dstChain && srcChain.chainId !== dstChain.chainId;
+  const failed = !!txError || !!delivery?.isFailed;
+  // Delivered, but as the bridged token: the destination swap never ran, and it
+  // never will — so this is an outcome to report, not a step still pending.
+  const partiallyFailed = !!delivery?.isPartiallyFailed;
+
+  const targetTx = delivery?.response?.targetTx;
+  const targetExplorerUrl = useMemo(() => {
+    if (!targetTx) {
+      return undefined;
+    }
+    const explorer = supportedChains.find(
+      (chain) =>
+        chain.chainId === targetTx.chainId && chain.ecosystem === Ecosystem.EVM,
+    )?.transactionExplorer;
+    return explorer ? `${explorer}/${targetTx.hash}` : undefined;
+  }, [supportedChains, targetTx]);
+
+  const note = useMemo(() => {
+    if (delivery?.isFailed) {
+      return `The transaction failed on ${
+        srcChain?.displayName || "the source chain"
+      }.`;
+    }
+    if (partiallyFailed) {
+      return `The swap on ${
+        dstChain?.displayName || "the destination chain"
+      } could not be completed, so the bridged tokens were sent to your wallet instead.`;
+    }
+    if (delivery?.isDelivered) {
+      return `Funds delivered on ${
+        dstChain?.displayName || "the destination chain"
+      }.`;
+    }
+    // Nothing was tracked (non-EVM source), so the estimate is all there is. Read
+    // the speed off the quote, never off the express-delivery fee — a fast CCTP
+    // transfer pays Circle out of the bridged USDC and charges no express fee.
+    if (isCrossChain) {
+      return `Approximated time of delivery: ${
+        isExpressDeliveryActive ? "30 sec" : "30 min"
+      }`;
+    }
+    return undefined;
+  }, [
+    delivery?.isDelivered,
+    delivery?.isFailed,
+    partiallyFailed,
+    isCrossChain,
+    isExpressDeliveryActive,
+    srcChain?.displayName,
+    dstChain?.displayName,
+  ]);
 
   return (
     <div className="flex flex-col gap-8 text-t_text_primary">
       <div className="flex flex-col gap-2">
         <div className="flex items-center gap-3">
           <div className="text-2xl font-medium leading-8 tracking-[0.01em]">
-            {txError ? "Transaction Error" : "Transaction Success"}
+            {failed
+              ? "Transaction Error"
+              : partiallyFailed
+                ? "Partially Completed"
+                : "Transaction Success"}
           </div>
-          {txError ? (
+          {failed ? (
             <ErrorCircleThinIcon className="w-6 h-6 shrink-0 text-[#F44336]" />
+          ) : partiallyFailed ? (
+            <ErrorCircleThinIcon className="w-6 h-6 shrink-0 text-t_warning_light" />
           ) : (
             <CheckCircleThinIcon className="w-6 h-6 shrink-0 text-[#6AE89B]" />
           )}
@@ -33,11 +103,9 @@ export const TxResult = ({ onCloseClick }: Props) => {
           </div>
         ) : (
           !txMsg &&
-          srcChain !== dstChain && (
+          !!note && (
             <div className="text-sm leading-5 tracking-[0.01em] text-t_text_primary text-opacity-50">
-              {`Approximated time of delivery: ${
-                isExpressDeliveryActive ? "30 sec" : "30 min"
-              }`}
+              {note}
             </div>
           )
         )}
@@ -64,6 +132,19 @@ export const TxResult = ({ onCloseClick }: Props) => {
               <RedirectThinIcon className="w-3 h-3" />
             </div>
           </a>
+          {targetExplorerUrl && (
+            <a
+              href={targetExplorerUrl}
+              target="_blank"
+              rel="noreferrer"
+              className="flex items-center gap-1.5 text-sm text-t_text_primary text-opacity-25 hover:text-opacity-50 transition-colors"
+            >
+              View Delivery{" "}
+              <div className="w-6 h-6 bg-t_bg_tertiary bg-opacity-5 rounded-[4px] flex items-center justify-center">
+                <RedirectThinIcon className="w-3 h-3" />
+              </div>
+            </a>
+          )}
           <div className="flex-1 h-px bg-t_text_primary bg-opacity-10" />
         </div>
       )}

package/src/components/Swap/SwapView/ConfirmationView/index.tsx

@@ -1,17 +1,32 @@
 import { useTxUIWrapper } from "@src/context";
+import { CrossChainDelivery } from "@src/hooks";
 import { TxStatus } from "@src/models";
 import { TxOverview } from "./TxOverview";
+import { TxProgress } from "./TxProgress";
 import { TxResult } from "./TxResult";
 
 type Props = {
   onCloseClick: () => void;
+  /** Delivery tracking for the transfer in the modal, owned by {@link TxUIWrapper}
+   *  so the modal's own styling can follow it too. Idle unless one is in flight. */
+  delivery: CrossChainDelivery;
 };
-export const ConfirmationView = ({ onCloseClick }: Props) => {
+export const ConfirmationView = ({ onCloseClick, delivery }: Props) => {
   const { txStatus, txError } = useTxUIWrapper();
 
-  return txStatus === TxStatus.COMPLETED || txError ? (
-    <TxResult onCloseClick={onCloseClick} />
+  if (txError) {
+    return <TxResult onCloseClick={onCloseClick} delivery={delivery} />;
+  }
+
+  if (txStatus !== TxStatus.COMPLETED) {
+    return <TxOverview onCloseClick={onCloseClick} />;
+  }
+
+  // The source tx is mined, which for a cross-chain swap is the halfway point, not
+  // the end: hold the success view until the funds actually land on the destination.
+  return delivery.isPolling ? (
+    <TxProgress onCloseClick={onCloseClick} delivery={delivery} />
   ) : (
-    <TxOverview onCloseClick={onCloseClick} />
+    <TxResult onCloseClick={onCloseClick} delivery={delivery} />
   );
 };

package/src/components/Swap/SwapView/FeesPanel/Fees/index.tsx

@@ -1,5 +1,5 @@
 import { useSwapContext } from "@src/context";
-import { weiToHumanReadable } from "@src/utils";
+import { safeBigNumberFrom, weiToHumanReadable } from "@src/utils";
 import { Fee } from "../Fee";
 
 export const Fees = ({
@@ -7,8 +7,14 @@ export const Fees = ({
 }: {
   solanaBridgeFee: string | null;
 }) => {
-  const { route, slippage, feeToken, dstToken, expressDelivery } =
-    useSwapContext();
+  const { route, slippage, feeToken, dstToken } = useSwapContext();
+
+  // Only routes that buy their speed with an express-delivery fee have a fee to show.
+  // A fast CCTP transfer has none — Circle's fast-transfer fee is taken out of the
+  // bridged USDC — so the row would read "0" on the very routes that are fastest.
+  const expressDeliveryFee = safeBigNumberFrom(
+    route?.xSwapFees.expressDeliveryFee || "0",
+  );
 
   const fees = [
     {
@@ -33,13 +39,13 @@ export const Fees = ({
         }) || 0
       } ${feeToken?.symbol || ""}`,
     },
-    ...(expressDelivery
+    ...(expressDeliveryFee.gt(0)
       ? [
           {
             name: "Express delivery Fee: ",
             value: `${
               weiToHumanReadable({
-                amount: route?.xSwapFees.expressDeliveryFee || "0",
+                amount: expressDeliveryFee.toString(),
                 decimals: feeToken?.decimals || 18,
                 precisionFractionalPlaces: 5,
               }) || 0

package/src/context/SwapProvider.tsx

@@ -498,14 +498,29 @@ export const SwapProvider = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [route],
   );
-  // useMemo: checks if express delivery is enabled and if the route includes a non-zero express delivery fee.
-  const isExpressDeliveryActive = useMemo(
-    () =>
+  /**
+   * Whether the quote in hand is delivered as express delivery.
+   *
+   * The API states it on the route wherever the fee cannot: a CCTP transfer charges
+   * no express-delivery fee (Circle's fast-transfer fee comes out of the bridged
+   * USDC), so it reports the flag outright. That answer wins whenever it is there.
+   *
+   * Everywhere else the fee IS the signal — on the CCIP paths express delivery is
+   * what the non-zero express-delivery fee buys — so the fee test stays as the
+   * fallback.
+   */
+  const isExpressDeliveryActive = useMemo(() => {
+    if (!route) {
+      return false;
+    }
+    if (typeof route.expressDelivery === "boolean") {
+      return route.expressDelivery;
+    }
+    return (
       expressDelivery &&
-      !!route &&
-      BigNumber.from(route.xSwapFees?.expressDeliveryFee || "0").gt("0"),
-    [expressDelivery, route],
-  );
+      BigNumber.from(route.xSwapFees?.expressDeliveryFee || "0").gt("0")
+    );
+  }, [expressDelivery, route]);
   // useMemo: indicates whether asynchronous data is loaded based on the presence of supported chains.
   const isAsyncDataLoaded = useMemo(
     () => supportedChains.length > 0 && bridgeTokens.length > 0,

package/src/context/TxUIWrapper.tsx

@@ -8,6 +8,7 @@ import {
 } from "@src/components";
 import { ConfirmationView } from "@src/components/Swap/SwapView/ConfirmationView";
 import { CCIP_EXPLORER } from "@src/constants";
+import { useCrossChainDelivery } from "@src/hooks";
 import {
   Ecosystem,
   EnqueueTxProps,
@@ -63,7 +64,33 @@ export const TxUIWrapper = ({ children }: Props) => {
   const [txNeedsApproval, setTxNeedsApproval] = useState(false);
   const [txStatus, setTxStatus] = useState(TxStatus.SWAP_INIT);
 
-  const { supportedChains, setSrcValue } = useSwapContext();
+  const { supportedChains, setSrcValue, srcChain, dstChain } = useSwapContext();
+
+  // A cross-chain swap is only done when the funds land on the destination, so once
+  // the source tx is mined the transfer is followed to its end rather than declared
+  // finished (the poll is also what claims a CCTP transfer — see the hook). Tracked
+  // here, not in the view, so the modal's own styling can follow it too.
+  const isCrossChainSwap =
+    !!srcChain && !!dstChain && srcChain.chainId !== dstChain.chainId;
+  const delivery = useCrossChainDelivery({
+    enabled:
+      txStatus === TxStatus.COMPLETED &&
+      !txError &&
+      // Only while the modal is up: the chains below are the ones currently
+      // selected, and the user is free to pick different ones the moment they close
+      // it. An unclaimed CCTP transfer is the executor's and the sweep's job from
+      // there on, not this poll's.
+      isTxModalOpen &&
+      // A custom message means the modal is running a standalone transaction
+      // (an approval reset, say), not a swap with a destination leg.
+      !txMsg &&
+      isCrossChainSwap &&
+      // The status endpoint reads an EVM receipt; a Solana source has none.
+      srcChain?.ecosystem === Ecosystem.EVM,
+    chainId: srcChain?.chainId,
+    txHash,
+    walletAddress: evm.address,
+  });
 
   const closeTransactionModal = (transactionKey: number) => {
     if (txKey.current === transactionKey) {
@@ -435,14 +462,18 @@ export const TxUIWrapper = ({ children }: Props) => {
     isTxModalOpenRef.current = flag;
   }, []);
 
+  // Funds still in flight read as "waiting": the success glow belongs to the
+  // delivery, not to the source tx that started it.
   const modalType: TxModalType = useMemo(
     () =>
       txError
         ? "error"
+        : delivery.isPolling
+        ? "waiting"
         : txStatus === TxStatus.COMPLETED
         ? "success"
         : "neutral",
-    [txError, txStatus],
+    [txError, txStatus, delivery.isPolling],
   );
 
   const state = useMemo<TxUIWrapperState>(
@@ -490,7 +521,7 @@ export const TxUIWrapper = ({ children }: Props) => {
           type={modalType}
           onCloseClick={closeTxModal}
         >
-          <ConfirmationView onCloseClick={closeTxModal} />
+          <ConfirmationView onCloseClick={closeTxModal} delivery={delivery} />
         </TxModal>
       )}
       {children}

package/src/hooks/index.ts

@@ -1,4 +1,5 @@
 export * from "./useBatchQuery";
+export * from "./useCrossChainDelivery";
 export * from "./useDebounce";
 export * from "./useEvmContractApi";
 export * from "./useXPower";

package/src/hooks/useCrossChainDelivery.ts

@@ -0,0 +1,143 @@
+import {
+  CrossChainDeliveryStatus,
+  TransactionStatusResponse,
+} from "@src/models";
+import { getTransactionStatus } from "@src/services";
+import { useEffect, useState } from "react";
+
+/** Nothing changes after these: either the funds landed or they never will. */
+const TERMINAL_STATUSES: CrossChainDeliveryStatus[] = [
+  "DONE",
+  "PARTIALLY_FAILED",
+  "FAILED",
+];
+
+/** A fast transfer lands in ~20s, so poll often enough that the UI is not the
+ *  slowest part of it. */
+const POLL_INTERVAL_MS = 4000;
+/** Past the point where the user is plainly waiting on finality, not on us. */
+const SLOW_POLL_INTERVAL_MS = 15000;
+const SLOW_POLL_AFTER_MS = 3 * 60 * 1000;
+
+type Params = {
+  /** Poll only while this is true — set it false for anything the endpoint cannot
+   *  answer for (single-chain swaps, a non-EVM source, a tx that is not mined yet). */
+  enabled: boolean;
+  /** Source chain of the tx, i.e. the chain `txHash` was mined on. */
+  chainId?: string;
+  txHash?: string;
+  walletAddress?: string;
+};
+
+export type CrossChainDelivery = {
+  status: CrossChainDeliveryStatus | undefined;
+  response: TransactionStatusResponse | undefined;
+  /** Tracking this transfer and still waiting on it. */
+  isPolling: boolean;
+  isSettled: boolean;
+  isDelivered: boolean;
+  /** Delivered, but as the bridged token: the destination swap did not run. */
+  isPartiallyFailed: boolean;
+  isFailed: boolean;
+  /** When tracking began, for elapsed-time UI. Undefined while disabled. */
+  startedAt: number | undefined;
+};
+
+/**
+ * Follows a submitted cross-chain transfer to its destination.
+ *
+ * The poll is not just an observer: the API claims an attested-but-unclaimed CCTP
+ * transfer from inside the same call, so polling is also what keeps the delivery
+ * moving. Which is the point — most transfers land in well under a minute, and a
+ * client that waits out a fixed 30-minute estimate instead of asking is both wrong
+ * and slower than the transfer it is describing.
+ *
+ * Polling stops as soon as the answer is terminal, and backs off to a slow cadence
+ * once the wait is long enough to be finality rather than latency.
+ */
+export const useCrossChainDelivery = ({
+  enabled,
+  chainId,
+  txHash,
+  walletAddress,
+}: Params): CrossChainDelivery => {
+  const [response, setResponse] = useState<TransactionStatusResponse>();
+  const [startedAt, setStartedAt] = useState<number>();
+
+  const active = enabled && !!chainId && !!txHash;
+
+  useEffect(() => {
+    if (!active) {
+      setResponse(undefined);
+      setStartedAt(undefined);
+      return;
+    }
+
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const controller = new AbortController();
+    const startTime = Date.now();
+
+    setResponse(undefined);
+    setStartedAt(startTime);
+
+    const poll = async () => {
+      try {
+        const next = await getTransactionStatus(
+          {
+            chainId: chainId as string,
+            txHash: txHash as string,
+            walletAddress,
+          },
+          controller.signal,
+        );
+        if (cancelled) {
+          return;
+        }
+        setResponse(next);
+        if (TERMINAL_STATUSES.includes(next.status)) {
+          return;
+        }
+      } catch (err) {
+        if (cancelled) {
+          return;
+        }
+        // A single failed poll says nothing about the transfer — a cold RPC, a rate
+        // limit or a dropped request all look like this, and the next poll usually
+        // answers. Keep the loop alive and keep it out of the UI.
+        console.warn("Failed to read cross-chain delivery status:", err);
+      }
+
+      timer = setTimeout(
+        poll,
+        Date.now() - startTime > SLOW_POLL_AFTER_MS
+          ? SLOW_POLL_INTERVAL_MS
+          : POLL_INTERVAL_MS,
+      );
+    };
+
+    poll();
+
+    return () => {
+      cancelled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      controller.abort();
+    };
+  }, [active, chainId, txHash, walletAddress]);
+
+  const status = response?.status;
+  const isSettled = !!status && TERMINAL_STATUSES.includes(status);
+
+  return {
+    status,
+    response,
+    isPolling: active && !isSettled,
+    isSettled,
+    isDelivered: status === "DONE",
+    isPartiallyFailed: status === "PARTIALLY_FAILED",
+    isFailed: status === "FAILED",
+    startedAt,
+  };
+};

package/src/models/Route.ts

@@ -3,6 +3,19 @@ interface BaseRoute {
   minAmountOut: string;
   xSwapFees: XSwapFees;
   message?: string;
+  /**
+   * Whether the route is delivered as express delivery, stated outright by the API.
+   *
+   * Served by the bridges whose speed the fee breakdown cannot express — today CCTP,
+   * which reports true on every route: it charges no express-delivery fee at all
+   * (Circle's fast-transfer fee comes out of the bridged USDC), so a client reading
+   * the fee saw every CCTP transfer as the slow tier.
+   *
+   * Absent everywhere else (the CCIP paths, single-chain), where the fee IS the
+   * signal — express delivery there is what a non-zero `expressDeliveryFee` buys —
+   * so fall back to the fee when this is undefined, never instead of it.
+   */
+  expressDelivery?: boolean;
 }
 
 export interface EVMRoute extends BaseRoute {

package/src/models/TransactionDelivery.ts

@@ -0,0 +1,40 @@
+/**
+ * States the API reports for a submitted transaction (`GET /getTransactionStatus`).
+ *
+ * - `NOT_FOUND` — the source tx is not visible to the API's RPCs yet. Expected for
+ *   the first poll or two after a swap; it is not a failure.
+ * - `IN_PROGRESS` — the source tx is mined and the destination has not settled yet.
+ * - `DONE` — the destination leg ran and the user holds the token they asked for.
+ * - `PARTIALLY_FAILED` — the transfer arrived but its destination swap did not run
+ *   (or produced less than the committed minimum), so the bridged token was
+ *   forwarded to the receiver as-is. Terminal: no swap will happen later.
+ * - `FAILED` — the source tx itself reverted.
+ * - `STUCK` — mined, but the bridge has not moved it for long enough that it needs
+ *   looking at rather than waiting on.
+ */
+export type CrossChainDeliveryStatus =
+  | "NOT_FOUND"
+  | "IN_PROGRESS"
+  | "DONE"
+  | "STUCK"
+  | "FAILED"
+  | "PARTIALLY_FAILED";
+
+export type DeliveryTransferInfo = {
+  hash: string;
+  chainId: string;
+  /** Absent on the plain tx references (the middle hop), which carry no transfer. */
+  token?: string;
+  amount?: string;
+};
+
+export type TransactionStatusResponse = {
+  status: CrossChainDeliveryStatus;
+  integratorHash?: string;
+  /** The speed the transfer actually settled at, as resolved by the bridge itself. */
+  expressDelivery?: boolean;
+  receiver?: string;
+  sourceTx?: DeliveryTransferInfo;
+  middleTx?: DeliveryTransferInfo;
+  targetTx?: DeliveryTransferInfo;
+};

package/src/models/index.ts

@@ -13,6 +13,7 @@ export * from "./Protocol";
 export * from "./Route";
 export * from "./SolanaWeb3Network";
 export * from "./TokenData";
+export * from "./TransactionDelivery";
 export * from "./TransactionHistory";
 export * from "./TxUIWrapper";
 export * from "./Web3Environment";

package/src/services/api.ts

@@ -14,6 +14,7 @@ import {
   TokenPrices,
   TransactionHistory,
   TransactionStatus,
+  TransactionStatusResponse,
 } from "@src/models";
 
 let XSWAP_API_URL = "https://xswap.link/api";
@@ -148,6 +149,28 @@ export async function getBalances(payload: GetTokenBalancesPayload) {
   );
 }
 
+/**
+ * Status of a submitted transaction, source tx and destination leg included.
+ *
+ * Polling this is also what moves a CCTP transfer along: when the API sees one
+ * attested by Circle but not yet claimed on the destination, it hands it to its own
+ * executor from inside this call (CCTP has no auto-relay). So a client that shows
+ * delivery progress should poll it rather than wait out a fixed estimate.
+ *
+ * EVM only — `chainId`/`txHash` identify an EVM receipt.
+ */
+export async function getTransactionStatus(
+  payload: { chainId: string; txHash: string; walletAddress?: string },
+  abortSignal?: AbortSignal,
+): Promise<TransactionStatusResponse> {
+  return _sendRequest<TransactionStatusResponse>(
+    `/getTransactionStatus?${new URLSearchParams({
+      data: JSON.stringify(payload),
+    })}`,
+    { signal: abortSignal },
+  );
+}
+
 export async function getTxStatus(payload: { transferId: string }) {
   return await _sendRequest<{ status: TransactionStatus }>(
     `/getTxStatus?${new URLSearchParams({