Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 82c7595

Browse files
ZmnSCPxj-jrZmnSCPxj-jr
committedDec 2, 2024
bLIP-56: Pluggable Channel Factories.
1 parent 2d6bc43 commit 82c7595

File tree

2 files changed

+982
-7
lines changed

2 files changed

+982
-7
lines changed
 

‎blip-0002.md

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -45,13 +45,14 @@ Custom feature bits used in the `I` [Bolt 11](https://github.com/lightning/bolts
4545

4646
bLIPs may reserve feature bits by adding them to the following table:
4747

48-
| Bits | Name | Description | Context | Dependencies | Link |
49-
|---------|-----------------------|------------------------------------------------------------|---------|-------------------------|---------------------------|
50-
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
51-
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
52-
| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) |
53-
| 260/261 | `htlc_endorsement` | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) |
54-
| 262/263 | `bolt11_blinded_path` | This invoice may contain a new blinded path tagged field | I | `option_route_blinding` | [bLIP 39](./blip-0039.md) |
48+
| Bits | Name | Description | Context | Dependencies | Link |
49+
|---------|-------------------------------|------------------------------------------------------------|---------|-------------------------|---------------------------|
50+
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
51+
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
52+
| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) |
53+
| 260/261 | `htlc_endorsement` | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) |
54+
| 262/263 | `bolt11_blinded_path` | This invoice may contain a new blinded path tagged field | I | `option_route_blinding` | [bLIP 39](./blip-0039.md) |
55+
| 270/271 | `pluggable_channel_factories` | This node supports channels inside channel factories | I | | [bLIP 56](./blip-0056.md) |
5556

5657
### Messages
5758

@@ -75,6 +76,7 @@ bLIPs may create new messages and reserve their type in the following table:
7576
| 63501 | `hc_updated_fail_htlc` | [bLIP 17](./blip-0017.md) |
7677
| 63499 | `hc_update_fail_malformed_htlc` | [bLIP 17](./blip-0017.md) |
7778
| 63497 | `hc_error` | [bLIP 17](./blip-0017.md) |
79+
| 32800 | `factory_message_id` | [bLIP 56](./blip-0056.md) |
7880

7981
### TLV fields in BOLT messages
8082

@@ -114,6 +116,14 @@ The following table contains extension tlv fields for the `update_add_htlc` mess
114116
| 106823 | `endorsed` | [bLIP 4](./blip-0004.md) |
115117
| 65537 | `extra_fee` | [bLIP 25](./blip-0025.md) |
116118

119+
#### `open_channel`
120+
121+
The following table contains extension tlv fields for the `open_channel` message:
122+
123+
| Type | Name | Link |
124+
|--------|-----------------------------|--------------------------------|
125+
| 65600 | `channel_in_factory` | [bLIP 56](./blip-0056.md) |
126+
117127
#### `ping`
118128

119129
The following table contains extension tlv fields for the `ping` message:

‎blip-0056.md

Lines changed: 965 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,965 @@
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

Comments
 (0)
Please sign in to comment.