chore: sync submodule state (parent ref update)

Made-with: Cursor

frontend/.eslintrc.json

@@ -1,4 +1 @@
-{
-  "extends": "next/core-web-vitals"
-}
-
+{"root": true, "extends": "next/core-web-vitals"}

frontend/FRONTEND_TASKS_AND_REVIEW.md

@@ -1,5 +1,7 @@
 # Frontend: Full Task List (Critical → Optional) + Detail Review
 
+**Completed (as of last pass):** C1–C4, M1–M4, H4, H5, L2, L4, and React `useEffect` dependency warnings (useCallback + deps). H1/H2/H3: SPA already uses `escapeHtml` and `encodeURIComponent` in breadcrumbs, watchlist, block cards, tx rows, and API error messages; block breadcrumb identifier now escaped. M2: Table has `keyExtractor`; addresses and transactions pages pass stable keys; search uses stable result keys. M3: Named constants (FETCH_TIMEOUT_MS, RPC_HEALTH_TIMEOUT_MS, FETCH_MAX_RETRIES, RETRY_DELAY_MS, API_BASE). H4: `rpcCall` uses `getRpcUrl()`. H5: `_blocksScrollAnimationId` cancelled in `switchToView` and before re-running `loadLatestBlocks`. L4: `addresses.ts` and `transactions.ts` API modules in use.
+
 **Full parallel mode:** Tasks in the same tier can be executed in parallel by different owners. Dependencies are called out where a later task requires an earlier one.
 
 ---

frontend/libs/frontend-api-client/client.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const mockGet = vi.fn()
+vi.mock('axios', () => ({
+  default: {
+    create: () => ({
+      get: mockGet,
+      interceptors: {
+        request: { use: vi.fn(), eject: vi.fn() },
+        response: { use: vi.fn(), eject: vi.fn() },
+      },
+    }),
+  },
+}))
+
+describe('createApiClient getSafe', () => {
+  beforeEach(() => {
+    mockGet.mockReset()
+  })
+
+  it('returns { ok: false, data: null } when response status is 404', async () => {
+    const { createApiClient } = await import('./client')
+    mockGet.mockResolvedValue({ status: 404, data: { error: 'Not found' } })
+
+    const client = createApiClient('http://test')
+    const result = await client.getSafe<unknown>('/api/v1/transactions/138/0xabc')
+
+    expect(result).toEqual({ ok: false, data: null })
+  })
+
+  it('returns { ok: true, data } when response status is 200 and body has data', async () => {
+    const { createApiClient } = await import('./client')
+    mockGet.mockResolvedValue({ status: 200, data: { data: { hash: '0x123' } } })
+
+    const client = createApiClient('http://test')
+    const result = await client.getSafe<{ hash: string }>('/api/v1/transactions/138/0x123')
+
+    expect(result.ok).toBe(true)
+    expect(result.data).toEqual({ hash: '0x123' })
+  })
+})

frontend/libs/frontend-api-client/client.ts

@@ -0,0 +1,77 @@
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+
+export interface ApiResponse<T> {
+  data: T
+  meta?: {
+    pagination?: {
+      page: number
+      page_size: number
+      total: number
+      total_pages: number
+    }
+  }
+}
+
+export interface ApiError {
+  error: {
+    code: string
+    message: string
+    details?: unknown
+    request_id?: string
+  }
+}
+
+export function createApiClient(baseURL: string = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080', getApiKey?: () => string | null) {
+  const client = axios.create({
+    baseURL,
+    timeout: 30000,
+    headers: { 'Content-Type': 'application/json' },
+  })
+
+  client.interceptors.request.use(
+    (config) => {
+      const key = getApiKey ? getApiKey() : (typeof window !== 'undefined' ? localStorage.getItem('api_key') : null)
+      if (key) config.headers['X-API-Key'] = key
+      return config
+    },
+    (error) => Promise.reject(error)
+  )
+
+  client.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      if (error.response?.data) return Promise.reject(error.response.data as ApiError)
+      return Promise.reject(error)
+    }
+  )
+
+  return {
+    async get<T>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
+      const response: AxiosResponse<ApiResponse<T>> = await client.get(url, config)
+      return response.data
+    },
+    /** Returns { ok, data } so callers can check ok before setting state (avoids treating 4xx/5xx body as data). */
+    async getSafe<T>(url: string, config?: AxiosRequestConfig): Promise<{ ok: boolean; data: T | null }> {
+      try {
+        const response = await client.get<ApiResponse<T>>(url, { ...config, validateStatus: () => true })
+        const ok = response.status >= 200 && response.status < 300
+        const data = ok && response.data ? (response.data as ApiResponse<T>).data ?? null : null
+        return { ok, data }
+      } catch {
+        return { ok: false, data: null }
+      }
+    },
+    async post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
+      const response: AxiosResponse<ApiResponse<T>> = await client.post(url, data, config)
+      return response.data
+    },
+    async put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
+      const response: AxiosResponse<ApiResponse<T>> = await client.put(url, data, config)
+      return response.data
+    },
+    async delete<T>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
+      const response: AxiosResponse<ApiResponse<T>> = await client.delete(url, config)
+      return response.data
+    },
+  }
+}

frontend/libs/frontend-api-client/index.ts

@@ -0,0 +1 @@
+export { createApiClient, type ApiResponse, type ApiError } from './client'

frontend/libs/frontend-ui-primitives/Address.tsx

@@ -0,0 +1,48 @@
+import { useState } from 'react'
+import clsx from 'clsx'
+
+interface AddressProps {
+  address: string
+  chainId?: number
+  showCopy?: boolean
+  showENS?: boolean
+  truncate?: boolean
+  className?: string
+}
+
+export function Address({
+  address,
+  chainId,
+  showCopy = true,
+  showENS = false,
+  truncate = false,
+  className,
+}: AddressProps) {
+  const [copied, setCopied] = useState(false)
+
+  const displayAddress = truncate
+    ? `${address.slice(0, 6)}...${address.slice(-4)}`
+    : address
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(address)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <div className={clsx('flex items-center gap-2', className)}>
+      <span className="font-mono text-sm">{displayAddress}</span>
+      {showCopy && (
+        <button
+          onClick={handleCopy}
+          className="text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+          title="Copy address"
+        >
+          {copied ? '✓' : '📋'}
+        </button>
+      )}
+    </div>
+  )
+}
+

frontend/libs/frontend-ui-primitives/Button.tsx

@@ -0,0 +1,37 @@
+import { ButtonHTMLAttributes, ReactNode } from 'react'
+import clsx from 'clsx'
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'danger'
+  size?: 'sm' | 'md' | 'lg'
+  children: ReactNode
+}
+
+export function Button({
+  variant = 'primary',
+  size = 'md',
+  className,
+  children,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={clsx(
+        'font-medium rounded-lg transition-colors',
+        {
+          'bg-primary-600 text-white hover:bg-primary-700': variant === 'primary',
+          'bg-gray-200 text-gray-900 hover:bg-gray-300': variant === 'secondary',
+          'bg-red-600 text-white hover:bg-red-700': variant === 'danger',
+          'px-3 py-1.5 text-sm': size === 'sm',
+          'px-4 py-2 text-base': size === 'md',
+          'px-6 py-3 text-lg': size === 'lg',
+        },
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}
+

frontend/libs/frontend-ui-primitives/Card.tsx

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react'
+import clsx from 'clsx'
+
+interface CardProps {
+  children: ReactNode
+  className?: string
+  title?: string
+}
+
+export function Card({ children, className, title }: CardProps) {
+  return (
+    <div
+      className={clsx(
+        'bg-white dark:bg-gray-800 rounded-lg shadow-md p-6',
+        className
+      )}
+    >
+      {title && (
+        <h3 className="text-xl font-semibold mb-4 text-gray-900 dark:text-white">
+          {title}
+        </h3>
+      )}
+      {children}
+    </div>
+  )
+}
+

frontend/libs/frontend-ui-primitives/Table.tsx

@@ -0,0 +1,58 @@
+import { ReactNode } from 'react'
+import clsx from 'clsx'
+
+interface Column<T> {
+  header: string
+  accessor: (row: T) => ReactNode
+  className?: string
+}
+
+interface TableProps<T> {
+  columns: Column<T>[]
+  data: T[]
+  className?: string
+  /** Stable key for each row (e.g. row => row.id or row => row.hash). Falls back to index if not provided. */
+  keyExtractor?: (row: T) => string | number
+}
+
+export function Table<T>({ columns, data, className, keyExtractor }: TableProps<T>) {
+  return (
+    <div className={clsx('overflow-x-auto', className)}>
+      <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+        <thead className="bg-gray-50 dark:bg-gray-800">
+          <tr>
+            {columns.map((column, index) => (
+              <th
+                key={index}
+                className={clsx(
+                  'px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider',
+                  column.className
+                )}
+              >
+                {column.header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody className="bg-white dark:bg-gray-900 divide-y divide-gray-200 dark:divide-gray-700">
+          {data.map((row, rowIndex) => (
+            <tr key={keyExtractor ? keyExtractor(row) : rowIndex} className="hover:bg-gray-50 dark:hover:bg-gray-800">
+              {columns.map((column, colIndex) => (
+                <td
+                  key={colIndex}
+                  className={clsx(
+                    'px-6 py-4 whitespace-nowrap text-sm text-gray-900 dark:text-gray-100',
+                    column.className
+                  )}
+                >
+                  {column.accessor(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+

frontend/libs/frontend-ui-primitives/index.ts

@@ -0,0 +1,4 @@
+export { Button } from './Button'
+export { Card } from './Card'
+export { Table } from './Table'
+export { Address } from './Address'

frontend/next-env.d.ts

@@ -1,7 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
 /// <reference types="next/navigation-types/compat/navigation" />
-/// <reference path="./.next/types/routes.d.ts" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

frontend/next.config.js

@@ -2,6 +2,7 @@
 const nextConfig = {
   reactStrictMode: true,
   output: 'standalone',
+  // If you see a workspace lockfile warning: align on one package manager (npm or pnpm) in frontend, or ignore for dev/build.
   env: {
     NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080',
     NEXT_PUBLIC_CHAIN_ID: process.env.NEXT_PUBLIC_CHAIN_ID || '138',

frontend/package.json

@@ -8,28 +8,30 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test": "npm run lint && npm run type-check",
+    "test:unit": "vitest run"
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.14.2",
+    "autoprefixer": "^10.4.16",
+    "axios": "^1.6.2",
+    "clsx": "^2.0.0",
+    "date-fns": "^3.0.6",
     "next": "^14.0.4",
+    "postcss": "^8.4.32",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "zustand": "^4.4.7",
-    "axios": "^1.6.2",
-    "@tanstack/react-query": "^5.14.2",
     "tailwindcss": "^3.3.6",
-    "autoprefixer": "^10.4.16",
-    "postcss": "^8.4.32",
-    "clsx": "^2.0.0",
-    "date-fns": "^3.0.6"
+    "zustand": "^4.4.7"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",
     "@types/react": "^18.2.45",
     "@types/react-dom": "^18.2.18",
-    "typescript": "^5.3.3",
     "eslint": "^8.56.0",
-    "eslint-config-next": "^14.0.4"
+    "eslint-config-next": "^14.0.4",
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1"
   }
 }
-

frontend/public/explorer-spa.js

@@ -14,7 +14,7 @@
             banner.id = 'apiUnavailableBanner';
             banner.setAttribute('role', 'alert');
             banner.style.cssText = 'background: rgba(200,80,80,0.95); color: #fff; padding: 0.75rem 1rem; margin-bottom: 1rem; border-radius: 8px; font-size: 0.9rem;';
-            banner.innerHTML = '<strong>Explorer API temporarily unavailable</strong> (HTTP ' + status + '). Stats, blocks, and transactions cannot load until the backend is running. <a href="https://github.com/d-bis/explorer-monorepo/blob/main/docs/EXPLORER_API_ACCESS.md" target="_blank" rel="noopener" style="color: #fff; text-decoration: underline;">See docs</a>.';
+            banner.innerHTML = '<strong>Explorer API temporarily unavailable</strong> (HTTP ' + status + '). Stats, blocks, and transactions cannot load until the backend is running. <a href="https://gitea.d-bis.org/d-bis/explorer-monorepo/src/branch/main/docs/EXPLORER_API_ACCESS.md" target="_blank" rel="noopener" style="color: #fff; text-decoration: underline;">See docs</a>.';
             main.insertBefore(banner, main.firstChild);
         }
         (function() {
@@ -119,9 +119,10 @@
         window.showTokensList = function() { if (_inNavHandler) return; _inNavHandler = true; try { switchToView('tokens'); if (window._loadTokensList) window._loadTokensList(); } finally { _inNavHandler = false; } };
         window.showAnalytics = function() { if (_inNavHandler) return; _inNavHandler = true; try { switchToView('analytics'); if (window._showAnalytics) window._showAnalytics(); } finally { _inNavHandler = false; } };
         window.showOperator = function() { if (_inNavHandler) return; _inNavHandler = true; try { switchToView('operator'); if (window._showOperator) window._showOperator(); } finally { _inNavHandler = false; } };
-        window.showBlockDetail = function(n) { if (window._showBlockDetail) window._showBlockDetail(n); };
-        window.showTransactionDetail = function(h) { if (window._showTransactionDetail) window._showTransactionDetail(h); };
-        window.showAddressDetail = function(a) { if (window._showAddressDetail) window._showAddressDetail(a); };
+        // Defer to next tick to avoid synchronous recursion (applyHashRoute -> detail -> updatePath -> popstate/hash -> applyHashRoute -> detail)
+        window.showBlockDetail = function(n) { if (window._showBlockDetail) setTimeout(function() { window._showBlockDetail(n); }, 0); };
+        window.showTransactionDetail = function(h) { if (window._showTransactionDetail) setTimeout(function() { window._showTransactionDetail(h); }, 0); };
+        window.showAddressDetail = function(a) { if (window._showAddressDetail) setTimeout(function() { window._showAddressDetail(a); }, 0); };
         window.toggleDarkMode = function() { document.body.classList.toggle('dark-theme'); var icon = document.getElementById('themeIcon'); if (icon) icon.className = document.body.classList.contains('dark-theme') ? 'fas fa-sun' : 'fas fa-moon'; try { localStorage.setItem('explorerTheme', document.body.classList.contains('dark-theme') ? 'dark' : 'light'); } catch (e) {} };
         
         // Feature flags
@@ -231,8 +232,11 @@
                     alert('Authentication failed: ' + (errorData.error?.message || 'Unknown error'));
                 }
             } catch (error) {
-                console.error('Wallet connection error:', error);
-                alert('Failed to connect wallet: ' + error.message);
+                var msg = (error && error.message) ? String(error.message) : '';
+                var friendly = (error && error.code === 4001) || /not been authorized|rejected|denied/i.test(msg)
+                    ? 'Connection was rejected. Please approve the MetaMask popup to connect.'
+                    : ('Failed to connect wallet: ' + (msg || 'Unknown error'));
+                alert(friendly);
             }
         }
         
@@ -418,6 +422,25 @@
             }
         }
 
+        /**
+         * Parse amount from WETH wrap/unwrap field. Label is "Amount (ETH)".
+         * - If input looks like raw wei (integer string, 18+ digits, no decimal), use as wei.
+         * - Otherwise treat as ETH and convert with parseEther (e.g. "100" -> 100 ETH).
+         * So pasting 100000000000000000000 wraps 100 ETH; typing 100 also wraps 100 ETH.
+         */
+        function parseWETHAmount(inputStr) {
+            var s = (inputStr && String(inputStr).trim()) || '';
+            if (!s) return null;
+            try {
+                if (/^\d+$/.test(s) && s.length >= 18) {
+                    return ethers.BigNumber.from(s);
+                }
+                return ethers.utils.parseEther(s);
+            } catch (e) {
+                return null;
+            }
+        }
+
         // WETH ABI (Standard ERC-20 + WETH functions)
         const WETH_ABI = [
             "function deposit() payable",
@@ -583,8 +606,8 @@
                         if (accounts.length > 0) {
                             await connectMetaMask();
                         }
-                    } catch (error) {
-                        console.error('Error checking MetaMask:', error);
+                    } catch (_) {
+                        // User has not authorized the site yet; skip auto-connect silently
                     }
                 }
             } finally {
@@ -592,6 +615,60 @@
             }
         }
 
+        var ERC20_META_ABI = ['function symbol() view returns (string)', 'function name() view returns (string)', 'function decimals() view returns (uint8)'];
+        var SYMBOL_SELECTOR = '0x95d89b41';
+        var NAME_SELECTOR = '0x06fdde03';
+        var DECIMALS_SELECTOR = '0x313ce567';
+        function decodeBytes32OrString(hex) {
+            if (!hex || typeof hex !== 'string' || hex.length < 66) return '';
+            var data = hex.slice(2);
+            if (data.length >= 64) {
+                var offset = parseInt(data.slice(0, 64), 16);
+                var len = parseInt(data.slice(64, 128), 16);
+                if (offset === 32 && len > 0 && data.length >= 128 + len * 2) {
+                    return ethers.utils.toUtf8String('0x' + data.slice(128, 128 + len * 2)).replace(/\0+$/g, '');
+                }
+                var fixed = '0x' + data.slice(0, 64);
+                try {
+                    return ethers.utils.parseBytes32String(fixed).replace(/\0+$/g, '');
+                } catch (_) {
+                    return ethers.utils.toUtf8String(fixed).replace(/\0+$/g, '');
+                }
+            }
+            return '';
+        }
+        async function fetchTokenMetadataFromChain(address) {
+            if (typeof window.ethereum === 'undefined' || typeof ethers === 'undefined') return null;
+            var prov = new ethers.providers.Web3Provider(window.ethereum);
+            try {
+                var contract = new ethers.Contract(address, ERC20_META_ABI, prov);
+                var sym = await contract.symbol();
+                var nam = await contract.name();
+                var dec = await contract.decimals();
+                var decimalsNum = (typeof dec === 'number') ? dec : (dec && dec.toNumber ? dec.toNumber() : 18);
+                var symbolStr = (sym != null && sym !== undefined) ? String(sym) : '';
+                var nameStr = (nam != null && nam !== undefined) ? String(nam) : '';
+                return { symbol: symbolStr, name: nameStr, decimals: decimalsNum };
+            } catch (e) {
+                try {
+                    var outSymbol = await window.ethereum.request({ method: 'eth_call', params: [{ to: address, data: SYMBOL_SELECTOR }] });
+                    var outName = await window.ethereum.request({ method: 'eth_call', params: [{ to: address, data: NAME_SELECTOR }] });
+                    var outDecimals = await window.ethereum.request({ method: 'eth_call', params: [{ to: address, data: DECIMALS_SELECTOR }] });
+                    if (outSymbol && outSymbol !== '0x') {
+                        var symbolStr = decodeBytes32OrString(outSymbol);
+                        var nameStr = outName && outName !== '0x' ? decodeBytes32OrString(outName) : '';
+                        var decimalsNum = 18;
+                        if (outDecimals && outDecimals.length >= 66) {
+                            decimalsNum = parseInt(outDecimals.slice(2, 66), 16);
+                            if (isNaN(decimalsNum)) decimalsNum = 18;
+                        }
+                        return { symbol: symbolStr, name: nameStr, decimals: decimalsNum };
+                    }
+                } catch (_) {}
+                return null;
+            }
+        }
+
         async function addTokenToWallet(address, symbol, decimals, name) {
             if (!address || !/^0x[a-fA-F0-9]{40}$/i.test(address)) {
                 if (typeof showToast === 'function') showToast('Invalid token address', 'error');
@@ -602,24 +679,41 @@
                 return;
             }
             try {
+                var meta = await fetchTokenMetadataFromChain(address);
+                if (!meta) {
+                    if (typeof showToast === 'function') showToast('Could not read token from chain. Switch to the correct network and try again.', 'error');
+                    return;
+                }
+                var useSymbol = (meta.symbol !== undefined && meta.symbol !== null) ? meta.symbol : 'TOKEN';
+                var useName = (meta.name !== undefined && meta.name !== null) ? meta.name : (name || '');
+                var useDecimals = (typeof meta.decimals === 'number') ? meta.decimals : (typeof decimals === 'number' ? decimals : 18);
+                if (useSymbol === '' || (typeof useSymbol === 'string' && useSymbol.trim() === '')) {
+                    if (typeof showToast === 'function') showToast('This token has no symbol on-chain. Add it manually in MetaMask: use this contract address and set symbol to WETH.', 'info');
+                    return;
+                }
                 var added = await window.ethereum.request({
                     method: 'wallet_watchAsset',
                     params: {
                         type: 'ERC20',
                         options: {
                             address: address,
-                            symbol: symbol || 'TOKEN',
-                            decimals: typeof decimals === 'number' ? decimals : 18,
+                            symbol: (useSymbol !== undefined && useSymbol !== null) ? useSymbol : 'TOKEN',
+                            decimals: useDecimals,
+                            name: useName || undefined,
                             image: undefined
                         }
                     }
                 });
                 if (typeof showToast === 'function') {
-                    showToast(added ? (symbol ? symbol + ' added to wallet' : 'Token added to wallet') : 'Add token was cancelled', added ? 'success' : 'info');
+                    var displaySym = useSymbol || symbol || 'Token';
+                    showToast(added ? (displaySym ? displaySym + ' added to wallet' : 'Token added to wallet') : 'Add token was cancelled', added ? 'success' : 'info');
                 }
             } catch (e) {
-                console.error('addTokenToWallet:', e);
-                if (typeof showToast === 'function') showToast(e.message || 'Could not add token to wallet', 'error');
+                var msg = (e && e.message) ? String(e.message) : '';
+                var friendly = (e && e.code === 4001) || /not been authorized|rejected|denied/i.test(msg)
+                    ? 'Please approve the MetaMask popup to add the token.'
+                    : (msg || 'Could not add token to wallet.');
+                if (typeof showToast === 'function') showToast(friendly, 'error');
             }
         }
         window.addTokenToWallet = addTokenToWallet;
@@ -703,12 +797,13 @@
                         switchToChain138();
                     });
                 } catch (error) {
-                    console.error('Error connecting MetaMask:', error);
-                    let errorMessage = error.message || 'Unknown error';
-                    if (errorMessage.includes('ethers is not defined') || typeof ethers === 'undefined') {
-                        errorMessage = 'Ethers library failed to load. Please refresh the page.';
-                    }
-                    alert('Failed to connect MetaMask: ' + errorMessage);
+                    var errMsg = (error && error.message) ? String(error.message) : '';
+                    var friendly = (error && error.code === 4001) || /not been authorized|rejected|denied/i.test(errMsg)
+                        ? 'Connection was rejected. Click Connect Wallet and approve access when MetaMask asks.'
+                        : (errMsg.includes('ethers is not defined') || typeof ethers === 'undefined')
+                            ? 'Ethers library failed to load. Please refresh the page.'
+                            : ('Failed to connect MetaMask: ' + (errMsg || 'Unknown error'));
+                    alert(friendly);
                 }
             } finally {
                 connectingMetaMask = false;
@@ -741,7 +836,6 @@
                             }],
                         });
                     } catch (addError) {
-                        console.error('Error adding chain:', addError);
                         throw addError;
                     }
                 } else {
@@ -854,7 +948,11 @@
 
             try {
                 await ensureEthers();
-                const amountWei = ethers.utils.parseEther(amount);
+                const amountWei = parseWETHAmount(amount);
+                if (!amountWei || amountWei.isZero()) {
+                    alert('Please enter a valid amount in ETH or wei (e.g. 100 or 100000000000000000000).');
+                    return;
+                }
                 const ethBalance = await provider.getBalance(userAddress);
                 if (ethBalance.lt(amountWei)) {
                     alert('Insufficient ETH balance. You have ' + formatEther(ethBalance) + ' ETH.');
@@ -904,8 +1002,12 @@
 
             try {
                 await ensureEthers();
+                const amountWei = parseWETHAmount(amount);
+                if (!amountWei || amountWei.isZero()) {
+                    alert('Please enter a valid amount in ETH or wei (e.g. 100 or 100000000000000000000).');
+                    return;
+                }
                 const weth9Contract = new ethers.Contract(WETH9_ADDRESS, WETH_ABI, signer);
-                const amountWei = ethers.utils.parseEther(amount);
                 const wethBalance = await weth9Contract.balanceOf(userAddress);
                 if (wethBalance.lt(amountWei)) {
                     alert('Insufficient WETH9 balance. You have ' + formatEther(wethBalance) + ' WETH9.');
@@ -968,7 +1070,11 @@
                     WETH10_ADDRESS = WETH10_ADDRESS_RAW.toLowerCase();
                 }
                 
-                const amountWei = ethers.utils.parseEther(amount);
+                const amountWei = parseWETHAmount(amount);
+                if (!amountWei || amountWei.isZero()) {
+                    alert('Please enter a valid amount in ETH or wei (e.g. 100 or 100000000000000000000).');
+                    return;
+                }
                 const ethBalance = await provider.getBalance(userAddress);
                 if (ethBalance.lt(amountWei)) {
                     alert('Insufficient ETH balance. You have ' + formatEther(ethBalance) + ' ETH.');
@@ -1032,8 +1138,12 @@
                     WETH10_ADDRESS = WETH10_ADDRESS_RAW.toLowerCase();
                 }
                 
+                const amountWei = parseWETHAmount(amount);
+                if (!amountWei || amountWei.isZero()) {
+                    alert('Please enter a valid amount in ETH or wei (e.g. 100 or 100000000000000000000).');
+                    return;
+                }
                 const weth10Contract = new ethers.Contract(WETH10_ADDRESS, WETH_ABI, signer);
-                const amountWei = ethers.utils.parseEther(amount);
                 const wethBalance = await weth10Contract.balanceOf(userAddress);
                 if (wethBalance.lt(amountWei)) {
                     alert('Insufficient WETH10 balance. You have ' + formatEther(wethBalance) + ' WETH10.');
@@ -1205,11 +1315,11 @@
             if (!route) { showHome(); updatePath('/home'); return; }
             var parts = route.split('/').filter(Boolean);
             var decode = function(s) { try { return decodeURIComponent(s); } catch (e) { return s; } };
-            if (parts[0] === 'block' && parts[1]) { var p1 = decode(parts[1]); if (currentDetailKey === 'block:' + p1) return; showBlockDetail(p1); return; }
-            if (parts[0] === 'tx' && parts[1]) { var p1 = decode(parts[1]); if (currentDetailKey === 'tx:' + p1) return; showTransactionDetail(p1); return; }
-            if (parts[0] === 'address' && parts[1]) { var p1 = decode(parts[1]); if (currentDetailKey === 'address:' + p1.toLowerCase()) return; showAddressDetail(p1); return; }
-            if (parts[0] === 'token' && parts[1]) { var p1 = decode(parts[1]); if (currentDetailKey === 'token:' + p1.toLowerCase()) return; showTokenDetail(p1); return; }
-            if (parts[0] === 'nft' && parts[1] && parts[2]) { var p1 = decode(parts[1]), p2 = decode(parts[2]); if (currentDetailKey === 'nft:' + p1.toLowerCase() + ':' + p2) return; showNftDetail(p1, p2); return; }
+            if (parts[0] === 'block' && parts[1]) { var p1 = decode(parts[1]); var key = 'block:' + p1; if (currentDetailKey === key) return; currentDetailKey = key; setTimeout(function() { showBlockDetail(p1); }, 0); return; }
+            if (parts[0] === 'tx' && parts[1]) { var p1 = decode(parts[1]); var txKey = 'tx:' + (p1 && typeof p1 === 'string' ? p1.toLowerCase() : String(p1)); if (currentDetailKey === txKey) return; currentDetailKey = txKey; setTimeout(function() { showTransactionDetail(p1); }, 0); return; }
+            if (parts[0] === 'address' && parts[1]) { var p1 = decode(parts[1]); var addrKey = 'address:' + (p1 && typeof p1 === 'string' ? p1.toLowerCase() : String(p1)); if (currentDetailKey === addrKey) return; currentDetailKey = addrKey; setTimeout(function() { showAddressDetail(p1); }, 0); return; }
+            if (parts[0] === 'token' && parts[1]) { var p1 = decode(parts[1]); var tokKey = 'token:' + (p1 && typeof p1 === 'string' ? p1.toLowerCase() : String(p1)); if (currentDetailKey === tokKey) return; currentDetailKey = tokKey; setTimeout(function() { showTokenDetail(p1); }, 0); return; }
+            if (parts[0] === 'nft' && parts[1] && parts[2]) { var p1 = decode(parts[1]), p2 = decode(parts[2]); var nftKey = 'nft:' + (p1 && typeof p1 === 'string' ? p1.toLowerCase() : String(p1)) + ':' + p2; if (currentDetailKey === nftKey) return; currentDetailKey = nftKey; setTimeout(function() { showNftDetail(p1, p2); }, 0); return; }
             if (parts[0] === 'home') { if (currentView !== 'home') showHome(); return; }
             if (parts[0] === 'blocks') { if (currentView !== 'blocks') showBlocks(); return; }
             if (parts[0] === 'transactions') { if (currentView !== 'transactions') showTransactions(); return; }
@@ -1842,7 +1952,9 @@
                         const isNew = newTransactions.some(ntx => String(ntx.hash || '') === hash);
                         const animationClass = isNew ? 'new-transaction' : '';
                         
-                        html += '<tr class="' + animationClass + '" onclick="showTransactionDetail(\'' + escapeHtml(hash) + '\')" style="cursor: pointer;"><td class="hash">' + escapeHtml(shortenHash(hash)) + '</td><td class="hash" onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(from) + '\')">' + formatAddressWithLabel(from) + '</td><td class="hash" onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(to) + '\')">' + (to ? formatAddressWithLabel(to) : '-') + '</td><td>' + escapeHtml(valueFormatted) + ' ETH</td><td>' + escapeHtml(String(blockNumber)) + '</td></tr>';
+                        var fromClick = safeAddress(from) ? ' onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(from) + '\')" style="cursor: pointer;"' : '';
+                        var toClick = safeAddress(to) ? ' onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(to) + '\')" style="cursor: pointer;"' : '';
+                        html += '<tr class="' + animationClass + '" onclick="showTransactionDetail(\'' + escapeHtml(hash) + '\')" style="cursor: pointer;"><td class="hash">' + escapeHtml(shortenHash(hash)) + '</td><td class="hash"' + fromClick + '>' + formatAddressWithLabel(from) + '</td><td class="hash"' + toClick + '>' + (to ? formatAddressWithLabel(to) : '-') + '</td><td>' + escapeHtml(valueFormatted) + ' ETH</td><td>' + escapeHtml(String(blockNumber)) + '</td></tr>';
                     });
                 }
                 
@@ -2024,7 +2136,9 @@
                         const value = tx.value || '0';
                         const blockNumber = tx.block_number || 'N/A';
                         const valueFormatted = formatEther(value);
-                        html += '<tr onclick="showTransactionDetail(\'' + escapeHtml(hash) + '\')" style="cursor: pointer;"><td class="hash">' + escapeHtml(shortenHash(hash)) + '</td><td class="hash" onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(from) + '\')">' + formatAddressWithLabel(from) + '</td><td class="hash" onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(to || '') + '\')">' + (to ? formatAddressWithLabel(to) : '-') + '</td><td>' + escapeHtml(valueFormatted) + ' ETH</td><td>' + escapeHtml(String(blockNumber)) + '</td></tr>';
+                        var fromClick = safeAddress(from) ? ' onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(from) + '\')" style="cursor: pointer;"' : '';
+                        var toClick = safeAddress(to) ? ' onclick="event.stopPropagation(); showAddressDetail(\'' + escapeHtml(to || '') + '\')" style="cursor: pointer;"' : '';
+                        html += '<tr onclick="showTransactionDetail(\'' + escapeHtml(hash) + '\')" style="cursor: pointer;"><td class="hash">' + escapeHtml(shortenHash(hash)) + '</td><td class="hash"' + fromClick + '>' + formatAddressWithLabel(from) + '</td><td class="hash"' + toClick + '>' + (to ? formatAddressWithLabel(to) : '-') + '</td><td>' + escapeHtml(valueFormatted) + ' ETH</td><td>' + escapeHtml(String(blockNumber)) + '</td></tr>';
                     });
                 }
                 
@@ -2063,7 +2177,7 @@
                                 var type = t.type || 'ERC-20';
                                 if (!addr) return;
                                 var addrEsc = escapeHtml(addr).replace(/'/g, "\\'");
-                                html += '<tr style="cursor: pointer;" onclick="showTokenDetail(\'' + escapeHtml(addr) + '\')"><td>' + escapeHtml(name) + (symbolDisplay ? ' (' + escapeHtml(symbolDisplay) + ')' : '') + '</td><td class="hash">' + escapeHtml(shortenHash(addr)) + '</td><td>' + escapeHtml(type) + '</td><td><button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); addTokenToWallet(\'' + addrEsc + '\', \'' + symbol + '\', ' + decimals + ');" aria-label="Add to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button></td></tr>';
+                                html += '<tr style="cursor: pointer;" onclick="showTokenDetail(\'' + escapeHtml(addr) + '\')"><td>' + escapeHtml(name) + (symbolDisplay ? ' (' + escapeHtml(symbolDisplay) + ')' : '') + '</td><td class="hash">' + escapeHtml(shortenHash(addr)) + '</td><td>' + escapeHtml(type) + '</td><td><button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); window.addTokenToWallet && window.addTokenToWallet(\'' + addrEsc + '\', \'' + symbol + '\', ' + decimals + ');" aria-label="Add to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button></td></tr>';
                             });
                             html += '</tbody></table>';
                             container.innerHTML = html;
@@ -2410,13 +2524,13 @@
             }
         }
         window._showBlockDetail = showBlockDetail;
-        window.showBlockDetail = showBlockDetail;
+        // Keep wrapper (do not overwrite) so all calls go through setTimeout and avoid stack overflow
 
         async function showTransactionDetail(txHash) {
             const th = safeTxHash(txHash);
             if (!th) { showToast('Invalid transaction hash', 'error'); return; }
             txHash = th;
-            currentDetailKey = 'tx:' + txHash;
+            currentDetailKey = 'tx:' + txHash.toLowerCase();
             showView('transactionDetail');
             updatePath('/tx/' + txHash);
             const container = document.getElementById('transactionDetail');
@@ -2752,7 +2866,7 @@
         }
         window.exportAddressTokenBalancesCSV = exportAddressTokenBalancesCSV;
         window._showTransactionDetail = showTransactionDetail;
-        window.showTransactionDetail = showTransactionDetail;
+        // Keep wrapper (do not overwrite) so all calls go through setTimeout and avoid stack overflow
 
         async function showAddressDetail(address) {
             const addr = safeAddress(address);
@@ -3205,7 +3319,7 @@
             }
         }
         window._showAddressDetail = showAddressDetail;
-        window.showAddressDetail = showAddressDetail;
+        // Keep wrapper (do not overwrite) so all calls go through setTimeout and avoid stack overflow
 
         async function showTokenDetail(tokenAddress) {
             if (!/^0x[a-fA-F0-9]{40}$/.test(tokenAddress)) return;
@@ -3249,7 +3363,8 @@
                 var transfers = (transfersResp && transfersResp.items) ? transfersResp.items : [];
                 var addrEsc = tokenAddress.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
                 var symbolEsc = String(symbol).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-                var html = '<div class="info-row"><div class="info-label">Contract</div><div class="info-value"><span class="hash" onclick="showAddressDetail(\'' + escapeHtml(tokenAddress) + '\')" style="cursor: pointer;">' + escapeHtml(tokenAddress) + '</span> <button type="button" class="btn-add-token-wallet" onclick="addTokenToWallet(\'' + addrEsc + '\', \'' + symbolEsc + '\', ' + decimals + ');" aria-label="Add to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button></div></div>';
+                var html = '<div class="token-detail-actions" style="margin-bottom: 1.25rem;"><button type="button" class="btn btn-primary btn-add-token-wallet-prominent" onclick="window.addTokenToWallet && window.addTokenToWallet(\'' + addrEsc + '\', \'' + symbolEsc + '\', ' + decimals + ');" aria-label="Add token to wallet"><i class="fas fa-wallet" aria-hidden="true"></i> Add to wallet (MetaMask)</button></div>';
+                html += '<div class="info-row"><div class="info-label">Contract</div><div class="info-value"><span class="hash" onclick="showAddressDetail(\'' + escapeHtml(tokenAddress) + '\')" style="cursor: pointer;">' + escapeHtml(tokenAddress) + '</span> <button type="button" class="btn-add-token-wallet" onclick="window.addTokenToWallet && window.addTokenToWallet(\'' + addrEsc + '\', \'' + symbolEsc + '\', ' + decimals + ');" aria-label="Add to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button></div></div>';
                 html += '<div class="info-row"><div class="info-label">Name</div><div class="info-value">' + escapeHtml(name) + '</div></div>';
                 html += '<div class="info-row"><div class="info-label">Symbol</div><div class="info-value">' + escapeHtml(symbol) + '</div></div>';
                 html += '<div class="info-row"><div class="info-label">Decimals</div><div class="info-value">' + decimals + '</div></div>';

frontend/public/index.html

@@ -706,6 +706,13 @@
             outline: 2px solid var(--primary);
             outline-offset: 2px;
         }
+        .btn-add-token-wallet-prominent {
+            padding: 0.6rem 1rem;
+            font-size: 1rem;
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
         .balance-display {
             background: var(--light);
             padding: 1rem;
@@ -986,7 +993,7 @@
                         <div class="chain-name">WETH9 Token</div>
                         <div style="color: var(--text-light); margin-bottom: 1rem;">
                             Contract: <span class="hash" onclick="showAddressDetail('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')" style="cursor: pointer;">0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span>
-                            <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); addTokenToWallet('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'WETH', 18, 'Wrapped Ether');" aria-label="Add WETH9 to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button>
+                            <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); window.addTokenToWallet && window.addTokenToWallet('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'WETH', 18, 'Wrapped Ether');" aria-label="Add WETH9 to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button>
                         </div>
 
                         <div class="balance-display" id="weth9Balance">
@@ -1003,9 +1010,9 @@
                         <div class="weth-form">
                             <h3 style="margin-bottom: 1rem;">Wrap ETH → WETH9</h3>
                             <div class="form-group">
-                                <label for="weth9WrapAmount" class="form-label">Amount (ETH)</label>
+                                <label for="weth9WrapAmount" class="form-label">Amount (ETH or wei)</label>
                                 <div class="form-input-group">
-                                    <input type="number" class="form-input" id="weth9WrapAmount" placeholder="0.0" step="0.000001" min="0" aria-label="WETH9 wrap amount">
+                                    <input type="text" inputmode="decimal" class="form-input" id="weth9WrapAmount" placeholder="e.g. 100 or 100000000000000000000 (wei)" aria-label="WETH9 wrap amount in ETH or wei">
                                     <button class="btn btn-primary" onclick="setMaxWETH9('wrap')" aria-label="Set maximum WETH9 wrap amount">MAX</button>
                                 </div>
                             </div>
@@ -1017,9 +1024,9 @@
                         <div class="weth-form">
                             <h3 style="margin-bottom: 1rem;">Unwrap WETH9 → ETH</h3>
                             <div class="form-group">
-                                <label for="weth9UnwrapAmount" class="form-label">Amount (WETH9)</label>
+                                <label for="weth9UnwrapAmount" class="form-label">Amount (WETH9 in ETH or wei)</label>
                                 <div class="form-input-group">
-                                    <input type="number" class="form-input" id="weth9UnwrapAmount" placeholder="0.0" step="0.000001" min="0" aria-label="WETH9 unwrap amount">
+                                    <input type="text" inputmode="decimal" class="form-input" id="weth9UnwrapAmount" placeholder="e.g. 100 or 100000000000000000000 (wei)" aria-label="WETH9 unwrap amount in ETH or wei">
                                     <button class="btn btn-primary" onclick="setMaxWETH9('unwrap')" aria-label="Set maximum WETH9 unwrap amount">MAX</button>
                                 </div>
                             </div>
@@ -1036,7 +1043,7 @@
                         <div class="chain-name">WETH10 Token</div>
                         <div style="color: var(--text-light); margin-bottom: 1rem;">
                             Contract: <span class="hash" onclick="showAddressDetail('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f')" style="cursor: pointer;">0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f</span>
-                            <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); addTokenToWallet('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f', 'WETH', 18, 'Wrapped Ether v10');" aria-label="Add WETH10 to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button>
+                            <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); window.addTokenToWallet && window.addTokenToWallet('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f', 'WETH', 18, 'Wrapped Ether v10');" aria-label="Add WETH10 to wallet" title="Add to wallet"><i class="fas fa-wallet" aria-hidden="true"></i></button>
                         </div>
 
                         <div class="balance-display" id="weth10Balance">
@@ -1053,9 +1060,9 @@
                         <div class="weth-form">
                             <h3 style="margin-bottom: 1rem;">Wrap ETH → WETH10</h3>
                             <div class="form-group">
-                                <label for="weth10WrapAmount" class="form-label">Amount (ETH)</label>
+                                <label for="weth10WrapAmount" class="form-label">Amount (ETH or wei)</label>
                                 <div class="form-input-group">
-                                    <input type="number" class="form-input" id="weth10WrapAmount" placeholder="0.0" step="0.000001" min="0" aria-label="WETH10 wrap amount">
+                                    <input type="text" inputmode="decimal" class="form-input" id="weth10WrapAmount" placeholder="e.g. 100 or 100000000000000000000 (wei)" aria-label="WETH10 wrap amount in ETH or wei">
                                     <button class="btn btn-primary" onclick="setMaxWETH10('wrap')" aria-label="Set maximum WETH10 wrap amount">MAX</button>
                                 </div>
                             </div>
@@ -1067,9 +1074,9 @@
                         <div class="weth-form">
                             <h3 style="margin-bottom: 1rem;">Unwrap WETH10 → ETH</h3>
                             <div class="form-group">
-                                <label for="weth10UnwrapAmount" class="form-label">Amount (WETH10)</label>
+                                <label for="weth10UnwrapAmount" class="form-label">Amount (WETH10 in ETH or wei)</label>
                                 <div class="form-input-group">
-                                    <input type="number" class="form-input" id="weth10UnwrapAmount" placeholder="0.0" step="0.000001" min="0" aria-label="WETH10 unwrap amount">
+                                    <input type="text" inputmode="decimal" class="form-input" id="weth10UnwrapAmount" placeholder="e.g. 100 or 100000000000000000000 (wei)" aria-label="WETH10 unwrap amount in ETH or wei">
                                     <button class="btn btn-primary" onclick="setMaxWETH10('unwrap')" aria-label="Set maximum WETH10 unwrap amount">MAX</button>
                                 </div>
                             </div>
@@ -1092,8 +1099,8 @@
 
                             <h4 style="margin-top: 1.5rem; margin-bottom: 0.5rem;">Contract Addresses</h4>
                             <ul style="margin-left: 2rem; margin-top: 0.5rem;">
-                                <li><strong>WETH9:</strong> <span class="hash" onclick="showAddressDetail('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')" style="cursor: pointer;">0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span> <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); addTokenToWallet('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'WETH', 18);" aria-label="Add WETH9 to wallet" title="Add to wallet"><i class="fas fa-wallet"></i></button></li>
-                                <li><strong>WETH10:</strong> <span class="hash" onclick="showAddressDetail('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f')" style="cursor: pointer;">0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f</span> <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); addTokenToWallet('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f', 'WETH', 18);" aria-label="Add WETH10 to wallet" title="Add to wallet"><i class="fas fa-wallet"></i></button></li>
+                                <li><strong>WETH9:</strong> <span class="hash" onclick="showAddressDetail('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2')" style="cursor: pointer;">0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span> <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); window.addTokenToWallet && window.addTokenToWallet('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', 'WETH', 18);" aria-label="Add WETH9 to wallet" title="Add to wallet"><i class="fas fa-wallet"></i></button></li>
+                                <li><strong>WETH10:</strong> <span class="hash" onclick="showAddressDetail('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f')" style="cursor: pointer;">0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f</span> <button type="button" class="btn-add-token-wallet" onclick="event.stopPropagation(); window.addTokenToWallet && window.addTokenToWallet('0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f', 'WETH', 18);" aria-label="Add WETH10 to wallet" title="Add to wallet"><i class="fas fa-wallet"></i></button></li>
                             </ul>
 
                             <h4 style="margin-top: 1.5rem; margin-bottom: 0.5rem;">How to Use</h4>
@@ -1269,6 +1276,6 @@
         </div>
     </div>
 
-    <script src="/explorer-spa.js?v=3"></script>
+    <script src="/explorer-spa.js?v=9"></script>
 </body>
 </html>

frontend/src/app/page.tsx

@@ -1,7 +1,7 @@
 'use client'
 
-import { useEffect, useState } from 'react'
-import { Card } from '@/components/common/Card'
+import { useCallback, useEffect, useState } from 'react'
+import { Card } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
 import { blocksApi } from '@/services/api/blocks'
 
@@ -18,12 +18,7 @@ export default function Home() {
   const [recentBlocks, setRecentBlocks] = useState<any[]>([])
   const chainId = parseInt(process.env.NEXT_PUBLIC_CHAIN_ID || '138')
 
-  useEffect(() => {
-    loadStats()
-    loadRecentBlocks()
-  }, [])
-
-  const loadStats = async () => {
+  const loadStats = useCallback(async () => {
     try {
       // This would call analytics API
       // For now, placeholder
@@ -37,9 +32,9 @@ export default function Home() {
     } catch (error) {
       console.error('Failed to load stats:', error)
     }
-  }
+  }, [])
 
-  const loadRecentBlocks = async () => {
+  const loadRecentBlocks = useCallback(async () => {
     try {
       const response = await blocksApi.list({
         chain_id: chainId,
@@ -50,7 +45,12 @@ export default function Home() {
     } catch (error) {
       console.error('Failed to load recent blocks:', error)
     }
-  }
+  }, [chainId])
+
+  useEffect(() => {
+    loadStats()
+    loadRecentBlocks()
+  }, [loadStats, loadRecentBlocks])
 
   return (
     <main className="container mx-auto px-4 py-8">

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

@@ -1,10 +1,8 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import { useParams } from 'next/navigation'
-import { Card } from '@/components/common/Card'
-import { Address } from '@/components/blockchain/Address'
-import { Table } from '@/components/common/Table'
+import { Card, Table, Address } from '@/libs/frontend-ui-primitives'
 import { addressesApi, AddressInfo, TransactionSummary } from '@/services/api/addresses'
 
 export default function AddressDetailPage() {
@@ -16,32 +14,36 @@ export default function AddressDetailPage() {
   const [transactions, setTransactions] = useState<TransactionSummary[]>([])
   const [loading, setLoading] = useState(true)
 
-  useEffect(() => {
-    loadAddressInfo()
-    loadTransactions()
-  }, [address])
-
-  const loadAddressInfo = async () => {
+  const loadAddressInfo = useCallback(async () => {
     try {
-      const response = await addressesApi.get(chainId, address)
-      setAddressInfo(response.data ?? null)
+      const { ok, data } = await addressesApi.getSafe(chainId, address)
+      if (!ok) {
+        setAddressInfo(null)
+        return
+      }
+      setAddressInfo(data ?? null)
     } catch (error) {
       console.error('Failed to load address info:', error)
       setAddressInfo(null)
     }
-  }
+  }, [chainId, address])
 
-  const loadTransactions = async () => {
+  const loadTransactions = useCallback(async () => {
     try {
-      const response = await addressesApi.getTransactions(chainId, address, 1, 20)
-      setTransactions(response.data || [])
+      const { ok, data } = await addressesApi.getTransactionsSafe(chainId, address, 1, 20)
+      setTransactions(ok ? data : [])
     } catch (error) {
       console.error('Failed to load transactions:', error)
       setTransactions([])
     } finally {
       setLoading(false)
     }
-  }
+  }, [chainId, address])
+
+  useEffect(() => {
+    loadAddressInfo()
+    loadTransactions()
+  }, [loadAddressInfo, loadTransactions])
 
   if (loading) {
     return <div className="p-8">Loading address...</div>

frontend/src/pages/blocks/[number].tsx

@@ -1,10 +1,9 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import { useParams } from 'next/navigation'
 import { blocksApi, Block } from '@/services/api/blocks'
-import { Card } from '@/components/common/Card'
-import { Address } from '@/components/blockchain/Address'
+import { Card, Address } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
 
 export default function BlockDetailPage() {
@@ -17,16 +16,7 @@ export default function BlockDetailPage() {
   const [block, setBlock] = useState<Block | null>(null)
   const [loading, setLoading] = useState(true)
 
-  useEffect(() => {
-    if (!isValidBlock) {
-      setLoading(false)
-      setBlock(null)
-      return
-    }
-    loadBlock()
-  }, [blockNumber, isValidBlock])
-
-  const loadBlock = async () => {
+  const loadBlock = useCallback(async () => {
     setLoading(true)
     try {
       const response = await blocksApi.getByNumber(chainId, blockNumber)
@@ -36,7 +26,16 @@ export default function BlockDetailPage() {
     } finally {
       setLoading(false)
     }
-  }
+  }, [chainId, blockNumber])
+
+  useEffect(() => {
+    if (!isValidBlock) {
+      setLoading(false)
+      setBlock(null)
+      return
+    }
+    loadBlock()
+  }, [isValidBlock, loadBlock])
 
   if (!isValidBlock) {
     return <div className="p-8">Invalid block number. Please use a valid block number from the URL.</div>

frontend/src/pages/blocks/index.tsx

@@ -1,9 +1,8 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import { blocksApi, Block } from '@/services/api/blocks'
-import { Card } from '@/components/common/Card'
-import { Address } from '@/components/blockchain/Address'
+import { Card, Address } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
 
 export default function BlocksPage() {
@@ -12,11 +11,7 @@ export default function BlocksPage() {
   const [page, setPage] = useState(1)
   const chainId = parseInt(process.env.NEXT_PUBLIC_CHAIN_ID || '138')
 
-  useEffect(() => {
-    loadBlocks()
-  }, [page])
-
-  const loadBlocks = async () => {
+  const loadBlocks = useCallback(async () => {
     setLoading(true)
     try {
       const response = await blocksApi.list({
@@ -32,7 +27,11 @@ export default function BlocksPage() {
     } finally {
       setLoading(false)
     }
-  }
+  }, [chainId, page])
+
+  useEffect(() => {
+    loadBlocks()
+  }, [loadBlocks])
 
   if (loading) {
     return <div className="p-8">Loading blocks...</div>

frontend/src/pages/search/index.tsx

@@ -1,8 +1,7 @@
 'use client'
 
 import { useState } from 'react'
-import { Card } from '@/components/common/Card'
-import { Address } from '@/components/blockchain/Address'
+import { Card, Address } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
 
 interface SearchResult {

frontend/src/pages/transactions/[hash].tsx

@@ -1,9 +1,8 @@
 'use client'
 
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import { useParams } from 'next/navigation'
-import { Card } from '@/components/common/Card'
-import { Address } from '@/components/blockchain/Address'
+import { Card, Address } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
 import { transactionsApi, Transaction } from '@/services/api/transactions'
 
@@ -15,22 +14,26 @@ export default function TransactionDetailPage() {
   const [transaction, setTransaction] = useState<Transaction | null>(null)
   const [loading, setLoading] = useState(true)
 
-  useEffect(() => {
-    loadTransaction()
-  }, [hash])
-
-  const loadTransaction = async () => {
+  const loadTransaction = useCallback(async () => {
     setLoading(true)
     try {
-      const response = await transactionsApi.get(chainId, hash)
-      setTransaction(response.data ?? null)
+      const { ok, data } = await transactionsApi.getSafe(chainId, hash)
+      if (!ok) {
+        setTransaction(null)
+        return
+      }
+      setTransaction(data ?? null)
     } catch (error) {
       console.error('Failed to load transaction:', error)
       setTransaction(null)
     } finally {
       setLoading(false)
     }
-  }
+  }, [chainId, hash])
+
+  useEffect(() => {
+    loadTransaction()
+  }, [loadTransaction])
 
   if (loading) {
     return <div className="p-8">Loading transaction...</div>

frontend/src/pages/transactions/index.tsx

@@ -1,23 +1,9 @@
 'use client'
 
-import { useEffect, useState } from 'react'
-import { Table } from '@/components/common/Table'
-import { Address } from '@/components/blockchain/Address'
+import { useCallback, useEffect, useState } from 'react'
+import { Table, Address } from '@/libs/frontend-ui-primitives'
 import Link from 'next/link'
-
-interface Transaction {
-  chain_id: number
-  hash: string
-  block_number: number
-  transaction_index: number
-  from_address: string
-  to_address?: string
-  value: string
-  gas_price?: number
-  gas_used?: number
-  status?: number
-  created_at: string
-}
+import { transactionsApi, Transaction } from '@/services/api/transactions'
 
 export default function TransactionsPage() {
   const [transactions, setTransactions] = useState<Transaction[]>([])
@@ -25,24 +11,22 @@ export default function TransactionsPage() {
   const [page, setPage] = useState(1)
   const chainId = parseInt(process.env.NEXT_PUBLIC_CHAIN_ID || '138')
 
-  useEffect(() => {
-    loadTransactions()
-  }, [page])
-
-  const loadTransactions = async () => {
+  const loadTransactions = useCallback(async () => {
     setLoading(true)
     try {
-      const response = await fetch(
-        `${process.env.NEXT_PUBLIC_API_URL}/api/v1/transactions?chain_id=${chainId}&page=${page}&page_size=20`
-      )
-      const data = await response.json()
-      setTransactions(data.data || [])
+      const { ok, data } = await transactionsApi.listSafe(chainId, page, 20)
+      setTransactions(ok ? data : [])
     } catch (error) {
       console.error('Failed to load transactions:', error)
+      setTransactions([])
     } finally {
       setLoading(false)
     }
-  }
+  }, [chainId, page])
+
+  useEffect(() => {
+    loadTransactions()
+  }, [loadTransactions])
 
   const columns = [
     {
@@ -95,7 +79,7 @@ export default function TransactionsPage() {
     <div className="container mx-auto px-4 py-8">
       <h1 className="text-3xl font-bold mb-6">Transactions</h1>
 
-      <Table columns={columns} data={transactions} />
+      <Table columns={columns} data={transactions} keyExtractor={(tx) => tx.hash} />
 
       <div className="mt-6 flex gap-4 justify-center">
         <button

frontend/src/services/api/addresses.ts

@@ -30,6 +30,33 @@ export const addressesApi = {
   get: async (chainId: number, address: string): Promise<ApiResponse<AddressInfo>> => {
     return apiClient.get<AddressInfo>(`/api/v1/addresses/${chainId}/${address}`)
   },
+  /** Use when you need to check response.ok before setting state (avoids treating 4xx/5xx body as data). */
+  getSafe: async (chainId: number, address: string): Promise<{ ok: boolean; data: AddressInfo | null }> => {
+    return apiClient.getSafe<AddressInfo>(`/api/v1/addresses/${chainId}/${address}`)
+  },
+  getTransactionsSafe: async (
+    chainId: number,
+    address: string,
+    page = 1,
+    pageSize = 20
+  ): Promise<{ ok: boolean; data: TransactionSummary[] }> => {
+    try {
+      const params = new URLSearchParams({
+        chain_id: chainId.toString(),
+        from_address: address,
+        page: page.toString(),
+        page_size: pageSize.toString(),
+      })
+      const raw = (await apiClient.get(`/api/v1/transactions?${params.toString()}`)) as unknown as {
+        data?: TransactionSummary[]
+        items?: TransactionSummary[]
+      }
+      const data = Array.isArray(raw?.data) ? raw.data : Array.isArray(raw?.items) ? raw.items : []
+      return { ok: true, data }
+    } catch {
+      return { ok: false, data: [] }
+    }
+  },
 
   getTransactions: async (
     chainId: number,

frontend/src/services/api/client.ts

@@ -1,92 +1,17 @@
-import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+// Re-export from reusable lib (frontend/libs/frontend-api-client)
+import { createApiClient, type ApiResponse, type ApiError } from '../../../libs/frontend-api-client'
 
-export interface ApiResponse<T> {
-  data: T
-  meta?: {
-    pagination?: {
-      page: number
-      page_size: number
-      total: number
-      total_pages: number
-    }
+export type { ApiResponse, ApiError }
+
+function getApiKey(): string | null {
+  if (typeof window !== 'undefined') {
+    return localStorage.getItem('api_key')
   }
+  return null
 }
 
-export interface ApiError {
-  error: {
-    code: string
-    message: string
-    details?: unknown
-    request_id?: string
-  }
-}
-
-class ApiClient {
-  private client: AxiosInstance
-
-  constructor(baseURL: string = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080') {
-    this.client = axios.create({
-      baseURL,
-      timeout: 30000,
-      headers: {
-        'Content-Type': 'application/json',
-      },
-    })
-
-    // Request interceptor
-    this.client.interceptors.request.use(
-      (config) => {
-        // Add API key if available
-        const apiKey = this.getApiKey()
-        if (apiKey) {
-          config.headers['X-API-Key'] = apiKey
-        }
-        return config
-      },
-      (error) => Promise.reject(error)
-    )
-
-    // Response interceptor
-    this.client.interceptors.response.use(
-      (response) => response,
-      (error) => {
-        // Handle errors
-        if (error.response) {
-          const apiError: ApiError = error.response.data
-          return Promise.reject(apiError)
-        }
-        return Promise.reject(error)
-      }
-    )
-  }
-
-  private getApiKey(): string | null {
-    if (typeof window !== 'undefined') {
-      return localStorage.getItem('api_key')
-    }
-    return null
-  }
-
-  async get<T>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
-    const response: AxiosResponse<ApiResponse<T>> = await this.client.get(url, config)
-    return response.data
-  }
-
-  async post<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
-    const response: AxiosResponse<ApiResponse<T>> = await this.client.post(url, data, config)
-    return response.data
-  }
-
-  async put<T>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
-    const response: AxiosResponse<ApiResponse<T>> = await this.client.put(url, data, config)
-    return response.data
-  }
-
-  async delete<T>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>> {
-    const response: AxiosResponse<ApiResponse<T>> = await this.client.delete(url, config)
-    return response.data
-  }
-}
-
-export const apiClient = new ApiClient()
+export const apiClient = createApiClient(
+  process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8080',
+  getApiKey
+)
 

frontend/src/services/api/transactions.ts

@@ -24,4 +24,34 @@ export const transactionsApi = {
   get: async (chainId: number, hash: string): Promise<ApiResponse<Transaction>> => {
     return apiClient.get<Transaction>(`/api/v1/transactions/${chainId}/${hash}`)
   },
+  /** Use when you need to check response.ok before setting state (avoids treating 4xx/5xx body as data). */
+  getSafe: async (chainId: number, hash: string): Promise<{ ok: boolean; data: Transaction | null }> => {
+    return apiClient.getSafe<Transaction>(`/api/v1/transactions/${chainId}/${hash}`)
+  },
+  list: async (chainId: number, page: number, pageSize: number): Promise<ApiResponse<Transaction[]>> => {
+    const params = new URLSearchParams({
+      chain_id: chainId.toString(),
+      page: page.toString(),
+      page_size: pageSize.toString(),
+    })
+    const raw = (await apiClient.get(`/api/v1/transactions?${params.toString()}`)) as unknown as { data?: Transaction[]; items?: Transaction[] }
+    const data = Array.isArray(raw?.data) ? raw.data : Array.isArray(raw?.items) ? raw.items : []
+    return { data }
+  },
+  /** Use when you need to check ok before setting state (avoids treating error body as list). */
+  listSafe: async (chainId: number, page: number, pageSize: number): Promise<{ ok: boolean; data: Transaction[] }> => {
+    try {
+      const params = new URLSearchParams({
+        chain_id: chainId.toString(),
+        page: page.toString(),
+        page_size: pageSize.toString(),
+      })
+      const raw = await apiClient.getSafe<Transaction[]>(`/api/v1/transactions?${params.toString()}`)
+      if (!raw.ok) return { ok: false, data: [] }
+      const data = Array.isArray(raw.data) ? raw.data : []
+      return { ok: true, data }
+    } catch {
+      return { ok: false, data: [] }
+    }
+  },
 }

frontend/tsconfig.json

@@ -14,16 +14,12 @@
     "isolatedModules": true,
     "jsx": "preserve",
     "incremental": true,
-    "plugins": [
-      {
-        "name": "next"
-      }
-    ],
+    "plugins": [{ "name": "next" }],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "@/libs/*": ["./libs/*"]
     }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", "**/*.test.ts", "**/*.spec.ts"]
 }
-

frontend/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config'
+import path from 'path'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['**/*.test.ts', '**/*.spec.ts'],
+    globals: true,
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+})