Add payment metadata to payment request

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: 14 (`payment_metadata`)
+    2. data:
+        * [`...*byte`:`payment_metadata`]
 
 ### Requirements
 

09-features.md

@@ -41,6 +41,7 @@ The Context column decodes as follows:
 | 20/21 | `option_anchor_outputs`          | Anchor outputs                                            | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)         |
 | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions   | IN       |                   | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]|
 | 26/27 | `option_shutdown_anysegwit`         | Future segwit versions allowed in `shutdown`              | IN       |                   | [BOLT #2][bolt02-shutdown]   |
+| 48    | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields)
 
 ## Definitions
 

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` (27): `data_length` variable. Additional metadata to attach to the
+  payment. Note that implementations may apply limits to the size of this field because the size of the hop payload itself is limited as well.
 * `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,7 +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 an `m` field is provided:
+    - MUST use that as [`payment_metadata`](04-onion-routing.md#tlv_payload-payload-format)
 ### Rationale
 
 The type-and-length format allows future extensions to be backward
@@ -235,6 +238,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
+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.
 
@@ -704,6 +710,36 @@ Breakdown:
 * `z599y53s3ujmcfjp5xrdap68qxymkqphwsexhmhr8wdz5usdzkzrse33chw6dlp3jhuhge9ley7j2ayx36kawe7kmgg8sv5ugdyusdcq`: signature
 * `zn8z9x`: Bech32 checksum
 
+> ### Please send 0.01 BTC with payment metadata 0x01fafaf0
+> lnbc10m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp9wpshjmt9de6zqmt9w3skgct5vysxjmnnd9jx2mq8q8a04uqnp4q0n326hr8v9zprg8gsvezcch06gfaqqhde2aj730yg0durunfhv66sp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9q2gqqqqqqsgqy9gw6ymamd20jumvdgpfphkhp8fzhhdhycw36egcmla5vlrtrmhs9t7psfy3hkkdqzm9eq64fjg558znccds5nhsfmxveha5xe0dykgpspdha0
+
+Breakdown:
+
+* `lnbc`: prefix, Lightning on Bitcoin mainnet
+* `10m`: amount (10 milli-bitcoin)
+* `1`: Bech32 separator
+* `pvjluez`: timestamp (1496314658)
+* `p`: payment hash
+  * `p5`: `data_length` (`p` = 1, `5` = 20; 1 * 32 + 20 == 52)
+  * `qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypq`: payment hash 0001020304050607080900010203040506070809000102030405060708090102
+* `d`: short description
+  * `p9`: `data_length` (`p` = 1, `9` = 5; 1 * 32 + 5 == 37)
+  * `wpshjmt9de6zqmt9w3skgct5vysxjmnnd9jx2`: 'payment metadata inside'
+* `m`: metadata
+  * `q8`: `data_length` (`q` = 0, `8` = 7; 0 * 32 + 7 == 7)
+  * `q8a04uq`: 0x01fafaf0
+* `n`: node id
+  * `p4`: `data_length` (`p` = 1, `4` = 21; 1 * 32 + 21 == 53)
+  * `q0n326hr8v9zprg8gsvezcch06gfaqqhde2aj730yg0durunfhv66`
+* `s`: payment secret
+  * `p5`: `data_length` (`p` = 1, `5` = 20; 1 * 32 + 20 == 52)
+  * `zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs`: 0x1111111111111111111111111111111111111111111111111111111111111111
+* `9`: features
+  * `q2`: `data_length` (`q` = 0, `2` = 10; 0 * 32 + 10 == 10)
+  * `gqqqqqqsgq`: [b01000000000000000000000000000000000100000100000000] = 8 + 14 + 48
+* `y9gw6ymamd20jumvdgpfphkhp8fzhhdhycw36egcmla5vlrtrmhs9t7psfy3hkkdqzm9eq64fjg558znccds5nhsfmxveha5xe0dykgp`: signature
+* `spdha0`: Bech32 checksum
+
 # Examples of Invalid Invoices
 
 > # Same, but adding invalid unknown feature 100