From f9bc8de5380696654c2d37eb88a6e335b1fd30fb Mon Sep 17 00:00:00 2001 From: Jeremy Parish Date: Sat, 16 Mar 2024 14:11:33 -0600 Subject: [PATCH] update registration documentation --- docs/overview/integrate/registration.md | 537 ++++++------------------ 1 file changed, 128 insertions(+), 409 deletions(-) diff --git a/docs/overview/integrate/registration.md b/docs/overview/integrate/registration.md index a51d9552e..71b54ca7d 100644 --- a/docs/overview/integrate/registration.md +++ b/docs/overview/integrate/registration.md @@ -2,27 +2,40 @@ sidebar_position: 4 --- # Register your Asset -Assets need to be registered in several locations in order to be displayed correctly on interfaces. Without registration, assets will show as a long list of characters. +This guide intends to support teams looking to enlist their tokenized crypto asset onto the Osmosis Zone app. Assets need to be registered in several locations in order to be displayed correctly on all interfaces. -# Prerequisites +### Overview -- Registered to [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) - - See: [How to register a bech32 prefix onto SLIP173](https://docs.osmosis.zone/overview/integrate/transfer#register-a-bech32-prefix-onto-slip173) -- If coin type is not like ATOM, registered to [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) - - Note: Coin Type 118 represents the Cosmos Hub's ATOM token, registered listed in [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md); many projects also default to using this coin type, while some have registered their own. +At a very high level, the process entails three main steps: + - Registering to the Cosmos Chain Registry, + - Registering to Osmosis Labs’ Assetlist Registry, and + - Establishing markets for the asset on Osmosis. +Note that the overall process could require collaboration from knowledgeable technical teams to provide information or services, as well as market-making entities to provide funding for initial liquidity or incentive programs. + +To ensure a complete integration with Osmosis Zone and related apps, see the [Osmosis Labs' Assetlist Repository's LISTING.md Document](https://github.com/osmosis-labs/assetlists/blob/main/LISTING.md). + +### Required Skills + +Basic understanding of GitHub, knowing how to fork a respository, create a branch, commit changes, and submit a Pull Request -## Step 1: Register onto the Cosmos Chain Registry +## Step 1: Register to the Cosmos Chain Registry ### Purpose -The Cosmos Chain Registry is used as a single source of truth and is used to look up chain and asset data +The Cosmos Chain Registry is meant to be a public good, used as a single source of truth for chain and asset metadata, as well as IBC connections, interfaces, and tooling supporting Cosmos chains. + +### Prerequisites + +- Registered to [SLIP173](https://github.com/satoshilabs/slips/blob/master/slip-0173.md) +- Registered to [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) + - Note: Coin Type 118 represents the Cosmos Hub's ATOM token, listed in [SLIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md); many projects also default to using this coin type, while some have registered their own. ### Requirements - Chain data--metadata, locations, network addresses, etc. - Asset data--metadata, such as name, symbol, minimal denomination, decimal precision, etc. - CoinGecko ID - - Refer to the latest [CoinGecko Coins List](https://api.coingecko.com/api/v3/coins/list) + - Refer to [CoinGecko's Coins List API (v3)](https://api.coingecko.com/api/v3/coins/list) - Basic understanding of GitHub, knowing how to fork a repository, create a branch, commit changes, and submit a Pull Request ### Steps @@ -31,429 +44,135 @@ The Cosmos Chain Registry is used as a single source of truth and is used to loo - Note: It is recommended to refer to another registration to serve as an example, such as [Osmosis' registration](https://github.com/cosmos/chain-registry/blob/master/osmosis/chain.json) 2. If registering a new Chain, submit a pull request with necessary changes to the `chain.json` file. - Follow the [chain.schema.json](https://github.com/cosmos/chain-registry/blob/master/chain.schema.json) format. - - Be sure to include `bech32_prefix` - - e.g., `"bech32_prefix": "cosmos",` - - Be sure to include `slip44` (coin type) - - e.g., `"slip44": 118,` - - Be sure to include at least one RPC and one REST under `apis` - - For explorers, opt for Mintscan, if available + - Be sure to include `bech32_prefix`. + - e.g., `"bech32_prefix": "cosmos",` + - Be sure to include `slip44` (coin type). + - e.g., `"slip44": 118,` + - Be sure to include at least one RPC and one REST under `apis`. + - Be sure to include at least one working Block Explorer. + - Note that to enlisted on Osmosis, an IBC connection will need to be set up and registered (in `/_IBC/`) at the Chgain Registry. 3. If registering a new Asset, submit a pull request with necessary changes to the `assetlists.json` file. - Follow the [assetlist.schema.json](https://github.com/cosmos/chain-registry/blob/master/assetlist.schema.json) format. - - The `name` of an asset refers to how the asset should be called in persoanl communication, while `symbol` is like a stock ticker, typically in ALL CAPS, and these values may differ. - - e.g., `"name": graviton, "display": "graviton", "symbol": "GRAV"` - - Be sure to include the CoinGecko ID for each asset where one exists - - e.g., `"coingecko_id": "cosmos"` + - `name` refers to how the asset should be called when spoken in conversation. + - `symbol` refers to ticker symbol, like how a stock or other securities use a shortened representation. Typically in ALL CAPS. + - e.g., TSLA for Telsa stock, or ATOM for Cosmos Hub's Atom. + - `description` provides a brief description of the asset. + - e.g., "Atom is the native staking and fee token of Cosmos Hub." + - `extended_description` provides additional context about the project in which the asset participates. + - `socials` allows for registering a website and X (formerly Twitter) profile. + - `coingecko_id` if one exists + - e.g., `"coingecko_id": "cosmos"` + - Be sure to include a high quality logo image. -## Step 2: Register an Asset onto the Osmosis Assetlists Registry +## Step 2: Register an Asset to the Osmosis Labs' Assetlist Registry ### Purpose -The Osmosis Assetlists Registry is used as a local source of truth for assets displayed on Osmosis' front end. +The Osmosis Labs' Assetlist Registry is used to serve asset metadata displayed on the Osmosis Zone app. ### Prerequisites - Registered onto the Cosmos Chain Registry - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/overview/integrate/registration#step-1-register-onto-the-cosmos-chain-registry) -- Opened IBC connection between the source chain and Osmosis - - Selected a sole desigate IBC connection between the registering chain and Osmosis for this asset - - All native assets from a chain should go through a single connection, but CW20 tokens can be sent through another connection - - See: [Enabling IBC transfers](https://docs.osmosis.zone/overview/integrate/transfer#enabling-ibc-transfers) and [Setting up and operating relayer to Osmosis](https://docs.osmosis.zone/overview/integrate/transfer#setting-up-and-operating-a-relayer-to-osmosis) -- There is a liquidity pool on Osmosis. - - See: [Pool Setup Guide](https://docs.osmosis.zone/overview/integrate/pool-setup) for the CLI command to create a pool -- Assets listed on CoinGecko (optional) +- IBC Connection + - Established an IBC connection between the source chain and Osmosis + - All native assets from a chain should go through a single connection, although some token types (e.g., CW20 tokens) may require another connection + - See: [Enabling IBC transfers](https://docs.osmosis.zone/overview/integrate/transfer#enabling-ibc-transfers) and [Setting up and operating relayer to Osmosis](https://docs.osmosis.zone/overview/integrate/transfer#setting-up-and-operating-a-relayer-to-osmosis) + - Registered IBC Connection at the Cosmos Chain Registry. +- There exists liquidity of the asset on Osmosis. + - See: [Pool Setup Guide](https://docs.osmosis.zone/overview/integrate/pool-setup) for the CLI command to create a pool. +- Assets listed on CoinGecko (optional, but highly recommended) - See: [How to enlist assets onto CoinGecko](../integrate/registration.md#how-to-enlist-an-asset-onto-coingecko) ### Requirements -- Designate IBC Connection details: - - Source channel (Osmosis' channel to the registering chain) - - Destination channel (Registering chain's channel to Osmosis) +- Chain data and services: + - [Chain Registry] `chain_name`. + - E.G., `cosmoshub` is the registered chain_name for Cosmos Hub. + - Block Explorer Transaction URL + - Mintscan is a preferred default + - Working RPC and REST endpoints + - Must not block the Osmosis Domain. + - Note that many Cosmos SDK RPC Nodes have CORS blocking by default + - RPC node must have Secure Web Sockets (wss://) protocol enabled. - Asset data: - - IBC denomination (when the asset is transferred to Osmosis, the base denomination looks like "ibc/...") - - E.g., For ATOM: `"base": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2",` - - Name, symbol, exponent, etc. - - CoinGecko ID (optional, but should be included if and when there is one) - - Refer to the latest [CoinGecko Coins List](https://api.coingecko.com/api/v3/coins/list) -- Token Logo Image files (both .png and .svg is recommended) - - Note: Currently, a .png is required to be able to render on [info.osmosis.zone](https://info.osmosis.zone) -- Basic understanding of GitHub, knowing how to fork a respository, create a branch, commit changes, and submit a Pull Request + - Base denomination on source chain + - e.g., 'uatom' is the `base_denom` (i.e., the unique and immutable indivisible denomination unit) of ATOM + - IBC Path + - Generally describes to the 'path' (IBC hops) that the asset takes to get to Osmosis + - Every IBC hop is described in the path, including destination chain port and destination chain channel-id + - Used as input for the IBC Hash function to determine the asset denomination on the destination chain. + - IBC denoms alway appear as: 'ibc/{SHA256 HASH of IBC Path}' + - In some rare cases, some characters in the source chain's base_denom or replaced with other characters. + - Whether the Asset is bridged (not referring to IBC transfers) ### Steps -1. Review the [Osmosis Assetlists Registry](https://github.com/osmosis-labs/assetlists) docs: +1. Review the [Osmosis Assetlists Registry](https://github.com/osmosis-labs/assetlists) docs and schema: 1. [README.md](https://github.com/osmosis-labs/assetlists/blob/main/README.md) - 2. [assetlist.schema.json](https://github.com/osmosis-labs/assetlists/blob/main/assetlist.schema.json) -2. Submit a pull request with necessary changes to the `osmosis-1/osmosis.zone_assets.json` file. - - Be sure to include the CoinGecko ID if one exists - - -## Step 3: Register an Asset on the Osmosis Frontend Repository - -### Prerequisites - -Chain Data - -- Chain registered onto the Cosmos Chain Registry - - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/overview/integrate/registration#step-1-register-onto-the-cosmos-chain-registry) -- Chain registered onto SLIP173 - - See: [How to Register onto SLIP173](https://docs.osmosis.zone/overview/integrate/transfer#register-a-bech32-prefix-onto-slip173) -- Relayer(s) set up to relay packets between chains - - To set up a relayer, see the [Relaying Guide](https://docs.osmosis.zone/osmosis-core/relaying/relayer-guide) - - Don't want to set up a Relayer? See: [Shop for a Relayer as a Service (RAAS) Provider](https://docs.osmosis.zone/osmosis-core/relaying/ibc-relayers-list) -- IBC token transfer has been validated - - Or else a functioning Bridge between Chains (only if regular IBC transfers are not possible) -- Chain has a block explorer, either: - - Mintscan (preferred), or - - Any other Block explorer, e.g., Big Dipper, Ping, or a chain-dedicated explorer - -Asset Data - -- Asset registered onto the Cosmos Chain Registry - - See: [How to register onto the Cosmos Chain Registry](https://docs.osmosis.zone/overview/integrate/registration#step-1-register-onto-the-cosmos-chain-registry) -- Asset registered onto the Osmosis Assetlists Registry - - See: [How to register an Asset onto the Osmosis Assetlists Registry](https://docs.osmosis.zone/overview/integrate/registration#step-2-register-an-asset-onto-the-osmosis-assetlists-registry) - -### Requirements - -- Chain data: - - RPC and REST endpoints - - Chain name, Chain id - - BIP44 Coin type (slip44) - - e.g., `coinType: 118,` - - bech32 prefix (slip173) - - At least one staking currency must be specified - - At least one fee currency must be specified - - Cosmos SDK version - - Used to determine which 'features' must be specified - - Gas prices - - The low, average, and high gas prices (per gas unit) so users can choose to either save on fees or expedite transactions using Keplr wallet - - URL to a transation on a Block Explorer - -- Asset data: - - Denominations - - Coin denomination (the denomination for a 'whole' token (e.g., 'ATOM')) - - Coin minimal denomination (base denom on originating chain (e.g., 'uatom') - - For CW20 tokens: - - The minimal denomination looks like `cw20:` - - Will also need the CW20`<>`ICS20 contract address - - For assets originally foreign to the integrating chain (multihop IBC tokens): - - The minimal denomination is the 'ibc/...' denom on the registering chain - - Will also need the entire IBC Transfer Path with the original denomination - - Coin decimal places (e.g., 'ATOM' can be split into micro-ATOM, hence it has 6 decimal places--1 ATOM == 1,000,000 uatom) - - Asset Price data (if available), either: - - CoinGecko ID (optional, but should be included if and when one exists), or - - Refer to the latest [CoinGecko Coins List](https://api.coingecko.com/api/v3/coins/list) - - Token Logo Image files (both .png and .svg is recommended) - - Note: Currently, a .png is required to be able to render on info.osmosis.zone - - Note: image files shall be titled exactly with the token Symbol in lowercase. E.g., for 'ATOM', title the files `atom.png` and `atom.svg` - - Whether the asset is a staking currency - - Whether the asset is a fee currency - - Designate IBC Connection details: - - Source channel (Osmosis' channel to the registering chain) - - Destination channel (Registering chain's channel to Osmosis) - - Bridge URL (only if regular IBC transfers are not possible) - - Best to include URL parameters to pre-select the networks and assets on the bridge interface -- Enough OSMO for the pool creation fee (100 OSMO) and initial liquidity for an OSMO pool (at least 2000 OSMO-worth per pool) -- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request - -### Steps - -1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend) docs: - 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) -2. Submit a pull request branch with necessary changes to the following: - - `osmosis-frontend/packages/web/public/tokens/`: - - Add token logo images - - `osmosis-frontend/packages/web/config/chain-infos.ts`: - - Add chain data to the `chainInfos` onject - - Include the optimal RPC and REST endpoints - - Be sure to include coin type - - Be sure to include bech32 prefix - - List all currencies, including stake and fee currencies - - For each currency, be sure to include the Asset Price Oracle as `CoinGeckoID:` - - opt for a real CoinGecko ID, if one exists - - alternatively, use `pool:` if a pool exists - - or else none - - Include features - - 'stargate' -- must be specified if using Cosmos SDK v0.40+ - - 'ibc-transfer' -- must be specified if IBC transfers following the ICS20 standard have been enabled on the chain - - 'no-legacy-stdTx' -- must be specified if using Cosmos SDK v0.43+, but still recommended to specify, regardless of Cosmos SDK version - - 'ibc-go' -- must be specified if using Cosmos SDK v0.43+, and import the ibc-go repository - - 'wasmd_0.24+' -- must be specified if it needs to append the /cosmwasm pathname (usually for cw20 tokens) - - E.g., `features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx', 'ibc-go'],` - - Include gas price step - - Include chain explorer path - - Opt for Mintscan, if available - - Note: watch out for and remove any dollar sign ($) in the URL, which may be included in the Explorer URL in the Cosmos Chain Registry - - See examples below - - `osmosis-frontend/packages/web/config/ibc-assets.ts` - - Add assets to `IBCAssetInfos` - - Be sure to include the external bridge URLs if an external site is required to bridge to assets to and from Osmosis - - See examples below -3. Validate the deposit and withdrawal of the asset(s) via the generated staging link - -### Examples - -Example of chain-infos.ts::chainInfos: - - Juno chain, with native asset JUNO listed as a stake, fee, and currency token. - - Note: CW20 assets have a the asset symbol appended to the contract address as the coinMinimalDenom. -``` -{ - rpc: 'https://rpc-juno.keplr.app', - rest: 'https://lcd-juno.keplr.app', - chainId: 'juno-1', - chainName: 'Juno', - bip44: { - coinType: 118, - }, - bech32Config: Bech32Address.defaultBech32Config('juno'), - currencies: [ - { - coinDenom: 'JUNO', - coinMinimalDenom: 'ujuno', - coinDecimals: 6, - coinGeckoId: 'juno-network', - coinImageUrl: window.location.origin + '/public/assets/tokens/juno.svg', - isStakeCurrency: true, - isFeeCurrency: true, - }, - { - type: 'cw20', - contractAddress: 'juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', - coinDenom: 'NETA', - coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr:NETA', - coinDecimals: 6, - coinGeckoId: 'neta', - coinImageUrl: window.location.origin + '/public/assets/tokens/neta.svg', - }, - { - type: 'cw20', - contractAddress: 'juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl', - coinDenom: 'MARBLE', - coinMinimalDenom: 'cw20:juno1g2g7ucurum66d42g8k5twk34yegdq8c82858gz0tq2fc75zy7khssgnhjl:MARBLE', - coinDecimals: 3, - coinGeckoId: 'pool:marble', - coinImageUrl: window.location.origin + '/public/assets/tokens/marble.svg', - }, - ], - gasPriceStep: { - low: 0, - average: 0, - high: 0.035, - }, - features: ['stargate', 'ibc-transfer'], - explorerUrlToTx: 'https://www.mintscan.io/juno/txs/{txHash}', -}, -``` - -Examples of ibc-assets.ts::IBCAssetInfos: -- ATOM, a native token from Cosmos Hub: -``` - { - counterpartyChainId: 'cosmoshub-4', - sourceChannelId: 'channel-0', - destChannelId: 'channel-141', - coinMinimalDenom: 'uatom', - }, -``` -- NETA, a CW20 token from Juno: - - Note: *channel-42* is Osmosis' channel to Juno for native Juno assets, but channel-169 is Osmosis' channel to this CW20`<>`ICS20 contract on Juno, which currently accomodates NETA, MARBLE, BLOCK, HOPE, RACOON, and potentially other CW20 tokens in the future -``` + 2. [LISTING.md](https://github.com/osmosis-labs/assetlists/blob/main/LISTING.md) + 3. [assetlist.schema.json](https://github.com/osmosis-labs/assetlists/blob/main/assetlist.schema.json) +2. Submit a pull request with necessary changes to enlist the asset: + 1. Ensure the source chain in included in `osmosis-1/osmosis.zone_chains.json`. + - If not yet registered, add the chain object to the end of the `chains` array. + - Include `chain_name`, `rpc`, `rest`, `explorer_tx_url`, and `keplr_features`. + - E.G., + ``` + { + "chain_name": "osmosis", + "rpc": "https://rpc-osmosis.keplr.app", + "rest": "https://lcd-osmosis.keplr.app", + "explorer_tx_url": "https://www.mintscan.io/osmosis/txs/${txHash}", + "keplr_features": [ + "ibc-go", + "ibc-transfer", + "cosmwasm", + "wasmd_0.24+", + "osmosis-txfees" + ] + } + ``` + 2. Add the asset to the `osmosis-1/osmosis.zone_assets.json` file. + - Add the new asset object to the end of the `assets` array. + - Include `base_denom`, `chain_name`, and `path`. + - New additions always must always start with `"osmosis_unlisted": true + - This allows the Osmosis team to validate via preview mode that the asset appears and behaves correctly on Osmosis Zone. + - New additions always default with having `"osmosis_verified": false + - Once assets are fully integrated, the asset can then be upgraded to "Verified" status. + - See [LISTING.md](https://github.com/osmosis-labs/assetlists/blob/main/LISTING.md) for details on upgrading an asset to Verified status. + - If adding a stablecoin, please include the `peg_mechanism` + - E.G., `"peg_mechanism": "collateralized"` + - If transferring the asset is not a simple IBC transfer, but requires another bridging/transfer interface, provide the URL(s) for the Deposit and Withdraw functions in the `transfer_methods` array within the asset's object. + - E.G., + ``` { - counterpartyChainId: 'juno-1', - sourceChannelId: 'channel-169', - destChannelId: 'channel-47', - coinMinimalDenom: 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr', - ics20ContractAddress: 'juno1v4887y83d6g28puzvt8cl0f3cdhd3y6y9mpysnsp3k8krdm7l6jqgm0rkn', + "chain_name": "terra", + "base_denom": "uluna", + "path": "transfer/channel-72/uluna", + "osmosis_verified": true, + "override_properties": { + "name": "Luna Classic" + }, + "transfer_methods": [ + { + "name": "Terra Bridge", + "type": "external_interface", + "deposit_url": "https://bridge.terra.money", + "withdraw_url": "https://bridge.terra.money" + } + ] }, -``` -- PSTAKE, an ICS20 token originating from Gravity Bridge chain, transfered through Persistence chain, and finally coming to Osmosis (i.e., not directly to Osmosis from Gravity Bridge): - - Note: *channel-38* is Persistence chain's channel to Gravity bridge - - Note: *gravity0xfB5...006* is Gravity Chain's denomination of PSTAKE (originally from Ethereum) -``` - { - counterpartyChainId: 'core-1', - sourceChannelId: 'channel-4', - destChannelId: 'channel-6', - coinMinimalDenom: 'ibc/A6E3AF63B3C906416A9AF7A556C59EA4BD50E617EFFE6299B99700CCB780E444', - ibcTransferPathDenom: 'transfer/channel-38/gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006', - }, -``` -- INJ, the staking and fee token for Injective chain. Injective uses an external site to bridge tokens between Injective Chain and Osmosis, thus we specifiy a custom deposit and withdraw URL override: -``` -{ - counterpartyChainId: 'injective-1', - sourceChannelId: 'channel-122', - destChannelId: 'channel-8', - coinMinimalDenom: 'inj', - depositUrlOverride: 'https://hub.injective.network/bridge/?destination=osmosis&origin=injective&token=inj', - withdrawUrlOverride: 'https://hub.injective.network/bridge/?destination=injective&origin=osmosis&token=inj', -}, -``` - - - - - -## How to Enlist an Asset onto CoinGecko - -### Purpose - -CoinGecko ([CoinGecko.com](https://coingecko.com)) is cryptocurrency price aggregator which can provide asset price data directly to Osmosis Zone via API. Check out their [FAQ](https://www.coingecko.com/en/faq) to learn more. - -Osmosis embraces CoinGecko price feeds and uses these as a backup for pool spot prices on Osmosis Zone. If as asset is not yet registered on CoinGecko, it should aim to do so. This procedure will guide project administrators to register their Asset onto CoinGecko. - -### Prerequisites - -- Chain mainnet is live - -From [coingecko.com/en/methodology](https://www.coingecko.com/en/methodology): -- Working, functional website that has sufficient information on cryptoasset that is being listed. Websites with no information on purpose, team or social media profiles will be considered as invalid. - - Website must be owned by the project/maintaining team. Websites hosted on website builders (i.e Wix) will not be accepted. -- Working block explorer -- Listed on at least one (1) active exchanges where CoinGecko is integrated with. - - Note: Because Osmosis is integrated with CoinGecko, this will automatically be fullfilled once a Liquidity Pool containing the new Asset is created on Osmosis. - - See: [How to Add an Asset onto the Osmosis Assets Page](https://docs.osmosis.zone/overview/integrate/registration#step-3-register-an-asset-on-the-osmosis-frontend-repository) - -### Requirements - -- Asset data: - - Name (e.g., 'Cosmos Hub') - - ID (e.g., 'cosmos') - - Symbol (e.g., 'ATOM') - - Circulating Supply - - Total Supply - - Osmosis Address (i.e., the 'ibc/...' denom on Osmosis) - -### Steps - -1. Review CoinGecko's [Methodology page](https://www.coingecko.com/en/methodology) - 1. Pay special attention to the following sections: - - 'Listings', - - 'Listing Criteria', - - 'Do's and Don'ts for Listing Submission', and - - 'Listing Process Flow' -2. Fill in and submit a 'CoinGecko Request Form' (a current link can be found on their 'Methodology' page) - - -### How to Specify Asset Price Oracle on Osmosis Zone (Liquidity Pool) - -#### Purpose - -This procedure will set up the default asset pricing mechanism for an asset to show its price throughout Osmosis Zone. If a CoinGecko Price feed exists, opt to use that instead. This pricing mechanism works by fetching the current spot price of the asset from a pool with an Asset of a known price. For exampe, we might not know the price of Foo coin directly, but we can assume it's price of, say, $2.00 by seeing that it's trading at 1 FOO per 2 UST in the FOO/UST pool. - -#### Pre-requisites - -- Asset is in a Pool - - See: [Pool Setup Guide](https://docs.osmosis.zone/overview/integrate/pool-setup) -- Pool containing Asset is acceptable - - The criteria for 'acceptable' pools are *roughly* as follows: - - Contains only 2 tokens - - Contains a common Base Asset (i.e., OSMO, ATOM, or UST) - - 50/50 weighting - - 0% exit fee - - No future governor (set to blank ("")) - - 0.2-0.3% swap fee - - Sufficient liquidity (at least USD $1000-worth) - -#### Requirements - -- Pool details - - Number (Pool ID) - - Assets - - coin minimal denomination - - source channel(s) (if Asset is foreign) -- Basic understanding of GitHub, knowing how to fork, create a branch, commit changes, and submit a Pull Request - -#### Steps - -1. Review the [Osmosis Frontend Repo](https://github.com/osmosis-labs/osmosis-frontend/tree/frontier) docs: - 1. [README.md](https://github.com/osmosis-labs/osmosis-frontend/blob/master/README.md) -2. Submit a pull request branch with necessary changes to the following: - - `src/stores/root.ts` - - Specify pool under `RootStore::constructor::priceStore::queriesStore` - - `alternativeCoinId: 'pool:'` - - `poolID: '',` - - `spotPriceSourceDenom: ` - - `spotPriceDestDenom: ` - - `destCoinId: 'osmosis'` - - See examples below - - `src/config.ts` - - Add the alternative coin Id under each specification of the Asset within `EmbedChainInfos: ChainInfoWithExplorer` - - E.g., `coinGeckoId: 'pool:ugraviton'` - - Note that many assets are listed as a staking currency, a fee payment currency, and as a trading currency for a chain; the coin Id should be added to each listing of the asset - - See example below + ``` + 3. In the Pull Request, briefly describe the change, and complete the checklist as thoroughly as possible. + - New Pull Requests will automatically initialize with a description template that includes the checklist. + - Be sure to describe the plan for onchain liquidity, and provide a Pool ID once one exists. + - The PR reviewers will assist with any questions. + - If requested, a preview link to Osmosis Zone that shows the new asset can be provided. + - From the preview, a Weighted liquidity pool can be created. However, note that a Supercharged (or newer) pool type is recommended. + - Be sure to check back to the PR regularly to check for any questions, comments, and additional action items required to complete the listing process. -#### Examples -- Pool 1: -``` -{ - alternativeCoinId: 'pool:uosmo', - poolId: '1', - spotPriceSourceDenom: 'uosmo', - spotPriceDestDenom: DenomHelper.ibcDenom([{ portId: 'transfer', channelId: 'channel-0' }], 'uatom'), - destCoinId: 'cosmos', -}, -``` -- Pool 631: - - This pool contains a foreign CW20 token. Note how `cw20:` prefixes the contract address. -``` -{ - alternativeCoinId: 'pool:neta', - poolId: '631', - spotPriceSourceDenom: DenomHelper.ibcDenom( - [{ portId: 'transfer', channelId: 'channel-169' }], - 'cw20:juno168ctmpyppk90d34p3jjy658zf5a5l3w8wk35wht6ccqj4mr0yv8s4j5awr' - ), - spotPriceDestDenom: 'uosmo', - destCoinId: 'osmosis', -}, -``` -- Pool 648: - - This pool contains an IBC-multihop token. Note how all transfer paths are included. -``` -{ - alternativeCoinId: 'pool:pstake', - poolId: '648', - spotPriceSourceDenom: DenomHelper.ibcDenom( - [ - { portId: 'transfer', channelId: 'channel-4' }, - { portId: 'transfer', channelId: 'channel-38' }, - ], - 'gravity0xfB5c6815cA3AC72Ce9F5006869AE67f18bF77006' - ), - spotPriceDestDenom: 'uosmo', - destCoinId: 'osmosis', -}, -``` +## Step 3 (optional): Complete the Asset Integration -Example of osmosis-frontend/packages/web/config/chain-infos.ts::chainInfos: -- Umee chain info: - - Note that `coinGeckoId: 'pool:uumee',` is specified three times, once under each listing of the currency - - Note: once UMEE gets a listing and live price feed on CoinGecko, the values here should then be replaced with the CoinGeckoID, e.g., `coingGeckoId: 'umee'` -``` -{ - rpc: 'https://rpc.aphrodite.main.network.umee.cc', - rest: 'https://api.aphrodite.main.network.umee.cc', - chainId: 'umee-1', - chainName: 'Umee', - bip44: { - coinType: 118, - }, - bech32Config: Bech32Address.defaultBech32Config('umee'), - currencies: [ - { - coinDenom: 'UMEE', - coinMinimalDenom: 'uumee', - coinDecimals: 6, - coinGeckoId: 'pool:uumee', - coinImageUrl: window.location.origin + '/public/assets/tokens/umee.png', - isStakeCurrency: true, - isFeeCurrency: true, - }, - ], - features: ['stargate', 'ibc-transfer', 'no-legacy-stdTx'], - explorerUrlToTx: 'https://www.mintscan.io/umee/txs/{txHash}', -}, -``` +To create an ideal user experience when interacting with an Asset on Osmosios Zone, it is best to ensure that all metadata is registered, dependend data sources have all data about the asset, and that there is sufficient and efficient liquidity of the asset on Osmosis. See [LISTING.md](https://github.com/osmosis-labs/assetlists/blob/main/LISTING.md) for details.