From f9fba1d7c6a820d7578cff949bc3279d69154e61 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 27 Sep 2018 14:59:17 +0930 Subject: [PATCH] doc/lightning-invoice: document warnings. Signed-off-by: Rusty Russell --- doc/lightning-invoice.7 | 34 +++++++++++++++++++++++++++++++--- doc/lightning-invoice.7.txt | 8 ++++++++ 2 files changed, 39 insertions(+), 3 deletions(-) diff --git a/doc/lightning-invoice.7 b/doc/lightning-invoice.7 index 584995b14..f0e6cc036 100644 --- a/doc/lightning-invoice.7 +++ b/doc/lightning-invoice.7 @@ -2,12 +2,12 @@ .\" Title: lightning-invoice .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.79.1 -.\" Date: 04/26/2018 +.\" Date: 09/27/2018 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "LIGHTNING\-INVOICE" "7" "04/26/2018" "\ \&" "\ \&" +.TH "LIGHTNING\-INVOICE" "7" "09/27/2018" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -49,7 +49,9 @@ The \fIfallbacks\fR array is one or more fallback addresses to include in the in The \fIpreimage\fR is a 64\-digit hex string to be used as payment preimage for the created invoice\&. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system\&. \fBIMPORTANT\fR: if you specify the \fIpreimage\fR, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret\&. This parameter is an advanced feature intended for use with cutting\-edge cryptographic protocols and should not be used unless explicitly needed\&. .SH "RETURN VALUE" .sp -On success, a hash is returned as \fIpayment_hash\fR to be given to the payer, and the \fIexpiry_time\fR as a UNIX timestamp\&. It also returns a BOLT11 invoice as \fIbolt11\fR to be given to the payer\&. On failure, an error is returned and no invoice is created\&. If the lightning process fails before responding, the caller should use lightning\-listinvoice(7) to query whether this invoice was created or not\&. +On success, a hash is returned as \fIpayment_hash\fR to be given to the payer, and the \fIexpiry_time\fR as a UNIX timestamp\&. It also returns a BOLT11 invoice as \fIbolt11\fR to be given to the payer\&. +.sp +On failure, an error is returned and no invoice is created\&. If the lightning process fails before responding, the caller should use lightning\-listinvoice(7) to query whether this invoice was created or not\&. .sp The following error codes may occur: .sp @@ -89,6 +91,32 @@ already exists\&. \fIpreimage\fR already exists\&. .RE +.sp +One of the following warnings may occur (on success): +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIwarning_offline\fR +if no channel with a currently connected peer has the incoming capacity to pay this invoice +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIwarning_capacity\fR +if there is no channel at all with sufficient incoming capacity to pay this invoice\&. +.RE .SH "AUTHOR" .sp Rusty Russell is mainly responsible\&. diff --git a/doc/lightning-invoice.7.txt b/doc/lightning-invoice.7.txt index fa3916535..1013dc346 100644 --- a/doc/lightning-invoice.7.txt +++ b/doc/lightning-invoice.7.txt @@ -55,6 +55,7 @@ On success, a hash is returned as 'payment_hash' to be given to the payer, and the 'expiry_time' as a UNIX timestamp. It also returns a BOLT11 invoice as 'bolt11' to be given to the payer. + On failure, an error is returned and no invoice is created. If the lightning process fails before responding, the caller should use lightning-listinvoice(7) to query whether this invoice was created or not. @@ -65,6 +66,13 @@ The following error codes may occur: * 900. An invoice with the given 'label' already exists. * 901. An invoice with the given 'preimage' already exists. +One of the following warnings may occur (on success): + +* 'warning_offline' if no channel with a currently + connected peer has the incoming capacity to pay this invoice +* 'warning_capacity' if there is no channel at all with sufficient + incoming capacity to pay this invoice. + AUTHOR ------ Rusty Russell is mainly responsible.