Errors

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:
 

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.

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:
 

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
 ------------
 

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
 ------------
 

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.

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

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
 ------------
 

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.

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
 ------------
 

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
 ------------
 

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
 ------------

doc/lightning-makesecret.7.md

@@ -25,6 +25,9 @@ On success, an object is returned, containing:
 [comment]: # (GENERATE-FROM-SCHEMA-END)
 
 
+ERRORS
+------
+
 The following error codes may occur:
 
 - -1: Catchall nonspecific error.

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.

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.

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.

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*.

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"
     }
   }
 }