Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIGHTNING-LISTPEERS(7)	      lightning-listpeers	LIGHTNING-LISTPEERS(7)

NAME
       lightning-listpeers  -  Command	returning  data	on connected lightning
       nodes

SYNOPSIS
       listpeers [id] [level]

DESCRIPTION
       The listpeers RPC command returns data on nodes that are	 connected  or
       are not connected but have open channels	with this node.

       Once a connection to another lightning node has been established, using
       the connect command, data on the	node can be returned  using  listpeers
       and the id that was used	with the connect command.

       If  no  id  is supplied,	then data on all lightning nodes that are con-
       nected, or not connected	but have open channels with this node, are re-
       turned.

       Supplying id will filter	the results to only return data	on a node with
       a matching id, if one exists.

       Supplying level will show log entries related to	that peer at the given
       log level. Valid	log levels are "io", "debug", "info", and "unusual".

       If a channel is open with a node	and the	connection has been lost, then
       the node	will still appear in the output	of the command and  the	 value
       of the connected	attribute of the node will be "false".

       The  channel  will  remain open for a set blocktime, after which	if the
       connection has not been re-established, the channel will	close and  the
       node will no longer appear in the command output.

RETURN VALUE
       On  success, an object with a "peers" key is returned containing	a list
       of 0 or more objects.

       Each object in the list contains	the following data:

	      o	     id	: The unique id	of the peer

	      o	     connected : A boolean value showing the connection	status

	      o	     netaddr : A list of network addresses the node is listen-
		     ing on

	      o	     features :	Bit flags showing supported features (BOLT #9)

	      o	     channels  :  An array of objects describing channels with
		     the peer.

	      o	     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:

	      o	     state: Any	of these strings:.RS

	      o	     "OPENINGD": The channel funding protocol with the peer is
		     ongoing and both sides are	negotiating parameters.

	      o	     "CHANNELD_AWAITING_LOCKIN":  The peer and you have	agreed
		     on	channel	parameters and are just	waiting	for the	 chan-
		     nel funding transaction to	be confirmed deeply.  Both you
		     and the peer must acknowledge the channel funding	trans-
		     action  to	 be  confirmed deeply before entering the next
		     state.

	      o	     "CHANNELD_NORMAL":	The channel can	 be  used  for	normal
		     payments.

	      o	     "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.

	      o	     "CLOSINGD_SIGEXCHANGE": You and the peer are  negotiating
		     the mutual	close onchain fee.

	      o	     "CLOSINGD_COMPLETE":  You and the peer have agreed	on the
		     mutual close onchain fee  and  are	 awaiting  the	mutual
		     close getting confirmed deeply.

	      o	     "AWAITING_UNILATERAL":  You initiated a unilateral	close,
		     and are now  waiting  for	the  peer-selected  unilateral
		     close timeout to complete.

	      o	     "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).

	      o	     "ONCHAIN":	You saw	the funding transaction	getting	 spent
		     and  now know what	happened (i.e. if it was a proper uni-
		     lateral close by the peer,	or a theft attempt).

	      o	     "CLOSED": The channel closure has been confirmed  deeply.
		     The channel will eventually be removed from this array.

       o      status:  An  array  of strings containing	the most important log
	      messages relevant	to this	channel.  Also	known  as  the	"bill-
	      board".

       o      owner: A string describing which particular sub-daemon of	light-
	      ningd currently  is  responsible	for  this  channel.   One  of:
	      "lightning_openingd",   "lightning_channeld",   "lightning_clos-
	      ingd", "lightning_onchaind".

       o      to_us_msat: A string describing how much of the funds  is	 owned
	      by us; a number followed by a string unit.

       o      total_msat:  A string describing the total capacity of the chan-
	      nel; a number followed by	a string unit.

       These fields may	exist if the channel has gotten	beyond the  "OPENINGD"
       state, or in various circumstances:

	      o	     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.

	      o	     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.

	      o	     channel_id: The full channel ID of	the channel; the fund-
		     ing transaction ID	XORed with the output number.

	      o	     funding_txid: The funding transaction ID of the channel.

	      o	     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  ad-
		     dress,  an	additional close_to_addr field will be present
		     with the standardized address.

	      o	     private: A	boolean, true if the channel  is  unpublished,
		     false if the channel is published.

	      o	     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.

	      o	     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.

	      o	     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  suc-
		     cessfully	steal  from  the  peer,	 this is the amount we
		     could potentially get.

	      o	     dust_limit_msat: A	string describing  an  amount;	if  an
		     HTLC  or the amount wholly-owned by one node is at	or be-
		     low 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.

	      o	     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.

	      o	     their_reserve_msat:  A  string  describing	 the   minimum
		     amount that the peer must keep in the channel when	it at-
		     tempts to send out; if it has less	than this in the chan-
		     nel,  it cannot send to us	on that	channel; a number fol-
		     lowed by a	string unit.  We impose	this on	them,  default
		     is	1% of the total	channel	capacity.

	      o	     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.

	      o	     spendable_msat and	receivable_msat: A  string  describing
		     an	 estimate of how much we can send or receive over this
		     channel in	a single payment (or payment-part  for	multi-
		     part payments); 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  ac-
		     tivity.   For  a  sufficiently-large channel, this	can be
		     limited by	the rules imposed under	 certain  blockchains;
		     for  example,  individual	Bitcoin	 mainnet payment-parts
		     cannot exceed 42.94967295 mBTC.

	      o	     minimum_htlc_in_msat: A  string  describing  the  minimum
		     amount that an HTLC must have before we accept it.

	      o	     their_to_self_delay:  The	number of blocks that the peer
		     must wait to claim	their funds, if	they  close  unilater-
		     ally.

	      o	     our_to_self_delay:	 The  number  of  blocks that you must
		     wait to claim your	funds, if you close unilaterally.

	      o	     max_accepted_htlcs: The maximum number of HTLCs you  will
		     accept on this channel.

	      o	     in_payments_offered: The number of	incoming HTLCs offered
		     over this channel.

	      o	     in_offered_msat: A	string describing the total amount  of
		     all  incoming  HTLCs  offered over	this channel; a	number
		     followed by a string unit.

	      o	     in_payments_fulfilled: The	number of incoming  HTLCs  of-
		     fered and successfully claimed over this channel.

	      o	     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.

	      o	     out_payments_offered:  The	 number	 of outgoing HTLCs of-
		     fered over	this channel.

	      o	     out_offered_msat: A string	describing the total amount of
		     all  outgoing  HTLCs  offered over	this channel; a	number
		     followed by a string unit.

	      o	     out_payments_fulfilled: The number	of outgoing HTLCs  of-
		     fered and successfully claimed over this channel.

	      o	     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.

	      o	     htlcs: An array of	objects	describing the HTLCs currently
		     in-flight in the channel.

       Objects in the htlcs array will contain these fields:

	      o	     direction:	Either the string "out"	or "in", whether it is
		     an	outgoing or incoming HTLC.

	      o	     id: A numeric ID uniquely identifying this	HTLC.

	      o	     amount_msat: The value of the HTLC.

	      o	     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  on-
		     chain.

	      o	     payment_hash:  The	 payment  hash,	whose preimage must be
		     revealed to successfully claim this HTLC.

	      o	     state: A string describing	whether	the HTLC has been com-
		     municated 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.

	      o	     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:

	      o	     -32602: If	the given parameters are wrong.

AUTHOR
       Michael Hawkins _michael.hawkins@protonmail.com>.

SEE ALSO
       lightning-connect(7), lightning-fundchannel_start(7)

RESOURCES
       Main  web  site:	https://github.com/ElementsProject/lightning Lightning
       RFC  site  (BOLT	 #9):	https://github.com/lightningnetwork/lightning-
       rfc/blob/master/09-features.md

							LIGHTNING-LISTPEERS(7)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | AUTHOR | SEE ALSO | RESOURCES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lightning-listpeers&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help