lightning-fundchannel_start

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 (msat): 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_zero_fee_htlc_tx (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 (msat, 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. (added v24.02):
      • (string, optional) (one of "static_remotekey/even", "anchor_outputs/even", "anchors_zero_fee_htlc_tx/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)

JSON EXAMPLE

Example 1:

Request:

{
  "id": "example:fundchannel_start#1",
  "method": "fundchannel_start",
  "params": {
    "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
    "amount": 16777216,
    "feerate": null,
    "announce": true,
    "close_to": null,
    "mindepth": null
  }
}

Response:

{
  "funding_address": "bcrt1qtwxd8wg5eanumk86vfeujvp48hfkgannf77evggzct048wggsrxsum2pmm",
  "scriptpubkey": "00205b8cd3b914cf67cdd8fa6273c930353dd36476734fbd962102c2df53b90880cd",
  "warning_usage": "The funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed by running `fundchannel_complete`"
}

Example 2:

Request:

{
  "id": "example:fundchannel_start#2",
  "method": "fundchannel_start",
  "params": {
    "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
    "amount": "100000sat",
    "feerate": null,
    "announce": true,
    "close_to": null,
    "mindepth": null,
    "channel_type": null
  }
}

Response:

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

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