Consolidate Unreleased entries for open PRs

[ArturWieczorek]

Collects the CHANGELOG entries for the currently-open fix/doc PRs into one place, so those PRs no longer touch CHANGELOG.md and stop conflicting with each other on merge.

The CHANGELOG entry has been removed from each of the following PRs; their entries now live here instead:

PR	Entry
#2137	duplicate off-chain vote metadata child rows (#1966)
#2153	document metadata-fetch tools (#1729)
#2160	value-domain schema checks
#2161	duplicate epoch_state rows (#2155)
#2166	db-tool utxo-set/validate RowError crash
#2168	db-tool validate runs all checks + clean errors (#2163)
#2169	db-tool report cosmetics (#2164)
#2171	db-tool validate check bugs (#2170)

Merge this last, once the referenced PRs have landed, so each entry describes code already in master. The feature PRs can now merge in any order without CHANGELOG conflicts.

(#2138 already merged, so its entry is in master already; #2146 intentionally has no changelog entry.)

[ArturWieczorek]

Consolidating the four cardano-db-tool PRs - merge plan

Date: 2026-07-16

The PRs

PR	Branch	Head	What it fixes
#2166	artur/fix-dbtool-txout-decoder-offbyone	8f77ec7	tx_out decoder off-by-one (utxo-set/validate RowError on enterprise outputs)
#2171	artur/fix-dbtool-validate-check-bugs	4073f1e	count epoch block-txs by block.id; clamp block-range sampling (Word64 underflow)
#2168	artur/fix-dbtool-validate-error-handling	1d33ce5	isolate validate checks (run all, exit non-zero at end); clean error rendering; clean missing-slot msg
#2169	artur/fix-dbtool-report-cosmetics	0762536	align report tables; uniform timestamps; help/identifier typo fixes

Merge feasibility (measured with git merge-tree, read-only)

• Shared base of all four branches: 43e2e2c2 (an ancestor of origin/master a379e68d).
• All six pairwise merges AND the cumulative 4-way merge are CLEAN - zero conflicts.
• The BlockTxs.hs conflict the PR bodies anticipated is gone: after the stack rewrite the
  two edits live in non-overlapping regions of the file.
• No branch touches CHANGELOG.md (entries were stripped into the dedicated CHANGELOG
  PR), so the usual conflict magnet is absent.

Files touched by more than one PR (all merge clean)

File	PRs	Why it's clean
cardano-db-tool/.../Validate/BlockTxs.hs	#2171 + #2168	#2171 edits validateBlockCount (count by id); #2168 edits the reporting branch of validateBlockTxs (error-based). Disjoint regions; merged file drops the now-unused forM_/when import. SEMANTIC: must compile - validated by the build.
cardano-db-tool/.../UtxoSet.hs	#2168 + #2169	#2168 changes reportSlotDate (displayException); #2169 fixes the paritioning typo. Disjoint lines.
cardano-db/.../Statement/DbTool.hs	#2166 + #2171	#2166 edits queryUtxoAtBlockId decoders; #2171 edits queryEpochBlockNumbers. Disjoint functions.
cardano-db/cardano-db.cabal, test/test-db.hs	#2166 + #2171	Additive test-module registrations (TxOutQuery, EpochBlockTxs). #2168 adds ErrorRender to the separate test suite.

Recommended strategy

1. Base the consolidation branch on origin/master (a379e68d) - the realistic
   integration target; the extra commits over the shared base are doc/config only and do
   not touch db-tool.
2. Merge the four branches sequentially with --no-ff, in a coherent order:
   Fix consume id in tx_out queries that select txout.* #2166 (decoder) -> Count epoch block txs by id and clamp block-range sampling #2171 (check bugs) -> Isolate validate checks and render errors cleanly #2168 (isolation) -> Align report tables, format timestamps, and fix help typos #2169 (cosmetics).
   Order is not forced by conflicts (there are none); it just tells a clean story and layers
   Count epoch block txs by id and clamp block-range sampling #2171 then Isolate validate checks and render errors cleanly #2168 onto BlockTxs.hs logically.
3. Because textual conflicts are nil, the only real risk is compile/semantic - covered
   by building everything (cabal build cardano-db cardano-db-tool cardano-db-sync +
   the test suites) under -Werror.

What conflicts have to be resolved

None at the text level. The single thing to verify by hand is that the auto-merged
BlockTxs.hs compiles: it must end up with #2168's error-based reporting AND #2171's
validateBlockCount (BlockId, blockNo, expected) + queryEpochBlockNumbers returning the
BlockId, with no leftover forM_/when import. If the build flags anything there, that is
the one place to touch.

Expected end-to-end payoff

A single validate over a real DB that no individual branch can produce: every check runs
(isolation, #2168), decoding is correct (#2166 -> TxAccounting/TotalSupply ok), and
EpochBlockTxs reports ok instead of thousands of false mismatches (#2171). Plus aligned
report tables with clean timestamps (#2169) against a freshly-synced cluster.

[ArturWieczorek]

Consolidated cardano-db-tool fixes (#2166 + #2171 + #2168 + #2169) - end-to-end test results

Date: 2026-07-16
Consolidation branch: tmp/consolidated-dbtool-fixes (local, throwaway)
Base: origin/master a379e68
Merge: the four PR branches merged sequentially, --no-ff, ZERO conflicts:
#2166 8f77ec7 -> #2171 4073f1e -> #2168 1d33ce5 -> #2169 0762536
Build: cabal build cardano-db-tool cardano-db-sync + test suites -> exit 0, clean under -Werror
(this compiles the auto-merged BlockTxs.hs = #2171 count-by-id + #2168 error-reporting).
db-tool binary: dist-newstyle/.../cardano-db-tool-13.7.2.1/x/cardano-db-tool/build/cardano-db-tool/cardano-db-tool

Format: database (full name) / blank / full command / blank / raw output (ANSI stripped).
Long repetitive blocks elided with an explicit marker; scratchpad holds the full captures.

NOTE on the cluster db-sync: the plan was to drive the fresh /cnt cluster with a
consolidated-branch db-sync. In practice a live cardonnay cluster was already running
(driven by the standard ~/.local/bin/cardano-db-sync). Since the decoder/isolation/report
fixes are all in the db-TOOL (and the cardano-db read decoders), and the DB schema/content
is identical regardless of which recent db-sync wrote it, the consolidated db-TOOL was
tested against that cluster's DB rather than tearing down the running cluster. The report
tables were run against a pg_dump clone of the cluster DB with its tip bumped to now (so the
300s report sync-guard passes); the running cluster was not modified, and the clone was
dropped afterward.

UNIT TESTS (consolidated branch)

(no DB) cardano-db-tool:test [#2169 Report.Display]

cardano-db-tool
Report.Display
formatReportTime drops sub-second noise: OK
formatReportTime is uniform regardless of fractional seconds: OK
renderTable aligns every line to a uniform width: OK
renderTable underline has no stray spaces: OK
All 4 tests passed (0.00s) EXIT=0

---

(no DB) cardano-db:test [#2168 ErrorRender + property suite]

Test.Property.Cardano.Db.ErrorRender
prop_lookupErrorShowsMessageOnly passed 1 test.
prop_sessionErrorHasNoRawRecordDump passed 1 test.
2 succeeded.
(+ Upstream, Migration, Types property suites all succeeded) EXIT=0

---

testing (local IO test DB) cardano-db:test-db -p "/TxOutQuery/ || /EpochBlockTxs/" [#2166 + #2171]

Database
EpochBlockTxs
epoch block tx count is looked up by block id: OK (0.32s)
TxOutQuery
queryTxOutputs decodes an enterprise output: OK (0.32s)
utxo-set query decodes an enterprise output: OK (0.32s)
All 3 tests passed (0.97s) EXIT=0

REAL DATABASES

preprod-dbsync-13.7.2.1-node-11.0.1

PGPASSFILE=config/pgpass-preprod cardano-db-tool validate

All pools have owners : ok
All block times are in the past: ok
Block numbers [4499504 .. 4599504] are contiguous: ok
Block time stamps for blocks [33502 .. 133502] are ordered: ok
Sum of AdaPots amounts is constant across epochs: ok
For 100 transactions out of 6097662 accounting is: ok
For 1000 withdrawal addresses, sum withdrawals <= sum rewards: 3 errors:
(3 stake_test1... rewards-vs-withdrawals lines)
All transactions for blocks in epoch 299 are present: ok
All transactions for blocks in epoch 248 are present: ok
Total supply + fees + deposit - withdrawals at block 4052659 is same as genesis supply: 30000000000 /= 29999999765.851334

EXIT=1
(EpochBlockTxs "Failed on block" lines: 0)

PAYOFF: TxAccounting ok (decoder, #2166), EpochBlockTxs ok with ZERO false
mismatches (was ~12,990 - #2171), TotalSupply now DECODES and computes (was a
RowError crash - #2166), and EVERY check ran to completion (isolation, #2168).
EXIT=1 comes only from genuine reconciliation deltas (Withdrawal 3 errors;
TotalSupply ~234 ADA short) - pre-existing check results, now visible because
validate no longer crashes/aborts first. Those checks' logic is untouched by all
four PRs.

---

preview-dbsync-13.7.2.1-node-11.0.1

PGPASSFILE=config/pgpass-preview cardano-db-tool validate

All pools have owners : ok
All block times are in the past: ok
Block numbers [4334934 .. 4434934] are contiguous: ok
Block time stamps for blocks [3145098 .. 3245098] are ordered: ok
Sum of AdaPots amounts is constant across epochs: ok
For 100 transactions out of 6676503 accounting is: ok
For 1000 withdrawal addresses, sum withdrawals <= sum rewards: 7 errors:
(7 stake_test1... lines)
All transactions for blocks in epoch 1354 are present: ok
All transactions for blocks in epoch 92 are present: ok
Total supply + fees + deposit - withdrawals at block 3467720 is same as genesis supply: 30000000000 /= 29999999704.527139

EXIT=1
(EpochBlockTxs "Failed on block" lines: 0)

Same as preprod: TxAccounting ok, EpochBlockTxs ok (0 false mismatches),
TotalSupply decodes, all checks run.

---

preprod-dbsync-13.7.2.1-node-11.0.1

PGPASSFILE=config/pgpass-preprod cardano-db-tool utxo-set --slot-no 185480

Genesis supply: 30000000000 Ada
At slot number 185480:
Date: 2022-06-22 03:31:20 UTC
Supply: 29999998493.355698 Ada
Fees: 0.644302 Ada
Supply + fees == genesis supply: False
From database:
Utxo entries: 11
Utxo supply : 29999998493.355698 Ada
(... aggregation/partition summary; utxo-accept/reject-185480.json written ...)

EXIT=0
Decoder fix (#2166): enterprise outputs decode, no RowError.

---

preprod-dbsync-13.7.2.1-node-11.0.1

PGPASSFILE=config/pgpass-preprod cardano-db-tool utxo-set --slot-no 999999999

Slot not found for slot_no: 999999999

EXIT=0
Clean missing-slot rendering (#2168).

FRESH /cnt CLUSTER (live cardonnay localnet; consolidated db-TOOL vs the cluster DB)

dbsync0 (cardonnay cluster, localhost:55432; 1914 blocks)

PGPASSFILE=/pgpass cardano-db-tool validate

All pools have owners : Failed, 3 pools are without owners.
All block times are in the past: ok
Block numbers [0 .. 1914] are contiguous: ok
Block time stamps for blocks [0 .. 1914] are ordered: ok
Sum of AdaPots amounts is constant across epochs: ok
For 100 transactions out of 27 accounting is:
TxId: 4
Fee: 0
TxIn: []
TxOut: [TxId 4 Value 3480000]
For 0 withdrawal addresses, sum withdrawals <= sum rewards: ok
All transactions for blocks in epoch 19 are present: ok
All transactions for blocks in epoch 14 are present: ok
Total supply + fees + deposit - withdrawals at block 1366 is same as genesis supply: 10020 /= 30003490020

EXIT=1

Bug 2 FIXED (#2171): block-property ranges are [0 .. 1914] (clamped to the real
block count), NOT the Word64 underflow (~1.8e19) the old code produced on a DB with
< 100000 blocks. Isolation (#2168): pools Failed, TxAccounting Failed (localnet
genesis zero-input tx, not the decoder), and TotalSupply mismatch (localnet genesis
10020 vs computed) are ALL reported and the run walks every check. EpochBlockTxs ok.

---

dbsync0_clusterreport (pg_dump clone of the cluster DB, tip bumped to now so the report sync-guard passes; original cluster untouched)

PGPASSFILE= cardano-db-tool report balance --stake-address <3 addrs>

stake_address                                                    |        balance
-----------------------------------------------------------------+---------------
stake_test1upxpaf4xmxq4fjnudj4ew0zupp5g4yewuvscr7de8fm3p3cy6uvtf | 1000771.170429
stake_test1up5rtsd2hxchqurdnl6up9fduc6l0pac78k5m9feemf43gsgfkvzh |  500000.000000
stake_test1up7dmkq9nntl84lzl2an85sxuh2levpz7lura42yxtxjj6swgmgg7 |  500000.000000
-----------------------------------------------------------------+---------------
total                                                            | 2000771.170429

EXIT=0
#2169: 64-char address column padded to full width, balance right-aligned, total
row set off by the restored divider.

---

dbsync0_clusterreport

PGPASSFILE= cardano-db-tool report rewards latest --stake-address

epoch | stake_address                                                    |      delegated | pool_id | ticker |      reward | RoS (%pa)
------+------------------------------------------------------------------+----------------+---------+--------+-------------+----------
   17 | stake_test1uq38rj9hwuff97s6m3jfwqfge4q5wjtq2uyq9sz3r237kdqdw5sr3 | 3506106.755704 |       3 | ???    | 1900.383825 |     3.959

EXIT=0
#2169: every column sized to its widest cell; the 64-char address does not shift
the following columns.

---

dbsync0_clusterreport

PGPASSFILE= cardano-db-tool report transactions --stake-address stake_test1up5rtsd2hxchqurdnl6up9fduc6l0pac78k5m9feemf43gsgfkvzh

Transactions for: stake_test1up5rtsd2hxchqurdnl6up9fduc6l0pac78k5m9feemf43gsgfkvzh

tx_hash                                                          | date/time               | direction |        amount
-----------------------------------------------------------------+-------------------------+-----------+--------------
d351cae7940985d913905789d1fa80848289a035150a6fde67371f77a454e771 | 2026-07-16 18:07:15 UTC | Incoming  | 500000.000000

EXIT=0
#2169 live timestamp: date/time renders via formatReportTime as
"2026-07-16 18:07:15 UTC" - uniform, second-precision, fixed width; all columns
aligned. This is the live timestamped row that the standalone #2169 test could not
produce (its localnet had no stake-linked outputs).

SUMMARY

• Merge: four PRs consolidated with ZERO conflicts (git merge-tree pre-check + live
  sequential merge). CHANGELOG stripped into the separate PR removed the usual conflict.
• Build: clean under -Werror -> the cross-PR BlockTxs.hs/UtxoSet.hs/DbTool.hs merges are
  semantically sound.
• Unit tests: 4 suites, all green (Fix consume id in tx_out queries that select txout.* #2166 TxOutQuery, Count epoch block txs by id and clamp block-range sampling #2171 EpochBlockTxs, Isolate validate checks and render errors cleanly #2168
  ErrorRender, Align report tables, format timestamps, and fix help typos #2169 Report.Display).
• Real DBs (preprod + preview): a single validate now walks every check, decodes
  correctly (TxAccounting + TotalSupply, Fix consume id in tx_out queries that select txout.* #2166), reports EpochBlockTxs ok with 0 false
  mismatches (Count epoch block txs by id and clamp block-range sampling #2171), and runs to completion (Isolate validate checks and render errors cleanly #2168). utxo-set decodes + clean missing-slot.
• Fresh cluster: Bug 2 range clamp [0 .. 1914] (Count epoch block txs by id and clamp block-range sampling #2171) + full isolation (Isolate validate checks and render errors cleanly #2168) live;
  all three report tables aligned with a live second-precision timestamp (Align report tables, format timestamps, and fix help typos #2169).

CONCLUSION: the four cardano-db-tool PRs combine cleanly, build under -Werror, and
together produce correct, complete, well-formatted db-tool output on real databases and a
fresh cluster - an end-to-end result none of the four branches can produce alone.
Remaining non-zero validate exits are genuine Withdrawal / TotalSupply reconciliation
deltas whose check logic is outside these four PRs.