|
| 1 | +namespace org { namespace ldk { namespace enums {/** |
| 2 | + * An enum representing the status of a channel monitor update persistence. |
| 3 | + */ |
| 4 | +public enum ChannelMonitorUpdateStatus { |
| 5 | + /** |
| 6 | + * The update has been durably persisted and all copies of the relevant [`ChannelMonitor`] |
| 7 | + * have been updated. |
| 8 | + * |
| 9 | + * This includes performing any `fsync()` calls required to ensure the update is guaranteed to |
| 10 | + * be available on restart even if the application crashes. |
| 11 | + */ |
| 12 | + LDKChannelMonitorUpdateStatus_Completed, |
| 13 | + /** |
| 14 | + * Used to indicate a temporary failure (eg connection to a watchtower or remote backup of |
| 15 | + * our state failed, but is expected to succeed at some point in the future). |
| 16 | + * |
| 17 | + * Such a failure will \"freeze\" a channel, preventing us from revoking old states or |
| 18 | + * submitting new commitment transactions to the counterparty. Once the update(s) which failed |
| 19 | + * have been successfully applied, a [`MonitorEvent::Completed`] can be used to restore the |
| 20 | + * channel to an operational state. |
| 21 | + * |
| 22 | + * Note that a given [`ChannelManager`] will *never* re-generate a [`ChannelMonitorUpdate`]. |
| 23 | + * If you return this error you must ensure that it is written to disk safely before writing |
| 24 | + * the latest [`ChannelManager`] state, or you should return [`PermanentFailure`] instead. |
| 25 | + * |
| 26 | + * Even when a channel has been \"frozen\", updates to the [`ChannelMonitor`] can continue to |
| 27 | + * occur (e.g. if an inbound HTLC which we forwarded was claimed upstream, resulting in us |
| 28 | + * attempting to claim it on this channel) and those updates must still be persisted. |
| 29 | + * |
| 30 | + * No updates to the channel will be made which could invalidate other [`ChannelMonitor`]s |
| 31 | + * until a [`MonitorEvent::Completed`] is provided, even if you return no error on a later |
| 32 | + * monitor update for the same channel. |
| 33 | + * |
| 34 | + * For deployments where a copy of ChannelMonitors and other local state are backed up in a |
| 35 | + * remote location (with local copies persisted immediately), it is anticipated that all |
| 36 | + * updates will return [`InProgress`] until the remote copies could be updated. |
| 37 | + * |
| 38 | + * [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure |
| 39 | + * [`InProgress`]: ChannelMonitorUpdateStatus::InProgress |
| 40 | + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager |
| 41 | + */ |
| 42 | + LDKChannelMonitorUpdateStatus_InProgress, |
| 43 | + /** |
| 44 | + * Used to indicate no further channel monitor updates will be allowed (likely a disk failure |
| 45 | + * or a remote copy of this [`ChannelMonitor`] is no longer reachable and thus not updatable). |
| 46 | + * |
| 47 | + * When this is returned, [`ChannelManager`] will force-close the channel but *not* broadcast |
| 48 | + * our current commitment transaction. This avoids a dangerous case where a local disk failure |
| 49 | + * (e.g. the Linux-default remounting of the disk as read-only) causes [`PermanentFailure`]s |
| 50 | + * for all monitor updates. If we were to broadcast our latest commitment transaction and then |
| 51 | + * restart, we could end up reading a previous [`ChannelMonitor`] and [`ChannelManager`], |
| 52 | + * revoking our now-broadcasted state before seeing it confirm and losing all our funds. |
| 53 | + * |
| 54 | + * Note that this is somewhat of a tradeoff - if the disk is really gone and we may have lost |
| 55 | + * the data permanently, we really should broadcast immediately. If the data can be recovered |
| 56 | + * with manual intervention, we'd rather close the channel, rejecting future updates to it, |
| 57 | + * and broadcast the latest state only if we have HTLCs to claim which are timing out (which |
| 58 | + * we do as long as blocks are connected). |
| 59 | + * |
| 60 | + * In order to broadcast the latest local commitment transaction, you'll need to call |
| 61 | + * [`ChannelMonitor::get_latest_holder_commitment_txn`] and broadcast the resulting |
| 62 | + * transactions once you've safely ensured no further channel updates can be generated by your |
| 63 | + * [`ChannelManager`]. |
| 64 | + * |
| 65 | + * Note that at least one final [`ChannelMonitorUpdate`] may still be provided, which must |
| 66 | + * still be processed by a running [`ChannelMonitor`]. This final update will mark the |
| 67 | + * [`ChannelMonitor`] as finalized, ensuring no further updates (e.g. revocation of the latest |
| 68 | + * commitment transaction) are allowed. |
| 69 | + * |
| 70 | + * Note that even if you return a [`PermanentFailure`] due to unavailability of secondary |
| 71 | + * [`ChannelMonitor`] copies, you should still make an attempt to store the update where |
| 72 | + * possible to ensure you can claim HTLC outputs on the latest commitment transaction |
| 73 | + * broadcasted later. |
| 74 | + * |
| 75 | + * In case of distributed watchtowers deployment, the new version must be written to disk, as |
| 76 | + * state may have been stored but rejected due to a block forcing a commitment broadcast. This |
| 77 | + * storage is used to claim outputs of rejected state confirmed onchain by another watchtower, |
| 78 | + * lagging behind on block processing. |
| 79 | + * |
| 80 | + * [`PermanentFailure`]: ChannelMonitorUpdateStatus::PermanentFailure |
| 81 | + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager |
| 82 | + */ |
| 83 | + LDKChannelMonitorUpdateStatus_PermanentFailure, |
| 84 | +}} } } |
0 commit comments