home | help 
LIGHTNING-FUNDCHANNEL_START(7)			  LIGHTNING-FUNDCHANNEL_START(7)

NAME
     fundchannel_start	--  Command  for  initiating channel establishment for a
     lightning channel

SYNOPSIS
     fundchannel_start id amount  [feerate  announce  close_to	push_msat  chan-
     nel_type mindepth reserve]

DESCRIPTION
     fundchannel_start	is a lower level RPC command. It allows a user to initi-
     ate channel establishment with a connected peer.

     Note that the funding transaction MUST NOT be broadcast until after channel
     establishment has been successfully completed by  running	fundchannel_com-
     plete,  as the commitment transactions for this channel are not secured un-
     til the complete command succeeds. Broadcasting transaction before that can
     lead to unrecoverable loss of funds.

     *	id (pubkey): The peer id obtained from connect.
     *	amount (sat): Satoshi value that the channel will  be  funded  at.  This
	value MUST be accurate, otherwise the negotiated commitment transactions
	will not encompass the correct channel value.
     *	feerate  (feerate, optional): Feerate for subsequent commitment transac-
	tions: see fundchannel. Note that this is ignored for channels with  op-
	tion_anchors (we always use a low commitment fee for these).
     *	announce (boolean, optional): Whether or not to announce this channel.
     *	close_to  (string, optional): Bitcoin address to which the channel funds
	should be sent to on close. Only valid if both peers have negotiated op-
	tion_upfront_shutdown_script. Returns close_to set to closing script iff
	is negotiated.
     *	push_msat (msat, optional): Amount of millisatoshis to push to the chan-
	nel 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.
     *	mindepth  (u32,  optional):  Number  of confirmations required before we
	consider the channel active.
     *	reserve (sat, optional): The amount we want the peer to maintain on  its
	side.
     *	channel_type  (array  of  u32s,  optional):  Each  bit set in this chan-
	nel_type.:
	*  (u32, optional): Bit number.

RETURN VALUE
     On success, an object is returned, containing:

     *	funding_address (string): The address to send funding to for  the  chan-
	nel. DO NOT SEND COINS TO THIS ADDRESS YET.
     *	scriptpubkey (hex): The raw scriptPubkey for the address.
     *	channel_type  (object,	optional): Channel_type as negotiated with peer.
	(added v24.02):
	*  bits (array of u32s): Each  bit  set  in  this  channel_type.  (added
	   v24.02):
	*  (u32, optional): Bit number.
	*  names (array of strings): Feature name for each bit set in this chan-
	   nel_type.  Note that anchors_zero_fee_htlc_tx is a deprecated synonym
	   for anchors. (added v24.02):
	*  (string,  optional)	(one  of  "static_remotekey/even",  "anchor_out-
	   puts/even",	    "anchors_zero_fee_htlc_tx/even",	 "anchors/even",
	   "scid_alias/even", "zeroconf/even"): Name of feature bit.
     *	close_to (hex, optional): The raw scriptPubkey which mutual  close  will
	go  to;  only  present if close_to parameter was specified and peer sup-
	ports option_upfront_shutdown_script.
     *	mindepth (u32, optional): Number of confirmations before we consider the
	channel active.

     The following warnings may also be returned:

     *	warning_usage: A warning not to prematurely broadcast the funding trans-
	action (always present!).

ERRORS
     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.
     *	306: Unknown peer id.
     *	312: Peer negotiated option_dual_fund,	must  use  openchannel_init  not
	fundchannel_start. (Only if ``experimental-dual-fund is enabled)

AUTHOR
     Lisa Neigut niftynei@gmail.com is mainly responsible.

SEE ALSO
     lightning-connect(7),   lightning-fundchannel(7),	lightning-multifundchan-
     nel(7), lightning-fundchannel_complete(7), lightning-fundchannel_cancel(7),
     lightning-openchannel_init(7), lightning-openchannel_update(7),  lightning-
     openchannel_signed(7),  lightning-openchannel_bump(7),  lightning-openchan-
     nel_abort(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli fundchannel_start "nodeid101010101010101010101010101010101010101010101010101010101010" "16777216"

     {
       "id": "example:fundchannel_start#1",
       "method": "fundchannel_start",
       "params": [
	 "nodeid101010101010101010101010101010101010101010101010101010101010",
	 16777216
       ]
     }

     Response:

     {
       "funding_address": "bcrt1p0002020202020202020202020202020202020202020202020202020202",
       "scriptpubkey": "scriptpubkey01010101010101010101010101010101010101010101010101010101",
       "channel_type": {
	 "bits": [
	   12,
	   22
	 ],
	 "names": [
	   "static_remotekey/even",
	   "anchors/even"
	 ]
       },
       "warning_usage": "The funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed by running `fundchannel_complete`"
     }

     Example 2:

     Request:

     $ lightning-cli fundchannel_start -k "id"="nodeid101010101010101010101010101010101010101010101010101010101010" "amount"=16777216

     {
       "id": "example:fundchannel_start#2",
       "method": "fundchannel_start",
       "params": {
	 "id": "nodeid101010101010101010101010101010101010101010101010101010101010",
	 "amount": 16777216
       }
     }

     Response:

     {
       "funding_address": "bcrt1p0003030303030303030303030303030303030303030303030303030303",
       "scriptpubkey": "scriptpubkey02020202020202020202020202020202020202020202020202020202",
       "channel_type": {
	 "bits": [
	   12,
	   22
	 ],
	 "names": [
	   "static_remotekey/even",
	   "anchors/even"
	 ]
       },
       "warning_usage": "The funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed by running `fundchannel_complete`"
     }

Core Lightning v26.06.1 			  LIGHTNING-FUNDCHANNEL_START(7)
home | help