@xswap-link/sdk 0.15.1 → 0.15.2

package/.eslintrc.json

@@ -1,5 +1,6 @@
 {
   "root": true,
+  "ignorePatterns": ["example"],
   "parser": "@typescript-eslint/parser",
   "plugins": ["@typescript-eslint"],
   "extends": [

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @xswap-link/xswap-sdk
 
+## 0.15.2
+
+### Patch Changes
+
+- 8d44122: Report fast delivery for CCTP routes and wait for the funds before calling a cross-chain swap done.
+
+  A route's speed is now read from the API's own `route.expressDelivery` flag where the API states it, instead of always being inferred from a non-zero express-delivery fee. CCTP charges no such fee — Circle's fast-transfer fee is taken out of the bridged USDC — so its routes were labelled "Est. Time 30 Min." and tracked with a 30-minute estimate while actually settling in seconds; they now report the flag outright. The fee test remains the fallback for the CCIP paths, where the fee is what buys express delivery, and the express-delivery fee row now only shows when there is a fee to show.
+
+  Once the source transaction is mined, a cross-chain swap now shows a delivery-progress view — spinner, per-chain steps and elapsed time — and polls `GET /getTransactionStatus` (the call that also claims an unclaimed CCTP transfer) until the transfer settles. The success view appears when the funds have actually landed, reports a delivery that arrived as the bridged token instead of the requested one, and links to the destination transaction. New public API: `getTransactionStatus`, the `useCrossChainDelivery` hook and the `TransactionStatusResponse` / `CrossChainDeliveryStatus` models.
+
 ## 0.15.1
 
 ### Patch Changes

package/README.md

@@ -88,21 +88,39 @@ cd xswap-sdk
 pnpm i
 ```
 
-#### 2. Create new branch based on the `develop` one
+#### 2. Test locally with the example app
+
+```sh
+pnpm build          # or `pnpm watch` to rebuild on every src change
+cd example && pnpm i && pnpm dev
+```
+
+Vite pre-bundles the SDK, so restart `pnpm dev` after every rebuild — a running
+server keeps serving the bundle it started with.
+
+Opens a Vite playground on http://localhost:5173 with `@xswap-link/sdk` linked
+from the repo root (`link:..`). Chains and tokens come from the live `/chains`
+endpoint, so `srcChain` / `srcToken` / `dstChain` / `dstToken` /
+`highlightedDstTokens` are pickers, colors use color inputs and `width` a slider.
+Picking a chain or token remounts the widget automatically (it reads those props
+only on mount), "Remount" does it manually after editing `integratorId` or
+`apiUrl`. Config is kept in localStorage, widget callbacks go to the console.
+
+#### 3. Create new branch based on the `develop` one
 
 ```sh
 git checkout develop
 git checkout -b feature/<your_feature_name>
 ```
 
-#### 3. Create changeset
+#### 4. Create changeset
 
 `pnpm changeset` and follow instructions to describe your changes
 
-#### 4. Commit changes
+#### 5. Commit changes
 
 including changeset: `git commit -m "feat: <your desc>>"`
 
-#### 5. Create PR to `develop` branch
+#### 6. Create PR to `develop` branch
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>

package/dist/index.d.mts

@@ -265,6 +265,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;
 }
 interface EVMRoute extends BaseRoute {
     ecosystem: "evm";
@@ -363,6 +376,39 @@ type ImportedTokenData = {
     decimals: number;
 };
 
+/**
+ * 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.
+ */
+type CrossChainDeliveryStatus = "NOT_FOUND" | "IN_PROGRESS" | "DONE" | "STUCK" | "FAILED" | "PARTIALLY_FAILED";
+type DeliveryTransferInfo = {
+    hash: string;
+    chainId: string;
+    /** Absent on the plain tx references (the middle hop), which carry no transfer. */
+    token?: string;
+    amount?: string;
+};
+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;
+};
+
 type TransferType = "CROSS_CHAIN" | "SINGLE_CHAIN";
 type TransactionHistory = {
     history: HistoryTransaction[];
@@ -524,4 +570,4 @@ declare const XPay: {
     TxWidgetWC: CustomElementConstructor;
 };
 
-export { type Addresses, type BridgeToken, type BridgeTokensDictionary, type Chain, type CoinTypeAddress, type CollectFees, type ContractCall, ContractName, type Contracts, type EVMRoute, Ecosystem, type EnqueueTxProps, Environment, type GenerateStakingCallsParams, type GetLeaderboardChangePayload, type GetPricesPayload, type GetRoutePayload, type GetSolanaRoutePayload, type GetTokenBalancesPayload, type HistoryTransaction, type ImportedTokenData, type ModalIntegrationPayload, type ModalIntegrationStyles, type ModalIntegrationThemeStyles, type MonitoredTransaction, type Prices, type Protocol, type SolanaRoute, SolanaWeb3Network, type Token, type TokenBalances, type TokenOption, type TokenPrices, type Transaction, type TransactionHistory, type TransactionRequest, type TransactionStatus, type Transactions, type TxConfigFormData, type TxStats, TxStatus, type TxUIWrapperState, TxWidgetWCWrapped as TxWidget, TxWidgetWC, type UnifiedRoute, Web3Environment, type WidgetIntegrationPayload, XSwapCallType, type XSwapFee, type XSwapFees, XPay as default, openTransactionModal };
+export { type Addresses, type BridgeToken, type BridgeTokensDictionary, type Chain, type CoinTypeAddress, type CollectFees, type ContractCall, ContractName, type Contracts, type CrossChainDeliveryStatus, type DeliveryTransferInfo, type EVMRoute, Ecosystem, type EnqueueTxProps, Environment, type GenerateStakingCallsParams, type GetLeaderboardChangePayload, type GetPricesPayload, type GetRoutePayload, type GetSolanaRoutePayload, type GetTokenBalancesPayload, type HistoryTransaction, type ImportedTokenData, type ModalIntegrationPayload, type ModalIntegrationStyles, type ModalIntegrationThemeStyles, type MonitoredTransaction, type Prices, type Protocol, type SolanaRoute, SolanaWeb3Network, type Token, type TokenBalances, type TokenOption, type TokenPrices, type Transaction, type TransactionHistory, type TransactionRequest, type TransactionStatus, type TransactionStatusResponse, type Transactions, type TxConfigFormData, type TxStats, TxStatus, type TxUIWrapperState, TxWidgetWCWrapped as TxWidget, TxWidgetWC, type UnifiedRoute, Web3Environment, type WidgetIntegrationPayload, XSwapCallType, type XSwapFee, type XSwapFees, XPay as default, openTransactionModal };

package/dist/index.d.ts

@@ -265,6 +265,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;
 }
 interface EVMRoute extends BaseRoute {
     ecosystem: "evm";
@@ -363,6 +376,39 @@ type ImportedTokenData = {
     decimals: number;
 };
 
+/**
+ * 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.
+ */
+type CrossChainDeliveryStatus = "NOT_FOUND" | "IN_PROGRESS" | "DONE" | "STUCK" | "FAILED" | "PARTIALLY_FAILED";
+type DeliveryTransferInfo = {
+    hash: string;
+    chainId: string;
+    /** Absent on the plain tx references (the middle hop), which carry no transfer. */
+    token?: string;
+    amount?: string;
+};
+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;
+};
+
 type TransferType = "CROSS_CHAIN" | "SINGLE_CHAIN";
 type TransactionHistory = {
     history: HistoryTransaction[];
@@ -524,4 +570,4 @@ declare const XPay: {
     TxWidgetWC: CustomElementConstructor;
 };
 
-export { type Addresses, type BridgeToken, type BridgeTokensDictionary, type Chain, type CoinTypeAddress, type CollectFees, type ContractCall, ContractName, type Contracts, type EVMRoute, Ecosystem, type EnqueueTxProps, Environment, type GenerateStakingCallsParams, type GetLeaderboardChangePayload, type GetPricesPayload, type GetRoutePayload, type GetSolanaRoutePayload, type GetTokenBalancesPayload, type HistoryTransaction, type ImportedTokenData, type ModalIntegrationPayload, type ModalIntegrationStyles, type ModalIntegrationThemeStyles, type MonitoredTransaction, type Prices, type Protocol, type SolanaRoute, SolanaWeb3Network, type Token, type TokenBalances, type TokenOption, type TokenPrices, type Transaction, type TransactionHistory, type TransactionRequest, type TransactionStatus, type Transactions, type TxConfigFormData, type TxStats, TxStatus, type TxUIWrapperState, TxWidgetWCWrapped as TxWidget, TxWidgetWC, type UnifiedRoute, Web3Environment, type WidgetIntegrationPayload, XSwapCallType, type XSwapFee, type XSwapFees, XPay as default, openTransactionModal };
+export { type Addresses, type BridgeToken, type BridgeTokensDictionary, type Chain, type CoinTypeAddress, type CollectFees, type ContractCall, ContractName, type Contracts, type CrossChainDeliveryStatus, type DeliveryTransferInfo, type EVMRoute, Ecosystem, type EnqueueTxProps, Environment, type GenerateStakingCallsParams, type GetLeaderboardChangePayload, type GetPricesPayload, type GetRoutePayload, type GetSolanaRoutePayload, type GetTokenBalancesPayload, type HistoryTransaction, type ImportedTokenData, type ModalIntegrationPayload, type ModalIntegrationStyles, type ModalIntegrationThemeStyles, type MonitoredTransaction, type Prices, type Protocol, type SolanaRoute, SolanaWeb3Network, type Token, type TokenBalances, type TokenOption, type TokenPrices, type Transaction, type TransactionHistory, type TransactionRequest, type TransactionStatus, type TransactionStatusResponse, type Transactions, type TxConfigFormData, type TxStats, TxStatus, type TxUIWrapperState, TxWidgetWCWrapped as TxWidget, TxWidgetWC, type UnifiedRoute, Web3Environment, type WidgetIntegrationPayload, XSwapCallType, type XSwapFee, type XSwapFees, XPay as default, openTransactionModal };