From 7443bf5ed58206af427615ac2a4b78de5afd34ac Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Sun, 11 Mar 2018 14:35:41 +0000 Subject: [PATCH] doc: Update for latest 'pay' command. --- doc/lightning-pay.7 | 31 +++++++++++++++++++++++-------- doc/lightning-pay.7.txt | 18 ++++++++++++++++-- 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index b0890be57..2cce4e182 100644 --- a/doc/lightning-pay.7 +++ b/doc/lightning-pay.7 @@ -2,12 +2,12 @@ .\" Title: lightning-pay .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 02/26/2018 +.\" Date: 03/16/2018 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNING\-PAY" "7" "02/26/2018" "\ \&" "\ \&" +.TH "LIGHTNING\-PAY" "7" "03/16/2018" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -31,7 +31,7 @@ lightning-pay \- Protocol for sending a payment to a BOLT11 invoice .SH "SYNOPSIS" .sp -\fBpay\fR \fIbolt11\fR [\fImsatoshi\fR] [\fIdescription\fR] [\fIriskfactor\fR] [\fImaxfeepercent\fR] +\fBpay\fR \fIbolt11\fR [\fImsatoshi\fR] [\fIdescription\fR] [\fIriskfactor\fR] [\fImaxfeepercent\fR] [\fIretry_for\fR] .SH "DESCRIPTION" .sp The \fBpay\fR RPC command attempts to find a route to the given destination, and send the funds it asks for\&. If the \fIbolt11\fR does not contain an amount, \fImsatoshi\fR is required, otherwise if it is specified it must be \fInull\fR\&. If \fIbolt11\fR contains a description hash (\fIh\fR field) \fIdescription\fR is required, otherwise it is unused\&. The \fIriskfactor\fR is described in detail in lightning\-getroute(7), and defaults to 1\&.0\&. The \fImaxfeepercent\fR limits the money paid in fees, and defaults to 0\&.5\&. The \(oqmaxfeepercent\(cq is a percentage of the amount that is to be paid\&. @@ -40,6 +40,8 @@ The \fBpay\fR RPC command will randomize routes slightly, as long as the route a .sp The response will occur when the payment fails or succeeds\&. Once a payment has succeeded, calls to \fBpay\fR with the same \fIbolt11\fR will succeed immediately\&. .sp +The command will keep finding routes and retrying the payment until it succeeds, or the given \fIretry_for\fR seconds passes\&. Note that the command may stop retrying while a pending payment is ongoing, which you need to monitor with \fBlistpayments\fR or \fBwaitsendpay\fR\&. \fIretry_for\fR defaults to 60 seconds and can only be an integer\&. +.sp When using \fIlightning\-cli\fR, you may skip optional parameters by using \fInull\fR\&. Alternatively, use \fB\-k\fR option to provide parameters by name\&. .SH "RETURN VALUE" .sp @@ -68,11 +70,11 @@ The following error codes may occur: .sp -1 .IP \(bu 2.3 .\} -200\&. A previous -\fBsendpay\fR -or -\fBpay\fR -is in progress\&. +200\&. Payment timed out while a payment is in progress\&. Monitor the status of that payment with +\fIlistpayments\fR +command, or wait for that payment to complete with +\fIpay\fR +command\&. .RE .sp .RS 4 @@ -146,6 +148,17 @@ field of the error indicates (the invoice expiration) as UNIX epoch time in seconds\&. .RE .sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +210\&. Payment timed out without a payment in progress\&. +.RE +.sp Error codes 202 and 204 will only get reported at \fBsendpay\fR; in \fBpay\fR we will keep retrying if we would have gotten those errors\&. .sp A routing failure object has the fields below: @@ -210,6 +223,8 @@ message received from the remote node\&. Only present if error is from the remot \fIfailcode\fR has the UPDATE bit set, as per BOLT #4\&. .RE +.sp +The \fIdata\fR field of errors will include statistics \fIgetroute_tries\fR and \fIsendpay_tries\fR\&. It will also contain a \fIfailures\fR field with detailed data about routing errors\&. .SH "AUTHOR" .sp Rusty Russell is mainly responsible\&. diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt index e504c8b7a..f1be7dc25 100644 --- a/doc/lightning-pay.7.txt +++ b/doc/lightning-pay.7.txt @@ -8,7 +8,7 @@ lightning-pay - Protocol for sending a payment to a BOLT11 invoice SYNOPSIS -------- -*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent'] +*pay* 'bolt11' ['msatoshi'] ['description'] ['riskfactor'] ['maxfeepercent'] ['retry_for'] DESCRIPTION ----------- @@ -30,6 +30,12 @@ The response will occur when the payment fails or succeeds. Once a payment has succeeded, calls to *pay* with the same 'bolt11' will succeed immediately. +The command will keep finding routes and retrying the payment until +it succeeds, or the given 'retry_for' seconds passes. +Note that the command may stop retrying while a pending payment is +ongoing, which you need to monitor with *listpayments* or *waitsendpay*. +'retry_for' defaults to 60 seconds and can only be an integer. + When using 'lightning-cli', you may skip optional parameters by using 'null'. Alternatively, use *-k* option to provide parameters by name. @@ -51,7 +57,9 @@ destination implies the payment should not be retried. The following error codes may occur: * -1. Catchall nonspecific error. -* 200. A previous *sendpay* or *pay* is in progress. +* 200. Payment timed out while a payment is in progress. Monitor + the status of that payment with 'listpayments' command, or + wait for that payment to complete with 'pay' command. * 201. Already paid with this 'hash' using different amount or destination. * 203. Permanent failure at destination. The 'data' field of @@ -66,6 +74,7 @@ The following error codes may occur: The 'data' field of the error indicates 'now' (the current time) and 'expiry' (the invoice expiration) as UNIX epoch time in seconds. +* 210. Payment timed out without a payment in progress. Error codes 202 and 204 will only get reported at *sendpay*; in *pay* we will keep retrying if we would have gotten those @@ -87,6 +96,11 @@ A routing failure object has the fields below: error is from the remote node and the 'failcode' has the UPDATE bit set, as per BOLT #4. +The 'data' field of errors will include statistics +'getroute_tries' and 'sendpay_tries'. +It will also contain a 'failures' field with detailed data +about routing errors. + AUTHOR ------