Align test specification with bitcoinkernel.h exported symbols

[stringintech]

Addresses #5.
Pre-release v0.0.2-alpha.1 can be used to test these changes (as I have used and tested in stringintech/go-bitcoinkernel@f03919c)

[janb84]

fast feedback : please also update the documentation =>
docs/handler-spec.md

### Error Response

```json
{
  "id": "unique-request-id",
  "error": {
    "type": "error_category",
    "variant": "specific_error"
  }
}

Error response fields:

• id (string, required): Must match the request ID
• success (null or omitted): Must not be present on error <===
• error (object, required): Error details
  • type (string, required): Error category/type
  • variant (string, optional): Specific error variant within the type. Whether the runner expects this field depends on the specific test case

[stringintech]

Oops, forgot to adapt the spec; thanks @janb84!
I will push another commit for that.

[janb84]

ACK cc128f1

lgtm and no mayor issues implementing the changes om my .NET handler.

[stickies-v]

Thank you for working on this alignment, I think it's definitely an improvement. I've thought a bit more about my earlier suggestion wrt the Response format, and I think it can be improved further.

A Response format could look like:

{
  "id": str,
  "result": optional[any],
  "error": optional[error]
}

For result:

• if a function return a value, result is specified as "result": value
• if a function returns a nullptr, result must be null
• if a function doesn't return (it is void, or the function errored), result must be null

For error:

• if a function doesn't "throw", error must be null
• if a function throws, error must be defined, with "error": {} being the base, catch-all exception, that may be further specified, e.g. with a code object (that is already in the spec)
• if error is not null, success must be null

Note: null is equivalent to the key being omitted from the object.

A couple of examples:

Scenario A: Function returns a value (e.g., btck_script_pubkey_verify -> true)

{
  "id": "req-1",
  "result": true
}

Scenario B: Function is void or returns nullptr on success, but doesn't throw

{
  "id": "req-2",
  "result": null  # can also be omitted
}

Scenario C: Specific Error (e.g., verification failed with code)

{
  "id": "req-3",
  "error": {
    "code": {
      "type": "btck_ScriptVerifyStatus",
      "member": "ERROR_INVALID_FLAGS_COMBINATION"
    }
  }
}

Scenario D: Generic/Unspecified Error

{
  "id": "req-4",
  "error": {}
}

[stringintech]

Thank you for the review @stickies-v!

I like the improvement you are suggesting; besides the success boolean field, adding a result field is inevitable for adding next test cases. So it makes sense to merge them and only have the result. Also, differentiating "error": {} from "error": null (or omitted) is reasonable and is a bit closer to what I initially had in mind.

Regarding your comment #7 (comment) on whether to treat invalid scripts (when the request is valid) as success cases:

I think it comes down to how to interpret the C API a bit. I understand how you are reading into this though: we are either successful in verifying (valid/invalid script) or we are not (error/throw), and it makes sense. I am OK with applying the change here, though it seems it contradicts the Rust/Go/.NET approaches (edit: also the python approach now that I am looking) of treating everything but the valid script as an error/exception. And with this change applied, these bindings have to translate back the invalid error cases to non-errors for the handler implementation.

[stringintech]

Rebased and implemented the semantics suggested here #7 (review) - Thanks @stickies-v!
Also added a unit test for handler response validation which exercises the new semantics in different scenarios.
Pre-release v0.0.2-alpha.2 can be used to test the changes (which I used and tested in stringintech/go-bitcoinkernel@f1a1438).

[stickies-v]

Approach ACK 0f1e00d

Besides nits as commented, everything feels about as natural as I can imagine it right now. No further suggestions from me for now, not sure I'll be diving deeper into code review.

(edit: draft PR for py-bitcoinkernel implementing conformance is here)

[stringintech]

Applied @stickies-v's #7 (comment) for further alignment with the C API naming and tested the new pre-release v0.0.2-alpha.3 in stringintech/go-bitcoinkernel@c57354b.

I think I will be merging this in a few hours (if no one sees any further issues) to be able to rebase and merge #9 too. Then hopefully all changes can be exercised with the release v0.0.2.

[janb84]

ACK dd5c930

Good update, nice to have unit tests now also !

[stickies-v]

Updated stickies-v/py-bitcoinkernel#42 to the latest force-push, no more comments on the alignment! Didn't review the code, but everything seems to work well.

For a future improvement, I think it might be worth considering using JSON Schema (or even OpenRPC) to document the interface in a more systematic way, but that's out of scope for this PR.

[stringintech]

For a future improvement, I think it might be worth considering using JSON Schema (or even OpenRPC) to document the interface in a more systematic way

That would be nice! Especially if we can have something that allows auto-generating code for encoding/decoding the JSON data on the handler side.

[janb84]

Updated stickies-v/py-bitcoinkernel#42 to the latest force-push, no more comments on the alignment! Didn't review the code, but everything seems to work well.

For a future improvement, I think it might be worth considering using JSON Schema (or even OpenRPC) to document the interface in a more systematic way, but that's out of scope for this PR.

Added schema.json in #10