mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
c3254e6639
mrkd started enforcing the `name -- short description` style of top-level headings somewhere, and was thus failing to build the man-pages. I swapped the title and with the existing short description to make it work again. `mrkd` will automatically infer the section from the filename so no need to put it in the title as well. In addition I removed the "last updated" lines at the bottom since they are out of date at best, and misleading at the worst. If we want to keep them, I'd suggest generating them from the commit that last touched them.
122 lines
4.3 KiB
Groff
122 lines
4.3 KiB
Groff
.TH "LIGHTNING-SENDPAY" "7" "" "" "lightning-sendpay"
|
|
.SH NAME
|
|
lightning-sendpay - Low-level command for sending a payment via a route
|
|
.SH SYNOPSIS
|
|
|
|
\fBsendpay\fR \fIroute\fR \fIpayment_hash\fR [\fIlabel\fR] [\fImsatoshi\fR]
|
|
[\fIbolt11\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBsendpay\fR RPC command attempts to send funds associated with the
|
|
given \fIpayment_hash\fR, along a route to the final destination in the
|
|
route\.
|
|
|
|
|
|
Generally, a client would call \fBlightning-getroute\fR(7) to resolve a route,
|
|
then use \fBsendpay\fR to send it\. If it fails, it would call
|
|
\fBlightning-getroute\fR(7) again to retry\.
|
|
|
|
|
|
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\.
|
|
|
|
|
|
The \fIlabel\fR and \fIbolt11\fR parameters, if provided, will be returned in
|
|
\fIwaitsendpay\fR and \fIlistsendpays\fR results\.
|
|
|
|
|
|
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\. \fImsatoshi\fR is in
|
|
millisatoshi precision; it can be a whole number, or a whole number
|
|
ending in \fImsat\fR or \fIsat\fR, or a number with three decimal places ending
|
|
in \fIsat\fR, or a number with 1 to 11 decimal places ending in \fIbtc\fR\.
|
|
|
|
|
|
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
|
|
|
|
On success, an object similar to the output of \fBlistsendpays\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\.
|
|
|
|
|
|
On error, if the error occurred from a node other than the final
|
|
destination, the route table will be updated so that
|
|
\fBlightning-getroute\fR(7) should return an alternate route (if any)\. An
|
|
error from the final destination implies the payment should not be
|
|
retried\.
|
|
|
|
|
|
The following error codes may occur:
|
|
|
|
.IP \[bu]
|
|
-1: Catchall nonspecific error\.
|
|
.IP \[bu]
|
|
201: Already paid with this \fIhash\fR using different amount or
|
|
destination\.
|
|
.IP \[bu]
|
|
202: Unparseable onion reply\. The \fIdata\fR field of the error will
|
|
have an \fIonionreply\fR field, a hex string representation of the raw
|
|
onion reply\.
|
|
.IP \[bu]
|
|
203: Permanent failure at destination\. The \fIdata\fR field of the error
|
|
will be routing failure object\.
|
|
.IP \[bu]
|
|
204: Failure along route; retry a different route\. The \fIdata\fR field
|
|
of the error will be routing failure object\.
|
|
|
|
|
|
A routing failure object has the fields below:
|
|
|
|
.IP \[bu]
|
|
\fIerring_index\fR\. The index of the node along the route that reported
|
|
the error\. 0 for the local node, 1 for the first hop, and so on\.
|
|
.IP \[bu]
|
|
\fIerring_node\fR\. The hex string of the pubkey id of the node that
|
|
reported the error\.
|
|
.IP \[bu]
|
|
\fIerring_channel\fR\. The short channel ID of the channel that has the
|
|
error, or \fI0:0:0\fR if the destination node raised the error\.
|
|
.IP \[bu]
|
|
\fIfailcode\fR\. The failure code, as per BOLT #4\.
|
|
.IP \[bu]
|
|
\fIchannel_update\fR\. The hex string of the \fIchannel_update\fR message
|
|
received from the remote node\. Only present if error is from the
|
|
remote node and the \fIfailcode\fR has the UPDATE bit set, as per BOLT
|
|
#4\.
|
|
|
|
.SH AUTHOR
|
|
|
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-listinvoice\fR(7), \fBlightning-delinvoice\fR(7),
|
|
\fBlightning-getroute\fR(7), \fBlightning-invoice\fR(7), \fBlightning-pay\fR(7),
|
|
\fBlightning-waitsendpay\fR(7)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
.HL
|
|
|
|
Last updated 2019-08-01 14:59:36 CEST
|
|
|