proxmox/docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md

# 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