NUT-15: Partial multi-path payments

optional

depends on: NUT-05

---

In this document, we describe how wallets can instruct multiple mints to each pay a partial amount of a bolt11 Lightning invoice. The full payment is composed of partial payments (MPP) from multiple multi-path payments from different Lightning nodes. This way, wallets can pay a larger Lightning invoice combined from multiple smaller balances on different mints. Due to the atomic nature of MPP, either all payments will be successful or all of them will fail.

The Lightning backend of the mint must support paying a partial amount of an Invoice and multi-path payments (MPP, see BOLT 4). For example, the mint's Lightning node must be able to pay 50 sats of a 100 sat bolt11 invoice. The receiving Lightning node must support receiving multi-path payments as well.

Multimint payment execution

Alice's wallet coordinates multiple MPPs on different mints that support the feature (see below for the indicated setting). For a given Lightning invoice of amount_total, Alice splits the total amount into several partial amounts amount_total = amount_1 + amount_2 + ... that each must be covered by her individual balances on the mints she wants to use for the payment. She constructs multiple PostMeltQuoteBolt11Request's that each include the corresponding partial amount in the payment option (see below) that she sends to all mints she wants to use for the payment. The mints then respond with a normal PostMeltQuoteBolt11Response (see NUT-05). Alice proceeds to pay the melt requests at each mint simultaneously. When all mints have sent out the partial Lightning payment, she receives a successful response from all mints individually.

Melt quote

To request a melt quote with a partial amount, the wallet of Alice makes a POST /v1/melt/quote/bolt11 similar to NUT-05.

POST https://mint.host:3338/v1/melt/quote/bolt11

The wallet Alice includes the following PostMeltQuoteBolt11Request data in its request which includes an additional (and optional) options object compared to the standard request in NUT-05:

{
  "request": <str>,
  "unit": <str_enum["sat"]>,
  "options": {
    "mpp": {
      "amount": <int>
    }
  }
}

Here, request is the bolt11 Lightning invoice to be paid, unit is the unit the wallet would like to pay with, and amount is the amount for the requested payment. The wallet then pays the returned melt quote the same way as in NUT-05.

Settings

The settings returned in the info endpoint (NUT-06) indicate that a mint supports this NUT. The mint MUST indicate each method and unit that supports mpp. It can indicate this in an array of objects for multiple method and unit pairs and the boolean flag mpp set to true.

MultipathPaymentSetting is of the form:

{
  [
    {
      "method": <str>,
      "unit": <str>,
      "mpp": <bool>
    },
    ...
  ]
}

Example MultipathPaymentSetting:

{
  "15": {
    [
      {
        "method": "bolt11",
        "unit": "sat",
        "mpp": true
      },
      {
        "method": "bolt11",
        "unit": "usd",
        "mpp": true
      },
    ]
  }
}