hold fees

Author: joostjager

02-peer-protocol.md

@@ -786,6 +786,12 @@ A fulfilling node:
   transaction, AND is past this fulfillment deadline:
     - MUST fail the channel.
 
+### Hold fees
+
+To prevent abuse of the network, nodes will charge a fee for the time that their money is locked up in htlcs. The general direction of this fee stream is backwards. Every node along the route that receives an htlc will pay a time-dependent hold fee rate to its predecessor when the htlc resolves, regardless of whether the htlc was fulfilled or failed. The hold fee rate increases with every hop downstream, because more and more money gets locked up. An intermediary or final node that holds on to the htlc for an unreasonably long period of time will need to pay for that (indirectly) to every node upstream.
+
+Forwarding an htlc will always add some delay. To prevent senders from collecting 'free' hold fees, routing nodes will demand a discount on the hold fee. If the routing node forwards swiftly, this discount will turn the hold fee negative and require the sender to pay. Ultimately the sum of all these discounts is paid by the original sender of the payment. This is a protection against spam.
+
 ### Adding an HTLC: `update_add_htlc`
 
 Either node can send `update_add_htlc` to offer an HTLC to the other,
@@ -805,6 +811,8 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
    * [`sha256`:`payment_hash`]
    * [`u32`:`cltv_expiry`]
    * [`1366*byte`:`onion_routing_packet`]
+   * [`u64`:`hold_fee_rate_day`]
+   * [`u64`:`hold_fee_discount`]
 
 #### Requirements
 
@@ -829,6 +837,8 @@ A sending node:
     its commitment transaction, it cannot pay the fee for the updated local or
     remote transaction at the current `feerate_per_kw` while maintaining its
     channel reserve.
+  - SHOULD NOT offer a combination of `amount_msat`, `cltv_expiry`, `hold_fee_rate_day` and `hold_fee_discount` such that the remote node cannot pay the hold fee for the longest possible hold duration. The longest possible hold duration is the `cltv_expiry` delta in blocks multiplied by ten minutes. This must also take into account all currently outstanding htlcs.
+  - SHOULD NOT offer a `hold_fee_discount` that it cannot pay for. This must also take into account all currently outstanding htlcs.
   - MUST offer `amount_msat` greater than 0.
   - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat`
   - MUST set `cltv_expiry` less than 500000000.
@@ -916,6 +926,7 @@ To supply the preimage:
    * [`channel_id`:`channel_id`]
    * [`u64`:`id`]
    * [`32*byte`:`payment_preimage`]
+   * [`u64:hold fee`]
 
 For a timed out or route-failed HTLC:
 
@@ -925,6 +936,7 @@ For a timed out or route-failed HTLC:
    * [`u64`:`id`]
    * [`u16`:`len`]
    * [`len*byte`:`reason`]
+   * [`u64:hold fee`]
 
 The `reason` field is an opaque encrypted blob for the benefit of the
 original HTLC initiator, as defined in [BOLT #4](04-onion-routing.md);
@@ -940,6 +952,7 @@ For an unparsable HTLC:
    * [`u64`:`id`]
    * [`sha256`:`sha256_of_onion`]
    * [`u16`:`failure_code`]
+   * [`u64:hold fee`]
 
 #### Requirements
 
@@ -950,6 +963,7 @@ A node:
   commitment transactions:
     - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or
 `update_fail_malformed_htlc`.
+  - MUST set `hold_fee` to the hold fees that it owes the sending node. Let `hold_duration_days` be the actual time what the htlc was held expressed in days. This value is calculated as `hold_fee_rate_day` (from `update_add_htlc`) * `hold_duration_days` - `hold_fee_discount` (also from `update_add_htlc`). Example: `hold_fee_rate_day`=200, `hold_fee_discount`=3, `hold_duration_days`=0.02 (30 minutes). Then `hold_fee` is 200 * 0.02 - 3 = 1 sat. `hold_fee` can be negative in which case the sending node owes the receiving node.
 
 A receiving node:
   - if the `id` does not correspond to an HTLC in its current commitment transaction:
@@ -967,6 +981,8 @@ A receiving node:
     - MUST return an error in the `update_fail_htlc` sent to the link which
       originally sent the HTLC, using the `failure_code` given and setting the
       data to `sha256_of_onion`.
+  - MUST fail the channel if `hold_fee` is more than 1% below the expected value. This tolerance exists to accommodate for clock skew.
+  - MUST account for the `hold_fee` internally by adding the value to its balance and subtracting the value from the remote balance.
 
 #### Rationale
 

04-onion-routing.md

@@ -263,6 +263,10 @@ It is formatted according to the Type-Length-Value format defined in [BOLT #1](0
     2. data:
         * [`32*byte`:`payment_secret`]
         * [`tu64`:`total_msat`]
+    1. type: 10 (`hold_fee`)
+    2. data:
+        * [`u64`:`hold_fee_rate_day`]
+        * [`u64`:`hold_fee_discount`]
 
 ### Requirements
 
@@ -271,16 +275,19 @@ The writer:
     - MUST use the legacy payload format instead.
   - For every node:
     - MUST include `amt_to_forward` and `outgoing_cltv_value`.
+    - MUST include `hold_fee`
   - For every non-final node:
     - MUST include `short_channel_id`
     - MUST NOT include `payment_data`
+    - MUST set `hold_fee_rate_day` so that difference between incoming and outgoing `hold_fee_rate_day` for the receiving node is at least the expected value based on the receiving node's channel policy.
+    - MUST set `hold_fee_discount` to the amount that the reading node would owe its predecessor if the htlc would remain locked for `hold_grace_period_sec` (as advertised by the reading node), plus all amounts owed by nodes further downstream to their predecessors if they'd all hold the htlc for their `hold_grace_period_sec`.
   - For the final node:
     - MUST NOT include `short_channel_id`
     - if the recipient provided `payment_secret`:
       - MUST include `payment_data`
       - MUST set `payment_secret` to the one provided
       - MUST set `total_msat` to the total amount it will send
-
+      - MUST set `hold_fee_discount` to the amount that the reading node would owe its predecessor if the htlc would remain locked for `hold_grace_period_sec` (as advertised by the reading node).
 The reader:
   - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present.
   - if it is the final node:

07-routing-gossip.md

@@ -408,6 +408,9 @@ of *relaying* payments, not *sending* payments. When making a payment
     * [`u32`:`fee_base_msat`]
     * [`u32`:`fee_proportional_millionths`]
     * [`u64`:`htlc_maximum_msat`] (option_channel_htlc_max)
+    * [`u64`:`hold_fee_rate_base_day`]
+    * [`u64`:`hold_fee_rate_ppm_day`]
+    * [`u64`:`hold_grace_period_sec`]
 
 The `channel_flags` bitfield is used to indicate the direction of the channel: it
 identifies the node that this update originated from and signals various options
@@ -485,6 +488,9 @@ The origin node:
   - MUST set `fee_proportional_millionths` to the amount (in millionths of a
   satoshi) it will charge per transferred satoshi.
   - SHOULD NOT create redundant `channel_update`s
+  - SHOULD set `hold_grace_period_sec` to the total processing time that it needs for forwarding an htlc over this channel. This includes both the forward (`update_add_htlc`) and the backward pass (`update_fulfill_htlc` / `update_fail_htlc`). As long as this node's delay stays within the grace period, there won't be any hold fee to pay.
+  - MUST set `hold_fee_rate_base_day` to the base fee per day that it expects to get paid via its outgoing link for having the htlc in flight.
+  - MUST set `hold_fee_rate_ppm_day` to the proportional fee (in parts per million) per day that is expects to get paid back via its outgoing link for having the htlc in flight. Example: `hold_fee_rate_base_day` = 10, `hold_fee_rate_ppm_day` = 1000, htlc amount = 2000000 sat, hold duration = 1 hour. The node will then expect to get paid (10 + 2000000 * 1000000 / 1000) / 24 = 83.75 sat in hold fees.
 
 The receiving node:
   - if the `short_channel_id` does NOT match a previous `channel_announcement`,