Browse Source
We split `send_invoice` offers inoo offerout (for want of a better name). This simplifies the API. Also took the opportunity to move the `vendor` tag to immediately follow `description` (our tests use arguments by keywords, so no change there). Suggested-by: shesek Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>ppa
Rusty Russell
4 years ago
10 changed files with 330 additions and 85 deletions
@ -0,0 +1,113 @@ |
|||||
|
.TH "LIGHTNING-OFFEROUT" "7" "" "" "lightning-offerout" |
||||
|
.SH NAME |
||||
|
lightning-offerout - Command for offering payments |
||||
|
.SH SYNOPSIS |
||||
|
|
||||
|
\fIEXPERIMENTAL_FEATURES only\fR |
||||
|
|
||||
|
|
||||
|
\fBofferout\fR \fIamount\fR \fIdescription\fR [\fIvendor\fR] [\fIlabel\fR] [\fIabsolute_expiry\fR] [\fIrefund_for\fR] |
||||
|
|
||||
|
.SH DESCRIPTION |
||||
|
|
||||
|
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 |
||||
|
\fBsend_invoice\fR offer to distinguish a normal \fBlightningd-offer\fR(7) |
||||
|
offer)\. It automatically enables the accepting and payment of |
||||
|
corresponding invoice message (we will only pay once, however!)\. |
||||
|
|
||||
|
|
||||
|
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\. |
||||
|
|
||||
|
|
||||
|
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\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 \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\. |
||||
|
|
||||
|
|
||||
|
\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 \fBpayer_key\fR\. |
||||
|
|
||||
|
.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 |
||||
|
.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 NOTES |
||||
|
|
||||
|
The specification allows quantity, recurrence and alternate currencies on |
||||
|
offers which contain \fBsend_invoice\fR, but these are not implemented here\. |
||||
|
|
||||
|
|
||||
|
We could also allow multi-use offers, but usually you're only offering to |
||||
|
send money once\. |
||||
|
|
||||
|
.SH AUTHOR |
||||
|
|
||||
|
Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\. |
||||
|
|
||||
|
.SH SEE ALSO |
||||
|
|
||||
|
\fBlightning-offer\fR(7), \fBlightning-listoffers\fR(7), \fBlightning-deloffer\fR(7)\. |
||||
|
|
||||
|
.SH RESOURCES |
||||
|
|
||||
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR |
||||
|
|
||||
|
\" SHA256STAMP:092f0d776162906eb1045b31caccc7e5eb9fdfa7ba233570f867310ea441ebe5 |
||||
@ -0,0 +1,93 @@ |
|||||
|
lightning-offerout -- Command for offering payments |
||||
|
================================================= |
||||
|
|
||||
|
SYNOPSIS |
||||
|
-------- |
||||
|
|
||||
|
*EXPERIMENTAL_FEATURES only* |
||||
|
|
||||
|
**offerout** *amount* *description* \[*vendor*\] \[*label*\] \[*absolute_expiry*\] \[*refund_for*\] |
||||
|
|
||||
|
DESCRIPTION |
||||
|
----------- |
||||
|
|
||||
|
The **offerout** RPC command creates an offer, which is a request to |
||||
|
send an invoice for us to pay (technically, this is referred to as a |
||||
|
`send_invoice` 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!). |
||||
|
|
||||
|
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*. |
||||
|
|
||||
|
The *description* is a short description of purpose of the offer, |
||||
|
e.g. *withdrawl from ATM*. 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 *label* field is an internal-use name for the offer, which can |
||||
|
be any UTF-8 string. |
||||
|
|
||||
|
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. |
||||
|
|
||||
|
*refund_for* 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 `payer_key`. |
||||
|
|
||||
|
RETURN VALUE |
||||
|
------------ |
||||
|
|
||||
|
On success, an object as follows is returned: |
||||
|
|
||||
|
* *offer_id*: the hash of the offer. |
||||
|
* *active*: true |
||||
|
* *single_use*: true |
||||
|
* *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. |
||||
|
|
||||
|
NOTES |
||||
|
----- |
||||
|
|
||||
|
The specification allows quantity, recurrence and alternate currencies on |
||||
|
offers which contain `send_invoice`, but these are not implemented here. |
||||
|
|
||||
|
We could also allow multi-use offers, but usually you're only offering to |
||||
|
send money once. |
||||
|
|
||||
|
AUTHOR |
||||
|
------ |
||||
|
|
||||
|
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. |
||||
|
|
||||
|
SEE ALSO |
||||
|
-------- |
||||
|
|
||||
|
lightning-offer(7), lightning-listoffers(7), lightning-deloffer(7). |
||||
|
|
||||
|
RESOURCES |
||||
|
--------- |
||||
|
|
||||
|
Main web site: <https://github.com/ElementsProject/lightning> |
||||
|
|
||||
Loading…
Reference in new issue