{
  "openapi": "3.1.0",
  "info": {
    "title": "Montrevane Transparency API",
    "version": "0.1.0-beta",
    "description": "Public read-only OP Mainnet evidence endpoint. It exposes values only when at least two of four fixed RPC endpoints return the same block hash and contract observations at one finalized block. Full observations use at most the three available endpoints with the highest finalized heads. It is not a price, valuation, circulating-supply, audit, legal or listing data source."
  },
  "servers": [
    { "url": "https://montrevane.com", "description": "Official public endpoint" }
  ],
  "paths": {
    "/api/transparency": {
      "get": {
        "operationId": "getTransparencySnapshot",
        "summary": "Get a quorum-verified read-only snapshot",
        "description": "No query parameters are accepted. Addresses, methods and RPC origins are fixed server-side.",
        "responses": {
          "200": {
            "description": "At least two fixed providers returned matching evidence.",
            "headers": {
              "Access-Control-Allow-Origin": { "schema": { "type": "string", "const": "*" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedSnapshot" } } }
          },
          "400": {
            "description": "Query parameters were supplied.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" } } }
          },
          "409": {
            "description": "Providers completed but no two observations matched.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureSnapshot" } } }
          },
          "503": {
            "description": "Fewer than two fixed providers completed verification.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureSnapshot" } } }
          }
        }
      },
      "head": {
        "operationId": "headTransparencySnapshot",
        "summary": "Check snapshot status without a response body",
        "responses": {
          "200": { "description": "Verified snapshot available." },
          "409": { "description": "Evidence conflict." },
          "503": { "description": "Evidence unavailable." }
        }
      },
      "options": {
        "operationId": "optionsTransparencySnapshot",
        "summary": "CORS capability response",
        "responses": { "204": { "description": "GET, HEAD and OPTIONS are allowed." } }
      }
    }
  },
  "components": {
    "schemas": {
      "Source": {
        "type": "object",
        "required": ["sourceId", "method"],
        "properties": {
          "sourceId": { "type": "string", "enum": ["optimism_official", "drpc", "one_rpc", "publicnode"] },
          "method": { "type": "string", "const": "ethereum-json-rpc" }
        },
        "additionalProperties": false
      },
      "Guardrails": {
        "type": "object",
        "required": ["walletConnection", "signing", "transactionSubmission", "priceCalculation"],
        "properties": {
          "walletConnection": { "type": "boolean", "const": false },
          "signing": { "type": "boolean", "const": false },
          "transactionSubmission": { "type": "boolean", "const": false },
          "priceCalculation": { "type": "boolean", "const": false }
        },
        "additionalProperties": false
      },
      "Observation": {
        "type": "object",
        "required": ["totalSupplyRaw", "treasuryMtvrnBalanceRaw", "poolMtvrnBalanceRaw", "treasuryEthBalanceWei", "safeThreshold", "poolToken0", "poolToken1", "poolFee", "poolLiquidityRaw", "lpNftOwner"],
        "properties": {
          "totalSupplyRaw": { "type": "string", "pattern": "^[0-9]+$" },
          "treasuryMtvrnBalanceRaw": { "type": "string", "pattern": "^[0-9]+$" },
          "poolMtvrnBalanceRaw": { "type": "string", "pattern": "^[0-9]+$" },
          "treasuryEthBalanceWei": { "type": "string", "pattern": "^[0-9]+$" },
          "safeThreshold": { "type": "integer", "minimum": 0 },
          "poolToken0": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" },
          "poolToken1": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" },
          "poolFee": { "type": "integer", "minimum": 0 },
          "poolLiquidityRaw": { "type": "string", "pattern": "^[0-9]+$" },
          "lpNftOwner": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" }
        },
        "additionalProperties": false
      },
      "VerifiedSnapshot": {
        "type": "object",
        "required": ["schemaVersion", "state", "tier", "label", "chainId", "blockNumber", "blockHash", "blockTimestamp", "retrievedAt", "freshUntil", "sources", "observations", "warnings", "guardrails"],
        "properties": {
          "schemaVersion": { "type": "string", "const": "0.1" },
          "state": { "type": "string", "const": "verified" },
          "tier": { "type": "string", "const": "A" },
          "label": { "type": "string", "const": "onchain_verified" },
          "chainId": { "type": "integer", "const": 10 },
          "blockNumber": { "type": "string", "pattern": "^[0-9]+$" },
          "blockHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" },
          "blockTimestamp": { "type": "string", "format": "date-time" },
          "retrievedAt": { "type": "string", "format": "date-time" },
          "freshUntil": { "type": "string", "format": "date-time" },
          "sources": { "type": "array", "minItems": 2, "maxItems": 3, "items": { "$ref": "#/components/schemas/Source" } },
          "observations": { "$ref": "#/components/schemas/Observation" },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "guardrails": { "$ref": "#/components/schemas/Guardrails" }
        }
      },
      "FailureSnapshot": {
        "type": "object",
        "required": ["schemaVersion", "state", "tier", "label", "chainId", "blockNumber", "blockHash", "blockTimestamp", "retrievedAt", "freshUntil", "sources", "observations", "warnings", "error", "guardrails"],
        "properties": {
          "schemaVersion": { "type": "string", "const": "0.1" },
          "state": { "type": "string", "enum": ["conflict", "unavailable"] },
          "tier": { "type": "string", "const": "U" },
          "label": { "type": "string", "const": "unverified_or_unavailable" },
          "chainId": { "type": "integer", "const": 10 },
          "blockNumber": { "type": "null" },
          "blockHash": { "type": "null" },
          "blockTimestamp": { "type": "null" },
          "retrievedAt": { "type": "string", "format": "date-time" },
          "freshUntil": { "type": "null" },
          "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } },
          "observations": { "type": "null" },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "error": {
            "type": "object",
            "required": ["code", "message", "retryable"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "retryable": { "type": "boolean" }
            },
            "additionalProperties": false
          },
          "guardrails": { "$ref": "#/components/schemas/Guardrails" }
        }
      },
      "RequestError": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" } },
        "additionalProperties": false
      }
    }
  }
}