kernel: Add non-utxo set block validation to API #35187

This adds a kernel C header API endpoint for validating a block without having access to the full UTXO set. The introduced block validation function is intended to be called after having instantiated a chainstate manager and processing the block's header. Following this contract, the block is internally validated by the CheckBlock, ContextualCheckBlockHeader, ContextualCheckBlock, and finally ConnectBlock functions.

The CoinsViewBlock class is introduced to validate user-provided coins from two arrays encoding OutPoint/Coin pairs. It inherits from CCoinsViewCache and is eventually passed to ConnectBlock. This allows validating the block's scripts and spends against user-provided UTXOs instead of using the chainstate's own internal UTXO set.

This also includes some more API endpoints to populate the coins and OutPoints and retrieve relevant data.

<!--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/35187.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process.

If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #26022 (Add util::ResultPtr class by ryanofsky)
• #25722 (refactor: Use util::Result class for wallet loading by ryanofsky)
• #25665 (refactor: Add util::Result failure types and ability to merge result values by ryanofsky)

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.

<!--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):

• Coin{output, 0, false} in src/test/kernel/test_kernel.cpp
• Coin{output, 1, true} in src/test/kernel/test_kernel.cpp

Possible places where comparison-specific test macros should replace generic comparisons:

• [src/test/kernel/test_kernel.cpp] BOOST_CHECK_THROW(Transaction{invalid_data}, std::runtime_error); -> prefer BOOST_CHECK_EXCEPTION(..., std::runtime_error, HasReason("...")) or another check that verifies the specific failure message instead of only the generic exception type.

^{2026-07-14 20:23:09}

The goal of this endeavor is to retire btck_block_spent_outputs_read from the kernel?

The goal of this endeavor is to retire btck_block_spent_outputs_read from the kernel?

No, I think that is unrelated. Read deserializes data, while the creation function introduced here takes an existing shape of coins.

Approach ACK If we are going through this route, won't it be more straightforward to just pass the spent coins and add them to the coins cache as demonstrated in https://github.com/ismaelsadeeq/bitcoin/commit/9b9db183535d063631b2e13f9d6fb1cd0b7dc98b?

Not sure why it is necessary to have the caller pass the block undo? Is it because we expect the client to have block undo, if not then it's an unnecessary round trip. Clients will map spent coins to block undo, and then we map the block undo to spent coins.

What format do we expect the block undo to be in? If we say they have to be well-constructed, i.e. be in the right index as the transaction that consumes them, etc., we have to verify that contract no? I don't think we do here. So, if we go ahead and do this and the proposed refactor in #32317 gets done, will passing an undo that violates that contract break things? I find it less footgun-y for this approach to just receive a list of spent coins instead of block undo, because of the edge cases of empty undo ordering, in the coinsview map of undo to coins you have to skip block undo entries whose coins are created in the same block etc.

After #32317, we can skip the validation of the block undo ordering and contract by us mapping the spent coins and the block into the desired format, i.e., block undo vector.

If we are going through this route, won't it be more straightforward to just pass the spent coins and add them to the coins cache ... I find it less footgun-y for this approach to just receive a list of spent coins instead of block undo, because of the edge cases of empty undo ordering, in the coinsview map of undo to coins you have to skip block undo entries whose coins are created in the same block etc.

I agree that the current approach here is not good and should be changed to not use the undo data structure. As you correctly lay out, it does rely on some internal coins cache behavior, and this was part of the motivation for opening #32317. I think passing the correctly shaped contiguous coins vector is a bit annoying to deal with for the calling developer. Maybe it's best to just rewire FetchCoinFromBase to take a callback that the developer passes to the validation function and then deals with it in their own space?

Not sure I truly understand the implications, but the callback passed to the validate method makes sense to me. From a client perspective, I believe the following would be most intuitive:

let state = chainman.validate_block(
    &block,
    |outpoint: TxOutPointRef<'_>| -> Option<Coin> {
        my_db.get(&outpoint)
    },
)?;

Which would translate to a signature of:

typedef const btck_Coin* (*btck_coin_getter)(
    void* context,
    const btck_TransactionOutPoint* outpoint
);

BITCOINKERNEL_API int btck_chainstate_manager_validate_block(
    btck_ChainstateManager* chainstate_manager,
    const btck_Block* block,
    btck_coin_getter coin_getter,
    void* context,
    btck_BlockValidationState* block_validation_state
);

Approach ACK

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task ASan + LSan + UBSan + integer: https://github.com/bitcoin/bitcoin/actions/runs/29262195354/job/86858105991} _{LLM reason (✨ experimental): CI failed because test_kernel hit an UndefinedBehaviorSanitizer error (invalid-null-argument) when creating chainstate manager options (null/empty dir passed).}

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

• Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

• A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

• An intermittent issue.

Leave a comment here, if you need help tracking down a confusing failure.

</details>

``

Opening this up for review again. Basically went with @ismaelsadeeq's suggestion of passing in two arrays encoding pairs of outpoints and coins.

Opening this up for review again. Basically went with @ismaelsadeeq's suggestion of passing in two arrays encoding pairs of outpoints and coins.

This looks much simpler now. I will review the changes thoroughly 👍🏾 .

Code review ACK a77602ed7d4b4dda7cb4ef67148e004102a93be1

I did not find any issue, these are just minor comments.

I rebased this on #35000 and tested this path in the unit tests, I did not get any failure https://github.com/ismaelsadeeq/bitcoin/tree/pr-35187.

The Validation blog post explains that there are essentially three different "levels" to validate a block with more or less consensus evidence:

1. Intrinsic validation
2. Validation against the ancestry of block headers
3. Validation against the ancestry plus the set of spendable coins (aka utxo-set)

The titles of the PR and the commit ("non-utxo set block validation", "sans utxo set block validation") seem to imply that this is adding a validation function for either level one or two. But looking at the signature of the added function, I get the impression that this is about level three instead: The block_tree_entry argument provides the ancestry while spent_out_points, spent_coins, and spent_outputs_len together provides access to the coins.

The way the spent coins are provided to the function (two arrays) requires the whole utxo-set to be converted twice:

1. Clients flatten their own dictionary into the two arrays.
2. The library then constructs an ephemeral std::map from the two arrays.

While this approach may serve as a proof-of-concept, it will not scale to a production application. As @alexanderwiederin pointed out, a better approach would be to abstract the lookup function. This way, the library is given direct, zero-copy lookup access to the clients dictionary structure.

While this approach may serve as a proof-of-concept, it will not scale to a production application. As @alexanderwiederin #35187 (comment), a better approach would be to abstract the lookup function. This way, the library is given direct, zero-copy lookup access to the clients dictionary structure.

Yeah, I agree that, depending on the script size, the coin copy may not be cheap. Your suggestion allows the lookup function to be passed to the CoinsViewBlock class, and the lookup will be direct and zero-copy, as u mention. But note the current approach does have the advantage of preventing footguns like child spend before parent, which is a consensus bug. A naive client might shoot themselves in the foot easily by allowing access to the child utxo in the db before it is created.

While this approach may serve as a proof-of-concept, it will not scale to a production application. As @alexanderwiederin #35187 (comment), a better approach would be to abstract the lookup function. This way, the library is given direct, zero-copy lookup access to the clients dictionary structure.

Yeah, I agree that, depending on the script size, the coin copy may not be cheap. Your suggestion allows the lookup function to be passed to the CoinsViewBlock class, and the lookup will be direct and zero-copy, as u mention.

It is not about the copy of a coin. It is about two copies of the complete utxo set, no? One copy to flatten it into two arrays and another copy to convert the two arrays into a map.

But note the current approach does have the advantage of preventing footguns like child spend before parent, which is a consensus bug. A naive client might shoot themselves in the foot easily by allowing access to the child utxo in the db before it is created.

How so? Inserting the block's utxos into the utxo set before the block is validated would indeed not be very smart. But how does this design prevent it?

But how does this design prevent it?

Because we have the block and the user provided utxo's the CoinsViewBlock checks during insertion into the map that it is not a block utxo.

Because we have the block and the user provided utxo's the CoinsViewBlock checks during insertion into the map that it is not a block utxo.

Can you elaborate? I want to make sure I follow. If you mean forward references in intra-block spends: FetchCoinFromBase already guards those with m_block_txids.contains(outpoint.hash) on every base fetch, before it consults the coin source. It could protect a callback source the same way it protects the two arrays.

@alexanderwiederin yeah sorry, my comment wasn't elaborate enough. Currently, we prevent forward references in intra block spends twice, both keyed on m_block_txids.contains(outpoint.hash).

1. In the CoinsViewBlock constructor, we don't add a supplied coin to the map if its outpoint belongs to a transaction created in this block.

        m_block_txids.reserve(block.vtx.size());
        for (const auto& tx : block.vtx) m_block_txids.insert(tx->GetHash());

        for (size_t i{0}; i < len; ++i) {
            const COutPoint& outpoint{btck_TransactionOutPoint::get(out_points[i])};
            const Coin& coin{btck_Coin::get(coins[i])};
            if (m_block_txids.contains(outpoint.hash)) continue;
            m_coins.try_emplace(outpoint, coin);
        }
    }

2. In FetchCoinFromBase, we return nullopt for any in-block outpoint before even consulting the map:

    std::optional<Coin> FetchCoinFromBase(const COutPoint& outpoint) const override
    {
        if (m_block_txids.contains(outpoint.hash)) return std::nullopt;
        if (auto it{m_coins.find(outpoint)}; it != m_coins.end()) return it->second;
        return std::nullopt;
    }

These two guards enforce the same invariant, so either one alone is sufficient. With only the constructor filter, m_coins can never hold an outpoint whose hash is an in block txid.

This holds for the BIP30 edge case too? But with only the FetchCoinFromBase guard, an in-block coin could sit in m_coins but would never be served.

So the IMO FetchCoinFromBase check is the redundant one, and it's on the hot path evaluated on every FetchCoinFromBase call, whereas the constructor check runs once per supplied coin at setup.

That's why I suggested removing it here #35187 (review), and why keeping approach 2 instead is the less efficient choice, as I noted here #35187 (review), but if you go with the approach you suggested, then we may need approach 2.

Please correct me if I am wrong here.