@@ -193,61 +193,68 @@ pub enum ChannelMonitorUpdateErr {
193
193
/// our state failed, but is expected to succeed at some point in the future).
194
194
///
195
195
/// Such a failure will "freeze" a channel, preventing us from revoking old states or
196
- /// submitting new commitment transactions to the counterparty. Once the update(s) that failed
197
- /// have been successfully applied, a [`MonitorEvent::UpdateCompleted`] event should be returned
198
- /// via [`Watch::release_pending_monitor_events`] which will then restore the channel to an
199
- /// operational state.
200
- ///
201
- /// Note that a given ChannelManager will *never* re-generate a given ChannelMonitorUpdate. If
202
- /// you return a TemporaryFailure you must ensure that it is written to disk safely before
203
- /// writing out the latest ChannelManager state.
204
- ///
205
- /// Even when a channel has been "frozen" updates to the ChannelMonitor can continue to occur
206
- /// (eg if an inbound HTLC which we forwarded was claimed upstream resulting in us attempting
207
- /// to claim it on this channel) and those updates must be applied wherever they can be. At
208
- /// least one such updated ChannelMonitor must be persisted otherwise PermanentFailure should
209
- /// be returned to get things on-chain ASAP using only the in-memory copy. Obviously updates to
210
- /// the channel which would invalidate previous ChannelMonitors are not made when a channel has
211
- /// been "frozen".
212
- ///
213
- /// Note that even if updates made after TemporaryFailure succeed you must still provide a
214
- /// [`MonitorEvent::UpdateCompleted`] to ensure you have the latest monitor and re-enable
215
- /// normal channel operation. Note that this is normally generated through a call to
216
- /// [`ChainMonitor::channel_monitor_updated`].
217
- ///
218
- /// Note that the update being processed here will not be replayed for you when you return a
219
- /// [`MonitorEvent::UpdateCompleted`] event via [`Watch::release_pending_monitor_events`], so
220
- /// you must store the update itself on your own local disk prior to returning a
221
- /// TemporaryFailure. You may, of course, employ a journaling approach, storing only the
222
- /// ChannelMonitorUpdate on disk without updating the monitor itself, replaying the journal at
223
- /// reload-time.
196
+ /// submitting new commitment transactions to the counterparty. Once the update(s) which failed
197
+ /// have been successfully applied, [`ChannelManager::channel_monitor_updated`] can be used to
198
+ /// restore the channel to an operational state.
199
+ ///
200
+ /// Note that a given [`ChannelManager`] will *never* re-generate a [`ChannelMonitorUpdate`].
201
+ /// If you return this error you must ensure that it is written to disk safely before writing
202
+ /// the latest [`ChannelManager`] state, or you should return [`PermanentFailure`] instead.
203
+ ///
204
+ /// Even when a channel has been "frozen", updates to the [`ChannelMonitor`] can continue to
205
+ /// occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us
206
+ /// attempting to claim it on this channel) and those updates must still be persisted.
207
+ ///
208
+ /// No updates to the channel will be made which could invalidate other [`ChannelMonitor`]s
209
+ /// until [`ChannelManager::channel_monitor_updated`] is called, even if you return no error on
210
+ /// a later monitor update for the same channel.
224
211
///
225
212
/// For deployments where a copy of ChannelMonitors and other local state are backed up in a
226
213
/// remote location (with local copies persisted immediately), it is anticipated that all
227
214
/// updates will return TemporaryFailure until the remote copies could be updated.
228
215
///
229
- /// [`ChainMonitor::channel_monitor_updated`]: chainmonitor::ChainMonitor::channel_monitor_updated
216
+ /// [`PermanentFailure`]: ChannelMonitorUpdateErr::PermanentFailure
217
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
218
+ /// [`ChannelManager::channel_monitor_updated`]: crate::ln::channelmanager::ChannelManager::channel_monitor_updated
230
219
TemporaryFailure ,
231
- /// Used to indicate no further channel monitor updates will be allowed (eg we've moved on to a
232
- /// different watchtower and cannot update with all watchtowers that were previously informed
233
- /// of this channel).
220
+ /// Used to indicate no further channel monitor updates will be allowed (likely a disk failure
221
+ /// or a remote copy of this [`ChannelMonitor`] is no longer reachable and thus not updatable).
234
222
///
235
- /// At reception of this error, ChannelManager will force-close the channel and return at
236
- /// least a final ChannelMonitorUpdate::ChannelForceClosed which must be delivered to at
237
- /// least one ChannelMonitor copy. Revocation secret MUST NOT be released and offchain channel
238
- /// update must be rejected.
223
+ /// When this is returned, [`ChannelManager`] will force-close the channel but *not* broadcast
224
+ /// our current commitment transaction. This avoids a dangerous case where a local disk failure
225
+ /// (e.g. the Linux-default remounting of the disk as read-only) causes [`PermanentFailure`]s
226
+ /// for all monitor updates. If we were to broadcast our latest commitment transaction and then
227
+ /// restart, we could end up reading a previous [`ChannelMonitor`] and [`ChannelManager`],
228
+ /// revoking our now-broadcasted state before seeing it confirm and losing all our funds.
239
229
///
240
- /// This failure may also signal a failure to update the local persisted copy of one of
241
- /// the channel monitor instance.
230
+ /// Note that this is somewhat of a tradeoff - if the disk is really gone and we may have lost
231
+ /// the data permanently, we really should broadcast immediately. If the data can be recovered
232
+ /// with manual intervention, we'd rather close the channel, rejecting future updates to it,
233
+ /// and broadcast the latest state only if we have HTLCs to claim which are timing out (which
234
+ /// we do as long as blocks are connected).
242
235
///
243
- /// Note that even when you fail a holder commitment transaction update, you must store the
244
- /// update to ensure you can claim from it in case of a duplicate copy of this ChannelMonitor
245
- /// broadcasts it (e.g distributed channel-monitor deployment)
236
+ /// In order to broadcast the latest local commitment transaction, you'll need to call
237
+ /// [`ChannelMonitor::get_latest_holder_commitment_txn`] and broadcast the resulting
238
+ /// transactions once you've safely ensured no further channel updates can be generated by your
239
+ /// [`ChannelManager`].
240
+ ///
241
+ /// Note that at least one final [`ChannelMonitorUpdate`] may still be provided, which must
242
+ /// still be processed by a running [`ChannelMonitor`]. This final update will mark the
243
+ /// [`ChannelMonitor`] as finalized, ensuring no further updates (e.g. revocation of the latest
244
+ /// commitment transaction) are allowed.
245
+ ///
246
+ /// Note that even if you return a [`PermanentFailure`] due to unavailability of secondary
247
+ /// [`ChannelMonitor`] copies, you should still make an attempt to store the update where
248
+ /// possible to ensure you can claim HTLC outputs on the latest commitment transaction
249
+ /// broadcasted later.
246
250
///
247
251
/// In case of distributed watchtowers deployment, the new version must be written to disk, as
248
252
/// state may have been stored but rejected due to a block forcing a commitment broadcast. This
249
253
/// storage is used to claim outputs of rejected state confirmed onchain by another watchtower,
250
254
/// lagging behind on block processing.
255
+ ///
256
+ /// [`PermanentFailure`]: ChannelMonitorUpdateErr::PermanentFailure
257
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
251
258
PermanentFailure ,
252
259
}
253
260
0 commit comments