LIGHTNING-LISTCLOSEDCHANNELS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💅 LIGHTNING-LISTCLOSEDCHANNELS 💅

okay so bestie, this is a lightning-listclosedchannels page — it's a manual page from Core Lightning, and it's lowkey the receipts-finder for your dead channels 💀

✨ NAME ✨

listclosedchannels — get data on our closed historical channels 🎀

🦋 SYNOPSIS 🦋

listclosedchannels [id]

🌸 DESCRIPTION 🌸

Bestie, this command was added in v23.05 ⭐

The listclosedchannels RPC command returns data on channels which are otherwise forgotten — and by forgotten we mean more than 100 blocks after they're completely resolved onchain, so like, fully gone-gone, moved on, deleted from the group chat 💅

  • id (pubkey, optional) — if no id is supplied, then channel data on all historical channels are given. Supplying id will filter the results to only match channels to that peer ✨ Note that prior to v23.05, old peers were forgotten 🙈

👑 RETURN VALUE 👑

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

  • channel_id (hash) — the full channel_id (funding txid Xored with output number) 🔥
  • opener (string) (one of "local", "remote") — who initiated the channel
  • private (boolean) — if True, we will not announce this channel 🤫
  • total_local_commitments (u64) — number of commitment transaction we made
  • total_remote_commitments (u64) — number of commitment transaction they made
  • total_htlcs_sent (u64) — number of HTLCs we ever sent
  • funding_txid (txid) — ID of the funding transaction
  • funding_outnum (u32) — the 0-based output number of the funding transaction which opens the channel
  • funding_withheld (boolean) — True if we have not broadcast the funding transaction (see fundchannel_complete). (added v25.12) 🫶
  • leased (boolean) — whether this channel was leased from opener
  • total_msat (msat) — total amount in the channel
  • final_to_us_msat (msat) — our balance in final commitment transaction
  • min_to_us_msat (msat) — 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) — most amount owed to us ever. If we were to successfully steal from the peer, this is the amount we could potentially get 🔥
  • close_cause (string) (one of "unknown", "local", "user", "remote", "protocol", "onchain") — what caused the channel to close
  • peer_id (pubkey, optional) — peer public key (can be missing with pre-v23.05 closes!) 💀
  • short_channel_id (short_channel_id, optional) — the short_channel_id
  • 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 🌈
  • closer (string, optional) (one of "local", "remote") — who initiated the channel close (only present if closing)
  • channel_type (object, optional) — channel_type as negotiated with peer.:
    • bits (array of u32s) — each bit set in this channel_type.:
    • (u32, optional) — bit number
    • names (array of strings) — feature name for each bit set in this channel_type. Note that anchors_zero_fee_htlc_tx is a deprecated synonym for anchors.:
    • (string, optional) (one of "static_remotekey/even", "anchor_outputs/even", "anchors/even", "anchors_zero_fee_htlc_tx/even", "scid_alias/even", "zeroconf/even") — name of feature bit
  • funding_psbt (string, optional) — the PSBT (may be non-final or unsigned) we should use to open the channel, if any (added v25.12) 💜
  • funding_fee_paid_msat (msat, optional) — how much we paid to lease the channel (iff leased is true and opener is local)
  • funding_fee_rcvd_msat (msat, optional) — how much they paid to lease the channel (iff leased is true and opener is remote)
  • funding_pushed_msat (msat, optional) — how much opener pushed immediate (if non-zero)
  • last_commitment_txid (hash, optional) — the final commitment tx's txid (or mutual close, if we accepted it). Not present for some very old, small channels pre-0.7.0 🙈
  • last_commitment_fee_msat (msat, optional) — the fee on last_commitment_txid
  • last_stable_connection (u64, optional) — last time we reestablished the open channel and stayed connected for 1 minute. (added v24.02) ⭐

💀 ERRORS 💀

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 🧚

Rusty Russell rusty@blockstream.com. 👑

🍓 SEE ALSO 🍓

lightning-listpeerchannels(7)

🌟 RESOURCES 🌟

Main web site: https://github.com/ElementsProject/lightning — go be nosy bestie 💖

💅 EXAMPLES 💅

Example 1:

Request:

$ lightning-cli listclosedchannels

{
  "id": "example:listclosedchannels#1",
  "method": "listclosedchannels",
  "params": {}
}

Response:

{
  "closedchannels": [
    {
      "peer_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "channel_id": "channelid0230000230000230000230000230000230000230000230000230000",
      "short_channel_id": "111x1x1",
      "alias": {
        "local": "121x131x141",
        "remote": "151x161x171"
      },
      "opener": "local",
      "closer": "local",
      "private": false,
      "channel_type": {
        "bits": [
          12,
          22
        ],
        "names": [
          "static_remotekey/even",
          "anchors/even"
        ]
      },
      "total_local_commitments": 16,
      "total_remote_commitments": 16,
      "total_htlcs_sent": 8,
      "funding_txid": "fundingtxid00202020202020202020202020202020202020202020202020202",
      "funding_outnum": 1,
      "leased": false,
      "total_msat": 1000000000,
      "final_to_us_msat": 489809898,
      "min_to_us_msat": 489809898,
      "max_to_us_msat": 1000000000,
      "last_commitment_txid": "txidcloselastcommitment00000100001000010000100001000010000100001",
      "last_commitment_fee_msat": 2895000,
      "close_cause": "user",
      "last_stable_connection": 1738500000
    },
    {
      "peer_id": "nodeid050505050505050505050505050505050505050505050505050505050505",
      "channel_id": "channelid0250000250000250000250000250000250000250000250000250000",
      "short_channel_id": "115x1x1",
      "alias": {
        "local": "122x132x142",
        "remote": "152x162x172"
      },
      "opener": "local",
      "closer": "local",
      "private": true,
      "channel_type": {
        "bits": [
          12,
          22
        ],
        "names": [
          "static_remotekey/even",
          "anchors/even"
        ]
      },
      "total_local_commitments": 2,
      "total_remote_commitments": 2,
      "total_htlcs_sent": 1,
      "funding_txid": "fundingtxid00101010101010101010101010101010101010101010101010101",
      "funding_outnum": 1,
      "leased": false,
      "total_msat": 1000000000,
      "final_to_us_msat": 500000000,
      "min_to_us_msat": 500000000,
      "max_to_us_msat": 1000000000,
      "last_commitment_txid": "txidcloselastcommitment00000200002000020000200002000020000200002",
      "last_commitment_fee_msat": 2896000,
      "close_cause": "user",
      "last_stable_connection": 1738500000
    }
  ]
}

and that's the whole page bestie, no cap 💖 this one's from Core Lightning v26.06.9 — go forth and dig up your closed channel lore 🎀✨🦋

📦 where this page comes from