- /// Returns short_channel_id if known.
- /// For `FirstHop` we assume [`ChannelDetails::get_outbound_payment_scid`] is always set, this assumption is checked in
- /// [`find_route`] method.
- /// For `Blinded` and `OneHopBlinded` we return `None` because next hop is not known.
- pub fn short_channel_id(&self) -> Option<u64> {
+ /// Returns the short channel ID for this hop, if one is known.
+ ///
+ /// This SCID could be an alias or a globally unique SCID, and thus is only expected to
+ /// uniquely identify this channel in conjunction with the [`CandidateRouteHop::source`].
+ ///
+ /// Returns `Some` as long as the candidate is a [`CandidateRouteHop::PublicHop`], a
+ /// [`CandidateRouteHop::PrivateHop`] from a BOLT 11 route hint, or a
+ /// [`CandidateRouteHop::FirstHop`] with a known [`ChannelDetails::get_outbound_payment_scid`]
+ /// (which is always true for channels which are funded and ready for use).
+ ///
+ /// In other words, this should always return `Some` as long as the candidate hop is not a
+ /// [`CandidateRouteHop::Blinded`] or a [`CandidateRouteHop::OneHopBlinded`].
+ ///
+ /// Note that this is deliberately not public as it is somewhat of a footgun because it doesn't
+ /// define a global namespace.
+ #[inline]
+ fn short_channel_id(&self) -> Option<u64> {