f doc preimages better

Author: TheBlueMatt

lightning/src/chain/channelmonitor.rs

@@ -923,7 +923,15 @@ pub(crate) struct ChannelMonitorImpl<Signer: EcdsaChannelSigner> {
 	/// The set of payment hashes from inbound payments for which we know the preimage. Payment
 	/// preimages that are not included in any unrevoked local commitment transaction or unrevoked
 	/// remote commitment transactions are automatically removed when commitment transactions are
-	/// revoked.
+	/// revoked. Note that this happens one revocation after it theoretically could, leaving
+	/// preimages present here for the previous state even when the channel is "at rest". This is a
+	/// good safety buffer, but also is important as it ensures we retain payment preimages for the
+	/// previous local commitment transaction, which may have been broadcast already when we see
+	/// the revocation (in setups with redundant monitors).
+	///
+	/// We also store [`PaymentClaimDetails`] here, tracking the payment information(s) for this
+	/// preimage for inbound payments. This allows us to rebuild the inbound payment information on
+	/// startup even if we lost our `ChannelManager`.
 	payment_preimages: HashMap<PaymentHash, (PaymentPreimage, Vec<PaymentClaimDetails>)>,
 
 	// Note that `MonitorEvent`s MUST NOT be generated during update processing, only generated