Document lightning crate features.

Author: Mateusz Faltyn

lightning-invoice/src/lib.rs

@@ -11,7 +11,7 @@
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
 
 //! This crate provides data structures to represent
-//! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)
+//! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
 //! invoices and functions to create, encode and decode these. If you just want to use the standard
 //! en-/decoding functionality this should get you started:
 //!

lightning/src/chain/mod.rs

@@ -76,7 +76,7 @@ pub trait Access {
 	/// Returns an error if `genesis_hash` is for a different chain or if such a transaction output
 	/// is unknown.
 	///
-	/// [`short_channel_id`]: https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#definition-of-short_channel_id
+	/// [`short_channel_id`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#definition-of-short_channel_id
 	fn get_utxo(&self, genesis_hash: &BlockHash, short_channel_id: u64) -> Result<TxOut, AccessError>;
 }
 

lightning/src/lib.rs

@@ -17,6 +17,25 @@
 //! figure out how best to make networking happen/timers fire/things get written to disk/keys get
 //! generated/etc. This makes it a good candidate for tight integration into an existing wallet
 //! instead of having a rather-separate lightning appendage to a wallet.
+//!
+//! `default` features are:
+//!
+//! * `std` - enables functionalities which require `std`, including `std::io` trait implementations and things which utilize time
+//! * `grind_signatures` - enables generation of [low-r bitcoin signatures](https://bitcoin.stackexchange.com/questions/111660/what-is-signature-grinding),
+//! which saves 1 byte per signature in 50% of the cases (see [bitcoin PR #13666](https://github.com/bitcoin/bitcoin/pull/13666))
+//!
+//! Available features are:
+//!
+//! * `std`
+//! * `grind_signatures`
+//! * `no-std ` - exposes write trait implementations from the `core2` crate (at least one of `no-std` or `std` are required)
+//! * Skip logging of messages at levels below the given log level:
+//!     * `max_level_off`
+//!     * `max_level_error`
+//!     * `max_level_warn`
+//!     * `max_level_info`
+//!     * `max_level_debug`
+//!     * `max_level_trace`
 
 #![cfg_attr(not(any(test, fuzzing, feature = "_test_utils")), deny(missing_docs))]
 #![cfg_attr(not(any(test, fuzzing, feature = "_test_utils")), forbid(unsafe_code))]

lightning/src/ln/chan_utils.rs

@@ -139,7 +139,7 @@ pub fn build_closing_transaction(to_holder_value_sat: u64, to_counterparty_value
 }
 
 /// Implements the per-commitment secret storage scheme from
-/// [BOLT 3](https://github.com/lightningnetwork/lightning-rfc/blob/dcbf8583976df087c79c3ce0b535311212e6812d/03-transactions.md#efficient-per-commitment-secret-storage).
+/// [BOLT 3](https://github.com/lightning/bolts/blob/dcbf8583976df087c79c3ce0b535311212e6812d/03-transactions.md#efficient-per-commitment-secret-storage).
 ///
 /// Allows us to keep track of all of the revocation secrets of our counterparty in just 50*32 bytes
 /// or so.

lightning/src/ln/channel.rs

@@ -126,7 +126,7 @@ enum InboundHTLCState {
 	/// signatures in a commitment_signed message.
 	/// Implies AwaitingRemoteRevoke.
 	///
-	/// [BOLT #2]: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md
+	/// [BOLT #2]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md
 	AwaitingRemoteRevokeToAnnounce(PendingHTLCStatus),
 	/// Included in a received commitment_signed message (implying we've revoke_and_ack'd it).
 	/// We have also included this HTLC in our latest commitment_signed and are now just waiting
@@ -775,7 +775,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/lightningnetwork/lightning-rfc/issues/905 for more details.
+/// See https://github.com/lightning/bolts/issues/905 for more details.
 pub const MIN_CHAN_DUST_LIMIT_SATOSHIS: u64 = 354;
 
 /// Used to return a simple Error back to ChannelManager. Will get converted to a

lightning/src/ln/channelmanager.rs

@@ -2258,7 +2258,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 							msg.cltv_expiry.write(&mut res).expect("Writes cannot fail");
 						}
 						else if code == 0x1000 | 20 {
-							// TODO: underspecified, follow https://github.com/lightningnetwork/lightning-rfc/issues/791
+							// TODO: underspecified, follow https://github.com/lightning/bolts/issues/791
 							0u16.write(&mut res).expect("Writes cannot fail");
 						}
 						(chan_update.serialized_length() as u16 + 2).write(&mut res).expect("Writes cannot fail");

lightning/src/ln/features.rs

@@ -19,7 +19,7 @@
 //! supports a feature if it advertises the feature (as either required or optional) to its peers.
 //! And the implementation can interpret a feature if the feature is known to it.
 //!
-//! [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md
+//! [BOLT #9]: https://github.com/lightning/bolts/blob/master/09-features.md
 //! [messages]: crate::ln::msgs
 
 use {io, io_extras};
@@ -244,7 +244,7 @@ mod sealed {
 			///
 			/// See [BOLT #9] for details.
 			///
-			/// [BOLT #9]: https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md
+			/// [BOLT #9]: https://github.com/lightning/bolts/blob/master/09-features.md
 			pub trait $feature: Context {
 				/// The bit used to signify that the feature is required.
 				const EVEN_BIT: usize = $odd_bit - 1;

lightning/src/ln/peer_channel_encryptor.rs

@@ -25,8 +25,8 @@ use util::crypto::hkdf_extract_expand_twice;
 use bitcoin::hashes::hex::ToHex;
 
 /// Maximum Lightning message data length according to
-/// [BOLT-8](https://github.com/lightningnetwork/lightning-rfc/blob/v1.0/08-transport.md#lightning-message-specification)
-/// and [BOLT-1](https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md#lightning-message-format):
+/// [BOLT-8](https://github.com/lightning/bolts/blob/v1.0/08-transport.md#lightning-message-specification)
+/// and [BOLT-1](https://github.com/lightning/bolts/blob/master/01-messaging.md#lightning-message-format):
 pub const LN_MAX_MSG_LEN: usize = ::core::u16::MAX as usize; // Must be equal to 65535
 
 // Sha256("Noise_XK_secp256k1_ChaChaPoly_SHA256")

lightning/src/ln/script.rs

@@ -16,7 +16,7 @@ use io;
 
 /// A script pubkey for shutting down a channel as defined by [BOLT #2].
 ///
-/// [BOLT #2]: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md
+/// [BOLT #2]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md
 #[derive(Clone, PartialEq)]
 pub struct ShutdownScript(ShutdownScriptImpl);
 
@@ -25,7 +25,7 @@ pub struct ShutdownScript(ShutdownScriptImpl);
 pub struct InvalidShutdownScript {
 	/// The script that did not meet the requirements from [BOLT #2].
 	///
-	/// [BOLT #2]: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md
+	/// [BOLT #2]: https://github.com/lightning/bolts/blob/master/02-peer-protocol.md
 	pub script: Script
 }
 

lightning/src/ln/wire.rs

@@ -10,7 +10,7 @@
 //! Wire encoding/decoding for Lightning messages according to [BOLT #1], and for
 //! custom message through the [`CustomMessageReader`] trait.
 //! 
-//! [BOLT #1]: https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md
+//! [BOLT #1]: https://github.com/lightning/bolts/blob/master/01-messaging.md
 
 use io;
 use ln::msgs;

lightning/src/routing/network_graph.rs

@@ -150,7 +150,7 @@ pub struct ReadOnlyNetworkGraph<'a> {
 /// Update to the [`NetworkGraph`] based on payment failure information conveyed via the Onion
 /// return packet by a node along the route. See [BOLT #4] for details.
 ///
-/// [BOLT #4]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md
+/// [BOLT #4]: https://github.com/lightning/bolts/blob/master/04-onion-routing.md
 #[derive(Clone, Debug, PartialEq)]
 pub enum NetworkUpdate {
 	/// An error indicating a `channel_update` messages should be applied via

lightning/src/routing/scoring.rs

@@ -903,6 +903,14 @@ impl<G: Deref<Target = NetworkGraph>, L: Deref, T: Time> Score for Probabilistic
 	fn channel_penalty_msat(
 		&self, short_channel_id: u64, source: &NodeId, target: &NodeId, usage: ChannelUsage
 	) -> u64 {
+		if let EffectiveCapacity::ExactLiquidity { liquidity_msat } = usage.effective_capacity {
+			if usage.amount_msat > liquidity_msat {
+				return u64::max_value();
+			} else {
+				return self.params.base_penalty_msat;
+			};
+		}
+
 		let liquidity_offset_half_life = self.params.liquidity_offset_half_life;
 		let amount_msat = usage.amount_msat;
 		let capacity_msat = usage.effective_capacity.as_msat()
@@ -2574,4 +2582,28 @@ mod tests {
 		let usage = ChannelUsage { inflight_htlc_msat: 251, ..usage };
 		assert_eq!(scorer.channel_penalty_msat(42, &source, &target, usage), u64::max_value());
 	}
+
+	#[test]
+	fn removes_uncertainity_when_exact_liquidity_known() {
+		let network_graph = network_graph();
+		let logger = TestLogger::new();
+		let params = ProbabilisticScoringParameters::default();
+		let scorer = ProbabilisticScorer::new(params, &network_graph, &logger);
+		let source = source_node_id();
+		let target = target_node_id();
+
+		let base_penalty_msat = params.base_penalty_msat;
+		let usage = ChannelUsage {
+			amount_msat: 750,
+			inflight_htlc_msat: 0,
+			effective_capacity: EffectiveCapacity::ExactLiquidity { liquidity_msat: 1_000 },
+		};
+		assert_eq!(scorer.channel_penalty_msat(42, &source, &target, usage), base_penalty_msat);
+
+		let usage = ChannelUsage { amount_msat: 1_000, ..usage };
+		assert_eq!(scorer.channel_penalty_msat(42, &source, &target, usage), base_penalty_msat);
+
+		let usage = ChannelUsage { amount_msat: 1_001, ..usage };
+		assert_eq!(scorer.channel_penalty_msat(42, &source, &target, usage), u64::max_value());
+	}
 }