peer_control: Make close wait for complete closure, with timeout.

contrib/pylightning/lightning/lightning.py

@@ -333,12 +333,16 @@ def fundchannel(self, channel_id, satoshi):
         }
         return self.call("fundchannel", payload)
 
-    def close(self, peer_id):
+    def close(self, peer_id, force=None, timeout=None):
         """
-        Close the channel with peer {id}
+        Close the channel with peer {id}, forcing a unilateral
+        close if {force} is True, and timing out with {timeout}
+        seconds.
         """
         payload = {
-            "id": peer_id
+            "id": peer_id,
+            "force": force,
+            "timeout": timeout
         }
         return self.call("close", payload)
 

doc/Makefile

@@ -6,6 +6,7 @@ doc-wrongdir:
 
 MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-autocleaninvoice.7 \
+	doc/lightning-close.7 \
 	doc/lightning-decodepay.7 \
 	doc/lightning-delexpiredinvoice.7 \
 	doc/lightning-delinvoice.7 \

doc/lightning-close.7

@@ -0,0 +1,59 @@
+'\" t
+.\"     Title: lightning-close
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 04/15/2018
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-CLOSE" "7" "04/15/2018" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+lightning-close \- Protocol for closing channels with direct peers
+.SH "SYNOPSIS"
+.sp
+\fBclose\fR \fIid\fR [\fIforce\fR] [\fItimeout\fR]
+.SH "DESCRIPTION"
+.sp
+The \fBclose\fR RPC command attempts to close the channel cooperatively with the peer\&. It applies to the active channel of the direct peer corresponding to the given peer \fIid\fR\&.
+.sp
+The \fBclose\fR command will time out and return with an error when the number of seconds specified in \fItimeout\fR is reached\&. If unspecified, it times out in 30 seconds\&.
+.sp
+The \fIforce\fR argument, if the JSON value \fItrue\fR, 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 \fIto_self_delay\fR parameter of the peer\&.
+.sp
+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\&.
+.SH "RETURN VALUE"
+.sp
+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\&.
+.sp
+A unilateral close may still occur with \fIforce\fR set to \fIfalse\fR if the peer did not behave correctly during the close negotiation\&.
+.sp
+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\&.
+.sp
+On failure, if \fBclose\fR failed due to timing out with \fIforce\fR argument \fIfalse\fR, the channel will still eventually close once we have contacted the peer\&.
+.SH "AUTHOR"
+.sp
+ZmnSCPxj <ZmnSCPxj@protonmail\&.com> is mainly responsible\&.
+.SH "SEE ALSO"
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-close.7.txt

@@ -0,0 +1,70 @@
+LIGHTNING-CLOSE(7)
+==================
+:doctype: manpage
+
+NAME
+----
+lightning-close - Protocol 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.
+It applies to the active channel of the direct peer corresponding to
+the given peer 'id'.
+
+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

lightningd/channel.c

@@ -321,7 +321,8 @@ void channel_fail_permanent(struct channel *channel, const char *fmt, ...)
 	}
 
 	channel_set_owner(channel, NULL);
-	drop_to_chain(ld, channel);
+	/* Drop non-cooperatively (unilateral) to chain. */
+	drop_to_chain(ld, channel, false);
 	tal_free(why);
 }
 

lightningd/closing_control.c

@@ -93,7 +93,8 @@ static void peer_closing_complete(struct channel *channel, const u8 *msg)
 	if (channel->state == CLOSINGD_COMPLETE)
 		return;
 
-	drop_to_chain(channel->peer->ld, channel);
+	/* Channel gets dropped to chain cooperatively. */
+	drop_to_chain(channel->peer->ld, channel, true);
 	channel_set_state(channel, CLOSINGD_SIGEXCHANGE, CLOSINGD_COMPLETE);
 }
 

lightningd/lightningd.c

@@ -68,6 +68,7 @@ static struct lightningd *new_lightningd(const tal_t *ctx)
 	list_head_init(&ld->connects);
 	list_head_init(&ld->waitsendpay_commands);
 	list_head_init(&ld->sendpay_commands);
+	list_head_init(&ld->close_commands);
 	ld->wireaddrs = tal_arr(ld, struct wireaddr, 0);
 	ld->portnum = DEFAULT_PORT;
 	timers_init(&ld->timers, time_mono());

lightningd/lightningd.h

@@ -138,6 +138,8 @@ struct lightningd {
 	struct list_head waitsendpay_commands;
 	/* Outstanding sendpay commands. */
 	struct list_head sendpay_commands;
+	/* Outstanding close commands. */
+	struct list_head close_commands;
 
 	/* Maintained by invoices.c */
 	struct invoices *invoices;