mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 18:11:28 +01:00
Code Issues Projects Releases Wiki Activity
0cf2c29b5c
core-lightning/doc/lightning-offer.7.md

134 lines
5.6 KiB
Markdown
Raw Normal View History

doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
lightning-offer -- Command for accepting payments
=================================================
SYNOPSIS
--------
doc: note where experimental-offers is required or affects commands. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-14 04:36:59 +01:00
**(WARNING: experimental-offers only)**
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
**offer** *amount* *description* [*issuer*] [*label*] [*quantity\_max*] [*absolute\_expiry*] [*recurrence*] [*recurrence\_base*] [*recurrence\_paywindow*] [*recurrence\_limit*] [*single\_use*]
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
DESCRIPTION
-----------
offer / offerout: return existing if its still active. As requested by @shesek: it's weird to fail if they ask for the exact same thing (which is quite possible, since offers don't expire by default). And add a new "created" field so they can tell if they have an old one. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-07-21 07:37:49 +02:00
The **offer** RPC command creates an offer (or returns an existing
one), which is a precursor to creating one or more invoices. It
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
automatically enables the processing of an incoming invoice\_request,
offer / offerout: return existing if its still active. As requested by @shesek: it's weird to fail if they ask for the exact same thing (which is quite possible, since offers don't expire by default). And add a new "created" field so they can tell if they have an old one. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-07-21 07:37:49 +02:00
and issuing of invoices.
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
random doc changes to test. [Moved into a separate commit --RR]
2023-08-03 07:13:59 +02:00
Note that for making an offer to *pay* someone else, see lightning-invoicerequest(7).
offers: signatures are now optional. As per latest spec revision. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-EXPERIMENTAL: BOLT12 offers can now be unsigned, for really short QR codes.
2021-07-02 02:11:34 +02:00
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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
offers: convert currency when they request an invoice. Means a reshuffle of our logic: we want to multiply by quantity before conversion for maximum accuracy. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-09 05:25:46 +01:00
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.
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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.
bolt12: update to latest spec. Main changes are: 1. Uses point32 instead of pubkey32. 2. Uses issuer instead of vendor. 3. Uses byte instead of u8. 4. blinded_path num_hops is now a byte, not u16 (we don't use that yet!). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-EXPERIMENTAL: bolt12: `vendor` is deprecated: the field is now called `issuer`.
2021-10-08 02:52:34 +02:00
The *issuer* is another (optional) field exposed in the offer, and
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
reflects who is issuing this offer (i.e. you) if appropriate.
The *label* field is an internal-use name for the offer, which can
doc: update documentation for fetchinvoice(7) and offer(7). 1. Don't refer to obsolete send_invoice flag. 2. Don't refer to obsolete quantity_min field. 3. Don't refer to unsigned vs signed offers: they're all unsigned. 4. Add references to invoicerequest(7). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-03-06 04:47:18 +01:00
be any UTF-8 string. This is *NOT* encoded in the offer not sent
to the issuer.
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
The presence of *quantity\_max* indicates that the
bolt12: import the latest spec, update to fit. I know this is an unforgivably large diff, but the spec has changed so much that most of this amounts to a rewrite. Some points: * We no longer have "offer_id" fields, we generate that locally, as all offer fields are mirrored into invoice_request and then invoice. * Because of that mirroring, field names all have explicit offer/invreq/invoice prefixes. * The `refund_for` fields have been removed from spec: will re-add locally later. * quantity_min was removed, max == 0 now mean "must specify a quantity". * I have put recurrence fields back in locally. This brings us to 655df03d8729c0918bdacac99eb13fdb0ee93345 ("BOLT 12: add explicit invoice_node_id.") Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-11-09 03:32:00 +01:00
invoice can specify more than one of the items up (and including)
this maximum: 0 is a special value meaning "no maximuim".
The *amount* for the invoice will need to be multiplied
accordingly. This is encoded in the offer.
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
The *absolute\_expiry* is optionally the time the offer is valid until,
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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".
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
*recurrence\_base* is an optional time in seconds since the first day
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
*recurrence\_paywindow* is an optional argument of form
Remove useless \
2022-01-26 18:18:49 +01:00
'-time+time[%]'. The first time is the number of seconds before the
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
*recurrence\_limit* is an optional argument to indicate the maximum
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
period which exists. eg. "12" means there are 13 periods, from 0 to
12 inclusive. This is encoded in the offer.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
*single\_use* (default false) indicates that the offer is only valid
offers: split offer send_invoice generation into new JSON command 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>
2021-01-07 19:46:47 +01:00
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).
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
RETURN VALUE
------------
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
doc: generate correct markdown from schemas. You can't start a list without a paragraph separator. ```diff --- /tmp/before 2022-07-20 22:02:23.485372596 +0930 +++ /tmp/after 2022-07-20 22:02:33.745528456 +0930 @@ -21,12 +21,16 @@ On startup of the daemon, no autoclean is set up. RETURN VALUE - On success, an object is returned, containing: - enabled (boolean): - whether invoice autocleaning is active + On success, an object is returned, containing: - If enabled is true: - expired_by (u64): how long an invoice must be ex‐ - pired (seconds) before we delete it - cycle_seconds (u64): how long an - invoice must be expired (seconds) before we delete it + • enabled (boolean): whether invoice autocleaning is active + + If enabled is true: + + • expired_by (u64): how long an invoice must be expired (seconds) be‐ + fore we delete it + • cycle_seconds (u64): how long an invoice must be expired (seconds) + before we delete it AUTHOR ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible. ``` Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-05 23:33:09 +02:00
doc: use specific types in schema rather than "hex". We have "secret" and "hash" types which are often more appropriate. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-01-30 07:24:17 +01:00
- **offer\_id** (hash): the id of this offer (merkle hash of non-signature fields)
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
- **active** (boolean): whether this can still be used (always *true*)
fromschema.py: escape underscores in descriptions
2022-11-11 03:03:13 +01:00
- **single\_use** (boolean): whether this expires as soon as it's paid (reflects the *single\_use* parameter)
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
- **bolt12** (string): the bolt12 encoding of the offer
offer / offerout: return existing if its still active. As requested by @shesek: it's weird to fail if they ask for the exact same thing (which is quite possible, since offers don't expire by default). And add a new "created" field so they can tell if they have an old one. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-07-21 07:37:49 +02:00
- **used** (boolean): True if an associated invoice has been paid
- **created** (boolean): false if the offer already existed
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
- **label** (string, optional): the (optional) user-specified label
doc: fix GH/readthedocs rendering of manual pages. They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-09-03 12:07:59 +02:00
doc: schemas for everything else. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Fixed: doc: Epic documentation rewrite: each now lists complete and accurate JSON output, tested against testsuite.
2021-06-16 03:10:17 +02:00
[comment]: # (GENERATE-FROM-SCHEMA-END)
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
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.
offer / offerout: return existing if its still active. As requested by @shesek: it's weird to fail if they ask for the exact same thing (which is quite possible, since offers don't expire by default). And add a new "created" field so they can tell if they have an old one. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-07-21 07:37:49 +02:00
If the offer already existed, and is still active, that is returned;
if it's not active then this call fails.
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
The following error codes may occur:
- -1: Catchall nonspecific error.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-11 02:44:56 +01:00
- 1000: Offer with this offer\_id already exists (but is not active).
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
doc: update documentation for fetchinvoice(7) and offer(7). 1. Don't refer to obsolete send_invoice flag. 2. Don't refer to obsolete quantity_min field. 3. Don't refer to unsigned vs signed offers: they're all unsigned. 4. Add references to invoicerequest(7). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-03-06 04:47:18 +01:00
lightning-listoffers(7), lightning-disableoffer(7), lightning-invoicerequest(7).
doc: document experimental commands. Not the low-level ones, just enough that people can play with the APIs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:45:47 +01:00
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
doc: use specific types in schema rather than "hex". We have "secret" and "hash" types which are often more appropriate. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-01-30 07:24:17 +01:00
[comment]: # ( SHA256STAMP:3ad09aed48fb17db5fae6d401f21e50a4479e970199bd039b453868057829653)
Reference in New Issue Copy Permalink