Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/CHAINLIST_METAMASK_BLOCKSCOUT_RELATIONSHIP.md
+++ b/docs/CHAINLIST_METAMASK_BLOCKSCOUT_RELATIONSHIP.md
@@ -0,0 +1,288 @@
+# Chainlist, MetaMask, and Blockscout Relationship for ChainID 138
+
+## 🎯 Quick Answer
+
+**Where does ChainID 138 metadata live for MetaMask?**
+
+1. **Chainlist.org** (Primary) - Network metadata (RPC URLs, explorer, chain name)
+   - **Status**: ⚠️ **NOT YET SUBMITTED** to Chainlist.org
+   - **Local File**: `token-lists/chainlists/chain-138.json`
+   - **Location**: Should be at `https://chainlist.org` after submission
+
+2. **RPC Endpoint** (VMID 2500) - Blockchain data only
+   - **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)
+   - **Provides**: Chain ID verification (`eth_chainId` → `0x8a`)
+   - **Does NOT Provide**: Network name, currency symbol, explorer URL
+
+3. **Blockscout** (VMID 5000) - Block explorer and API
+   - **Location**: `https://explorer.d-bis.org`
+   - **Role**: Referenced in chainlist config as the explorer
+   - **Does NOT Provide**: Chain metadata or chainlist data
+
+4. **Token Lists** (GitHub) - Token metadata
+   - **Local File**: `token-lists/lists/dbis-138.tokenlist.json`
+   - **Status**: ✅ **HOSTED** at: https://raw.githubusercontent.com/Defi-Oracle-Meta-Blockchain/metamask-integration/main/config/token-list.json
+   - **Purpose**: Token names, symbols, decimals, logos
+
+---
+
+## 📊 Data Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    MetaMask Wallet                           │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │ Network Info │  │ Token Lists  │  │  Explorer    │     │
+│  │ (from        │  │ (from        │  │  (from       │     │
+│  │  Chainlist)  │  │  Token List) │  │  Blockscout) │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
+│  Chainlist.org  │  │  Token List    │  │   Blockscout    │
+│                 │  │  (GitHub)     │  │   (VMID 5000)   │
+│  - RPC URLs     │  │                │  │                 │
+│  - Chain Name   │  │  - WETH9       │  │  - Block API    │
+│  - Explorer URL │  │  - WETH10      │  │  - Tx API       │
+│  - Currency     │  │  - Oracle      │  │  - Address API  │
+└─────────────────┘  └─────────────────┘  └─────────────────┘
+         │                    │                    │
+         │                    │                    │
+         └────────────────────┴────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │   RPC Node      │
+                    │   (VMID 2500)   │
+                    │                 │
+                    │  - eth_chainId │
+                    │  - eth_balance │
+                    │  - eth_call     │
+                    │  - eth_sendTx  │
+                    └─────────────────┘
+```
+
+---
+
+## 🔍 Detailed Breakdown
+
+### 1. Chainlist.org - The Source of Truth
+
+**What It Is**: Public registry of EVM networks that MetaMask uses to discover networks
+
+**Current Status for ChainID 138**:
+- ✅ Configuration file exists: `token-lists/chainlists/chain-138.json`
+- ❌ **NOT YET SUBMITTED** to Chainlist.org
+- ❌ ChainID 138 does NOT appear on chainlist.org yet
+
+**What's in chain-138.json**:
+```json
+{
+  "name": "DBIS Chain",
+  "chainId": 138,
+  "rpc": [
+    "https://rpc-http-pub.d-bis.org",
+    "https://rpc-http-prv.d-bis.org"
+  ],
+  "explorers": [{
+    "name": "Blockscout",
+    "url": "https://explorer.d-bis.org",  ← Blockscout URL here
+    "standard": "EIP3091"
+  }],
+  "nativeCurrency": {
+    "name": "Ether",
+    "symbol": "ETH",
+    "decimals": 18
+  }
+}
+```
+
+**How MetaMask Uses It**:
+1. User visits chainlist.org
+2. Searches for "DBIS" or "138"
+3. Clicks "Add to MetaMask"
+4. MetaMask reads the JSON config
+5. Network is added with all settings
+
+**Key Point**: Blockscout is **referenced** in the chainlist config, but Blockscout itself doesn't provide the chainlist data.
+
+---
+
+### 2. RPC Endpoint - Blockchain Data Provider
+
+**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)
+
+**What RPC Provides**:
+- ✅ Chain ID: `eth_chainId` → Returns `0x8a` (138 in hex)
+- ✅ Block data: `eth_getBlockByNumber`
+- ✅ Transaction data: `eth_getTransactionByHash`
+- ✅ Account balances: `eth_getBalance`
+- ✅ Contract calls: `eth_call`
+- ✅ Transaction submission: `eth_sendTransaction`
+
+**What RPC Does NOT Provide**:
+- ❌ Network name ("DBIS Chain")
+- ❌ Currency symbol ("ETH")
+- ❌ Block explorer URL
+- ❌ Token lists
+- ❌ Chain metadata
+
+**Key Point**: RPC only provides **blockchain data**, not **network metadata**. MetaMask needs chainlist to know the network name and other metadata.
+
+---
+
+### 3. Blockscout - Block Explorer
+
+**Location**: `https://explorer.d-bis.org` (VMID 5000)
+
+**What Blockscout Provides**:
+- ✅ Block explorer UI
+- ✅ API endpoints: `/api/v2/blocks`, `/api/v2/transactions`, `/api/v2/addresses`
+- ✅ Token information: `/api/v2/tokens`
+- ✅ Stats: `/api/v2/stats`
+
+**What Blockscout Does NOT Provide**:
+- ❌ Chain metadata (name, RPC URLs, etc.)
+- ❌ Chainlist configuration
+- ❌ Token lists (Uniswap format)
+
+**How Blockscout Relates to Chainlist**:
+1. Blockscout URL is **stored in** `chain-138.json` as the explorer
+2. When MetaMask adds the network, it uses this URL for "View on Explorer"
+3. Blockscout itself doesn't know about chainlist or provide chain metadata
+
+**Blockscout Token Data**:
+- Blockscout has token data in its database (from indexing)
+- Format: Blockscout API format (different from Uniswap token list format)
+- Example: `/api/v2/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
+
+**Key Point**: Blockscout is the **explorer**, not the **source of chain metadata**. It's referenced in chainlist, but doesn't provide chainlist data.
+
+---
+
+### 4. Token Lists - Token Metadata
+
+**Location**: 
+- Local: `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
+
+**What Token Lists Provide**:
+- ✅ Token names (e.g., "Wrapped Ether")
+- ✅ Token symbols (e.g., "WETH")
+- ✅ Decimals (e.g., 18)
+- ✅ Logo URLs
+- ✅ Token tags/categories
+
+**Current Tokens in List**:
+1. WETH9: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
+2. WETH10: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
+3. ETH/USD Oracle: `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`
+
+**How MetaMask Uses It**:
+1. User adds token list URL in MetaMask Settings
+2. MetaMask fetches the JSON file
+3. Tokens appear automatically when on ChainID 138
+4. Token balances come from RPC, metadata from token list
+
+**Key Point**: Token lists are **separate** from chain metadata. They provide token information, not network information.
+
+---
+
+## 🔗 How They Work Together
+
+### Scenario 1: User Adds Network to MetaMask
+
+**Without Chainlist Submission** (Current):
+```
+User → MetaMask → Add Network Manually
+  → Enters: RPC URL, Chain ID, Network Name, Explorer URL
+  → MetaMask connects to RPC (http://192.168.11.250:8545)
+  → Verifies Chain ID matches (0x8a)
+  → Stores network config locally
+  → Uses Blockscout URL for "View on Explorer"
+```
+
+**With Chainlist Submission** (Future):
+```
+User → chainlist.org → Search "DBIS" → Click "Add to MetaMask"
+  → MetaMask reads chain-138.json from Chainlist
+  → Adds network with all settings
+  → Connects to RPC (https://rpc-http-pub.d-bis.org)
+  → Verifies Chain ID matches
+  → Uses Blockscout URL from chainlist config
+```
+
+### Scenario 2: User Views Transaction
+
+```
+User → MetaMask → Click "View on Explorer"
+  → MetaMask opens: https://explorer.d-bis.org/tx/{hash}
+  → Blockscout displays transaction details
+  → Blockscout API provides the data
+```
+
+### Scenario 3: User Sees Token Balance
+
+```
+User → MetaMask → View Token Balance
+  → Token metadata (name, symbol, logo) from Token List
+  → Token balance from RPC (eth_call to token contract)
+  → Click "View on Explorer" → Opens Blockscout
+```
+
+---
+
+## 📍 Where Each Piece Lives
+
+| Component | Location | Status | Purpose |
+|-----------|----------|--------|---------|
+| **Chain Metadata** | Chainlist.org | ❌ Not submitted | Network name, RPC URLs, explorer |
+| **Chain Config File** | `token-lists/chainlists/chain-138.json` | ✅ Ready | Local copy, needs submission |
+| **RPC Endpoint** | VMID 2500 (port 8545) | ✅ Running | Blockchain data |
+| **Blockscout** | VMID 5000 (port 4000) | ✅ Running | Block explorer |
+| **Token List** | `token-lists/lists/dbis-138.tokenlist.json` | ✅ Ready | Token metadata |
+| **Token List URL** | (Not yet hosted) | ❌ Missing | Public URL for MetaMask |
+
+---
+
+## 🎯 Key Takeaways
+
+1. **Chainlist.org is the primary source** for network metadata that MetaMask uses
+2. **RPC provides blockchain data**, not network metadata
+3. **Blockscout is referenced** in chainlist as the explorer, but doesn't provide chain metadata
+4. **Token lists are separate** from chain metadata and provide token information
+5. **ChainID 138 is NOT yet on Chainlist.org** - needs to be submitted
+6. **Token list is NOT yet hosted** - needs public URL
+
+---
+
+## 🚀 Next Steps to Complete Integration
+
+1. **Submit to Chainlist.org**
+   - Fork https://github.com/ethereum-lists/chains
+   - Add `chain-138.json` to repository
+   - Create pull request
+   - Once merged, ChainID 138 will be discoverable
+
+2. **Host Token List**
+   - Deploy `dbis-138.tokenlist.json` to public URL
+   - Options: GitHub Pages, GitHub Raw, or custom domain
+   - Add URL to MetaMask Settings → Token Lists
+
+3. **Link Token List in Chainlist** (Optional)
+   - Add `tokenLists` field to `chain-138.json`
+   - Users can discover tokens when adding network
+
+---
+
+**Last Updated**: 2025-12-24
+**Status**: Analysis Complete
+