test: exercise the reorg undo round-trip against a real UTXO-Z database

[fpelliccioni]

First real execution of the reorg storage path. Everything merged so far (#571 undo/disconnect, #572 active chain, #573 chain switch) compiled and passed unit tests, but the undo record's central claim — a spent output can be put back exactly as it was — had never actually run.

What it covers

• capture → spend → restore over three UTXOs created at different heights, asserting each returns with its original creation height, not the height of the block that spent it. The height spread is deliberate: a restore that reused one height for all of them would still pass a single-entry test. Getting this wrong would corrupt coinbase maturity and, in compact mode, the median-time-past window used when the UTXO is resolved — silently, and only for outputs a reorg touched.
• an output created and spent inside one block produces no undo entry (it did not exist before the block, so a disconnect must not restore it).
• find_raw reports a miss for an unknown outpoint, so capture fails loudly instead of writing an empty record.

Runs against a real utxoz_database on a temp directory, which is the layer disconnect_block depends on.

Both storage modes

Green in compact (1581 assertions / 165 cases) and full (1606 / 166 — the extra case is the full-mode-only utxoz_roundtrip regression).

Worth flagging: I had been asserting compact was the default. It is not — conanfile.py sets utxoz_compact=False, so normal builds are full mode and the compact path had never been exercised at all. It has now.

Config fix

KTH_UTXOZ_COMPACT_MODE disagreed between modules — database defaulted ON, blockchain OFF — while the real value comes from Conan. Both branch on that macro for the stored value layout, so a standalone build could compile the write path and the storage layer against different formats. Aligned to Conan's value, with a comment saying where the real default lives.

Still not covered

This is the storage layer only. A full reorg (disconnect → switch → re-download) still has no end-to-end test — that needs a harness able to build competing chains and drive the sync pipeline, which is the next step.

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability of UTXO reorganization undo handling, including restoration of spent outputs and their original creation heights.
  • Ensured outputs created and spent within the same block are excluded from undo data.
  • Added validation for unknown transaction outputs.

• Documentation

  • Clarified UTXO storage mode defaults and configuration requirements for standalone builds.

[coderabbitai]

Warning

Review limit reached

@fpelliccioni, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 51 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 096decee-e663-4ca3-8579-89657d648f48

📥 Commits

Reviewing files that changed from the base of the PR and between 92dad0c and d76d98a.

📒 Files selected for processing (5)

• src/blockchain/CMakeLists.txt
• src/blockchain/include/kth/blockchain/utxo_builder.hpp
• src/blockchain/src/utxo_builder.cpp
• src/blockchain/test/reorg_undo_roundtrip.cpp
• src/database/CMakeLists.txt

📝 Walkthrough

Walkthrough

The change documents standalone UTXO-Z compact-mode configuration and adds database-backed blockchain tests for undo restoration, same-block cancellation, payload preservation, creation heights, and unknown outpoints.

Changes

UTXO-Z undo validation

Layer / File(s)	Summary
UTXO-Z build configuration src/database/CMakeLists.txt, src/blockchain/CMakeLists.txt	Documents compact-mode requirements and changes the standalone default from enabled to disabled.
Undo test setup and registration src/blockchain/test/reorg_undo_roundtrip.cpp, src/blockchain/CMakeLists.txt	Adds temporary database, deterministic outpoint, and storage-payload helpers. Registers the new test source.
Undo round-trip assertions src/blockchain/test/reorg_undo_roundtrip.cpp	Verifies UTXO restoration, payload and height preservation, same-block cancellation, and unknown-outpoint misses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• k-nuth/kth#547: Adds related UTXO-Z round-trip tests and compact-mode build configuration.
• k-nuth/kth#564: Concerns related reorganization and UTXO storage functionality.
• k-nuth/kth#571: Introduces related block undo and UTXO restoration functionality.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: integration coverage for reorg undo using a real UTXO-Z database.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/reorg-integration-harness

---

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.}

[fpelliccioni]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 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/blockchain/test/reorg_undo_roundtrip.cpp`:
- Around line 93-124: Replace the manually constructed undo capture, delete map,
and restore logic around the test’s spend/disconnect flow with the production
block-delta path using process_compact_block_utxos and capture_block_undo. Build
the delta from the block, capture its undo record before applying it, then apply
that record to restore the database, including the internal-output case covered
by the later setup. Ensure the test exercises production handling of spending
heights, deferred lookups, and same-block output cancellation.
- Line 164: Update the `find_raw` assertion in the reorg undo round-trip test to
verify that the unknown outpoint returns `result_code::key_not_found`, rather
than only checking that no value is present. Preserve the existing outpoint and
lookup arguments while asserting the documented miss result code.

🪄 Autofix

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 42a423e4-6ccf-4bff-a2ad-0df1c36d68b6

📥 Commits

Reviewing files that changed from the base of the PR and between 03c81ea and 92dad0c.

📒 Files selected for processing (3)

• src/blockchain/CMakeLists.txt
• src/blockchain/test/reorg_undo_roundtrip.cpp
• src/database/CMakeLists.txt