CAIP2

Introduction

CAIP-2 (Chain Agnostic Improvement Proposal 2) provides a standardized format for blockchain network identification. This guide covers the implementation using the @snowballmoney/chain-agnostic-utils library, which simplifies cross-chain development by providing a consistent way to identify and work with different blockchain networks.

Understanding CAIP-2

CAIP-2 addresses a critical challenge in blockchain development: the inconsistent ways different chains identify their networks. For example:

• Ethereum and EVM chains use numeric IDs (e.g., 1 for mainnet, 5 for goerli)

• Solana uses cluster names (e.g., mainnet-beta, devnet)

• Some chains have conflicting IDs (both Ethereum and Aptos use 1 for mainnet)

The CAIP-2 standard solves this by using a consistent format:

namespace:reference

Where:

• namespace: Identifies the blockchain ecosystem (e.g., 'eip155' for EVM chains, 'solana' for Solana)

• reference: Network-specific identifier within that ecosystem

Installation

Install the library using npm or yarn:

npm install @snowballmoney/chain-agnostic-utils
# or
yarn add @snowballmoney/chain-agnostic-utils

Basic Usage

Network Identification

import { NETWORKS, isValidCAIP2 } from '@snowballmoney/chain-agnostic-utils';

// Access predefined network identifiers
const ethereumMainnet = NETWORKS.ETHEREUM.MAINNET;    // 'eip155:1'
const solanaMainnet = NETWORKS.SOLANA.MAINNET;       // 'solana:mainnet-beta'
const movementMainnet = NETWORKS.MOVEMENT.MAINNET;    // 'move-mvmt:126'

// Validate CAIP-2 identifiers
console.log(isValidCAIP2(ethereumMainnet));  // true
console.log(isValidCAIP2('invalid'));        // false

Working with Network Metadata

import { NETWORK_METADATA, getNetworkMetadata } from '@snowballmoney/chain-agnostic-utils';

// Access network metadata
const ethereumData = NETWORK_METADATA[NETWORKS.ETHEREUM.MAINNET];
console.log(ethereumData);
/*
{
  name: 'Ethereum Mainnet',
  currency: 'ETH',
  icon: 'https://assets.coingecko.com/coins/images/279/small/ethereum.png',
  explorerUrl: 'https://etherscan.io'
}
*/

Advanced Usage: CAIP2Manager

The CAIP2Manager provides a flexible way to manage network metadata and combine built-in networks with custom ones.

import { CAIP2Manager } from '@snowballmoney/chain-agnostic-utils';

// Get singleton instance
const manager = CAIP2Manager.getInstance();

// Initialize with default and custom networks
manager.init({
    defaultNetworks: true, // Include built-in networks
    networks: {
        'eip155:11155111': {
            name: 'Sepolia',
            currency: 'ETH',
            icon: 'path/to/icon',
            explorerUrl: 'https://sepolia.etherscan.io',
            rpcUrl: 'https://rpc.sepolia.org'
        }
    }
});

// Access network information
const ethData = manager.getNetwork('eip155:1');
const isSupported = manager.hasNetwork('eip155:1');

// Add custom networks
manager.addNetwork('eip155:123456', {
    name: 'My Custom Network',
    currency: 'TOKEN',
    icon: 'path/to/icon'
});

// Get all registered networks
const allNetworks = manager.getAllNetworks();

Parsing CAIP-2 Identifiers

import { parseCAIP2 } from '@snowballmoney/chain-agnostic-utils';

const { namespace, reference } = parseCAIP2('eip155:1');
console.log(namespace);  // 'eip155'
console.log(reference);  // '1'

Supported Networks

The library supports a wide range of blockchain networks across different ecosystems:

EVM-based Networks (eip155)

• Ethereum

• BNB Smart Chain

• Polygon

• Arbitrum

• Optimism

• Avalanche

• Base

• Linea

Move-based Networks

• Movement

• Aptos

• Sui

Layer 1 Ecosystems

• Bitcoin (BIP-122)

• Solana

• Cardano

• Polkadot

• Cosmos

• NEAR

Layer 2 Solutions

• StarkNet

• zkSync

• Linea

Network Metadata

Each supported network includes comprehensive metadata:

• Name: Human-readable network name

• Native Currency: Network's native token symbol

• Icon URL: Network's icon or logo

• Explorer URL: Block explorer URL

• RPC URL: Network RPC endpoint (where applicable)

Best Practices

1. Always validate CAIP-2 identifiers before using them in your application

2. Use the CAIP2Manager for consistent network management across your application

3. Include proper error handling for unsupported networks

4. Consider caching network metadata for better performance

Contributing

To add support for new networks or update existing network information, please submit a pull request with:

1. Network identifier following CAIP-2 format

2. Complete network metadata

3. Documentation updates if needed