From b7c9029fe3fc63c50bb1e4bc5f205cfd3ce0cdf2 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Sat, 3 Feb 2018 12:07:18 +0000 Subject: [PATCH] doc: Update for new error codes of sendpay. --- doc/lightning-pay.7 | 162 +++++++++++++++++++++++++++++++++++- doc/lightning-pay.7.txt | 37 +++++++- doc/lightning-sendpay.7 | 149 ++++++++++++++++++++++++++++++++- doc/lightning-sendpay.7.txt | 30 ++++++- 4 files changed, 372 insertions(+), 6 deletions(-) diff --git a/doc/lightning-pay.7 b/doc/lightning-pay.7 index 85ad95b3e..5e89cc4be 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: 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 is mainly responsible\&. diff --git a/doc/lightning-pay.7.txt b/doc/lightning-pay.7.txt index 5f3bb2ba9..c497ae886 100644 --- a/doc/lightning-pay.7.txt +++ b/doc/lightning-pay.7.txt @@ -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 ------ diff --git a/doc/lightning-sendpay.7 b/doc/lightning-sendpay.7 index 45cdf1497..06be452dd 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: 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 is mainly responsible\&. diff --git a/doc/lightning-sendpay.7.txt b/doc/lightning-sendpay.7.txt index 9ec0f1f73..a0550e0f5 100644 --- a/doc/lightning-sendpay.7.txt +++ b/doc/lightning-sendpay.7.txt @@ -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 ------