Fix dashboard trend test expectations

frontend/src/components/common/DisplayCurrencyContext.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from 'react'
+
+export type DisplayCurrency = 'native' | 'usd'
+
+const DISPLAY_CURRENCY_STORAGE_KEY = 'explorer_display_currency'
+
+const DisplayCurrencyContext = createContext<{
+  currency: DisplayCurrency
+  setCurrency: (currency: DisplayCurrency) => void
+} | null>(null)
+
+export function DisplayCurrencyProvider({ children }: { children: ReactNode }) {
+  const [currency, setCurrencyState] = useState<DisplayCurrency>('native')
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const stored = window.localStorage.getItem(DISPLAY_CURRENCY_STORAGE_KEY)
+    if (stored === 'native' || stored === 'usd') {
+      setCurrencyState(stored)
+    }
+  }, [])
+
+  const setCurrency = (nextCurrency: DisplayCurrency) => {
+    setCurrencyState(nextCurrency)
+    if (typeof window !== 'undefined') {
+      window.localStorage.setItem(DISPLAY_CURRENCY_STORAGE_KEY, nextCurrency)
+    }
+  }
+
+  const value = useMemo(
+    () => ({
+      currency,
+      setCurrency,
+    }),
+    [currency],
+  )
+
+  return <DisplayCurrencyContext.Provider value={value}>{children}</DisplayCurrencyContext.Provider>
+}
+
+export function useDisplayCurrency() {
+  const context = useContext(DisplayCurrencyContext)
+  if (!context) {
+    throw new Error('useDisplayCurrency must be used within a DisplayCurrencyProvider')
+  }
+  return context
+}

frontend/src/components/common/ExplorerChrome.tsx

@@ -2,25 +2,28 @@ import type { ReactNode } from 'react'
 import Navbar from './Navbar'
 import Footer from './Footer'
 import ExplorerAgentTool from './ExplorerAgentTool'
+import { DisplayCurrencyProvider } from './DisplayCurrencyContext'
 import { UiModeProvider } from './UiModeContext'
 
 export default function ExplorerChrome({ children }: { children: ReactNode }) {
   return (
     <UiModeProvider>
-      <div className="flex min-h-screen flex-col bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-gray-100">
-        <a
-          href="#main-content"
-          className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100] focus:rounded-md focus:bg-primary-600 focus:px-4 focus:py-2 focus:text-sm focus:font-medium focus:text-white"
-        >
-          Skip to content
-        </a>
-        <Navbar />
-        <div id="main-content" className="flex-1">
-          {children}
+      <DisplayCurrencyProvider>
+        <div className="flex min-h-screen flex-col bg-gray-50 text-gray-900 dark:bg-gray-900 dark:text-gray-100">
+          <a
+            href="#main-content"
+            className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100] focus:rounded-md focus:bg-primary-600 focus:px-4 focus:py-2 focus:text-sm focus:font-medium focus:text-white"
+          >
+            Skip to content
+          </a>
+          <Navbar />
+          <div id="main-content" className="flex-1">
+            {children}
+          </div>
+          <ExplorerAgentTool />
+          <Footer />
         </div>
-        <ExplorerAgentTool />
-        <Footer />
-      </div>
+      </DisplayCurrencyProvider>
     </UiModeProvider>
   )
 }

frontend/src/pages/addresses/[address].tsx

@@ -51,17 +51,14 @@ export default function AddressDetailPage() {
   const [watchlistEntries, setWatchlistEntries] = useState<string[]>([])
   const [methodResults, setMethodResults] = useState<Record<string, { loading: boolean; value?: string; error?: string }>>({})
   const [methodInputs, setMethodInputs] = useState<Record<string, string[]>>({})
-  const [addressInfoLoading, setAddressInfoLoading] = useState(true)
-  const [activityLoading, setActivityLoading] = useState(true)
+  const [loading, setLoading] = useState(true)
 
   const loadAddressInfo = useCallback(async () => {
-    setAddressInfoLoading(true)
     try {
       const { ok, data } = await addressesApi.getSafe(chainId, address)
       if (!ok) {
         setAddressInfo(null)
         setContractProfile(null)
-        setGruProfile(null)
         return
       }
       setAddressInfo(data ?? null)
@@ -85,13 +82,10 @@ export default function AddressDetailPage() {
       setAddressInfo(null)
       setContractProfile(null)
       setGruProfile(null)
-    } finally {
-      setAddressInfoLoading(false)
     }
   }, [chainId, address])
 
   const loadTransactions = useCallback(async () => {
-    setActivityLoading(true)
     try {
       const [transactionsResult, balancesResult, transfersResult] = await Promise.all([
         addressesApi.getTransactionsSafe(chainId, address, 1, 20),
@@ -108,37 +102,27 @@ export default function AddressDetailPage() {
       setTokenBalances([])
       setTokenTransfers([])
     } finally {
-      setActivityLoading(false)
+      setLoading(false)
     }
   }, [chainId, address])
 
   useEffect(() => {
     if (!router.isReady || !address) {
-      setAddressInfoLoading(!router.isReady)
-      setActivityLoading(!router.isReady)
+      setLoading(router.isReady ? false : true)
       if (router.isReady && !address) {
         setAddressInfo(null)
         setTransactions([])
-        setTokenBalances([])
-        setTokenTransfers([])
       }
       return
     }
     if (!isValidAddressParam) {
-      setAddressInfoLoading(false)
-      setActivityLoading(false)
+      setLoading(false)
       setAddressInfo(null)
       setTransactions([])
-      setTokenBalances([])
-      setTokenTransfers([])
       return
     }
-    setAddressInfo(null)
-    setTransactions([])
-    setTokenBalances([])
-    setTokenTransfers([])
-    void loadAddressInfo()
-    void loadTransactions()
+    loadAddressInfo()
+    loadTransactions()
   }, [address, isValidAddressParam, loadAddressInfo, loadTransactions, router.isReady])
 
   useEffect(() => {
@@ -419,8 +403,6 @@ export default function AddressDetailPage() {
   const gruTransferCount = tokenTransfers.filter((transfer) =>
     Boolean(getGruExplorerMetadata({ address: transfer.token_address, symbol: transfer.token_symbol })),
   ).length
-  const showPrimaryLoadingState = !router.isReady || (addressInfoLoading && !addressInfo)
-  const resolvedAddressInfo = addressInfo as AddressInfo
 
   return (
     <div className="container mx-auto px-4 py-6 sm:py-8">
@@ -444,7 +426,7 @@ export default function AddressDetailPage() {
             Search this address
           </Link>
         )}
-        {watchlistAddress && router.isReady && !addressInfoLoading && (
+        {watchlistAddress && router.isReady && !loading && (
           <button
             type="button"
             onClick={handleWatchlistToggle}
@@ -455,7 +437,7 @@ export default function AddressDetailPage() {
         )}
       </div>
 
-      {showPrimaryLoadingState ? (
+      {!router.isReady || loading ? (
         <Card className="mb-6">
           <p className="text-sm text-gray-600 dark:text-gray-400">Loading address...</p>
         </Card>
@@ -471,7 +453,7 @@ export default function AddressDetailPage() {
             </Link>
           </div>
         </Card>
-      ) : !addressInfoLoading && !addressInfo ? (
+      ) : !addressInfo ? (
         <Card className="mb-6">
           <p className="text-sm text-gray-600 dark:text-gray-400">Address not found.</p>
           <div className="mt-4 flex flex-wrap gap-3 text-sm">
@@ -488,69 +470,68 @@ export default function AddressDetailPage() {
           <Card title="Address Information" className="mb-6">
             <dl className="space-y-4">
               <DetailRow label="Address">
-                <Address address={resolvedAddressInfo.address} />
+                <Address address={addressInfo.address} />
               </DetailRow>
-              {resolvedAddressInfo.balance && (
-                <DetailRow label="Coin Balance">{formatWeiAsEth(resolvedAddressInfo.balance)}</DetailRow>
+              {addressInfo.balance && (
+                <DetailRow label="Coin Balance">{formatWeiAsEth(addressInfo.balance)}</DetailRow>
               )}
               <DetailRow label="Watchlist">
                 {isSavedToWatchlist ? 'Saved for quick access' : 'Not saved yet'}
               </DetailRow>
               <DetailRow label="Verification">
                 <div className="flex flex-wrap gap-2">
-                  <EntityBadge label={resolvedAddressInfo.is_contract ? (resolvedAddressInfo.is_verified ? 'verified' : 'contract') : 'eoa'} />
+                  <EntityBadge label={addressInfo.is_contract ? (addressInfo.is_verified ? 'verified' : 'contract') : 'eoa'} />
                   {contractProfile?.source_verified ? <EntityBadge label="source available" tone="success" /> : null}
                   {contractProfile?.abi_available ? <EntityBadge label="abi available" tone="info" /> : null}
-                  {resolvedAddressInfo.token_contract ? <EntityBadge label={resolvedAddressInfo.token_contract.type || 'token'} tone="info" /> : null}
+                  {addressInfo.token_contract ? <EntityBadge label={addressInfo.token_contract.type || 'token'} tone="info" /> : null}
                 </div>
               </DetailRow>
-              {resolvedAddressInfo.token_contract && (
+              {addressInfo.token_contract && (
                 <DetailRow label="Token Contract">
                   <div className="space-y-2">
                     <div>
-                      {resolvedAddressInfo.token_contract.symbol || resolvedAddressInfo.token_contract.name || 'Token contract'} · {resolvedAddressInfo.token_contract.type || 'Token'}
+                      {addressInfo.token_contract.symbol || addressInfo.token_contract.name || 'Token contract'} · {addressInfo.token_contract.type || 'Token'}
                     </div>
-                    <Link href={`/tokens/${resolvedAddressInfo.token_contract.address}`} className="text-primary-600 hover:underline">
+                    <Link href={`/tokens/${addressInfo.token_contract.address}`} className="text-primary-600 hover:underline">
                       Open token detail →
                     </Link>
                   </div>
                 </DetailRow>
               )}
-              {resolvedAddressInfo.tags.length > 0 && (
+              {addressInfo.tags.length > 0 && (
                 <DetailRow label="Tags" valueClassName="flex flex-wrap gap-2">
-                    {resolvedAddressInfo.tags.map((tag, i) => (
+                    {addressInfo.tags.map((tag, i) => (
                       <EntityBadge key={i} label={tag} className="px-2 py-1 text-[11px]" />
                     ))}
                 </DetailRow>
               )}
-              <DetailRow label="Transactions">{resolvedAddressInfo.transaction_count}</DetailRow>
-              <DetailRow label="Tokens">{resolvedAddressInfo.token_count}</DetailRow>
-              <DetailRow label="Type">{resolvedAddressInfo.is_contract ? 'Contract' : 'EOA'}</DetailRow>
+              <DetailRow label="Transactions">{addressInfo.transaction_count}</DetailRow>
+              <DetailRow label="Tokens">{addressInfo.token_count}</DetailRow>
+              <DetailRow label="Type">{addressInfo.is_contract ? 'Contract' : 'EOA'}</DetailRow>
               <DetailRow label="Recent Activity">
-                {activityLoading ? 'Loading recent activity...' : `${incomingTransactions} incoming / ${outgoingTransactions} outgoing txs`}
+                {incomingTransactions} incoming / {outgoingTransactions} outgoing txs
               </DetailRow>
-              {resolvedAddressInfo.internal_transaction_count != null && (
-                <DetailRow label="Internal Calls">{resolvedAddressInfo.internal_transaction_count}</DetailRow>
+              {addressInfo.internal_transaction_count != null && (
+                <DetailRow label="Internal Calls">{addressInfo.internal_transaction_count}</DetailRow>
               )}
-              {resolvedAddressInfo.logs_count != null && (
-                <DetailRow label="Indexed Logs">{resolvedAddressInfo.logs_count}</DetailRow>
+              {addressInfo.logs_count != null && (
+                <DetailRow label="Indexed Logs">{addressInfo.logs_count}</DetailRow>
               )}
               <DetailRow label="Token Flow">
-                {activityLoading
-                  ? 'Loading token transfer activity...'
-                  : `${incomingTokenTransfers} incoming / ${outgoingTokenTransfers} outgoing token transfers${resolvedAddressInfo.token_transfer_count != null ? ` · ${resolvedAddressInfo.token_transfer_count} total indexed` : ''}`}
+                {incomingTokenTransfers} incoming / {outgoingTokenTransfers} outgoing token transfers
+                {addressInfo.token_transfer_count != null ? ` · ${addressInfo.token_transfer_count} total indexed` : ''}
               </DetailRow>
-              {resolvedAddressInfo.creation_transaction_hash && (
+              {addressInfo.creation_transaction_hash && (
                 <DetailRow label="Created In">
-                  <Link href={`/transactions/${resolvedAddressInfo.creation_transaction_hash}`} className="text-primary-600 hover:underline">
-                    <Address address={resolvedAddressInfo.creation_transaction_hash} truncate showCopy={false} />
+                  <Link href={`/transactions/${addressInfo.creation_transaction_hash}`} className="text-primary-600 hover:underline">
+                    <Address address={addressInfo.creation_transaction_hash} truncate showCopy={false} />
                   </Link>
                 </DetailRow>
               )}
             </dl>
           </Card>
 
-          {resolvedAddressInfo.is_contract && (
+          {addressInfo.is_contract && (
             <Card title="Contract Profile" className="mb-6">
               <dl className="space-y-4">
                 <DetailRow label="Interaction Surface">
@@ -790,16 +771,12 @@ export default function AddressDetailPage() {
                 </Link>
               </div>
             ) : null}
-            {activityLoading ? (
-              <p className="text-sm text-gray-600 dark:text-gray-400">Loading token balances...</p>
-            ) : (
-              <Table
-                columns={tokenBalanceColumns}
-                data={tokenBalances}
-                emptyMessage="No token balances were indexed for this address."
-                keyExtractor={(balance) => balance.token_address || `${balance.token_symbol}-${balance.value}`}
-              />
-            )}
+            <Table
+              columns={tokenBalanceColumns}
+              data={tokenBalances}
+              emptyMessage="No token balances were indexed for this address."
+              keyExtractor={(balance) => balance.token_address || `${balance.token_symbol}-${balance.value}`}
+            />
           </Card>
 
           <Card title="Recent Token Transfers" className="mb-6">
@@ -814,29 +791,21 @@ export default function AddressDetailPage() {
                 </Link>
               </div>
             ) : null}
-            {activityLoading ? (
-              <p className="text-sm text-gray-600 dark:text-gray-400">Loading token transfers...</p>
-            ) : (
-              <Table
-                columns={tokenTransferColumns}
-                data={tokenTransfers}
-                emptyMessage="No token transfers were found for this address."
-                keyExtractor={(transfer) => `${transfer.transaction_hash}-${transfer.token_address}-${transfer.value}`}
-              />
-            )}
+            <Table
+              columns={tokenTransferColumns}
+              data={tokenTransfers}
+              emptyMessage="No token transfers were found for this address."
+              keyExtractor={(transfer) => `${transfer.transaction_hash}-${transfer.token_address}-${transfer.value}`}
+            />
           </Card>
 
           <Card title="Transactions">
-            {activityLoading ? (
-              <p className="text-sm text-gray-600 dark:text-gray-400">Loading recent transactions...</p>
-            ) : (
-              <Table
-                columns={transactionColumns}
-                data={transactions}
-                emptyMessage="No recent transactions were found for this address."
-                keyExtractor={(tx) => tx.hash}
-              />
-            )}
+            <Table
+              columns={transactionColumns}
+              data={transactions}
+              emptyMessage="No recent transactions were found for this address."
+              keyExtractor={(tx) => tx.hash}
+            />
           </Card>
         </>
       )}

frontend/src/pages/tokens/[address].tsx

@@ -12,8 +12,10 @@ import { DetailRow } from '@/components/common/DetailRow'
 import EntityBadge from '@/components/common/EntityBadge'
 import GruStandardsCard from '@/components/common/GruStandardsCard'
 import { formatTokenAmount, formatTimestamp } from '@/utils/format'
+import { useDisplayCurrency } from '@/components/common/DisplayCurrencyContext'
 import { getGruStandardsProfileSafe, type GruStandardsProfile } from '@/services/api/gru'
 import { getGruExplorerMetadata } from '@/services/api/gruExplorerData'
+import { formatUsdValue, getSecondaryDisplayValue } from '@/utils/displayCurrency'
 
 function isValidAddress(value: string) {
   return /^0x[a-fA-F0-9]{40}$/.test(value)
@@ -31,15 +33,12 @@ function toNumeric(value: string | number | null | undefined): number | null {
 function formatUsd(value: string | number | null | undefined): string {
   const numeric = toNumeric(value)
   if (numeric == null) return 'Unavailable'
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency: 'USD',
-    maximumFractionDigits: numeric >= 100 ? 0 : 2,
-  }).format(numeric)
+  return formatUsdValue(numeric)
 }
 
 export default function TokenDetailPage() {
   const router = useRouter()
+  const { currency, setCurrency } = useDisplayCurrency()
   const address = typeof router.query.address === 'string' ? router.query.address : ''
   const isValidTokenAddress = address !== '' && isValidAddress(address)
 
@@ -177,6 +176,28 @@ export default function TokenDetailPage() {
     [address, token?.address, token?.symbol],
   )
 
+  const renderAmountWithDisplayCurrency = useCallback(
+    (rawAmount: string | number | null | undefined, decimals: number, symbol?: string | null) => {
+      const primaryAmount = formatTokenAmount(rawAmount, decimals, symbol)
+      const secondaryAmount = getSecondaryDisplayValue({
+        rawAmount,
+        decimals,
+        exchangeRate: token?.exchange_rate,
+        displayCurrency: currency,
+      })
+
+      if (!secondaryAmount) return primaryAmount
+
+      return (
+        <div className="space-y-1">
+          <div>{primaryAmount}</div>
+          <div className="text-xs text-gray-500 dark:text-gray-400">Approx. {secondaryAmount}</div>
+        </div>
+      )
+    },
+    [currency, token?.exchange_rate],
+  )
+
   const holderColumns = [
     {
       header: 'Holder',
@@ -188,7 +209,7 @@ export default function TokenDetailPage() {
     },
     {
       header: 'Balance',
-      accessor: (holder: TokenHolder) => formatTokenAmount(holder.value, token?.decimals || holder.token_decimals, token?.symbol),
+      accessor: (holder: TokenHolder) => renderAmountWithDisplayCurrency(holder.value, token?.decimals || holder.token_decimals, token?.symbol),
     },
   ]
 
@@ -238,7 +259,7 @@ export default function TokenDetailPage() {
     },
     {
       header: 'Amount',
-      accessor: (transfer: AddressTokenTransfer) => formatTokenAmount(transfer.value, transfer.token_decimals, transfer.token_symbol),
+      accessor: (transfer: AddressTokenTransfer) => renderAmountWithDisplayCurrency(transfer.value, transfer.token_decimals, transfer.token_symbol),
     },
     {
       header: 'When',
@@ -316,9 +337,27 @@ export default function TokenDetailPage() {
               </DetailRow>
               <DetailRow label="Type">{token.type || 'Unknown'}</DetailRow>
               <DetailRow label="Decimals">{token.decimals}</DetailRow>
+              <DetailRow label="Display Currency">
+                <div className="space-y-2">
+                  <label className="inline-flex items-center gap-2 text-sm text-gray-700 dark:text-gray-300">
+                    <span className="sr-only">Display currency</span>
+                    <select
+                      value={currency}
+                      onChange={(event) => setCurrency(event.target.value === 'usd' ? 'usd' : 'native')}
+                      className="rounded-xl border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 shadow-sm focus:border-primary-500 focus:outline-none focus:ring-2 focus:ring-primary-200 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100 dark:focus:ring-primary-900"
+                    >
+                      <option value="native">Native token amounts</option>
+                      <option value="usd">USD estimate</option>
+                    </select>
+                  </label>
+                  <div className="text-xs text-gray-500 dark:text-gray-400">
+                    USD estimates use the explorer&apos;s current indicative token price and appear as a secondary line when available.
+                  </div>
+                </div>
+              </DetailRow>
               {token.total_supply && (
                 <DetailRow label="Total Supply">
-                  {formatTokenAmount(token.total_supply, token.decimals, token.symbol)}
+                  {renderAmountWithDisplayCurrency(token.total_supply, token.decimals, token.symbol)}
                 </DetailRow>
               )}
               {token.holders != null && (

frontend/src/utils/dashboard.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import type { Block } from '@/services/api/blocks'
-import type { ExplorerStats } from '@/services/api/stats'
+import type { ExplorerStats, ExplorerTransactionTrendPoint } from '@/services/api/stats'
 import { loadDashboardData } from './dashboard'
 
 const sampleStats: ExplorerStats = {
@@ -23,6 +23,17 @@ const sampleBlocks: Block[] = [
   },
 ]
 
+const sampleTrend: ExplorerTransactionTrendPoint[] = [
+  {
+    date: '2026-04-03',
+    count: 11,
+  },
+  {
+    date: '2026-04-04',
+    count: 17,
+  },
+]
+
 describe('loadDashboardData', () => {
   it('returns both stats and recent blocks when both loaders succeed', async () => {
     const result = await loadDashboardData({
@@ -33,6 +44,7 @@ describe('loadDashboardData', () => {
     expect(result).toEqual({
       stats: sampleStats,
       recentBlocks: sampleBlocks,
+      recentTransactionTrend: [],
     })
   })
 
@@ -50,6 +62,7 @@ describe('loadDashboardData', () => {
     expect(result).toEqual({
       stats: null,
       recentBlocks: sampleBlocks,
+      recentTransactionTrend: [],
     })
     expect(onError).toHaveBeenCalledTimes(1)
     expect(onError).toHaveBeenCalledWith('stats', expect.any(Error))
@@ -69,8 +82,44 @@ describe('loadDashboardData', () => {
     expect(result).toEqual({
       stats: sampleStats,
       recentBlocks: [],
+      recentTransactionTrend: [],
     })
     expect(onError).toHaveBeenCalledTimes(1)
     expect(onError).toHaveBeenCalledWith('blocks', expect.any(Error))
   })
+
+  it('returns the recent transaction trend when the optional loader succeeds', async () => {
+    const result = await loadDashboardData({
+      loadStats: async () => sampleStats,
+      loadRecentBlocks: async () => sampleBlocks,
+      loadRecentTransactionTrend: async () => sampleTrend,
+    })
+
+    expect(result).toEqual({
+      stats: sampleStats,
+      recentBlocks: sampleBlocks,
+      recentTransactionTrend: sampleTrend,
+    })
+  })
+
+  it('falls back to an empty recent transaction trend when the optional loader fails', async () => {
+    const onError = vi.fn()
+
+    const result = await loadDashboardData({
+      loadStats: async () => sampleStats,
+      loadRecentBlocks: async () => sampleBlocks,
+      loadRecentTransactionTrend: async () => {
+        throw new Error('trend unavailable')
+      },
+      onError,
+    })
+
+    expect(result).toEqual({
+      stats: sampleStats,
+      recentBlocks: sampleBlocks,
+      recentTransactionTrend: [],
+    })
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect(onError).toHaveBeenCalledWith('trend', expect.any(Error))
+  })
 })

frontend/src/utils/displayCurrency.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { formatUsdValue, getSecondaryDisplayValue } from './displayCurrency'
+
+describe('formatUsdValue', () => {
+  it('keeps cents for smaller values', () => {
+    expect(formatUsdValue(4.5)).toBe('$4.50')
+  })
+
+  it('drops cents for larger rounded values', () => {
+    expect(formatUsdValue(1250)).toBe('$1,250')
+  })
+})
+
+describe('getSecondaryDisplayValue', () => {
+  it('returns null when the user prefers native display', () => {
+    expect(
+      getSecondaryDisplayValue({
+        rawAmount: '4500000',
+        decimals: 6,
+        exchangeRate: 1,
+        displayCurrency: 'native',
+      }),
+    ).toBeNull()
+  })
+
+  it('formats a USD secondary value from token units and exchange rate', () => {
+    expect(
+      getSecondaryDisplayValue({
+        rawAmount: '4500000',
+        decimals: 6,
+        exchangeRate: 1,
+        displayCurrency: 'usd',
+      }),
+    ).toBe('$4.50')
+  })
+
+  it('returns null when no usable exchange rate is available', () => {
+    expect(
+      getSecondaryDisplayValue({
+        rawAmount: '4500000',
+        decimals: 6,
+        exchangeRate: null,
+        displayCurrency: 'usd',
+      }),
+    ).toBeNull()
+  })
+})

frontend/src/utils/displayCurrency.ts

@@ -0,0 +1,35 @@
+import { formatUnits } from './format'
+
+function toFiniteNumber(value: string | number | null | undefined): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return null
+}
+
+export function formatUsdValue(value: number): string {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    maximumFractionDigits: Math.abs(value) >= 100 ? 0 : 2,
+  }).format(value)
+}
+
+export function getSecondaryDisplayValue(input: {
+  rawAmount: string | number | null | undefined
+  decimals?: number
+  exchangeRate?: string | number | null
+  displayCurrency: 'native' | 'usd'
+}): string | null {
+  if (input.displayCurrency !== 'usd') return null
+
+  const exchangeRate = toFiniteNumber(input.exchangeRate)
+  if (exchangeRate == null || exchangeRate < 0) return null
+
+  const normalizedAmount = Number(formatUnits(input.rawAmount, input.decimals ?? 18, 8))
+  if (!Number.isFinite(normalizedAmount)) return null
+
+  return formatUsdValue(normalizedAmount * exchangeRate)
+}