explorer-monorepo/backend/api/rest/README.md

# REST API Server

REST API implementation for the ChainID 138 Explorer Platform.

## Structure

- `server.go` - Main server setup and route configuration
- `routes.go` - Route handlers and URL parsing
- `blocks.go` - Block-related endpoints
- `transactions.go` - Transaction-related endpoints
- `addresses.go` - Address-related endpoints
- `search.go` - Unified search endpoint
- `mission_control.go` - Mission-control bridge trace and cached liquidity helpers
- `validation.go` - Input validation utilities
- `middleware.go` - HTTP middleware (logging, compression)
- `errors.go` - Error response utilities

## API Endpoints

### Blocks
- `GET /api/v1/blocks` - List blocks (paginated)
- `GET /api/v1/blocks/{chain_id}/{number}` - Get block by number
- `GET /api/v1/blocks/{chain_id}/hash/{hash}` - Get block by hash

### Transactions
- `GET /api/v1/transactions` - List transactions (paginated, filterable)
- `GET /api/v1/transactions/{chain_id}/{hash}` - Get transaction by hash

### Addresses
- `GET /api/v1/addresses/{chain_id}/{address}` - Get address information

### Search
- `GET /api/v1/search?q={query}` - Unified search (auto-detects type: block number, address, or transaction hash)

### Health
- `GET /health` - Health check endpoint

### Mission control
- `GET /api/v1/mission-control/stream` - SSE stream for bridge/RPC health
- `GET /api/v1/mission-control/bridge/trace?tx=0x...` - Blockscout-backed tx trace with Chain 138 contract labels
- `GET /api/v1/mission-control/liquidity/token/{address}/pools` - 30-second cached proxy to token-aggregation pools

### Track 4 operator
- `POST /api/v1/track4/operator/run-script` - Run an allowlisted script under `OPERATOR_SCRIPTS_ROOT`

## Features

- Input validation (addresses, hashes, block numbers)
- Pagination support
- Query timeouts for database operations
- CORS headers
- Request logging
- Error handling with consistent error format
- Health checks with database connectivity

## Running

```bash
cd backend/api/rest
go run main.go
```

Or use the development script:
```bash
./scripts/run-dev.sh
```

## Configuration

Set environment variables:
- `DB_HOST` - Database host
- `DB_PORT` - Database port
- `DB_USER` - Database user
- `DB_PASSWORD` - Database password
- `DB_NAME` - Database name
- `PORT` - API server port (default: 8080)
- `CHAIN_ID` - Chain ID (default: 138)
- `RPC_URL` - Chain RPC used by Track 1 and mission-control health/SSE data
- `TOKEN_AGGREGATION_BASE_URL` - Upstream token-aggregation base URL for mission-control liquidity proxy
- `BLOCKSCOUT_INTERNAL_URL` - Internal Blockscout base URL for bridge trace lookups
- `EXPLORER_PUBLIC_BASE` - Public explorer base URL used in mission-control trace responses
- `CCIP_RELAY_HEALTH_URL` - Optional relay health 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 snapshot fallback when relay health is provided as a file instead of an HTTP endpoint
- `OPERATOR_SCRIPTS_ROOT` - Root directory for allowlisted Track 4 scripts
- `OPERATOR_SCRIPT_ALLOWLIST` - Comma-separated list of permitted script names or relative paths
- `OPERATOR_SCRIPT_TIMEOUT_SEC` - Optional Track 4 script timeout in seconds (max 599)

## Mission-control deployment notes

- Include `explorer-monorepo/deployment/common/nginx-mission-control-sse.conf` in the same nginx server block that proxies `/explorer-api/`.
- Keep the nginx upstream port aligned with the Go API `PORT`.
- Verify internal reachability to `BLOCKSCOUT_INTERNAL_URL` and `TOKEN_AGGREGATION_BASE_URL` from the API host before enabling the mission-control cards in production.