lightning-close -- Command for closing channels with direct
peers
close id [unilateraltimeout]
[destination] [fee_negotiation_step] [wrong_funding]
[force_lease_closed] [feerange]
The close RPC command attempts to close the channel
cooperatively with the peer, or unilaterally after unilateraltimeout,
and the to-local output will be sent to the address specified in
destination.
The peer needs to be live and connected in order to negotiate a
mutual close. The default of unilaterally closing after 48 hours is usually
a reasonable indication that you can no longer contact the peer.
- id (string): Peer id, channel id or short_channel_id. If the given
id is a peer ID (66 hex digits as a string), then it applies to the
active channel of the direct peer corresponding to the given peer ID. If
the given 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.
- unilateraltimeout (u32, optional): If it is not zero, the command
will unilaterally close the channel when that number of seconds is
reached. If unilateraltimeout is zero, then the command will wait
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. 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): It controls how closing
fee negotiation is performed assuming the peer proposes a fee that is
different than our estimate. (Note that modern peers use the quick-close
protocol which does not allow negotiation: see feerange
instead).
- On every negotiation step we must give up some amount from our proposal
towards the peer's proposal. This parameter can be an integer in which
case it is interpreted as 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.
- 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).:
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.
Notifications may be returned indicating what is going on,
especially if the peer is offline and we are waiting.
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 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) - tx (hex,
optional): The raw bitcoin transaction used to close the channel (if it was
open). deprecated in v24.11, removed after v25.11 - txid
(txid, optional): The transaction id of the tx field. deprecated
in v24.11, removed after v25.11
A unilateral close may still occur at any time if the peer did not
behave correctly during the close negotiation.
Unilateral closes will return your funds after a delay. The delay
will vary based on the peer to_self_delay setting, not your own
setting.
lightning-disconnect(7), lightning-fundchannel(7),
lightningd-config(5)
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:
Request:
$ lightning-cli close -k "id"="nodeid040404040404040404040404040404040404040404040404040404040404" "destination"="bcrt1p0004040404040404040404040404040404040404040404040404040404"
{
"id": "example:close#2",
"method": "close",
"params": {
"id": "nodeid040404040404040404040404040404040404040404040404040404040404",
"destination": "bcrt1p0004040404040404040404040404040404040404040404040404040404"
}
}
Response:
{
"tx": "02000000000101cls10202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202",
"txid": "txid020202020202020202020202020202020202020202020202020202020202",
"txs": [
"02000000000101cls10202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202"
],
"txids": [
"txid020202020202020202020202020202020202020202020202020202020202"
],
"type": "mutual"
}