@chain-registry/client

The @chain-registry/client package provides a client for dynamically fetching and managing chain and asset data from the Cosmos chain registry. This tool is essential for developers who need to access up-to-date blockchain information, including asset lists and IBC data.

• Introduction
• Installation
• Usage
  • ChainRegistryClient
    • Initializing the Client
    • Methods
    • Fetching Chain and Asset Data
    • Accessing Chain Information
    • Retrieving Asset Lists
  • ChainRegistryFetcher
    • Fetching Data
    • Fetching Schemata
    • fetchUrls
    • fetch
    • Asset Lists
    • Chain Info
• Related Projects
• Credits
• Disclaimer

Installation

npm install @chain-registry/client

Usage

We recommend using the ChainRegistryClient directly, the ChainRegistryFetcher is lower-level if you don't need a higher-level class.

ChainRegistryClient

ChainRegistryClient dynamically fetches and manages chain and asset data from the chain-registry.

Initializing the Client

import { ChainRegistryClient } from '@chain-registry/client';

const client = new ChainRegistryClient({
  chainNames: ['osmosis', 'juno']
});

After instantiation, you can use client to access chain and asset information, along with IBC data.

ChainRegistryClient Options

While the default usage above is simple, you can customize it.

The ChainRegistryClient constructor accepts an options object you can specify:

• chainNames (required): An array of strings representing the names of the chains you want to fetch data for. This option is essential to determine which chains' data will be managed by the client.

• assetListNames (optional): An array of strings specifying the names of the chains for which asset lists should be fetched. If not provided, the client uses the chainNames array as the default list.

• ibcNamePairs (optional): An array of string arrays, where each nested array contains two elements representing a pair of chain names. This setting specifies the Inter-Blockchain Communication (IBC) connections between the chains for which data should be considered. It is particularly useful for limiting the scope of IBC-related data processing.

• baseUrl (optional): A string representing the base URL for fetching the chain registry data. If not specified, the client defaults to the official Cosmos chain registry on GitHub (https://raw.githubusercontent.com/cosmos/chain-registry/master).

Initialization Examples

Here is a client with specified chain names and limited IBC name pairs, and custom baseUrl:

const client = new ChainRegistryClient({
  chainNames: ['osmosis', 'juno', 'stargaze', 'cosmoshub'],
  ibcNamePairs: [['osmosis', 'stargaze']],
  baseUrl: 'https://yourregistry.com/'
});

Here is a client with specified chain names and limited asset list, and limited IBC name pairs:

const clientWithAssetLists = new ChainRegistryClient({
  chainNames: ['osmosis', 'juno', 'stargaze'],
  assetListNames: ['osmosis', 'juno'],
  ibcNamePairs: [['osmosis', 'juno']]
});

Let's walk through this example where you can specify which IBC connections you're interested in:

import { ChainRegistryClient } from '@chain-registry/client';

const client = new ChainRegistryClient({
  chainNames: ['osmosis', 'juno', 'stargaze', 'cosmoshub'],
  ibcNamePairs: [['osmosis', 'stargaze']]
});

In this example, the chainNames option includes four chains, but ibcNamePairs only includes a pair between osmosis and stargaze. This configuration means that the client will fetch and manage data for all four specified chains, but when it comes to generating asset lists with getGeneratedAssetLists(), it will only consider the IBC connections between osmosis and stargaze for IBC-connected assets.

Methods

• fetchUrls(): Asynchronously fetches the data for all the configured URLs and stores the results internally within the client instance.
• getChain(chainName): Returns the Chain object for the specified chain name.
• getChainInfo(chainName): Retrieves ChainInfo, an object with detailed information about the specified chain, including its configuration, assets, and IBC connections.
• getAssetList(chainName): Obtains a list of assets available on the specified chain.
• getChainAssetList(chainName): Returns the AssetList for the specified chain.
• getGeneratedAssetLists(chainName): Generates and returns AssetList[] for the specified chain, including IBC-connected assets.
• getChainIbcData(chainName): Retrieves IBC data related to the specified chain.

Fetching chain and asset data

To initiate the data fetching process, the ChainRegistryClient must first execute the fetchUrls method. This method asynchronously retrieves data from the predefined URLs based on the configuration provided during the client's instantiation.

await client.fetchUrls();

In this line, client.fetchUrls() asynchronously fetches the chain and asset data for the chains specified in the client's configuration. This process involves making HTTP requests to the URLs constructed from the base URL and the chain names, asset list names, and IBC name pairs provided in the ChainRegistryClientOptions.

Accessing Chain Information

After fetching the data, you can access detailed information about a specific chain using the getChainInfo method. This method returns a ChainInfo object, which contains data about the requested chain, including its assets, IBC connections, and other metadata.

const osmosisInfo = client.getChainInfo('osmosis');
 // returns ChainInfo, which is an object containing everything

if you just want the Chain object, you can do:

const osmosisInfo = client.getChain('osmosis');
 // returns Chain from `@chain-registry/types`

Retrieving Asset Lists

Here, client.getAssetList('juno') fetches the asset list for the Juno chain. The junoAssets variable will hold an array of assets defined on the Juno chain, detailing each asset's properties such as its name, symbol, and other asset-specific information.

const junoAssets = client.getAssetList('juno');
// returns AssetList from '@chain-registry/types'

If you want to get the IBC denominations, and the asset lists based on the IBC connections, you can use getGeneratedAssetLists():

const generatedOsmosisAssets = client.getGeneratedAssetLists('osmosis');
// returns AssetList from '@chain-registry/types' — including generated IBC assets based on IBC connections

ChainRegistryFetcher

ChainRegistryFetcher is a lower-level component used by ChainRegistryClient for fetching data from specified URLs.

Fetching data

import { ChainRegistryFetcher, ChainRegistryFetcherOptions } from '@chain-registry/client';

const options: ChainRegistryFetcherOptions = {
  urls: [
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/osmosis/chain.json',
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/osmosis/assetlist.json',
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/juno/assetlist.json',
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/secretnetwork/assetlist.json',
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/_IBC/juno-osmosis.json',
    'https://raw.githubusercontent.com/cosmos/chain-registry/master/_IBC/osmosis-secretnetwork.json'
  ]
};
const registry = new ChainRegistryFetcher(options);
await registry.fetchUrls();

Fetching Schemata

We currently only support fetching JSON schemas as defined in https://github.com/cosmos/chain-registry. Supported are assetlist.schema.json, chain.schema.json and ibc_data.schema.json.

fetchUrls

You can set the ChainRegistryFetcher.urls property and call ChainRegistryFetcher.fetchUrls()

registry.urls = [
  // urls to fetch
];
await registry.fetchUrls();

fetch

Or, you can simply call ChainRegistryFetcher.fetch()

await registry.fetch('https://some-json-schema.com/some-schema.json');

Asset lists

You can get generated asset lists directly from the registry:

// generated asset lists
const generated: AssetList[] = registry.getGeneratedAssetLists('osmosis');

You can get generated AssetList[] objects directly from the ChainRegistry via the assetLists method:

// you can also get generated assets from ChainInfo object
const chainInfo: Chain = registry.getChainInfo('osmosis');
const generatedAssets: AssetList[] = chainInfo.assetLists;

Chain info

You can get Chain object directly from the ChainRegistry via the getChain method:

// get Chain from registry
const chain: Chain = registry.getChain('osmosis');

or get the ChainInfo object:

const chainInfo: ChainInfo = registry.getChainInfo('osmosis');

// AssetList[] of the generated assets
const assets: AssetList[] = chainInfo.assetLists;

// Chain 
const chain: Chain = chainInfo.chain;

// Native asset list
const nativeAssetList: AssetList = chainInfo.nativeAssetList;

Related

Checkout these related projects:

• @cosmology/telescope Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
• @cosmwasm/ts-codegen Convert your CosmWasm smart contracts into dev-friendly TypeScript classes.
• chain-registry Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
• cosmos-kit Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
• create-cosmos-app Set up a modern Cosmos app by running one command.
• interchain-ui The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
• starship Unified Testing and Development for the Interchain.

Credits

🛠 Built by Cosmology — if you like our tools, please consider delegating to our validator ⚛️

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.