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
125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
# Token-Aggregation Report API — Reachability Runbook
|
|
|
|
**Purpose:** Ensure `GET /api/v1/report/coingecko`, `GET /api/v1/report/cmc`, and `GET /api/v1/report/token-list` are reachable for CoinGecko/CMC submission and Chain 138 Snap.
|
|
|
|
---
|
|
|
|
## 1. Verify current state
|
|
|
|
```bash
|
|
# From repo root
|
|
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
|
|
```
|
|
|
|
**Expected when working:** Token list and networks return valid JSON with `.tokens` and `.networks`.
|
|
|
|
**If you see "no .tokens" or "no .networks":** The `/api/v1/` path is likely proxied to Blockscout (or another backend) instead of token-aggregation. Proceed to §2.
|
|
|
|
---
|
|
|
|
## 2. Deploy token-aggregation (if not running)
|
|
|
|
### 2.1 On explorer VM (VMID 5000) or dedicated host
|
|
|
|
1. **Deploy the service:**
|
|
```bash
|
|
cd smom-dbis-138/services/token-aggregation
|
|
cp .env.example .env
|
|
# Edit .env: DATABASE_URL, CUSDC_ADDRESS_138, CUSDT_ADDRESS_138 (minimum for report)
|
|
npm install && npm run build
|
|
```
|
|
|
|
2. **Run via systemd** (or use `deploy-to-proxmox.sh` / `deploy-to-vmid.sh`):
|
|
```bash
|
|
# Example systemd unit
|
|
ExecStart=/usr/bin/node /opt/token-aggregation/dist/index.js
|
|
WorkingDirectory=/opt/token-aggregation
|
|
```
|
|
|
|
3. **Verify locally:**
|
|
```bash
|
|
curl -s "http://localhost:3000/api/v1/report/token-list?chainId=138" | jq '.tokens | length'
|
|
curl -s "http://localhost:3000/api/v1/report/coingecko?chainId=138" | jq '.'
|
|
curl -s "http://localhost:3000/api/v1/networks" | jq '.networks | length'
|
|
```
|
|
|
|
### 2.2 Minimum env for report API
|
|
|
|
| Var | Purpose |
|
|
|-----|---------|
|
|
| `CUSDC_ADDRESS_138` | cUSDC on Chain 138 |
|
|
| `CUSDT_ADDRESS_138` | cUSDT on Chain 138 |
|
|
| `CHAIN_138_RPC_URL` or `RPC_URL_138` | RPC for indexing |
|
|
| `DATABASE_URL` | PostgreSQL (required for full service) |
|
|
|
|
**Note:** The report endpoints may work with minimal config; full indexing requires DB and RPC.
|
|
|
|
---
|
|
|
|
## 3. Proxy /api/v1/ to token-aggregation (explorer.d-bis.org)
|
|
|
|
If token-aggregation runs on the **explorer VM** (e.g. port 3000):
|
|
|
|
```bash
|
|
# SSH to explorer VM (VMID 5000), then:
|
|
TOKEN_AGG_PORT=3000 CONFIG_FILE=/etc/nginx/sites-available/blockscout \
|
|
bash /path/to/explorer-monorepo/scripts/apply-nginx-token-aggregation-proxy.sh
|
|
```
|
|
|
|
This inserts `location /api/v1/` proxying to `http://127.0.0.1:3000/api/v1/`. **Important:** The token-aggregation `location` must be defined **before** any Blockscout API `location` that might also match `/api/v1/`, so token-aggregation takes precedence.
|
|
|
|
### 3.1 If token-aggregation runs elsewhere
|
|
|
|
- **Option A:** Run token-aggregation on the explorer host (same machine as nginx) and proxy to `127.0.0.1:3000`.
|
|
- **Option B:** Run on a different host; proxy to that host, e.g. `proxy_pass http://192.168.11.XXX:3000/api/v1/;`
|
|
- **Option C:** Use a separate domain (e.g. `api.d-bis.org`) for the token-aggregation API and set `GATSBY_SNAP_API_BASE_URL` to that URL when building the Snap site.
|
|
|
|
---
|
|
|
|
## 4. Re-verify
|
|
|
|
```bash
|
|
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
|
|
```
|
|
|
|
All checks should pass. Then:
|
|
|
|
```bash
|
|
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
|
|
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
|
|
```
|
|
|
|
Use these files for CoinGecko/CMC submission per [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md).
|
|
|
|
---
|
|
|
|
## 5. Troubleshooting
|
|
|
|
| Issue | Cause | Fix |
|
|
|-------|-------|-----|
|
|
| `curl .../api/v1/report/token-list` returns Blockscout-style JSON (`message`, `result`, `status`) | `/api/v1/` proxied to Blockscout, not token-aggregation | Ensure token-aggregation `location` is first; reload nginx |
|
|
| Connection refused to 127.0.0.1:3000 | Token-aggregation not running | Start service; check `systemctl status token-aggregation` |
|
|
| Empty `tokens` array | `CUSDC_ADDRESS_138`, `CUSDT_ADDRESS_138` unset or wrong | Set in `.env`; restart service |
|
|
| 502 Bad Gateway | Token-aggregation crashed or wrong port | Check logs; verify `TOKEN_AGG_PORT` matches service |
|
|
|
|
---
|
|
|
|
## 6. Quick commands summary
|
|
|
|
```bash
|
|
# 1. Verify (from repo root)
|
|
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
|
|
|
|
# 2. Export for submission (after API is reachable)
|
|
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
|
|
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Related docs
|
|
|
|
- [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md) — Price feed checklist
|
|
- [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) — Export and submit
|
|
- [smom-dbis-138/services/token-aggregation/README.md](../../../smom-dbis-138/services/token-aggregation/README.md) — Service setup
|