d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6945f69d7d28deb09eaaebb009035f6cf6c2ad52
proxmox/docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md
defiQUG dbd517b279 Sync workspace: config, docs, scripts, CI, operator rules, and submodule pointers. 
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains
- Omit embedded publish git dirs and empty placeholders from index

Made-with: Cursor
2026-04-12 06:12:20 -07:00

186 lines
11 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.
---
## 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