openapi: "3.0.3"
info:
  title: TBURN SNS Content Kit API
  description: |
    Public REST API for the TBURN SNS Content Kit (sns.tburn.io).
    Provides real-time TBURN L2 blockchain metrics: GARCH gas analytics,
    EWMA/Holt-Winters TPS forecasting, ZK rollup status, Shannon entropy mempool,
    Jain's fairness index, and composite health scoring.
    
    TBURN L1 Chain ID: 5800 | TBURN L2 Chain ID: 58001
    EMBER gas unit: 1 EMB = 10^12 wei | 1 TBURN = 10^18 wei = 10^6 EMB
  version: "1.0.0"
  contact:
    email: contact@tburn.io
    url: https://tburn.io
  license:
    name: Public API — No Auth Required
    url: https://sns.tburn.io

servers:
  - url: https://sns.tburn.io
    description: Production

paths:
  /api/l2/status:
    get:
      operationId: getL2Status
      summary: Full L2 sequencer metrics
      description: Returns complete TBURN L2 state including GARCH, EWMA, Holt-Winters, PID, ZK rollup, validators, and mempool.
      tags: [L2 Engine]
      responses:
        "200":
          description: L2 status payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "429":
          description: Rate limit exceeded (120 req/min per IP)

  /api/l2/gas:
    get:
      operationId: getL2Gas
      summary: GARCH(1,1) gas price + VaR95 + EMBER tiers
      description: |
        Returns current gas price computed via GARCH(1,1) model (ω=1e-6, α=0.10, β=0.85).
        Includes VaR95, Monte Carlo P95, and 4 EMBER gas tiers (Economy/Standard/Express/Instant).
      tags: [L2 Engine]
      responses:
        "200":
          description: Gas analytics payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "429":
          description: Rate limit exceeded

  /api/l2/health:
    get:
      operationId: getL2Health
      summary: Composite health score S/A/B/C/D
      description: |
        Returns composite health score (0-100) with letter grade S/A/B/C/D.
        Components: circuit breaker state, ZK proof success rate, finalization rate,
        mempool entropy score, EWMA TPS score.
      tags: [L2 Engine]
      responses:
        "200":
          description: Health assessment payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "429":
          description: Rate limit exceeded

  /api/l2/mempool:
    get:
      operationId: getL2Mempool
      summary: Shannon entropy + Jain's fairness + queue depths
      description: |
        Returns mempool congestion analytics:
        Shannon entropy H = -Σ pᵢ·log₂(pᵢ) (256-bin histogram, bits),
        Jain's fairness J = (Σxᵢ)² / (n·Σxᵢ²) ∈ [0,1],
        and 4 priority queue depths (Economy/Standard/Express/Instant).
      tags: [L2 Engine]
      responses:
        "200":
          description: Mempool analytics payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "429":
          description: Rate limit exceeded

  /api/l2/dashboard:
    get:
      operationId: getL2Dashboard
      summary: Aggregated L2 dashboard payload
      description: Returns combined status, gas, health, and mempool data in a single request.
      tags: [L2 Engine]
      responses:
        "200":
          description: Aggregated dashboard payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "429":
          description: Rate limit exceeded

  /api/l2/gas/forecast/{blocks}:
    get:
      operationId: garchForecast
      summary: GARCH k-step gas price forecast
      description: |
        Projects GARCH(1,1) variance k blocks forward using mean-reversion formula:
        projVariance = σ²_t × 0.95^k + longRunVar × (1 - 0.95^k)
        Returns P95 and P99 gas price estimates in wei and EMB.
      tags: [L2 Engine]
      parameters:
        - name: blocks
          in: path
          required: true
          description: Number of blocks to forecast (integer 1–100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: GARCH forecast payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid blocks parameter
        "429":
          description: Rate limit exceeded

  /api/l2/gas/estimate:
    get:
      operationId: gasEstimate
      summary: Istanbul + Monte Carlo P95 gas estimate
      description: |
        Estimates gas usage via Monte Carlo simulation (100 runs, CV-capped 0.5).
        Returns P50/P95/P99 and recommended = ceil(P95 × 1.10) with 10% safety margin.
        Uses Istanbul base: 21,000 gas.
      tags: [L2 Engine]
      parameters:
        - name: gas
          in: query
          required: false
          description: Base gas units (integer 21000–30000000, default 21000)
          schema:
            type: integer
            minimum: 21000
            maximum: 30000000
            default: 21000
      responses:
        "200":
          description: Gas estimate payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: Invalid gas parameter
        "429":
          description: Rate limit exceeded

  /api/federation/health:
    get:
      operationId: getFederationHealth
      summary: TBURN Federation Gateway L1 public health
      description: Returns public health status of the TBURN Federation Gateway (L1 Chain ID 5800). No HMAC auth required.
      tags: [Federation Gateway]
      responses:
        "200":
          description: Federation health payload
        "429":
          description: Rate limit exceeded

components:
  schemas:
    SuccessResponse:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Endpoint-specific payload
        error:
          type: string
          description: Error message (only present when success=false)