fix(utxo): register epoch mining-reward boxes as account-mirror provenance (danaher #2819, reward path)

[Scottcjn]

Companion to #8388. Closes the same cross-model double-spend class in the epoch settlement path (found while fixing the /utxo/transfer receiver residual).

The bug

Under UTXO_DUAL_WRITE=1, finalize_epoch credits each miner's account balance (the primary ledger) and mints a UTXO reward box for them — but never registered those boxes in account_mirror_boxes. So each mining reward was spendable via both models (UTXO box + account balance) = double spend. A total-only integrity check stays models_agree=True. Latent today (prod runs UTXO_DUAL_WRITE=0).

Fix

• account_mirror_boxes is now canonical UTXO schema (SCHEMA_SQL), so init_tables() creates it for every dual-write writer. This deliberately avoids a CREATE TABLE inside finalize_epoch's open settlement transaction — Python's sqlite3 issues an implicit COMMIT before DDL, which would split the atomic epoch settle. (The schema comment is kept free of the ; character, since _execute_schema splits SCHEMA_SQL on it — a real gotcha caught in testing.)
• finalize_epoch registers every reward box of each dual-write batch into account_mirror_boxes, located by the batch's creation_height (apply_transaction enforces one mining_reward per height, so all boxes at that height are exactly the batch's outputs). Pure INSERTs on the same connection/transaction.

The mirror-input exclusion then blocks re-spending these boxes via the UTXO path, forcing the reward through the account path (single spend).

Tests (node/test_utxo_dualwrite_reward_provenance.py)

• init_tables creates account_mirror_boxes;
• a registered reward box is excluded from UTXO spendable candidates (double-spend closed), while an unregistered one is not (control);
• finalize_epoch wires the registration inside the dual-write block (source/AST, matching test_epoch_utxo_dual_write_guard's convention).

All fail on origin/main, pass here. UTXO + settlement suites: 165 passed, no new failures (2 pre-existing genesis-migration failures are identical on origin/main).

Notes

• Companion to fix(utxo): register dual-write transfer outputs as account-mirror provenance (danaher #2819 receiver residual) #8388 (transfer receiver residual). Recommend merging both together; keep UTXO_DUAL_WRITE=0 on prod until both land.
• danaher-j fix(docs): correct license reference in INSTALL.md (rebased from #2712) #2819 bounty remains held pending payout destination; recommend his review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbyXP4eiiRYEa8GsQtQPhR

[github-actions]

⚠️ BCOS v2 Scan Results

Metric	Value
Trust Score	36/100
Certificate ID	BCOS-8022541e
Tier	L2 (not met)

What does this mean?

The BCOS (Beacon Certified Open Source) engine scans for:

• SPDX license header compliance
• Known CVE vulnerabilities (OSV database)
• Static analysis findings (Semgrep)
• SBOM completeness
• Dependency freshness
• Test infrastructure evidence
• Review attestation tier

Full report | What is BCOS?

---

BCOS v2 Engine - Free & Open Source (MIT) - Elyan Labs

[favoritegrandson-tech]

Heads-up before merging: the reward boxes this registration picks up don't equal the balance credits they shadow. The mint truncates the same amount_decimal twice — 8 dp for the box value, 6 dp for the balances credit — so the box exceeds the credit by up to 99 nRTC per miner per epoch, and mirror ≤ balance fails at creation: integrity_check() returns mirror_exceeds_account, _settle_account_transfer_in_utxo() raises mirror_exceeds_balance → /pending/confirm can never settle transfers touching those wallets, and the now-mirror-tagged box is UTXO-blocked as well (reward frozen in both models).

Repro against main (real finalize_epoch → your registration semantics → the real reconcile fn) plus a one-line fix that makes box value exactly 100 × credit:

Scottcjn/rustchain-bounties#2819 (comment)

[Scottcjn]

Updated (rebased + tightened).

1. Stacked on fix(utxo): dual-write reward boxes exactly mirror the account credit #8481 (the precision fix + credit gate). Its commit shows here until fix(utxo): dual-write reward boxes exactly mirror the account credit #8481 merges, so merge fix(utxo): dual-write reward boxes exactly mirror the account credit #8481 first. Without it, the reward mirrors registered here would be up to 99 nRTC larger than the credits they mirror, and a ghost miner's reward would become a mirror with no balance behind it.
2. Registration tightened. The original query tagged every box at batch_height. The one-mint-per-height guard only limits mining_reward transactions, and ordinary /utxo/transfer boxes use slot heights in the same number space. A user's transfer at the first slot of the settled epoch would have been tagged as a mirror and locked (409). It now joins on the mining_reward tx.
3. New end-to-end test (node/tests/test_finalize_epoch_reward_mirror_registration.py): real finalize_epoch, dual-write on, and a user transfer box placed at the batch height.
   • original query: ❌ 'user-box' tagged as a mirror
   • main: ❌ reward box not registered
   • this version: ✅ the user box is untouched, each reward box is registered once, and each mirror equals its account credit exactly.

Regression check against the #8481 base (CI tests/ plus the epoch, UTXO and dual-write suites): 0 regressions, 4195 → 4199.

[github-actions]

RTC Reward

This merged PR earned 5 RTC — sent to Scottcjn.

RustChain Bounty Program