Portfolio UI System

The Portfolio UI is a sophisticated multi-chain asset viewing system that enables users to explore their digital assets across multiple EVM-compatible blockchains. Built with React, TanStack Query, and wagmi, it provides real-time asset discovery with intelligent caching and prefetching capabilities.

Core Features

Architecture Overview

The portfolio system follows a layered architecture pattern that separates concerns and maximizes reusability. Due to the complexity of the system, we’ve broken down the architecture into three focused diagrams:

Main Component Structure

Selection Layer Components

Organization and Display Layers

Component Hierarchy

• portfolio
  • PortfolioClient.tsx
  • components
    • selection
    • organize
    • assets
  • hooks
  • __tests__

Multi-Chain Architecture

The portfolio viewer seamlessly integrates with multiple blockchain networks through a combination of wagmi’s chain configuration and Alchemy’s unified API endpoints.

Supported Networks

Data Flow

Understanding how data flows through the portfolio system is crucial for debugging and extending functionality:

1. User Selection Flow

2. Asset Discovery Flow

3. Optimization Flow

Supported Assets

The portfolio viewer handles three distinct asset types, each with specialized display logic:

ERC-20 Tokens

Standard fungible tokens with:

• Token name and symbol
• Decimal-aware balance formatting
• Logo retrieval from Alchemy metadata
• Optional price integration support

ERC-721 NFTs

Non-fungible tokens featuring:

• Individual token display with images
• Metadata parsing for names and descriptions
• Attribute visualization
• IPFS gateway integration for decentralized images

ERC-1155 Multi-Tokens

Semi-fungible tokens supporting:

• Balance tracking for each token ID
• Mixed fungible/non-fungible display
• Batch metadata fetching

Native Currencies

Each blockchain’s native currency (ETH, MATIC, AVAX, etc.) is displayed separately using wagmi’s balance hooks for real-time accuracy.

User Interface

The portfolio UI implements a progressive disclosure pattern that prevents information overload while maintaining quick access to all assets:

Visual Hierarchy

1. Account Selection - Primary wallet address with ENS resolution (no loading indicator shown during resolution)
2. Network Selection - Visual grid with chain logos and checkboxes
3. Token Type Selection - Simple checkbox interface for asset types
4. Asset Display - Nested accordions revealing assets on demand

Animation Strategy

All transitions use Framer Motion for smooth, hardware-accelerated animations:

• Accordion animations: Height-based transitions with opacity fades
• Asset grid animations: Staggered entry for visual polish
• Loading states: Skeleton screens and spinners for feedback
• Error states: Contextual retry buttons with helpful messages

Data Fetching

The portfolio leverages Alchemy’s comprehensive blockchain APIs through a custom React Query implementation:

Caching Strategy

Prefetching

The system implements intelligent prefetching:

• Hover-based prefetch for accordion items
• Background refresh for stale data
• Pagination prefetch for large collections

Error Recovery

Automatic retry logic with exponential backoff:

• 3 retry attempts for transient failures
• No retry for 404 errors
• Manual retry buttons for user control

Performance Optimizations

The portfolio UI implements several performance optimizations:

Component-Level Optimizations

• Lazy loading: Accordion content only mounts when opened
• Virtualization ready: Asset grids prepared for react-window integration
• Memoization: Expensive computations cached with useMemo

Network-Level Optimizations

• Request deduplication: TanStack Query prevents duplicate API calls
• Infinite pagination: Load assets in chunks of 100
• Selective fetching: Only request data for selected chains/tokens

Memory Management

• Query garbage collection: Unused queries removed after cache time
• Image optimization: Lazy load NFT images with intersection observer
• Component unmounting: Proper cleanup of subscriptions and timers

Security Considerations

The portfolio system implements several security measures:

• Address validation: All addresses normalized and validated
• CORS compliance: Proper handling of cross-origin image requests
• XSS prevention: React’s built-in protections for user content
• Input sanitization: Chain IDs and token addresses validated

Accessibility

The portfolio UI follows WCAG 2.1 guidelines:

• Keyboard navigation: Full accordion control via keyboard
• Screen reader support: Proper ARIA labels and roles
• Focus management: Clear focus indicators and logical tab order
• Color contrast: Meets AA standards for all text

Testing Coverage

The portfolio system includes comprehensive test coverage:

Top-Level Tests

• PortfolioClient Integration Test: Verifies all components render within ChainInfoProvider wrapper
• Content Unit Test: Validates mapping logic from selection state to ChainData format

Component Tests

• Unit tests: Individual component behavior
• Integration tests: Component interaction flows
• Hook tests: Data fetching and caching logic
• Accessibility tests: Automated a11y validation

See individual component documentation for specific test examples and coverage reports.

Next Steps