Error return and conclusion

10_onion_routing.asciidoc

@@ -544,7 +544,7 @@ If Bob extracts and removes his hop payload, the remaining onion will not be 130
 
 ==== Bob generates filler
 
-Bob generates filler in a slightly different way than Alice, but following the same general principle. 
+Bob generates filler in a slightly different way than Alice, but following the same general principle.
 
 First, Bob *extends* the onion payload by 1300 bytes and filles them with +0+ values. Now the onion packet is 2600 bytes long, with the first half containing the data Alice sent and the next half containing zeroes. This operation is shown in <<bob_extends>>:
 
@@ -663,3 +663,66 @@ When Dina receives the +update_add_htlc+ message from Chan, she knows from the +
 Dina follows the exact same process as Bob and Chan to verify and unwrap the onion, except she doesn't construct new filler and doesn't forward anything. Instead, Dina responds to Chan with +update_fulfill_htlc+ to redeem the HTLC. The +update_fulfill_htlc+ will flow backwards along the path until it reaches Alice. All the HTLCs are redeemed and channel balances are updated. The payment is complete!
 
 === Returning errors
+
+This far we've looked at the forward propagation of the onion establishing the HTLCs, and the backwards propagation of the payment secret unwinding the HTLCs once payment is successful.
+
+There is another very important function of onion routing which is _error return_. If there is a problem with the payment, onion, or hops, we must propagate an error backwards to inform all nodes of the failure and unwind any HTLCs.
+
+Errors generally fall into 3 categories: onion failures, node failures and channel failures. These furthermore may be subdivided into permanent and transient errors. Finally, some errors contain channel updates to help with future payment delivery attempts.
+
+[NOTE]
+====
+Unlike messages in the Peer-to-Peer (P2P) protocol (defined in BOLT #2), errors are not sent as P2P messages but wrapped inside onion return packets and following the reverse of the onion path (back-propagating).
+====
+
+Error return is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#returning-errors[BOLT #4 - Onion Routing - Returning Errors].
+
+Errors are encoded by the returning node (the one that discovered an error) encoded in a _return packet_ a follows:
+
+----
+    [32*byte:hmac]
+    [u16:failure_len]
+    [failure_len*byte:failuremsg]
+    [u16:pad_len]
+    [pad_len*byte:pad]
+----
+
+The return packet HMAC verification checksum is calculated with the +um+ key, generated from the shared secret established by the onion.
+
+[TIP]
+====
+The "um" key name is the reverse of the "mu" name, indicating the same use but in the opposite direction (back-propagation)
+====
+
+Next, the returning node generates a +ammag+ (inverse of the word "gamma") key and obfuscates the return packet using an XOR operation with a byte-stream generated from +ammag+.
+
+Finally the return node sends the return packet to the hop from which it received the original onion.
+
+Each hop receiving an error, will generate an +ammag+ key and obfuscate the return packet again using an XOR operation with the byte-stream from +ammag+.
+
+Eventually, the sender (origin node) receives a return packet. It will then generate +ammag+ and +um+ keys for each hop and XOR de-bfuscate the return error iteratively until it reveals the return packet.
+
+==== Failure Messages
+
+The +failuremsg+ is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages[BOLT #4 - Onion Routing - Failure Messages].
+
+A failure message consists of a 2-byte +failure code+ followed by the data applicable to that failute type.
+
+The top byte of the +failure_code+ is a set of binary flags that can be combined (with binary OR):
+
+
+* 0x8000 (BADONION): unparsable onion encrypted by sending peer
+* 0x4000 (PERM): permanent failure (otherwise transient)
+* 0x2000 (NODE): node failure (otherwise channel)
+* 0x1000 (UPDATE): new channel update enclosed
+
+
+The following failure types are currently defined:
+
+include::failure_types_table.asciidoc[]
+
+A detailed list of the current failure types and their format is found in <<appendix_failure_types>>.
+
+=== Conclusion
+
+the Lightning Network's onion routing protocol is adapted from the Sphinx Protocol to better serve the needs of a payment network. As such, it offers a huge improvement in privacy and counter-surveillance compared to the public and transparent Bitcoin blockchain.

10_onion_routing.pdf

@@ -0,0 +1,165 @@
+1. type: PERM|1 (`invalid_realm`)
+
+The `realm` byte was not understood by the processing node.
+
+1. type: NODE|2 (`temporary_node_failure`)
+
+General temporary failure of the processing node.
+
+1. type: PERM|NODE|2 (`permanent_node_failure`)
+
+General permanent failure of the processing node.
+
+1. type: PERM|NODE|3 (`required_node_feature_missing`)
+
+The processing node has a required feature which was not in this onion.
+
+1. type: BADONION|PERM|4 (`invalid_onion_version`)
+2. data:
+   * [`sha256`:`sha256_of_onion`]
+
+The `version` byte was not understood by the processing node.
+
+1. type: BADONION|PERM|5 (`invalid_onion_hmac`)
+2. data:
+   * [`sha256`:`sha256_of_onion`]
+
+The HMAC of the onion was incorrect when it reached the processing node.
+
+1. type: BADONION|PERM|6 (`invalid_onion_key`)
+2. data:
+   * [`sha256`:`sha256_of_onion`]
+
+The ephemeral key was unparsable by the processing node.
+
+1. type: UPDATE|7 (`temporary_channel_failure`)
+2. data:
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The channel from the processing node was unable to handle this HTLC,
+but may be able to handle it, or others, later.
+
+1. type: PERM|8 (`permanent_channel_failure`)
+
+The channel from the processing node is unable to handle any HTLCs.
+
+1. type: PERM|9 (`required_channel_feature_missing`)
+
+The channel from the processing node requires features not present in
+the onion.
+
+1. type: PERM|10 (`unknown_next_peer`)
+
+The onion specified a `short_channel_id` which doesn't match any
+leading from the processing node.
+
+1. type: UPDATE|11 (`amount_below_minimum`)
+2. data:
+   * [`u64`:`htlc_msat`]
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The HTLC amount was below the `htlc_minimum_msat` of the channel from
+the processing node.
+
+1. type: UPDATE|12 (`fee_insufficient`)
+2. data:
+   * [`u64`:`htlc_msat`]
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The fee amount was below that required by the channel from the
+processing node.
+
+1. type: UPDATE|13 (`incorrect_cltv_expiry`)
+2. data:
+   * [`u32`:`cltv_expiry`]
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The `cltv_expiry` does not comply with the `cltv_expiry_delta` required by
+the channel from the processing node: it does not satisfy the following
+requirement:
+
+        cltv_expiry - cltv_expiry_delta >= outgoing_cltv_value
+
+1. type: UPDATE|14 (`expiry_too_soon`)
+2. data:
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The CLTV expiry is too close to the current block height for safe
+handling by the processing node.
+
+1. type: PERM|15 (`incorrect_or_unknown_payment_details`)
+2. data:
+   * [`u64`:`htlc_msat`]
+   * [`u32`:`height`]
+
+The `payment_hash` is unknown to the final node, the `payment_secret` doesn't
+match the `payment_hash`, the amount for that `payment_hash` is incorrect or
+the CLTV expiry of the htlc is too close to the current block height for safe
+handling.
+
+The `htlc_msat` parameter is superfluous, but left in for backwards
+compatibility. The value of `htlc_msat` always matches the amount specified in
+the final hop onion payload. It therefore does not have any informative value to
+the sender. A penultimate hop sending a different amount or expiry for the htlc
+is handled through `final_incorrect_cltv_expiry` and
+`final_incorrect_htlc_amount`.
+
+The `height` parameter is set by the final node to the best known block height
+at the time of receiving the htlc. This can be used by the sender to distinguish
+between sending a payment with the wrong final CLTV expiry and an intermediate
+hop delaying the payment so that the receiver's invoice CLTV delta requirement
+is no longer met.
+
+Note: Originally PERM|16 (`incorrect_payment_amount`) and 17
+(`final_expiry_too_soon`) were used to differentiate incorrect htlc parameters
+from unknown payment hash. Sadly, sending this response allows for probing
+attacks whereby a node which receives an HTLC for forwarding can check guesses
+as to its final destination by sending payments with the same hash but much
+lower values or expiry heights to potential destinations and check the response.
+Care must be taken by implementations to differentiate the previously
+non-permanent case for `final_expiry_too_soon` (17) from the other, permanent
+failures now represented by `incorrect_or_unknown_payment_details` (PERM|15).
+
+1. type: 18 (`final_incorrect_cltv_expiry`)
+2. data:
+   * [`u32`:`cltv_expiry`]
+
+The CLTV expiry in the HTLC doesn't match the value in the onion.
+
+1. type: 19 (`final_incorrect_htlc_amount`)
+2. data:
+   * [`u64`:`incoming_htlc_amt`]
+
+The amount in the HTLC doesn't match the value in the onion.
+
+1. type: UPDATE|20 (`channel_disabled`)
+2. data:
+   * [`u16`:`flags`]
+   * [`u16`:`len`]
+   * [`len*byte`:`channel_update`]
+
+The channel from the processing node has been disabled.
+
+1. type: 21 (`expiry_too_far`)
+
+The CLTV expiry in the HTLC is too far in the future.
+
+1. type: PERM|22 (`invalid_onion_payload`)
+2. data:
+   * [`bigsize`:`type`]
+   * [`u16`:`offset`]
+
+The decrypted onion per-hop payload was not understood by the processing node
+or is incomplete. If the failure can be narrowed down to a specific tlv type in
+the payload, the erring node may include that `type` and its byte `offset` in
+the decrypted byte stream.
+
+1. type: 23 (`mpp_timeout`)
+
+The complete amount of the multi-part payment was not received within a
+reasonable time.