@xswap-link/sdk 0.15.0 → 0.15.2

package/src/components/Swap/SwapView/SwapPanel/TokenPanel/TokenPicker/index.tsx

@@ -480,7 +480,7 @@ export const TokenPicker = ({
   return showImportWarning ? (
     <>
       <div className="flex justify-between items-center mb-6">
-        <div className="text-2xl leading-8 tracking-[0.01em]">
+        <div className="text-2xl font-medium leading-8 tracking-[0.01em]">
           Import token
         </div>
         <button
@@ -570,7 +570,7 @@ export const TokenPicker = ({
   ) : (
     <>
       <div className="flex justify-between items-center mb-6">
-        <div className="text-2xl leading-8 tracking-[0.01em] text-t_text_primary">
+        <div className="text-2xl font-medium leading-8 tracking-[0.01em] text-t_text_primary">
           Select Token
         </div>
         <button
@@ -626,7 +626,7 @@ export const TokenPicker = ({
                     <div className="text-sm font-medium text-ellipsis">
                       {customTokenData.name}
                     </div>
-                    <div className="text-xs text-t_text_primary !text-opacity-50 font-medium">
+                    <div className="text-xs text-t_text_primary !text-opacity-50">
                       {importChain?.displayName}
                     </div>
                   </div>
@@ -648,7 +648,7 @@ export const TokenPicker = ({
               <div className="flex flex-col h-full min-h-0">
                 {/* Pinned label of the group at the top of the list; sits
                     above the scroller, so rows clip on its bottom edge. */}
-                <p className="pb-3 text-[10px] font-medium leading-4 tracking-[0.015em] text-t_text_primary text-opacity-30 text-left shrink-0">
+                <p className="pb-3 text-[10px] leading-4 tracking-[0.015em] text-t_text_primary text-opacity-30 text-left shrink-0">
                   {pinnedGroupLabel}
                 </p>
                 <div className="relative flex flex-col flex-1 min-h-0">
@@ -663,7 +663,7 @@ export const TokenPicker = ({
                       }
                       if (row.kind === "label") {
                         return (
-                          <p className="pt-2 pb-3 text-[10px] font-medium leading-4 tracking-[0.015em] text-t_text_primary text-opacity-30 text-left">
+                          <p className="pt-2 pb-3 text-[10px] leading-4 tracking-[0.015em] text-t_text_primary text-opacity-30 text-left">
                             {row.label}
                           </p>
                         );

package/src/components/Swap/SwapView/SwapPanel/TokenPanel/index.tsx

@@ -1,5 +1,5 @@
 import { ChevronDownThinIcon } from "@src/assets/icons";
-import { TokenLogoWithChain } from "@src/components";
+import { Skeleton, TokenLogoWithChain } from "@src/components";
 import { useSwapContext } from "@src/context";
 import { Chain, Token } from "@src/models";
 import { useMemo } from "react";
@@ -19,6 +19,7 @@ export const TokenPanel = ({ chain, token, type, className }: Props) => {
     srcTokenLocked,
     dstChainLocked,
     setActivePicker,
+    isAsyncDataLoaded,
   } = useSwapContext();
 
   const integratorLockedDestinationToken = useMemo(
@@ -43,6 +44,25 @@ export const TokenPanel = ({ chain, token, type, className }: Props) => {
     integratorLockedDestinationToken ||
     integratorLockedSourceToken;
 
+  if (!isAsyncDataLoaded) {
+    // Mirror the loaded layout: symbol bar + token circle with the small
+    // chain badge, so nothing shifts when the real content arrives.
+    return (
+      <div
+        className={`flex items-center shrink-0 min-h-11 ${className || ""}`}
+        aria-hidden
+      >
+        <div className="flex items-center gap-3">
+          <Skeleton className="w-12 h-4" />
+          <div className="relative flex items-end pr-1 pb-1">
+            <Skeleton className="w-10 h-10 rounded-full" />
+            <Skeleton className="absolute bottom-0 right-0 w-[18px] h-[18px] rounded-full border border-solid border-t_bg_secondary" />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <button
       type="button"
@@ -86,7 +106,9 @@ export const TokenPanel = ({ chain, token, type, className }: Props) => {
         )}
       </div>
       {!locked && (
-        <div className="flex items-center justify-center w-6 h-6 text-t_text_primary opacity-50">
+        // The 24px glyph has 8px of built-in whitespace on each side; pull the
+        // right side back so the chevron sits flush with the panel edge.
+        <div className="flex items-center justify-center w-6 h-6 ml-1 -mr-2 text-t_text_primary opacity-50">
           <ChevronDownThinIcon />
         </div>
       )}

package/src/components/Swap/SwapView/SwapPanel/WalletPanel/index.tsx

@@ -1,4 +1,5 @@
 import { ChevronDownThinSmallIcon } from "@src/assets/icons";
+import { Skeleton } from "@src/components";
 import { useWallet } from "@src/context/WalletProvider";
 import { useSwapContext } from "@src/context";
 import { SwapPanelType } from "../..";
@@ -21,8 +22,12 @@ export const WalletPanel = ({ chain, className }: Props) => {
     solana,
     sui,
   } = useWallet();
-  const { integrationConfig, hasOnConnectWalletCallback, onConnectWallet } =
-    useSwapContext();
+  const {
+    integrationConfig,
+    hasOnConnectWalletCallback,
+    onConnectWallet,
+    isAsyncDataLoaded,
+  } = useSwapContext();
 
   const openEvmWalletModal = useCallback(() => {
     // Mirror SwapButton's contract: when the integrator supplied their own
@@ -68,6 +73,10 @@ export const WalletPanel = ({ chain, className }: Props) => {
     return "";
   }, [chain, evm, solana, sui]);
 
+  if (!isAsyncDataLoaded) {
+    return <Skeleton className="w-16 h-6" />;
+  }
+
   // Reserve the button's height before the chain loads so the card
   // doesn't grow when the wallet button appears.
   if (!chain) {
@@ -85,7 +94,9 @@ export const WalletPanel = ({ chain, className }: Props) => {
       <p className="text-[10px] leading-4 tracking-[0.01em] text-t_text_primary whitespace-nowrap">
         {address ? shortAddress(address) : "Connect"}
       </p>
-      <div className="flex items-center justify-center w-4 h-4 text-t_text_primary opacity-50">
+      {/* The 16px glyph has 6px of built-in whitespace on each side; pull the
+          right side back so the button's visual padding stays symmetric. */}
+      <div className="flex items-center justify-center w-4 h-4 -mr-1.5 text-t_text_primary opacity-50">
         <ChevronDownThinSmallIcon />
       </div>
     </button>

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

@@ -1,5 +1,5 @@
 import { useSwapContext } from "@src/context";
-import { useMemo } from "react";
+import { MouseEvent, useMemo } from "react";
 import { SwapPanelType } from "../index";
 import { AmountPanel } from "./AmountPanel";
 import { Balance } from "./AmountPanel/Balance";
@@ -23,11 +23,23 @@ export const SwapPanel = ({ type }: Props) => {
     [type, srcChain, dstChain],
   );
 
+  // The whole source card acts as the amount input's hit area; clicks on the
+  // nested buttons (wallet, MAX, token picker) must keep their own actions.
+  const focusAmountInput = (event: MouseEvent<HTMLDivElement>) => {
+    if (type !== "source" || (event.target as HTMLElement).closest("button")) {
+      return;
+    }
+    event.currentTarget
+      .querySelector<HTMLInputElement>("#swap-amount-input")
+      ?.focus();
+  };
+
   return (
     <div
+      onClick={focusAmountInput}
       className={`flex flex-col gap-2 px-4 sm:px-6 py-4 rounded-2xl backdrop-blur-[12px] ${
         type === "source"
-          ? "bg-gradient-to-r from-t_bg_tertiary/5 to-t_bg_tertiary/5 border border-solid border-t_text_primary border-opacity-25"
+          ? "bg-gradient-to-r from-t_bg_tertiary/5 to-t_bg_tertiary/5 swap-panel-gradient-border cursor-text"
           : "bg-gradient-to-r from-t_bg_tertiary/[0.03] to-t_bg_tertiary/[0.03]"
       }`}
     >

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

@@ -167,7 +167,7 @@ export const WalletPicker: FC<{
   return (
     <div className={`flex flex-col h-full min-h-0 ${className || ""}`}>
       <div className="flex justify-between items-center mb-6">
-        <div className="text-2xl leading-8 tracking-[0.01em] text-t_text_primary">
+        <div className="text-2xl font-medium leading-8 tracking-[0.01em] text-t_text_primary">
           Select Wallet
         </div>
         <button

package/src/components/ToggleButton/index.tsx

@@ -12,13 +12,15 @@ const ToggleButton = ({ checked, onClick }: Props) => {
       onClick={onClick}
       className={`relative inline-flex items-center w-10 h-5 p-0.5 rounded-full cursor-pointer transition-opacity border-none bg-gradient-to-r ${
         checked
-          ? "from-t_main_accent_light/25 to-t_main_accent_dark/25"
+          ? "from-x_blue_light/25 to-x_blue_dark/25"
           : "from-t_main_accent_light/20 to-t_main_accent_dark/20 opacity-50"
       }`}
     >
       <span
-        className={`w-4 h-4 rounded-full transition-transform bg-gradient-to-r from-t_main_accent_light to-t_main_accent_dark ${
-          checked ? "translate-x-5" : "translate-x-0"
+        className={`w-4 h-4 rounded-full transition-transform bg-gradient-to-r ${
+          checked
+            ? "translate-x-5 from-x_blue_light to-x_blue_dark"
+            : "translate-x-0 from-t_main_accent_light to-t_main_accent_dark"
         }`}
       ></span>
     </button>

package/src/components/TxModal/index.tsx

@@ -38,12 +38,8 @@ export const TxModal = ({
       onMouseDown={onBackdropClick}
     >
       <div
-        className={`relative rounded-[32px] p-6 sm:p-8 w-full min-w-[340px] overflow-auto max-w-x_modal backdrop-blur-[32px] bg-t_bg_secondary bg-opacity-75 border border-solid ${
-          type === "error"
-            ? "border-[#F44336]"
-            : type === "success"
-            ? "border-[#6AE89B]"
-            : type === "warning"
+        className={`relative rounded-[32px] p-6 sm:p-8 w-full min-w-[340px] overflow-auto max-w-[var(--modal-width,588px)] backdrop-blur-[32px] bg-t_bg_secondary bg-opacity-75 border border-solid ${
+          type === "warning"
             ? "border-t_warning_dark"
             : type === "waiting"
             ? "border-t_main_accent_dark"

package/src/components/global.css

@@ -43,6 +43,91 @@
     @apply border border-solid border-t_text_primary border-opacity-10;
   }
 
+  /* 1px gradient stroke of the source swap panel (Figma 1762:39085): the
+     design's stroke is white 25%->50% stops under a 10% paint opacity, so the
+     effective colors are 2.5%->5% (hover: 50%->75% stops, i.e. 5%->7.5%).
+     Border-image can't round corners, hence the masked-pseudo-element ring;
+     the two pseudo-elements crossfade because gradients don't interpolate. */
+  .swap-panel-gradient-border {
+    position: relative;
+  }
+
+  .swap-panel-gradient-border::before,
+  .swap-panel-gradient-border::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    padding: 1px;
+    -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+    -webkit-mask-composite: xor;
+    mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+    mask-composite: exclude;
+    pointer-events: none;
+  }
+
+  .swap-panel-gradient-border::before {
+    background: linear-gradient(
+      90deg,
+      color-mix(in srgb, var(--text-primary) 2.5%, transparent),
+      color-mix(in srgb, var(--text-primary) 5%, transparent)
+    );
+  }
+
+  .swap-panel-gradient-border::after {
+    background: linear-gradient(
+      90deg,
+      color-mix(in srgb, var(--text-primary) 5%, transparent),
+      color-mix(in srgb, var(--text-primary) 7.5%, transparent)
+    );
+    opacity: 0;
+    transition: opacity 0.15s ease;
+  }
+
+  .swap-panel-gradient-border:hover::after {
+    opacity: 1;
+  }
+
+  /* Surface of the network filter dropdown (Figma 1770:15593): a 20% black
+     wash over a subtle vertical sheen (white 4% -> 2% -> 4%).
+     The design carries those over a 72px background blur, but Chromium
+     ignores backdrop-filter nested inside the widget's own backdrop-blur,
+     so the translucent stack alone would let the token list read through.
+     Hence the opaque base underneath — it lands on the same near-black the
+     blurred design resolves to. */
+  .network-dropdown-surface {
+    background:
+      linear-gradient(
+        90deg,
+        color-mix(in srgb, var(--bg-primary) 20%, transparent) 0%,
+        color-mix(in srgb, var(--bg-primary) 20%, transparent) 100%
+      ),
+      linear-gradient(
+        180deg,
+        color-mix(in srgb, var(--bg-tertiary) 4%, transparent) 0%,
+        color-mix(in srgb, var(--bg-tertiary) 2%, transparent) 49.5%,
+        color-mix(in srgb, var(--bg-tertiary) 4%, transparent) 100%
+      ),
+      var(--bg-secondary);
+  }
+
+  /* Hover/selected pill of a network row ("Active Fill", Figma 1770:15599):
+     a horizontal sheen peaking in the middle and fading out at both ends.
+     The design's stops are white 0 -> 10% -> 50% -> 10% -> 0 under a 5% layer
+     opacity, so the effective values are the ones below. Gradients don't
+     interpolate, hence no transition. */
+  .network-dropdown-row:hover,
+  .network-dropdown-row-active {
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      color-mix(in srgb, var(--bg-tertiary) 0.5%, transparent) 15%,
+      color-mix(in srgb, var(--bg-tertiary) 2.5%, transparent) 50%,
+      color-mix(in srgb, var(--bg-tertiary) 0.5%, transparent) 85%,
+      transparent 100%
+    );
+  }
+
   /* Corner glow of the transaction result modal, fading towards the center */
   .tx-modal-glow-success {
     background: radial-gradient(

package/src/config/fonts.ts

@@ -52,9 +52,18 @@
 //   font-style: italic;
 // }`;
 
+import SatoshiRegularWOFF2 from "../fonts/Satoshi-Regular.woff2";
+const SatoshiRegular = `@font-face {
+  font-family: "Satoshi";
+  src: url(${SatoshiRegularWOFF2}) format("woff2");
+  font-weight: 400;
+  font-display: swap;
+  font-style: normal;
+}`;
+
 import SatoshiMediumWOFF2 from "../fonts/Satoshi-Medium.woff2";
 const SatoshiMedium = `@font-face {
-  font-family: "Satoshi-Medium";
+  font-family: "Satoshi";
   src: url(${SatoshiMediumWOFF2}) format("woff2");
   font-weight: 500;
   font-display: swap;
@@ -109,6 +118,10 @@ const SatoshiMedium = `@font-face {
 // Fonts are inlined into JS bundle when we import them and they are added into DOM when we add them to this array.
 // Use only fonts that you need.
 // We don't want to increase the bundle size unnecessarily.
-const enabledFonts = [SatoshiMedium];
+//
+// Regular and Medium are registered under one "Satoshi" family so that
+// `font-weight` picks a face. With a single face loaded every weight renders
+// as that face, which is why `font-medium` used to be a no-op.
+const enabledFonts = [SatoshiRegular, SatoshiMedium];
 
 export const fontDefinitions = enabledFonts.join("\n");

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>(
@@ -487,11 +518,10 @@ export const TxUIWrapper = ({ children }: Props) => {
       {isTxModalOpen && (
         <TxModal
           id="tx_modal"
-          className="max-w-x_modal"
           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;
+};