mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-03-11 01:27:58 +01:00
Code Issues Projects Releases Wiki Activity

doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute.

Browse source 
We also add a test for getlog, since it was never called by the
testsuite.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2021-05-26 17:05:01 +09:30
parent fbc2672074
commit ec83d7a8a5
37 changed files with 1093 additions and 257 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
doc/lightning-disableoffer.7 generated
View file

@ -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<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:55cfb050fa2d28f58750dc74659d9f7bc5ec00499e218ccffd058db51efc38d2
\" SHA256STAMP:33b8cddae4a830e710906268c1d0d301442bc7ab0711e1d6ce670f86c77ae320

14
doc/lightning-disableoffer.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:6b0ae21e38a83742735f38e9c022b33ed4a436cacc746ff22e63d7b00779e4d0)

2
doc/lightning-disconnect.7 generated
View file

@ -63,4 +63,4 @@ Michael Hawkins \fI<michael.hawkins@protonmail.com\fR>\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:fe16ccb06f56e5b59a1aea19b1a6625624b93e668cd07bba9e3f581873fa3eab
\" SHA256STAMP:7efc0fbbb7397d3767ea170ba091b5bc00f4efaf8e1283c7b7ed1aaaccfd3c4d

3
doc/lightning-disconnect.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:f974a3848c4db5b73fffa969a741ef6619c9a375783fabe731882d84a6bbf5ff)

100
doc/lightning-feerates.7 generated
View file

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

70
doc/lightning-feerates.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:e16ae963e528995f1e01c80b4ed4e9b0d6c457a559928e98ab6cf32624557894)

64
doc/lightning-fetchinvoice.7 generated
View file

@ -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<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:a96df8e4f480c093c83268688d683db82575341ecb4176ab586eae9baf69d9c1
\" SHA256STAMP:23be8c105314c109fa0f7c532c3eebf9b2cbe47f520d600d3d2159765def3cbd

40
doc/lightning-fetchinvoice.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:e2b81ad7a61dd6a6d55e21c5367c3286aaf00cee734b2719a8e38bc87f7ac8aa)

23
doc/lightning-fundchannel.7 generated
View file

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

17
doc/lightning-fundchannel.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:5b17c334b90f840a986750f9fcdb6a6bfa79bd1a3da11319a1957ba87bc4b0a7)

10
doc/lightning-fundchannel_cancel.7 generated
View file

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

7
doc/lightning-fundchannel_cancel.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:f639e58991b8a9b58b181e9f4bd325fb24368af5cb76f94a94ca21675421829b)

12
doc/lightning-fundchannel_complete.7 generated
View file

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

8
doc/lightning-fundchannel_complete.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:7cb52658d81c5834e34a6011c04283bf740fe6e5feedb0208778abad5fddc519)

15
doc/lightning-fundchannel_start.7 generated
View file

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

10
doc/lightning-fundchannel_start.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:9417a2d8d48b69f3557b08984d6b362e20cf20eeefcbef168fdc84b6f1de6411)

2
doc/lightning-fundpsbt.7 generated
View file

@ -122,4 +122,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:6420ab94377f1a25df686e97e79da3c67c69f99978b6177432426dfd45296052
\" SHA256STAMP:b02d5c31f0fe6b5423871f4f5859519b41a882388d17f460bd7331f714880126

1
doc/lightning-fundpsbt.7.md
View file

@ -110,3 +110,4 @@ RESOURCES
Main web site: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:25b32367f5bbf6f1e53036c38b7b7d19eebf62fa749a3ab580e4093eedc88584)

60
doc/lightning-getinfo.7 generated
View file

@ -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<vincenzo.palazzo@protonmail.com\fR> wrote the initial versi
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:9e6a0e0c25569bfc9d23b07e84392a3f70f6c94a86cd482fbf48c3d668a1796d
\" SHA256STAMP:637babe08b35ca524666bc51f1d0191e2006064af2b4c22997fbbe49cc7f935c

44
doc/lightning-getinfo.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:2aa0f0cf9de7b2d373bdce8b337535a0197ad8cb1df2cdb0e043ba49c3704816)

60
doc/lightning-getlog.7 generated
View file

@ -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<vincenzo.palazzo@protonmail.com\fR> wrote the initial versi
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:789e23927120d0fefd374592a3c655244fd6c28a122368bdd8da2f3cdde66798
\" SHA256STAMP:13e3ab43fb6811bff8bee102ba85e7d4cb8eb97d11bb0720ae5c0c576ba021ec

35
doc/lightning-getlog.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:db99eeb155bb44ebda8b77afdc1fad773e82fa8892e1df6afd61c60a1f4b7ec3)

28
doc/lightning-getroute.7 generated
View file

@ -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<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:52fe58e923c36f62601e6cb2779031d0428d3561bdeae2ab8eadf3dff84a3179
\" SHA256STAMP:aaf1dab77352de52f8bf8a5c3e4a6449769b5dbfa51bdbf9b1a06575c8ae37fe

20
doc/lightning-getroute.7.md
View file

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:c15c56751270e8a3df25f3e3f72fbe8ea56366e5fe1157a8485b85cec1878982)

35
doc/schemas/disableoffer.schema.json Normal file
View file

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

7
doc/schemas/disconnect.schema.json Normal file
View file

@ -0,0 +1,7 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"properties": {
}
}

119
doc/schemas/feerates.schema.json Normal file
View file

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

68
doc/schemas/fetchinvoice.schema.json Normal file
View file

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

30
doc/schemas/fundchannel.schema.json Normal file
View file

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

12
doc/schemas/fundchannel_cancel.schema.json Normal file
View file

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

19
doc/schemas/fundchannel_complete.schema.json Normal file
View file

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

20
doc/schemas/fundchannel_start.schema.json Normal file
View file

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

61
doc/schemas/fundpsbt.schema.json Normal file
View file

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

124
doc/schemas/getinfo.schema.json Normal file
View file

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

127
doc/schemas/getlog.schema.json Normal file
View file

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

47
doc/schemas/getroute.schema.json Normal file
View file

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

13
tests/test_misc.py
View file

@ -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'] == []