diff --git a/doc/lightning-autoclean-once.7.md b/doc/lightning-autoclean-once.7.md index b3e1e8445ad7..64ba3948592d 100644 --- a/doc/lightning-autoclean-once.7.md +++ b/doc/lightning-autoclean-once.7.md @@ -23,8 +23,6 @@ The *subsystem*s currently supported are: * `expiredinvoices`: invoices which were not paid (and cannot be) (`expired` in listinvoices `status`). * `paidinvoices`: invoices which were paid (`paid` in listinvoices `status). -*age* is a non-zero number in seconds. - RETURN VALUE ------------ diff --git a/doc/lightning-batching.7.md b/doc/lightning-batching.7.md index 2cfba5eaaba0..9fdf12ba64a1 100644 --- a/doc/lightning-batching.7.md +++ b/doc/lightning-batching.7.md @@ -16,9 +16,6 @@ which case it can offer a performance improvement (the cost being that if there is a crash, it's unclear how many of the commands will have been persisted). -*enable* is *true* to enable batching, *false* to disable it (the -default). - EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-disableinvoicerequest.7.md b/doc/lightning-disableinvoicerequest.7.md index 24aa2860de63..639bf946e935 100644 --- a/doc/lightning-disableinvoicerequest.7.md +++ b/doc/lightning-disableinvoicerequest.7.md @@ -4,13 +4,13 @@ lightning-disableinvoicerequest -- Command for removing an invoice request SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **disableinvoicerequest** *invreq\_id* DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **disableinvoicerequest** RPC command disables an invoice\_request, so that no further invoices will be accepted (and thus, no further payments made).. diff --git a/doc/lightning-disableoffer.7.md b/doc/lightning-disableoffer.7.md index 7a2e7a973855..b1acf1a39e29 100644 --- a/doc/lightning-disableoffer.7.md +++ b/doc/lightning-disableoffer.7.md @@ -4,13 +4,13 @@ lightning-disableoffer -- Command for removing an offer SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **disableoffer** *offer\_id* DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **disableoffer** RPC command disables an offer, so that no further invoices will be given out. diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md index c9125f4b17df..1dcce81c2257 100644 --- a/doc/lightning-fetchinvoice.7.md +++ b/doc/lightning-fetchinvoice.7.md @@ -4,13 +4,13 @@ lightning-fetchinvoice -- Command for fetch an invoice for an offer SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **fetchinvoice** *offer* [*amount\_msat*] [*quantity*] [*recurrence\_counter*] [*recurrence\_start*] [*recurrence\_label*] [*timeout*] [*payer\_note*] DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **fetchinvoice** RPC command contacts the issuer of an *offer* to get an actual invoice that can be paid. It highlights any changes between the offer and the returned invoice. diff --git a/doc/lightning-fundchannel_cancel.7.md b/doc/lightning-fundchannel_cancel.7.md index 947af2beddc1..0b751e9b99c3 100644 --- a/doc/lightning-fundchannel_cancel.7.md +++ b/doc/lightning-fundchannel_cancel.7.md @@ -12,8 +12,6 @@ DESCRIPTION `fundchannel_cancel` is a lower level RPC command. It allows channel opener to cancel a channel before funding broadcast with a connected peer. -*id* is the node id of the remote peer with which to cancel. - Note that the funding transaction MUST NOT be broadcast before `fundchannel_cancel`. Broadcasting transaction before `fundchannel_cancel` WILL lead to unrecoverable loss of funds. diff --git a/doc/lightning-fundchannel_complete.7.md b/doc/lightning-fundchannel_complete.7.md index 723e2014b03d..1e62a2f7d8ae 100644 --- a/doc/lightning-fundchannel_complete.7.md +++ b/doc/lightning-fundchannel_complete.7.md @@ -12,11 +12,6 @@ DESCRIPTION `fundchannel_complete` is a lower level RPC command. It allows a user to complete an initiated channel establishment with a connected peer. -*id* is the node id of the remote peer. - -*psbt* is the transaction to use for funding (does not need to be -signed but must be otherwise complete). - Note that the funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed, as the commitment transactions for this channel are not secured until this command diff --git a/doc/lightning-fundchannel_start.7.md b/doc/lightning-fundchannel_start.7.md index 451652c95259..30cfaaa6dec6 100644 --- a/doc/lightning-fundchannel_start.7.md +++ b/doc/lightning-fundchannel_start.7.md @@ -12,28 +12,6 @@ DESCRIPTION `fundchannel_start` is a lower level RPC command. It allows a user to initiate channel establishment with a connected peer. -*id* is the node id of the remote peer. - -*amount* is the satoshi value that the channel will be funded at. This -value MUST be accurate, otherwise the negotiated commitment transactions -will not encompass the correct channel value. - -*feerate* is an optional field. Sets the feerate for subsequent -commitment transactions: see **fundchannel**. Note that this is ignored -for channels with *option\_anchors\_zero\_fee\_htlc\_tx* (we always use a low -commitment fee for these). - -*announce* whether or not to announce this channel. - -*close\_to* is a Bitcoin address to which the channel funds should be sent to -on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. -Returns `close_to` set to closing script iff is negotiated. - -*push\_msat* is the amount of millisatoshis to push to the channel peer at -open. Note that this is a gift to the peer -- these satoshis are -added to the initial balance of the peer at channel start and are largely -unrecoverable once pushed. - Note that the funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed by running `fundchannel_complete`, as the commitment transactions for this channel diff --git a/doc/lightning-funderupdate.7.md b/doc/lightning-funderupdate.7.md index d7da56c74677..318d836c3b23 100644 --- a/doc/lightning-funderupdate.7.md +++ b/doc/lightning-funderupdate.7.md @@ -6,19 +6,14 @@ SYNOPSIS **funderupdate** [*policy*] [*policy\_mod*] [*leases\_only*] [*min\_their\_funding\_msat*] [*max\_their\_funding\_msat*] [*per\_channel\_min\_msat*] [*per\_channel\_max\_msat*] [*reserve\_tank\_msat*] [*fuzz\_percent*] [*fund\_probability*] [*lease\_fee\_base\_msat*] [*lease\_fee\_basis*] [*funding\_weight*] [*channel\_fee\_max\_base\_msat*] [*channel\_fee\_max\_proportional\_thousandths*] [*compact\_lease*] -NOTE: Must have --experimental-dual-fund enabled for these settings to take effect. - DESCRIPTION ----------- -For channel open requests using +NOTE: Must have --experimental-dual-fund enabled for these settings to take effect. +For channel open requests using dual funding. -*policy*, *policy\_mod* is the policy the funder plugin will use to decide -how much capital to commit to a v2 open channel request. There are three -policy options, detailed below: `match`, `available`, and `fixed`. -The *policy\_mod* is the number or 'modification' to apply to the policy. -Default is (fixed, 0sats). +There are three policy options, detailed below: * `match` -- Contribute *policy\_mod* percent of their requested funds. Valid *policy\_mod* values are 0 to 200. If this is a channel lease @@ -33,39 +28,21 @@ Default is (fixed, 0sats). Note: to maximize channel leases, best policy setting is (match, 100). *leases\_only* will only contribute funds to `option_will_fund` requests -which pay to lease funds. Defaults to false, will fund any v2 open request +which pay to lease funds. It will fund any v2 open request using *policy* even if it's they're not seeking to lease funds. Note that `option_will_fund` commits funds for 4032 blocks (~1mo). Must also set *lease\_fee\_base\_msat*, *lease\_fee\_basis*, *funding\_weight*, *channel\_fee\_max\_base\_msat*, and *channel\_fee\_max\_proportional\_thousandths* to advertise available channel leases. -*min\_their\_funding\_msat* is the minimum funding sats that we require in order -to activate our contribution policy to the v2 open. Defaults to 10k sats. - -*max\_their\_funding\_msat* is the maximum funding sats that we will consider -to activate our contribution policy to the v2 open. Any channel open above this -will not be funded. Defaults to no max (`UINT_MAX`). - -*per\_channel\_min\_msat* is the minimum amount that we will contribute to a -channel open. Defaults to 10k sats. - -*per\_channel\_max\_msat* is the maximum amount that we will contribute to a -channel open. Defaults to no max (`UINT_MAX`). - -*reserve\_tank\_msat* is the amount of sats to leave available in the node wallet. -Defaults to zero sats. - *fuzz\_percent* is a percentage to fuzz the resulting contribution amount by. Valid values are 0 to 100. Note that turning this on with (match, 100) policy will randomly fail `option_will_fund` leases, as most clients expect an exact or greater match of their `requested_funds`. -Defaults to 0% (no fuzz). *fund\_probability* is the percent of v2 channel open requests to apply our policy to. Valid values are integers from 0 (fund 0% of all open requests) to 100 (fund every request). Useful for randomizing opens that receive funds. -Defaults to 100. Setting any of the next 5 options will activate channel leases for this node, and advertise these values via the lightning gossip network. If any one is set, @@ -73,29 +50,28 @@ the other values will be the default. *lease\_fee\_base\_msat* is the flat fee for a channel lease. Node will receive this much extra added to their channel balance, paid by the opening -node. Defaults to 2k sats. Note that the minimum is 1sat. +node. *lease\_fee\_basis* is a basis fee that's calculated as 1/10k of the total requested funds the peer is asking for. Node will receive the total of *lease\_fee\_basis* times requested funds / 10k satoshis added to their channel -balance, paid by the opening node. Default is 0.65% (65 basis points) +balance, paid by the opening node. *funding\_weight* is used to calculate the fee the peer will compensate your node for its contributing inputs to the funding transaction. The total fee is calculated as the `open_channel2`.`funding_feerate_perkw` times this *funding\_weight* divided by 1000. Node will have this funding fee added -to their channel balance, paid by the opening node. Default is -2 inputs + 1 P2WPKH output. +to their channel balance, paid by the opening node. *channel\_fee\_max\_base\_msat* is a commitment to a maximum `channel_fee_base_msat` that your node will charge for routing payments -over this leased channel during the lease duration. Default is 5k sats. +over this leased channel during the lease duration. *channel\_fee\_max\_proportional\_thousandths* is a commitment to a maximum `channel_fee_proportional_millionths` that your node will charge for routing payments over this leased channel during the lease duration. Note that it's denominated in 'thousandths'. A setting of `1` is equal -to 1k ppm; `5` is 5k ppm, etc. Default is 100 (100k ppm). +to 1k ppm; `5` is 5k ppm, etc. *compact\_lease* is a compact description of the channel lease params. When opening a channel, passed in to `fundchannel` to indicate the terms we @@ -141,7 +117,6 @@ SEE ALSO lightning-fundchannel(7), lightning-listfunds(7) - RESOURCES --------- diff --git a/doc/lightning-getlog.7.md b/doc/lightning-getlog.7.md index 811ce5555980..a0600b033201 100644 --- a/doc/lightning-getlog.7.md +++ b/doc/lightning-getlog.7.md @@ -11,8 +11,6 @@ DESCRIPTION The **getlog** the RPC command to show logs, with optional log *level*. -- *level*: A string that represents the log level (*broken*, *unusual*, *info*, *debug*, or *io*). The default is *info*. - EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-listconfigs.7.md b/doc/lightning-listconfigs.7.md index 117f211ceedb..e80d8790da29 100644 --- a/doc/lightning-listconfigs.7.md +++ b/doc/lightning-listconfigs.7.md @@ -9,8 +9,6 @@ SYNOPSIS DESCRIPTION ----------- -*config* (optional) is a configuration option name to restrict return. - The **listconfigs** RPC command to list all configuration options, or with *config* only one. The returned values reflect the current configuration, including diff --git a/doc/lightning-listoffers.7.md b/doc/lightning-listoffers.7.md index bb6edfc95e33..be8fdf34b634 100644 --- a/doc/lightning-listoffers.7.md +++ b/doc/lightning-listoffers.7.md @@ -4,16 +4,15 @@ lightning-listoffers -- Command for listing offers SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **listoffers** [*offer\_id*] [*active\_only*] DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **listoffers** RPC command list all offers, or with `offer_id`, -only the offer with that offer\_id (if it exists). If `active_only` is -set and is true, only offers with `active` true are returned. +only the offer with that offer\_id (if it exists). EXAMPLE JSON REQUEST ------------ diff --git a/doc/lightning-multifundchannel.7.md b/doc/lightning-multifundchannel.7.md index e3b479b39133..140127064b0e 100644 --- a/doc/lightning-multifundchannel.7.md +++ b/doc/lightning-multifundchannel.7.md @@ -22,67 +22,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. -*destinations* is an array of objects, with the fields: - -* *id* is the 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*. -* *amount* is the amount in satoshis taken from the internal wallet - to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). - The string *all* can be used to specify all available funds - (or 16,777,215 satoshi if more is available and large channels were - not negotiated with the peer). - 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*. - The value cannot be less than the dust limit, currently 546 satoshi - as of this writing, nor more than 16,777,215 satoshi - (unless large channels were negotiated with the peer). -* *announce* is an optional flag that indicates whether to announce - the channel with this, default `true`. - If set to `false`, the channel is unpublished. -* *push\_msat* is the amount of millisatoshis to outright give to the - node. - This is a gift to the peer, and you do not get a proof-of-payment - out of this. -* *close\_to* is a Bitcoin address to which the channel funds should be sent to - on close. Only valid if both peers have negotiated - `option_upfront_shutdown_script`. Returns `close_to` set to - closing script iff is negotiated. -* *request\_amt* is the amount of liquidity you'd like to lease from peer. - If peer supports `option_will_fund`, indicates to them to include this - much liquidity into the channel. Must also pass in *compact\_lease*. -* *compact\_lease* is a 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. -* *reserve* is the 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*. - -There must be at least one entry in *destinations*; -it cannot be an empty array. - -*feerate* is an optional 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* specifies the minimum number of confirmations that used -outputs should have. Default is 1. - -*utxos* specifies the utxos to be used to fund the channel, as an array -of "txid:vout". - -*minchannels*, if specified, will 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* is the initial feerate for commitment and HTLC -transactions. See *feerate* for valid values. +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 b7cb4f34cc1f..27859a4e5c41 100644 --- a/doc/lightning-multiwithdraw.7.md +++ b/doc/lightning-multiwithdraw.7.md @@ -10,25 +10,7 @@ DESCRIPTION ----------- The **multiwithdraw** RPC command sends funds from Core Lightning's internal -wallet to the addresses specified in *outputs*, -which is an array containing objects of the form `{address: amount}`. -The `amount` may be the string *"all"*, indicating that all onchain funds -be sent to the specified address. -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. +wallet to the addresses specified in *outputs*. RETURN VALUE ------------ diff --git a/doc/lightning-notifications.7.md b/doc/lightning-notifications.7.md index 188e13283111..16b5f4d13c94 100644 --- a/doc/lightning-notifications.7.md +++ b/doc/lightning-notifications.7.md @@ -16,8 +16,6 @@ disabled. Various commands, especially complex and slow ones, offer notifications which indicate their progress. -- *enable*: *true* to enable notifications, *false* to disable them. - EXAMPLE JSON REQUEST -------------------- diff --git a/doc/lightning-offer.7.md b/doc/lightning-offer.7.md index c903b6646e3a..fbdab9e73d93 100644 --- a/doc/lightning-offer.7.md +++ b/doc/lightning-offer.7.md @@ -4,89 +4,20 @@ lightning-offer -- Command for accepting payments SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **offer** *amount* *description* [*issuer*] [*label*] [*quantity\_max*] [*absolute\_expiry*] [*recurrence*] [*recurrence\_base*] [*recurrence\_paywindow*] [*recurrence\_limit*] [*single\_use*] DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **offer** RPC command creates an offer (or returns an existing -one), which is a precursor to creating one or more invoices. It +one), which is a precursor to creating one or more invoices. It automatically enables the processing of an incoming invoice\_request, and issuing of invoices. Note that for making an offer to *pay* someone else, see lightning-invoicerequest(7). -The *amount* parameter can be the string "any", which creates an offer -that can be paid with any amount (e.g. a donation). Otherwise it 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*. - -*amount* can also have an ISO 4217 postfix (i.e. USD), in which case -currency conversion will need to be done for the invoice itself. A -plugin is needed which provides the "currencyconvert" API for this -currency, otherwise the offer creation will fail. - -The *description* is a short description of purpose of the offer, -e.g. *coffee*. This value is encoded into the resulting offer and is -viewable by anyone you expose this offer to. It must be UTF-8, and -cannot use *\\u* JSON escape codes. - -The *issuer* is another (optional) field exposed in the offer, and -reflects who is issuing this offer (i.e. you) if appropriate. - -The *label* field is an internal-use name for the offer, which can -be any UTF-8 string. This is *NOT* encoded in the offer not sent -to the issuer. - -The presence of *quantity\_max* indicates that the -invoice can specify more than one of the items up (and including) -this maximum: 0 is a special value meaning "no maximuim". -The *amount* for the invoice will need to be multiplied -accordingly. This is encoded in the offer. - -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 offer -remains valid (though it can be deactivated by the issuer of course). -This is encoded in the offer. - -*recurrence* means that an invoice is expected at regular intervals. -The argument is a positive number followed by one of "seconds", -"minutes", "hours", "days", "weeks", "months" or "years" (variants -without the trailing "s" are also permitted). This is encoded in the -offer. The semantics of recurrence is fairly predictable, but fully -documented in BOLT 12. e.g. "4weeks". - -*recurrence\_base* is an optional time in seconds since the first day -of 1970 UTC, optionally with a "@" prefix. This indicates when the -first period begins; without this, the recurrence periods start from -the first invoice. The "@" prefix means that the invoice must start -by paying the first period; otherwise it is permitted to start at any -period. This is encoded in the offer. e.g. "@1609459200" indicates -you must start paying on the 1st January 2021. - -*recurrence\_paywindow* is an optional argument of form -'-time+time[%]'. The first time is the number of seconds before the -start of a period in which an invoice and payment is valid, the second -time is the number of seconds after the start of the period. For -example *-604800+86400* means you can fetch an pay the invoice 4 weeks -before the given period starts, and up to 1 day afterwards. The -optional *%* indicates that the amount of the invoice will be scaled -by the time remaining in the period. If this is not specified, the -default is that payment is allowed during the current and previous -periods. This is encoded in the offer. - -*recurrence\_limit* is an optional argument to indicate the maximum -period which exists. eg. "12" means there are 13 periods, from 0 to -12 inclusive. This is encoded in the offer. - -*single\_use* (default false) indicates that the offer is only valid -once; we may issue multiple invoices, but as soon as one is paid all other -invoices will be expired (i.e. only one person can pay this offer). - RETURN VALUE ------------ diff --git a/doc/lightning-openchannel_abort.7.md b/doc/lightning-openchannel_abort.7.md index 930f9b6e60f1..3b9c433b8d19 100644 --- a/doc/lightning-openchannel_abort.7.md +++ b/doc/lightning-openchannel_abort.7.md @@ -13,9 +13,6 @@ DESCRIPTION open with a specified peer. It uses the openchannel protocol which allows for interactive transaction construction. -*channel\_id* is id of this channel. - - RETURN VALUE ------------ diff --git a/doc/lightning-openchannel_bump.7.md b/doc/lightning-openchannel_bump.7.md index 2b313da82683..e39517b89b48 100644 --- a/doc/lightning-openchannel_bump.7.md +++ b/doc/lightning-openchannel_bump.7.md @@ -13,23 +13,6 @@ DESCRIPTION RBF (Replace-By-Fee) for the specified channel. It uses the openchannel protocol which allows for interactive transaction construction. -*id* is the id of the channel to RBF. - -*amount* is the satoshi value that we will contribute to the channel. -This value will be _added_ to the provided PSBT in the output which is -encumbered by the 2-of-2 script for this channel. - -*initialpsbt* is the funded, incomplete PSBT that specifies the UTXOs and -change output for our channel contribution. It can be updated, -see `openchannel_update`; *initialpsbt* must have at least one input. -Must have the Non-Witness UTXO (PSBT\_IN\_NON\_WITNESS\_UTXO) set for -every input. An error (code 309) will be returned if this requirement -is not met. - -*funding\_feerate* is an optional field. Sets the feerate for the -funding transaction. Defaults to 1/64th greater than the last -feerate used for this channel. - Warning: bumping a leased channel will lose the lease. RETURN VALUE diff --git a/doc/lightning-openchannel_init.7.md b/doc/lightning-openchannel_init.7.md index 16a4c6101527..2b24926bbd5e 100644 --- a/doc/lightning-openchannel_init.7.md +++ b/doc/lightning-openchannel_init.7.md @@ -13,41 +13,6 @@ DESCRIPTION open with a specified peer. It uses the openchannel protocol which allows for interactive transaction construction. -*id* is the node id of the remote peer. - -*amount* is the satoshi value that we will contribute to the channel. -This value will be _added_ to the provided PSBT in the output which is -encumbered by the 2-of-2 script for this channel. - -*initialpsbt* is the funded, incomplete PSBT that specifies the UTXOs and -change output for our channel contribution. It can be updated, -see `openchannel_update`; *initialpsbt* must have at least one input. -Must have the Non-Witness UTXO (PSBT\_IN\_NON\_WITNESS\_UTXO) set for -every input. An error (code 309) will be returned if this requirement -is not met. - -*commitment\_feerate* is an optional field. Sets the feerate for -commitment transactions for non-anchor channels: see **fundchannel**. -For anchor channels, it is ignored. - -*funding\_feerate* is an optional field. Sets the feerate for the -funding transaction. Defaults to 'opening' feerate. - -*announce* is an optional field. Whether or not to announce this channel. - -*close\_to* is a Bitcoin address to which the channel funds should be -sent on close. Only valid if both peers have negotiated -`option_upfront_shutdown_script`. - -*request\_amt* is an amount of liquidity you'd like to lease from the peer. -If peer supports `option_will_fund`, indicates to them to include this -much liquidity into the channel. Must also pass in *compact\_lease*. - -*compact\_lease* is a 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. - - RETURN VALUE ------------ diff --git a/doc/lightning-openchannel_signed.7.md b/doc/lightning-openchannel_signed.7.md index 33eb42175d6d..29042d5810ff 100644 --- a/doc/lightning-openchannel_signed.7.md +++ b/doc/lightning-openchannel_signed.7.md @@ -19,13 +19,6 @@ This command should be called after `openchannel_update` returns This command will broadcast the finalized funding transaction, if we receive valid signatures from the peer. -*channel\_id* is the id of the channel. - -*signed\_psbt* is the PSBT returned from `openchannel_update` (where -*commitments\_secured* was true) with partial signatures or finalized -witness stacks included for every input that we contributed to the -PSBT. - RETURN VALUE ------------ diff --git a/doc/lightning-openchannel_update.7.md b/doc/lightning-openchannel_update.7.md index e7bce0844548..ccbcd6adbf42 100644 --- a/doc/lightning-openchannel_update.7.md +++ b/doc/lightning-openchannel_update.7.md @@ -20,10 +20,6 @@ Must be called until *commitments\_secured* is returned as true, at which point `openchannel_signed` should be called with a signed version of the PSBT returned by the last call to `openchannel_update`. -*channel\_id* is the id of the channel. - -*psbt* is the updated PSBT to be sent to the peer. May be identical to -the PSBT last returned by either `openchannel_init` or `openchannel_update`. RETURN VALUE ------------ diff --git a/doc/lightning-plugin.7.md b/doc/lightning-plugin.7.md index 6aa9117b0b3c..84d1561ea36e 100644 --- a/doc/lightning-plugin.7.md +++ b/doc/lightning-plugin.7.md @@ -13,15 +13,6 @@ DESCRIPTION The **plugin** RPC command command can be used to control dynamic plugins, i.e. plugins that declared themself "dynamic" (in getmanifest). -*subcommand* can be **start**, **stop**, **startdir**, **rescan** or **list** and -determines what action is taken - -*plugin* is the *path* or *name* of a plugin executable to start or stop - -*directory* is the *path* of a directory containing plugins - -*options* are optional *keyword=value* options passed to plugin, can be repeated - *subcommand* **start** takes a *path* to an executable as argument and starts it as plugin. *path* may be an absolute path or a path relative to the plugins directory (default *~/.lightning/plugins*). If the plugin is already running and the executable (checksum) has changed, the plugin is diff --git a/doc/lightning-renepay.7.md b/doc/lightning-renepay.7.md index 7063ff8587d7..6f9832af911c 100644 --- a/doc/lightning-renepay.7.md +++ b/doc/lightning-renepay.7.md @@ -24,34 +24,11 @@ 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*. *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*. - -*maxfee* 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. - -*maxdelay* overrides the value of `max-locktime-blocks` for this payment. -It serves to limit the locktime of funds in the payment HTLC measured in blocks. - -*retry\_for* measured in seconds (default: 60) specifies how much time it is -allowed for the command to keep retrying the payment. - -*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. - -The *label* field is used to attach a label to payments, and is returned -in lightning-listpays(7) and lightning-listsendpays(7). +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. - OPTIMALITY ---------- diff --git a/doc/lightning-renepaystatus.7.md b/doc/lightning-renepaystatus.7.md index df78aabe7624..46423096c84b 100644 --- a/doc/lightning-renepaystatus.7.md +++ b/doc/lightning-renepaystatus.7.md @@ -12,8 +12,10 @@ 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 3d205244b109..959ceac63c76 100644 --- a/doc/lightning-reserveinputs.7.md +++ b/doc/lightning-reserveinputs.7.md @@ -15,11 +15,7 @@ with an error if any of the inputs are known to be spent, and ignore inputs which are unknown. Normally the command will fail (with no reservations made) if an input -is already reserved. If *exclusive* is set to *False*, then existing -reservations are simply extended, rather than causing failure. - -By default, reservations are for the next 72 blocks (approximately 6 -hours), but this can be changed by setting *reserve*. +is already reserved. RETURN VALUE ------------ diff --git a/doc/lightning-sendinvoice.7.md b/doc/lightning-sendinvoice.7.md index 45171b857319..033e6f45b8fe 100644 --- a/doc/lightning-sendinvoice.7.md +++ b/doc/lightning-sendinvoice.7.md @@ -4,13 +4,13 @@ lightning-sendinvoice -- Command for send an invoice for an offer SYNOPSIS -------- -**(WARNING: experimental-offers only)** - **sendinvoice** *invreq* *label* [*amount\_msat*] [*timeout*] [*quantity*] DESCRIPTION ----------- +**(WARNING: experimental-offers only)** + The **sendinvoice** RPC command creates and sends an invoice to the issuer of an *invoice\_request* for it to pay: lightning-invoicerequest(7). @@ -18,22 +18,6 @@ If **fetchinvoice-noconnect** is not specified in the configuation, it will connect to the destination in the (currently common!) case where it cannot find a route which supports `option_onion_messages`. -*invreq* is the bolt12 invoice\_request string beginning with "lnr1". - -*label* is the unique label to use for this invoice. - -*amount\_msat* is optional: it is required if the *offer* does not specify -an amount at all, or specifies it in a different currency. Otherwise -you may set it (e.g. to provide a tip), and if not it defaults to the -amount contained in the offer (multiplied by *quantity* if any). - -*timeout* is how many seconds to wait for the offering node to pay the -invoice or return an error, default 90 seconds. This will also be the -timeout on the invoice that is sent. - -*quantity* is optional: it is required if the *offer* specifies -*quantity\_max*, otherwise it is not allowed. - RETURN VALUE ------------ diff --git a/doc/lightning-sendonionmessage.7.md b/doc/lightning-sendonionmessage.7.md index 31abab740333..dbbb9222ca8e 100644 --- a/doc/lightning-sendonionmessage.7.md +++ b/doc/lightning-sendonionmessage.7.md @@ -4,20 +4,17 @@ lightning-sendonionmessage -- low-level command to send an onion message SYNOPSIS -------- -**(WARNING: experimental-onion-messages only)** - **sendonionmessage** *first\_id* *blinding* *hops* DESCRIPTION ----------- +**(WARNING: experimental-onion-messages only)** + The **sendonionmessage** RPC command can be used to send a message via the lightning network. These are currently used by *offers* to request and receive invoices. -*hops* is an array of json objects: *id* as a public key of the node, -and *tlv* contains a hexidecimal TLV to include. - RETURN VALUE ------------ diff --git a/doc/lightning-splice_init.7.md b/doc/lightning-splice_init.7.md index 426a86374480..5f47715b78db 100644 --- a/doc/lightning-splice_init.7.md +++ b/doc/lightning-splice_init.7.md @@ -4,13 +4,13 @@ lightning-splice\_init -- Command to initiate a channel to a peer SYNOPSIS -------- -**(WARNING: experimental-splicing only)** - **splice\_init** *channel\_id* *relative\_amount* [*initalpsbt*] [*feerate\_per\_kw*] [*force\_feerate*] DESCRIPTION ----------- +**(WARNING: experimental-splicing only)** + `splice_init` is a low level RPC command which initiates a channel splice for a given channel specified by `channel_id`. diff --git a/doc/lightning-splice_signed.7.md b/doc/lightning-splice_signed.7.md index d1ece90c44b3..07313e237463 100644 --- a/doc/lightning-splice_signed.7.md +++ b/doc/lightning-splice_signed.7.md @@ -4,13 +4,13 @@ lightning-splice\_signed -- Command to initiate a channel to a peer SYNOPSIS -------- -**(WARNING: experimental-splicing only)** - **splice\_signed** *channel\_id* *psbt* [*sign\_first*] DESCRIPTION ----------- +**(WARNING: experimental-splicing only)** + `splice_signed` is a low level RPC command which finishes the active channel splice associated with `channel_id`. diff --git a/doc/lightning-splice_update.7.md b/doc/lightning-splice_update.7.md index b3c5b7ee75a9..3b73ddbc1af2 100644 --- a/doc/lightning-splice_update.7.md +++ b/doc/lightning-splice_update.7.md @@ -4,13 +4,13 @@ lightning-splice\_update -- Command to initiate a channel to a peer SYNOPSIS -------- -**(WARNING: experimental-splicing only)** - **splice\_update** *channel\_id* *psbt* DESCRIPTION ----------- +**(WARNING: experimental-splicing only)** + `splice_update` is a low level RPC command which updates the active channel splice associated with `channel_id`. diff --git a/doc/lightning-unreserveinputs.7.md b/doc/lightning-unreserveinputs.7.md index 34fca85605db..a9fa6d9d3915 100644 --- a/doc/lightning-unreserveinputs.7.md +++ b/doc/lightning-unreserveinputs.7.md @@ -13,11 +13,6 @@ The **unreserveinputs** RPC command releases (or reduces reservation) on UTXOs which were previously marked as reserved, generally by lightning-reserveinputs(7). -The inputs to unreserve are the inputs specified in the passed-in *psbt*. - -If *reserve* is specified, it is the number of blocks to decrease -reservation by; default is 72. - RETURN VALUE ------------ diff --git a/doc/schemas/addpsbtoutput.request.json b/doc/schemas/addpsbtoutput.request.json index 5f63a7a5df54..bf80e47ed5ae 100644 --- a/doc/schemas/addpsbtoutput.request.json +++ b/doc/schemas/addpsbtoutput.request.json @@ -10,13 +10,13 @@ "satoshi": { "type": "msat" }, - "locktime": { - "type": "u32" - }, "initialpsbt": { "type": "string", "description": "the (optional) base 64 encoded PSBT to begin with. If not specified, one will be generated automatically" }, + "locktime": { + "type": "u32" + }, "destination": { "type": "string" } diff --git a/doc/schemas/autoclean-once.request.json b/doc/schemas/autoclean-once.request.json index 9cc41516273e..c0196748bc63 100644 --- a/doc/schemas/autoclean-once.request.json +++ b/doc/schemas/autoclean-once.request.json @@ -21,7 +21,7 @@ }, "age": { "type": "u64", - "description": "How many seconds old an entry must be to delete it" + "description": "non-zero number in seconds. How many seconds old an entry must be to delete it" } } } diff --git a/doc/schemas/batching.request.json b/doc/schemas/batching.request.json index 03c794d4a92b..d4cd745ad1e7 100644 --- a/doc/schemas/batching.request.json +++ b/doc/schemas/batching.request.json @@ -8,7 +8,7 @@ "properties": { "enable": { "type": "boolean", - "description": "Whether to enable or disable transaction batching" + "description": "whether to enable or disable transaction batching. Defaults to *False*" } } } diff --git a/doc/schemas/disableoffer.request.json b/doc/schemas/disableoffer.request.json new file mode 100644 index 000000000000..053011840d42 --- /dev/null +++ b/doc/schemas/disableoffer.request.json @@ -0,0 +1,14 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["offer_id"], + "properties": { + "offer_id": { + "type": "hex", + "description": "the id we use to identify this offer", + "maxLength": 64, + "minLength": 64 + } + } +} \ No newline at end of file diff --git a/doc/schemas/fundchannel_cancel.request.json b/doc/schemas/fundchannel_cancel.request.json new file mode 100644 index 000000000000..d380e4663e48 --- /dev/null +++ b/doc/schemas/fundchannel_cancel.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["id"], + "properties": { + "id": { + "type": "pubkey", + "description": "node id of the remote peer with which to cancel" + } + } +} \ No newline at end of file diff --git a/doc/schemas/fundchannel_complete.request.json b/doc/schemas/fundchannel_complete.request.json new file mode 100644 index 000000000000..77466f7433f3 --- /dev/null +++ b/doc/schemas/fundchannel_complete.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["id", "psbt"], + "properties": { + "id": { + "type": "pubkey", + "description": "node id of the remote peer" + }, + "psbt": { + "type": "string", + "description": "transaction to use for funding (does not need to be signed but must be otherwise complete)" + } + } +} \ No newline at end of file diff --git a/doc/schemas/fundchannel_start.request.json b/doc/schemas/fundchannel_start.request.json new file mode 100644 index 000000000000..9f07bdbf1f63 --- /dev/null +++ b/doc/schemas/fundchannel_start.request.json @@ -0,0 +1,47 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["id", "amount"], + "properties": { + "id": { + "type": "pubkey", + "description": "node id of the remote peer" + }, + "amount": { + "type": "integer", + "description": "satoshi value that the channel will be funded at. This value MUST be accurate, otherwise the negotiated commitment transactions will not encompass the correct channel value" + }, + "feerate": { + "type": "object", + "description": "feerate for subsequent commitment transactions: see **fundchannel**. Note that this is ignored for channels with *option_anchors_zero_fee_htlc_tx* (we always use a low commitment fee for these)", + "additionalProperties": false, + "required": [ + "perkw", + "perkb" + ], + "properties": { + "perkw": { + "type": "u32", + "description": "Feerate per 1000 weight (i.e kSipa)" + }, + "perkb": { + "type": "u32", + "description": "Feerate per 1000 virtual bytes" + } + } + }, + "announce": { + "type": "boolean", + "description": "whether or not to announce this channel" + }, + "close_to": { + "type": "string", + "description": "bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`. Returns `close_to` set to closing script iff is negotiated" + }, + "push_msat": { + "type": "msat", + "description": "amount of millisatoshis to push to the channel peer at open. Note that this is a gift to the peer -- these satoshis are added to the initial balance of the peer at channel start and are largely unrecoverable once pushed" + } + } +} \ No newline at end of file diff --git a/doc/schemas/funderupdate.request.json b/doc/schemas/funderupdate.request.json new file mode 100644 index 000000000000..ba5b9b8b0162 --- /dev/null +++ b/doc/schemas/funderupdate.request.json @@ -0,0 +1,77 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "policy": { + "type": "string", + "enum": [ + "match", + "available", + "fixed" + ], + "description": "funder plugin will use to decide how much captial to commit to a v2 open channel request. Default is fixed" + }, + "policy_mod": { + "type": "u32", + "description": "number or 'modification' to apply to the policy. Default is 0sats" + }, + "leases_only": { + "type": "boolean", + "description": "only contribute funds to `option_will_fund` lease requests. Defaults to false" + }, + "min_their_funding_msat": { + "type": "msat", + "description": "minimum funding sats that we require in order to activate our contribution policy to the v2 open. Defaults to 10k sats" + }, + "max_their_funding_msat": { + "type": "msat", + "description": "maximum funding sats that we will consider to activate our contribution policy to the v2 open. Any channel open above this will not be funded. Defaults to no max (`UINT_MAX`)" + }, + "per_channel_min_msat": { + "type": "msat", + "description": "minimum amount that we will contribute to a channel open. Defaults to 10k sats" + }, + "per_channel_max_msat": { + "type": "msat", + "description": "maximum amount that we will contribute to a channel open. Defaults to no max (`UINT_MAX`)" + }, + "reserve_tank_msat": { + "type": "msat", + "description": "amount of sats to leave available in the node wallet. Defaults to zero sats" + }, + "fuzz_percent": { + "type": "u32", + "description": "percentage to fuzz our funding amount by. Defaults to 0% (no fuzz)" + }, + "fund_probability": { + "type": "u32", + "description": "percent of opens to consider funding. 100 means we'll consider funding every requested open channel request. Defaults to 100" + }, + "lease_fee_base_msat": { + "type": "msat", + "description": "flat fee to charge for a channel lease. Defaults to 2k sats. Note that the minimum is 1sat." + }, + "lease_fee_basis": { + "type": "u32", + "description": "proportional fee to charge for a channel lease, calculated as 1/10,000th of requested funds. Default is 0.65% (65 basis points)" + }, + "funding_weight": { + "type": "u32", + "description": "transaction weight the channel opener will pay us for a leased funding transaction. Default is 2 inputs + 1 P2WPKH output." + }, + "channel_fee_max_base_msat": { + "type": "msat", + "description": "maximum channel_fee_base_msat we'll charge for routing funds leased on this channel. Default is 5k sats" + }, + "channel_fee_max_proportional_thousandths": { + "type": "u32", + "description": "maximum channel_fee_proportional_millitionths we'll charge for routing funds leased on this channel, in thousandths. Default is 100 (100k ppm)" + }, + "compact_lease": { + "type": "hex", + "description": "compact description of the channel lease parameters" + } + } +} \ No newline at end of file diff --git a/doc/schemas/getlog.request.json b/doc/schemas/getlog.request.json new file mode 100644 index 000000000000..8e48874f9c3f --- /dev/null +++ b/doc/schemas/getlog.request.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "level": { + "type": "string", + "enum": [ + "broken", + "unusual", + "info", + "debug", + "io" + ], + "description": "a string that represents the log level. The default is *info*" + } + } +} \ No newline at end of file diff --git a/doc/schemas/help.request.json b/doc/schemas/help.request.json new file mode 100644 index 000000000000..dc4c9c23da3f --- /dev/null +++ b/doc/schemas/help.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "command": { + "type": "string", + "description": "command to get information about" + } + } +} \ No newline at end of file diff --git a/doc/schemas/listconfigs.request.json b/doc/schemas/listconfigs.request.json new file mode 100644 index 000000000000..9c74a640d873 --- /dev/null +++ b/doc/schemas/listconfigs.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "config": { + "type": "string", + "description": "configuration option name to restrict return" + } + } +} \ No newline at end of file diff --git a/doc/schemas/listoffers.request.json b/doc/schemas/listoffers.request.json new file mode 100644 index 000000000000..4bc91e64450c --- /dev/null +++ b/doc/schemas/listoffers.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "offer_id": { + "type": "string", + "description": "offer_id to get details for (if it exists)" + }, + "active_only": { + "type": "boolean", + "description": "if set and is true, only offers with `active` true are returned" + } + } +} \ No newline at end of file diff --git a/doc/schemas/multifundchannel.request.json b/doc/schemas/multifundchannel.request.json new file mode 100644 index 000000000000..236c009a2a7d --- /dev/null +++ b/doc/schemas/multifundchannel.request.json @@ -0,0 +1,78 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["destinations"], + "properties": { + "destinations": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "amount" + ], + "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*" + }, + "amount": { + "type": "msat", + "description": "amount in satoshis taken from the internal wallet to fund the channel (but if we have any anchor channels, this will always leave at least `min-emergency-msat` as change). The string *all* can be used to specify all available funds (or 16,777,215 satoshi if more is available and large channels were not negotiated with the peer). 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*. The value cannot be less than the dust limit, currently 546 satoshi as of this writing, nor more than 16,777,215 satoshi (unless large channels were negotiated with the peer)" + + }, + "announce": { + "type": "boolean", + "description": "flag that indicates whether to announce the channel with this, default `true`. If set to `false`, the channel is unpublished" + }, + "push_msat": { + "type": "msat", + "description": "amount of millisatoshis to outright give to the node. This is a gift to the peer, and you do not get a proof-of-payment out of this" + }, + "close_to": { + "type": "string", + "description": "bitcoin address to which the channel funds should be sent to on close. Only valid if both peers have negotiated `option_upfront_shutdown_script` Returns `close_to` set to closing script iff is negotiated" + }, + "request_amt": { + "type": "msat", + "description": "amount of liquidity you'd like to lease from peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*" + }, + "compact_lease": { + "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" + }, + "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" + } + } + } +} \ No newline at end of file diff --git a/doc/schemas/multiwithdraw.request.json b/doc/schemas/multiwithdraw.request.json new file mode 100644 index 000000000000..7e9339cb666a --- /dev/null +++ b/doc/schemas/multiwithdraw.request.json @@ -0,0 +1,28 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["outputs"], + "properties": { + "outputs": { + "type": "outputs", + "description": "an array containing objects of the form `{address: amount}`. The `amount` may be the string *all*, indicating that all onchain funds be sent to the specified address. 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", + "description": "feerate used for the withdrawals. 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 be withdrawn from, as an array of `txid:vout`. These must be drawn from the node's available UTXO set" + } + } + } +} \ No newline at end of file diff --git a/doc/schemas/notifications.request.json b/doc/schemas/notifications.request.json new file mode 100644 index 000000000000..818e06179501 --- /dev/null +++ b/doc/schemas/notifications.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["enable"], + "properties": { + "enable": { + "type": "boolean", + "description": "whether to enable or disable notifications" + } + } +} \ No newline at end of file diff --git a/doc/schemas/offer.request.json b/doc/schemas/offer.request.json new file mode 100644 index 000000000000..2cdcd8fb0800 --- /dev/null +++ b/doc/schemas/offer.request.json @@ -0,0 +1,52 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["amount", "description"], + "properties": { + "amount": { + "type": "msat or any or string", + "description": "can be the string `any`, which creates an offer that can be paid with any amount (e.g. a donation). Otherwise it 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*. It can also have an ISO 4217 postfix (i.e. USD), in which case currency conversion will need to be done for the invoice itself. A plugin is needed which provides the `currencyconvert` API for this currency, otherwise the offer creation will fail" + }, + "description": { + "type": "string", + "description": "a short description of purpose of the offer, e.g. *coffee*. This value is encoded into the resulting offer and is viewable by anyone you expose this offer to. It must be UTF-8, and cannot use *\\u* JSON escape codes" + }, + "issuer": { + "type": "string", + "description": "who is issuing this offer (i.e. you) if appropriate" + }, + "label": { + "type": "string", + "description": "an internal-use name for the offer, which can be any UTF-8 string. This is *NOT* encoded in the offer not sent to the issuer" + }, + "quantity_max": { + "type": "integer", + "description": "invoice can specify more than one of the items up (and including) this maximum: 0 is a special value meaning `no maximuim`. The *amount* for the invoice will need to be multiplied accordingly. This is encoded in the offer" + }, + "absolute_expiry": { + "type": "integer", + "description": "time the offer is valid until,in seconds since the first day of 1970 UTC. If not set, the offer remains valid (though it can be deactivated by the issuer of course). This is encoded in the offer" + }, + "recurrence": { + "type": "string", + "description": "an invoice is expected at regular intervals. The argument is a positive number followed by one of `seconds`, `minutes`, `hours`, `days`, `weeks`, `months` or `years` (variants without the trailing `s` are also permitted). This is encoded in the offer. The semantics of recurrence is fairly predictable, but fully documented in BOLT 12. e.g. `4weeks`" + }, + "recurrence_base": { + "type": "string", + "description": "time in seconds since the first day of 1970 UTC, optionally with a `@` prefix. This indicates when the first period begins; without this, the recurrence periods start from the first invoice. The `@` prefix means that the invoice must start by paying the first period; otherwise it is permitted to start at any period. This is encoded in the offer. e.g. `@1609459200` indicates you must start paying on the 1st January 2021" + }, + "recurrence_paywindow": { + "type": "string", + "description": "argument of form `-time+time[%]`. The first time is the number of seconds before the start of a period in which an invoice and payment is valid, the second time is the number of seconds after the start of the period. For example *-604800+86400* means you can fetch an pay the invoice 4 weeks before the given period starts, and up to 1 day afterwards. The optional *%* indicates that the amount of the invoice will be scaled by the time remaining in the period. If this is not specified, the default is that payment is allowed during the current and previous periods. This is encoded in the offer" + }, + "recurrence_limit": { + "type": "integer", + "description": "to indicate the maximum period which exists. eg. `12` means there are 13 periods, from 0 to 12 inclusive. This is encoded in the offer" + }, + "single_use": { + "type": "boolean", + "description": "indicates that the offer is only valid once; we may issue multiple invoices, but as soon as one is paid all other invoices will be expired (i.e. only one person can pay this offer). Defaults to false" + } + } +} \ No newline at end of file diff --git a/doc/schemas/openchannel_abort.request.json b/doc/schemas/openchannel_abort.request.json new file mode 100644 index 000000000000..b65a999d76e6 --- /dev/null +++ b/doc/schemas/openchannel_abort.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["channel_id"], + "properties": { + "channel_id": { + "type": "string", + "description": "channel id of the channel to be aborted" + } + } +} \ No newline at end of file diff --git a/doc/schemas/openchannel_bump.request.json b/doc/schemas/openchannel_bump.request.json new file mode 100644 index 000000000000..3d6d7d13d946 --- /dev/null +++ b/doc/schemas/openchannel_bump.request.json @@ -0,0 +1,24 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["channel_id", "amount", "initialpsbt"], + "properties": { + "channel_id": { + "type": "string", + "description": "id of the channel to RBF" + }, + "amount": { + "type": "u64", + "description": "satoshi value that we will contribute to the channel. This value will be _added_ to the provided PSBT in the output which is encumbered by the 2-of-2 script for this channel" + }, + "initialpsbt": { + "type": "string", + "description": "the funded, incomplete PSBT that specifies the UTXOs and change output for our channel contribution. It can be updated, see `openchannel_update`; *initialpsbt* must have at least one input. Must have the Non-Witness UTXO (PSBT_IN_NON_WITNESS_UTXO) set for every input. An error (code 309) will be returned if this requirement is not met" + }, + "funding_feerate": { + "type": "u64", + "description": "feerate for the funding transaction. Defaults to 1/64th greater than the last feerate used for this channel" + } + } +} \ No newline at end of file diff --git a/doc/schemas/openchannel_init.request.json b/doc/schemas/openchannel_init.request.json new file mode 100644 index 000000000000..031730723966 --- /dev/null +++ b/doc/schemas/openchannel_init.request.json @@ -0,0 +1,44 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["id", "amount", "initialpsbt"], + "properties": { + "id": { + "type": "pubkey", + "description": "node id of the remote peer" + }, + "amount": { + "type": "u64", + "description": "satoshi value that we will contribute to the channel. This value will be _added_ to the provided PSBT in the output which is encumbered by the 2-of-2 script for this channel" + }, + "initialpsbt": { + "type": "string", + "description": "funded, incomplete PSBT that specifies the UTXOs and change output for our channel contribution. It can be updated, see `openchannel_update`; *initialpsbt* must have at least one input. Must have the Non-Witness UTXO (PSBT_IN_NON_WITNESS_UTXO) set for every input. An error (code 309) will be returned if this requirement is not met" + }, + "commitment_feerate": { + "type": "u64", + "description": "feerate for commitment transactions for non-anchor channels: see **fundchannel**. For anchor channels, it is ignored" + }, + "funding_feerate": { + "type": "u64", + "description": "feerate for the funding transaction. Defaults to 'opening' feerate" + }, + "announce": { + "type": "boolean", + "description": "whether or not to announce this channel" + }, + "close_to": { + "type": "string", + "description": "bitcoin address to which the channel funds should be sent on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`" + }, + "request_amt": { + "type": "msat", + "description": "an amount of liquidity you'd like to lease from the peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*" + }, + "compact_lease": { + "type": "string", + "description": "a 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" + } + } +} \ No newline at end of file diff --git a/doc/schemas/openchannel_signed.request.json b/doc/schemas/openchannel_signed.request.json new file mode 100644 index 000000000000..a58e3d85257e --- /dev/null +++ b/doc/schemas/openchannel_signed.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["channel_id", "signed_psbt"], + "properties": { + "channel_id": { + "type": "string", + "description": "id of the channel" + }, + "signed_psbt": { + "type": "string", + "description": "the PSBT returned from `openchannel_update` (where *commitments_secured* was true) with partial signatures or finalized witness stacks included for every input that we contributed to the PSBT" + } + } +} \ No newline at end of file diff --git a/doc/schemas/openchannel_update.request.json b/doc/schemas/openchannel_update.request.json new file mode 100644 index 000000000000..e07bf576d333 --- /dev/null +++ b/doc/schemas/openchannel_update.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["channel_id", "psbt"], + "properties": { + "channel_id": { + "type": "string", + "description": "id of the channel" + }, + "psbt": { + "type": "string", + "description": "updated PSBT to be sent to the peer. May be identical to the PSBT last returned by either `openchannel_init` or `openchannel_update`" + } + } +} \ No newline at end of file diff --git a/doc/schemas/parsefeerate.request.json b/doc/schemas/parsefeerate.request.json new file mode 100644 index 000000000000..da399ba5ee4e --- /dev/null +++ b/doc/schemas/parsefeerate.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["feerate_str"], + "properties": { + "feerate_str": { + "type": "string", + "description": "The feerate string to parse" + } + } +} \ No newline at end of file diff --git a/doc/schemas/plugin.request.json b/doc/schemas/plugin.request.json new file mode 100644 index 000000000000..472e6bba678d --- /dev/null +++ b/doc/schemas/plugin.request.json @@ -0,0 +1,34 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["subcommand"], + "properties": { + "subcommand": { + "type": "string", + "enum": [ + "start", + "stop", + "rescan", + "startdir", + "list" + ], + "description": "determines what action is taken" + }, + "plugin": { + "type": "string", + "description": "*path* or *name* of a plugin executable to start or stop" + }, + "directory": { + "type": "string", + "description": "*path* of a directory containing plugins" + }, + "options": { + "type": "array", + "items": { + "type": "string", + "description": "*keyword=value* options passed to plugin, can be repeated" + } + } + } +} \ No newline at end of file diff --git a/doc/schemas/renepay.request.json b/doc/schemas/renepay.request.json new file mode 100644 index 000000000000..20363cd16faf --- /dev/null +++ b/doc/schemas/renepay.request.json @@ -0,0 +1,36 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["invstring"], + "properties": { + "invstring": { + "type": "string", + "description": "bolt11 invoice to pay" + }, + "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*" + }, + "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" + }, + "maxdelay": { + "type": "number", + "description": "overrides the value of `max-locktime-blocks` for this payment. It serves to limit the locktime of funds in the payment HTLC measured in blocks" + }, + "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": { + "type": "string", + "description": "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" + }, + "label": { + "type": "string", + "description": "used to attach a label to payments, and is returned in lightning-listpays(7) and lightning-listsendpays(7)" + } + } +} \ No newline at end of file diff --git a/doc/schemas/renepaystatus.request.json b/doc/schemas/renepaystatus.request.json new file mode 100644 index 000000000000..4581b36f7137 --- /dev/null +++ b/doc/schemas/renepaystatus.request.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [], + "properties": { + "invstring": { + "type": "string", + "description": "bolt11 invoice to check status" + } + } +} \ No newline at end of file diff --git a/doc/schemas/reserveinputs.request.json b/doc/schemas/reserveinputs.request.json new file mode 100644 index 000000000000..ddf5b2479272 --- /dev/null +++ b/doc/schemas/reserveinputs.request.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["psbt"], + "properties": { + "psbt": { + "type": "string", + "description": "the PSBT to reserve inputs from" + }, + "exclusive": { + "type": "boolean", + "description": "If set to *False*, existing reservations are simply extended, rather than causing failure" + }, + "reserve": { + "type": "integer", + "description": "the number of blocks to reserve. By default, reservations are for the next 72 blocks (approximately 6 hours)" + } + } +} \ No newline at end of file diff --git a/doc/schemas/sendinvoice.request.json b/doc/schemas/sendinvoice.request.json new file mode 100644 index 000000000000..ca4fd00a251d --- /dev/null +++ b/doc/schemas/sendinvoice.request.json @@ -0,0 +1,28 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["invreq", "label"], + "properties": { + "invreq": { + "type": "string", + "description": "the bolt12 invoice_request string beginning with `lnr1`" + }, + "label": { + "type": "string", + "description": "the unique label to use for this invoice" + }, + "amount_msat": { + "type": "msat", + "description": "required if the *offer* does not specify an amount at all, or specifies it in a different currency. Otherwise you may set it (e.g. to provide a tip), and if not it defaults to the amount contained in the offer (multiplied by *quantity* if any)" + }, + "timeout": { + "type": "u32", + "description": "seconds to wait for the offering node to pay the invoice or return an error, default 90 seconds. This will also be the timeout on the invoice that is sent" + }, + "quantity": { + "type": "u64", + "description": "quantity is is required if the offer specifies quantity_max, otherwise it is not allowed." + } + } +} \ No newline at end of file diff --git a/doc/schemas/sendonionmessage.request.json b/doc/schemas/sendonionmessage.request.json new file mode 100644 index 000000000000..e202f5402b63 --- /dev/null +++ b/doc/schemas/sendonionmessage.request.json @@ -0,0 +1,38 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["first_id", "blinding", "hops"], + "properties": { + "first_id": { + "type": "pubkey", + "description": "the (presumably well-known) public key of the start of the path" + }, + "blinding": { + "type": "pubkey", + "description": "blinding factor for this path" + }, + "hops": { + "type": "array", + "description": "", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "node", + "tlv" + ], + "properties": { + "node": { + "type": "pubkey", + "description": "public key of the node" + }, + "tlv": { + "type": "u8", + "description": "contains a hexidecimal TLV to include" + } + } + } + } + } +} \ No newline at end of file diff --git a/doc/schemas/unreserveinputs.request.json b/doc/schemas/unreserveinputs.request.json new file mode 100644 index 000000000000..084c62eb0cfa --- /dev/null +++ b/doc/schemas/unreserveinputs.request.json @@ -0,0 +1,16 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["psbt"], + "properties": { + "psbt": { + "type": "string", + "description": "inputs to unreserve are the inputs specified in the passed-in *psbt*" + }, + "reserve": { + "type": "integer", + "description": "the number of blocks to decrease reservation by; default is 72" + } + } +} \ No newline at end of file