External wallet funding

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Config: Adds parameter `min-capacity-sat` to reject tiny channels.
 - JSON API: `listforwards` now includes the time an HTLC was received and when it was resolved. Both are expressed as UNIX timestamps to facilitate parsing (Issue [#2491](https://github.com/ElementsProject/lightning/issues/2491), PR [#2528](https://github.com/ElementsProject/lightning/pull/2528))
 - JSON API: new plugin hooks `invoice_payment` for intercepting invoices before they're paid, `openchannel` for intercepting channel opens, and `htlc_accepted` to decide whether to resolve, reject or continue an incoming or forwarded payment..
+- JSON API: add three new RPC commands: `fundchannel_start`, `fundchannel_complete` and `fundchannel_cancel`. Allows a user to initiate and complete a channel open using funds that are in a external wallet.
 - plugin: the `connected` hook can now send an `error_message` to the rejected peer.
 - Protocol: we now enforce `option_upfront_shutdown_script` if a peer negotiates it.
 - JSON API: `listforwards` now includes the local_failed forwards with failcode (Issue [#2435](https://github.com/ElementsProject/lightning/issues/2435), PR [#2524](https://github.com/ElementsProject/lightning/pull/2524))

common/Makefile

@@ -1,4 +1,5 @@
 COMMON_SRC_NOGEN :=				\
+	common/addr.c				\
 	common/amount.c				\
 	common/base32.c				\
 	common/bech32.c				\

common/addr.c

@@ -0,0 +1,22 @@
+#include "addr.h"
+#include <bitcoin/script.h>
+#include <common/bech32.h>
+
+/* Returns NULL if the script is not a P2WPKH or P2WSH */
+char *encode_scriptpubkey_to_addr(const tal_t *ctx,
+				   const char *hrp,
+				   const u8 *scriptPubkey)
+{
+	char *out;
+	size_t scriptLen = tal_bytelen(scriptPubkey);
+
+        /* Check that scriptPubkey is P2WSH or P2WPKH */
+	if (!is_p2wsh(scriptPubkey, NULL) && !is_p2wpkh(scriptPubkey, NULL))
+                return NULL;
+
+	out = tal_arr(ctx, char, 73 + strlen(hrp));
+	if (!segwit_addr_encode(out, hrp, 0, scriptPubkey + 2, scriptLen - 2))
+		return tal_free(out);
+
+	return out;
+}

common/addr.h

@@ -0,0 +1,12 @@
+#ifndef LIGHTNING_COMMON_ADDR_H
+#define LIGHTNING_COMMON_ADDR_H
+#include "config.h"
+#include <ccan/short_types/short_types.h>
+#include <ccan/tal/tal.h>
+
+/* Given a P2WSH or P2WPKH scriptPubkey, return a bech32 encoded address */
+char *encode_scriptpubkey_to_addr(const tal_t *ctx,
+                                  const char *hrp,
+                                  const u8 *scriptPubkey);
+
+#endif /* LIGHTNING_COMMON_ADDR_H */

contrib/pylightning/lightning/lightning.py

@@ -509,6 +509,44 @@ def fundchannel(self, node_id, satoshi, feerate=None, announce=True, minconf=Non
         }
         return self.call("fundchannel", payload)
 
+    def fundchannel_start(self, node_id, satoshi, feerate=None, announce=True):
+        """
+        Start channel funding with {id} for {satoshi} satoshis
+        with feerate of {feerate} (uses default feerate if unset).
+        If {announce} is False, don't send channel announcements.
+        Returns a Bech32 {funding_address} for an external wallet
+        to create a funding transaction for. Requires a call to
+        'fundchannel_complete' to complete channel establishment
+        with peer.
+        """
+        payload = {
+            "id": node_id,
+            "satoshi": satoshi,
+            "feerate": feerate,
+            "announce": announce,
+        }
+        return self.call("fundchannel_start", payload)
+
+    def fundchannel_cancel(self, node_id):
+        """
+        Cancel a 'started' fundchannel with node {id}.
+        """
+        payload = {
+            "id": node_id,
+        }
+        return self.call("fundchannel_cancel", payload)
+
+    def fundchannel_complete(self, node_id, funding_txid, funding_txout):
+        """
+        Complete channel establishment with {id}, using {funding_txid} at {funding_txout}
+        """
+        payload = {
+            "id": node_id,
+            "txid": funding_txid,
+            "txout": funding_txout,
+        }
+        return self.call("fundchannel_complete", payload)
+
     def getinfo(self):
         """
         Show information about this node

doc/Makefile

@@ -15,6 +15,9 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-delinvoice.7 \
 	doc/lightning-disconnect.7 \
 	doc/lightning-fundchannel.7 \
+	doc/lightning-fundchannel_start.7 \
+	doc/lightning-fundchannel_complete.7 \
+	doc/lightning-fundchannel_cancel.7 \
 	doc/lightning-getroute.7 \
 	doc/lightning-invoice.7 \
 	doc/lightning-listchannels.7 \

doc/lightning-fundchannel_cancel.7

@@ -0,0 +1,53 @@
+'\" t
+.\"     Title: lightning-fundchannel_cancel
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 06/05/2019
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-FUNDCHANN" "7" "06/05/2019" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * 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-fundchannel_cancel \- Command for completing channel establishment
+.SH "SYNOPSIS"
+.sp
+\fBfundchannel_cancel\fR \fIid\fR
+.SH "DESCRIPTION"
+.sp
+fundchannel_cancel is a lower level RPC command\&. It allows a user to cancel an initiated channel establishment with a connected peer\&.
+.sp
+\fIid\fR is the node id of the remote peer with which to cancel the
+.SH "RETURN VALUE"
+.sp
+On success, returns confirmation that the channel establishment has been canceled\&.
+.sp
+On failure, returns an error\&.
+.SH "AUTHOR"
+.sp
+Lisa Neigut <niftynei@gmail\&.com> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-connect(7), lightning\-fundchannel(7), lightning\-fundchannel_start(7), lightning\-fundchannel_complete(7)
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-fundchannel_cancel.7.txt

@@ -0,0 +1,37 @@
+LIGHTNING-FUNDCHANNEL_CANCEL(7)
+===============================
+:doctype: manpage
+
+NAME
+----
+lightning-fundchannel_cancel - Command for completing channel establishment
+
+SYNOPSIS
+--------
+*fundchannel_cancel* 'id'
+
+DESCRIPTION
+-----------
+`fundchannel_cancel` is a lower level RPC command. It allows a user to cancel an initiated
+channel establishment with a connected peer.
+
+'id' is the node id of the remote peer with which to cancel the 
+
+RETURN VALUE
+------------
+On success, returns confirmation that the channel establishment has been canceled.
+
+On failure, returns an error.
+
+AUTHOR
+------
+Lisa Neigut <niftynei@gmail.com> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-connect(7), lightning-fundchannel(7), lightning-fundchannel_start(7),
+lightning-fundchannel_complete(7)
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightning-fundchannel_complete.7

@@ -0,0 +1,59 @@
+'\" t
+.\"     Title: lightning-fundchannel_complete
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 06/05/2019
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-FUNDCHANN" "7" "06/05/2019" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * 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-fundchannel_complete \- Command for completing channel establishment
+.SH "SYNOPSIS"
+.sp
+\fBfundchannel_complete\fR \fIid\fR \fItxid\fR \fItxout\fR
+.SH "DESCRIPTION"
+.sp
+fundchannel_complete is a lower level RPC command\&. It allows a user to complete an initiated channel establishment with a connected peer
+.sp
+\fIid\fR is the node id of the remote peer
+.sp
+\fItxid\fR is the hex string of the funding transaction id\&.
+.sp
+\fItxout\fR is the integer outpoint of the funding output for this channel\&.
+.sp
+Note that the funding transaction should not be broadcast until after channel establishment has been successfully completed, as the commitment transactions for this channel are not secured until this command succesfully completes\&.
+.SH "RETURN VALUE"
+.sp
+On success, returns a confirmation that \fIcommitments_secured\fR and the derived \fIchannel_id\fR\&.
+.sp
+On failure, returns an error\&.
+.SH "AUTHOR"
+.sp
+Lisa Neigut <niftynei@gmail\&.com> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-connect(7), lightning\-fundchannel(7), lightning\-fundchannel_start(7), lightning\-fundchannel_cancel(7)
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning

doc/lightning-fundchannel_complete.7.txt

@@ -0,0 +1,46 @@
+LIGHTNING-FUNDCHANNEL_COMPLETE(7)
+=================================
+:doctype: manpage
+
+NAME
+----
+lightning-fundchannel_complete - Command for completing channel establishment
+
+SYNOPSIS
+--------
+*fundchannel_complete* 'id' 'txid' 'txout'
+
+DESCRIPTION
+-----------
+`fundchannel_complete` is a lower level RPC command. It allows a user to complete an initiated
+channel establishment with a connected peer
+
+'id' is the node id of the remote peer
+
+'txid' is the hex string of the funding transaction id.
+
+'txout' is the integer outpoint of the funding output for this channel.
+
+Note that the funding transaction should not be broadcast until after channel
+establishment has been successfully completed, as the commitment transactions
+for this channel are not secured until this command succesfully completes.
+
+RETURN VALUE
+------------
+On success, returns a confirmation that 'commitments_secured' and the
+derived 'channel_id'.
+
+On failure, returns an error.
+
+AUTHOR
+------
+Lisa Neigut <niftynei@gmail.com> is mainly responsible.
+
+SEE ALSO
+--------
+lightning-connect(7), lightning-fundchannel(7), lightning-fundchannel_start(7),
+lightning-fundchannel_cancel(7)
+
+RESOURCES
+---------
+Main web site: https://github.com/ElementsProject/lightning

doc/lightning-fundchannel_start.7

@@ -0,0 +1,59 @@
+'\" t
+.\"     Title: lightning-fundchannel_start
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 06/05/2019
+.\"    Manual: \ \&
+.\"    Source: \ \&
+.\"  Language: English
+.\"
+.TH "LIGHTNING\-FUNDCHANN" "7" "06/05/2019" "\ \&" "\ \&"
+.\" -----------------------------------------------------------------
+.\" * 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-fundchannel_start \- Command for initiating channel establishment for a lightning channel
+.SH "SYNOPSIS"
+.sp
+\fBfundchannel_start\fR \fIid\fR \fIsatoshi\fR [\fIfeerate\fR \fIannounce\fR]
+.SH "DESCRIPTION"
+.sp
+fundchannel_start is a lower level RPC command\&. It allows a user to initiate channel establishment with a connected peer\&.
+.sp
+\fIid\fR is the node id of the remote peer\&.
+.sp
+\fIsatoshi\fR is the satoshi value that the channel will be funded at\&. This value MUST be accurate, otherwise the negotiated commitment transactions will not encompass the correct channel value\&.
+.sp
+\fIfeerate\fR is an optional field\&. Sets the feerate for subsequent commitment transactions\&.
+.sp
+\fIannounce\fR whether or not to annouce this channel\&.
+.SH "RETURN VALUE"
+.sp
+On success, returns the \fIfunding_address\fR for the channel\&.
+.sp
+On failure, returns an error\&.
+.SH "AUTHOR"
+.sp
+Lisa Neigut <niftynei@gmail\&.com> is mainly responsible\&.
+.SH "SEE ALSO"
+.sp
+lightning\-connect(7), lightning\-fundchannel(7), lightning\-fundchannel_complete(7), lightning\-fundchannel_cancel(7)
+.SH "RESOURCES"
+.sp
+Main web site: https://github\&.com/ElementsProject/lightning