X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=c_sharp%2Fsrc%2Forg%2Fldk%2Fstructs%2FPersist.cs;fp=c_sharp%2Fsrc%2Forg%2Fldk%2Fstructs%2FPersist.cs;h=6cbed960e2426280b31f91c11f854b2a061e1c7e;hb=8de7213fbf663ff60322896282dad51e8ab2f001;hp=9a44bba3d8b2d5259315a9d398c9adfab23054e3;hpb=afc50e5d491a11364849383b75a8f939df703bac;p=ldk-java diff --git a/c_sharp/src/org/ldk/structs/Persist.cs b/c_sharp/src/org/ldk/structs/Persist.cs index 9a44bba3..6cbed960 100644 --- a/c_sharp/src/org/ldk/structs/Persist.cs +++ b/c_sharp/src/org/ldk/structs/Persist.cs @@ -1,3 +1,4 @@ + using org.ldk.impl; using org.ldk.enums; using org.ldk.util; @@ -5,97 +6,132 @@ using System; namespace org { namespace ldk { namespace structs { + + +/** An implementation of Persist */ +public interface PersistInterface { + /**Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is + * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup. + * + * The data can be stored any way you want, but the identifier provided by LDK is the + * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint + * and the stored channel data). Note that you **must** persist every new monitor to disk. + * + * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`], + * if you return [`ChannelMonitorUpdateStatus::InProgress`]. + * + * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor` + * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors. + * + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager + * [`Writeable::write`]: crate::util::ser::Writeable::write + */ + ChannelMonitorUpdateStatus persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id); + /**Update one channel's data. The provided [`ChannelMonitor`] has already applied the given + * update. + * + * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the + * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more + * details. + * + * During blockchain synchronization operations, and in some rare cases, this may be called with + * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. + * Note that after the full [`ChannelMonitor`] is persisted any previous + * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be + * applied to the persisted [`ChannelMonitor`] as they were already applied. + * + * If an implementer chooses to persist the updates only, they need to make + * sure that all the updates are applied to the `ChannelMonitors` *before + * the set of channel monitors is given to the `ChannelManager` + * deserialization routine. See [`ChannelMonitor::update_monitor`] for + * applying a monitor update to a monitor. If full `ChannelMonitors` are + * persisted, then there is no need to persist individual updates. + * + * Note that there could be a performance tradeoff between persisting complete + * channel monitors on every update vs. persisting only updates and applying + * them in batches. The size of each monitor grows `O(number of state updates)` + * whereas updates are small and `O(1)`. + * + * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`], + * if you return [`ChannelMonitorUpdateStatus::InProgress`]. + * + * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`, + * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and + * [`ChannelMonitorUpdateStatus`] for requirements when returning errors. + * + * [`Writeable::write`]: crate::util::ser::Writeable::write + * + * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None + */ + ChannelMonitorUpdateStatus update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id); +} + /** * `Persist` defines behavior for persisting channel monitors: this could mean * writing once to disk, and/or uploading to one or more backup services. * - * Each method can return three possible values: - * If persistence (including any relevant `fsync()` calls) happens immediately, the - * implementation should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal - * channel operation should continue. - * If persistence happens asynchronously, implementations should first ensure the - * [`ChannelMonitor`] or [`ChannelMonitorUpdate`] are written durably to disk, and then return - * [`ChannelMonitorUpdateStatus::InProgress`] while the update continues in the background. - * Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be called with - * the corresponding [`MonitorUpdateId`]. + * Persistence can happen in one of two ways - synchronously completing before the trait method + * calls return or asynchronously in the background. + * + * # For those implementing synchronous persistence + * + * If persistence completes fully (including any relevant `fsync()` calls), the implementation + * should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal channel operation + * should continue. + * + * If persistence fails for some reason, implementations should consider returning + * [`ChannelMonitorUpdateStatus::InProgress`] and retry all pending persistence operations in + * the background with [`ChainMonitor::list_pending_monitor_updates`] and + * [`ChainMonitor::get_monitor`]. + * + * Once a full [`ChannelMonitor`] has been persisted, all pending updates for that channel can + * be marked as complete via [`ChainMonitor::channel_monitor_updated`]. + * + * If at some point no further progress can be made towards persisting the pending updates, the + * node should simply shut down. + * + * If the persistence has failed and cannot be retried further (e.g. because of an outage), + * [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in + * an immediate panic and future operations in LDK generally failing. + * + * # For those implementing asynchronous persistence + * + * All calls should generally spawn a background task and immediately return + * [`ChannelMonitorUpdateStatus::InProgress`]. Once the update completes, + * [`ChainMonitor::channel_monitor_updated`] should be called with the corresponding + * [`MonitorUpdateId`]. * * Note that unlike the direct [`chain::Watch`] interface, * [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs. * - * If persistence fails for some reason, implementations should return - * [`ChannelMonitorUpdateStatus::PermanentFailure`], in which case the channel will likely be - * closed without broadcasting the latest state. See - * [`ChannelMonitorUpdateStatus::PermanentFailure`] for more details. + * If at some point no further progress can be made towards persisting a pending update, the node + * should simply shut down. Until then, the background task should either loop indefinitely, or + * persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`] + * and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending + * monitor updates may be marked completed). + * + * # Using remote watchtowers + * + * Watchtowers may be updated as a part of an implementation of this trait, utilizing the async + * update process described above while the watchtower is being updated. The following methods are + * provided for bulding transactions for a watchtower: + * [`ChannelMonitor::initial_counterparty_commitment_tx`], + * [`ChannelMonitor::counterparty_commitment_txs_from_update`], + * [`ChannelMonitor::sign_to_local_justice_tx`], [`TrustedCommitmentTransaction::revokeable_output_index`], + * [`TrustedCommitmentTransaction::build_to_local_justice_tx`]. + * + * [`TrustedCommitmentTransaction::revokeable_output_index`]: crate::ln::chan_utils::TrustedCommitmentTransaction::revokeable_output_index + * [`TrustedCommitmentTransaction::build_to_local_justice_tx`]: crate::ln::chan_utils::TrustedCommitmentTransaction::build_to_local_justice_tx */ public class Persist : CommonBase { - internal readonly bindings.LDKPersist bindings_instance; + internal bindings.LDKPersist bindings_instance; + internal long instance_idx; + internal Persist(object _dummy, long ptr) : base(ptr) { bindings_instance = null; } - private Persist(bindings.LDKPersist arg) : base(bindings.LDKPersist_new(arg)) { - this.ptrs_to.AddLast(arg); - this.bindings_instance = arg; - } ~Persist() { if (ptr != 0) { bindings.Persist_free(ptr); } } - public interface PersistInterface { - /** - * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is - * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup. - * - * The data can be stored any way you want, but the identifier provided by LDK is the - * channel's outpoint (and it is up to you to maintain a correct mapping between the outpoint - * and the stored channel data). Note that you **must** persist every new monitor to disk. - * - * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`], - * if you return [`ChannelMonitorUpdateStatus::InProgress`]. - * - * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor` - * and [`ChannelMonitorUpdateStatus`] for requirements when returning errors. - * - * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager - * [`Writeable::write`]: crate::util::ser::Writeable::write - */ - ChannelMonitorUpdateStatus persist_new_channel(OutPoint _channel_id, ChannelMonitor _data, MonitorUpdateId _update_id); - /** - * Update one channel's data. The provided [`ChannelMonitor`] has already applied the given - * update. - * - * Note that on every update, you **must** persist either the [`ChannelMonitorUpdate`] or the - * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more - * details. - * - * During blockchain synchronization operations, this may be called with no - * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. - * Note that after the full [`ChannelMonitor`] is persisted any previous - * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be - * applied to the persisted [`ChannelMonitor`] as they were already applied. - * - * If an implementer chooses to persist the updates only, they need to make - * sure that all the updates are applied to the `ChannelMonitors` *before - * the set of channel monitors is given to the `ChannelManager` - * deserialization routine. See [`ChannelMonitor::update_monitor`] for - * applying a monitor update to a monitor. If full `ChannelMonitors` are - * persisted, then there is no need to persist individual updates. - * - * Note that there could be a performance tradeoff between persisting complete - * channel monitors on every update vs. persisting only updates and applying - * them in batches. The size of each monitor grows `O(number of state updates)` - * whereas updates are small and `O(1)`. - * - * The `update_id` is used to identify this call to [`ChainMonitor::channel_monitor_updated`], - * if you return [`ChannelMonitorUpdateStatus::InProgress`]. - * - * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`, - * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and - * [`ChannelMonitorUpdateStatus`] for requirements when returning errors. - * - * [`Writeable::write`]: crate::util::ser::Writeable::write - * - * Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None - */ - ChannelMonitorUpdateStatus update_persisted_channel(OutPoint _channel_id, ChannelMonitorUpdate _update, ChannelMonitor _data, MonitorUpdateId _update_id); - } private class LDKPersistHolder { internal Persist held; } private class LDKPersistImpl : bindings.LDKPersist { internal LDKPersistImpl(PersistInterface arg, LDKPersistHolder impl_holder) { this.arg = arg; this.impl_holder = impl_holder; } @@ -124,11 +160,19 @@ public class Persist : CommonBase { return ret; } } + + /** Creates a new instance of Persist from a given implementation */ public static Persist new_impl(PersistInterface arg) { LDKPersistHolder impl_holder = new LDKPersistHolder(); - impl_holder.held = new Persist(new LDKPersistImpl(arg, impl_holder)); + LDKPersistImpl impl = new LDKPersistImpl(arg, impl_holder); + long[] ptr_idx = bindings.LDKPersist_new(impl); + + impl_holder.held = new Persist(null, ptr_idx[0]); + impl_holder.held.instance_idx = ptr_idx[1]; + impl_holder.held.bindings_instance = impl; return impl_holder.held; } + /** * Persist a new channel's data in response to a [`chain::Watch::watch_channel`] call. This is * called by [`ChannelManager`] for new channels, or may be called directly, e.g. on startup. @@ -166,8 +210,8 @@ public class Persist : CommonBase { * updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more * details. * - * During blockchain synchronization operations, this may be called with no - * [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. + * During blockchain synchronization operations, and in some rare cases, this may be called with + * no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. * Note that after the full [`ChannelMonitor`] is persisted any previous * [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be * applied to the persisted [`ChannelMonitor`] as they were already applied.