@zerodev/smart-routing-address-react-ui 0.0.1

package/src/constants.ts

@@ -0,0 +1,102 @@
+import type { TOKEN_TYPE } from '@zerodev/smart-routing-address'
+import { SUPPORTED_TOKENS } from '@zerodev/smart-routing-address'
+import type { Chain } from 'viem'
+import {
+  arbitrum,
+  base,
+  blast,
+  bsc,
+  celo,
+  flowMainnet,
+  hyperEvm,
+  ink,
+  linea,
+  mainnet,
+  megaeth,
+  mode,
+  monad,
+  optimism,
+  plasma,
+  polygon,
+  scroll,
+  soneium,
+  tempo,
+  unichain,
+  worldchain,
+  zora,
+} from 'viem/chains'
+import type { SourceToken } from './types'
+
+export const DEFAULT_POLLING_INTERVAL_MS = 5_000
+
+export const DEFAULT_FILL_TIME_SECONDS = 30
+
+export const DEFAULT_DASHBOARD_URL = 'https://smart-routing-address.zerodev.app'
+
+/**
+ * Chains supported by the smart routing address SDK; mirrors the
+ * smart-account-plus core `supportedChainIds` list.
+ */
+export const SUPPORTED_CHAINS: readonly Chain[] = [
+  mainnet,
+  optimism,
+  arbitrum,
+  polygon,
+  plasma,
+  base,
+  celo,
+  mode,
+  monad,
+  blast,
+  bsc,
+  flowMainnet,
+  hyperEvm,
+  linea,
+  ink,
+  megaeth,
+  scroll,
+  soneium,
+  tempo,
+  unichain,
+  worldchain,
+  zora,
+]
+
+export const CHAINS_BY_ID: ReadonlyMap<number, Chain> = new Map(
+  SUPPORTED_CHAINS.map((chain) => [chain.id, chain]),
+)
+
+/**
+ * Token types the SDK ships in `SUPPORTED_TOKENS` but the SRA server does not
+ * yet recognize. Sending one of these as a source token makes the server
+ * reject the whole `createSmartRoutingAddress` request with
+ * `Invalid params: Token address … is not supported on chain N`, which breaks
+ * the entire destination (e.g. Base). Remove entries here as the server
+ * registry catches up.
+ *
+ * TODO: file/track ZeroDev SRA server bug for EURC on Base
+ * (chain 8453, address 0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42) — once the
+ * server accepts it, drop this filter.
+ */
+const UNSUPPORTED_TOKEN_TYPES: ReadonlySet<TOKEN_TYPE> = new Set(['EURC'])
+
+/**
+ * Source tokens offered for deposits: every supported mainnet token the SDK
+ * exposes (NATIVE plus each ERC-20, with wrapped native surfaced as WETH),
+ * mapped to its viem chain object. Testnets are excluded from the default;
+ * chains this package cannot resolve to a viem chain are skipped, and token
+ * types the server can't route yet are filtered via `UNSUPPORTED_TOKEN_TYPES`.
+ */
+export const DEFAULT_SOURCE_TOKENS: SourceToken[] = Object.entries(
+  SUPPORTED_TOKENS,
+).flatMap(([chainId, tokens]) => {
+  // Skip chains this package cannot resolve to a viem chain object
+  const chain = CHAINS_BY_ID.get(Number(chainId))
+  if (!chain) return []
+  return Object.keys(tokens)
+    .filter((t) => !UNSUPPORTED_TOKEN_TYPES.has(t as TOKEN_TYPE))
+    .map((tokenType) => ({
+      chain,
+      tokenType: tokenType as TOKEN_TYPE,
+    }))
+})

package/src/context/SmartRoutingAddressContext.ts

@@ -0,0 +1,48 @@
+import { createContext, useContext } from 'react'
+import type { Address } from 'viem'
+import type {
+  ActiveRoute,
+  AddressState,
+  SmartRoutingAddressConfig,
+} from '../types'
+
+export type SmartRoutingAddressContextValue = {
+  config: SmartRoutingAddressConfig
+  addressState: AddressState
+  /** Recipient of the active (or last requested) smart routing address */
+  recipient?: Address | undefined
+  /**
+   * Return the smart routing address for the recipient, creating it if it
+   * has not been created yet. Safe to call multiple times; concurrent calls
+   * for the same recipient share one request, while a new recipient
+   * triggers a fresh creation. Rejects when creation fails (the failure
+   * also lands in `addressState`).
+   */
+  getOrCreateAddress: (recipient: Address) => Promise<Address>
+  /**
+   * Re-run address creation for the current recipient. No-op if no recipient
+   * has been set yet. Wired to the "Failed to create deposit address" retry
+   * button in the deposit UI.
+   */
+  retry: () => Promise<void>
+  /**
+   * The route currently shown in the deposit UI. `null` until the picker
+   * seeds a selection. Hosts can read this to mirror the widget's state.
+   */
+  activeRoute: ActiveRoute | null
+  /** Deposit UI internal — writes the current picker selection to context. */
+  setActiveRoute: (route: ActiveRoute | null) => void
+}
+
+export const SmartRoutingAddressContext =
+  createContext<SmartRoutingAddressContextValue | null>(null)
+
+export function useSmartRoutingAddressContext(): SmartRoutingAddressContextValue {
+  const context = useContext(SmartRoutingAddressContext)
+  if (!context) {
+    throw new Error(
+      'Smart routing address components must be rendered inside <SmartRoutingAddressProvider>',
+    )
+  }
+  return context
+}

package/src/context/SmartRoutingAddressProvider.tsx

@@ -0,0 +1,145 @@
+import { createSmartRoutingAddress } from '@zerodev/smart-routing-address'
+import { type ReactNode, useCallback, useMemo, useRef, useState } from 'react'
+import type { Address } from 'viem'
+import type {
+  ActiveRoute,
+  AddressState,
+  SmartRoutingAddressConfig,
+} from '../types'
+import {
+  resolveActions,
+  resolveBaseUrl,
+  resolveDestChain,
+  resolveSourceTokens,
+  resolveVersion,
+} from '../utils/config'
+import { SmartRoutingAddressContext } from './SmartRoutingAddressContext'
+
+export type SmartRoutingAddressProviderProps = {
+  config: SmartRoutingAddressConfig
+  children: ReactNode
+}
+
+/**
+ * Holds the config and the lazily created routing address. Wrap the subtree
+ * that renders <SmartRoutingAddress /> with this provider — the deposit UI
+ * itself is rendered inline by the consumer, not by this provider.
+ */
+export function SmartRoutingAddressProvider({
+  config,
+  children,
+}: SmartRoutingAddressProviderProps) {
+  const [addressState, setAddressState] = useState<AddressState>({
+    status: 'idle',
+  })
+  const [recipient, setRecipient] = useState<Address | undefined>(undefined)
+  const [activeRoute, setActiveRoute] = useState<ActiveRoute | null>(null)
+  const pendingRef = useRef<Promise<Address> | null>(null)
+  const recipientRef = useRef<Address | null>(null)
+  // Each creation request gets a generation; only the latest generation
+  // may write state, so superseded requests are ignored entirely
+  const genRef = useRef(0)
+  const configRef = useRef(config)
+
+  const getOrCreateAddress = useCallback(
+    async (nextRecipient: Address): Promise<Address> => {
+      // A new config invalidates any cached request
+      if (configRef.current !== config) {
+        configRef.current = config
+        genRef.current += 1
+        pendingRef.current = null
+        recipientRef.current = null
+      }
+
+      // Reuse the pending/settled request for the same recipient
+      if (pendingRef.current && recipientRef.current === nextRecipient) {
+        return pendingRef.current
+      }
+
+      genRef.current += 1
+      const gen = genRef.current
+      recipientRef.current = nextRecipient
+      setRecipient(nextRecipient)
+
+      const request = (async () => {
+        setAddressState({ status: 'loading' })
+        try {
+          const baseUrl = resolveBaseUrl(config)
+          const result = await createSmartRoutingAddress({
+            owner: nextRecipient,
+            destChain: resolveDestChain(config),
+            ...(config.slippage !== undefined && {
+              slippage: config.slippage,
+            }),
+            srcTokens: resolveSourceTokens(config),
+            ...(resolveActions(config, nextRecipient) && {
+              actions: resolveActions(config, nextRecipient),
+            }),
+            // Drop source tokens without an available route instead
+            // of failing the whole address creation
+            allowPartialRoutes: true,
+            config: {
+              ...(baseUrl && { baseUrl }),
+              version: resolveVersion(config),
+            },
+          })
+          // State writes are generation-gated (results superseded by a newer
+          // request must not clobber the live one), but the promise still
+          // resolves with the address this call created — per-call semantics
+          // stay honest even after the provider has moved on.
+          if (genRef.current === gen) {
+            setAddressState({
+              status: 'success',
+              address: result.smartRoutingAddress,
+              estimatedFees: result.estimatedFees,
+            })
+          }
+          return result.smartRoutingAddress
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error))
+          // Superseded failures must not clear the live request
+          if (genRef.current === gen) {
+            // Allow a retry after failures
+            pendingRef.current = null
+            setAddressState({ status: 'error', error: err })
+          }
+          throw err
+        }
+      })()
+
+      pendingRef.current = request
+      return request
+    },
+    [config],
+  )
+
+  const retry = useCallback(async () => {
+    const current = recipientRef.current
+    if (!current) return
+    // Force a fresh request even if we still have a settled one cached
+    pendingRef.current = null
+    recipientRef.current = null
+    // Failures surface via `addressState`; swallow the rejection so retry
+    // callers (e.g. the ErrorRetryCard click handler) don't need a catch.
+    await getOrCreateAddress(current).catch(() => {})
+  }, [getOrCreateAddress])
+
+  const value = useMemo(
+    () => ({
+      config,
+      addressState,
+      recipient,
+      getOrCreateAddress,
+      retry,
+      activeRoute,
+      setActiveRoute,
+    }),
+    [config, addressState, recipient, getOrCreateAddress, retry, activeRoute],
+  )
+
+  return (
+    <SmartRoutingAddressContext.Provider value={value}>
+      {children}
+    </SmartRoutingAddressContext.Provider>
+  )
+}

package/src/hooks/useCreateSmartRoutingAddress.ts

@@ -0,0 +1,28 @@
+import type { Address } from 'viem'
+import { useSmartRoutingAddressContext } from '../context/SmartRoutingAddressContext'
+
+export type UseCreateSmartRoutingAddressResult = {
+  /**
+   * Return the deposit address for the recipient, creating it if it doesn't
+   * exist yet. Idempotent per recipient — concurrent and repeated calls
+   * share one request, so it's safe to call on every hover/focus/mount.
+   * Rejects when creation fails (the failure also lands in the read hook's
+   * `addressState`). Creation params (`actions`, `slippage`, …) come from
+   * the provider config so the address always matches what the widget
+   * displays — there are no per-call overrides. To create addresses with
+   * bespoke params, use `createSmartRoutingAddress` from
+   * `@zerodev/smart-routing-address`.
+   */
+  getOrCreateAddress: (recipient: Address) => Promise<Address>
+}
+
+/**
+ * Action counterpart to `useSmartRoutingAddress` (which is read-only): lets
+ * hosts embedding the `<SmartRoutingAddress />` widget pre-create the
+ * deposit address — e.g. on hover or route entry, before the modal opens —
+ * so the widget renders instantly.
+ */
+export function useCreateSmartRoutingAddress(): UseCreateSmartRoutingAddressResult {
+  const { getOrCreateAddress } = useSmartRoutingAddressContext()
+  return { getOrCreateAddress }
+}

package/src/hooks/useDepositStatus.ts

@@ -0,0 +1,110 @@
+import type { DepositedToken } from '@zerodev/smart-routing-address'
+import { getSmartRoutingAddressStatus } from '@zerodev/smart-routing-address'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { Address } from 'viem'
+import { DEFAULT_POLLING_INTERVAL_MS } from '../constants'
+
+export type UseDepositStatusParams = {
+  address: Address | undefined
+  enabled?: boolean | undefined
+  pollingInterval?: number | undefined
+  baseUrl?: string | undefined
+}
+
+export type UseDepositStatusResult = {
+  deposits: DepositedToken[]
+  totalCount: number
+  /** True once at least one status response has been received */
+  hasLoaded: boolean
+  isLoading: boolean
+  error: Error | null
+  /** Trigger an immediate poll — used by the "Retry" button after a fetch
+   * error. No-op while no address is set. */
+  refetch: () => void
+}
+
+const INITIAL_STATE = {
+  deposits: [] as DepositedToken[],
+  totalCount: 0,
+  hasLoaded: false,
+  isLoading: false,
+  error: null as Error | null,
+}
+
+/**
+ * Polls the smart routing address status endpoint while enabled, returning
+ * the current list of deposits.
+ */
+export function useDepositStatus({
+  address,
+  enabled = true,
+  pollingInterval = DEFAULT_POLLING_INTERVAL_MS,
+  baseUrl,
+}: UseDepositStatusParams): UseDepositStatusResult {
+  const [state, setState] = useState(INITIAL_STATE)
+  // Exposed via `refetch`; reassigned every time the effect runs so we always
+  // point at the poller bound to the current (address, baseUrl) pair.
+  const pollRef = useRef<(() => void) | null>(null)
+
+  useEffect(() => {
+    if (!address || !enabled) {
+      pollRef.current = null
+      return
+    }
+
+    let cancelled = false
+    // Each `poll()` call bumps `gen`; only the latest generation may write
+    // to state. Prevents a stale interval-driven response from clobbering a
+    // fresh `refetch()` (or vice-versa) when the two overlap in flight.
+    let gen = 0
+
+    const poll = async () => {
+      gen += 1
+      const requestGen = gen
+      try {
+        const result = await getSmartRoutingAddressStatus({
+          smartRoutingAddress: address,
+          ...(baseUrl && { config: { baseUrl } }),
+        })
+        if (cancelled || requestGen !== gen) return
+        setState({
+          deposits: result.deposits,
+          totalCount: result.totalCount,
+          hasLoaded: true,
+          isLoading: false,
+          error: null,
+        })
+      } catch (error) {
+        if (cancelled || requestGen !== gen) return
+        setState((previous) => ({
+          ...previous,
+          isLoading: false,
+          error: error instanceof Error ? error : new Error(String(error)),
+        }))
+      }
+    }
+
+    pollRef.current = () => {
+      setState((previous) => ({ ...previous, isLoading: true, error: null }))
+      poll().catch(() => {})
+    }
+
+    setState((previous) => ({ ...previous, isLoading: true }))
+    poll().catch(() => {})
+    const intervalId = setInterval(() => {
+      poll().catch(() => {})
+    }, pollingInterval)
+
+    return () => {
+      cancelled = true
+      clearInterval(intervalId)
+      pollRef.current = null
+    }
+  }, [address, enabled, pollingInterval, baseUrl])
+
+  const refetch = useCallback(() => {
+    pollRef.current?.()
+  }, [])
+
+  return { ...state, refetch }
+}

package/src/hooks/useNewDeposits.ts

@@ -0,0 +1,25 @@
+import type { DepositedToken } from '@zerodev/smart-routing-address'
+import { useMemo, useRef } from 'react'
+import { getDepositKey, getNewDeposits } from '../utils/deposits'
+
+/**
+ * Tracks deposits that arrived after the first loaded status snapshot.
+ * The snapshot taken when `ready` first becomes true acts as the baseline,
+ * so pre-existing deposits are not reported as new.
+ */
+export function useNewDeposits(
+  deposits: DepositedToken[],
+  ready: boolean,
+): DepositedToken[] {
+  const baselineRef = useRef<ReadonlySet<string> | null>(null)
+
+  if (ready && baselineRef.current === null) {
+    baselineRef.current = new Set(deposits.map(getDepositKey))
+  }
+
+  const baseline = baselineRef.current
+  return useMemo(() => {
+    if (!baseline) return []
+    return getNewDeposits(deposits, baseline)
+  }, [deposits, baseline])
+}

package/src/hooks/useProviderFees.ts

@@ -0,0 +1,235 @@
+import type { TOKEN_TYPE } from '@zerodev/smart-routing-address'
+import { useEffect, useState } from 'react'
+import type { Address, Chain } from 'viem'
+import { zeroAddress } from 'viem'
+import type { EstimatedFeeData, SourceToken } from '../types'
+import { resolveTokenAddress } from '../utils/fees'
+import {
+  AcrossSuggestedFeesSchema,
+  type FeeBreakdown,
+  parseAcrossFees,
+  parseRelayFees,
+  RelayQuoteSchema,
+} from '../utils/providerFees'
+
+const ACROSS_API = 'https://app.across.to/api/suggested-fees'
+const RELAY_API = 'https://api.relay.link/quote'
+// Quotes barely depend on the caller; used only when no recipient is known
+const QUOTE_USER: Address = '0x1111111111111111111111111111111111111111'
+
+type Route = {
+  tokenType: TOKEN_TYPE
+  originChainId: number
+  destinationChainId: number
+  amount: string
+  user: Address
+  symbol: string
+  decimals: number
+}
+
+/** Across is keyed by ERC-20 addresses; native is quoted via its wrapped form */
+function acrossToken(tokenType: TOKEN_TYPE, chainId: number): Address | null {
+  if (tokenType === 'NATIVE') return resolveTokenAddress('WETH', chainId)
+  return resolveTokenAddress(tokenType, chainId)
+}
+
+/** Relay represents native as the zero address; ERC-20s by their address */
+function relayToken(tokenType: TOKEN_TYPE, chainId: number): Address | null {
+  if (tokenType === 'NATIVE') return zeroAddress
+  return resolveTokenAddress(tokenType, chainId)
+}
+
+async function fetchAcross(
+  route: Route,
+  signal: AbortSignal,
+): Promise<FeeBreakdown | null> {
+  const inputToken = acrossToken(route.tokenType, route.originChainId)
+  const outputToken = acrossToken(route.tokenType, route.destinationChainId)
+  if (!inputToken || !outputToken) return null
+  const params = new URLSearchParams({
+    inputToken,
+    outputToken,
+    originChainId: String(route.originChainId),
+    destinationChainId: String(route.destinationChainId),
+    amount: route.amount,
+  })
+  const res = await fetch(`${ACROSS_API}?${params}`, { signal })
+  if (!res.ok) return null
+  const json = await res.json()
+  if (!json || json.error) return null
+  // Validate the response shape before handing it to the parser — if Across
+  // changes their API in a way we don't recognise, we degrade gracefully to
+  // the collapsed fee view instead of computing garbage from missing fields.
+  const parsed = AcrossSuggestedFeesSchema.safeParse(json)
+  if (!parsed.success) {
+    // biome-ignore lint/suspicious/noConsole: schema-drift signal for developers; silent failure is what we're trying to avoid.
+    console.warn(
+      '[useProviderFees] Across response failed schema validation',
+      parsed.error.issues,
+    )
+    return null
+  }
+  return parseAcrossFees(parsed.data, route.symbol, route.decimals)
+}
+
+async function fetchRelay(
+  route: Route,
+  signal: AbortSignal,
+): Promise<FeeBreakdown | null> {
+  const originCurrency = relayToken(route.tokenType, route.originChainId)
+  const destinationCurrency = relayToken(
+    route.tokenType,
+    route.destinationChainId,
+  )
+  if (!originCurrency || !destinationCurrency) return null
+  const res = await fetch(RELAY_API, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal,
+    body: JSON.stringify({
+      user: route.user,
+      recipient: route.user,
+      originChainId: route.originChainId,
+      destinationChainId: route.destinationChainId,
+      originCurrency,
+      destinationCurrency,
+      amount: route.amount,
+      tradeType: 'EXACT_INPUT',
+    }),
+  })
+  if (!res.ok) return null
+  const json = await res.json()
+  if (!json || json.error) return null
+  // See fetchAcross above — schema validation is the last line of defence
+  // between a silently changed API and wrong fees rendered to the user.
+  const parsed = RelayQuoteSchema.safeParse(json)
+  if (!parsed.success) {
+    // biome-ignore lint/suspicious/noConsole: schema-drift signal for developers; silent failure is what we're trying to avoid.
+    console.warn(
+      '[useProviderFees] Relay response failed schema validation',
+      parsed.error.issues,
+    )
+    return null
+  }
+  return parseRelayFees(parsed.data)
+}
+
+/** Pick the cheaper live route by full quoted cost; else the first available */
+function bestRoute(routes: (FeeBreakdown | null)[]): FeeBreakdown | null {
+  const available = routes.filter((r): r is FeeBreakdown => r !== null)
+  if (available.length === 0) return null
+  const withUsd = available.filter((r) => r.quotedTotalUsd !== null)
+  if (withUsd.length === 0) return available[0] ?? null
+  return withUsd.reduce((best, r) =>
+    (r.quotedTotalUsd as number) < (best.quotedTotalUsd as number) ? r : best,
+  )
+}
+
+export type ProviderFeesState = {
+  /** Cheapest normalised quote, or null while loading / unquotable */
+  fees: FeeBreakdown | null
+  /** True from the moment the route changes until the quotes resolve */
+  loading: boolean
+}
+
+/**
+ * Fetch live fee quotes for the selected route from every supported provider
+ * (Across + Relay), normalise them, and return the cheapest. Across and Relay
+ * expose the itemised bridge legs the SRA fee estimate alone does not, so this
+ * enriches the breakdown with how the user is actually charged and which route
+ * is currently best.
+ *
+ * Returns null while loading, for routes that can't be quoted (native /
+ * unresolvable tokens), or when every request fails — callers fall back to
+ * the SRA execution fee on their own.
+ */
+export function useProviderFees(
+  source: SourceToken | null,
+  destChain: Chain,
+  feeData: EstimatedFeeData | null,
+  recipient?: string,
+): ProviderFeesState {
+  const [breakdown, setBreakdown] = useState<FeeBreakdown | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  const sourceChainId = source?.chain.id
+  const tokenType = source?.tokenType
+  const destChainId = destChain.id
+  const minDeposit = feeData?.minDeposit
+  const symbol = feeData?.name
+  const decimals = feeData?.decimal
+
+  useEffect(() => {
+    setBreakdown(null)
+    if (
+      tokenType === undefined ||
+      sourceChainId === undefined ||
+      !minDeposit ||
+      symbol === undefined ||
+      decimals === undefined
+    ) {
+      setLoading(false)
+      return
+    }
+    setLoading(true)
+
+    let amount: string
+    try {
+      amount = BigInt(minDeposit).toString()
+    } catch {
+      // Malformed `minDeposit` — nothing to quote. Clear loading so the
+      // caller doesn't sit in a spinner forever until the route changes.
+      setLoading(false)
+      return
+    }
+
+    const route: Route = {
+      tokenType,
+      originChainId: sourceChainId,
+      destinationChainId: destChainId,
+      amount,
+      user: (recipient as Address) || QUOTE_USER,
+      symbol,
+      decimals,
+    }
+
+    const controller = new AbortController()
+    // Swallow provider failures so one broken provider doesn't take out the
+    // other — but log everything except the expected abort so a real bug
+    // (network, parser regression) doesn't disappear silently.
+    const safe = (label: string, p: Promise<FeeBreakdown | null>) =>
+      p.catch((err) => {
+        if (err?.name !== 'AbortError') {
+          // biome-ignore lint/suspicious/noConsole: surfaces network / parser regressions that would otherwise be invisible.
+          console.warn(`[useProviderFees] ${label} failed`, err)
+        }
+        return null
+      })
+    Promise.all([
+      safe('Across', fetchAcross(route, controller.signal)),
+      safe('Relay', fetchRelay(route, controller.signal)),
+    ])
+      .then(([across, relay]) => {
+        const chosen = bestRoute([across, relay])
+        if (!controller.signal.aborted) {
+          setBreakdown(chosen)
+          setLoading(false)
+        }
+      })
+      .catch(() => {
+        // All providers failed → caller shows the SRA fee
+        if (!controller.signal.aborted) setLoading(false)
+      })
+    return () => controller.abort()
+  }, [
+    sourceChainId,
+    tokenType,
+    destChainId,
+    minDeposit,
+    symbol,
+    decimals,
+    recipient,
+  ])
+
+  return { fees: breakdown, loading }
+}