b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
181 lines
6.7 KiB
Markdown
181 lines
6.7 KiB
Markdown
# IPFS Token Logos — Full Coverage for All Networks and Explorers
|
||
|
||
**Last Updated:** 2026-02-28
|
||
**Purpose:** Host all token logos on IPFS so they are available for explorer.d-bis.org (Blockscout), token lists, MetaMask, CoinGecko/CMC, and all bridge networks.
|
||
|
||
---
|
||
|
||
## 1. Current State
|
||
|
||
### IPFS in This Repo
|
||
|
||
| Component | Location | Purpose |
|
||
|-----------|----------|---------|
|
||
| **Firefly IPFS** | `smom-dbis-138/k8s/firefly/ipfs.yaml`, `smom-dbis-138-proxmox/install/firefly-install.sh` | Firefly shared storage (internal) |
|
||
| **Kubo (standalone)** | `ProxmoxVE/install/kubo-install.sh` | General-purpose IPFS node (LXC) |
|
||
|
||
### Logo Consumers
|
||
|
||
| Consumer | Where | Format |
|
||
|----------|-------|--------|
|
||
| **Blockscout (explorer.d-bis.org)** | `tokens.logo_url` in DB, or `/images/tokens/{address}.png` | PNG, any size |
|
||
| **Token list (dbis-138.tokenlist.json)** | `logoURI` per token | URL (PNG/SVG) |
|
||
| **Token-aggregation API** | `getLogoUriForSpec()` in canonical-tokens.ts | Trust Wallet URLs |
|
||
| **MetaMask / Snap** | Fetches token list with logoURI | URL |
|
||
| **CoinGecko / CMC** | 512×512 PNG for submission | PNG |
|
||
| **Other explorers** | etherscan.io, bscscan.com, polygonscan.com, etc. | Token metadata or external lists |
|
||
|
||
### Networks and Explorers
|
||
|
||
| Chain ID | Network | Explorer | Token Logo Source |
|
||
|----------|---------|----------|-------------------|
|
||
| 138 | Chain 138 | explorer.d-bis.org | Blockscout DB / static / IPFS |
|
||
| 651940 | ALL Mainnet | — | Token list |
|
||
| 1 | Ethereum | etherscan.io | Contract metadata, token lists |
|
||
| 56 | BSC | bscscan.com | Same |
|
||
| 137 | Polygon | polygonscan.com | Same |
|
||
| 100 | Gnosis | gnosisscan.io | Same |
|
||
| 10 | Optimism | optimistic.etherscan.io | Same |
|
||
| 42161 | Arbitrum | arbiscan.io | Same |
|
||
| 8453 | Base | basescan.org | Same |
|
||
| 43114 | Avalanche | snowtrace.io | Same |
|
||
| 25 | Cronos | cronoscan.com | Same |
|
||
| 42220 | Celo | celoscan.io | Same |
|
||
| 1111 | Wemix | scan.wemix.com | Same |
|
||
|
||
**Key:** Third-party explorers (Etherscan, BSCScan, etc.) resolve logos from contract metadata, token lists, or their own registries. Our token list URL (`https://explorer.d-bis.org/api/v1/report/token-list`) provides logoURI for wallets. For Blockscout (our explorer), we control logo display.
|
||
|
||
---
|
||
|
||
## 2. Logo Inventory (All Tokens)
|
||
|
||
### Chain 138 Tokens (dbis-138.tokenlist.json)
|
||
|
||
| Symbol | Address (138) | Current logoURI |
|
||
|--------|---------------|-----------------|
|
||
| ETH-USD | 0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6 | ethereum.org |
|
||
| WETH | 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 | ethereum.org |
|
||
| WETH10 | 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f | ethereum.org |
|
||
| LINK | 0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03 | chainlink-docs |
|
||
| cUSDT | 0x93E66202A11B1772E55407B32B44e5Cd8eda7f22 | Trust Wallet |
|
||
| cUSDC | 0xf22258f57794CC8E06237084b353Ab30fFfa640b | Trust Wallet |
|
||
|
||
### Canonical Tokens (All Networks)
|
||
|
||
From `canonical-tokens.ts`: cUSDC, cUSDT, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT, LiXAU, USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW, WETH, WETH10, LINK, ETH-USD (oracle).
|
||
|
||
---
|
||
|
||
## 3. IPFS Setup Options
|
||
|
||
### Option A: Use Existing Firefly IPFS
|
||
|
||
If Firefly IPFS is running and has a public gateway:
|
||
|
||
```bash
|
||
# Gateway typically at http://<ipfs-host>:8080
|
||
# Add file: curl -X POST -F file=@logo.png "http://<ipfs-api>:5001/api/v0/add"
|
||
```
|
||
|
||
### Option B: Standalone Kubo (ProxmoxVE Script)
|
||
|
||
```bash
|
||
# Install Kubo on LXC via ProxmoxVE script
|
||
# ProxmoxVE/install/kubo-install.sh
|
||
# Then: ipfs add logo.png
|
||
```
|
||
|
||
### Option C: Pinata / Infura / Web3.Storage
|
||
|
||
For production, use a pinning service so logos stay available even when your node is offline:
|
||
|
||
- **Pinata:** https://pinata.cloud — free tier, pin by upload
|
||
- **Web3.Storage:** https://web3.storage — free, IPFS + Filecoin
|
||
- **Infura IPFS:** https://infura.io/product/ipfs
|
||
|
||
### Option D: Public Gateway (ipfs.io)
|
||
|
||
After `ipfs add`, use `https://ipfs.io/ipfs/<CID>` or `https://<cid>.ipfs.dweb.link`. No pinning service needed if you pin locally and others fetch; for reliability, use a pinning service.
|
||
|
||
---
|
||
|
||
## 4. Workflow: Prepare → Upload → Update
|
||
|
||
### Step 1: Prepare 512×512 PNGs
|
||
|
||
```bash
|
||
./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh
|
||
# Output: docs/04-configuration/coingecko/logos/*.png
|
||
```
|
||
|
||
### Step 2: Upload to IPFS
|
||
|
||
```bash
|
||
./scripts/upload-token-logos-to-ipfs.sh
|
||
# Uses: ipfs add (local) or Pinata API (if PINATA_JWT set)
|
||
# Output: docs/04-configuration/coingecko/logos/ipfs-manifest.json
|
||
```
|
||
|
||
### Step 3: Update Configs
|
||
|
||
- **Token list:** Replace logoURI with IPFS gateway URL
|
||
- **canonical-tokens.ts:** Add `logoUrl` to specs or change LOGO_BASE to IPFS
|
||
- **Blockscout:** Update `tokens.logo_url` via migration or admin; or serve from `/images/tokens/{address}.png` (nginx static)
|
||
|
||
### Step 4: Pin for Persistence
|
||
|
||
If using local IPFS: `ipfs pin add <CID>`
|
||
If using Pinata: upload pins the file automatically.
|
||
|
||
---
|
||
|
||
## 5. Blockscout Logo Paths
|
||
|
||
Blockscout can show token logos from:
|
||
|
||
1. **`tokens.logo_url`** — Set in DB per token (address). Use IPFS gateway URL.
|
||
2. **Static files** — `/images/tokens/{address}.png` (lowercase address). Nginx serves from Blockscout static dir or custom path.
|
||
3. **External URL** — If logo_url is an external URL, Blockscout may proxy or hotlink (check Blockscout version).
|
||
|
||
Recommended: Set `logo_url` in DB to `https://ipfs.io/ipfs/<CID>` or your gateway. Run migration to backfill:
|
||
|
||
```sql
|
||
UPDATE tokens SET logo_url = 'https://ipfs.io/ipfs/Qm...' WHERE address = '0x...';
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Chainlist Icon (eip155-138.json)
|
||
|
||
Chainlist requires `_data/icons/defioraclemeta.json` if you use `"icon": "defioraclemeta"`. Format:
|
||
|
||
```json
|
||
[{"url":"ipfs://Qm...","width":1000,"height":1628,"format":"png"}]
|
||
```
|
||
|
||
Upload chain logo (512×512 or larger) to IPFS, then add this file to chains repo. Or omit `icon` (current approach).
|
||
|
||
---
|
||
|
||
## 7. Checklist
|
||
|
||
- [x] Run `prepare-token-logos-512x512.sh` — all 24 tokens
|
||
- [x] Run `upload-token-logos-to-ipfs.sh` — CIDs in ipfs-manifest.json
|
||
- [ ] Run `upload-token-logos-to-ipfs.sh` — get CIDs
|
||
- [ ] Pin CIDs (local or Pinata/Web3.Storage)
|
||
- [ ] Update `dbis-138.tokenlist.json` logoURI to IPFS URLs
|
||
- [ ] Update `canonical-tokens.ts` LOGO_BASE or per-spec logoUrl
|
||
- [ ] Backfill Blockscout `tokens.logo_url` for Chain 138
|
||
- [ ] Serve `/images/tokens/{address}.png` from nginx (optional fallback)
|
||
- [ ] Add chain icon to Chainlist if desired
|
||
- [ ] Verify logos in MetaMask, Blockscout, token list API
|
||
|
||
---
|
||
|
||
## See Also
|
||
|
||
- [FULL_PARITY_TOKEN_COVERAGE_RUNBOOK](FULL_PARITY_TOKEN_COVERAGE_RUNBOOK.md)
|
||
- [PUBLICATION_LOCATIONS_MASTER](PUBLICATION_LOCATIONS_MASTER.md)
|
||
- [prepare-token-logos-512x512.sh](coingecko/scripts/prepare-token-logos-512x512.sh)
|
||
- [scripts/upload-token-logos-to-ipfs.sh](../../scripts/upload-token-logos-to-ipfs.sh)
|