X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FPersist.java;h=335576fca31b1d18820009aaef758c8c06f2678c;hb=c6bac88847b7c09560af81f00ba8dd3c2ebe3a19;hp=f424851a8d37e88b3e22351d27ba72abdedd5022;hpb=0d48e557e83ef085cc92c2de63b9c81c061ce78c;p=ldk-java diff --git a/src/main/java/org/ldk/structs/Persist.java b/src/main/java/org/ldk/structs/Persist.java index f424851a..335576fc 100644 --- a/src/main/java/org/ldk/structs/Persist.java +++ b/src/main/java/org/ldk/structs/Persist.java @@ -10,14 +10,22 @@ import javax.annotation.Nullable; * `Persist` defines behavior for persisting channel monitors: this could mean * writing once to disk, and/or uploading to one or more backup services. * - * Note that for every new monitor, you **must** persist the new `ChannelMonitor` - * to disk/backups. And, on every update, you **must** persist either the - * `ChannelMonitorUpdate` or the updated monitor itself. Otherwise, there is risk - * of situations such as revoking a transaction, then crashing before this - * revocation can be persisted, then unintentionally broadcasting a revoked - * transaction and losing money. This is a risk because previous channel states - * are toxic, so it's important that whatever channel state is persisted is - * kept up-to-date. + * Each method can return three possible values: + * If persistence (including any relevant `fsync()` calls) happens immediately, the + * implementation should return `Ok(())`, 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 + * `Err(ChannelMonitorUpdateErr::TemporaryFailure)` while the update continues in the + * background. 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 + * `Err(ChannelMonitorUpdateErr::PermanentFailure)`, in which case the channel will likely be + * closed without broadcasting the latest state. See + * [`ChannelMonitorUpdateErr::PermanentFailure`] for more details. */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class Persist extends CommonBase { @@ -35,25 +43,36 @@ public class Persist extends CommonBase { public static interface PersistInterface { /** - * Persist a new channel's data. The data can be stored any way you want, but - * the identifier provided by Rust-Lightning 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. See the `Persist` trait documentation for more details. + * 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 [`ChannelMonitorUpdateErr::TemporaryFailure`]. * * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor` * and [`ChannelMonitorUpdateErr`] for requirements when returning errors. * + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager * [`Writeable::write`]: crate::util::ser::Writeable::write */ - Result_NoneChannelMonitorUpdateErrZ persist_new_channel(OutPoint id, ChannelMonitor data); + Result_NoneChannelMonitorUpdateErrZ 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. + * 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. * - * 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 @@ -67,32 +86,41 @@ public class Persist extends CommonBase { * 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 [`ChannelMonitorUpdateErr::TemporaryFailure`]. + * * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`, * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and * [`ChannelMonitorUpdateErr`] 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 */ - Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint id, ChannelMonitorUpdate update, ChannelMonitor data); + Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint channel_id, ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id); } private static class LDKPersistHolder { Persist held; } public static Persist new_impl(PersistInterface arg) { final LDKPersistHolder impl_holder = new LDKPersistHolder(); impl_holder.held = new Persist(new bindings.LDKPersist() { - @Override public long persist_new_channel(long id, long data) { - OutPoint id_hu_conv = new OutPoint(null, id); - id_hu_conv.ptrs_to.add(this); - ChannelMonitor data_hu_conv = new ChannelMonitor(null, data); - Result_NoneChannelMonitorUpdateErrZ ret = arg.persist_new_channel(id_hu_conv, data_hu_conv); + @Override public long persist_new_channel(long channel_id, long data, long update_id) { + OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new OutPoint(null, channel_id); } + channel_id_hu_conv.ptrs_to.add(this); + ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new ChannelMonitor(null, data); } + MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new MonitorUpdateId(null, update_id); } + update_id_hu_conv.ptrs_to.add(this); + Result_NoneChannelMonitorUpdateErrZ ret = arg.persist_new_channel(channel_id_hu_conv, data_hu_conv, update_id_hu_conv); long result = ret != null ? ret.ptr : 0; return result; } - @Override public long update_persisted_channel(long id, long update, long data) { - OutPoint id_hu_conv = new OutPoint(null, id); - id_hu_conv.ptrs_to.add(this); - ChannelMonitorUpdate update_hu_conv = new ChannelMonitorUpdate(null, update); - ChannelMonitor data_hu_conv = new ChannelMonitor(null, data); - Result_NoneChannelMonitorUpdateErrZ ret = arg.update_persisted_channel(id_hu_conv, update_hu_conv, data_hu_conv); + @Override public long update_persisted_channel(long channel_id, long update, long data, long update_id) { + OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new OutPoint(null, channel_id); } + channel_id_hu_conv.ptrs_to.add(this); + ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new ChannelMonitorUpdate(null, update); } + ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new ChannelMonitor(null, data); } + MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new MonitorUpdateId(null, update_id); } + update_id_hu_conv.ptrs_to.add(this); + Result_NoneChannelMonitorUpdateErrZ ret = arg.update_persisted_channel(channel_id_hu_conv, update_hu_conv, data_hu_conv, update_id_hu_conv); long result = ret != null ? ret.ptr : 0; return result; } @@ -100,32 +128,43 @@ public class Persist extends CommonBase { return impl_holder.held; } /** - * Persist a new channel's data. The data can be stored any way you want, but - * the identifier provided by Rust-Lightning 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. See the `Persist` trait documentation for more details. + * 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 [`ChannelMonitorUpdateErr::TemporaryFailure`]. * * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor` * and [`ChannelMonitorUpdateErr`] for requirements when returning errors. * + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager * [`Writeable::write`]: crate::util::ser::Writeable::write */ - public Result_NoneChannelMonitorUpdateErrZ persist_new_channel(OutPoint id, ChannelMonitor data) { - long ret = bindings.Persist_persist_new_channel(this.ptr, id == null ? 0 : id.ptr & ~1, data == null ? 0 : data.ptr & ~1); - if (ret >= 0 && ret < 1024) { return null; } + public Result_NoneChannelMonitorUpdateErrZ persist_new_channel(OutPoint channel_id, ChannelMonitor data, MonitorUpdateId update_id) { + long ret = bindings.Persist_persist_new_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr & ~1, data == null ? 0 : data.ptr & ~1, update_id == null ? 0 : update_id.ptr & ~1); + if (ret >= 0 && ret <= 4096) { return null; } Result_NoneChannelMonitorUpdateErrZ ret_hu_conv = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret); this.ptrs_to.add(data); return ret_hu_conv; } /** - * Update one channel's data. The provided `ChannelMonitor` has already - * applied the given update. + * 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. + * 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 @@ -139,15 +178,20 @@ public class Persist extends CommonBase { * 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 [`ChannelMonitorUpdateErr::TemporaryFailure`]. + * * See [`Writeable::write`] on [`ChannelMonitor`] for writing out a `ChannelMonitor`, * [`Writeable::write`] on [`ChannelMonitorUpdate`] for writing out an update, and * [`ChannelMonitorUpdateErr`] 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 */ - public Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint id, ChannelMonitorUpdate update, ChannelMonitor data) { - long ret = bindings.Persist_update_persisted_channel(this.ptr, id == null ? 0 : id.ptr & ~1, update == null ? 0 : update.ptr & ~1, data == null ? 0 : data.ptr & ~1); - if (ret >= 0 && ret < 1024) { return null; } + public Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint channel_id, @Nullable ChannelMonitorUpdate update, ChannelMonitor data, MonitorUpdateId update_id) { + long ret = bindings.Persist_update_persisted_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr & ~1, update == null ? 0 : update.ptr & ~1, data == null ? 0 : data.ptr & ~1, update_id == null ? 0 : update_id.ptr & ~1); + if (ret >= 0 && ret <= 4096) { return null; } Result_NoneChannelMonitorUpdateErrZ ret_hu_conv = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret); this.ptrs_to.add(update); this.ptrs_to.add(data);