kernel: validate C API inputs #35340

Fixes #35339.

This hardens the experimental libbitcoinkernel C API so caller-provided invalid runtime inputs fail through documented return/status channels instead of assertions. Existing script verification status numeric values are preserved, and the new values are appended.

Summary

• Return nullptr for out-of-range transaction, block transaction, block spent-output, and transaction spent-output accessors.
• Add script verification statuses for unsupported flag bits and out-of-range input indexes.
• Reject malformed precomputed transaction data spent-output arrays at construction.
• Document script verification failure statuses and precomputed spent-output array requirements.
• Add focused kernel API tests for the new failure behavior, including nullable status output handling.

Testing

• git diff --check
• cmake -B build-kernel-validation -DBUILD_KERNEL_LIB=ON -DBUILD_KERNEL_TEST=ON -DBUILD_TESTS=OFF -DBUILD_DAEMON=OFF -DBUILD_CLI=OFF -DBUILD_BITCOIN_BIN=OFF -DBUILD_TX=OFF -DBUILD_UTIL=OFF -DENABLE_WALLET=OFF -DENABLE_IPC=OFF
• cmake --build build-kernel-validation --target test_kernel -j $(sysctl -n hw.ncpu)
• build-kernel-validation/bin/test_kernel

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35340.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

• btck_precomputed_transaction_data_create(tx.get(), too_many_spent_outputs, 2) in src/test/kernel/test_kernel.cpp
• btck_precomputed_transaction_data_create(tx.get(), nullptr, 1) in src/test/kernel/test_kernel.cpp
• btck_precomputed_transaction_data_create(tx.get(), null_spent_outputs, 1) in src/test/kernel/test_kernel.cpp

^{2026-05-20 22:20:57}