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