d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
proxmox/docs/04-configuration/IPFS_TOKEN_LOGOS_RUNBOOK.md

181 lines
6.7 KiB
Markdown
Raw Permalink Normal View History

chore: sync all changes to Gitea - Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
2026-03-02 11:37:34 -08:00
# 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)
Reference in New Issue Copy Permalink