dashpay · Claudius-Maginificent · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026
@@ -36,6 +36,9 @@ bincode = { version = "=2.0.1" }
 # Hex used for error diagnostics that include a wallet_id.
 hex = "0.4"
 
+# `IndexMap` mirrors `platform-wallet`'s insertion-ordered outputs API.
+indexmap = "2.7"
+
 # Persistence loader emits structured warnings for skipped /
 # corrupt rows so operators can detect snapshot drift without a
 # native debugger attached.

@@ -76,6 +76,12 @@ pub enum PlatformWalletFFIResultCode {
     ErrorInvalidIdentifier = 10,
     ErrorMemoryAllocation = 11,
     ErrorUtf8Conversion = 12,
+    /// `PlatformWalletError::OnlyOutputAddressesFunded`: auto-selection
+    /// found that every funded address is also a destination output.
+    ErrorOnlyOutputAddressesFunded = 13,
+    /// `PlatformWalletError::OnlyDustInputs`: auto-selection found that
+    /// every funded address is below `min_input_amount`.
+    ErrorOnlyDustInputs = 14,
 
     NotFound = 98, // Used exclusively for all the Option that are retuned as errors
     ErrorUnknown = 99,
@@ -156,7 +162,16 @@ impl<T> From<Option<T>> for PlatformWalletFFIResult {
 
 impl From<PlatformWalletError> for PlatformWalletFFIResult {
     fn from(error: PlatformWalletError) -> Self {
-        PlatformWalletFFIResult::err(PlatformWalletFFIResultCode::ErrorUnknown, error.to_string())
+        let code = match &error {
+            PlatformWalletError::OnlyOutputAddressesFunded { .. } => {
+                PlatformWalletFFIResultCode::ErrorOnlyOutputAddressesFunded
+            }
+            PlatformWalletError::OnlyDustInputs { .. } => {
+                PlatformWalletFFIResultCode::ErrorOnlyDustInputs
+            }
+            _ => PlatformWalletFFIResultCode::ErrorUnknown,
+        };
+        PlatformWalletFFIResult::err(code, error.to_string())
     }
 }
 
@@ -368,6 +383,42 @@ mod tests {
         assert!(r.message.is_null());
     }
 
+    /// CMT-003: typed `PlatformWalletError` variants route to the
+    /// dedicated FFI codes, not the catch-all `ErrorUnknown`.
+    #[test]
+    fn typed_errors_route_to_dedicated_codes() {
+        use dpp::address_funds::PlatformAddress;
+        let cases: Vec<(PlatformWalletError, PlatformWalletFFIResultCode)> = vec![
+            (
+                PlatformWalletError::OnlyOutputAddressesFunded {
+                    funded_outputs: vec![PlatformAddress::P2pkh([0u8; 20])],
+                    sub_min_count: 0,
+                    sub_min_aggregate: 0,
+                    min_input_amount: 100_000,
+                },
+                PlatformWalletFFIResultCode::ErrorOnlyOutputAddressesFunded,
+            ),
+            (
+                PlatformWalletError::OnlyDustInputs {
+                    sub_min_count: 2,
+                    sub_min_aggregate: 12_345,
+                    min_input_amount: 100_000,
+                },
+                PlatformWalletFFIResultCode::ErrorOnlyDustInputs,
+            ),
+            (
+                PlatformWalletError::AddressOperation("plain string".to_string()),
+                PlatformWalletFFIResultCode::ErrorUnknown,
+            ),
+        ];
+
+        for (err, expected) in cases {
+            let result: PlatformWalletFFIResult = err.into();
+            assert_eq!(result.code, expected);
+            assert!(!result.message.is_null());
+        }
+    }
+
     #[test]
     fn nul_in_message_is_replaced() {
         let r = PlatformWalletFFIResult::err(

@@ -182,18 +182,23 @@ pub struct AddressBalanceEntryFFI {
     pub address_index: u32,
 }
 
-/// Parse output entries into a BTreeMap.
+/// Parse output entries into an insertion-ordered `IndexMap`.
+///
+/// Mirrors `platform-wallet`'s public-API output ordering (QA-002): the
+/// wallet preserves the caller's order for UI/debug while DPP still
+/// keys the transition by lex-smallest address. Use `IndexMap` here so
+/// the caller's array order survives the FFI boundary.
 ///
 /// # Safety
 /// `ptr` must point to `count` valid elements.
 pub unsafe fn parse_outputs(
     ptr: *const AddressBalanceEntryFFI,
     count: usize,
-) -> Result<BTreeMap<PlatformAddress, Credits>, &'static str> {
+) -> Result<indexmap::IndexMap<PlatformAddress, Credits>, &'static str> {
     if ptr.is_null() && count > 0 {
         return Err("Null output pointer with non-zero count");
     }
-    let mut map = BTreeMap::new();
+    let mut map = indexmap::IndexMap::new();
     if count > 0 {
         for entry in std::slice::from_raw_parts(ptr, count) {
             let addr = PlatformAddress::try_from(entry.address)?;

@@ -27,6 +27,11 @@ arc-swap = "1"
 
 # Collections
 bimap = "0.6"
+# `IndexMap` powers the insertion-ordered public outputs map on
+# `PlatformAddressWallet::transfer` / `transfer_with_change_address`.
+# Same crate that dpp and rs-sdk already vendor; pin a workspace-aligned
+# minor that satisfies all in-tree requirements.
+indexmap = "2.7"
 
 # Async runtime
 tokio = { version = "1", features = ["sync", "rt", "time", "macros"] }

@@ -129,8 +129,8 @@ async fn build_core_changeset(
             addresses_derived,
             ..
         } => {
-            // Derive UTXO deltas BEFORE moving the record into `records`
-            // so we still have the per-record borrows.
+            // Derive UTXO deltas before moving the record into `records`
+            // so the per-record borrows are still live.
             CoreChangeSet {
                 new_utxos: derive_new_utxos(record),
                 spent_utxos: derive_spent_utxos(record),
@@ -354,5 +354,6 @@ impl CoreChangeSet {
             && self.last_processed_height.is_none()
             && self.synced_height.is_none()
             && self.last_applied_chain_lock.is_none()
+            && self.addresses_derived.is_empty()
     }
 }
@@ -1,3 +1,5 @@
+use dpp::address_funds::PlatformAddress;
+use dpp::fee::Credits;
 use dpp::identifier::Identifier;
 use key_wallet::Network;
 
@@ -72,6 +74,58 @@ pub enum PlatformWalletError {
     #[error("Address operation failed: {0}")]
     AddressOperation(String),
 
+    #[error(
+        "no selectable inputs: only funded addresses appear as destinations \
+         (funded_outputs={funded_outputs:?}, sub_min_count={sub_min_count}, \
+         sub_min_aggregate={sub_min_aggregate}, min_input_amount={min_input_amount}); \
+         rotate to a fresh receive address, consolidate funds, or use \
+         InputSelection::Explicit"
+    )]
+    OnlyOutputAddressesFunded {
+        /// Funded addresses dropped by the input-equals-output filter.
+        funded_outputs: Vec<PlatformAddress>,
+        /// Number of additional addresses with a positive balance below
+        /// `min_input_amount`. Preserved even though the output-collision
+        /// signal is the typically-actionable fix, so a UI rotating to a
+        /// fresh receive address has the dust breadcrumb on the next try.
+        sub_min_count: usize,
+        /// Aggregate of the sub-minimum balances counted in `sub_min_count`.
+        sub_min_aggregate: Credits,
+        /// Per-input minimum from the active platform version.
+        min_input_amount: Credits,
+    },
+
+    #[error(
+        "no selectable inputs: every funded address is below the per-input \
+         minimum (sub_min_count={sub_min_count}, sub_min_aggregate={sub_min_aggregate} \
+         credits, min_input_amount={min_input_amount}); consolidate funds or use \
+         InputSelection::Explicit"
+    )]
+    OnlyDustInputs {
+        /// Number of addresses with a positive balance below `min_input_amount`.
+        sub_min_count: usize,
+        /// Aggregate of those sub-minimum balances.
+        sub_min_aggregate: Credits,
+        /// Per-input minimum from the active platform version.
+        min_input_amount: Credits,
+    },
+
+    #[error(
+        "change output amount {change_amount} is below the protocol per-output \
+         minimum {min_output_amount}; raise the input sum or drop the change \
+         address so the residual would exceed the minimum"
+    )]
+    ChangeBelowMinimumOutput {
+        /// `Σ inputs − Σ user_outputs` — the residual that would have been
+        /// routed to the change output.
+        change_amount: Credits,
+        /// Per-output minimum from the active platform version.
+        min_output_amount: Credits,
+    },
+
+    #[error("input sum overflow: caller-supplied input balances exceed u64::MAX")]
+    InputSumOverflow,
+
     #[error("Platform address not found in wallet: {0}")]
     AddressNotFound(String),
 

@@ -328,8 +328,6 @@ impl PlatformWalletInfo {
         drop(token_balances);
 
         // 7. Recompute cached UI balance from the now-restored UTXO set.
-        //    `update_balance` returns its own changeset internally; we
-        //    discard it (apply does not re-emit).
         use key_wallet::wallet::managed_wallet_info::wallet_info_interface::WalletInfoInterface;
         self.core_wallet.update_balance();
         // Mirror the recomputed balance into the lock-free Arc that the

@@ -6,13 +6,42 @@ use dpp::address_funds::PlatformAddress;
 use dpp::fee::Credits;
 pub use dpp::prelude::AddressNonce;
 
+#[cfg(doc)]
+use crate::PlatformWalletError;
+
 mod fund_from_asset_lock;
 pub(crate) mod provider;
 mod sync;
 mod transfer;
 mod wallet;
 mod withdrawal;
 
+/// Saturating sum over `Credits` (== `u64`) — total credit supply is far
+/// below `u64::MAX`, so saturation is unreachable in practice but the policy
+/// keeps debug-build panics off the table. Use this only for sums over
+/// wallet-derived balances; for caller-supplied input maps prefer
+/// [`checked_sum_credits`] so a bogus FFI input is reported as
+/// [`crate::PlatformWalletError::InputSumOverflow`] rather than silently
+/// saturating to `u64::MAX`.
+pub(crate) fn saturating_sum_credits<I>(iter: I) -> Credits
+where
+    I: IntoIterator<Item = Credits>,
+{
+    iter.into_iter().fold(0u64, Credits::saturating_add)
+}
+
+/// Checked sum over `Credits` for caller-supplied input maps. Returns
+/// [`crate::PlatformWalletError::InputSumOverflow`] on overflow so a
+/// bogus FFI caller cannot trigger a silent saturation downstream.
+pub(crate) fn checked_sum_credits<I>(iter: I) -> Result<Credits, crate::PlatformWalletError>
+where
+    I: IntoIterator<Item = Credits>,
+{
+    iter.into_iter()
+        .try_fold(0u64, |acc, c| acc.checked_add(c))
+        .ok_or(crate::PlatformWalletError::InputSumOverflow)
+}
+
 pub use provider::{
     PerAccountPlatformAddressState, PerWalletPlatformAddressState, PlatformAddressTag,
 };
@@ -24,8 +53,23 @@ pub enum InputSelection {
     Explicit(BTreeMap<PlatformAddress, Credits>),
     /// Explicit inputs with known nonces and balances.
     ExplicitWithNonces(BTreeMap<PlatformAddress, (AddressNonce, Credits)>),
-    /// Automatically select inputs from the account, consuming addresses
-    /// from lowest derivation index to highest until the required amount
-    /// plus estimated fees is covered.
+    /// Automatically select inputs from the account.
+    ///
+    /// Candidates are ordered balance-descending, filtered to balances
+    /// `≥ min_input_amount`, and addresses that also appear as outputs
+    /// are excluded (DPP rejects same-address input+output). Supported
+    /// fee strategies: `[DeductFromInput(0)]` (fee comes out of the
+    /// lex-smallest input's remaining balance) and `[ReduceOutput(0)]`
+    /// (fee absorbed at chain time from the lex-smallest output);
+    /// other shapes must use [`Self::Explicit`].
+    ///
+    /// # Errors
+    ///
+    /// Typed variants surface diagnosable failure shapes:
+    /// [`PlatformWalletError::OnlyOutputAddressesFunded`] when every
+    /// funded address is also a destination,
+    /// [`PlatformWalletError::OnlyDustInputs`] when every funded balance
+    /// is below `min_input_amount`, and the generic
+    /// [`PlatformWalletError::AddressOperation`] otherwise.
     Auto,
 }