test(platform-wallet): QA-V6→V26 fixes + parallelism contract

packages/rs-platform-wallet/Cargo.toml

@@ -90,8 +90,12 @@ tokio-util = { version = "0.7", features = ["rt"] }
 # and `framework/context_provider.rs` and is currently disabled
 # (see harness.rs) — re-enable when SPV cold-start is stable
 # (Task #15).
-rs-sdk-trusted-context-provider = { path = "../rs-sdk-trusted-context-provider" }
-
+rs-sdk-trusted-context-provider = { path = "../rs-sdk-trusted-context-provider", features = ["dpns-contract"] }
+# In-memory test runs (NoPlatformPersistence) need finalized txs retained in RAM.
+# Re-declaring here enables the feature for the test target only; production
+# builds pay no memory overhead. Per upstream rust-dashcore maintainer guidance.
+key-wallet = { workspace = true, features = ["keep-finalized-transactions"] }
+key-wallet-manager = { workspace = true, features = ["keep-finalized-transactions"] }
 
 [features]
 default = ["bls", "eddsa"]

packages/rs-platform-wallet/src/error.rs

@@ -73,6 +73,20 @@ pub enum PlatformWalletError {
     #[error("Address operation failed: {0}")]
     AddressOperation(String),
 
+    #[error(
+        "gap-limit exceeded: requested {requested} fresh unused addresses but only \
+         {available} are derivable past the current gap-limit boundary \
+         (highest_used={highest_used:?}, highest_generated={highest_generated:?}, \
+         gap_limit={gap_limit})"
+    )]
+    GapLimitExceeded {
+        requested: usize,
+        available: u32,
+        highest_used: Option<u32>,
+        highest_generated: Option<u32>,
+        gap_limit: u32,
+    },
+
     #[error("Arithmetic overflow on Credits in {context}")]
     ArithmeticOverflow { context: String },
 

packages/rs-platform-wallet/src/wallet/core/broadcast.rs

@@ -182,6 +182,18 @@ impl<B: TransactionBroadcaster + ?Sized> CoreWallet<B> {
         // network resolves that race exactly as it does on `v3.1-dev`
         // today, but neither caller corrupts local state on a transient
         // broadcast failure.
+        //
+        // TODO(CR-004 / dash-evo-tool#845): pin that this post-broadcast
+        // hook actually mutates `standard_bip32_accounts` UTXO state — not
+        // just `standard_bip44_accounts`. The downstream
+        // `key_wallet::ManagedWalletInfo::check_core_transaction` routes
+        // standard txs through both BIP32 and BIP44 collections via
+        // `TransactionRouter::get_relevant_account_types`, but if a future
+        // routing regression skips BIP32 (the "legacy" path DET v0.9.x
+        // wallets still rely on), this call will silently leave UTXOs
+        // marked spendable on `standard_bip32_accounts[0]`. The CR-004 e2e
+        // test pins the contract end-to-end; this comment names the call
+        // site so a reviewer chasing that test failure lands here directly.
         {
             let mut wm = self.wallet_manager.write().await;
             let (wallet, info) =
@@ -191,6 +203,16 @@ impl<B: TransactionBroadcaster + ?Sized> CoreWallet<B> {
                             "Wallet not found in wallet manager".to_string(),
                         )
                     })?;
+            tracing::debug!(
+                target: "platform_wallet::core::broadcast",
+                txid = %tx.txid(),
+                account_type = ?account_type,
+                account_index,
+                inputs = tx.input.len(),
+                outputs = tx.output.len(),
+                "post-broadcast: dispatching check_core_transaction(Mempool) — \
+                 must mark consumed UTXOs spent on the matching account collection"
+            );
             info.check_core_transaction(&tx, TransactionContext::Mempool, wallet, true, true)
                 .await;
         }

packages/rs-platform-wallet/src/wallet/platform_addresses/transfer.rs

@@ -183,6 +183,96 @@ impl PlatformAddressWallet {
         Ok(cs)
     }
 
+    /// Transfer credits with an explicit "change address" override.
+    ///
+    /// Companion to [`Self::transfer`] that surfaces the implicit
+    /// "where does the residual go?" decision as a first-class
+    /// parameter (PA-001b).
+    ///
+    /// **Override semantics**:
+    /// - `output_change_address: None` — straight passthrough to
+    ///   [`Self::transfer`]; residual stays on the input addresses
+    ///   under the existing implicit-change behaviour. Use this branch
+    ///   when the caller does not care where the change lands.
+    /// - `output_change_address: Some(change_addr)` — every input is
+    ///   spent in full, and `change_addr` is added as an extra output
+    ///   absorbing `Σ inputs − Σ user_outputs`. The protocol's
+    ///   `Σ inputs == Σ outputs` invariant holds because the change
+    ///   output exactly balances the surplus.
+    ///
+    /// The change branch requires [`InputSelection::Explicit`] (or
+    /// [`InputSelection::ExplicitWithNonces`]): the caller declares
+    /// the inputs and their consumption explicitly, which is the only
+    /// shape where "consume the entire input balance" is unambiguous
+    /// — the auto-selector trims to the smallest covering prefix, so
+    /// it has no concept of a residual to route. The map's values
+    /// must therefore equal the full balances the caller wants
+    /// consumed; the wrapper sums them and assigns the surplus to
+    /// `change_addr`.
+    ///
+    /// Errors:
+    /// - [`PlatformWalletError::AddressOperation`] when the change
+    ///   branch is requested with [`InputSelection::Auto`], when
+    ///   `change_addr` already appears in `user_outputs` (would merge
+    ///   silently), or when `Σ inputs ≤ Σ user_outputs` (no surplus
+    ///   to route).
+    #[allow(clippy::too_many_arguments)] // mirrors `transfer`'s signature plus the change-address override; merging into a builder would obscure the additive surface PA-001b pins.
+    pub async fn transfer_with_change_address<S: Signer<PlatformAddress> + Send + Sync>(
+        &self,
+        account_index: u32,
+        input_selection: InputSelection,
+        user_outputs: BTreeMap<PlatformAddress, Credits>,
+        output_change_address: Option<PlatformAddress>,
+        fee_strategy: AddressFundsFeeStrategy,
+        platform_version: Option<&PlatformVersion>,
+        address_signer: &S,
+    ) -> Result<PlatformAddressChangeSet, PlatformWalletError> {
+        let Some(change_addr) = output_change_address else {
+            return self
+                .transfer(
+                    account_index,
+                    input_selection,
+                    user_outputs,
+                    fee_strategy,
+                    platform_version,
+                    address_signer,
+                )
+                .await;
+        };
+
+        let (input_sum, augmented_selection) = match input_selection {
+            InputSelection::Explicit(ref inputs) => (
+                inputs.values().copied().sum::<Credits>(),
+                InputSelection::Explicit(inputs.clone()),
+            ),
+            InputSelection::ExplicitWithNonces(ref inputs) => (
+                inputs.values().map(|(_n, c)| *c).sum::<Credits>(),
+                InputSelection::ExplicitWithNonces(inputs.clone()),
+            ),
+            InputSelection::Auto => {
+                return Err(PlatformWalletError::AddressOperation(
+                    "output_change_address: Some(_) requires InputSelection::Explicit \
+                     or ExplicitWithNonces — the auto-selector trims inputs to a covering \
+                     prefix and has no concept of a residual to route to a change address"
+                        .to_string(),
+                ));
+            }
+        };
+
+        let outputs_with_change =
+            augment_outputs_with_change(user_outputs, change_addr, input_sum)?;
+
+        self.transfer(
+            account_index,
+            augmented_selection,
+            outputs_with_change,
+            fee_strategy,
+            platform_version,
+            address_signer,
+        )
+        .await
+    }
+
     /// Auto-select inputs balance-descending and dispatch to the
     /// fee-strategy-specific helper. The returned map's values are
     /// the **consumed amount per address** — the protocol enforces
@@ -879,6 +969,45 @@ fn checked_credits_add(
         })
 }
 
+/// Augment `user_outputs` with an explicit change output absorbing
+/// the surplus `Σ inputs − Σ user_outputs`.
+///
+/// Validates the three error cases that
+/// [`PlatformAddressWallet::transfer_with_change_address`] needs to
+/// reject before calling [`PlatformAddressWallet::transfer`]:
+/// 1. `change_addr` already declared as a user output (silent merge).
+/// 2. `Σ user_outputs ≥ Σ inputs` (no surplus to route).
+/// 3. arithmetic overflow on the difference (defensive — every
+///    realistic call sums far below `u64::MAX`).
+fn augment_outputs_with_change(
+    mut user_outputs: BTreeMap<PlatformAddress, Credits>,
+    change_addr: PlatformAddress,
+    input_sum: Credits,
+) -> Result<BTreeMap<PlatformAddress, Credits>, PlatformWalletError> {
+    if user_outputs.contains_key(&change_addr) {
+        return Err(PlatformWalletError::AddressOperation(format!(
+            "output_change_address {change_addr:?} already appears in user_outputs; \
+             the wrapper refuses to silently merge a change-output amount into a \
+             caller-declared output. Pick a fresh change_addr.",
+        )));
+    }
+    let user_output_sum: Credits = user_outputs.values().copied().sum();
+    if input_sum <= user_output_sum {
+        return Err(PlatformWalletError::AddressOperation(format!(
+            "output_change_address: Some(_) requires Σ inputs ({input_sum}) > \
+             Σ user_outputs ({user_output_sum}); no surplus to route as change. \
+             Drop output_change_address or grow the input map.",
+        )));
+    }
+    let change_amount = checked_credits_sub(
+        input_sum,
+        user_output_sum,
+        "augment_outputs_with_change: change_amount",
+    )?;
+    user_outputs.insert(change_addr, change_amount);
+    Ok(user_outputs)
+}
+
 /// Checked sub of two `Credits` values. Returns
 /// [`PlatformWalletError::ArithmeticOverflow`] when the subtraction
 /// would wrap. Mirrors [`checked_credits_add`] — defensive only.
@@ -1820,6 +1949,69 @@ mod auto_select_tests {
         }
     }
 
+    /// PA-001b: the change-address override must add exactly one
+    /// extra output absorbing `Σ inputs − Σ user_outputs`, leaving
+    /// `Σ inputs == Σ outputs` so the protocol's structural
+    /// invariant still holds.
+    #[test]
+    fn augment_outputs_with_change_adds_residual_output() {
+        let user_target = p2pkh(0x22);
+        let change_addr = p2pkh(0x33);
+        let user_outputs = outputs_for(user_target, 5_000_000);
+        let outputs =
+            augment_outputs_with_change(user_outputs, change_addr, 60_000_000).expect("augment");
+        assert_eq!(outputs.len(), 2);
+        assert_eq!(outputs.get(&user_target), Some(&5_000_000));
+        assert_eq!(
+            outputs.get(&change_addr),
+            Some(&55_000_000),
+            "change output must absorb exactly the surplus"
+        );
+        let output_sum: Credits = outputs.values().sum();
+        assert_eq!(
+            output_sum, 60_000_000,
+            "Σ outputs must equal input sum (Σ inputs == Σ outputs invariant)"
+        );
+    }
+
+    /// PA-001b: the override must reject a `change_addr` that
+    /// already appears in the caller's user outputs to prevent a
+    /// silent merge.
+    #[test]
+    fn augment_outputs_with_change_rejects_duplicate_address() {
+        let target = p2pkh(0x44);
+        let user_outputs = outputs_for(target, 5_000_000);
+        let err = augment_outputs_with_change(user_outputs, target, 60_000_000)
+            .expect_err("change_addr equal to user output must be rejected");
+        match err {
+            PlatformWalletError::AddressOperation(msg) => {
+                assert!(
+                    msg.contains("already appears in user_outputs"),
+                    "unexpected message: {msg}"
+                );
+            }
+            other => panic!("expected AddressOperation, got {other:?}"),
+        }
+    }
+
+    /// PA-001b: when `Σ user_outputs ≥ Σ inputs` there is no
+    /// surplus to route. The wrapper must reject rather than emit a
+    /// zero-credit (or underflowing) change output.
+    #[test]
+    fn augment_outputs_with_change_rejects_no_surplus() {
+        let target = p2pkh(0x55);
+        let change_addr = p2pkh(0x66);
+        let user_outputs = outputs_for(target, 60_000_000);
+        let err = augment_outputs_with_change(user_outputs, change_addr, 60_000_000)
+            .expect_err("equal sums must be rejected: nothing to route as change");
+        match err {
+            PlatformWalletError::AddressOperation(msg) => {
+                assert!(msg.contains("no surplus"), "unexpected message: {msg}");
+            }
+            other => panic!("expected AddressOperation, got {other:?}"),
+        }
+    }
+
     /// End-to-end structural validation: feed the selector's output
     /// to `AddressFundsTransferTransitionV0::validate_structure` to
     /// confirm the transition is shape-valid under