diff --git a/doc/lightning-disableoffer.7 b/doc/lightning-disableoffer.7 index 1b1547e38..88f923c77 100644 --- a/doc/lightning-disableoffer.7 +++ b/doc/lightning-disableoffer.7 @@ -33,9 +33,26 @@ forgotten entirely (there may be invoices which refer to this offer)\. .fi .SH RETURN VALUE -If successful the command returns an object, in the same format as \fBlistoffers\fR\. -The "active" field will always be false\. +Note: the returned object is the same format as \fBlistoffers\fR\. + +On success, an object is returned, containing: + +.RS +.IP \[bu] +\fBoffer_id\fR (hex): the merkle hash of the offer (always 64 characters) +.IP \[bu] +\fBactive\fR (boolean): Whether the offer can produce invoices/payments (always "false") +.IP \[bu] +\fBsingle_use\fR (boolean): Whether the offer is disabled after first successful use +.IP \[bu] +\fBbolt12\fR (string): The bolt12 string representing this offer +.IP \[bu] +\fBused\fR (boolean): Whether the offer has had an invoice paid / payment made +.IP \[bu] +\fBlabel\fR (string, optional): The label provided when offer was created + +.RE .SH EXAMPLE JSON RESPONSE .nf .RS @@ -61,4 +78,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:55cfb050fa2d28f58750dc74659d9f7bc5ec00499e218ccffd058db51efc38d2 +\" SHA256STAMP:33b8cddae4a830e710906268c1d0d301442bc7ab0711e1d6ce670f86c77ae320 diff --git a/doc/lightning-disableoffer.7.md b/doc/lightning-disableoffer.7.md index 398fd0438..201cd99c5 100644 --- a/doc/lightning-disableoffer.7.md +++ b/doc/lightning-disableoffer.7.md @@ -32,8 +32,17 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -If successful the command returns an object, in the same format as **listoffers**. -The "active" field will always be false. +Note: the returned object is the same format as **listoffers**. + +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **offer_id** (hex): the merkle hash of the offer (always 64 characters) +- **active** (boolean): Whether the offer can produce invoices/payments (always "false") +- **single_use** (boolean): Whether the offer is disabled after first successful use +- **bolt12** (string): The bolt12 string representing this offer +- **used** (boolean): Whether the offer has had an invoice paid / payment made +- **label** (string, optional): The label provided when offer was created +[comment]: # (GENERATE-FROM-SCHEMA-END) EXAMPLE JSON RESPONSE ----- @@ -63,3 +72,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:6b0ae21e38a83742735f38e9c022b33ed4a436cacc746ff22e63d7b00779e4d0) diff --git a/doc/lightning-disconnect.7 b/doc/lightning-disconnect.7 index bbea46d36..5110a3801 100644 --- a/doc/lightning-disconnect.7 +++ b/doc/lightning-disconnect.7 @@ -63,4 +63,4 @@ Michael Hawkins \fI\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:fe16ccb06f56e5b59a1aea19b1a6625624b93e668cd07bba9e3f581873fa3eab +\" SHA256STAMP:7efc0fbbb7397d3767ea170ba091b5bc00f4efaf8e1283c7b7ed1aaaccfd3c4d diff --git a/doc/lightning-disconnect.7.md b/doc/lightning-disconnect.7.md index e3bc72a7f..30571804a 100644 --- a/doc/lightning-disconnect.7.md +++ b/doc/lightning-disconnect.7.md @@ -33,7 +33,9 @@ connection. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) On success, an empty object is returned. +[comment]: # (GENERATE-FROM-SCHEMA-END) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -56,3 +58,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff) diff --git a/doc/lightning-feerates.7 b/doc/lightning-feerates.7 index c6ec64de2..294aeaf2f 100644 --- a/doc/lightning-feerates.7 +++ b/doc/lightning-feerates.7 @@ -54,61 +54,77 @@ which will override the recommended feerates returned by \fBfeerates\fR\. .SH RETURN VALUE -The \fBfeerates\fR command returns the feerates in an object named -\fIperkw\fR or \fIperkb\fR, depending on your \fIstyle\fR parameter\. - - -Some of these estimations may be missing, except for \fImin_acceptable\fR -and \fImax_acceptable\fR, which are always present\. - - -The \fIperkw\fR or \fIperkb\fR object may have fields containing the estimates: +On success, an object is returned, containing: .RS .IP \[bu] -\fIopening\fR - feerate used for channel opening by \fBlightning-fundchannel\fR(7), -as well as normal onchain-to-onchain spends by \fBlightning-withdraw\fR(7)\. -In general, for all normal onchain-to-onchain spends, this is the feerate -you should also use\. +\fBperkb\fR (object, optional): If \fIstyle\fR parameter was perkb: +.RS .IP \[bu] -\fImutual_close\fR - the starting feerate used in mutual close negotiation\. -Note that since mutual close is a \fBnegotiation\fR, -the actual feerate used in mutual close -will be somewhere between this -and the corresponding mutual close feerate of the peer\. +\fBmin_acceptable\fR (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend .IP \[bu] -\fIunilateral_close\fR - the feerate we will pay for when a unilateral close -is done on a channel we originally funded\. -When anchor commitments are implemented, -this will be the feerate we will use -for a unilateral close we initiated\. +\fBmax_acceptable\fR (u32): The largest feerate we will accept from remote negotiations\. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)\. .IP \[bu] -\fIdelayed_to_us\fR - the feerate we will use when claiming our output from -a unilateral close we initiated\. +\fBopening\fR (u32, optional): Default feerate for \fBlightning-fundchannel\fR(7) and \fBlightning-withdraw\fR(7) .IP \[bu] -\fIhtlc_resolution\fR - the feerate we will use to claim HTLCs -from a unilateral close we initiated\. +\fBmutual_close\fR (u32, optional): Feerate to aim for in cooperative shutdown\. Note that since mutual close is a \fBnegotiation\fR, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer\. .IP \[bu] -\fIpenalty\fR - the feerate we will use to revoke old state, -if the counterparty attempts to cheat us\. +\fBunilateral_close\fR (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded +.IP \[bu] +\fBdelayed_to_us\fR (u32, optional): Feerate for returning unilateral close funds to our wallet +.IP \[bu] +\fBhtlc_resolution\fR (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet +.IP \[bu] +\fBpenalty\fR (u32, optional): Feerate to start at when penalizing a cheat attempt .RE -The following fields are always present in the \fIperkw\fR or \fIperkb\fR object: +.IP \[bu] +\fBperkw\fR (object, optional): If \fIstyle\fR parameter was perkw: +.RS +.IP \[bu] +\fBmin_acceptable\fR (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend +.IP \[bu] +\fBmax_acceptable\fR (u32): The largest feerate we will accept from remote negotiations\. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)\. +.IP \[bu] +\fBopening\fR (u32, optional): Default feerate for \fBlightning-fundchannel\fR(7) and \fBlightning-withdraw\fR(7) +.IP \[bu] +\fBmutual_close\fR (u32, optional): Feerate to aim for in cooperative shutdown\. Note that since mutual close is a \fBnegotiation\fR, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer\. +.IP \[bu] +\fBunilateral_close\fR (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded +.IP \[bu] +\fBdelayed_to_us\fR (u32, optional): Feerate for returning unilateral close funds to our wallet +.IP \[bu] +\fBhtlc_resolution\fR (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet +.IP \[bu] +\fBpenalty\fR (u32, optional): Feerate to start at when penalizing a cheat attempt + +.RE + +.IP \[bu] +\fBonchain_fee_estimates\fR (object, optional): +.RS +.IP \[bu] +\fBopening_channel_satoshis\fR (u64): Estimated cost of typical channel open +.IP \[bu] +\fBmutual_close_satoshis\fR (u64): Estimated cost of typical channel close +.IP \[bu] +\fBunilateral_close_satoshis\fR (u64): Estimated cost of typical unilateral close (without HTLCs) +.IP \[bu] +\fBhtlc_timeout_satoshis\fR (u64): Estimated cost of typical HTLC timeout transaction +.IP \[bu] +\fBhtlc_success_satoshis\fR (u64): Estimated cost of typical HTLC fulfillment transaction + +.RE + + +.RE + +The following warnings may also be returned: .RS .IP \[bu] -\fImin_acceptable\fR - the smallest feerate that you can use, -usually the minimum relayed feerate of the backend\. -.IP \[bu] -\fImax_acceptable\fR - the largest feerate we will accept -from remote negotiations\. -If a peer attempts to open a channel to us but wants a unilateral close -feerate larger than \fImax_acceptable\fR, we reject the open attempt\. -If the peer attempts to change the unilateral close feerate of a channel it -opened to us, such that the new feerate exceeds \fImax_acceptable\fR, we -unilaterally close the channel -(at the current unilateral close feerate instead of the new one)\. +\fBwarning_missing_feerates\fR: Some fee estimates are missing .RE .SH ERRORS @@ -153,4 +169,4 @@ manpage\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:f0fc7218cc1286cb6fb299cf81553d851d4ba4fee570e7bb169593d17aea951b +\" SHA256STAMP:6e1ae2f26676a76231461ac1f696066e538edabfab00ec9480550a5c6bc6981e diff --git a/doc/lightning-feerates.7.md b/doc/lightning-feerates.7.md index 043ab6237..79ae753e6 100644 --- a/doc/lightning-feerates.7.md +++ b/doc/lightning-feerates.7.md @@ -44,47 +44,36 @@ which will override the recommended feerates returned by **feerates**. RETURN VALUE ------------ -The **feerates** command returns the feerates in an object named -*perkw* or *perkb*, depending on your *style* parameter. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **perkb** (object, optional): If *style* parameter was perkb: + - **min_acceptable** (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend + - **max_acceptable** (u32): The largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet). + - **opening** (u32, optional): Default feerate for lightning-fundchannel(7) and lightning-withdraw(7) + - **mutual_close** (u32, optional): Feerate to aim for in cooperative shutdown. Note that since mutual close is a **negotiation**, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer. + - **unilateral_close** (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded + - **delayed_to_us** (u32, optional): Feerate for returning unilateral close funds to our wallet + - **htlc_resolution** (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet + - **penalty** (u32, optional): Feerate to start at when penalizing a cheat attempt +- **perkw** (object, optional): If *style* parameter was perkw: + - **min_acceptable** (u32): The smallest feerate that you can use, usually the minimum relayed feerate of the backend + - **max_acceptable** (u32): The largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet). + - **opening** (u32, optional): Default feerate for lightning-fundchannel(7) and lightning-withdraw(7) + - **mutual_close** (u32, optional): Feerate to aim for in cooperative shutdown. Note that since mutual close is a **negotiation**, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer. + - **unilateral_close** (u32, optional): Feerate for commitment_transaction in a live channel which we originally funded + - **delayed_to_us** (u32, optional): Feerate for returning unilateral close funds to our wallet + - **htlc_resolution** (u32, optional): Feerate for returning unilateral close HTLC outputs to our wallet + - **penalty** (u32, optional): Feerate to start at when penalizing a cheat attempt +- **onchain_fee_estimates** (object, optional): + - **opening_channel_satoshis** (u64): Estimated cost of typical channel open + - **mutual_close_satoshis** (u64): Estimated cost of typical channel close + - **unilateral_close_satoshis** (u64): Estimated cost of typical unilateral close (without HTLCs) + - **htlc_timeout_satoshis** (u64): Estimated cost of typical HTLC timeout transaction + - **htlc_success_satoshis** (u64): Estimated cost of typical HTLC fulfillment transaction -Some of these estimations may be missing, except for *min\_acceptable* -and *max\_acceptable*, which are always present. - -The *perkw* or *perkb* object may have fields containing the estimates: - -* *opening* - feerate used for channel opening by lightning-fundchannel(7), - as well as normal onchain-to-onchain spends by lightning-withdraw(7). - In general, for all normal onchain-to-onchain spends, this is the feerate - you should also use. -* *mutual\_close* - the starting feerate used in mutual close negotiation. - Note that since mutual close is a **negotiation**, - the actual feerate used in mutual close - will be somewhere between this - and the corresponding mutual close feerate of the peer. -* *unilateral\_close* - the feerate we will pay for when a unilateral close - is done on a channel we originally funded. - When anchor commitments are implemented, - this will be the feerate we will use - for a unilateral close we initiated. -* *delayed\_to\_us* - the feerate we will use when claiming our output from - a unilateral close we initiated. -* *htlc_resolution* - the feerate we will use to claim HTLCs - from a unilateral close we initiated. -* *penalty* - the feerate we will use to revoke old state, - if the counterparty attempts to cheat us. - -The following fields are always present in the *perkw* or *perkb* object: - -* *min\_acceptable* - the smallest feerate that you can use, - usually the minimum relayed feerate of the backend. -* *max\_acceptable* - the largest feerate we will accept - from remote negotiations. - If a peer attempts to open a channel to us but wants a unilateral close - feerate larger than *max\_acceptable*, we reject the open attempt. - If the peer attempts to change the unilateral close feerate of a channel it - opened to us, such that the new feerate exceeds *max\_acceptable*, we - unilaterally close the channel - (at the current unilateral close feerate instead of the new one). +The following warnings may also be returned: +- **warning_missing_feerates**: Some fee estimates are missing +[comment]: # (GENERATE-FROM-SCHEMA-END) ERRORS ------ @@ -129,3 +118,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:e16ae963e528995f1e01c80b4ed4e9b0d6c457a559928e98ab6cf32624557894) diff --git a/doc/lightning-fetchinvoice.7 b/doc/lightning-fetchinvoice.7 index ec1223ca1..753f4c66e 100644 --- a/doc/lightning-fetchinvoice.7 +++ b/doc/lightning-fetchinvoice.7 @@ -47,55 +47,43 @@ we fail (default, 60 seconds)\. .SH RETURN VALUE -On success, an object as follows is returned: +On success, an object is returned, containing: .RS .IP \[bu] -\fIinvoice\fR: the bolt12-encoded invoice string, starting with "lni1"\. +\fBinvoice\fR (string): The BOLT12 invoice we fetched .IP \[bu] -\fIchanges\fR: an object detailing changes between the offer and invoice\. +\fBchanges\fR (object): Summary of changes from offer: +.RS +.IP \[bu] +\fBdescription_appended\fR (string, optional): extra characters appended to the \fIdescription\fR field\. +.IP \[bu] +\fBdescription\fR (string, optional): a completely replaced \fIdescription\fR field +.IP \[bu] +\fBvendor_removed\fR (string, optional): The \fIvendor\fR from the offer, which is missing in the invoice +.IP \[bu] +\fBvendor\fR (string, optional): a completely replaced \fIvendor\fR field +.IP \[bu] +\fBmsat\fR (msat, optional): the amount, if different from the offer amount multiplied by any \fIquantity\fR (or the offer had no amount, or was not in BTC)\. .RE -Optionally: - +.IP \[bu] +\fBnext_period\fR (object, optional): Only for recurring invoices if the next period is under the \fIrecurrence_limit\fR: .RS .IP \[bu] -\fInext_period\fR: an object returned for recurring invoices if the next -period is under the recurrence_limit (if any)\. +\fBcounter\fR (u64): the index of the next period to fetchinvoice +.IP \[bu] +\fBstarttime\fR (u64): UNIX timestamp that the next period starts +.IP \[bu] +\fBendtime\fR (u64): UNIX timestamp that the next period ends +.IP \[bu] +\fBpaywindow_start\fR (u64): UNIX timestamp of the earliest time that the next invoice can be fetched +.IP \[bu] +\fBpaywindow_end\fR (u64): UNIX timestamp of the latest time that the next invoice can be fetched .RE -The \fIchanges\fR object can have and of the following members: - -.RS -.IP \[bu] -\fIdescription_appended\fR: extra characters appended to the \fIdescription\fR field\. -.IP \[bu] -\fIdescription\fR: a completely replaced \fIdescription\fR field\. -.IP \[bu] -\fIvendor_removed\fR": the offer vendor field, which has been omitted from the invoice\. -.IP \[bu] -\fIvendor\fR": the offer vendor field, which has changed from the invoice\. -.IP \[bu] -\fImsat\fR": the amount, if different from the offer amount multiplied -by any \fIquantity\fR (or the offer had no amount, or was not in BTC)\. - -.RE - -The \fInext_period\fR object has at least the following members: - -.RS -.IP \[bu] -\fIcounter\fR: the index of the next period to be fetchinvoice\. -.IP \[bu] -\fIstarttime\fR: the time that the next period starts (seconds since 1970) -.IP \[bu] -\fIendtime\fR: the time that the next period ends (seconds since 1970) -.IP \[bu] -\fIpaywindow_start\fR: the earliest time that the next invoice can be fetched (seconds since 1970) -.IP \[bu] -\fIpaywindow_end\fR: the latest time that the next invoice can be fetched (seconds since 1970) .RE @@ -126,4 +114,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:a96df8e4f480c093c83268688d683db82575341ecb4176ab586eae9baf69d9c1 +\" SHA256STAMP:23be8c105314c109fa0f7c532c3eebf9b2cbe47f520d600d3d2159765def3cbd diff --git a/doc/lightning-fetchinvoice.7.md b/doc/lightning-fetchinvoice.7.md index de1faafb1..46de11de5 100644 --- a/doc/lightning-fetchinvoice.7.md +++ b/doc/lightning-fetchinvoice.7.md @@ -42,29 +42,22 @@ we fail (default, 60 seconds). RETURN VALUE ------------ -On success, an object as follows is returned: - -* *invoice*: the bolt12-encoded invoice string, starting with "lni1". -* *changes*: an object detailing changes between the offer and invoice. - -Optionally: -* *next_period*: an object returned for recurring invoices if the next - period is under the recurrence_limit (if any). - -The *changes* object can have and of the following members: -* *description_appended*: extra characters appended to the *description* field. -* *description*: a completely replaced *description* field. -* *vendor_removed*": the offer vendor field, which has been omitted from the invoice. -* *vendor*": the offer vendor field, which has changed from the invoice. -* *msat*": the amount, if different from the offer amount multiplied - by any *quantity* (or the offer had no amount, or was not in BTC). - -The *next_period* object has at least the following members: -* *counter*: the index of the next period to be fetchinvoice. -* *starttime*: the time that the next period starts (seconds since 1970) -* *endtime*: the time that the next period ends (seconds since 1970) -* *paywindow_start*: the earliest time that the next invoice can be fetched (seconds since 1970) -* *paywindow_end*: the latest time that the next invoice can be fetched (seconds since 1970) +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **invoice** (string): The BOLT12 invoice we fetched +- **changes** (object): Summary of changes from offer: + - **description_appended** (string, optional): extra characters appended to the *description* field. + - **description** (string, optional): a completely replaced *description* field + - **vendor_removed** (string, optional): The *vendor* from the offer, which is missing in the invoice + - **vendor** (string, optional): a completely replaced *vendor* field + - **msat** (msat, optional): the amount, if different from the offer amount multiplied by any *quantity* (or the offer had no amount, or was not in BTC). +- **next_period** (object, optional): Only for recurring invoices if the next period is under the *recurrence_limit*: + - **counter** (u64): the index of the next period to fetchinvoice + - **starttime** (u64): UNIX timestamp that the next period starts + - **endtime** (u64): UNIX timestamp that the next period ends + - **paywindow_start** (u64): UNIX timestamp of the earliest time that the next invoice can be fetched + - **paywindow_end** (u64): UNIX timestamp of the latest time that the next invoice can be fetched +[comment]: # (GENERATE-FROM-SCHEMA-END) The following error codes may occur: - -1: Catchall nonspecific error. @@ -88,3 +81,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:e2b81ad7a61dd6a6d55e21c5367c3286aaf00cee734b2719a8e38bc87f7ac8aa) diff --git a/doc/lightning-fundchannel.7 b/doc/lightning-fundchannel.7 index 73860c32a..69944ba73 100644 --- a/doc/lightning-fundchannel.7 +++ b/doc/lightning-fundchannel.7 @@ -86,16 +86,21 @@ lightning-cli -k fundchannel id=03f...fc1 amount=all feerate=normal utxos='["bcc .fi .SH RETURN VALUE -On success, the \fItx\fR and \fItxid\fR of the transaction is returned, as well -as the \fIoutnum\fR indicating the output index which creates the channel, as well -as the \fIchannel_id\fR of the newly created channel\. On failure, an error -is reported and the channel is not funded\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBtx\fR (hex): The raw transaction which funded the channel +.IP \[bu] +\fBtxid\fR (txid): The txid of the transaction which funded the channel +.IP \[bu] +\fBoutnum\fR (u32): The 0-based output index showing which output funded the channel +.IP \[bu] +\fBchannel_id\fR (hex): The channel_id of the resulting channel (always 64 characters) +.IP \[bu] +\fBclose_to\fR (hex, optional): The raw scriptPubkey which mutual close will go to; only present if \fIclose_to\fR parameter was specified and peer supports \fBoption_upfront_shutdown_script\fR -If a \fBclose_to\fR address was provided, will close to this address -iff the \fBclose_to\fR script is returned in the response\. Otherwise, -the peer does not support \fBoption_upfront_shutdownscript\fR\. - +.RE The following error codes may occur: @@ -125,4 +130,4 @@ channel parameters (funding limits, channel reserves, fees, etc\.)\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:6b8356d6c8f33ffa6885060386776334b6ee4eaf051362eed188541e3582e1e5 +\" SHA256STAMP:ee8d7d247d9d4f263f8bbed936a2ba4b61d4afc5c48580f462a0d6142c13dbbd diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index 723914ed3..deaa3904e 100644 --- a/doc/lightning-fundchannel.7.md +++ b/doc/lightning-fundchannel.7.md @@ -73,14 +73,14 @@ This example shows how to use lightning-cli to open new channel with peer 03f... RETURN VALUE ------------ -On success, the *tx* and *txid* of the transaction is returned, as well -as the *outnum* indicating the output index which creates the channel, as well -as the *channel\_id* of the newly created channel. On failure, an error -is reported and the channel is not funded. - -If a `close_to` address was provided, will close to this address -iff the `close_to` script is returned in the response. Otherwise, -the peer does not support `option_upfront_shutdownscript`. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **tx** (hex): The raw transaction which funded the channel +- **txid** (txid): The txid of the transaction which funded the channel +- **outnum** (u32): The 0-based output index showing which output funded the channel +- **channel_id** (hex): The channel_id of the resulting channel (always 64 characters) +- **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` +[comment]: # (GENERATE-FROM-SCHEMA-END) The following error codes may occur: - -1: Catchall nonspecific error. @@ -103,3 +103,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:5b17c334b90f840a986750f9fcdb6a6bfa79bd1a3da11319a1957ba87bc4b0a7) diff --git a/doc/lightning-fundchannel_cancel.7 b/doc/lightning-fundchannel_cancel.7 index e2c94a58d..663e39ccd 100644 --- a/doc/lightning-fundchannel_cancel.7 +++ b/doc/lightning-fundchannel_cancel.7 @@ -25,9 +25,13 @@ to remote peer again before opening channel\. .SH RETURN VALUE -On success, returns confirmation that the channel establishment has been -canceled\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBcancelled\fR (string): A message indicating it was cancelled by RPC + +.RE On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -60,4 +64,4 @@ lightning-openchannel_\fBsigned\fR(7), lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:72ea44cf6efea20b369fb3ecfb61c8ede142800cbc8b427dbb9a26ec254452ce +\" SHA256STAMP:d9006c6b2519f1ae2009a683e3e8131af6e182929d8f0025e451155e4e7d6fe6 diff --git a/doc/lightning-fundchannel_cancel.7.md b/doc/lightning-fundchannel_cancel.7.md index 8c2da4d26..80f24c379 100644 --- a/doc/lightning-fundchannel_cancel.7.md +++ b/doc/lightning-fundchannel_cancel.7.md @@ -25,8 +25,10 @@ to remote peer again before opening channel. RETURN VALUE ------------ -On success, returns confirmation that the channel establishment has been -canceled. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **cancelled** (string): A message indicating it was cancelled by RPC +[comment]: # (GENERATE-FROM-SCHEMA-END) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -56,3 +58,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:f639e58991b8a9b58b181e9f4bd325fb24368af5cb76f94a94ca21675421829b) diff --git a/doc/lightning-fundchannel_complete.7 b/doc/lightning-fundchannel_complete.7 index 41a0acda8..566fabe0d 100644 --- a/doc/lightning-fundchannel_complete.7 +++ b/doc/lightning-fundchannel_complete.7 @@ -26,9 +26,15 @@ unrecoverable loss of funds\. .SH RETURN VALUE -On success, returns a confirmation that \fIcommitments_secured\fR and the -derived \fIchannel_id\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBchannel_id\fR (hex): The channel_id of the resulting channel (always 64 characters) +.IP \[bu] +\fBcommitments_secured\fR (boolean): Indication that channel is safe to use (always \fItrue\fR) + +.RE On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -62,4 +68,4 @@ lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:13e5fee7b987b38e9b08685f4b49062314ec9e2cf52afbb5a2c5a4965fe2b01f +\" SHA256STAMP:72b7e8826beb42061bf53e59b72c35c4fba6cdb421e491ffe6bf07dc51412342 diff --git a/doc/lightning-fundchannel_complete.7.md b/doc/lightning-fundchannel_complete.7.md index 06b8b53b7..8a2a95957 100644 --- a/doc/lightning-fundchannel_complete.7.md +++ b/doc/lightning-fundchannel_complete.7.md @@ -26,8 +26,11 @@ unrecoverable loss of funds. RETURN VALUE ------------ -On success, returns a confirmation that *commitments\_secured* and the -derived *channel\_id*. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **channel_id** (hex): The channel_id of the resulting channel (always 64 characters) +- **commitments_secured** (boolean): Indication that channel is safe to use (always *true*) +[comment]: # (GENERATE-FROM-SCHEMA-END) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -57,3 +60,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:7cb52658d81c5834e34a6011c04283bf740fe6e5feedb0208778abad5fddc519) diff --git a/doc/lightning-fundchannel_start.7 b/doc/lightning-fundchannel_start.7 index 256e0e0e3..fa212251f 100644 --- a/doc/lightning-fundchannel_start.7 +++ b/doc/lightning-fundchannel_start.7 @@ -45,10 +45,17 @@ transaction before that can lead to unrecoverable loss of funds\. .SH RETURN VALUE -On success, returns the \fIfunding_address\fR and the \fIscriptpubkey\fR for the channel funding output\. -If a \fBclose_to\fR address was provided, will close to this address iff the \fBclose_to\fR address is -returned in the response\. Otherwise, the peer does not support \fBoption_upfront_shutdownscript\fR\. +On success, an object is returned, containing: +.RS +.IP \[bu] +\fBfunding_address\fR (string): The address to send funding to for the channel +.IP \[bu] +\fBscriptpubkey\fR (hex): The raw scriptPubkey for the address +.IP \[bu] +\fBclose_to\fR (hex, optional): The raw scriptPubkey which mutual close will go to; only present if \fIclose_to\fR parameter was specified and peer supports \fBoption_upfront_shutdown_script\fR + +.RE On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -86,4 +93,4 @@ lightning-openchannel_\fBabort\fR(7) Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:6dd30561d6b00b1f2d5595cfe199e09576eb4ba2afea7ba52e8f38546720c76c +\" SHA256STAMP:959e97d593fb77f9403e8c5024d5582a2ae81b5cffae1799a285e0a26281b770 diff --git a/doc/lightning-fundchannel_start.7.md b/doc/lightning-fundchannel_start.7.md index ff1d8b046..5f34431b6 100644 --- a/doc/lightning-fundchannel_start.7.md +++ b/doc/lightning-fundchannel_start.7.md @@ -41,9 +41,12 @@ transaction before that can lead to unrecoverable loss of funds. RETURN VALUE ------------ -On success, returns the *funding\_address* and the *scriptpubkey* for the channel funding output. -If a `close_to` address was provided, will close to this address iff the `close_to` address is -returned in the response. Otherwise, the peer does not support `option_upfront_shutdownscript`. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **funding_address** (string): The address to send funding to for the channel +- **scriptpubkey** (hex): The raw scriptPubkey for the address +- **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` +[comment]: # (GENERATE-FROM-SCHEMA-END) On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -75,3 +78,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:9417a2d8d48b69f3557b08984d6b362e20cf20eeefcbef168fdc84b6f1de6411) diff --git a/doc/lightning-fundpsbt.7 b/doc/lightning-fundpsbt.7 index 160885b3e..b7c12cc51 100644 --- a/doc/lightning-fundpsbt.7 +++ b/doc/lightning-fundpsbt.7 @@ -122,4 +122,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:6420ab94377f1a25df686e97e79da3c67c69f99978b6177432426dfd45296052 +\" SHA256STAMP:b02d5c31f0fe6b5423871f4f5859519b41a882388d17f460bd7331f714880126 diff --git a/doc/lightning-fundpsbt.7.md b/doc/lightning-fundpsbt.7.md index 9e15a668d..ae5bde389 100644 --- a/doc/lightning-fundpsbt.7.md +++ b/doc/lightning-fundpsbt.7.md @@ -110,3 +110,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:25b32367f5bbf6f1e53036c38b7b7d19eebf62fa749a3ab580e4093eedc88584) diff --git a/doc/lightning-getinfo.7 b/doc/lightning-getinfo.7 index 92bab929a..402fc691b 100644 --- a/doc/lightning-getinfo.7 +++ b/doc/lightning-getinfo.7 @@ -22,43 +22,69 @@ The \fBgetinfo\fR gives a summary of the current running node\. .fi .SH RETURN VALUE -On success, an object with the following information is returned: +On success, an object is returned, containing: .RS .IP \[bu] -\fIid\fR: A string that represents the public key of the node\. It will represents the node on the public network\. +\fBid\fR (pubkey): The public key unique to this node .IP \[bu] -\fIalias\fR: A string that represents the alias of the node, by default is calculate from the public key (node id)\. This is just for fun; the name can be anything and is not unique! +\fBalias\fR (string): The fun alias this node will advertize (up to 32 characters) .IP \[bu] -\fIcolor\fR: A string that represents the preferred color of the node\. +\fBcolor\fR (hex): The favorite RGB color this node will advertize (always 6 characters) .IP \[bu] -\fInum_peers\fR: An integer that represents the number of peer connect to the node\. +\fBnum_peers\fR (u32): The total count of peers, connected or with channels .IP \[bu] -\fInum_pending_channels\fR: An integer that represents the number of channel which are still awaiting opening confirmation\. +\fBnum_pending_channels\fR (u32): The total count of channels being opened .IP \[bu] -\fInum_active_channels\fR: A integer that represents the number of channel which are currently open\. +\fBnum_active_channels\fR (u32): The total count of channels in normal state .IP \[bu] -\fInum_inactive_channels\fR: A integer that represents the number of channel which are closing\. +\fBnum_inactive_channels\fR (u32): The total count of channels waiting for opening or closing transactions to be mined .IP \[bu] -\fIaddress\fR: An array that represents all published addresses of the node, each object inside the array contains the following proprieties: +\fBversion\fR (string): Identifies what bugs you are running into +.IP \[bu] +\fBlightning-dir\fR (string): Identifies where you can find the configuration and other related files +.IP \[bu] +\fBblockheight\fR (u32): The highest block height we've learned +.IP \[bu] +\fBnetwork\fR (string): represents the type of network on the node are working (e\.g: \fBbitcoin\fR, \fBtestnet\fR, or \fBregtest\fR) +.IP \[bu] +\fBfees_collected_msat\fR (msat): Total routing fees collected by this node +.IP \[bu] +\fBaddress\fR (array of objects, optional): The addresses we announce to the world: .RS .IP \[bu] -\fItype\fR: A string that represents the type of the address (currently \fBipv4\fR, \fBipv6\fR, \fBtorv3\fR or \fBtorv4\fR)\. +\fBtype\fR (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3") .IP \[bu] -\fIaddress\fR: A string that represents the value of the address\. +\fBaddress\fR (string): address in expected format for \fBtype\fR .IP \[bu] -\fIport\fR: An integer that represents the port where the node is listening with this address\. +\fBport\fR (u16): port number .RE .IP \[bu] -\fIbinding\fR: An array that represents all addresses where the node is binded\. Each object contains the same object type of the address propriety above\. +\fBbinding\fR (array of objects, optional): The addresses we are listening on: +.RS .IP \[bu] -\fIversion\fR: A string that represents the version of the node\. +\fBtype\fR (string): Type of connection (one of "local socket", "ipv4", "ipv6", "torv2", "torv3") .IP \[bu] -\fIblockheight\fR: An integer that represents the blockchain height\. +\fBaddress\fR (string, optional): address in expected format for \fBtype\fR .IP \[bu] -\fInetwork\fR: A string that represents the type of network on the node are working (e\.g: \fBbitcoin\fR, \fBtestnet\fR, or \fBregtest\fR)\. +\fBport\fR (u16, optional): port number +.IP \[bu] +\fBsocket\fR (string, optional): socket filename (only if \fBtype\fR is "local socket") + +.RE + + +.RE + +The following warnings may also be returned: + +.RS +.IP \[bu] +\fBwarning_bitcoind_sync\fR: Bitcoind is not up-to-date with network\. +.IP \[bu] +\fBwarning_lightningd_sync\fR: Lightningd is still loading latest blocks from bitcoind\. .RE @@ -121,4 +147,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:9e6a0e0c25569bfc9d23b07e84392a3f70f6c94a86cd482fbf48c3d668a1796d +\" SHA256STAMP:637babe08b35ca524666bc51f1d0191e2006064af2b4c22997fbbe49cc7f935c diff --git a/doc/lightning-getinfo.7.md b/doc/lightning-getinfo.7.md index a5e09b231..3419953ea 100644 --- a/doc/lightning-getinfo.7.md +++ b/doc/lightning-getinfo.7.md @@ -25,23 +25,34 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, an object with the following information is returned: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **id** (pubkey): The public key unique to this node +- **alias** (string): The fun alias this node will advertize (up to 32 characters) +- **color** (hex): The favorite RGB color this node will advertize (always 6 characters) +- **num_peers** (u32): The total count of peers, connected or with channels +- **num_pending_channels** (u32): The total count of channels being opened +- **num_active_channels** (u32): The total count of channels in normal state +- **num_inactive_channels** (u32): The total count of channels waiting for opening or closing transactions to be mined +- **version** (string): Identifies what bugs you are running into +- **lightning-dir** (string): Identifies where you can find the configuration and other related files +- **blockheight** (u32): The highest block height we've learned +- **network** (string): represents the type of network on the node are working (e.g: `bitcoin`, `testnet`, or `regtest`) +- **fees_collected_msat** (msat): Total routing fees collected by this node +- **address** (array of objects, optional): The addresses we announce to the world: + - **type** (string): Type of connection (one of "ipv4", "ipv6", "torv2", "torv3") + - **address** (string): address in expected format for **type** + - **port** (u16): port number +- **binding** (array of objects, optional): The addresses we are listening on: + - **type** (string): Type of connection (one of "local socket", "ipv4", "ipv6", "torv2", "torv3") + - **address** (string, optional): address in expected format for **type** + - **port** (u16, optional): port number + - **socket** (string, optional): socket filename (only if **type** is "local socket") -- *id*: A string that represents the public key of the node. It will represents the node on the public network. -- *alias*: A string that represents the alias of the node, by default is calculate from the public key (node id). This is just for fun; the name can be anything and is not unique! -- *color*: A string that represents the preferred color of the node. -- *num_peers*: An integer that represents the number of peer connect to the node. -- *num_pending_channels*: An integer that represents the number of channel which are still awaiting opening confirmation. -- *num_active_channels*: A integer that represents the number of channel which are currently open. -- *num_inactive_channels*: A integer that represents the number of channel which are closing. -- *address*: An array that represents all published addresses of the node, each object inside the array contains the following proprieties: - - *type*: A string that represents the type of the address (currently `ipv4`, `ipv6`, `torv3` or `torv4`). - - *address*: A string that represents the value of the address. - - *port*: An integer that represents the port where the node is listening with this address. -- *binding*: An array that represents all addresses where the node is binded. Each object contains the same object type of the address propriety above. -- *version*: A string that represents the version of the node. -- *blockheight*: An integer that represents the blockchain height. -- *network*: A string that represents the type of network on the node are working (e.g: `bitcoin`, `testnet`, or `regtest`). +The following warnings may also be returned: +- **warning_bitcoind_sync**: Bitcoind is not up-to-date with network. +- **warning_lightningd_sync**: Lightningd is still loading latest blocks from bitcoind. +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -103,3 +114,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:2aa0f0cf9de7b2d373bdce8b337535a0197ad8cb1df2cdb0e043ba49c3704816) diff --git a/doc/lightning-getlog.7 b/doc/lightning-getlog.7 index 13eedfb04..2fe16a77e 100644 --- a/doc/lightning-getlog.7 +++ b/doc/lightning-getlog.7 @@ -29,31 +29,63 @@ The \fBgetlog\fR the RPC command to show logs, with optional log \fIlevel\fR\. .fi .SH RETURN VALUE -On success, a object will be return with the following parameters: +On success, an object is returned, containing: .RS .IP \[bu] -\fIcreated_at\fR: An floating point value that represents the UNIX timestamp when logging began\. +\fBcreated_at\fR (string): UNIX timestamp with 9 decimal places, when logging was initialized .IP \[bu] -\fIbytes_used\fR: A string that represents the dimension in bytes of the log file\. +\fBbytes_used\fR (u32): The number of bytes used by logging records .IP \[bu] -\fIbytes_max\fR: An integer that represents the max dimension in bytes of log file\. +\fBbytes_max\fR (u32): The bytes_used values at which records will be trimmed .IP \[bu] -\fIlog\fR: An array of objects where each element contains the following proprieties: + +\fBlog\fR (array of objects): + .RS .IP \[bu] -\fItype\fR: A string that represents the log level\. The propriety can have an value equal to SKIPPED to indicate the existence of omitted entries\. -.IP \[bu] -\fItime\fR: A floating point value that represents the time since \fIcreated_at\fR\. -.IP \[bu] -\fIsource\fR: A string that represents the source of line\. -.IP \[bu] -\fIlog\fR: A string that represents the content of line\. +\fBtype\fR (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") .RE +If \fBtype\fR is "SKIPPED": + +.RS .IP \[bu] -\fInum_skipped\fR: An integer that it is present only if the log level is equal to SKIPPED\. +\fBnum_skipped\fR (u32): number of unprinted log entries (deleted or below \fIlevel\fR parameter) + +.RE + +If \fBtype\fR is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + +.RS +.IP \[bu] +\fBtime\fR (string): UNIX timestamp with 9 decimal places after \fBcreated_at\fR +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The actual log message +.IP \[bu] +\fBnode_id\fR (pubkey, optional): The peer this is associated with + +.RE + +If \fBtype\fR is "IO_IN" or "IO_OUT": + +.RS +.IP \[bu] +\fBtime\fR (string): Seconds after \fBcreated_at\fR, with 9 decimal places +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The associated log message +.IP \[bu] +\fBdata\fR (hex): The IO which occurred +.IP \[bu] +\fBnode_id\fR (pubkey, optional): The peer this is associated with + +.RE + .RE @@ -95,4 +127,4 @@ Vincenzo Palazzo \fI wrote the initial versi Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:789e23927120d0fefd374592a3c655244fd6c28a122368bdd8da2f3cdde66798 +\" SHA256STAMP:13e3ab43fb6811bff8bee102ba85e7d4cb8eb97d11bb0720ae5c0c576ba021ec diff --git a/doc/lightning-getlog.7.md b/doc/lightning-getlog.7.md index dad81dc0f..4fffb2d8d 100644 --- a/doc/lightning-getlog.7.md +++ b/doc/lightning-getlog.7.md @@ -28,18 +28,30 @@ EXAMPLE JSON REQUEST RETURN VALUE ------------ -On success, a object will be return with the following parameters: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **created_at** (string): UNIX timestamp with 9 decimal places, when logging was initialized +- **bytes_used** (u32): The number of bytes used by logging records +- **bytes_max** (u32): The bytes_used values at which records will be trimmed +- **log** (array of objects): + - **type** (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") -- *created_at*: An floating point value that represents the UNIX timestamp when logging began. -- *bytes_used*: A string that represents the dimension in bytes of the log file. -- *bytes_max*: An integer that represents the max dimension in bytes of log file. -- *log*: An array of objects where each element contains the following proprieties: - - *type*: A string that represents the log level. The propriety can have an value equal to SKIPPED to indicate the existence of omitted entries. - - *time*: A floating point value that represents the time since *created_at*. - - *source*: A string that represents the source of line. - - *log*: A string that represents the content of line. -- *num_skipped*: An integer that it is present only if the log level is equal to SKIPPED. - + If **type** is "SKIPPED": + - **num_skipped** (u32): number of unprinted log entries (deleted or below *level* parameter) + + If **type** is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + - **time** (string): UNIX timestamp with 9 decimal places after **created_at** + - **source** (string): The particular logbook this was found in + - **log** (string): The actual log message + - **node_id** (pubkey, optional): The peer this is associated with + + If **type** is "IO_IN" or "IO_OUT": + - **time** (string): Seconds after **created_at**, with 9 decimal places + - **source** (string): The particular logbook this was found in + - **log** (string): The associated log message + - **data** (hex): The IO which occurred + - **node_id** (pubkey, optional): The peer this is associated with +[comment]: # (GENERATE-FROM-SCHEMA-END) On failure, one of the following error codes may be returned: @@ -77,3 +89,4 @@ RESOURCES --------- Main web site: +[comment]: # ( SHA256STAMP:db99eeb155bb44ebda8b77afdc1fad773e82fa8892e1df6afd61c60a1f4b7ec3) diff --git a/doc/lightning-getroute.7 b/doc/lightning-getroute.7 index 70f2675d9..3d2d9c88c 100644 --- a/doc/lightning-getroute.7 +++ b/doc/lightning-getroute.7 @@ -111,17 +111,29 @@ factor for larger amounts, and is basically ignored for tiny ones\. .SH RETURN VALUE -On success, a "route" array is returned\. Each array element contains -\fIid\fR (the node being routed through), \fImsatoshi\fR (the millisatoshis -sent), \fIamount_msat\fR (the same, with \fImsat\fR appended), \fIdelay\fR (the -number of blocks to timeout at this node), and \fIstyle\fR (indicating -the features which can be used for this hop)\. +On success, an object containing \fBroute\fR is returned\. It is an array of objects, where each object contains: +.RS +.IP \[bu] +\fBid\fR (pubkey): The node at the end of this hop +.IP \[bu] +\fBchannel\fR (short_channel_id): The channel joining these nodes +.IP \[bu] +\fBdirection\fR (u32): 0 if this channel is traversed from lesser to greater \fBid\fR, otherwise 1 +.IP \[bu] +\fBamount_msat\fR (msat): The amount expected by the node at the end of this hop +.IP \[bu] +\fBdelay\fR (u32): The total CLTV expected by the node at the end of this hop +.IP \[bu] +\fBstyle\fR (string): The features understood by the destination node (one of "legacy", "tlv") + +.RE The final \fIid\fR will be the destination \fIid\fR given in the input\. The difference between the first \fImsatoshi\fR minus the \fImsatoshi\fR given in -the input is the fee\. The first \fIdelay\fR is the very worst case timeout -for the payment failure, in blocks\. +the input is the fee (assuming the first hop is free)\. The first +\fIdelay\fR is the very worst case timeout for the payment failure, in +blocks\. .SH AUTHOR @@ -135,4 +147,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:52fe58e923c36f62601e6cb2779031d0428d3561bdeae2ab8eadf3dff84a3179 +\" SHA256STAMP:aaf1dab77352de52f8bf8a5c3e4a6449769b5dbfa51bdbf9b1a06575c8ae37fe diff --git a/doc/lightning-getroute.7.md b/doc/lightning-getroute.7.md index 435e3142c..1c84d58fc 100644 --- a/doc/lightning-getroute.7.md +++ b/doc/lightning-getroute.7.md @@ -277,16 +277,21 @@ factor for larger amounts, and is basically ignored for tiny ones. RETURN VALUE ------------ -On success, a "route" array is returned. Each array element contains -*id* (the node being routed through), *msatoshi* (the millisatoshis -sent), *amount\_msat* (the same, with *msat* appended), *delay* (the -number of blocks to timeout at this node), and *style* (indicating -the features which can be used for this hop). +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **route** is returned. It is an array of objects, where each object contains: +- **id** (pubkey): The node at the end of this hop +- **channel** (short_channel_id): The channel joining these nodes +- **direction** (u32): 0 if this channel is traversed from lesser to greater **id**, otherwise 1 +- **amount_msat** (msat): The amount expected by the node at the end of this hop +- **delay** (u32): The total CLTV expected by the node at the end of this hop +- **style** (string): The features understood by the destination node (one of "legacy", "tlv") +[comment]: # (GENERATE-FROM-SCHEMA-END) The final *id* will be the destination *id* given in the input. The difference between the first *msatoshi* minus the *msatoshi* given in -the input is the fee. The first *delay* is the very worst case timeout -for the payment failure, in blocks. +the input is the fee (assuming the first hop is free). The first +*delay* is the very worst case timeout for the payment failure, in +blocks. AUTHOR ------ @@ -303,3 +308,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:c15c56751270e8a3df25f3e3f72fbe8ea56366e5fe1157a8485b85cec1878982) diff --git a/doc/schemas/disableoffer.schema.json b/doc/schemas/disableoffer.schema.json new file mode 100644 index 000000000..6b745c8b7 --- /dev/null +++ b/doc/schemas/disableoffer.schema.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "offer_id", "active", "single_use", "bolt12", "used" ], + "additionalProperties": false, + "properties": { + "offer_id": { + "type": "hex", + "description": "the merkle hash of the offer", + "maxLength": 64, + "minLength": 64 + }, + "active": { + "type": "boolean", + "enum": [ "false" ], + "description": "Whether the offer can produce invoices/payments" + }, + "single_use": { + "type": "boolean", + "description": "Whether the offer is disabled after first successful use" + }, + "bolt12": { + "type": "string", + "description": "The bolt12 string representing this offer" + }, + "used": { + "type": "boolean", + "description": "Whether the offer has had an invoice paid / payment made" + }, + "label": { + "type": "string", + "description": "The label provided when offer was created" + } + } +} diff --git a/doc/schemas/disconnect.schema.json b/doc/schemas/disconnect.schema.json new file mode 100644 index 000000000..b797a82c2 --- /dev/null +++ b/doc/schemas/disconnect.schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "properties": { + } +} diff --git a/doc/schemas/feerates.schema.json b/doc/schemas/feerates.schema.json new file mode 100644 index 000000000..3f25817e7 --- /dev/null +++ b/doc/schemas/feerates.schema.json @@ -0,0 +1,119 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ ], + "properties": { + "warning_missing_feerates": { + "type": "string", + "description": "Some fee estimates are missing" + }, + "perkb": { + "type": "object", + "description": "If *style* parameter was perkb", + "additionalProperties": false, + "required": [ "min_acceptable", "max_acceptable" ], + "properties": { + "min_acceptable": { + "type": "u32", + "description": "The smallest feerate that you can use, usually the minimum relayed feerate of the backend" + }, + "max_acceptable": { + "type": "u32", + "description": "The largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)." + }, + "opening": { + "type": "u32", + "description": "Default feerate for lightning-fundchannel(7) and lightning-withdraw(7)" + }, + "mutual_close": { + "type": "u32", + "description": "Feerate to aim for in cooperative shutdown. Note that since mutual close is a **negotiation**, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer." + }, + "unilateral_close": { + "type": "u32", + "description": "Feerate for commitment_transaction in a live channel which we originally funded" + }, + "delayed_to_us": { + "type": "u32", + "description": "Feerate for returning unilateral close funds to our wallet" + }, + "htlc_resolution": { + "type": "u32", + "description": "Feerate for returning unilateral close HTLC outputs to our wallet" + }, + "penalty": { + "type": "u32", + "description": "Feerate to start at when penalizing a cheat attempt" + } + } + }, + "perkw": { + "type": "object", + "description": "If *style* parameter was perkw", + "additionalProperties": false, + "required": [ "min_acceptable", "max_acceptable" ], + "properties": { + "min_acceptable": { + "type": "u32", + "description": "The smallest feerate that you can use, usually the minimum relayed feerate of the backend" + }, + "max_acceptable": { + "type": "u32", + "description": "The largest feerate we will accept from remote negotiations. If a peer attempts to set the feerate higher than this we will unilaterally close the channel (or simply forget it if it's not open yet)." + }, + "opening": { + "type": "u32", + "description": "Default feerate for lightning-fundchannel(7) and lightning-withdraw(7)" + }, + "mutual_close": { + "type": "u32", + "description": "Feerate to aim for in cooperative shutdown. Note that since mutual close is a **negotiation**, the actual feerate used in mutual close will be somewhere between this and the corresponding mutual close feerate of the peer." + }, + "unilateral_close": { + "type": "u32", + "description": "Feerate for commitment_transaction in a live channel which we originally funded" + }, + "delayed_to_us": { + "type": "u32", + "description": "Feerate for returning unilateral close funds to our wallet" + }, + "htlc_resolution": { + "type": "u32", + "description": "Feerate for returning unilateral close HTLC outputs to our wallet" + }, + "penalty": { + "type": "u32", + "description": "Feerate to start at when penalizing a cheat attempt" + } + } + }, + "onchain_fee_estimates": { + "type": "object", + "additionalProperties": false, + "required": [ "opening_channel_satoshis", "mutual_close_satoshis", "unilateral_close_satoshis", "htlc_timeout_satoshis", "htlc_success_satoshis" ], + "properties": { + "opening_channel_satoshis": { + "type": "u64", + "description": "Estimated cost of typical channel open" + }, + "mutual_close_satoshis": { + "type": "u64", + "description": "Estimated cost of typical channel close" + }, + "unilateral_close_satoshis": { + "type": "u64", + "description": "Estimated cost of typical unilateral close (without HTLCs)" + }, + "htlc_timeout_satoshis": { + "type": "u64", + "description": "Estimated cost of typical HTLC timeout transaction" + }, + "htlc_success_satoshis": { + "type": "u64", + "description": "Estimated cost of typical HTLC fulfillment transaction" + } + } + } + } +} diff --git a/doc/schemas/fetchinvoice.schema.json b/doc/schemas/fetchinvoice.schema.json new file mode 100644 index 000000000..ff538b58c --- /dev/null +++ b/doc/schemas/fetchinvoice.schema.json @@ -0,0 +1,68 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "invoice", "changes" ], + "properties": { + "invoice": { + "type": "string", + "description": "The BOLT12 invoice we fetched" + }, + "changes": { + "type": "object", + "description": "Summary of changes from offer", + "additionalProperties": false, + "required": [ ], + "properties": { + "description_appended": { + "type": "string", + "description": "extra characters appended to the *description* field." + }, + "description": { + "type": "string", + "description": "a completely replaced *description* field" + }, + "vendor_removed": { + "type": "string", + "description": "The *vendor* from the offer, which is missing in the invoice" + }, + "vendor": { + "type": "string", + "description": "a completely replaced *vendor* field" + }, + "msat": { + "type": "msat", + "description": "the amount, if different from the offer amount multiplied by any *quantity* (or the offer had no amount, or was not in BTC)." + } + } + }, + "next_period": { + "type": "object", + "description": "Only for recurring invoices if the next period is under the *recurrence_limit*", + "additionalProperties": false, + "required": [ "counter", "starttime", "endtime", "paywindow_start", "paywindow_end" ], + "properties": { + "counter": { + "type": "u64", + "description": "the index of the next period to fetchinvoice" + }, + "starttime": { + "type": "u64", + "description": "UNIX timestamp that the next period starts" + }, + "endtime": { + "type": "u64", + "description": "UNIX timestamp that the next period ends" + }, + "paywindow_start": { + "type": "u64", + "description": "UNIX timestamp of the earliest time that the next invoice can be fetched" + }, + "paywindow_end": { + "type": "u64", + "description": "UNIX timestamp of the latest time that the next invoice can be fetched" + } + } + } + } +} diff --git a/doc/schemas/fundchannel.schema.json b/doc/schemas/fundchannel.schema.json new file mode 100644 index 000000000..44775d377 --- /dev/null +++ b/doc/schemas/fundchannel.schema.json @@ -0,0 +1,30 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "tx", "txid", "outnum", "channel_id" ], + "properties": { + "tx": { + "type": "hex", + "description": "The raw transaction which funded the channel" + }, + "txid": { + "type": "txid", + "description": "The txid of the transaction which funded the channel" + }, + "outnum": { + "type": "u32", + "description": "The 0-based output index showing which output funded the channel" + }, + "channel_id": { + "type": "hex", + "description": "The channel_id of the resulting channel", + "minLength": 64, + "maxLength": 64 + }, + "close_to": { + "type": "hex", + "description": "The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script`" + } + } +} diff --git a/doc/schemas/fundchannel_cancel.schema.json b/doc/schemas/fundchannel_cancel.schema.json new file mode 100644 index 000000000..a9e1e663e --- /dev/null +++ b/doc/schemas/fundchannel_cancel.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "cancelled" ], + "properties": { + "cancelled": { + "type": "string", + "description": "A message indicating it was cancelled by RPC" + } + } +} diff --git a/doc/schemas/fundchannel_complete.schema.json b/doc/schemas/fundchannel_complete.schema.json new file mode 100644 index 000000000..90b29faee --- /dev/null +++ b/doc/schemas/fundchannel_complete.schema.json @@ -0,0 +1,19 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "channel_id", "commitments_secured" ], + "properties": { + "channel_id": { + "type": "hex", + "description": "The channel_id of the resulting channel", + "minLength": 64, + "maxLength": 64 + }, + "commitments_secured": { + "type": "boolean", + "enum": [ true ], + "description": "Indication that channel is safe to use" + } + } +} diff --git a/doc/schemas/fundchannel_start.schema.json b/doc/schemas/fundchannel_start.schema.json new file mode 100644 index 000000000..335e1eb1f --- /dev/null +++ b/doc/schemas/fundchannel_start.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "funding_address", "scriptpubkey" ], + "properties": { + "funding_address": { + "type": "string", + "description": "The address to send funding to for the channel" + }, + "scriptpubkey": { + "type": "hex", + "description": "The raw scriptPubkey for the address" + }, + "close_to": { + "type": "hex", + "description": "The raw scriptPubkey which mutual close will go to; only present if *close_to* parameter was specified and peer supports `option_upfront_shutdown_script`" + } + } +} diff --git a/doc/schemas/fundpsbt.schema.json b/doc/schemas/fundpsbt.schema.json new file mode 100644 index 000000000..c93513622 --- /dev/null +++ b/doc/schemas/fundpsbt.schema.json @@ -0,0 +1,61 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "psbt", "feerate_per_kw", "estimated_final_weight", "excess_msat" ], + "properties": { + "psbt": { + "type": "string", + "description": "Unsigned PSBT which fulfills the parameters given" + }, + "feerate_per_kw": { + "type": "u32", + "description": "The feerate used to create the PSBT, in satoshis-per-kiloweight" + }, + "estimated_final_weight": { + "type": "u32", + "description": "The estimated weight of the transaction once fully signed" + }, + "excess_msat": { + "type": "msat", + "description": "The amount above *satoshi* which is available. This could be zero, or dust; it will be zero if *change_outnum* is also returned" + }, + "change_outnum": { + "type": "u32", + "description": "The 0-based output number where change was placed (only if parameter *excess_as_change* was true and there was sufficient funds)" + }, + "reservations": { + "type": "array", + "description": "If the *reserve* was true, just as per lightning-reserveinputs(7)", + "items": { + "type": "object", + "required": ["txid", "vout", "was_reserved", "reserved", "reserved_to_block" ], + "additionalProperties": false, + "properties": { + "txid": { + "type": "txid", + "description": "The txid of the transaction" + }, + "vout": { + "type": "u32", + "description": "The 0-based output number" + }, + "was_reserved": { + "type": "boolean", + "enum": [ false ], + "description": "Whether this output was previously reserved" + }, + "reserved": { + "type": "boolean", + "enum": [ true ], + "description": "Whether this output is now reserved" + }, + "reserved_to_block": { + "type": "u32", + "description": "The blockheight the reservation will expire" + } + } + } + } + } +} diff --git a/doc/schemas/getinfo.schema.json b/doc/schemas/getinfo.schema.json new file mode 100644 index 000000000..3c964fee2 --- /dev/null +++ b/doc/schemas/getinfo.schema.json @@ -0,0 +1,124 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "id", "alias", "color", "num_peers", "num_pending_channels", "num_active_channels", "num_inactive_channels", "version", "blockheight", "network", "fees_collected_msat", "lightning-dir" ], + "properties": { + "id": { + "type": "pubkey", + "description": "The public key unique to this node" + }, + "alias": { + "type": "string", + "description": "The fun alias this node will advertize", + "maxLength": 32 + }, + "color": { + "type": "hex", + "description": "The favorite RGB color this node will advertize", + "minLength": 6, + "maxLength": 6 + }, + "num_peers": { + "type": "u32", + "description": "The total count of peers, connected or with channels" + }, + "num_pending_channels": { + "type": "u32", + "description": "The total count of channels being opened" + }, + "num_active_channels": { + "type": "u32", + "description": "The total count of channels in normal state" + }, + "num_inactive_channels": { + "type": "u32", + "description": "The total count of channels waiting for opening or closing transactions to be mined" + }, + "version": { + "type": "string", + "description": "Identifies what bugs you are running into" + }, + "lightning-dir": { + "type": "string", + "description": "Identifies where you can find the configuration and other related files" + }, + "blockheight": { + "type": "u32", + "description": "The highest block height we've learned" + }, + "network": { + "type": "string", + "description": "represents the type of network on the node are working (e.g: `bitcoin`, `testnet`, or `regtest`)" + }, + "msatoshi_fees_collected": { + "type": "u64", + "deprecated": true + }, + "fees_collected_msat": { + "type": "msat", + "description": "Total routing fees collected by this node" + }, + "address": { + "type": "array", + "description": "The addresses we announce to the world", + "items": { + "type": "object", + "required": [ "type", "address", "port" ], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "enum": [ "ipv4", "ipv6", "torv2", "torv3" ], + "description": "Type of connection" + }, + "address": { + "type": "string", + "description": "address in expected format for **type**" + }, + "port": { + "type": "u16", + "description": "port number" + } + } + } + }, + "binding": { + "type": "array", + "description": "The addresses we are listening on", + "items": { + "type": "object", + "required": [ "type" ], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "*FIXME*": "The variant in connect.schema.json is more complete", + "enum": [ "local socket", "ipv4", "ipv6", "torv2", "torv3" ], + "description": "Type of connection" + }, + "address": { + "type": "string", + "description": "address in expected format for **type**" + }, + "port": { + "type": "u16", + "description": "port number" + }, + "socket": { + "type": "string", + "description": "socket filename (only if **type** is \"local socket\")" + } + } + } + }, + "warning_bitcoind_sync": { + "type": "string", + "description": "Bitcoind is not up-to-date with network." + }, + "warning_lightningd_sync": { + "type": "string", + "description": "Lightningd is still loading latest blocks from bitcoind." + } + } +} diff --git a/doc/schemas/getlog.schema.json b/doc/schemas/getlog.schema.json new file mode 100644 index 000000000..23c9981b5 --- /dev/null +++ b/doc/schemas/getlog.schema.json @@ -0,0 +1,127 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "created_at", "bytes_used", "bytes_max", "log" ], + "properties": { + "created_at": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places, when logging was initialized" + }, + "bytes_used": { + "type": "u32", + "description": "The number of bytes used by logging records" + }, + "bytes_max": { + "type": "u32", + "description": "The bytes_used values at which records will be trimmed " + }, + "log": { + "type": "array", + "items": { + "type": "object", + "required": [ "type" ], + "additionalProperties": true, + "properties": { + "type": { + "type": "string", + "enum": [ "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT" ] + } + }, + "allOf": [ + { + "if": { + "additionalProperties": true, + "properties": { + "type": { + "enum": [ "SKIPPED" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "num_skipped" ], + "properties": { + "type": { }, + "num_skipped": { + "type": "u32", + "description": "number of unprinted log entries (deleted or below *level* parameter)" + } + } + } + }, + { + "if": { + "additionalProperties": true, + "properties": { + "type": { + "enum": [ "BROKEN", "UNUSUAL", "INFO", "DEBUG" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "time", "source", "log" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places after **created_at**" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The actual log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + } + } + } + }, + { + "if": { + "additionalProperties": true, + "properties": { + "type": { + "enum": [ "IO_IN", "IO_OUT" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "time", "source", "log", "data" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "Seconds after **created_at**, with 9 decimal places" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The associated log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + }, + "data": { + "type": "hex", + "description": "The IO which occurred" + } + } + } + } + ] + } + } + } +} diff --git a/doc/schemas/getroute.schema.json b/doc/schemas/getroute.schema.json new file mode 100644 index 000000000..9e5ebe7eb --- /dev/null +++ b/doc/schemas/getroute.schema.json @@ -0,0 +1,47 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "route" ], + "properties": { + "route": { + "type": "array", + "items": { + "type": "object", + "required": [ "id", "direction", "channel", "amount_msat", "delay", "style" ], + "additionalProperties": false, + "properties": { + "id": { + "type": "pubkey", + "description": "The node at the end of this hop" + }, + "channel": { + "type": "short_channel_id", + "description": "The channel joining these nodes" + }, + "direction": { + "type": "u32", + "description": "0 if this channel is traversed from lesser to greater **id**, otherwise 1" + }, + "msatoshi": { + "type": "u64", + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "The amount expected by the node at the end of this hop" + }, + "delay": { + "type": "u32", + "description": "The total CLTV expected by the node at the end of this hop" + }, + "style": { + "type": "string", + "description": "The features understood by the destination node", + "enum": [ "legacy", "tlv" ] + } + } + } + } + } +} diff --git a/tests/test_misc.py b/tests/test_misc.py index e3ebd5685..c1dee2b55 100644 --- a/tests/test_misc.py +++ b/tests/test_misc.py @@ -2546,3 +2546,16 @@ def test_notimestamp_logging(node_factory): assert l1.daemon.logs[0].startswith("DEBUG") assert l1.rpc.listconfigs()['log-timestamps'] is False + + +def test_getlog(node_factory): + """Test the getlog command""" + l1 = node_factory.get_node(options={'log-level': 'io'}) + + # Default will skip some entries + logs = l1.rpc.getlog()['log'] + assert [l for l in logs if l['type'] == 'SKIPPED'] != [] + + # This should not + logs = l1.rpc.getlog(level='io')['log'] + assert [l for l in logs if l['type'] == 'SKIPPED'] == []