|
| 1 | +``` |
| 2 | +bLIP: TBD |
| 3 | +Title: Pluggable Channel Factories |
| 4 | +Status: Draft |
| 5 | +Author: ZmnSCPxj jxPCSnmZ <zmnscpxj@protonmail.com> |
| 6 | +Created: 2024-11-11 |
| 7 | +* Post-History: https://delvingbitcoin.org/t/pluggable-channel-factories/1252 |
| 8 | +License: CC0 |
| 9 | +``` |
| 10 | + |
| 11 | +Abstract |
| 12 | +======== |
| 13 | + |
| 14 | +Pluggable channel factories are a way of modifying existing Lightning Network |
| 15 | +node software to allow them to manage channel state and payment forwarding |
| 16 | +state for channels hosted inside channel factories. |
| 17 | +The existing node software would only be aware that the channel is hosted inside |
| 18 | +*some* channel factory, while additional software could be connected to it |
| 19 | +("plugged in" via some plugin or equivalent mechanism, such as side daemons in |
| 20 | +LND or trait-implementing client structures in LDK) that handles the details of the |
| 21 | +channel factory itself. |
| 22 | +This neatly divides responsibility: existing node software handles in-channel |
| 23 | +state and payment forwarding, while the "plugin" software handles the channel |
| 24 | +factory state. |
| 25 | + |
| 26 | +Copyright |
| 27 | +========= |
| 28 | + |
| 29 | +This bLIP is licensed under CC0. |
| 30 | + |
| 31 | +Rationale |
| 32 | +========= |
| 33 | + |
| 34 | +Channel factories are multiparty (N > 2) offchain constructions that themselves |
| 35 | +contain multiple 2-party offchain channels. |
| 36 | + |
| 37 | +For the most part, 2-party channels, whether hosted directly from a UTXO confirmed |
| 38 | +on the blockchain, or inside a channel factory, work the same, and the messages |
| 39 | +and transactions involved would be largely identical. |
| 40 | + |
| 41 | +We can therefore consider that existing software that handles channel state and |
| 42 | +payment forwarding can be minimally modified to support channels that are inside a |
| 43 | +channel factory instead of on the blockchain. |
| 44 | + |
| 45 | +In addition, many existing Lightning Network node software, such as CLN, Eclair, |
| 46 | +LND, and LDK, all have mechanisms by which additional code can be attached to them |
| 47 | +to modify their operation. |
| 48 | +CLN and Eclair have plugins, LND has side daemons, and LDK has trait-implementing |
| 49 | +client structures. |
| 50 | +Thus, it would be conceivable for these node software to expose additional |
| 51 | +interfaces to their plugin (or equivalent) interfaces, where the plugin can manage |
| 52 | +state for a channel factory, and the actual node software manages the state for |
| 53 | +the channels inside the channel factory. |
| 54 | + |
| 55 | +This bLIP thus describes a common protocol for node software to agree that some |
| 56 | +channel being managed with a peer is inside a channel factory, and for operations |
| 57 | +that change the capacity of that channel. |
| 58 | +It also describes a protocol that the factory protocol plugin can use to tunnel |
| 59 | +its messages for other participants in the same factory instance. |
| 60 | + |
| 61 | +Glossary |
| 62 | +======== |
| 63 | + |
| 64 | +* Channel Factory Protocol Identifier (`factory_protocol_id`) - a 256-bit |
| 65 | + identifier that identifies the protocol of the channel factory. |
| 66 | + - It is recommended, but not required, that the `factory_protocol_id` be |
| 67 | + the SHA-256 of the concatenation of the channel factory protocol name and |
| 68 | + major version. |
| 69 | +* Channel Factory Instance Identifier (`factory_instance_id`) - a 256-bit |
| 70 | + identifier that identifies a specific instance of a channel factory |
| 71 | + protocol. |
| 72 | +* Channel Factory Early Warning Time (`factory_early_warning_time`) - a 16-bit |
| 73 | + number, specified per instance of a channel factory, that specifies to the |
| 74 | + node software how early to warn the channel factory plugin that an HTLC is |
| 75 | + about to time out. |
| 76 | +* Channel Factory Sub-message Identifier (`factory_submessage_id`) - a 16-bit |
| 77 | + message identifier, in a separate namespace from the common BOLT messages, |
| 78 | + for all messages related to the pluggable channel factory protocol. |
| 79 | + The "it's okay to be odd" rule also applies to this message identifier. |
| 80 | +* Pluggable Channel Factory Message (`factory_message_id`, 32800) - a 16-bit |
| 81 | + message identifier, with the value 32800, in the namespace of the common |
| 82 | + BOLT messages. |
| 83 | + All messages related to the pluggable channel factory protocol share a |
| 84 | + single `factory_message_id`, and are differentiated by the |
| 85 | + `factory_submessage_id`. |
| 86 | +* Pluggable Channel Factory Feature Bit |
| 87 | + (`pluggable_channel_factories`, 271) - a feature bit, |
| 88 | + index 271, in the namespace of the common BOLT |
| 89 | + feature bits. |
| 90 | + A node which advertises this feature bit in `node_announcement` and |
| 91 | + `init` supports the pluggable channel factory protocol described in this |
| 92 | + document. |
| 93 | +* Channel Factory Plugin - some code that handles channel factory concerns |
| 94 | + for a specific `factory_protocol_id`. |
| 95 | + |
| 96 | +Overview |
| 97 | +======== |
| 98 | + |
| 99 | +This protocol adds the following extensions: |
| 100 | + |
| 101 | +* Adds a feature bit, `pluggable_channel_factories` |
| 102 | + (271), that indicates |
| 103 | + support for this protocol. |
| 104 | +* Adds a TLV, `channel_in_factory` (65600), to the |
| 105 | + `open_channel` message. |
| 106 | +* Slightly modifies the timing of the `channel_ready` |
| 107 | + message if the above TLV is included in |
| 108 | + `open_channel`. |
| 109 | +* Adds a new message, `factory_message_id` (32800), |
| 110 | + that is used for all messages in this protocol. |
| 111 | +* Reuses most of the splicing flow (`stfu` message, |
| 112 | + the `batch` TLV of `commitment_signed`, and |
| 113 | + `next_funding_txid` TLV of `channel_reestablish`) |
| 114 | + for channel factory state changes. |
| 115 | + |
| 116 | +Channel Factory Plugin |
| 117 | +====================== |
| 118 | + |
| 119 | +***How*** the base node software talks to the channel |
| 120 | +factory plugin is not specified by this protocol. |
| 121 | +It depends entirely on the actual node software. |
| 122 | + |
| 123 | +The node software MAY implement a particular channel |
| 124 | +factory protocol "built in", i.e. without implementing |
| 125 | +some plugin interface, and implementing all the code |
| 126 | +necessary for that particular channel factory protocol |
| 127 | +to work. |
| 128 | +However, in the rest of this document, I will describe |
| 129 | +the "base" node software as checking with its channel |
| 130 | +factory plugin. |
| 131 | +This means that the base node software checks if there |
| 132 | +is some code (built in, or connected via some plugin |
| 133 | +or equivalent interface) that implements a particular |
| 134 | +`factory_protocol_id`, and then passes as much |
| 135 | +information to that code as possible, which then |
| 136 | +should indicate whether validation passes or fails. |
| 137 | + |
| 138 | +The "base" node software is something like CLN, LND, |
| 139 | +LDK, Eclair, etc., which handles the in-channel states |
| 140 | +as well as changing the channel funding outpoint |
| 141 | +whenever the channel factory itself changes state. |
| 142 | +The base node software has to implement the protocol |
| 143 | +described in this document. |
| 144 | +The "channel factory plugin" is additional code, which |
| 145 | +may or may not be built-in to the base node software, |
| 146 | +which directly handles the channel factory state. |
| 147 | + |
| 148 | +In this document, validation requirements are |
| 149 | +indicated for the "base" node software. |
| 150 | +Some additional validation would then be delegated |
| 151 | +to the channel factory plugin, and specified as such, |
| 152 | +but the specific validation details would vary |
| 153 | +depending on the actual channel factory protocol, |
| 154 | +and are not in the scope of this document. |
| 155 | + |
| 156 | +New `open_channel` TLV (`channel_in_factory`, 65600) |
| 157 | +==================================================== |
| 158 | + |
| 159 | +A new TLV for `open_channel` indicates that the channel |
| 160 | +to be opened is actually inside a channel factory, |
| 161 | +with the factory protocol indicated, as well as the |
| 162 | +specific instance of the factory. |
| 163 | +It also indicates the "early warning time" that the |
| 164 | +base node software needs to warn its instance of the |
| 165 | +factory plugin, before an HTLC times out. |
| 166 | + |
| 167 | +1. types: |
| 168 | + 1. type: 65600 (`channel_in_factory`) |
| 169 | + 2. data: |
| 170 | + * [`32 * u8`: `factory_protocol_id`] |
| 171 | + * [`32 * u8`: `factory_instance_id`] |
| 172 | + * [`u16`: `factory_early_warning_time`] |
| 173 | + |
| 174 | +Requirements: |
| 175 | + |
| 176 | +The sender: |
| 177 | + |
| 178 | +* MUST NOT include the `channel_in_factory` TLV, unless |
| 179 | + all of the below are true: |
| 180 | + - The peer advertised support for the specified |
| 181 | + `factory_protocol_id`. |
| 182 | + - The channel factory plugin (or equivalent) specified |
| 183 | + that this TLV is to be included, and specified the |
| 184 | + information `factory_protocol_id`, |
| 185 | + `factory_instance_id`, and `factory_early_warning_time`. |
| 186 | +* MUST indicate `option_zeroconf` for the channel if it |
| 187 | + includes `channel_in_factory` TLV. |
| 188 | + |
| 189 | +The receiver, if it receives an `open_channel` with a |
| 190 | +`channel_in_factory` TLV: |
| 191 | + |
| 192 | +* MUST validate that it advertised support for the specified |
| 193 | + `factory_protocol_id`. |
| 194 | +* MUST check, with its channel factory plugin (or equivalent) |
| 195 | + that the `factory_instance_id` and `factory_early_warning_time`, |
| 196 | + as well as the other fields of `open_channel`, are |
| 197 | + valid for the channel being opened. |
| 198 | + - If the channel factory plugin indicates validation |
| 199 | + failure, MUST reject the channel by sending |
| 200 | + `error`. |
| 201 | +* MUST check that `option_zeroconf` channel type is set. |
| 202 | +* MUST fail the channel if the above validation fails. |
| 203 | +* SHOULD accept the channel otherwise. |
| 204 | + |
| 205 | +If an openv1 channel open is started with `channel_in_factory` |
| 206 | +TLV, the channel opening flow is subsequently modified: |
| 207 | + |
| 208 | +* Both peers MUST save the contents of `channel_in_factory` |
| 209 | + in persistent storage, associated with the channel, until |
| 210 | + the channel can be safely forgotten. |
| 211 | +* `funding_created`: |
| 212 | + * The sender MUST use a `funding_txid` and |
| 213 | + `funding_output_index` specified by the channel factory |
| 214 | + plugin (or equivalent). |
| 215 | + * The receiver MUST check, with its channel factory plugin |
| 216 | + (or equivalent) that the `funding_txid` and |
| 217 | + `funding_output_index` are valid for the specific channel |
| 218 | + that is being constructed. |
| 219 | +* `channel_ready`: |
| 220 | + * Both peers MUST check, with their respective |
| 221 | + channel factory plugin (or equivalent) *when* the |
| 222 | + `channel_ready` message is to be sent. |
| 223 | + Even if `option_zeroconf` is required to be set, |
| 224 | + the base node software must wait for the channel |
| 225 | + factory plugin to complete setting up of the |
| 226 | + channel factory state to include the new channel, |
| 227 | + before accepting transfers on that channel. |
| 228 | +* The fundee MUST NOT forget the channel even if the channel |
| 229 | + funding transaction is not confirmed within 2016 blocks. |
| 230 | +* The funder MUST NOT broadcast the channel funding |
| 231 | + transaction. |
| 232 | + - The base node software of the funder node should |
| 233 | + not have access to this transaction, and even if |
| 234 | + it does, should not broadcast it itself; broadcast |
| 235 | + of any transactions would need to be initiated by |
| 236 | + the channel factory plugin (or equivalent). |
| 237 | + |
| 238 | +In addition, if a channel was opened with |
| 239 | +`channel_in_factory`, the following additional restrictions |
| 240 | +on update messages exist: |
| 241 | + |
| 242 | +* `update_add_htlc`: |
| 243 | + * The sender MUST set `cltv_expiry` to greater than or |
| 244 | + equal to the current block height plus |
| 245 | + `factory_early_warning_time` plus 1. |
| 246 | + - If the sender would fail this check due to a |
| 247 | + forwarding request, SHOULD fail the forward |
| 248 | + with `expiry_too_soon`. |
| 249 | + * The receiver MUST check that `cltv_expiry` is greater |
| 250 | + than or equal to the current block height plus |
| 251 | + `factory_early_warning_time` plus 1. |
| 252 | + - if this validation fails, MUST send `error` and |
| 253 | + fail the channel. |
| 254 | + |
| 255 | +If a channel was opened with `channel_in_factory`: |
| 256 | + |
| 257 | +* If the node has a pending offered HTLC on the |
| 258 | + channel, and the current block height plus |
| 259 | + `factory_early_warning_time` is greater than or |
| 260 | + equal to the `cltv_expiry` of the HTLC, it MUST |
| 261 | + raise an ignorable event to the channel factory |
| 262 | + plugin regarding this early warning of an impending |
| 263 | + HTLC timeout. |
| 264 | +* If the node would fail the channel, or otherwise |
| 265 | + close the channel (such as by a closure request by |
| 266 | + the human operator), it MUST raise an ignorable event |
| 267 | + to the channel factory plugin. |
| 268 | + - The plugin SHOULD broadcast any parent transactions |
| 269 | + as well as the funding transaction for the channel, |
| 270 | + but MAY elect not to do so depending on the |
| 271 | + channel factory protocol. |
| 272 | + - The base node software MUST persist the failed |
| 273 | + state and treat the channel as closed, but remember |
| 274 | + its latest signed commitment transactions, until |
| 275 | + the base node software sees the funding transaction |
| 276 | + confirmed, or until the plugin indicates to |
| 277 | + forget the channel completely. |
| 278 | + - On node restart, the base node software MUST |
| 279 | + raise the same event to the relevant plugin, as |
| 280 | + long as it has a closed in-factory channel where |
| 281 | + it has not seen any funding transaction confirmed, |
| 282 | + and which the plugin has not indicated to forget. |
| 283 | + - The base node software MUST NOT broadcast the |
| 284 | + latest commitment transaction until it has seen |
| 285 | + one of the possible funding transactions confirmed. |
| 286 | +* The channel factory plugin MAY indicate to completely |
| 287 | + forget about the channel at any time, including after |
| 288 | + the base node software indicates it will fail or |
| 289 | + close the channel. |
| 290 | + - The base node software MUST treat the forgotten |
| 291 | + channel as successfully closed with deep |
| 292 | + confirmation of the closure, even if it did not |
| 293 | + successfully broadcast and confirm a commitment |
| 294 | + transaction for the channel. |
| 295 | + - The base node software MAY remember the previous |
| 296 | + existence of the forgotten channel for reporting |
| 297 | + to the human operator, and SHOULD forget any |
| 298 | + cryptographic data, such as historical HTLCs, |
| 299 | + revocation keys, and commitment transaction |
| 300 | + signatures, that it would normally forget about a |
| 301 | + long-closed channel. |
| 302 | + - **Rationale** A channel factory protocol may itself |
| 303 | + have a punishment mechanism (outside of the BOLT |
| 304 | + punishment mechanism) where a hosted channel |
| 305 | + is invalidated, with all in-channel funds sent as |
| 306 | + compensation to the attempted theft victim. |
| 307 | + In such cases, the state of the channel would |
| 308 | + become moot, and persisted state about it can be |
| 309 | + deleted to free up space. |
| 310 | + |
| 311 | +If any channel of a node was opened with |
| 312 | +`channel_in_factory`: |
| 313 | + |
| 314 | +* When creating an invoice, SHOULD add, to its |
| 315 | + expected `min_final_cltv_expiry_delta`, the highest |
| 316 | + `factory_early_warning_time` amongst all active |
| 317 | + non-`shutdown` channels with sufficient inbound |
| 318 | + liquidity (channels that were not opened with |
| 319 | + `channel_in_factory` consider their |
| 320 | + `factory_early_warning_time` as 0), or any higher |
| 321 | + number. |
| 322 | +* When sending a payment, SHOULD ensure that, if it |
| 323 | + uses a `channel_in_factory` channel as the first |
| 324 | + hop, it sends an HTLC with timeout of at least |
| 325 | + `factory_early_warning_time` plus current |
| 326 | + blockheight plus the second hop's `cltv_delta` |
| 327 | + (or `min_final_cltv_expiry_delta` if the direct |
| 328 | + peer is the final payee). |
| 329 | + |
| 330 | +New `factory_message_id` Message Type |
| 331 | +===================================== |
| 332 | + |
| 333 | +A new `factory_message_id` (32800) is used to multiplex all |
| 334 | +messages related to pluggable channel factories: |
| 335 | + |
| 336 | +1. type: 32800 (`factory_message_id`) |
| 337 | +2. data: |
| 338 | + * [`u16` : `factory_submessage_id`] |
| 339 | +3. `tlv_stream` : `factory_message_tlvs` |
| 340 | +4. types: depends on `factory_submessage_id` |
| 341 | + |
| 342 | +The subsections below describe the valid values of |
| 343 | +`factory_submessage_id` and their respective TLVs. |
| 344 | + |
| 345 | +> **Rationale** A single message ID is allocated |
| 346 | +> so that future extensions to this protocol can |
| 347 | +> use the full 16 bits of the `factory_submessage_id` |
| 348 | +> without having to continuously add to blip-002. |
| 349 | +
|
| 350 | +The `supported_factory_protocols` Message |
| 351 | +----------------------------------------- |
| 352 | + |
| 353 | +The `supported_factory_protocols` (`2`) message informs |
| 354 | +the peer of the `factory_protocol_id`s a node supports. |
| 355 | + |
| 356 | +1. type: 32800 (`factory_message_id`) |
| 357 | +2. data: |
| 358 | + * [`u16` : `0x0002` (`supported_factory_protocols`)] |
| 359 | +3. `tlv_stream` : `factory_message_tlvs` |
| 360 | +4. types |
| 361 | + 1. type: 512 (`factory_protocol_ids_tlv`) |
| 362 | + 2. data: |
| 363 | + * [`... * 32 * u8` : `supported_factory_protocol_ids`] |
| 364 | + |
| 365 | +Requirements: |
| 366 | + |
| 367 | +Nodes: |
| 368 | + |
| 369 | +* MUST send this message after receiving `init` message |
| 370 | + from a peer, if that peer indicates support for |
| 371 | + pluggable channel factories feature bit |
| 372 | + (`pluggable_channel_factories`, 271). |
| 373 | + |
| 374 | +The sender: |
| 375 | + |
| 376 | +* MUST include `factory_protocol_ids_tlv`. |
| 377 | +* MAY set `factory_protocol_ids_tlv` to 0 length, |
| 378 | + indicating it does not actually support any actual |
| 379 | + channel factory protocols. |
| 380 | + |
| 381 | +The receiver: |
| 382 | + |
| 383 | +* MUST check that `factory_protocol_ids_tlv` exists |
| 384 | + and has length that is a multiple of 32 bytes, |
| 385 | + including 0. |
| 386 | + - If not, MUST send `warning` and close the |
| 387 | + connection. |
| 388 | +* SHOULD store the union of its set of supported |
| 389 | + `factory_protocol_id`s and the set sent by the peer, |
| 390 | + and make this available to any channel factory plugin |
| 391 | + (or equivalent) it has. |
| 392 | + |
| 393 | +The `factory_piggyback` Message |
| 394 | +------------------------------- |
| 395 | + |
| 396 | +The `factory_piggyback` (`4`) message is intended to |
| 397 | +be used by the channel factory plugin (or equivalent) |
| 398 | +to directly communicate with its counterpart on the |
| 399 | +peer. |
| 400 | + |
| 401 | +1. type: 32800 (`factory_message_id`) |
| 402 | +2. data: |
| 403 | + * [`u16` : `0x0004` (`factory_piggyback`)] |
| 404 | +3. `tlv_stream` : `factory_message_tlvs` |
| 405 | +4. types: |
| 406 | + 1. type: 0 (`factory_protocol_id_tlv`) |
| 407 | + 2. data: |
| 408 | + * [`32 * u8` : `factory_protocol_id`] |
| 409 | + 3. type: 1024 (`factory_piggyback_payload_tlv`) |
| 410 | + 4. data: |
| 411 | + * [`...*byte`: `factory_piggyback_payload`] |
| 412 | + |
| 413 | +Requirements: |
| 414 | + |
| 415 | +The sender: |
| 416 | + |
| 417 | +* MUST NOT send this message unless indicated by the |
| 418 | + channel factory plugin (or equivalent). |
| 419 | +* MUST include `factory_protocol_id_tlv` and |
| 420 | + `factory_piggyback_payload_tlv`. |
| 421 | +* MUST set `factory_protocol_id` to a value that |
| 422 | + is advertised by itself *and* by the receiver in |
| 423 | + their respective `supported_factory_protocols`. |
| 424 | + - SHOULD consider it an error of the plugin if the |
| 425 | + plugin indicates sending a message to a peer that |
| 426 | + does not support its indicated |
| 427 | + `factory_protocol_id`. |
| 428 | + |
| 429 | +The receiver: |
| 430 | + |
| 431 | +* MUST check that `factory_protocol_id_tlv` and |
| 432 | + `factory_piggyback_payload_tlv` are included. |
| 433 | +* MUST check that it advertised support of the |
| 434 | + indicated `factory_protocol_id`. |
| 435 | +* If the above validation fails, MUST send |
| 436 | + `warning` and close the connection. |
| 437 | + |
| 438 | +On receiving and validating this message, the base |
| 439 | +node software SHOULD pass it to the channel factory |
| 440 | +plugin (or equivalent), which then interprets the |
| 441 | +`factory_piggyback_payload` depending on the |
| 442 | +channel fatory protocol. |
| 443 | +The exact format of the data inside the payload is |
| 444 | +outside the scope of this document. |
| 445 | + |
| 446 | +The Channel Factory State Change Flow |
| 447 | +------------------------------------- |
| 448 | + |
| 449 | +The state of the channel factory layer can change, |
| 450 | +and this change in state is likely to cause the |
| 451 | +funding transactions of channels hosted inside it to |
| 452 | +also change, whether or not the channels change |
| 453 | +their capacity. |
| 454 | + |
| 455 | +The channel factory state change flow co-opts some |
| 456 | +steps of the onchain splicing flow (feature 62/63, |
| 457 | +[BOLTs pull request 1160][]). |
| 458 | + |
| 459 | +[BOLTs pull request 1160]: https://github.com/lightning/bolts/pull/1160 |
| 460 | + |
| 461 | +The overall flow of splicing is below: |
| 462 | + |
| 463 | +1. The channel must be quiesced with [the `stfu` |
| 464 | + message](https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#stfu). |
| 465 | +2. A peer sends `splice_init`, and the peers exchange |
| 466 | + `tx_add_input` and `tx_add_output` messages until |
| 467 | + they are satisfied and end with `tx_complete`, |
| 468 | + then they exchange an initial `commitment_signed` |
| 469 | + for the post-splice state. |
| 470 | +3. The peers sign the splice transaction with |
| 471 | + `tx_signature`. |
| 472 | +4. The peers then resume the channel. |
| 473 | + In this intermediate state, the peers exchange |
| 474 | + multiple `commitment_signed` messages for each |
| 475 | + channel state update, using the `batch` TLV, |
| 476 | + one for the pre-splice state and one for each |
| 477 | + valid post-splice state. |
| 478 | +5. The splice transaction confirms deeply enough, |
| 479 | + and the peers exchange `splice_locked`. |
| 480 | +6. The channel returns to the "normal" state where |
| 481 | + each channel state only requires one |
| 482 | + `commitment_signed` message without `batch` TLV. |
| 483 | + |
| 484 | +The flow for changing a channel factory state (which |
| 485 | +MAY change the capacity of channels) replaces the |
| 486 | +above flow with some factory messages: |
| 487 | + |
| 488 | +1. The channel must be quiesced with [the `stfu` |
| 489 | + message](https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#stfu). |
| 490 | +2. A peer sends `factory_change_init` containing |
| 491 | + the change in capacity of the channel, then |
| 492 | + the peers agree on the new funding transaction |
| 493 | + outpoint via `factory_change_funding`, |
| 494 | + then they exchange an initial |
| 495 | + `commitment_signed` for the post-change state. |
| 496 | +3. The peers arrange to sign the next channel factory |
| 497 | + state (they need not sign immediately, but they do |
| 498 | + need to start signalling each other to do so). |
| 499 | + This may require piggybacked messages to exchange |
| 500 | + signatures for the new factory state, depending |
| 501 | + on the channel factory details. |
| 502 | + The peers then exchange |
| 503 | + `factory_change_continue` messages containing the |
| 504 | + transaction ID and output number for the hosted |
| 505 | + channel. |
| 506 | +4. The peers then resume the channel. |
| 507 | + In this intermediate state, the peers exchange |
| 508 | + multiple `commitment_signed` messages for each |
| 509 | + channel state update, using the `batch` TLV, |
| 510 | + one for the pre-factory-change state and one for |
| 511 | + each valid post-factory-change state. |
| 512 | +5. The peers make the old channel factory state |
| 513 | + invalid and the new channel factory state valid. |
| 514 | + The peers then exchange `factory_change_locked` |
| 515 | + messages. |
| 516 | +6. The channel returns to the "normal" state where |
| 517 | + each channel state only requires one |
| 518 | + `commitment_signed` message without `batch` TLV. |
| 519 | + |
| 520 | +Co-opting the *channel*-level onchain splicing |
| 521 | +flow does not preclude *factory*-level onchain |
| 522 | +splicing. |
| 523 | +If the factory itself implements splicing (including |
| 524 | +splicing in and out entire channels or even |
| 525 | +participants) then the factory would need to |
| 526 | +construct *some* change in the in-factory state, |
| 527 | +which, at the channel level, can then use this |
| 528 | +flow of changing the hosting factory state. |
| 529 | + |
| 530 | +### The `factory_change_init` and `factory_change_ack` Messages |
| 531 | + |
| 532 | +The `factory_change_init` (`6`) message signals |
| 533 | +the beginning of the change in the channel factory |
| 534 | +state. |
| 535 | +The `factory_change_ack` (`8`) message signals |
| 536 | +that the other side agrees to this change. |
| 537 | +These two messages also indicate the new funding |
| 538 | +outpoint to be used after the change. |
| 539 | + |
| 540 | +Both messages use the same `factory_change_tlv`, |
| 541 | +and optionally may include a piggybacked payload |
| 542 | +via `factory_piggyback_payload_tlv`. |
| 543 | + |
| 544 | +1. type: 32800 (`factory_message_id`) |
| 545 | +2. data: |
| 546 | + * [`u16` : `0x0006` (`factory_change_init`)] |
| 547 | +3. `tlv_stream` : `factory_message_tlvs` |
| 548 | +4. types: |
| 549 | + 1. type: 1024 (`factory_piggyback_payload_tlv`) |
| 550 | + 2. data: |
| 551 | + * [`...*byte`: `factory_piggyback_payload`] |
| 552 | + 3. type: 1536 (`factory_change_tlv`) |
| 553 | + 4. data: |
| 554 | + * [`channel_id` : `channel_id`] |
| 555 | + * [`s64` : `funding_contribution_satoshis`] |
| 556 | + * [`point` : `funding_pubkey`] |
| 557 | + |
| 558 | +Requirements: |
| 559 | + |
| 560 | +The sender: |
| 561 | + |
| 562 | +* MUST NOT send `factory_change_init` if the channel |
| 563 | + is not quiescent. |
| 564 | +* MUST NOT send `factory_change_init` if it is not |
| 565 | + the quiescence initiator. |
| 566 | +* MUST NOT send `factory_change_init` before sending |
| 567 | + `channel_ready`. |
| 568 | +* MUST NOT send `factory_change_init` while another |
| 569 | + factory-level change is being negotiated. |
| 570 | +* MUST NOT send `factory_change_init` if another |
| 571 | + factory-level change has been negotiated but |
| 572 | + `factory_change_locked` has not been sent and |
| 573 | + received. |
| 574 | +* MUST NOT send `factory_change_init` if it has |
| 575 | + sent `shutdown`. |
| 576 | +* MUST NOT send `factory_change_init` unless indicated |
| 577 | + by the channel factory plugin (or equivalent). |
| 578 | +* MUST include `factory_piggyback_payload_tlv` if the |
| 579 | + channel factory plugin indicated a piggybacked |
| 580 | + payload, and MUST NOT include it otherwise. |
| 581 | +* MUST always include `factory_change_tlv`. |
| 582 | +* MUST set `channel_id` to a channel that was opened |
| 583 | + with `channel_in_factory` TLV. |
| 584 | +* MUST set `funding_contribution_satoshis` to 0, |
| 585 | + positive, or a negative amount whose absolute |
| 586 | + value is less than or equal to the sender's |
| 587 | + current channel balance. |
| 588 | + - SHOULD consider it an error of the plugin if the |
| 589 | + plugin indicates using a negative |
| 590 | + `funding_contribution_satoshis` whose absolute |
| 591 | + value is greater than the sender's current channel |
| 592 | + balance. |
| 593 | + - MAY set this to 0 (unlike the splice case, where |
| 594 | + it must be non-0). |
| 595 | +* SHOULD use a different `funding_pubkey` than the |
| 596 | + one used for the previous funding transaction. |
| 597 | + |
| 598 | +The receiver: |
| 599 | + |
| 600 | +* MUST check that the `factory_change_tlv` exists. |
| 601 | + - If not, MUST send `warning` and close the |
| 602 | + connection. |
| 603 | +* MUST check that the `channel_id` refers to a channel |
| 604 | + that was opened with `channel_in_factory`. |
| 605 | + - If not, MUST send `warning` and close the |
| 606 | + connection, or send `error` and fail the channel. |
| 607 | +* MUST check that all the following conditions hold for |
| 608 | + the channel; if any condition does not hold, it MUST |
| 609 | + send a `warning` and close the connection, or send |
| 610 | + `error` and fail the channel: |
| 611 | + - The channel is quiescent. |
| 612 | + - The sender is the quiescence initiator. |
| 613 | + - No other factory-level change is being negotiated |
| 614 | + for this channel. |
| 615 | + - No other factory-level change has been negotiated |
| 616 | + and not locked in yet. |
| 617 | + - `funding_contribution_satoshis` is 0 or positive, |
| 618 | + or if it is negative, has an absolute value that |
| 619 | + is less than or equal to the sender's current |
| 620 | + channel balance. |
| 621 | +* MUST check, with its channel factory plugin (or |
| 622 | + equivalent), that the `channel_id` and |
| 623 | + `funding_contribution_satoshis` from the sender |
| 624 | + are correct, as well as `factory_piggyback_payload` |
| 625 | + if included, as per the channel factory protocol. |
| 626 | + - If the channel factory plugin indicates validation |
| 627 | + failure, MUST send `warning` and close the |
| 628 | + connection or send `error` and fail the channel. |
| 629 | +- MUST respond with `factory_change_ack` after the |
| 630 | + channel factory plugin (or equivalent) has validated |
| 631 | + the incoming message and indicates to respond, which |
| 632 | + can be some time later. |
| 633 | + |
| 634 | +1. type: 32800 (`factory_message_id`) |
| 635 | +2. data: |
| 636 | + * [`u16` : `0x0008` (`factory_change_ack`)] |
| 637 | +3. `tlv_stream` : `factory_message_tlvs` |
| 638 | +4. types: |
| 639 | + 1. type: 1024 (`factory_piggyback_payload_tlv`) |
| 640 | + 2. data: |
| 641 | + * [`...*byte`: `factory_piggyback_payload`] |
| 642 | + 3. type: 1536 (`factory_change_tlv`) |
| 643 | + 4. data: |
| 644 | + * [`channel_id` : `channel_id`] |
| 645 | + * [`s64` : `funding_contribution_satoshis`] |
| 646 | + * [`point` : `funding_pubkey`] |
| 647 | + |
| 648 | +Requirements: |
| 649 | + |
| 650 | +The sender: |
| 651 | + |
| 652 | +* MUST NOT send `factory_change_ack` unless the |
| 653 | + peer sent `factory_change_init`. |
| 654 | +* MUST NOT send `factory_change_ack` unless the |
| 655 | + channel factory plugin (or equivalent) has |
| 656 | + validated the `factory_change_init` from the |
| 657 | + peer, and has indicated the |
| 658 | + `funding_contribution_satoshis` and optionally |
| 659 | + `factory_piggyback_payload` to include. |
| 660 | +* MUST include `factory_piggyback_payload_tlv` if the |
| 661 | + channel factory plugin indicated a piggybacked |
| 662 | + payload, and MUST NOT include it otherwise. |
| 663 | +* MUST always include `factory_change_tlv`. |
| 664 | +* MUST set `funding_contribution_satoshis` to 0, |
| 665 | + positive, or a negative amount whose absolute |
| 666 | + value is less than or equal to the sender's |
| 667 | + current channel balance. |
| 668 | + - SHOULD consider it an error of the plugin if the |
| 669 | + plugin indicates using a negative |
| 670 | + `funding_contribution_satoshis` whose absolute |
| 671 | + value is greater than the sender's current channel |
| 672 | + balance. |
| 673 | +* SHOULD use a different `funding_pubkey` than the |
| 674 | + one used for the previous funding transaction. |
| 675 | +* MUST, after sending `factory_change_ack`, wait for |
| 676 | + the channel factory plugin (or equivalent) to |
| 677 | + provide the funding transaction ID. |
| 678 | + |
| 679 | +The receiver: |
| 680 | + |
| 681 | +* MUST check that the `factory_change_tlv` exists. |
| 682 | + - If not, MUST send `warning` and close the |
| 683 | + connection. |
| 684 | +* If it has not sent `factory_change_init`: |
| 685 | + - MUST send a `warning` and close the connection, |
| 686 | + or send an `error` and fail the channel. |
| 687 | +* MUST check, with its channel factory plugin (or |
| 688 | + equivalent), that the `channel_id` and |
| 689 | + `funding_contribution_satoshis` from the sender |
| 690 | + are correct, as well as `factory_piggyback_payload` |
| 691 | + if included, as per the channel factory protocol, |
| 692 | + and wait for the plugin to provide the funding |
| 693 | + transaction ID. |
| 694 | + - If the channel factory plugin indicates validation |
| 695 | + failure, MUST send `warning` and close the |
| 696 | + connection or send `error` and fail the channel. |
| 697 | + |
| 698 | +### The `factory_change_funding` Message |
| 699 | + |
| 700 | +The `factory_change_funding` (`10`) message is |
| 701 | +exchanged by both peers to agree on the transaction |
| 702 | +ID that the channel factory will use to host the |
| 703 | +channel after the factory-level change. |
| 704 | +It is sent after the `factory_change_init` and |
| 705 | +`factory_change_ack` exchange. |
| 706 | + |
| 707 | +The channel factory plugin (or equivalent) may need to |
| 708 | +initiate factory-level changes across multiple |
| 709 | +channels, with multiple peers,for a single |
| 710 | +factory-level change. |
| 711 | +Once all the channels affected have had factory-level |
| 712 | +changes initiated, the channel factory can determine |
| 713 | +the new funding transactions needed for the affected |
| 714 | +channels. |
| 715 | +Then the plugin can inform the base node software |
| 716 | +about the post-factory-level-change funding |
| 717 | +transaction ID for each affected channel, which the |
| 718 | +base node software counterchecks with the peer |
| 719 | +base node software. |
| 720 | + |
| 721 | +1. type: 32800 (`factory_message_id`) |
| 722 | +2. data: |
| 723 | + * [`u16` : `0x000A` (`factory_change_funding`)] |
| 724 | +3. `tlv_stream` : `factory_message_tlvs` |
| 725 | +4. types: |
| 726 | + 1. type: 2560 (`factory_change_funding_tlv`) |
| 727 | + 2. data: |
| 728 | + * [`channel_id` : `channel_id`] |
| 729 | + * [`sha256` : `funding_txid`] |
| 730 | + * [`u16` : `funding_output_index`] |
| 731 | + |
| 732 | +Requirements: |
| 733 | + |
| 734 | +The sender: |
| 735 | + |
| 736 | +* MUST NOT send `factory_change_funding` until |
| 737 | + after the `factory_change_ack` has been received |
| 738 | + by itself (if it initiated quiescence) or sent |
| 739 | + by itself (if it did not initiate quiescence). |
| 740 | +* MUST NOT send `factory_change_funding` until |
| 741 | + indicated by its channel factory plugin (or |
| 742 | + equivalent), with the plugin also indicating |
| 743 | + the `funding_txid` and `funding_output_index` |
| 744 | + to use. |
| 745 | +* MUST include `factory_change_funding_tlv`. |
| 746 | + |
| 747 | +The receiver: |
| 748 | + |
| 749 | +* MUST check that `factory_change_funding_tlv` |
| 750 | + exists. |
| 751 | + - If not, MUST send `warning` and close the |
| 752 | + connection. |
| 753 | +* MUST check that the given `funding_txid` |
| 754 | + and `funding_output_index` are equal to what |
| 755 | + its own channel factory plugin indicated or |
| 756 | + will later indicate. |
| 757 | + - If not, MUST send `warning` and close the |
| 758 | + connection, or send `error` and fail the |
| 759 | + channel. |
| 760 | + |
| 761 | +After it has both sent and received |
| 762 | +`factory_change_funding`, the node: |
| 763 | + |
| 764 | +* MUST compute the channel balance for each |
| 765 | + side by adding their respective |
| 766 | + `funding_contribution_satoshis` to their |
| 767 | + previous channel balance. |
| 768 | + |
| 769 | +### The `commitment_signed` Message |
| 770 | + |
| 771 | +After exchanging `factory_change_funding`, both |
| 772 | +peers send `commitment_signed` to commit to the |
| 773 | +factory-level change funding transaction (the |
| 774 | +`funding_txid` sent in `factory_change_funding`) |
| 775 | +by creating a commitment transaction spending the new |
| 776 | +agreed-upon funding transaction output. |
| 777 | + |
| 778 | +The usual `commitment_signed` requirements apply |
| 779 | +with the following additional requirements: |
| 780 | + |
| 781 | +The sender: |
| 782 | + |
| 783 | +* MUST create a commitment transaction that spends |
| 784 | + the factory-level change funding transaction |
| 785 | + output, and: |
| 786 | + - Adds `funding_contribution_satoshis` from |
| 787 | + `factory_change_init` and `factory_change_ack` |
| 788 | + to the main balance of their respective sender. |
| 789 | + - Uses the same feerate as the existing commitment |
| 790 | + transaction. |
| 791 | + - Uses the same `commitment_number` as the existing |
| 792 | + commitment transaction. |
| 793 | + - Does not set the `batch` field. |
| 794 | +- MUST send signatures for pending HTLCs. |
| 795 | +- MUST remember the details of the new funding |
| 796 | + transaction output. |
| 797 | + |
| 798 | +The receiver: |
| 799 | + |
| 800 | +* MUST NOT respond with `revoke_and_ack`. |
| 801 | +* If it has not already transmitted its own |
| 802 | + `commitment_signed`: |
| 803 | + - MUST send `commitment_signed`. |
| 804 | + |
| 805 | +On `channel_reestablish` after a reconnection: |
| 806 | + |
| 807 | +* If `next_funding_txid` matches the |
| 808 | + factory-level change funding transaction: |
| 809 | + - MUST retransmit `commitment_signed`. |
| 810 | + |
| 811 | +### The `factory_change_continue` Message |
| 812 | + |
| 813 | +Once the base node software have exchanged |
| 814 | +`commitment_signed`, they indicate this to the |
| 815 | +channel factory plugin (or equivalent). |
| 816 | +The plugin MUST then arrange to make the new state |
| 817 | +of the factory valid. |
| 818 | +How this is done in unspecified; the expectation is |
| 819 | +that the plugin MAY use `factory_piggyback` messages |
| 820 | +to exchange the necessary cryptographic data to |
| 821 | +make the new factory-level state valid. |
| 822 | + |
| 823 | +Once the plugin has made the new factory-level |
| 824 | +state valid, and has reliably persisted this |
| 825 | +information, it then indicates to the base node |
| 826 | +software to exchange `factory_change_continue` (`12`) |
| 827 | +messages. |
| 828 | +The base node software then resume the channel once |
| 829 | +they have both sent and received this message. |
| 830 | + |
| 831 | +1. type: 32800 (`factory_message_id`) |
| 832 | +2. data: |
| 833 | + * [`u16` : `0x000C` (`factory_change_continue`)] |
| 834 | +3. `tlv_stream` : `factory_message_tlvs` |
| 835 | +4. types: |
| 836 | + 1. type: 3072 (`factory_change_continue_tlv`) |
| 837 | + 2. data: |
| 838 | + * [`channel_id` : `channel_id`] |
| 839 | + * [`sha256` : `funding_txid`] |
| 840 | + * [`u16` : `funding_output_index`] |
| 841 | + |
| 842 | +Requirements: |
| 843 | + |
| 844 | +The sender: |
| 845 | + |
| 846 | +* MUST send this message as soon as its channel factory |
| 847 | + plugin (or equivalent) indicates to do so. |
| 848 | +* MUST include `factory_change_continue_tlv`. |
| 849 | +* MUST set `funding_txid` and `funding_output_index` |
| 850 | + to the same values it sent for |
| 851 | + `factory_change_funding`. |
| 852 | + |
| 853 | +The receiver: |
| 854 | + |
| 855 | +* MUST check that the `factoy_change_continue_tlv` |
| 856 | + exists. |
| 857 | + - If not, MUST send a `warning` and close the |
| 858 | + connection. |
| 859 | +* MUST check that the `funding_txid` and |
| 860 | + `funding_output_index` matches with its expected |
| 861 | + values. |
| 862 | + - If not, MUST send an `error` and fail the channel, |
| 863 | + or send a `warning` and close the connection. |
| 864 | +* If it has not yet sent `factory_change_continue`: |
| 865 | + - MUST wait for its channel factory plugin (or |
| 866 | + equivalent) to indicate to send the |
| 867 | + `factory_change_continue` message, and send |
| 868 | + that message. |
| 869 | + |
| 870 | +Nodes: |
| 871 | + |
| 872 | +* If they have sent and received this message: |
| 873 | + - MUST resume the channel (i.e. remove it from |
| 874 | + quiescence state), sending multiple |
| 875 | + `commitment_signed` transactions with `batch` |
| 876 | + TLVs, signing for the current funding transaction |
| 877 | + and all factory-level change funding transactions. |
| 878 | + - MUST wait for their plugin to indicate to send |
| 879 | + `factory_change_locked` messages. |
| 880 | +* On a restart, if they have not sent |
| 881 | + `factory_change_continue` yet: |
| 882 | + - MUST ask their plugin to indicate when to send |
| 883 | + `factory_change_continue` messages. |
| 884 | +* On a restart, if they have sent |
| 885 | + `factory_change_continue`: |
| 886 | + - MUST resend it. |
| 887 | + |
| 888 | +### The `factory_change_locked` Message |
| 889 | + |
| 890 | +After the factory change has been continued by the |
| 891 | +nodes, the channel state itself is now valid for |
| 892 | +both the current and new state of the factory. |
| 893 | +At this point, the channel factory protocol should |
| 894 | +now arrange to invalidate the current factory state, |
| 895 | +so that only the new factory state will be depended |
| 896 | +on. |
| 897 | + |
| 898 | +At this point, the channel factory protocol must |
| 899 | +stabilize to a new state by invalidating the current |
| 900 | +state and making the new state publishable (but not |
| 901 | +yet confirmed) onchain. |
| 902 | + |
| 903 | +The channel factory protocol MAY also negotiate |
| 904 | +another new factory state, by again triggering a |
| 905 | +quiescence period and a `factory_change_init`. |
| 906 | +This implies that *any*, but *at most one*, of the |
| 907 | +possible new factory states could become the true |
| 908 | +new state. |
| 909 | +This parallels splicing, where multiple splice RBFs |
| 910 | +might be done, and at most one splice transaction |
| 911 | +can confirm and become the new funding transaction. |
| 912 | + |
| 913 | +Once the channel factory has stabilized to a new |
| 914 | +state, the channel factory plugins (or equivalent) |
| 915 | +indicate to their respective node software to exchange |
| 916 | +`factory_change_locked` (`14`) messages. |
| 917 | + |
| 918 | +1. type: 32800 (`factory_message_id`) |
| 919 | +2. data: |
| 920 | + * [`u16` : `0x000E` (`factory_change_locked`)] |
| 921 | +3. `tlv_stream` : `factory_message_tlvs` |
| 922 | +4. types: |
| 923 | + 1. type: 3584 (`factory_change_locked_tlv`) |
| 924 | + 2. data: |
| 925 | + * [`channel_id` : `channel_id`] |
| 926 | + * [`sha256` : `locked_funding_txid`] |
| 927 | + |
| 928 | +Requirements: |
| 929 | + |
| 930 | +The sender: |
| 931 | + |
| 932 | +* MUST send this message as soon as its channel factory |
| 933 | + plugin (or equivalent) indicates to do so. |
| 934 | +* MUST include `factory_change_locked_tlv`. |
| 935 | +* MUST set `locked_funding_txid` to a pending |
| 936 | + new factory change funding transaction ID. |
| 937 | + - MUST NOT set `locked_funding_txid` to the previous |
| 938 | + funding transaction of the channel. |
| 939 | + |
| 940 | +The receiver: |
| 941 | + |
| 942 | +* MUST check that the `factory_change_locked_tlv` |
| 943 | + exists. |
| 944 | + - If not, MUST send a `warning` and close the |
| 945 | + connection. |
| 946 | +* MUST check that the given `locked_funding_txid` |
| 947 | + are equal to what its own channel factory plugin |
| 948 | + indicated or will indicate. |
| 949 | + - If not, MUST send `warning` and close the |
| 950 | + connection, or send `error` and fail the channel. |
| 951 | + |
| 952 | +Once a node has both sent and received |
| 953 | +`factory_change_locked`: |
| 954 | + |
| 955 | +- MUST consider the indivated `locked_funding_txid` |
| 956 | + as the new funding transaction for all future |
| 957 | + `commitment_signed` and factory change negotiations. |
| 958 | +- SHOULD discard the previous funding transaction and |
| 959 | + alternative factory changes. |
| 960 | + |
| 961 | +On reconnection, a node: |
| 962 | + |
| 963 | +- MUST retransmit its last `factory_change_locked` |
| 964 | + if the `commitment_number` is the same as before |
| 965 | + sending `factory_change_locked`. |
0 commit comments