0xtrails 0.14.0 → 0.15.1

package/README.md

@@ -1,29 +1,475 @@
 # 0xtrails
 
-> Trails SDK for sending any token from any chain.
+Trails SDK for cross-chain orchestration, fund, swap, pay, earn with any token from any chain. Use the embeddable widget for a pre-built UI experience, or compose your own UI with React hooks and utilities.
 
 ## Installation
 
 ```bash
 npm install 0xtrails
+pnpm add 0xtrails
+yarn add 0xtrails
+bun add 0xtrails
 ```
 
-## Usage
+`0xtrails` expects React, React DOM, wagmi, viem, and TanStack Query to be provided by your app.
 
-### React Widget Component
+## Quick Start
 
-The easiest way to integrate Trails is using our pre-built React widget:
+### Widget
 
-```typescript
-import { TrailsWidget } from '0xtrails/widget'
+The widget is the fastest integration path. Pick a mode and pass the props.
+
+```tsx
+import { Pay } from "0xtrails/widget"
+
+export function Checkout() {
+  return (
+    <Pay
+      apiKey="<YOUR_TRAILS_API_KEY>"
+      to={{
+        recipient: "0xRecipientAddress",
+        chain: "base",
+        token: "USDC",
+        amount: "25",
+      }}
+      payMessage="Pay for order #1234"
+      onPaymentSuccess={(data) => console.log("Paid", data.sessionId)}
+    />
+  )
+}
+```
+
+### 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 wagmi-like transaction hook with Trails routing. It 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.
+
+To request a destination token and let the user pick how to pay, provide `tokenAddress` and `tokenAmount`.
+
+```tsx
+import { useTrailsSendTransaction } from "0xtrails"
+
+export function RequestUsdcPayment() {
+  const { sendTransaction, isPending } = useTrailsSendTransaction({
+    receiptActionButtonText: "Back to app",
+  })
 
-export const App = () => {
   return (
-    <TrailsWidget />
+    <>
+      <button
+        disabled={isPending}
+        onClick={() =>
+          sendTransaction({
+            to: "0xMerchantAddress",
+            tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+            tokenAmount: "25"
+          })
+        }
+      >
+        Pay 25 USDC
+      </button>
+    </>
   )
 }
 ```
 
+Use `fromTokenAddress`, `fromChainId`, and `fromAmount` when your app already knows the source asset. Use the `*Raw` fields 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: userAddress,
+            tokenAddress: erc20Utils.USDC.addressOn("polygon"),
+            tokenAmount: "50",
+            tokenDecimals: erc20Utils.USDC.decimalsOn("polygon"),
+          })
+        }
+      >
+        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`.
+
 ## Development
 
 ```bash
@@ -35,8 +481,11 @@ pnpm run build
 
 # Run tests
 pnpm test
+
+# Run the SDK in dev mode
+pnpm dev
 ```
 
 ## License
 
-MIT License
+Apache-2.0

package/dist/_virtual/_@oxc-project_runtime@0.126.0/helpers/defineProperty.js

@@ -0,0 +1,12 @@
+import { toPropertyKey as t } from "./toPropertyKey.js";
+function i(e, r, o) {
+  return (r = t(r)) in e ? Object.defineProperty(e, r, {
+    value: o,
+    enumerable: !0,
+    configurable: !0,
+    writable: !0
+  }) : e[r] = o, e;
+}
+export {
+  i as _defineProperty
+};

package/dist/_virtual/_@oxc-project_runtime@0.126.0/helpers/toPrimitive.js

@@ -0,0 +1,14 @@
+import { _typeof as o } from "./typeof.js";
+function n(r, i) {
+  if (o(r) != "object" || !r) return r;
+  var e = r[Symbol.toPrimitive];
+  if (e !== void 0) {
+    var t = e.call(r, i || "default");
+    if (o(t) != "object") return t;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return (i === "string" ? String : Number)(r);
+}
+export {
+  n as toPrimitive
+};

package/dist/_virtual/_@oxc-project_runtime@0.126.0/helpers/toPropertyKey.js

@@ -0,0 +1,9 @@
+import { _typeof as t } from "./typeof.js";
+import { toPrimitive as i } from "./toPrimitive.js";
+function p(o) {
+  var r = i(o, "string");
+  return t(r) == "symbol" ? r : r + "";
+}
+export {
+  p as toPropertyKey
+};

package/dist/_virtual/_@oxc-project_runtime@0.126.0/helpers/typeof.js

@@ -0,0 +1,11 @@
+function t(e) {
+  "@babel/helpers - typeof";
+  return t = typeof Symbol == "function" && typeof Symbol.iterator == "symbol" ? function(o) {
+    return typeof o;
+  } : function(o) {
+    return o && typeof Symbol == "function" && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+  }, t(e);
+}
+export {
+  t as _typeof
+};

package/dist/abis/requireUtils.d.ts

@@ -0,0 +1,134 @@
+export declare const requireUtilsAbi: readonly [{
+    readonly type: "function";
+    readonly name: "requireNonExpired";
+    readonly inputs: readonly [{
+        readonly name: "expiration";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinBalance";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "minBalance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinBalanceSelf";
+    readonly inputs: readonly [{
+        readonly name: "minBalance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC20Balance";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "minBalance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC20BalanceSelf";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "minBalance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC20Allowance";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "minAllowance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC20AllowanceSelf";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "minAllowance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC20BalanceAllowanceSelf";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "minAmount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireERC721OwnerSelf";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "requireMinERC1155BalanceSelf";
+    readonly inputs: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "minBalance";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "view";
+}];
+//# sourceMappingURL=requireUtils.d.ts.map

package/dist/abis/requireUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireUtils.d.ts","sourceRoot":"","sources":["../../src/abis/requireUtils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGlB,CAAA"}