feat: coinjoin promotion / demotion

doc/release-notes-7052.md

@@ -0,0 +1,45 @@
+P2P and network changes
+-----------------------
+
+- The protocol version was bumped to 70241. The `dsa` message gained a
+  version-gated flags field declaring which mixing direction a
+  participant intends. A session commits to carrying promotion/demotion
+  entries only once a participant is admitted that actually declared one,
+  and it becomes closed to pre-70241 clients only from that point on;
+  conversely, a session that has already admitted a pre-70241 client
+  refuses later promotion/demotion participants. Either way the refusal
+  happens at acceptance time, before any collateral is committed, so a
+  client doing ordinary 1:1 mixing is never turned away from a session
+  simply because of who opened it. Unbalanced (promotion/demotion) DSTXes
+  are only announced as `dstx` to peers at protocol 70241 or newer, since
+  older peers would reject them as structurally invalid and penalize the
+  relayer; those peers are sent a plain `tx` announcement instead, so
+  they still receive the transaction without the mixing metadata they
+  cannot parse. (#7052)
+
+- A mixing session only completes once each side of its denomination is
+  occupied by nobody or by at least two participants, since coins are
+  only concealed by other coins of the same size on the same side. A
+  session that attracts a lone promotion or demotion participant and no
+  counterpart therefore waits, and expires in the queue stage without
+  charging anyone's collateral, rather than publishing a transaction that
+  would identify that participant's coins. Because admission relies on
+  the declared directions, a participant whose entry deviates from what
+  it declared has its collateral consumed. (#7052)
+
+Wallet
+------
+
+- CoinJoin can now promote and demote between adjacent standard
+  denominations within a mixing session after V24 activation.
+  Promotion combines 10 inputs of one denomination into 1 output of the
+  next larger denomination, while demotion splits 1 input into 10
+  outputs of the next smaller denomination. Pre-V24 behavior remains
+  unchanged. (#7052)
+
+- Conversions only spend fully-mixed coins, and their outputs start
+  mixing over from zero rounds. The 10:1 shape of a conversion publicly
+  clusters one participant's coins even inside a mixing transaction, so
+  a converted coin is not treated as mixed: it re-enters mixing at its
+  new denomination and disperses normally, while the histories of the
+  fully-mixed coins that fed the conversion remain protected. (#7052)

src/coinjoin/client.h

@@ -89,6 +89,11 @@ class CCoinJoinClientSession : public CCoinJoinBaseSession
 
     CKeyHolderStorage keyHolderStorage; // storage for keys used in PrepareDenominate
 
+    // Post-V24: Promotion/demotion session state
+    bool m_fPromotion{false};  // True if this session is promoting smaller -> larger denom
+    bool m_fDemotion{false};   // True if this session is demoting larger -> smaller denom
+    std::vector<COutPoint> m_vecRebalanceInputs;  // Selected inputs for promotion/demotion rebalancing
+
     /// Create denominations
     bool CreateDenominated(CAmount nBalanceToDenominate);
     bool CreateDenominated(CAmount nBalanceToDenominate, const wallet::CompactTallyItem& tallyItem, bool fCreateMixingCollaterals)
@@ -102,16 +107,35 @@ class CCoinJoinClientSession : public CCoinJoinBaseSession
     bool CreateCollateralTransaction(CMutableTransaction& txCollateral, std::string& strReason)
         EXCLUSIVE_LOCKS_REQUIRED(m_wallet->cs_wallet);
 
-    bool JoinExistingQueue(CAmount nBalanceNeedsAnonymized, CConnman& connman);
+    bool JoinExistingQueue(CAmount nBalanceNeedsAnonymized, CConnman& connman,
+                           int nTargetDenom = 0, bool fPromotion = false, bool fDemotion = false);
     bool StartNewQueue(CAmount nBalanceNeedsAnonymized, CConnman& connman);
+    bool StartNewQueue(CAmount nBalanceNeedsAnonymized, CConnman& connman,
+                       int nTargetDenom, bool fPromotion, bool fDemotion);
     CDeterministicMNCPtr GetRandomNotUsedMasternode();
 
+    /// Post-V24: select and lock inputs for a promotion/demotion session. Locked outpoints are
+    /// recorded in m_vecRebalanceInputs and vecOutPointLocked so UnlockCoins() releases them on
+    /// any failure path.
+    bool SelectRebalanceInputs(int nTargetDenom, bool fPromotion, std::vector<CTxDSIn>& vecTxDSInRet);
+    /// Post-V24: unlock and forget the inputs selected by SelectRebalanceInputs (session setup failed)
+    void UnlockRebalanceInputs();
+
     /// step 0: select denominated inputs and txouts
     bool SelectDenominate(std::string& strErrorRet, std::vector<CTxDSIn>& vecTxDSInRet);
     /// step 1: prepare denominated inputs and outputs
     bool PrepareDenominate(int nMinRounds, int nMaxRounds, std::string& strErrorRet, const std::vector<CTxDSIn>& vecTxDSIn,
                            std::vector<std::pair<CTxDSIn, CTxOut>>& vecPSInOutPairsRet, bool fDryRun = false)
         EXCLUSIVE_LOCKS_REQUIRED(m_wallet->cs_wallet);
+
+    /// Post-V24: prepare promotion entry (10 inputs of smaller denom -> 1 output of larger denom)
+    bool PreparePromotionEntry(std::string& strErrorRet, std::vector<std::pair<CTxDSIn, CTxOut>>& vecPSInOutPairsRet)
+        EXCLUSIVE_LOCKS_REQUIRED(m_wallet->cs_wallet);
+
+    /// Post-V24: prepare demotion entry (1 input of larger denom -> 10 outputs of smaller denom)
+    bool PrepareDemotionEntry(std::string& strErrorRet, std::vector<std::pair<CTxDSIn, CTxOut>>& vecPSInOutPairsRet)
+        EXCLUSIVE_LOCKS_REQUIRED(m_wallet->cs_wallet);
+
     /// step 2: send denominated inputs and outputs prepared in step 1
     bool SendDenominate(const std::vector<std::pair<CTxDSIn, CTxOut> >& vecPSInOutPairsIn, CConnman& connman) EXCLUSIVE_LOCKS_REQUIRED(!cs_coinjoin);
 
@@ -226,7 +250,7 @@ class CCoinJoinClientManager : public interfaces::CoinJoin::Client
 
     bool TrySubmitDenominate(const uint256& proTxHash, CConnman& connman) EXCLUSIVE_LOCKS_REQUIRED(!cs_deqsessions);
     bool MarkAlreadyJoinedQueueAsTried(CCoinJoinQueue& dsq) const EXCLUSIVE_LOCKS_REQUIRED(!cs_deqsessions);
-    bool GetQueueItemAndTry(CCoinJoinQueue& dsq) const;
+    bool GetQueueItemAndTry(CCoinJoinQueue& dsq, int nDenomFilter = 0) const;
 
     void CheckTimeout() EXCLUSIVE_LOCKS_REQUIRED(!cs_deqsessions);
 
@@ -256,6 +280,24 @@ class CCoinJoinClientManager : public interfaces::CoinJoin::Client
     bool isMixing() const override;
     bool startMixing() override;
     void stopMixing() override;
+
+    /**
+     * Post-V24: Check if we should promote smaller denominations into larger ones
+     * @param nSmallerDenom The smaller denomination to promote from
+     * @param nLargerDenom The larger denomination to promote into
+     * @param counts Wallet denomination counts, e.g. from CWallet::GetDenominationCounts()
+     * @return true if promotion is recommended
+     */
+    static bool ShouldPromote(int nSmallerDenom, int nLargerDenom, const wallet::CoinJoinDenomCounts& counts);
+
+    /**
+     * Post-V24: Check if we should demote larger denominations into smaller ones
+     * @param nLargerDenom The larger denomination to demote from
+     * @param nSmallerDenom The smaller denomination to demote into
+     * @param counts Wallet denomination counts, e.g. from CWallet::GetDenominationCounts()
+     * @return true if demotion is recommended
+     */
+    static bool ShouldDemote(int nLargerDenom, int nSmallerDenom, const wallet::CoinJoinDenomCounts& counts);
 };
 
 #endif // BITCOIN_COINJOIN_CLIENT_H