LIGHTNING-CLOSE(7)

NAME
lightning-close - Command for closing channels with direct peers

SYNOPSIS

close id [force] [timeout]

DESCRIPTION

The close RPC command attempts to close the channel cooperatively with the peer. 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.

The close command will time out and return with an error when the number of seconds specified in timeout is reached. If unspecified, it times out in 30 seconds.

The force argument, if the JSON value true, will cause the channel to be unilaterally closed when the timeout is reached. If so, timeout will not cause an error, but instead cause the channel to be failed and put onchain unilaterally. Unilateral closes will lead to your funds getting locked according to the to_self_delay parameter of the peer.

Normally the peer needs to be live and connected in order to negotiate a mutual close. Forcing a unilateral close can be used if you suspect you can no longer contact the peer.

RETURN VALUE

On success, an object with fields tx and txid containing the closing transaction are returned. It will also have a field type which is either the JSON string mutual or the JSON string unilateral. A mutual close means that we could negotiate a close with the peer, while a unilateral close means that the force flag was set and we had to close the channel without waiting for the counterparty.

A unilateral close may still occur with force set to false 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.

On failure, if close failed due to timing out with force argument false, the channel will still eventually close once we have contacted the peer.

AUTHOR

ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible.

SEE ALSO

RESOURCES

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