backport: bitcoin/bitcoin#24304: [kernel 0/n] Introduce dash-chainstate

[knst]

Issue being fixed or feature implemented

This PR is a first backport of the libdashkernel project, see for details: bitcoin#24303

What was done?

This PR introduces an example/demo dash-chainstate executable using said library which can print out information about a datadir and take in new blocks on stdin.

There are multiple PR that has been extracted from this PR and merged independently:

• [merged] refactor: remove dependencies of CInstantSendManager on mempool, signer, chainstate #7178
• [excluded, replaced by NullNodeSyncNotified] refactor: remove dependencies of CChainState on CMasternodeSync #7212
• [merged] refactor: simplify architecture of quorum observer and quorum participant #7247
• [merged] refactor: multiple kernel-0 preparations #7299
• [merged] refactor: drop dependency of spork manager on network code #7303

Beside these PR multiple other PR has been done in the past, such as: #7178, #7070, #7008, #6992, #6959, #7106 (by Udjin), #7065 (by kwvg) and many other PRs.

This PR:

• new stub implementation NullNodeSyncNotifier of CActiveMaternodeSync for governance
• moved network code from llmq/utils to llmq/net_quorum to avoid network dependencies for dash-chainstate
• backport [kernel 0/n] Introduce bitcoin-chainstate bitcoin/bitcoin#24304

There are several important notes about implementation:

• UpdateUncommittedBlockStructures is segwit related; omitted from bitcoin-chainstate.cpp
• call chainman.UnloadBlockIndex is removed by refactor: Move mutable globals cleared in ::UnloadBlockIndex to BlockManager bitcoin/bitcoin#22564, not backported
• binary name is renamed from bitcoin-chainstate to dash-chainstate. Names of source files and some variables are untouched, but final artefact has the correct dashified name
• added LIBDASHBLS to list of libraries to link
• couple functions are reimplemented to avoid balooning dash-chainstate by including extra heavy depenencies
  • ValueFromAmount (reimplemented, core_write.cpp)
  • GetPrettyExceptionStr (reimplemented, stacktrackes.cpp)
  • g_stats_client (redefined)

There are several modules that should be removed in the near future from dash-chainstate binary, but out-of-scope of this PR:

• protocol.cpp -- move NetMsgType inline helpers out of chainlock/clsig.h, governance/object.h, evo/simplifiedmns.h into their .cpp files
• llmq/{dkgsession,dkgsessionhandler,dkgsessionmgr,debug}.cpp and batchedlogger.cpp -- CQuorumManager already null-guards m_qdkgsman; drop once ConnectManagers() is never called on the kernel side
• llmq/signing.cpp -- split CSigningManager out of LLMQContext into a post-construction Connect() so the context becomes quorum-only
• governance/*.cpp -- promote the 4 methods used by CMNPaymentsProcessor (IsValid, IsSuperblockTriggered, IsValidSuperblock, GetSuperblockPayments) to a base interface; instantiate a NullGovernanceManager in bitcoin-chainstate.cpp

How Has This Been Tested?

New binary dash-chainstate is produced, functional & unit tests succeed.

Run dash-chainstate:

$ src/dash-chainstate /home/knst/.dashcore/
Hello! I'm going to print out some information about your datadir.
        Path: "/home/knst/.dashcore"
        Reindexing: false
        Snapshot Active: false
        Active Height: 2294070
        Active IBD: true
        CBlockIndex(pprev=0x5654a3bdb218, nHeight=2294070, merkle=5c87e557b9e697e9308a4a6bd684e362910fe418ca60e59ae1376e91c487df77, hashBlock=0000000000000010938b2d1c2f1ff08163dae17f4196a41d73b9e6e3c4114cc2)

Breaking Changes

N/A

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have made corresponding changes to the documentation
• I have assigned this pull request to a milestone (for repository code-owners and collaborators only)

[github-actions]

This pull request has conflicts, please rebase.

[github-actions]

⚠️ Potential Merge Conflicts Detected

This PR has potential conflicts with the following open PRs:

• ci: migrate primary CI jobs to ARM runners #7232 - ci: migrate primary CI jobs to ARM runners

Please coordinate with the authors of these PRs to avoid merge conflicts.

[github-actions]

This pull request has conflicts, please rebase.

[github-actions]

This pull request has conflicts, please rebase.

[thepastaclaw]

✅ Review complete (commit 0aaadb0)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 99d2079bfc

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[coderabbitai]

Walkthrough

This PR introduces the dash-chainstate experimental executable and adds build/CI wiring for it. Quorum connection and probe helpers are moved from llmq::utils into llmq::net_quorum with a new llmq::EnsureQuorumConnections API; DKG session handler calls are updated to use the relocated logic and a local probe helper. A NullNodeSyncNotifier stub is added for chainstate-only, non-network contexts. The new executable initializes chainstate, reads hex blocks from stdin, validates them via consensus, prints results, and performs deterministic shutdown.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.53% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing a dash-chainstate executable as part of a kernel backport effort.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the dash-chainstate executable introduction, code movements, backport decisions, and implementation notes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/llmq/net_quorum.h (1)

10-10: ⚡ Quick win

TODO comment for removing llmq/utils.h include.

The comment indicates this include should be removed in the future. Verify that moving the quorum connection logic truly eliminates the need for this transitive dependency, or if types/utilities from llmq/utils.h are still required by the declarations in this header.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/llmq/net_quorum.h` at line 10, The TODO notes removing the `#include`
<llmq/utils.h> from src/llmq/net_quorum.h; inspect the public declarations in
net_quorum.h for any direct uses of types, enums, or functions declared in
llmq/utils.h and either (A) remove the include if none are used, (B) replace it
with precise includes for the specific headers that declare the referenced
symbols, or (C) add forward declarations for llmq types used only by
pointer/reference in declarations (so the header no longer depends on
llmq/utils.h). Update net_quorum.h so it no longer relies on transitive includes
from llmq/utils.h while keeping compile errors fixed (focus on symbols
referenced in declarations within net_quorum.h).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/bitcoin-chainstate.cpp`:
- Line 87: Wrap the std::filesystem::create_directories(abs_datadir) call with
error handling: catch std::filesystem::filesystem_error (or std::exception)
around that call, log a clear error message including abs_datadir and the
exception text (e.what()), and then propagate failure by returning an error /
setting an appropriate error code or calling process exit so later code doesn't
run on a missing directory; alternatively check existence after the call and
handle the failed creation path accordingly.

---

Nitpick comments:
In `@src/llmq/net_quorum.h`:
- Line 10: The TODO notes removing the `#include` <llmq/utils.h> from
src/llmq/net_quorum.h; inspect the public declarations in net_quorum.h for any
direct uses of types, enums, or functions declared in llmq/utils.h and either
(A) remove the include if none are used, (B) replace it with precise includes
for the specific headers that declare the referenced symbols, or (C) add forward
declarations for llmq types used only by pointer/reference in declarations (so
the header no longer depends on llmq/utils.h). Update net_quorum.h so it no
longer relies on transitive includes from llmq/utils.h while keeping compile
errors fixed (focus on symbols referenced in declarations within net_quorum.h).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: b488a754-51c5-47cc-903b-b31a03f5095c

📥 Commits

Reviewing files that changed from the base of the PR and between beca567 and 99d2079.

📒 Files selected for processing (14)

• .gitignore
• ci/dash/matrix.sh
• ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
• configure.ac
• src/Makefile.am
• src/active/dkgsessionhandler.cpp
• src/active/dkgsessionhandler.h
• src/bitcoin-chainstate.cpp
• src/llmq/net_quorum.cpp
• src/llmq/net_quorum.h
• src/llmq/utils.cpp
• src/llmq/utils.h
• src/masternode/sync.cpp
• src/masternode/sync.h

💤 Files with no reviewable changes (2)

• src/llmq/utils.h
• src/llmq/utils.cpp

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add error handling for directory creation.

The std::filesystem::create_directories call can fail (e.g., due to permission errors or disk space issues), but there's no check for success. If directory creation fails, subsequent operations will encounter less-clear error messages.

🛡️ Proposed fix to check directory creation

 std::filesystem::path abs_datadir = std::filesystem::absolute(argv[1]);
-std::filesystem::create_directories(abs_datadir);
+if (!std::filesystem::exists(abs_datadir) && !std::filesystem::create_directories(abs_datadir)) {
+    std::cerr << "Failed to create directory: " << abs_datadir << std::endl;
+    return 1;
+}
 gArgs.ForceSetArg("-datadir", abs_datadir.string());

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	std::filesystem::create_directories(abs_datadir);
	std::filesystem::path abs_datadir = std::filesystem::absolute(argv[1]);
	if (!std::filesystem::exists(abs_datadir) && !std::filesystem::create_directories(abs_datadir)) {
	std::cerr << "Failed to create directory: " << abs_datadir << std::endl;
	return 1;
	}
	gArgs.ForceSetArg("-datadir", abs_datadir.string());

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/bitcoin-chainstate.cpp` at line 87, Wrap the
std::filesystem::create_directories(abs_datadir) call with error handling: catch
std::filesystem::filesystem_error (or std::exception) around that call, log a
clear error message including abs_datadir and the exception text (e.what()), and
then propagate failure by returning an error / setting an appropriate error code
or calling process exit so later code doesn't run on a missing directory;
alternatively check existence after the call and handle the failed creation path
accordingly.

[thepastaclaw]

Code Review

Two real build defects in src/Makefile.am are confirmed: the obj/build.h dependency rule references the upstream target name (bitcoin_chainstate-clientversion) instead of the renamed dash_chainstate-clientversion, and dash_chainstate_LDADD references an undefined $(LIBLEVELDB_SSE42). One additional suggestion about the experimental binary's shutdown order is worth surfacing. Most remaining findings either describe intentional, explicitly-documented adaptations for the experimental kernel binary (NullNodeSyncNotifier-induced behavior, mainnet hardcoding) or are low-value nitpicks.

Reviewed commit: 99d2079

🟡 3 suggestion(s)

🤖 Prompt for all review comments with AI agents

These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.

In `src/Makefile.am`:
- [SUGGESTION] lines 1318-1321: obj/build.h dependency rule uses old upstream target name
  Because `dash_chainstate` sets per-target CPPFLAGS/CXXFLAGS (lines 1306-1307), automake compiles its sources to per-target objects named `dash_chainstate-<basename>.$(OBJEXT)` (same convention as `libbitcoin_util_a-clientversion.$(OBJEXT)` on line 482). The rule `bitcoin_chainstate-clientversion.$(OBJEXT): obj/build.h` was copied verbatim from upstream and references a file automake will never produce for this binary, so it never enforces that `obj/build.h` is generated before `clientversion.o` is compiled. The PR's own merge note says the binary was renamed but "Names of source files and some variables are untouched" — this rule is one of the spots that did need to be renamed for the renamed target.
- [SUGGESTION] lines 1309-1316: dash_chainstate_LDADD references undefined variable LIBLEVELDB_SSE42
  `LIBLEVELDB_SSE42` is not defined anywhere in the tree. `src/Makefile.leveldb.include` only defines `LIBLEVELDB = $(LIBLEVELDB_INT) $(LIBCRC32C)` and `LIBMEMENV`; a grep for `LIBLEVELDB_SSE42` finds only this LDADD line. Make silently expands an unset variable to empty so this is dead text rather than a build failure today, but it is misleading (implies SSE4.2 acceleration is being linked when it isn't) and would silently pick up content if that variable is later defined for an unrelated purpose. Drop the line, or define it explicitly in `Makefile.leveldb.include` if SSE4.2-accelerated leveldb is actually intended.

In `src/bitcoin-chainstate.cpp`:
- [SUGGESTION] lines 307-327: Shutdown does not explicitly tear down Dash kernel objects before UnsetGlobals
  The epilogue stops the scheduler, flushes chainstates, unregisters the background scheduler, and then calls `init::UnsetGlobals()` — but the Dash-specific kernel objects (`chain_helper`, `llmq_ctx`, `dmnman`, `evodb`) are left to be destroyed implicitly when `main()` returns, which happens *after* `init::UnsetGlobals()` runs. The normal node shutdown at `src/init.cpp:405` calls `DashChainstateSetupClose(chain_helper, dmnman, llmq_ctx, ...)` and `evodb.reset()` *before* final global teardown. The file's own comment at line 308 states "Without this precise shutdown sequence, there will be a lot of nullptr dereferencing and UB." Even though the binary is experimental, mirroring the node's destruction order would avoid an exit-time crash class as the kernel surface grows.

[coderabbitai]

♻️ Duplicate comments (1)

src/bitcoin-chainstate.cpp (1)

87-87: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add error handling for directory creation.

The std::filesystem::create_directories call can fail (e.g., due to permission errors or disk space issues), but there's no check for success. If directory creation fails, subsequent operations will encounter less-clear error messages.

🛡️ Proposed fix to check directory creation

 std::filesystem::path abs_datadir = std::filesystem::absolute(argv[1]);
-std::filesystem::create_directories(abs_datadir);
+if (!std::filesystem::exists(abs_datadir) && !std::filesystem::create_directories(abs_datadir)) {
+    std::cerr << "Failed to create directory: " << abs_datadir << std::endl;
+    return 1;
+}
 gArgs.ForceSetArg("-datadir", abs_datadir.string());

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/bitcoin-chainstate.cpp` at line 87, The call to
std::filesystem::create_directories(abs_datadir) can fail and currently has no
error handling; wrap the call in a try/catch for
std::filesystem::filesystem_error (or check its boolean return on non-throwing
overload) and on failure log a clear error message including abs_datadir and the
exception message, then return an appropriate error/exit status so subsequent
code does not run on a missing directory. Target the
create_directories(abs_datadir) call in bitcoin-chainstate.cpp and ensure the
error path uses existing logging/error reporting used elsewhere in the module.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@src/bitcoin-chainstate.cpp`:
- Line 87: The call to std::filesystem::create_directories(abs_datadir) can fail
and currently has no error handling; wrap the call in a try/catch for
std::filesystem::filesystem_error (or check its boolean return on non-throwing
overload) and on failure log a clear error message including abs_datadir and the
exception message, then return an appropriate error/exit status so subsequent
code does not run on a missing directory. Target the
create_directories(abs_datadir) call in bitcoin-chainstate.cpp and ensure the
error path uses existing logging/error reporting used elsewhere in the module.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 19ba7c83-f01c-4ab5-bfd7-d78a543b892f

📥 Commits

Reviewing files that changed from the base of the PR and between 99d2079 and 0aaadb0.

📒 Files selected for processing (12)

• .gitignore
• ci/dash/matrix.sh
• ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh
• configure.ac
• src/Makefile.am
• src/active/dkgsessionhandler.cpp
• src/active/dkgsessionhandler.h
• src/bitcoin-chainstate.cpp
• src/llmq/net_quorum.cpp
• src/llmq/net_quorum.h
• src/llmq/utils.cpp
• src/llmq/utils.h

💤 Files with no reviewable changes (2)

• src/llmq/utils.h
• src/llmq/utils.cpp

✅ Files skipped from review due to trivial changes (2)

• .gitignore
• src/active/dkgsessionhandler.h

🚧 Files skipped from review as they are similar to previous changes (5)

• src/Makefile.am
• configure.ac
• src/active/dkgsessionhandler.cpp
• src/llmq/net_quorum.cpp
• ci/test/00_setup_env_native_nowallet_libbitcoinkernel.sh

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0aaadb0dd6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Return non-zero status when load/validation fails

This failure branch jumps to epilogue, but main() never sets or returns an error code afterward, so the process exits with status 0 even when chainstate loading or verification fails. The same pattern is used for malformed stdin blocks (break to epilogue), so callers and CI scripts cannot distinguish success from failure by exit status and may treat failed runs as successful.

Useful? React with 👍 / 👎.

[thepastaclaw]

Code Review

I verified the queued worktree at commit 0aaadb0dd6b72846d6c6605554f8b8f8ff36f187 against the verifier artifacts and the touched source files. There are no remaining valid findings from Claude, Codex, or CodeRabbit on this head; the earlier src/Makefile.am issues and the dash-chainstate shutdown-order concern are fixed in the current code.

Reviewed commit: 0aaadb0