mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 09:54:16 +01:00
doc: Update for new error codes of sendpay.
This commit is contained in:
ZmnSCPxj
Christian Decker
parent
a6c6b8d9d3
commit
b7c9029fe3
@ -2,12 +2,12 @@
|
||||
.\" Title: lightning-pay
|
||||
.\" Author: [see the "AUTHOR" section]
|
||||
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
||||
.\" Date: 01/13/2018
|
||||
.\" Date: 02/05/2018
|
||||
.\" Manual: \ \&
|
||||
.\" Source: \ \&
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "LIGHTNING\-PAY" "7" "01/13/2018" "\ \&" "\ \&"
|
||||
.TH "LIGHTNING\-PAY" "7" "02/05/2018" "\ \&" "\ \&"
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" * Define some portability stuff
|
||||
.\" -----------------------------------------------------------------
|
||||
@ -40,6 +40,164 @@ The response will occur when the payment fails or succeeds\&. Once a payment has
|
||||
.SH "RETURN VALUE"
|
||||
.sp
|
||||
On success, this returns the payment \fIpreimage\fR which hashes to the \fIpayment_hash\fR to prove that the payment was successful\&.
|
||||
.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
|
||||
.\}
|
||||
200\&. A previous
|
||||
\fBsendpay\fR
|
||||
or
|
||||
\fBpay\fR
|
||||
is in progress\&.
|
||||
.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 a
|
||||
\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
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
.sp -1
|
||||
.IP \(bu 2.3
|
||||
.\}
|
||||
205\&. Unable to find a route\&.
|
||||
.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
|
||||
.\}
|
||||
\fIorigin_index\fR\&. The index of the node along the route that reported the error\&. 0 for the first hop node, \-1 if the local node reported the error\&.
|
||||
.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\&.
|
||||
|
||||
@ -30,7 +30,42 @@ RETURN VALUE
|
||||
On success, this returns the payment 'preimage' which hashes to the
|
||||
'payment_hash' to prove that the payment was successful.
|
||||
|
||||
//FIXME:Enumerate errors
|
||||
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.
|
||||
|
||||
The following error codes may occur:
|
||||
|
||||
* -1. Catchall nonspecific error.
|
||||
* 200. A previous *sendpay* or *pay* is in progress.
|
||||
* 201. Already paid with this 'hash' using different amount or
|
||||
destination.
|
||||
* 202. Unparseable onion reply. The 'data' field of the error
|
||||
will have a 'onionreply' field, a hex string representation
|
||||
of the raw onion reply.
|
||||
* 203. Permanent failure at destination. The 'data' field of
|
||||
the error will be routing failure object.
|
||||
* 204. Failure along route; retry a different route. The 'data'
|
||||
field of the error will be routing failure object.
|
||||
* 205. Unable to find a route.
|
||||
|
||||
A routing failure object has the fields below:
|
||||
|
||||
* 'origin_index'. The index of the node along the route that
|
||||
reported the error. 0 for the first hop node, -1 if the local
|
||||
node reported the error.
|
||||
* 'erring_node'. The hex string of the pubkey id of the node
|
||||
that reported the error.
|
||||
* 'erring_channel'. The short channel ID of the channel that
|
||||
has the error, or '0:0:0' if the destination node raised
|
||||
the error.
|
||||
* 'failcode'. The failure code, as per BOLT #4.
|
||||
* 'channel_update'. The hex string of the 'channel_update'
|
||||
message received from the remote node. Only present if
|
||||
error is from the remote node and the 'failcode' has the
|
||||
UPDATE bit set, as per BOLT #4.
|
||||
|
||||
|
||||
AUTHOR
|
||||
------
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
.\" Title: lightning-sendpay
|
||||
.\" Author: [see the "AUTHOR" section]
|
||||
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
||||
.\" Date: 09/06/2016
|
||||
.\" Date: 02/05/2018
|
||||
.\" Manual: \ \&
|
||||
.\" Source: \ \&
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "LIGHTNING\-SENDPAY" "7" "09/06/2016" "\ \&" "\ \&"
|
||||
.TH "LIGHTNING\-SENDPAY" "7" "02/05/2018" "\ \&" "\ \&"
|
||||
.\" -----------------------------------------------------------------
|
||||
.\" * Define some portability stuff
|
||||
.\" -----------------------------------------------------------------
|
||||
@ -44,6 +44,151 @@ The response will occur when the payment fails or succeeds\&. Once a payment has
|
||||
On success, a \fIpreimage\fR hex string is returned as proof that the destination received the payment\&. The \fIpreimage\fR will SHA256 to the \fIhash\fR given by the caller\&.
|
||||
.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
|
||||
.\}
|
||||
200\&. A previous
|
||||
\fBsendpay\fR
|
||||
or
|
||||
\fBpay\fR
|
||||
is in progress\&.
|
||||
.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 a
|
||||
\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
|
||||
.\}
|
||||
\fIorigin_index\fR\&. The index of the node along the route that reported the error\&. 0 for the first hop node, \-1 if the local node reported the error\&.
|
||||
.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\&.
|
||||
|
||||
@ -36,7 +36,35 @@ 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.
|
||||
|
||||
//FIXME:Enumerate errors
|
||||
The following error codes may occur:
|
||||
|
||||
* -1. Catchall nonspecific error.
|
||||
* 200. A previous *sendpay* or *pay* is in progress.
|
||||
* 201. Already paid with this 'hash' using different amount or
|
||||
destination.
|
||||
* 202. Unparseable onion reply. The 'data' field of the error
|
||||
will have a 'onionreply' field, a hex string representation
|
||||
of the raw onion reply.
|
||||
* 203. Permanent failure at destination. The 'data' field of
|
||||
the error will be routing failure object.
|
||||
* 204. Failure along route; retry a different route. The 'data'
|
||||
field of the error will be routing failure object.
|
||||
|
||||
A routing failure object has the fields below:
|
||||
|
||||
* 'origin_index'. The index of the node along the route that
|
||||
reported the error. 0 for the first hop node, -1 if the local
|
||||
node reported the error.
|
||||
* 'erring_node'. The hex string of the pubkey id of the node
|
||||
that reported the error.
|
||||
* 'erring_channel'. The short channel ID of the channel that
|
||||
has the error, or '0:0:0' if the destination node raised
|
||||
the error.
|
||||
* 'failcode'. The failure code, as per BOLT #4.
|
||||
* 'channel_update'. The hex string of the 'channel_update'
|
||||
message received from the remote node. Only present if
|
||||
error is from the remote node and the 'failcode' has the
|
||||
UPDATE bit set, as per BOLT #4.
|
||||
|
||||
AUTHOR
|
||||
------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user