d-bis/explorer-monorepo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harden explorer AI runtime and API ownership

Browse Source
This commit is contained in:
defiQUG
2026-03-27 14:12:14 -07:00
parent f6f25aa457
commit a18918ce91
10 changed files with 774 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/EXPLORER_API_ACCESS.md
View File

@@ -104,9 +104,22 @@ Or SSH into the VM (192.168.11.140) and run `df -h`, clear logs, remove unused D
| Chain 138 (Blockscout) | `https://explorer.d-bis.org/api/v2/blocks`, `/api/v2/transactions`, `/api/v2/addresses`, `/api/v2/stats`, etc. | **Blockscout** (Elixir) on port **4000** |
| Stats (optional) | `/api/v2/stats` | Blockscout or Go API |
| Config | `/api/config/token-list`, `/api/config/networks` | Go API (if used) |
| Explorer backend v1 | `/explorer-api/v1/features`, `/explorer-api/v1/auth/*`, `/explorer-api/v1/ai/*` | **Explorer Config API** (Go) on port **8081** |
| Explorer AI metrics | `/explorer-api/v1/ai/metrics` | **Explorer Config API** (Go) on port **8081** |
| Token aggregation | `/token-aggregation/api/v1/routes/*`, `/token-aggregation/api/v1/partner-payloads*` | **token-aggregation** service on port **3001** |
For the **static frontend + Blockscout** setup (VMID 5000), **nginx** must proxy `/api/` to **Blockscout** at `http://127.0.0.1:4000`. A 502 means nginx is up but the upstream (Blockscout) is down or unreachable.
### API ownership normalization
Use these ownership rules consistently:
- `/api/*` is reserved for **Blockscout** compatibility and v2 explorer reads.
- `/explorer-api/v1/*` is reserved for the **Go explorer backend** (auth, features, AI, explorer-owned helpers).
- `/token-aggregation/api/v1/*` is reserved for the **token-aggregation** service.
Avoid routing mixed services behind the same `/api/v1/*` prefix. That pattern caused the earlier conflicts where AI and feature endpoints were accidentally sent to token-aggregation or Blockscout.
### RPC and WebSocket (Chain 138)
The explorer uses **either FQDN or IP and port** for the Chain 138 RPC/WebSocket:
@@ -193,11 +206,31 @@ bash scripts/fix-explorer-complete.sh
bash scripts/fix-nginx-serve-custom-frontend.sh
```
### C. CORS (browser)
### C. Deploy or refresh the explorer AI backend
Use the dedicated deployment script when you need to:
- rebuild the Go explorer backend
- refresh `/opt/explorer-ai-docs`
- ensure a real `JWT_SECRET`
- install or refresh the explorer database override used for AI indexed context
- optionally install `OPENAI_API_KEY`
- normalize nginx for `/explorer-api/v1/*`
```bash
cd /path/to/explorer-monorepo
OPENAI_API_KEY=... bash scripts/deploy-explorer-ai-to-vmid5000.sh
```
If `OPENAI_API_KEY` is omitted, the AI context endpoint will still work, but chat will remain disabled with a backend `service_unavailable` response.
On VMID `5000`, the script also writes a dedicated `database.conf` drop-in for `explorer-config-api` so AI context can query the live Blockscout Postgres container instead of assuming `localhost:5432`.
### D. CORS (browser)
The frontend is same-origin (`https://explorer.d-bis.org`), so `/api/` is same-origin and CORS is not required for same-origin requests. The `add_header Access-Control-Allow-Origin *` above helps if you ever call the API from another origin.
### D. Optional: OPTIONS preflight
### E. Optional: OPTIONS preflight
If you need CORS preflight (e.g. custom headers from another site), add inside `location /api/`: