0xtrails 0.16.2 → 0.17.1

package/README.md

@@ -55,13 +55,449 @@ export function App() {
 }
 ```
 
+### Hooks
+
+Hooks are for custom UI. Wrap your app with your existing wagmi and React Query providers, then add `TrailsProvider`.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { WagmiProvider } from "wagmi"
+import { TrailsProvider } from "0xtrails"
+import { wagmiConfig } from "./wagmi"
+
+const queryClient = new QueryClient()
+
+export function App() {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      <QueryClientProvider client={queryClient}>
+        <TrailsProvider config={{ trailsApiKey: "<YOUR_TRAILS_API_KEY>" }}>
+          <YourRoutes />
+        </TrailsProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  )
+}
+```
+
+## Widget Modes
+
+Import mode-specific wrappers from `0xtrails/widget`. 
+
+### Pay
+
+Use `Pay` when your app knows the exact recipient, destination token, chain, and amount.
+
+```tsx
+import { Pay } from "0xtrails/widget"
+
+export function PayInvoice() {
+  return (
+    <Pay
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      to={{
+        recipient: "0xMerchantAddress",
+        chain: "base",
+        token: "USDC",
+        amount: "49.99",
+      }}
+      from={{ chain: "arbitrum", token: "ETH" }}
+      paymentMethod="CONNECTED_WALLET"
+      payMessage="Invoice #INV-1001"
+      buttonText="Pay now"
+    />
+  )
+}
+```
+
+### Fund
+
+Use `Fund` to let a user add funds to a wallet or destination account. You can allow different payment methods, use a connected wallet, qr code transfers,  exchanges, or fiat on ramp.
+
+The user selects payment method in the widget UI
+
+```tsx
+import { Fund } from "0xtrails/widget"
+
+export function FundWallet() {
+  return (
+    <Fund
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      to={{
+        recipient: "0xUserWallet",
+        chain: "base",
+        token: "USDC",
+      }}
+      onFundingSuccess={(data) => console.log("Funded", data.sessionId)}
+    />
+  )
+}
+```
+
+The host app pre-selects paymentMethod to credit card for funding crypto with 100 USD.
+
+```tsx
+import { Fund } from "0xtrails/widget"
+
+export function FundWallet() {
+  return (
+    <Fund
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      paymentMethod="CREDIT_DEBIT_CARD"
+      from={{
+        currency="USD",
+        amount="100"
+      }}
+      to={{
+        recipient: "0xUserWallet",
+        chain: "base",
+        token: "USDC",
+      }}
+      onFundingSuccess={(data) => console.log("Funded", data.sessionId)}
+    />
+  )
+}
+```
+
+### Swap
+
+Use `Swap` for same-chain and cross-chain token swaps.
+
+```tsx
+import { Swap } from "0xtrails/widget"
+
+export function SwapToBaseUsdc() {
+  return (
+    <Swap
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      onSwapSuccess={(data) => console.log("Swap complete", data.sessionId)}
+    />
+  )
+}
+```
+
+### Earn
+
+Use `Earn` for a built-in UI cross-chain experience for earning yield. 
+
+```tsx
+import { Earn } from "0xtrails/widget"
+
+export function EarnUsdc() {
+  return (
+    <Earn
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      buttonText="Deposit into a protocol"
+      onEarnSuccess={(data) => console.log("Earn deposit", data.sessionId)}
+    />
+  )
+}
+```
+
+### Withdraw
+
+Use `Withdraw` for crypto withdrawal flows. Let users withdraw and swap their assets to any token on any chain.
+
+```tsx
+import { Withdraw } from "0xtrails/widget"
+
+export function WithdrawToBase() {
+  return (
+    <Withdraw
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      onWithdrawSuccess={(data) => console.log("Withdrawn", data.sessionId)}
+    />
+  )
+}
+```
+
+## `useQuote`
+
+`useQuote` gives you a quote and an executable `send` function for a fully custom UI. Exactly one amount should be provided: `from.amount` or `from.amountRaw` for exact-input, or `to.amount` or `to.amountRaw` for exact-output. You can use "feeOptions" to allow paying gas in stablecoins.
+
+```tsx
+import { useQuote, QuoteError } from "0xtrails"
+import { useAccount, useWalletClient } from "wagmi"
+
+export function CustomSwap() {
+  const { address } = useAccount()
+  const { data: walletClient } = useWalletClient()
+
+  const {
+    quote,
+    send,
+    isLoadingQuote,
+    quoteError,
+    quoteErrorPrettified,
+    feeOptions,
+    refetchQuote,
+    abort,
+  } = useQuote({
+    from: {
+      chain: "base",
+      token: "USDC",
+      amount: "10",
+    },
+    to: {
+      chain: "arbitrum",
+      token: "ETH",
+      recipient: address,
+    },
+    onStatusUpdate: (states) => console.log("status", states),
+  })
+
+  if (quoteError instanceof QuoteError) {
+    console.log("Quote failed with code", quoteError.code)
+  }
+
+  return (
+    <section>
+      {isLoadingQuote && <p>Loading quote...</p>}
+      {quoteErrorPrettified && <p>{quoteErrorPrettified}</p>}
+
+      {quote && (
+        <>
+          <p>
+            Spend {quote.originAmountDisplay} for{" "}
+            {quote.destinationAmountDisplay}
+          </p>
+          <p>Estimated time: {quote.completionEstimateDisplay}</p>
+          <p>Fee options: {feeOptions.length}</p>
+        </>
+      )}
+
+      <button disabled={!send} onClick={() => send?.()}>
+        Send
+      </button>
+      <button onClick={() => refetchQuote()}>Refresh</button>
+      <button onClick={() => abort()}>Abort</button>
+    </section>
+  )
+}
+```
+
+For previewing a quote, without needing a connected wallet, pass `walletAddress`.
+
+## `useTrailsSendTransaction`
+
+`useTrailsSendTransaction` is a destination-first transaction hook with Trails routing. It mirrors `useQuote`'s `from`/`to` shape and can open the Trails widget modal when the user needs to choose the origin chain, token, or amount so you don't have to build this step.
+
+Render `TrailsHookModal` once inside `TrailsProvider` so modal-driven sends have somewhere to mount.
+
+Describe what the recipient should receive via `to` and let the user pick how to pay. Set `to.amount` for an exact-output send (the modal only needs origin token selection).
+
+```tsx
+import { useTrailsSendTransaction } from "0xtrails"
+
+export function RequestUsdcPayment() {
+  const { sendTransaction, isPending } = useTrailsSendTransaction({
+    receiptActionButtonText: "Back to app",
+  })
+
+  return (
+    <>
+      <button
+        disabled={isPending}
+        onClick={() =>
+          sendTransaction({
+            to: {
+              chain: "polygon",
+              token: "USDC", // or a contract address
+              recipient: "0xMerchantAddress",
+              amount: "25",
+            },
+          })
+        }
+      >
+        Pay 25 USDC
+      </button>
+    </>
+  )
+}
+```
+
+Provide `from` (`{ chain, token, amount }`) when your app already knows the source asset to skip the modal. Use `from.amountRaw`/`to.amountRaw` when you already have smallest-unit amounts.
+
+## Composable Actions
+
+Composable actions describe what should happen after funds arrive on the destination chain. They are resolved into destination calls by the SDK and can be used from both `useQuote` and `useTrailsSendTransaction`.
+
+Available action builders include:
+
+- `swap` for destination-chain swaps.
+- `lend` and `deposit` for supported earn markets.
+- `custom` for bulding your own action.
+- `assertCondition` for runtime checks.
+- `dynamic()` to spend the intent wallet's runtime balance when value amounts are unknown.
+
+### Quote And Execute Actions
+
+```tsx
+import {
+  assertCondition,
+  dynamic,
+  lend,
+  swap,
+  useQuote,
+} from "0xtrails"
+import { useAccount, useWalletClient } from "wagmi"
+
+export function QuoteActions() {
+  const { address } = useAccount()
+  const { data: walletClient } = useWalletClient()
+
+  const actions = [
+    // Check if we received enough USDC on the destination chain
+    assertCondition({
+      erc20Balance: { token: "USDC", gte: "100" },
+    }),
+    // Swap 100 USDC in WETH (defaults to Uniswap V3)
+    swap({
+      tokenIn: "USDC",
+      tokenOut: "WETH",
+      amountIn: "100",
+      fee: "0.05"
+    }),
+    // Lend all WETH received from the swap 
+    lend({
+      marketId: "base-weth-aave-v3-lending",
+      amount: dynamic(),
+      receiverAddress: address,
+    }),
+  ]
+
+  const { quote, send, isLoadingQuote } = useQuote({
+    from: { chain: "base", token: "USDC" },
+    to: { chain: "base", token: "USDC", amount: "100" },
+    actions,
+  })
+
+  return (
+    <button disabled={!send || isLoadingQuote} onClick={() => send?.()}>
+      {quote ? "Execute recipe" : "Get quote"}
+    </button>
+  )
+}
+```
+
+`actions` is mutually exclusive with `to.calls` and deprecated `to.calldata`.
+
+### Execute Actions With The Widget Modal
+
+```tsx
+import { dynamic, erc20Utils, lend, swap, useTrailsSendTransaction } from "0xtrails"
+
+export function WidgetActionRecipe({ userAddress }: { userAddress: `0x${string}` }) {
+  const actions = [
+    swap({
+      tokenIn: "USDC",
+      tokenOut: "USDT",
+      amountIn: dynamic(),
+      fee: "0.05",
+    }),
+    lend({
+      marketId: "polygon-usdt-fluid-lending",
+      amount: dynamic(),
+      receiverAddress: userAddress,
+    }),
+  ]
+
+  const { sendTransaction, isPending } = useTrailsSendTransaction({
+    actions,
+    receiptActionButtonText: "Done",
+  })
+
+  return (
+    <>
+      <button
+        disabled={isPending}
+        onClick={() =>
+          sendTransaction({
+            to: {
+              chain: "polygon",
+              token: erc20Utils.USDC.addressOn("polygon"),
+              recipient: userAddress,
+              amount: "50"
+            },
+          })
+        }
+      >
+        Choose payment token
+      </button>
+    </>
+  )
+}
+```
+
+### Raw Destination Calls
+
+Use `to.calls` when you need low-level ABI-encoded calls instead of action builders.
+
+```tsx
+import { buildApproveAndCall, buildCall, erc20Utils, useQuote } from "0xtrails"
+import { useAccount } from "wagmi"
+import { stakingAbi } from "./stakingAbi"
+
+export function RawCallsQuote() {
+  const { address } = useAccount()
+
+  const stakingCall = buildCall({
+    to: "0xStakingContract",
+    data: {
+      abi: stakingAbi,
+      functionName: "stake",
+      args: [1_000_000n],
+    },
+  })
+
+  const calls = buildApproveAndCall({
+    token: erc20Utils.USDC.addressOn("base"),
+    call: stakingCall,
+  })
+
+  const { quote, send } = useQuote({
+    from: { chain: "base", token: "USDC" },
+    to: {
+      chain: "base",
+      token: "USDC",
+      amount: "1",
+      calls,
+    },
+  })
+
+  return (
+    <button disabled={!send} onClick={() => send?.()}>
+      {quote ? "Stake USDC" : "Loading quote"}
+    </button>
+  )
+}
+```
+
+## Utilities
+
+Common exports from `0xtrails`:
+
+- `getSupportedChains`, `useSupportedChains`, and `resolveChainId`.
+- `getChainInfo`, `getAllChains`, and `attemptSwitchChain`.
+- `useTokenList`, `useSupportedTokens`, `useTokenBalances`, `useTokenBalancesForMultipleAccounts`, `useAccountTotalBalanceUsd`, `useHasSufficientBalanceToken`, and `useHasSufficientBalanceUsd`.
+- `getTokenPrice`, `getTokenPrices`, `useTokenPrice`, `useTokenPrices`
+- `erc20Utils`, `buildCall`, `buildApproveAndCall`, `buildErc20Approve`, and `getAmountWithSlippage` for token metadata, ERC-20 calls, approvals, and custom calldata.
+- `uniswapV3` and `sushiswapV3` for custom Uniswap V3 / SushiSwap V3 pool lookup, quote, and swap call construction.
+- `useEarnProviders`, `useEarnMarkets`, `useEarnBalances`, `getEarnProviders`, `getEarnMarkets`, and `getEarnBalances`.
+- `useResolveActions`, `encodeDestinationForIntentProtocol`, `createHydratePayload`, and `encodeMulticallHydrateExecute` for advanced destination-call and hydrate flows.
+- `prepareSend`, `commitIntent`, `quoteIntent`, `sendOriginTransaction`, `getIntent`, `useGetIntent`, `pollIntentReceipt`, and `useIntentReceiptMonitor`.
+- `getAccountTransactionHistory`, `useAccountTransactionHistory`, `useIntentTransactionHistory`, and `getTxTimeDiff`.
+- `useFiatCurrencyList`, `useExchangeRate`, `getCurrencyInfo`
+- `getTrailsClient`, `useTrailsClient`, `TrailsClient`
+- `useIntentRecover`, `useIntentRecoverWithAddress`, `buildRefundTransactionWithSignature`, and `signPayload`.
+
 `TrailsProvider` mounts the built-in wallet runtime by default. Add `config.adapters` when Trails should use explicit wallet runtime adapters instead.
 
 ## Use Trails with wagmi
 
-If your app already uses wagmi, add `@0xtrails/adapter-wagmi` so Trails can share your wallet setup.
+If your app already uses wagmi, add `@0xtrails/adapter-wagmi` so Trails can share your wallet setup. Wagmi 3 is the primary integration target; wagmi 2 remains supported through the same adapter peer range.
 
-For more options and examples, see `packages/wallet/adapters/wagmi/README.md`.
+For more options and wagmi 2/3 examples, see `packages/wallet/adapters/wagmi/README.md`, `apps/examples/wagmi3`, and `apps/examples/wagmi2`.
 
 ```tsx
 import { TrailsProvider, TrailsWidget } from '0xtrails'
@@ -109,12 +545,61 @@ Regenerate widget SVG components from a folder of raw SVGs with `pnpm --dir pack
 
 ## Rules
 
-- `wagmi` is optional and only needed for adapter-based integrations
+- `wagmi` is optional and only needed for adapter-based integrations; wagmi 3 is the primary target and wagmi 2 remains supported for compatibility
 - hooks require both `QueryClientProvider` and `TrailsProvider`
 - `adapters` can live on `TrailsProvider config.adapters` or `TrailsWidget adapters`
 - do not provide adapters in both places at the same time
 - `TrailsWidget adapters` cannot be used inside an existing parent wallet context, including the default runtime mounted by `TrailsProvider`
 
+## Use Trails with Solana
+
+Install `@0xtrails/svm` to enable Solana edge payments — users fund from a Solana wallet and the payment lands on any EVM chain.
+
+```bash
+npm install @0xtrails/svm
+```
+
+Pass `svmAdapter` alongside your EVM adapter. With no `wallet` option, it auto-detects Wallet Standard Solana wallets such as Phantom and Solflare:
+
+```tsx
+import { TrailsWidget, evmAdapter } from '0xtrails'
+import { svmAdapter } from '@0xtrails/svm'
+
+const adapters = [
+  evmAdapter({ wallets: [{ id: 'injected', name: 'MetaMask' }] }),
+  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
+]
+
+export function App() {
+  return (
+    <TrailsWidget
+      apiKey="YOUR_TRAILS_API_KEY"
+      adapters={adapters}
+      fundOptions={{ fundMethodsList: ['connected-wallet'] }}
+      renderInline
+    />
+  )
+}
+```
+
+Solana funding is available through the connected-wallet funding path when a Solana adapter is configured. Supported origin tokens are SOL, USDC, USDT, and PYUSD.
+
+### With wagmi
+
+Combine `wagmiAdapter` and `svmAdapter` when your app uses both EVM and Solana wallets:
+
+```tsx
+import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
+import { svmAdapter } from '@0xtrails/svm'
+
+const adapters = [
+  wagmiAdapter({ wagmiConfig }),
+  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
+]
+```
+
+For more options and examples, see `packages/0xtrails-svm/README.md`.
+
 ## License
 
 Apache-2.0

package/dist/BluvoExchangeSelection.lazy-D6ynQVSb.js

@@ -0,0 +1 @@
+import{Bt as e,Tt as t,ar as n,j as r}from"./src-Cy3oxYgV.js";import{useState as i}from"react";import{useQuery as a}from"@tanstack/react-query";import{jsx as o,jsxs as s}from"react/jsx-runtime";import{ChevronRight as c}from"lucide-react";const l=({environment:l,onBack:u,onSelectExchange:d})=>{let{apiKey:f,trailsApiUrl:p}=n(),m=t(),[h,g]=i(!1),[_,v]=i(new Set),{data:y,isLoading:b,error:x}=a({queryKey:[`bluvo-exchanges`,p,f,l],queryFn:async()=>{let e=await m.getBluvoClientConfig({environment:l});return e.enabled?{config:e,exchanges:(await m.getBluvoExchanges({environment:l})).exchanges||[]}:{config:e,exchanges:[]}},enabled:!!f&&!!p,staleTime:300*1e3}),S=y?.exchanges||[],C=h?S:S.slice(0,3);return s(`div`,{className:`flex flex-col h-full`,children:[o(e,{onBack:u,headerContent:`Select Exchange`,headerContentAlign:`left`}),o(`div`,{className:`flex-1`,children:b?o(`div`,{className:`flex h-full items-center justify-center`,children:s(`div`,{className:`w-full rounded-xl border border-solid border-gray-200 bg-gray-50 p-6 text-center dark:border-gray-700 dark:bg-gray-900/40`,children:[o(r,{className:`mx-auto mb-4 h-8 w-8`}),o(`p`,{className:`text-sm font-medium text-gray-900 dark:text-white`,children:`Loading exchanges...`}),o(`p`,{className:`mt-2 text-sm text-gray-500 dark:text-gray-400`,children:`Fetching the exchange accounts available for this app.`})]})}):x?o(`div`,{className:`flex h-full items-center justify-center`,children:s(`div`,{className:`w-full rounded-xl border border-solid border-red-200 bg-red-50 p-4 text-left dark:border-red-800 dark:bg-red-900/20`,children:[o(`p`,{className:`text-sm font-medium text-red-800 dark:text-red-200`,children:`Failed to load exchanges`}),o(`p`,{className:`mt-2 text-sm text-red-700 dark:text-red-300`,children:x instanceof Error?x.message:`Failed to load Bluvo exchanges`})]})}):y&&!y.config.enabled?o(`div`,{className:`flex h-full items-center justify-center`,children:s(`div`,{className:`w-full rounded-xl border border-solid border-yellow-200 bg-yellow-50 p-4 text-left dark:border-yellow-800 dark:bg-yellow-900/20`,children:[o(`p`,{className:`text-sm font-medium text-yellow-900 dark:text-yellow-100`,children:`Exchange funding unavailable`}),o(`p`,{className:`mt-2 text-sm text-yellow-700 dark:text-yellow-300`,children:`Bluvo exchange funding is currently disabled.`})]})}):S.length===0?o(`div`,{className:`flex h-full items-center justify-center`,children:s(`div`,{className:`w-full rounded-xl border border-solid border-gray-200 bg-gray-50 p-4 text-left dark:border-gray-700 dark:bg-gray-800/70`,children:[o(`p`,{className:`text-sm font-medium text-gray-900 dark:text-white`,children:`No exchanges available`}),o(`p`,{className:`mt-2 text-sm text-gray-600 dark:text-gray-300`,children:`No Bluvo exchanges are currently available for this app.`})]})}):o(`div`,{className:`max-h-[420px] overflow-y-auto pr-1 pt-2`,children:s(`div`,{className:`space-y-2`,children:[C.map(e=>s(`button`,{type:`button`,onClick:()=>d({id:e.id,name:e.name,logoUrl:e.logoUrl}),className:`w-full flex items-center justify-between cursor-pointer rounded-xl border border-solid border-gray-200 bg-white px-3 py-3 text-gray-900 transition-colors duration-200 hover:border-blue-200 hover:bg-blue-50 dark:border-gray-800 dark:bg-gray-900/40 dark:text-white dark:hover:border-blue-900/60 dark:hover:bg-blue-950/30`,children:[s(`div`,{className:`flex items-center gap-3`,children:[o(`div`,{className:`h-10 w-10 shrink-0 rounded-full bg-blue-50 text-blue-700 dark:bg-blue-900/30 dark:text-blue-200 flex items-center justify-center text-sm font-semibold overflow-hidden`,children:e.logoUrl&&!_.has(e.id)?o(`img`,{src:e.logoUrl,alt:e.name,className:`h-10 w-10 object-contain`,onError:()=>{v(t=>{let n=new Set(t);return n.add(e.id),n})}}):e.name.slice(0,1)}),s(`div`,{className:`min-w-0 text-left`,children:[o(`h4`,{className:`truncate text-base font-medium leading-6`,children:e.name}),o(`p`,{className:`mt-0.5 text-xs text-gray-500 dark:text-gray-400`,children:`Connect your account to transfer funds`})]})]}),o(c,{className:`h-5 w-5 shrink-0 text-gray-500 dark:text-gray-300`})]},e.id)),!h&&S.length>3&&o(`button`,{type:`button`,onClick:()=>g(!0),className:`mt-4 w-full cursor-pointer rounded-full border border-solid border-gray-200 bg-white px-6 py-3 text-sm font-medium text-gray-900 transition-colors hover:border-blue-200 hover:bg-blue-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100 dark:hover:border-blue-900/60 dark:hover:bg-blue-950/30`,children:`Show more`})]})})}),l===`sandbox`&&o(`div`,{className:`mt-4 border border-solid border-yellow-200 bg-yellow-50 p-3 dark:border-yellow-800 dark:bg-yellow-900/20`,children:s(`div`,{className:`text-center`,children:[o(`p`,{className:`text-sm font-medium text-yellow-800 dark:text-yellow-200`,children:`Sandbox environment`}),o(`p`,{className:`text-xs text-yellow-600 dark:text-yellow-300`,children:`No real funds are used`})]})})]})};export{l as default};