From: Jeffrey Czyz Date: Fri, 3 Nov 2023 19:44:45 +0000 (-0500) Subject: Break ChannelManager docs into sections X-Git-Tag: v0.0.123-beta~15^2~8 X-Git-Url: http://git.bitcoin.ninja/?a=commitdiff_plain;h=9b60d7cf1d87094814893903ef187c3769542d66;p=rust-lightning Break ChannelManager docs into sections ChannelManager docs aren't very approachable as they consist of a large wall of texts without much direction. As a first step of improvement, add sections to help delineate the existing text and make it easier to scan. --- diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index bddcd4c9b..13210c377 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -1115,6 +1115,8 @@ where /// Implements [`ChannelMessageHandler`], handling the multi-channel parts and passing things through /// to individual Channels. /// +/// # Persistence +/// /// Implements [`Writeable`] to write out all channel state to disk. Implies [`peer_disconnected`] for /// all peers during write/read (though does not modify this instance, only the instance being /// serialized). This will result in any channels which have not yet exchanged [`funding_created`] (i.e., @@ -1134,12 +1136,16 @@ where /// tells you the last block hash which was connected. You should get the best block tip before using the manager. /// See [`chain::Listen`] and [`chain::Confirm`] for more details. /// +/// # `ChannelUpdate` Messages +/// /// Note that `ChannelManager` is responsible for tracking liveness of its channels and generating /// [`ChannelUpdate`] messages informing peers that the channel is temporarily disabled. To avoid /// spam due to quick disconnection/reconnection, updates are not sent until the channel has been /// offline for a full minute. In order to track this, you must call /// [`timer_tick_occurred`] roughly once per minute, though it doesn't have to be perfect. /// +/// # DoS Mitigation +/// /// To avoid trivial DoS issues, `ChannelManager` limits the number of inbound connections and /// inbound channels without confirmed funding transactions. This may result in nodes which we do /// not have a channel with being unable to connect to us or open new channels with us if we have @@ -1149,6 +1155,8 @@ where /// exempted from the count of unfunded channels. Similarly, outbound channels and connections are /// never limited. Please ensure you limit the count of such channels yourself. /// +/// # Type Aliases +/// /// Rather than using a plain `ChannelManager`, it is preferable to use either a [`SimpleArcChannelManager`] /// a [`SimpleRefChannelManager`], for conciseness. See their documentation for more details, but /// essentially you should default to using a [`SimpleRefChannelManager`], and use a