mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-02-24 07:07:46 +01:00
Code Issues Projects Releases Wiki Activity
core-lightning/doc/lightning-fundchannel_start.7.md

120 lines
4.9 KiB
Markdown
Raw Normal View History

docs: Update manpages to be recognized correctly by mrkd mrkd started enforcing the `name -- short description` style of top-level headings somewhere, and was thus failing to build the man-pages. I swapped the title and with the existing short description to make it work again. `mrkd` will automatically infer the section from the filename so no need to put it in the title as well. In addition I removed the "last updated" lines at the bottom since they are out of date at best, and misleading at the worst. If we want to keep them, I'd suggest generating them from the commit that last touched them.
2019-08-31 14:30:56 +02:00
lightning-fundchannel\_start -- Command for initiating channel establishment for a lightning channel
====================================================================================================
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
SYNOPSIS
--------
Doc: Undocumented parameters in fundchannel_start - Documented `mindepth` and `reserve` in `fundchannel_start`. These parameters are supported but had not been documented (yet). - Removed `mindepth` from return-type. I'm unable to find any scenario in which a value is returned. - Documented the 312 error code
2024-01-02 13:01:37 +01:00
**fundchannel\_start** *id* *amount* [*feerate* *announce* *close\_to* *push\_msat* *channel\_type*] *mindepth* *reserve*]
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
DESCRIPTION
-----------
`fundchannel_start` is a lower level RPC command. It allows a user to
initiate channel establishment with a connected peer.
*id* is the node id of the remote peer.
doc: Use `amount` as the parameter name for `fundchannel`
2019-09-19 15:51:07 +08:00
*amount* is the satoshi value that the channel will be funded at. This
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
value MUST be accurate, otherwise the negotiated commitment transactions
will not encompass the correct channel value.
*feerate* is an optional field. Sets the feerate for subsequent
openingd: use a lower feerate for first commitment tx for anchors. We need to know both, because in theory we could negotiate a non-anchor channel even if they support it. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2023-06-26 08:41:21 +09:30
commitment transactions: see **fundchannel**. Note that this is ignored
for channels with *option\_anchors\_zero\_fee\_htlc\_tx* (we always use a low
commitment fee for these).
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
doc: fix wording for fundchannel_complete
2019-08-21 15:55:49 +07:00
*announce* whether or not to announce this channel.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-10 20:44:56 -05:00
*close\_to* is a Bitcoin address to which the channel funds should be sent to
funding: add RPC arg to specify a 'close_to' address Takes advantage of upfront-shutdown-script to permit users to specify the close-to address for a channel at open, by adding a `close_to` field to `fundchannel_start`. Note that this only is in effect if `fundchannel_start` returns with `close_to` set -- otherwise, peer doesn't support `option_upfront_shutdown_script`.
2019-10-15 11:38:33 +10:30
on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`.
Returns `close_to` set to closing script iff is negotiated.
doc: escape more naughty underscores The only time underscores aren't special in Markdown is when they appear in preformatted text. We have gotten away with not escaping underscores where an asterisk-enclosed span or the paragraph ends before the next underscore appears, but this is fragile and bad practice. Conversely, there are many places where we have not escaped underscores but needed to. Escape all underscores that do not appear in preformatted blocks or preformatted spans and are not themselves delineating emphasized spans. The changes in this commit are exactly the result of executing the following Bash code: ```bash e=':x;' # begin loop e+='s/^' # anchor match at beginning of line e+='(' # begin capturing subexpression e+='(' # begin list of alternatives e+='[^`_\\]|' # any mundane character, or e+='`([^`\\]|\\.)*`|' # backtick-enclosed span, or e+='\b_|_\b|' # underscore at boundary, or e+='\\.' # backslash-escaped character e+=')*' # any number of the preceding alternatives e+=')' # end capturing subexpression e+='\B_\B/\1\\_/;' # escape non-formatting underscore e+='tx' # repeat loop if we escaped an underscore escape_underscores=( sed # use extended regular expressions -E # skip over indented blocks (following an empty line) -e '/^$/{:i;n;/^( {4,}|\t)/bi}' # skip over preformatted blocks -e '/^\s*```/,/^\s*```/{p;d}' # skip over generated sections -e '/GENERATE-FROM-SCHEMA-START/,/GENERATE-FROM-SCHEMA-END/{p;d}' # escape underscores -e "${e}" ) "${escape_underscores[@]}" -i doc/*.[0-9].md ``` Changelog-None
2022-11-10 20:44:56 -05:00
*push\_msat* is the amount of millisatoshis to push to the channel peer at
funding: enable push_msat it's that time of year (merry xmas!) enables the ability to push_msat on fundchannel Changelog-Added: RPC: `fundchannel` and `fundchannel_start` can now accept an optional parameter, `push_msat`, which will gift that amount of satoshis to the peer at channel open.
2019-12-20 23:53:12 -06:00
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.
fundchannel_start / openchannel_init: add a channel_type parameter to force channel type. And add request schemas for openchannel_init and fundchannel_start. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: `fundchannel_start` and `openchannel_init` now take an optional `channel_type` parameter.
2024-01-29 10:04:17 +10:30
*channel\_type* *(added v24.02)* is an array of bit numbers, representing the explicit
channel type to request. BOLT 2 defines the following value types:
```
The currently defined basic types are:
- no features (no bits set) `[]`
- `option_static_remotekey` (`[12]`)
- `option_anchor_outputs` and `option_static_remotekey` (`[20, 12]`)
- `option_anchors_zero_fee_htlc_tx` and `option_static_remotekey` ([22, 12])
Each basic type has the following variations allowed:
- `option_scid_alias` ([46])
- `option_zeroconf` ([50])
```
Doc: Undocumented parameters in fundchannel_start - Documented `mindepth` and `reserve` in `fundchannel_start`. These parameters are supported but had not been documented (yet). - Removed `mindepth` from return-type. I'm unable to find any scenario in which a value is returned. - Documented the 312 error code
2024-01-02 13:01:37 +01:00
*mindepth* is the number of confirmations before we accept the channel as
active.
*reserve* is the amount we want the peer to maintain on its side of the channel.
Default is 1% of the funding amount. 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*.
doc: fix wording for fundchannel_complete
2019-08-21 15:55:49 +07:00
Note that the funding transaction MUST NOT be broadcast until after
channel establishment has been successfully completed by running
`fundchannel_complete`, as the commitment transactions for this channel
are not secured until the complete command succeeds. Broadcasting
transaction before that can lead to unrecoverable loss of funds.
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
RETURN VALUE
------------
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 17:05:01 +09:30
[comment]: # (GENERATE-FROM-SCHEMA-START)
On success, an object is returned, containing:
doc: generate correct markdown from schemas. You can't start a list without a paragraph separator. ```diff --- /tmp/before 2022-07-20 22:02:23.485372596 +0930 +++ /tmp/after 2022-07-20 22:02:33.745528456 +0930 @@ -21,12 +21,16 @@ On startup of the daemon, no autoclean is set up. RETURN VALUE - On success, an object is returned, containing: - enabled (boolean): - whether invoice autocleaning is active + On success, an object is returned, containing: - If enabled is true: - expired_by (u64): how long an invoice must be ex‐ - pired (seconds) before we delete it - cycle_seconds (u64): how long an - invoice must be expired (seconds) before we delete it + • enabled (boolean): whether invoice autocleaning is active + + If enabled is true: + + • expired_by (u64): how long an invoice must be expired (seconds) be‐ + fore we delete it + • cycle_seconds (u64): how long an invoice must be expired (seconds) + before we delete it AUTHOR ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible. ``` Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-06 07:03:09 +09:30
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-06 07:15:06 +09:30
- **funding\_address** (string): The address to send funding to for the channel. DO NOT SEND COINS TO THIS ADDRESS YET.
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 17:05:01 +09:30
- **scriptpubkey** (hex): The raw scriptPubkey for the address
fundchannel_start & multifundchannel: add channel_type. Let's tell the caller what channel_type they got! Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: `fundchannel`, `multifundchannel`, `fundchannel_start` and `openchannel_init`: new field `channel_type`.
2024-01-29 10:08:40 +10:30
- **channel\_type** (object): channel\_type as negotiated with peer *(added v24.02)*:
- **bits** (array of u32s): Each bit set in this channel\_type *(added v24.02)*:
- Bit number
- **names** (array of strings): Feature name for each bit set in this channel\_type *(added v24.02)*:
- Name of feature bit (one of "static\_remotekey/even", "anchor\_outputs/even", "anchors\_zero\_fee\_htlc\_tx/even", "scid\_alias/even", "zeroconf/even")
fromschema.py: escape underscores in descriptions
2022-11-10 21:03:13 -05:00
- **close\_to** (hex, optional): The raw scriptPubkey which mutual close will go to; only present if *close\_to* parameter was specified and peer supports `option_upfront_shutdown_script`
doc: fix GH/readthedocs rendering of manual pages. They render the comment as if it's in the list. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-09-03 19:37:59 +09:30
Add more warnings to fundchannel_start [ Slight modifications to fix schema -- RR ]
2022-03-20 16:07:48 +01:00
The following warnings may also be returned:
doc: generate correct markdown from schemas. You can't start a list without a paragraph separator. ```diff --- /tmp/before 2022-07-20 22:02:23.485372596 +0930 +++ /tmp/after 2022-07-20 22:02:33.745528456 +0930 @@ -21,12 +21,16 @@ On startup of the daemon, no autoclean is set up. RETURN VALUE - On success, an object is returned, containing: - enabled (boolean): - whether invoice autocleaning is active + On success, an object is returned, containing: - If enabled is true: - expired_by (u64): how long an invoice must be ex‐ - pired (seconds) before we delete it - cycle_seconds (u64): how long an - invoice must be expired (seconds) before we delete it + • enabled (boolean): whether invoice autocleaning is active + + If enabled is true: + + • expired_by (u64): how long an invoice must be expired (seconds) be‐ + fore we delete it + • cycle_seconds (u64): how long an invoice must be expired (seconds) + before we delete it AUTHOR ZmnSCPxj <ZmnSCPxj@protonmail.com> is mainly responsible. ``` Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-06 07:03:09 +09:30
doc: always escape underscores in property names If there's only a single underscore, lowdown ignores it, but if there are multiple (see min_final_cltv_expiry) it decides we're trying to highlight part of the word. Reported-by: @wtogami Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-06 07:15:06 +09:30
- **warning\_usage**: A warning not to prematurely broadcast the funding transaction (always present!)
Add more warnings to fundchannel_start [ Slight modifications to fix schema -- RR ]
2022-03-20 16:07:48 +01:00
doc/schemas: disableoffer, disconnect, feerates, fetchinvoice, fundchannel, fundchannel_cancel, fundchannel_complete, fundchannel_start, fundpsbt, getinfo, getlog, getroute. We also add a test for getlog, since it was never called by the testsuite. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2021-05-26 17:05:01 +09:30
[comment]: # (GENERATE-FROM-SCHEMA-END)
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
doc: list the error codes of funding_* commands Changelog-None
2020-01-05 16:40:17 +01:00
On error the returned object will contain `code` and `message` properties,
with `code` being one of the following:
- -32602: If the given parameters are wrong.
- -1: Catchall nonspecific error.
- 300: The amount exceeded the maximum configured funding amount.
- 301: The provided `push_msat` is greater than the provided `amount`.
- 304: Still syncing with bitcoin network
- 305: Peer is not connected.
Doc: Undocumented parameters in fundchannel_start - Documented `mindepth` and `reserve` in `fundchannel_start`. These parameters are supported but had not been documented (yet). - Removed `mindepth` from return-type. I'm unable to find any scenario in which a value is returned. - Documented the 312 error code
2024-01-02 13:01:37 +01:00
- 306: Unknown peer id
- 312: Peer negotiated `option_dual_fund`, must use `openchannel_init` not `fundchannel_start`. (Only if ``experimental-dual-fund` is enabled)
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
AUTHOR
------
Lisa Neigut <<niftynei@gmail.com>> is mainly responsible.
SEE ALSO
--------
df: add openchannel_abort command Allows us to clean up an in-progress open that we won't be completing Changelog-Added: EXPERIMENTAL JSON-RPC: Permit user-initiated aborting of in-progress opens. Only valid for not-yet-committed opens and RBF-attempts
2021-03-09 15:14:08 -06:00
lightning-connect(7), lightning-fundchannel(7), lightning-multifundchannel(7),
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
lightning-fundchannel\_complete(7), lightning-fundchannel\_cancel(7)
df-doc: add docs for openchannel_bump, more checks for valid psbt Add docs for openchannel_bump, plus some checks that were missed for verifying the amount is valid.
2021-03-10 22:33:47 -06:00
lightning-openchannel\_init(7), lightning-openchannel\_update(7),
df: add openchannel_abort command Allows us to clean up an in-progress open that we won't be completing Changelog-Added: EXPERIMENTAL JSON-RPC: Permit user-initiated aborting of in-progress opens. Only valid for not-yet-committed opens and RBF-attempts
2021-03-09 15:14:08 -06:00
lightning-openchannel\_signed(7), lightning-openchannel\_bump(7),
lightning-openchannel\_abort(7)
doc/manpages: replace asciidoc by markdown
2019-08-10 01:54:18 +02:00
RESOURCES
---------
Main web site: <https://github.com/ElementsProject/lightning>
doc: force refresh of all manpages. The idea is that you regenerate the man pages in the same commit you alter them: that's how we know whether to try regenerating them or not (git doesn't store timestamps, so it can't really tell). Travis will now check this, so force them all to sync to this commit. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2020-08-25 11:03:16 +09:30
fundchannel_start & multifundchannel: add channel_type. Let's tell the caller what channel_type they got! Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Changelog-Added: JSON-RPC: `fundchannel`, `multifundchannel`, `fundchannel_start` and `openchannel_init`: new field `channel_type`.
2024-01-29 10:08:40 +10:30
[comment]: # ( SHA256STAMP:55a714d25c1e01c90076462f022ad814aad42bbf824ba44060d406d53ebcad0c)
Reference in a new issue Copy permalink