Allow forwarding less than the amount in the onion

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out

lightning/src/events/mod.rs

@@ -387,8 +387,25 @@ pub enum Event {
  ///
  /// Payments received on LDK versions prior to 0.0.115 will have this field unset.
  onion_fields: Option<RecipientOnionFields>,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater
+ /// than the invoice amount.
+ ///
+ /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set
+ /// and the previous hop took an extra fee.
+ ///
+ /// # Note
+ /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this
+ /// field, you may lose money!
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
  amount_msat: u64,
+ /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
+ /// taken by our channel counterparty.
+ ///
+ /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set.
+ ///
+ /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
+ counterparty_skimmed_fee_msat: u64,
  /// Information for claiming this received payment, based on whether the purpose of the
  /// payment is to pay an invoice or to send a spontaneous payment.
  purpose: PaymentPurpose,
@@ -430,7 +447,8 @@ pub enum Event {
  /// The payment hash of the claimed payment. Note that LDK will not stop you from
  /// registering duplicate payment hashes for inbound payments.
  payment_hash: PaymentHash,
- /// The value, in thousandths of a satoshi, that this payment is for.
+ /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
+ /// invoice amount.
  amount_msat: u64,
  /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
  /// spontaneous payment.
@@ -623,6 +641,7 @@ pub enum Event {
  inbound_amount_msat: u64,
  /// How many msats the payer intended to route to the next node. Depending on the reason you are
  /// intercepting this payment, you might take a fee by forwarding less than this amount.
+ /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
  ///
  /// Note that LDK will NOT check that expected fees were factored into this value. You MUST
  /// check that whatever fee you want has been included here or subtract it as required. Further,
@@ -832,8 +851,8 @@ impl Writeable for Event {
  // We never write out FundingGenerationReady events as, upon disconnection, peers
  // drop any channels which have not yet exchanged funding_signed.
  },
- &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose,
- ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
+ &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat,
+ ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id,
  ref claim_deadline, ref onion_fields
  } => {
  1u8.write(writer)?;
@@ -848,6 +867,8 @@ impl Writeable for Event {
  payment_preimage = Some(*preimage);
  }
  }
+ let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None }
+ else { Some(counterparty_skimmed_fee_msat) };
  write_tlv_fields!(writer, {
  (0, payment_hash, required),
  (1, receiver_node_id, option),
@@ -859,6 +880,7 @@ impl Writeable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, skimmed_fee_opt, option),
  });
  },
  &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
@@ -1058,6 +1080,7 @@ impl MaybeReadable for Event {
  let mut payment_preimage = None;
  let mut payment_secret = None;
  let mut amount_msat = 0;
+ let mut counterparty_skimmed_fee_msat_opt = None;
  let mut receiver_node_id = None;
  let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
  let mut via_channel_id = None;
@@ -1075,6 +1098,7 @@ impl MaybeReadable for Event {
  (7, claim_deadline, option),
  (8, payment_preimage, option),
  (9, onion_fields, option),
+ (10, counterparty_skimmed_fee_msat_opt, option),
  });
  let purpose = match payment_secret {
  Some(secret) => PaymentPurpose::InvoicePayment {
@@ -1088,6 +1112,7 @@ impl MaybeReadable for Event {
  receiver_node_id,
  payment_hash,
  amount_msat,
+ counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0),
  purpose,
  via_channel_id,
  via_user_channel_id,

lightning/src/ln/channel.rs

@@ -224,6 +224,7 @@ struct OutboundHTLCOutput {
 	payment_hash: PaymentHash,
 	state: OutboundHTLCState,
 	source: HTLCSource,
+	skimmed_fee_msat: Option<u64>,
 }
 
 /// See AwaitingRemoteRevoke ChannelState for more info
@@ -235,6 +236,8 @@ enum HTLCUpdateAwaitingACK {
  payment_hash: PaymentHash,
  source: HTLCSource,
  onion_routing_packet: msgs::OnionPacket,
+ // The extra fee we're skimming off the top of this HTLC.
+ skimmed_fee_msat: Option<u64>,
 	},
 	ClaimHTLC {
  payment_preimage: PaymentPreimage,
@@ -3052,8 +3055,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  // handling this case better and maybe fulfilling some of the HTLCs while attempting
  // to rebalance channels.
  match &htlc_update {
- &HTLCUpdateAwaitingACK::AddHTLC {amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet, ..} => {
- match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(), onion_routing_packet.clone(), false, logger) {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ amount_msat, cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat, ..
+ } => {
+ match self.send_htlc(amount_msat, *payment_hash, cltv_expiry, source.clone(),
+ onion_routing_packet.clone(), false, skimmed_fee_msat, logger)
+ {
  Ok(update_add_msg_option) => update_add_htlcs.push(update_add_msg_option.unwrap()),
  Err(e) => {
  match e {
@@ -3695,6 +3703,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash: htlc.payment_hash,
  cltv_expiry: htlc.cltv_expiry,
  onion_routing_packet: (**onion_packet).clone(),
+ skimmed_fee_msat: htlc.skimmed_fee_msat,
  });
  }
  }
@@ -5042,11 +5051,13 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// commitment update.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	pub fn queue_add_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, logger: &L)
-	-> Result<(), ChannelError> where L::Target: Logger {
+	pub fn queue_add_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<(), ChannelError> where L::Target: Logger {
  self
- .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true, logger)
+ .send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, true,
+ skimmed_fee_msat, logger)
  .map(|msg_opt| assert!(msg_opt.is_none(), "We forced holding cell?"))
  .map_err(|err| {
  if let ChannelError::Ignore(_) = err { /* fine */ }
@@ -5071,9 +5082,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	/// on this [`Channel`] if `force_holding_cell` is false.
 	///
 	/// `Err`s will only be [`ChannelError::Ignore`].
-	fn send_htlc<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
- onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool, logger: &L)
-	-> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
+	fn send_htlc<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, mut force_holding_cell: bool,
+ skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> where L::Target: Logger {
  if (self.context.channel_state & (ChannelState::ChannelReady as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelReady as u32) {
  return Err(ChannelError::Ignore("Cannot send HTLC until channel is fully established and we haven't started shutting down".to_owned()));
  }
@@ -5125,6 +5138,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  source,
  onion_routing_packet,
+ skimmed_fee_msat,
  });
  return Ok(None);
  }
@@ -5136,6 +5150,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  cltv_expiry,
  state: OutboundHTLCState::LocalAnnounced(Box::new(onion_routing_packet.clone())),
  source,
+ skimmed_fee_msat,
  });
 
  let res = msgs::UpdateAddHTLC {
@@ -5145,6 +5160,7 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
  payment_hash,
  cltv_expiry,
  onion_routing_packet,
+ skimmed_fee_msat,
  };
  self.context.next_holder_htlc_id += 1;
 
@@ -5283,8 +5299,12 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	///
 	/// Shorthand for calling [`Self::send_htlc`] followed by a commitment update, see docs on
 	/// [`Self::send_htlc`] and [`Self::build_commitment_no_state_update`] for more info.
-	pub fn send_htlc_and_commit<L: Deref>(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket, logger: &L) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
- let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source, onion_routing_packet, false, logger);
+	pub fn send_htlc_and_commit<L: Deref>(
+ &mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource,
+ onion_routing_packet: msgs::OnionPacket, skimmed_fee_msat: Option<u64>, logger: &L
+	) -> Result<Option<&ChannelMonitorUpdate>, ChannelError> where L::Target: Logger {
+ let send_res = self.send_htlc(amount_msat, payment_hash, cltv_expiry, source,
+ onion_routing_packet, false, skimmed_fee_msat, logger);
  if let Err(e) = &send_res { if let ChannelError::Ignore(_) = e {} else { debug_assert!(false, "Sending cannot trigger channel failure"); } }
  match send_res? {
  Some(_) => {
@@ -6609,9 +6629,10 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  }
 
  let mut preimages: Vec<&Option<PaymentPreimage>> = vec![];
+ let mut pending_outbound_skimmed_fees: Vec<Option<u64>> = Vec::new();
 
  (self.context.pending_outbound_htlcs.len() as u64).write(writer)?;
- for htlc in self.context.pending_outbound_htlcs.iter() {
+ for (idx, htlc) in self.context.pending_outbound_htlcs.iter().enumerate() {
  htlc.htlc_id.write(writer)?;
  htlc.amount_msat.write(writer)?;
  htlc.cltv_expiry.write(writer)?;
@@ -6647,18 +6668,37 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  reason.write(writer)?;
  }
  }
+ if let Some(skimmed_fee) = htlc.skimmed_fee_msat {
+ if pending_outbound_skimmed_fees.is_empty() {
+ for _ in 0..idx { pending_outbound_skimmed_fees.push(None); }
+ }
+ pending_outbound_skimmed_fees.push(Some(skimmed_fee));
+ } else if !pending_outbound_skimmed_fees.is_empty() {
+ pending_outbound_skimmed_fees.push(None);
+ }
  }
 
+ let mut holding_cell_skimmed_fees: Vec<Option<u64>> = Vec::new();
  (self.context.holding_cell_htlc_updates.len() as u64).write(writer)?;
- for update in self.context.holding_cell_htlc_updates.iter() {
+ for (idx, update) in self.context.holding_cell_htlc_updates.iter().enumerate() {
  match update {
- &HTLCUpdateAwaitingACK::AddHTLC { ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet } => {
+ &HTLCUpdateAwaitingACK::AddHTLC {
+ ref amount_msat, ref cltv_expiry, ref payment_hash, ref source, ref onion_routing_packet,
+ skimmed_fee_msat,
+ } => {
  0u8.write(writer)?;
  amount_msat.write(writer)?;
  cltv_expiry.write(writer)?;
  payment_hash.write(writer)?;
  source.write(writer)?;
  onion_routing_packet.write(writer)?;
+
+ if let Some(skimmed_fee) = skimmed_fee_msat {
+ if holding_cell_skimmed_fees.is_empty() {
+ for _ in 0..idx { holding_cell_skimmed_fees.push(None); }
+ }
+ holding_cell_skimmed_fees.push(Some(skimmed_fee));
+ } else if !holding_cell_skimmed_fees.is_empty() { holding_cell_skimmed_fees.push(None); }
  },
  &HTLCUpdateAwaitingACK::ClaimHTLC { ref payment_preimage, ref htlc_id } => {
  1u8.write(writer)?;
@@ -6825,6 +6865,8 @@ impl<Signer: WriteableEcdsaChannelSigner> Writeable for Channel<Signer> {
  (29, self.context.temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, self.context.pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees, optional_vec),
+ (37, holding_cell_skimmed_fees, optional_vec),
  });
 
  Ok(())
@@ -6935,6 +6977,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  },
  _ => return Err(DecodeError::InvalidValue),
  },
+ skimmed_fee_msat: None,
  });
  }
 
@@ -6948,6 +6991,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  payment_hash: Readable::read(reader)?,
  source: Readable::read(reader)?,
  onion_routing_packet: Readable::read(reader)?,
+ skimmed_fee_msat: None,
  },
  1 => HTLCUpdateAwaitingACK::ClaimHTLC {
  payment_preimage: Readable::read(reader)?,
@@ -7103,6 +7147,9 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let mut pending_monitor_updates = Some(Vec::new());
 
+ let mut pending_outbound_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+ let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
+
  read_tlv_fields!(reader, {
  (0, announcement_sigs, option),
  (1, minimum_depth, option),
@@ -7126,6 +7173,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
  (29, temporary_channel_id, option),
  (31, channel_pending_event_emitted, option),
  (33, pending_monitor_updates, vec_type),
+ (35, pending_outbound_skimmed_fees_opt, optional_vec),
+ (37, holding_cell_skimmed_fees_opt, optional_vec),
  });
 
  let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -7180,6 +7229,25 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
  let holder_max_accepted_htlcs = holder_max_accepted_htlcs.unwrap_or(DEFAULT_MAX_HTLCS);
 
+ if let Some(skimmed_fees) = pending_outbound_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in pending_outbound_htlcs.iter_mut() {
+ htlc.skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+ if let Some(skimmed_fees) = holding_cell_skimmed_fees_opt {
+ let mut iter = skimmed_fees.into_iter();
+ for htlc in holding_cell_htlc_updates.iter_mut() {
+ if let HTLCUpdateAwaitingACK::AddHTLC { ref mut skimmed_fee_msat, .. } = htlc {
+ *skimmed_fee_msat = iter.next().ok_or(DecodeError::InvalidValue)?;
+ }
+ }
+ // We expect all skimmed fees to be consumed above
+ if iter.next().is_some() { return Err(DecodeError::InvalidValue) }
+ }
+
  Ok(Channel {
  context: ChannelContext {
  user_id,
@@ -7522,7 +7590,8 @@ mod tests {
  session_priv: SecretKey::from_slice(&hex::decode("0fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap()[..]).unwrap(),
  first_hop_htlc_msat: 548,
  payment_id: PaymentId([42; 32]),
- }
+ },
+ skimmed_fee_msat: None,
  });
 
  // Make sure when Node A calculates their local commitment transaction, none of the HTLCs pass
@@ -8079,6 +8148,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0202020202020202020202020202020202020202020202020202020202020202").unwrap()).into_inner();
  out
@@ -8091,6 +8161,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0303030303030303030303030303030303030303030303030303030303030303").unwrap()).into_inner();
  out
@@ -8492,6 +8563,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out
@@ -8504,6 +8576,7 @@ mod tests {
  payment_hash: PaymentHash([0; 32]),
  state: OutboundHTLCState::Committed,
  source: HTLCSource::dummy(),
+ skimmed_fee_msat: None,
  };
  out.payment_hash.0 = Sha256::hash(&hex::decode("0505050505050505050505050505050505050505050505050505050505050505").unwrap()).into_inner();
  out