explorer-monorepo/backend/api/rest

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

cd backend/api/rest
go run main.go

Or use the development script:

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