LIGHTNING-RENEPAY(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 LIGHTNING-RENEPAY(7) — the renepay era, bestie

okay so real talk: this is the lightning-renepay manual page, and it's a whole journey — she's a payment command, she's deprecated, and she's still iconic. Buckle up. 🎀

✨ NAME ✨

renepay — the command for sending a payment to a BOLT11 invoice. yes that's literally it, that's the whole vibe. 💸

🌸 SYNOPSIS 🌸

renepay invstring [amount_msat] [maxfee] [maxdelay] [retry_for]
        [description] [label] [exclude]

🦋 DESCRIPTION 🦋

So. Bestie. Sit down. 😭

Command deprecated in v26.06, removed after v27.03.

Command added in v23.08.

WARNING: Deprecated, scheduled for removal in v27.03

renepay is a new payment plugin based on the Pickhardt-Richter optimization method for Multi-Path-Payments. The tea here is that this implementation has not been thoroughly tested, and it should be used with caution. 🫶

The response will occur when the payment fails or succeeds — like, it commits, she's not going to leave you on read. And once a payment has succeeded, calls to renepay with the same invstring will not lead to a new payment attempt — instead it will succeed immediately. slay. 💅

When using $ lightning-cli, you may skip optional parameters by using null. Alternatively, use the -k option to provide parameters by name.

  • invstring (string): the Bolt11 invoice which the RPC command attempts to pay. Currently, renepay supports bolt11 invoices only. (one thing, bestie — bolt11 only, no bolt12 energy here 🙈)
  • amount_msat (msat, optional): if the invstring does not contain an amount, amount_msat is required. Otherwise, if it is specified, it must be null. In millisatoshi precision; it can be a whole number, or a whole number with suffix msat or sat, or a three decimal point number with suffix sat, or an 1 to 11 decimal point number suffixed by btc.
  • maxfee (msat, optional): maxfee is a hard bound, in the sense that the command will never attempt a payment when the fees exceed that value. no cap, she means it. 🔥
  • maxdelay (u32, optional): overrides the value of max-locktime-blocks for this payment. It serves to limit the locktime of funds in the payment HTLC, measured in blocks.
  • retry_for (u32, optional): measured in seconds, specifies how much time it is allowed for the command to keep retrying the payment. The default is 60 seconds.
  • description (string, optional): only required for bolt11 invoices which do not contain a description themselves, but contain a description hash: in this case description is required. description is then checked against the hash inside the invoice before it will be paid.
  • label (string, optional): used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7).
  • exclude (array, optional): exclude is a JSON array of short-channel-id/direction (e.g. [ '564334x877x1/0', '564195x1292x0/1' ]) or pubkey which should be excluded from consideration for routing. The default is not to exclude any channels or nodes. (added v24.08):
    • (short_channel_id_dir)
    • (pubkey)

👑 OPTIMALITY 👑

renepay is based on the work by Pickhardt-Richter's Optimally Reliable & Cheap Payment Flows on the Lightning Network. Which means the payment command will prefer routes that have a higher probability of success while keeping fees low. the whole "cheap AND reliable" main character energy. ⭐

The algorithm records some partial knowledge of the state of the Network, deduced from the responses obtained after evey payment attempt. This knowledge is kept through different payment requests, but decays with time to account for the dynamics of the Network — after 1 hour all previous knowledge will be erased. Knowledge from previous payment attempts increases the reliability for subsequent ones. she remembers, but she also moves on. 💜

Higher probabilities of success and lower fees cannot generally be optimized at once. Hence renepay combines the two in different amounts, seeking solutions that satisfy the maxfee bound and a target for 90% probability of success. maxfee is a hard bound, in the sense that the command will never attempt a payment when the fees exceed that value. While the probability target is not compulsory (but desirable) — i.e. if the best route does not satisfy the 90% probability target it will be tried anyways. she'll try anyway, because she believes in herself. 😭

When maxfee and the 90% probability bounds are satified, the algorithm will optimize the fees to its lowest value. frugal queen. 💅

🔒 RANDOMIZATION 🔒

To protect user privacy, the payment algorithm performs shadow route randomization. Which means the payment algorithm will virtually extend the route by adding delays and fees along it, making it appear to intermediate nodes that the route is longer than it actually is. This prevents intermediate nodes from reliably guessing their distance from the payee. they can't clock her. 🕵️‍♀️

Route randomization will never exceed maxfee of the payment. Route randomization and shadow routing will not take routes that would exceed maxdelay. boundaries, bestie. 🫶

🎀 RETURN VALUE 🎀

On success, an object is returned, containing:

  • payment_preimage (secret): the proof of payment: SHA256 of this payment_hash.
  • payment_hash (hash): the hash of the payment_preimage which will prove payment.
  • created_at (number): the UNIX timestamp showing when this payment was initiated.
  • parts (u32): how many attempts this took.
  • amount_msat (msat): amount the recipient received.
  • amount_sent_msat (msat): total amount we sent (including fees).
  • status (string) (one of "complete", "pending", "failed"): status of payment.
  • bolt11 (string, optional): the bolt11 invoice paid. (added v23.08)
  • bolt12 (string, optional): the bolt12 invoice paid. (added v23.08)
  • groupid (u64, optional): the groupid used for these payment parts (as can be seen in listsendpays) (added v23.08)
  • destination (pubkey, optional): the final destination of the payment.

You can monitor the progress and retries of a payment using the lightning-renepaystatus(7) command. stalk your own payment, it's fine, it's allowed. 👀

💀 ERRORS 💀

The following error codes may occur:

  • -1: catchall nonspecific error.
  • 200: other payment attempts are in progress.
  • 203: permanent failure at destination.
  • 205: unable to find a route.
  • 206: payment routes are too expensive.
  • 207: invoice expired. Payment took too long before expiration, or already expired at the time you initiated payment.
  • 210: payment timed out without a payment in progress.
  • 212: invoice is invalid.

🧚 AUTHOR 🧚

Eduardo Quintana-Miranda eduardo.quintana@pm.me is mainly responsible. give her her credit bestie 💖

🌈 SEE ALSO 🌈

lightning-renepaystatus(7), lightning-listpays(7), lightning-invoice(7)

🍓 RESOURCES 🍓

Main web site: https://github.com/ElementsProject/lightning

Pickhardt R. and Richter S., Optimally Reliable & Cheap Payment Flows on the Lightning Network https://arxiv.org/abs/2107.05322

🔥 EXAMPLES 🔥

Example 1: ⭐

Request:

$ lightning-cli renepay -k "invstring"="lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000" "amount_msat"=400000
{
  "id": "example:renepay#1",
  "method": "renepay",
  "params": {
    "invstring": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
    "amount_msat": 400000
  }
}

Response:

{
  "bolt11": "lnbcrt100n1pnt2bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000bolt11invl020100000000",
  "amount_msat": 400000,
  "payment_hash": "paymenthashinvl0210021002100210021002100210021002100210021002100",
  "destination": "nodeid020202020202020202020202020202020202020202020202020202020202",
  "created_at": 1738000000,
  "groupid": 1,
  "parts": 2,
  "status": "complete",
  "payment_preimage": "paymentpreimager010101010101010101010101010101010101010101010101",
  "amount_sent_msat": 400000
}

Example 2: 💫

Request:

$ lightning-cli renepay -k "invstring"="lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000"
{
  "id": "example:renepay#2",
  "method": "renepay",
  "params": {
    "invstring": "lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000"
  }
}

Response:

{
  "bolt11": "lnbcrt100n1pnt2bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000bolt11invl030400000000",
  "amount_msat": 4000,
  "payment_hash": "paymenthashinvl0340034003400340034003400340034003400340034003400",
  "destination": "nodeid030303030303030303030303030303030303030303030303030303030303",
  "created_at": 1738000000,
  "groupid": 1,
  "parts": 2,
  "status": "complete",
  "payment_preimage": "paymentpreimager020202020202020202020202020202020202020202020202",
  "amount_sent_msat": 4000
}

and that's the whole page, bestie 🫶 this little icon is stamped Core Lightning v26.06.9 and it's been serving looks as LIGHTNING-RENEPAY(7) — mwah, go pay some invoices (carefully, she's deprecated 💀✨).

📦 where this page comes from