Merge pull request #59 from tnull/2025-03-add-bolt12-support-for-blip-51

Update bLIP-51 to add BOLT-12 support

Author: TheBlueMatt

blip-0051.md

@@ -197,6 +197,13 @@ The client MUST check if [option_support_large_channel](https://bitcoinops.org/e
       "order_total_sat": "2008888",
       "invoice" : "lnbc252u1p3aht9ysp580g4633gd2x9lc5al0wd8wx0mpn9748jeyz46kqjrpxn52uhfpjqpp5qgf67tcqmuqehzgjm8mzya90h73deafvr4m5705l5u5l4r05l8cqdpud3h8ymm4w3jhytnpwpczqmt0de6xsmre2pkxzm3qydmkzdjrdev9s7zhgfaqxqyjw5qcqpjrzjqt6xptnd85lpqnu2lefq4cx070v5cdwzh2xlvmdgnu7gqp4zvkus5zapryqqx9qqqyqqqqqqqqqqqcsq9q9qyysgqen77vu8xqjelum24hgjpgfdgfgx4q0nehhalcmuggt32japhjuksq9jv6eksjfnppm4hrzsgyxt8y8xacxut9qv3fpyetz8t7tsymygq8yzn05"
     },
+    "bolt12": {
+      "state" : "EXPECT_PAYMENT",
+      "expires_at": "2025-01-01T00:00:00Z",
+      "fee_total_sat": "8888",
+      "order_total_sat": "200888",
+      "offer": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrcgqvp3pwq2q3shxerxzzfqyxdxxkjqxfpt9tz94zj79m4n99kwjddq92uqryuwsu4nt0t3lthfq02jzqla96dtkf4rew8edxw0p85swe89wd8ldekdl5j262n76qyl2qgzajm08clzr74z6ssy0qlvvp9f5kvrxf27yz4pcy99jge69kxu8ttsqt8gw8jsk5397zvvdf4lfd52paf73thcg6xf57xmvtdrwny5mn2r4jw2d5jzalqrq537mmt6u9qpqytzzql6zemrme07jqqwtza76lldcj9wgc0ccd4d2w584cdcx6szsuupvy"
+    },
     "onchain": {
       "state": "EXPECT_PAYMENT",
       "expires_at": "2015-01-25T19:29:44.612Z",
@@ -302,6 +309,13 @@ This section describes the `payment` object returned by `lsps1.create_order` and
     "order_total_sat": "200888",
     "invoice": "lnbc252u1p3aht9ysp580g4633gd2x9lc5al0wd8wx0mpn9748jeyz46kqjrpxn52uhfpjqpp5qgf67tcqmuqehzgjm8mzya90h73deafvr4m5705l5u5l4r05l8cqdpud3h8ymm4w3jhytnpwpczqmt0de6xsmre2pkxzm3qydmkzdjrdev9s7zhgfaqxqyjw5qcqpjrzjqt6xptnd85lpqnu2lefq4cx070v5cdwzh2xlvmdgnu7gqp4zvkus5zapryqqx9qqqyqqqqqqqqqqqcsq9q9qyysgqen77vu8xqjelum24hgjpgfdgfgx4q0nehhalcmuggt32japhjuksq9jv6eksjfnppm4hrzsgyxt8y8xacxut9qv3fpyetz8t7tsymygq8yzn05"
   },
+  "bolt12": {
+    "state" : "EXPECT_PAYMENT",
+    "expires_at": "2025-01-01T00:00:00Z",
+    "fee_total_sat": "8888",
+    "order_total_sat": "200888",
+    "offer": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrcgqvp3pwq2q3shxerxzzfqyxdxxkjqxfpt9tz94zj79m4n99kwjddq92uqryuwsu4nt0t3lthfq02jzqla96dtkf4rew8edxw0p85swe89wd8ldekdl5j262n76qyl2qgzajm08clzr74z6ssy0qlvvp9f5kvrxf27yz4pcy99jge69kxu8ttsqt8gw8jsk5397zvvdf4lfd52paf73thcg6xf57xmvtdrwny5mn2r4jw2d5jzalqrq537mmt6u9qpqytzzql6zemrme07jqqwtza76lldcj9wgc0ccd4d2w584cdcx6szsuupvy"
+  },
   "onchain": {
     "state": "EXPECT_PAYMENT",
     "expires_at": "2025-01-01T00:00:00Z",
@@ -378,7 +392,48 @@ The LSP MAY omit payment options.
     - MUST reject the payment.
     - MUST set the `payment.state` to `CANCELLED`.
 
-#### 3.2 Onchain payments
+#### 3.2 Lightning Payments using BOLT-12
+
+```json
+{
+    "state" : "EXPECT_PAYMENT",
+    "expires_at": "2025-01-01T00:00:00Z",
+    "fee_total_sat": "8888",
+    "order_total_sat": "200888",
+    "offer": "lno1qgsqvgnwgcg35z6ee2h3yczraddm72xrfua9uve2rlrm9deu7xyfzrcgqvp3pwq2q3shxerxzzfqyxdxxkjqxfpt9tz94zj79m4n99kwjddq92uqryuwsu4nt0t3lthfq02jzqla96dtkf4rew8edxw0p85swe89wd8ldekdl5j262n76qyl2qgzajm08clzr74z6ssy0qlvvp9f5kvrxf27yz4pcy99jge69kxu8ttsqt8gw8jsk5397zvvdf4lfd52paf73thcg6xf57xmvtdrwny5mn2r4jw2d5jzalqrq537mmt6u9qpqytzzql6zemrme07jqqwtza76lldcj9wgc0ccd4d2w584cdcx6szsuupvy"
+}
+```
+
+- `state`
+    - `EXPECT_PAYMENT` Payment expected.
+    - `HOLD` Lighting payment arrived, preimage NOT released.
+    - `PAID`  When the has been preimage released
+    - `REFUNDED` Lightning payment has been refunded.
+- `expires_at` <[LSPS0.datetime][]> The timestamp at which the payment option for this order expires
+- `fee_total_sat` <[LSPS0.sat][]> The total fee the LSP will charge to open this channel in satoshi.
+- `order_total_sat` <[LSPS0.sat][]> What the client needs to pay in total to open the requested channel.
+    - MUST be the `fee_total_sat` plus the `client_balance_sat` requested in satoshi.
+- `offer <string>`
+    - MUST be a [Lightning BOLT 12 offer](https://github.com/lightning/bolts/blob/master/12-offer-encoding.md) for the number of `order_total_sat`.
+    - MUST be at most 2048 characters long.
+
+**Client**
+
+- MAY pay the `offer`.
+- MAY pull `lsps1.get_order` to check the success of the payment.
+- The client gets refunded automatically in case the channel open failed, the order expires, or just before the payment times out.
+
+**LSP**
+
+- MUST change the `payment.state` to `HOLD` when the payment arrived.
+- If the channel has been opened successfully
+    - MUST release the preimage and therefore complete the payment.
+    - MUST set the `payment.state` to `PAID`.
+- If the channel failed to open or the order expired or shortly before the payment times out:
+    - MUST reject the payment.
+    - MUST set the `payment.state` to `CANCELLED`.
+
+#### 3.3 Onchain payments
 
 Onchain payments dictionary MUST be omitted if the client didn't provide a `refund_onchain_address` 
 and/or the LSP disabled onchain payments.