Nodes advertise the fees for forwarding over a channel as part of a channel_update
message. The update should be sent as soon as a channel_announcement
is sent. Each party can decide its own fees for the channel.
For private channels, nodes advertise the fees inside the r
tagged field of the BOLT#11 invoice.
When forwarding a payment, your node must calculate the required fee for each hop and add it to the payment requested in the invoice. When each intermediate hop receives an update_add_htlc
message, they will unwrap one level of the onion packet, which contains an amt_to_forward
. This is subtracted from the amount_msat
in the update_add_htlc
message, and the difference is the fee paid for this hop.
If the hop determines that the fee is insufficient, they respond to the sender with fee_insufficient
error as part of an update_fail_htlc
message. This message also includes the most recent channel_update
for this channel so that the payer can re-attempt the payment with new fees.
There is always the possibility of a race condition where fees may have changed between the most recently received channel_update
and the payment attempt. This is minimized by including the channel_update
as part of the failure as above.
If the payment at the last hop is too small, they will respond with a failure containing the incorrect_or_unknown_payment_details
failure code.