Check for preimage before failing back missing HTLCs

When an outstanding HTLC is missing from a confirmed commitment, the
current recommendation is to fail it back immediately (or after a
reorg-safety delay).  But if a preimage is available for the HTLC,
failing it back is at best going to cause an error (if the HTLC has
already been fulfilled upstream) and at worst going to cause loss of
funds (if the HTLC has *not* already been fulfilled upstream).

Instead, the spec should clearly indicate that upstream HTLCs should be
fulfilled when possible and only failed back if a preimage is not
available.

05-onchain.md

@@ -254,11 +254,14 @@ A node:
       before spending that HTLC-timeout output.
   - for any committed HTLC that does NOT have an output in this commitment
   transaction:
-    - once the commitment transaction has reached reasonable depth:
+    - if the payment preimage is known:
-      - MUST fail the corresponding incoming HTLC (if any).
+      - MUST fulfill the corresponding incoming HTLC (if any).
-    - if no *valid* commitment transaction contains an output corresponding to
+    - otherwise:
-    the HTLC.
+      - once the commitment transaction has reached reasonable depth:
-      - MAY fail the corresponding incoming HTLC sooner.
+        - MUST fail the corresponding incoming HTLC (if any).
+      - if no *valid* commitment transaction contains an output corresponding to
+      the HTLC:
+        - MAY fail the corresponding incoming HTLC sooner.
 
 ### Rationale
 
@@ -281,12 +284,21 @@ detailed in
 If the incoming HTLC is also on-chain, a node must simply wait for it to
 timeout: there is no way to signal early failure.
 
-If an HTLC is too small to appear in *any commitment transaction*, it can be
+There are several reasons a committed HTLC may not have an output in the
-safely failed immediately. Otherwise, if an HTLC isn't in the *local commitment
+confirmed commitment transaction: the HTLC may be smaller than
-transaction*, a node needs to make sure that a blockchain reorganization, or
+`dust_limit_satoshis`, the HTLC may not have been added to the commitment
-race, does not switch to a commitment transaction that does contain the HTLC
+transaction yet, or the HTLC may have already been failed or fulfilled. In any
-before the node fails it (hence the wait). The requirement that the incoming
+case, if the payment preimage is known for the HTLC, the upstream HTLC needs to
-HTLC be failed before its own timeout still applies as an upper bound.
+be fulfilled to avoid loss of funds.
+
+If the payment preimage is not known for the missing HTLC, the correct action
+depends on the possibility of a blockchain reorganization that swaps out the
+confirmed commitment transaction for one with the HTLC present.
+If the HTLC is too small to appear in *any commitment transaction*, such a
+reorganization is not possible, and the HTLC can be safely failed immediately.
+Otherwise, a reorganization delay is required before failing the incoming HTLC.
+The requirement that the incoming HTLC be failed before its own timeout still
+applies as an upper bound.
 
 ## HTLC Output Handling: Local Commitment, Remote Offers
 
@@ -406,12 +418,14 @@ A local node:
     - MUST *resolve* the output, by spending it to a convenient address.
   - for any committed HTLC that does NOT have an output in this commitment
   transaction:
-    - once the commitment transaction has reached reasonable depth:
+    - if the payment preimage is known:
-      - MUST fail the corresponding incoming HTLC (if any).
+      - MUST fulfill the corresponding incoming HTLC (if any).
     - otherwise:
+      - once the commitment transaction has reached reasonable depth:
+        - MUST fail the corresponding incoming HTLC (if any).
       - if no *valid* commitment transaction contains an output corresponding to
       the HTLC:
-        - MAY fail it sooner.
+        - MAY fail the corresponding incoming HTLC sooner.
 
 ### Rationale
 
@@ -437,13 +451,21 @@ back-fail any corresponding incoming HTLC, using `update_fail_htlc`
 If the incoming HTLC is also on-chain, a node simply waits for it to
 timeout, as there's no way to signal early failure.
 
-If an HTLC is too small to appear in *any commitment transaction*, it
+There are several reasons a committed HTLC may not have an output in the
-can be safely failed immediately. Otherwise,
+confirmed commitment transaction: the HTLC may be smaller than
-if an HTLC isn't in the *local commitment transaction* a node needs to make sure
+`dust_limit_satoshis`, the HTLC may not have been added to the commitment
-that a blockchain reorganization or race does not switch to a
+transaction yet, or the HTLC may have already been failed or fulfilled. In any
-commitment transaction that does contain it before the node fails it: hence
+case, if the payment preimage is known for the HTLC, the upstream HTLC needs to
-the wait. The requirement that the incoming HTLC be failed before its
+be fulfilled to avoid loss of funds.
-own timeout still applies as an upper bound.
+
+If the payment preimage is not known for the missing HTLC, the correct action
+depends on the possibility of a blockchain reorganization that swaps out the
+confirmed commitment transaction for one with the HTLC present.
+If the HTLC is too small to appear in *any commitment transaction*, such a
+reorganization is not possible, and the HTLC can be safely failed immediately.
+Otherwise, a reorganization delay is required before failing the incoming HTLC.
+The requirement that the incoming HTLC be failed before its own timeout still
+applies as an upper bound.
 
 ## HTLC Output Handling: Remote Commitment, Remote Offers