You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
187 lines
5.1 KiB
187 lines
5.1 KiB
'\" t
|
|
.\" Title: lightning-sendpay
|
|
.\" Author: [see the "AUTHOR" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
|
.\" Date: 03/14/2018
|
|
.\" Manual: \ \&
|
|
.\" Source: \ \&
|
|
.\" Language: English
|
|
.\"
|
|
.TH "LIGHTNING\-SENDPAY" "7" "03/14/2018" "\ \&" "\ \&"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
lightning-sendpay \- Protocol for sending a payment via a route\&.
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
\fBsendpay\fR \fIroute\fR \fIhash\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\&.
|
|
.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\&.
|
|
.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
|
|
Once a payment has succeeded, calls to \fBsendpay\fR with the same \fIhash\fR but a different amount or destination will fail; this prevents accidental multiple payments\&. Calls to \fBsendpay\fR with the same \fIhash\fR, amount, 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\&.
|
|
.sp
|
|
The following error codes may occur:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\-1\&. Catchall nonspecific error\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
201\&. Already paid with this
|
|
\fIhash\fR
|
|
using different amount or destination\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
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\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
203\&. Permanent failure at destination\&. The
|
|
\fIdata\fR
|
|
field of the error will be routing failure object\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
204\&. Failure along route; retry a different route\&. The
|
|
\fIdata\fR
|
|
field of the error will be routing failure object\&.
|
|
.RE
|
|
.sp
|
|
A routing failure object has the fields below:
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\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\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fIerring_node\fR\&. The hex string of the pubkey id of the node that reported the error\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\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\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\fIfailcode\fR\&. The failure code, as per BOLT #4\&.
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.ie n \{\
|
|
\h'-04'\(bu\h'+03'\c
|
|
.\}
|
|
.el \{\
|
|
.sp -1
|
|
.IP \(bu 2.3
|
|
.\}
|
|
\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\&.
|
|
.RE
|
|
.SH "AUTHOR"
|
|
.sp
|
|
Rusty Russell <rusty@rustcorp\&.com\&.au> is mainly responsible\&.
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
lightning\-listinvoice(7), lightning\-delinvoice(7), lightning\-getroute(7), lightning\-invoice(7), lightning\-pay(7), lightning\-waitsendpay(7)\&.
|
|
.SH "RESOURCES"
|
|
.sp
|
|
Main web site: https://github\&.com/ElementsProject/lightning
|
|
|