Chain Info Provider

The Chain Info Provider is a React context system that extends wagmi’s chain information with visual assets and display name management. While wagmi provides chain IDs and technical names, it doesn’t include logos or handle edge cases in naming conventions across different services.

What This System Solves

🖼️ Blockchain Logo Management

Automatically fetches and manages blockchain logos from TrustWallet’s CDN, with intelligent fallback handling when assets are unavailable.

🏷️ Display Name Normalization

Transforms technical chain names into user-friendly display names, handling special cases and inconsistencies across different services.

🔧 Custom Chain Support

Enables seamless integration of local and custom blockchains with their own assets, perfect for development networks and private chains.

Architecture Overview

The system consists of two tightly coupled components that work together to provide a complete chain information solution:

• components
  • providers
    • ChainInfoProvider.tsx
    • chainOverrides.ts

How It Extends Wagmi

Wagmi provides essential blockchain connectivity but has limitations when building user interfaces:

Core Components

ChainInfoProvider

The main provider component that creates a React context with chain information utilities.

import { ChainInfoProvider } from '@/components/providers/ChainInfoProvider'
 
export default function App({ children }) {
  return (
    <ChainInfoProvider>
      {children}
    </ChainInfoProvider>
  )
}

useChainInfo Hook

Access chain information throughout your application:

import { useChainInfo } from '@/components/providers/ChainInfoProvider'
 
function MyComponent() {
  const { 
    getCurrentChainLogoUrl,
    getCurrentChainDisplayName 
  } = useChainInfo()
  
  // Use in your UI
  return (
    <img src={getCurrentChainLogoUrl()} alt={getCurrentChainDisplayName()} />
  )
}

API Reference

ChainInfoProvider Props

The ChainInfoProvider component accepts the following props:

useChainInfo Hook Return Values

The useChainInfo hook provides access to the following methods and properties:

Chain Overrides Configuration

The chainOverrides.ts file allows you to customize chain information for specific networks:

export interface ChainOverride {
  displayName?: string    // Custom display name
  walletKey?: string      // TrustWallet CDN key override
  localLogoUrl?: string   // Local file path for custom logos
}

Configuration Examples

export const CHAIN_OVERRIDES: Record<number, ChainOverride> = {
  // Optimism: Standard name works fine
  10: { 
    displayName: "Optimism", 
    walletKey: "optimism" 
  },
  
  // Avalanche: TrustWallet uses "avalanchec" not "avalanche"
  43114: { 
    displayName: "Avalanche", 
    walletKey: "avalanchec"  // Special case!
  },
}

// Custom local blockchain (e.g., development network)
[Number(process.env.NEXT_PUBLIC_LOCAL_CHAIN_ID) || 90999999]: {
  displayName: process.env.NEXT_PUBLIC_RITONET_DISPLAY_NAME ?? "RitoNet",
  walletKey: "ritonet", // Won't exist on CDN
  localLogoUrl: "/images/blockchainLogos/ritonet.png", // Use local file
}

Name Normalization

The provider automatically normalizes chain names for CDN compatibility when no override is specified:

// Input: "Test Chain 2.0!"
// Output: "test-chain-20"
 
normalizeKey(name: string) {
  return name
    .toLowerCase()              // "test chain 2.0!"
    .replace(/\s+/g, "-")      // "test-chain-2.0!"
    .replace(/[^a-z0-9-]/g, "") // "test-chain-20"
}

This ensures special characters and spaces don’t break CDN URL construction.

Logo Resolution Logic

The provider follows a specific hierarchy when resolving logos:

TrustWallet CDN Structure

The provider constructs URLs following TrustWallet’s asset structure:

# Chain logos
https://cdn.jsdelivr.net/gh/trustwallet/assets@master/blockchains/{key}/info/logo.png

# Token logos
https://cdn.jsdelivr.net/gh/trustwallet/assets@master/blockchains/{key}/assets/{tokenAddress}/logo.png

Usage Example: NetworkWidget

Here’s how the NetworkWidget component uses the Chain Info Provider:

import { useChainInfo } from "@providers/ChainInfoProvider";
 
export default function NetworkWidget() {
  const {
    activeChain,
    getCurrentChainLogoUrl,
    getFallbackLogoUrl,
  } = useChainInfo();
  
  const logoUrl = getCurrentChainLogoUrl();
  const fallback = getFallbackLogoUrl();
  
  return (
    <img
      src={logoUrl}
      alt={`${symbol} logo`}
      className={styles.logo}
      onError={(e) => {
        // Graceful fallback on load error
        e.currentTarget.onerror = null;
        e.currentTarget.src = fallback;
      }}
    />
  );
}

This pattern ensures users always see a logo, even if:

• The chain isn’t supported by TrustWallet
• The CDN is temporarily unavailable
• You’re using a custom local blockchain

Error Handling

The provider implements multiple layers of error handling:

Missing Chain Data

When a requested chain ID isn’t found in wagmi’s configuration, the system falls back to the currently active chain rather than immediately showing an error:

// If chain 999 doesn't exist but user is on Ethereum (chain 1)
getChainLogoUrl(999) // Returns Ethereum's logo URL

This ensures users see familiar branding even when querying unknown chains.

Invalid Token Address

Token logo requests validate the address parameter:

if (!target || !tokenAddress) return FALLBACK_LOGO;

Token addresses are automatically normalized to lowercase to match CDN conventions:

const addr = tokenAddress.toLowerCase();

Fallback Logo Design

The fallback logo is a data URI SVG that displays a blue circle with a white ”?” symbol:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
  <circle cx="10" cy="10" r="10" fill="#04426C"/>
  <text x="10" y="11" text-anchor="middle" dominant-baseline="middle" 
        fill="white" font-size="16" font-family="Arial, sans-serif">?</text>
</svg>

This provides a consistent, recognizable indicator when logos can’t be loaded.

Image Load Failures

Components using the provider should implement onError handlers:

<img
  src={logoUrl}
  onError={(e) => {
    e.currentTarget.src = getFallbackLogoUrl();
  }}
/>

Best Practices

Extending the System

To add support for a new chain:

1. Check if the chain’s wagmi name matches TrustWallet’s key
2. If not, add an override in chainOverrides.ts:

export const CHAIN_OVERRIDES: Record<number, ChainOverride> = {
  // ... existing overrides
  
  [YOUR_CHAIN_ID]: {
    displayName: "Your Chain Display Name",
    walletKey: "trustwallet-key", // If different from chain name
    localLogoUrl: "/images/your-chain.png" // Optional
  }
}

3. For local/custom chains, always provide localLogoUrl since they won’t exist on the CDN

Common Issues

Logo Not Loading

1. Check the CDN key: Visit TrustWallet’s assets repo to verify the correct blockchain folder name
2. Add an override: If the key differs from the chain name, add it to chainOverrides.ts
3. Use local fallback: For custom chains, always provide a localLogoUrl

Display Name Issues

Some wagmi chain names are technical or inconsistent. Override them for better UX:

// Instead of "Arbitrum One" or "arbitrum"
42161: { displayName: "Arbitrum" }

Token Logo 404s

Token logos require:

• Lowercase token address
• Token must be listed in TrustWallet’s assets
• Correct blockchain key

Not all tokens have logos available. Implement appropriate fallbacks in your UI.