diff --git a/doc/Makefile b/doc/Makefile index 3a26050d30b5..c0f21bdb9a3f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,80 +4,133 @@ doc-wrongdir: $(MAKE) -C .. doc-all -MANPAGES := doc/lightning-cli.1 \ - doc/lightningd.8 \ - doc/lightningd-config.5 \ - doc/lightningd-rpc.7 \ - doc/lightning-addgossip.7 \ - doc/lightning-autoclean-once.7 \ - doc/lightning-autoclean-status.7 \ - doc/lightning-batching.7 \ - doc/lightning-bkpr-channelsapy.7 \ - doc/lightning-bkpr-dumpincomecsv.7 \ - doc/lightning-bkpr-inspect.7 \ - doc/lightning-bkpr-listaccountevents.7 \ - doc/lightning-bkpr-listbalances.7 \ - doc/lightning-bkpr-listincome.7 \ - doc/lightning-blacklistrune.7 \ - doc/lightning-check.7 \ - doc/lightning-checkmessage.7 \ - doc/lightning-checkrune.7 \ - doc/lightning-close.7 \ - doc/lightning-connect.7 \ - doc/lightning-commando.7 \ - doc/lightning-commando-blacklist.7 \ - doc/lightning-commando-listrunes.7 \ - doc/lightning-commando-rune.7 \ - doc/lightning-createonion.7 \ - doc/lightning-createinvoice.7 \ - doc/lightning-createrune.7 \ - doc/lightning-datastore.7 \ - doc/lightning-datastoreusage.7 \ - doc/lightning-decodepay.7 \ - doc/lightning-decode.7 \ - doc/lightning-deldatastore.7 \ - doc/lightning-delexpiredinvoice.7 \ - doc/lightning-delforward.7 \ - doc/lightning-delinvoice.7 \ - doc/lightning-delpay.7 \ - doc/lightning-disableinvoicerequest.7 \ - doc/lightning-disableoffer.7 \ - doc/lightning-disconnect.7 \ - doc/lightning-emergencyrecover.7 \ - doc/lightning-feerates.7 \ - doc/lightning-fetchinvoice.7 \ - doc/lightning-fundchannel.7 \ - doc/lightning-fundchannel_start.7 \ - doc/lightning-fundchannel_complete.7 \ - doc/lightning-fundchannel_cancel.7 \ - doc/lightning-funderupdate.7 \ - doc/lightning-addpsbtoutput.7 \ - doc/lightning-fundpsbt.7 \ - doc/lightning-getroute.7 \ - doc/lightning-hsmtool.8 \ - doc/lightning-invoice.7 \ - doc/lightning-invoicerequest.7 \ - doc/lightning-keysend.7 \ - doc/lightning-listchannels.7 \ - doc/lightning-listclosedchannels.7 \ - doc/lightning-listdatastore.7 \ - doc/lightning-listforwards.7 \ - doc/lightning-listfunds.7 \ - doc/lightning-listhtlcs.7 \ - doc/lightning-listinvoices.7 \ - doc/lightning-listinvoicerequests.7 \ - doc/lightning-listoffers.7 \ - doc/lightning-listpays.7 \ - doc/lightning-listpeers.7 \ - doc/lightning-listpeerchannels.7 \ - doc/lightning-showrunes.7 \ - doc/lightning-listsendpays.7 \ - doc/lightning-makesecret.7 \ - doc/lightning-multifundchannel.7 \ - doc/lightning-multiwithdraw.7 \ - doc/lightning-newaddr.7 \ - doc/lightning-notifications.7 \ - doc/lightning-offer.7 \ +# MANPAGES := doc/lightning-cli.1 \ +# doc/lightningd.8 \ +# doc/lightningd-config.5 \ +# doc/lightningd-rpc.7 \ +# doc/lightning-addgossip.7 \ +# doc/lightning-autoclean-once.7 \ +# doc/lightning-autoclean-status.7 \ +# doc/lightning-batching.7 \ +# doc/lightning-bkpr-channelsapy.7 \ +# doc/lightning-bkpr-dumpincomecsv.7 \ +# doc/lightning-bkpr-inspect.7 \ +# doc/lightning-bkpr-listaccountevents.7 \ +# doc/lightning-bkpr-listbalances.7 \ +# doc/lightning-bkpr-listincome.7 \ +# doc/lightning-blacklistrune.7 \ +# doc/lightning-check.7 \ +# doc/lightning-checkmessage.7 \ +# doc/lightning-checkrune.7 \ +# doc/lightning-close.7 \ +# doc/lightning-connect.7 \ +# doc/lightning-commando.7 \ +# doc/lightning-commando-blacklist.7 \ +# doc/lightning-commando-listrunes.7 \ +# doc/lightning-commando-rune.7 \ +# doc/lightning-createonion.7 \ +# doc/lightning-createinvoice.7 \ +# doc/lightning-createrune.7 \ +# doc/lightning-datastore.7 \ +# doc/lightning-datastoreusage.7 \ +# doc/lightning-decodepay.7 \ +# doc/lightning-decode.7 \ +# doc/lightning-deldatastore.7 \ +# doc/lightning-delexpiredinvoice.7 \ +# doc/lightning-delforward.7 \ +# doc/lightning-delinvoice.7 \ +# doc/lightning-delpay.7 \ +# doc/lightning-disableinvoicerequest.7 \ +# doc/lightning-disableoffer.7 \ +# doc/lightning-disconnect.7 \ +# doc/lightning-emergencyrecover.7 \ +# doc/lightning-feerates.7 \ +# doc/lightning-fetchinvoice.7 \ +# doc/lightning-fundchannel.7 \ +# doc/lightning-fundchannel_start.7 \ +# doc/lightning-fundchannel_complete.7 \ +# doc/lightning-fundchannel_cancel.7 \ +# doc/lightning-funderupdate.7 \ +# doc/lightning-addpsbtoutput.7 \ +# doc/lightning-fundpsbt.7 \ +# doc/lightning-getroute.7 \ +# doc/lightning-hsmtool.8 \ +# doc/lightning-invoice.7 \ +# doc/lightning-invoicerequest.7 \ +# doc/lightning-keysend.7 \ +# doc/lightning-listchannels.7 \ +# doc/lightning-listclosedchannels.7 \ +# doc/lightning-listdatastore.7 \ +# doc/lightning-listforwards.7 \ +# doc/lightning-listfunds.7 \ +# doc/lightning-listhtlcs.7 \ +# doc/lightning-listinvoices.7 \ +# doc/lightning-listinvoicerequests.7 \ +# doc/lightning-listoffers.7 \ +# doc/lightning-listpays.7 \ +# doc/lightning-listpeers.7 \ +# doc/lightning-listpeerchannels.7 \ +# doc/lightning-showrunes.7 \ +# doc/lightning-listsendpays.7 \ +# doc/lightning-makesecret.7 \ +# doc/lightning-multifundchannel.7 \ +# doc/lightning-multiwithdraw.7 \ +# doc/lightning-newaddr.7 \ +# doc/lightning-notifications.7 \ +# doc/lightning-offer.7 \ +# doc/lightning-openchannel_abort.7 \ +# doc/lightning-openchannel_bump.7 \ +# doc/lightning-openchannel_init.7 \ +# doc/lightning-openchannel_signed.7 \ +# doc/lightning-openchannel_update.7 \ +# doc/lightning-pay.7 \ +# doc/lightning-parsefeerate.7 \ +# doc/lightning-plugin.7 \ +# doc/lightning-preapproveinvoice.7 \ +# doc/lightning-preapprovekeysend.7 \ +# doc/lightning-recover.7 \ +# doc/lightning-recoverchannel.7 \ +# doc/lightning-renepay.7 \ +# doc/lightning-renepaystatus.7 \ +# doc/lightning-reserveinputs.7 \ +# doc/lightning-sendinvoice.7 \ +# doc/lightning-sendonion.7 \ +# doc/lightning-sendonionmessage.7 \ +# doc/lightning-sendpay.7 \ +# doc/lightning-setchannel.7 \ +# doc/lightning-setconfig.7 \ +# doc/lightning-setpsbtversion.7 \ +# doc/lightning-sendcustommsg.7 \ +# doc/lightning-signinvoice.7 \ +# doc/lightning-signmessage.7 \ +# doc/lightning-splice_init.7 \ +# doc/lightning-splice_update.7 \ +# doc/lightning-splice_signed.7 \ +# doc/lightning-staticbackup.7 \ +# doc/lightning-txprepare.7 \ +# doc/lightning-txdiscard.7 \ +# doc/lightning-txsend.7 \ +# doc/lightning-unreserveinputs.7 \ +# doc/lightning-utxopsbt.7 \ +# doc/lightning-wait.7 \ +# doc/lightning-waitinvoice.7 \ +# doc/lightning-waitanyinvoice.7 \ +# doc/lightning-waitblockheight.7 \ +# doc/lightning-waitsendpay.7 \ +# doc/lightning-withdraw.7 \ +# doc/lightning-ping.7 \ +# doc/lightning-stop.7 \ +# doc/lightning-signpsbt.7 \ +# doc/lightning-sendpsbt.7 \ +# doc/lightning-getinfo.7 \ +# doc/lightning-listtransactions.7 \ +# doc/lightning-listnodes.7 \ +# doc/lightning-listconfigs.7 \ +# doc/lightning-help.7 \ +# doc/lightning-getlog.7 \ +# doc/reckless.7 + +MANPAGES := doc/lightning-offer.7 \ doc/lightning-openchannel_abort.7 \ doc/lightning-openchannel_bump.7 \ doc/lightning-openchannel_init.7 \ @@ -93,51 +146,16 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-renepay.7 \ doc/lightning-renepaystatus.7 \ doc/lightning-reserveinputs.7 \ - doc/lightning-sendinvoice.7 \ - doc/lightning-sendonion.7 \ - doc/lightning-sendonionmessage.7 \ - doc/lightning-sendpay.7 \ - doc/lightning-setchannel.7 \ - doc/lightning-setconfig.7 \ - doc/lightning-setpsbtversion.7 \ - doc/lightning-sendcustommsg.7 \ - doc/lightning-signinvoice.7 \ - doc/lightning-signmessage.7 \ - doc/lightning-splice_init.7 \ - doc/lightning-splice_update.7 \ - doc/lightning-splice_signed.7 \ - doc/lightning-staticbackup.7 \ - doc/lightning-txprepare.7 \ - doc/lightning-txdiscard.7 \ - doc/lightning-txsend.7 \ - doc/lightning-unreserveinputs.7 \ - doc/lightning-utxopsbt.7 \ - doc/lightning-wait.7 \ - doc/lightning-waitinvoice.7 \ - doc/lightning-waitanyinvoice.7 \ - doc/lightning-waitblockheight.7 \ - doc/lightning-waitsendpay.7 \ - doc/lightning-withdraw.7 \ - doc/lightning-ping.7 \ - doc/lightning-stop.7 \ - doc/lightning-signpsbt.7 \ - doc/lightning-sendpsbt.7 \ - doc/lightning-getinfo.7 \ - doc/lightning-listtransactions.7 \ - doc/lightning-listnodes.7 \ - doc/lightning-listconfigs.7 \ - doc/lightning-help.7 \ - doc/lightning-getlog.7 \ - doc/reckless.7 - -ifeq ($(HAVE_SQLITE3),1) -MANPAGES += doc/lightning-listsqlschemas.7 \ - doc/lightning-sql.7 -endif + + +# ifeq ($(HAVE_SQLITE3),1) +# MANPAGES += doc/lightning-listsqlschemas.7 \ +# doc/lightning-sql.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 +174,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-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..9d76820aa962 100644 --- a/doc/lightning-pay.7.md +++ b/doc/lightning-pay.7.md @@ -114,6 +114,9 @@ The following warnings may also be returned: You can monitor the progress and retries of a payment using the lightning-paystatus(7) command. +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-renepay.7.md b/doc/lightning-renepay.7.md index 6f9832af911c..3c5f3594512a 100644 --- a/doc/lightning-renepay.7.md +++ b/doc/lightning-renepay.7.md @@ -91,6 +91,9 @@ On success, an object is returned, containing: You can monitor the progress and retries of a payment using the lightning-renepaystatus(7) command. +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md index 033e6f45b8fe..e125c79bbbd9 100644 --- a/doc/lightning-sendinvoice.7.md +++ b/doc/lightning-sendinvoice.7.md @@ -43,6 +43,9 @@ If **status** is "paid": [comment]: # (GENERATE-FROM-SCHEMA-END) +ERRORS +------ + The following error codes may occur: - -1: Catchall nonspecific error. diff --git a/doc/lightning-txdiscard.7.md b/doc/lightning-txdiscard.7.md index a16c2be578a9..d24603c05ea6 100644 --- a/doc/lightning-txdiscard.7.md +++ b/doc/lightning-txdiscard.7.md @@ -27,6 +27,9 @@ If there is no matching *txid*, an error is reported. Note that this may happen due to incorrect usage, such as **txdiscard** or **txsend** already being called for *txid*. +ERRORS +------ + The following error codes may occur: - -1: An unknown *txid*. diff --git a/doc/schemas/decodepay.request.json b/doc/schemas/decodepay.request.json index d4e5ae4d31d7..d89d88afe009 100644 --- a/doc/schemas/decodepay.request.json +++ b/doc/schemas/decodepay.request.json @@ -8,10 +8,12 @@ ], "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice to decode" }, "description": { - "type": "string" + "type": "string", + "description": "description of the invoice to decode" } } } diff --git a/doc/schemas/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/invoice.request.json b/doc/schemas/invoice.request.json index 04430b38a4de..237a123a9f7b 100644 --- a/doc/schemas/invoice.request.json +++ b/doc/schemas/invoice.request.json @@ -10,63 +10,58 @@ "properties": { "amount_msat": { "type": "msat_or_any", - "description": "" + "description": "the string `any`, which creates an invoice that can be paid with any amount. Otherwise it is a positive value in millisatoshi precision; it can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*" }, "label": { - "oneOf": [ - { - "type": "string", - "description": "" - }, - { - "type": "integer", - "description": "" - } - ] + "type": "string", + "description": "a unique string or number (which is treated as a string, so `01` is different from `1`); it is never revealed to other nodes on the lightning network, but it can be used to query the status of this invoice" }, "description": { "type": "string", - "description": "" + "description": "a short description of purpose of payment, e.g. *1 cup of coffee*. This value is encoded into the BOLT11 invoice and is viewable by any node you send this invoice to (unless *deschashonly* is true as described below). It must be UTF-8, and cannot use *\\u* JSON escape codes" }, "expiry": { "type": "u64", - "description": "" + "description": "the time the invoice is valid for, in seconds. If no value is provided the default of 604800 (1 week) is used" }, "fallbacks": { "type": "array", - "description": "", + "description": "one or more fallback addresses to include in the invoice (in order from most-preferred to least): note that these arrays are not currently tracked to fulfill the invoice", "items": { "type": "string" } }, "preimage": { "type": "hex", - "description": "" + "description": "a 64-digit hex string to be used as payment preimage for the created invoice. By default, if unspecified, lightningd will generate a secure pseudorandom preimage seeded from an appropriate entropy source on your system. **IMPORTANT**: if you specify the *preimage*, you are responsible, to ensure appropriate care for generating using a secure pseudorandom generator seeded with sufficient entropy, and keeping the preimage secret. This parameter is an advanced feature intended for use with cutting-edge cryptographic protocols and should not be used unless explicitly needed" }, "exposeprivatechannels": { + "description": "if specified, it overrides the default route hint logic, which will use unpublished channels only if there are no published channels", "oneOf": [ { "type": "boolean", - "description": "" + "description": "if *True* unpublished channels are always considered as a route hint candidate; if *False*, never" }, { "type": "array", + "description": "array of short channel ids (or a remote alias), only those specific channels will be considered candidates, even if they are public or dead-ends", "items": { "type": "short_channel_id" } }, { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "if it is a short channel id (e.g. *1x1x3*), only this specific channel will be considered candidate, even if it is public or dead-end" } ] }, "cltv": { "type": "u32", - "description": "" + "description": "if specified, sets the *min_final_cltv_expiry* for the invoice. Otherwise, it's set to the parameter **cltv-final**" }, "deschashonly": { "type": "boolean", - "description": "" + "description": "if True, then the bolt11 returned contains a hash of the *description*, rather than the *description* itself: this allows much longer descriptions, but they must be communicated via some other mechanism. Defaults to False" } } } diff --git a/doc/schemas/invoicerequest.request.json b/doc/schemas/invoicerequest.request.json index e94b190ba40a..7cb8ebfccb8d 100644 --- a/doc/schemas/invoicerequest.request.json +++ b/doc/schemas/invoicerequest.request.json @@ -10,27 +10,27 @@ "properties": { "amount": { "type": "msat", - "description": "" + "description": "a positive value in millisatoshi precision; it can be a whole number, or a whole number ending in *msat* or *sat*, or a number with three decimal places ending in *sat*, or a number with 1 to 11 decimal places ending in *btc*" }, "description": { "type": "string", - "description": "" + "description": "a short description of purpose of the payment, e.g. *ATM withdrawl*. This value is encoded into the resulting `invoice_request` and is viewable by anyone you expose it to. It must be UTF-8, and cannot use *\\u* JSON escape codes" }, "issuer": { "type": "string", - "description": "" + "description": "who is issuing it (i.e. you) if appropriate" }, "label": { "type": "string", - "description": "" + "description": "an internal-use name for the offer, which can be any UTF-8 string" }, "absolute_expiry": { "type": "u64", - "description": "" + "description": "the time the offer is valid until, in seconds since the first day of 1970 UTC. If not set, the `invoice_request` remains valid (though it can be deactivated by the issuer of course). This is encoded in the `invoice_request`" }, "single_use": { "type": "boolean", - "description": "" + "description": "indicates that the `invoice_request` is only valid once; we may attempt multiple payments, but as soon as one is successful no more invoices are accepted (i.e. only one person can take the money). Defaults to True" } } } diff --git a/doc/schemas/keysend.request.json b/doc/schemas/keysend.request.json index 64e74e73c7b7..66f37cb4b42c 100644 --- a/doc/schemas/keysend.request.json +++ b/doc/schemas/keysend.request.json @@ -8,25 +8,32 @@ ], "properties": { "destination": { - "type": "pubkey" + "type": "pubkey", + "description": "the 33 byte, hex-encoded, node ID of the node that the payment should go to" }, "amount_msat": { - "type": "msat" + "type": "msat", + "description": "a whole number, or a whole number with suffix `msat` or `sat`, or a three decimal point number with suffix `sat`, or an 1 to 11 decimal point number suffixed by `btc`" }, "label": { - "type": "string" + "type": "string", + "description": "used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)" }, "maxfeepercent": { - "type": "number" + "type": "number", + "description": "limits the money paid in fees as percentage of the total amount that is to be transferred, and defaults to *0.5*" }, "retry_for": { - "type": "u32" + "type": "u32", + "description": "until *retry_for* seconds passes, the command will keep finding routes and retrying the payment. However, a payment may be delayed for up to `maxdelay` blocks by another node; clients should be prepared for this worst case. Defaults to 60 seconds" }, "maxdelay": { - "type": "u32" + "type": "u32", + "description": "number of blocks the payment may be delayed" }, "exemptfee": { - "type": "msat" + "type": "msat", + "description": "used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Setting `exemptfee` allows the `maxfeepercent` check to be skipped on fees that are smaller than *exemptfee*. Defaults to 5000 millisatoshi" }, "routehints": { "type": "array", @@ -65,7 +72,8 @@ "extratlvs": { "type": "object", "additionalProperties": true, - "required": [] + "required": [], + "description": "dictionary of additional fields to insert into the final tlv. The format is 'fieldnumber': 'hexstring'" } } } diff --git a/doc/schemas/listchannels.request.json b/doc/schemas/listchannels.request.json index 80c7344900ee..2779b0298de4 100644 --- a/doc/schemas/listchannels.request.json +++ b/doc/schemas/listchannels.request.json @@ -6,15 +6,15 @@ "properties": { "short_channel_id": { "type": "short_channel_id", - "description": "If short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null." + "description": "if short_channel_id is a short channel id, then only known channels with a matching short_channel_id are returned. Otherwise, it must be null" }, "source": { "type": "pubkey", - "description": "If source is a node id, then only channels leading from that node id are returned." + "description": "if source is a node id, then only channels leading from that node id are returned" }, "destination": { "type": "pubkey", - "description": "If destination is a node id, then only channels leading to that node id are returned." + "description": "if destination is a node id, then only channels leading to that node id are returned" } } } diff --git a/doc/schemas/listclosedchannels.request.json b/doc/schemas/listclosedchannels.request.json index 2726913be3d1..eb11e66565ad 100644 --- a/doc/schemas/listclosedchannels.request.json +++ b/doc/schemas/listclosedchannels.request.json @@ -7,7 +7,7 @@ "properties": { "id": { "type": "pubkey", - "description": "If supplied, limits the channels to just the peer with the given ID, if it exists." + "description": "if no *id* is supplied, then channel data on all historical channels are given. Supplying *id* will filter the results to only match channels to that peer. Note that prior to v23.05, old peers were forgotten" } } } diff --git a/doc/schemas/listdatastore.request.json b/doc/schemas/listdatastore.request.json index fc817532724f..906fa7f6af1b 100644 --- a/doc/schemas/listdatastore.request.json +++ b/doc/schemas/listdatastore.request.json @@ -5,17 +5,18 @@ "required": [], "properties": { "key": { + "description": "a *key* with children won't have a *hex* or *generation* entry. All immediate children of the *key* (or root children) are returned", "oneOf": [ { "type": "array", - "description": "key is an array of values (though a single value is treated as a one-element array), to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically.", + "description": "an array of values, to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically", "items": { "type": "string" } }, { "type": "string", - "description": "" + "description": "a single value is treated as a one-element array, to form a heirarchy. Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended. A key can either have children or a value, never both: parents are created and removed automatically." } ] } diff --git a/doc/schemas/listforwards.request.json b/doc/schemas/listforwards.request.json index b5e9e6fa89d0..22c91902d2dc 100644 --- a/doc/schemas/listforwards.request.json +++ b/doc/schemas/listforwards.request.json @@ -5,6 +5,7 @@ "properties": { "status": { "type": "string", + "description": "if specified, then only the forwards with the given status are returned", "enum": [ "offered", "settled", @@ -13,10 +14,12 @@ ] }, "in_channel": { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "only the matching forwards on the given inbound channel are returned" }, "out_channel": { - "type": "short_channel_id" + "type": "short_channel_id", + "description": "only the matching forwards on the given outbount channel are returned" }, "index": { "type": "string", @@ -25,17 +28,17 @@ "created", "updated" ], - "description": "" + "description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`" }, "start": { "type": "u64", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/listfunds.request.json b/doc/schemas/listfunds.request.json index 00faf6c658e8..cef1bb3128ee 100644 --- a/doc/schemas/listfunds.request.json +++ b/doc/schemas/listfunds.request.json @@ -6,7 +6,7 @@ "properties": { "spent": { "type": "boolean", - "description": "Should outputs that are already spent be included in the result?" + "description": "if True, then the *outputs* will include spent outputs in addition to the unspent ones. Default is False" } } } diff --git a/doc/schemas/listhtlcs.request.json b/doc/schemas/listhtlcs.request.json index df03123299a8..764e3dbc064e 100644 --- a/doc/schemas/listhtlcs.request.json +++ b/doc/schemas/listhtlcs.request.json @@ -5,7 +5,7 @@ "properties": { "id": { "type": "string", - "description": "channel id or short_channel_id" + "description": "a short channel id (e.g. 1x2x3) or full 64-byte hex channel id, it will only list htlcs for that channel (which must be known)" } } } diff --git a/doc/schemas/listinvoicerequests.request.json b/doc/schemas/listinvoicerequests.request.json index 01104b40a18f..2b22dace5708 100644 --- a/doc/schemas/listinvoicerequests.request.json +++ b/doc/schemas/listinvoicerequests.request.json @@ -7,11 +7,11 @@ "properties": { "invreq_id": { "type": "string", - "description": "" + "description": "a specific invoice can be queried by providing the `invreq_id`, which is presented by lightning-invoicerequest(7), or can be calculated from a bolt12 invoice" }, "active_only": { "type": "boolean", - "description": "" + "description": "if it is *True* then only active invoice requests are returned. Default is *False*" } } } diff --git a/doc/schemas/listinvoices.request.json b/doc/schemas/listinvoices.request.json index f40710fa7490..6f91f173f188 100644 --- a/doc/schemas/listinvoices.request.json +++ b/doc/schemas/listinvoices.request.json @@ -5,28 +5,29 @@ "required": [], "properties": { "label": { + "description": "a label used a the creation of the invoice to get a specific invoice", "oneOf": [ { "type": "string", - "description": "" + "description": "a text label to search for" }, { "type": "integer", - "description": "" + "description": "a numeric label to search for" } ] }, "invstring": { "type": "string", - "description": "" + "description": "a invoice string representing the invoice to query a specific invoice" }, "payment_hash": { "type": "hex", - "description": "" + "description": "a payment_hash of the invoice to get the details of a specific invoice" }, "offer_id": { "type": "string", - "description": "" + "description": "a local `offer_id` the invoice was issued for a specific invoice details" }, "index": { "type": "string", @@ -35,17 +36,17 @@ "created", "updated" ], - "description": "" + "description": "if neither *in_channel* nor *out_channel* is specified, it controls ordering. Defaults to `created`" }, "start": { "type": "u64", - "added": "v23.08", - "description": "" + "added": "v23.11", + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", - "added": "v23.08", - "description": "" + "added": "v23.11", + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/listpays.request.json b/doc/schemas/listpays.request.json index f313c861388b..50cdac247831 100644 --- a/doc/schemas/listpays.request.json +++ b/doc/schemas/listpays.request.json @@ -5,13 +5,16 @@ "additionalProperties": false, "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 string to get the payment details" }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "payment hash to get the payment details" }, "status": { "type": "string", + "description": "to filter the payment by status", "enum": [ "pending", "complete", diff --git a/doc/schemas/listpeers.request.json b/doc/schemas/listpeers.request.json index f2b02304acd3..01f5bbe453cb 100644 --- a/doc/schemas/listpeers.request.json +++ b/doc/schemas/listpeers.request.json @@ -6,11 +6,17 @@ "properties": { "id": { "type": "pubkey", - "description": "If supplied, limits the result to just the peer with the given ID, if it exists." + "description": "if supplied, limits the result to just the peer with the given ID, if it exists" }, "level": { "type": "string", - "description": "Supplying level will show log entries related to that peer at the given log level. Valid log levels are “io”, “debug”, “info”, and “unusual”." + "description": "supplying level will show log entries related to that peer at the given log level", + "enum": [ + "io", + "debug", + "info", + "unusual" + ] } } } diff --git a/doc/schemas/listsendpays.request.json b/doc/schemas/listsendpays.request.json index a498bbc697ad..701f6a76efd9 100644 --- a/doc/schemas/listsendpays.request.json +++ b/doc/schemas/listsendpays.request.json @@ -5,10 +5,12 @@ "additionalProperties": false, "properties": { "bolt11": { - "type": "string" + "type": "string", + "description": "bolt11 invoice" }, "payment_hash": { - "type": "hash" + "type": "hash", + "description": "the hash of the payment_preimage" }, "status": { "type": "string", @@ -16,7 +18,8 @@ "pending", "complete", "failed" - ] + ], + "description": "Whether the invoice has been paid, pending, or failed" }, "index": { "type": "string", @@ -25,17 +28,17 @@ "created", "updated" ], - "description": "" + "description": "if neither bolt11 or payment_hash is specified, `index` controls ordering, by `created` (default) or `updated`" }, "start": { "type": "u64", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `start` may be specified to start from that value, which is generally returned from lightning-wait(7)" }, "limit": { "type": "u32", "added": "v23.11", - "description": "" + "description": "if `index` is specified, `limit` can be used to specify the maximum number of entries to return" } } } diff --git a/doc/schemas/makesecret.request.json b/doc/schemas/makesecret.request.json index 5059babd01d5..54d6fef91d11 100644 --- a/doc/schemas/makesecret.request.json +++ b/doc/schemas/makesecret.request.json @@ -6,11 +6,11 @@ "properties": { "hex": { "type": "hex", - "description": "This will be used for deriving the secret" + "description": "One of `hex` or `string` must be specified: `hex` can be any hex data" }, "string": { "type": "string", - "description": "This will be used for deriving the secret" + "description": "One of `hex` or `string` must be specified: `string` is a UTF-8 string interpreted literally" } } } diff --git a/doc/schemas/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/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/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/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..59d7b68558c2 100644 --- a/tools/merge.py +++ b/tools/merge.py @@ -23,70 +23,22 @@ # 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", + "offer", + "openchannel_abort", + "openchannel_bump", + "openchannel_init", + "openchannel_signed", + "openchannel_update", + "pay", + "parsefeerate", + "plugin", + "preapproveinvoice", + "preapprovekeysend", + "recover", + "recoverchannel", + "renepay", + "renepaystatus", + "reserveinputs", # "sendinvoice", # "sendonion", # "sendonionmessage", @@ -122,7 +74,7 @@ # "listconfigs", # "help", # "getlog", - # "reckless.7" + # "reckless" ] # Merge and create new JSON files @@ -142,6 +94,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 = {}