From e1b1abd32825634c47f5326c48bed15ce668fe0e Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 23 Oct 2018 20:47:26 +1030 Subject: [PATCH] doc: fix argument documentation for lightning-sendpay. The parameter is 'payment_hash' not 'hash', and the 'description' parameter wasn't documented at all. Reported-by: @darosior Signed-off-by: Rusty Russell --- doc/lightning-sendpay.7 | 16 +++++++++------- doc/lightning-sendpay.7.txt | 17 ++++++++++------- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/doc/lightning-sendpay.7 b/doc/lightning-sendpay.7 index 43a25e461..c58f84659 100644 --- a/doc/lightning-sendpay.7 +++ b/doc/lightning-sendpay.7 @@ -2,12 +2,12 @@ .\" Title: lightning-sendpay .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 03/22/2018 +.\" Date: 10/23/2018 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNING\-SENDPAY" "7" "03/22/2018" "\ \&" "\ \&" +.TH "LIGHTNING\-SENDPAY" "7" "10/23/2018" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -31,23 +31,25 @@ lightning-sendpay \- Command for sending a payment via a route\&. .SH "SYNOPSIS" .sp -\fBsendpay\fR \fIroute\fR \fIhash\fR [\fImsatoshi\fR] +\fBsendpay\fR \fIroute\fR \fIpayment_hash\fR [\fIdescription\fR] [\fImsatoshi\fR] .SH "DESCRIPTION" .sp -The \fBsendpay\fR RPC command attempts to send funds associated with the given \fIhash\fR, along a route to the final destination in the route\&. +The \fBsendpay\fR RPC command attempts to send funds associated with the given payment_\(cqhash\*(Aq, along a route to the final destination in the route\&. .sp -Generally, a client would call getroute(7) to resolve a route, then use \fBsendpay\fR to send it\&. If it fails, it would call getroute(7) again to retry\&. +Generally, a client would call lightning\-getroute(7) to resolve a route, then use \fBsendpay\fR to send it\&. If it fails, it would call lightning\-getroute(7) again to retry\&. .sp The response will occur when the payment is on its way to the destination\&. The \fBsendpay\fR RPC command does not wait for definite success or definite failure of the payment\&. Instead, use the \fBwaitsendpay\fR RPC command to poll or wait for definite success or definite failure\&. .sp +The \fIdescription\fR parameter, if provided, will be returned in \fIwaitsendpay\fR and \fIlistpayments\fR results\&. +.sp The \fImsatoshi\fR amount, if provided, is the amount that will be recorded as the target payment value\&. If not specified, it will be the final amount to the destination\&. If specified, then the final amount at the destination must be from the specified \fImsatoshi\fR to twice the specified \fImsatoshi\fR, inclusive\&. This is intended to obscure payments by overpaying slightly at the destination; the actual target payment is what should be specified as the \fImsatoshi\fR argument\&. .sp -Once a payment has succeeded, calls to \fBsendpay\fR with the same \fIhash\fR but a different \fImsatoshi\fR or destination will fail; this prevents accidental multiple payments\&. Calls to \fBsendpay\fR with the same \fIhash\fR, \fImsatoshi\fR, and destination as a previous successful payment (even if a different route) will return immediately with success\&. +Once a payment has succeeded, calls to \fBsendpay\fR with the same \fIpayment_hash\fR but a different \fImsatoshi\fR or destination will fail; this prevents accidental multiple payments\&. Calls to \fBsendpay\fR with the same \fIpayment_hash\fR, \fImsatoshi\fR, and destination as a previous successful payment (even if a different route) will return immediately with success\&. .SH "RETURN VALUE" .sp On success, an object similar to the output of \fBlistpayments\fR will be returned\&. This object will have a \fIstatus\fR field that is typically the string \fI"pending"\fR, but may be \fI"complete"\fR if the payment was already performed successfully\&. .sp -On error, if the error occurred from a node other than the final destination, the route table will be updated so that getroute(7) should return an alternate route (if any)\&. An error from the final destination implies the payment should not be retried\&. +On error, if the error occurred from a node other than the final destination, the route table will be updated so that lightning\-getroute(7) should return an alternate route (if any)\&. An error from the final destination implies the payment should not be retried\&. .sp The following error codes may occur: .sp diff --git a/doc/lightning-sendpay.7.txt b/doc/lightning-sendpay.7.txt index 2d55054d0..91c3cdd36 100644 --- a/doc/lightning-sendpay.7.txt +++ b/doc/lightning-sendpay.7.txt @@ -8,16 +8,16 @@ lightning-sendpay - Command for sending a payment via a route. SYNOPSIS -------- -*sendpay* 'route' 'hash' ['msatoshi'] +*sendpay* 'route' 'payment_hash' ['description'] ['msatoshi'] DESCRIPTION ----------- The *sendpay* RPC command attempts to send funds associated with the -given 'hash', along a route to the final destination in the route. +given payment_'hash', along a route to the final destination in the route. -Generally, a client would call getroute(7) to resolve a route, then -use *sendpay* to send it. If it fails, it would call getroute(7) +Generally, a client would call lightning-getroute(7) to resolve a route, then +use *sendpay* to send it. If it fails, it would call lightning-getroute(7) again to retry. The response will occur when the payment is on its way to the @@ -27,6 +27,9 @@ definite failure of the payment. Instead, use the *waitsendpay* RPC command to poll or wait for definite success or definite failure. +The 'description' parameter, if provided, will be returned in +'waitsendpay' and 'listpayments' results. + The 'msatoshi' amount, if provided, is the amount that will be recorded as the target payment value. If not specified, it will be the final amount to the destination. @@ -38,10 +41,10 @@ the destination; the actual target payment is what should be specified as the 'msatoshi' argument. -Once a payment has succeeded, calls to *sendpay* with the same 'hash' +Once a payment has succeeded, calls to *sendpay* with the same 'payment_hash' but a different 'msatoshi' or destination will fail; this prevents accidental multiple payments. -Calls to *sendpay* with the same 'hash', 'msatoshi', and destination as a +Calls to *sendpay* with the same 'payment_hash', 'msatoshi', and destination as a previous successful payment (even if a different route) will return immediately with success. @@ -55,7 +58,7 @@ string '"pending"', but may be '"complete"' if the payment was already performed successfully. On error, if the error occurred from a node other than the final -destination, the route table will be updated so that getroute(7) +destination, the route table will be updated so that lightning-getroute(7) should return an alternate route (if any). An error from the final destination implies the payment should not be retried.