- /// For a new or already known (from previous announcement) channel, store or update channel info.
- /// Also store nodes (if not stored yet) the channel is between, and make node aware of this channel.
- /// Checking utxo on-chain is useful if we receive an update for already known channel id,
- /// which is probably result of a reorg. In that case, we update channel info only if the
- /// utxo was checked, otherwise stick to the existing update, to prevent DoS risks.
+ /// Store or update channel info from a channel announcement.
+ ///
+ /// You probably don't want to call this directly, instead relying on a NetGraphMsgHandler's
+ /// RoutingMessageHandler implementation to call it indirectly. This may be useful to accept
+ /// routing messages without checking their signatures.
+ ///
+ /// If the channel has been confirmed to exist on chain (with correctly-formatted scripts on
+ /// chain), set utxo_value to the value of the output on chain, otherwise leave it as None.
+ /// The UTXO value is then used in routing calculation if we have no better information on the
+ /// maximum HTLC value that can be sent over the channel.
+ ///
+ /// Further, setting utxo_value to Some indicates that the announcement message is genuine,
+ /// allowing us to update existing channel data in the case of reorgs or to replace bogus
+ /// channel data generated by a DoS attacker.
+ ///