From 5c7f9b542aece3e5330faaf16e2c44e9cbd5cd94 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj jxPCSnmZ Date: Mon, 10 Feb 2020 03:57:22 +0000 Subject: [PATCH] doc/lightning-listpeers.7.md: Expand and correct. ChangeLog-Fixed: Corrected and expanded `lightning-listpeers.7` documentation. --- doc/lightning-listpeers.7 | 226 ++++++++++++++++++++++++++++++++++- doc/lightning-listpeers.7.md | 165 ++++++++++++++++++++++++- 2 files changed, 387 insertions(+), 4 deletions(-) diff --git a/doc/lightning-listpeers.7 b/doc/lightning-listpeers.7 index 70305ffd5d24..5bf11d928ad3 100644 --- a/doc/lightning-listpeers.7 +++ b/doc/lightning-listpeers.7 @@ -57,7 +57,7 @@ Each object in the list contains the following data: .IP \[bu] \fIfeatures\fR : Bit flags showing supported features (BOLT #9) .IP \[bu] -\fIchannels\fR : An list of channel id’s open on the peer +\fIchannels\fR : An array of objects describing channels with the peer\. .IP \[bu] \fIlog\fR : Only present if \fIlevel\fR is set\. List logs related to the peer at the specified \fIlevel\fR @@ -68,6 +68,228 @@ If \fIid\fR is supplied and no matching nodes are found, a "peers" object with an empty list is returned\. +The objects in the \fIchannels\fR array will have at least these fields: + +.RS +.IP \[bu] +\fIstate\fR: Any of these strings:.RS +.IP \[bu] +\fB"OPENINGD"\fR: The channel funding protocol with the peer is ongoing +and both sides are negotiating parameters\. +.IP \[bu] +\fB"CHANNELD_AWAITING_LOCKIN"\fR: The peer and you have agreed on channel +parameters and are just waiting for the channel funding transaction to +be confirmed deeply\. +Both you and the peer must acknowledge the channel funding transaction +to be confirmed deeply before entering the next state\. +.IP \[bu] +\fB"CHANNELD_NORMAL"\fR: The channel can be used for normal payments\. +.IP \[bu] +\fB"CHANNELD_SHUTTING_DOWN"\fR: A mutual close was requested (by you or +peer) and both of you are waiting for HTLCs in-flight to be either +failed or succeeded\. +The channel can no longer be used for normal payments and forwarding\. +Mutual close will proceed only once all HTLCs in the channel have +either been fulfilled or failed\. +.IP \[bu] +\fB"CLOSINGD_SIGEXCHANGE"\fR: You and the peer are negotiating the mutual +close onchain fee\. +.IP \[bu] +\fB"CLOSINGD_COMPLETE"\fR: You and the peer have agreed on the mutual close +onchain fee and are awaiting the mutual close getting confirmed deeply\. +.IP \[bu] +\fB"AWAITING_UNILATERAL"\fR: You initiated a unilateral close, and are now +waiting for the peer-selected unilateral close timeout to complete\. +.IP \[bu] +\fB"FUNDING_SPEND_SEEN"\fR: You saw the funding transaction getting +spent (usually the peer initiated a unilateral close) and will now +determine what exactly happened (i\.e\. if it was a theft attempt)\. +.IP \[bu] +\fB"ONCHAIN"\fR: You saw the funding transaction getting spent and now +know what happened (i\.e\. if it was a proper unilateral close by the +peer, or a theft attempt)\. +.IP \[bu] +\fB"CLOSED"\fR: The channel closure has been confirmed deeply\. +The channel will eventually be removed from this array\. + +.RE + +.IP \[bu] +\fIstatus\fR: An array of strings containing the most important log messages +relevant to this channel\. +Also known as the "billboard"\. +.IP \[bu] +\fIowner\fR: A string describing which particular sub-daemon of \fBlightningd\fR +currently is responsible for this channel\. +One of: \fB"lightning_openingd"\fR, \fB"lightning_channeld"\fR, +\fB"lightning_closingd"\fR, \fB"lightning_onchaind"\fR\. +.IP \[bu] +\fIto_us_msat\fR: A string describing how much of the funds is owned by us; +a number followed by a string unit\. +.IP \[bu] +\fItotal_msat\fR: A string describing the total capacity of the channel; +a number followed by a string unit\. + +.RE + +These fields may exist if the channel has gotten beyond the \fB"OPENINGD"\fR +state, or in various circumstances: + +.RS +.IP \[bu] +\fIshort_channel_id\fR: A string of the short channel ID for the channel; +Format is \fB"BBBBxTTTxOOO"\fR, where \fB"BBBB"\fR is the numeric block height +at which the funding transaction was confirmed, \fB"TTT"\fR is the numeric +funding transaction index within that block, and \fB"OOO"\fR is the +numeric output index of the transaction output that actually anchors +this channel\. +.IP \[bu] +\fIdirection\fR: The channel-direction we own, as per BOLT #7\. +We own channel-direction 0 if our node ID is "less than" the peer node ID +in a lexicographical ordering of our node IDs, otherwise we own +channel-direction 1\. +Our \fBchannel_update\fR will use this \fIdirection\fR\. +.IP \[bu] +\fIchannel_id\fR: The full channel ID of the channel; +the funding transaction ID XORed with the output number\. +.IP \[bu] +\fIfunding_txid\fR: The funding transaction ID of the channel\. +.IP \[bu] +\fIclose_to\fR: The raw \fBscriptPubKey\fR that was indicated in the starting +\fBfundchannel_start\fR command and accepted by the peer\. +If the \fBscriptPubKey\fR encodes a standardized address, an additional +\fIclose_to_addr\fR field will be present with the standardized address\. +.IP \[bu] +\fIprivate\fR: A boolean, true if the channel is unpublished, false if the +channel is published\. +.IP \[bu] +\fIfunding_msat\fR: An object, whose field names are the node +IDs involved in the channel, and whose values are strings (numbers with +a unit suffix) indicating how much that node originally contributed in +opening the channel\. +.IP \[bu] +\fImin_to_us_msat\fR: A string describing the historic point at which +we owned the least amount of funds in this channel; +a number followed by a string unit\. +If the peer were to succesfully steal from us, this is the amount we +would still retain\. +.IP \[bu] +\fImax_to_us_msat\fR: A string describing the historic point at which +we owned the most amount of funds in this channel; +a number followed by a string unit\. +If we were to successfully steal from the peer, this is the amount we +could potentially get\. +.IP \[bu] +\fIdust_limit_msat\fR: A string describing an amount; +if an HTLC or the amount wholly-owned by one node is at or below this +amount, it will be considered "dusty" and will not appear in a close +transaction, and will be donated to miners as fee; +a number followed by a string unit\. +.IP \[bu] +\fImax_total_htlc_in_msat\fR: A string describing an amount; +the sum of all HTLCs in the channel cannot exceed this amount; +a number followed by a string unit\. +.IP \[bu] +\fItheir_reserve_msat\fR: A string describing the minimum amount that +the peer must keep in the channel when it attempts to send out; +if it has less than this in the channel, it cannot send to us on +that channel; +a number followed by a string unit\. +We impose this on them, default is 1% of the total channel capacity\. +.IP \[bu] +\fIour_reserve_msat\fR: A string describing the minimum amount that +you must keep in the channel when you attempt to send out; +if you have less than this in the channel, you cannot send out +via this channel; +a number followed by a string unit\. +The peer imposes this on us, default is 1% of the total channel capacity\. +.IP \[bu] +\fIspendable_msat\fR: A string describing an \fB\fIestimate\fR\fR of how much we +can send out over this channel; +a number followed by a string unit\. +This is an \fB\fIestimate\fR\fR, which can be wrong because adding HTLCs requires +an increase in fees paid to onchain miners, and onchain fees change +dynamically according to onchain activity\. +.IP \[bu] +\fIminimum_htlc_in_msat\fR: A string describing the minimum amount that +an HTLC must have before we accept it\. +.IP \[bu] +\fItheir_to_self_delay\fR: The number of blocks that the peer must wait +to claim their funds, if they close unilaterally\. +.IP \[bu] +\fIour_to_self_delay\fR: The number of blocks that you must wait to claim +your funds, if you close unilaterally\. +.IP \[bu] +\fImax_accepted_htlcs\fR: The maximum number of HTLCs you will accept on +this channel\. +.IP \[bu] +\fIin_payments_offered\fR: The number of incoming HTLCs offered over this +channel\. +.IP \[bu] +\fIin_offered_msat\fR: A string describing the total amount of all incoming +HTLCs offered over this channel; +a number followed by a string unit\. +.IP \[bu] +\fIin_payments_fulfilled\fR: The number of incoming HTLCs offered \fIand +successfully claimed\fR over this channel\. +.IP \[bu] +\fIin_fulfilled_msat\fR: A string describing the total amount of all +incoming HTLCs offered \fIand successfully claimed\fR over this channel; +a number followed by a string unit\. +.IP \[bu] +\fIout_payments_offered\fR: The number of outgoing HTLCs offered over +this channel\. +.IP \[bu] +\fIout_offered_msat\fR: A string describing the total amount of all +outgoing HTLCs offered over this channel; +a number followed by a string unit\. +.IP \[bu] +\fIout_payments_fulfilled\fR: The number of outgoing HTLCs offered \fIand +successfully claimed\fR over this channel\. +.IP \[bu] +\fIout_fulfilled_msat\fR: A string describing the total amount of all +outgoing HTLCs offered \fIand successfully claimed\fR over this channel; +a number followed by a string unit\. +.IP \[bu] +\fIhtlcs\fR: An array of objects describing the HTLCs currently in-flight +in the channel\. + +.RE + +Objects in the \fIhtlcs\fR array will contain these fields: + +.RS +.IP \[bu] +\fIdirection\fR: Either the string \fB"out"\fR or \fB"in"\fR, whether it is an +outgoing or incoming HTLC\. +.IP \[bu] +\fIid\fR: A numeric ID uniquely identifying this HTLC\. +.IP \[bu] +\fIamount_msat\fR: The value of the HTLC\. +.IP \[bu] +\fIexpiry\fR: The blockheight at which the HTLC will be forced to return +to its offerer: an \fB"in"\fR HTLC will be returned to the peer, an +\fB"out"\fR HTLC will be returned to you\. +\fBNOTE\fR If the \fIexpiry\fR of any outgoing HTLC will arrive in the next +block, \fBlightningd\fR(8) will automatically unilaterally close the +channel in order to enforce the timeout onchain\. +.IP \[bu] +\fIpayment_hash\fR: The payment hash, whose preimage must be revealed to +successfully claim this HTLC\. +.IP \[bu] +\fIstate\fR: A string describing whether the HTLC has been communicated to +or from the peer, whether it has been signed in a new commitment, whether +the previous commitment (that does not contain it) has been revoked, as +well as when the HTLC is fulfilled or failed offchain\. +.IP \[bu] +\fIlocal_trimmed\fR: A boolean, existing and \fBtrue\fR if the HTLC is not +actually instantiated as an output (i\.e\. "trimmed") on the commitment +transaction (and will not be instantiated on a unilateral close)\. +Generally true if the HTLC is below the \fIdust_limit_msat\fR for the +channel\. + +.RE + On error the returned object will contain \fBcode\fR and \fBmessage\fR properties, with \fBcode\fR being one of the following: @@ -82,7 +304,7 @@ Michael Hawkins \fI\. .SH SEE ALSO -\fBlightning-connect\fR(7) +\fBlightning-connect\fR(7), lightning-fundchannel_\fBstart\fR(7) .SH RESOURCES diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md index 54d083a0286b..c69ffb4b6a73 100644 --- a/doc/lightning-listpeers.7.md +++ b/doc/lightning-listpeers.7.md @@ -46,13 +46,174 @@ Each object in the list contains the following data: - *connected* : A boolean value showing the connection status - *netaddr* : A list of network addresses the node is listening on - *features* : Bit flags showing supported features (BOLT \#9) -- *channels* : An list of channel id’s open on the peer +- *channels* : An array of objects describing channels with the peer. - *log* : Only present if *level* is set. List logs related to the peer at the specified *level* If *id* is supplied and no matching nodes are found, a "peers" object with an empty list is returned. +The objects in the *channels* array will have at least these fields: + +* *state*: Any of these strings: + * `"OPENINGD"`: The channel funding protocol with the peer is ongoing + and both sides are negotiating parameters. + * `"CHANNELD_AWAITING_LOCKIN"`: The peer and you have agreed on channel + parameters and are just waiting for the channel funding transaction to + be confirmed deeply. + Both you and the peer must acknowledge the channel funding transaction + to be confirmed deeply before entering the next state. + * `"CHANNELD_NORMAL"`: The channel can be used for normal payments. + * `"CHANNELD_SHUTTING_DOWN"`: A mutual close was requested (by you or + peer) and both of you are waiting for HTLCs in-flight to be either + failed or succeeded. + The channel can no longer be used for normal payments and forwarding. + Mutual close will proceed only once all HTLCs in the channel have + either been fulfilled or failed. + * `"CLOSINGD_SIGEXCHANGE"`: You and the peer are negotiating the mutual + close onchain fee. + * `"CLOSINGD_COMPLETE"`: You and the peer have agreed on the mutual close + onchain fee and are awaiting the mutual close getting confirmed deeply. + * `"AWAITING_UNILATERAL"`: You initiated a unilateral close, and are now + waiting for the peer-selected unilateral close timeout to complete. + * `"FUNDING_SPEND_SEEN"`: You saw the funding transaction getting + spent (usually the peer initiated a unilateral close) and will now + determine what exactly happened (i.e. if it was a theft attempt). + * `"ONCHAIN"`: You saw the funding transaction getting spent and now + know what happened (i.e. if it was a proper unilateral close by the + peer, or a theft attempt). + * `"CLOSED"`: The channel closure has been confirmed deeply. + The channel will eventually be removed from this array. +* *status*: An array of strings containing the most important log messages + relevant to this channel. + Also known as the "billboard". +* *owner*: A string describing which particular sub-daemon of `lightningd` + currently is responsible for this channel. + One of: `"lightning_openingd"`, `"lightning_channeld"`, + `"lightning_closingd"`, `"lightning_onchaind"`. +* *to\_us\_msat*: A string describing how much of the funds is owned by us; + a number followed by a string unit. +* *total\_msat*: A string describing the total capacity of the channel; + a number followed by a string unit. + +These fields may exist if the channel has gotten beyond the `"OPENINGD"` +state, or in various circumstances: + +* *short\_channel\_id*: A string of the short channel ID for the channel; + Format is `"BBBBxTTTxOOO"`, where `"BBBB"` is the numeric block height + at which the funding transaction was confirmed, `"TTT"` is the numeric + funding transaction index within that block, and `"OOO"` is the + numeric output index of the transaction output that actually anchors + this channel. +* *direction*: The channel-direction we own, as per BOLT \#7. + We own channel-direction 0 if our node ID is "less than" the peer node ID + in a lexicographical ordering of our node IDs, otherwise we own + channel-direction 1. + Our `channel_update` will use this *direction*. +* *channel\_id*: The full channel ID of the channel; + the funding transaction ID XORed with the output number. +* *funding\_txid*: The funding transaction ID of the channel. +* *close\_to*: The raw `scriptPubKey` that was indicated in the starting + **fundchannel\_start** command and accepted by the peer. + If the `scriptPubKey` encodes a standardized address, an additional + *close\_to\_addr* field will be present with the standardized address. +* *private*: A boolean, true if the channel is unpublished, false if the + channel is published. +* *funding\_msat*: An object, whose field names are the node + IDs involved in the channel, and whose values are strings (numbers with + a unit suffix) indicating how much that node originally contributed in + opening the channel. +* *min\_to\_us\_msat*: A string describing the historic point at which + we owned the least amount of funds in this channel; + a number followed by a string unit. + If the peer were to succesfully steal from us, this is the amount we + would still retain. +* *max\_to\_us\_msat*: A string describing the historic point at which + we owned the most amount of funds in this channel; + a number followed by a string unit. + If we were to successfully steal from the peer, this is the amount we + could potentially get. +* *dust\_limit\_msat*: A string describing an amount; + if an HTLC or the amount wholly-owned by one node is at or below this + amount, it will be considered "dusty" and will not appear in a close + transaction, and will be donated to miners as fee; + a number followed by a string unit. +* *max\_total\_htlc\_in\_msat*: A string describing an amount; + the sum of all HTLCs in the channel cannot exceed this amount; + a number followed by a string unit. +* *their\_reserve\_msat*: A string describing the minimum amount that + the peer must keep in the channel when it attempts to send out; + if it has less than this in the channel, it cannot send to us on + that channel; + a number followed by a string unit. + We impose this on them, default is 1% of the total channel capacity. +* *our\_reserve\_msat*: A string describing the minimum amount that + you must keep in the channel when you attempt to send out; + if you have less than this in the channel, you cannot send out + via this channel; + a number followed by a string unit. + The peer imposes this on us, default is 1% of the total channel capacity. +* *spendable\_msat*: A string describing an ***estimate*** of how much we + can send out over this channel; + a number followed by a string unit. + This is an ***estimate***, which can be wrong because adding HTLCs requires + an increase in fees paid to onchain miners, and onchain fees change + dynamically according to onchain activity. +* *minimum\_htlc\_in\_msat*: A string describing the minimum amount that + an HTLC must have before we accept it. +* *their\_to\_self\_delay*: The number of blocks that the peer must wait + to claim their funds, if they close unilaterally. +* *our\_to\_self\_delay*: The number of blocks that you must wait to claim + your funds, if you close unilaterally. +* *max\_accepted\_htlcs*: The maximum number of HTLCs you will accept on + this channel. +* *in\_payments_offered*: The number of incoming HTLCs offered over this + channel. +* *in\_offered\_msat*: A string describing the total amount of all incoming + HTLCs offered over this channel; + a number followed by a string unit. +* *in\_payments\_fulfilled*: The number of incoming HTLCs offered *and + successfully claimed* over this channel. +* *in\_fulfilled\_msat*: A string describing the total amount of all + incoming HTLCs offered *and successfully claimed* over this channel; + a number followed by a string unit. +* *out\_payments\_offered*: The number of outgoing HTLCs offered over + this channel. +* *out\_offered\_msat*: A string describing the total amount of all + outgoing HTLCs offered over this channel; + a number followed by a string unit. +* *out\_payments\_fulfilled*: The number of outgoing HTLCs offered *and + successfully claimed* over this channel. +* *out\_fulfilled\_msat*: A string describing the total amount of all + outgoing HTLCs offered *and successfully claimed* over this channel; + a number followed by a string unit. +* *htlcs*: An array of objects describing the HTLCs currently in-flight + in the channel. + +Objects in the *htlcs* array will contain these fields: + +* *direction*: Either the string `"out"` or `"in"`, whether it is an + outgoing or incoming HTLC. +* *id*: A numeric ID uniquely identifying this HTLC. +* *amount\_msat*: The value of the HTLC. +* *expiry*: The blockheight at which the HTLC will be forced to return + to its offerer: an `"in"` HTLC will be returned to the peer, an + `"out"` HTLC will be returned to you. + **NOTE** If the *expiry* of any outgoing HTLC will arrive in the next + block, `lightningd`(8) will automatically unilaterally close the + channel in order to enforce the timeout onchain. +* *payment\_hash*: The payment hash, whose preimage must be revealed to + successfully claim this HTLC. +* *state*: A string describing whether the HTLC has been communicated to + or from the peer, whether it has been signed in a new commitment, whether + the previous commitment (that does not contain it) has been revoked, as + well as when the HTLC is fulfilled or failed offchain. +* *local\_trimmed*: A boolean, existing and `true` if the HTLC is not + actually instantiated as an output (i.e. "trimmed") on the commitment + transaction (and will not be instantiated on a unilateral close). + Generally true if the HTLC is below the *dust\_limit\_msat* for the + channel. + On error the returned object will contain `code` and `message` properties, with `code` being one of the following: @@ -66,7 +227,7 @@ Michael Hawkins <>. SEE ALSO -------- -lightning-connect(7) +lightning-connect(7), lightning-fundchannel\_start(7) RESOURCES ---------