Add payment metadata to payment request

Author: joostjager

04-onion-routing.md

@@ -263,6 +263,9 @@ It is formatted according to the Type-Length-Value format defined in [BOLT #1](0
     2. data:
         * [`32*byte`:`payment_secret`]
         * [`tu64`:`total_msat`]
+    1. type: 10 (`payment_metadata`)
+    2. data:
+        * [`len*byte`:`payment_metadata`]
 
 ### Requirements
 

11-payment-encoding.md

@@ -140,6 +140,8 @@ Currently defined tagged fields are:
 * `p` (1): `data_length` 52. 256-bit SHA256 payment_hash. Preimage of this provides proof of payment.
 * `s` (16): `data_length` 52. This 256-bit secret prevents forwarding nodes from probing the payment recipient.
 * `d` (13): `data_length` variable. Short description of purpose of payment (UTF-8), e.g. '1 cup of coffee' or 'ナンセンス 1杯'
+* `m` (14): `data_length` variable. Additional metadata to attach to the
+  payment.
 * `n` (19): `data_length` 53. 33-byte public key of the payee node
 * `h` (23): `data_length` 52. 256-bit description of purpose of payment (SHA256). This is used to commit to an associated description that is over 639 bytes, but the transport mechanism for the description in that case is transport specific and not defined here.
 * `x` (6): `data_length` variable. `expiry` time in seconds (big-endian). Default is 3600 (1 hour) if not specified.
@@ -216,6 +218,8 @@ A reader:
     - MUST use that as [`payment_secret`](04-onion-routing.md#tlv_payload-payload-format)
   - if the `c` field (`min_final_cltv_expiry`) is not provided:
     - MUST use an expiry delta of at least 18 when making the payment
+  - if the `m` field is provided, it MUST send the contents of this field in the
+    final hop payload as tlv field 10.
 
 ### Rationale
 
@@ -235,6 +239,9 @@ by which the description is served is as-yet unspecified and will
 probably be transport dependent. The `h` format could change in the future,
 by changing the length, so readers ignore it if it's not 256 bits.
 
+The `m` field allows metadata to be attached to the payment. This supports
+spontaneous payments and other applications where the recipient doesn't keep any context for the payment.
+
 The `n` field can be used to explicitly specify the destination node ID,
 instead of requiring signature recovery.