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:

```json
{
  "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`:

```json
{
  "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**:

```json
{
  "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:

```markdown
## 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