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.:
  • (u32, optional): Bit number.

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):
  • 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 channel_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_outputs/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 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 <[email protected]> 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

lightning-cli fundchannel_start "027ba5906fad81fcdbb774b4c806eb572b7fac3bee4720b12c44e7f70931d4b7cc" "16777216"

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

{
  "funding_address": "bcrt1q5ptrvwlgcldm2ygf3nzsl09zfpp7dmtduqlczer97xvc4x5z5zwsc2ulv4",
  "scriptpubkey": "0020a056363be8c7dbb511098cc50fbca24843e6ed6de03f816465f1998a9a82a09d",
  "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`"
}

lightning-cli fundchannel_start -k "id"="027ba5906fad81fcdbb774b4c806eb572b7fac3bee4720b12c44e7f70931d4b7cc" "amount"=16777216

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

{
  "funding_address": "bcrt1q4hz6a4gtecfmy8z870cwkq2gzc0t7n9u9pu23689u55ghwewemqsv4v2zs",
  "scriptpubkey": "0020adc5aed50bce13b21c47f3f0eb0148161ebf4cbc2878a8e8e5e5288bbb2ecec1",
  "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`"
}