131 lines
4.2 KiB
Groff
131 lines
4.2 KiB
Groff
|
.\" -*- mode: troff; coding: utf-8 -*-
|
||
|
.TH "LIGHTNING-OFFEROUT" "7" "" "Core Lightning 0.12.1" ""
|
||
|
.SH
|
||
|
NAME
|
||
|
.LP
|
||
|
lightning-offerout -- Command for offering payments
|
||
|
.SH
|
||
|
SYNOPSIS
|
||
|
.LP
|
||
|
\fB(WARNING: experimental-offers only)\fR
|
||
|
.PP
|
||
|
\fBofferout\fR \fIamount\fR \fIdescription\fR [\fIissuer\fR] [\fIlabel\fR] [\fIabsolute_expiry\fR] [\fIrefund_for\fR]
|
||
|
.SH
|
||
|
DESCRIPTION
|
||
|
.LP
|
||
|
The \fBofferout\fR RPC command creates an offer, which is a request to
|
||
|
send an invoice for us to pay (technically, this is referred to as a
|
||
|
\fCsend_invoice\fR offer to distinguish a normal lightningd-offer(7)
|
||
|
offer). It automatically enables the accepting and payment of
|
||
|
corresponding invoice message (we will only pay once, however!).
|
||
|
.PP
|
||
|
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.
|
||
|
.PP
|
||
|
The \fIamount\fR parameter can be the string \(dqany\(dq, 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.
|
||
|
.PP
|
||
|
The \fIdescription\fR is a short description of purpose of the offer,
|
||
|
e.g. \fIwithdrawl from ATM\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\eu\fR JSON escape codes.
|
||
|
.PP
|
||
|
The \fIissuer\fR is another (optional) field exposed in the offer, and
|
||
|
reflects who is issuing this offer (i.e. you) if appropriate.
|
||
|
.PP
|
||
|
The \fIlabel\fR field is an internal-use name for the offer, which can
|
||
|
be any UTF-8 string.
|
||
|
.PP
|
||
|
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.
|
||
|
.PP
|
||
|
\fIrefund_for\fR is a previous (paid) invoice of ours. The
|
||
|
payment_preimage of this is encoded in the offer, and redemption
|
||
|
requires that the invoice we receive contains a valid signature using
|
||
|
that previous \fCpayer_key\fR.
|
||
|
.SH
|
||
|
RETURN VALUE
|
||
|
.LP
|
||
|
On success, an object is returned, containing:
|
||
|
.IP "\(bu" 2
|
||
|
\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters)
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBactive\fR (boolean): whether this will pay a matching incoming invoice (always \fItrue\fR)
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBsingle_use\fR (boolean): whether this expires as soon as it's paid out (always \fItrue\fR)
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBbolt12\fR (string): the bolt12 encoding of the offer
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBbolt12_unsigned\fR (string): the bolt12 encoding of the offer, without a signature
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBused\fR (boolean): True if an incoming invoice has been paid (always \fIfalse\fR)
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBcreated\fR (boolean): false if the offer already existed
|
||
|
.if n \
|
||
|
.sp -1
|
||
|
.if t \
|
||
|
.sp -0.25v
|
||
|
.IP "\(bu" 2
|
||
|
\fBlabel\fR (string, optional): the (optional) user-specified label
|
||
|
.LP
|
||
|
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.
|
||
|
.PP
|
||
|
The following error codes may occur:
|
||
|
- -1: Catchall nonspecific error.
|
||
|
- 1000: Offer with this offer_id already exists.
|
||
|
.SH
|
||
|
NOTES
|
||
|
.LP
|
||
|
The specification allows quantity, recurrence and alternate currencies on
|
||
|
offers which contain \fCsend_invoice\fR, but these are not implemented here.
|
||
|
.PP
|
||
|
We could also allow multi-use offers, but usually you're only offering to
|
||
|
send money once.
|
||
|
.SH
|
||
|
AUTHOR
|
||
|
.LP
|
||
|
Rusty Russell <\fIrusty@rustcorp.com.au\fR> is mainly responsible.
|
||
|
.SH
|
||
|
SEE ALSO
|
||
|
.LP
|
||
|
lightning-sendinvoice(7), lightning-offer(7), lightning-listoffers(7), lightning-disableoffer(7).
|
||
|
.SH
|
||
|
RESOURCES
|
||
|
.LP
|
||
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||
|
\" SHA256STAMP:ea91032636be21415005cc735ad2aa31151552f058b1fd0b5455db39b7829549
|