[UTXO-BUG] Fix dual-write reward settlement

[jonathanpopham]

Summary

• Fixes a UTXO dual-write reward-settlement failure in the Phase 1/2 migration path covered by the Red Team UTXO bounty: [BOUNTY] Red Team UTXO Implementation — Find Bugs, Earn RTC (50-200 RTC) rustchain-bounties#2819
• Configures the finalize_epoch() SQLite connection with sqlite3.Row before passing it into UtxoDB.apply_transaction(), which expects row-style access.
• Batches all miner reward outputs into one or more mining_reward transactions instead of applying one mining_reward per miner at the same block height.

Vulnerability class

High/Medium: UTXO dual-write reward settlement failure.

With UTXO_DUAL_WRITE=1, finalize_epoch() passed a plain SQLite connection into the UTXO layer. UtxoDB.apply_transaction() uses row["n"]/named-row access, so that path can fail before UTXO rewards are written. After that is fixed, the old per-miner loop still attempts multiple mining_reward transactions at epoch * 144; the UTXO layer correctly permits only one mining reward per block height, so multi-miner epochs can fail and roll back settlement.

Impact: enabling UTXO dual-write can prevent epoch rewards from settling for normal multi-miner epochs, leaving the migration path unusable until fixed.

Fix

• Set conn.row_factory = sqlite3.Row before creating the epoch cursor.
• Collect miner UTXO reward outputs during the account update loop.
• Apply batched mining_reward transactions after reward calculation, using one block height per batch inside the epoch window.
• Cap batch size with the UTXO layer MAX_OUTPUTS value.

Validation

• Added regression coverage in node/tests/test_integrated_balance_scale.py for row-style UTXO connections and multi-miner UTXO reward batching.
• python3 -m compileall -q node/rustchain_v2_integrated_v2.2.1_rip200.py node/tests/test_integrated_balance_scale.py
• git show --check --stat --oneline HEAD

Bounty wallet/miner ID for payout if accepted: jonathanpopham

[github-actions]

Welcome to RustChain! Thanks for your first pull request.

Before we review, please make sure:

• Non-doc PRs have a BCOS-L1 or BCOS-L2 label
• Doc-only PRs are exempt from BCOS tier labels when they only touch docs/**, *.md, or common image/PDF files
• New code files include an SPDX license header
• You've tested your changes against the live node

Bounty tiers: Micro (1-10 RTC) | Standard (20-50) | Major (75-100) | Critical (100-150)

A maintainer will review your PR soon. Thanks for contributing!

[jonathanpopham]

Payout address update if this bounty claim is accepted: RTC4730a64f821a590972e8b37781fae5d568b5865c.

[jonathanpopham]

Maintainer note: this is a non-doc UTXO/node fix and should be tagged BCOS-L1 or BCOS-L2 per the project PR checklist. I do not have label permission on the upstream repo; the current checks are otherwise passing except the repository-wide test job baseline failure.

[eliasx45]

Reviewed current head 84b99077773673743cd2f9a5fd71e30d03e42623.

Verdict: request changes.

The production change is directionally sensible: finalize_epoch() now sets conn.row_factory = sqlite3.Row before passing the shared connection into UtxoDB.apply_transaction(), and it batches miner reward outputs so the UTXO layer does not see multiple mining_reward transactions at the same block height.

However, I cannot approve yet because the focused test file does not pass on this Windows checkout.

First run in the repo venv failed before executing tests because prometheus_client is not installed here and is not listed in requirements.txt or requirements-node.txt:

ModuleNotFoundError: No module named 'prometheus_client'

After installing prometheus_client into the repo venv only so I could continue verification, the focused tests executed their assertions but failed in teardown because the temp SQLite DB remained open:

PermissionError: [WinError 32] The process cannot access the file because it is being used by another process: '...\\scale.db'

I reproduced that with both:

PYTHONPATH=node .\.venv\Scripts\python.exe -m unittest node.tests.test_integrated_balance_scale

and the two new focused tests:

PYTHONPATH=node .\.venv\Scripts\python.exe -m unittest node.tests.test_integrated_balance_scale.TestIntegratedBalanceScale.test_finalize_epoch_passes_row_connection_to_utxo_db node.tests.test_integrated_balance_scale.TestIntegratedBalanceScale.test_finalize_epoch_batches_multi_miner_utxo_rewards

Other checks:

• python -m compileall -q node/rustchain_v2_integrated_v2.2.1_rip200.py node/tests/test_integrated_balance_scale.py passed.
• git diff --check origin/main...HEAD passed.
• git merge-tree --write-tree origin/main HEAD produced a clean tree (ade7636699de7e08766704225254b5b61ce24ae5).

Requested fix: make the focused test module runnable from a clean repo test environment and close/release the SQLite handles on Windows before TemporaryDirectory.cleanup(). A small cleanup step such as explicitly stopping/closing imported-node background resources, or at minimum a deterministic gc.collect()/retry around the temp DB cleanup if that matches the repo's test pattern, should be enough. Please also account for prometheus_client as a test dependency or avoid requiring it for this test module.

[jonathanpopham]

Updated in b88bb0c.

• Merged current origin/main into the branch; the PR now includes main at d9ac21c.
• Removed the focused test dependency on external prometheus_client by installing a local fake module only during the integrated module import.
• Closed SQLite helper connections with contextlib.closing, dropped the imported module reference, and forced GC before TemporaryDirectory cleanup so Windows can release scale.db.

Local verification passed:

PYTHONPATH=node /tmp/rustchain6537-py311-venv/bin/python -m compileall -q node/rustchain_v2_integrated_v2.2.1_rip200.py node/tests/test_integrated_balance_scale.py
PYTHONPATH=node /tmp/rustchain6537-py311-venv/bin/python -m unittest node.tests.test_integrated_balance_scale

Result: 4 focused tests passed.

[jonathanpopham]

CI note: the remaining red test check is the repo-wide pytest sweep. Current main is also red on the same CI workflow at d9ac21c, and this PR head has all BCOS/label/PoC checks green.

The failures reported by that broad job are outside this PR path: monitor payload shape, setup-miner artifact hash, tx-handler auth/status expectations, stale-data UTXO tests, and wallet-network retry tests. The focused test for this fix passed locally after the update, as noted above.

[eliasx45]

Re-reviewed updated head b88bb0c4f2faffb4d6b717b94abd1b16a0ce3f6d after the Windows/test-harness follow-up.

Verdict: approve.

The blockers from my previous review are resolved:

• The test no longer depends on an installed external prometheus_client; it installs a local fake module during the integrated module import.
• The Windows temp SQLite cleanup issue is fixed; the focused tests no longer fail with PermissionError on scale.db cleanup.

Validation on this Windows checkout:

• PYTHONPATH=node .\.venv\Scripts\python.exe -m compileall -q node/rustchain_v2_integrated_v2.2.1_rip200.py node/tests/test_integrated_balance_scale.py passed.
• PYTHONPATH=node .\.venv\Scripts\python.exe -m unittest node.tests.test_integrated_balance_scale passed: 4 tests OK.
• Direct focused rerun passed: test_finalize_epoch_passes_row_connection_to_utxo_db and test_finalize_epoch_batches_multi_miner_utxo_rewards both OK.
• After fetching current origin/main, git diff --check origin/main...HEAD passed.
• git merge-tree --write-tree origin/main HEAD produced a clean tree (fd40b5f71ef21962f23090ba5e41cd64ca55a2d8).

The hosted broad test check is still red, but the current main branch is also red on that broad workflow per the author's note, and the PR-scoped integrated balance tests now pass locally. I do not see a remaining blocker in the changed files.

[crystal-tensor]

Code Review: PR #6537 — Fix dual-write reward settlement

Security Assessment: ✅ APPROVED — Medium/High

Severity: High (UTXO migration path broken)

Summary: Two bugs in finalize_epoch() when UTXO_DUAL_WRITE=1:

1. SQLite connection lacked row_factory = sqlite3.Row, causing row["n"] access to fail
2. Per-miner mining_reward transactions at the same block height violate UTXO's one-mining-reward-per-block-height rule

Strengths

1. Both bugs correctly identified and fixed: Row factory fix is straightforward; batching ensures one mining_reward tx per block height.

2. Batching respects UTXO constraints: Batch size capped at UTXO_MAX_OUTPUTS, distributed across EPOCH_SLOTS block heights.

3. Safety check: If reward batches exceed EPOCH_SLOTS, raises RuntimeError — prevents silent failure.

4. Test coverage: test_integrated_balance_scale.py covers both fixes.

Security Impact

Confirmed: Without fix #1, any epoch finalization with UTXO_DUAL_WRITE=1 fails at the first mining reward. Without fix #2, multi-miner epochs fail and roll back entirely.

Final Verdict

✅ APPROVED — Critical UTXO migration path fix. Ready to merge.

[Scottcjn]

Merged + paid 25 RTC (Medium #2867). Reserved at github:jonathanpopham.

Codex review: feature-flagged path real, fix correct, tests good. Thanks @jonathanpopham.