kernel: Expose `CheckTransaction` consensus validation function #33796

w0xlt · 2025-11-05T23:59:50Z

This PR exposes the consensus-level CheckTransaction function through the libbitcoinkernel C API and adds a corresponding C++ wrapper.

Currently, libkernel only provided script-level validation via btck_script_pubkey_verify and ScriptPubkeyApi<>::Verify.

AFAIK there was no way to perform context-free consensus checks on a transaction’s structure (e.g., coinbase rules, money-range, duplicate inputs).

This change introduces a new API:

int btck_check_transaction(const btck_Transaction* tx, btck_TxValidationState** out_state);

and a C++ convenience wrapper:

std::pair<bool, TxValidationState> btck::CheckTransaction(const Transaction& tx);

Both follow the ownership and error-handling conventions established in bitcoinkernel.h.

The test suite is extended with cases covering:

coinbase scriptSig length bounds
empty vin / vout detection
negative or out-of-range output values
duplicate inputs
null prevouts in non-coinbase transactions

DrahtBot · 2025-11-05T23:59:55Z

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

Code Coverage & Benchmarks

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

Reviews

See the guideline for information on the review process.

Type	Reviewers
Concept ACK	TheCharlatan, janb84
Approach ACK	yuvicc

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#33908 (kernel: add context‑free block validation API (btck_check_block_context_free) with POW/Merkle flags by w0xlt)
#33891 (kernel: Expose reusable PrecomputedTransactionData in script validation by joshdoman)
#33856 (kernel, validation: Refactor ProcessNewBlockHeaders to return BlockValidationState by yuvicc)
#33847 (kernel: Improve logging API by ryanofsky)
#33822 (kernel: Add block header support and validation by yuvicc)
#33779 (ci, iwyu: Fix warnings in src/kernel and treat them as errors by hebasto)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

l0rinc · 2025-11-06T09:04:06Z

src/kernel/bitcoinkernel.h

+#define btck_TxValidationResult_MEMPOOL_POLICY      ((btck_TxValidationResult)(9))
+#define btck_TxValidationResult_NO_MEMPOOL          ((btck_TxValidationResult)(10))
+#define btck_TxValidationResult_RECONSIDERABLE      ((btck_TxValidationResult)(11))
+#define btck_TxValidationResult_UNKNOWN             ((btck_TxValidationResult)(12))


shouldn't this be bigger than 12 (or could maybe be 0) so that new values can be added in the future?

sedited · 2025-11-06T11:01:14Z

Concept ACK on adding more checks. I am not sure how useful this check by itself is though, since it lacks finality, inputs, sigops, amount + fee, and script checks. Are you planning on adding these too and if not, what is the purpose served from surfacing the context-free checks, but not the others?

I think the unit tests are going a bit too far. We don't have to verify again that our validation logic works internally and should instead just verify that the function's contract is correct. If you want to check that the mapping for each of the result enums is correct maybe pass in a few hard-coded transactions instead? We do the same in our unit tests too so maybe just reuse a few of the vectors from test/data/tx_invalid.json?

w0xlt · 2025-11-06T18:44:12Z

I am not sure how useful this check by itself is … what is the purpose served from surfacing the context‑free checks, but not the others?

The new API intentionally exposes only the context‑free consensus predicate (consensus/tx_check::CheckTransaction) so callers can fail fast on malformed transactions without needing a kernel context, UTXO set, or policy knobs.

This gives library users (indexers, gateways, alternative mempool layers, etc.) a cheap pre‑filter to catch structural rule violations like empty vin/vout, out‑of‑range amounts, coinbase scriptSig length bounds, duplicate inputs, or null prevouts in non‑coinbase txs—before doing any stateful or expensive work.

Script checks are already available via btck_script_pubkey_verify in this API; inputs/fees/sigops/finality all need UTXO and/or chain context and are out of scope for a context‑free entry point.

think the unit tests are going a bit too far … instead just verify that the function’s contract is correct.

Agreed. This can be simplified.

yuvicc

Approach ACK

Great addition exposing CheckTransaction to the kernel API. This will be useful to external users needing context-free transaction validation.

yuvicc · 2025-11-08T06:27:31Z

src/kernel/bitcoinkernel.h

+/**
+ * @brief Run consensus/tx_check::CheckTransaction on a tx and return the filled state.
+ * @return 1 if valid, 0 if invalid.
+ */


Suggested change

/**

* @brief Run consensus/tx_check::CheckTransaction on a tx and return the filled state.

* @return 1 if valid, 0 if invalid.

*/

/**

* @brief Run consensus/tx_check::CheckTransaction on a transaction.

*

* Performs context-free consensus validation on a transaction without

* requiring blockchain state.

*

* @param[in] tx The transaction to validate

* @param[out] out_state Pointer to receive the validation state (always set,

* caller must destroy with btck_tx_validation_state_destroy)

* @return 1 if valid, 0 if invalid

*/

janb84

Concept ACK a262282

PR extends bitcoin kernel library with the checkTransaction consensus validation function.

Added a suggestion NIT (non-blocking) and I agree with the NIT from yuvicc

Steps taken:

Build & tested
Code review
Create a implementation PR for BitcoinKernel.Net

janb84 · 2025-11-17T10:20:46Z

src/test/kernel/test_kernel.cpp

+
+// -----------------------------------------------------------------------------
+// CheckTransaction tests
+// -----------------------------------------------------------------------------


NIT: (non-blocking) maybe add a note why only the 2 (possible) states are tested ? For a non-bitcoin-core dev this is maybe a bit unclear given all the TxValidationResults and the Check_Transaction that these are the 2 outcomes.
It's for me not logical to add this as a comment on the function because it returns a pointer to the results.

Suggested change

// -----------------------------------------------------------------------------

// -----------------------------------------------------------------------------

// Note: CheckTransaction performs only basic consensus checks and returns either:

// - VALID (ValidationMode::VALID, TxValidationResult::UNSET) for valid transactions

// - INVALID (ValidationMode::INVALID, TxValidationResult::CONSENSUS) for violations

//

// Other TxValidationResult values are set by higher-level validation functions and

// not exposed through btck_check_transaction.

// -----------------------------------------------------------------------------

DrahtBot · 2025-12-27T17:44:18Z

🐙 This pull request conflicts with the target branch and needs rebase.

[kernel] Expose CheckTransaction consensus function

a262282

l0rinc reviewed Nov 6, 2025

View reviewed changes

sedited mentioned this pull request Nov 7, 2025

Bitcoin Kernel Library Project Tracking #27587

Open

2 tasks

sedited moved this to Ready for Review PRs in The libbitcoinkernel Project Nov 7, 2025

sedited added this to The libbitcoinkernel Project Nov 7, 2025

fanquake changed the title ~~[kernel] Expose CheckTransaction consensus validation function~~ kernel: Expose CheckTransaction consensus validation function Nov 7, 2025

DrahtBot added the Validation label Nov 7, 2025

DrahtBot mentioned this pull request Nov 8, 2025

kernel: Add block header support and validation #33822

Open

yuvicc reviewed Nov 8, 2025

View reviewed changes

This was referenced Nov 11, 2025

kernel: Improve logging API #33847

Draft

kernel, logging: Pass Logger instances to kernel objects #30342

Draft

kernel, validation: Refactor ProcessNewBlockHeaders to return BlockValidationState #33856

Open

janb84 mentioned this pull request Nov 17, 2025

Implement pr #33796 CheckTransaction consensus validation function janb84/BitcoinKernel.NET#2

Open

janb84 reviewed Nov 17, 2025

View reviewed changes

This was referenced Nov 18, 2025

kernel: Expose reusable PrecomputedTransactionData in script validation #33891

Merged

kernel: add context‑free block validation API (btck_check_block_context_free) with POW/Merkle flags #33908

Open

DrahtBot mentioned this pull request Dec 17, 2025

ci, iwyu: Fix warnings in src/kernel and treat them as errors #33779

Open

DrahtBot added the Needs rebase label Dec 27, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

kernel: Expose `CheckTransaction` consensus validation function #33796

kernel: Expose `CheckTransaction` consensus validation function #33796

w0xlt commented Nov 5, 2025

Uh oh!

DrahtBot commented Nov 5, 2025 •

edited

Loading

Uh oh!

l0rinc Nov 6, 2025

Uh oh!

sedited commented Nov 6, 2025

Uh oh!

w0xlt commented Nov 6, 2025

Uh oh!

yuvicc left a comment

Uh oh!

yuvicc Nov 8, 2025

Uh oh!

janb84 left a comment

Uh oh!

janb84 Nov 17, 2025

Uh oh!

DrahtBot commented Dec 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

-/**
- * @brief Run consensus/tx_check::CheckTransaction on a tx and return the filled state.
- * @return 1 if valid, 0 if invalid.
- */
+/**
+   * @brief Run consensus/tx_check::CheckTransaction on a transaction.
+   *
+   * Performs context-free consensus validation on a transaction without
+   * requiring blockchain state.
+   *
+   * @param[in] tx The transaction to validate
+   * @param[out] out_state Pointer to receive the validation state (always set,
+   *                       caller must destroy with btck_tx_validation_state_destroy)
+   * @return 1 if valid, 0 if invalid
+   */

-// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Note: CheckTransaction performs only basic consensus checks and returns either:
+//   - VALID (ValidationMode::VALID, TxValidationResult::UNSET) for valid transactions
+//   - INVALID (ValidationMode::INVALID, TxValidationResult::CONSENSUS) for violations
+//
+// Other TxValidationResult values are set by higher-level validation functions and
+// not exposed through btck_check_transaction.
+// -----------------------------------------------------------------------------

kernel: Expose CheckTransaction consensus validation function #33796

Are you sure you want to change the base?

kernel: Expose CheckTransaction consensus validation function #33796

Conversation

w0xlt commented Nov 5, 2025

Uh oh!

DrahtBot commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage & Benchmarks

Reviews

Conflicts

Uh oh!

l0rinc Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

sedited commented Nov 6, 2025

Uh oh!

w0xlt commented Nov 6, 2025

Uh oh!

yuvicc left a comment

Choose a reason for hiding this comment

Uh oh!

yuvicc Nov 8, 2025

Choose a reason for hiding this comment

Uh oh!

janb84 left a comment

Choose a reason for hiding this comment

Uh oh!

janb84 Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

DrahtBot commented Dec 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

kernel: Expose `CheckTransaction` consensus validation function #33796

kernel: Expose `CheckTransaction` consensus validation function #33796

DrahtBot commented Nov 5, 2025 •

edited

Loading