multi: add resource bucketing for HTLC slots and liquidity

Author: carlaKC

02-peer-protocol.md

@@ -995,7 +995,10 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
     1. type: 0 (`blinding_point`)
     2. data:
         * [`point`:`blinding`]
-
+    1. type: 1 (`endorsed`)
+    2. data:
+        * [`byte`:`endorsed`]
+ 
 #### Requirements
 
 A sending node:
@@ -1033,6 +1036,10 @@ A sending node:
   - MUST increase the value of `id` by 1 for each successive offer.
   - if it is relaying a payment inside a blinded route:
     - MUST set `blinding_point` (see [Route Blinding](04-onion-routing.md#route-blinding))
+  - if it is the original source of the HTLC:
+    - SHOULD set `endorsed` to `1`. 
+  - otherwise: 
+    - SHOULD set `endorsed` as described in [Bolt 4](04-onion-routing.md#resource-bucketing).
 
 `id` MUST NOT be reset to 0 after the update is complete (i.e. after `revoke_and_ack` has
 been received). It MUST continue incrementing instead.
@@ -1059,6 +1066,8 @@ A receiving node:
       `error` and fail the channel.
   - if `blinding_point` is provided:
     - MUST use the corresponding blinded private key to decrypt the `onion_routing_packet` (see [Route Blinding](04-onion-routing.md#route-blinding))
+  - if `endorsed` is provided:
+    - SHOULD interpret `endorsed` as described in [Bolt 4](04-onion-routing.md#resource-bucketing).
 
 The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path.
 It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs.

04-onion-routing.md

@@ -53,6 +53,7 @@ A node:
     * [Route Blinding](#route-blinding)
   * [Accepting and Forwarding a Payment](#accepting-and-forwarding-a-payment)
     * [Non-strict Forwarding](#non-strict-forwarding)
+    * [Resource Bucketing](#resource-bucketing)
     * [Payload for the Last Node](#payload-for-the-last-node)
   * [Shared Secret](#shared-secret)
   * [Blinding Ephemeral Keys](#blinding-ephemeral-keys)
@@ -62,6 +63,7 @@ A node:
   * [Returning Errors](#returning-errors)
     * [Failure Messages](#failure-messages)
     * [Receiving Failure Codes](#receiving-failure-codes)
+  * [Recommendations for Reputation](#recommendations-for-reputation)
   * [Test Vector](#test-vector)
     * [Returning Errors](#returning-errors)
   * [References](#references)
@@ -635,6 +637,38 @@ Alternatively, implementations may choose to apply non-strict forwarding only to
 like-policy channels to ensure their expected fee revenue does not deviate by
 using an alternate channel.
 
+## Resource Bucketing
+
+When making the decision to forward a payment on its outgoing channel, a node 
+MAY choose to limit its exposure to HTLCs that put it at risk of a denial of 
+service attack.
+* `unknown_allocation_slots`: defines the number of HTLC slots allocated to 
+   unknown traffic. 
+* `unknown_allocation_liquidity`: defines the amount of the channel balance 
+   that is allocated to unknown traffic.
+
+It is recommended to allocate 50% of a channel's liquidity and slots to unknown
+traffic to accommodate the recommended maximum HTLC size (per the Oakland 
+Protocol).
+ 
+A node implementing resource bucketing limits exposure on its outgoing channel:
+- MUST choose `unknown_allocation_slots` <= the remote channel peer's 
+  `max_accepted_htlcs`.
+- MUST choose `unknown_allocation_liquidity` <= the remote channel peer's 
+  `max_htlc_value_in_flight_msat`.
+- If `endorsed` is set to 1 in the incoming `update_add_htlc` AND the HTLC 
+  is from a node that the forwarding node considers to have good local 
+  reputation (see [Recommendations for Reputation](#recommendations-for-reputation)):
+  - SHOULD proceed with forwarding the HTLC.
+  - SHOULD set `endorsed` to 1 in the outgoing `update_add_htlc`.
+- Otherwise, the HTLC is classified as `unknown`:
+  - If `unknown_allocation_slots` HTLC slots are occupied by other `unknown` HTLCs: 
+    - SHOULD return `temporary_channel_failure` as specified in [Failure Messages](#failure-messages).
+  - If `unknown_allocation_liquidity`  satoshis of liquidity are locked in 
+    other `unknown` HTLCs: 
+    - SHOULD return `temporary_channel_failure` as specified in [Failure Messages](#failure-messages).
+  - SHOULD set `endorsed` to 0 in the outgoing `update_add_htlc`. 
+
 ## Payload for the Last Node
 
 When building the route, the origin node MUST use a payload for
@@ -1407,6 +1441,10 @@ The _origin node_:
   - MAY use the data specified in the various failure types for debugging
   purposes.
 
+# Recommendations for Reputation
+
+At the time of writing, specification for reputation recommendations is ongoing.
+
 # Test Vector
 
 ## Returning Errors