Blockchain Denoms and Indexing

The application stores assets in amount/denom pairs, a bit like how the Cosmos SDK implements the Coin type.

There are 2 ways we support on-chain denoms during indexing and CSV parsing.

What is a Denom

A denom is a unit of representation of a token on a blockchain. There are usually multiple ways to represent the token, with a base being the on-chain token representation and higher exponents being used for more human-friendly representation.

For example:

1. Osmosis' native coin is the OSMO (in symbol form).
2. OSMO has a base denom of uosmo.
3. The human friendly symbol OSMO represents 10^6 uosmo.

The blockchain does not store tokens in symbol form, relying on the base uosmo for all token storage.

How do we use Denoms?

We use denoms to convert from the base to the symbol at CSV generation time. We store tokens in a coin/base denom pair throughout our database. When a CSV is generated, we need the Symbol (usually) and the 10^6 amount representation for use in various output formats.

Methods for Gathering Denom Data

We use 2 methods for gathering and indexing denom data. One is a built-in method that is intended to work for all blockchains (but is unreliable, explained below). The second is chain-specific.

Cosmos SDK Bank Module Denom Metadata

The Cosmos SDK bank module provides the denom-metadata query for querying denoms. This endpoint will gather the denoms stored in the bank module KV Store.

This endpoint returns denoms in a list like so:

{
  "metadatas": [
    {
      "description": "",
      "denom_units": [
        {
          "denom": "<base>",
          "exponent": 0,
          "aliases": [
            ""
          ]
        },
        {
          "denom": "<human readable>",
          "exponent": 6,
          "aliases": [
            ""
          ]
        }
      ],
      "base": "<base>",
      "display": "",
      "name": "",
      "symbol": "<symbol>"
    }
]

We use this endpoint in the basic Denom Update task, hoping to rely on this endpoint long-term to get on chain denom representations.

Unfortunately, this endpoint is unreliable. It does not always return all the denoms found on a blockchain. From a bit of research done, it seems like the data store for this requires blockchain developers to include the base denoms manually instead of indexing all denoms found on chain.

Developer Maintained Asset Lists

As a fallback, we also rely on chain-specific asset lists maintained by blockchain developers. Various repositories contain these asset lists, but you can find an example of them at the Cosmos Chain Registry repo:

1. Base repo - https://github.com/cosmos/chain-registry
2. An example of an asset list (Juno) - https://github.com/cosmos/chain-registry/blob/master/juno/assetlist.json

The Cosmos Chain Registry is defining standards for these lists and maintaining them across the ecosystem.

We parse these lists per-chain when indexing. While unwieldy since we are relying on external maintainers of the lists, this process has proven more reliable to fill our indexer with denom data.