0x拖车

在 React apps中嵌入部件并调用拖车钩的Trails SDK.

安装

npm install 0xtrails @tanstack/react-query viem

如果您想要拖车使用您现有的 wagmi 设置, 请同时安装 @0xtrails/adapter-wagmi 财务报告和审定财务报表 wagmi。 。 。 .

独立部件

仅供部件使用, TrailsWidget 无需 QueryClientProvider 或者说 TrailsProvider。 。 。 .

import { TrailsWidget } from '0xtrails'

const apiKey = 'YOUR_TRAILS_API_KEY'

export function App() {
  return <TrailsWidget apiKey={apiKey} renderInline />
}

当没有父钱包上下文和没有时 adapters,部件使用其内置的 EVM 运行时间.

钩子 TrailsProvider

使用 TrailsProvider 当你想直接拨打拖车钩时.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { TrailsProvider, useAccountTotalBalanceUsd } from '0xtrails'

const apiKey = 'YOUR_TRAILS_API_KEY'
const queryClient = new QueryClient()

function BalancePreview() {
  const address = '0x0000000000000000000000000000000000000000'
  const totalBalance = useAccountTotalBalanceUsd(address)

  return <pre>{JSON.stringify(totalBalance.data, null, 2)}</pre>
}

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TrailsProvider config={{ trailsApiKey: apiKey }}>
        <BalancePreview />
      </TrailsProvider>
    </QueryClientProvider>
  )
}

钩子

虎克是用于定制的UI. 将您的应用程序与您已有的 wagmi 和 React 查询提供者包装, 然后添加 TrailsProvider。 。 。 .

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>
  )
}

部件模式

从 0xtrails/widget。 。 。 .

支付

使用 Pay 当你的应用程序知道 准确的接收者, 目的地标志, 链, 和数量.

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 允许用户在钱包或目的账户中添加资金。 您可以允许不同的支付方法, 使用连接的钱包, qr 代码传输, 交换, 或在斜坡上 fiat .

用户在部件 UI 中选择支付方法

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)}
    />
  )
}

主机应用预选支付款Method为信用卡,以100美元进行融资加密.

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 同链和跨链的代币互换.

import { Swap } from "0xtrails/widget"

export function SwapToBaseUsdc() {
  return (
    <Swap
      apiKey="<YOUR_TRAILS_API_KEY>"
      onSwapSuccess={(data) => console.log("Swap complete", data.sessionId)}
    />
  )
}

赚

使用 Earn 内置的UI跨链体验,以赚取收益.

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 用于加密提取流量。 让用户退出,并将其资产交换给任何链条上的任何令牌.

import { Withdraw } from "0xtrails/widget"

export function WithdrawToBase() {
  return (
    <Withdraw
      apiKey="<YOUR_TRAILS_API_KEY>"
      onWithdrawSuccess={(data) => console.log("Withdrawn", data.sessionId)}
    />
  )
}

自定义标签

每个模式都接受 labels 重命名部件本身副本的对象。 每个 字段是可选的,并倒回内置字符串,这样您就可以覆盖 一个字或四个都行 空白字符串计算为没有覆盖 字段直接输入文字输入,在清除框时做正确的事情。 例如,捐款流动是基金模式,用于: 资金词汇交换:

import { Fund } from "0xtrails/widget"

export function Donate() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{ recipient: "0xReliefFund", chain: "polygon", token: "USDC" }}
      labels={{
        confirmButton: "Donate",
        formTitle: "Donate",
        methodsTitle: "Choose a donation method",
        tokensTitle: "Donate with any token",
      }}
    />
  )
}

formTitle 刻意跟踪用户进入加密传输屏幕( QR代码和存款地址步骤,所以捐款流总是说"捐赠" 而不是在中途切换到“ 保存” 。 刷卡显示屏是 独自一人——他们向第三方交接,通过设计阅读.

tokensTitle 仅覆盖采源者。 取地者("收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收取","收","收","收","收","收","收","收","收"等","收"等, "选择目的地令牌")保留自己的标题,因为令牌使用者 发送和收件人得到的信号是不同的问题.

有两件事情是故意的:

• 即时按钮状态. "输入一个数量","得到引用...","连接" 您的钱包和“ 不足余额” 报告部件正在做什么, 不是 按钮是做什么的,所以他们保留自己的副本.
• 从另一个模式借来的屏幕 . 覆盖仅适用于 配置模式 。 从基金部件头部和按钮打开交换标签 仍然说"扫地"——一个"捐赠"的标签会出现错误.

对于模式触发按钮, buttonText 仍然胜过 labels.confirmButton。 。 。 .

同意复选框

consentCheckbox 将同意线直接放在主按钮上方,并加一个 链接用户可以在他们承诺之前打开。 设置道具是使 勾选为强制性——没有单独的旗帜,因为可选同意 复选框不是别人想要的.

import { Fund } from "0xtrails/widget"

export function DonateWithTerms() {
  return (
    <Fund
      apiKey="<YOUR_TRAILS_API_KEY>"
      to={{ recipient: "0xReliefFund", chain: "polygon", token: "USDC" }}
      labels={{ confirmButton: "Donate" }}
      consentCheckbox={{
        label:
          "I've read and agree to the " +
          '<a href="https://example.org/terms">Terms &amp; Conditions</a>',
        requiredMessage: "Please accept the Terms & Conditions to donate.",
      }}
    />
  )
}

一个空白 label 取出出出门. 设置道具是什么使勾选 强制,所以只使用白空间标签意味着没有复选框使 编辑 确认按钮没有门 ——流动始终在同意步骤下发挥作用 默然去来. 这是刻意的(没有什么可以解释的) 绑定时无法查看模式 label 到 CMS 字段或 i18n 键 可能不会解决。 SDK一旦发生就会记录一个警告.

按钮保持活性. 当盒子解开时,确认按钮会保留 正常的外形,所以一个已准备好的引文 仍然可以读到。 按着它 不提交:行会摇动,会起子,焦点会移动到复选框.

requiredMessage 决定一个失败的媒体留下什么. 设置它和 信件站在复选框下直到选中该框, 所以一个用户错过了 摇动在屏幕上还有原因 放下它,摇摆和锡是 整个反应——轻而易举,它永远不会改变休息布局,但一秒钟 媒体教的是什么 第一个没有。 无论哪种方式, 失败的媒体移动 聚焦到复选框中,因此辅助技术宣布了未锁定的控制.

label 已经消毒. 它是作为 HTML 提供的一种道具,对一固定 允许列表 :

• 保留 : a, (中文(简体) ), b, (中文(简体) ), strong, (中文(简体) ), i, (中文(简体) ), em, (中文(简体) ), span, (中文(简体) ), br。所有其它标记被丢弃 而不是逃脱,所以一个不支持的标记会变成干净的文本.
• 每个属性都被剥去. 一个锚保持它的 href 如果那个赫雷夫 决定: http(s) 或者说 mailto 包括亲属(/terms和 协议关系(//host/path表格,按书面形式公布。 任何东西 其他(无)javascript:, (中文(简体) ), data:) 被打开为纯文本,所以没有惰性 看起来可以点击.
• 幸存锚重写为 target="_blank" rel="noopener noreferrer",因此读取术语从来不会让用户花费填充的引文.

此允许列表保留了标签, 避免断开部件或插入元素 . 没错 没有 您从其它地方插入的 URL 验证符 — 如果 红外线来自 CMS 、 查询字符串或用户输入, 你自己检查 在它来之前.

打开链接从不勾选盒子——两者是故意分开的行为. 如果您希望链接打开自己的页面模式, 请添加授权 点击听众并拨打 preventDefault();部件在阴影内 根,但是它的事件是由组成的,所以 composedPath() 见起锚.

同意是每届会议的,而且从未坚持过. 重新装入又问,即 是什么使滴滴的证据 同意而不是被记住的偏好.

喜欢 labels,复选框属于已配置模式的屏幕。 打开 从基金部件头部取出互换标签, 它没有遵循 .

useQuote

useQuote 给你一个引用和一个可执行文件 send 函数用于完全自定义 UI 。 应提供一笔金额: from.amount 或者说 from.amountRaw 准确输入,或 to.amount 或者说 to.amountRaw 准确的输出。 您可以使用“ 收费选项” 来允许在稳定币中支付气体 .

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>
  )
}

预览引用时, 不需要连接的钱包, 即可通过 walletAddress。 。 。 .

useTrailsSendTransaction

useTrailsSendTransaction 是一个目的地第一交易钩 与有轨电车路线。 镜子 useQuote是因为 from编号 :to 形状和可以打开 Trails 部件模式,当用户需要选择原产地链、令牌或数量,所以不需要构建此步骤.

渲染器 TrailsHookModal 一次进去 TrailsProvider 所以模式驱动的发送 有地方上载.

说明收款人应通过下列方式得到什么: to 并让用户选择如何支付。 设定 to.amount 用于精确输出发送(该模式仅需要源代码选择).

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>
    </>
  )
}

提供 from (单位:千美元){ chain, token, amount }当您的应用程序已经知道要跳过模式的来源资产时 。 使用 from.amountRaw编号 :to.amountRaw 当您已经拥有最小单位金额时.

可编译动作

可编译的行动描述了资金到达目的地后应当发生的情况。 由SDK解决进入目的地的电话,可以从两者中调用 useQuote 财务报告和审定财务报表 useTrailsSendTransaction。 。 。 .

现有的行动构建者包括:

• swap 交换目的地链.
• lend 财务报告和审定财务报表 deposit 支持创收市场.
• custom 让你自己行动起来.
• assertCondition 用于运行时间检查.
• dynamic() 以在未知值时使用意图钱包的运行时余额.

引用和执行动作

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 两者相互排斥 to.calls 和已贬值 to.calldata。 。 。 .

执行使用部件 Modal 的动作

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>
    </>
  )
}

原始目标呼叫

使用 to.calls 当您需要低级别ABI编码的呼叫而不是动作构建器时.

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>
  )
}

公用事业

共同出口 0xtrails数字 :

• getSupportedChains, (中文(简体) ), useSupportedChains,以及 resolveChainId。 。 。 .
• getChainInfo, (中文(简体) ), getAllChains,以及 attemptSwitchChain。 。 。 .
• useTokenList, (中文(简体) ), useSupportedTokens, (中文(简体) ), useTokenBalances, (中文(简体) ), useTokenBalancesForMultipleAccounts, (中文(简体) ), useAccountTotalBalanceUsd, (中文(简体) ), useHasSufficientBalanceToken,以及 useHasSufficientBalanceUsd。 。 。 .
• getTokenPrice, (中文(简体) ), getTokenPrices, (中文(简体) ), useTokenPrice, (中文(简体) ), useTokenPrices
• erc20Utils, (中文(简体) ), buildCall, (中文(简体) ), buildApproveAndCall, (中文(简体) ), buildErc20Approve,以及 getAmountWithSlippage 对于符号元数据,ERC-20调用,批准,以及自定义调用数据.
• uniswapV3 财务报告和审定财务报表 sushiswapV3 用于自定义 Uniswap V3 / SushiSwap V3 池的查询、引用和交换呼叫构建.
• useEarnProviders, (中文(简体) ), useEarnMarkets, (中文(简体) ), useEarnBalances, (中文(简体) ), getEarnProviders, (中文(简体) ), getEarnMarkets,以及 getEarnBalances。 。 。 .
• useResolveActions, (中文(简体) ), encodeDestinationForIntentProtocol, (中文(简体) ), createHydratePayload,以及 encodeMulticallHydrateExecute 用于高级目的地呼叫和水合物流动.
• prepareSend, (中文(简体) ), commitIntent, (中文(简体) ), quoteIntent, (中文(简体) ), sendOriginTransaction, (中文(简体) ), getIntent, (中文(简体) ), useGetIntent, (中文(简体) ), pollIntentReceipt,以及 useIntentReceiptMonitor。 。 。 .
• getAccountTransactionHistory, (中文(简体) ), useAccountTransactionHistory, (中文(简体) ), useIntentTransactionHistory,以及 getTxTimeDiff。 。 。 .
• useFiatCurrencyList, (中文(简体) ), useExchangeRate, (中文(简体) ), getCurrencyInfo
• getTrailsClient, (中文(简体) ), useTrailsClient, (中文(简体) ), TrailsClient
• useIntentRecover, (中文(简体) ), useIntentRecoverWithAddress, (中文(简体) ), buildRefundTransactionWithSignature,以及 signPayload。 。 。 .

TrailsProvider 默认情况下挂载内置钱包运行时间。 添加 config.adapters 当拖车使用明确的钱包运行时间适配器时.

使用带有 wagmi 的拖车

如果您的应用程序已经使用 wagmi, 请添加 @0xtrails/adapter-wagmi 这样拖车就可以分享你的钱包设置. Wagmi 3是首要的集成目标;wagmi 2仍然通过相同的适配器对等范围支持.

更多选项和wagmi 2/3 例见 packages/wallet/adapters/wagmi/README.md, (中文(简体) ), apps/examples/wagmi3,以及 apps/examples/wagmi2。 。 。 .

import { TrailsProvider, TrailsWidget } from '0xtrails'
import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { WagmiProvider } from 'wagmi'

const apiKey = 'YOUR_TRAILS_API_KEY'
// Create wagmiConfig with your chains, transports, and connectors.
const adapters = [wagmiAdapter({ wagmiConfig })]

export function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <TrailsProvider config={{ trailsApiKey: apiKey, adapters }}>
        <TrailsWidget renderInline />
      </TrailsProvider>
    </WagmiProvider>
  )
}

用同样的 wagmiConfig 例如,两者均 WagmiProvider 财务报告和审定财务报表 wagmiAdapter(...) 当有轨电车在主机的 wagmi 运行时间中连接。 如果周围没有匹配 WagmiProvider,适配器用提供的配置来挂载自己的运行时间.

运行时间所有权

适配器运行时间选择和生命周期所有权是分开的:

• wagmi 运行时间选择基于 wagmiConfig 身份
  • 与周围的配置实例相同 WagmiProvider * 连接主机运行时间
  • 没有匹配周围提供者 ~ 挂载适配器自有的运行时间
• managedBy 用于复合适配器列表,控制有轨电车的生命周期所有权
  • managedBy: 'host' 意味着拖车可以使用钱包, 但不应该拥有像断开这样的主机生命周期动作
  • managedBy: 'trails' 指有轨电车拥有适配器的钱包生命周期

const adapters = [
  { adapter: wagmiAdapter({ wagmiConfig: hostWagmiConfig }), managedBy: 'host' },
  { adapter: wagmiAdapter({ wagmiConfig: trailsWagmiConfig }), managedBy: 'trails' },
]

发展

从原始 SVG 文件夹中复制部件 SVG 组件 pnpm --dir packages/0xtrails icons:generate <source-dir>。 。 。 .

规则

• wagmi wagmi 3是首要目标, wagmi 2 仍然支持兼容性
• 钩子需要两个 QueryClientProvider 财务报告和审定财务报表 TrailsProvider
• adapters 还能活下去 TrailsProvider config.adapters 或者说 TrailsWidget adapters
• 不同时在两地提供适配器
• TrailsWidget adapters 无法在现有父钱包上下文中使用, 包括默认运行时间 TrailsProvider

使用带索拉纳的拖车

安装 @0xtrails/svm ——用户从索拉纳钱包和任何EVM链的支付地获得资金.

npm install @0xtrails/svm

过 svmAdapter 与您的 EVM 适配器。 没有 wallet 选项,它自动检测钱包标准索拉纳钱包,如幽灵和索尔夫拉尔:

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
    />
  )
}

在配置索拉纳适配器时,可通过连接-Wallet供资路径获得索拉纳资金。 支持的原产地代币有SOL、USDC、USDT和PYUSD等.

和华克米

组合 wagmiAdapter 财务报告和审定财务报表 svmAdapter 当您的应用程序同时使用 EVM 和 Solana 钱包时 :

import { wagmiAdapter } from '@0xtrails/adapter-wagmi'
import { svmAdapter } from '@0xtrails/svm'

const adapters = [
  wagmiAdapter({ wagmiConfig }),
  svmAdapter({ rpcUrls: ['https://api.mainnet-beta.solana.com'] }),
]

更多选项和实例见 packages/0xtrails-svm/README.md。 。 。 .

许可证

阿帕奇 - 2.0