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: Animated Orb placeholders for image slots plus traditional spinners for query status
• 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
• Progressive image placeholders: OrbImage/ProgressiveImage keep logo and NFT frames stable while assets stream in

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
• Prefetch on intent: Hovering token accordions invokes useAssets prefetch so data is ready when panels open

Memory Management

• Query garbage collection: Unused queries removed after cache time
• Lightweight placeholders: Animated placeholders avoid extra DOM nodes or timers once the image resolves
• Component unmounting: Proper cleanup of subscriptions and timers when accordions close

Security Considerations

Beyond protecting API keys, the current implementation relies on wagmi’s wallet connectors and Alchemy’s APIs for input fidelity. If your deployment requires additional validation (for example, address normalization or stricter chain filtering), implement those guards in a server-side proxy or extend the selection components accordingly.

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