Osmosis Assetlists

Description

This repository generates asset and chain information for the Osmosis Zone frontend. It uses the Cosmos Chain Registry as the source of truth for asset metadata, then layers Osmosis-specific configurations on top:

• Reliable Endpoints - Curated RPC/REST endpoints with validation and health monitoring
• Transfer Methods - Custom transfer configurations for assets requiring special handling
• Verification Status - Asset verification flags based on listing criteria
• Categories - Asset categorization (DeFi, meme tokens, etc.) for frontend filtering
• Property Overrides - Osmosis-specific display properties when needed

The generated files power the Osmosis Zone interface, providing wallet integration, asset discovery, and chain connectivity information. Asset metadata (logos, descriptions, social links) comes from Chain Registry and is automatically updated during scheduled runs.

Prerequisite: Chain Registry Registration

The Cosmos Chain Registry is the source of truth for all asset metadata. Assets registered in Chain Registry with IBC connections to Osmosis are automatically detected and added to osmosis.zone_assets.json during scheduled workflow runs (twice weekly), making them visible on Osmosis Zone.

Submission Workflow

1. Submit PR to Chain Registry - Register your chain and asset at the Cosmos Chain Registry

   • Include complete asset metadata (name, symbol, logo, description, etc.)
   • Register IBC connection information between your chain and Osmosis (if applicable)
   • Follow the Chain Registry contribution guide

2. Wait for Chain Registry PR to be merged - Once your PR is approved and merged into Chain Registry

3. Automatic Detection and Listing - Automated runs in this repo occur twice weekly (Mondays and Thursdays at 09:00 UTC) and will:

   • Pull latest Chain Registry data
   • Automatically detect new assets with IBC connections to Osmosis
   • Automatically add detected assets to osmosis.zone_assets.json
   • Generate assetlists with your complete metadata from Chain Registry
   • Make your asset visible on Osmosis frontend
   • Can also be triggered manually by maintainers

4. Optional: Configure Additional Properties - Manually edit your entry in osmosis.zone_assets.json if you need to:

   • Set asset categories ("defi", "meme", etc.)
   • Request verified status (osmosis_verified: true - requires meeting verification criteria)
   • Configure custom transfer methods or property overrides
   • Override display properties from Chain Registry

Important: All asset metadata (images, descriptions, social links, etc.) comes from Chain Registry. To update asset information, submit PRs to Chain Registry, not this repository. Changes will be automatically picked up during the next automated run (twice weekly).

Repository Structure

This repository contains several types of files organized by chain:

Input Files (Zone Configuration)

These files serve as input for automated generation:

• osmosis.zone_assets.json - Configuration for assets on Osmosis Zone. Auto-populated by workflow for detected assets; manually edit for categories, verification, and overrides.
• osmosis.zone_chains.json - Manual configuration for chains with custom 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)

Zone Asset Configuration

How Assets Are Added to osmosis.zone_assets.json:

1. Automatically by Workflow - Assets with IBC connections to Osmosis are automatically detected from Chain Registry and added to osmosis.zone_assets.json during scheduled runs (twice weekly).

2. Manually for Additional Configuration - You can manually add or edit entries in osmosis.zone_assets.json to configure:

   • Asset categories ("defi", "meme", etc.)
   • Verification status (osmosis_verified: true or false)
   • Custom transfer methods
   • Property overrides

Please see the asset listing requirements for information about verification and display requirements on Osmosis Zone.

Asset Object Structure

When the workflow adds an asset (or if you manually edit), each asset object in osmosis.zone_assets.json includes these identifying 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. The generated chainlist includes chains from two sources:

1. Manually Configured Chains (~47 chains) - Chains in osmosis.zone_chains.json with custom endpoints and settings (takes precedence)
2. Auto-Detected Counterparty Chains (~133 chains) - Origin chains of assets listed in osmosis.zone_assets.json, automatically detected and included from Chain Registry

The automated generation process merges these sources:

• Manual chains from osmosis.zone_chains.json are used first (with your custom RPC/REST endpoints and overrides)
• Auto-detected counterparty chains supplement the manual list
• Chain metadata is fetched from Chain Registry for both
• Wallet-compatible chain configuration is generated for all chains

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
  • force_rpc - Boolean flag to force using ONLY the zone-specified RPC endpoint (ignores Chain Registry endpoints)
  • force_rest - Boolean flag to force using ONLY the zone-specified REST endpoint (ignores Chain Registry endpoints)
• 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"
}

Example Chain Object with Endpoint Override:

{
  "chain_name": "stride",
  "rpc": "https://stride-rpc.polkachu.com/",
  "rest": "https://stride-api.polkachu.com/",
  "explorer_tx_url": "https://explorer.stride.zone/stride/tx/${txHash}",
  "keplr_features": ["ibc-go"],
  "override_properties": {
    "force_rest": true
  },
  "_comment": "Force using only the specified REST endpoint, ignoring Chain Registry backups"
}

Endpoint Override Behavior

When you specify rpc or rest endpoints in your chain configuration:

1. Your zone-specified endpoint is placed first in the endpoint list
2. Chain Registry endpoints are added as backups
3. State-based optimization may reorder endpoints based on validation results (unless forced)

How State-Based Optimization Works:

• Validation results are tracked in state/state.json
• If a backup endpoint works better than the primary, it's automatically promoted to first position in the generated chainlist
• This enables intelligent failover without manual intervention
• Optimization happens during chainlist generation based on historical validation data

Forcing Override Endpoint Priority: To lock your specified endpoint in first position (preventing state-based reordering):

• Set "force_rpc": true in override_properties to lock your RPC endpoint in first position
• Set "force_rest": true in override_properties to lock your REST endpoint in first position
• Chain Registry endpoints are still included as backups, they just won't be promoted to first position.

This is useful when:

• You have a highly reliable endpoint that should always be tried first
• You want to prevent the validation algorithm from reordering your preferred endpoint

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

Data Consumers

Apps, interfaces, and tools that consume data from this repository:

• 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:
  • generated/frontend/assetlist.json
  • generated/chain-registry/assetlist.json

Data Providers (Bidirectional Dependencies)

External services that provide data TO this repository:

• Cosmos Chain Registry - Source of truth for all asset metadata, chain information, and IBC connections
• Numia Data Services API - Provides pool liquidity data and market depth measurements for asset verification checks (requirements #6 and #7)

How It Works

Automated Generation Process

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

Scheduled Generation (Twice weekly: Mondays and Thursdays at 09:00 UTC): The Generate All Files bundle workflow runs automatically and includes:

• Updates the chain-registry submodule to the latest version
• Adds chain stubs to osmosis.zone_chains.json for any newly detected chains
  • Creates minimal entries (chain_name + comment) for chains in zone_assets.json not yet in zone_chains.json
  • Makes it easy for maintainers to add custom RPC/REST endpoints later
  • All fields default to Chain Registry values unless explicitly overridden
• Validates RPC/REST endpoints (priority-based selection: 10 of ~180 chains per run)
  • Prioritizes: Failed chains (1 day requery delay) → Never-validated chains → Oldest-validated chains (7 day requery delay)
  • Tracks validation results in state/state.json for endpoint optimization
  • Full validation available via manual Full Endpoint Validation workflow
• 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
• Auto-merges the PR after validation passes (scheduled runs only)

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

For Manual Changes to Zone Configuration:

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

For Automated Generation Runs:

1. Scheduled Run: Workflow executes twice weekly (Mondays and Thursdays at 09:00 UTC)
2. Generation: Creates updated assetlist/chainlist files
3. PR Creation: Automatically creates a PR to the update/assetlist_all branch with all generated changes
4. Validation: All validation checks must pass
5. Auto-Merge: PR is automatically merged (scheduled runs only; manual triggers require manual merge)

Deployment to Frontend

Changes to generated files are automatically deployed to the Osmosis Zone frontend via Vercel:

Deployment Schedule:

• Scheduled: Every Monday and Thursday at 09:30 UTC (30 minutes after generation workflow completes)
• Manual: Can be triggered manually via GitHub Actions workflow dispatch
• Fallback: Push to main (won't trigger with auto-merge due to GITHUB_TOKEN limitation)

Monitored Files:

• osmosis-1/generated/frontend/assetlist.json and chainlist.json (mainnet)
• osmo-test-5/generated/frontend/assetlist.json and chainlist.json (testnet)

Deployment Flow:

1. Generation workflow completes at 09:00 UTC (Mon/Thu) and auto-merges to main
2. 30 minutes later (09:30 UTC), deployment workflow runs on schedule
3. Workflow checks if monitored files were modified in the last 2 hours
4. If files unchanged: Deployment is skipped (no unnecessary Vercel builds)
5. If files changed: Vercel webhooks are triggered (preview + production for mainnet, testnet separately)
6. Vercel builds and deploys to environments
7. Osmosis Zone app reflects updated data within ~30-45 minutes of generation

This completes the full pipeline: Chain Registry → Detection → Generation → PR → Merge → Scheduled Deployment → Frontend

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.