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>ppa
Rusty Russell
4 years ago
8 changed files with 668 additions and 0 deletions
@ -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 |
||||
@ -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> |
||||
|
|
||||
@ -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 |
||||
@ -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> |
||||
|
|
||||
@ -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 |
||||
@ -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> |
||||
|
|
||||
Loading…
Reference in new issue