mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-20 02:27:51 +01:00
Code Issues Projects Releases Wiki Activity
eb6b8551d4
core-lightning/doc/lightning-sendinvoice.7.md

84 lines
3.0 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-sendinvoice -- Command for send 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
**sendinvoice** *offer* *label* [*amount\_msat*] [*timeout*] [*quantity*]
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 **sendinvoice** RPC command creates and sends an invoice to the
issuer of an *offer* for it to pay: the offer must contain
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
*send\_invoice*; see lightning-fetchinvoice(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
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: 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
*offer* is the bolt12 offer string beginning with "lno1".
*label* is the unique label to use for this invoice.
doc: replace deprecated parameter keyword "msatoshi" with "amount_msat" [ amount\_msat -- RR ]
2022-12-10 09:10:19 +01:00
*amount\_msat* is optional: it is required if the *offer* does not specify
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
an amount at all, or specifies it in a different currency. Otherwise
you may set it (e.g. to provide a tip), and if not it defaults to the
amount contained in the offer (multiplied by *quantity* if any).
*timeout* is how many seconds to wait for the offering node to pay the
sendinvoice: don't allow separate invoice and command timeouts. It was too confusing, and can be added later if desired. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-01-07 19:53:47 +01:00
invoice or return an error, default 90 seconds. This will also be the
timeout on the invoice that is sent.
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 optional: it is required if the *offer* specifies
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
*quantity\_min* or *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
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: 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): unique label supplied at invoice creation
- **description** (string): description used in the invoice
fromschema.py: escape underscores in descriptions
2022-11-11 03:03:13 +01:00
- **payment\_hash** (hex): the hash of the *payment\_preimage* which will prove payment (always 64 characters)
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
- **status** (string): Whether it's paid, unpaid or unpayable (one of "unpaid", "paid", "expired")
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
- **expires\_at** (u64): UNIX timestamp of when it will become / became unpayable
- **amount\_msat** (msat, optional): the amount required to pay this invoice
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, optional): the BOLT12 string
If **status** is "paid":
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: 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
- **pay\_index** (u64): Unique incrementing index for this payment
fromschema.py: escape underscores in descriptions
2022-11-11 03:03:13 +01:00
- **amount\_received\_msat** (msat): the amount actually received (could be slightly greater than *amount\_msat*, since clients may overpay)
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
- **paid\_at** (u64): UNIX timestamp of when it was paid
- **payment\_preimage** (hex): proof of payment (always 64 characters)
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
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 waiting for the invoice to be paid
AUTHOR
------
Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible.
SEE ALSO
--------
lightning-fetchinvoice(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:a088e5202cb822518a2214b485083edf0a929290b17beb9a3930dd93d97411d0)
Reference in New Issue Copy Permalink