aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2026-02-02 20:54:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: document experimental commands.

Browse Source 
Not the low-level ones, just enough that people can play with the APIs.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell
2021-01-08 05:15:47 +10:30
parent 55983827b6
commit 47ce7ff0c1
8 changed files with 668 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/Makefile
View File

@@ -21,6 +21,7 @@ MANPAGES := doc/lightning-cli.1 \
doc/lightning-dev-sendcustommsg.7 \
doc/lightning-disconnect.7 \
doc/lightning-feerates.7 \
doc/lightning-fetchinvoice.7 \
doc/lightning-fundchannel.7 \
doc/lightning-fundchannel_start.7 \
doc/lightning-fundchannel_complete.7 \
@@ -42,12 +43,14 @@ MANPAGES := doc/lightning-cli.1 \
doc/lightning-multiwithdraw.7 \
doc/lightning-newaddr.7 \
doc/lightning-notifications.7 \
doc/lightning-offer.7 \
doc/lightning-openchannel_init.7 \
doc/lightning-openchannel_signed.7 \
doc/lightning-openchannel_update.7 \
doc/lightning-pay.7 \
doc/lightning-plugin.7 \
doc/lightning-reserveinputs.7 \
doc/lightning-sendinvoice.7 \
doc/lightning-sendonion.7 \
doc/lightning-sendpay.7 \
doc/lightning-setchannelfee.7 \

3
doc/index.rst
View File

@@ -44,6 +44,7 @@ c-lightning Documentation
lightning-dev-sendcustommsg <lightning-dev-sendcustommsg.7.md>
lightning-disconnect <lightning-disconnect.7.md>
lightning-feerates <lightning-feerates.7.md>
lightning-fetchinvoice <lightning-fetchinvoice.7.md>
lightning-fundchannel <lightning-fundchannel.7.md>
lightning-fundchannel_cancel <lightning-fundchannel_cancel.7.md>
lightning-fundchannel_complete <lightning-fundchannel_complete.7.md>
@@ -71,6 +72,7 @@ c-lightning Documentation
lightning-multiwithdraw <lightning-multiwithdraw.7.md>
lightning-newaddr <lightning-newaddr.7.md>
lightning-notifications <lightning-notifications.7.md>
lightning-offer <lightning-offer.7.md>
lightning-openchannel_init <lightning-openchannel_init.7.md>
lightning-openchannel_signed <lightning-openchannel_signed.7.md>
lightning-openchannel_update <lightning-openchannel_update.7.md>
@@ -78,6 +80,7 @@ c-lightning Documentation
lightning-ping <lightning-ping.7.md>
lightning-plugin <lightning-plugin.7.md>
lightning-reserveinputs <lightning-reserveinputs.7.md>
lightning-sendinvoice <lightning-sendinvoice.7.md>
lightning-sendonion <lightning-sendonion.7.md>
lightning-sendpay <lightning-sendpay.7.md>
lightning-sendpsbt <lightning-sendpsbt.7.md>

129
doc/lightning-fetchinvoice.7 generated Normal file
View File

@@ -0,0 +1,129 @@
.TH "LIGHTNING-FETCHINVOICE" "7" "" "" "lightning-fetchinvoice"
.SH NAME
lightning-fetchinvoice - Command for fetch an invoice for an offer
.SH SYNOPSIS
\fIEXPERIMENTAL_FEATURES only\fR
\fBfetchinvoice\fR \fIoffer\fR [\fImsatoshi\fR] [\fIquantity\fR] [\fIrecurrence_counter\fR] [\fIrecurrence_start\fR] [\fIrecurrence_label\fR] [\fItimeout\fR]
.SH DESCRIPTION
The \fBfetchinvoice\fR RPC command contacts the issuer of an \fIoffer\fR to get
an actual invoice that can be paid\. It highlights any changes between the
offer and the returned invoice\.
The offer must not contain \fIsend_invoice\fR; see \fBlightning-sendinvoice\fR(7)\.
\fImsatoshi\fR is required if the \fIoffer\fR does not specify
an amount at all, otherwise it is not allowed\.
\fIquantity\fR is is required if the \fIoffer\fR specifies
\fIquantity_min\fR or \fIquantity_max\fR, otherwise it is not allowed\.
\fIrecurrence_counter\fR is required if the \fIoffer\fR
specifies \fIrecurrence\fR, otherwise it is not allowed\.
\fIrecurrence_counter\fR should first be set to 0, and incremented for
each successive invoice in a given series\.
\fIrecurrence_start\fR is required if the \fIoffer\fR
specifies \fIrecurrence_base\fR with \fIstart_any_period\fR set, otherwise it
is not allowed\. It indicates what period number to start at\.
\fIrecurrence_label\fR is required if \fIrecurrence_counter\fR is set, and
otherwise is not allowed\. It must be the same as prior fetchinvoice
calls for the same recurrence, as it is used to link them together\.
\fItimeout\fR is an optional timeout; if we don't get a reply before this
we fail (default, 60 seconds)\.
.SH RETURN VALUE
On success, an object as follows is returned:
.RS
.IP \[bu]
\fIinvoice\fR: the bolt12-encoded invoice string, starting with "lni1"\.
.IP \[bu]
\fIchanges\fR: an object detailing changes between the offer and invoice\.
.RE
Optionally:
.RS
.IP \[bu]
\fInext_period\fR: an object returned for recurring invoices if the next
period is under the recurrence_limit (if any)\.
.RE
The \fIchanges\fR object can have and of the following members:
.RS
.IP \[bu]
\fIdescription_appended\fR: extra characters appended to the \fIdescription\fR field\.
.IP \[bu]
\fIdescription\fR: a completely replaced \fIdescription\fR field\.
.IP \[bu]
\fIvendor_removed\fR": the offer vendor field, which has been omitted from the invoice\.
.IP \[bu]
\fIvendor\fR": the offer vendor field, which has changed from the invoice\.
.IP \[bu]
\fImsat\fR": the amount, if different from the offer amount multiplied
by any \fIquantity\fR (or the offer had no amount, or was not in BTC)\.
.RE
The \fInext_period\fR object has at least the following members:
.RS
.IP \[bu]
\fIcounter\fR: the index of the next period to be fetchinvoice\.
.IP \[bu]
\fIstarttime\fR: the time that the next period starts (seconds since 1970)
.IP \[bu]
\fIendtime\fR: the time that the next period ends (seconds since 1970)
.IP \[bu]
\fIpaywindow_start\fR: the earliest time that the next invoice can be fetched (seconds since 1970)
.IP \[bu]
\fIpaywindow_end\fR: the latest time that the next invoice can be fetched (seconds since 1970)
.RE
The following error codes may occur:
.RS
.IP \[bu]
-1: Catchall nonspecific error\.
.IP \[bu]
1002: Offer has expired\.
.IP \[bu]
1003: Cannot find a route to the node making the offer\.
.IP \[bu]
1004: The node making the offer returned an error message\.
.IP \[bu]
1005: We timed out trying to fetch an invoice\.
.RE
.SH AUTHOR
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
.SH SEE ALSO
\fBlightning-sendinvoice\fR(7), \fBlightning-pay\fR(7)\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:d891c6471a81b3b73109b19d1bc6a393bc60b5df804d6b14d330e2d8dca47f4e

90
doc/lightning-fetchinvoice.7.md Normal file
View File

@@ -0,0 +1,90 @@
lightning-fetchinvoice -- Command for fetch an invoice for an offer
===================================================================
SYNOPSIS
--------
*EXPERIMENTAL_FEATURES only*
**fetchinvoice** *offer* \[*msatoshi*\] \[*quantity*\] \[*recurrence_counter*\] \[*recurrence_start*\] \[*recurrence_label*\] \[*timeout*\]
DESCRIPTION
-----------
The **fetchinvoice** RPC command contacts the issuer of an *offer* to get
an actual invoice that can be paid. It highlights any changes between the
offer and the returned invoice.
The offer must not contain *send_invoice*; see lightning-sendinvoice(7).
*msatoshi* is required if the *offer* does not specify
an amount at all, otherwise it is not allowed.
*quantity* is is required if the *offer* specifies
*quantity_min* or *quantity_max*, otherwise it is not allowed.
*recurrence_counter* is required if the *offer*
specifies *recurrence*, otherwise it is not allowed.
*recurrence_counter* should first be set to 0, and incremented for
each successive invoice in a given series.
*recurrence_start* is required if the *offer*
specifies *recurrence_base* with *start_any_period* set, otherwise it
is not allowed. It indicates what period number to start at.
*recurrence_label* is required if *recurrence_counter* is set, and
otherwise is not allowed. It must be the same as prior fetchinvoice
calls for the same recurrence, as it is used to link them together.
*timeout* is an optional timeout; if we don't get a reply before this
we fail (default, 60 seconds).
RETURN VALUE
------------
On success, an object as follows is returned:
* *invoice*: the bolt12-encoded invoice string, starting with "lni1".
* *changes*: an object detailing changes between the offer and invoice.
Optionally:
* *next_period*: an object returned for recurring invoices if the next
period is under the recurrence_limit (if any).
The *changes* object can have and of the following members:
* *description_appended*: extra characters appended to the *description* field.
* *description*: a completely replaced *description* field.
* *vendor_removed*": the offer vendor field, which has been omitted from the invoice.
* *vendor*": the offer vendor field, which has changed from the invoice.
* *msat*": the amount, if different from the offer amount multiplied
by any *quantity* (or the offer had no amount, or was not in BTC).
The *next_period* object has at least the following members:
* *counter*: the index of the next period to be fetchinvoice.
* *starttime*: the time that the next period starts (seconds since 1970)
* *endtime*: the time that the next period ends (seconds since 1970)
* *paywindow_start*: the earliest time that the next invoice can be fetched (seconds since 1970)
* *paywindow_end*: the latest time that the next invoice can be fetched (seconds since 1970)
The following error codes may occur:
- -1: Catchall nonspecific error.
- 1002: Offer has expired.
- 1003: Cannot find a route to the node making the offer.
- 1004: The node making the offer returned an error message.
- 1005: We timed out trying to fetch an invoice.
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-sendinvoice(7), lightning-pay(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>

162
doc/lightning-offer.7 generated Normal file
View File

@@ -0,0 +1,162 @@
.TH "LIGHTNING-OFFER" "7" "" "" "lightning-offer"
.SH NAME
lightning-offer - Command for accepting payments
.SH SYNOPSIS
\fIEXPERIMENTAL_FEATURES only\fR
\fBoffer\fR \fIamount\fR \fIdescription\fR [\fIsend_invoice\fR] [\fIlabel\fR] [\fIvendor\fR] [\fIquantity_min\fR] [\fIquantity_max\fR] [\fIabsolute_expiry\fR] [\fIrecurrence\fR] [\fIrecurrence_base\fR] [\fIrecurrence_paywindow\fR] [\fIrecurrence_limit\fR] [\fIrefund_for\fR] [\fIsingle_use\fR]
.SH DESCRIPTION
The \fBoffer\fR RPC command creates an offer, which is a precursor to
one or more invoices\. It automatically enables the accepting of
corresponding invoice_request or invoice messages (depending on
\fIsend_invoice\fR)\.
The \fIamount\fR parameter can be the string "any", which creates an offer
that can be paid with any amount (e\.g\. a donation)\. Otherwise it can
be a positive value 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\.
\fIamount\fR can also have an ISO 4217 postfix (i\.e\. USD), in which case
currency conversion will need to be done for the invoice itself\.
The \fIdescription\fR is a short description of purpose of the offer,
e\.g\. \fIcoffee\fR\. This value is encoded into the resulting offer and is
viewable by anyone you expose this offer to\. It must be UTF-8, and
cannot use \fI\u\fR JSON escape codes\.
The \fIvendor\fR is another (optional) field exposed in the offer, and
reflects who is issuing this offer (i\.e\. you) if appropriate\.
The \fIsend_invoice\fR boolean (default false unless \fIsingle_use\fR) creates
an offer to send money: the user of the offer will send an invoice,
rather than an invoice_request\. This is encoded in the offer\. Note
that \fIrecurrence\fR and ISO 4217 currencies are not currently
well-supported for this case!
The \fIlabel\fR field is an internal-use name for the offer, which can
be any UTF-8 string\.
The present of \fIquantity_min\fR or \fIquantity_max\fR indicates that the
invoice can specify more than one of the items within this (inclusive)
range\. The \fIamount\fR for the invoice will need to be multiplied
accordingly\. These are encoded in the offer\.
The \fIabsolute_expiry\fR is optionally the time the offer is valid until,
in seconds since the first day of 1970 UTC\. If not set, the offer
remains valid (though it can be deactivated by the issuer of course)\.
This is encoded in the offer\.
\fIrecurrence\fR means that an invoice is expected at regular intervals\.
The argument is a positive number followed by one of "seconds",
"minutes", "hours", "days", "weeks", "months" or "years" (variants
without the trailing "s" are also permitted)\. This is encoded in the
offer\. The semantics of recurrence is fairly predictable, but fully
documented in BOLT 12\. e\.g\. "4weeks"\.
\fIrecurrence_base\fR is an optional time in seconds since the first day
of 1970 UTC, optionally with a "@" prefix\. This indicates when the
first period begins; without this, the recurrence periods start from
the first invoice\. The "@" prefix means that the invoice must start
by paying the first period; otherwise it is permitted to start at any
period\. This is encoded in the offer\. e\.g\. "@1609459200" indicates
you must start paying on the 1st January 2021\.
\fIrecurrence_paywindow\fR is an optional argument of form
'-time+time[%]'\. The first time is the number of seconds before the
start of a period in which an invoice and payment is valid, the second
time is the number of seconds after the start of the period\. For
example \fI-604800+86400\fR means you can fetch an pay the invoice 4 weeks
before the given period starts, and up to 1 day afterwards\. The
optional \fI%\fR indicates that the amount of the invoice will be scaled
by the time remaining in the period\. If this is not specified, the
default is that payment is allowed during the current and previous
periods\. This is encoded in the offer\.
\fIrecurrence_limit\fR is an optional argument to indicate the maximum
period which exists\. eg\. "12" means there are 13 periods, from 0 to
12 inclusive\. This is encoded in the offer\.
\fIrefund_for\fR is the payment_preimage of a previous (paid) invoice\.
This implies \fIsend_invoice\fR and \fIsingle_use\fR\. This is encoded in the
offer\.
\fIsingle_use\fR (default false, unless \fIrefund_for\fR) indicates that the
invoice associated with the offer is only valid once; for a
\fIsend_invoice\fR offer many invoices can be accepted until one is
successfully paid (and we will only attempt to pay one at any time)\.
For a non-\fIsingle-use\fR offer, we will issue any number of invoices as
requested, until one is paid, at which time we will expire all the
other invoices for this offer and issue no more\.
.SH RETURN VALUE
On success, an object as follows is returned:
.RS
.IP \[bu]
\fIoffer_id\fR: the hash of the offer\.
.IP \[bu]
\fIactive\fR: true
.IP \[bu]
\fIsingle_use\fR: true if \fIsingle_use\fR was specified or implied\.
.IP \[bu]
\fIbolt12\fR: the bolt12 offer, starting with "lno1"
.RE
Optionally:
.RS
.IP \[bu]
\fIlabel\fR: the user-specified label\.
.RE
On failure, an error is returned and no offer is created\. If the
lightning process fails before responding, the caller should use
\fBlightning-listoffers\fR(7) to query whether this offer was created or
not\.
The following error codes may occur:
.RS
.IP \[bu]
-1: Catchall nonspecific error\.
.IP \[bu]
1000: Offer with this offer_id already exists\.
.RE
.SH AUTHOR
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
.SH SEE ALSO
\fBlightning-listoffers\fR(7), \fBlightning-deloffer\fR(7)\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:88a1e0515adae79cdeef661b6462879d7fb0d666a7731ffdb131053c15c1b9de

134
doc/lightning-offer.7.md Normal file
View File

@@ -0,0 +1,134 @@
lightning-offer -- Command for accepting payments
=================================================
SYNOPSIS
--------
*EXPERIMENTAL_FEATURES only*
**offer** *amount* *description* \[*send_invoice*\] \[*label*\] \[*vendor*\] \[*quantity_min*\] \[*quantity_max*\] \[*absolute_expiry*\] \[*recurrence*\] \[*recurrence_base*\] \[*recurrence_paywindow*\] \[*recurrence_limit*\] \[*refund_for*\] \[*single_use*\]
DESCRIPTION
-----------
The **offer** RPC command creates an offer, which is a precursor to
one or more invoices. It automatically enables the accepting of
corresponding invoice_request or invoice messages (depending on
*send_invoice*).
The *amount* parameter can be the string "any", which creates an offer
that can be paid with any amount (e.g. a donation). Otherwise it can
be a positive value in millisatoshi precision; it can be a whole
number, or a whole number ending in *msat* or *sat*, or a number with
three decimal places ending in *sat*, or a number with 1 to 11 decimal
places ending in *btc*.
*amount* can also have an ISO 4217 postfix (i.e. USD), in which case
currency conversion will need to be done for the invoice itself.
The *description* is a short description of purpose of the offer,
e.g. *coffee*. This value is encoded into the resulting offer and is
viewable by anyone you expose this offer to. It must be UTF-8, and
cannot use *\\u* JSON escape codes.
The *vendor* is another (optional) field exposed in the offer, and
reflects who is issuing this offer (i.e. you) if appropriate.
The *send_invoice* boolean (default false unless *single_use*) creates
an offer to send money: the user of the offer will send an invoice,
rather than an invoice_request. This is encoded in the offer. Note
that *recurrence* and ISO 4217 currencies are not currently
well-supported for this case!
The *label* field is an internal-use name for the offer, which can
be any UTF-8 string.
The present of *quantity_min* or *quantity_max* indicates that the
invoice can specify more than one of the items within this (inclusive)
range. The *amount* for the invoice will need to be multiplied
accordingly. These are encoded in the offer.
The *absolute_expiry* is optionally the time the offer is valid until,
in seconds since the first day of 1970 UTC. If not set, the offer
remains valid (though it can be deactivated by the issuer of course).
This is encoded in the offer.
*recurrence* means that an invoice is expected at regular intervals.
The argument is a positive number followed by one of "seconds",
"minutes", "hours", "days", "weeks", "months" or "years" (variants
without the trailing "s" are also permitted). This is encoded in the
offer. The semantics of recurrence is fairly predictable, but fully
documented in BOLT 12. e.g. "4weeks".
*recurrence_base* is an optional time in seconds since the first day
of 1970 UTC, optionally with a "@" prefix. This indicates when the
first period begins; without this, the recurrence periods start from
the first invoice. The "@" prefix means that the invoice must start
by paying the first period; otherwise it is permitted to start at any
period. This is encoded in the offer. e.g. "@1609459200" indicates
you must start paying on the 1st January 2021.
*recurrence_paywindow* is an optional argument of form
'-time+time\[%\]'. The first time is the number of seconds before the
start of a period in which an invoice and payment is valid, the second
time is the number of seconds after the start of the period. For
example *-604800+86400* means you can fetch an pay the invoice 4 weeks
before the given period starts, and up to 1 day afterwards. The
optional *%* indicates that the amount of the invoice will be scaled
by the time remaining in the period. If this is not specified, the
default is that payment is allowed during the current and previous
periods. This is encoded in the offer.
*recurrence_limit* is an optional argument to indicate the maximum
period which exists. eg. "12" means there are 13 periods, from 0 to
12 inclusive. This is encoded in the offer.
*refund_for* is the payment_preimage of a previous (paid) invoice.
This implies *send_invoice* and *single_use*. This is encoded in the
offer.
*single_use* (default false, unless *refund_for*) indicates that the
invoice associated with the offer is only valid once; for a
*send_invoice* offer many invoices can be accepted until one is
successfully paid (and we will only attempt to pay one at any time).
For a non-*single-use* offer, we will issue any number of invoices as
requested, until one is paid, at which time we will expire all the
other invoices for this offer and issue no more.
RETURN VALUE
------------
On success, an object as follows is returned:
* *offer_id*: the hash of the offer.
* *active*: true
* *single_use*: true if *single_use* was specified or implied.
* *bolt12*: the bolt12 offer, starting with "lno1"
Optionally:
* *label*: the user-specified label.
On failure, an error is returned and no offer is created. If the
lightning process fails before responding, the caller should use
lightning-listoffers(7) to query whether this offer was created or
not.
The following error codes may occur:
- -1: Catchall nonspecific error.
- 1000: Offer with this offer_id already exists.
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-listoffers(7), lightning-deloffer(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>

81
doc/lightning-sendinvoice.7 generated Normal file
View File

@@ -0,0 +1,81 @@
.TH "LIGHTNING-SENDINVOICE" "7" "" "" "lightning-sendinvoice"
.SH NAME
lightning-sendinvoice - Command for send an invoice for an offer
.SH SYNOPSIS
\fIEXPERIMENTAL_FEATURES only\fR
\fBsendinvoice\fR \fIoffer\fR [\fIlabel\fR] [\fImsatoshi\fR] [\fItimeout\fR] [\fIinvoice_timeout\fR] [\fIquantity\fR]
.SH DESCRIPTION
The \fBsendinvoice\fR RPC command creates and sends an invoice to the
issuer of an \fIoffer\fR for it to pay: the offer must contain
\fIsend_invoice\fR; see \fBlightning-fetchinvoice\fR(7)\.
\fIoffer\fR is the bolt12 offer string beginning with "lno1"\.
\fIlabel\fR is the unique label to use for this invoice\.
\fImsatoshi\fR is optional: it is required if the \fIoffer\fR does not specify
an amount at all, or specifies it in a different currency\. Otherwise
you may set it (e\.g\. to provide a tip), and if not it defaults to the
amount contained in the offer (multiplied by \fIquantity\fR if any)\.
\fItimeout\fR is how many seconds to wait for the offering node to pay the
invoice or return an error, default 90 seconds\.
\fIinvoice_timeout\fR can be set to greater than \fItimeout\fR, to give the
offering node longer to pay; in this case \fIsendinvoice\fR will time out
but the invoice will still be valid, and the caller should monitor it\.
\fIquantity\fR is optional: it is required if the \fIoffer\fR specifies
\fIquantity_min\fR or \fIquantity_max\fR, otherwise it is not allowed\.
.SH RETURN VALUE
On success, an object as follows is returned:
.RS
.IP \[bu]
\fIinvstring\fR: the bolt12-encoded invoice string we sent (now paid), starting with "lni1"\.
.IP \[bu]
\fImsat\fR: the amount they paid\.
.RE
The following error codes may occur:
.RS
.IP \[bu]
-1: Catchall nonspecific error\.
.IP \[bu]
1002: Offer has expired\.
.IP \[bu]
1003: Cannot find a route to the node making the offer\.
.IP \[bu]
1004: The node making the offer returned an error message\.
.IP \[bu]
1005: We timed out waiting for the invoice to be paid
.RE
.SH AUTHOR
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
.SH SEE ALSO
\fBlightning-fetchinvoice\fR(7)\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:0ffd4c0967f4aa7ffb2f14ed4658dbe4ef79926a08acf0534db47fdd8bd1b6bc

66
doc/lightning-sendinvoice.7.md Normal file
View File

@@ -0,0 +1,66 @@
lightning-sendinvoice -- Command for send an invoice for an offer
=================================================================
SYNOPSIS
--------
*EXPERIMENTAL_FEATURES only*
**sendinvoice** *offer* \[*label*\] \[*msatoshi*\] \[*timeout*\] \[*invoice_timeout*\] \[*quantity*\]
DESCRIPTION
-----------
The **sendinvoice** RPC command creates and sends an invoice to the
issuer of an *offer* for it to pay: the offer must contain
*send_invoice*; see lightning-fetchinvoice(7).
*offer* is the bolt12 offer string beginning with "lno1".
*label* is the unique label to use for this invoice.
*msatoshi* is optional: it is required if the *offer* does not specify
an amount at all, or specifies it in a different currency. Otherwise
you may set it (e.g. to provide a tip), and if not it defaults to the
amount contained in the offer (multiplied by *quantity* if any).
*timeout* is how many seconds to wait for the offering node to pay the
invoice or return an error, default 90 seconds.
*invoice_timeout* can be set to greater than *timeout*, to give the
offering node longer to pay; in this case *sendinvoice* will time out
but the invoice will still be valid, and the caller should monitor it.
*quantity* is optional: it is required if the *offer* specifies
*quantity_min* or *quantity_max*, otherwise it is not allowed.
RETURN VALUE
------------
On success, an object as follows is returned:
* *invstring*: the bolt12-encoded invoice string we sent (now paid), starting with "lni1".
* *msat*: the amount they paid.
The following error codes may occur:
- -1: Catchall nonspecific error.
- 1002: Offer has expired.
- 1003: Cannot find a route to the node making the offer.
- 1004: The node making the offer returned an error message.
- 1005: We timed out waiting for the invoice to be paid
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-fetchinvoice(7).
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>