LIGHTNING-CLOSE(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

🎀 LIGHTNING-CLOSE(7) 🎀

okay bestie, buckle up — this is the lightning-close page from the LIGHTNING-CLOSE(7) manual, and it's literally the "how do I break up with my channel" guide 💔✨

✨ NAME ✨

close — the command for closing channels with your direct peers, no cap 🫶

💅 SYNOPSIS 💅

close id [unilateraltimeout] [destination] [fee_negotiation_step]
[wrong_funding] [force_lease_closed] [feerange]

🌸 DESCRIPTION 🌸

So the close RPC command tries to close the channel cooperatively with the peer — like, mutual, civilized, we-both-agree vibes 🤝 — or unilaterally after unilateraltimeout runs out, and the to-local output gets sent to the address you put in destination. Periodt.

Your peer needs to be live and connected for a mutual close negotiation to even happen. And the default of unilaterally closing after 48 hours? That's usually a pretty reasonable signal that you literally cannot contact the peer anymore, iykyk 😭

id (string) — Peer id, channel id, or short_channel_id. If the id you pass is a peer ID (66 hex digits as a string), then it applies to the active channel of the direct peer that corresponds to that peer ID. If the id is a channel ID (64 hex digits as a string, or the short channel ID blockheight:txindex:outindex form), then it applies to that channel. Slay, options 💅
unilateraltimeout (u32, optional) — If it's not zero, the command will unilaterally close the channel once that number of seconds is reached. If unilateraltimeout is zero, then the command waits indefinitely until the peer is online and can negotiate a mutual close 🕰️. The default is 2 days (172800 seconds).
destination (string, optional) — Any Bitcoin bech32 type. BUT: if the peer hasn't offered the option_shutdown_anysegwit feature, then taproot addresses (or other v1+ segwit) are not allowed. Tell your friends to upgrade! 🙈 The default is a Core Lightning wallet address.
fee_negotiation_step (string, optional) — This controls how closing fee negotiation is performed, assuming the peer proposes a fee that's different from our estimate. (Note that modern peers use the quick-close protocol which does not allow negotiation: see feerange instead 👀).

On every negotiation step we gotta give up some amount from our proposal towards the peer's proposal. This parameter can be an integer, in which case it's interpreted as the number of satoshis to step at a time. Or it can be an integer followed by % to designate a percentage of the interval to give up. A few examples, assuming the peer proposes a closing fee of 3000 satoshi and our estimate shows it must be 4000:

10: our next proposal will be 4000-10=3990.
10%: our next proposal will be 4000-(10% of (4000-3000))=3900.
'1': our next proposal will be 3999. This is the most extreme case when we insist on our fee as much as possible 😤
100%: our next proposal will be 3000. This is the most relaxed case when we quickly accept the peer's proposal. The default is 50%. 🧘‍♀️

wrong_funding (outpoint, optional) — It can only be specified if both sides have offered the shutdown_wrong_funding feature (enabled by the experimental-shutdown-wrong-funding option). It must be a transaction id followed by a colon then the output number. Instead of negotiating a shutdown to spend the expected funding transaction, the shutdown transaction will spend this output instead. This is only allowed if this peer opened the channel and the channel is unused: it can rescue openings which have been manually miscreated 🩹 (iconic little rescue mission, honestly).
force_lease_closed (boolean, optional) — If the channel has funds leased to the peer (option_will_fund), we prevent initiation of a mutual close unless this flag is passed in. The default is False.
feerange (array of feerates, optional) — An optional array [ min, max ], indicating the minimum and maximum feerates to offer: the peer will obey these if it supports the quick-close protocol. slow and unilateral_close are the defaults. Note that the maximum fee will be capped at the final commitment transaction fee (unless the experimental anchor-outputs option is negotiated).:
- (feerate, optional)

💀 NOTES 💀

Prior to 0.7.2, close took two parameters: force and timeout. timeout was the number of seconds before force took effect (default, 30), and force determined whether the result was a unilateral close or an RPC error (default). Even after the timeout, the channel would be closed if the peer reconnected. Throwback lore fr fr 🕯️

🔔 NOTIFICATIONS 🔔

Notifications may be returned indicating what is going on — especially if the peer is offline and we're just sitting there waiting 🫠

📦 RETURN VALUE 📦

On success, an object is returned, containing:

type (string) (one of "mutual", "unilateral", "unopened") — Whether we successfully negotiated a mutual close, closed without them, or discarded a not-yet-opened channel.

If type is "mutual" or "unilateral": - txs (array of hexs): The raw bitcoin transactions used to close the channel (if it was open). (added v24.11): - (hex, optional) - txids (array of txids): The transaction ids of the tx field(s). (added v24.11): - (txid, optional)

⚠️ A unilateral close may still occur at any time if the peer did not behave correctly during the close negotiation. Not me trusting the peer and getting rug-pulled 😭

Unilateral closes will return your funds after a delay. The delay will vary based on the peer's to_self_delay setting — not your own setting. Read that again, bestie 👑.

👑 AUTHOR 👑

ZmnSCPxj ZmnSCPxj@protonmail.com is mainly responsible. Respect the legend 🫡

🦋 RESOURCES 🦋

Main web site: https://github.com/ElementsProject/lightning

🍓 EXAMPLES 🍓

Example 1:

Request:

$ lightning-cli close -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303" "unilateraltimeout"=1

{
  "id": "example:close#1",
  "method": "close",
  "params": {
    "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
    "unilateraltimeout": 1
  }
}

Response:

{
  "tx": "02000000000101cls00101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101",
  "txid": "txid010101010101010101010101010101010101010101010101010101010101",
  "txs": [
    "02000000000101cls00101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101"
  ],
  "txids": [
    "txid010101010101010101010101010101010101010101010101010101010101"
  ],
  "type": "mutual"
}

Example 2: