Outgoing reputation and HTLC Accountability

02-peer-protocol.md

@@ -2233,6 +2233,7 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
     1. type: 0 (`blinded_path`)
     2. data:
         * [`point`:`path_key`]
+    1. type: 1 (`accountable`)
 
 #### Requirements
 
@@ -2271,6 +2272,18 @@ 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 `path_key` (see [Route Blinding](04-onion-routing.md#route-blinding))
+  - if it is the original source of the HTLC:
+    - SHOULD omit `accountable`.
+    - MAY set `accountable` to mimic patterns of HTLCs it has forwarded.
+  - otherwise:
+    - MAY choose to limit resources assigned to the HTLC (see [Resource Bucketing](recommendations/local-resource-conservation.md#resource-bucketing)).
+    - if `accountable` is present in the incoming `update_add_htlc`:
+      - MUST set `accountable`.
+    - otherwise:
+      - if `upgrade_accountability` is present in the onion:
+        - MAY set `accountable`.
+      - otherwise:
+        - MUST NOT set `accountable`.
 
 `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.

04-onion-routing.md

@@ -214,6 +214,7 @@ This is formatted according to the Type-Length-Value format defined in [BOLT #1]
     1. type: 18 (`total_amount_msat`)
     2. data:
         * [`tu64`:`total_msat`]
+    1. type: 19 (`upgrade_accountability`)
 
 `short_channel_id` is the ID of the outgoing channel used to route the
 message; the receiving peer should operate the other end of this channel.
@@ -240,6 +241,9 @@ The requirements ensure consistency in responding to an unexpected
 `outgoing_cltv_value`, whether it is the final node or not, to avoid
 leaking its position in the route.
 
+`upgrade_accountability` is a marker field that indicates that the 
+forwarding node may set `accountable` in its `update_add_htlc`.
+
 ### Requirements
 
 The creator of `encrypted_recipient_data` (usually, the recipient of payment):
@@ -288,6 +292,10 @@ The writer of the TLV `payload`:
       - if the recipient provided `payment_metadata`:
         - MUST include `payment_metadata` with every HTLC
         - MUST not apply any limits to the size of `payment_metadata` except the limits implied by the fixed onion size
+  - if the recipient provided an invoice with an `accountable` field set:
+    - MUST include `upgrade_accountability` for every node in the route.
+  - otherwise:
+    - MUST NOT include `upgrade_accountability`.
 
 The reader:
 
@@ -339,6 +347,10 @@ The reader:
       - incoming `amount_msat` < `amt_to_forward`.
       - incoming `cltv_expiry` < `outgoing_cltv_value`.
       - incoming `cltv_expiry` < `current_block_height` + `min_final_cltv_expiry_delta`.
+      - `accountable` is set in the incoming `update_add_htlc` but `accountable` was not set in the invoice. 
+  - Otherwise:
+    - MUST return an error if:
+      - `accountable` is set in the incoming `update_add_htlc` but `upgrade_accountability` was not set in the payload.
 
 Additional requirements are specified [here](#basic-multi-part-payments) for
 multi-part payments, and [here](#route-blinding) for blinded payments.
@@ -436,6 +448,11 @@ otherwise meets the amount criterion (eg. some other failure, or
 invoice timeout), however if it were to fulfill only some of them,
 intermediary nodes could simply claim the remaining ones.
 
+`accountable` may only be set in `update_add_htlc` if the receiving 
+node provided an `accountable` signal in its invoice. If the 
+`update_add_htlc` signal is not consistent, a node along the route
+has corrupted this value.
+
 ## Route Blinding
 
 1. subtype: `blinded_path`

11-payment-encoding.md

@@ -158,6 +158,7 @@ Currently defined tagged fields are:
 * `9` (5): `data_length` variable. One or more 5-bit values containing features
   supported or required for receiving this payment.
   See [Feature Bits](#feature-bits).
+* `a` (31): `data_length` 0. A marker field that indicates whether the recipient is willing to be held accountable for the timely resolution of the invoice upon HTLC(s) receipt. 
 
 ### Requirements
 
@@ -203,6 +204,10 @@ A writer:
   - MUST pad field data to a multiple of 5 bits, using 0s.
   - if a writer offers more than one of any field type, it:
     - MUST specify the most-preferred field first, followed by less-preferred fields, in order.
+  - if the invoice will be resolved within 90 seconds of HTLC(s) arrival:
+    - SHOULD include a single `a` field
+  - otherwise:
+    - MUST NOT include an `a` field
 
 A reader:
   - MUST skip over unknown fields, OR an `f` field with unknown `version`, OR  `p`, `h` or
@@ -270,6 +275,11 @@ The `r` field allows limited routing assistance: as specified, it only
 allows minimum information to use private channels, however, it could also
 assist in future partial-knowledge routing.
 
+The `a` field indicates that the recipient is willing to be held 
+accountable for the timely resolution of the invoice. In the absence
+of this field, the reader should assume that there are no guarantees
+from the writer about resolution time.
+
 ### Security Considerations for Payment Descriptions
 
 Payment descriptions are user-defined and provide a potential avenue for

12-offer-encoding.md

@@ -644,6 +644,7 @@ the `onion_message` `invoice` field.
         * [`name_len*byte`:`name`]
         * [`u8`:`domain_len`]
         * [`domain_len*byte`:`domain`]
+    1. type: 93 (`accountable`)
     1. type: 160 (`invoice_paths`)
     2. data:
         * [`...*blinded_path`:`paths`]
@@ -745,6 +746,10 @@ A writer of an invoice:
     - MUST include `invoice_blindedpay` with exactly one `blinded_payinfo` for each `blinded_path` in `paths`, in order.
     - MUST set `features` in each `blinded_payinfo` to match `encrypted_data_tlv`.`allowed_features` (or empty, if no `allowed_features`).
     - SHOULD ignore any payment which does not use one of the paths.
+  - if the invoice will be resolved within 90 seconds of HTLC(s) arrival:
+    - SHOULD set `accountable`.
+  - otherwise:
+    - MUST NOT set `accountable`.
 
 A reader of an invoice:
   - MUST reject the invoice if `invoice_amount` is not present.