mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
6d1897b796
They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
163 lines
6.1 KiB
Groff
Generated
163 lines
6.1 KiB
Groff
Generated
.TH "LIGHTNING-OFFER" "7" "" "" "lightning-offer"
|
|
.SH NAME
|
|
lightning-offer - Command for accepting payments
|
|
.SH SYNOPSIS
|
|
|
|
\fB(WARNING: experimental-offers only)\fR
|
|
|
|
|
|
\fBoffer\fR \fIamount\fR \fIdescription\fR [\fIvendor\fR] [\fIlabel\fR] [\fIquantity_min\fR] [\fIquantity_max\fR] [\fIabsolute_expiry\fR] [\fIrecurrence\fR] [\fIrecurrence_base\fR] [\fIrecurrence_paywindow\fR] [\fIrecurrence_limit\fR] [\fIsingle_use\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fBoffer\fR RPC command creates an offer (or returns an existing
|
|
one), which is a precursor to creating one or more invoices\. It
|
|
automatically enables the processing of an incoming invoice_request,
|
|
and issuing of invoices\.
|
|
|
|
|
|
Note that it creates two variants of the offer: a signed and an
|
|
unsigned one (which is smaller)\. Wallets should accept both: the
|
|
current specification allows either\.
|
|
|
|
|
|
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\. A
|
|
plugin is needed which provides the "currencyconvert" API for this
|
|
currency, otherwise the offer creation will fail\.
|
|
|
|
|
|
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 \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) indicates that the offer is only valid
|
|
once; we may issue multiple invoices, but as soon as one is paid all other
|
|
invoices will be expired (i\.e\. only one person can pay this offer)\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
|
|
.IP \[bu]
|
|
\fBactive\fR (boolean): whether this can still be used (always \fItrue\fR)
|
|
.IP \[bu]
|
|
\fBsingle_use\fR (boolean): whether this expires as soon as it's paid (reflects the \fIsingle_use\fR parameter)
|
|
.IP \[bu]
|
|
\fBbolt12\fR (string): the bolt12 encoding of the offer
|
|
.IP \[bu]
|
|
\fBbolt12_unsigned\fR (string): the bolt12 encoding of the offer, without a signature
|
|
.IP \[bu]
|
|
\fBused\fR (boolean): True if an associated invoice has been paid
|
|
.IP \[bu]
|
|
\fBcreated\fR (boolean): false if the offer already existed
|
|
.IP \[bu]
|
|
\fBlabel\fR (string, optional): the (optional) 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\.
|
|
|
|
|
|
If the offer already existed, and is still active, that is returned;
|
|
if it's not active then this call fails\.
|
|
|
|
|
|
The following error codes may occur:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
-1: Catchall nonspecific error\.
|
|
.IP \[bu]
|
|
1000: Offer with this offer_id already exists (but is not active)\.
|
|
|
|
.RE
|
|
.SH AUTHOR
|
|
|
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBlightning-offerout\fR(7), \fBlightning-listoffers\fR(7), \fBlightning-disableoffer\fR(7)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
\" SHA256STAMP:caa067d4f2b43e99445f165545fe98593402fbb6f10d939067ed2bc963e3fdc3
|