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

package/src/pages/index.tsx

@@ -0,0 +1,165 @@
+import { PoweredBy, Screen, TopNav } from '@zerodev/react-ui'
+import type { DepositedToken } from '@zerodev/smart-routing-address'
+import { type ReactNode, useEffect, useState } from 'react'
+import type { Address } from 'viem'
+import { QrSheet } from '../components/QrSheet'
+import { useSmartRoutingAddressContext } from '../context/SmartRoutingAddressContext'
+import { Deposit } from './Deposit'
+import { PastDeposits } from './PastDeposits'
+import { TransactionDetails } from './TransactionDetails'
+
+/**
+ * Steps rendered by `SmartRoutingAddress`. Sub-views advance/rewind local
+ * step state; the widget owns navigation and the `TopNav` chrome accordingly.
+ */
+export type SmartRoutingAddressStep = 'deposit' | 'past' | 'transaction'
+
+const TITLE_BY_STEP: Record<SmartRoutingAddressStep, string> = {
+  deposit: 'Deposit funds',
+  past: 'Past deposits',
+  transaction: 'Transaction details',
+}
+
+function renderStep(
+  step: SmartRoutingAddressStep,
+  {
+    onQrClick,
+    onViewPastDeposits,
+    onSelectDeposit,
+    selectedDeposit,
+  }: {
+    onQrClick?: (() => void) | undefined
+    onViewPastDeposits?: (() => void) | undefined
+    onSelectDeposit?: ((deposit: DepositedToken) => void) | undefined
+    selectedDeposit?: DepositedToken | undefined
+  },
+): ReactNode {
+  switch (step) {
+    case 'deposit':
+      return (
+        <Deposit
+          {...(onQrClick && { onQrClick })}
+          {...(onViewPastDeposits && { onViewPastDeposits })}
+          {...(onSelectDeposit && { onSelectDeposit })}
+        />
+      )
+    case 'past':
+      return <PastDeposits {...(onSelectDeposit && { onSelectDeposit })} />
+    case 'transaction':
+      // `selectedDeposit` is set by the past-deposits row-click handler
+      // before advancing the step, so this branch always has a deposit.
+      return selectedDeposit ? (
+        <TransactionDetails deposit={selectedDeposit} />
+      ) : null
+    default:
+      return null
+  }
+}
+
+/**
+ * The Figma "Deposit funds" flow (`17634:104268` / `18721:96092`).
+ *
+ * Owns the shared `Screen` + `TopNav` chrome and delegates the body to the
+ * current page in this directory. Mirrors the layout of `wallet-react-ui`'s
+ * `auth/index.tsx` and `signing/index.tsx`.
+ *
+ * Wrap the subtree with `<SmartRoutingAddressProvider config={…}>` first.
+ */
+export interface SmartRoutingAddressProps {
+  /** Recipient address the smart routing address is created for. */
+  recipient: Address
+  /** Called when the top-right × close button is clicked. */
+  onClose: () => void
+  className?: string
+  size?: 'sm' | 'md' | 'lg'
+}
+
+export function SmartRoutingAddress({
+  recipient,
+  onClose,
+  className,
+  size,
+}: SmartRoutingAddressProps) {
+  const { addressState, getOrCreateAddress } = useSmartRoutingAddressContext()
+  const [qrOpen, setQrOpen] = useState(false)
+  const [step, setStep] = useState<SmartRoutingAddressStep>('deposit')
+  const [selectedDeposit, setSelectedDeposit] = useState<
+    DepositedToken | undefined
+  >(undefined)
+
+  useEffect(() => {
+    // Errors surface via `addressState.status === 'error'`; swallow rejection
+    // here so React doesn't warn about an unhandled promise.
+    getOrCreateAddress(recipient).catch(() => {})
+  }, [recipient, getOrCreateAddress])
+
+  const title = TITLE_BY_STEP[step]
+
+  const address =
+    addressState.status === 'success' ? addressState.address : undefined
+
+  // The QR button in AddressDisplay only exists once the address has resolved,
+  // but guard here too so we don't render an empty QrSheet.
+  const handleQrClick = address ? () => setQrOpen(true) : undefined
+
+  const handleCopy = async () => {
+    if (!address) return
+    try {
+      await navigator.clipboard.writeText(address)
+    } catch {
+      // Clipboard can reject on insecure contexts / permissions; the visual
+      // "copied" state isn't in the spec yet, so just close and swallow.
+    }
+    setQrOpen(false)
+  }
+
+  // Sub-view chrome — sub-views swap the left slot for a back chevron that
+  // returns to the parent step. Root (deposit) step has no left button
+  // (TopNav renders a spacer so the title stays centred).
+  const goBack =
+    step === 'transaction'
+      ? () => setStep('past')
+      : step === 'past'
+        ? () => setStep('deposit')
+        : undefined
+
+  return (
+    <Screen
+      className={className}
+      {...(size && { size })}
+      topNav={
+        <TopNav
+          title={title}
+          {...(goBack && {
+            onLeftButtonClick: goBack,
+            leftButtonIcon: 'chevronLeft' as const,
+          })}
+          onRightButtonClick={onClose}
+        />
+      }
+      footer={<PoweredBy />}
+    >
+      {renderStep(step, {
+        onQrClick: handleQrClick,
+        onViewPastDeposits: () => setStep('past'),
+        onSelectDeposit: (deposit) => {
+          setSelectedDeposit(deposit)
+          setStep('transaction')
+        },
+        selectedDeposit,
+      })}
+      {/* QrSheet renders itself via `useScreenOverlayContainer()` + portal, so
+        it stays inside the card frame while composing at this level rather
+        than being hoisted into `Screen`'s API. Mounted whenever an address
+        exists so Radix Dialog owns the open/close animation lifecycle. */}
+      {address && (
+        <QrSheet
+          open={qrOpen}
+          onOpenChange={setQrOpen}
+          address={address}
+          onCopy={handleCopy}
+        />
+      )}
+    </Screen>
+  )
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+import type {
+  CreateSmartRoutingAddressParams,
+  DepositedToken,
+  GetSmartRoutingAddressFeeEstimatesReturns,
+  SmartRoutingAddressVersion,
+  TOKEN_TYPE,
+} from '@zerodev/smart-routing-address'
+import type { Address, Chain } from 'viem'
+
+/** `DepositedToken` with the optional `createdAt` some SRA servers ship
+ * alongside the response. The SDK's public type doesn't include it yet, so
+ * we model it as an optional augmentation here — one canonical shape shared
+ * by the pending/past/detail views. */
+export type DepositWithTimestamp = DepositedToken & { createdAt?: string }
+
+export type EstimatedFee =
+  GetSmartRoutingAddressFeeEstimatesReturns['estimatedFees'][number]
+
+export type EstimatedFeeData = EstimatedFee['data'][number]
+
+/** Internal chain-object form of a source token */
+export type SourceToken = {
+  tokenType: TOKEN_TYPE
+  chain: Chain
+  minAmount?: bigint
+}
+
+export type SmartRoutingAddressConfig = {
+  /**
+   * ZeroDev project id; when non-empty it is appended to the server URL
+   * for every request
+   */
+  projectId?: string
+  /** Chain id where funds settle */
+  targetChainId: number
+  /** Smart routing address version, defaults to the latest stable */
+  version?: SmartRoutingAddressVersion
+  /**
+   * Destination actions per token type. When omitted, funds are simply
+   * transferred to the owner.
+   */
+  actions?: CreateSmartRoutingAddressParams['actions']
+  /** Max slippage in basis points (50 = 0.5%) */
+  slippage?: number
+  /**
+   * Override the smart routing address server root URL; the projectId is
+   * appended to it
+   */
+  baseUrl?: string
+}
+
+export type AddressState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | {
+      status: 'success'
+      address: Address
+      estimatedFees: EstimatedFee[]
+    }
+  | { status: 'error'; error: Error }
+
+export type DepositStage = 'pending' | 'bridging' | 'completed' | 'failed'
+
+/**
+ * The route the deposit UI is currently showing (selected source token +
+ * chain + estimated fee), surfaced through context so hosts can mirror it —
+ * e.g. a demo "send" panel that matches the chosen token, or analytics.
+ */
+export type ActiveRoute = {
+  /** Source chain id the deposit would come from */
+  sourceChainId: number
+  /** Source chain display name (e.g. "Base") */
+  sourceChainName: string
+  /** On-chain address of the selected source token */
+  token: Address
+  /** Display symbol of the selected source token (e.g. "USDC", "ETH") */
+  symbol: string
+  /** Decimals of the selected source token */
+  decimals: number
+  /** Estimated all-in fee amount in source-token atomic units, as a
+   * base-10 string (e.g. `"250000"` for 0.25 USDC). Consumers can pass it
+   * straight to `BigInt()` or `parseInt(x, 10)`. */
+  feeAmount: string
+}

package/src/utils/chains.ts

@@ -0,0 +1,26 @@
+import type { Chain } from 'viem'
+import { CHAINS_BY_ID, SUPPORTED_CHAINS } from '../constants'
+
+/** Resolve a chain id to its viem chain object, throwing for unknown ids */
+export function getChainById(chainId: number): Chain {
+  const chain = CHAINS_BY_ID.get(chainId)
+  if (!chain) {
+    const supported = SUPPORTED_CHAINS.map((c) => `${c.name} (${c.id})`)
+    throw new Error(
+      `Unsupported chain id ${chainId}. Supported chains: ${supported.join(', ')}`,
+    )
+  }
+  return chain
+}
+
+/** Block explorer URL for a transaction, or `undefined` when no explorer is
+ * known. Returns `undefined` (not `null`) so the value can be passed straight
+ * to optional link `href` props under `exactOptionalPropertyTypes`. */
+export function getTxUrl(
+  chainId: number,
+  transactionHash: string,
+): string | undefined {
+  const explorer = CHAINS_BY_ID.get(chainId)?.blockExplorers?.default
+  if (!explorer) return undefined
+  return `${explorer.url}/tx/${transactionHash}`
+}

package/src/utils/config.ts

@@ -0,0 +1,142 @@
+import type {
+  CreateSmartRoutingAddressParams,
+  SmartRoutingAddressVersion,
+  TOKEN_TYPE,
+} from '@zerodev/smart-routing-address'
+import {
+  createCall,
+  FLEX,
+  SMART_ROUTING_ADDRESS_SERVER_URL,
+  SMART_ROUTING_ADDRESS_V0_2_1,
+  SUPPORTED_TOKENS,
+} from '@zerodev/smart-routing-address'
+import { type Address, type Chain, erc20Abi } from 'viem'
+import { DEFAULT_DASHBOARD_URL, DEFAULT_SOURCE_TOKENS } from '../constants'
+import type {
+  EstimatedFee,
+  SmartRoutingAddressConfig,
+  SourceToken,
+} from '../types'
+import { getChainById } from './chains'
+import { tokenAddressMatches } from './fees'
+
+export function resolveVersion(
+  config: SmartRoutingAddressConfig,
+): SmartRoutingAddressVersion {
+  return config.version ?? SMART_ROUTING_ADDRESS_V0_2_1
+}
+
+/**
+ * Server URL for all smart routing address requests: the server root
+ * (default or `config.baseUrl`) with the ZeroDev project id appended.
+ * Without a project id the URL is only overridden when `config.baseUrl`
+ * is set; undefined leaves the SDK default in place.
+ */
+export function resolveBaseUrl(
+  config: SmartRoutingAddressConfig,
+): string | undefined {
+  if (!config.projectId) return config.baseUrl
+  const root = config.baseUrl ?? SMART_ROUTING_ADDRESS_SERVER_URL
+  return `${root.replace(/\/+$/, '')}/${config.projectId}`
+}
+
+export function resolveDashboardUrl(address?: string): string {
+  if (!address) return DEFAULT_DASHBOARD_URL
+  return `${DEFAULT_DASHBOARD_URL.replace(/\/+$/, '')}/address/${address}`
+}
+
+/** Chain where the routed funds settle */
+export function resolveDestChain(config: SmartRoutingAddressConfig): Chain {
+  return getChainById(config.targetChainId)
+}
+
+/**
+ * Whether the SDK can resolve the token type to an asset on the chain:
+ * generic ERC20 deposits are always accepted, every other type (including
+ * NATIVE) needs a SUPPORTED_TOKENS entry for the chain.
+ */
+function isTokenOnChain(tokenType: TOKEN_TYPE, chainId: number): boolean {
+  if (tokenType === 'ERC20') return true
+  return SUPPORTED_TOKENS[chainId]?.[tokenType] !== undefined
+}
+
+/**
+ * The DEFAULT_SOURCE_TOKENS, excluding token types that do not exist on the
+ * destination chain (the default actions deliver the deposited token type
+ * there, so a missing destination token would make the deposit unfulfillable).
+ */
+export function resolveSourceTokens(
+  config: SmartRoutingAddressConfig,
+): SourceToken[] {
+  const destChainId = resolveDestChain(config).id
+  return DEFAULT_SOURCE_TOKENS.filter((source) =>
+    isTokenOnChain(source.tokenType, destChainId),
+  )
+}
+
+/**
+ * Source tokens the server actually returned routes for, taken straight from
+ * the fee estimates. Each returned (chain, token address) pair is matched back
+ * to a DEFAULT_SOURCE_TOKENS entry to recover its TOKEN_TYPE.
+ */
+export function sourceTokensFromFees(
+  estimatedFees: EstimatedFee[],
+): SourceToken[] {
+  return estimatedFees.flatMap((fee) =>
+    fee.data.flatMap((data) => {
+      const token = DEFAULT_SOURCE_TOKENS.find(
+        (source) =>
+          source.chain.id === fee.chainId &&
+          tokenAddressMatches(source.tokenType, fee.chainId, data.token),
+      )
+      return token ? [token] : []
+    }),
+  )
+}
+
+function uniqueTokenTypes(sources: SourceToken[]): TOKEN_TYPE[] {
+  return [...new Set(sources.map((source) => source.tokenType))]
+}
+
+/**
+ * Destination actions for every resolved source token type: ERC-20 deposits
+ * are transferred to the recipient and native deposits are forwarded as
+ * value. FLEX placeholders are resolved by the server per deposit.
+ */
+export function resolveActions(
+  config: SmartRoutingAddressConfig,
+  recipient: Address,
+): CreateSmartRoutingAddressParams['actions'] {
+  const erc20Call = createCall({
+    target: FLEX.TOKEN_ADDRESS,
+    value: 0n,
+    abi: erc20Abi,
+    functionName: 'transfer',
+    args: [recipient, FLEX.AMOUNT],
+  })
+  const nativeCall = createCall({
+    target: recipient,
+    value: FLEX.NATIVE_AMOUNT,
+  })
+
+  return Object.fromEntries(
+    uniqueTokenTypes(resolveSourceTokens(config)).map((tokenType) => [
+      tokenType,
+      {
+        action: tokenType === 'NATIVE' ? [nativeCall] : [erc20Call],
+        fallBack: tokenType === 'NATIVE' ? [nativeCall] : [erc20Call],
+      },
+    ]),
+  )
+}
+
+/** Display symbol for a source token (native tokens use the chain symbol) */
+export function getSourceTokenSymbol(source: SourceToken): string {
+  if (source.tokenType === 'NATIVE') {
+    return source.chain.nativeCurrency.symbol
+  }
+  if (source.tokenType === 'WRAPPED_NATIVE') {
+    return `W${source.chain.nativeCurrency.symbol}`
+  }
+  return source.tokenType
+}

package/src/utils/deposits.ts

@@ -0,0 +1,106 @@
+import type { DepositedToken } from '@zerodev/smart-routing-address'
+import type {
+  DepositStage,
+  EstimatedFee,
+  SmartRoutingAddressConfig,
+} from '../types'
+import { resolveDestChain, resolveSourceTokens } from './config'
+import { findFeeDataByToken } from './fees'
+import { formatTokenAmount, truncateAddress } from './format'
+
+export const DEPOSIT_STAGE_LABELS: Record<DepositStage, string> = {
+  pending: 'Deposit detected',
+  bridging: 'Bridging',
+  completed: 'Completed',
+  failed: 'Failed',
+}
+
+/**
+ * Newer SRA servers split a deposit into legs that each carry their own
+ * bridge/execution status; the published SDK types don't include the
+ * field yet, so it is modeled here as an optional extension.
+ */
+export type DepositSplitLeg = Pick<DepositedToken, 'bridge' | 'execution'> & {
+  splitIndex: number
+  amount: string
+}
+
+export type DepositWithSplits = DepositedToken & {
+  splits?: DepositSplitLeg[]
+}
+
+export function getDepositKey(deposit: DepositedToken): string {
+  return deposit.deposit.transactionHash
+}
+
+export function getDepositStage(deposit: DepositWithSplits): DepositStage {
+  if (deposit.error) return 'failed'
+  // Split deposits carry bridge/execution on each leg; the top-level
+  // fields stay null.
+  if (deposit.splits && deposit.splits.length > 0) {
+    if (deposit.splits.every((leg) => leg.execution !== null)) {
+      return 'completed'
+    }
+    if (
+      deposit.splits.some(
+        (leg) => leg.bridge !== null || leg.execution !== null,
+      )
+    ) {
+      return 'bridging'
+    }
+    return 'pending'
+  }
+  if (deposit.execution) return 'completed'
+  if (deposit.bridge) return 'bridging'
+  return 'pending'
+}
+
+export function getNewDeposits(
+  deposits: DepositedToken[],
+  baseline: ReadonlySet<string>,
+): DepositedToken[] {
+  return deposits.filter((deposit) => !baseline.has(getDepositKey(deposit)))
+}
+
+export type DepositSummary = {
+  key: string
+  stage: DepositStage
+  stageLabel: string
+  chainName: string
+  symbol: string
+  amount: string
+  transactionHash: string
+}
+
+function getChainName(
+  chainId: number,
+  config: SmartRoutingAddressConfig,
+): string {
+  const destChain = resolveDestChain(config)
+  if (destChain.id === chainId) return destChain.name
+  const source = resolveSourceTokens(config).find(
+    (token) => token.chain.id === chainId,
+  )
+  return source?.chain.name ?? `Chain ${chainId}`
+}
+
+export function summarizeDeposit(
+  deposit: DepositedToken,
+  estimatedFees: EstimatedFee[],
+  config: SmartRoutingAddressConfig,
+): DepositSummary {
+  const { chainId, token, amount, transactionHash } = deposit.deposit
+  const feeData = findFeeDataByToken(estimatedFees, chainId, token)
+  const stage = getDepositStage(deposit)
+  return {
+    key: getDepositKey(deposit),
+    stage,
+    stageLabel: DEPOSIT_STAGE_LABELS[stage],
+    chainName: getChainName(chainId, config),
+    symbol: feeData?.name ?? truncateAddress(token),
+    amount: feeData
+      ? formatTokenAmount(amount, feeData.decimal)
+      : String(amount),
+    transactionHash,
+  }
+}

package/src/utils/fees.ts

@@ -0,0 +1,51 @@
+import type { TOKEN_TYPE } from '@zerodev/smart-routing-address'
+import { SUPPORTED_TOKENS } from '@zerodev/smart-routing-address'
+import type { Address } from 'viem'
+import { isAddressEqual, zeroAddress } from 'viem'
+import type { EstimatedFee, EstimatedFeeData } from '../types'
+
+/**
+ * Resolve the on-chain token address used by the routing server for a given
+ * token type on a chain. Returns null when the type cannot be resolved
+ * (generic ERC20 or unknown token on that chain).
+ */
+export function resolveTokenAddress(
+  tokenType: TOKEN_TYPE,
+  chainId: number,
+): Address | null {
+  if (tokenType === 'NATIVE') return zeroAddress
+  if (tokenType === 'ERC20') return null
+  return SUPPORTED_TOKENS[chainId]?.[tokenType] ?? null
+}
+
+/** Whether the token type resolves to the given on-chain address on a chain. */
+export function tokenAddressMatches(
+  tokenType: TOKEN_TYPE,
+  chainId: number,
+  token: Address,
+): boolean {
+  const address = resolveTokenAddress(tokenType, chainId)
+  return address !== null && isAddressEqual(address, token)
+}
+
+export function findFeeDataByToken(
+  estimatedFees: EstimatedFee[],
+  chainId: number,
+  token: Address,
+): EstimatedFeeData | null {
+  const chainFees = estimatedFees.find((fee) => fee.chainId === chainId)
+  if (!chainFees) return null
+  return (
+    chainFees.data.find((data) => isAddressEqual(data.token, token)) ?? null
+  )
+}
+
+export function findFeeData(
+  estimatedFees: EstimatedFee[],
+  chainId: number,
+  tokenType: TOKEN_TYPE,
+): EstimatedFeeData | null {
+  const token = resolveTokenAddress(tokenType, chainId)
+  if (!token) return null
+  return findFeeDataByToken(estimatedFees, chainId, token)
+}

package/src/utils/format.ts

@@ -0,0 +1,108 @@
+import { formatUnits } from 'viem'
+
+/**
+ * Format a raw token amount (decimal string, hex string or bigint) into a
+ * human readable unit string. Falls back to the raw value if parsing fails.
+ */
+export function formatTokenAmount(
+  value: string | bigint,
+  decimals: number,
+): string {
+  try {
+    const amount = typeof value === 'bigint' ? value : BigInt(value)
+    return formatUnits(amount, decimals)
+  } catch {
+    return String(value)
+  }
+}
+
+/** Rounding direction for display amounts. `'up'` / `'down'` are ceil / floor
+ * — use them for values where over- or under-stating is unsafe (fees, min
+ * deposit). `'nearest'` is `Math.round` — use for values the user reads as a
+ * final quantity ("you received X") so 249.9996… reads as 250.00. */
+export type RoundDirection = 'up' | 'down' | 'nearest'
+
+function displayFractionDigits(value: number): number {
+  if (value >= 1000) return 0
+  if (value >= 1) return 2
+  // Two significant digits for sub-unit amounts
+  return Math.min(8, 1 - Math.floor(Math.log10(value)))
+}
+
+/**
+ * Format a raw token amount for display: thousands grouping and a
+ * magnitude-aware precision (whole numbers above 1000, two decimals above 1,
+ * two significant digits below). Rounds in the given direction so limits and
+ * fees are never overstated/understated. Falls back to the raw value if
+ * parsing fails.
+ */
+export function formatDisplayAmount(
+  value: string | bigint,
+  decimals: number,
+  round: RoundDirection,
+): string {
+  let amount: number
+  try {
+    amount = Number(
+      formatUnits(typeof value === 'bigint' ? value : BigInt(value), decimals),
+    )
+  } catch {
+    return String(value)
+  }
+  if (amount === 0) return '0'
+
+  const digits = displayFractionDigits(amount)
+  const factor = 10 ** digits
+  const roundFn =
+    round === 'up' ? Math.ceil : round === 'down' ? Math.floor : Math.round
+  const rounded = roundFn(amount * factor) / factor
+  return rounded.toLocaleString('en-US', {
+    maximumFractionDigits: digits,
+  })
+}
+
+export function truncateAddress(address: string): string {
+  if (address.length <= 12) return address
+  return `${address.slice(0, 6)}…${address.slice(-4)}`
+}
+
+export function formatSlippage(basisPoints: number): string {
+  return `${(basisPoints / 100).toFixed(2).replace(/\.?0+$/, '')}%`
+}
+
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) return `~${Math.max(1, Math.round(seconds))} sec`
+  return `~${Math.round(seconds / 60)} min`
+}
+
+/** Symbols treated as ~$1, so a USD equivalent can be shown for their amounts */
+export const STABLE_SYMBOLS = new Set([
+  'USDC',
+  'USDT',
+  'DAI',
+  'USDBC',
+  'USDC.E',
+])
+
+/** ISO timestamp → compact "N unit ago" ("just now", "2 m ago", "3 h ago",
+ * "5 d ago", "2 mo ago", "1 y ago"). Returns `null` on invalid input. */
+export function formatRelativeTime(
+  iso: string,
+  now: number = Date.now(),
+): string | null {
+  const then = Date.parse(iso)
+  if (Number.isNaN(then)) return null
+  const seconds = Math.max(0, Math.round((now - then) / 1000))
+  if (seconds < 30) return 'just now'
+  if (seconds < 60) return `${seconds} s ago`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes} m ago`
+  const hours = Math.round(minutes / 60)
+  if (hours < 24) return `${hours} h ago`
+  const days = Math.round(hours / 24)
+  if (days < 30) return `${days} d ago`
+  const months = Math.round(days / 30)
+  if (months < 12) return `${months} mo ago`
+  const years = Math.round(months / 12)
+  return `${years} y ago`
+}