From 27cebe39f4ef54fb4dbbc48a4cc6c087eba8adc4 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Thu, 21 Dec 2023 14:20:30 -0800 Subject: [PATCH] Errors --- doc/lightning-datastore.7.md | 2 + doc/lightning-fetchinvoice.7.md | 3 ++ doc/lightning-fundchannel.7.md | 4 +- doc/lightning-invoice.7.md | 56 -------------------- doc/lightning-invoicerequest.7.md | 27 ---------- doc/lightning-keysend.7.md | 19 ++----- doc/lightning-listchannels.7.md | 9 ---- doc/lightning-listclosedchannels.7.md | 4 -- doc/lightning-listdatastore.7.md | 6 +-- doc/lightning-listforwards.7.md | 12 ----- doc/lightning-listfunds.7.md | 3 -- doc/lightning-listhtlcs.7.md | 4 +- doc/lightning-listinvoicerequests.7.md | 5 -- doc/lightning-listinvoices.7.md | 10 +--- doc/lightning-listpays.7.md | 1 - doc/lightning-listpeerchannels.7.md | 3 -- doc/lightning-listpeers.7.md | 7 --- doc/lightning-listsendpays.7.md | 11 +--- doc/lightning-makesecret.7.md | 5 +- doc/lightning-newaddr.7.md | 10 +--- doc/lightning-notifications.7.md | 7 ++- doc/lightning-pay.7.md | 3 ++ doc/lightning-renepay.7.md | 3 ++ doc/lightning-sendinvoice.7.md | 3 ++ doc/lightning-txdiscard.7.md | 3 ++ doc/schemas/decodepay.request.json | 6 ++- doc/schemas/invoice.request.json | 33 +++++------- doc/schemas/invoicerequest.request.json | 12 ++--- doc/schemas/keysend.request.json | 24 ++++++--- doc/schemas/listchannels.request.json | 6 +-- doc/schemas/listclosedchannels.request.json | 2 +- doc/schemas/listdatastore.request.json | 5 +- doc/schemas/listforwards.request.json | 13 +++-- doc/schemas/listfunds.request.json | 2 +- doc/schemas/listhtlcs.request.json | 2 +- doc/schemas/listinvoicerequests.request.json | 4 +- doc/schemas/listinvoices.request.json | 21 ++++---- doc/schemas/listpays.request.json | 7 ++- doc/schemas/listpeers.request.json | 10 +++- doc/schemas/listsendpays.request.json | 15 +++--- doc/schemas/makesecret.request.json | 4 +- doc/schemas/newaddr.request.json | 1 + doc/schemas/showrunes.request.json | 2 +- 43 files changed, 131 insertions(+), 258 deletions(-) diff --git a/doc/lightning-datastore.7.md b/doc/lightning-datastore.7.md index dae548fb6ea8..af81f63fc2d6 100644 --- a/doc/lightning-datastore.7.md +++ b/doc/lightning-datastore.7.md @@ -43,6 +43,8 @@ On success, an object is returned, containing: [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ The following error codes may occur: diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md index 34da01cec6da..7650adc9e730 100644 --- a/doc/lightning-fetchinvoice.7.md +++ b/doc/lightning-fetchinvoice.7.md @@ -41,6 +41,9 @@ On success, an object is returned, containing: [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index b97a1497378f..06d389228738 100644 --- a/doc/lightning-fundchannel.7.md +++ b/doc/lightning-fundchannel.7.md @@ -39,8 +39,8 @@ On success, an object is returned, containing: - **close_to** (hex, optional): The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script` - **mindepth** (u32, optional): Number of confirmations before we consider the channel active. -ERROR ------- +ERRORS +------- The following error codes may occur: diff --git a/doc/lightning-invoice.7.md b/doc/lightning-invoice.7.md index 5d84b340ec11..e669945bafa3 100644 --- a/doc/lightning-invoice.7.md +++ b/doc/lightning-invoice.7.md @@ -16,62 +16,6 @@ lightning daemon can use to pay this invoice. This token includes a *route hint* description of an incoming channel with capacity to pay the invoice, if any exists. -The *amount\_msat* parameter can be the string "any", which creates an -invoice that can be paid with any amount. Otherwise it is 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 *label* must be a unique string or number (which is treated as a -string, so "01" is different from "1"); it is never revealed to other -nodes on the lightning network, but it can be used to query the status -of this invoice. - -The *description* is a short description of purpose of payment, e.g. *1 -cup of coffee*. This value is encoded into the BOLT11 invoice and is -viewable by any node you send this invoice to (unless *deschashonly* is -true as described below). It must be UTF-8, and cannot use *\\u* JSON -escape codes. - -The *expiry* is optionally the time the invoice is valid for, in seconds. -If no value is provided the default of 604800 (1 week) is used. - -The *fallbacks* array is one or more fallback addresses to include in -the invoice (in order from most-preferred to least): note that these -arrays are not currently tracked to fulfill the invoice. - -The *preimage* is a 64-digit hex string to be used as payment preimage -for the created invoice. By default, if unspecified, lightningd will -generate a secure pseudorandom preimage seeded from an appropriate -entropy source on your system. **IMPORTANT**: if you specify the -*preimage*, you are responsible, to ensure appropriate care for -generating using a secure pseudorandom generator seeded with sufficient -entropy, and keeping the preimage secret. This parameter is an advanced -feature intended for use with cutting-edge cryptographic protocols and -should not be used unless explicitly needed. - -If specified, *exposeprivatechannels* overrides the default route hint -logic, which will use unpublished channels only if there are no -published channels. If *true* unpublished channels are always considered -as a route hint candidate; if *false*, never. If it is a short channel id -(e.g. *1x1x3*) or array of short channel ids (or a remote alias), only those specific channels -will be considered candidates, even if they are public or dead-ends. - -The route hint is selected from the set of incoming channels of which: -peer's balance minus their reserves is at least *amount\_msat*, state is -normal, the peer is connected and not a dead end (i.e. has at least one -other public channel). The selection uses some randomness to prevent -probing, but favors channels that become more balanced after the -payment. - -If specified, *cltv* sets the *min\_final\_cltv\_expiry* for the invoice. -Otherwise, it's set to the parameter **cltv-final**. - -If *deschashonly* is true (default false), then the bolt11 returned -contains a hash of the *description*, rather than the *description* -itself: this allows much longer descriptions, but they must be -communicated via some other mechanism. - RETURN VALUE ------------ diff --git a/doc/lightning-invoicerequest.7.md b/doc/lightning-invoicerequest.7.md index a9373ce888cf..ab8eb7374cff 100644 --- a/doc/lightning-invoicerequest.7.md +++ b/doc/lightning-invoicerequest.7.md @@ -17,33 +17,6 @@ invoice, and payment of it. The reader of the resulting `invoice_request` can use lightning-sendinvoice(7) to collect their payment. -The *amount* parameter 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 payment, -e.g. *ATM withdrawl*. This value is encoded into the resulting -`invoice_request` and is viewable by anyone you expose it to. It must -be UTF-8, and cannot use *\\u* JSON escape codes. - -The *issuer* is another (optional) field exposed in the -`invoice_request`, and reflects who is issuing it (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 -`invoice_request` remains valid (though it can be deactivated by the -issuer of course). This is encoded in the `invoice_request`. - -*single\_use* (default true) indicates that the `invoice_request` is -only valid once; we may attempt multiple payments, but as soon as one -is successful no more invoices are accepted (i.e. only one person can -take the money). - RETURN VALUE ------------ diff --git a/doc/lightning-keysend.7.md b/doc/lightning-keysend.7.md index c0f47dbb56d9..df206b399b1a 100644 --- a/doc/lightning-keysend.7.md +++ b/doc/lightning-keysend.7.md @@ -22,22 +22,6 @@ generated on the destination, and the only way sender could have it is by sending a payment. Please ensure that this matches your use-case when using `keysend`. -`destination` is the 33 byte, hex-encoded, node ID of the node that the payment should go to. -`amount\_msat` is in millisatoshi precision; it can be a whole number, or a whole number with suffix `msat` or `sat`, or a three decimal point number with suffix `sat`, or an 1 to 11 decimal point number suffixed by `btc`. - -The `label` field is used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7). -The `maxfeepercent` limits the money paid in fees as percentage of the total amount that is to be transferred, and defaults to *0.5*. -The `exemptfee` option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. -Setting `exemptfee` allows the `maxfeepercent` check to be skipped on fees that are smaller than *exemptfee* (default: 5000 millisatoshi). - -The response will occur when the payment fails or succeeds. -Unlike lightning-pay(7), issuing the same `keysend` commands multiple times will result in multiple payments being sent. - -Until *retry\_for* seconds passes (default: 60), the command will keep finding routes and retrying the payment. -However, a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case. - -*extratlvs* is an optional dictionary of additional fields to insert into the final tlv. The format is 'fieldnumber': 'hexstring'. - When using *lightning-cli*, you may skip optional parameters by using *null*. Alternatively, use **-k** option to provide parameters by name. @@ -87,6 +71,9 @@ The following warnings may also be returned: You can monitor the progress and retries of a payment using the lightning-paystatus(7) command. +ERRORS +------ + The following error codes may occur: - `-1`: Catchall nonspecific error. diff --git a/doc/lightning-listchannels.7.md b/doc/lightning-listchannels.7.md index 1082f2516aac..dd8e63745fef 100644 --- a/doc/lightning-listchannels.7.md +++ b/doc/lightning-listchannels.7.md @@ -13,15 +13,6 @@ The **listchannels** RPC command returns data on channels that are known to the node. Because channels may be bidirectional, up to 2 objects will be returned for each channel (one for each direction). -If *short\_channel\_id* is a short channel id, then only known channels with a -matching *short\_channel\_id* are returned. Otherwise, it must be null. - -If *source* is a node id, then only channels leading from that node id -are returned. - -If *destination* is a node id, then only channels leading to that node id -are returned. - Only one of *short\_channel\_id*, *source* or *destination* can be supplied. If nothing is supplied, data on all lightning channels known to this node, are returned. These can be local channels or public channels diff --git a/doc/lightning-listclosedchannels.7.md b/doc/lightning-listclosedchannels.7.md index 35f0d6da37da..4e88c4e33164 100644 --- a/doc/lightning-listclosedchannels.7.md +++ b/doc/lightning-listclosedchannels.7.md @@ -13,10 +13,6 @@ The **listclosedchannels** RPC command returns data on channels which are otherwise forgotten (more than 100 blocks after they're completely resolved onchain). -If no *id* is supplied, then channel data on all historical channels are given. - -Supplying *id* will filter the results to only match channels to that peer. Note that prior to v23.05, old peers were forgotten. - RETURN VALUE ------------ diff --git a/doc/lightning-listdatastore.7.md b/doc/lightning-listdatastore.7.md index 22c66d28362e..64cffa6a8d73 100644 --- a/doc/lightning-listdatastore.7.md +++ b/doc/lightning-listdatastore.7.md @@ -12,9 +12,6 @@ DESCRIPTION The **listdatastore** RPC command allows plugins to fetch data which was stored in the Core Lightning database. -All immediate children of the *key* (or root children) are returned: -a *key* with children won't have a *hex* or *generation* entry. - RETURN VALUE ------------ @@ -29,6 +26,9 @@ On success, an object containing **datastore** is returned. It is an array of o [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - -32602: invalid parameters. diff --git a/doc/lightning-listforwards.7.md b/doc/lightning-listforwards.7.md index 964d2321cd1b..de0ebb98f67e 100644 --- a/doc/lightning-listforwards.7.md +++ b/doc/lightning-listforwards.7.md @@ -12,18 +12,6 @@ DESCRIPTION The **listforwards** RPC command displays all htlcs that have been attempted to be forwarded by the Core Lightning node. -If *status* is specified, then only the forwards with the given status are returned. -*status* can be either *offered* or *settled* or *failed* or *local\_failed* - -If *in\_channel* or *out\_channel* is specified, then only the matching forwards -on the given in/out channel are returned. - -If neither *in\_channel* or *out\_channel* is specified, -`index` controls ordering, by `created` (default) or `updated`. If -`index` is specified, `start` may be specified to start from that -value, which is generally returned from lightning-wait(7), and `limit` -can be used to specify the maximum number of entries to return. - RETURN VALUE ------------ diff --git a/doc/lightning-listfunds.7.md b/doc/lightning-listfunds.7.md index d3cbdc8d76ca..69782968110d 100644 --- a/doc/lightning-listfunds.7.md +++ b/doc/lightning-listfunds.7.md @@ -13,9 +13,6 @@ The **listfunds** RPC command displays all funds available, either in unspent outputs (UTXOs) in the internal wallet or funds locked in currently open channels. -*spent* is a boolean: if true, then the *outputs* will include spent outputs -in addition to the unspent ones. Default is false. - RETURN VALUE ------------ diff --git a/doc/lightning-listhtlcs.7.md b/doc/lightning-listhtlcs.7.md index e85f84ff211a..b402df79e3ff 100644 --- a/doc/lightning-listhtlcs.7.md +++ b/doc/lightning-listhtlcs.7.md @@ -11,9 +11,7 @@ DESCRIPTION The **listhtlcs** RPC command gets all HTLCs (which, generally, we remember for as long as a channel is open, even if they've completed -long ago). If given a short channel id (e.g. 1x2x3) or full 64-byte -hex channel id, it will only list htlcs for that channel (which -must be known). +long ago). RETURN VALUE ------------ diff --git a/doc/lightning-listinvoicerequests.7.md b/doc/lightning-listinvoicerequests.7.md index 9b8ed2e83660..7ce408d4c0eb 100644 --- a/doc/lightning-listinvoicerequests.7.md +++ b/doc/lightning-listinvoicerequests.7.md @@ -12,11 +12,6 @@ DESCRIPTION The **listinvoicerequests** RPC command gets the status of a specific `invoice_request`, if it exists, or the status of all `invoice_requests` if given no argument. -A specific invoice can be queried by providing the `invreq_id`, which -is presented by lightning-invoicerequest(7), or can be calculated from -a bolt12 invoice. If `active_only` is `true` (default is `false`) then -only active invoice\_requests are returned. - RETURN VALUE ------------ diff --git a/doc/lightning-listinvoices.7.md b/doc/lightning-listinvoices.7.md index 6358b3567934..b09ef700fb60 100644 --- a/doc/lightning-listinvoices.7.md +++ b/doc/lightning-listinvoices.7.md @@ -12,15 +12,7 @@ DESCRIPTION The **listinvoices** RPC command gets the status of a specific invoice, if it exists, or the status of all invoices if given no argument. -A specific invoice can be queried by providing either the `label` -provided when creating the invoice, the `invstring` string representing -the invoice, the `payment_hash` of the invoice, or the local `offer_id` -this invoice was issued for. Only one of the query parameters can be used at once. - -`index` controls ordering, by `created` (default) or `updated`. If -`index` is specified, `start` may be specified to start from that -value, which is generally returned from lightning-wait(7), and `limit` -can be used to specify the maximum number of entries to return. +Only one of the query parameters can be used from *label*, *invstring*, *payment_hash*, or *offer_id* RETURN VALUE ------------ diff --git a/doc/lightning-listpays.7.md b/doc/lightning-listpays.7.md index 1ff9fefe6e13..1d40d28cee59 100644 --- a/doc/lightning-listpays.7.md +++ b/doc/lightning-listpays.7.md @@ -11,7 +11,6 @@ DESCRIPTION The **listpay** RPC command gets the status of all *pay* commands, or a single one if either *bolt11* or *payment\_hash* was specified. -It is possible filter the payments also by *status*. RETURN VALUE ------------ diff --git a/doc/lightning-listpeerchannels.7.md b/doc/lightning-listpeerchannels.7.md index 872ac09b6ae6..00e0641c5f6a 100644 --- a/doc/lightning-listpeerchannels.7.md +++ b/doc/lightning-listpeerchannels.7.md @@ -15,9 +15,6 @@ If no *id* is supplied, then channel data on all lightning nodes that are connected, or not connected but have open channels with this node, are returned. -Supplying *id* will filter the results to only return channel data that match *id*, -if one exists. - RETURN VALUE ------------ diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md index 44780f9d478a..cfb3ae0d2ade 100644 --- a/doc/lightning-listpeers.7.md +++ b/doc/lightning-listpeers.7.md @@ -20,13 +20,6 @@ If no *id* is supplied, then data on all lightning nodes that are connected, or not connected but have open channels with this node, are returned. -Supplying *id* will filter the results to only return data on a node -with a matching *id*, if one exists. - -Supplying *level* will show log entries related to that peer at the -given log level. Valid log levels are "io", "debug", "info", and -"unusual". - If a channel is open with a node and the connection has been lost, then the node will still appear in the output of the command and the value of the *connected* attribute of the node will be "false". diff --git a/doc/lightning-listsendpays.7.md b/doc/lightning-listsendpays.7.md index 9f2f5ebcb9b3..a6a0e47d5d79 100644 --- a/doc/lightning-listsendpays.7.md +++ b/doc/lightning-listsendpays.7.md @@ -12,17 +12,11 @@ DESCRIPTION The **listsendpays** RPC command gets the status of all *sendpay* commands (which is also used by the *pay* command), or with *bolt11* or *payment\_hash* limits results to that specific payment. You cannot -specify both. It is possible filter the payments also by *status*. +specify both. It is possible to filter the payments also by *status*. Note that there may be more than one concurrent *sendpay* command per *pay*, so this command should be used with caution. -If neither *bolt11* or *payment\_hash* is specified, -`index` controls ordering, by `created` (default) or `updated`. If -`index` is specified, `start` may be specified to start from that -value, which is generally returned from lightning-wait(7), and `limit` -can be used to specify the maximum number of entries to return. - RETURN VALUE ------------ @@ -60,8 +54,7 @@ If **status** is "failed": AUTHOR ------ -Christian Decker <> is mainly -responsible. +Christian Decker <> is mainly responsible. SEE ALSO -------- diff --git a/doc/lightning-makesecret.7.md b/doc/lightning-makesecret.7.md index 69ea50b0d002..550a3e988451 100644 --- a/doc/lightning-makesecret.7.md +++ b/doc/lightning-makesecret.7.md @@ -11,9 +11,6 @@ DESCRIPTION The **makesecret** RPC command derives a secret key from the HSM\_secret. -One of *hex* or *string* must be specified: *hex* can be any hex data, -*string* is a UTF-8 string interpreted literally. - RETURN VALUE ------------ @@ -24,6 +21,8 @@ On success, an object is returned, containing: [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ The following error codes may occur: diff --git a/doc/lightning-newaddr.7.md b/doc/lightning-newaddr.7.md index 474eba89afcc..2ea948aaef79 100644 --- a/doc/lightning-newaddr.7.md +++ b/doc/lightning-newaddr.7.md @@ -14,15 +14,7 @@ subsequently be used to fund channels managed by the Core Lightning node. The funding transaction needs to be confirmed before funds can be used. -*addresstype* specifies the type of address wanted; currently *bech32* -(e.g. `tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg` on bitcoin testnet -or `bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej` on -bitcoin mainnet), or *p2tr* taproot addresses. The special value *all* -generates all known address types for the same underlying key. - -If no *addresstype* is specified the address generated is a *bech32* address. - -To send an on-chain payment _from_ the Core Lightning node wallet, use `withdraw`. +To send an on-chain payment from the Core Lightning node wallet, use `withdraw`. RETURN VALUE ------------ diff --git a/doc/lightning-notifications.7.md b/doc/lightning-notifications.7.md index 16b5f4d13c94..f7456b3edeac 100644 --- a/doc/lightning-notifications.7.md +++ b/doc/lightning-notifications.7.md @@ -10,11 +10,10 @@ DESCRIPTION ----------- The **notifications** the RPC command enabled notifications for this JSON-RPC -connection. By default (and for backwards-compatibility) notifications are -disabled. +connection. By default (and for backwards-compatibility) notifications are disabled. -Various commands, especially complex and slow ones, offer -notifications which indicate their progress. +Various commands, especially complex and slow ones, offer notifications which indicate +their progress. EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-pay.7.md b/doc/lightning-pay.7.md index 8cc8fe434d9d..9d76820aa962 100644 --- a/doc/lightning-pay.7.md +++ b/doc/lightning-pay.7.md @@ -114,6 +114,9 @@ The following warnings may also be returned: You can monitor the progress and retries of a payment using the lightning-paystatus(7) command. +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-renepay.7.md b/doc/lightning-renepay.7.md index 6f9832af911c..3c5f3594512a 100644 --- a/doc/lightning-renepay.7.md +++ b/doc/lightning-renepay.7.md @@ -91,6 +91,9 @@ On success, an object is returned, containing: You can monitor the progress and retries of a payment using the lightning-renepaystatus(7) command. +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md index 033e6f45b8fe..e125c79bbbd9 100644 --- a/doc/lightning-sendinvoice.7.md +++ b/doc/lightning-sendinvoice.7.md @@ -43,6 +43,9 @@ If **status** is "paid": [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-txdiscard.7.md b/doc/lightning-txdiscard.7.md index a16c2be578a9..d24603c05ea6 100644 --- a/doc/lightning-txdiscard.7.md +++ b/doc/lightning-txdiscard.7.md @@ -27,6 +27,9 @@ If there is no matching *txid*, an error is reported. Note that this may happen due to incorrect usage, such as **txdiscard** or **txsend** already being called for *txid*. +ERRORS +------ + The following error codes may occur: - -1: An unknown *txid*. diff --git a/doc/schemas/decodepay.request.json b/doc/schemas/decodepay.request.json index d4e5ae4d31d7..d89d88afe009 100644 --- a/doc/schemas/decodepay.request.json +++ b/doc/schemas/decodepay.request.json @@ -8,10 +8,12 @@ ], "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice to decode" }, "description": { - "type": "string" + "type": "string", + "description": "description of the invoice to decode" } } } diff --git a/doc/schemas/invoice.request.json b/doc/schemas/invoice.request.json index 04430b38a4de..237a123a9f7b 100644 --- a/doc/schemas/invoice.request.json +++ b/doc/schemas/invoice.request.json @@ -10,63 +10,58 @@ "properties": { "amount_msat": { "type": "msat_or_any", - "description": "" + "description": "the string `any`, which creates an invoice that can be paid with any amount. Otherwise it is 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*" }, "label": { - "oneOf": [ - { - "type": "string", - "description": "" - }, - { - "type": "integer", - "description": "" - } - ] + "type": "string", + "description": "a unique string or number (which is treated as a string, so `01` is different from `1`); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice" }, "description": { "type": "string", - "description": "" + "description": "a short description of purpose of payment, e.g. *1 cup of coffee*. This value is encoded into the BOLT11 invoice and is viewable by any node you send this invoice to (unless *deschashonly* is true as described below). It must be UTF-8, and cannot use *\\u* JSON escape codes" }, "expiry": { "type": "u64", - "description": "" + "description": "the time the invoice is valid for, in seconds. If no value is provided the default of 604800 (1 week) is used" }, "fallbacks": { "type": "array", - "description": "", + "description": "one or more fallback addresses to include in the invoice (in order from most-preferred to least): note that these arrays are not currently tracked to fulfill the invoice", "items": { "type": "string" } }, "preimage": { "type": "hex", - "description": "" + "description": "a 64-digit hex string to be used as payment preimage for the created invoice. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system. **IMPORTANT**: if you specify the *preimage*, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret. This parameter is an advanced feature intended for use with cutting-edge cryptographic protocols and should not be used unless explicitly needed" }, "exposeprivatechannels": { + "description": "if specified, it overrides the default route hint logic, which will use unpublished channels only if there are no published channels", "oneOf": [ { "type": "boolean", - "description": "" + "description": "if *True* unpublished channels are always considered as a route hint candidate; if *False*, never" }, { "type": "array", + "description": "array of short channel ids (or a remote alias), only those specific channels will be considered candidates, even if they are public or dead-ends", "items": { "type": "short_channel_id" } }, { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "if it is a short channel id (e.g. *1x1x3*), only this specific channel will be considered candidate, even if it is public or dead-end" } ] }, "cltv": { "type": "u32", - "description": "" + "description": "if specified, sets the *min_final_cltv_expiry* for the invoice. Otherwise, it's set to the parameter **cltv-final**" }, "deschashonly": { "type": "boolean", - "description": "" + "description": "if True, then the bolt11 returned contains a hash of the *description*, rather than the *description* itself: this allows much longer descriptions, but they must be communicated via some other mechanism. Defaults to False" } } } diff --git a/doc/schemas/invoicerequest.request.json b/doc/schemas/invoicerequest.request.json index e94b190ba40a..7cb8ebfccb8d 100644 --- a/doc/schemas/invoicerequest.request.json +++ b/doc/schemas/invoicerequest.request.json @@ -10,27 +10,27 @@ "properties": { "amount": { "type": "msat", - "description": "" + "description": "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*" }, "description": { "type": "string", - "description": "" + "description": "a short description of purpose of the payment, e.g. *ATM withdrawl*. This value is encoded into the resulting `invoice_request` and is viewable by anyone you expose it to. It must be UTF-8, and cannot use *\\u* JSON escape codes" }, "issuer": { "type": "string", - "description": "" + "description": "who is issuing it (i.e. you) if appropriate" }, "label": { "type": "string", - "description": "" + "description": "an internal-use name for the offer, which can be any UTF-8 string" }, "absolute_expiry": { "type": "u64", - "description": "" + "description": "the time the offer is valid until, in seconds since the first day of 1970 UTC. If not set, the `invoice_request` remains valid (though it can be deactivated by the issuer of course). This is encoded in the `invoice_request`" }, "single_use": { "type": "boolean", - "description": "" + "description": "indicates that the `invoice_request` is only valid once; we may attempt multiple payments, but as soon as one is successful no more invoices are accepted (i.e. only one person can take the money). Defaults to True" } } } diff --git a/doc/schemas/keysend.request.json b/doc/schemas/keysend.request.json index 64e74e73c7b7..66f37cb4b42c 100644 --- a/doc/schemas/keysend.request.json +++ b/doc/schemas/keysend.request.json @@ -8,25 +8,32 @@ ], "properties": { "destination": { - "type": "pubkey" + "type": "pubkey", + "description": "the 33 byte, hex-encoded, node ID of the node that the payment should go to" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "a whole number, or a whole number with suffix `msat` or `sat`, or a three decimal point number with suffix `sat`, or an 1 to 11 decimal point number suffixed by `btc`" }, "label": { - "type": "string" + "type": "string", + "description": "used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)" }, "maxfeepercent": { - "type": "number" + "type": "number", + "description": "limits the money paid in fees as percentage of the total amount that is to be transferred, and defaults to *0.5*" }, "retry_for": { - "type": "u32" + "type": "u32", + "description": "until *retry_for* seconds passes, the command will keep finding routes and retrying the payment. However, a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case. Defaults to 60 seconds" }, "maxdelay": { - "type": "u32" + "type": "u32", + "description": "number of blocks the payment may be delayed" }, "exemptfee": { - "type": "msat" + "type": "msat", + "description": "used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Setting `exemptfee` allows the `maxfeepercent` check to be skipped on fees that are smaller than *exemptfee*. Defaults to 5000 millisatoshi" }, "routehints": { "type": "array", @@ -65,7 +72,8 @@ "extratlvs": { "type": "object", "additionalProperties": true, - "required": [] + "required": [], + "description": "dictionary of additional fields to insert into the final tlv. The format is 'fieldnumber': 'hexstring'" } } } diff --git a/doc/schemas/listchannels.request.json b/doc/schemas/listchannels.request.json index 80c7344900ee..2779b0298de4 100644 --- a/doc/schemas/listchannels.request.json +++ b/doc/schemas/listchannels.request.json @@ -6,15 +6,15 @@ "properties": { "short_channel_id": { "type": "short_channel_id", - "description": "If short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null." + "description": "if short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null" }, "source": { "type": "pubkey", - "description": "If source is a node id, then only channels leading from that node id are returned." + "description": "if source is a node id, then only channels leading from that node id are returned" }, "destination": { "type": "pubkey", - "description": "If destination is a node id, then only channels leading to that node id are returned." + "description": "if destination is a node id, then only channels leading to that node id are returned" } } } diff --git a/doc/schemas/listclosedchannels.request.json b/doc/schemas/listclosedchannels.request.json index 2726913be3d1..eb11e66565ad 100644 --- a/doc/schemas/listclosedchannels.request.json +++ b/doc/schemas/listclosedchannels.request.json @@ -7,7 +7,7 @@ "properties": { "id": { "type": "pubkey", - "description": "If supplied, limits the channels to just the peer with the given ID, if it exists." + "description": "if no *id* is supplied, then channel data on all historical channels are given. Supplying *id* will filter the results to only match channels to that peer. Note that prior to v23.05, old peers were forgotten" } } } diff --git a/doc/schemas/listdatastore.request.json b/doc/schemas/listdatastore.request.json index fc817532724f..906fa7f6af1b 100644 --- a/doc/schemas/listdatastore.request.json +++ b/doc/schemas/listdatastore.request.json @@ -5,17 +5,18 @@ "required": [], "properties": { "key": { + "description": "a *key* with children won't have a *hex* or *generation* entry. All immediate children of the *key* (or root children) are returned", "oneOf": [ { "type": "array", - "description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically.", + "description": "an array of values, to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically", "items": { "type": "string" } }, { "type": "string", - "description": "" + "description": "a single value is treated as a one-element array, to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically." } ] } diff --git a/doc/schemas/listforwards.request.json b/doc/schemas/listforwards.request.json index b5e9e6fa89d0..22c91902d2dc 100644 --- a/doc/schemas/listforwards.request.json +++ b/doc/schemas/listforwards.request.json @@ -5,6 +5,7 @@ "properties": { "status": { "type": "string", + "description": "if specified, then only the forwards with the given status are returned", "enum": [ "offered", "settled", @@ -13,10 +14,12 @@ ] }, "in_channel": { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "only the matching forwards on the given inbound channel are returned" }, "out_channel": { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "only the matching forwards on the given outbount channel are returned" }, "index": { "type": "string", @@ -25,17 +28,17 @@ "created", "updated" ], - "description": "" + "description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`" }, "start": { "type": "u64", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/listfunds.request.json b/doc/schemas/listfunds.request.json index 00faf6c658e8..cef1bb3128ee 100644 --- a/doc/schemas/listfunds.request.json +++ b/doc/schemas/listfunds.request.json @@ -6,7 +6,7 @@ "properties": { "spent": { "type": "boolean", - "description": "Should outputs that are already spent be included in the result?" + "description": "if True, then the *outputs* will include spent outputs in addition to the unspent ones. Default is False" } } } diff --git a/doc/schemas/listhtlcs.request.json b/doc/schemas/listhtlcs.request.json index df03123299a8..764e3dbc064e 100644 --- a/doc/schemas/listhtlcs.request.json +++ b/doc/schemas/listhtlcs.request.json @@ -5,7 +5,7 @@ "properties": { "id": { "type": "string", - "description": "channel id or short_channel_id" + "description": "a short channel id (e.g. 1x2x3) or full 64-byte hex channel id, it will only list htlcs for that channel (which must be known)" } } } diff --git a/doc/schemas/listinvoicerequests.request.json b/doc/schemas/listinvoicerequests.request.json index 01104b40a18f..2b22dace5708 100644 --- a/doc/schemas/listinvoicerequests.request.json +++ b/doc/schemas/listinvoicerequests.request.json @@ -7,11 +7,11 @@ "properties": { "invreq_id": { "type": "string", - "description": "" + "description": "a specific invoice can be queried by providing the `invreq_id`, which is presented by lightning-invoicerequest(7), or can be calculated from a bolt12 invoice" }, "active_only": { "type": "boolean", - "description": "" + "description": "if it is *True* then only active invoice requests are returned. Default is *False*" } } } diff --git a/doc/schemas/listinvoices.request.json b/doc/schemas/listinvoices.request.json index f40710fa7490..6f91f173f188 100644 --- a/doc/schemas/listinvoices.request.json +++ b/doc/schemas/listinvoices.request.json @@ -5,28 +5,29 @@ "required": [], "properties": { "label": { + "description": "a label used a the creation of the invoice to get a specific invoice", "oneOf": [ { "type": "string", - "description": "" + "description": "a text label to search for" }, { "type": "integer", - "description": "" + "description": "a numeric label to search for" } ] }, "invstring": { "type": "string", - "description": "" + "description": "a invoice string representing the invoice to query a specific invoice" }, "payment_hash": { "type": "hex", - "description": "" + "description": "a payment_hash of the invoice to get the details of a specific invoice" }, "offer_id": { "type": "string", - "description": "" + "description": "a local `offer_id` the invoice was issued for a specific invoice details" }, "index": { "type": "string", @@ -35,17 +36,17 @@ "created", "updated" ], - "description": "" + "description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`" }, "start": { "type": "u64", - "added": "v23.08", - "description": "" + "added": "v23.11", + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", - "added": "v23.08", - "description": "" + "added": "v23.11", + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/listpays.request.json b/doc/schemas/listpays.request.json index f313c861388b..50cdac247831 100644 --- a/doc/schemas/listpays.request.json +++ b/doc/schemas/listpays.request.json @@ -5,13 +5,16 @@ "additionalProperties": false, "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 string to get the payment details" }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "payment hash to get the payment details" }, "status": { "type": "string", + "description": "to filter the payment by status", "enum": [ "pending", "complete", diff --git a/doc/schemas/listpeers.request.json b/doc/schemas/listpeers.request.json index f2b02304acd3..01f5bbe453cb 100644 --- a/doc/schemas/listpeers.request.json +++ b/doc/schemas/listpeers.request.json @@ -6,11 +6,17 @@ "properties": { "id": { "type": "pubkey", - "description": "If supplied, limits the result to just the peer with the given ID, if it exists." + "description": "if supplied, limits the result to just the peer with the given ID, if it exists" }, "level": { "type": "string", - "description": "Supplying level will show log entries related to that peer at the given log level. Valid log levels are “io”, “debug”, “info”, and “unusual”." + "description": "supplying level will show log entries related to that peer at the given log level", + "enum": [ + "io", + "debug", + "info", + "unusual" + ] } } } diff --git a/doc/schemas/listsendpays.request.json b/doc/schemas/listsendpays.request.json index a498bbc697ad..701f6a76efd9 100644 --- a/doc/schemas/listsendpays.request.json +++ b/doc/schemas/listsendpays.request.json @@ -5,10 +5,12 @@ "additionalProperties": false, "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice" }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "the hash of the payment_preimage" }, "status": { "type": "string", @@ -16,7 +18,8 @@ "pending", "complete", "failed" - ] + ], + "description": "Whether the invoice has been paid, pending, or failed" }, "index": { "type": "string", @@ -25,17 +28,17 @@ "created", "updated" ], - "description": "" + "description": "if neither bolt11 or payment_hash is specified, `index` controls ordering, by `created` (default) or `updated`" }, "start": { "type": "u64", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/makesecret.request.json b/doc/schemas/makesecret.request.json index 5059babd01d5..54d6fef91d11 100644 --- a/doc/schemas/makesecret.request.json +++ b/doc/schemas/makesecret.request.json @@ -6,11 +6,11 @@ "properties": { "hex": { "type": "hex", - "description": "This will be used for deriving the secret" + "description": "One of `hex` or `string` must be specified: `hex` can be any hex data" }, "string": { "type": "string", - "description": "This will be used for deriving the secret" + "description": "One of `hex` or `string` must be specified: `string` is a UTF-8 string interpreted literally" } } } diff --git a/doc/schemas/newaddr.request.json b/doc/schemas/newaddr.request.json index b0eadf2c7d98..b5089932f144 100644 --- a/doc/schemas/newaddr.request.json +++ b/doc/schemas/newaddr.request.json @@ -6,6 +6,7 @@ "properties": { "addresstype": { "type": "string", + "description": "it specifies the type of address wanted; currently *bech32* (e.g. `tb1qu9j4lg5f9rgjyfhvfd905vw46eg39czmktxqgg` on bitcoin testnet or `bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej` on bitcoin mainnet), or *p2tr* taproot addresses. The special value *all* generates all known address types for the same underlying key. Defaults to *bech32* address", "enum": [ "bech32", "p2tr", diff --git a/doc/schemas/showrunes.request.json b/doc/schemas/showrunes.request.json index 5bc5b8fc8322..da2831ff7379 100644 --- a/doc/schemas/showrunes.request.json +++ b/doc/schemas/showrunes.request.json @@ -7,7 +7,7 @@ "properties": { "rune": { "type": "string", - "description": "optional rune to list" + "description": "if specified, only details of that rune will be returned" } } }