# 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://:8080 # Add file: curl -X POST -F file=@logo.png "http://: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/` or `https://.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 ` 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/` 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)