mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-01-01 03:24:41 +01:00
6e636a835f
1. listpeers has a deprecated `"closer": null`, which we need to handle in the schema, while trying not to damage our documentation too much. 2. Don't print a condition if there are no fields to print. 3. Allow a special "untyped" marker for multifundchannel which returns arbitrary JSON in a field. 4. Allow a single field return (for 'stop'). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
134 lines
4.8 KiB
Groff
Generated
134 lines
4.8 KiB
Groff
Generated
.TH "LIGHTNING-FUNDCHANNEL" "7" "" "" "lightning-fundchannel"
|
||
.SH NAME
|
||
lightning-fundchannel - Command for establishing a lightning channel
|
||
.SH SYNOPSIS
|
||
|
||
\fBfundchannel\fR \fIid\fR \fIamount\fR [\fIfeerate\fR] [\fIannounce\fR] [\fIminconf\fR]
|
||
[\fIutxos\fR] [\fIpush_msat\fR] [\fIclose_to\fR]
|
||
|
||
.SH DESCRIPTION
|
||
|
||
The \fBfundchannel\fR RPC command opens a payment channel with a peer by
|
||
committing a funding transaction to the blockchain as defined in BOLT
|
||
#2\.
|
||
If not already connected, \fBfundchannel\fR will automatically attempt
|
||
to connect if C-lightning knows a way to contact the node (either from
|
||
normal gossip, or from a previous \fBconnect\fR call)\.
|
||
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 \fBCHANNELD_NORMAL\fR
|
||
for the channel\.
|
||
|
||
|
||
\fIid\fR is the peer id obtained from \fBconnect\fR\.
|
||
|
||
|
||
\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 16777215 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 set to 546, nor more than 16777215 satoshi (unless large
|
||
channels were negotiated with the peer)\.
|
||
|
||
|
||
\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\.
|
||
|
||
|
||
\fIannounce\fR is an optional flag that triggers whether to announce this
|
||
channel or not\. Defaults to \fBtrue\fR\. An unannounced channel is considered
|
||
private\.
|
||
|
||
|
||
\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"\.
|
||
|
||
|
||
\fIpush_msat\fR is the amount of millisatoshis to push to the channel peer at
|
||
open\. Note that this is a gift to the peer -- these satoshis are
|
||
added to the initial balance of the peer at channel start and are largely
|
||
unrecoverable once pushed\.
|
||
|
||
|
||
\fIclose_to\fR is a Bitcoin address to which the channel funds should be sent to
|
||
on close\. Only valid if both peers have negotiated \fBoption_upfront_shutdown_script\fR\.
|
||
Returns \fBclose_to\fR set to closing script iff is negotiated\.
|
||
|
||
|
||
This example shows how to use lightning-cli to open new channel with peer 03f\.\.\.fc1 from one whole utxo bcc1\.\.\.39c:0
|
||
(you can use \fBlistfunds\fR command to get txid and vout):
|
||
|
||
.nf
|
||
.RS
|
||
lightning-cli -k fundchannel id=03f...fc1 amount=all feerate=normal utxos='["bcc1...39c:0"]'
|
||
|
||
|
||
|
||
.RE
|
||
|
||
.fi
|
||
.SH RETURN VALUE
|
||
|
||
On success, an object is returned, containing:
|
||
|
||
.RS
|
||
.IP \[bu]
|
||
\fBtx\fR (hex): The raw transaction which funded the channel
|
||
.IP \[bu]
|
||
\fBtxid\fR (txid): The txid of the transaction which funded the channel
|
||
.IP \[bu]
|
||
\fBoutnum\fR (u32): The 0-based output index showing which output funded the channel
|
||
.IP \[bu]
|
||
\fBchannel_id\fR (hex): The channel_id of the resulting channel (always 64 characters)
|
||
.IP \[bu]
|
||
\fBclose_to\fR (hex, optional): The raw scriptPubkey which mutual close will go to; only present if \fIclose_to\fR parameter was specified and peer supports \fBoption_upfront_shutdown_script\fR
|
||
|
||
.RE
|
||
|
||
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\.)\.
|
||
|
||
.SH SEE ALSO
|
||
|
||
\fBlightning-connect\fR(7), lightning-listfunds(), \fBlightning-listpeers\fR(7),
|
||
\fBlightning-feerates\fR(7), \fBlightning-multifundchannel\fR(7)
|
||
|
||
.SH RESOURCES
|
||
|
||
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
|
||
|
||
\" SHA256STAMP:d25fc36b745b6f58556f7f4b06f23ff83b466d4a00911f7ffdc9d86572902954
|