diff --git a/lightning-invoice/src/lib.rs b/lightning-invoice/src/lib.rs index 4737173eef5..c01dfa47ba0 100644 --- a/lightning-invoice/src/lib.rs +++ b/lightning-invoice/src/lib.rs @@ -297,7 +297,7 @@ pub struct RawInvoice { /// Data of the `RawInvoice` that is encoded in the human readable part /// -/// (C-not exported) As we don't yet support Option +/// (C-not exported) As we don't yet support `Option` #[derive(Eq, PartialEq, Debug, Clone, Hash)] pub struct RawHrp { /// The currency deferred from the 3rd and 4th character of the bech32 transaction @@ -806,6 +806,7 @@ impl SignedRawInvoice { /// /// The following example would extract the first B. /// +/// ```ignore /// enum Enum { /// A(u8), /// B(u16) @@ -814,6 +815,7 @@ impl SignedRawInvoice { /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)]; /// /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16)); +/// ``` macro_rules! find_extract { ($iter:expr, $enm:pat, $enm_var:ident) => { find_all_extract!($iter, $enm, $enm_var).next() @@ -825,6 +827,7 @@ macro_rules! find_extract { /// /// The following example would extract all A. /// +/// ```ignore /// enum Enum { /// A(u8), /// B(u16) @@ -836,6 +839,7 @@ macro_rules! find_extract { /// find_all_extract!(elements.iter(), Enum::A(x), x).collect::>(), /// vec![1u8, 2u8, 4u8] /// ); +/// ``` macro_rules! find_all_extract { ($iter:expr, $enm:pat, $enm_var:ident) => { $iter.filter_map(|tf| match *tf { @@ -1276,7 +1280,7 @@ impl Invoice { self.signed_invoice.amount_pico_btc().map(|v| v / 10) } - /// Returns the amount if specified in the invoice as pico . + /// Returns the amount if specified in the invoice as pico BTC. fn amount_pico_btc(&self) -> Option { self.signed_invoice.amount_pico_btc() } diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs index 76dc15065c0..448fcd7fe31 100644 --- a/lightning/src/ln/channel.rs +++ b/lightning/src/ln/channel.rs @@ -798,7 +798,7 @@ pub const MAX_CHAN_DUST_LIMIT_SATOSHIS: u64 = MAX_STD_OUTPUT_DUST_LIMIT_SATOSHIS /// In order to avoid having to concern ourselves with standardness during the closing process, we /// simply require our counterparty to use a dust limit which will leave any segwit output /// standard. -/// See https://github.com/lightning/bolts/issues/905 for more details. +/// See for more details. pub const MIN_CHAN_DUST_LIMIT_SATOSHIS: u64 = 354; // Just a reasonable implementation-specific safe lower bound, higher than the dust limit. diff --git a/lightning/src/ln/msgs.rs b/lightning/src/ln/msgs.rs index 399feaf6769..278352845ac 100644 --- a/lightning/src/ln/msgs.rs +++ b/lightning/src/ln/msgs.rs @@ -12,12 +12,12 @@ //! For a normal node you probably don't need to use anything here, however, if you wish to split a //! node into an internet-facing route/message socket handling daemon and a separate daemon (or //! server entirely) which handles only channel-related messages you may wish to implement -//! ChannelMessageHandler yourself and use it to re-serialize messages and pass them across +//! [`ChannelMessageHandler`] yourself and use it to re-serialize messages and pass them across //! daemons/servers. //! //! Note that if you go with such an architecture (instead of passing raw socket events to a //! non-internet-facing system) you trust the frontend internet-facing system to not lie about the -//! source node_id of the message, however this does allow you to significantly reduce bandwidth +//! source `node_id` of the message, however this does allow you to significantly reduce bandwidth //! between the systems as routing messages can represent a significant chunk of bandwidth usage //! (especially for non-channel-publicly-announcing nodes). As an alternate design which avoids //! this issue, if you have sufficient bidirectional bandwidth between your systems, you may send @@ -53,37 +53,46 @@ pub(crate) const MAX_VALUE_MSAT: u64 = 21_000_000_0000_0000_000; #[derive(Clone, Debug, PartialEq, Eq)] pub enum DecodeError { /// A version byte specified something we don't know how to handle. - /// Includes unknown realm byte in an OnionHopData packet + /// + /// Includes unknown realm byte in an onion hop data packet. UnknownVersion, - /// Unknown feature mandating we fail to parse message (eg TLV with an even, unknown type) + /// Unknown feature mandating we fail to parse message (e.g., TLV with an even, unknown type) UnknownRequiredFeature, - /// Value was invalid, eg a byte which was supposed to be a bool was something other than a 0 + /// Value was invalid. + /// + /// For example, a byte which was supposed to be a bool was something other than a 0 /// or 1, a public key/private key/signature was invalid, text wasn't UTF-8, TLV was - /// syntactically incorrect, etc + /// syntactically incorrect, etc. InvalidValue, - /// Buffer too short + /// The buffer to be read was too short. ShortRead, - /// A length descriptor in the packet didn't describe the later data correctly + /// A length descriptor in the packet didn't describe the later data correctly. BadLengthDescriptor, - /// Error from std::io + /// Error from [`std::io`]. Io(io::ErrorKind), /// The message included zlib-compressed values, which we don't support. UnsupportedCompression, } -/// An init message to be sent or received from a peer +/// An [`init`] message to be sent to or received from a peer. +/// +/// [`init`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-init-message #[derive(Clone, Debug, PartialEq, Eq)] pub struct Init { - /// The relevant features which the sender supports + /// The relevant features which the sender supports. pub features: InitFeatures, - /// The receipient's network address. This adds the option to report a remote IP address - /// back to a connecting peer using the init message. A node can decide to use that information - /// to discover a potential update to its public IPv4 address (NAT) and use - /// that for a node_announcement update message containing the new address. + /// The receipient's network address. + /// + /// This adds the option to report a remote IP address back to a connecting peer using the init + /// message. A node can decide to use that information to discover a potential update to its + /// public IPv4 address (NAT) and use that for a [`NodeAnnouncement`] update message containing + /// the new address. pub remote_network_address: Option, } -/// An error message to be sent or received from a peer +/// An [`error`] message to be sent to or received from a peer. +/// +/// [`error`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-error-and-warning-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct ErrorMessage { /// The channel ID involved in the error. @@ -92,13 +101,16 @@ pub struct ErrorMessage { /// with the sending peer should be closed. pub channel_id: [u8; 32], /// A possibly human-readable error description. - /// The string should be sanitized before it is used (e.g. emitted to logs or printed to - /// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in + /// + /// The string should be sanitized before it is used (e.g., emitted to logs or printed to + /// `stdout`). Otherwise, a well crafted error message may trigger a security vulnerability in /// the terminal emulator or the logging subsystem. pub data: String, } -/// A warning message to be sent or received from a peer +/// A [`warning`] message to be sent to or received from a peer. +/// +/// [`warning`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-error-and-warning-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct WarningMessage { /// The channel ID involved in the warning. @@ -106,31 +118,40 @@ pub struct WarningMessage { /// All-0s indicates a warning unrelated to a specific channel. pub channel_id: [u8; 32], /// A possibly human-readable warning description. + /// /// The string should be sanitized before it is used (e.g. emitted to logs or printed to /// stdout). Otherwise, a well crafted error message may trigger a security vulnerability in /// the terminal emulator or the logging subsystem. pub data: String, } -/// A ping message to be sent or received from a peer +/// A [`ping`] message to be sent to or received from a peer. +/// +/// [`ping`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-ping-and-pong-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct Ping { - /// The desired response length + /// The desired response length. pub ponglen: u16, /// The ping packet size. + /// /// This field is not sent on the wire. byteslen zeros are sent. pub byteslen: u16, } -/// A pong message to be sent or received from a peer +/// A [`pong`] message to be sent to or received from a peer. +/// +/// [`pong`]: https://github.com/lightning/bolts/blob/master/01-messaging.md#the-ping-and-pong-messages #[derive(Clone, Debug, PartialEq, Eq)] pub struct Pong { /// The pong packet size. + /// /// This field is not sent on the wire. byteslen zeros are sent. pub byteslen: u16, } -/// An open_channel message to be sent or received from a peer +/// An [`open_channel`] message to be sent to or received from a peer. +/// +/// [`open_channel`]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#the-open_channel-message #[derive(Clone, Debug, PartialEq, Eq)] pub struct OpenChannel { /// The genesis hash of the blockchain where the channel is to be opened @@ -149,9 +170,11 @@ pub struct OpenChannel { pub channel_reserve_satoshis: u64, /// The minimum HTLC size incoming to sender, in milli-satoshi pub htlc_minimum_msat: u64, - /// The feerate per 1000-weight of sender generated transactions, until updated by update_fee + /// The feerate per 1000-weight of sender generated transactions, until updated by + /// [`UpdateFee`] pub feerate_per_kw: u32, - /// The number of blocks which the counterparty will have to wait to claim on-chain funds if they broadcast a commitment transaction + /// The number of blocks which the counterparty will have to wait to claim on-chain funds if + /// they broadcast a commitment transaction pub to_self_delay: u16, /// The maximum number of inbound HTLCs towards sender pub max_accepted_htlcs: u16, @@ -167,17 +190,20 @@ pub struct OpenChannel { pub htlc_basepoint: PublicKey, /// The first to-be-broadcast-by-sender transaction's per commitment point pub first_per_commitment_point: PublicKey, - /// Channel flags + /// The channel flags to be used pub channel_flags: u8, - /// Optionally, a request to pre-set the to-sender output's scriptPubkey for when we collaboratively close + /// Optionally, a request to pre-set the to-sender output's `scriptPubkey` for when we collaboratively close pub shutdown_scriptpubkey: OptionalField