From a6a2417db1ecdfc27892b363294b1944a38bb5f0 Mon Sep 17 00:00:00 2001 From: janb84 Date: Tue, 2 Dec 2025 14:09:31 +0000 Subject: [PATCH] Add JSON Schema for Bitcoin Kernel Bindings Test Handler Protocol --- docs/schema.json | 266 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 docs/schema.json diff --git a/docs/schema.json b/docs/schema.json new file mode 100644 index 0000000..fcb5458 --- /dev/null +++ b/docs/schema.json @@ -0,0 +1,266 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://github.com/stringintech/kernel-bindings-tests/schema.json", + "title": "Bitcoin Kernel Bindings Test Handler Protocol", + "description": "JSON Schema for the stdin/stdout protocol used by Bitcoin Kernel binding conformance test handlers", + "version": "0.2.0", + "$ref": "#/definitions/TestSuite", + "definitions": { + "TestSuite": { + "type": "object", + "description": "A collection of test cases", + "properties": { + "name": { + "type": "string", + "description": "Name of the test suite" + }, + "description": { + "type": "string", + "description": "Description of what this test suite covers" + }, + "tests": { + "type": "array", + "description": "Array of test cases", + "items": { + "$ref": "#/definitions/TestCase" + } + } + }, + "required": ["name", "tests"] + }, + "TestCase": { + "type": "object", + "description": "A single test case", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for this test" + }, + "description": { + "type": "string", + "description": "Human-readable description of what this test verifies" + }, + "method": { + "type": "string", + "description": "The method to invoke", + "enum": ["btck_script_pubkey_verify"] + }, + "params": { + "$ref": "#/definitions/ScriptPubkeyVerifyParams" + }, + "expected": { + "$ref": "#/definitions/TestExpectation" + } + }, + "required": ["id", "method", "params", "expected"] + }, + "TestExpectation": { + "type": "object", + "description": "Expected result of a test case", + "properties": { + "result": { + "type": "boolean", + "description": "Expected boolean result (true for valid script, false for invalid)" + }, + "error": { + "$ref": "#/definitions/ScriptVerifyError", + "description": "Expected error if the operation should fail" + } + } + }, + "Request": { + "type": "object", + "description": "A request sent from the test runner to the handler via stdin", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for this request. The response must include the same id" + }, + "method": { + "type": "string", + "description": "The method to invoke on the handler", + "enum": ["btck_script_pubkey_verify"] + }, + "params": { + "description": "Method-specific parameters", + "oneOf": [ + { "$ref": "#/definitions/ScriptPubkeyVerifyParams" } + ] + } + }, + "required": ["id", "method"] + }, + "Response": { + "type": "object", + "description": "A response sent from the handler to the test runner via stdout", + "properties": { + "id": { + "type": "string", + "description": "Must match the request id" + }, + "result": { + "description": "The result of the operation. Null on error or for void operations" + }, + "error": { + "oneOf": [ + { "$ref": "#/definitions/ScriptVerifyError" }, + { "type": "null" } + ], + "description": "Error details if the operation failed. Null or omitted on success" + } + }, + "required": ["id"] + }, + "Error": { + "type": "object", + "description": "Error information returned when an operation fails", + "properties": { + "code": { + "$ref": "#/definitions/ErrorCode", + "description": "Structured error code" + } + } + }, + "ErrorCode": { + "type": "object", + "description": "Structured error code with type and member", + "properties": { + "type": { + "type": "string", + "description": "The error type/category (e.g., 'btck_ScriptVerifyStatus')" + }, + "member": { + "type": "string", + "description": "The specific error member within the type (e.g., 'ERROR_INVALID_FLAGS_COMBINATION')" + } + }, + "required": ["type", "member"] + }, + "ScriptPubkeyVerifyParams": { + "type": "object", + "description": "Parameters for the btck_script_pubkey_verify method", + "properties": { + "script_pubkey": { + "type": "string", + "description": "The scriptPubKey of the output being spent, hex-encoded", + "pattern": "^[0-9a-fA-F]*$" + }, + "amount": { + "type": "integer", + "description": "The amount in satoshis of the output being spent", + "minimum": 0 + }, + "tx_to": { + "type": "string", + "description": "The spending transaction, hex-encoded in raw format", + "pattern": "^[0-9a-fA-F]*$" + }, + "input_index": { + "type": "integer", + "description": "The index of the input in tx_to that is spending the output", + "minimum": 0 + }, + "flags": { + "type": "array", + "description": "Array of script verification flags to apply", + "items": { + "$ref": "#/definitions/ScriptVerificationFlag" + } + }, + "spent_outputs": { + "type": "array", + "description": "Array of all outputs being spent by this transaction. Required for Taproot verification", + "items": { + "$ref": "#/definitions/SpentOutput" + } + } + }, + "required": ["script_pubkey", "amount", "tx_to", "input_index", "flags", "spent_outputs"] + }, + "ScriptVerificationFlag": { + "type": "string", + "description": "Script verification flags that control which rules are enforced during script execution", + "enum": [ + "btck_ScriptVerificationFlags_NONE", + "btck_ScriptVerificationFlags_P2SH", + "btck_ScriptVerificationFlags_DERSIG", + "btck_ScriptVerificationFlags_NULLDUMMY", + "btck_ScriptVerificationFlags_CHECKLOCKTIMEVERIFY", + "btck_ScriptVerificationFlags_CHECKSEQUENCEVERIFY", + "btck_ScriptVerificationFlags_WITNESS", + "btck_ScriptVerificationFlags_TAPROOT" + ] + }, + "SpentOutput": { + "type": "object", + "description": "Information about a transaction output being spent", + "properties": { + "script_pubkey": { + "type": "string", + "description": "The scriptPubKey of the output, hex-encoded", + "pattern": "^[0-9a-fA-F]*$" + }, + "amount": { + "type": "integer", + "description": "The amount in satoshis", + "minimum": 0 + } + }, + "required": ["script_pubkey", "amount"] + }, + "ScriptPubkeyVerifyResult": { + "type": "boolean", + "description": "True if the script verification succeeded, false if the script is invalid" + }, + "ScriptVerifyErrorCode": { + "description": "Error code specific to script verification failures. Extends ErrorCode with constrained values", + "allOf": [ + { "$ref": "#/definitions/ErrorCode" }, + { + "properties": { + "type": { + "const": "btck_ScriptVerifyStatus", + "description": "The error type for script verification errors" + }, + "member": { + "enum": [ + "ERROR_INVALID_FLAGS_COMBINATION", + "ERROR_SPENT_OUTPUTS_REQUIRED" + ], + "description": "ERROR_INVALID_FLAGS_COMBINATION: Invalid or inconsistent verification flags. ERROR_SPENT_OUTPUTS_REQUIRED: Spent outputs required but not provided (e.g., for Taproot)" + } + } + } + ] + }, + "ScriptVerifyError": { + "description": "Error returned when script verification cannot be performed. Extends the generic Error type with script-specific error codes", + "allOf": [ + { "$ref": "#/definitions/Error" }, + { + "type": "object", + "properties": { + "code": { + "$ref": "#/definitions/ScriptVerifyErrorCode", + "description": "Script verification specific error code" + } + }, + "required": ["code"] + } + ] + }, + "ScriptPubkeyVerifyRequest": { + "allOf": [ + { + "type": "object", + "properties": { + "id": { "type": "string" }, + "method": { "const": "btck_script_pubkey_verify" }, + "params": { "$ref": "#/definitions/ScriptPubkeyVerifyParams" } + }, + "required": ["id", "method", "params"] + } + ] + } + } +}