Asset Lists

Description

Inspired by Ethereum's Token Lists project, Asset Lists aim to enhance the discoverability of Cosmos SDK denominations by associating them with metadata. While primarily used for assets transferred over IBC, this standard is still evolving. The assets format in the assetlist.json structure closely mirrors Cosmos SDK's banktypes.DenomMetadata, paving the way for potential migration into a Cosmos SDK module for on-chain maintenance in the future. Find the assetlist JSON Schema at the Cosmos Chain Registry.

Prerequisite

The .assetlist.json files herein are generated, which will be triggered by additions to the corresponding osmosis.zone_assets.json file, fetching the metadata from the Cosmos Chain Registry. The primary prerequisite to adding an asset here is complete registration of the asset and it's originating chain (and the IBC connection between the origin chain and Osmosis, if not native to Osmosis) to the Cosmos Chain Registry, so please make sure that's done first. We have a guide on registering a Chain and Asset to the Cosmos Chain Registry.

Repository Structure

This repository contains several types of files organized by chain:

Input Files (Zone Configuration)

These files are manually maintained and serve as input for automated generation:

• osmosis.zone_assets.json - Configuration for assets to be listed on Osmosis Zone. Add new assets here.
• osmosis.zone_chains.json - Configuration for chains to be supported on Osmosis Zone. Includes RPC/REST endpoints, explorers, and chain-specific settings.
• osmosis.zone_config.json - General configuration and settings for the zone.

Generated Files

These files are automatically generated by GitHub Actions and should not be edited manually:

• generated/frontend/assetlist.json - Asset list formatted for Osmosis Zone frontend consumption
• generated/frontend/chainlist.json - Chain list formatted for Osmosis Zone frontend, including wallet integration metadata
• generated/chain-registry/assetlist.json - Asset list in Cosmos Chain Registry format
• generated/external/ - Integration files for external services (CoinGecko, Mintscan)
• generated/asset_detail/ - Detailed metadata for individual assets including pricing, related assets, and counterparty information
• state/ - Tracks asset state information such as listing status, warnings, and historical data

Directory Structure

osmosis-1/                    # Mainnet configuration
  ├── osmosis.zone_assets.json
  ├── osmosis.zone_chains.json
  ├── osmosis.zone_config.json
  ├── state/
  └── generated/
      ├── frontend/
      ├── chain-registry/
      ├── external/
      └── asset_detail/

osmo-test-5/                  # Testnet configuration
  └── (same structure as mainnet)

How to Add Assets

Please see the asset listing requirements for information about displaying assets on Osmosis Zone.

To add an asset, add a new asset object to the very bottom of the osmosis.zone_assets.json file, containing some identifying and key details:

• base_denom is the minimal/indivisible (i.e., exponent: 0) denomination unit for the asset, corresponding to its base at the Chain Registry.
• chain_name must be the exact value defined as chain_name in the chain's chain.json file at the Chain Registry.
• path is required for all ics20 assets (i.e., assets that are transferred to Osmosis from another chain via IBC); the only exception are asset deployed directly on Osmosis (e.g., factory tokens). It is comprised of: the destination IBC port and channel for each IBC hop, followed by the base denom on the IBC-originating chain. The is used as input into the SHA256 hash function.
  • e.g., "path": "transfer/channel-0/uatom"
• osmosis_verified should always be set to false upon initial listing; this indicates whether the 'Unverified Assets' setting must be toggled to reveal the asset on Osmosis Zone. After meeting the requirements described in the listing requirements page, an additional PR may created to set it to true.

There are also some additional details that may be defined for an asset:

• transfer_methods should be included whenever a basic IBC transfer initiated via Osmosis Zone Deposit and Withdraw buttons is unable to carry-out an interchain transfer.
• override_properties may be defined for cases where Osmosis Zone shall display the asset differently than how registered on its source chain.
• canonical shall be defined for assets that are Osmosis' canonical representation of an asset different than its source (e.g., Axelar's WETH(.axl) is Osmosis' canonical representation of Ether $ETH on Osmosis)
• categories are best manually defined for an asset, including: "defi" and "meme".

Chains

Automatic Chain Inclusion

You typically don't need to manually add chains. When you add an asset to osmosis.zone_assets.json, the automated generation process will:

1. Detect the asset's origin chain from Chain Registry
2. Automatically include that chain in the generated chainlist
3. Fetch all necessary chain metadata from Chain Registry
4. Generate wallet-compatible chain configuration

This means chains are automatically added as counterparty chains whenever their assets are listed.

Manual Chain Configuration (Optional)

You only need to manually configure a chain in osmosis.zone_chains.json if you want to:

• Provide custom/reliable RPC and REST endpoints
• Override default Chain Registry properties
• Add a chain before any of its assets are listed
• Configure chain-specific features or settings

To manually add or update a chain, add/modify a chain object in osmosis.zone_chains.json:

Required Fields (for manual configuration):

• chain_name - Must match exactly the chain_name in the Chain Registry
• rpc - A reliable RPC endpoint URL for the chain
• rest - A reliable REST API endpoint URL for the chain
• explorer_tx_url - URL template for transaction explorer (e.g., https://www.mintscan.io/osmosis/txs/{txHash})

Optional Fields:

• keplr_features - Array of feature flags for Keplr wallet (e.g., ["ibc-go", "cosmwasm"])
• override_properties - Override specific chain properties from Chain Registry:
  • pretty_name - Display name
  • status - Chain status (e.g., "live", "upcoming")
  • network_type - Network type (e.g., "mainnet", "testnet")
  • bech32_prefix - Address prefix
  • fees - Custom fee configuration
  • images - Custom chain logo
• outage - Boolean flag to indicate if chain is experiencing an outage

Example Chain Object:

{
  "chain_name": "cosmoshub",
  "rpc": "https://rpc.cosmos.directory/cosmoshub",
  "rest": "https://rest.cosmos.directory/cosmoshub",
  "explorer_tx_url": "https://www.mintscan.io/cosmos/txs/{txHash}",
  "keplr_features": ["ibc-go"],
  "_comment": "Cosmos Hub"
}

Zone Example

An example asset object in osmosis.zone_assets.json:

{
  "base_denom": "uosmo",
  "chain_name": "osmosis",
  "osmosis_verified": true,
  "_comment": "Osmosis $OSMO"
},
...
{
  "base_denom": "ustk",
  "chain_name": "steakchain",
  "path": "transfer/channel-69/ustk",
  "osmosis_verified": true,
  "_comment": "Steak $STK"
},
{
  "base_denom": "ufoocoin",
  "chain_name": "fubarchain",
  "path": "transfer/channel-420/ufoocoin",
  "osmosis_verified": false,
  "osmosis_unlisted": true,
  "_comment": "Foocoin $FOO"
}

Dependencies

Note that there are apps, interfaces, and tools that look at this repository as a data dependency:

• Osmosis Zone app (app.osmosis.zone):
  • .../generated/frontend/assetlist.json
  • .../generated/frontend/chainlist.json
• Osmosis Labs' Sidecar Query Service (SQS):
  • .../generated/frontend/assetlist.json
• Numia Data Services (e.g., API):
  • .../generated/frontend/assetlist.json
  • .../generated/chain-registry/assetlist.json

How It Works

Automated Generation Process

This repository uses GitHub Actions workflows to automatically generate and validate files:

Scheduled Generation (Every Monday at 12:00 UTC): The Generate All Files bundle workflow runs automatically and includes:

• Updates the chain-registry submodule to the latest version
• Validates RPC/REST endpoints (7 endpoints per run for performance)
• Generates assetlist files in multiple formats
• Generates chainlist files with wallet integration metadata
• Updates asset state
• Generates comments for zone assets
• Runs localization for multi-language support
• Creates a pull request with all updates to the update/assetlist_all branch

Manual Workflows (Not included in bundle): Individual generation workflows can be triggered manually via GitHub Actions:

• Generate Assetlist - Regenerate asset lists only
• Generate Chainlist - Regenerate chain lists only
• Generate CoinGecko - Update CoinGecko integration (standalone)
• Generate Mintscan - Update Mintscan integration (standalone)
• Localization - Update translations

Note on Pool Pricing: Pool-based pricing functionality (getPools.mjs) exists in the codebase but is currently disabled via the getPools = false flag in generate_assetlist.mjs. This code includes pool querying, asset pricing calculations, and routing logic. It was previously used to add pricing information to generated assetlists but is not currently active. The code remains available for future re-implementation if needed.

Pull Request Workflow

1. Submit Changes: Create a PR with additions/updates to osmosis.zone_assets.json or osmosis.zone_chains.json
2. Validation: Automated checks run to validate your changes
   • Zone file validation
   • Asset data validation
   • Endpoint health checks (for chains)
3. Review: Maintainers review the PR
4. Merge: Once approved, changes are merged
5. Auto-Generation: Generated files are automatically updated on the next scheduled run or manual trigger

Validation Workflows

Several validation workflows help maintain data quality:

• Validate Zone Assets - Checks asset configurations are valid and complete
• Validate Zone Chains - Verifies chain configurations and endpoint availability
• Validate Zone Data - Cross-validates data against Chain Registry
• Check Verification Criteria - Evaluates if assets meet verification requirements (check workflow logs for results)

Asset Verification

Assets in this repository can have two verification states:

Unverified Assets

• Default state for newly added assets (osmosis_verified: false)
• Visible only when "Show Unverified Assets" toggle is enabled in Osmosis Zone
• Minimal requirements:
  • Complete Chain Registry registration
  • Valid zone asset configuration
  • Basic asset metadata (name, symbol, logo)

Verified Assets

Assets can be upgraded to verified status (osmosis_verified: true) after meeting comprehensive requirements. See LISTING.md for complete criteria.

Key Requirements Summary:

• Complete asset metadata including description and extended_description
• Social links (website, Twitter)
• Square logo image < 250 KB
• Minimum liquidity on Osmosis (≥$1,000 in pools)
• Market depth requirements (2% depth of $50)
• Validation by Osmosis Zone maintainers

Automated Verification Checks: The Check Verification Criteria workflow automatically evaluates assets against verification requirements. To view verification status:

1. Go to the Actions tab
2. Select the "Check Verification Criteria" workflow
3. View the latest run logs for detailed assessment results

Upgrading to Verified:

1. Ensure your asset meets all requirements in LISTING.md
2. Check the verification workflow logs for your asset
3. Submit a PR updating osmosis_verified from false to true
4. Maintainers will review against criteria before approval

Contributing

Contributions are welcome! Please ensure:

• Changes follow the documented structure and requirements
• All required fields are present and valid
• References to Chain Registry data are accurate
• PRs include clear descriptions of changes

For questions or issues, please open a GitHub issue or reach out in the Osmosis Discord.