From 961ad21281b6976ce1fc75c77913039db69f58b9 Mon Sep 17 00:00:00 2001 From: Lagrang3 Date: Mon, 7 Aug 2023 10:30:20 +0100 Subject: [PATCH] renepay: add help for renepay & renepaystatus Signed-off-by: Lagrang3 --- doc/Makefile | 2 + doc/index.rst | 2 + doc/lightning-renepay.7.md | 152 ++++++++++++++++++++++++++ doc/lightning-renepaystatus.7.md | 55 ++++++++++ doc/schemas/renepay.schema.json | 54 +++++++++ doc/schemas/renepaystatus.schema.json | 83 ++++++++++++++ 6 files changed, 348 insertions(+) create mode 100644 doc/lightning-renepay.7.md create mode 100644 doc/lightning-renepaystatus.7.md create mode 100644 doc/schemas/renepay.schema.json create mode 100644 doc/schemas/renepaystatus.schema.json diff --git a/doc/Makefile b/doc/Makefile index 021a2eb2d..692203230 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -87,6 +87,8 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-preapproveinvoice.7 \ doc/lightning-preapprovekeysend.7 \ doc/lightning-recoverchannel.7 \ + doc/lightning-renepay.7 \ + doc/lightning-renepaystatus.7 \ doc/lightning-reserveinputs.7 \ doc/lightning-sendinvoice.7 \ doc/lightning-sendonion.7 \ diff --git a/doc/index.rst b/doc/index.rst index ebbb5412f..d59d7700c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -99,6 +99,8 @@ Core Lightning Documentation lightning-preapproveinvoice lightning-preapprovekeysend lightning-recoverchannel + lightning-renepay + lightning-renepaystatus lightning-reserveinputs lightning-sendcustommsg lightning-sendinvoice diff --git a/doc/lightning-renepay.7.md b/doc/lightning-renepay.7.md new file mode 100644 index 000000000..826ae9bbb --- /dev/null +++ b/doc/lightning-renepay.7.md @@ -0,0 +1,152 @@ +lightning-renepay -- Command for sending a payment to a BOLT11 invoice +====================================================================== + +SYNOPSIS +-------- + +**renepay** *invstring* [*amount\_msat*] [*maxfee*] [*maxdelay*] +[*retry\_for*] [*description*] [*label*] + + +DESCRIPTION +----------- + +**renepay** is a new payment plugin based on Pickhardt-Richter optimization +method for Multi-Path-Payments. This implementation has not been thoroughly +tested and it should be used with caution. + +The **renepay** RPC command attempts to pay the invoice specified +as *invstring*. Currently, **renepay** supports bolt11 invoices only. + +The response will occur when the payment fails or succeeds. Once a +payment has succeeded, calls to **renepay** with the same *invstring* +will not lead to a new payment attempt, but instead it will succeed immediately. + +If the *invstring* does not contain an amount, +*amount\_msat* is required, otherwise if it is specified +it must be *null*. *amount\_msat* is 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* limits how much is paid fees and it is measured in millisatoshi +by default, but also in this case the unit can be specified with a suffix: *msat*, *sat* or *btc*. +The default value is 5 sats or 0.5% whichever is higher. + +*maxdelay* 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* measured in seconds (default: 60) specifies how much time it is +allowed for the command to keep retrying the payment. + +*description* is 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. + +The *label* field is used to attach a label to payments, and is returned +in lightning-listpays(7) and lightning-listsendpays(7). + +When using *lightning-cli*, you may skip optional parameters by using +*null*. Alternatively, use **-k** option to provide parameters by name. + + +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 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. + +Higher probabilities of success and lower fees cannot generally by optimized at +once. Hence **renepay** combines the two in different amounts seeking solutions +that satisfy *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. + +When *maxfee* and the 90% probability bounds are satified, the algorithm will +optimize the fees to its lowest value. + + +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. + +Route randomization will never exceed *maxfee* of the payment. +Route randomization and shadow routing will not take routes that would +exceed *maxdelay*. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +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): status of payment (one of "complete", "pending", "failed") +- **destination** (pubkey, optional): the final destination of the payment + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +You can monitor the progress and retries of a payment using the +lightning-renepaystatus(7) command. + +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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-renepaystatus(7), lightning-listpays(7), lightning-invoice(7). + +RESOURCES +--------- + +- Main web site: +- Pickhardt R. and Richter S., *Optimally Reliable & Cheap Payment Flows on the Lightning Network* + +[comment]: # ( SHA256STAMP:505a2ea336078020826b5897f2db02d4c4e0e03a9561170458afae008e47e06e) diff --git a/doc/lightning-renepaystatus.7.md b/doc/lightning-renepaystatus.7.md new file mode 100644 index 000000000..df78aabe7 --- /dev/null +++ b/doc/lightning-renepaystatus.7.md @@ -0,0 +1,55 @@ +lightning-renepaystatus -- Command for quering the status of previous renepay attempts +====================================================================================== + +SYNOPSIS +-------- + +**renepaystatus** [*invstring*] + + +DESCRIPTION +----------- + +The **renepaystatus** RPC command queries the payment plugin **renepay** +for the status of previous payment attempts. +If *invstring* is specified, the command will return a list of payment attempts +whose invoice matches *invstring*, otherwise all payments with be listed. +This command always succeeds. + +RETURN VALUE +------------ + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **paystatus** is returned. It is an array of objects, where each object contains: + +- **bolt11** (string): invoice string BOLT11 +- **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 +- **groupid** (u32): the id for this payment attempt +- **amount\_msat** (msat): amount the recipient received +- **status** (string): status of payment (one of "complete", "pending", "failed") +- **notes** (array of strings): a list of messages for debugging purposes: + - a message generated by renepay +- **payment\_preimage** (secret, optional): the proof of payment: SHA256 of this **payment\_hash** (for completed payments only) +- **parts** (u32, optional): how many attempts this took +- **amount\_sent\_msat** (msat, optional): total amount we sent including fees (for completed payments only) +- **destination** (pubkey, optional): the final destination of the payment + +[comment]: # (GENERATE-FROM-SCHEMA-END) + +AUTHOR +------ + +Eduardo Quintana-Miranda <> is mainly responsible. + +SEE ALSO +-------- + +lightning-renepay(7), lightning-listpays(7). + +RESOURCES +--------- + +Main web site: + +[comment]: # ( SHA256STAMP:3dfae7499b76853c08d307d8d723933ab680f6827ff079569af97ba2dda03833) diff --git a/doc/schemas/renepay.schema.json b/doc/schemas/renepay.schema.json new file mode 100644 index 000000000..2700a5e92 --- /dev/null +++ b/doc/schemas/renepay.schema.json @@ -0,0 +1,54 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "added": "v23.08", + "type": "object", + "additionalProperties": false, + "required": [ + "payment_preimage", + "payment_hash", + "created_at", + "parts", + "amount_msat", + "amount_sent_msat", + "status" + ], + "properties": { + "payment_preimage": { + "type": "secret", + "description": "the proof of payment: SHA256 of this **payment_hash**" + }, + "payment_hash": { + "type": "hash", + "description": "the hash of the *payment_preimage* which will prove payment" + }, + "created_at": { + "type": "number", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "parts": { + "type": "u32", + "description": "how many attempts this took" + }, + "amount_msat": { + "type": "msat", + "description": "amount the recipient received" + }, + "amount_sent_msat": { + "type": "msat", + "description": "total amount we sent (including fees)" + }, + "status": { + "type": "string", + "enum": [ + "complete", + "pending", + "failed" + ], + "description": "status of payment" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment" + } + } +} diff --git a/doc/schemas/renepaystatus.schema.json b/doc/schemas/renepaystatus.schema.json new file mode 100644 index 000000000..03da45dc1 --- /dev/null +++ b/doc/schemas/renepaystatus.schema.json @@ -0,0 +1,83 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "added": "v23.08", + "type": "object", + "additionalProperties": false, + "required": [ + "paystatus" + ], + "properties": { + "paystatus": { + "type": "array", + "description": "a list of payments attempted by renepay", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "bolt11", + "payment_hash", + "created_at", + "groupid", + "amount_msat", + "status", + "notes" + ], + "properties": { + "bolt11": { + "type": "string", + "description": "invoice string BOLT11" + }, + "payment_preimage": { + "type": "secret", + "description": "the proof of payment: SHA256 of this **payment_hash** (for completed payments only)" + }, + "payment_hash": { + "type": "hash", + "description": "the hash of the *payment_preimage* which will prove payment" + }, + "created_at": { + "type": "number", + "description": "the UNIX timestamp showing when this payment was initiated" + }, + "groupid": { + "type": "u32", + "description": "the id for this payment attempt" + }, + "parts": { + "type": "u32", + "description": "how many attempts this took" + }, + "amount_msat": { + "type": "msat", + "description": "amount the recipient received" + }, + "amount_sent_msat": { + "type": "msat", + "description": "total amount we sent including fees (for completed payments only)" + }, + "status": { + "type": "string", + "enum": [ + "complete", + "pending", + "failed" + ], + "description": "status of payment" + }, + "destination": { + "type": "pubkey", + "description": "the final destination of the payment" + }, + "notes": { + "type": "array", + "description": "a list of messages for debugging purposes", + "items": { + "type": "string", + "description": "a message generated by renepay" + } + } + } + } + } + } +}