ZmnSCPxj jxPCSnmZ
4 years ago
committed by
Rusty Russell
Rusty Russell
7 changed files with 305 additions and 5 deletions
@ -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 |
|||
@ -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> |
|||
Loading…
Reference in new issue