diff --git a/doc/Makefile b/doc/Makefile index 3a26050d30b5..6331b909aee5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -137,7 +137,7 @@ endif doc-all: $(MANPAGES) doc/index.rst -SCHEMAS := $(wildcard doc/schemas/*.new.json) +SCHEMAS := $(wildcard doc/schemas/lightning-*.json) check-fmt-schemas: $(SCHEMAS:%=check-fmt-schema/%) fmt-schemas: $(SCHEMAS:%=fmt-schema/%) @@ -156,8 +156,8 @@ MARKDOWN_WITH_SCHEMA := $(shell grep -l GENERATE-FROM-SCHEMA $(MANPAGES:=.md)) LBRACKET=( RBRACKET=) -$(MARKDOWN_WITH_SCHEMA): doc/lightning-%.7.md: doc/schemas/%.new.json tools/fromschema.py - @if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "fromschema $@", tools/fromschema.py --markdownfile=$@ doc/schemas/$*.new.json > $@.tmp && grep -v SHA256STAMP: $@.tmp > $@ && rm -f $@.tmp && $(call SHA256STAMP,[comment]: # $(LBRACKET),$(RBRACKET))); else touch $@; fi +$(MARKDOWN_WITH_SCHEMA): doc/lightning-%.7.md: doc/schemas/lightning-%.json tools/fromschema.py + @if $(call SHA256STAMP_CHANGED); then $(call VERBOSE, "fromschema $@", tools/fromschema.py --markdownfile=$@ doc/schemas/lightning-$*.json > $@.tmp && grep -v SHA256STAMP: $@.tmp > $@ && rm -f $@.tmp && $(call SHA256STAMP,[comment]: # $(LBRACKET),$(RBRACKET))); else touch $@; fi # If we need to build lowdown, make tools/md2man.sh depend on it. # That way it's not used in SHA256STAMP (which only uses direct 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-fundpsbt.7.md b/doc/lightning-fundpsbt.7.md index 881a6e9f7df2..99f962b107cb 100644 --- a/doc/lightning-fundpsbt.7.md +++ b/doc/lightning-fundpsbt.7.md @@ -12,38 +12,6 @@ DESCRIPTION `fundpsbt` is a low-level RPC command which creates a PSBT using unreserved inputs in the wallet, optionally reserving them as well. -*satoshi* is the minimum satoshi value of the output(s) needed (or the -string "all" meaning use all unreserved inputs). If a value, it can -be a whole number, a whole number ending in *sat*, a whole number -ending in *000msat*, or a number with 1 to 8 decimal places ending in -*btc*. - -*feerate* is an optional feerate: see NOTES in lightning-feerates(7) -for possible values. The default is *normal*. - -*startweight* is the weight of the transaction before *fundpsbt* has -added any inputs. - -*minconf* specifies the minimum number of confirmations that used -outputs should have. Default is 1. - -If *reserve* if not zero, then *reserveinputs* is called (successfully, with -*exclusive* true) on the returned PSBT for this number of blocks (default -72 blocks if unspecified). - -*locktime* is an optional locktime: if not set, it is set to a recent -block height. - -*min\_witness\_weight* is an optional minimum weight to use for a UTXO's -witness. If the actual witness weight is greater than the provided minimum, -the actual witness weight will be used. - -*excess\_as\_change* is an optional boolean to flag to add a change output -for the excess sats. - -*nonwrapped* is an optional boolean to signal to filter out any p2sh-wrapped -inputs from funding this PSBT. - EXAMPLE USAGE ------------- 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-multifundchannel.7.md b/doc/lightning-multifundchannel.7.md index 140127064b0e..0b63168065ad 100644 --- a/doc/lightning-multifundchannel.7.md +++ b/doc/lightning-multifundchannel.7.md @@ -13,17 +13,10 @@ The **multifundchannel** RPC command opens multiple payment channels with nodes by committing a single funding transaction to the blockchain that is shared by all channels. -If not already connected, **multifundchannel** will automatically attempt -to connect; you may provide a *@host:port* hint appended to the node ID -so that Core Lightning can learn how to connect to the node; -see lightning-connect(7). - Once the transaction is confirmed, normal channel operations may begin. Readiness is indicated by **listpeers** reporting a *state* of `CHANNELD_NORMAL` for the channel. -There must be at least one entry in *destinations*; it cannot be an empty array. - RETURN VALUE ------------ diff --git a/doc/lightning-multiwithdraw.7.md b/doc/lightning-multiwithdraw.7.md index 27859a4e5c41..a792c7203cc3 100644 --- a/doc/lightning-multiwithdraw.7.md +++ b/doc/lightning-multiwithdraw.7.md @@ -4,7 +4,7 @@ lightning-multiwithdraw -- Command for withdrawing to multiple addresses SYNOPSIS -------- -**multiwithdraw** *outputs* [*feerate*] [*minconf*] [*utxos*] +**multiwithdraw** *outputs* [*feerate*] [*minconf*] [*utxos*] DESCRIPTION ----------- 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..9068ec9f0e39 100644 --- a/doc/lightning-pay.7.md +++ b/doc/lightning-pay.7.md @@ -12,57 +12,12 @@ DESCRIPTION ----------- The **pay** RPC command attempts to find a route to the given -destination, and send the funds it asks for. If the *bolt11* does not -contain an amount, *amount\_msat* is required, otherwise if it is specified -it must be *null*. *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*. - -(Note: if **experimental-offers** is enabled, *bolt11* can actually be -a bolt12 invoice, such as one received from lightningd-fetchinvoice(7)). - -The *label* field is used to attach a label to payments, and is returned -in lightning-listpays(7) and lightning-listsendpays(7). The *riskfactor* -is described in detail in lightning-getroute(7), and defaults to 10. The -*maxfeepercent* limits the money paid in fees, and defaults to 0.5. The -`maxfeepercent` is a percentage of the amount that is to be paid. 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). - -`localinvreqid` is used by offers to link a payment attempt to a local -`invoice_request` offer created by lightningd-invoicerequest(7). This ensures -that we only make a single payment for an offer, and that the offer is -marked `used` once paid. - -*maxfee* overrides both *maxfeepercent* and *exemptfee* defaults (and -if you specify *maxfee* you cannot specify either of those), and -creates an absolute limit on what fee we will pay. This allows you to -implement your own heuristics rather than the primitive ones used -here. - -*description* is only required for bolt11 invoices which do not -contain a description themselves, but contain a description hash: -in this case *description* is required. -*description* is then checked against the hash inside the invoice -before it will be paid. +destination, and send the funds it asks for. The response will occur when the payment fails or succeeds. Once a payment has succeeded, calls to **pay** with the same *bolt11* will succeed immediately. -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. - -*exclude* is a JSON array of short-channel-id/direction (e.g. [ -"564334x877x1/0", "564195x1292x0/1" ]) or node-id which should be excluded -from consideration for routing. The default is not to exclude any channels -or nodes. - When using *lightning-cli*, you may skip optional parameters by using *null*. Alternatively, use **-k** option to provide parameters by name. @@ -114,6 +69,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-ping.7.md b/doc/lightning-ping.7.md index e8a4e2efa8ef..f148eb5d34e7 100644 --- a/doc/lightning-ping.7.md +++ b/doc/lightning-ping.7.md @@ -12,13 +12,6 @@ DESCRIPTION The **ping** command checks if the node with *id* is ready to talk. It currently only works for peers we have a channel with. -It accepts the following parameters: - -- *id*: A string that represents the node id; -- *len*: A integer that represents the length of the ping (default 128); -- *pongbytes*: An integer that represents the length of the reply (default 128). - A value of 65532 to 65535 means "don't reply". - EXAMPLE JSON REQUEST ------------ diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md index 84d1561ea36e..b1bfcd1b1afd 100644 --- a/doc/lightning-plugin.7.md +++ b/doc/lightning-plugin.7.md @@ -4,13 +4,12 @@ lightning-plugin -- Manage plugins with RPC SYNOPSIS -------- -**plugin** *subcommand* [plugin|directory] [*options*] ... - +**plugin** *subcommand* [*plugin*] [*directory*] [*options*] DESCRIPTION ----------- -The **plugin** RPC command command can be used to control dynamic plugins, +The **plugin** RPC command can be used to control dynamic plugins, i.e. plugins that declared themself "dynamic" (in getmanifest). *subcommand* **start** takes a *path* to an executable as argument and starts it as plugin. @@ -41,26 +40,29 @@ that are not already running. Checksum and timeout behavior as in **start** appl *subcommand* **list** lists all running plugins (incl. non-dynamic) +- **subcommand** (string): determines what action is taken (one of "start", "stop", "rescan", "startdir", "list") +- **plugin** (string, optional): *path* or *name* of a plugin executable to start or stop +- **directory** (string, optional): *path* of a directory containing plugins +- **options** (array of strings, optional) + - *keyword=value* options passed to plugin, can be repeated + RETURN VALUE ------------ -[comment]: # (GENERATE-FROM-SCHEMA-START) On success, an object is returned, containing: - **command** (string): the subcommand this is responding to (one of "start", "stop", "rescan", "startdir", "list") If **command** is "start", "startdir", "rescan" or "list": - - - **plugins** (array of objects): + - **plugins** (array of objects) - **name** (string): full pathname of the plugin - **active** (boolean): status; plugin completed init and is operational, plugins are configured asynchronously. - **dynamic** (boolean): plugin can be stopped or started without restarting lightningd -If **command** is "stop": +If **command** is "stop": - **result** (string): A message saying it successfully stopped -[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -83,5 +85,5 @@ RESOURCES Main web site: -[writing plugins]: PLUGINS.md -[comment]: # ( SHA256STAMP:66b5b924fa927c85e065fd01a7b94a0a892b3e027830a8c1f2c584586ee2a7e7) + +[comment]: # ( SHA256STAMP:dc82bdeb3609676de7b38918b57a7df61bd15a804d5de5687812a07574f2d05e) diff --git a/doc/lightning-preapprovekeysend.7.md b/doc/lightning-preapprovekeysend.7.md index 05e928887d0b..8c2afde8bdca 100644 --- a/doc/lightning-preapprovekeysend.7.md +++ b/doc/lightning-preapprovekeysend.7.md @@ -13,15 +13,6 @@ The **preapprovekeysend** RPC command submits the *destination*, *payment\_hash* and *amount\_msat* parameters to the HSM to check that they are approved as a keysend payment. -*destination* is a 33 byte, hex-encoded, node ID of the node that the payment should go to. - -*payment\_hash* is the unique identifier of a payment. - -*amount\_msat* is the amount to send 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`. - Generally the **preapprovekeysend** request does not need to be made explicitly, it is automatically generated as part of a **keysend** request. diff --git a/doc/lightning-renepay.7.md b/doc/lightning-renepay.7.md index 6f9832af911c..3e5f6975faeb 100644 --- a/doc/lightning-renepay.7.md +++ b/doc/lightning-renepay.7.md @@ -7,7 +7,6 @@ SYNOPSIS **renepay** *invstring* [*amount\_msat*] [*maxfee*] [*maxdelay*] [*retry\_for*] [*description*] [*label*] - DESCRIPTION ----------- @@ -15,17 +14,10 @@ DESCRIPTION method for Multi-Path-Payments. This implementation has not been thoroughly tested and it should be used with caution. -The **renepay** RPC command attempts to pay the invoice specified -as *invstring*. Currently, **renepay** supports bolt11 invoices only. - The response will occur when the payment fails or succeeds. Once a payment has succeeded, calls to **renepay** with the same *invstring* will not lead to a new payment attempt, but instead it will succeed immediately. -If the *invstring* does not contain an amount, -*amount\_msat* is required, otherwise if it is specified -it must be *null*. - When using *lightning-cli*, you may skip optional parameters by using *null*. Alternatively, use **-k** option to provide parameters by name. @@ -91,6 +83,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-renepaystatus.7.md b/doc/lightning-renepaystatus.7.md index 46423096c84b..d6f300c9af9b 100644 --- a/doc/lightning-renepaystatus.7.md +++ b/doc/lightning-renepaystatus.7.md @@ -13,9 +13,6 @@ DESCRIPTION The **renepaystatus** RPC command queries the payment plugin **renepay** for the status of previous payment attempts. -If *invstring* is specified, the command will return a list of payment attempts -whose invoice matches *invstring*, otherwise all payments with be listed. - This command always succeeds. RETURN VALUE diff --git a/doc/lightning-reserveinputs.7.md b/doc/lightning-reserveinputs.7.md index 959ceac63c76..3370cceb0404 100644 --- a/doc/lightning-reserveinputs.7.md +++ b/doc/lightning-reserveinputs.7.md @@ -31,15 +31,6 @@ On success, an object containing **reservations** is returned. It is an array o [comment]: # (GENERATE-FROM-SCHEMA-END) -On success, a *reservations* array is returned, with an entry for each input -which was reserved: - -- *txid* is the input transaction id. -- *vout* is the input index. -- *was\_reserved* indicates whether the input was already reserved. -- *reserved* indicates that the input is now reserved (i.e. true). -- *reserved\_to\_block* indicates what blockheight the reservation will expire. - ERRORS ------ diff --git a/doc/lightning-sendcustommsg.7.md b/doc/lightning-sendcustommsg.7.md index 6ca1fe93831b..3e27ba381039 100644 --- a/doc/lightning-sendcustommsg.7.md +++ b/doc/lightning-sendcustommsg.7.md @@ -14,24 +14,9 @@ into the communication with the peer with the given `node_id`. This is intended as a low-level interface to implement custom protocol extensions on top, not for direct use by end-users. -The message must be a hex encoded well-formed message, including the 2-byte -type prefix, but excluding the length prefix which will be added by the RPC -method. The message types may not be one of the internally handled -types, since that may cause issues with the internal state tracking of -Core Lightning. We do (as of *v23.11*) allow sending of even types, but note that peers (as per the spec) will disconnect on receiving unknown even types. - -The node specified by `node_id` must be a peer, i.e., it must have a direct -connection with the node receiving the RPC call, and the connection must be -established. For a method to send arbitrary messages over multiple hops, -including hops that do not understand the custom message, see the -`createonion` and `sendonion` RPC methods. Messages can only be injected if -the connection is handled by `openingd` or `channeld`. Messages cannot be -injected when the peer is handled by `onchaind` or `closingd` since these do -not have a connection, or are synchronous daemons that do not handle -spontaneous messages. - -On the reveiving end a plugin may implement the `custommsg` plugin hook and -get notified about incoming messages, and allow additional unknown even types in their getmanifest response. +On the receiving end a plugin may implement the `custommsg` plugin hook and +get notified about incoming messages, and allow additional unknown even types +in their getmanifest response. RETURN VALUE ------------ 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-sendonion.7.md b/doc/lightning-sendonion.7.md index d4720567a872..a85368605142 100644 --- a/doc/lightning-sendonion.7.md +++ b/doc/lightning-sendonion.7.md @@ -18,51 +18,9 @@ of the payment for the final hop. However, it is possible to add arbitrary information for hops in the custom onion, allowing for custom extensions that are not directly supported by Core Lightning. -The onion is specific to the route that is being used and the *payment\_hash* -used to construct, and therefore cannot be reused for other payments or to -attempt a separate route. The custom onion can generally be created using the -`devtools/onion` CLI tool, or the **createonion** RPC command. - -The *onion* parameter is a hex-encoded 1366 bytes long blob that was returned -by either of the tools that can generate onions. It contains the payloads -destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for -further details. - -The *first\_hop* parameter instructs Core Lightning which peer to send the onion -to. It is a JSON dictionary that corresponds to the first element of the route -array returned by *getroute*. The following is a minimal example telling -Core Lightning to use any available channel to `022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59` -to add an HTLC for 1002 millisatoshis and a delay of 21 blocks on top of the current blockheight: - -```json -{ - "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59", - "amount_msat": "1002msat", - "delay": 21, -} -``` - If the first element of *route* does not have "channel" set, a suitable channel (if any) will be chosen, otherwise that specific -short-channel-id is used. - -The *payment\_hash* parameter specifies the 32 byte hex-encoded hash to use as -a challenge to the HTLC that we are sending. It is specific to the onion and -has to match the one the onion was created with. - -The *label* parameter can be used to provide a human readable reference to -retrieve the payment at a later time. - -The *shared\_secrets* parameter is a JSON list of 32 byte hex-encoded secrets -that were used when creating the onion. Core Lightning can send a payment with a -custom onion without the knowledge of these secrets, however it will not be -able to parse an eventual error message since that is encrypted with the -shared secrets used in the onion. If *shared\_secrets* is provided Core Lightning -will decrypt the error, act accordingly, e.g., add a `channel_update` included -in the error to its network view, and set the details in *listsendpays* -correctly. If it is not provided Core Lightning will store the encrypted onion, -and expose it in *listsendpays* allowing the caller to decrypt it -externally. The following is an example of a 3 hop onion: +short-channel-id is used. The following is an example of a 3 hop onion: ```json [ @@ -72,21 +30,6 @@ externally. The following is an example of a 3 hop onion: ] ``` -If *shared\_secrets* is not provided the Core Lightning node does not know how -long the route is, which channels or nodes are involved, and what an eventual -error could have been. It can therefore be used for oblivious payments. - -The *partid* value, if provided and non-zero, allows for multiple parallel -partial payments with the same *payment\_hash*. - -The *bolt11* parameter, if provided, will be returned in -*waitsendpay* and *listsendpays* results. - -The *destination* parameter, if provided, will be returned in **listpays** result. - -The *amount\_msat* parameter is used to annotate the payment, and is returned by -*waitsendpay* and *listsendpays*. - RETURN VALUE ------------ @@ -117,9 +60,14 @@ If **status** is "pending": [comment]: # (GENERATE-FROM-SCHEMA-END) -If *shared\_secrets* was provided and an error was returned by one of the -intermediate nodes the error details are decrypted and presented -here. Otherwise the error code is 202 for an unparseable onion. +ERRORS +------ + +The following error codes may occur: + +- 202: an parseable onion +- the error details are decrypted and presented here, if *shared\_secrets* was provided and an error was returned by one of the +intermediate nodes AUTHOR ------ diff --git a/doc/lightning-sendpay.7.md b/doc/lightning-sendpay.7.md index 4115e5edd65c..d12e08ab53ad 100644 --- a/doc/lightning-sendpay.7.md +++ b/doc/lightning-sendpay.7.md @@ -26,35 +26,6 @@ payments, or to-self payments). Instead, use the **waitsendpay** RPC command to poll or wait for definite success or definite failure. -The *label* and *bolt11* parameters, if provided, will be returned in -*waitsendpay* and *listsendpays* results. - -The *amount\_msat* amount must be provided if *partid* is non-zero, or the payment is to-self, otherwise -it must be equal to the final -amount to the destination. By default it is 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 *payment\_secret* is the value that the final recipient requires to -accept the payment, as defined by the `payment_data` field in BOLT 4 -and the `s` field in the BOLT 11 invoice format. It is required if -*partid* is non-zero. - -The *partid* value must not be provided for self-payments. If provided and non-zero, allows for multiple parallel -partial payments with the same *payment\_hash*. The *amount\_msat* amount -(which must be provided) for each **sendpay** with matching -*payment\_hash* must be equal, and **sendpay** will fail if there are differing values given. - -The *localinvreqid* value indicates that this payment is being made for a local -invoice\_request: this ensures that we only send a payment for a single-use -invoice\_request once. - -*groupid* allows you to attach a number which appears in **listsendpays** so -payments can be identified as part of a logical group. The *pay* plugin uses -this to identify one attempt at a MPP payment, for example. - -*payment\_metadata* is placed in the final onion hop TLV. - Once a payment has succeeded, calls to **sendpay** with the same *payment\_hash* but a different *amount\_msat* or destination will fail; this prevents accidental multiple payments. Calls to **sendpay** with diff --git a/doc/lightning-sendpsbt.7.md b/doc/lightning-sendpsbt.7.md index bb955a2939d7..8028e9930d01 100644 --- a/doc/lightning-sendpsbt.7.md +++ b/doc/lightning-sendpsbt.7.md @@ -11,9 +11,6 @@ DESCRIPTION The **sendpsbt** is a low-level RPC command which sends a fully-signed PSBT. -- *psbt*: A string that represents psbt value. -- *reserve*: an optional number of blocks to increase reservation of any of our inputs by; default is 72. - EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-setchannel.7.md b/doc/lightning-setchannel.7.md index 7d77cf7cb44f..6ccffca63a74 100644 --- a/doc/lightning-setchannel.7.md +++ b/doc/lightning-setchannel.7.md @@ -19,56 +19,6 @@ These changes (for a public channel) will be broadcast to the rest of the network (though many nodes limit the rate of such changes they will accept: we allow 2 a day, with a few extra occasionally). -*id* is required and should contain a scid (short channel ID), channel -id or peerid (pubkey) of the channel to be modified. If *id* is set to -"all", the updates are applied to all channels in states -CHANNELD\_NORMAL CHANNELD\_AWAITING\_LOCKIN or DUALOPEND\_AWAITING\_LOCKIN. -If *id* is a peerid, all channels with the +peer in those states are -changed. - -*feebase* is an optional value in millisatoshi that is added as base fee to -any routed payment: if omitted, it is unchanged. 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*. - -*feeppm* is an optional value that is added proportionally per-millionths -to any routed payment volume in satoshi. For example, if ppm is 1,000 -and 1,000,000 satoshi is being routed through the channel, an -proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee. - -*htlcmin* is an optional value that limits how small an HTLC we will -forward: if omitted, it is unchanged (the default is no lower limit). 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*. Note that the peer also enforces a -minimum for the channel: setting it below that will simply set it to -that value with a warning. Also note that *htlcmin* only applies to forwarded -HTLCs: we can still send smaller payments ourselves. - -*htlcmax* is an optional value that limits how large an HTLC we will -forward: if omitted, it is unchanged (the default is no effective -limit). 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*. Note that *htlcmax* -only applies to forwarded HTLCs: we can still send larger payments ourselves. - -*enforcedelay* is the number of seconds to delay before enforcing the -new fees/htlc max (default 600, which is ten minutes). This gives the -network a chance to catch up with the new rates and avoids rejecting -HTLCs before they do. This only has an effect if rates are increased -(we always allow users to overpay fees) or *htlcmax* is decreased, and -only applied to a single rate increase per channel (we don't remember -an arbitrary number of prior feerates) and if the node is restarted -the updated configuration is enforced immediately. - -*ignorefeelimits* set to True means to allow the peer to set the commitment -transaction fees (or closing transaction fees) to any value they want. This is dangerous: they could -set an exorbitant fee (so HTLCs are unenforcable), or a tiny fee (so that -commitment transactions cannot be relayed), but avoids channel breakage -in case of feerate disagreements. (Note: the global `ignore_fee_limits` -setting overrides this). - RETURN VALUE ------------ @@ -116,4 +66,4 @@ RESOURCES Main web site: -[comment]: # ( SHA256STAMP:5209ba4d4bbe2d897d9824f95a97fa48d968e83ffec2e4cfbd87df6fd90c48f0) +[comment]: # ( SHA256STAMP:5209ba4d4bbe2d897d9824f95a97fa48d968e83ffec2e4cfbd87df6fd90c48f0) \ No newline at end of file diff --git a/doc/lightning-setconfig.7.md b/doc/lightning-setconfig.7.md index f18270bcd54c..986c13509e36 100644 --- a/doc/lightning-setconfig.7.md +++ b/doc/lightning-setconfig.7.md @@ -15,7 +15,6 @@ This new value will *also* be written at the end of the config file, for persist You can see what options are dynamically adjustable using lightning-listconfigs(7). Note that you can also adjust existing options for stopped plugins; they will have an effect when the plugin is restarted. - RETURN VALUE ------------ diff --git a/doc/lightning-setpsbtversion.7.md b/doc/lightning-setpsbtversion.7.md index 13a1ec03c95d..c317992e6808 100644 --- a/doc/lightning-setpsbtversion.7.md +++ b/doc/lightning-setpsbtversion.7.md @@ -11,9 +11,6 @@ DESCRIPTION The **setpsbtversion** RPC command converts the provided PSBT to the given version, and returns the base64 result of the conversion. Returns an error if version is invalid. -- *psbt*: The PSBT to change versions. -- *version*: The version to set. - EXAMPLE JSON REQUEST ------------ @@ -36,11 +33,9 @@ If successful the command returns a converted PSBT of the requested version. ERRORS ------ -On failure, an error is returned. - The following error codes may occur: -- -32602: Parameter missed or malformed; +- 32602: Parameter missed or malformed. EXAMPLE JSON RESPONSE ----- @@ -51,7 +46,6 @@ EXAMPLE JSON RESPONSE } ``` - AUTHOR ------ diff --git a/doc/lightning-signinvoice.7.md b/doc/lightning-signinvoice.7.md index fb1fba98c701..d79dc97be54c 100644 --- a/doc/lightning-signinvoice.7.md +++ b/doc/lightning-signinvoice.7.md @@ -13,9 +13,6 @@ The **signinvoice** RPC command signs an invoice. Unlike **createinvoice** it does not save the invoice into the database and thus does not require the preimage. -The *invstring* parameter is of bolt11 form, but the final signature -is ignored. Minimal sanity checks are done. - RETURN VALUE ------------ diff --git a/doc/lightning-signmessage.7.md b/doc/lightning-signmessage.7.md index d0759ff3b3f9..45aef6449762 100644 --- a/doc/lightning-signmessage.7.md +++ b/doc/lightning-signmessage.7.md @@ -14,8 +14,6 @@ The **signmessage** RPC command creates a digital signature of node's *id* and the *message* can be sure that the resulting signature could only be created by something with access to this node's secret key. -*message* must be less that 65536 characters. - RETURN VALUE ------------ diff --git a/doc/lightning-signpsbt.7.md b/doc/lightning-signpsbt.7.md index 1457970fe315..f6b45cafa552 100644 --- a/doc/lightning-signpsbt.7.md +++ b/doc/lightning-signpsbt.7.md @@ -12,9 +12,6 @@ DESCRIPTION **signpsbt** is a low-level RPC command which signs a PSBT as defined by BIP-174. -- *psbt*: A string that represents the PSBT value. -- *signonly*: An optional array of input numbers to sign. - By default, all known inputs are signed, and others ignored: with *signonly*, only those inputs are signed, and an error is returned if one of them cannot be signed. @@ -22,7 +19,6 @@ one of them cannot be signed. Note that the command will fail if there are no inputs to sign, or if the inputs to be signed were not previously reserved. - EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-splice_init.7.md b/doc/lightning-splice_init.7.md index 5f47715b78db..5df1d5fec46a 100644 --- a/doc/lightning-splice_init.7.md +++ b/doc/lightning-splice_init.7.md @@ -14,22 +14,6 @@ DESCRIPTION `splice_init` is a low level RPC command which initiates a channel splice for a given channel specified by `channel_id`. -*channel\_id* is the channel id of the channel to be spliced. - -*relative\_amount* is a positive or negative amount of satoshis to add or -subtract from the channel. - -*initalpsbt* is the (optional) base 64 encoded PSBT to begin with. If not -specified, one will be generated automatically. - -*feerate\_per\_kw* is the miner fee we promise our peer to pay for our side of -the splice transaction. It is calculated by `feerate_per_kw` * -our\_bytes\_in\_splice\_tx / 1000. - -*force\_feerate* is a boolean flag. By default splices will fail if the fee -provided looks too high. This is to protect against accidentally setting your -fee higher than intended. Set `force_feerate` to true to skip this saftey check. - Note you may need to add a double dash (\-\-) after splice\_init if using a negative *relative\_amount* so it is not interpretted as a command modifier. For example: ```shell @@ -101,10 +85,12 @@ On success, an object is returned, containing: SEE ALSO -------- +lightning-splice_signed(7), lightning-splice_update(7) + AUTHOR ------ -@dusty\_daemon +Dusty <<@dusty_daemon>> is mainly responsible. RESOURCES --------- diff --git a/doc/lightning-splice_signed.7.md b/doc/lightning-splice_signed.7.md index 07313e237463..1fe76c09bd43 100644 --- a/doc/lightning-splice_signed.7.md +++ b/doc/lightning-splice_signed.7.md @@ -14,15 +14,6 @@ DESCRIPTION `splice_signed` is a low level RPC command which finishes the active channel splice associated with `channel_id`. -*channel\_id* is the channel id of the channel being spliced. - -*psbt* is the final version of the psbt to complete the splice with. - -*sign\_first* is a flag that makes our node offer the final splice signature -first (defaults to false). When false, the node will calculate who should -sign first based off who is adding inputting the least sats to the splice as per -spec. - The *psbt* must have all signatures attached to all inputs that you have added to it or it will fail. @@ -83,10 +74,12 @@ On success, an object is returned, containing: SEE ALSO -------- +lightning-splice_init(7), lightning-splice_update(7) + AUTHOR ------ -@dusty\_daemon +Dusty <<@dusty_daemon>> is mainly responsible. RESOURCES --------- diff --git a/doc/lightning-splice_update.7.md b/doc/lightning-splice_update.7.md index 3b73ddbc1af2..e204c03ecf12 100644 --- a/doc/lightning-splice_update.7.md +++ b/doc/lightning-splice_update.7.md @@ -14,11 +14,6 @@ DESCRIPTION `splice_update` is a low level RPC command which updates the active channel splice associated with `channel_id`. -*channel\_id* is the channel id of the channel being spliced. - -*psbt* is the base 64 encoded PSBT returned from `splice_init` with any changes -added by the user. - `splice_update` must be called repeatidly until the result `commitments_secured` is `true`. Each time `splice_update` is called, it will return a new PSBT that may have changes. In the simplest case, you take the returned `psbt` and pass @@ -96,10 +91,12 @@ On success, an object is returned, containing: SEE ALSO -------- +lightning-splice_init(7), lightning-splice_signed(7) + AUTHOR ------ -@dusty\_daemon +Dusty <<@dusty_daemon>> is mainly responsible. RESOURCES --------- 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/lightning-txprepare.7.md b/doc/lightning-txprepare.7.md index cbcd8dbc0e1d..8209b4ced815 100644 --- a/doc/lightning-txprepare.7.md +++ b/doc/lightning-txprepare.7.md @@ -13,31 +13,6 @@ The **txprepare** RPC command creates an unsigned transaction which spends funds from Core Lightning's internal wallet to the outputs specified in *outputs*. -The *outputs* is the array of output that include *destination* -and *amount*(\{*destination*: *amount*\}). Its format is like: -[\{address1: amount1\}, \{address2: amount2\}] -or -[\{address: *all*\}]. -It supports any number of **confirmed** outputs. - -The *destination* of output is the address which can be of any Bitcoin accepted -type, including bech32. - -The *amount* of output is the amount to be sent from the internal wallet -(expressed, as name suggests, in amount). The string *all* can be used to specify -all available funds. Otherwise, it is in amount precision; it can be a whole -number, a whole number ending in *sat*, a whole number ending in *000msat*, -or a number with 1 to 8 decimal places ending in *btc*. - -*feerate* is an optional feerate to use: see NOTES in lightning-feerates(7) -for possible values. The default is *normal*. - -*minconf* specifies the minimum number of confirmations that used -outputs should have. Default is 1. - -*utxos* specifies the utxos to be used to fund the transaction, as an array -of "txid:vout". These must be drawn from the node's available UTXO set. - **txprepare** is similar to the first part of a **withdraw** command, but supports multiple outputs and uses *outputs* as parameter. The second part is provided by **txsend**. diff --git a/doc/lightning-utxopsbt.7.md b/doc/lightning-utxopsbt.7.md index e3a235d93e7c..2c017310cec1 100644 --- a/doc/lightning-utxopsbt.7.md +++ b/doc/lightning-utxopsbt.7.md @@ -4,7 +4,7 @@ lightning-utxopsbt -- Command to populate PSBT inputs from given UTXOs SYNOPSIS -------- -**utxopsbt** *satoshi* *feerate* *startweight* *utxos* [*reserve*] [*reservedok*] [*locktime*] [*min\_witness\_weight*] [*excess\_as\_change*] +**utxopsbt** *satoshi* *feerate* *startweight* *utxos* [*reserve*] [*reservedok*] [*locktime*] [*min\_witness\_weight*] [*excess\_as\_change*] [*opening\_anchor\_channel*] DESCRIPTION ----------- @@ -17,29 +17,6 @@ lightning-fundpsbt(7) except instead of an optional *minconf* parameter to select unreserved outputs from the wallet, it takes a compulsory list of outputs to use. -*utxos* must be an array of "txid:vout", each of which must be -reserved or available: the total amount must be sufficient to pay for -the resulting transaction plus *startweight* at the given *feerate*, -with at least *satoshi* left over (unless *satoshi* is **all**, which -is equivalent to setting it to zero). - -If *reserve* if not zero, then *reserveinputs* is called (successfully, with -*exclusive* true) on the returned PSBT for this number of blocks (default -72 blocks if unspecified). - -Unless *reservedok* is set to true (default is false) it will also fail -if any of the *utxos* are already reserved. - -*locktime* is an optional locktime: if not set, it is set to a recent -block height. - -*min\_witness\_weight* is an optional minimum weight to use for a UTXO's -witness. If the actual witness weight is greater than the provided minimum, -the actual witness weight will be used. - -*excess\_as\_change* is an optional boolean to flag to add a change output -for the excess sats. - RETURN VALUE ------------ diff --git a/doc/lightning-waitanyinvoice.7.md b/doc/lightning-waitanyinvoice.7.md index 2013a182e51e..3f3c4312c70f 100644 --- a/doc/lightning-waitanyinvoice.7.md +++ b/doc/lightning-waitanyinvoice.7.md @@ -15,20 +15,8 @@ any invoices paid prior to or including the *lastpay\_index*. This is usually called iteratively: once with no arguments, then repeatedly with the returned *pay\_index* entry. This ensures that no -paid invoice is missed. - -The *pay\_index* is a monotonically-increasing number assigned to an -invoice when it gets paid. The first valid *pay\_index* is 1; specifying -*lastpay\_index* of 0 equivalent to not specifying a *lastpay\_index*. -Negative *lastpay\_index* is invalid. - -If *timeout* is specified, wait at most that number of seconds, which -must be an integer. -If the specified *timeout* is reached, this command will return with an -error. -You can specify this to 0 so that **waitanyinvoice** will return -immediately with an error if no pending invoice is available yet. -If unspecified, this command will wait indefinitely. +paid invoice is missed. The *pay\_index* is a monotonically-increasing number +assigned to an invoice when it gets paid. The first valid *pay\_index* is 1. RETURN VALUE ------------ diff --git a/doc/lightning-waitblockheight.7.md b/doc/lightning-waitblockheight.7.md index 7e4ec8ee3e63..af3982c58892 100644 --- a/doc/lightning-waitblockheight.7.md +++ b/doc/lightning-waitblockheight.7.md @@ -11,10 +11,6 @@ DESCRIPTION The **waitblockheight** RPC command waits until the blockchain has reached the specified *blockheight*. -It will only wait up to *timeout* seconds (default 60). - -If the *blockheight* is a present or past block height, then this -command returns immediately. RETURN VALUE ------------ @@ -22,7 +18,7 @@ RETURN VALUE [comment]: # (GENERATE-FROM-SCHEMA-START) On success, an object is returned, containing: -- **blockheight** (u32): The current block height (>= *blockheight* parameter) +- **blockheight** (u32): The current block height (> *blockheight* parameter) [comment]: # (GENERATE-FROM-SCHEMA-END) diff --git a/doc/lightning-waitsendpay.7.md b/doc/lightning-waitsendpay.7.md index 217053da73fa..16b111821cf0 100644 --- a/doc/lightning-waitsendpay.7.md +++ b/doc/lightning-waitsendpay.7.md @@ -4,7 +4,7 @@ lightning-waitsendpay -- Command for sending a payment via a route SYNOPSIS -------- -**waitsendpay** *payment\_hash* [*timeout*] [*partid*] +**waitsendpay** *payment\_hash* [*timeout*] [*partid*] [*groupid*] DESCRIPTION ----------- @@ -13,18 +13,6 @@ The **waitsendpay** RPC command polls or waits for the status of an outgoing payment that was initiated by a previous **sendpay** invocation. -The *partid* argument must match that of the **sendpay** command. - -Optionally the client may provide a *timeout*, an integer in seconds, -for this RPC command to return. If the *timeout* is provided and the -given amount of time passes without the payment definitely succeeding or -definitely failing, this command returns with a 200 error code (payment -still in progress). If *timeout* is not provided this call will wait -indefinitely. - -Indicating a *timeout* of 0 effectively makes this call a pollable query -of the status of the payment. - If the payment completed with success, this command returns with success. Otherwise, if the payment completed with failure, this command returns an error. diff --git a/doc/lightning-withdraw.7.md b/doc/lightning-withdraw.7.md index 86ff6351c1d6..55a107ab4739 100644 --- a/doc/lightning-withdraw.7.md +++ b/doc/lightning-withdraw.7.md @@ -12,26 +12,6 @@ DESCRIPTION The **withdraw** RPC command sends funds from Core Lightning's internal wallet to the address specified in *destination*. -The address can be of any Bitcoin accepted type, including bech32. - -*satoshi* is the amount to be withdrawn from the internal wallet -(expressed, as name suggests, in satoshi). The string *all* can be used -to specify withdrawal of all available funds (but if we have -any anchor channels, this will always leave at least `min-emergency-msat` as change). -. Otherwise, it is in -satoshi precision; it can be a whole number, a whole number ending in -*sat*, a whole number ending in *000msat*, or a number with 1 to 8 -decimal places ending in *btc*. - -*feerate* is an optional feerate: see NOTES in lightning-feerates(7) -for possible values. The default is *normal*. - -*minconf* specifies the minimum number of confirmations that used -outputs should have. Default is 1. - -*utxos* specifies the utxos to be used to be withdrawn from, as an array -of "txid:vout". These must be drawn from the node's available UTXO set. - RETURN VALUE ------------ 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/delpay.schema.json b/doc/schemas/delpay.schema.json index 64e6d445b6b7..8fc82024556c 100644 --- a/doc/schemas/delpay.schema.json +++ b/doc/schemas/delpay.schema.json @@ -73,7 +73,7 @@ }, "groupid": { "type": "u64", - "description": "Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash" + "description": "grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash" }, "payment_preimage": { "type": "secret", diff --git a/doc/schemas/fundchannel_start.schema.json b/doc/schemas/fundchannel_start.schema.json index cbd420a39e75..6b1f94df9dcb 100644 --- a/doc/schemas/fundchannel_start.schema.json +++ b/doc/schemas/fundchannel_start.schema.json @@ -26,7 +26,7 @@ }, "mindepth": { "type": "u32", - "description": "Number of confirmations before we consider the channel active." + "description": "Number of confirmations before we consider the channel active" } } } diff --git a/doc/schemas/fundpsbt.request.json b/doc/schemas/fundpsbt.request.json index 7752196ade17..d1baebd68d42 100644 --- a/doc/schemas/fundpsbt.request.json +++ b/doc/schemas/fundpsbt.request.json @@ -9,37 +9,46 @@ ], "properties": { "satoshi": { - "type": "msat_or_all" + "type": "msat_or_all", + "description": "the minimum satoshi value of the output(s) needed (or the string `all` meaning use all unreserved inputs). If a value, it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" }, "feerate": { - "type": "feerate" + "type": "feerate", + "description": "used for the transaction as initial feerate. The default is *normal*" }, "startweight": { - "type": "u32" + "type": "u32", + "description": "the weight of the transaction before *fundpsbt* has added any inputs" }, "minconf": { - "type": "u32" + "type": "u32", + "description": "the minimum number of confirmations that used outputs should have. Default is 1" }, "reserve": { "type": "u32", - "description": "reserve is a number: if non-zero number then reserveinputs is called (successfully, with exclusive true) on the returned PSBT for this number of blocks (default: 72)." + "description": "if not zero, then *reserveinputs* is called (successfully, with *exclusive* true) on the returned PSBT for this number of blocks. Defaults to 72 blocks if unspecified" }, "locktime": { - "type": "u32" + "type": "u32", + "description": "the locktime of the transaction. if not set, it is set to a recent block height" }, "min_witness_weight": { - "type": "u32" + "type": "u32", + "description": "minimum weight to use for a UTXO's witness. If the actual witness weight is greater than the provided minimum, the actual witness weight will be used" }, "excess_as_change": { - "type": "boolean" + "type": "boolean", + "description": "flag to add a change output for the excess sats" }, "nonwrapped": { "added": "v23.02", - "type": "boolean" + "type": "boolean", + "description": "to signal to filter out any p2sh-wrapped inputs from funding this PSBT" }, "opening_anchor_channel": { "added": "v23.08", - "type": "boolean" + "type": "boolean", + "description": "to signel that it needs emergency reserve for anchors so that we can lowball our commitment tx fees, and min-emergency-msat for reserving some sats for closing anchor channels" } } } 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/listchannels.schema.json b/doc/schemas/listchannels.schema.json index 9761f0a15e8f..a9a89bab58b9 100644 --- a/doc/schemas/listchannels.schema.json +++ b/doc/schemas/listchannels.schema.json @@ -79,7 +79,7 @@ }, "delay": { "type": "u32", - "description": "The number of blocks delay required by *source* to use this channel" + "description": "the number of blocks delay required by *source* to use this channel" }, "htlc_minimum_msat": { "type": "msat", 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..d5b960ff41da 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": "the string value 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/listnodes.request.json b/doc/schemas/listnodes.request.json index c7f1eb55611f..4ea8c6322d77 100644 --- a/doc/schemas/listnodes.request.json +++ b/doc/schemas/listnodes.request.json @@ -5,7 +5,8 @@ "additionalProperties": false, "properties": { "id": { - "type": "pubkey" + "type": "pubkey", + "description": "The public key of the node to list" } } } 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/multifundchannel.request.json b/doc/schemas/multifundchannel.request.json index 236c009a2a7d..96f082479d5b 100644 --- a/doc/schemas/multifundchannel.request.json +++ b/doc/schemas/multifundchannel.request.json @@ -6,6 +6,7 @@ "properties": { "destinations": { "type": "array", + "description": "there must be at least one entry in *destinations*; it cannot be an empty array", "items": { "type": "object", "additionalProperties": false, @@ -16,7 +17,7 @@ "properties": { "id": { "type": "pubkey", - "description": "node ID, with an optional *@host:port* appended to it in a manner understood by **connect**; see lightning-connect(7). Each entry in the *destinations* array must have a unique node *id*" + "description": "node ID, with an optional *@host:port* appended to it in a manner understood by **connect**; see lightning-connect(7). Each entry in the *destinations* array must have a unique node *id*. If not already connected, **multifundchannel** will automatically attempt to connect to the node" }, "amount": { "type": "msat", @@ -43,36 +44,40 @@ "type": "string", "description": "compact represenation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel to this destination" }, + "mindepth": { + "type": "u32", + "description": "number of confirmations before we consider the channel active" + }, "reserve": { "type": "msat", "description": "amount we want the peer to maintain on its side of the channel. Default is 1% of the funding amount. It can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" } } - }, - "feerate": { - "type": "feerate", - "description": "feerate used for the opening transaction, and if *commitment_feerate* is not set, as initial feerate for commitment and HTLC transactions. See NOTES in lightning-feerates(7) for possible values. The default is *normal*" - }, - "minconf": { - "type": "integer", - "description": "minimum number of confirmations that used outputs should have. Default is 1", - "default": 1 - }, - "utxos": { - "type": "array", - "items": { - "type": "outpoint", - "description": "utxos to be used to fund the channel, as an array of `txid:vout`" - } - }, - "minchannels": { - "type": "integer", - "description": "re-attempt funding as long as at least this many peers remain (must not be zero). The **multifundchannel** command will only fail if too many peers fail the funding process" - }, - "commitment_feerate": { - "type": "feerate", - "description": "initial feerate for commitment and HTLC transactions. See *feerate* for valid values" } + }, + "feerate": { + "type": "feerate", + "description": "feerate used for the opening transaction, and if *commitment_feerate* is not set, as initial feerate for commitment and HTLC transactions. See NOTES in lightning-feerates(7) for possible values. The default is *normal*" + }, + "minconf": { + "type": "integer", + "description": "minimum number of confirmations that used outputs should have. Default is 1", + "default": 1 + }, + "utxos": { + "type": "array", + "items": { + "type": "outpoint", + "description": "utxos to be used to fund the channel, as an array of `txid:vout`" + } + }, + "minchannels": { + "type": "integer", + "description": "re-attempt funding as long as at least this many peers remain (must not be zero). The **multifundchannel** command will only fail if too many peers fail the funding process" + }, + "commitment_feerate": { + "type": "feerate", + "description": "initial feerate for commitment and HTLC transactions. See *feerate* for valid values" } } } \ No newline at end of file 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/pay.request.json b/doc/schemas/pay.request.json index 784035cfac3c..8942a3863e9e 100644 --- a/doc/schemas/pay.request.json +++ b/doc/schemas/pay.request.json @@ -7,38 +7,48 @@ ], "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice, if **experimental-offers** is enabled, it can actually be a bolt12 invoice, such as one received from lightningd-fetchinvoice(7). If it does not contain an amount, *amount_msat* is required, otherwise if it is specified it must be *null*" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "*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*" }, "label": { - "type": "string" + "type": "string", + "description": "it is used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)" }, "riskfactor": { - "type": "number" + "type": "number", + "description": "the *riskfactor* is described in detail in lightning-getroute(7), and defaults to 10" }, "maxfeepercent": { - "type": "number" + "type": "number", + "description": "percentage of the amount that is to be paid. Defaults to 0.5" }, "retry_for": { - "type": "u16" + "type": "u16", + "description": "until *retry_for* seconds passes, the command will keep finding routes and retrying the payment. Defaults to 60 seconds" }, "maxdelay": { - "type": "u16" + "type": "u16", + "description": "a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case" }, "exemptfee": { - "type": "msat" + "type": "msat", + "description": "this 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`. Defaults to 5000 millisatoshi" }, "localinvreqid": { - "type": "hex" + "type": "hex", + "description": "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7). This ensures that we only make a single payment for an offer, and that the offer is marked `used` once paid" }, "exclude": { "type": "array", + "description": "*exclude* is a JSON array of short-channel-id/direction (e.g. [ '564334x877x1/0', '564195x1292x0/1' ]) or pubkey which should be excluded from consideration for routing. The default is not to exclude any channels or nodes", "items": { "oneOf": [ { - "type": "short_channel_id_dir" + "type": "short-channel-id/direction" }, { "type": "pubkey" @@ -47,10 +57,12 @@ } }, "maxfee": { - "type": "msat" + "type": "msat", + "description": "*maxfee* overrides both *maxfeepercent* and *exemptfee* defaults (and if you specify *maxfee* you cannot specify either of those), and creates an absolute limit on what fee we will pay. This allows you to implement your own heuristics rather than the primitive ones used here" }, "description": { - "type": "string" + "type": "string", + "description": "it is only required for bolt11 invoices which do not contain a description themselves, but contain a description hash: in this case *description* is required. *description* is then checked against the hash inside the invoice before it will be paid" } } } diff --git a/doc/schemas/ping.request.json b/doc/schemas/ping.request.json index 31f2aefdbd7a..c5b2dae32470 100644 --- a/doc/schemas/ping.request.json +++ b/doc/schemas/ping.request.json @@ -7,13 +7,16 @@ "additionalProperties": false, "properties": { "id": { - "type": "pubkey" + "type": "pubkey", + "description": "The pubkey of the node to ping" }, "len": { - "type": "u16" + "type": "u16", + "description": "the length of the ping. Defaults to 128" }, "pongbytes": { - "type": "u16" + "type": "u16", + "description": "the length of the reply. A value of 65532 to 65535 means `don't reply`. Defaults to 128" } } } diff --git a/doc/schemas/preapproveinvoice.request.json b/doc/schemas/preapproveinvoice.request.json index 85437b9a21af..19625fc29eff 100644 --- a/doc/schemas/preapproveinvoice.request.json +++ b/doc/schemas/preapproveinvoice.request.json @@ -9,6 +9,7 @@ "properties": { "bolt11": { "type": "string", + "description": "bolt11 invoice to submit to the HSM to check", "added": "v23.02" } } diff --git a/doc/schemas/preapprovekeysend.request.json b/doc/schemas/preapprovekeysend.request.json index 53a1cb8d50f9..ee2fc3a1d034 100644 --- a/doc/schemas/preapprovekeysend.request.json +++ b/doc/schemas/preapprovekeysend.request.json @@ -11,17 +11,19 @@ "properties": { "destination": { "type": "pubkey", + "description": "it is a 33 byte, hex-encoded, node ID of the node that the payment should go to", "added": "v23.02" }, "payment_hash": { "type": "hex", "added": "v23.02", - "description": "the hash of the *payment_preimage* which will prove payment", + "description": "it is the unique identifier of a payment", "maxLength": 64, "minLength": 64 }, "amount_msat": { "type": "msat", + "description": "the amount to send 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`", "added": "v23.02" } } diff --git a/doc/schemas/recover.request.json b/doc/schemas/recover.request.json new file mode 100644 index 000000000000..2e983f6f3b93 --- /dev/null +++ b/doc/schemas/recover.request.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ + "hsmsecret" + ], + "properties": { + "hsmsecret": { + "type": "string", + "description": "either a codex32 secret starting with `cl1` as returned by `hsmtool getcodexsecret`, or a raw 64 character hex string" + } + } +} diff --git a/doc/schemas/recover.schema.json b/doc/schemas/recover.schema.json new file mode 100644 index 000000000000..1aad2dcae935 --- /dev/null +++ b/doc/schemas/recover.schema.json @@ -0,0 +1,6 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "properties": {} +} diff --git a/doc/schemas/renepay.request.json b/doc/schemas/renepay.request.json index 20363cd16faf..241abd8f7186 100644 --- a/doc/schemas/renepay.request.json +++ b/doc/schemas/renepay.request.json @@ -6,15 +6,15 @@ "properties": { "invstring": { "type": "string", - "description": "bolt11 invoice to pay" + "description": "bolt11 invoice which the RPC command attempts to pay. Currently, **renepay** supports bolt11 invoices only" }, "amount_msat": { "type": "msat", - "description": "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*" + "description": "if the *invstring* does not contain an amount, *amount_msat* is required, otherwise if it is specified it must be *null*. 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*" }, "maxfee": { "type": "msat", - "description": "limits how much is paid fees and it is measured in millisatoshi by default, but also in this case the unit can be specified with a suffix: *msat*, *sat* or *btc*. The default value is 5 sats or 0.5% whichever is higher" + "description": "*maxfee* is a hard bound, in the sense that the command will never attempt a payment when the fees exceed that value" }, "maxdelay": { "type": "number", @@ -22,7 +22,7 @@ }, "retry_for": { "type": "number", - "description": "measured in seconds (default: 60) specifies how much time it is allowed for the command to keep retrying the payment" + "description": "measured in seconds specifies how much time it is allowed for the command to keep retrying the payment. Defaults to 60 seconds" }, "description": { "type": "string", diff --git a/doc/schemas/renepaystatus.request.json b/doc/schemas/renepaystatus.request.json index 4581b36f7137..b1fd461dbd0f 100644 --- a/doc/schemas/renepaystatus.request.json +++ b/doc/schemas/renepaystatus.request.json @@ -6,7 +6,7 @@ "properties": { "invstring": { "type": "string", - "description": "bolt11 invoice to check status" + "description": "if specified, the command will return a list of payment attempts whose invoice matches *invstring*, otherwise all payments with be listed" } } } \ No newline at end of file diff --git a/doc/schemas/reserveinputs.schema.json b/doc/schemas/reserveinputs.schema.json index adfc66b9df76..b0803854ace0 100644 --- a/doc/schemas/reserveinputs.schema.json +++ b/doc/schemas/reserveinputs.schema.json @@ -21,11 +21,11 @@ "properties": { "txid": { "type": "txid", - "description": "the transaction id" + "description": "the input transaction id" }, "vout": { "type": "u32", - "description": "the output number which was reserved" + "description": "the input index output number which was reserved" }, "was_reserved": { "type": "boolean", diff --git a/doc/schemas/sendcustommsg.request.json b/doc/schemas/sendcustommsg.request.json index 3a06534d4feb..6a3787debc0c 100644 --- a/doc/schemas/sendcustommsg.request.json +++ b/doc/schemas/sendcustommsg.request.json @@ -9,10 +9,12 @@ "additionalProperties": false, "properties": { "node_id": { - "type": "pubkey" + "type": "pubkey", + "description": "the node specified by `node_id` must be a peer, i.e., it must have a direct connection with the node receiving the RPC call, and the connection must be established. For a method to send arbitrary messages over multiple hops, including hops that do not understand the custom message, see the `createonion` and `sendonion` RPC methods. Messages can only be injected if the connection is handled by `openingd` or `channeld`. Messages cannot be injected when the peer is handled by `onchaind` or `closingd` since these do not have a connection, or are synchronous daemons that do not handle spontaneous messages" }, "msg": { - "type": "hex" + "type": "hex", + "description": "must be a hex encoded well-formed message, including the 2-byte type prefix, but excluding the length prefix which will be added by the RPC method. The message types may not be one of the internally handled types, since that may cause issues with the internal state tracking of Core Lightning. We do (as of *v23.11*) allow sending of even types, but note that peers (as per the spec) will disconnect on receiving unknown even types" } } } diff --git a/doc/schemas/sendonion.request.json b/doc/schemas/sendonion.request.json index 26cd99aa6ee7..a4ab01ae0ecc 100644 --- a/doc/schemas/sendonion.request.json +++ b/doc/schemas/sendonion.request.json @@ -9,10 +9,12 @@ ], "properties": { "onion": { - "type": "hex" + "type": "hex", + "description": "hex-encoded 1366 bytes long blob that was returned by either of the tools that can generate onions. It contains the payloads destined for each hop and some metadata. Please refer to [BOLT 04][bolt04] for further details. If is specific to the route that is being used and the *payment_hash* used to construct, and therefore cannot be reused for other payments or to attempt a separate route. The custom onion can generally be created using the `devtools/onion` CLI tool, or the **createonion** RPC command" }, "first_hop": { "type": "object", + "description": "instructs Core Lightning which peer to send the onion to. It is a JSON dictionary that corresponds to the first element of the route array returned by *getroute*", "required": [ "id", "amount_msat", @@ -20,45 +22,61 @@ ], "properties": { "id": { - "type": "pubkey" + "type": "pubkey", + "description": "node id for the peer. Use any available channel available to this peer" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "the amount to add an HTLC for millisatoshis" }, "delay": { - "type": "u16" + "type": "u16", + "description": "the number of blocks delay of blocks on top of the current blockheight" } } }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "specifies the 32 byte hex-encoded hash to use as a challenge to the HTLC that we are sending. It is specific to the onion and has to match the one the onion was created with" }, "label": { - "type": "string" + "type": "string", + "description": "can be used to provide a human readable reference to retrieve the payment at a later time" }, "shared_secrets": { "type": "array", + "description": "a JSON list of 32 byte hex-encoded secrets that were used when creating the onion. Core Lightning can send a payment with a custom onion without the knowledge of these secrets, however it will not be able to parse an eventual error message since that is encrypted with the shared secrets used in the onion. If *shared_secrets* is provided Core Lightning will decrypt the error, act accordingly, e.g., add a `channel_update` included in the error to its network view, and set the details in *listsendpays* correctly. If it is not provided Core Lightning will store the encrypted onion, and expose it in *listsendpays* allowing the caller to decrypt it externally. If it is not provided the Core Lightning node does not know how long the route is, which channels or nodes are involved, and what an eventual error could have been. It can therefore be used for oblivious payments", "items": { "type": "secret" } }, "partid": { - "type": "u16" + "type": "u16", + "description": "if provided and non-zero, allows for multiple parallel partial payments with the same *payment_hash*" }, "bolt11": { - "type": "string" + "type": "string", + "description": "if provided, it will be returned in *waitsendpay* and *listsendpays* results" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "used to annotate the payment, and is returned by *waitsendpay* and *listsendpays*" }, "destination": { - "type": "pubkey" + "type": "pubkey", + "description": "if provided, it will be returned in **listpays** result" }, "localinvreqid": { - "type": "hash" + "type": "hex", + "description": "`localinvreqid` is used by offers to link a payment attempt to a local `invoice_request` offer created by lightningd-invoicerequest(7)" }, "groupid": { - "type": "u64" + "type": "u64", + "description": "grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash" + }, + "description": { + "type": "string", + "description": "if provided, it will be returned in *waitsendpay* and *listsendpays* results" } } } diff --git a/doc/schemas/sendpay.request.json b/doc/schemas/sendpay.request.json index 67d645423ec9..2a8077919093 100644 --- a/doc/schemas/sendpay.request.json +++ b/doc/schemas/sendpay.request.json @@ -18,44 +18,64 @@ "channel" ], "properties": { - "amount_msat": { - "type": "msat" - }, "id": { - "type": "pubkey" + "type": "pubkey", + "description": "The node at the end of this hop" + }, + "channel": { + "type": "short_channel_id", + "description": "The channel joining these nodes" }, "delay": { - "type": "u16" + "type": "u32", + "description": "The total CLTV expected by the node at the end of this hop" }, - "channel": { - "type": "short_channel_id" + "amount_msat": { + "type": "msat", + "description": "The amount expected by the node at the end of this hop" } } } }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "the hash of the payment_preimage" }, "label": { - "type": "string" + "type": "string", + "description": "the label provided when creating the invoice_request" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "amount must be provided if *partid* is non-zero, or the payment is to-self, otherwise it must be equal to the final amount to the destination. By default it is 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*" }, "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice to pay. If provided, will be returned in *waitsendpay* and *listsendpays* results" }, "payment_secret": { - "type": "secret" + "type": "secret", + "description": "value that the final recipient requires to accept the payment, as defined by the `payment_data` field in BOLT 4 and the `s` field in the BOLT 11 invoice format. It is required if *partid* is non-zero" }, "partid": { - "type": "u16" + "type": "u64", + "description": "must not be provided for self-payments. If provided and non-zero, allows for multiple parallel partial payments with the same *payment_hash*. The *amount_msat* amount (which must be provided) for each **sendpay** with matching *payment_hash* must be equal, and **sendpay** will fail if there are differing values given" }, "localinvreqid": { - "type": "hex" + "type": "hex", + "description": "indicates that this payment is being made for a local invoice_request. This ensures that we only send a payment for a single-use invoice_request once" }, "groupid": { - "type": "u64" + "type": "u64", + "description": "allows you to attach a number which appears in **listsendpays** so payments can be identified as part of a logical group. The *pay* plugin uses this to identify one attempt at a MPP payment, for example" + }, + "payment_metadata": { + "type": "hex", + "description": "placed in the final onion hop TLV" + }, + "description": { + "type": "string", + "description": "description used in the invoice" } } } diff --git a/doc/schemas/sendpsbt.request.json b/doc/schemas/sendpsbt.request.json index bc55bb8308ba..e8e2f9e8d5a0 100644 --- a/doc/schemas/sendpsbt.request.json +++ b/doc/schemas/sendpsbt.request.json @@ -7,10 +7,12 @@ ], "properties": { "psbt": { - "type": "string" + "type": "string", + "description": "the fully signed psbt to be sent" }, "reserve": { - "type": "boolean" + "type": "u32", + "description": "number of blocks to increase reservation of any of our inputs by. Default is 72" } } } diff --git a/doc/schemas/setchannel.request.json b/doc/schemas/setchannel.request.json index dae031975705..0499e7497077 100644 --- a/doc/schemas/setchannel.request.json +++ b/doc/schemas/setchannel.request.json @@ -7,26 +7,33 @@ ], "properties": { "id": { - "type": "string" + "type": "string", + "description": "should contain a scid (short channel ID), channel id or peerid (pubkey) of the channel to be modified. If *id* is set to `all`, the updates are applied to all channels in states CHANNELD_NORMAL CHANNELD_AWAITING_LOCKIN or DUALOPEND_AWAITING_LOCKIN. If *id* is a peerid, all channels with the +peer in those states are changed" }, "feebase": { - "type": "msat" + "type": "msat", + "description": "value in millisatoshi that is added as base fee to any routed payment: if omitted, it is unchanged. 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*" }, "feeppm": { - "type": "u32" + "type": "u32", + "description": "value that is added proportionally per-millionths to any routed payment volume in satoshi. For example, if ppm is 1,000 and 1,000,000 satoshi is being routed through the channel, an proportional fee of 1,000 satoshi is added, resulting in a 0.1% fee" }, "htlcmin": { - "type": "msat" + "type": "msat", + "description": "value that limits how small an HTLC we will forward: if omitted, it is unchanged (the default is no lower limit). 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*. Note that the peer also enforces a minimum for the channel: setting it below that will simply set it to that value with a warning. Also note that *htlcmin* only applies to forwarded HTLCs: we can still send smaller payments ourselves" }, "htlcmax": { - "type": "msat" + "type": "msat", + "description": "value that limits how large an HTLC we will forward: if omitted, it is unchanged (the default is no effective limit). 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*. Note that *htlcmax* only applies to forwarded HTLCs: we can still send larger payments ourselves" }, "enforcedelay": { - "type": "u32" + "type": "u32", + "description": "number of seconds to delay before enforcing the new fees/htlc max (default 600, which is ten minutes). This gives the network a chance to catch up with the new rates and avoids rejecting HTLCs before they do. This only has an effect if rates are increased (we always allow users to overpay fees) or *htlcmax* is decreased, and only applied to a single rate increase per channel (we don't remember an arbitrary number of prior feerates) and if the node is restarted the updated configuration is enforced immediately" }, "ignorefeelimits": { "added": "v23.08", - "type": "boolean" + "type": "boolean", + "description": "if set to True means to allow the peer to set the commitment transaction fees (or closing transaction fees) to any value they want. This is dangerous: they could set an exorbitant fee (so HTLCs are unenforcable), or a tiny fee (so that commitment transactions cannot be relayed), but avoids channel breakage in case of feerate disagreements. (Note: the global `ignore_fee_limits` setting overrides this)" } } } diff --git a/doc/schemas/setconfig.request.json b/doc/schemas/setconfig.request.json index 7dd24fc1b151..6331bdddf6b9 100644 --- a/doc/schemas/setconfig.request.json +++ b/doc/schemas/setconfig.request.json @@ -8,8 +8,12 @@ "added": "v23.08", "properties": { "config": { - "type": "string" + "type": "string", + "description": "name of the config variable which should be set to the value of the variable" }, - "val": {} + "val": { + "type": "string or msat or int or boolean", + "description": "value of the config variable to be set or updated" + } } } diff --git a/doc/schemas/setpsbtversion.request.json b/doc/schemas/setpsbtversion.request.json new file mode 100644 index 000000000000..aac57525487e --- /dev/null +++ b/doc/schemas/setpsbtversion.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["psbt", "version"], + "properties": { + "psbt": { + "type": "string", + "description": "the PSBT to change versions" + }, + "version": { + "type": "integer", + "description": "the version to set" + } + } +} diff --git a/doc/schemas/setpsbtversion.schema.json b/doc/schemas/setpsbtversion.schema.json new file mode 100644 index 000000000000..ac11f52e773b --- /dev/null +++ b/doc/schemas/setpsbtversion.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["psbt"], + "properties": { + "psbt": { + "type": "string", + "description": "a converted PSBT of the requested version" + } + } +} 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" } } } diff --git a/doc/schemas/signinvoice.request.json b/doc/schemas/signinvoice.request.json index 40b8e3f46a55..25ff240945af 100644 --- a/doc/schemas/signinvoice.request.json +++ b/doc/schemas/signinvoice.request.json @@ -8,8 +8,8 @@ ], "properties": { "invstring": { - "type": "string", - "description": "" + "type": "bolt11", + "description": "bolt11 form, but the final signature is ignored. Minimal sanity checks are done" } } } diff --git a/doc/schemas/signmessage.request.json b/doc/schemas/signmessage.request.json index 163239e207bc..9ff224c7f339 100644 --- a/doc/schemas/signmessage.request.json +++ b/doc/schemas/signmessage.request.json @@ -7,7 +7,8 @@ "additionalProperties": false, "properties": { "message": { - "type": "string" + "type": "string", + "description": "less that 65536 characters long message to be signed by the node" } } } diff --git a/doc/schemas/signpsbt.request.json b/doc/schemas/signpsbt.request.json index c8a2bbf85555..11cbe05e1778 100644 --- a/doc/schemas/signpsbt.request.json +++ b/doc/schemas/signpsbt.request.json @@ -7,10 +7,12 @@ ], "properties": { "psbt": { - "type": "string" + "type": "string", + "description": "the psbt to be signed" }, "signonly": { "type": "array", + "description": "input numbers to sign", "items": { "type": "u32" } diff --git a/doc/schemas/splice_init.request.json b/doc/schemas/splice_init.request.json index ed01150df351..01573ac1090a 100644 --- a/doc/schemas/splice_init.request.json +++ b/doc/schemas/splice_init.request.json @@ -26,7 +26,7 @@ }, "force_feerate": { "type": "boolean", - "description": "By default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check" + "description": "by default splices will fail if the fee provided looks too high. This is to protect against accidentally setting your fee higher than intended. Set `force_feerate` to true to skip this saftey check" } } } diff --git a/doc/schemas/splice_update.request.json b/doc/schemas/splice_update.request.json index 08bf814a49a8..1cdac8e25e39 100644 --- a/doc/schemas/splice_update.request.json +++ b/doc/schemas/splice_update.request.json @@ -14,7 +14,7 @@ }, "psbt": { "type": "string", - "description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically" + "description": "the base 64 encoded PSBT returned from `splice_init` with any changes added by the user" } } } diff --git a/doc/schemas/txdiscard.request.json b/doc/schemas/txdiscard.request.json index 6488647acce7..7a9e87538208 100644 --- a/doc/schemas/txdiscard.request.json +++ b/doc/schemas/txdiscard.request.json @@ -7,7 +7,8 @@ ], "properties": { "txid": { - "type": "txid" + "type": "txid", + "description": "the transaction id, inputs should be unreseverd from" } } } diff --git a/doc/schemas/txprepare.request.json b/doc/schemas/txprepare.request.json index 936c4d9e5880..91d3484b00ff 100644 --- a/doc/schemas/txprepare.request.json +++ b/doc/schemas/txprepare.request.json @@ -8,18 +8,37 @@ "properties": { "outputs": { "type": "array", + "description": "format is like: [{destination1: amount1}, {destination2: amount2}] or [{destination: *all*}]. It supports any number of **confirmed** outputs", "items": { - "type": "outputdesc" + "type": "object", + "additionalProperties": true, + "required": [ + "destination", + "amount" + ], + "properties": { + "destination": { + "type": "string", + "description": "the address which can be of any Bitcoin accepted type, including bech32" + }, + "amount": { + "type": "msat", + "description": "the amount to be sent from the internal wallet (expressed, as name suggests, in amount). The string *all* can be used to specify all available funds. Otherwise, it is in amount precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" + } + } } }, "feerate": { - "type": "feerate" + "type": "feerate", + "description": "used for the transaction as initial feerate. The default is *normal*" }, "minconf": { - "type": "u32" + "type": "u32", + "description": "the minimum number of confirmations that used outputs should have. Default is 1" }, "utxos": { "type": "array", + "description": "to be used to fund the transaction, as an array of `txid:vout`. These must be drawn from the node's available UTXO set", "items": { "type": "outpoint" } diff --git a/doc/schemas/txsend.request.json b/doc/schemas/txsend.request.json index 6488647acce7..18ef78478ffa 100644 --- a/doc/schemas/txsend.request.json +++ b/doc/schemas/txsend.request.json @@ -7,7 +7,8 @@ ], "properties": { "txid": { - "type": "txid" + "type": "txid", + "description": "The transaction id of the transaction created by **txprepare**" } } } diff --git a/doc/schemas/utxopsbt.request.json b/doc/schemas/utxopsbt.request.json index 6a58abdfacc6..db6f3d98c663 100644 --- a/doc/schemas/utxopsbt.request.json +++ b/doc/schemas/utxopsbt.request.json @@ -10,39 +10,48 @@ ], "properties": { "satoshi": { - "type": "msat" + "type": "msat_or_all", + "description": "the minimum satoshi value of the output(s) needed (or the string `all` meaning use all unreserved inputs). If a value, it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" }, "feerate": { - "type": "feerate" + "type": "feerate", + "description": "used for the transaction as initial feerate. The default is *normal*" }, "startweight": { - "type": "u32" + "type": "u32", + "description": "the weight of the transaction before *fundpsbt* has added any inputs" }, "utxos": { "type": "array", + "description": "an array of `txid:vout`, each of which must be reserved or available", "items": { "type": "outpoint" } }, "reserve": { "type": "u32", - "description": "reserve is a number: if non-zero number then reserveinputs is called (successfully, with exclusive true) on the returned PSBT for this number of blocks (default: 72)." + "description": "if not zero, then *reserveinputs* is called (successfully, with *exclusive* true) on the returned PSBT for this number of blocks. Defaults to 72 blocks if unspecified" }, "reservedok": { - "type": "boolean" + "type": "boolean", + "description": "if set to true, it will also fail if any of the *utxos* are already reserved. Default is false" }, "locktime": { - "type": "u32" + "type": "u32", + "description": "if not set, it is set to a recent block height" }, "min_witness_weight": { - "type": "u32" + "type": "u32", + "description": "minimum weight to use for a UTXO's witness. If the actual witness weight is greater than the provided minimum, the actual witness weight will be used" }, "excess_as_change": { - "type": "boolean" + "type": "boolean", + "description": "flag to add a change output for the excess sats" }, "opening_anchor_channel": { "added": "v23.08", - "type": "boolean" + "type": "boolean", + "description": "to signel that it needs emergency reserve for anchors so that we can lowball our commitment tx fees, and min-emergency-msat for reserving some sats for closing anchor channels" } } } diff --git a/doc/schemas/wait.request.json b/doc/schemas/wait.request.json index 2febefeb16dd..e21c13d6095a 100644 --- a/doc/schemas/wait.request.json +++ b/doc/schemas/wait.request.json @@ -11,6 +11,7 @@ "properties": { "subsystem": { "type": "string", + "description": "the subsystem to get the next index value from", "enum": [ "invoices", "forwards", @@ -19,6 +20,7 @@ }, "indexname": { "type": "string", + "description": "the name of the index to get the next value for", "enum": [ "created", "updated", @@ -26,7 +28,8 @@ ] }, "nextvalue": { - "type": "u64" + "type": "u64", + "description": "the next value of the index" } } } diff --git a/doc/schemas/waitanyinvoice.request.json b/doc/schemas/waitanyinvoice.request.json index 5c9ce9867bb0..f39c0b8f3077 100644 --- a/doc/schemas/waitanyinvoice.request.json +++ b/doc/schemas/waitanyinvoice.request.json @@ -5,10 +5,12 @@ "required": [], "properties": { "lastpay_index": { - "type": "u64" + "type": "u64", + "description": "ignores any invoices paid prior to or including this index. 0 is equivalent to not specifying and negative value is invalid" }, "timeout": { - "type": "u64" + "type": "u64", + "description": "if specified, wait at most that number of seconds, which must be an integer. If the specified *timeout* is reached, this command will return with an error. You can specify this to 0 so that **waitanyinvoice** will return immediately with an error if no pending invoice is available yet. If unspecified, this command will wait indefinitely" } } } diff --git a/doc/schemas/waitblockheight.request.json b/doc/schemas/waitblockheight.request.json index d564a5628afa..3e2a1b091643 100644 --- a/doc/schemas/waitblockheight.request.json +++ b/doc/schemas/waitblockheight.request.json @@ -8,11 +8,11 @@ "properties": { "blockheight": { "type": "u32", - "description": "The current block height (>= blockheight parameter)" + "description": "current blockheight of the blockchain if the value is greater than this number. If it is a present or past block height, then the command returns immediately" }, "timeout": { "type": "u32", - "description": "If timeout seconds is reached without the specified blockheight being reached, this command will fail with a code of 2000." + "description": "only wait up to specified seconds. Defaults to 60 seconds" } } } diff --git a/doc/schemas/waitinvoice.request.json b/doc/schemas/waitinvoice.request.json index 18cc4093d54b..dea8da0f5fd9 100644 --- a/doc/schemas/waitinvoice.request.json +++ b/doc/schemas/waitinvoice.request.json @@ -7,7 +7,8 @@ ], "properties": { "label": { - "type": "string" + "type": "string", + "description": "unique label of the invoice waiting to be paid" } } } diff --git a/doc/schemas/waitsendpay.request.json b/doc/schemas/waitsendpay.request.json index 9e6f3942b14a..8add51b93046 100644 --- a/doc/schemas/waitsendpay.request.json +++ b/doc/schemas/waitsendpay.request.json @@ -7,16 +7,20 @@ ], "properties": { "payment_hash": { - "type": "hash" + "type": "hash", + "description": "the hash of the *payment_preimage*" }, "timeout": { - "type": "u32" + "type": "u32", + "description": "a timeout in seconds, for this RPC command to return. If the *timeout* is provided and the given amount of time passes without the payment definitely succeeding or definitely failing, this command returns with a 200 error code (payment still in progress). If *timeout* is not provided this call will wait indefinitely. Indicating a *timeout* of 0 effectively makes this call a pollable query of the status of the payment" }, "partid": { - "type": "u64" + "type": "u64", + "description": "unique ID within this (multi-part) payment. It must match that of the **sendpay** command" }, "groupid": { - "type": "u64" + "type": "u64", + "description": "grouping key to disambiguate multiple attempts to pay the same payment_hash" } } } diff --git a/doc/schemas/withdraw.request.json b/doc/schemas/withdraw.request.json index 8a43b988fa94..41311d7517f8 100644 --- a/doc/schemas/withdraw.request.json +++ b/doc/schemas/withdraw.request.json @@ -3,23 +3,29 @@ "type": "object", "additionalProperties": false, "required": [ - "destination" + "destination", + "satoshi" ], "properties": { "destination": { - "type": "string" + "type": "string", + "description": "any Bitcoin accepted type, including bech32" }, "satoshi": { - "type": "msat_or_all" + "type": "msat_or_all", + "description": "the amount to be withdrawn from the internal wallet (expressed, as name suggests, in satoshi). The string *all* can be used to specify withdrawal of all available funds (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). Otherwise, it is in satoshi precision; it can be a whole number, a whole number ending in *sat*, a whole number ending in *000msat*, or a number with 1 to 8 decimal places ending in *btc*" }, "feerate": { - "type": "feerate" + "type": "feerate", + "description": "used for the withdrawal as initial feerate. The default is *normal*" }, "minconf": { - "type": "u16" + "type": "u16", + "description": "minimum number of confirmations that used outputs should have. Default is 1" }, "utxos": { "type": "array", + "description": "specifies the utxos to be used to be withdrawn from, as an array of `txid:vout`. These must be drawn from the node's available UTXO set", "items": { "type": "outpoint" } diff --git a/tools/fromschema.py b/tools/fromschema.py index 7d00639545bf..ff5dbdfe7ed7 100755 --- a/tools/fromschema.py +++ b/tools/fromschema.py @@ -104,6 +104,11 @@ def fmt_propname(propname): return "**{}**".format(esc_underscores(propname)) +def fmt_paramname(paramname, is_optional=True): + """Pretty-print format a parameter name""" + return " [*{}*]".format(esc_underscores(paramname)) if is_optional else " *{}*".format(esc_underscores(paramname)) + + def deprecated_to_deleted(vername): """We promise a 6 month minumum deprecation period, and versions are every 3 months""" assert vername.startswith("v") @@ -281,10 +286,7 @@ def output_params(schema): output("{}".format(fmt_propname(schema["rpc"]))) for p in toplevels: - if "required" in request and p in request["required"]: - output(" *" + p + "*") - else: - output(" [*" + p + "*]") + output("{}".format(fmt_paramname(p, False if "required" in request and p in request["required"] else True))) output("\n") diff --git a/tools/merge.py b/tools/merge.py index 2a8ccb00e14d..62ca4c0144e7 100644 --- a/tools/merge.py +++ b/tools/merge.py @@ -4,126 +4,23 @@ # Input folder containing JSON files input_folder = "/home/shahana/workspace/lightning/doc/" -# raw_request_date = { -# "$schema": "http://json-schema.org/draft-07/schema#", -# "type": "object", -# "additionalProperties": False, -# "required": [], -# "properties": {} -# } +raw_request_date = { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": False, + "required": [], + "properties": {} +} -# # Process all files in the input folder -# for root, _, files in os.walk(os.path.join(input_folder, "schemas")): -# # Group request and schema files with the same name -# grouped_files = [] -# for file in files: -# if file.endswith(".schema.json"): -# base_name = file[:-12] -# if base_name not in grouped_files: -# grouped_files.append(base_name) - -grouped_files = [ - "close", - "commando", - "datastore", - "datastoreusage", - "decodepay", - "decode", - "deldatastore", - "delexpiredinvoice", - "delforward", - "delinvoice", - "delpay", - "disableinvoicerequest", - "disableoffer", - "disconnect", - "emergencyrecover", - # "feerates", - # "fetchinvoice", - # "fundchannel", - # "fundchannel_start", - # "fundchannel_complete", - # "fundchannel_cancel", - # "funderupdate", - # "addpsbtoutput", - # "fundpsbt", - # "getroute", - # "hsmtool.8", - # "invoice", - # "invoicerequest", - # "keysend", - # "listchannels", - # "listclosedchannels", - # "listdatastore", - # "listforwards", - # "listfunds", - # "listhtlcs", - # "listinvoices", - # "listinvoicerequests", - # "listoffers", - # "listpays", - # "listpeers", - # "listpeerchannels", - # "showrunes", - # "listsendpays", - # "makesecret", - # "multifundchannel", - # "multiwithdraw", - # "newaddr", - # "notifications", - # "offer", - # "openchannel_abort", - # "openchannel_bump", - # "openchannel_init", - # "openchannel_signed", - # "openchannel_update", - # "pay", - # "parsefeerate", - # "plugin", - # "preapproveinvoice", - # "preapprovekeysend", - # "recover", - # "recoverchannel", - # "renepay", - # "renepaystatus", - # "reserveinputs", - # "sendinvoice", - # "sendonion", - # "sendonionmessage", - # "sendpay", - # "setchannel", - # "setconfig", - # "setpsbtversion", - # "sendcustommsg", - # "signinvoice", - # "signmessage", - # "splice_init", - # "splice_update", - # "splice_signed", - # "staticbackup", - # "txprepare", - # "txdiscard", - # "txsend", - # "unreserveinputs", - # "utxopsbt", - # "wait", - # "waitinvoice", - # "waitanyinvoice", - # "waitblockheight", - # "waitsendpay", - # "withdraw", - # "ping", - # "stop", - # "signpsbt", - # "sendpsbt", - # "getinfo", - # "listtransactions", - # "listnodes", - # "listconfigs", - # "help", - # "getlog", - # "reckless.7" -] +# Process all files in the input folder +for root, _, files in os.walk(os.path.join(input_folder, "schemas")): + # Group request and schema files with the same name + grouped_files = [] + for file in files: + if file.endswith(".schema.json"): + base_name = file[:-12] + if base_name not in grouped_files: + grouped_files.append(base_name) # Merge and create new JSON files for base_name in grouped_files: @@ -142,6 +39,7 @@ with open(input_folder + "schemas/" + base_name + ".request.json", "r") as request_file, \ open(input_folder + "schemas/" + base_name + ".schema.json", "r") as response_file, \ open(input_folder + "lightning-" + base_name + ".7.md", "r") as md_file: + print(f"Merging base file: {base_name}") request_json = json.load(request_file) response_json = json.load(response_file) merged_json = {}