@shapeshiftoss/swap-widget 0.9.0 → 0.10.0

package/README.md

@@ -12,6 +12,7 @@ An embeddable React widget that enables multi-chain token swaps using ShapeShift
 - [Props Reference](#props-reference)
 - [Filtering Chains and Assets](#filtering-chains-and-assets)
 - [Exact Output and Locked Destinations](#exact-output-and-locked-destinations)
+- [External Wallets and Deposit Addresses](#external-wallets-and-deposit-addresses)
 - [Theming](#theming)
 - [Examples](#examples)
 - [Exported Types](#exported-types)
@@ -122,7 +123,8 @@ Once connected, the widget can sign and broadcast transactions for three wallet
 The header shows a **Connect** button by default (toggle with `showConnectButton`) that opens the
 AppKit modal. Swaps whose sell asset is not in an executable namespace (see
 [Supported Chains](#supported-chains)) redirect to [app.shapeshift.com](https://app.shapeshift.com)
-when `allowShapeshiftRedirect` is enabled.
+when `allowShapeshiftRedirect` is enabled. When such a swap is quoted by an externally paid route,
+both are offered: continue without a wallet, or proceed on ShapeShift.
 
 ## Props Reference
 
@@ -150,7 +152,7 @@ when `allowShapeshiftRedirect` is enabled.
 | `showConnectButton`      | `boolean`                                       | `true`             | Show the built-in Connect button in the widget header.                                                   |
 | `ratesRefetchInterval`   | `number`                                        | `15000`            | How often (ms) to refetch swap rates.                                                                    |
 | `onSwapSuccess`          | `(txHash: string) => void`                      | –                  | Called when a swap transaction succeeds.                                                                  |
-| `onSwapError`            | `(error: Error) => void`                        | –                  | Called when a swap transaction fails.                                                                     |
+| `onSwapError`            | `(error: Error) => void`                        | –                  | Called when a swap fails, or when its outcome can no longer be tracked.                                   |
 
 ## Filtering Chains and Assets
 
@@ -233,14 +235,16 @@ address.
 | `defaultReceiveAddress` only | Prefilled, user can still edit it   |
 | Both                         | Locked to the address you supplied  |
 
-A locked address is checked against the buy asset's chain, and if it doesn't validate there the
-widget says so and blocks the swap rather than falling back to the connected wallet — paying the
-user's own address is never what a locked destination meant. This is reachable whenever the buy
-asset is left unlocked, since the user can switch to a chain the address doesn't belong to.
+The address belongs to the chain of the `defaultBuyAsset` you pair it with. It is usable there, and
+on any other EVM chain if it is an EVM address, since those share an address space; nowhere else,
+even where the format would pass — a Bitcoin address is not a Bitcoin Cash address. A locked address
+the buy chain can't use blocks the swap and says so, rather than falling back to the connected
+wallet — paying the user's own address is never what a locked destination meant. This is reachable
+whenever the buy asset is left unlocked, since the user can switch chains.
 
-An **unlocked** prefill is checked the same way but fails quietly: one that doesn't match the buy
-chain is dropped, and the connected wallet's address takes over as if you had passed nothing. Verify
-a prefill against the chain of the buy asset you pair it with.
+An **unlocked** prefill follows the same rule but fails quietly: switching to a chain that can't use
+it drops it, and the connected wallet's address takes over as if you had passed nothing. Verify a
+prefill against the chain of the buy asset you pair it with.
 
 A lock is only accepted alongside the value it locks — `isReceiveAddressLocked` on its own is a type
 error, as is `isBuyAmountLocked` without `defaultBuyAmountCryptoBaseUnit`. Locking with nothing to
@@ -285,15 +289,14 @@ user's own wallet, or topping up a locked address again, are both things a user
 twice.
 `isBuyAssetLocked` never affects this — restricting swaps to a given token is just a configuration.
 
-### Redirects are disabled by either lock
+### Locking the buy amount or receive address disables redirects
 
 The app.shapeshift.com redirect carries neither the destination nor the buy amount, so following it
 would drop whichever constraint you set. Locking the buy amount **or** the receive address
 therefore disables it outright: `allowShapeshiftRedirect` has no effect, and assets on
 non-executable chains drop out of the asset pickers rather than dead-ending. The pickers share that
 filter, so Cosmos-SDK assets go from the **buy** side too, even though a swap into them works — only
-the sell side needs a signature. The remaining redirect-only chains lose nothing: the widget has no
-address validator for them, so they were never usable as a destination.
+the sell side needs a signature. The remaining redirect-only chains go with them.
 
 Note this is a wider condition than payment mode — locking either one is enough, because a single
 dropped constraint can send funds somewhere you didn't intend.
@@ -341,8 +344,70 @@ only the swap itself resets.
 ### Refunds
 
 If a swap can't be completed, the provider returns the funds to the **sending** address — the wallet
-the user swapped from — not to the receive address. A locked destination does not affect where a
-refund goes.
+the user swapped from, or the address they entered in the [deposit
+flow](#external-wallets-and-deposit-addresses) — not to the receive address. A locked destination
+does not affect where a refund goes.
+
+## External Wallets and Deposit Addresses
+
+Some protocols execute a swap by issuing a **deposit address**: the user sends the sell asset to it
+from any wallet, and the protocol handles the rest. The widget uses this to let people swap with no
+wallet connected at all, and to serve chains it can't sign for.
+
+There is nothing to configure. When the selected route comes from a deposit-address protocol and no
+wallet is connected for the sell chain, the primary button becomes **Continue without a wallet**
+instead of Connect Wallet.
+
+### What the user provides
+
+Two addresses, both entered in the widget and validated against their chains:
+
+- **Receive address** — where the bought asset is sent.
+- **Refund address** — their own address on the sell chain, returned to if the swap can't complete.
+  This is also recorded as the swap's send address; the two are always the same value. There is no
+  prop for it, because it must belong to the user.
+
+### The deposit screen
+
+After quoting, the widget shows the exact amount to send, the deposit address with a QR code, a
+countdown to the quote's expiry, and a summary of the receive and refund addresses. The user pays
+from any external wallet.
+
+The QR carries the bare deposit address by default, which any wallet that scans addresses can read.
+A **With amount** option switches it to a payment URI (BIP-21, EIP-681, Solana Pay, TON) that also
+prefills the amount, with a note that not every wallet reads it. Chains with no adopted URI scheme
+(Tron, Sui, NEAR, Starknet) only ever show the address.
+
+Tracking then proceeds on its own — the widget polls the ShapeShift API, which learns of the deposit
+from the protocol and reports the sell transaction once it lands. From that point the flow is
+identical to a wallet swap. Tracking is bounded: the API abandons a swap still unsettled a day after
+it was registered, and the widget stops with it and says the swap may still be settling, rather than
+spinning indefinitely.
+
+### Expiry and recovery
+
+A deposit window is finite (NEAR Intents quotes run one hour, or four when a UTXO chain is
+involved; Chainflip channels six hours).
+When the countdown reaches zero the screen warns not to send and offers a fresh quote. The same
+happens if the API stops recognising the quote before any deposit was seen. Treat expiry as a hard
+cutoff: what happens to a late deposit is protocol-specific — NEAR Intents refunds it to the refund
+address, while an expired Chainflip channel stops being watched altogether and recovering funds sent
+to it is not guaranteed. If a late deposit is credited anyway, the expired screen still resolves to
+the final result rather than stranding there.
+
+The deposit is persisted to `localStorage` for as long as it is tracked — while funds are owed and
+after they land — and restored if the page reloads, so a reload mid-settlement doesn't lose the
+swap. A reload after the deposit was seen rejoins tracking rather than asking for it again. It is
+dropped when the swap finishes, when tracking gives up, or when the user starts a new swap.
+
+### Limitations
+
+- **Not every route can be paid this way.** Swappers that sign transactions, and a few routes that
+  cannot take a plain transfer (currently TON via NEAR Intents), keep the Connect Wallet or
+  redirect path instead.
+- **Wallet QR scanners vary.** Support for payment URIs is uneven: some wallets read only the
+  address from one, and some fail to parse or misinterpret it. That is why the QR defaults to the
+  bare address. The amount and address are always shown as copyable text alongside it.
 
 ## Theming
 
@@ -624,7 +689,8 @@ React Query client).
 Assets on the following chains appear in the selector. Swaps are **executed in-widget** only for EVM,
 UTXO, and Solana assets (`isWidgetExecutableChainId` returns `true`). Cosmos-SDK and redirect-only
 chains are selectable but route the user to [app.shapeshift.com](https://app.shapeshift.com) to
-complete the swap (when `allowShapeshiftRedirect` is enabled).
+complete the swap (when `allowShapeshiftRedirect` is enabled), unless an
+[externally paid route](#external-wallets-and-deposit-addresses) quotes them, which needs no signer.
 
 | Chain             | Chain ID                                  | Type   | Executable in-widget |
 | ----------------- | ----------------------------------------- | ------ | -------------------- |
@@ -656,11 +722,15 @@ complete the swap (when `allowShapeshiftRedirect` is enabled).
 The widget aggregates quotes across the protocols below and surfaces the best rate. Use
 `allowedSwapperNames` to restrict which are used.
 
-- **NEAR Intents** (`SwapperName.NearIntents`)
+- **NEAR Intents** (`SwapperName.NearIntents`) — deposit address
+- **Chainflip** (`SwapperName.Chainflip`) — deposit address
 - **Relay** (`SwapperName.Relay`)
 - **THORChain** (`SwapperName.Thorchain`)
 - **MAYAChain** (`SwapperName.Mayachain`)
 
+Protocols marked *deposit address* can be paid from any wallet — see [External Wallets and Deposit
+Addresses](#external-wallets-and-deposit-addresses).
+
 > The set of enabled swappers changes over time. Treat this list as current-at-publish; the
 > authoritative source is the `SwapperName` enum exported by this package.
 
@@ -687,10 +757,16 @@ revenue attribution works.
 - **Redirects.** Assets on non-executable chains (Cosmos, Zcash, Tron, Sui, TON, NEAR, Starknet)
   send the user to app.shapeshift.com to finish the swap, unless `allowShapeshiftRedirect={false}`
   or the buy amount or receive address is locked (see
-  [Redirects are disabled by either lock](#redirects-are-disabled-by-either-lock)).
+  [Locking the buy amount or receive address disables redirects](#locking-the-buy-amount-or-receive-address-disables-redirects)).
+  An [externally paid route](#external-wallets-and-deposit-addresses) takes precedence where one is
+  available, since it can be paid without any wallet.
 - **Configuration is applied at mount.** `default*` props are read once; locked values keep
   tracking their prop. Remount to change anything else, or to start a fresh swap. See
   [Configuration is applied at mount](#configuration-is-applied-at-mount).
-- **`onSwapSuccess` reports the sell transaction.** The hash it receives is the transaction the user
-  signed on the sell chain. On cross-chain routes the destination transfer may still be in flight.
+- **`onSwapSuccess` reports the sell transaction.** The hash it receives is the transaction that
+  paid the swap on the sell chain — signed by the user, or their deposit as the protocol reported
+  it. On cross-chain routes the destination transfer may still be in flight.
+- **`onSwapError` does not always mean the swap failed.** It also fires when the widget stops
+  tracking a swap whose outcome it never learned, which can still settle afterwards. Treat it as
+  "not confirmed" rather than "failed" if you act on it.
 - **Mobile responsive.** The widget is designed to work on mobile as well as desktop.

package/dist/index.css

@@ -325,7 +325,10 @@
 .ssw-swap-btn:disabled:active {
   transform: none;
 }
-.ssw-receive-row {
+.ssw-address-group {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
   margin-top: 12px;
   background: var(--ssw-bg-tertiary);
   border: 1px solid var(--ssw-border);
@@ -333,10 +336,14 @@
   padding: 12px 16px;
   transition: box-shadow 0.15s ease;
 }
-.ssw-receive-row:focus-within {
+.ssw-address-group:focus-within {
   border-color: var(--ssw-accent);
   transition: border-color 0.15s ease, box-shadow 0.15s ease;
 }
+.ssw-address-group > * + * {
+  border-top: 1px solid var(--ssw-border);
+  padding-top: 12px;
+}
 .ssw-receive-row-resolved {
   display: flex;
   align-items: center;
@@ -459,10 +466,14 @@
   font-size: 12px;
   color: var(--ssw-error);
 }
-.ssw-receive-row.ssw-attention {
+.ssw-receive-hint {
+  font-size: 12px;
+  color: var(--ssw-text-muted);
+}
+.ssw-address-group.ssw-attention {
   box-shadow: 0 0 16px -2px var(--ssw-accent);
 }
-.ssw-receive-row.ssw-receive-row-invalid {
+.ssw-address-group.ssw-address-group-invalid {
   border-color: var(--ssw-error);
 }
 .ssw-quotes {
@@ -709,19 +720,43 @@
   width: 100%;
   max-width: 320px;
 }
+.ssw-or-divider {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin: -4px 16px 12px;
+  color: var(--ssw-text-muted);
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+.ssw-or-divider::before,
+.ssw-or-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: var(--ssw-border);
+}
 .ssw-step-actions .ssw-action-btn {
   flex: 1;
   width: auto;
   margin: 0;
   white-space: nowrap;
 }
-.ssw-step-actions .ssw-secondary {
+.ssw-step-actions .ssw-secondary,
+.ssw-deposit > .ssw-secondary,
+.ssw-btn-outline .ssw-step-actions .ssw-action-btn.ssw-secondary,
+.ssw-btn-outline .ssw-deposit > .ssw-action-btn.ssw-secondary {
   background: var(--ssw-bg-tertiary);
-  border: 1px solid var(--ssw-border);
-  color: var(--ssw-text-secondary);
+  border: 1px solid var(--ssw-border-hover);
+  color: var(--ssw-text-primary);
 }
-.ssw-step-actions .ssw-secondary:hover {
-  border-color: var(--ssw-border-hover);
+.ssw-step-actions .ssw-action-btn.ssw-secondary:hover:not(:disabled),
+.ssw-deposit > .ssw-action-btn.ssw-secondary:hover:not(:disabled),
+.ssw-btn-outline .ssw-step-actions .ssw-action-btn.ssw-secondary:hover:not(:disabled),
+.ssw-btn-outline .ssw-deposit > .ssw-action-btn.ssw-secondary:hover:not(:disabled) {
+  background: var(--ssw-bg-tertiary);
+  border-color: color-mix(in srgb, var(--ssw-accent) 55%, transparent);
   color: var(--ssw-text-primary);
 }
 .ssw-btn-outline .ssw-action-btn {
@@ -749,6 +784,191 @@
   color: var(--ssw-text-primary);
   background: var(--ssw-bg-hover);
 }
+.ssw-deposit {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 14px;
+  padding: 12px 0 4px;
+}
+.ssw-deposit-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--ssw-text-primary);
+  text-align: center;
+}
+.ssw-deposit-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  width: 100%;
+}
+.ssw-deposit-field-label {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--ssw-text-secondary);
+}
+.ssw-qr {
+  border-radius: var(--ssw-radius-md);
+  padding: 8px;
+  background: #ffffff;
+}
+.ssw-deposit-qr-mode {
+  display: inline-flex;
+  border: 1px solid var(--ssw-border);
+  border-radius: var(--ssw-radius-md);
+  overflow: hidden;
+}
+.ssw-deposit-qr-mode button {
+  padding: 6px 12px;
+  border: none;
+  background: transparent;
+  color: var(--ssw-text-secondary);
+  font-family: var(--ssw-font-family);
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+}
+.ssw-deposit-qr-mode button + button {
+  border-left: 1px solid var(--ssw-border);
+}
+.ssw-deposit-qr-mode button[aria-pressed=true] {
+  background: var(--ssw-accent-light);
+  color: var(--ssw-accent);
+}
+.ssw-deposit-qr-mode button:focus-visible {
+  outline: 2px solid var(--ssw-accent);
+  outline-offset: -2px;
+}
+.ssw-deposit-qr-controls {
+  position: relative;
+  display: flex;
+}
+.ssw-deposit-qr-info {
+  position: absolute;
+  top: 50%;
+  left: calc(100% + 6px);
+  transform: translateY(-50%);
+  display: grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: transparent;
+  color: var(--ssw-text-muted);
+  cursor: help;
+}
+.ssw-deposit-qr-info:hover,
+.ssw-deposit-qr-info:focus-visible {
+  color: var(--ssw-text-primary);
+}
+.ssw-deposit-qr-info:focus-visible {
+  outline: 2px solid var(--ssw-accent);
+  outline-offset: 1px;
+}
+.ssw-deposit-qr-tooltip {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 50%;
+  z-index: 10;
+  display: grid;
+  gap: 6px;
+  width: max-content;
+  max-width: 240px;
+  padding: 8px 10px;
+  border: 1px solid var(--ssw-border);
+  border-radius: var(--ssw-radius-sm);
+  background: var(--ssw-bg-secondary);
+  color: var(--ssw-text-secondary);
+  font-size: 12px;
+  line-height: 1.4;
+  text-align: left;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateX(-50%);
+}
+.ssw-deposit-qr-tooltip strong {
+  color: var(--ssw-text-primary);
+  font-weight: 600;
+}
+.ssw-deposit-qr-info:hover + .ssw-deposit-qr-tooltip,
+.ssw-deposit-qr-info:focus-visible + .ssw-deposit-qr-tooltip,
+.ssw-deposit-qr-tooltip.ssw-open {
+  opacity: 1;
+  visibility: visible;
+}
+.ssw-deposit-qr-controls .ssw-deposit-qr-info + .ssw-deposit-qr-tooltip.ssw-dismissed {
+  opacity: 0;
+  visibility: hidden;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .ssw-deposit-qr-tooltip {
+    transition: opacity 0.12s ease, visibility 0.12s ease;
+  }
+}
+.ssw-deposit-value {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  width: 100%;
+  padding: 12px;
+  border: 1px solid var(--ssw-border);
+  border-radius: var(--ssw-radius-md);
+  background: var(--ssw-bg-input);
+  color: var(--ssw-text-primary);
+  font-family: monospace;
+  font-size: 13px;
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+}
+.ssw-deposit-value:hover {
+  border-color: var(--ssw-border-hover);
+}
+.ssw-deposit-copy {
+  color: var(--ssw-accent);
+  font-family: var(--ssw-font-family);
+  font-size: 12px;
+  font-weight: 600;
+}
+.ssw-deposit-countdown {
+  font-size: 13px;
+  color: var(--ssw-text-muted);
+}
+.ssw-deposit-watching {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 12px;
+  max-width: 280px;
+  font-size: 13px;
+  color: var(--ssw-text-muted);
+  line-height: 1.5;
+  text-align: left;
+}
+.ssw-deposit-summary {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+  margin-top: 2px;
+  padding-top: 14px;
+  border-top: 1px solid var(--ssw-border);
+}
+.ssw-deposit .ssw-action-btn {
+  margin-top: 6px;
+}
+.ssw-deposit-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-size: 13px;
+  color: var(--ssw-text-secondary);
+}
 
 /* src/components/QuoteSelector.css */
 .ssw-quote-selector {

package/dist/index.d.ts

@@ -8,7 +8,8 @@ declare enum SwapperName {
     NearIntents = "NEAR Intents",
     Relay = "Relay",
     Thorchain = "THORChain",
-    Mayachain = "MAYAChain"
+    Mayachain = "MAYAChain",
+    Chainflip = "Chainflip"
 }
 type Chain = {
     chainId: ChainId;
@@ -71,6 +72,7 @@ type TradeRate = {
     shapeshiftBps: string;
     affiliateBps: string;
     networkFeeCryptoBaseUnit?: string;
+    supportsExternalPayment?: boolean;
     error?: {
         code: string;
         message: string;