LIGHTNING-FUNDCHANNEL_START(7)

📦

version 26.06.9 · 2 versions

26.06.9 · nixpkgs unstable (latest)
26.04.1 · nixos 26.05

💅 fundchannel_start — initiating channel establishment, the lowkey way 🦋

okay so bestie, you're reading the LIGHTNING-FUNDCHANNEL_START(7) page, straight out of the LIGHTNING manual (section 7, fancy). Sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

fundchannel_start — the command for initiating channel establishment for a lightning channel. it's giving "step one of a glow-up" energy 👑

🌸 SYNOPSIS 🌸

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

she's got a lot of optional args and honestly? iconic for that.

💖 DESCRIPTION 💖

okay so fundchannel_start is a lower level RPC command. it lets a user initiate channel establishment with a peer you're already connected to. think of it as sending the "hey bestie let's open a channel 👀" text.

⚠️ REAL TALK ⚠️ the funding transaction MUST NOT be broadcast until after channel establishment has been successfully completed by running fundchannel_complete, because the commitment transactions for this channel are not secured until the complete command succeeds. broadcasting the transaction before that can lead to unrecoverable loss of funds. like... actual money, gone, no cap. 😭💀

here's the whole cast of parameters, one by one:

id (pubkey) — the peer id you got from connect. bestie's name tag 🎀
amount (sat) — the 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. no rounding shenanigans, fr fr.
feerate (feerate, optional) — feerate for subsequent commitment transactions: see fundchannel. heads up though, 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. do you want the world to know, or is this private? 🙈
close_to (string, optional) — a 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 the 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. it's giving "venmo-ing your ex" energy, be careful 💸😭
mindepth (u32, optional) — number of confirmations required before we consider the channel active. patience is a virtue etc etc ⏳
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. cute little number, that's it 🌈

🎀 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. like please, I am begging 🫶
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!). yes, always. she never misses 💅

🔥 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. vibe check failed 💀
-1 — catchall nonspecific error. the classic "idk what happened" 😭
300 — the amount exceeded the maximum configured funding amount.
301 — the provided push_msat is greater than the provided amount. math is not mathing.
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. give her her flowers, she ate 💐

the whole friend group, honestly 🫶

⭐ 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: