mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-20 02:27:51 +01:00
134 lines
4.9 KiB
Groff
Generated
134 lines
4.9 KiB
Groff
Generated
.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] [\fIwrong_funding\fR] [\fIforce_lease_closed\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\. If
|
|
the peer hasn't offered the \fBoption_shutdown_anysegwit\fR feature, then
|
|
taproot addresses (or other v1+ segwit) are not allowed\. Tell your
|
|
friends to upgrade!
|
|
|
|
|
|
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\.
|
|
|
|
.RE
|
|
|
|
The default is "50%"\.
|
|
|
|
|
|
\fIwrong_funding_txid\fR can only be specified if both sides have offered
|
|
the "shutdown_wrong_funding" feature (enabled by the
|
|
\fBexperimental-shutdown-wrong-funding\fR 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\.
|
|
|
|
|
|
\fIforce_lease_closed\fR 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\. Defaults to false\.
|
|
|
|
|
|
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 NOTIFICATIONS
|
|
|
|
Notifications may be returned indicating what is going on, especially
|
|
if the peer is offline and we are waiting\.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, an object is returned, containing:
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtype\fR (string): Whether we successfully negotiated a mutual close, closed without them, or discarded not-yet-opened channel (one of "mutual", "unilateral", "unopened")
|
|
|
|
.RE
|
|
|
|
If \fBtype\fR is "mutual" or "unilateral":
|
|
|
|
.RS
|
|
.IP \[bu]
|
|
\fBtx\fR (hex): the raw bitcoin transaction used to close the channel (if it was open)
|
|
.IP \[bu]
|
|
\fBtxid\fR (txid): the transaction id of the \fItx\fR field
|
|
|
|
.RE
|
|
|
|
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), \fBlightningd-config\fR(5)\.
|
|
|
|
.SH RESOURCES
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
|
|
|
\" SHA256STAMP:a28dd05f6b0a86e1f3d748759ae9bcaa0ffc95686fb904969f07def600c23168
|