d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
579a3bbe3a5ef114973496975ca25eebdcbcee1d
proxmox/docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md
defiQUG 76253586e7 feat(cloudflare): explorer.d-bis WAN DNS helper + d-bis.org SSL full mode 
- configure-explorer-d-bis-dns-wan.sh: PATCH explorer A (default 76.53.10.36), preserve proxied unless EXPLORER_D_BIS_CF_PROXIED set
- set-d-bis-org-zone-ssl-mode.sh: same SSL API as sankofa script for d-bis.org (fixes Flexible+NPM loops)
- TOKEN_AGGREGATION_REPORT_API_RUNBOOK: operator sequence for 502/522/loops + LAN fallback pointer

Made-with: Cursor
2026-04-13 22:26:26 -07:00

203 lines
13 KiB
Markdown
Raw Blame History

# 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. **Repo check:** `scripts/verify/check-public-report-api.sh` tries apex `/api/v1/` first, then `/token-aggregation/api/v1/`, and uses whichever returns a `.networks` array.
### 1.1 HTTPS 502 / 522 / redirect loops on `/token-aggregation/` while LAN is OK
If `curl -H "Host: explorer.d-bis.org" http://192.168.11.140/token-aggregation/api/v1/networks` is **200** but the public URL fails, nginx and `token-aggregation` on VMID **5000** are healthy; the break is usually **Cloudflare ↔ NPM ↔ WAN**.
**Operator sequence (repo scripts, from LAN with `.env`):**
1. **d-bis.org SSL mode Full** (fixes Flexible + NPM “SSL forced” redirect loops):
`bash scripts/cloudflare/set-d-bis-org-zone-ssl-mode.sh full`
2. **Explorer A record** (default primary WAN `76.53.10.36`, orange-cloud preserved unless you export `EXPLORER_D_BIS_CF_PROXIED`):
`bash scripts/cloudflare/configure-explorer-d-bis-dns-wan.sh`
If only an alternate WAN forwards cleanly to the NPM row for `explorer`, set e.g. `EXPLORER_D_BIS_WAN_A=76.53.10.34` (see `config/ip-addresses.conf` `PUBLIC_IP_ER605_WAN1`) and re-run.
3. **Verify:** `bash scripts/verify/check-public-report-api.sh` (or `BASE_URL=…` as below).
**LAN-only verification** (bypasses public DNS):
`bash scripts/verify/check-public-report-api.sh "http://192.168.11.140"`
**`run-completable-tasks-from-anywhere.sh`** retries that LAN URL automatically if the public HTTPS check fails.
---
## 2. Deploy token-aggregation (if not running)
### 2.1 On explorer VM (VMID 5000) or dedicated host
**Bundle + rsync (recommended from repo root on LAN):** builds with synced GRU/RPC env, then copies to `/opt/token-aggregation` and restarts `token-aggregation` systemd (if present):
```bash
bash scripts/deploy-token-aggregation-for-publication.sh ./token-aggregation-build
EXPLORER_SSH=root@192.168.11.140 bash scripts/deployment/push-token-aggregation-bundle-to-explorer.sh ./token-aggregation-build
```
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'
curl -s "http://localhost:3000/api/v1/bridge/preflight" | jq '.gruTransport.summary'
```
### 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 and (when reachable) on-chain PMM quotes on Chain 138 DODO pools |
| `TOKEN_AGGREGATION_CHAIN138_RPC_URL` | Optional explicit alias; `deploy-token-aggregation-for-publication.sh` sets this to the same public RPC as `RPC_URL_138` |
| `TOKEN_AGGREGATION_PMM_RPC_URL` | Optional: PMM `querySell*` calls only (e.g. operator core RPC) while keeping `CHAIN_138_RPC_URL` on the public node |
| `TOKEN_AGGREGATION_PMM_QUERY_TRADER` | Optional `trader` address for PMM view calls (defaults to deployer in code) |
| `DATABASE_URL` | PostgreSQL (required for full service) |
**Note:** The report endpoints may work with minimal config; full indexing requires DB and RPC. Successful PMM quotes return `quoteEngine: "pmm-onchain"` on `GET /api/v1/quote`; otherwise the service falls back to constant-product math (`quoteEngine: "constant-product"`).
### 2.3 GRU Transport runtime env on published explorer deployments
The public explorer deployment does more than token-list/report reads. `/api/v1/bridge/status`, `/api/v1/bridge/routes`, and `/api/v1/bridge/preflight` also resolve the GRU Monetary Transport overlay from runtime env.
At minimum, published `token-aggregation` deployments should carry:
- `CHAIN138_L1_BRIDGE`
- `CW_BRIDGE_MAINNET`, `CW_BRIDGE_CRONOS`, `CW_BRIDGE_BSC`, `CW_BRIDGE_POLYGON`, `CW_BRIDGE_GNOSIS`, `CW_BRIDGE_AVALANCHE`, `CW_BRIDGE_BASE`, `CW_BRIDGE_ARBITRUM`, `CW_BRIDGE_OPTIMISM`
- `CW_RESERVE_VERIFIER_CHAIN138`
- `CW_STABLECOIN_RESERVE_VAULT`
- `CW_RESERVE_SYSTEM`
- optional neutral reference: `CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138`
- the `CW_MAX_OUTSTANDING_*` caps referenced by [`gru-transport-active.json`](../../config/gru-transport-active.json)
- the gas-family refs referenced by [`gru-transport-active.json`](../../config/gru-transport-active.json), including `CW_BRIDGE_WEMIX`, `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138`, `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138`, `CW_GAS_ESCROW_VAULT_CHAIN138`, `CW_GAS_TREASURY_SYSTEM`, `CW_GAS_OUTSTANDING_*`, `CW_GAS_ESCROWED_*`, `CW_GAS_TREASURY_BACKED_*`, `CW_GAS_TREASURY_CAP_*`, and the gas-family `CW_MAX_OUTSTANDING_*` caps
`bash scripts/deploy-token-aggregation-for-publication.sh` now syncs the full GRU transport env surface from `config/gru-transport-active.json` into the deployed `.env` automatically, including the Chain 138 `CWReserveVerifier` from the latest Foundry broadcast artifact when the root repo env does not already export it, plus a neutral `CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` reference derived from [`config/smart-contracts-master.json`](../../config/smart-contracts-master.json). Gas-accounting refs default conservatively to `0` on publication builds when they are not supplied by the operator env so the API can publish the lane shape without inventing outstanding supply, and gas-lane `CW_MAX_OUTSTANDING_*` caps now derive from the lane-specific `perLaneCaps` declared in [`gru-transport-active.json`](../../config/gru-transport-active.json) instead of a blanket fallback. The deploy helper intentionally does not auto-fill `CW_GAS_STRICT_ESCROW_VERIFIER_CHAIN138` or `CW_GAS_HYBRID_CAP_VERIFIER_CHAIN138`; keep those unset until the live L1 bridge is explicitly wired to the gas verifier.
For a local non-secret gas env scaffold, run `bash scripts/verify/print-gas-runtime-env-canonical.sh`.
Deferred lanes such as the current `wemix` rollout remain visible in staged registry metadata, but the active `/api/v1/bridge/*` transport summary and the gas rollout verification scripts exclude them from active pair counts by default.
---
## 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 scripts/verify/check-token-aggregation-chain138-api.sh
# or: BASE_URL=https://explorer.d-bis.org bash scripts/verify/check-token-aggregation-chain138-api.sh
```
Expect `200` on tokens, pools, quote, networks, **`/api/v1/bridge/routes`**, **`/api/v1/bridge/status`**, and **`/api/v1/bridge/preflight`**. If `bridge/routes` or `bridge/preflight` is `404` or `{"error":"Not found"}`, the explorer host is still running an older token-aggregation build: redeploy the service from `smom-dbis-138/services/token-aggregation` and reload nginx.
```bash
# Reachability only
ALLOW_BLOCKED=1 bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
# Strict operator preflight: fails if any GRU pair is still blocked
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
```
```bash
# Gas rollout registry + deployment-status summary
SKIP_GAS_REGISTRY=0 bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
bash scripts/verify/check-gas-public-pool-status.sh
```
```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 | Indexer / DB | **Chain 138:** `CHAIN_138_DODO_PMM_INTEGRATION` defaults to canonical DODOPMMIntegration if unset. Set `DATABASE_URL`, run migrations, ensure RPC to 138. Also set `CUSDT_ADDRESS_138` / `CUSDC_ADDRESS_138` (see `smom-dbis-138/services/token-aggregation/.env.example`). |
| 502 Bad Gateway | Token-aggregation crashed or wrong port | Check logs; verify `TOKEN_AGG_PORT` matches service |
| `/api/v1/bridge/preflight` shows blocked pairs | Missing runtime env refs for GRU Transport | Run `bash scripts/verify/check-gru-transport-preflight.sh` and clear the reported `runtimeMissingRequirements` / `eligibilityBlockers` |
| `/api/v1/report/gas-registry` is missing or empty | Older token-aggregation build or gas rollout config not deployed | Redeploy `token-aggregation`, then verify `GET /api/v1/report/gas-registry?chainId=10` returns `gasAssetFamilies[]`, `gasRedeemGroups[]`, `chains[]`, and `gasProtocolExposure[]` |
| `/api/v1/bridge/preflight` returns `200` but gas lanes are blocked | Published service `.env` is missing the GRU gas bridge/verifier/cap block, or the live gas verifier has not been attached yet | Re-run `bash scripts/deploy-token-aggregation-for-publication.sh` or manually sync the `CHAIN138_L1_BRIDGE`, `CW_BRIDGE_*`, `CW_RESERVE_VERIFIER_CHAIN138`, `CW_STABLECOIN_RESERVE_VAULT`, `CW_RESERVE_SYSTEM`, `CW_GAS_*`, and `CW_MAX_OUTSTANDING_*` variables into `/opt/token-aggregation/.env`, then restart `token-aggregation`. Treat `CW_ASSET_RESERVE_VERIFIER_DEPLOYED_CHAIN138` as informational only until the live L1 bridge is explicitly wired. |
---
## 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
# 1b. GRU Transport operator preflight
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
# 1c. Gas-native rollout summary
SKIP_GAS_REGISTRY=0 bash scripts/verify/check-public-report-api.sh https://explorer.d-bis.org
bash scripts/verify/check-gas-public-pool-status.sh
# 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
Reference in New Issue View Git Blame Copy Permalink