LIGHTNING-HOOK-OPENCHANNEL(7)

✨ LIGHTNING-HOOK-OPENCHANNEL(7) ✨

okay so bestie, welcome to lightning-hook-openchannel — the manual page. it's a section 7 one, so it's all about the hook itself, not a command you type. buckle up 💖

---

🌸 NAME 🌸

openchannel — the hook that fires when a peer proposes opening a channel using the v1 protocol. it's giving "hey girl, wanna open a channel" and lightningd's like "hold on, let me ask my plugins first" 🎀

---

🦋 DESCRIPTION 🦋

the openchannel hook gets called whenever a remote peer tries to fund a channel using the v1 protocol — and it only happens after they've passed the basic sanity checks, so no dusty sketchy requests make it this far, periodt ✨

the payload mirrors the BOLT #2 open_channel message and may include extra fields defined by the protocol. iykyk.

plugins can straight up reject the channel or modify certain parameters before accepting it. main character energy fr 💅

this is a chained hook: the first plugin returning a non-"continue" result terminates the chain. the mutation fields (close_to, mindepth, reserve) are only applied from the first plugin that sets them. additional fields may be present in the request as defined by BOLT #2. and 💀 providing invalid values (e.g. an invalid close_to address) will cause lightningd to exit — so like, don't do that, ngl.

---

💜 HOOK PAYLOAD 💜

• openchannel (object) — the whole vibe check, containing:
  • id (pubkey): the peer's node_id. who they are 🫶
  • funding_msat (msat): funding amount proposed by the peer.
  • push_msat (msat): amount pushed to us at channel open.
  • dust_limit_msat (msat): dust limit for outputs.
  • max_htlc_value_in_flight_msat (msat): maximum HTLC value allowed in flight.
  • channel_reserve_msat (msat): channel reserve required by the peer.
  • htlc_minimum_msat (msat): minimum HTLC value.
  • feerate_per_kw (u32): feerate in satoshi per kw.
  • to_self_delay (u32): the number of blocks before they can take their funds if they unilateral close.
  • max_accepted_htlcs (u32): maximum number of HTLC's the remote is allowed to offer at once.
  • channel_flags (u8): channel flags as defined in BOLT #7.
  • channel_type (object) (added v25.09): the new kid on the block 🌈
    • bits (array of u32s): list of feature bit numbers that define the negotiated channel type. each value represents a feature bit as defined in BOLT #2:
      • (u32, optional): feature bit number.
    • names (array of strings): human-readable names corresponding to each feature bit. names are implementation-defined and may evolve over time:
      • (string, optional): name of the feature bit.
  • shutdown_scriptpubkey (hex, optional): optional shutdown scriptPubKey proposed by the peer.

---

⭐ HOOK RETURN ⭐

okay so this is what your plugin sends back when it's done thinking 👑

• result (string) (one of "continue", "reject"): whether to accept or reject the channel opening request.
• error_message (string, optional): optional error message sent to the peer when rejecting. be nice, or don't, your call 🎀
• close_to (string, optional): bitcoin address for mutual close output. must be valid for the current chain or lightningd will exit with an error. no cap on that one 😭
• mindepth (u32, optional): mindepth is the number of confirmations to require before making the channel usable. notice that setting this to 0 (zeroconf) or some other low value might expose you to double-spending issues, so only lower this value from the default if you trust the peer not to double-spend, or you reject incoming payments, including forwards, until the funding is confirmed. (added v0.12.0) ⚠️
• reserve (sat, optional): reserve is an absolute value for the amount (in satoshi) in the channel that the peer must keep on their side. this ensures that they always have something to lose, so only lower this below the 1% of funding amount if you trust the peer. the protocol requires this to be larger than the dust limit, hence it will be adjusted to be the dust limit if the specified value is below. (added v22.11) 🔥

and one last lil detail that's lowkey important:

if result is present, and result is "reject":

• error_message (string, optional)

---

that's the whole page, bestie! slay, you read it all 🌸

signed off with love from Core Lightning v26.06.9 — catch you in the next LIGHTNING-HOOK-OPENCHANNEL(7) manual, mwah 💋👑