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
703ffdf59b
core-lightning/doc/lightning-fetchinvoice.7.md

93 lines
3.7 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-fetchinvoice -- Command for fetch an invoice for an offer
===================================================================
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: replace deprecated parameter keyword "msatoshi" with "amount_msat" [ amount\_msat -- RR ]
2022-12-10 09:10:19 +01:00
**fetchinvoice** *offer* [*amount\_msat*] [*quantity*] [*recurrence\_counter*] [*recurrence\_start*] [*recurrence\_label*] [*timeout*] [*payer\_note*]
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
-----------
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.
fetchinvoice: try to connect to note if we can't find a path for messages. This also adds a `fetchinvoice-noconnect` option to suppress it too. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-EXPERIMENTAL: `fetchinvoice` and `sendinvoice` will connect directly if they can't find an onionmessage route. Fixes: #4624
2021-07-01 06:28:57 +02:00
If **fetchinvoice-noconnect** is not specified in the configuation, it
will connect to the destination in the (currently common!) case where it
cannot find a route which supports `option_onion_messages`.
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
*amount\_msat* is required if the *offer* does not specify an amount
at all, otherwise it is optional (but presumably if you set it to less
than the offer, you will get an error from 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
*quantity* is is required if the *offer* specifies
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
*quantity\_max*, otherwise it is not allowed.
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
*recurrence\_counter* is required if 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
specifies *recurrence*, otherwise it is not allowed.
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\_counter* should first be set to 0, and incremented for
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
each successive invoice in a given series.
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\_start* is required if the *offer*
specifies *recurrence\_base* with *start\_any\_period* set, otherwise it
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
is not allowed. It indicates what period number to start at.
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\_label* is required if *recurrence\_counter* is set, 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
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).
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
*payer\_note* is an optional payer note to ask the issuer to include
in the fetched invoice.
docs/fetchinvoice: document payer_note Signed-off-by: William Casarin <jb55@jb55.com>
2021-09-03 21:09:11 +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
RETURN VALUE
------------
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +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/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **invoice** (string): The BOLT12 invoice we fetched
- **changes** (object): Summary of changes from offer:
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-05 23:45:06 +02:00
- **description\_appended** (string, optional): extra characters appended to the *description* field.
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **description** (string, optional): a completely replaced *description* field
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-05 23:45:06 +02:00
- **vendor\_removed** (string, optional): The *vendor* from the offer, which is missing in the invoice
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **vendor** (string, optional): a completely replaced *vendor* field
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-05 23:45:06 +02:00
- **amount\_msat** (msat, optional): the amount, if different from the offer amount multiplied by any *quantity* (or the offer had no amount, or was not in BTC).
fromschema.py: escape underscores in descriptions
2022-11-11 03:03:13 +01:00
- **next\_period** (object, optional): Only for recurring invoices if the next period is under the *recurrence\_limit*:
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +02:00
- **counter** (u64): the index of the next period to fetchinvoice
- **starttime** (u64): UNIX timestamp that the next period starts
- **endtime** (u64): UNIX timestamp that the next period ends
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-05 23:45:06 +02:00
- **paywindow\_start** (u64): UNIX timestamp of the earliest time that the next invoice can be fetched
- **paywindow\_end** (u64): UNIX timestamp of the latest time that the next invoice can be fetched
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: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 09:35:01 +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
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>
tools/fromschema.py: don't try to handle more complex cases. We only handle top-level objects with an array of objects: make sure it is one before we call the routines. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-01-30 07:24:16 +01:00
[comment]: # ( SHA256STAMP:c14601b72fda248cbc8b86253bda6399a0886fc1fd0332d3acbc1d8800342126)
Reference in New Issue Copy Permalink