Skip to content

Add JSON Schema for Bitcoin Kernel Bindings Test Handler Protocol #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
+266 −0
Draft

Add JSON Schema for Bitcoin Kernel Bindings Test Handler Protocol #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 266 additions & 0 deletions docs/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"]
}
]
}
}
}
Loading