openchannel2 -- Hook fired when a peer proposes opening a channel using v2 protocol

DESCRIPTION

The openchannel2 hook is called whenever a remote peer tries to fund a channel using the v2 (dual-funding) protocol, after passing basic sanity checks.

The payload mirrors the BOLT #2 open_channel message and dual-funding extensions.
There may be additional fields present depending on negotiated features.

requested_lease_msat, lease_blockheight_start, and node_blockheight are only present if the peer requested a funding lease (option_will_fund).

The plugin can reject the channel, accept it, or contribute funds via a PSBT when accepting.

See plugins/funder.c for an example of how to use this hook to contribute funds to a channel open.

This is a chained hook: multiple plugins may be invoked.
Returning any result other than "continue" terminates the chain.
Only the first plugin that sets mutation fields (e.g. close_to) will have them applied.
Invalid close_to addresses will cause lightningd to exit.
The PSBT must be consistent with the funding transaction and respect feerate constraints.

HOOK PAYLOAD

• openchannel2 (object):
  • id (pubkey): The node_id of the peer proposing the channel.
  • channel_id (hash): 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.
• 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.
• 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.

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

• error_message (string, optional)