Complete markdown files cleanup and organization
- Organized 252 files across project - Root directory: 187 → 2 files (98.9% reduction) - Moved configuration guides to docs/04-configuration/ - Moved troubleshooting guides to docs/09-troubleshooting/ - Moved quick start guides to docs/01-getting-started/ - Moved reports to reports/ directory - Archived temporary files - Generated comprehensive reports and documentation - Created maintenance scripts and guides All files organized according to established standards.
This commit is contained in:
defiQUG
161
docs/11-references/76.53.10.34_CONNECTION_EXPLANATION.md
Normal file
161
docs/11-references/76.53.10.34_CONNECTION_EXPLANATION.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 76.53.10.34:8545 Connection Refused - Explanation
|
||||
|
||||
**Date**: 2026-01-04
|
||||
**Issue**: Connection to `76.53.10.34:8545` is being refused
|
||||
**Status**: ✅ **EXPECTED BEHAVIOR** (This is not an error)
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Why Connection is Refused
|
||||
|
||||
### IP Address Identity
|
||||
|
||||
**`76.53.10.34`** is the **ER605 router's WAN IP address**, not an RPC service endpoint.
|
||||
|
||||
- **Device**: TP-Link ER605 v2.20 (er605-1)
|
||||
- **Role**: Primary Edge Router (WAN interface)
|
||||
- **Network**: Public WAN IP (Block #1: 76.53.10.32/28)
|
||||
- **Gateway**: 76.53.10.33
|
||||
|
||||
### Why Port 8545 is Not Available
|
||||
|
||||
1. **Router Functionality**: Routers forward traffic, they don't host services on port 8545
|
||||
2. **No RPC Service**: The ER605 router does not run a blockchain RPC service
|
||||
3. **Port Not Forwarded**: Even if an RPC service existed internally, port 8545 is not forwarded from the router's WAN interface to any internal service
|
||||
|
||||
---
|
||||
|
||||
## ✅ Correct RPC Endpoints
|
||||
|
||||
### Internal Network RPC Endpoints
|
||||
|
||||
These are accessible from within the internal network (192.168.11.0/24):
|
||||
|
||||
| VMID | IP Address | Port | Service | Purpose |
|
||||
|------|------------|------|---------|---------|
|
||||
| 2500 | 192.168.11.250 | 8545 | Besu HTTP RPC | Primary RPC node |
|
||||
| 2500 | 192.168.11.250 | 8546 | Besu WebSocket RPC | Primary RPC node (WS) |
|
||||
| 2501 | 192.168.11.251 | 8545 | Besu HTTP RPC | Permissioned RPC node |
|
||||
| 2502 | 192.168.11.252 | 8545 | Besu HTTP RPC | Public RPC node |
|
||||
|
||||
**Example Internal Access**:
|
||||
```bash
|
||||
# From internal network
|
||||
curl -X POST http://192.168.11.250:8545 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
|
||||
```
|
||||
|
||||
### Public RPC Endpoints
|
||||
|
||||
These are accessible from the public internet via Cloudflare:
|
||||
|
||||
| Domain | Type | Authentication | Routing |
|
||||
|--------|------|----------------|---------|
|
||||
| `https://rpc-http-pub.d-bis.org` | HTTP RPC | ❌ No Auth | Cloudflare → Tunnel → VMID 2502 |
|
||||
| `https://rpc-ws-pub.d-bis.org` | WebSocket RPC | ❌ No Auth | Cloudflare → Tunnel → VMID 2502 |
|
||||
| `https://rpc-http-prv.d-bis.org` | HTTP RPC | ✅ JWT Required | Cloudflare → Tunnel → VMID 2501 |
|
||||
| `https://rpc-ws-prv.d-bis.org` | WebSocket RPC | ✅ JWT Required | Cloudflare → Tunnel → VMID 2501 |
|
||||
|
||||
**Example Public Access**:
|
||||
```bash
|
||||
# Public endpoint (no authentication)
|
||||
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}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Network Architecture
|
||||
|
||||
### Request Flow for Public RPC Access
|
||||
|
||||
```
|
||||
Internet Client
|
||||
↓
|
||||
Cloudflare DNS (rpc-http-pub.d-bis.org)
|
||||
↓
|
||||
Cloudflare Edge (SSL Termination, DDoS Protection)
|
||||
↓
|
||||
Cloudflared Tunnel (VMID 102: 192.168.11.9)
|
||||
↓
|
||||
Nginx Proxy (VMID 2502: 192.168.11.252:443)
|
||||
↓
|
||||
Besu RPC Service (VMID 2502: 192.168.11.252:8545)
|
||||
```
|
||||
|
||||
**Important**: Traffic does NOT go through the router's WAN IP (`76.53.10.34`) for RPC services. It goes through Cloudflare Tunnel, which bypasses the router's WAN interface.
|
||||
|
||||
### Why Router WAN IP is Not Used
|
||||
|
||||
1. **Cloudflare Tunnel**: Public services use Cloudflare Tunnel (VMID 102) which creates an encrypted connection directly from Cloudflare to internal services
|
||||
2. **No Port Forwarding Needed**: Tunnel bypasses the need for port forwarding on the router
|
||||
3. **Security**: Tunnel provides better security than exposing ports directly on the router's WAN interface
|
||||
4. **DDoS Protection**: Cloudflare provides DDoS protection before traffic reaches internal network
|
||||
|
||||
---
|
||||
|
||||
## 🔧 If You Need to Access RPC from External Network
|
||||
|
||||
### Option 1: Use Public Endpoints (Recommended)
|
||||
|
||||
Use the public domain names that route through Cloudflare:
|
||||
|
||||
```bash
|
||||
# Public RPC (no authentication)
|
||||
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}'
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"result": "0x8a"
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Connect to Internal Network First
|
||||
|
||||
If you're on the internal network (192.168.11.0/24), use internal IPs:
|
||||
|
||||
```bash
|
||||
curl -X POST http://192.168.11.250:8545 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'
|
||||
```
|
||||
|
||||
### Option 3: VPN Access (If Available)
|
||||
|
||||
If VPN access is configured, connect to VPN first, then use internal IPs.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Summary
|
||||
|
||||
| Item | Value |
|
||||
|------|-------|
|
||||
| **76.53.10.34** | ER605 Router WAN IP (not an RPC service) |
|
||||
| **Connection Refused** | ✅ Expected (router doesn't host RPC service) |
|
||||
| **Internal RPC** | `192.168.11.250:8545` (and other RPC nodes) |
|
||||
| **Public RPC** | `https://rpc-http-pub.d-bis.org` (via Cloudflare) |
|
||||
| **Router Role** | Network routing only, not service hosting |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Conclusion
|
||||
|
||||
**The connection refusal is expected and correct behavior.**
|
||||
|
||||
- `76.53.10.34` is a router, not an RPC service
|
||||
- Use internal IPs for internal access: `192.168.11.250:8545`
|
||||
- Use public domains for external access: `https://rpc-http-pub.d-bis.org`
|
||||
- Router WAN IP is not used for RPC service routing
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-04
|
||||
**Status**: ✅ **EXPECTED BEHAVIOR - NOT AN ERROR**
|
||||
150
docs/11-references/API_DOCUMENTATION.md
Normal file
150
docs/11-references/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# Bridge API Documentation
|
||||
|
||||
**Purpose**: API documentation for bridge operations
|
||||
|
||||
---
|
||||
|
||||
## 🔌 RPC Endpoints
|
||||
|
||||
### ChainID 138
|
||||
|
||||
**HTTP**: `http://192.168.11.250:8545`
|
||||
**HTTPS**: `https://rpc-core.d-bis.org`
|
||||
**WebSocket**: `ws://192.168.11.250:8546`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Contract Addresses
|
||||
|
||||
### WETH9 Bridge
|
||||
```
|
||||
0x89dd12025bfCD38A168455A44B400e913ED33BE2
|
||||
```
|
||||
|
||||
### WETH10 Bridge
|
||||
```
|
||||
0xe0E93247376aa097dB308B92e6Ba36bA015535D0
|
||||
```
|
||||
|
||||
### WETH9 Token
|
||||
```
|
||||
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
|
||||
```
|
||||
|
||||
### WETH10 Token
|
||||
```
|
||||
0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f
|
||||
```
|
||||
|
||||
### LINK Token
|
||||
```
|
||||
0x326C977E6efc84E512bB9C30f76E30c160eD06FB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Available Functions
|
||||
|
||||
### Bridge Functions
|
||||
|
||||
#### sendCrossChain
|
||||
Send tokens cross-chain via CCIP
|
||||
|
||||
**Parameters**:
|
||||
- `uint64 destinationChainSelector`: Destination chain selector
|
||||
- `address receiver`: Receiver address on destination chain
|
||||
- `uint256 amount`: Amount to send
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cast send <BRIDGE_ADDRESS> "sendCrossChain(uint64,address,uint256)" \
|
||||
<CHAIN_SELECTOR> <RECEIVER> <AMOUNT> \
|
||||
--rpc-url $RPC_URL --private-key $PRIVATE_KEY
|
||||
```
|
||||
|
||||
#### calculateFee
|
||||
Calculate CCIP fee for transfer
|
||||
|
||||
**Parameters**:
|
||||
- `uint64 destinationChainSelector`: Destination chain selector
|
||||
- `uint256 amount`: Amount to send
|
||||
|
||||
**Returns**: Fee in wei
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cast call <BRIDGE_ADDRESS> "calculateFee(uint64,uint256)" \
|
||||
<CHAIN_SELECTOR> <AMOUNT> --rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
#### destinations
|
||||
Get destination bridge address for chain
|
||||
|
||||
**Parameters**:
|
||||
- `uint64 chainSelector`: Chain selector
|
||||
|
||||
**Returns**: Bridge address on destination chain
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cast call <BRIDGE_ADDRESS> "destinations(uint64)" \
|
||||
<CHAIN_SELECTOR> --rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Chain Selectors
|
||||
|
||||
| Chain | Selector |
|
||||
|-------|----------|
|
||||
| BSC | 11344663589394136015 |
|
||||
| Polygon | 4051577828743386545 |
|
||||
| Avalanche | 6433500567565415381 |
|
||||
| Base | 15971525489660198786 |
|
||||
| Arbitrum | 4949039107694359620 |
|
||||
| Optimism | 3734403246176062136 |
|
||||
| Ethereum | 5009297550715157269 |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Events
|
||||
|
||||
### CrossChainTransferInitiated
|
||||
|
||||
Emitted when cross-chain transfer is initiated
|
||||
|
||||
**Parameters**:
|
||||
- `uint64 destinationChainSelector`
|
||||
- `address receiver`
|
||||
- `uint256 amount`
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
cast logs --address <BRIDGE_ADDRESS> \
|
||||
"CrossChainTransferInitiated(uint64,address,uint256)" \
|
||||
--rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Test Connectivity
|
||||
```bash
|
||||
cast block-number --rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
### Test Contract
|
||||
```bash
|
||||
cast code <CONTRACT_ADDRESS> --rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
### Test Function
|
||||
```bash
|
||||
cast call <CONTRACT_ADDRESS> "<function>" <args> --rpc-url $RPC_URL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: $(date)
|
||||
|
||||
80
docs/11-references/CHAIN138_TOKEN_ADDRESSES.md
Normal file
80
docs/11-references/CHAIN138_TOKEN_ADDRESSES.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# Token Contract Addresses - ChainID 138
|
||||
|
||||
**Network**: ChainID 138 (SMOM-DBIS-138)
|
||||
**RPC Endpoint**: `http://192.168.11.250:8545` or `https://rpc-core.d-bis.org`
|
||||
**Explorer**: https://explorer.d-bis.org
|
||||
**Last Updated**: 2025-12-24
|
||||
|
||||
---
|
||||
|
||||
## 📋 ERC20 Token Contracts
|
||||
|
||||
### Standard Tokens
|
||||
|
||||
| Token | Symbol | Address | Decimals | Status | Notes |
|
||||
|-------|--------|---------|----------|--------|-------|
|
||||
| **Wrapped Ether** | WETH | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | 18 | ✅ Pre-deployed | Pre-deployed in Genesis |
|
||||
| **Wrapped Ether v10** | WETH10 | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | 18 | ✅ Pre-deployed | Pre-deployed in Genesis |
|
||||
| **Chainlink Token** | LINK | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | 18 | ✅ Deployed | Used for CCIP fees |
|
||||
|
||||
### Compliant Stablecoins
|
||||
|
||||
| Token | Symbol | Address | Decimals | Status | Notes |
|
||||
|-------|--------|---------|----------|--------|-------|
|
||||
| **Tether USD (Compliant)** | cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | 6 | ✅ Deployed | Compliant USDT token |
|
||||
| **USD Coin (Compliant)** | cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | 6 | ✅ Deployed | Compliant USDC token |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Token Registry
|
||||
|
||||
The tokens can be tracked through the TokenRegistry contract:
|
||||
|
||||
| Contract | Address | Purpose |
|
||||
|----------|---------|---------|
|
||||
| **TokenRegistry** | `0x91Efe92229dbf7C5B38D422621300956B55870Fa` | Centralized registry for all tokens on ChainID 138 |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Summary
|
||||
|
||||
### Total Token Contracts: 5
|
||||
|
||||
1. **WETH** - `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
|
||||
2. **WETH10** - `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
|
||||
3. **LINK** - `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03`
|
||||
4. **CompliantUSDT (cUSDT)** - `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
|
||||
5. **CompliantUSDC (cUSDC)** - `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
1. **WETH9 and WETH10** were pre-deployed in the genesis block
|
||||
2. **LINK token** is used for CCIP (Cross-Chain Interoperability Protocol) fees
|
||||
3. **Compliant stablecoins** (cUSDT, cUSDC) include regulatory compliance features
|
||||
4. All addresses are checksummed and verified on-chain
|
||||
5. Token list maintained at: `token-lists/lists/dbis-138.tokenlist.json`
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Verification
|
||||
|
||||
To verify a token contract on-chain:
|
||||
|
||||
```bash
|
||||
# Check contract code
|
||||
cast code <TOKEN_ADDRESS> --rpc-url http://192.168.11.250:8545
|
||||
|
||||
# Check token details (name, symbol, decimals)
|
||||
cast call <TOKEN_ADDRESS> "name()" --rpc-url http://192.168.11.250:8545
|
||||
cast call <TOKEN_ADDRESS> "symbol()" --rpc-url http://192.168.11.250:8545
|
||||
cast call <TOKEN_ADDRESS> "decimals()" --rpc-url http://192.168.11.250:8545
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**References:**
|
||||
- Token List: `token-lists/lists/dbis-138.tokenlist.json`
|
||||
- Deployment Docs: `explorer-monorepo/docs/DEPLOYMENT_COMPLETE_CHAINID_138.md`
|
||||
- Contract Reference: `docs/CONTRACT_ADDRESSES_REFERENCE.md`
|
||||
79
docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md
Normal file
79
docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Contract Addresses Reference - ChainID 138
|
||||
|
||||
**Date**: $(date)
|
||||
**Network**: ChainID 138
|
||||
**RPC Endpoint**: `http://192.168.11.250:8545` or `https://rpc-core.d-bis.org`
|
||||
|
||||
---
|
||||
|
||||
## 📋 Complete Contract Address List
|
||||
|
||||
### ✅ Pre-Deployed Contracts (Genesis)
|
||||
|
||||
These contracts were pre-deployed when ChainID 138 was initialized:
|
||||
|
||||
| Contract | Address | Status | Notes |
|
||||
|----------|---------|--------|-------|
|
||||
| **WETH9** | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | ✅ Pre-deployed | Genesis allocation |
|
||||
| **WETH10** | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | ✅ Pre-deployed | Genesis allocation |
|
||||
| **Multicall** | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | ✅ Pre-deployed | Genesis allocation |
|
||||
|
||||
### ✅ Newly Deployed Contracts
|
||||
|
||||
Contracts deployed after chain initialization:
|
||||
|
||||
| Contract | Address | Status | Purpose |
|
||||
|----------|---------|--------|---------|
|
||||
| **Oracle Aggregator** | `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` | ✅ Deployed | Price feed aggregator |
|
||||
| **Oracle Proxy** | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` | ✅ Deployed | **MetaMask price feed** |
|
||||
| **CCIP Router** | `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e` | ✅ Deployed | Cross-chain router |
|
||||
| **CCIP Sender** | `0x105F8A15b819948a89153505762444Ee9f324684` | ✅ Deployed | Cross-chain sender | [📄 Details](./CCIP_SENDER_CONTRACT_REFERENCE.md) |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Key Addresses for Services
|
||||
|
||||
### Oracle Publisher Service (VMID 3500)
|
||||
```bash
|
||||
ORACLE_ADDRESS=0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6
|
||||
AGGREGATOR_ADDRESS=0x99b3511a2d315a497c8112c1fdd8d508d4b1e506
|
||||
RPC_URL=http://192.168.11.250:8545
|
||||
CHAIN_ID=138
|
||||
```
|
||||
|
||||
### CCIP Monitor Service (VMID 3501)
|
||||
```bash
|
||||
CCIP_ROUTER_ADDRESS=0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e
|
||||
CCIP_SENDER_ADDRESS=0x105F8A15b819948a89153505762444Ee9f324684
|
||||
RPC_URL=http://192.168.11.250:8545
|
||||
CHAIN_ID=138
|
||||
```
|
||||
|
||||
### MetaMask Configuration
|
||||
```json
|
||||
{
|
||||
"chainId": 138,
|
||||
"chainName": "SMOM-DBIS-138",
|
||||
"rpcUrls": ["https://rpc-core.d-bis.org"],
|
||||
"nativeCurrency": {
|
||||
"name": "ETH",
|
||||
"symbol": "ETH",
|
||||
"decimals": 18
|
||||
},
|
||||
"priceFeedAddress": "0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
1. **WETH9 and WETH10** are pre-deployed in genesis.json - no deployment needed
|
||||
2. **Oracle Proxy** address is the primary address for MetaMask price feeds
|
||||
3. **CCIP Router** is required for cross-chain communication
|
||||
4. All addresses are on ChainID 138
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: $(date)
|
||||
|
||||
28
docs/11-references/GET_EMAIL_FROM_API.md
Normal file
28
docs/11-references/GET_EMAIL_FROM_API.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Get Cloudflare Email for API Key
|
||||
|
||||
Since you're using CLOUDFLARE_API_KEY, you need to add your Cloudflare account email.
|
||||
|
||||
## Option 1: Add Email to .env
|
||||
|
||||
Add this line to your .env file:
|
||||
```
|
||||
CLOUDFLARE_EMAIL="your-email@example.com"
|
||||
```
|
||||
|
||||
## Option 2: Create API Token (Recommended)
|
||||
|
||||
1. Go to: https://dash.cloudflare.com/profile/api-tokens
|
||||
2. Click **Create Token**
|
||||
3. Use **Edit zone DNS** template OR create custom with:
|
||||
- **Zone** → **DNS** → **Edit**
|
||||
- **Account** → **Cloudflare Tunnel** → **Edit**
|
||||
4. Copy the token
|
||||
5. Add to .env:
|
||||
```
|
||||
CLOUDFLARE_API_TOKEN="your-token-here"
|
||||
```
|
||||
6. Remove or comment out CLOUDFLARE_API_KEY
|
||||
|
||||
## Option 3: Get Email from Cloudflare Dashboard
|
||||
|
||||
Your email is the one you use to log into Cloudflare Dashboard.
|
||||
282
docs/11-references/GLOSSARY.md
Normal file
282
docs/11-references/GLOSSARY.md
Normal file
@@ -0,0 +1,282 @@
|
||||
# Glossary and Terminology
|
||||
|
||||
**Last Updated:** 2025-01-20
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This glossary provides definitions for terms, acronyms, and technical concepts used throughout the documentation.
|
||||
|
||||
---
|
||||
|
||||
## A
|
||||
|
||||
### API (Application Programming Interface)
|
||||
A set of protocols and tools for building software applications. In this context, refers to RPC APIs (ETH, NET, WEB3) exposed by Besu nodes.
|
||||
|
||||
### Archive Node
|
||||
A blockchain node that stores the complete historical state of the blockchain, including all transactions and state changes. See also: Full Node, RPC Node.
|
||||
|
||||
---
|
||||
|
||||
## B
|
||||
|
||||
### Besu
|
||||
Hyperledger Besu, an Ethereum client used for running blockchain nodes. Supports both public and private networks, with features like permissioning and QBFT consensus.
|
||||
|
||||
### Block
|
||||
A collection of transactions grouped together and added to the blockchain. In ChainID 138, blocks are produced approximately every 2 seconds using QBFT consensus.
|
||||
|
||||
### Blockscout
|
||||
An open-source blockchain explorer that provides a web interface for viewing blockchain data, transactions, and smart contracts.
|
||||
|
||||
### Break-glass
|
||||
Emergency access method that bypasses normal security controls. In this architecture, refers to optional inbound NAT rules for emergency access.
|
||||
|
||||
---
|
||||
|
||||
## C
|
||||
|
||||
### CCIP (Chainlink Cross-Chain Interoperability Protocol)
|
||||
A protocol for secure cross-chain communication and token transfers. The deployment includes Commit, Execute, and RMN node types.
|
||||
|
||||
### ChainID
|
||||
A unique identifier for a blockchain network. ChainID 138 is the identifier for the Sankofa/Phoenix/PanTel network.
|
||||
|
||||
### cloudflared
|
||||
The Cloudflare Tunnel client software that creates secure, encrypted connections between internal services and Cloudflare's edge network.
|
||||
|
||||
### Container (LXC)
|
||||
Linux Container, a lightweight virtualization technology used by Proxmox. Containers share the host kernel but have isolated filesystems and network namespaces.
|
||||
|
||||
### CORS (Cross-Origin Resource Sharing)
|
||||
A security feature that allows web applications to make requests to APIs from different domains. Configured in Besu RPC settings.
|
||||
|
||||
---
|
||||
|
||||
## D
|
||||
|
||||
### DHCP (Dynamic Host Configuration Protocol)
|
||||
A network protocol that automatically assigns IP addresses to devices on a network. Used for management VLAN (VLAN 11).
|
||||
|
||||
### DNS (Domain Name System)
|
||||
A system that translates domain names (e.g., `rpc-http-pub.d-bis.org`) to IP addresses.
|
||||
|
||||
### DON (Decentralized Oracle Network)
|
||||
A network of Chainlink nodes that work together to provide oracle services. In CCIP, there are Commit DONs and Execute DONs.
|
||||
|
||||
---
|
||||
|
||||
## E
|
||||
|
||||
### Egress
|
||||
Outbound network traffic leaving the internal network. Egress NAT pools map internal IPs to public IPs for allowlisting.
|
||||
|
||||
### Enode
|
||||
Ethereum node identifier, a unique address that identifies a blockchain node on the network. Format: `enode://<node-id>@<ip>:<port>`
|
||||
|
||||
### ER605
|
||||
TP-Link ER605 router, used as the edge router in this architecture. Two routers (ER605-A and ER605-B) provide redundancy.
|
||||
|
||||
### ES216G
|
||||
TP-Link ES216G managed switch, used for network switching and VLAN trunking. Three switches provide core, compute, and management connectivity.
|
||||
|
||||
---
|
||||
|
||||
## F
|
||||
|
||||
### Failover
|
||||
Automatic switching to a backup system when the primary system fails. ER605 routers support WAN failover.
|
||||
|
||||
### Firewall
|
||||
Network security system that controls incoming and outgoing network traffic based on predetermined security rules.
|
||||
|
||||
### Full Node
|
||||
A blockchain node that stores the complete blockchain and validates all transactions. See also: Archive Node, RPC Node.
|
||||
|
||||
---
|
||||
|
||||
## G
|
||||
|
||||
### Gateway
|
||||
A network device that connects different networks and routes traffic between them. In this architecture, gateways are configured on ER605 routers for each VLAN.
|
||||
|
||||
### Genesis Block
|
||||
The first block in a blockchain. The genesis block contains the initial configuration, including validators and network parameters.
|
||||
|
||||
---
|
||||
|
||||
## H
|
||||
|
||||
### HA (High Availability)
|
||||
System design that ensures services remain available even if individual components fail. ER605 routers provide active/standby redundancy.
|
||||
|
||||
### Hostname
|
||||
A human-readable name assigned to a network device. In this architecture, hostnames follow patterns like `r630-01`, `ml110`, `besu-rpc-1`.
|
||||
|
||||
---
|
||||
|
||||
## I
|
||||
|
||||
### Ingress
|
||||
Inbound network traffic entering the internal network. In this architecture, ingress is primarily handled through Cloudflare tunnels.
|
||||
|
||||
### IPAM (IP Address Management)
|
||||
The process of planning, tracking, and managing IP address space. This architecture uses deterministic IPAM aligned with VMID allocation.
|
||||
|
||||
### ISP (Internet Service Provider)
|
||||
A company that provides internet access. This architecture uses Spectrum as the primary ISP, with a second ISP for failover.
|
||||
|
||||
---
|
||||
|
||||
## J
|
||||
|
||||
### JWT (JSON Web Token)
|
||||
A compact, URL-safe token format used for authentication. Besu RPC nodes use JWT tokens for secure API access.
|
||||
|
||||
---
|
||||
|
||||
## L
|
||||
|
||||
### LXC (Linux Container)
|
||||
See: Container
|
||||
|
||||
### Load Balancer
|
||||
A device or service that distributes network traffic across multiple servers to improve performance and reliability.
|
||||
|
||||
---
|
||||
|
||||
## M
|
||||
|
||||
### Mermaid
|
||||
A text-based diagramming language used to create flowcharts, sequence diagrams, and other visualizations in markdown documents.
|
||||
|
||||
### ML110
|
||||
HP ML110 Gen9 server, used as the management and bootstrap node in this architecture. IP: 192.168.11.10
|
||||
|
||||
---
|
||||
|
||||
## N
|
||||
|
||||
### NAT (Network Address Translation)
|
||||
A method of remapping IP addresses. In this architecture, NAT is used for egress traffic to map private IPs to public IPs for allowlisting.
|
||||
|
||||
### Nginx
|
||||
A web server and reverse proxy. In this architecture, Nginx Proxy Manager (VMID 105) routes HTTP traffic to internal services.
|
||||
|
||||
### Node
|
||||
A computer or virtual machine that participates in a network. In blockchain context, refers to Besu nodes (validators, sentries, RPC nodes).
|
||||
|
||||
---
|
||||
|
||||
## O
|
||||
|
||||
### Omada
|
||||
TP-Link's network management system. Used for managing ER605 routers and ES216G switches.
|
||||
|
||||
### Oracle
|
||||
In blockchain context, a service that provides external data to smart contracts. Chainlink provides oracle services.
|
||||
|
||||
---
|
||||
|
||||
## P
|
||||
|
||||
### P2P (Peer-to-Peer)
|
||||
A network architecture where nodes communicate directly with each other without a central server. Blockchain networks use P2P for node communication.
|
||||
|
||||
### Permissioning
|
||||
A feature that restricts which nodes can join a blockchain network. Besu supports node permissioning and account permissioning.
|
||||
|
||||
### Proxmox VE (Proxmox Virtual Environment)
|
||||
An open-source server virtualization platform. Used to manage VMs and containers in this architecture.
|
||||
|
||||
### Public IP Block
|
||||
A range of public IP addresses assigned by an ISP. This architecture uses 6× /28 blocks (16 IPs each) for different purposes.
|
||||
|
||||
---
|
||||
|
||||
## Q
|
||||
|
||||
### QBFT (QBFT Consensus)
|
||||
QBFT (QBFT Byzantine Fault Tolerance) is a consensus algorithm used by Besu for private/permissioned networks. Provides fast block times and finality.
|
||||
|
||||
---
|
||||
|
||||
## R
|
||||
|
||||
### R630
|
||||
Dell PowerEdge R630 server, used as compute nodes in the Proxmox cluster. Four R630 servers provide production compute capacity.
|
||||
|
||||
### RPC (Remote Procedure Call)
|
||||
A protocol for requesting services from remote programs. Besu nodes expose RPC APIs (HTTP and WebSocket) for blockchain interactions.
|
||||
|
||||
### RMN (Risk Management Network)
|
||||
A network of Chainlink nodes that provide security validation for CCIP operations. RMN nodes review and approve sensitive cross-chain operations.
|
||||
|
||||
---
|
||||
|
||||
## S
|
||||
|
||||
### Sentry Node
|
||||
A blockchain node that acts as a proxy between validator nodes and the public network, protecting validators from direct exposure.
|
||||
|
||||
### Sovereign Tenant
|
||||
An isolated tenant environment with dedicated resources and network segmentation. This architecture supports multiple sovereign tenants (SMOM, ICCC, DBIS, Absolute Realms).
|
||||
|
||||
### Static Node
|
||||
A hard-coded list of peer nodes that a blockchain node will always try to connect to. Used for reliable peer discovery in private networks.
|
||||
|
||||
### Subnet
|
||||
A logical subdivision of an IP network. This architecture uses multiple subnets (one per VLAN) for network segmentation.
|
||||
|
||||
---
|
||||
|
||||
## T
|
||||
|
||||
### TOML (Tom's Obvious Minimal Language)
|
||||
A configuration file format. Besu uses TOML files for node configuration.
|
||||
|
||||
### Tunnel
|
||||
An encrypted connection between networks. Cloudflare tunnels provide secure access to internal services without exposing public IPs.
|
||||
|
||||
---
|
||||
|
||||
## V
|
||||
|
||||
### Validator
|
||||
A blockchain node that participates in consensus by proposing and validating blocks. In QBFT, validators take turns proposing blocks.
|
||||
|
||||
### VLAN (Virtual Local Area Network)
|
||||
A logical network segment that groups devices regardless of physical location. This architecture uses 19 VLANs for network segmentation.
|
||||
|
||||
### VMID (Virtual Machine ID)
|
||||
A unique identifier assigned to each VM or container in Proxmox. This architecture uses a deterministic VMID allocation scheme (11,000 VMIDs).
|
||||
|
||||
### VM (Virtual Machine)
|
||||
A software emulation of a physical computer. Proxmox supports both VMs (full virtualization) and containers (LXC).
|
||||
|
||||
---
|
||||
|
||||
## W
|
||||
|
||||
### WebSocket
|
||||
A communication protocol that provides full-duplex communication over a single TCP connection. Used for real-time RPC subscriptions.
|
||||
|
||||
### WAN (Wide Area Network)
|
||||
A network that spans a large geographic area. In this architecture, WAN refers to internet connections on ER605 routers.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[../02-architecture/NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md)** ⭐⭐⭐ - Network architecture reference
|
||||
- **[../06-besu/BESU_OFFICIAL_REFERENCE.md](../06-besu/BESU_OFFICIAL_REFERENCE.md)** ⭐ - Besu official documentation
|
||||
- **[../07-ccip/CCIP_DEPLOYMENT_SPEC.md](../07-ccip/CCIP_DEPLOYMENT_SPEC.md)** ⭐⭐ - CCIP deployment specification
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-01-20
|
||||
**Review Cycle:** Quarterly
|
||||
52
docs/11-references/OMADA_AUTH_NOTE.md
Normal file
52
docs/11-references/OMADA_AUTH_NOTE.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Omada API Authentication Notes
|
||||
|
||||
## Current Issue
|
||||
|
||||
The Omada Controller API `/api/v2/login` endpoint requires the **Omada Controller admin username and password**, not OAuth Client ID/Secret.
|
||||
|
||||
## OAuth Application Configuration
|
||||
|
||||
Your OAuth application is configured in **Authorization Code** mode, which requires user interaction and is not suitable for automated API access.
|
||||
|
||||
## Solutions
|
||||
|
||||
### Option 1: Use Admin Credentials (Recommended for Testing)
|
||||
|
||||
Update `~/.env` to use your Omada Controller admin credentials:
|
||||
|
||||
```bash
|
||||
# For /api/v2/login endpoint - uses admin username/password
|
||||
OMADA_CONTROLLER_URL=https://192.168.11.8:8043
|
||||
OMADA_ADMIN_USERNAME=your-admin-username
|
||||
OMADA_ADMIN_PASSWORD=your-admin-password
|
||||
OMADA_SITE_ID=090862bebcb1997bb263eea9364957fe
|
||||
OMADA_VERIFY_SSL=false
|
||||
```
|
||||
|
||||
Note: The current code uses OMADA_API_KEY/OMADA_API_SECRET as username/password for `/api/v2/login`.
|
||||
|
||||
### Option 2: Switch to Client Credentials Mode
|
||||
|
||||
1. In Omada Controller: Settings → Platform Integration → Open API
|
||||
2. Edit your application
|
||||
3. Change **Access Mode** from "Authorization Code" to **"Client Credentials"**
|
||||
4. Save changes
|
||||
5. Then use Client ID/Secret with OAuth token endpoint (if available)
|
||||
|
||||
### Option 3: Use OAuth Token Endpoint
|
||||
|
||||
If your controller supports OAuth token endpoint, we need to:
|
||||
1. Find the OAuth token endpoint URL
|
||||
2. Update Authentication.ts to use OAuth2 token exchange instead of /api/v2/login
|
||||
|
||||
## Current Status
|
||||
|
||||
- Controller is reachable: ✓
|
||||
- `/api/v2/login` endpoint exists: ✓
|
||||
- Authentication fails with Client ID/Secret: ✗ (Expected - endpoint needs admin credentials)
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **For immediate testing**: Use admin username/password in ~/.env
|
||||
2. **For production**: Consider switching OAuth app to Client Credentials mode
|
||||
3. **Alternative**: Check Omada Controller documentation for OAuth token endpoint
|
||||
156
docs/11-references/OMADA_QUERY_INSTRUCTIONS.md
Normal file
156
docs/11-references/OMADA_QUERY_INSTRUCTIONS.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Omada Controller Query Instructions
|
||||
|
||||
**Date**: 2026-01-05
|
||||
**Purpose**: Query Omada controller to find device using 192.168.11.14
|
||||
|
||||
---
|
||||
|
||||
## Omada Controller Information
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **VMID** | 103 |
|
||||
| **Host** | r630-02 (192.168.11.12) |
|
||||
| **IP Address** | 192.168.11.20 |
|
||||
| **Port** | 8043 (HTTPS) |
|
||||
| **Web Interface** | https://192.168.11.20:8043 |
|
||||
| **Status** | ✅ Running |
|
||||
|
||||
---
|
||||
|
||||
## Query Methods
|
||||
|
||||
### Method 1: Web Interface (Recommended)
|
||||
|
||||
1. **Access Omada Controller**:
|
||||
- URL: `https://192.168.11.20:8043`
|
||||
- Login with admin credentials
|
||||
|
||||
2. **Navigate to Devices**:
|
||||
- Go to **Devices** section
|
||||
- Look for device with IP `192.168.11.14`
|
||||
- Check MAC address `bc:24:11:ee:a6:ec`
|
||||
|
||||
3. **Device Information**:
|
||||
- Device name
|
||||
- Device type (router, switch, AP, client)
|
||||
- Connection status
|
||||
- Port assignment
|
||||
|
||||
### Method 2: API Query (If Credentials Available)
|
||||
|
||||
**Using query-omada-devices.js**:
|
||||
```bash
|
||||
cd /home/intlc/projects/proxmox
|
||||
|
||||
# Ensure credentials are in ~/.env:
|
||||
# OMADA_CONTROLLER_URL=https://192.168.11.20:8043
|
||||
# OMADA_ADMIN_USERNAME=admin
|
||||
# OMADA_ADMIN_PASSWORD=<password>
|
||||
# OMADA_SITE_ID=<site-id> (optional)
|
||||
|
||||
node query-omada-devices.js | grep -A 10 "192.168.11.14"
|
||||
```
|
||||
|
||||
**Using MCP Omada Server** (if configured):
|
||||
- Use `omada_list_devices` tool
|
||||
- Filter for IP 192.168.11.14
|
||||
- Get device details
|
||||
|
||||
### Method 3: Direct Container Access
|
||||
|
||||
```bash
|
||||
# Access Omada container
|
||||
ssh root@192.168.11.12
|
||||
pct enter 103
|
||||
|
||||
# Check Omada logs or database for device information
|
||||
# (Requires knowledge of Omada internal structure)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What to Look For
|
||||
|
||||
### Device Information Needed
|
||||
|
||||
1. **Device Name**: What is the device called in Omada?
|
||||
2. **Device Type**: Router, Switch, AP, or Client?
|
||||
3. **MAC Address**: Does it match `bc:24:11:ee:a6:ec`?
|
||||
4. **Connection Status**: Online/Offline?
|
||||
5. **Port Assignment**: Which switch port is it connected to?
|
||||
6. **VLAN Assignment**: What VLAN is it on?
|
||||
|
||||
### Expected Findings
|
||||
|
||||
**If it's a container/VM**:
|
||||
- Should show as a "Client" device
|
||||
- May show hostname or container name
|
||||
- MAC address will match
|
||||
|
||||
**If it's a network device**:
|
||||
- Will show as Router/Switch/AP
|
||||
- Will have device model information
|
||||
- May show firmware version
|
||||
|
||||
**If it's not in Omada**:
|
||||
- Device might be on different network segment
|
||||
- Device might not be managed by Omada
|
||||
- Device might be using static IP outside Omada management
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Query
|
||||
|
||||
1. **If Device Found in Omada**:
|
||||
- Document device information
|
||||
- Determine if it's a container, VM, or network device
|
||||
- Plan IP reassignment
|
||||
|
||||
2. **If Device Not Found in Omada**:
|
||||
- Device is likely not managed by Omada
|
||||
- May be on different network segment
|
||||
- May require network scan or physical inspection
|
||||
|
||||
3. **Resolution**:
|
||||
- Stop/remove container if found
|
||||
- Reconfigure device if network device
|
||||
- Reassign IP to r630-04 when powered on
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Cannot Access Omada Web Interface
|
||||
|
||||
1. **Check container status**:
|
||||
```bash
|
||||
ssh root@192.168.11.12 "pct status 103"
|
||||
```
|
||||
|
||||
2. **Check network connectivity**:
|
||||
```bash
|
||||
ping -c 2 192.168.11.20
|
||||
curl -k https://192.168.11.20:8043
|
||||
```
|
||||
|
||||
3. **Check firewall rules**:
|
||||
- Ensure port 8043 is accessible
|
||||
- Check if Cloudflare tunnel is needed
|
||||
|
||||
### API Query Fails
|
||||
|
||||
1. **Check credentials**:
|
||||
- Verify ~/.env file exists
|
||||
- Check OMADA_* variables are set
|
||||
- Test credentials manually
|
||||
|
||||
2. **Check SSL certificate**:
|
||||
- May need to set `OMADA_VERIFY_SSL=false`
|
||||
- Check certificate validity
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-01-05
|
||||
**Status**: 📋 **INSTRUCTIONS READY**
|
||||
**Next**: Access Omada web interface to query devices
|
||||
@@ -4,6 +4,8 @@ This directory contains technical reference documentation.
|
||||
|
||||
## Documents
|
||||
|
||||
### Reference Guides
|
||||
- **[GLOSSARY.md](GLOSSARY.md)** ⭐⭐⭐ - Comprehensive glossary of terms and acronyms
|
||||
- **[APT_PACKAGES_CHECKLIST.md](APT_PACKAGES_CHECKLIST.md)** ⭐ - APT packages checklist
|
||||
- **[PATHS_REFERENCE.md](PATHS_REFERENCE.md)** ⭐ - Paths reference guide
|
||||
- **[SCRIPT_REVIEW.md](SCRIPT_REVIEW.md)** ⭐ - Script review documentation
|
||||
|
||||
96
docs/11-references/README_EXPLORER_SUBMODULE.md
Normal file
96
docs/11-references/README_EXPLORER_SUBMODULE.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Explorer Monorepo Submodule
|
||||
|
||||
The Chain 138 Explorer is now organized as a monorepo and added as a git submodule.
|
||||
|
||||
## 📁 Location
|
||||
|
||||
The explorer monorepo is located at: `explorer-monorepo/`
|
||||
|
||||
## 🚀 Usage
|
||||
|
||||
### Initial Setup
|
||||
|
||||
If cloning the main project fresh, initialize the submodule:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### Updating the Explorer
|
||||
|
||||
To update the explorer to the latest version:
|
||||
|
||||
```bash
|
||||
cd explorer-monorepo
|
||||
git pull origin main # or master
|
||||
cd ..
|
||||
git add explorer-monorepo
|
||||
git commit -m "Update explorer submodule"
|
||||
```
|
||||
|
||||
### Making Changes to Explorer
|
||||
|
||||
1. Navigate to the submodule:
|
||||
```bash
|
||||
cd explorer-monorepo
|
||||
```
|
||||
|
||||
2. Make your changes
|
||||
3. Commit and push (if using remote repo):
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Your change description"
|
||||
git push
|
||||
```
|
||||
|
||||
4. Update the parent project reference:
|
||||
```bash
|
||||
cd ..
|
||||
git add explorer-monorepo
|
||||
git commit -m "Update explorer submodule reference"
|
||||
```
|
||||
|
||||
### Deploying Explorer
|
||||
|
||||
From the explorer monorepo directory:
|
||||
|
||||
```bash
|
||||
cd explorer-monorepo
|
||||
./scripts/deploy.sh
|
||||
```
|
||||
|
||||
Or from the root:
|
||||
|
||||
```bash
|
||||
cd explorer-monorepo && ./scripts/deploy.sh
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
See `explorer-monorepo/README.md` and `explorer-monorepo/docs/` for detailed documentation.
|
||||
|
||||
## 🔗 Structure
|
||||
|
||||
```
|
||||
proxmox/
|
||||
├── explorer-monorepo/ # Explorer submodule
|
||||
│ ├── frontend/ # Frontend code
|
||||
│ ├── scripts/ # Deployment scripts
|
||||
│ ├── docs/ # Documentation
|
||||
│ └── ...
|
||||
├── scripts/ # Main project scripts
|
||||
├── docs/ # Main project docs
|
||||
└── ...
|
||||
```
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
1. **Submodule is Local**: Currently, the submodule points to a local path. To use with a remote repository:
|
||||
- Create a remote repository for the explorer
|
||||
- Update `.gitmodules` with the remote URL
|
||||
- Push the explorer repo to remote
|
||||
|
||||
2. **Deployment**: The explorer is deployed to `192.168.11.140:/var/www/html/`
|
||||
|
||||
3. **Backups**: The deploy script creates automatic backups before deployment
|
||||
|
||||
439
docs/11-references/TOKEN_LIST_AUTHORING_GUIDE.md
Normal file
439
docs/11-references/TOKEN_LIST_AUTHORING_GUIDE.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# Token List Authoring Guide
|
||||
|
||||
**Based on**: [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists#authoring-token-lists)
|
||||
**Schema**: [https://uniswap.org/tokenlist.schema.json](https://uniswap.org/tokenlist.schema.json)
|
||||
**Network**: ChainID 138 (SMOM-DBIS-138)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
This guide explains how to create and maintain token lists that conform to the Uniswap Token Lists specification. Token lists are JSON files that contain metadata about ERC20 tokens for use in dApp interfaces like MetaMask, Uniswap, and other DeFi applications.
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
Our token list files:
|
||||
|
||||
- **`token-lists/lists/dbis-138.tokenlist.json`** - Main token list file (production)
|
||||
- **`docs/METAMASK_TOKEN_LIST.json`** - Legacy location (deprecated, kept for backward compatibility)
|
||||
- **`token-list.json`** - Public-facing token list (deployed version)
|
||||
|
||||
The `.tokenlist.json` extension enables automatic JSON schema validation in editors like VSCode and IntelliJ.
|
||||
|
||||
**Note**: The token list has been migrated to `token-lists/lists/dbis-138.tokenlist.json` for better organization and CI/CD integration.
|
||||
|
||||
---
|
||||
|
||||
## 📝 Token List Structure
|
||||
|
||||
### Required Fields
|
||||
|
||||
Every token list must include:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "SMOM-DBIS-138 Token List",
|
||||
"version": {
|
||||
"major": 1,
|
||||
"minor": 0,
|
||||
"patch": 0
|
||||
},
|
||||
"timestamp": "2025-12-22T17:45:00.000Z",
|
||||
"tokens": [
|
||||
// Array of token objects
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
Recommended fields for better compatibility:
|
||||
|
||||
- **`logoURI`** (string): Logo URL for the token list itself
|
||||
- **`tags`** (object): Tag definitions for categorizing tokens
|
||||
- **`tokenMap`** (object): Optional map for quick token lookups
|
||||
|
||||
### Token Object Structure
|
||||
|
||||
Each token in the `tokens` array must have:
|
||||
|
||||
**Required:**
|
||||
- `chainId` (number): Chain ID (138 for SMOM-DBIS-138)
|
||||
- `address` (string): Ethereum address (0x-prefixed, 40 hex chars)
|
||||
- `name` (string): Human-readable token name
|
||||
- `symbol` (string): Token symbol (e.g., "WETH", "ETH-USD")
|
||||
- `decimals` (number): Number of decimals (0-255)
|
||||
|
||||
**Optional:**
|
||||
- `logoURI` (string): URL to token logo image
|
||||
- `tags` (array of strings): Array of tag identifiers
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Example Token List
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "SMOM-DBIS-138 Token List",
|
||||
"version": {
|
||||
"major": 1,
|
||||
"minor": 1,
|
||||
"patch": 0
|
||||
},
|
||||
"timestamp": "2025-12-22T17:45:00.000Z",
|
||||
"logoURI": "https://example.com/logo.png",
|
||||
"tokens": [
|
||||
{
|
||||
"chainId": 138,
|
||||
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
|
||||
"name": "Wrapped Ether",
|
||||
"symbol": "WETH",
|
||||
"decimals": 18,
|
||||
"logoURI": "https://example.com/weth.png",
|
||||
"tags": ["defi", "wrapped"]
|
||||
}
|
||||
],
|
||||
"tags": {
|
||||
"defi": {
|
||||
"name": "DeFi",
|
||||
"description": "Decentralized Finance tokens"
|
||||
},
|
||||
"wrapped": {
|
||||
"name": "Wrapped",
|
||||
"description": "Wrapped tokens representing native assets"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Validation
|
||||
|
||||
### Using the Validation Script
|
||||
|
||||
We provide enhanced validation scripts in `token-lists/scripts/`:
|
||||
|
||||
```bash
|
||||
# Validate the token list (schema, checksums, duplicates, chain ID)
|
||||
node token-lists/scripts/validate-token-list.js token-lists/lists/dbis-138.tokenlist.json
|
||||
|
||||
# Validate address checksums
|
||||
node token-lists/scripts/checksum-addresses.js token-lists/lists/dbis-138.tokenlist.json
|
||||
|
||||
# Fix checksummed addresses
|
||||
node token-lists/scripts/checksum-addresses.js token-lists/lists/dbis-138.tokenlist.json --fix
|
||||
|
||||
# Validate logos
|
||||
node token-lists/scripts/validate-logos.js token-lists/lists/dbis-138.tokenlist.json
|
||||
|
||||
# Verify on-chain contracts
|
||||
node token-lists/scripts/verify-on-chain.js token-lists/lists/dbis-138.tokenlist.json
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Fetch the official Uniswap schema
|
||||
2. Validate the JSON structure
|
||||
3. Check all required fields
|
||||
4. Validate token addresses format
|
||||
5. Verify decimals are in valid range (0-255)
|
||||
6. Display token list information
|
||||
|
||||
### Manual Validation
|
||||
|
||||
For manual validation, you can:
|
||||
|
||||
1. **Use an editor with JSON Schema support** (VSCode, IntelliJ, etc.)
|
||||
- Files with `.tokenlist.json` extension automatically get schema validation
|
||||
- The schema is registered in SchemaStore
|
||||
|
||||
2. **Use online validators**:
|
||||
- [JSON Schema Validator](https://www.jsonschemavalidator.net/)
|
||||
- Schema URL: `https://uniswap.org/tokenlist.schema.json`
|
||||
|
||||
3. **Use command-line tools**:
|
||||
```bash
|
||||
# Basic JSON validation
|
||||
jq empty docs/METAMASK_TOKEN_LIST.json
|
||||
|
||||
# Validate against schema (requires ajv-cli)
|
||||
ajv validate -s tokenlist.schema.json -d docs/METAMASK_TOKEN_LIST.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Semantic Versioning
|
||||
|
||||
Token list versions follow [semantic versioning](https://semver.org/) rules:
|
||||
|
||||
### Version Increment Rules
|
||||
|
||||
- **Major version** (1.0.0 → 2.0.0):
|
||||
- When tokens are **removed** from the list
|
||||
- When token addresses or chain IDs change (considered remove + add)
|
||||
|
||||
- **Minor version** (1.0.0 → 1.1.0):
|
||||
- When tokens are **added** to the list
|
||||
|
||||
- **Patch version** (1.0.0 → 1.0.1):
|
||||
- When **existing tokens** have minor details changed:
|
||||
- Name changes
|
||||
- Symbol changes
|
||||
- Logo URL updates
|
||||
- Decimals changes
|
||||
- Tag additions/removals
|
||||
|
||||
### Example Version Changes
|
||||
|
||||
```json
|
||||
// Version 1.0.0 → 1.0.1 (patch)
|
||||
// Changed logo URL for WETH
|
||||
{
|
||||
"version": { "major": 1, "minor": 0, "patch": 1 },
|
||||
"tokens": [
|
||||
{ "symbol": "WETH", "logoURI": "https://new-logo.png" }
|
||||
]
|
||||
}
|
||||
|
||||
// Version 1.0.0 → 1.1.0 (minor)
|
||||
// Added new token
|
||||
{
|
||||
"version": { "major": 1, "minor": 1, "patch": 0 },
|
||||
"tokens": [
|
||||
{ "symbol": "WETH", ... },
|
||||
{ "symbol": "USDC", ... } // New token
|
||||
]
|
||||
}
|
||||
|
||||
// Version 1.0.0 → 2.0.0 (major)
|
||||
// Removed token
|
||||
{
|
||||
"version": { "major": 2, "minor": 0, "patch": 0 },
|
||||
"tokens": [
|
||||
{ "symbol": "WETH", ... }
|
||||
// USDC removed
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Authoring Methods
|
||||
|
||||
### Manual Authoring
|
||||
|
||||
**Recommended for**: Small lists, occasional updates
|
||||
|
||||
1. **Use an editor with JSON Schema support**:
|
||||
- VSCode (recommended)
|
||||
- IntelliJ IDEA
|
||||
- Other editors from [SchemaStore](https://www.schemastore.org/json/)
|
||||
|
||||
2. **Open the `.tokenlist.json` file**:
|
||||
```bash
|
||||
code docs/METAMASK_TOKEN_LIST.tokenlist.json
|
||||
```
|
||||
|
||||
3. **The editor will provide**:
|
||||
- Autocomplete for valid fields
|
||||
- Validation errors in real-time
|
||||
- Schema-aware formatting
|
||||
|
||||
4. **Make your changes** and save
|
||||
|
||||
5. **Validate before committing**:
|
||||
```bash
|
||||
node token-lists/scripts/validate-token-list.js token-lists/lists/dbis-138.tokenlist.json
|
||||
```
|
||||
|
||||
### Automated Authoring
|
||||
|
||||
**Recommended for**: Large lists, frequent updates, pulling from contracts
|
||||
|
||||
You can use the `@uniswap/token-lists` npm package:
|
||||
|
||||
```javascript
|
||||
import { TokenList, schema } from '@uniswap/token-lists'
|
||||
import Ajv from 'ajv'
|
||||
import addFormats from 'ajv-formats'
|
||||
|
||||
// Generate your token list
|
||||
const myList: TokenList = {
|
||||
name: "SMOM-DBIS-138 Token List",
|
||||
version: { major: 1, minor: 0, patch: 0 },
|
||||
timestamp: new Date().toISOString(),
|
||||
tokens: [
|
||||
// Your tokens
|
||||
]
|
||||
}
|
||||
|
||||
// Validate against schema
|
||||
const ajv = new Ajv({ allErrors: true, verbose: true })
|
||||
addFormats(ajv)
|
||||
const validator = ajv.compile(schema)
|
||||
const valid = validator(myList)
|
||||
|
||||
if (!valid) {
|
||||
console.error('Validation errors:', validator.errors)
|
||||
} else {
|
||||
// Print JSON
|
||||
console.log(JSON.stringify(myList, null, 2))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📤 Deploying Token Lists
|
||||
|
||||
### Release Process
|
||||
|
||||
For production releases, use the release script:
|
||||
|
||||
```bash
|
||||
# Bump version (patch, minor, or major)
|
||||
cd token-lists
|
||||
./scripts/release.sh patch
|
||||
|
||||
# Sign the token list
|
||||
./scripts/sign-list.sh sign
|
||||
|
||||
# Create git tag and push (triggers GitHub Actions release workflow)
|
||||
git tag -a v1.2.0 -m "Release v1.2.0"
|
||||
git push --tags
|
||||
```
|
||||
|
||||
The GitHub Actions release workflow will automatically:
|
||||
- Validate the token list
|
||||
- Verify on-chain contracts
|
||||
- Generate checksums
|
||||
- Sign the token list
|
||||
- Create a GitHub Release
|
||||
|
||||
For manual hosting, you can use the hosting script:
|
||||
|
||||
```bash
|
||||
# Prepare for GitHub Pages
|
||||
./scripts/host-token-list.sh github
|
||||
|
||||
# Prepare for IPFS
|
||||
./scripts/host-token-list.sh ipfs
|
||||
|
||||
# Get instructions for custom hosting
|
||||
./scripts/host-token-list.sh local
|
||||
```
|
||||
|
||||
See [METAMASK_TOKEN_LIST_HOSTING.md](./METAMASK_TOKEN_LIST_HOSTING.md) for detailed deployment instructions.
|
||||
|
||||
### Hosting Requirements
|
||||
|
||||
- **HTTPS required**: MetaMask and other dApps require HTTPS
|
||||
- **CORS headers**: Must include `Access-Control-Allow-Origin: *`
|
||||
- **Content-Type**: Should be `application/json`
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Current Token List Contents
|
||||
|
||||
Our token list currently includes:
|
||||
|
||||
1. **WETH9** (`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`)
|
||||
- Wrapped Ether (18 decimals)
|
||||
- Tags: `defi`, `wrapped`
|
||||
|
||||
2. **WETH10** (`0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`)
|
||||
- Wrapped Ether v10 (18 decimals)
|
||||
- Tags: `defi`, `wrapped`
|
||||
|
||||
3. **ETH/USD Price Feed** (`0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6`)
|
||||
- Oracle price feed (8 decimals)
|
||||
- Tags: `oracle`, `price-feed`
|
||||
|
||||
---
|
||||
|
||||
## 📚 Best Practices
|
||||
|
||||
1. **Always validate** before deploying
|
||||
```bash
|
||||
node scripts/validate-token-list.js docs/METAMASK_TOKEN_LIST.json
|
||||
```
|
||||
|
||||
2. **Update timestamp** when making changes
|
||||
```json
|
||||
"timestamp": "2025-12-22T17:45:00.000Z"
|
||||
```
|
||||
|
||||
3. **Use checksummed addresses** (mixed case)
|
||||
- Use tools like [ethsum.netlify.app](https://ethsum.netlify.app/)
|
||||
- Or use ethers.js: `ethers.getAddress(address)`
|
||||
|
||||
4. **Provide logo URLs** for better UX
|
||||
- Use reliable CDNs (GitHub, IPFS, etc.)
|
||||
- Recommended format: PNG or SVG
|
||||
- Recommended size: 256x256 or larger
|
||||
|
||||
5. **Use tags** to categorize tokens
|
||||
- Makes filtering easier for users
|
||||
- Define tag descriptions in the `tags` object
|
||||
|
||||
6. **Follow versioning rules** strictly
|
||||
- Helps users understand what changed
|
||||
- Prevents breaking changes
|
||||
|
||||
7. **Test in MetaMask** after updates
|
||||
- Add the token list URL to MetaMask
|
||||
- Verify tokens appear correctly
|
||||
- Check metadata (name, symbol, decimals, logo)
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- [Token Lists README](../token-lists/README.md) - Main token lists documentation
|
||||
- [Token List Policy](../token-lists/docs/TOKEN_LIST_POLICY.md) - Inclusion and delisting policy
|
||||
- [Integration Guide](../token-lists/docs/INTEGRATION_GUIDE.md) - Integration instructions
|
||||
- [Uniswap Token Lists Specification](https://github.com/Uniswap/token-lists)
|
||||
- [JSON Schema](https://uniswap.org/tokenlist.schema.json)
|
||||
- [MetaMask Token List Guide](./METAMASK_ADD_TOKEN_LIST_GUIDE.md)
|
||||
- [Token List Hosting Guide](./METAMASK_TOKEN_LIST_HOSTING.md)
|
||||
- [MetaMask Integration Requirements](./METAMASK_FULL_INTEGRATION_REQUIREMENTS.md)
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Validation Errors
|
||||
|
||||
**Error: "Missing or invalid address"**
|
||||
- Ensure address is 0x-prefixed with 40 hex characters
|
||||
- Use checksummed (mixed case) addresses
|
||||
|
||||
**Error: "Invalid decimals"**
|
||||
- Decimals must be a number between 0 and 255
|
||||
|
||||
**Error: "Invalid chainId"**
|
||||
- Chain ID must be a number
|
||||
- For SMOM-DBIS-138, use 138
|
||||
|
||||
### Schema Validation Fails
|
||||
|
||||
If AJV validation fails but basic validation passes:
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install ajv ajv-formats
|
||||
```
|
||||
|
||||
2. Run validation again:
|
||||
```bash
|
||||
node scripts/validate-token-list.js docs/METAMASK_TOKEN_LIST.json
|
||||
```
|
||||
|
||||
3. Check specific errors in the output
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-12-22
|
||||
**Maintainer**: DBIS Team
|
||||
|
||||
Reference in New Issue
Block a user