doc/, contrib/: Additional support etc. for multifundchannel.

contrib/pyln-client/pyln/client/lightning.py

@@ -846,6 +846,27 @@ class LightningRpc(UnixDomainSocketRpc):
         }
         return self.call("listsendpays", payload)
 
+    def multifundchannel(self, destinations, feerate=None, minconf=None, utxos=None, best_effort=False, **kwargs):
+        """
+        Fund channels to an array of {destinations},
+        each entry of which is a dict of node {id}
+        and {amount} to fund, and optionally whether
+        to {announce} and how much {push_msat} to
+        give outright to the node.
+        You may optionally specify {feerate},
+        {minconf} depth, and the {utxos} set to use
+        for the single transaction that funds all
+        the channels.
+        """
+        payload = {
+            "destinations": destinations,
+            "feerate": feerate,
+            "minconf": minconf,
+            "utxos": utxos
+        }
+        payload.update({k: v for k, v in kwargs.items()})
+        return self.call("multifundchannel", payload)
+
     def newaddr(self, addresstype=None):
         """Get a new address of type {addresstype} of the internal wallet.
         """

doc/Makefile

@@ -36,6 +36,7 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-listpays.7 \
 	doc/lightning-listpeers.7 \
 	doc/lightning-listsendpays.7 \
+	doc/lightning-multifundchannel.7 \
 	doc/lightning-newaddr.7 \
 	doc/lightning-pay.7 \
 	doc/lightning-plugin.7 \

doc/index.rst

@@ -64,6 +64,7 @@ c-lightning Documentation
    lightning-listpeers <lightning-listpeers.7.md>
    lightning-listsendpays <lightning-listsendpays.7.md>
    lightning-listtransactions <lightning-listtransactions.7.md>
+   lightning-multifundchannel <lightning-multifundchannel.7.md>
    lightning-newaddr <lightning-newaddr.7.md>
    lightning-pay <lightning-pay.7.md>
    lightning-ping <lightning-ping.7.md>

doc/lightning-fundchannel.7

@@ -18,7 +18,7 @@ This auto-connection can fail if C-lightning does not know how to contact
 the target node; see \fBlightning-connect\fR(7)\.
 Once the
 transaction is confirmed, normal channel operations may begin\. Readiness
-is indicated by \fBlistpeers\fR reporting a \fIstate\fR of CHANNELD_NORMAL
+is indicated by \fBlistpeers\fR reporting a \fIstate\fR of \fBCHANNELD_NORMAL\fR
 for the channel\.
 
 
@@ -96,10 +96,10 @@ channel parameters (funding limits, channel reserves, fees, etc\.)\.
 .SH SEE ALSO
 
 \fBlightning-connect\fR(7), lightning-listfunds(), \fBlightning-listpeers\fR(7),
-\fBlightning-feerates\fR(7)
+\fBlightning-feerates\fR(7), \fBlightning-multifundchannel\fR(7)
 
 .SH RESOURCES
 
 Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
 
-\" SHA256STAMP:7d1358db44e2b81554fe1b105865e93d489d470bdbc43b7e09c7bddf7f10f396
+\" SHA256STAMP:f885008c6e60738b1ec9c5def19cc0877b0f9a72498ffa60e9fb3277ed9d9919

doc/lightning-fundchannel.7.md

@@ -20,7 +20,7 @@ This auto-connection can fail if C-lightning does not know how to contact
 the target node; see lightning-connect(7).
 Once the
 transaction is confirmed, normal channel operations may begin. Readiness
-is indicated by **listpeers** reporting a *state* of CHANNELD\_NORMAL
+is indicated by **listpeers** reporting a *state* of `CHANNELD_NORMAL`
 for the channel.
 
 *id* is the peer id obtained from **connect**.
@@ -82,7 +82,7 @@ SEE ALSO
 --------
 
 lightning-connect(7), lightning-listfunds(), lightning-listpeers(7),
-lightning-feerates(7)
+lightning-feerates(7), lightning-multifundchannel(7)
 
 RESOURCES
 ---------

doc/lightning-multifundchannel.7

@@ -0,0 +1,150 @@
+.TH "LIGHTNING-MULTIFUNDCHANNEL" "7" "" "" "lightning-multifundchannel"
+.SH NAME
+lightning-multifundchannel - Command for establishing many lightning channels
+.SH SYNOPSIS
+
+\fBmultifundchannel\fR \fIdestinations\fR [\fIfeerate\fR] [\fIminconf\fR] [\fIutxos\fR]
+
+.SH DESCRIPTION
+
+The \fBmultifundchannel\fR RPC command opens multiple payment channels
+with nodes by committing a single funding transaction to the blockchain
+that is shared by all channels\.
+
+
+If not already connected, \fBmultifundchannel\fR will automatically attempt
+to connect; you may provide a \fI@host:port\fR hint appended to the node ID
+so that c-lightning can learn how to connect to the node;
+see \fBlightning-connect\fR(7)\.
+
+
+Once the transaction is confirmed, normal channel operations may begin\.
+Readiness is indicated by \fBlistpeers\fR reporting a \fIstate\fR of
+\fBCHANNELD_NORMAL\fR for the channel\.
+
+
+\fIdestinations\fR is an array of objects, with the fields:
+
+.RS
+.IP \[bu]
+\fIid\fR is the node ID, with an optional \fI@host:port\fR appended to it
+in a manner understood by \fBconnect\fR; see \fBlightning-connect\fR(7)\.
+Each entry in the \fIdestinations\fR array must have a unique node \fIid\fR\.
+.IP \[bu]
+\fIamount\fR is the amount in satoshis taken from the internal wallet
+to fund the channel\.
+The string \fIall\fR can be used to specify all available funds
+(or 16,777,215 satoshi if more is available and large channels were
+not negotiated with the peer)\.
+Otherwise it is in satoshi precision; it can be
+ a whole number,
+ a whole number ending in \fIsat\fR,
+ a whole number ending in \fI000msat\fR, or
+ a number with 1 to 8 decimal places ending in \fIbtc\fR\.
+The value cannot be less than the dust limit, currently 546 satoshi
+as of this writing, nor more than 16,777,215 satoshi
+(unless large channels were negotiated with the peer)\.
+.IP \[bu]
+\fIannounce\fR is an optional flag that indicates whether to announce
+the channel with this, default \fBtrue\fR\.
+If set to \fBfalse\fR, the channel is unpublished\.
+.IP \[bu]
+\fIpush_msat\fR is the amount of millisatoshis to outright give to the
+node\.
+This is a gift to the peer, and you do not get a proof-of-payment
+out of this\.
+
+.RE
+
+There must be at least one entry in \fIdestinations\fR;
+it cannot be an empty array\.
+
+
+\fIfeerate\fR is an optional feerate used for the opening transaction and as
+initial feerate for commitment and HTLC transactions\. It can be one of
+the strings \fIurgent\fR (aim for next block), \fInormal\fR (next 4 blocks or
+so) or \fIslow\fR (next 100 blocks or so) to use lightningd’s internal
+estimates: \fInormal\fR is the default\.
+
+
+Otherwise, \fIfeerate\fR is a number, with an optional suffix: \fIperkw\fR means
+the number is interpreted as satoshi-per-kilosipa (weight), and \fIperkb\fR
+means it is interpreted bitcoind-style as satoshi-per-kilobyte\. Omitting
+the suffix is equivalent to \fIperkb\fR\.
+
+
+\fIminconf\fR specifies the minimum number of confirmations that used
+outputs should have\. Default is 1\.
+
+
+\fIutxos\fR specifies the utxos to be used to fund the channel, as an array
+of "txid:vout"\.
+
+.SH RETURN VALUE
+
+On success, the \fItx\fR and \fItxid\fR of the signed and broadcsted funding
+transaction is returned\.
+This command opens multiple channels with a single large transaction,
+thus only one transaction is returned\.
+
+
+An array of \fIchannel_ids\fR is returned;
+each entry of the array is an object,
+ with an \fIid\fR field being the node ID of the peer,
+ an \fIoutnum\fR field being the output number of the transaction
+  that anchors this channel,
+ and \fIchannel_id\fR field being the channel ID with that peer\.
+
+
+On failure, none of the channels are created\.
+
+
+The following error codes may occur:
+
+.RS
+.IP \[bu]
+-1: Catchall nonspecific error\.
+.IP \[bu]
+300: The maximum allowed funding amount is exceeded\.
+.IP \[bu]
+301: There are not enough funds in the internal wallet (including fees) to create the transaction\.
+.IP \[bu]
+302: The output amount is too small, and would be considered dust\.
+.IP \[bu]
+303: Broadcasting of the funding transaction failed, the internal call to bitcoin-cli returned with an error\.
+
+.RE
+
+Failure may also occur if \fBlightningd\fR and the peer cannot agree on
+channel parameters (funding limits, channel reserves, fees, etc\.)\.
+See lightning-fundchannel_\fBstart\fR(7) and lightning-fundchannel_\fBcomplete\fR(7)\.
+
+
+There may be rare edge cases where a communications failure later in
+the channel funding process will cancel the funding locally, but
+the peer thinks the channel is already waiting for funding lockin\.
+In that case, the next time we connect to the peer, our node will
+tell the peer to forget the channel, but some nodes (in particular,
+c-lightning nodes) will disconnect when our node tells them to
+forget the channel\.
+If you immediately \fBmultifundchannel\fR with that peer, it could
+trigger this connect-forget-disconnect behavior, causing the
+second \fBmultifundchannel\fR to fail as well due to disconnection\.
+Doing a \fBconnect\fR with the peers separately, and waiting for a
+few seconds, should help clear this hurdle;
+running \fBmultifundchannel\fR a third time would also clear this\.
+
+.SH AUTHOR
+
+ZmnSCPxj \fI<ZmnSCPxj@protonmail.com\fR> is mainly responsible\.
+
+.SH SEE ALSO
+
+\fBlightning-connect\fR(7), lightning-listfunds(), \fBlightning-listpeers\fR(7),
+\fBlightning-fundchannel\fR(7)
+
+.SH RESOURCES
+
+Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
+
+\" SHA256STAMP:3f7d15c9b3492535e74ec1f0077be84c385d4c22058756df4df638dd29c25f4c

doc/lightning-multifundchannel.7.md

@@ -0,0 +1,127 @@
+lightning-multifundchannel -- Command for establishing many lightning channels
+==============================================================================
+
+SYNOPSIS
+--------
+
+**multifundchannel** *destinations* \[*feerate*\] \[*minconf*\] \[*utxos*\]
+
+DESCRIPTION
+-----------
+
+The **multifundchannel** RPC command opens multiple payment channels
+with nodes by committing a single funding transaction to the blockchain
+that is shared by all channels.
+
+If not already connected, **multifundchannel** will automatically attempt
+to connect; you may provide a *@host:port* hint appended to the node ID
+so that c-lightning can learn how to connect to the node;
+see lightning-connect(7).
+
+Once the transaction is confirmed, normal channel operations may begin.
+Readiness is indicated by **listpeers** reporting a *state* of
+`CHANNELD_NORMAL` for the channel.
+
+*destinations* is an array of objects, with the fields:
+
+* *id* is the node ID, with an optional *@host:port* appended to it
+  in a manner understood by **connect**; see lightning-connect(7).
+  Each entry in the *destinations* array must have a unique node *id*.
+* *amount* is the amount in satoshis taken from the internal wallet
+  to fund the channel.
+  The string *all* can be used to specify all available funds
+  (or 16,777,215 satoshi if more is available and large channels were
+  not negotiated with the peer).
+  Otherwise it is in satoshi precision; it can be
+   a whole number,
+   a whole number ending in *sat*,
+   a whole number ending in *000msat*, or
+   a number with 1 to 8 decimal places ending in *btc*.
+  The value cannot be less than the dust limit, currently 546 satoshi
+  as of this writing, nor more than 16,777,215 satoshi
+  (unless large channels were negotiated with the peer).
+* *announce* is an optional flag that indicates whether to announce
+  the channel with this, default `true`.
+  If set to `false`, the channel is unpublished.
+* *push\_msat* is the amount of millisatoshis to outright give to the
+  node.
+  This is a gift to the peer, and you do not get a proof-of-payment
+  out of this.
+
+There must be at least one entry in *destinations*;
+it cannot be an empty array.
+
+*feerate* is an optional feerate used for the opening transaction and as
+initial feerate for commitment and HTLC transactions. It can be one of
+the strings *urgent* (aim for next block), *normal* (next 4 blocks or
+so) or *slow* (next 100 blocks or so) to use lightningd’s internal
+estimates: *normal* is the default.
+
+Otherwise, *feerate* is a number, with an optional suffix: *perkw* means
+the number is interpreted as satoshi-per-kilosipa (weight), and *perkb*
+means it is interpreted bitcoind-style as satoshi-per-kilobyte. Omitting
+the suffix is equivalent to *perkb*.
+
+*minconf* specifies the minimum number of confirmations that used
+outputs should have. Default is 1.
+
+*utxos* specifies the utxos to be used to fund the channel, as an array
+of "txid:vout".
+
+RETURN VALUE
+------------
+
+On success, the *tx* and *txid* of the signed and broadcsted funding
+transaction is returned.
+This command opens multiple channels with a single large transaction,
+thus only one transaction is returned.
+
+An array of *channel\_ids* is returned;
+each entry of the array is an object,
+ with an *id* field being the node ID of the peer,
+ an *outnum* field being the output number of the transaction
+  that anchors this channel,
+ and *channel_id* field being the channel ID with that peer.
+
+On failure, none of the channels are created.
+
+The following error codes may occur:
+* -1: Catchall nonspecific error.
+- 300: The maximum allowed funding amount is exceeded.
+- 301: There are not enough funds in the internal wallet (including fees) to create the transaction.
+- 302: The output amount is too small, and would be considered dust.
+- 303: Broadcasting of the funding transaction failed, the internal call to bitcoin-cli returned with an error.
+
+Failure may also occur if **lightningd** and the peer cannot agree on
+channel parameters (funding limits, channel reserves, fees, etc.).
+See lightning-fundchannel\_start(7) and lightning-fundchannel\_complete(7).
+
+There may be rare edge cases where a communications failure later in
+the channel funding process will cancel the funding locally, but
+the peer thinks the channel is already waiting for funding lockin.
+In that case, the next time we connect to the peer, our node will
+tell the peer to forget the channel, but some nodes (in particular,
+c-lightning nodes) will disconnect when our node tells them to
+forget the channel.
+If you immediately **multifundchannel** with that peer, it could
+trigger this connect-forget-disconnect behavior, causing the
+second **multifundchannel** to fail as well due to disconnection.
+Doing a **connect** with the peers separately, and waiting for a
+few seconds, should help clear this hurdle;
+running **multifundchannel** a third time would also clear this.
+
+AUTHOR
+------
+
+ZmnSCPxj <<ZmnSCPxj@protonmail.com>> is mainly responsible.
+
+SEE ALSO
+--------
+
+lightning-connect(7), lightning-listfunds(), lightning-listpeers(7),
+lightning-fundchannel(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>