{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://axon.nanocorp.app/schemas/v1/axon-protocol-spec.schema.json",
  "title": "Axon Protocol Spec",
  "description": "Machine-readable specification for DeFi protocols, enabling AI agents to discover, understand, and interact with on-chain protocols.",
  "version": "1.0.0",
  "type": "object",
  "required": ["axon_version", "protocol", "actions", "risk", "fees"],
  "properties": {
    "axon_version": {
      "type": "string",
      "const": "1.0.0",
      "description": "Version of the Axon Protocol Spec format"
    },
    "protocol": {
      "type": "object",
      "description": "Protocol identity and deployment information",
      "required": ["name", "slug", "version", "chain", "contracts"],
      "properties": {
        "name": { "type": "string", "description": "Human-readable protocol name" },
        "slug": { "type": "string", "pattern": "^[a-z0-9-]+$", "description": "URL-safe unique identifier" },
        "version": { "type": "string", "description": "Protocol version (e.g. v3)" },
        "description": { "type": "string", "description": "Brief protocol description" },
        "category": {
          "type": "string",
          "enum": ["dex", "lending", "staking", "yield", "derivatives", "bridge", "other"]
        },
        "chain": {
          "type": "object",
          "required": ["id", "name"],
          "properties": {
            "id": { "type": "integer", "description": "EIP-155 chain ID" },
            "name": { "type": "string" },
            "network": { "type": "string", "enum": ["mainnet", "testnet"] }
          }
        },
        "contracts": {
          "type": "object",
          "description": "Key contract addresses keyed by role",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
              "label": { "type": "string" },
              "verified": { "type": "boolean" }
            },
            "required": ["address"]
          }
        },
        "links": {
          "type": "object",
          "properties": {
            "website": { "type": "string", "format": "uri" },
            "docs": { "type": "string", "format": "uri" },
            "github": { "type": "string", "format": "uri" },
            "governance": { "type": "string", "format": "uri" }
          }
        }
      }
    },
    "actions": {
      "type": "array",
      "description": "Available protocol operations an agent can execute",
      "items": {
        "type": "object",
        "required": ["id", "name", "type", "parameters", "transaction_flow"],
        "properties": {
          "id": { "type": "string", "description": "Unique action identifier" },
          "name": { "type": "string", "description": "Human-readable action name" },
          "description": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["swap", "supply", "borrow", "repay", "withdraw", "stake", "unstake", "claim", "bridge", "wrap"]
          },
          "parameters": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "type", "required"],
              "properties": {
                "name": { "type": "string" },
                "type": {
                  "type": "string",
                  "enum": ["address", "uint256", "uint24", "uint16", "bytes", "bool", "string"]
                },
                "required": { "type": "boolean" },
                "description": { "type": "string" },
                "default": {},
                "constraints": {
                  "type": "object",
                  "properties": {
                    "min": { "type": "string" },
                    "max": { "type": "string" },
                    "enum": { "type": "array" },
                    "pattern": { "type": "string" }
                  }
                }
              }
            }
          },
          "constraints": {
            "type": "object",
            "properties": {
              "min_amount": { "type": "string" },
              "max_slippage_bps": { "type": "integer" },
              "deadline_required": { "type": "boolean" },
              "supported_tokens": { "type": "string" },
              "requires_position": { "type": "boolean" }
            }
          },
          "approvals": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": { "type": "string", "enum": ["erc20_approve", "permit2", "erc721_approve"] },
                "token": { "type": "string", "description": "Parameter name referencing the token" },
                "spender": { "type": "string", "description": "Contract key from protocol.contracts" },
                "amount": { "type": "string", "enum": ["exact", "unlimited", "exact_or_max"] }
              }
            }
          },
          "transaction_flow": {
            "type": "array",
            "description": "Ordered steps to execute this action",
            "items": {
              "type": "object",
              "required": ["step", "action", "contract", "method"],
              "properties": {
                "step": { "type": "integer" },
                "action": { "type": "string" },
                "description": { "type": "string" },
                "contract": { "type": "string" },
                "method": { "type": "string", "description": "Solidity function signature" },
                "conditional": { "type": "string" },
                "returns": { "type": "array", "items": { "type": "string" } }
              }
            }
          }
        }
      }
    },
    "risk": {
      "type": "object",
      "description": "Risk metadata for agent decision-making",
      "properties": {
        "audit_status": {
          "type": "object",
          "properties": {
            "audited": { "type": "boolean" },
            "auditors": { "type": "array", "items": { "type": "string" } },
            "last_audit_date": { "type": "string", "format": "date" },
            "audit_reports": { "type": "array", "items": { "type": "string", "format": "uri" } }
          }
        },
        "tvl": {
          "type": "object",
          "properties": {
            "current_usd": { "type": "number" },
            "source": { "type": "string" },
            "last_updated": { "type": "string", "format": "date-time" }
          }
        },
        "incidents": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": { "type": "string", "format": "date" },
              "severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "info"] },
              "title": { "type": "string" },
              "description": { "type": "string" },
              "resolved": { "type": "boolean" },
              "post_mortem": { "type": "string", "format": "uri" }
            }
          }
        },
        "risk_score": {
          "type": "object",
          "description": "Axon risk ratings (A+ to F)",
          "properties": {
            "overall": { "type": "string", "enum": ["A+", "A", "B+", "B", "C", "D", "F"] },
            "smart_contract": { "type": "string" },
            "centralization": { "type": "string" },
            "oracle_dependence": { "type": "string" },
            "liquidity": { "type": "string" }
          }
        }
      }
    },
    "fees": {
      "type": "object",
      "description": "Protocol fee structure",
      "properties": {
        "model": { "type": "string", "enum": ["per_trade", "interest_rate", "performance", "flat", "none"] },
        "tiers": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "fee_bps": { "type": ["integer", "null"], "description": "Fee in basis points" },
              "description": { "type": "string" },
              "conditions": { "type": "string" }
            }
          }
        },
        "gas_estimates": {
          "type": "object",
          "description": "Estimated gas costs per action",
          "additionalProperties": { "type": "string" }
        }
      }
    }
  }
}