NAME

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

SYNOPSIS

fundchannel_start id amount [feerate announce close_to push_msat channel_type mindepth reserve]

DESCRIPTION

fundchannel_start is a lower level RPC command. It allows a user to initiate 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_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.

• 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 transactions: see fundchannel. Note that this is ignored for channels with option_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 option_upfront_shutdown_script. Returns close_to set to closing script iff is negotiated.

• push_msat (msat, optional): 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.

• 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 channel_type.:

RETURN VALUE

On success, an object is returned, containing:

• funding_address (string): The address to send funding to for the channel. 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):

• 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.

• 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 transaction (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-multifundchannel(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-openchannel_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`"
}