# Chainlist and MetaMask Data Flow for ChainID 138

## Overview

This document explains how ChainID 138 metadata flows from various sources to MetaMask, and how Blockscout and the RPC endpoint relate to this data feed.

---

## 🔄 Data Flow Architecture

```
┌─────────────────┐
│  Chainlist.org  │ ← Public registry (chainlist.org)
│  (Chainlists)   │   - Chain metadata (RPC URLs, explorer, etc.)
└────────┬────────┘   - Token lists (optional)
         │
         │ MetaMask fetches from chainlist.org
         │
         ▼
┌─────────────────┐
│    MetaMask     │
│   (User Wallet) │
└────────┬────────┘
         │
         │ Uses RPC to query blockchain
         │ Uses Blockscout API for explorer data
         │
         ├─────────────────┬──────────────────┐
         │                 │                  │
         ▼                 ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  RPC Node    │  │  Blockscout  │  │ Token Lists  │
│ (VMID 2500)  │  │  (VMID 5000) │  │  (GitHub)    │
│              │  │              │  │              │
│ Port 8545    │  │ Port 4000    │  │ Public URL   │
│ (HTTP)       │  │ (HTTP)       │  │              │
│ Port 8546    │  │              │  │              │
│ (WebSocket)  │  │              │  │              │
└──────────────┘  └──────────────┘  └──────────────┘
```

---

## 📍 Where ChainID 138 Metadata Resides

### 1. **Chainlist.org (Primary Source for MetaMask)**

**Location**: `https://chainlist.org`

**Purpose**: Public registry that MetaMask uses to discover and add networks

**Current Status**: 
- ⚠️ **NOT YET SUBMITTED** to Chainlist.org
- Chain configuration exists locally: `token-lists/chainlists/chain-138.json`

**File**: `/home/intlc/projects/proxmox/token-lists/chainlists/chain-138.json`

```json
{
  "name": "DBIS Chain",
  "chain": "DBIS",
  "rpc": [
    "https://rpc-http-pub.d-bis.org",
    "https://rpc-http-prv.d-bis.org"
  ],
  "chainId": 138,
  "networkId": 138,
  "explorers": [{
    "name": "Blockscout",
    "url": "https://explorer.d-bis.org",
    "standard": "EIP3091"
  }],
  "nativeCurrency": {
    "name": "Ether",
    "symbol": "ETH",
    "decimals": 18
  }
}
```

**Note**: 
- `https://rpc-http-pub.d-bis.org` - **Public RPC** (for general use, MetaMask, dApps)
- `https://rpc-http-prv.d-bis.org` - **Permissioned RPC** (for authorized/private access)
- `https://rpc-core.d-bis.org` - **Internal only** (not public, VMID 2500)

**How MetaMask Uses It**:
1. User searches for "DBIS" or "138" on chainlist.org
2. Clicks "Add to MetaMask" button
3. MetaMask reads the chain configuration
4. Adds network to user's MetaMask with RPC URLs, explorer, etc.

**Submission Status**: 
- ✅ Configuration file ready
- ❌ Not yet submitted to Chainlist.org
- 📋 See: `token-lists/chainlists/SUBMISSION_GUIDE.md`

---

### 2. **RPC Endpoint (VMID 2500)**

**Location**: 
- Internal: `http://192.168.11.250:8545` (VMID 2500 - internal only, not public)
- Public: `https://rpc-http-pub.d-bis.org` (public RPC endpoint)
- Permissioned: `https://rpc-http-prv.d-bis.org` (permissioned/private RPC endpoint)

**Purpose**: Provides blockchain data via JSON-RPC

**What MetaMask Queries**:
- `eth_chainId` → Returns `0x8a` (138 in hex)
- `eth_blockNumber` → Latest block number
- `eth_getBalance` → Account balances
- `eth_sendTransaction` → Submit transactions
- `eth_call` → Read contract state
- `eth_getBlockByNumber` → Block data

**RPC Endpoints**:
- **Public RPC**: `https://rpc-http-pub.d-bis.org` - For general use, MetaMask, dApps
- **Permissioned RPC**: `https://rpc-http-prv.d-bis.org` - For authorized/private access
- **Internal RPC**: `http://192.168.11.250:8545` - Internal network only (VMID 2500)

**Chain Metadata from RPC**:
- ✅ Chain ID: 138 (0x8a) - **VERIFIED**
- ✅ Network ID: 138
- ⚠️ **RPC does NOT provide**:
  - Network name
  - Native currency symbol
  - Block explorer URL
  - Token lists

**Key Point**: RPC only provides **blockchain data**, not **network metadata**. MetaMask needs the chainlist configuration to know the network name, currency symbol, and explorer URL.

---

### 3. **Blockscout (VMID 5000)**

**Location**: `https://explorer.d-bis.org`

**Purpose**: Block explorer and API for transaction/block/address data

**What Blockscout Provides**:
- ✅ Block data via `/api/v2/blocks`
- ✅ Transaction data via `/api/v2/transactions`
- ✅ Address data via `/api/v2/addresses`
- ✅ Token data via `/api/v2/tokens`
- ✅ Stats via `/api/v2/stats`

**What Blockscout Does NOT Provide**:
- ❌ Chain metadata (name, RPC URLs, etc.)
- ❌ Token lists (Uniswap format)
- ❌ Chainlist configuration

**Key Point**: Blockscout is referenced in the chainlist configuration as the **block explorer**, but Blockscout itself doesn't store or provide the chainlist metadata.

**Blockscout's Role**:
1. Referenced in `chain-138.json` as the explorer URL
2. MetaMask uses this URL when user clicks "View on Explorer"
3. Provides transaction/block/address data via API
4. Can be queried for token information, but not in chainlist format

---

### 4. **Token Lists (GitHub/Public URL)**

**Location**: 
- Local: `/home/intlc/projects/proxmox/token-lists/lists/dbis-138.tokenlist.json`
- Public: ✅ **HOSTED** at https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json

**Purpose**: Token metadata for MetaMask token discovery

**Current Tokens**:
1. WETH9 (`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`)
2. WETH10 (`0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`)
3. ETH/USD Price Feed (`0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`)

**How MetaMask Uses It**:
1. User adds token list URL in MetaMask Settings → Security & Privacy → Token Lists
2. MetaMask fetches the JSON file
3. Tokens appear automatically in MetaMask when on ChainID 138
4. Token balances are fetched via RPC, but metadata (name, symbol, decimals, logo) comes from token list

**Current Status**:
- ✅ Token list file exists
- ✅ **Hosted at public URL**: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json
- ⚠️ Not yet linked in chainlist configuration (optional)

---

## 🔍 How MetaMask Discovers ChainID 138

### Current Flow (Without Chainlist Submission)

1. **Manual Addition** (Current Method):
   ```
   User → MetaMask → Add Network → Enter details manually
   - Network Name: SMOM-DBIS-138
   - RPC URL: https://rpc-http-pub.d-bis.org
   - Chain ID: 138
   - Currency Symbol: ETH
   - Block Explorer: https://explorer.d-bis.org
   ```

2. **Programmatic Addition** (dApp Method):
   ```javascript
   await window.ethereum.request({
     method: 'wallet_addEthereumChain',
     params: [{
       chainId: '0x8a',
       chainName: 'SMOM-DBIS-138',
       rpcUrls: ['https://rpc-http-pub.d-bis.org'],
       blockExplorerUrls: ['https://explorer.d-bis.org'],
       nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 }
     }]
   });
   ```

### Future Flow (After Chainlist Submission)

1. **Automatic Discovery**:
   ```
   User → chainlist.org → Search "DBIS" or "138" → Click "Add to MetaMask"
   → MetaMask reads chain-138.json from Chainlist repository
   → Network added automatically
   ```

2. **Token List Integration**:
   ```
   User → MetaMask Settings → Token Lists → Add URL
   → MetaMask fetches dbis-138.tokenlist.json
   → Tokens appear automatically
   ```

---

## 📊 Data Sources Comparison

| Data Type | Source | Location | MetaMask Usage |
|-----------|--------|----------|----------------|
| **Chain ID** | RPC | `eth_chainId` | Verify correct network |
| **Network Name** | Chainlist | `chain-138.json` | Display in UI |
| **RPC URLs** | Chainlist | `chain-138.json` | Connect to blockchain |
| **Block Explorer** | Chainlist | `chain-138.json` | "View on Explorer" link |
| **Native Currency** | Chainlist | `chain-138.json` | Display ETH symbol |
| **Token Metadata** | Token List | `dbis-138.tokenlist.json` | Token names, symbols, logos |
| **Token Balances** | RPC | `eth_call` to token contract | Display balances |
| **Block Data** | Blockscout API | `/api/v2/blocks` | Explorer view |
| **Transaction Data** | Blockscout API | `/api/v2/transactions` | Explorer view |

---

## 🔗 Relationships

### Chainlist ↔ MetaMask
- **Chainlist.org** is the **primary source** for network metadata
- MetaMask queries Chainlist.org to discover networks
- Once added, MetaMask stores network config locally

### RPC ↔ MetaMask
- **RPC endpoint** provides **blockchain data**
- MetaMask uses RPC for all blockchain queries
- RPC validates Chain ID matches expected value

### Blockscout ↔ Chainlist
- **Blockscout** is **referenced** in chainlist config as explorer
- Blockscout does NOT provide chainlist data
- Blockscout provides explorer API for viewing transactions/blocks

### Token List ↔ MetaMask
- **Token list** provides **token metadata** (name, symbol, decimals, logo)
- MetaMask fetches token list from public URL
- Token balances come from RPC, metadata from token list

---

## 🎯 Key Insights

### 1. **Chainlist is the Source of Truth for Network Metadata**

- Chainlist.org is where MetaMask looks for network information
- RPC only provides blockchain data, not network metadata
- Blockscout is just referenced as the explorer, doesn't provide chain metadata

### 2. **RPC Provides Blockchain Data, Not Metadata**

- RPC can tell you the Chain ID (`eth_chainId` → `0x8a`)
- RPC cannot tell you the network name, currency symbol, or explorer URL
- This metadata must come from Chainlist or manual entry

### 3. **Blockscout is Referenced, Not a Source**

- Blockscout URL is stored in chainlist config
- MetaMask uses this URL for "View on Explorer" functionality
- Blockscout itself doesn't know about chainlist or provide chain metadata

### 4. **Token Lists are Separate from Chain Metadata**

- Token lists provide token metadata (name, symbol, decimals, logo)
- Chain metadata provides network information (RPC, explorer, currency)
- Both are needed for full MetaMask integration

---

## 📝 Current Status

### ✅ Completed
- [x] Chain configuration file (`chain-138.json`)
- [x] Token list file (`dbis-138.tokenlist.json`)
- [x] RPC endpoint configured and working
- [x] Blockscout explorer running and accessible
- [x] MetaMask network config JSON file

### ❌ Missing
- [ ] **Chainlist.org submission** (chain-138.json not yet on Chainlist)
- [x] **Public token list URL** ✅ Hosted at: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json
- [ ] **Token list linked in chainlist config** (optional but recommended)

---

## 🚀 Next Steps

### 1. Submit to Chainlist.org

**Action**: Submit `chain-138.json` to Chainlist repository

**Steps**:
1. Fork https://github.com/ethereum-lists/chains
2. Copy `chain-138.json` to `_data/chains/eip155-138/chain.json`
3. Create pull request
4. Once merged, ChainID 138 will appear on chainlist.org

**Impact**: 
- Users can discover ChainID 138 on chainlist.org
- "Add to MetaMask" button will work automatically
- Network will be searchable

### 2. Host Token List Publicly

**Action**: Host `dbis-138.tokenlist.json` at public URL

**Current URL**: 
- ✅ **Already Hosted**: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json

**Alternative Options** (if needed):
- GitHub Pages: `https://{user}.github.io/{repo}/token-lists/lists/dbis-138.tokenlist.json`
- Custom domain: `https://tokens.d-bis.org/lists/dbis-138.tokenlist.json`

**Impact**:
- Users can add token list URL in MetaMask
- Tokens will appear automatically
- Token metadata (logos, names) will be available

### 3. Link Token List in Chainlist (Optional)

**Action**: Add token list URL to chain-138.json

**Update**:
```json
{
  "name": "DBIS Chain",
  ...
  "tokenLists": [
    "https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json"
  ]
}
```

**Impact**:
- Token list will be discoverable from chainlist.org
- Users can add tokens when adding network

---

## 🔍 Verification Commands

### Check RPC Chain ID
```bash
# Public RPC
curl -X POST https://rpc-http-pub.d-bis.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# Should return: {"result":"0x8a"}

# Internal RPC (VMID 2500)
curl -X POST http://192.168.11.250:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
# Should return: {"result":"0x8a"}
```

### Check Blockscout API
```bash
curl -s "https://explorer.d-bis.org/api/v2/stats" | jq '.chain_id'
# Should return: 138 (if available)
```

### Check Chainlist Status
```bash
# Check if ChainID 138 exists on Chainlist
curl -s "https://chainlist.org/api/v1/chains/138" | jq '.'
# Currently returns: 404 (not yet submitted)
```

---

## 📚 References

- **Chainlist Repository**: https://github.com/ethereum-lists/chains
- **Chainlist Website**: https://chainlist.org
- **Uniswap Token Lists**: https://github.com/Uniswap/token-lists
- **EIP-155**: Chain ID specification
- **EIP-3091**: Block Explorer API standard
- **MetaMask Docs**: https://docs.metamask.io/guide/ethereum-provider.html

---

**Last Updated**: 2025-12-24
**Status**: Analysis Complete - Ready for Chainlist Submission

