proxmox/docs/04-configuration/IPFS_TOKEN_LOGOS_RUNBOOK.md

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:

# 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)

# 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

./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh
# Output: docs/04-configuration/coingecko/logos/*.png

Step 2: Upload to IPFS

./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:

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:

[{"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

• Run prepare-token-logos-512x512.sh — all 24 tokens
• 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
• PUBLICATION_LOCATIONS_MASTER
• prepare-token-logos-512x512.sh
• scripts/upload-token-logos-to-ipfs.sh