feat: explorer API, wallet, CCIP scripts, and config refresh

- Backend REST/gateway/track routes, analytics, Blockscout proxy paths. - Frontend wallet and liquidity surfaces; MetaMask token list alignment. - Deployment docs, verification scripts, address inventory updates. Check: go build ./... under backend/ (pass). Made-with: Cursor
2026-04-07 23:22:12 -07:00
parent 4044fb07e1
commit bdae5a9f6e
224 changed files with 19671 additions and 3291 deletions
--- a/docs/COMPLETE_BRIDGE_FIX_GUIDE.md
+++ b/docs/COMPLETE_BRIDGE_FIX_GUIDE.md
@@ -131,25 +131,27 @@ All checks should now pass.

 | Chain | Selector | Bridge Address |
 |-------|----------|----------------|
-| BSC | 11344663589394136015 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` |
-| Polygon | 4051577828743386545 | `0xa780ef19a041745d353c9432f2a7f5a241335ffe` |
-| Avalanche | 6433500567565415381 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` |
-| Base | 15971525489660198786 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` |
-| Arbitrum | 4949039107694359620 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` |
-| Optimism | 3734403246176062136 | `0x8078a09637e47fa5ed34f626046ea2094a5cde5e` |
-| Ethereum Mainnet | 5009297550715157269 | **TBD** (needs deployment/address) |
+| BSC | 11344663589394136015 | `0x24293CA562aE1100E60a4640FF49bd656cFf93B4` |
+| Polygon | 4051577828743386545 | `0xF7736443f02913e7e0773052103296CfE1637448` |
+| Avalanche | 6433500567565415381 | `0x24293CA562aE1100E60a4640FF49bd656cFf93B4` |
+| Base | 15971525489660198786 | `0x24293CA562aE1100E60a4640FF49bd656cFf93B4` |
+| Arbitrum | 4949039107694359620 | `0x937824f2516fa58f25aeAb92E7BFf7D74F463B4c` |
+| Optimism | 3734403246176062136 | `0x6e94e53F73893b2a6784Df663920D31043A6dE07` |
+| Ethereum Mainnet | 5009297550715157269 | `0xc9901ce2Ddb6490FAA183645147a87496d8b20B6` |

 ### WETH10 Bridge Destinations

 | Chain | Selector | Bridge Address |
 |-------|----------|----------------|
-| BSC | 11344663589394136015 | `0x105f8a15b819948a89153505762444ee9f324684` |
-| Polygon | 4051577828743386545 | `0xdab0591e5e89295ffad75a71dcfc30c5625c4fa2` |
-| Avalanche | 6433500567565415381 | `0x105f8a15b819948a89153505762444ee9f324684` |
-| Base | 15971525489660198786 | `0x105f8a15b819948a89153505762444ee9f324684` |
-| Arbitrum | 4949039107694359620 | `0x105f8a15b819948a89153505762444ee9f324684` |
-| Optimism | 3734403246176062136 | `0x105f8a15b819948a89153505762444ee9f324684` |
-| Ethereum Mainnet | 5009297550715157269 | **TBD** (needs deployment/address) |
+| BSC | 11344663589394136015 | `0x937824f2516fa58f25aeAb92E7BFf7D74F463B4c` |
+| Polygon | 4051577828743386545 | `0x0CA60e6f8589c540200daC9D9Cb27BC2e48eE66A` |
+| Avalanche | 6433500567565415381 | `0x937824f2516fa58f25aeAb92E7BFf7D74F463B4c` |
+| Base | 15971525489660198786 | `0x937824f2516fa58f25aeAb92E7BFf7D74F463B4c` |
+| Arbitrum | 4949039107694359620 | `0x73376eB92c16977B126dB9112936A20Fa0De3442` |
+| Optimism | 3734403246176062136 | `0x24293CA562aE1100E60a4640FF49bd656cFf93B4` |
+| Ethereum Mainnet | 5009297550715157269 | `0x04E1e22B0D41e99f4275bd40A50480219bc9A223` |
+
+Note: Arbitrum remains operationally blocked on the current Mainnet hub leg until the `0xc990... -> 42161` WETH9 path is repaired, even though the destination bridge addresses are known.

 ---

@@ -203,4 +205,3 @@ All checks should now pass.
 ---

 **Last Updated**: $(date)
-
--- a/docs/COMPLETION_SUMMARY.md
+++ b/docs/COMPLETION_SUMMARY.md
@@ -7,9 +7,10 @@ All implementation steps have been completed successfully. The tiered architectu
 ## Completed Components

 ### 1. ✅ Database Schema
- Migration file: `backend/database/migrations/0010_track_schema.up.sql`
+- Full migration file: `backend/database/migrations/0010_track_schema.up.sql`
+- Shared-DB auth/operator migration: `backend/database/migrations/0010_track_schema.auth_only.sql`
 - Rollback file: `backend/database/migrations/0010_track_schema.down.sql`
- Script: `scripts/run-migration-0010.sh`
+- Helper script: `scripts/run-migration-0010.sh` (auto-detects DB mode)

 ### 2. ✅ JWT Secret Configuration
 - Server reads `JWT_SECRET` from environment variable
@@ -65,7 +66,7 @@ bash scripts/setup-tiered-architecture.sh
 export JWT_SECRET="your-strong-secret-here"
 export RPC_URL="http://192.168.11.250:8545"

-# 3. Run migration
+# 3. Run migration helper
 bash scripts/run-migration-0010.sh

 # 4. Start server
@@ -94,4 +95,3 @@ The implementation is complete and ready for:
 5. Production deployment

 All code has been verified, linter errors resolved, and documentation completed.
-
--- a/docs/DATABASE_CONNECTION_GUIDE.md
+++ b/docs/DATABASE_CONNECTION_GUIDE.md
@@ -1,30 +1,45 @@
 # Database Connection Guide

-## Important: Two Different Database Users
+## Supported Database Layouts

-There are **two separate database systems**:
+The explorer backend supports **two deployment modes**:

-1. **Blockscout Database** (for Blockscout explorer)
-   - User: `blockscout`
-   - Password: `blockscout`
-   - Database: `blockscout`
+1. **Standalone explorer DB**
+   - User: usually `explorer`
+   - Database: usually `explorer`
+   - Migration mode: full Track 2-4 schema

-2. **Custom Explorer Backend Database** (for tiered architecture)
-   - User: `explorer`
-   - Password: `L@ker$2010`
-   - Database: `explorer`
+2. **Shared Blockscout DB**
+   - User: usually `blockscout`
+   - Database: usually `blockscout`
+   - Migration mode: explorer auth/operator subset only
+
+Use `bash scripts/run-migration-0010.sh` for both modes. The helper auto-detects whether it is connected to a standalone explorer database or a shared Blockscout database and chooses the safe migration path automatically.

 ## Correct Connection Command

-For the **custom explorer backend** (tiered architecture), use:
+For a **standalone explorer database**, use:

 ```bash
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT 1;"
+export DB_PASSWORD='<your explorer DB password>'
+PGPASSWORD="$DB_PASSWORD" psql -h localhost -U explorer -d explorer -c "SELECT 1;"
 ```

+For a **shared Blockscout database**, use:
+
+```bash
+export DB_HOST=localhost
+export DB_USER=blockscout
+export DB_NAME=blockscout
+export DB_PASSWORD='<your Blockscout DB password>'
+PGPASSWORD="$DB_PASSWORD" psql -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME" -c "SELECT 1;"
+```
+
+Do **not** run the full `0010_track_schema.up.sql` directly against the shared Blockscout DB.
+
 **NOT:**
 ```bash
-# ❌ Wrong - this is for Blockscout
+# ❌ Wrong - mismatched user/database pair
 PGPASSWORD='blockscout' psql -h localhost -U blockscout -d explorer -c "SELECT 1;"
 ```

@@ -34,40 +49,32 @@ PGPASSWORD='blockscout' psql -h localhost -U blockscout -d explorer -c "SELECT 1

 ```bash
 # Test connection to custom explorer database
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT version();"
+export DB_PASSWORD='<your explorer DB password>'
+PGPASSWORD="$DB_PASSWORD" psql -h localhost -U explorer -d explorer -c "SELECT version();"
 ```

 ### 2. Check if Tables Exist

 ```bash
-# Check for track schema tables
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "
-SELECT table_name 
-FROM information_schema.tables 
-WHERE table_schema = 'public' 
-AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers')
-ORDER BY table_name;
-"
+# Check the database mode and required tables
+bash scripts/check-database-connection.sh
 ```

 ### 3. Run Migration (if tables don't exist)

 ```bash
 cd explorer-monorepo
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer \
-  -f backend/database/migrations/0010_track_schema.up.sql
+export DB_PASSWORD='<your explorer DB password>'
+bash scripts/run-migration-0010.sh
 ```

 ### 4. Verify Migration

 ```bash
-# Should return 4 or more
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "
-SELECT COUNT(*) as table_count 
-FROM information_schema.tables 
-WHERE table_schema = 'public' 
-AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers', 'analytics_flows', 'operator_events');
-"
+# Standalone explorer DB should include Track 2-4 tables plus auth/operator tables.
+# Shared Blockscout DB should include at least:
+#   wallet_nonces, operator_roles, operator_events, operator_ip_whitelist
+bash scripts/check-database-connection.sh
 ```

 ## Troubleshooting
@@ -94,10 +101,10 @@ AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transf
   
   You should see both `blockscout` and `explorer` databases.

-4. **Create user and database if missing:**
+4. **Create a standalone explorer user and database if you want a dedicated backend DB:**
   ```bash
   sudo -u postgres psql << EOF
-   CREATE USER explorer WITH PASSWORD 'L@ker\$2010';
+   CREATE USER explorer WITH PASSWORD '<set-a-strong-password>';
   CREATE DATABASE explorer OWNER explorer;
   GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;
   \q
@@ -106,9 +113,10 @@ AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transf

 ### If Password Authentication Fails

-1. **Verify password is correct:**
-   - Custom explorer: `L@ker$2010`
-   - Blockscout: `blockscout`
+1. **Verify the correct password is exported in `DB_PASSWORD`**
+2. **Confirm you are connecting with the right mode pair**
+   - standalone explorer DB: `explorer` / `explorer`
+   - shared Blockscout DB: `blockscout` / `blockscout`

 2. **Check pg_hba.conf:**
   ```bash
@@ -128,7 +136,7 @@ Use the provided script:

 ```bash
 cd explorer-monorepo
-export DB_PASSWORD='L@ker$2010'
+export DB_PASSWORD='<your explorer DB password>'
 bash scripts/fix-database-connection.sh
 ```

@@ -144,7 +152,7 @@ This script will:
   ```bash
   pkill -f api-server
   cd explorer-monorepo/backend
-   export DB_PASSWORD='L@ker$2010'
+   export DB_PASSWORD='<your explorer DB password>'
   export JWT_SECRET='your-secret-here'
   ./bin/api-server
   ```
@@ -162,10 +170,10 @@ This script will:
     -H 'Content-Type: application/json' \
     -d '{"address":"0x1234567890123456789012345678901234567890"}'
   ```
+   If the response mentions `wallet_nonces`, returns `service_unavailable`, or the wallet popup shows `Nonce: undefined`, rerun `bash scripts/run-migration-0010.sh`, restart the backend, and retry.

 ## Summary

- **Custom Explorer Backend:** Use `explorer` user with password `L@ker$2010`
- **Blockscout:** Use `blockscout` user with password `blockscout`
- **They are separate systems** with separate databases
-
+- **Standalone explorer DB:** use the `explorer` user/database pair and the full Track 2-4 schema
+- **Shared Blockscout DB:** use the Blockscout credentials and let `scripts/run-migration-0010.sh` apply only the auth/operator subset
+- **Do not** apply `0010_track_schema.up.sql` directly to the shared Blockscout DB
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -10,6 +10,25 @@

 ### Quick Deploy

+For the current frontend, use the Next standalone deploy path:
+
+```bash
+# From explorer-monorepo root
+./scripts/deploy-next-frontend-to-vmid5000.sh
+```
+
+This builds `frontend/`, uploads the standalone bundle, installs the
+`solacescanscout-frontend.service` unit, and starts the frontend on
+`127.0.0.1:3000` inside VMID 5000.
+
+Nginx should keep the existing explorer API routes and proxy `/` plus `/_next/`
+to the frontend service. Use
+[nginx-next-frontend-proxy.conf](/home/intlc/projects/proxmox/explorer-monorepo/deployment/common/nginx-next-frontend-proxy.conf)
+inside the explorer server block after `/api`, `/api/config/*`, `/explorer-api/*`,
+`/token-aggregation/api/v1/*`, `/snap/`, and `/health`.
+
+### Legacy Static Deploy
+
 ```bash
 # From explorer-monorepo root
 ./scripts/deploy.sh
@@ -18,7 +37,10 @@
 ### Manual Deploy

 ```bash
-# Copy files manually
+# Canonical Next deployment:
+./scripts/deploy-next-frontend-to-vmid5000.sh
+
+# Legacy static fallback only:
 scp frontend/public/index.html root@192.168.11.140:/var/www/html/index.html
 ```

@@ -34,6 +56,33 @@ The deployment script uses these environment variables:
 IP=192.168.11.140 DOMAIN=explorer.d-bis.org ./scripts/deploy.sh
 ```

+## Mission-control and Track 4 runtime wiring
+
+If you are deploying the Go explorer API with the mission-control additions enabled, set these backend env vars as well:
+
+- `RPC_URL` - Chain 138 RPC for Track 1 and mission-control status/SSE data
+- `TOKEN_AGGREGATION_BASE_URL` - used by `GET /api/v1/mission-control/liquidity/token/{address}/pools`
+- `BLOCKSCOUT_INTERNAL_URL` - used by `GET /api/v1/mission-control/bridge/trace`
+- `EXPLORER_PUBLIC_BASE` - public base URL returned in bridge trace links
+- `CCIP_RELAY_HEALTH_URL` - optional relay probe URL, for example `http://192.168.11.11:9860/healthz`
+- `CCIP_RELAY_HEALTH_URLS` - optional comma-separated named relay probes, for example `mainnet=http://192.168.11.11:9860/healthz,bsc=http://192.168.11.11:9861/healthz,avax=http://192.168.11.11:9862/healthz`
+- `MISSION_CONTROL_CCIP_JSON` - optional JSON-file fallback for relay health snapshots
+- `OPERATOR_SCRIPTS_ROOT` - root directory for Track 4 script execution
+- `OPERATOR_SCRIPT_ALLOWLIST` - comma-separated allowlist for `POST /api/v1/track4/operator/run-script`
+- `OPERATOR_SCRIPT_TIMEOUT_SEC` - optional per-script timeout in seconds
+
+For nginx, include [nginx-mission-control-sse.conf](/home/intlc/projects/proxmox/explorer-monorepo/deployment/common/nginx-mission-control-sse.conf) inside the same server block that proxies `/explorer-api/`, and update the `proxy_pass` target if your Go API is not listening on `127.0.0.1:8080`.
+
+### Quick verification
+
+```bash
+curl -N https://explorer.d-bis.org/explorer-api/v1/mission-control/stream
+curl "https://explorer.d-bis.org/explorer-api/v1/mission-control/bridge/trace?tx=0x..."
+curl "https://explorer.d-bis.org/explorer-api/v1/mission-control/liquidity/token/0x93E66202A11B1772E55407B32B44e5Cd8eda7f22/pools"
+# Optional relay probe from the explorer host:
+curl http://192.168.11.11:9860/healthz
+```
+
 ## Rollback

 If deployment fails, rollback to previous version:
@@ -43,6 +92,10 @@ ssh root@192.168.11.140
 cp /var/www/html/index.html.backup.* /var/www/html/index.html
 ```

+For the Next standalone path, restart the previous release by repointing
+`/opt/solacescanscout/frontend/current` to the prior release and restarting
+`solacescanscout-frontend`.
+
 ## Testing

 After deployment, test the explorer:
@@ -56,4 +109,3 @@ Or manually:
 ```bash
 curl -k -I https://explorer.d-bis.org/
 ```
-
--- a/docs/DEPLOYMENT_COMPLETE.md
+++ b/docs/DEPLOYMENT_COMPLETE.md
@@ -25,7 +25,7 @@
 - ✅ `/api/v1/auth/nonce` - Endpoint active
 - ✅ `/api/v1/auth/wallet` - Endpoint active
 - ✅ JWT token generation configured
- ⚠️ Requires database for nonce storage
+- ⚠️ Requires database plus the `run-migration-0010.sh` helper for nonce storage

 ### 4. Feature Flags
 - ✅ `/api/v1/features` - Working
@@ -120,7 +120,7 @@ DB_NAME=explorer
 # Set correct password
 export DB_PASSWORD='your-actual-password'

-# Run migration
+# Run migration helper
 bash scripts/run-migration-0010.sh

 # Restart server
@@ -143,6 +143,8 @@ curl -X POST http://localhost:8080/api/v1/auth/wallet \
  -d '{"address":"...","signature":"...","nonce":"..."}'
 ```

+If the nonce request returns `service_unavailable`, mentions `wallet_nonces`, or the wallet signature popup shows `Nonce: undefined`, the backend is still missing the wallet-auth schema. Run `bash scripts/run-migration-0010.sh`, restart the backend, and retry. The helper auto-detects standalone explorer DB vs shared Blockscout DB and uses the safe migration path for each.
+
 ### 3. Approve Users
 ```bash
 # Approve for Track 2
@@ -217,4 +219,3 @@ The tiered architecture has been **successfully deployed and tested**. The API s
 5. Production deployment

 **Deployment Status: ✅ COMPLETE**
-
--- a/docs/DEPLOYMENT_STATUS.md
+++ b/docs/DEPLOYMENT_STATUS.md
@@ -34,7 +34,7 @@
 1. **Database Connection**
   - Status: ⚠️ Not connected
   - Impact: Track 1 endpoints work (use RPC), Track 2-4 require database
-   - Solution: Set `DB_PASSWORD` environment variable and run migration
+   - Solution: Set `DB_PASSWORD` environment variable and run `bash scripts/run-migration-0010.sh`

 2. **Health Endpoint**
   - Status: ⚠️ Returns degraded status (due to database)
@@ -49,7 +49,7 @@
 | `/api/v1/features` | ✅ Working | Returns track level and features |
 | `/api/v1/track1/blocks/latest` | ✅ Working | HTTP 200 |
 | `/api/v1/track1/bridge/status` | ✅ Working | Returns bridge status |
-| `/api/v1/auth/nonce` | ⚠️ HTTP 400 | Requires valid address format |
+| `/api/v1/auth/nonce` | ⚠️ DB-backed | Requires both a valid address and the `wallet_nonces` table created by `scripts/run-migration-0010.sh` |
 | `/api/v1/track2/search` | ✅ Working | Correctly requires auth (401) |

 ### Environment Configuration
@@ -94,6 +94,7 @@ DB_NAME=explorer
     -H 'Content-Type: application/json' \
     -d '{"address":"...","signature":"...","nonce":"..."}'
   ```
+   If the response mentions `wallet_nonces` or the wallet popup shows `Nonce: undefined`, rerun `bash scripts/run-migration-0010.sh` and restart the backend before retrying.

 ### Production Deployment

@@ -104,7 +105,7 @@ DB_NAME=explorer

 2. **Configure Database**
   - Set proper `DB_PASSWORD`
-   - Run migration: `bash scripts/run-migration-0010.sh`
+   - Run migration helper: `bash scripts/run-migration-0010.sh`
   - Verify connection: `bash scripts/check-database-connection.sh`

 3. **Start as Service**
@@ -156,4 +157,3 @@ curl http://localhost:8080/api/v1/features
 The tiered architecture has been successfully deployed. The API server is running and responding to requests. Track 1 endpoints (public RPC gateway) are fully functional. Track 2-4 endpoints are configured but require database connectivity for full functionality.

 **Deployment Status: ✅ SUCCESSFUL**
-
--- a/docs/ENV_COMPREHENSIVE_VERIFICATION.md
+++ b/docs/ENV_COMPREHENSIVE_VERIFICATION.md
@@ -63,8 +63,8 @@

 | Contract | Address | In .env | Variable Name | Status |
 |----------|---------|---------|---------------|--------|
-| **CCIPWETH9Bridge** | `0x2A0840e5117683b11682ac46f5CF5621E67269E3` | ✅ | `CCIPWETH9_BRIDGE_MAINNET` | ✅ Verified |
-| **CCIPWETH10Bridge** | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | ✅ | `CCIPWETH10_BRIDGE_MAINNET` | ✅ Verified |
+| **CCIPWETH9Bridge** | `0xc9901ce2Ddb6490FAA183645147a87496d8b20B6` | ✅ | `CCIPWETH9_BRIDGE_MAINNET` | ✅ Verified |
+| **CCIPWETH10Bridge** | `0x04E1e22B0D41e99f4275bd40A50480219bc9A223` | ✅ | `CCIPWETH10_BRIDGE_MAINNET` | ✅ Verified |

 ### Cross-Chain Contracts

--- a/docs/ENV_FINAL_COMPREHENSIVE_UPDATE.md
+++ b/docs/ENV_FINAL_COMPREHENSIVE_UPDATE.md
@@ -156,8 +156,8 @@ PRICEFEED_KEEPER_138=0xD3AD6831aacB5386B8A25BB8D8176a6C8a026f04
 ### Ethereum Mainnet Variables
 ```bash
 # Bridges
-CCIPWETH9_BRIDGE_MAINNET=0x2A0840e5117683b11682ac46f5CF5621E67269E3
-CCIPWETH10_BRIDGE_MAINNET=0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03
+CCIPWETH9_BRIDGE_MAINNET=0xc9901ce2Ddb6490FAA183645147a87496d8b20B6
+CCIPWETH10_BRIDGE_MAINNET=0x04E1e22B0D41e99f4275bd40A50480219bc9A223

 # Cross-Chain
 TRANSACTION_MIRROR_MAINNET=0x4CF42c4F1dBa748601b8938be3E7ABD732E87cE9
--- a/docs/EXPLORER_API_ACCESS.md
+++ b/docs/EXPLORER_API_ACCESS.md
@@ -13,6 +13,50 @@ The frontend is reachable at **https://explorer.d-bis.org** (FQDN) or by **VM IP
  2. **Same-origin /api** – When the site is served from the explorer host (FQDN `https://explorer.d-bis.org` or VM IP `http://192.168.11.140` / `https://192.168.11.140`), the frontend uses relative `/api` so all requests go through the same nginx proxy. If you open the frontend from elsewhere, the code falls back to the full Blockscout URL (CORS must allow it).
 - If the API returns **200** but the UI still shows no data, check the browser console for JavaScript errors (e.g. CSP or network errors).

+## Wallet connect fails with “nonce not found or expired”
+
+If the explorer shows a MetaMask sign-in failure such as:
+
+```text
+Authentication failed: nonce not found or expired
+```
+
+or the wallet signature request itself shows:
+
+```text
+Nonce: undefined
+```
+
+check the nonce endpoint directly:
+
+```bash
+curl -sS -H 'Content-Type: application/json' \
+  -X POST https://explorer.d-bis.org/explorer-api/v1/auth/nonce \
+  --data '{"address":"0x4A666F96fC8764181194447A7dFdb7d471b301C8"}'
+```
+
+If that returns an error mentioning:
+
+```text
+relation "wallet_nonces" does not exist
+```
+
+then the explorer backend is running without the wallet-auth schema migration. Run:
+
+```bash
+cd explorer-monorepo
+bash scripts/run-migration-0010.sh
+```
+
+`scripts/run-migration-0010.sh` now auto-detects the database layout:
+
+- **Standalone explorer DB**: applies the full Track 2-4 schema from `0010_track_schema.up.sql`
+- **Shared Blockscout DB**: applies only the explorer-owned auth/operator tables from `0010_track_schema.auth_only.sql`
+
+Do **not** pipe `0010_track_schema.up.sql` directly into the shared Blockscout database on VMID 5000; its `addresses` and `token_transfers` tables already exist with Blockscout's schema and the full migration will collide with them.
+
+The `Nonce: undefined` popup means the frontend asked for a nonce, got back an error instead of a nonce, and the old deployed frontend still opened the signature request anyway. After the helper migration, retry the nonce request and then retry wallet connect in the browser.
+
 ### Frontend env contract

 For the Next frontend in `frontend/`, keep the runtime base URL at the **host origin**, not the `/api` subpath:
@@ -340,6 +384,11 @@ The script checks:
 - HTTP 200 on `/api/v2/stats`, `/api/v2/blocks`, `/api/v2/transactions`.
 - Explorer frontend at `/` returns 200.
 - Chain 138 Snap companion site at `/snap/` returns 200 or 301 and contains expected content when 200.
+- The static Visual Command Center at `/chain138-command-center.html` returns 200 and contains expected architecture text.
+- Mission Control endpoints return healthy responses:
+  - `/explorer-api/v1/mission-control/stream`
+  - `/explorer-api/v1/mission-control/bridge/trace`
+  - `/explorer-api/v1/mission-control/liquidity/token/{address}/pools`

 **Full verification (single place for all checks — API, explorer, Snap):**

@@ -347,7 +396,7 @@ The script checks:
 bash scripts/verify-vmid5000-all.sh [BASE_URL]
 ```

-Run this after every deploy or nginx change to confirm explorer and Snap site are reachable and correct.
+Run this after every deploy or nginx change to confirm explorer, Snap site, Visual Command Center, and Mission Control are reachable and correct.

 ---

--- a/docs/FINAL_DEPLOYMENT_REPORT.md
+++ b/docs/FINAL_DEPLOYMENT_REPORT.md
@@ -23,9 +23,10 @@ The SolaceScanScout tiered architecture has been successfully deployed and teste
   - ✅ RPC integration working

 3. **Authentication System**
-   - ✅ Nonce endpoint active
+   - ✅ Nonce endpoint wired
   - ✅ Wallet authentication configured
   - ✅ JWT token generation ready
+   - ⚠️ Wallet sign-in requires database connectivity plus the `run-migration-0010.sh` helper (`wallet_nonces`)

 4. **Feature Flags**
   - ✅ Endpoint operational
@@ -39,8 +40,8 @@ The SolaceScanScout tiered architecture has been successfully deployed and teste

 ### ⚠️ Database Connection

-**Status:** Password authentication issue  
-**Impact:** Track 2-4 endpoints require database for full functionality  
+**Status:** Password authentication or schema issue  
+**Impact:** Track 2-4 endpoints and wallet sign-in require database for full functionality  
 **Workaround:** Track 1 endpoints work without database

 **To Fix:**
@@ -48,14 +49,16 @@ The SolaceScanScout tiered architecture has been successfully deployed and teste
 # Verify PostgreSQL is running
 systemctl status postgresql

-# Test connection with password
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT 1;"
+# Test connection with the configured explorer DB password
+export DB_PASSWORD='<your explorer DB password>'
+PGPASSWORD="$DB_PASSWORD" psql -h localhost -U explorer -d explorer -c "SELECT 1;"

-# If connection works, run migration
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer \
-  -f backend/database/migrations/0010_track_schema.up.sql
+# If connection works, run the migration helper
+bash scripts/run-migration-0010.sh
 ```

+The helper auto-detects standalone explorer DB vs shared Blockscout DB and picks the safe migration path.
+
 ## Test Results

 ### ✅ Passing Tests
@@ -68,7 +71,7 @@ PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer \
 | Track 1 | Blocks | ✅ PASS |
 | Track 1 | Transactions | ✅ PASS |
 | Track 1 | Bridge | ✅ PASS |
-| Auth | Nonce | ✅ PASS |
+| Auth | Nonce | ⚠️ PASS only when DB is reachable and `wallet_nonces` exists |
 | Track 2 | Auth Check | ✅ PASS (401) |
 | Track 3 | Auth Check | ✅ PASS (401) |
 | Track 4 | Auth Check | ✅ PASS (401) |
@@ -100,7 +103,7 @@ CHAIN_ID=138
 PORT=8080
 DB_HOST=localhost
 DB_USER=explorer
-DB_PASSWORD=L@ker$2010
+DB_PASSWORD=<set in environment>
 DB_NAME=explorer
 ```

@@ -120,7 +123,8 @@ sudo systemctl start postgresql
 **Option B: Verify Credentials**
 ```bash
 # Test connection
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT 1;"
+export DB_PASSWORD='<your explorer DB password>'
+PGPASSWORD="$DB_PASSWORD" psql -h localhost -U explorer -d explorer -c "SELECT 1;"

 # If this fails, check:
 # 1. User exists: psql -U postgres -c "\du"
@@ -128,12 +132,11 @@ PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer -c "SELECT 1;"
 # 3. Password is correct
 ```

-**Option C: Run Migration**
+**Option C: Run Migration Helper**
 ```bash
 cd explorer-monorepo
-export DB_PASSWORD='L@ker$2010'
-PGPASSWORD='L@ker$2010' psql -h localhost -U explorer -d explorer \
-  -f backend/database/migrations/0010_track_schema.up.sql
+export DB_PASSWORD='<your explorer DB password>'
+bash scripts/run-migration-0010.sh
 ```

 ### 2. Restart Server with Database
@@ -144,7 +147,7 @@ pkill -f api-server

 # Start with database
 cd backend
-export DB_PASSWORD='L@ker$2010'
+export DB_PASSWORD='<your explorer DB password>'
 export JWT_SECRET='your-secret-here'
 ./bin/api-server
 ```
@@ -169,10 +172,12 @@ curl http://localhost:8080/api/v1/track2/search?q=test \

 ```bash
 # After database is connected
-export DB_PASSWORD='L@ker$2010'
+export DB_PASSWORD='<your explorer DB password>'
 bash scripts/approve-user.sh <address> <track_level>
 ```

+If the nonce request mentions `wallet_nonces`, returns `service_unavailable`, or the wallet popup shows `Nonce: undefined`, rerun `bash scripts/run-migration-0010.sh`, restart the backend, and retry. On the shared VMID 5000 Blockscout database, this helper applies only the auth/operator subset and avoids colliding with Blockscout's existing `addresses` schema.
+
 ## Monitoring

 ### Server Logs
@@ -213,4 +218,3 @@ The tiered architecture deployment is **complete and operational**. Track 1 (pub
 - User authentication testing
 - User approval workflow
 - Indexer startup
-
--- a/docs/METAMASK_AND_PROVIDER_INTEGRATION.md
+++ b/docs/METAMASK_AND_PROVIDER_INTEGRATION.md
@@ -9,7 +9,9 @@ The explorer (SolaceScanScout) provides add-to-MetaMask and token list discovery
  - **Path:** `/api/config/token-list`
  - **Full URL:** `{EXPLORER_API_BASE}/api/config/token-list` (e.g. `https://explorer.d-bis.org/api/config/token-list` if the API is on the same origin).
  Add this URL in MetaMask **Settings → Token lists** so tokens for Chain 138 and Mainnet appear automatically.
+  As of April 3, 2026, the public explorer token list exposes `190` entries, including the full Mainnet `cW*` suite.
 - **Networks config:** `/api/config/networks` returns the same chain params (Chain 138 + Ethereum Mainnet) in JSON for programmatic use.
+- **GRU v2 public rollout status:** the explorer also publishes static status surfaces at `/config/GRU_V2_PUBLIC_DEPLOYMENT_STATUS.json` and `/config/GRU_V2_DEPLOYMENT_QUEUE.json`. Together they summarize the public EVM `cW*` mesh, Wave 1 transport posture, the current public-protocol truth for `Uniswap v3`, `Balancer`, `Curve 3`, `DODO PMM`, and `1inch`, and the remaining operator queue by asset/chain/protocol.

 ## Provider and feature parity

@@ -32,8 +34,11 @@ Discovery is via **token list** (hosted at the explorer token list URL above), *
 - **Wallet page:** https://explorer.d-bis.org/wallet  
 - **Token list URL:** https://explorer.d-bis.org/api/config/token-list  
 - **Networks config:** https://explorer.d-bis.org/api/config/networks  
+- **GRU v2 public rollout status:** https://explorer.d-bis.org/config/GRU_V2_PUBLIC_DEPLOYMENT_STATUS.json
+- **GRU v2 deployment queue:** https://explorer.d-bis.org/config/GRU_V2_DEPLOYMENT_QUEUE.json

 For backend deployment and integration tests, see [EXPLORER_D_BIS_ORG_INTEGRATION.md](../../docs/04-configuration/metamask/EXPLORER_D_BIS_ORG_INTEGRATION.md).
+For token-list publishing, use `explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh`; it now falls back through the Proxmox host automatically when local `pct` is not installed.

 ## Related

--- a/docs/PRODUCTION_CHECKLIST.md
+++ b/docs/PRODUCTION_CHECKLIST.md
@@ -10,11 +10,12 @@ Before running the Explorer API and indexer in production:
   See `deployment/ENVIRONMENT_TEMPLATE.env` for all required variables.

 2. **Run database migrations**  
-   Apply migrations before starting the API and indexer, e.g.:
+   Apply migrations before starting the API and indexer:
   ```bash
-   psql -U explorer -d explorer -f backend/database/migrations/0010_track_schema.up.sql
+   export DB_PASSWORD='<your DB password>'
+   bash scripts/run-migration-0010.sh
   ```
-   Or use your migration runner (e.g. `go run backend/database/migrations/migrate.go --up` if applicable).
+   `scripts/run-migration-0010.sh` auto-detects standalone explorer DB vs shared Blockscout DB. Do **not** apply `backend/database/migrations/0010_track_schema.up.sql` directly to a shared Blockscout database.

 3. **Configure DB and RPC**  
   Ensure `DB_*`, `RPC_URL`, `WS_URL`, and `CHAIN_ID` are set correctly for the target environment.
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,16 +18,24 @@ Overview of documentation for the ChainID 138 Explorer (SolaceScanScout).

 | Doc | Description |
 |-----|-------------|
-| **[../frontend/FRONTEND_REVIEW.md](../frontend/FRONTEND_REVIEW.md)** | Frontend code review (SPA + React) |
+| **[../frontend/FRONTEND_REVIEW.md](../frontend/FRONTEND_REVIEW.md)** | Frontend code review (Next app + legacy SPA) |
 | **[../frontend/FRONTEND_TASKS_AND_REVIEW.md](../frontend/FRONTEND_TASKS_AND_REVIEW.md)** | Task list C1–L4 and detail review |

-**Deploy the live SPA (VMID 5000):**
+**Deploy the current Next standalone frontend (VMID 5000):**
+
+```bash
+./scripts/deploy-next-frontend-to-vmid5000.sh
+```
+
+Nginx should preserve `/api`, `/api/config/*`, `/explorer-api/*`, `/token-aggregation/api/v1/*`, `/snap/`, and `/health`, then proxy `/` and `/_next/` using [deployment/common/nginx-next-frontend-proxy.conf](/home/intlc/projects/proxmox/explorer-monorepo/deployment/common/nginx-next-frontend-proxy.conf).
+
+**Legacy static SPA deploy (fallback only):**

 ```bash
 ./scripts/deploy-frontend-to-vmid5000.sh
 ```

-**Full fix (Blockscout + nginx + frontend):**
+**Full explorer/API fix (Blockscout + nginx + frontend):**

 ```bash
 ./scripts/complete-explorer-api-access.sh
--- a/docs/TIERED_ARCHITECTURE_IMPLEMENTATION.md
+++ b/docs/TIERED_ARCHITECTURE_IMPLEMENTATION.md
@@ -30,7 +30,7 @@ All components have been implemented according to the plan:
 ### ✅ Phase 4: Track 2 (Full Indexed Explorer)
 - **Indexers**: Block, transaction, and token indexers (`backend/indexer/track2/`)
 - **Track 2 API**: All endpoints implemented (`backend/api/track2/endpoints.go`)
- **Database Schema**: Complete schema for indexed data (`backend/database/migrations/0010_track_schema.up.sql`)
+- **Database Schema**: Full Track 2-4 schema plus shared-DB-safe auth/operator subset (`backend/database/migrations/0010_track_schema.up.sql`, `backend/database/migrations/0010_track_schema.auth_only.sql`)

 ### ✅ Phase 5: Track 3 (Analytics)
 - **Analytics Engine**: Flow tracking, bridge analytics, token distribution (`backend/analytics/`)
@@ -80,7 +80,8 @@ Backend
 - `backend/analytics/` - Analytics engine

 ### Database
- `backend/database/migrations/0010_track_schema.up.sql` - Track 2-4 schema
+- `backend/database/migrations/0010_track_schema.up.sql` - full Track 2-4 schema
+- `backend/database/migrations/0010_track_schema.auth_only.sql` - shared Blockscout DB auth/operator subset

 ### Frontend
 - Updated `frontend/public/index.html` with feature gating
@@ -89,9 +90,10 @@ Backend

 1. **Run Database Migrations**:
   ```bash
-   cd explorer-monorepo/backend/database/migrations
-   # Run migration 0010_track_schema.up.sql
+   cd explorer-monorepo
+   bash scripts/run-migration-0010.sh
   ```
+   The helper auto-detects standalone explorer DB vs shared Blockscout DB and chooses the safe migration path automatically.

 2. **Configure JWT Secret**:
   - Update `backend/api/rest/auth.go` to use environment variable for JWT secret
@@ -126,4 +128,3 @@ Test each track level:
 - JWT secret is hardcoded in auth.go - move to environment variable
 - Track routes are commented in routes.go - uncomment and wire up middleware when ready
 - Frontend feature gating is implemented but needs testing with actual API responses
-
--- a/docs/TIERED_ARCHITECTURE_SETUP.md
+++ b/docs/TIERED_ARCHITECTURE_SETUP.md
@@ -26,9 +26,9 @@ cd backend

 ### Required
 - `DB_HOST` - PostgreSQL host (default: localhost)
- `DB_USER` - Database user (default: explorer)
+- `DB_USER` - Database user (default: explorer; use `blockscout` for the shared Blockscout DB mode)
 - `DB_PASSWORD` - Database password (default: changeme)
- `DB_NAME` - Database name (default: explorer)
+- `DB_NAME` - Database name (default: explorer; use `blockscout` for the shared Blockscout DB mode)

 ### Recommended (Production)
 - `JWT_SECRET` - Strong random secret for JWT signing (required for production)
@@ -38,17 +38,18 @@ cd backend

 ## Database Migration

-Run the Track 2-4 schema migration:
+Run the migration helper:

 ```bash
 bash scripts/run-migration-0010.sh
 ```

-This creates:
- Track 2 tables: `addresses`, `token_transfers`, `token_balances`, `internal_transactions`
- Track 3 tables: `analytics_flows`, `analytics_bridge_history`, `token_distribution` (materialized view)
- Track 4 tables: `operator_events`, `operator_ip_whitelist`, `operator_roles`
- Auth table: `wallet_nonces`
+The helper auto-detects the database layout:
+
+- **Standalone explorer DB**: creates the full Track 2-4 schema
+- **Shared Blockscout DB**: creates only `operator_events`, `operator_ip_whitelist`, `operator_roles`, and `wallet_nonces`
+
+Do **not** apply `backend/database/migrations/0010_track_schema.up.sql` directly to the shared Blockscout DB.

 ## User Management

@@ -152,11 +153,13 @@ The indexers will:
 ### Migration Fails
 - Check database connection: `psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"`
 - Verify user has CREATE TABLE permissions
+- If you are using the shared Blockscout DB, keep `DB_USER` and `DB_NAME` aligned to `blockscout`

 ### Authentication Fails
 - Check JWT_SECRET is set
 - Verify wallet_nonces table exists
 - Check database connection in auth handlers
+- If the wallet popup shows `Nonce: undefined`, the nonce request failed before signing. Run `bash scripts/run-migration-0010.sh`, restart the backend, and retry.

 ### Track Routes Not Working
 - Verify user is approved: Check `operator_roles` table
@@ -179,4 +182,3 @@ The indexers will:
 7. ✅ Verify feature gating

 For detailed API documentation, see: `docs/api/track-api-contracts.md`
-
--- a/docs/openapi/mission-control.openapi.yaml
+++ b/docs/openapi/mission-control.openapi.yaml
@@ -0,0 +1,104 @@
+openapi: 3.0.3
+info:
+  title: Explorer mission-control API
+  version: "1.0"
+  description: |
+    Public health, liquidity proxy, and bridge-trace helpers on the Go REST service.
+    SSE for `/mission-control/stream` should be proxied with **proxy_buffering off** so chunks flush (see `deployment/common/nginx-mission-control-sse.conf`).
+servers:
+  - url: /explorer-api/v1
+paths:
+  /mission-control/stream:
+    get:
+      summary: Server-Sent Events stream of bridge/RPC health
+      description: |
+        `Content-Type: text/event-stream`. Emits `event: mission-control` with JSON `{"data":{...}}` immediately, then every 20s.
+        Same inner `data` shape as `GET /track1/bridge/status`.
+      responses:
+        "200":
+          description: SSE stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+  /mission-control/liquidity/token/{address}/pools:
+    get:
+      summary: Cached proxy to token-aggregation pools
+      parameters:
+        - name: address
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{40}$'
+      responses:
+        "200":
+          description: Upstream JSON (pass-through)
+        "503":
+          description: TOKEN_AGGREGATION_BASE_URL not set
+  /mission-control/bridge/trace:
+    get:
+      summary: Resolve tx `to`/`from` via Blockscout and label with smart-contracts-master
+      parameters:
+        - name: tx
+          in: query
+          required: true
+          schema:
+            type: string
+            pattern: '^0x[a-fA-F0-9]{64}$'
+      responses:
+        "200":
+          description: Labeled trace
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      tx_hash:
+                        type: string
+                      from:
+                        type: string
+                      to:
+                        type: string
+                      from_registry:
+                        type: string
+                      to_registry:
+                        type: string
+                      blockscout_url:
+                        type: string
+  /track4/operator/run-script:
+    post:
+      summary: Run an allowlisted script under OPERATOR_SCRIPTS_ROOT (Track 4 + IP whitelist)
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [script]
+              properties:
+                script:
+                  type: string
+                  description: Path relative to OPERATOR_SCRIPTS_ROOT (no ..)
+                args:
+                  type: array
+                  items:
+                    type: string
+                  maxItems: 24
+      responses:
+        "200":
+          description: stdout/stderr and exit code
+        "403":
+          description: Not allowlisted or not whitelisted IP
+        "503":
+          description: Root or allowlist not configured
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer