|
|
|
|
.TH "LIGHTNING-CLOSE" "7" "" "" "lightning-close"
|
|
|
|
|
.SH NAME
|
|
|
|
|
lightning-close - Command for closing channels with direct peers
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
|
|
|
|
|
\fBclose\fR \fIid\fR [\fIunilateraltimeout\fR] [\fIdestination\fR] [\fIfee_negotiation_step\fR]
|
|
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
|
|
|
|
|
The \fBclose\fR RPC command attempts to close the channel cooperatively
|
|
|
|
|
with the peer, or unilaterally after \fIunilateraltimeout\fR, and the
|
|
|
|
|
to-local output will be sent to the address specified in \fIdestination\fR\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If the given \fIid\fR 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 \fIid\fR is a channel ID (64 hex digits as a
|
|
|
|
|
string, or the short channel ID \fIblockheight:txindex:outindex\fR form),
|
|
|
|
|
then it applies to that channel\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If \fIunilateraltimeout\fR is not zero, the \fBclose\fR command will
|
|
|
|
|
unilaterally close the channel when that number of seconds is reached\.
|
|
|
|
|
If \fIunilateraltimeout\fR is zero, then the \fBclose\fR command will wait
|
|
|
|
|
indefinitely until the peer is online and can negotiate a mutual close\.
|
|
|
|
|
The default is 2 days (172800 seconds)\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The \fIdestination\fR can be of any Bitcoin accepted type, including bech32\.
|
|
|
|
|
If it isn't specified, the default is a c-lightning wallet address\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The \fIfee_negotiation_step\fR parameter controls how closing fee
|
|
|
|
|
negotiation is performed assuming the peer proposes a fee that is
|
|
|
|
|
different than our estimate\. 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:
|
|
|
|
|
|
|
|
|
|
.RS
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
"10": our next proposal will be 4000-10=3990\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
"10%": our next proposal will be 4000-(10% of (4000-3000))=3900\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
"1": our next proposal will be 3999\. This is the most extreme case when we
|
|
|
|
|
insist on our fee as much as possible\.
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
"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%"\.
|
|
|
|
|
|
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
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\.
|
|
|
|
|
|
|
|
|
|
.SH NOTES
|
|
|
|
|
|
|
|
|
|
Prior to 0\.7\.2, \fBclose\fR took two parameters: \fIforce\fR and \fItimeout\fR\.
|
|
|
|
|
\fItimeout\fR was the number of seconds before \fIforce\fR took effect (default,
|
|
|
|
|
30), and \fIforce\fR 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\.
|
|
|
|
|
|
|
|
|
|
.SH RETURN VALUE
|
|
|
|
|
|
|
|
|
|
On success, an object with fields \fItx\fR and \fItxid\fR containing the closing
|
|
|
|
|
transaction are returned\. It will also have a field \fItype\fR which is
|
|
|
|
|
either the JSON string \fImutual\fR or the JSON string \fIunilateral\fR\. A
|
|
|
|
|
\fImutual\fR close means that we could negotiate a close with the peer,
|
|
|
|
|
while a \fIunilateral\fR close means that the \fIforce\fR flag was set and we
|
|
|
|
|
had to close the channel without waiting for the counterparty\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 \fIto_self_delay\fR setting, not your own setting\.
|
|
|
|
|
|
|
|
|
|
.SH AUTHOR
|
|
|
|
|
|
|
|
|
|
ZmnSCPxj \fI<ZmnSCPxj@protonmail.com\fR> is mainly responsible\.
|
|
|
|
|
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
|
|
|
|
|
\fBlightning-disconnect\fR(7), \fBlightning-fundchannel\fR(7)
|
|
|
|
|
|
|
|
|
|
.SH RESOURCES
|
|
|
|
|
|
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
|
|
|
|
|
|
\" SHA256STAMP:3763db99c82aebedf40e1ef39407f2970d0408601f9250ec9c52995956da621b
|
