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

# 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 on /token-aggregation/ while LAN is OK

If curl https://explorer.d-bis.org/token-aggregation/api/v1/networks returns 502 but curl -H "Host: explorer.d-bis.org" http://192.168.11.140/token-aggregation/api/v1/networks is 200, nginx and token-aggregation on VMID 5000 are healthy; suspect WAN port-forward or public IP routing (one public IP may forward correctly while another does not). Compare curl -k --resolve explorer.d-bis.org:443:<candidate_wan_ip> across routed NPM addresses, fix UDM/NAT or Cloudflare A for explorer, or rely on LAN verification: 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 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:

   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):

   # Example systemd unit
   ExecStart=/usr/bin/node /opt/token-aggregation/dist/index.js
   WorkingDirectory=/opt/token-aggregation
   

3. Verify locally:

   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
• the gas-family refs referenced by 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. 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 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):

# 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 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.

# 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

# 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 metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org

All checks should pass. Then:

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.

---

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

# 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 checklist
• CMC_COINGECKO_SUBMISSION_RUNBOOK — Export and submit
• smom-dbis-138/services/token-aggregation/README.md — Service setup