explorer-monorepo/docs/TOKEN_LIST_IN_CHAINLIST.md

Adding Token List to Chainlist Configuration

Overview

This document explains how to add token list references to ChainID 138's Chainlist configuration.

---

Token List Support in Chainlist

Schema Status

The official Chainlist JSON schema you provided does NOT include a tokenLists field in the required or optional properties. However:

1. Chainlist may accept additional fields not in the strict schema (using additionalProperties: false might be flexible)
2. Token lists are typically separate from chain configurations
3. Some chains include token list URLs as custom properties

---

Current Token List Status

Token List Location:

• ✅ Hosted: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json
• ✅ Contains: WETH9, WETH10, ETH/USD Oracle (3 tokens)
• ✅ Format: Uniswap Token Lists Specification

---

Options for Adding Token List

Option 1: Add as Custom Field (Not in Schema)

Even though tokenLists is not in the schema, you can try adding it:

{
  "name": "DBIS Chain",
  "chain": "DBIS",
  "chainId": 138,
  "networkId": 138,
  "rpc": [
    "https://rpc-http-pub.d-bis.org",
    "https://rpc-http-prv.d-bis.org"
  ],
  "faucets": [],
  "nativeCurrency": {
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18
  },
  "infoURL": "https://d-bis.org",
  "shortName": "dbis",
  "explorers": [
    {
      "name": "Blockscout",
      "url": "https://explorer.d-bis.org",
      "standard": "EIP3091"
    }
  ],
  "icon": "https://raw.githubusercontent.com/ethereum/ethereum.org/main/static/images/eth-diamond-black.png",
  "tokenLists": [
    "https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json"
  ]
}

Pros:

• Makes token list discoverable from chainlist.org
• Users can find tokens when adding network

Cons:

• Not in official schema (may be rejected)
• Chainlist maintainers may remove it

---

Option 2: Keep Separate (Recommended)

Keep token list separate from chain configuration:

1. Chain configuration (in Chainlist):

   • Network metadata only
   • RPC URLs, explorer, currency info

2. Token list (separate):

   • Hosted at GitHub
   • Users add manually in MetaMask
   • Or linked in documentation

Pros:

• Follows standard practice
• Token lists are typically separate
• No schema conflicts

Cons:

• Less discoverable
• Users need to add token list manually

---

Option 3: Update Schema (Advanced)

If Chainlist accepts schema updates, you could propose adding tokenLists:

{
  "tokenLists": {
    "type": "array",
    "items": {
      "type": "string",
      "description": "URL to token list JSON file"
    },
    "description": "Optional array of token list URLs for this chain"
  }
}

Pros:

• Official support
• Better discoverability

Cons:

• Requires schema change approval
• Longer process

---

Recommended Approach

For Chainlist PR (Immediate)

Do NOT include tokenLists in the PR because:

1. It's not in the schema
2. Chainlist maintainers may reject it
3. Token lists are typically separate

Focus on:

• ✅ Updating RPC URLs
• ✅ Verifying explorer URL
• ✅ Ensuring all required fields are correct

For Token List Discovery

Use these methods:

1. Documentation:

   • Link token list in chain description
   • Add to infoURL website
   • Include in PR description

2. MetaMask Integration:

   • Users can add token list URL manually
   • Or use programmatic addition in dApps

3. Separate Token List Registry:

   • Submit to Uniswap Token Lists registry
   • List on token list aggregators

---

Updated chain-138.json (Without tokenLists)

Recommended for Chainlist PR:

{
  "name": "DBIS Chain",
  "chain": "DBIS",
  "rpc": [
    "https://rpc-http-pub.d-bis.org",
    "https://rpc-http-prv.d-bis.org"
  ],
  "faucets": [],
  "nativeCurrency": {
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18
  },
  "infoURL": "https://d-bis.org",
  "shortName": "dbis",
  "chainId": 138,
  "networkId": 138,
  "explorers": [
    {
      "name": "Blockscout",
      "url": "https://explorer.d-bis.org",
      "standard": "EIP3091"
    }
  ],
  "icon": "https://raw.githubusercontent.com/ethereum/ethereum.org/main/static/images/eth-diamond-black.png"
}

Note: No tokenLists field - keep it schema-compliant.

---

PR Description Template (Including Token List Info)

Even though we don't include tokenLists in the JSON, we can mention it in the PR description:

## Update ChainID 138 RPC Endpoints

### Summary
Updates RPC endpoints for ChainID 138 (DBIS Chain) to use the new public and permissioned endpoints.

### Changes
- Updated RPC URLs:
  - From: `https://rpc.defi-oracle.io`
  - To: `https://rpc-http-pub.d-bis.org`, `https://rpc-http-prv.d-bis.org`

### Token List
A token list for ChainID 138 is available at:
- **URL**: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json
- **Tokens**: WETH9, WETH10, ETH/USD Oracle
- **Format**: Uniswap Token Lists Specification

Users can add this token list in MetaMask Settings → Security & Privacy → Token Lists.

### Testing
- ✅ Verified RPC endpoints return Chain ID 138 (0x8a)
- ✅ Tested `eth_chainId` method on both endpoints
- ✅ Verified JSON schema compliance
- ✅ Validated all required fields are present

### Related
- Explorer: https://explorer.d-bis.org
- Token List: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json

---

Summary

Answer: There is NO official tokenLists field in the Chainlist schema.

Recommendation:

1. ✅ Do NOT add tokenLists to chain.json (not in schema)
2. ✅ Mention token list in PR description (for discoverability)
3. ✅ Keep token list separate (standard practice)
4. ✅ Link token list in documentation (on infoURL website)

Token List Discovery:

• Users add token list URL manually in MetaMask
• Or dApps can programmatically reference it
• Or link it in chain documentation/website

---

Last Updated: 2025-12-24 Status: Token list should be kept separate from chain configuration