AI-generated analysisPublished automatically and not human-verified. Validated context appears in community notes below.
← Watch feed
Low 26 Bitcoin

kernel: Introduce initial kernel C header API

Public commit record

What the developer wrote

Authored by TheCharlatan

90/100 · Strong
kernel: Introduce initial kernel C header API

As a first step, implement the equivalent of what was implemented in the
now deprecated libbitcoinconsensus header. Also add a test binary to
exercise the header and library.

Unlike the deprecated libbitcoinconsensus the kernel library can now use
the hardware-accelerated sha256 implementations thanks for its
statically-initialzed context. The functions kept around for
backwards-compatibility in the libbitcoinconsensus header are not ported
over. As a new header, it should not be burdened by previous
implementations. Also add a new error code for handling invalid flag
combinations, which would otherwise cause a crash.

The macros used in the new C header were adapted from the libsecp256k1
header.

To make use of the C header from C++ code, a C++ header is also
introduced for wrapping the C header. This makes it safer and easier to
use from C++ code.

Co-authored-by: stickies-v <stickies-v@protonmail.com>
✓ Descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Mentions testing or verification
The short version

What changed, and why it matters

This commit introduces a brand-new C and C++ programming interface for Bitcoin Core's experimental "kernel" library. It exposes functions for parsing transactions, reading transaction outputs, and verifying Bitcoin scripts. The change is primarily a feature addition: it replaces the older libbitcoinconsensus-style API with a cleaner, modern one and adds tests. The commit message notes that one new error code was added specifically to prevent crashes when callers combine script-verification flags in invalid ways. There is no direct evidence in the commit of an exploitable vulnerability in existing code, but the new API does handle untrusted transaction data and must be used carefully.

Recommended action

Treat this as a new attack surface rather than an active vulnerability. Reviewers should audit the C API boundary for lifetime safety (especially the const-pointer "views"), ensure exceptions cannot leak across the C boundary, verify that all flag combinations are correctly rejected, and run the new test_kernel binary in CI. Downstream users of the experimental library should pin to a release that has undergone further review before relying on it for consensus validation in production.

Security signals we found

01

New public C/C++ API exposes consensus-critical parsing and script verification to external callers

02

Commit message explicitly states a new error code was added because invalid flag combinations would otherwise cause a crash

03

is_valid_flag_combination() rejects CLEANSTACK without P2SH/WITNESS and WITNESS without P2SH

04

TAPROOT verification requires spent_outputs to be provided; missing them returns an error status rather than dereferencing null

05

Uses reinterpret_cast between C opaque structs and C++ objects, requiring strict lifetime discipline

06

C++ wrapper stores raw C pointers in View/Handle classes; misuse can produce use-after-free (acknowledged in a commented-out test)

07

WriterStream callback can throw across the C API boundary if the user's write callback returns non-zero

08

No input validation beyond deserialization exceptions for raw transaction/script data

Risk score

Why this scored 26/100

Our methodology →
Potential impact 5/30
Exploitability 3/25
Stealth signal 3/15
Affected reach 5/15
Confidence 7/10
Evidence quality 3/5
Human-validated context

Community notes

Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.

No validated notes yet.

The AI analysis stands alone for now. Submit a note if you can add evidence or important context.