Tools for generating and parsing CAIP identifiers
npm install caip-utilsA comprehensive JavaScript library for parsing and verifying CAIP (Chain Agnostic Improvement Proposals) identifiers across multiple blockchain networks.
- ✅ CAIP-2: Chain ID parsing and validation
- ✅ CAIP-10: Account ID parsing and validation
- ✅ CAIP-19: Asset ID parsing and on-chain verification
- ✅ CAIP-221: Transaction ID parsing and on-chain verification
- 🌐 Multi-chain support: EIP155 (Ethereum), Stellar, and extensible architecture
- 🔗 On-chain verification: Real-time validation using RPC nodes and APIs
- 🛡️ Robust error handling: Graceful fallbacks and comprehensive validation
- 📝 TypeScript-ready: Consistent return types and clear interfaces
``bash`
npm install caip-utils
`javascript
import { parseCAIP2, parseCAIP10, parseCAIP19, verifyCAIP19, parseCAIP221, verifyCAIP221 } from 'caip-utils';
// Parse a chain identifier
const chain = await parseCAIP2('eip155:1');
console.log(chain.chainName); // "Ethereum Mainnet"
// Parse an account identifier
const account = await parseCAIP10('eip155:1:0x742d35Cc6634C0532925a3b8D4C1B4E7c5B4E8C0');
console.log(account.explorerUrl); // "https://etherscan.io/address/0x742d..."
// Parse and verify an asset identifier
const asset = await verifyCAIP19('eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');
if (asset.verified) {
console.log(${asset.name} (${asset.symbol})); // "USD Coin (USDC)"`
}
Parses a CAIP-2 chain identifier and returns chain information.
Parameters:
- caip2 (string): Chain identifier in format namespace:reference
Returns: Promise
Example:
`javascript`
const result = await parseCAIP2('eip155:1');
// {
// namespace: "eip155",
// reference: "1",
// chainName: "Ethereum Mainnet",
// explorerUrl: "https://etherscan.io"
// }
Supported Networks:
- eip155:* - Ethereum and EVM-compatible chainsstellar:pubnet
- - Stellar Mainnet
- Generic fallback for other namespaces
---
Parses a CAIP-10 account identifier and returns account information.
Parameters:
- caip10 (string): Account identifier in format namespace:reference:address
Returns: Promise
Example:
`javascript`
const result = await parseCAIP10('eip155:1:0x742d35Cc6634C0532925a3b8D4C1B4E7c5B4E8C0');
// {
// namespace: "eip155",
// reference: "1",
// address: "0x742d35Cc6634C0532925a3b8D4C1B4E7c5B4E8C0",
// chainName: "Ethereum Mainnet",
// explorerUrl: "https://etherscan.io/address/0x742d35Cc6634C0532925a3b8D4C1B4E7c5B4E8C0"
// }
---
Parses a CAIP-19 asset identifier and returns asset information.
Parameters:
- caip19 (string): Asset identifier in format namespace:reference/asset_namespace:asset_reference[/token_id]
Returns: Promise
Example:
`javascript
// ERC20 Token
const erc20 = await parseCAIP19('eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');
// ERC721 NFT with token ID
const nft = await parseCAIP19('eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234');
// Stellar asset
const stellar = await parseCAIP19('stellar:pubnet/slip44:148');
`
---
Parses a CAIP-19 asset identifier and verifies it exists on-chain.
Parameters:
- caip19 (string): Asset identifier in format namespace:reference/asset_namespace:asset_reference[/token_id]
Returns: Promise
Example:
`javascript
const result = await verifyCAIP19('eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48');
if (result.verified) {
console.log(${result.name} (${result.symbol})); // "USD Coin (USDC)"Decimals: ${result.decimals}
console.log(); // "Decimals: 6"Verification failed: ${result.verificationError}
} else {
console.log();`
}
Verification Features:
- ERC20: Fetches name, symbol, decimals, totalSupply from contract
- ERC721/ERC1155: Verifies contract exists and fetches metadata
- Stellar: Verifies native XLM or custom assets via Horizon API
- RPC Resilience: Automatically tries multiple RPC endpoints
- Graceful Failures: Returns verified: false instead of throwing
---
Parses a CAIP-221 transaction identifier and returns transaction information.
Parameters:
- caip221 (string): Transaction identifier in format namespace:reference:txn/transaction_id
Returns: Promise
Example:
`javascript`
const result = await parseCAIP221('eip155:1:txn/0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060');
// {
// namespace: "eip155",
// reference: "1",
// chainName: "Ethereum Mainnet",
// transactionId: "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
// explorerUrl: "https://etherscan.io/tx/0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
// verified: false
// }
---
Parses a CAIP-221 transaction identifier and verifies it exists on-chain.
Parameters:
- caip221 (string): Transaction identifier in format namespace:reference:txn/transaction_id
Returns: Promise
Example:
`javascript
const result = await verifyCAIP221('eip155:1:txn/0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060');
if (result.verified) {
console.log(Transaction confirmed in block ${result.blockNumber});From: ${result.from} → To: ${result.to}
console.log();Value: ${result.value} wei
console.log();Verification failed: ${result.verificationError}
} else {
console.log();`
}
Verification Features:
- EIP155: Fetches full transaction data via RPC calls
- Stellar: Verifies transactions via Horizon API (when implemented)
- RPC Resilience: Automatically tries multiple RPC endpoints
- Pending Detection: Distinguishes between pending and confirmed transactions
All functions follow consistent error handling patterns:
or verificationNotejavascript
try {
const result = await verifyCAIP19('eip155:1/erc20:0xInvalidAddress');
if (result.verified) {
// Use verified data
} else {
// Handle verification failure
console.log(result.verificationError);
}
} catch (error) {
// Handle format/syntax errors
console.log('Invalid CAIP format:', error.message);
}
`Supported Networks
$3
- Ethereum:
- Polygon:
- Arbitrum: eip155:42161
- Optimism:
- And 1000+ other EVM chains$3
- Mainnet:
- Testnet: (parsing only)$3
The library is designed to easily add support for new blockchain networks. Each namespace implements its own parsing and verification logic.Advanced Usage
$3
`javascript
// Force refresh chain data cache
const result = await parseCAIP19('eip155:1/erc20:0xA0b...', { forceRefresh: true });// Verification automatically handles RPC fallbacks
const verified = await verifyCAIP19('eip155:1/erc20:0xA0b...');
`$3
javascript
// Parse NFT collection
const collection = await parseCAIP19('eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D');// Parse specific NFT
const nft = await parseCAIP19('eip155:1/erc721:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D/1234');
console.log(nft.tokenId); // "1234"
`Development
$3
bash
npm test
`$3
bash
npm run update-chains
``This fetches the latest chain information from chainlist.org and updates the local snapshot.
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
MIT License - see LICENSE file for details.
- CAIP Standards
- CAIP-2: Chain ID
- CAIP-10: Account ID
- CAIP-19: Asset ID
- CAIP-221: Transaction ID