Explanation of Processing adamant-wallets (all coin information for ADAMANT client applications)

[metalisk]

adamant-wallets consolidates all coin information for ADAMANT client applications.
This document explains how to create coins/tokens and how values for tokens across different blockchains are merged inside client apps.

The client app is responsible for correctly processing adamant-wallets, providing developers with a convenient, unified data structure.

The proposed structure of adamant-wallets is not perfect (because token information is merged from different folders), but alternatives have their own trade-offs. That’s why we describe it as is — no structural changes are proposed.

📖 Read also: adamant-wallets README

Terminology

• Crypto — a general term which includes both coins and tokens.
  Each crypto has:

  • Name (e.g., Bitcoin)
  • Ticker / Symbol (e.g., BTC)

• Coin — a crypto that exists on its own blockchain (chain).
  Examples: ADM, BTC, DOGE, DASH, KLY

• Token — a crypto that exists on some blockchain.

  • Examples of blockchains: Ethereum, Binance Smart Chain
  • Examples of tokens: STORJ, USDT

• Main Coin — every blockchain has one.
  It shares common properties for all tokens on the chain and is used to pay fees for token transfers.

  • Ethereum → ETH
  • Binance Smart Chain → BNB
  • Example: USDT on Ethereum pays transfer fees in ETH.

• Token Type per Blockchain

  • Ethereum → ERC20
  • Binance Smart Chain → BEP20

• Multi-chain Tokens — a token may exist on multiple blockchains.
  Example:

  • USDT on Ethereum → ERC20
  • USDT on Binance Smart Chain → BEP20
    It’s the same token with the same value and general info, but stored and transferred on different chains.

Basic Structure of adamant-wallets

• Each crypto exists in /general folder.
• Tokens additionally exist in /blockchains folder.

Example:

• /general/USDT/info.json — general info about USDT
• /blockchains/ethereum/USDT/info.json — USDT on Ethereum

The /blockchains/{chain}/info.json file:

• Stores chain-specific shared info for all tokens on this chain
• Defines the “main coin” link with base properties

Property Sources for a Token

Any token on any blockchain has four sources of properties.
They are merged in the following priority (from high → low):

1. /blockchains/ethereum/USDT/info.json — specific token on specific blockchain
2. /blockchains/ethereum/info.json — shared token info for this blockchain
3. /general/ethereum/info.json — info from blockchain’s main coin
4. /general/USDT/info.json — general token info

Example: USDT on Ethereum merges all of these, with (1) overriding (2), etc.

Creating Coins and Tokens in Apps

Create Coins

1. Loop through all cryptos in /general.
2. Read /general/{crypto}/info.json.
   • Skip if status is not active.
   • Skip if type is not coin.
3. If createCoin = true, create a coin.
   • Display it as “Blockchain” (no token type).
   • Examples: ADM, BTC.

Create Tokens

1. Loop through all blockchains in /blockchains.
   • Examples: /blockchains/ethereum, /blockchains/binanceSmartChain
2. Read (1) /blockchains/{blockchain}/info.json.
   • Skip blockchain if its status is not active.
   • Note mainCoin.
3. Read (2) /general/{mainCoin}/info.json.
4. Loop through all tokens in {blockchain} (e.g., USDT, STORJ).
   • Read (3) /general/{token}/info.json.
     • If missing → skip token.
     • Ensure type = token.
   • Read (4) /blockchains/{blockchain}/{token}/info.json.
   • Skip if status is not active.
5. Merge (1 + 2 + 3 + 4) according to priority.
6. Create token object.
   • Display with token type (“ERC20”, “BEP20”).
   • Examples: USDT, USDC, DAI.

Data Object for a Crypto

After parsing adamant-wallets, the app holds a data object with info on all coins and tokens across chains.
Because properties are already merged, retrieving data is convenient:

// Inside token-related methods
let property = coinInfo.property

// Outside, referencing by token and chain
let property = coinInfo["USDT"]["ethereum"].property

✅ This ensures ADAMANT apps can handle multiple blockchains and tokens consistently.

[dev-adamant-im]

Thanks for the detailed explanation of how adamant-wallets consolidates and merges crypto information for ADAMANT apps.

I see several important points here:

• Unified structure for apps. Even though the merging rules may look a bit complex at first (priority from specific token → chain info → main coin → general info), in practice this gives client apps a ready-to-use object without extra logic on the app side. That’s a big advantage for consistency across different platforms (PWA, iOS, Android).
• Trade-offs of current design. You mention that the structure is “not perfect” because tokens exist both in /general and /blockchains. That’s true — duplication is visible, but it solves a real problem: keeping blockchain-specific details (like gas coin or token type) while also reusing general info. If we moved to a purely normalized model, client apps would become more complicated. So the current compromise is pragmatic.
• Multi-chain tokens. The merging model is especially important here. USDT is a good example: different chains, same token identity. With the 4-level priority system, we can keep both shared token properties (name, symbol, decimals) and chain-specific ones (contract address, type = ERC20/BEP20). This is critical for UX, because users expect “the same USDT” across chains, while the app must know the technical differences.
• Developer experience. The final merged data object is very convenient: coinInfo["USDT"]["ethereum"].property, means no need for app developers to manually check multiple JSON files or merge properties themselves. That reduces bugs and makes integration of new coins/tokens faster.

[al-onyxprotocol]

The multi-chain token handling is indeed the strongest point. Having a unified identity for tokens like USDT while still carrying chain-specific details is exactly what users expect, and it gives developers a predictable way to access those details without reinventing merging logic.

All in all, the model may not be mathematically perfect, but it’s pragmatic and developer-friendly — and that’s what matters most for consistent UX across platforms.