home | help 
LIGHTNING-CLOSE(7)					      LIGHTNING-CLOSE(7)

NAME
     close -- Command for closing channels with direct peers

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

DESCRIPTION
     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 rea-
     sonable 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  chan-
	nel ID blockheight:txindex:outindex form), then it applies to that chan-
	nel.

     *	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  ad-
	dresses  (or other v1+ segwit) are not allowed. Tell your friends to up-
	grade! The default is a Core Lightning wallet address.

     *	fee_negotiation_step (string, optional): It controls how closing fee ne-
	gotiation is performed assuming the peer proposes a fee that is  differ-
	ent  than our estimate. (Note that modern peers use the quick-close pro-
	tocol 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 inter-
	val 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 trans-
	action 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 op-
	tion 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 de-
     termined  whether	the  result  was a unilateral close or an RPC error (de-
     fault). Even after the timeout, the channel would be closed if the peer re-
     connected.

NOTIFICATIONS
     Notifications may be returned indicating what is going  on,  especially  if
     the peer is offline and we are 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  dis-
	carded 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.

     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.

AUTHOR
     ZmnSCPxj ZmnSCPxj@protonmail.com is mainly responsible.

SEE ALSO
     lightning-disconnect(7), lightning-fundchannel(7), lightningd-config(5)

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:

     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"
     }

Core Lightning v26.06.1 				      LIGHTNING-CLOSE(7)
home | help