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.
2026-01-06 01:46:25 -08:00
parent 1edcec953c
commit cb47cce074
1327 changed files with 217220 additions and 801 deletions
--- a/token-lists/docs/INTEGRATION_GUIDE.md
+++ b/token-lists/docs/INTEGRATION_GUIDE.md
@@ -0,0 +1,320 @@
+# Token List Integration Guide
+
+**Network**: ChainID 138 (DBIS Chain)  
+**Token List**: DBIS Chain 138 Token List  
+**Last Updated**: 2025-12-22
+
+---
+
+## Overview
+
+This guide explains how to integrate the DBIS Chain 138 Token List into various applications, wallets, and services.
+
+---
+
+## Token List Endpoints
+
+### Primary Endpoints
+
+- **GitHub Pages**: `https://{user}.github.io/{repo}/token-lists/lists/dbis-138.tokenlist.json`
+- **GitHub Raw**: `https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json`
+- **DBIS Domain** (if configured): `https://tokens.d-bis.org/lists/dbis-138.tokenlist.json`
+
+### Verification
+
+- **Signature**: `{token-list-url}.sig`
+- **Checksums**: See GitHub Releases for `SHA256SUMS`
+- **Public Key**: `token-lists/minisign.pub`
+
+---
+
+## MetaMask Integration
+
+### Method 1: Manual Addition
+
+1. Open MetaMask
+2. Go to **Settings** → **Security & Privacy** → **Token Lists**
+3. Click **"Add custom token list"**
+4. Enter token list URL:
+   ```
+   https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json
+   ```
+5. Click **Add**
+
+### Method 2: Programmatic Addition
+
+```javascript
+// Add network first (if not already added)
+await window.ethereum.request({
+  method: 'wallet_addEthereumChain',
+  params: [{
+    chainId: '0x8a', // 138 in hex
+    chainName: 'SMOM-DBIS-138',
+    rpcUrls: ['https://rpc-core.d-bis.org'],
+    nativeCurrency: {
+      name: 'Ether',
+      symbol: 'ETH',
+      decimals: 18
+    },
+    blockExplorerUrls: ['https://explorer.d-bis.org']
+  }]
+});
+
+// Token list is added via MetaMask UI (Settings → Token Lists)
+// MetaMask doesn't provide API for programmatic token list addition
+```
+
+### Verifying Token List in MetaMask
+
+1. Ensure you're connected to ChainID 138
+2. Go to **Assets** tab
+3. Click **"Import tokens"**
+4. Tokens from the list should appear automatically
+
+---
+
+## Ledger Integration
+
+Ledger Live doesn't directly support token lists. Use MetaMask with Ledger:
+
+1. **Connect Ledger to MetaMask**
+   - Connect Ledger device
+   - Enable "Ethereum" app on Ledger
+   - In MetaMask, select "Connect Hardware Wallet" → "Ledger"
+
+2. **Add DBIS Network**
+   - Follow MetaMask network addition steps above
+   - Network will use Ledger for signing
+
+3. **Add Token List**
+   - Follow MetaMask token list addition steps above
+   - Tokens will be available when using Ledger with MetaMask
+
+---
+
+## dApp Integration
+
+### Using Web3.js
+
+```javascript
+const Web3 = require('web3');
+const web3 = new Web3('https://rpc-core.d-bis.org');
+
+// Fetch token list
+async function getTokenList() {
+  const response = await fetch('https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json');
+  const tokenList = await response.json();
+  return tokenList.tokens;
+}
+
+// Use token metadata
+const tokens = await getTokenList();
+const wethToken = tokens.find(t => t.symbol === 'WETH');
+console.log(`WETH address: ${wethToken.address}`);
+console.log(`WETH decimals: ${wethToken.decimals}`);
+```
+
+### Using Ethers.js
+
+```javascript
+const { ethers } = require('ethers');
+const provider = new ethers.JsonRpcProvider('https://rpc-core.d-bis.org');
+
+// Fetch token list
+async function getTokenList() {
+  const response = await fetch('https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json');
+  const tokenList = await response.json();
+  return tokenList.tokens;
+}
+
+// Create contract instance using token metadata
+const tokens = await getTokenList();
+const wethToken = tokens.find(t => t.symbol === 'WETH');
+
+const erc20ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function decimals() view returns (uint8)'
+];
+
+const contract = new ethers.Contract(wethToken.address, erc20ABI, provider);
+const balance = await contract.balanceOf(userAddress);
+const decimals = await contract.decimals();
+console.log(`Balance: ${ethers.formatUnits(balance, decimals)} WETH`);
+```
+
+---
+
+## Explorer/Indexer Integration
+
+### Blockscout Integration
+
+1. **Configure Token List URL**
+   - Add token list URL to Blockscout configuration
+   - Blockscout will fetch token metadata automatically
+
+2. **Manual Token Addition**
+   - Use Blockscout admin interface
+   - Add tokens from the list manually
+
+### Custom Indexer
+
+```javascript
+// Fetch and cache token list
+async function fetchTokenList() {
+  const response = await fetch('https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json');
+  const tokenList = await response.json();
+  
+  // Create lookup map
+  const tokenMap = new Map();
+  tokenList.tokens.forEach(token => {
+    tokenMap.set(token.address.toLowerCase(), token);
+  });
+  
+  return tokenMap;
+}
+
+// Use in indexing
+const tokenMap = await fetchTokenList();
+const token = tokenMap.get(contractAddress.toLowerCase());
+if (token) {
+  console.log(`Token: ${token.symbol} (${token.name})`);
+  console.log(`Decimals: ${token.decimals}`);
+  console.log(`Logo: ${token.logoURI}`);
+}
+```
+
+---
+
+## Signature Verification
+
+Verify token list integrity using minisign:
+
+```bash
+# Install minisign (if not installed)
+# macOS: brew install minisign
+# Ubuntu: apt-get install minisign
+
+# Download files
+curl -O https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json
+curl -O https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json.sig
+curl -O https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/minisign.pub
+
+# Verify signature
+minisign -V -p minisign.pub -m dbis-138.tokenlist.json -x dbis-138.tokenlist.json.sig
+```
+
+---
+
+## CORS Configuration
+
+If hosting the token list on a custom domain, ensure CORS headers are configured:
+
+### Nginx Example
+
+```nginx
+location /lists/dbis-138.tokenlist.json {
+    add_header Access-Control-Allow-Origin *;
+    add_header Access-Control-Allow-Methods "GET, OPTIONS";
+    add_header Content-Type application/json;
+    add_header Cache-Control "public, max-age=3600";
+    
+    if ($request_method = OPTIONS) {
+        add_header Access-Control-Allow-Origin *;
+        add_header Access-Control-Allow-Methods "GET, OPTIONS";
+        add_header Content-Length 0;
+        add_header Content-Type text/plain;
+        return 204;
+    }
+}
+```
+
+### Apache Example
+
+```apache
+<Location "/lists/dbis-138.tokenlist.json">
+    Header set Access-Control-Allow-Origin "*"
+    Header set Access-Control-Allow-Methods "GET, OPTIONS"
+    Header set Content-Type "application/json"
+    Header set Cache-Control "public, max-age=3600"
+</Location>
+```
+
+---
+
+## Rate Limiting
+
+When fetching the token list:
+
+- Use appropriate caching (recommended: 1 hour)
+- Respect rate limits if using GitHub API
+- Consider mirroring to CDN for high-traffic applications
+
+### Caching Example
+
+```javascript
+const CACHE_KEY = 'dbis-token-list-v1.1.0';
+const CACHE_TTL = 3600000; // 1 hour
+
+async function getTokenListCached() {
+  const cached = localStorage.getItem(CACHE_KEY);
+  const cachedTime = localStorage.getItem(`${CACHE_KEY}-time`);
+  
+  if (cached && cachedTime && Date.now() - parseInt(cachedTime) < CACHE_TTL) {
+    return JSON.parse(cached);
+  }
+  
+  const response = await fetch('https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json');
+  const tokenList = await response.json();
+  
+  localStorage.setItem(CACHE_KEY, JSON.stringify(tokenList));
+  localStorage.setItem(`${CACHE_KEY}-time`, Date.now().toString());
+  
+  return tokenList;
+}
+```
+
+---
+
+## Error Handling
+
+Always handle errors when fetching token lists:
+
+```javascript
+async function getTokenList() {
+  try {
+    const response = await fetch('https://raw.githubusercontent.com/{user}/{repo}/main/token-lists/lists/dbis-138.tokenlist.json');
+    
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    const tokenList = await response.json();
+    
+    // Validate structure
+    if (!tokenList.tokens || !Array.isArray(tokenList.tokens)) {
+      throw new Error('Invalid token list format');
+    }
+    
+    return tokenList;
+  } catch (error) {
+    console.error('Failed to fetch token list:', error);
+    // Fallback to cached version or default list
+    return null;
+  }
+}
+```
+
+---
+
+## Support
+
+For integration questions or issues:
+
+- Create an issue in the repository
+- Check existing documentation
+- Contact DBIS team
+
+---
+
+**Last Updated**: 2025-12-22
+