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 (Tuesdays and Fridays at 15: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

Required Fields

Each asset object in osmosis.zone_assets.json must include these identifying details:

• chain_name - Must match exactly the chain_name in the chain's chain.json file at the Chain Registry.
• base_denom - The minimal/indivisible (i.e., exponent: 0) denomination unit for the asset, corresponding to its base at the Chain Registry.
• path - Required for all ICS20 assets (transferred to Osmosis from another chain via IBC). Comprised of the destination IBC port and channel for each IBC hop, followed by the base denom on the IBC-originating chain. Used as input into the SHA256 hash function.
  • Exception: Not required for assets deployed directly on Osmosis (e.g., factory tokens)
  • Example: "path": "transfer/channel-0/uatom"

Verification & Visibility Flags

• osmosis_verified (boolean, default: false) - Controls whether the asset appears by default or requires "Show Unverified Assets" toggle.

  • Should always be set to false upon initial listing
  • After meeting requirements in LISTING.md, can be upgraded to true via PR
  • Frontend output: verified: true/false

• osmosis_unlisted (boolean, default: false) - Temporarily hides the asset from the Osmosis Zone app, even if verified.

  • Use for deprecating assets or temporary removal
  • Frontend output: preview: true/false

Transfer & Reliability Flags

• osmosis_unstable (boolean, default: false) - Critical flag indicating the asset cannot reliably be transferred to or from Osmosis.

  • Frontend Behavior: Sets both unstable: true AND disabled: true in generated assetlist
  • User Impact: Disables native IBC Deposit/Withdraw buttons; frontend may redirect to external interfaces (e.g., TFM)
  • Common Causes: Unreliable IBC relayers, frequent chain downtime, channel connectivity issues
  • When to Remove: After confirming IBC channels work reliably and consistently

• osmosis_disabled (boolean, default: false) - Explicitly disables Deposit and Withdraw functions, independent of reliability status.

  • Frontend Behavior: Disables native IBC Deposit/Withdraw buttons
  • Difference from unstable: This is an intentional decision to disable transfers, not a reliability issue
  • Common Reasons: Forcing the external or custom transfer methods, security or reliabiliy concerns - Asset remains visible and tradeable

• transfer_methods (array) - Custom transfer configurations for assets requiring special handling.

  • Should be included whenever basic IBC transfer cannot carry out an interchain transfer
  • Types: external_interface (e.g., Squid Router, TFM, chain bridges), integrated_bridge, fiat_onramp
  • Provides alternative deposit/withdraw interfaces when native IBC is disabled or unavailable
  • Example:

    "transfer_methods": [
      {
        "name": "Squid Router",
        "type": "external_interface",
        "deposit_url": "https://app.squidrouter.com/?chains=1,osmosis-1&tokens=...",
        "withdraw_url": "https://app.squidrouter.com/?chains=osmosis-1,1&tokens=..."
      }
    ]

Important: The frontend maps osmosis_unstable: true to BOTH unstable: true AND disabled: true. This means setting the unstable flag will automatically disable native IBC transfers.

Asset Relationship Flags

• canonical (object: {chain_name, base_denom}) - Defines assets that are Osmosis' canonical representation of an asset different than its source.

  • Example: Axelar's WETH is Osmosis' canonical representation of Ethereum's ETH
  • Used when multiple bridge paths exist but one is preferred

• origin (object: {chain_name, base_denom}) - Defines the original/source asset for derivative or wrapped assets.

  • Traces an asset back to its ultimate origin chain and denomination
  • Used for liquid staking derivatives and multi-hop wrapped assets

Special Asset Types

• is_alloyed (boolean, default: false) - Indicates the asset is an Alloyed Asset on Osmosis.

  • Alloyed Assets are transmuter pools that combine multiple variants of the same underlying asset into a single fungible token
  • Example: allUSDT combines USDT from different bridges
  • Frontend output: isAlloyed: true/false

• peg_mechanism (enum: "collateralized", "algorithmic", "hybrid") - The peg mechanism for synthetically created assets, most important for stablecoins.

Categorization & Metadata

• categories (array of strings) - Categorizes assets for filtering and organization.

  • Standard categories: "defi", "meme", "liquid_staking", "stablecoin", "built_on_osmosis", "dweb", "oracles"
  • Best practice: Manually define categories for better asset discovery

• tooltip_message (string) - Custom on-hover tooltip message displayed for the asset.

  • Use for warnings, clarifications, or important notices to users
  • Example: "This asset is NOT affiliated with the Bad Kids NFT collection."

• listing_date_time_utc (string, ISO 8601 format) - UTC timestamp when asset was listed on Osmosis Zone.

  • Format: "YYYY-MM-DDTHH:MM:SSZ"
  • Used for "New" badges, sorting, and tracking
  • Frontend output: listingDate: Date

Advanced Configuration

• override_properties (object) - Properties that should not follow the Chain Registry and behave or appear differently on Osmosis Zone.
  • Available overrides: symbol, name, logo_URIs, coingecko_id, use_asset_name, counterparty
  • Use when Chain Registry data doesn't match desired Osmosis display

For complete schema definitions, see zone_assets.schema.json.

Common Configuration Scenarios

Scenario 1: Standard Asset with Working IBC (Most Common)

{
  "chain_name": "cosmoshub",
  "base_denom": "uatom",
  "path": "transfer/channel-0/uatom",
  "osmosis_verified": true,
  "categories": ["defi"],
  "_comment": "Cosmos Hub $ATOM"
}

Result: Verified asset with native IBC deposit/withdraw buttons enabled.

Scenario 2: New Unverified Asset

{
  "chain_name": "newchain",
  "base_denom": "unew",
  "path": "transfer/channel-999/unew",
  "osmosis_verified": false,
  "_comment": "NewChain $NEW"
}

Result: Visible only with "Show Unverified Assets" toggle, native IBC works.

Scenario 3: Unreliable IBC - Needs External Interface

{
  "chain_name": "genesisl1",
  "base_denom": "el1",
  "path": "transfer/channel-253/el1",
  "osmosis_verified": false,
  "osmosis_unstable": true,
  "_comment": "GenesisL1 $L1"
}

Result: Native IBC buttons disabled, frontend redirects to TFM or other external interface.

To enable native IBC: Remove osmosis_unstable after confirming channels work reliably.

Scenario 4: Asset with Custom Transfer Method

{
  "chain_name": "ethereum",
  "base_denom": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "path": "transfer/channel-208/uusdc",
  "osmosis_verified": true,
  "transfer_methods": [
    {
      "name": "Squid Router",
      "type": "external_interface",
      "deposit_url": "https://app.squidrouter.com/?chains=1,osmosis-1&tokens=...",
      "withdraw_url": "https://app.squidrouter.com/?chains=osmosis-1,1&tokens=..."
    }
  ],
  "_comment": "USDC via Axelar"
}

Result: Shows both native IBC and Squid Router options.

Scenario 5: Intentionally Disabled Transfers

{
  "chain_name": "composable",
  "base_denom": "ppica",
  "path": "transfer/channel-1279/ppica",
  "osmosis_disabled": true,
  "transfer_methods": [
    {
      "name": "Picasso App",
      "type": "external_interface",
      "depositUrl": "https://app.picasso.network/?from=PicassoKusama&to=OSMOSIS",
      "withdrawUrl": "https://app.picasso.network/?from=OSMOSIS&to=PicassoKusama"
    }
  ],
  "_comment": "Picasso $PICA - use custom interface only"
}

Result: Native IBC disabled, shows only Picasso App transfer method.

Decision Guide: Enabling Native IBC Transfers

Question: Why isn't my asset showing native deposit/withdraw buttons?

Check your asset configuration for these flags:

1. osmosis_unstable: true → This disables native IBC

   • Solution: Remove this flag after testing IBC channels work reliably
   • Test: Verify deposits and withdrawals work without errors or delays

2. osmosis_disabled: true → This intentionally disables native IBC

   • Solution: Remove this flag if you want to enable native transfers
   • Consider: Was this set for security/liquidity management? Verify it's safe to remove

3. No transfer_methods but IBC is disabled → Likely osmosis_unstable is set

   • Solution: Add custom transfer_methods OR remove unstable flag

Question: When should I use osmosis_unstable vs osmosis_disabled?

• Use osmosis_unstable: When IBC technically works but has reliability problems (downtime, slow relayers, failed transactions)
• Use osmosis_disabled: When you intentionally want to disable transfers for business/security reasons, regardless of technical reliability

Both flags disable the frontend IBC buttons, but they signal different reasons.

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: Tuesdays and Fridays at 15: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 (Tuesdays and Fridays at 15: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 Tuesday and Friday at 15: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 15:00 UTC (Tue/Fri) and auto-merges to main
2. 30 minutes later (15: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.