Add a bLIP for backwards-compatible inbound fees

blip-0019.md

@@ -0,0 +1,101 @@
+```
+bLIP: 19
+Title: Inbound Routing Fees
+Status: Active
+Author:  Matt Corallo <bl19lea@bluematt.me>
+Created: 2023-01-08
+License: CC0
+```
+
+## Abstract
+
+This bLIP describes a mechanism whereby a node can charge either a positive or a negative amount in fees for an HTLC based on the channel on which the HTLC came in to said node. It does not modify existing `channel_update` messages, avoiding issues where temporary negative fees cause nodes to spam the gossip network (see "Rate Cards" for a proposal which adds negative fees without this issue). Instead, it relies on informing peers that a fee will be charged, and having them incrase their corresponding outbound fees.
+
+## Copyright
+
+This bLIP is licensed under the CC0 license.
+
+## Specification
+
+One new message is defined, `inbound_fees_update`:
+
+1. type: 34242 (`inbound_fees_update`)
+2. data:
+   * [`32*byte`:`channel_id`]
+   * [`i32`:`inbound_forwarding_fee_proportional_millionths`]
+   * [`i32`:`inbound_forwarding_fee_base_msat`]
+
+Additionally, one new feature flag is defined:
+
+| Bits    | Name           | Description                                            | Context | Dependencies |
+|---------|----------------|--------------------------------------------------------|---------|--------------|
+| 282/283 | `inbound_fees` | Supports receiving and enforcing `inbound_fees_update` | IN      | None         |
+
+### Requirements
+
+A node receiving `inbound_fees_update`:
+ * MUST ensure it's next `channel_update` message for the corresponding channel
+   has its `fee_proportional_millionths` and `fee_base_msat` fields incremented
+   by the `inbound_forwarding_fee_proportional_millionths` and
+   `inbound_forwarding_fee_base_msat` fields, respectively. Fields which fall
+   below zero MUST be set to zero.
+ * SHOULD ensure that it's next `channel_update` goes out in a timely manner,
+   subject to relevant rate-limits.
+ * MUST increase the amount forwarded in an HTLC by the advertised inbound fees,
+ * however SHOULD delay increasing the amount forwarded by an updated inbound
+   fee until it has a chance to broadcast a new `channel_update` after
+   rate-limits.
+
+A node sending `inbound_fees_update`:
+ * SHOULD NOT send such a message more often than it anticipates
+   `channel_update` messages may be accepted by the gossip network.
+ * MUST verify that inbound fees corresponding with the provided settings are
+   paid on all HTLCs, noting that the inbound fees are calculated against the
+   inbound HTLC amount *before* the inbound fees are subtracted. This includes
+   received payments as well as forwarded ones.
+ * SHOULD delay enforcing updated inbound fees for some time, congruous with
+   the delay applied when enforcing new fees after sending a `channel_update`.
+
+## Rationale
+
+Because a node cannot set the fee fields in its `channel_update` below zero,
+only a node's immediate peer may utilize negative inbound fees in excess of
+its outbound fees. This may be useful for private channels where a peer can
+provide a fee discount to its counterparty even though it is not available to
+the global network.
+
+Because senders calculate fees based on the amount as they think it will be
+forwarded, inbound fees must be checked by adding required fees back up from
+the `amt_to_forward` value. i.e. in order to check the total fee on an HTLC, a
+node must calculate the total expected fee based on it's announced forwarding
+parameters, subtract that from the `amt_to_forward` to get the amount the
+sending node (likely) expected the processing node to receive. From there, the
+processing node can calculate the inbound fee it expected and check that it was
+included in the forwarded HTLC.
+
+Note that inbound fees are charged both on forwarded payments and inbound
+payments to prevent a forwarding node from probing to determine if the next hop
+is the final destination by checking if the recipient enforces inbound fees.
+This also ensures that nodes charging inbound fees for the purpose of
+encouraging HTLCs be routed over a given path applies to all HTLCs, not only a
+subset.
+
+## Motivation
+
+Many lightning node operators have expressed a desire for "inbound routing fees," i.e. fees which a sender must pay when forwarding *inbound* through a channel, rather than outbound. There is some debate as to whether such fees make sense in the general case - ultimately it's not the fee-charging node's liquidity which is being used here, so why can they charge a fee for it?
+
+However, ignoring whether this feature makes sense for routing nodes, routing nodes may which to use this to provide fee discounts for peers with which they have a commercial relationship with. For example LSP's may wish to use this to provide explicit fee discounts to their paying clients.
+
+Having a standard, interoperable way for such relationships to be implemented allows LSP's to provide such a service without vendor lockin.
+
+## Universality
+
+This bLIP describes a mechanism for inbound fees which is completely transparent to the broader lightning network. Only the two nodes involved in the channel are aware of the inbound fees. More importantly, due to the above concerns expressed over the general applicability of inbound routing fees, it is anticipated that not all lightning implementations will support this. Users wishing to charge inbound fees may seek out peers which support it, and LSP clients may wish to use this when working with an LSP to receive a fee discount.
+
+## Backwards Compatibility
+
+The new messages described in the bLIP are gated by a new feature bit, which nodes MAY set to odd to ensure backwards compatibility.
+
+## Reference Implementations
+
+* LDK: https://github.com/lightningdevkit/rust-lightning/pull/1942