diff --git a/contrib/pyln-client/pyln/client/lightning.py b/contrib/pyln-client/pyln/client/lightning.py index a88d866ac..ce882a7a2 100644 --- a/contrib/pyln-client/pyln/client/lightning.py +++ b/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. """ diff --git a/doc/Makefile b/doc/Makefile index e9f343d4d..e5c9b8d45 100644 --- a/doc/Makefile +++ b/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 \ diff --git a/doc/index.rst b/doc/index.rst index 7721c1221..03c9433f9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -64,6 +64,7 @@ c-lightning Documentation lightning-listpeers lightning-listsendpays lightning-listtransactions + lightning-multifundchannel lightning-newaddr lightning-pay lightning-ping diff --git a/doc/lightning-fundchannel.7 b/doc/lightning-fundchannel.7 index 0700ecb5c..830a331b3 100644 --- a/doc/lightning-fundchannel.7 +++ b/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 diff --git a/doc/lightning-fundchannel.7.md b/doc/lightning-fundchannel.7.md index c7955d341..f314dd811 100644 --- a/doc/lightning-fundchannel.7.md +++ b/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 --------- diff --git a/doc/lightning-multifundchannel.7 b/doc/lightning-multifundchannel.7 new file mode 100644 index 000000000..a68182418 --- /dev/null +++ b/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 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 diff --git a/doc/lightning-multifundchannel.7.md b/doc/lightning-multifundchannel.7.md new file mode 100644 index 000000000..d377bfc9b --- /dev/null +++ b/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 <> is mainly responsible. + +SEE ALSO +-------- + +lightning-connect(7), lightning-listfunds(), lightning-listpeers(7), +lightning-fundchannel(7) + +RESOURCES +--------- + +Main web site: