LIGHTNING-HOOK-OPENCHANNEL2(7)

LIGHTNING-HOOK-OPENCHANNEL2(7) 💅

okay bestie, pull up a chair — this is the manual page for lightning-hook-openchannel2 (yep, that's the lightning-hook-openchannel2(7) page, section 7, in case you were wondering), and it's genuinely one of the slay-est hooks in the whole Lightning stack. let's get into it 💖

---

✨ NAME ✨

openchannel2 — the hook that fires when a peer proposes opening a channel using v2 protocol. that's it. that's the vibe. 🎀

---

🌸 DESCRIPTION 🌸

so, openchannel2 gets called whenever a remote peer tries to fund a channel using the v2 (dual-funding) protocol — but only after passing the basic sanity checks, obviously. like, we have standards. 🙈

the payload mirrors the BOLT #2 open_channel message and its dual-funding extensions, no cap. and heads up — there may be additional fields present depending on the negotiated features. iykyk. ✨

okay so this part is important: requested_lease_msat, lease_blockheight_start, and node_blockheight are only present if the peer requested a funding lease (option_will_fund). if there's no lease, those three just aren't there. simple as. 💅

your plugin has three moves: reject the channel, accept it, or contribute funds via a PSBT when accepting. main character energy, honestly. 🔥

if you want to see how this is actually done, check plugins/funder.c — that's the example for using this hook to contribute funds to a channel open. go read it, it eats. 👑

now. this is a chained hook, which means multiple plugins may be invoked. and the way that works is — returning any result other than "continue" terminates the chain. that's a full stop on the whole thing, so be careful out there. 😭

also: only the first plugin that sets mutation fields (e.g. close_to) will have them applied. first one wins, everyone after is just vibing in the void. and listen — invalid close_to addresses will cause lightningd to exit. like, dead. gone. so maybe double-check those addresses, bestie. 🫶

last thing: the PSBT must be consistent with the funding transaction and respect feerate constraints. fr fr, don't skip that part. ⭐

---

🦋 HOOK PAYLOAD 🦋

• openchannel2 (object):
  • id (pubkey): the node_id of the peer proposing the channel. who's this diva? 🧚
  • channel_id (hash): the temporary channel_id assigned for this channel negotiation.
  • their_funding_msat (msat): amount contributed by the remote peer to the channel funding transaction.
  • dust_limit_msat (msat): minimum output value below which outputs are considered dust.
  • max_htlc_value_in_flight_msat (msat): maximum total value of outstanding HTLCs allowed in the channel at any time.
  • htlc_minimum_msat (msat): minimum HTLC value the peer will accept.
  • funding_feerate_per_kw (u32): feerate (per kw) used for the funding transaction.
  • commitment_feerate_per_kw (u32): feerate (per kw) used for commitment transactions.
  • feerate_our_max (u32): maximum feerate we are willing to accept for commitment transactions.
  • feerate_our_min (u32): minimum feerate we are willing to accept for commitment transactions.
  • to_self_delay (u16): the number of blocks before they can take their funds if they unilateral close.
  • max_accepted_htlcs (u16): maximum number of HTLC's the remote is allowed to offer at once.
  • channel_flags (u8): channel flags as defined in BOLT #7.
  • locktime (u32): locktime to be used in the funding transaction.
  • channel_max_msat (msat): maximum capacity this channel is allowed to reach.
  • require_confirmed_inputs (boolean): indicates whether the peer requires all funding inputs to be confirmed. (added v23.02) ✅
  • channel_type (object) (added v25.09): 🆕
  • 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 provided by the peer for cooperative close.
  • requested_lease_msat (msat, optional): amount of liquidity the peer is requesting us to lease to them. only present if option_will_fund is negotiated.
  • lease_blockheight_start (u32, optional): blockheight at which the lease period begins. only present if requested_lease_msat is present.
  • node_blockheight (u32, optional): current blockheight of the node. used in conjunction with lease parameters. only present if requested_lease_msat is present.

---

💜 HOOK RETURN 💜

• result (string) (one of "continue", "reject"): indicates whether to accept or reject the channel proposal. returning "continue" allows the channel negotiation to proceed. returning "reject" aborts the channel opening. yes or no, pick one, no in-between. 💀
• error_message (string, optional): error message sent to the peer when rejecting the channel. only valid if result is "reject".
• close_to (string, optional): Bitcoin address to which funds will be sent on cooperative close. must be valid for the current chain or lightningd will exit with an error. ⚠️ seriously.
• psbt (string, optional): Partially Signed Bitcoin Transaction contributing inputs and outputs for the funding transaction. used when the plugin contributes funds to the channel.
• our_funding_msat (msat, optional): amount we contribute to the channel funding. this amount must NOT be included in any outputs in the provided PSBT. change outputs must be included separately. 🙅‍♀️ like, do not do that.

✨ quick recap corner ✨ if result is present, and result is "reject": - error_message (string, optional)

---

and that's the whole page, bestie — you're now legally required to go contribute some funds to a channel 🫶

🎀 this has been lightning-hook-openchannel2(7) from Core Lightning v26.06.9 — go forth and dual-fund, ily, mwah 💖✨