BOLT 04: Add failure code for invalid payload. (#627)

The specification currently doesn't specify the case where the onion per-hop
payload can't be correctly decoded.

This is somewhat fine with the fixed frames because every field of the payload
can always be interpreted as a numeric value from the input bytes, so it leads
to application errors in upper layers when those values are actually
interpreted (and we realize that for instance we have an invalid
short_channel_id` value).

With variable-length tlv streams in the onion payloads, we will encounter
decoding errors (duplicate tlv types, invalid ordering, etc) and the spec
should define the failure code to use in that case.

04-onion-routing.md

@@ -875,6 +875,16 @@ The channel from the processing node has been disabled.
 
 The CLTV expiry in the HTLC is too far in the future.
 
+1. type: PERM|22 (`invalid_onion_payload`)
+2. data:
+   * [`varint`:`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.
+
 ### Requirements
 
 An _erring node_:
@@ -886,6 +896,9 @@ An _erring node_:
 Any _erring node_ MAY:
   - if the `realm` byte is unknown:
     - return an `invalid_realm` error.
+  - if the per-hop payload in the onion is invalid (e.g. it is not a valid tlv stream)
+  or is missing required information (e.g. the amount was not specified):
+    - return an `invalid_onion_payload` error.
   - if an otherwise unspecified transient error occurs for the entire node:
     - return a `temporary_node_failure` error.
   - if an otherwise unspecified permanent error occurs for the entire node: