mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-20 13:54:36 +01:00
Code Issues Projects Releases Wiki Activity

renepay: add help for renepay & renepaystatus

Browse source 
Signed-off-by: Lagrang3 <eduardo.quintana@pm.me>
This commit is contained in:
Lagrang3 2023-08-07 10:30:20 +01:00 • committed by Rusty Russell
parent dabd6c6b70
commit 961ad21281
6 changed files with 348 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/Makefile
View file

@ -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 \

2
doc/index.rst
View file

@ -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>

152
doc/lightning-renepay.7.md Normal file
View file

@ -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 <<eduardo.quintana@pm.me>> 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)

55
doc/lightning-renepaystatus.7.md Normal file
View file

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

54
doc/schemas/renepay.schema.json Normal file
View file

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

83
doc/schemas/renepaystatus.schema.json Normal file
View file

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