{
  "openapi": "3.0.3",
  "info": {
    "title": "ZANOS Network JSON-RPC Gateway",
    "version": "1.0.0",
    "description": "ZANOS L1 (Chain ID 77777) exposes a single JSON-RPC 2.0 endpoint. Every method below is dispatched through this one POST route by its `method` field. Gated methods require an `Authorization: x402-ZANOS <voucher>` header minted by zanos_claimGasVoucher. See /llms.txt for a narrative quick-start.",
    "contact": { "name": "ZANOS Network", "url": "https://zanos.tech" }
  },
  "servers": [{ "url": "https://rpc.zanos.tech:7777/rpc", "description": "Production RPC gateway (JSON-RPC 2.0 handler is mounted at /rpc)" }],
  "paths": {
    "/": {
      "post": {
        "summary": "JSON-RPC 2.0 dispatch endpoint",
        "operationId": "jsonRpcCall",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response envelope (either `result` or `error` is present, never both).",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402Voucher": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Format: \"x402-ZANOS <base64url(no padding) of {\\\"kind\\\":\\\"voucher\\\",\\\"voucher\\\":GasVoucher}>\". Minted by redeeming zanos_claimGasVoucher."
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "id", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": "integer" },
          "method": {
            "type": "string",
            "enum": [
              "zanos_chainTip",
              "zanos_getBlockByHash",
              "zanos_getUTXOs",
              "zanos_getMempool",
              "zanos_sendRawTransaction",
              "zanos_claimGasVoucher",
              "zanos_fetchCleanContext",
              "zanos_executeIsolated",
              "zanos_storeState",
              "zanos_queryState",
              "zanos_createBounty",
              "zanos_submitProof",
              "zanos_listBounties",
              "zanos_broadcastDispatch",
              "zanos_getDispatches"
            ]
          },
          "params": { "type": "array", "items": {}, "description": "Positional params, method-specific. See each *Params schema below." }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id"],
        "properties": {
          "jsonrpc": { "type": "string", "enum": ["2.0"] },
          "id": { "type": "integer" },
          "result": {},
          "error": { "$ref": "#/components/schemas/JsonRpcError" }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "integer" },
          "message": { "type": "string" },
          "data": {}
        }
      },
      "WeiString": {
        "type": "string",
        "description": "A base-10 integer string denominated in the token's smallest unit (18 decimals for $ZNS). Always a string, never a JSON number, to preserve precision past 2^53."
      },
      "BlockHeader": {
        "type": "object",
        "properties": {
          "version": { "type": "integer" },
          "chainId": { "type": "integer", "example": 77777 },
          "number": { "type": "integer" },
          "parentHash": { "type": "string" },
          "stateRoot": { "type": "string" },
          "txRoot": { "type": "string" },
          "receiptRoot": { "type": "string" },
          "timestamp": { "type": "integer" },
          "difficulty": { "$ref": "#/components/schemas/WeiString" },
          "nonce": { "$ref": "#/components/schemas/WeiString" },
          "powHash": { "type": "string" },
          "coinbase": { "type": "string" },
          "gasLimit": { "type": "integer" },
          "gasUsed": { "type": "integer" }
        }
      },
      "ChainTipResult": {
        "type": "object",
        "properties": {
          "number": { "type": "integer" },
          "hash": { "type": "string" },
          "header": { "$ref": "#/components/schemas/BlockHeader" }
        }
      },
      "UTXOEntry": {
        "type": "object",
        "properties": {
          "txHash": { "type": "string" },
          "index": { "type": "integer" },
          "value": { "$ref": "#/components/schemas/WeiString" }
        }
      },
      "ComputeChallenge": {
        "type": "object",
        "description": "A Proof-of-Compute challenge. Solve by finding `nonce` such that doubleSHA256(seed || bigEndianUint64(nonce)) <= (2^256-1)/difficulty.",
        "properties": {
          "address": { "type": "string" },
          "seed": { "type": "string", "description": "Hex-encoded challenge seed." },
          "difficulty": { "$ref": "#/components/schemas/WeiString" },
          "bucket": { "type": "integer" },
          "expiresAt": { "type": "integer" }
        }
      },
      "GasVoucher": {
        "type": "object",
        "properties": {
          "address": { "type": "string" },
          "gasUnits": { "$ref": "#/components/schemas/WeiString" },
          "issuedAt": { "type": "integer" },
          "expiresAt": { "type": "integer" },
          "nonce": { "type": "integer" },
          "signature": { "type": "string" }
        }
      },
      "ClaimGasVoucherParams": {
        "type": "object",
        "required": ["address"],
        "properties": {
          "address": { "type": "string", "description": "Bech32m zns1... or znsagent1... address." },
          "difficulty": { "type": "integer", "default": 10000 },
          "bucket": { "type": "integer", "description": "Echoed back from a prior ComputeChallenge when redeeming." },
          "nonce": { "type": "integer", "description": "The solved Proof-of-Compute nonce, when redeeming." }
        }
      },
      "ClaimGasVoucherResult": {
        "type": "object",
        "properties": {
          "challenge": { "$ref": "#/components/schemas/ComputeChallenge" },
          "voucher": { "$ref": "#/components/schemas/GasVoucher" }
        }
      },
      "FetchCleanContextParams": {
        "type": "object",
        "required": ["url"],
        "properties": { "url": { "type": "string", "format": "uri" } }
      },
      "FetchCleanContextResult": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "title": { "type": "string" },
          "markdown": { "type": "string" },
          "elapsedMs": { "type": "integer" },
          "gasPaid": { "$ref": "#/components/schemas/WeiString" }
        },
        "security": [{ "x402Voucher": [] }]
      },
      "Dispatch": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "sha256 digest of the dispatch, hex-encoded with 0x prefix." },
          "title": { "type": "string" },
          "body": { "type": "string" },
          "timestamp": { "type": "integer" },
          "author": { "type": "string", "description": "Ed25519 public key, hex." },
          "signature": { "type": "string", "description": "Ed25519 signature over the digest, hex." }
        }
      },
      "BroadcastDispatchParams": {
        "type": "object",
        "required": ["title", "body", "timestamp", "publicKey", "signature"],
        "properties": {
          "title": { "type": "string" },
          "body": { "type": "string" },
          "timestamp": { "type": "integer" },
          "publicKey": { "type": "string" },
          "signature": { "type": "string" }
        },
        "security": [{ "x402Voucher": [] }]
      }
    }
  }
}