{ "$schema": "../rpc-schema-draft.json", "type": "object", "rpc": "openchannel_init", "title": "Command to initiate a channel to a peer", "description": [ "`openchannel_init` is a low level RPC command which initiates a channel open with a specified peer. It uses the openchannel protocol which allows for interactive transaction construction." ], "request": { "required": [ "id", "amount", "initialpsbt" ], "additionalProperties": false, "properties": { "id": { "type": "pubkey", "description": [ "Node id of the remote peer." ] }, "amount": { "type": "sat", "description": [ "Satoshi value that we will contribute to the channel. This value will be _added_ to the provided PSBT in the output which is encumbered by the 2-of-2 script for this channel." ] }, "initialpsbt": { "type": "string", "description": [ "Funded, incomplete PSBT that specifies the UTXOs and change output for our channel contribution. It can be updated, see `openchannel_update`; *initialpsbt* must have at least one input. Must have the Non-Witness UTXO (PSBT_IN_NON_WITNESS_UTXO) set for every input. An error (code 309) will be returned if this requirement is not met." ] }, "commitment_feerate": { "type": "feerate", "description": [ "Feerate for commitment transactions for non-anchor channels: see **fundchannel**. For anchor channels, it is ignored." ] }, "funding_feerate": { "type": "feerate", "description": [ "Feerate for the funding transaction." ], "default": "'opening' feerate" }, "announce": { "type": "boolean", "description": [ "Whether or not to announce this channel." ] }, "close_to": { "type": "string", "description": [ "Bitcoin address to which the channel funds should be sent on close. Only valid if both peers have negotiated `option_upfront_shutdown_script`." ] }, "request_amt": { "type": "sat", "description": [ "An amount of liquidity you'd like to lease from the peer. If peer supports `option_will_fund`, indicates to them to include this much liquidity into the channel. Must also pass in *compact_lease*." ] }, "compact_lease": { "type": "hex", "description": [ "A compact representation of the peer's expected channel lease terms. If the peer's terms don't match this set, we will fail to open the channel." ] }, "channel_type": { "type": "array", "description": [ "Each bit set in this channel_type." ], "items": { "type": "u32", "description": [ "Bit number." ] } } } }, "response": { "required": [ "channel_id", "psbt", "channel_type", "commitments_secured", "funding_serial" ], "additionalProperties": false, "properties": { "channel_id": { "type": "hash", "description": [ "The channel id of the channel." ] }, "psbt": { "type": "string", "description": [ "The (incomplete) PSBT of the funding transaction." ] }, "channel_type": { "type": "object", "description": [ "Channel_type as negotiated with peer." ], "added": "v24.02", "additionalProperties": false, "required": [ "bits", "names" ], "properties": { "bits": { "type": "array", "description": [ "Each bit set in this channel_type." ], "added": "v24.02", "items": { "type": "u32", "description": [ "Bit number." ] } }, "names": { "type": "array", "description": [ "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", "items": { "type": "string", "enum": [ "static_remotekey/even", "anchor_outputs/even", "anchors_zero_fee_htlc_tx/even", "anchors/even", "scid_alias/even", "zeroconf/even" ], "description": [ "Name of feature bit." ] } } } }, "commitments_secured": { "type": "boolean", "enum": [ false ], "description": [ "Whether the *psbt* is complete." ] }, "funding_serial": { "type": "u64", "description": [ "The serial_id of the funding output in the *psbt*." ] }, "requires_confirmed_inputs": { "type": "boolean", "description": [ "Does peer require confirmed inputs in psbt?" ] } }, "post_return_value_notes": [ "If the peer does not support `option_dual_fund`, this command will return an error.", "", "If you sent a *request_amt* and the peer supports `option_will_fund` and is interested in leasing you liquidity in this channel, returns their updated channel fee max (*channel_fee_proportional_basis*, *channel_fee_base_msat*), updated rate card for the lease fee (*lease_fee_proportional_basis*, *lease_fee_base_sat*) and their on-chain weight *weight_charge*, which will be added to the lease fee at a rate of *funding_feerate* * *weight_charge* / 1000." ] }, "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 PSBT cannot afford the funding amount.", "- 304: Still syncing with bitcoin network", "- 305: Peer is not connected.", "- 306: Unknown peer id.", "- 309: PSBT missing required fields", "- 310: v2 channel open protocol not supported by peer", "- 312: Channel in an invalid state" ], "author": [ "Lisa Neigut <> is mainly responsible." ], "see_also": [ "lightning-openchannel_update(7)", "lightning-openchannel_signed(7)", "lightning-openchannel_abort(7)", "lightning-openchannel_bump(7)", "lightning-fundchannel_start(7)", "lightning-fundchannel_complete(7)", "lightning-fundchannel(7)", "lightning-fundpsbt(7)", "lightning-utxopsbt(7)", "lightning-multifundchannel(7)" ], "resources": [ "Main web site: " ], "examples": [ { "request": { "id": "example:openchannel_init#1", "method": "openchannel_init", "params": { "id": "03a00f49374e4bb876e766e9305e5fefa86e53dbc89a4f27d794b02f59ca316426", "amount": 1000000, "initialpsbt": "cHNidP8BAF4CAAAAAZiQf/mEs4NcFFfD4K8xauOgSpbz/xeetoXVWAPCI0h6AQAAAAD9////AahhAAAAAAAAIlEg+3d9jpNmK0getyg5W+Mp31CPIRDKcJg/mZs/uaVrQ+GZAAAAAAEAiQIAAAABswU80whDZOoIHS/lfyxwmHh5USHBwbcjWHaJ9/XU+78BAAAAAP3///8CgIQeAAAAAAAiACDJvFwGPK7796bHgUQHtWJ7T4GotW7L6TLGgvnLrA0Z32INzQsAAAAAIlEgyRg+3pEh88b9FJiCLEenYCcyJ2ackJUIhDusW72BP2iYAAAAAQErYg3NCwAAAAAiUSDJGD7ekSHzxv0UmIIsR6dgJzInZpyQlQiEO6xbvYE/aAAA" } }, "response": { "channel_id": "a5be438539f73c018a98a4b9dd557d62430881c56552025b5579d180cc3887ed", "psbt": "cHNidP8BAgQCAAAAAQMEmQAAAAEEAQEBBQECAQYBAwH7BAIAAAAAAQCJAgAAAAGzBTzTCENk6ggdL+V/LHCYeHlRIcHBtyNYdon39dT7vwEAAAAA/f///wKAhB4AAAAAACIAIMm8XAY8rvv3pseBRAe1YntPgai1bsvpMsaC+cusDRnfYg3NCwAAAAAiUSDJGD7ekSHzxv0UmIIsR6dgJzInZpyQlQiEO6xbvYE/aJgAAAABAStiDc0LAAAAACJRIMkYPt6RIfPG/RSYgixHp2AnMidmnJCVCIQ7rFu9gT9oAQ4gmJB/+YSzg1wUV8PgrzFq46BKlvP/F562hdVYA8IjSHoBDwQBAAAAARAE/f///wz8CWxpZ2h0bmluZwEI/+im2BTLcnwAAQMIqGEAAAAAAAABBCJRIPt3fY6TZitIHrcoOVvjKd9QjyEQynCYP5mbP7mla0PhDPwJbGlnaHRuaW5nAQhfx1o3nKFaVgABAwhAQg8AAAAAAAEEIgAgBkixRgS2irzkjzD4bs/Wm7V/PQFNNgUvPR5aBVpSJHoM/AlsaWdodG5pbmcBCHHI3g73GwAQAA==", "channel_type": { "bits": [ 12, 22 ], "names": [ "static_remotekey/even", "anchors/even" ] }, "commitments_secured": false, "funding_serial": 8199047277484638000, "requires_confirmed_inputs": false } }, { "request": { "id": "example:openchannel_init#2", "method": "openchannel_init", "params": [ "03a00f49374e4bb876e766e9305e5fefa86e53dbc89a4f27d794b02f59ca316426", 500000, "cHNidP8BAF4CAAAAAZiQf/mEs4NcFFfD4K8xauOgSpbz/xeetoXVWAPCI0h6AQAAAAD9////AfZRxQsAAAAAIlEg21kTTo7K2doCG6F2JqgaDjc1kRCrH7AL08oPVVJhuE+ZAAAAAAEAiQIAAAABswU80whDZOoIHS/lfyxwmHh5USHBwbcjWHaJ9/XU+78BAAAAAP3///8CgIQeAAAAAAAiACDJvFwGPK7796bHgUQHtWJ7T4GotW7L6TLGgvnLrA0Z32INzQsAAAAAIlEgyRg+3pEh88b9FJiCLEenYCcyJ2ackJUIhDusW72BP2iYAAAAAQErYg3NCwAAAAAiUSDJGD7ekSHzxv0UmIIsR6dgJzInZpyQlQiEO6xbvYE/aAAA" ] }, "response": { "channel_id": "b3b2e46371876858784cd1b87ecf406e32d8f98b7a44b7f436d1dca317ce0f1b", "psbt": "cHNidP8BAgQCAAAAAQMEmQAAAAEEAQEBBQECAQYBAwH7BAIAAAAAAQCJAgAAAAGzBTzTCENk6ggdL+V/LHCYeHlRIcHBtyNYdon39dT7vwEAAAAA/f///wKAhB4AAAAAACIAIMm8XAY8rvv3pseBRAe1YntPgai1bsvpMsaC+cusDRnfYg3NCwAAAAAiUSDJGD7ekSHzxv0UmIIsR6dgJzInZpyQlQiEO6xbvYE/aJgAAAABAStiDc0LAAAAACJRIMkYPt6RIfPG/RSYgixHp2AnMidmnJCVCIQ7rFu9gT9oAQ4gmJB/+YSzg1wUV8PgrzFq46BKlvP/F562hdVYA8IjSHoBDwQBAAAAARAE/f///wz8CWxpZ2h0bmluZwEILfzCFE4M1pQAAQMIIKEHAAAAAAABBCIAIMG0H4vceOuMkzqvG9svQmglTygLSd9kn0qrQFRmpEvIDPwJbGlnaHRuaW5nAQhU+Hu3eGH5tgABAwj2UcULAAAAAAEEIlEg21kTTo7K2doCG6F2JqgaDjc1kRCrH7AL08oPVVJhuE8M/AlsaWdodG5pbmcBCG0sGEoFgVYuAA==", "channel_type": { "bits": [ 12, 22 ], "names": [ "static_remotekey/even", "anchors/even" ] }, "commitments_secured": false, "funding_serial": 6122779721339107000, "requires_confirmed_inputs": false } } ] }