docs(kotlin-sdk): a drain's scope is the account type, which defaults to pooled

`SelectionStrategy.ALL` was documented as "drains the account" -- written
when a drain could only mean one account. Since #4329 the send APIs default
`accountType` to `ALL_SPENDABLE`, so `ALL` on a call that does not name an
account type drains BIP44 AND BIP32 AND every DashPay contact-receiving
account in one transaction, change returning to BIP44.

That is the intended shape rather than a hazard: "send everything" means
everything the wallet can sign for, and achieving it before the pooled
selector meant sweeping accounts together on-chain first. Document it on
the strategy enum and again on `buildSignedPayment`, where the two
parameters meet and where the scope is inherited rather than typed, so a
reader can see what a defaulted drain reaches. Naming a single account type
is for drains genuinely scoped to one family -- a CoinJoin sweep that must
not leave its privacy domain.

A test pins the sweep scope per selector, so anything later added to
SEND_FUNDING_SOURCES -- which would enlarge every defaulted drain -- fails
there first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: HashEngineering

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/CoreTransactionBuilder.kt

@@ -48,7 +48,31 @@ class CoreTransactionBuilder internal constructor(network: Network) : AutoClosea
 
     /**
      * Coin-selection strategy — mirror of key-wallet's `SelectionStrategy`
-     * (`CoreSelectionStrategyFFI`). [ALL] drains the account.
+     * (`CoreSelectionStrategyFFI`).
+     *
+     * [ALL] drains — it selects every spendable UTXO the chosen funding
+     * source offers, sets the single destination output to
+     * `total inputs − fee`, and leaves no change. **Its scope is whatever
+     * [AccountType] names, not "the wallet's main account":**
+     *
+     * - [AccountType.BIP44] / [AccountType.BIP32] / [AccountType.COIN_JOIN]
+     *   drain that one account family;
+     * - [AccountType.ALL_SPENDABLE] — **the default** — drains BIP44 **and**
+     *   BIP32 **and** every DashPay contact-receiving account, in one
+     *   transaction.
+     *
+     * So `selectionStrategy = ALL` on a call that does not name an
+     * [AccountType] sweeps the wallet's whole spendable balance, contact
+     * receiving accounts included. That is the intended shape of a drain: a
+     * host asking to send everything means everything it can sign for, and
+     * before the pooled selector existed a host had to sweep accounts
+     * together on-chain first to achieve it. Name a single [AccountType] only
+     * when the drain is genuinely scoped to one family — a CoinJoin sweep,
+     * say, which must stay in its own privacy domain.
+     *
+     * Read what a drain actually pays from
+     * [SignedCoreTransaction.deliverableAmountDuffs]; the engine computes it,
+     * and the caller's requested amount is discarded.
      */
     enum class SelectionStrategy(val ffiValue: Int) {
         SMALLEST_FIRST(0),

packages/kotlin-sdk/sdk/src/main/kotlin/org/dashfoundation/dashsdk/wallet/ManagedPlatformWallet.kt

@@ -384,6 +384,17 @@ class ManagedPlatformWallet internal constructor(
      *   [SignedCoreTransaction.deliverableAmountDuffs] BEFORE broadcasting —
      *   that is the only way to learn the engine-computed amount, and it is
      *   what a swap quote must be taken from.
+     *
+     *   **A drain's scope is [accountType], which defaults to
+     *   [CoreTransactionBuilder.AccountType.ALL_SPENDABLE].** Combined with
+     *   `ALL`, a call that does not name an account type sweeps BIP44, BIP32
+     *   AND every DashPay contact-receiving account into one transaction,
+     *   change returning to BIP44. That is the intended shape: "send
+     *   everything" means everything the wallet can sign for, which before
+     *   the pooled selector required sweeping accounts together on-chain
+     *   first. Name a single [CoreTransactionBuilder.AccountType] only for a
+     *   drain genuinely scoped to one family, such as a CoinJoin sweep that
+     *   must not leave its privacy domain.
      */
     suspend fun buildSignedPayment(
         recipients: List<Pair<String, Long>>,

packages/rs-platform-wallet-ffi/src/core_wallet/transaction_builder.rs

@@ -923,9 +923,43 @@ pub unsafe extern "C" fn core_wallet_transaction_free(tx: *mut FFICoreTransactio
 
 #[cfg(test)]
 mod tests {
-    use super::sole_deliverable_value;
+    use super::{sole_deliverable_value, CoreAccountTypeFFI};
     use dashcore::blockdata::script::ScriptBuf;
     use dashcore::TxOut;
+    use key_wallet::wallet::managed_wallet_info::transaction_building::AccountTypePreference;
+
+    /// What a DRAIN spans, per selector. `SelectionStrategy::All` takes every
+    /// UTXO each named source offers, so this list IS the sweep scope — the
+    /// claim the Kotlin `SelectionStrategy.ALL` doc makes to callers.
+    ///
+    /// The pooled selector is the DEFAULT for a send, so a caller who asks for
+    /// a drain without naming an account type sweeps all three families at
+    /// once, contact-receiving funds included. Pinned here so that widening
+    /// cannot happen silently: anything added to `SEND_FUNDING_SOURCES`
+    /// enlarges every defaulted drain, and this test is where that shows up.
+    #[test]
+    fn a_drains_scope_is_whatever_the_selector_names() {
+        assert_eq!(
+            CoreAccountTypeFFI::BIP44.funding_sources(),
+            &[AccountTypePreference::BIP44],
+            "a single-family selector drains exactly one account"
+        );
+        assert_eq!(
+            CoreAccountTypeFFI::CoinJoin.funding_sources(),
+            &[AccountTypePreference::CoinJoin],
+            "CoinJoin stays its own privacy domain, never pooled"
+        );
+        assert_eq!(
+            CoreAccountTypeFFI::AllSpendable.funding_sources(),
+            &[
+                AccountTypePreference::BIP44,
+                AccountTypePreference::BIP32,
+                AccountTypePreference::AllDashpayReceivingFunds,
+            ],
+            "the DEFAULT selector drains BIP44 + BIP32 + every DashPay \
+             receiving account; BIP44 must stay first, as it supplies change"
+        );
+    }
 
     /// A spendable output. The script only has to NOT be an OP_RETURN.
     fn destination(value: u64) -> TxOut {