lightning-listpeerchannels -- Command returning data on channels of connected lightning nodes

SYNOPSIS

listpeerchannels [id]

DESCRIPTION

The listpeerchannels RPC command returns data on channels of the network, with the possibility to filter the channels by node id.

If no id is supplied, then channel data on all lightning nodes that are
connected, or not connected but have open channels with this node, are
returned.

Supplying id will filter the results to only return channel data that match id,
if one exists.

RETURN VALUE

On success, an object containing channels is returned. It is an array of objects, where each object contains:

peer_id (pubkey): Node Public key
peer_connected (boolean): A boolean flag that is set to true if the peer is online
state (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN", "CHANNELD_AWAITING_SPLICE", "DUALOPEND_OPEN_COMMITTED", "DUALOPEND_OPEN_COMMIT_READY")
opener (string): Who initiated the channel (one of "local", "remote")
features (array of strings):
- BOLT #9 features which apply to this channel (one of "option_static_remotekey", "option_anchor_outputs", "option_anchors_zero_fee_htlc_tx", "option_scid_alias", "option_zeroconf")
scratch_txid (txid, optional): The txid we would use if we went onchain now
channel_type (object, optional): channel_type as negotiated with peer (added v23.05):
- bits (array of u32s): Each bit set in this channel_type:
  - Bit number
- names (array of strings): Feature name for each bit set in this channel_type:
  - Name of feature bit (one of "static_remotekey/even", "anchor_outputs/even", "anchors_zero_fee_htlc_tx/even", "scid_alias/even", "zeroconf/even")
updates (object, optional): Latest gossip updates sent/received (added v24.02):
- local (object): Our gossip for channel (added v24.02):
  - htlc_minimum_msat (msat): Minimum msat amount we allow (added v24.02)
  - htlc_maximum_msat (msat): Maximum msat amount we allow (added v24.02)
  - cltv_expiry_delta (u32): Blocks delay required between incoming and outgoing HTLCs (added v24.02)
  - fee_base_msat (msat): Amount we charge to use the channel (added v24.02)
  - fee_proportional_millionths (u32): Amount we charge to use the channel in parts-per-million (added v24.02)
- remote (object, optional): Peer's gossip for channel (added v24.02):
  - htlc_minimum_msat (msat): Minimum msat amount they allow (added v24.02)
  - htlc_maximum_msat (msat): Maximum msat amount they allow (added v24.02)
  - cltv_expiry_delta (u32): Blocks delay required between incoming and outgoing HTLCs (added v24.02)
  - fee_base_msat (msat): Amount they charge to use the channel (added v24.02)
  - fee_proportional_millionths (u32): Amount they charge to use the channel in parts-per-million (added v24.02)
ignore_fee_limits (boolean, optional): set if we allow this peer to set fees to anything they want (added v23.08)
lost_state (boolean, optional): set if we are fallen behind i.e. lost some channel state. (added v24.02)
feerate (object, optional): Feerates for the current tx:
- perkw (u32): Feerate per 1000 weight (i.e kSipa)
- perkb (u32): Feerate per 1000 virtual bytes
owner (string, optional): The current subdaemon controlling this connection
short_channel_id (short_channel_id, optional): The short_channel_id (once locked in)
channel_id (hash, optional): The full channel_id (funding txid Xored with output number)
funding_txid (txid, optional): ID of the funding transaction
funding_outnum (u32, optional): The 0-based output number of the funding transaction which opens the channel
initial_feerate (string, optional): For inflight opens, the first feerate used to initiate the channel open
last_feerate (string, optional): For inflight opens, the most recent feerate used on the channel open
next_feerate (string, optional): For inflight opens, the next feerate we'll use for the channel open
next_fee_step (u32, optional): For inflight opens, the next feerate step we'll use for the channel open
inflight (array of objects, optional): Current candidate funding transactions:
- funding_txid (txid): ID of the funding transaction
- funding_outnum (u32): The 0-based output number of the funding transaction which opens the channel
- feerate (string): The feerate for this funding transaction in per-1000-weight, with "kpw" appended
- total_funding_msat (msat): total amount in the channel
- splice_amount (integer): The amouont of sats we're splicing in or out (added v23.08)
- our_funding_msat (msat): amount we have in the channel
- scratch_txid (txid, optional): The commitment transaction txid we would use if we went onchain now
close_to (hex, optional): scriptPubkey which we have to close to if we mutual close
private (boolean, optional): if True, we will not announce this channel
closer (string, optional): Who initiated the channel close (only present if closing) (one of "local", "remote")
funding (object, optional):
- local_funds_msat (msat): Amount of channel we funded
- remote_funds_msat (msat): Amount of channel they funded
- pushed_msat (msat, optional): Amount pushed from opener to peer
- fee_paid_msat (msat, optional): Amount we paid peer at open
- fee_rcvd_msat (msat, optional): Amount we were paid by peer at open
to_us_msat (msat, optional): How much of channel is owed to us
min_to_us_msat (msat, optional): Least amount owed to us ever. If the peer were to successfully steal from us, this is the amount we would still retain.
max_to_us_msat (msat, optional): Most amount owed to us ever. If we were to successfully steal from the peer, this is the amount we could potentially get.
total_msat (msat, optional): total amount in the channel
fee_base_msat (msat, optional): amount we charge to use the channel
fee_proportional_millionths (u32, optional): amount we charge to use the channel in parts-per-million
dust_limit_msat (msat, optional): Minimum amount for an output on the channel transactions
max_total_htlc_in_msat (msat, optional): Max amount accept in a single payment
their_reserve_msat (msat, optional): Minimum we insist they keep in channel (default is 1% of the total channel capacity). If they have less than this in the channel, they cannot send to us on that channel
our_reserve_msat (msat, optional): Minimum they insist we keep in channel. If you have less than this in the channel, you cannot send out via this channel.
spendable_msat (msat, optional): An estimate of the total we could send through channel (can be wrong because adding HTLCs requires an increase in fees paid to onchain miners, and onchain fees change dynamically according to onchain activity)
receivable_msat (msat, optional): An estimate of the total peer could send through channel
minimum_htlc_in_msat (msat, optional): The minimum amount HTLC we accept
minimum_htlc_out_msat (msat, optional): The minimum amount HTLC we will send
maximum_htlc_out_msat (msat, optional): The maximum amount HTLC we will send
their_to_self_delay (u32, optional): The number of blocks before they can take their funds if they unilateral close
our_to_self_delay (u32, optional): The number of blocks before we can take our funds if we unilateral close
max_accepted_htlcs (u32, optional): Maximum number of incoming HTLC we will accept at once
alias (object, optional):
- local (short_channel_id, optional): An alias assigned by this node to this channel, used for outgoing payments
- remote (short_channel_id, optional): An alias assigned by the remote node to this channel, usable in routehints and invoices
state_changes (array of objects, optional): Prior state changes:
- timestamp (string): UTC timestamp of form YYYY-mm-ddTHH:MM:SS.%03dZ
- old_state (string): Previous state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN", "DUALOPEND_OPEN_COMMITTED", "DUALOPEND_OPEN_COMMIT_READY", "CHANNELD_AWAITING_SPLICE")
- new_state (string): New state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN", "DUALOPEND_OPEN_COMMITTED", "DUALOPEND_OPEN_COMMIT_READY", "CHANNELD_AWAITING_SPLICE")
- cause (string): What caused the change (one of "unknown", "local", "user", "remote", "protocol", "onchain")
- message (string): Human-readable explanation
status (array of strings, optional):
- Billboard log of significant changes
in_payments_offered (u64, optional): Number of incoming payment attempts
in_offered_msat (msat, optional): Total amount of incoming payment attempts
in_payments_fulfilled (u64, optional): Number of successful incoming payment attempts
in_fulfilled_msat (msat, optional): Total amount of successful incoming payment attempts
out_payments_offered (u64, optional): Number of outgoing payment attempts
out_offered_msat (msat, optional): Total amount of outgoing payment attempts
out_payments_fulfilled (u64, optional): Number of successful outgoing payment attempts
out_fulfilled_msat (msat, optional): Total amount of successful outgoing payment attempts
last_stable_connection (u64, optional): Last time we reestablished the open channel and stayed connected for 1 minute (added v24.02)
htlcs (array of objects, optional): current HTLCs in this channel:
- direction (string): Whether it came from peer, or is going to peer (one of "in", "out")
- id (u64): Unique ID for this htlc on this channel in this direction
- amount_msat (msat): Amount send/received for this HTLC
- expiry (u32): Block this HTLC expires at (after which an in direction HTLC will be returned to the peer, an out returned to us). If this expiry is too close, lightningd(8) will automatically unilaterally close the channel in order to enforce the timeout onchain.
- payment_hash (hash): the hash of the payment_preimage which will prove payment
- local_trimmed (boolean, optional): If this is too small to enforce onchain; it doesn't appear in the commitment transaction and will not be enforced in a unilateral close. Generally true if the HTLC (after subtracting onchain fees) is below the dust_limit_msat for the channel. (always true)
- status (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin)
If direction is "out":
- state (string): Status of the HTLC (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION")
If direction is "in":
- state (string): Status of the HTLC (one of "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION")

If peer_connected is true:

reestablished (boolean, optional): True if we have successfully exchanged reestablish messages this connection

If close_to is present:

close_to_addr (string, optional): The bitcoin address we will close to (present if close_to_addr is a standardized address)

If scratch_txid is present:

last_tx_fee_msat (msat): fee attached to this the current tx

If short_channel_id is present:

direction (u32): 0 if we're the lesser node_id, 1 if we're the greater (as used in BOLT #7 channel_update)

If inflight is present:

initial_feerate (string): The feerate for the initial funding transaction in per-1000-weight, with "kpw" appended
last_feerate (string): The feerate for the latest funding transaction in per-1000-weight, with "kpw" appended
next_feerate (string): The minimum feerate for the next funding transaction in per-1000-weight, with "kpw" appended

The state field values (and old_state / new_state) are worth describing further:

"OPENINGD": The channel funding protocol with the peer is ongoing
and both sides are negotiating parameters.
"DUALOPEND_OPEN_INIT": Like OPENINGD, but for v2 connections which
are using collaborative opens.
"DUALOPEND_OPEN_COMMIT_READY": Like OPENINGD, but for v2 connections which
are using collaborative opens. You're ready to send your commitment signed
to your peer.
"DUALOPEND_OPEN_COMMITTED": Like OPENINGD, but for v2 connections which
are using collaborative opens. You've gotten an initial signed commitment
from your peer.
"CHANNELD_AWAITING_LOCKIN" / "DUALOPEND\_AWAITING\_LOCKIN": The peer and you have agreed on channel
parameters and are just waiting for the channel funding transaction to
be confirmed deeply (original and collaborative open protocols, respectively).
Both you and the peer must acknowledge the channel funding transaction
to be confirmed deeply before entering the next state.
Also, you can increase the onchain fee for channels in DUALOPEND\_AWAITING\_LOCKIN
using lightning-openchannel_bump(7).
"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).

On error the returned object will contain code and message properties,
with code being one of the following:

-32602: If the given parameters are wrong.

AUTHOR

Michael Hawkins <[email protected]>.

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