cleanup 1

Author: devrandom

lightning/src/ln/msgs.rs

@@ -104,76 +104,76 @@ pub struct Pong {
 pub struct OpenChannel {
 	/// The genesis hash of the blockchain where the channel is to be opened
 	pub chain_hash: BlockHash,
-	/// A temporary channel ID, until the funding is established
+	/// A temporary channel ID, until the funding outpoint is announced
 	pub temporary_channel_id: [u8; 32],
 	/// The channel value
 	pub funding_satoshis: u64,
 	/// The amount to push to the counterparty as part of the open, in milli-satoshi
 	pub push_msat: u64,
-	/// The threshold below which outputs should be omitted
+	/// The threshold below which outputs on sender broadcast transactions will be omitted
 	pub dust_limit_satoshis: u64,
-	/// The maximum total HTLC value in flight, in milli-satoshi
+	/// The maximum inbound HTLC value in flight on sender, in milli-satoshi
 	pub max_htlc_value_in_flight_msat: u64,
-	/// The minimum value for the counterparty to keep in the channel
+	/// The minimum value unencumbered by HTLCs for the counterparty to keep in the channel
 	pub channel_reserve_satoshis: u64,
-	/// The minimum HTLC size, in milli-satoshi
+	/// The minimum HTLC size incoming to sender, in milli-satoshi
 	pub htlc_minimum_msat: u64,
-	/// The feerate per 1000-weight of the transaction
+	/// The feerate per 1000-weight of sender generated transactions, until updated by update_fee
 	pub feerate_per_kw: u32,
-	/// The minimum to_self_delay for the counterparty's transactions
+	/// 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 accepted HTLCs
+	/// The maximum number of inbound HTLCs on sender
 	pub max_accepted_htlcs: u16,
-	/// The funding public key
+	/// The sender's key controlling the funding transaction
 	pub funding_pubkey: PublicKey,
-	/// The funding public key
+	/// Used to derive a revocation key for transactions broadcast by counterparty
 	pub revocation_basepoint: PublicKey,
-	/// The payment point
+	/// Used to derive a payment key to sender for transactions broadcast by counterparty
 	pub payment_point: PublicKey,
-	/// The delayed payment basepoint
+	/// Used to derive a payment key to sender for transactions broadcast by sender
 	pub delayed_payment_basepoint: PublicKey,
-	/// The HTLC basepoint
+	/// Used to derive an HTLC payment key to sender
 	pub htlc_basepoint: PublicKey,
-	/// The first transaction's per commitment point
+	/// The first to-be-broadcast-by-sender transaction's per commitment point
 	pub first_per_commitment_point: PublicKey,
 	/// Channel flags
 	pub channel_flags: u8,
-	/// Optionally, the scriptPubkey 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<Script>,
 }
 
 /// An accept_channel message to be sent or received from a peer
 #[derive(Clone)]
 pub struct AcceptChannel {
-	/// A temporary channel ID, until the funding is established
+	/// A temporary channel ID, until the funding outpoint is announced
 	pub temporary_channel_id: [u8; 32],
-	/// The threshold below which outputs should be omitted
+	/// The threshold below which outputs on sender broadcast transactions will be omitted
 	pub dust_limit_satoshis: u64,
-	/// The maximum total HTLC value in flight, in milli-satoshi
+	/// The maximum inbound HTLC value in flight on sender, in milli-satoshi
 	pub max_htlc_value_in_flight_msat: u64,
-	/// The minimum value for the counterparty to keep in the channel
+	/// The minimum value unencumbered by HTLCs for the counterparty to keep in the channel
 	pub channel_reserve_satoshis: u64,
-	/// The minimum HTLC size, in milli-satoshi
+	/// The minimum HTLC size incoming to sender, in milli-satoshi
 	pub htlc_minimum_msat: u64,
 	/// Minimum depth of the funding transaction before the channel is considered open
 	pub minimum_depth: u32,
-	/// The minimum to_self_delay for the counterparty's transactions
+	/// 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 accepted HTLCs
+	/// The maximum number of inbound HTLCs on sender
 	pub max_accepted_htlcs: u16,
-	/// The funding public key
+	/// The sender's key controlling the funding transaction
 	pub funding_pubkey: PublicKey,
-	/// The funding public key
+	/// Used to derive a revocation key for transactions broadcast by counterparty
 	pub revocation_basepoint: PublicKey,
-	/// The payment point
+	/// Used to derive a payment key to sender for transactions broadcast by counterparty
 	pub payment_point: PublicKey,
-	/// The delayed payment basepoint
+	/// Used to derive a payment key to sender for transactions broadcast by sender
 	pub delayed_payment_basepoint: PublicKey,
-	/// The HTLC basepoint
+	/// Used to derive an HTLC payment key to sender for transactions broadcast by counterparty
 	pub htlc_basepoint: PublicKey,
-	/// The first transaction's per commitment point
+	/// The first to-be-broadcast-by-sender transaction's per commitment point
 	pub first_per_commitment_point: PublicKey,
-	/// Optionally, the scriptPubkey 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<Script>,
 }
 
@@ -193,7 +193,7 @@ pub struct FundingCreated {
 /// A funding_signed message to be sent or received from a peer
 #[derive(Clone)]
 pub struct FundingSigned {
-	/// The channel ID, which is the funding transaction ID mixed with the funding output index
+	/// The channel ID
 	pub channel_id: [u8; 32],
 	/// The signature of the channel acceptor (fundee) on the funding transaction
 	pub signature: Signature,
@@ -238,7 +238,7 @@ pub struct UpdateAddHTLC {
 	pub htlc_id: u64,
 	/// The HTLC value in milli-satoshi
 	pub amount_msat: u64,
-	/// The payment hash
+	/// The payment hash, the pre-image of which controls HTLC redemption
 	pub payment_hash: PaymentHash,
 	/// The expiry height of the HTLC
 	pub cltv_expiry: u32,
@@ -252,7 +252,7 @@ pub struct UpdateFulfillHTLC {
 	pub channel_id: [u8; 32],
 	/// The HTLC ID
 	pub htlc_id: u64,
-	/// The pre-image of the payment hash
+	/// The pre-image of the payment hash, allowing HTLC redemption
 	pub payment_preimage: PaymentPreimage,
 }
 
@@ -296,7 +296,7 @@ pub struct RevokeAndACK {
 	pub channel_id: [u8; 32],
 	/// The secret corresponding to the per-commitment point
 	pub per_commitment_secret: [u8; 32],
-	/// The next transaction's per-commitment point
+	/// The next sender-broadcast commitment transaction's per-commitment point
 	pub next_per_commitment_point: PublicKey,
 }
 
@@ -490,8 +490,7 @@ pub struct UnsignedNodeAnnouncement {
 	/// An alias, for UI purposes.  This should be sanitized before use.  There is no guarantee
 	/// of uniqueness.
 	pub alias: [u8; 32],
-	/// List of addresses on which this node is reachable. Note that you may only have up to one
-	/// address of each type, if you have more, they may be silently discarded or we may panic!
+	/// List of addresses on which this node is reachable
 	pub addresses: Vec<NetAddress>,
 	pub(crate) excess_address_data: Vec<u8>,
 	pub(crate) excess_data: Vec<u8>,
@@ -508,7 +507,7 @@ pub struct NodeAnnouncement {
 /// The unsigned part of a channel_announcement
 #[derive(PartialEq, Clone, Debug)]
 pub struct UnsignedChannelAnnouncement {
-	/// The advertised features
+	/// The advertised channel features
 	pub features: ChannelFeatures,
 	/// The genesis hash of the blockchain where the channel is to be opened
 	pub chain_hash: BlockHash,
@@ -527,13 +526,13 @@ pub struct UnsignedChannelAnnouncement {
 /// A channel_announcement message to be sent or received from a peer
 #[derive(PartialEq, Clone, Debug)]
 pub struct ChannelAnnouncement {
-	/// A signature of the announcement by the node key of the first node
+	/// Authentication of the announcement by the first public node
 	pub node_signature_1: Signature,
-	/// A signature of the announcement by the node key of the second node
+	/// Authentication of the announcement by the second public node
 	pub node_signature_2: Signature,
-	/// The funding signature of the first node
+	/// Proof of funding UTXO ownership by the first public node
 	pub bitcoin_signature_1: Signature,
-	/// The funding signature of the second node
+	/// Proof of funding UTXO ownership by the second public node
 	pub bitcoin_signature_2: Signature,
 	/// The actual announcement
 	pub contents: UnsignedChannelAnnouncement,
@@ -552,11 +551,11 @@ pub struct UnsignedChannelUpdate {
 	pub flags: u8,
 	/// The number of blocks to subtract from incoming HTLC cltv_expiry values
 	pub cltv_expiry_delta: u16,
-	/// The minimum HTLC value in milli-satoshi
+	/// The minimum HTLC size incoming to sender, in milli-satoshi
 	pub htlc_minimum_msat: u64,
-	/// Optionally, the maximum HTLC value in milli-satoshi
+	/// Optionally, the maximum HTLC value incoming to sender, in milli-satoshi
 	pub htlc_maximum_msat: OptionalField<u64>,
-	/// The base HTLC fee in milli-satoshi
+	/// The base HTLC fee charged by sender, in milli-satoshi
 	pub fee_base_msat: u32,
 	/// The amount to fee multiplier, in micro-satoshi
 	pub fee_proportional_millionths: u32,