{ "openapi": "3.0.3", "info": { "title": "Monero NFT Oracle", "version": "0.2.0", "description": "仅Stagenet；行情仅供参考；治理摘要上链由独立验证器核验，Monero不执行投票规则。普通JSON上限64KiB，治理及成长证据验证上限4MiB。" }, "servers": [ { "url": "http://127.0.0.1:8780" } ], "paths": { "/healthz": { "get": { "summary": "进程存活、治理配置与成长承诺上链状态", "operationId": "get__healthz", "responses": { "200": { "description": "操作成功" } }, "security": [] } }, "/v1/config": { "get": { "summary": "查看固定信任根和规则版本", "operationId": "get__v1_config", "responses": { "200": { "description": "操作成功" } }, "security": [] } }, "/v1/beta-table": { "get": { "summary": "获取四种颜色的128位整数CDF表", "operationId": "get__v1_beta-table", "responses": { "200": { "description": "操作成功" } }, "security": [] } }, "/v1/randomness/requests": { "post": { "summary": "幂等创建未来成长承诺", "operationId": "post__v1_randomness_requests", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrowthInput" } } } } } }, "/v1/randomness/requests/{id}": { "get": { "summary": "读取持久化承诺和已生成的证据", "operationId": "get__v1_randomness_requests_id", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "404": { "description": "承诺不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ] } }, "/v1/randomness/requests/{id}/resolve": { "post": { "summary": "获取固定轮次，验签并保存成长证据", "operationId": "post__v1_randomness_requests_id_resolve", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Record" } } } }, "202": { "description": "轮次未到，结果尚不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "承诺不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ] } }, "/v1/proofs/verify": { "post": { "summary": "核验本节点签名、BLS证明并重新计算成长", "operationId": "post__v1_proofs_verify", "responses": { "200": { "description": "操作成功" }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "证明无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } } } }, "/v1/nft/price": { "post": { "summary": "计算规则售价，不认证输入状态或市场价值", "operationId": "post__v1_nft_price", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceInput" } } } } } }, "/v1/market/xmr-usd": { "get": { "summary": "至少两个有效来源的XMR/USD参考行情", "operationId": "get__v1_market_xmr-usd", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "并发达到上限", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/governance/status": { "get": { "summary": "查看固定创世摘要、当前规则和节点核验结果", "operationId": "get__v1_governance_status", "responses": { "200": { "description": "操作成功" }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/governance/events/{id}": { "get": { "summary": "查看治理记录、摘要载荷及交易状态", "operationId": "get__v1_governance_events_id", "responses": { "200": { "description": "操作成功" }, "404": { "description": "承诺不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ] } }, "/v1/governance/bundle": { "get": { "summary": "下载完整治理批准链；下载不代表已经核验", "operationId": "get__v1_governance_bundle", "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceBundle" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "config", "in": "query", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "可选的历史配置摘要" } ] } }, "/v1/governance/proposals": { "get": { "summary": "查看最多100项提案和选票", "operationId": "get__v1_governance_proposals", "responses": { "200": { "description": "操作成功" }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "post": { "summary": "提交名册成员签名的参数提案", "operationId": "post__v1_governance_proposals", "responses": { "200": { "description": "操作成功" }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "description": "使用 Ed25519 成员签名鉴权，不使用管理 Bearer。正文是 govsign 输出的完整信封；不接收私钥。" } }, "/v1/governance/artifacts": { "post": { "summary": "上传分布制品；上传不使其生效", "operationId": "post__v1_governance_artifacts", "responses": { "200": { "description": "操作成功" }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BetaArtifact" } } } } } }, "/v1/governance/proposals/{id}/votes": { "post": { "summary": "提交名册成员签名的选票", "operationId": "post__v1_governance_proposals_id_votes", "responses": { "200": { "description": "操作成功" }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "description": "使用 Ed25519 成员签名鉴权，不使用管理 Bearer。正文是 govsign 输出的完整信封；不接收私钥。" } }, "/v1/governance/proposals/{id}/finalize": { "post": { "summary": "结算投票", "operationId": "post__v1_governance_proposals_id_finalize", "responses": { "200": { "description": "操作成功" }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } }, "/v1/governance/proposals/{id}/activate": { "post": { "summary": "生成待上链的时间锁激活记录", "operationId": "post__v1_governance_proposals_id_activate", "responses": { "200": { "description": "操作成功" }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } }, "/v1/governance/events/{id}/reserve-broadcast": { "post": { "summary": "广播前持久化预留，禁止盲目重发", "operationId": "post__v1_governance_events_id_reserve-broadcast", "responses": { "200": { "description": "操作成功" }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } }, "/v1/governance/events/{id}/record-broadcast": { "post": { "summary": "保存交易号，不确认锚点", "operationId": "post__v1_governance_events_id_record-broadcast", "responses": { "200": { "description": "操作成功" }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionID" } } } } } }, "/v1/governance/events/{id}/confirm": { "post": { "summary": "从可信节点核验交易并记录锚点", "operationId": "post__v1_governance_events_id_confirm", "responses": { "200": { "description": "操作成功" }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "订单或状态冲突", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionID" } } } } } }, "/v1/governance/verify": { "post": { "summary": "从固定创世摘要和可信节点复核完整批准链", "operationId": "post__v1_governance_verify", "responses": { "200": { "description": "操作成功" }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "禁止浏览器写入", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "证明无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "可信上游不可用", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernanceBundle" } } } } } } }, "components": { "schemas": { "GrowthInput": { "type": "object", "additionalProperties": false, "required": [ "network", "platform", "order_id", "nft_id", "previous_state_hash", "growth_count", "activity", "total_bp", "base_atomic" ], "properties": { "network": { "type": "string", "enum": [ "stagenet" ] }, "platform": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }, "order_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }, "nft_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }, "previous_state_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "growth_count": { "type": "integer", "minimum": 0, "maximum": 999999 }, "activity": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "活性百分数乘以100" }, "total_bp": { "type": "integer", "minimum": 0, "maximum": 399999600 }, "base_atomic": { "type": "string", "pattern": "^[1-9][0-9]{0,24}$", "description": "首发XMR基价的原子单位" } } }, "Envelope": { "type": "object", "required": [ "payload", "public_key", "signature" ], "properties": { "payload": { "type": "object" }, "public_key": { "type": "string" }, "signature": { "type": "string" } } }, "Beacon": { "type": "object", "required": [ "round", "signature" ], "properties": { "round": { "type": "integer", "minimum": 1 }, "signature": { "type": "string" }, "randomness": { "type": "string" } } }, "Proof": { "type": "object", "additionalProperties": false, "required": [ "receipt", "beacon", "result" ], "properties": { "receipt": { "$ref": "#/components/schemas/Envelope" }, "beacon": { "$ref": "#/components/schemas/Beacon" }, "result": { "$ref": "#/components/schemas/Envelope" }, "governance": { "$ref": "#/components/schemas/GovernanceBundle" } } }, "Record": { "type": "object", "required": [ "receipt", "commitment" ], "properties": { "receipt": { "$ref": "#/components/schemas/Envelope" }, "commitment": { "type": "string" }, "proof": { "$ref": "#/components/schemas/Proof" } } }, "PriceInput": { "type": "object", "additionalProperties": false, "required": [ "base_atomic", "total_bp" ], "properties": { "base_atomic": { "type": "string", "pattern": "^[1-9][0-9]{0,24}$", "description": "首发XMR基价的原子单位" }, "total_bp": { "type": "integer", "minimum": 0, "maximum": 400000000 } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "BetaArtifact": { "type": "object", "additionalProperties": false, "required": [ "parameters", "tables" ], "properties": { "parameters": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string" } } }, "tables": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "array", "minItems": 301, "maxItems": 301, "items": { "type": "string", "pattern": "^[0-9]+$" } } } } }, "GovernanceBundle": { "type": "object", "required": [ "genesis", "genesis_event", "changes", "artifacts" ], "properties": { "genesis": { "type": "object", "description": "固定创世名册、门槛和首版规则，结构详见 GOVERNANCE.md" }, "genesis_event": { "type": "object" }, "changes": { "type": "array", "maxItems": 1000, "items": { "type": "object" } }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/BetaArtifact" } } } }, "TransactionID": { "type": "object", "additionalProperties": false, "required": [ "txid" ], "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "Empty": { "type": "object", "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }