renepay: add help for renepay & renepaystatus

Signed-off-by: Lagrang3 <[email protected]>

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 \

doc/index.rst

@@ -99,6 +99,8 @@ Core Lightning Documentation
    lightning-preapproveinvoice <lightning-preapproveinvoice.7.md>
    lightning-preapprovekeysend <lightning-preapprovekeysend.7.md>
    lightning-recoverchannel <lightning-recoverchannel.7.md>
+   lightning-renepay <lightning-renepay.7.md>
+   lightning-renepaystatus <lightning-renepaystatus.7.md>
    lightning-reserveinputs <lightning-reserveinputs.7.md>
    lightning-sendcustommsg <lightning-sendcustommsg.7.md>
    lightning-sendinvoice <lightning-sendinvoice.7.md>

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 <<[email protected]>> is mainly responsible.
+
+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>
+[comment]: # ( SHA256STAMP:505a2ea336078020826b5897f2db02d4c4e0e03a9561170458afae008e47e06e)

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 <<[email protected]>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-renepay(7), lightning-listpays(7).
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:3dfae7499b76853c08d307d8d723933ab680f6827ff079569af97ba2dda03833)

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"
+    }
+  }
+}

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"
+            }
+          }
+        }
+      }
+    }
+  }
+}