X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FPersist.java;h=5ce6a58051739e7cd1d213d42cf0b7a12feedfff;hb=8aa8a96fc6d8fcdd3fbb419b4b4c12482af14938;hp=754f39115955c0ed313a5814583201c4ee114dce;hpb=4f914d250ae903770128765403d62ce3d8f54126;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/Persist.java b/src/main/java/org/ldk/structs/Persist.java
index 754f3911..5ce6a580 100644
--- a/src/main/java/org/ldk/structs/Persist.java
+++ b/src/main/java/org/ldk/structs/Persist.java
@@ -4,7 +4,31 @@ import org.ldk.impl.bindings;
 import org.ldk.enums.*;
 import org.ldk.util.*;
 import java.util.Arrays;
+import java.lang.ref.Reference;
+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.
+ * 
+ * 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`].
+ * 
+ * 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.
+ */
 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
 public class Persist extends CommonBase {
 	final bindings.LDKPersist bindings_instance;
@@ -20,46 +44,169 @@ public class Persist extends CommonBase {
 	}
 
 	public static interface PersistInterface {
-		Result_NoneChannelMonitorUpdateErrZ persist_new_channel(OutPoint id, ChannelMonitor data);
-		Result_NoneChannelMonitorUpdateErrZ update_persisted_channel(OutPoint id, ChannelMonitorUpdate update, ChannelMonitor data);
+		/**
+		 * 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 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);
-				ChannelMonitor data_hu_conv = new ChannelMonitor(null, data);
-				Result_NoneChannelMonitorUpdateErrZ ret = arg.persist_new_channel(id_hu_conv, data_hu_conv);
-				long result = ret != null ? ret.ptr : 0;
-				return result;
+			@Override public ChannelMonitorUpdateStatus persist_new_channel(long channel_id, long data, long update_id) {
+				org.ldk.structs.OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.OutPoint(null, channel_id); }
+				if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
+				org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
+				org.ldk.structs.MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new org.ldk.structs.MonitorUpdateId(null, update_id); }
+				if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
+				ChannelMonitorUpdateStatus ret = arg.persist_new_channel(channel_id_hu_conv, data_hu_conv, update_id_hu_conv);
+				Reference.reachabilityFence(arg);
+				return ret;
 			}
-			@Override public long update_persisted_channel(long id, long update, long data) {
-				OutPoint id_hu_conv = new OutPoint(null, id);
-				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);
-				long result = ret != null ? ret.ptr : 0;
-				return result;
+			@Override public ChannelMonitorUpdateStatus update_persisted_channel(long channel_id, long update, long data, long update_id) {
+				org.ldk.structs.OutPoint channel_id_hu_conv = null; if (channel_id < 0 || channel_id > 4096) { channel_id_hu_conv = new org.ldk.structs.OutPoint(null, channel_id); }
+				if (channel_id_hu_conv != null) { channel_id_hu_conv.ptrs_to.add(this); };
+				org.ldk.structs.ChannelMonitorUpdate update_hu_conv = null; if (update < 0 || update > 4096) { update_hu_conv = new org.ldk.structs.ChannelMonitorUpdate(null, update); }
+				org.ldk.structs.ChannelMonitor data_hu_conv = null; if (data < 0 || data > 4096) { data_hu_conv = new org.ldk.structs.ChannelMonitor(null, data); }
+				org.ldk.structs.MonitorUpdateId update_id_hu_conv = null; if (update_id < 0 || update_id > 4096) { update_id_hu_conv = new org.ldk.structs.MonitorUpdateId(null, update_id); }
+				if (update_id_hu_conv != null) { update_id_hu_conv.ptrs_to.add(this); };
+				ChannelMonitorUpdateStatus ret = arg.update_persisted_channel(channel_id_hu_conv, update_hu_conv, data_hu_conv, update_id_hu_conv);
+				Reference.reachabilityFence(arg);
+				return ret;
 			}
 		});
 		return impl_holder.held;
 	}
-	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);
-		Result_NoneChannelMonitorUpdateErrZ ret_hu_conv = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret);
-		this.ptrs_to.add(id);
-		this.ptrs_to.add(data);
-		return ret_hu_conv;
+	/**
+	 * 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
+	 */
+	public ChannelMonitorUpdateStatus persist_new_channel(org.ldk.structs.OutPoint channel_id, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
+		ChannelMonitorUpdateStatus ret = bindings.Persist_persist_new_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
+		Reference.reachabilityFence(this);
+		Reference.reachabilityFence(channel_id);
+		Reference.reachabilityFence(data);
+		Reference.reachabilityFence(update_id);
+		if (this != null) { this.ptrs_to.add(channel_id); };
+		if (this != null) { this.ptrs_to.add(data); };
+		if (this != null) { this.ptrs_to.add(update_id); };
+		return ret;
 	}
 
-	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);
-		Result_NoneChannelMonitorUpdateErrZ ret_hu_conv = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret);
-		this.ptrs_to.add(id);
-		this.ptrs_to.add(update);
-		this.ptrs_to.add(data);
-		return ret_hu_conv;
+	/**
+	 * 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
+	 */
+	public ChannelMonitorUpdateStatus update_persisted_channel(org.ldk.structs.OutPoint channel_id, @Nullable org.ldk.structs.ChannelMonitorUpdate update, org.ldk.structs.ChannelMonitor data, org.ldk.structs.MonitorUpdateId update_id) {
+		ChannelMonitorUpdateStatus ret = bindings.Persist_update_persisted_channel(this.ptr, channel_id == null ? 0 : channel_id.ptr, update == null ? 0 : update.ptr, data == null ? 0 : data.ptr, update_id == null ? 0 : update_id.ptr);
+		Reference.reachabilityFence(this);
+		Reference.reachabilityFence(channel_id);
+		Reference.reachabilityFence(update);
+		Reference.reachabilityFence(data);
+		Reference.reachabilityFence(update_id);
+		if (this != null) { this.ptrs_to.add(channel_id); };
+		if (this != null) { this.ptrs_to.add(update); };
+		if (this != null) { this.ptrs_to.add(data); };
+		if (this != null) { this.ptrs_to.add(update_id); };
+		return ret;
 	}
 
 }