fix(drive-abci): record unshield and shield-surplus credits in recent address balance changes

[QuantumExplorer]

Symptom (dashwallet-ios QA)

Platform payments received via Unshield (Type 17) never appear through incremental address sync — the wallet's GetRecentAddressBalanceChanges passes returned 0 entries across 18 consecutive queries with last_known_recent_block stuck at 0, while the same payments showed up immediately after a full trunk/branch rescan (app relaunch / sync-state clear). Receivers see the money "sometimes" — i.e. only after the next full scan.

Root cause

UnshieldAction credits the transparent platform output address by pushing a raw AddressFundsOperationType::AddBalanceToAddress drive op (action_convert_to_operations/shielded/unshield_transition.rs), which mutates the absolute address-funds tree — what full scans read. But its execution event PaidFromShieldedPool carried no output data, and the executor arm never wrote the credit into address_balances_in_update — the sole feed for store_address_balances_for_block, i.e. the recent-address-balance-changes tree (SavedBlockTransactions/'m') that incremental sync queries. The recent tree was genuinely empty for unshield-credited blocks.

PaidFromAssetLockToPool had the identical omission for a Type 18 ShieldFromAssetLock surplus_output credit.

All transparent-side transitions (AddressFundsTransfer, IdentityCreditTransferToAddresses, fundings, withdrawals, identity ops) already record correctly via PaidFromAddressInputs / Paid { added_to_balance_outputs }. The client-side apply in rs-sdk was verified correct — it would have applied entries had any existed.

Fix

• Extend ExecutionEvent::PaidFromShieldedPool and ::PaidFromAssetLockToPool with added_to_balance_outputs: Option<BTreeMap<PlatformAddress, Credits>> (same shape as Paid's field).
  • Unshield populates output_address → amount − fee (only when net > 0, mirroring the converter's guard).
  • ShieldFromAssetLock populates the surplus output when set and positive.
  • Type 16 ShieldedTransfer / Type 19 ShieldedWithdrawal pass None — neither credits a transparent platform address (Type 19's output is a Core-chain address).
• Both executor arms fold the outputs into address_balances_in_update as CreditOperation::AddToCredits on the applied path, using the identical entry/merge idiom as the Paid arm (including the chargeable-failure fallback, whose address is genuinely credited by the applied ops).

Rolling-upgrade safety (protocol v13)

The recording changes the committed state root, so each changed behavior — and ONLY the changed behavior — is a versioned method with a real v0/v1:

• record_added_balance_outputs/{mod.rs, v0/, v1/} (new method, field 0 in V1..V8 → 1 in V9): v0 folds Transparent-origin outputs, drops ShieldedSpend-origin; v1 folds both. Events carry credits unconditionally (in-memory only).
• process_validation_result/{mod.rs, v0/, v1/} (the per-ST result helper, hoisted into its own method with a new field, 0 in V1..V8 → 1 in V9): v0 = base behavior (paid-invalid passes None, PaidConsensusError carries empty); v1 = unconditional paid-invalid tracking + carry into address_balances_updated. The outer process_raw_state_transitions loop did not change and stays at v0 — it just calls the dispatching helper, same as execute_event_v0 calls the dispatching record_added_balance_outputs.
• DRIVE_ABCI_METHOD_VERSIONS_V9 therefore carries exactly two field deltas — together they define the v13 recorded-set expansion: shielded-spend transparent credits (Unshield net output, shield surplus, identity-create fallback) plus the previously-dropped balance effects of paid-invalid / unsuccessful-paid transitions (charged fees, adjusted outputs).
• store_address_balances_to_recent_block_storage untouched at Some(0); the process_raw_state_transitions dispatch, store dispatch, and feature_initial_protocol_versions are byte-identical to base.
• Pre-v13 parity is proven compositionally: v0 helpers record nothing (asserted even when handed credit-bearing events, at v12 and v13 inputs), v1 records, and the platform-version gating test pins both fields 0@v12 / 1@v13 (and the store method + outer loop unchanged at both).

Tests

• 4 construction tests (net output populated, net-zero → none, surplus populated, no-surplus → none)
• 3 executor tests proving address_balances_in_update receives AddToCredits for both variants and stays empty without outputs
• cargo check -p drive-abci / -p drive clean; touched-module suites green (17 passed drive-abci filter, 43 passed drive saved_block_transactions/converters)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Transparent credits resulting from unshielding and asset-lock surplus outputs are now included in address balance updates.
  • Paid consensus errors on paid-invalid chargeable-failure paths can now carry eligible address balance changes for incremental sync.
  • Protocol version 13 expands shielded-spend transparent credit recording while keeping prior behavior for older versions.

• Bug Fixes

  • Fixed credit aggregation for paid-invalid and chargeable-failure flows, including correct zero/none handling.
  • Ensured paid-consensus error results include accurate balance-change data when applicable.

• Tests

  • Added regression tests for protocol gating and paid failure scenarios.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Execution events now carry optional transparent credit outputs for unshielding and asset-lock shielding. Versioned recording folds these credits into address balances, propagates them through paid consensus errors, and aggregates them into block-level balance updates.

Changes

Transparent credit output propagation

Layer / File(s)	Summary
Protocol version configuration packages/rs-platform-version/src/version/drive_abci_versions/..., packages/rs-platform-version/src/version/v13.rs	Adds the record_added_balance_outputs method version and enables version 1 for protocol v13.
Event fields and output construction packages/rs-drive-abci/src/execution/types/execution_event/mod.rs	Adds optional credit maps to shielded-pool and asset-lock events, populated for positive unshield net amounts and asset-lock surplus outputs.
Execution balance folding packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/...	Adds version-aware credit recording and folds eligible outputs during paid event execution.
Paid error balance propagation packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs	Carries tracked address balance changes into invalid and unsuccessful PaidConsensusError results.
Consensus error aggregation packages/rs-drive-abci/src/platform_types/state_transitions_processing_result/mod.rs	Merges paid-error balance changes into address_balances_updated.
Result and event compatibility packages/rs-drive-abci/src/abci/app/execution_result.rs, packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v0/mod.rs, packages/rs-drive-abci/src/execution/validation/...	Updates destructuring and test fixtures for the new event and result fields.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant StateTransitionAction
  participant ExecutionEvent
  participant execute_event_v0
  participant PaidConsensusError
  participant StateTransitionsProcessingResult
  StateTransitionAction->>ExecutionEvent: construct optional credit outputs
  ExecutionEvent->>execute_event_v0: execute paid event
  execute_event_v0->>PaidConsensusError: attach address balance changes
  PaidConsensusError->>StateTransitionsProcessingResult: aggregate address balance changes

Loading

Suggested labels: ready for final review

Suggested reviewers: thepastaclaw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main fix: recording unshield and shield-surplus credits in recent address balance changes.

✨ 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 fix/unshield-recent-address-balance-changes

---

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

[thepastaclaw]

🕓 Ready for review — 35 ahead in queue (commit cbd5b86)
Queue position: 36/72 · 2 reviews active
ETA: start ~04:06 UTC · complete ~04:34 UTC (median 28m across 30 recent reviews; 2 slots)
Queued 13h 45m ago · Last checked: 2026-07-22 19:40 UTC

[codecov]

Codecov Report

❌ Patch coverage is 79.85154% with 190 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.46%. Comparing base (c311c7e) to head (cbd5b86).
⚠️ Report is 263 commits behind head on v4.1-dev.

Files with missing lines	Patch %	Lines
...ion_processing/process_validation_result/v0/mod.rs	49.01%	78 Missing ⚠️
...ion_processing/process_validation_result/v1/mod.rs	57.14%	66 Missing ⚠️
...ion_processing/record_added_balance_outputs/mod.rs	85.57%	15 Missing ⚠️
...sition_processing/process_validation_result/mod.rs	87.93%	14 Missing ⚠️
...tate_transition_processing/execute_event/v0/mod.rs	93.10%	8 Missing ⚠️
...ve-abci/src/execution/types/execution_event/mod.rs	96.61%	8 Missing ⚠️
...m_types/state_transitions_processing_result/mod.rs	96.96%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           v4.1-dev    #4142      +/-   ##
============================================
+ Coverage     87.44%   87.46%   +0.01%     
============================================
  Files          2648     2658      +10     
  Lines        334178   335741    +1563     
============================================
+ Hits         292230   293663    +1433     
- Misses        41948    42078     +130     

Components	Coverage Δ
dpp	88.44% <ø> (+<0.01%)	⬆️
drive	86.16% <ø> (+0.03%)	⬆️
drive-abci	89.55% <79.85%> (-0.03%)	⬇️
sdk	∅ <ø> (∅)
dapi-client	∅ <ø> (∅)
platform-version	∅ <ø> (∅)
platform-value	92.90% <ø> (+0.01%)	⬆️
platform-wallet	∅ <ø> (∅)
drive-proof-verifier	49.79% <ø> (+0.23%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v0/mod.rs (1)

596-621: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extract the repeated address-credit merge into a helper.

These blocks duplicate each other and the Paid arm’s Set/Add semantics. Centralizing this logic will prevent event paths from silently diverging when merge behavior changes.

Also applies to: 674-699

🤖 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
`@packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v0/mod.rs`
around lines 596 - 621, Extract the address-credit merge logic from the shown
block and the corresponding block around the Paid arm into a shared helper,
using the existing balance-update map and address/credits inputs. Preserve the
current SetCredits + AddToCredits and AddToCredits + AddToCredits saturating-add
semantics, then replace both duplicated loops with calls to the helper.

🤖 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 `@packages/rs-drive-abci/src/execution/types/execution_event/mod.rs`:
- Around line 95-102: Update the documentation for added_to_balance_outputs to
include the identity-create duplicate-key fallback surfaced as an
UnshieldAction, which may credit a transparent address. Keep the existing
Unshield net-positive amount behavior accurate while revising the statement that
all IdentityCreateFromShieldedPool paths produce None.

---

Nitpick comments:
In
`@packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v0/mod.rs`:
- Around line 596-621: Extract the address-credit merge logic from the shown
block and the corresponding block around the Paid arm into a shared helper,
using the existing balance-update map and address/credits inputs. Preserve the
current SetCredits + AddToCredits and AddToCredits + AddToCredits saturating-add
semantics, then replace both duplicated loops with calls to the helper.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 632c9b40-1bdf-47cc-a529-2253dcace728

📥 Commits

Reviewing files that changed from the base of the PR and between b889e05 and 5c335bc.

📒 Files selected for processing (3)

• packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/execute_event/v0/mod.rs
• packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/validate_fees_of_event/v0/mod.rs
• packages/rs-drive-abci/src/execution/types/execution_event/mod.rs

[thepastaclaw]

Preliminary review — Codex only

Fully revalidated the cumulative PR range b889e05..87dab29 and latest-push delta 5c335bc..87dab29. Normal Unshield and ShieldFromAssetLock-surplus credits are recorded, but the IdentityCreateFromShieldedPool duplicate-key fallback is an applied, chargeable invalid transition whose caller passes no balance-change map; PaidConsensusError cannot carry the discarded credit and aggregation only consumes SuccessfulExecution payloads. The claimed fallback regression calls execute_event with None and asserts only the paid result and pool debit, while the new map test supplies Some(&mut map) directly, so neither test covers the failing process_raw_state_transitions-to-recent-storage path; local focused test attempts were blocked by the Tenderdash source download requiring unavailable network access.

Validated blockers were found in the Codex precheck. Sonnet is deferred until a fresh Codex revalidation clears the blocker gate.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (failed), gpt-5.6-sol — rust-quality (failed), gpt-5.6-sol — general (failed), gpt-5.6-sol — rust-quality (failed), gpt-5.6-sol — general (failed), gpt-5.6-sol — general (failed), gpt-5.6-sol — general (completed), gpt-5.6-sol — rust-quality (completed)
• Verifier: gpt-5.6-sol — verifier
• Sonnet: not run (deferred by blocker gate)

🔴 1 blocking

1 additional finding(s) omitted (not in diff).

🤖 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 `packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs`:
- [BLOCKING] packages/rs-drive-abci/src/execution/platform_events/state_transition_processing/process_raw_state_transitions/v0/mod.rs:278-284: Propagate fallback address credits from paid-invalid transitions
  The duplicate-key IdentityCreateFromShieldedPool fallback returns an Unshield action with consensus errors and chargeable_failure=true. execute_event applies that event's operations, including the transparent fallback-address credit, and calls record_added_balance_outputs, but this invalid-transition branch passes None for address_balances_in_update, so the credit is discarded. The resulting PaidConsensusError contains only the error and fees, and StateTransitionsProcessingResult::add merges address changes only from SuccessfulExecution; no later path reconstructs the applied credit before address_balances_updated is stored as the block's recent address-balance changes. Incremental sync therefore omits a GroveDB balance credit that the block actually applied. Preserve the balance-change map for applied paid-invalid events, carry it through PaidConsensusError, aggregate it into address_balances_updated, and add a regression that processes the duplicate-key fallback through process_raw_state_transitions and asserts the recent-balance accumulator or stored entry.

[QuantumExplorer]

Blocker addressed in the latest push:

• The invalid-transition branch of process_raw_state_transitions now tracks address balances (the executor records into the map only on the applied path, so ordinary bump-only paid-invalid transitions stay empty).
• StateTransitionExecutionResult::PaidConsensusError gained address_balance_changes (same shape as SuccessfulExecution's), populated at both construction sites — including the valid-branch UnsuccessfulPaidExecution arm, which had the identical latent omission — and StateTransitionsProcessingResult::add() merges it into address_balances_updated.
• New tests pin the chain at each seam: the real duplicate-key fallback UnshieldAction produces the credited PaidFromShieldedPool event (construction test), the invalid branch of process_validation_result_v0 carries the credit out in PaidConsensusError, and add() merges it into address_balances_updated. A full process_raw_state_transitions fixture was judged disproportionate: the fallback only arises after Halo 2 proof verification succeeds on a duplicate-key create, and no existing fixture produces a valid-proof serialized ST for it — the seam tests jointly cover the exact links the finding identified as broken.

🤖 Addressed by Claude Code

[thepastaclaw]

Final validation — Codex + Sonnet

At exact head 23675f4, no in-scope defects remain. The final commit fixes the sole prior blocker by threading a mutable address-balance map through the invalid branch of process_raw_state_transitions, carrying it via a new address_balance_changes field on PaidConsensusError, and merging it into address_balances_updated exactly like SuccessfulExecution. I independently re-read the diff and reran both regression tests (invalid_branch_chargeable_failure_carries_address_credit and add_merges_paid_consensus_error_address_changes) against the working tree at this SHA — both pass, corroborating the Codex and Sonnet lanes' independent findings.

Review provenance

• Codex reviewers: gpt-5.6-sol — general (failed), gpt-5.6-sol — security-auditor (failed), gpt-5.6-sol — rust-quality (failed), gpt-5.6-sol — general (failed), gpt-5.6-sol — security-auditor (failed), gpt-5.6-sol — rust-quality (failed), gpt-5.6-sol — general (failed), gpt-5.6-sol — security-auditor (failed), gpt-5.6-sol — rust-quality (failed), gpt-5.6-sol — general (completed), gpt-5.6-sol — security-auditor (completed), gpt-5.6-sol — rust-quality (completed)
• Verifier: claude-sonnet-5 — final-verifier
• Sonnet reviewers: claude-sonnet-5 — general (failed), claude-sonnet-5 — security-auditor (failed), claude-sonnet-5 — rust-quality (failed), claude-sonnet-5 — general (completed), claude-sonnet-5 — security-auditor (completed), claude-sonnet-5 — rust-quality (completed)

[QuantumExplorer]

@coderabbitai 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.

[QuantumExplorer]

Self Reviewed