f Document new locking requirements on claimable payments

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -805,13 +805,20 @@ pub struct ChannelManager<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 	/// Note that, no consistency guarantees are made about the channels given here actually
 	/// existing anymore by the time you go to read them!
 	///
+	/// When adding to the map, [`pending_claimed_payments`] must also be checked (under the same
+	/// lock) to ensure we don't get a duplicate payment.
+	///
 	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	claimable_htlcs: Mutex<HashMap<PaymentHash, (events::PaymentPurpose, Vec<ClaimableHTLC>)>>,
 
 	/// Map from payment hash to the payment data for HTLCs which we have begun claiming, but which
 	/// are waiting on a [`ChannelMonitorUpdate`] to complete in order to be surfaced to the user
 	/// as an [`events::Event::PaymentClaimed`].
 	///
+	/// When adding to this map (by moving an entry from [`claimable_htlcs`]), the
+	/// [`claimable_htlcs`] lock should also be held to ensure we don't end up with a duplicate
+	/// payment by racing a [`claimable_htlcs`] addition.
+	///
 	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	pending_claimed_payments: Mutex<HashMap<PaymentHash, PendingClaimingPayment>>,