X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-java;a=blobdiff_plain;f=ts%2Fstructs%2FWatch.mts;h=736d77ee4984f19cb966015eaaea67a7219cdfdb;hp=772ec08f24749f8cbcaa86e108ca6a14a6601097;hb=c629a01650402c8e2f9b9db8ced9ed63ce687727;hpb=d1d0121c000b713c10fd0bedd249eb8dda2e4db7

diff --git a/ts/structs/Watch.mts b/ts/structs/Watch.mts
index 772ec08f..736d77ee 100644
--- a/ts/structs/Watch.mts
+++ b/ts/structs/Watch.mts
@@ -283,9 +283,40 @@ import * as bindings from '../bindings.mjs'
 
 
 
+/** An implementation of Watch */
 export interface WatchInterface {
+	/**Watches a channel identified by `funding_txo` using `monitor`.
+	 * 
+	 * Implementations are responsible for watching the chain for the funding transaction along
+	 * with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
+	 * calling [`block_connected`] and [`block_disconnected`] on the monitor.
+	 * 
+	 * Note: this interface MUST error with `ChannelMonitorUpdateErr::PermanentFailure` if
+	 * the given `funding_txo` has previously been registered via `watch_channel`.
+	 * 
+	 * [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
+	 * [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
+	 * [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
+	 */
 	watch_channel(funding_txo: OutPoint, monitor: ChannelMonitor): Result_NoneChannelMonitorUpdateErrZ;
+	/**Updates a channel identified by `funding_txo` by applying `update` to its monitor.
+	 * 
+	 * Implementations must call [`update_monitor`] with the given update. See
+	 * [`ChannelMonitorUpdateErr`] for invariants around returning an error.
+	 * 
+	 * [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
+	 */
 	update_channel(funding_txo: OutPoint, update: ChannelMonitorUpdate): Result_NoneChannelMonitorUpdateErrZ;
+	/**Returns any monitor events since the last call. Subsequent calls must only return new
+	 * events.
+	 * 
+	 * Note that after any block- or transaction-connection calls to a [`ChannelMonitor`], no
+	 * further events may be returned here until the [`ChannelMonitor`] has been fully persisted
+	 * to disk.
+	 * 
+	 * For details on asynchronous [`ChannelMonitor`] updating and returning
+	 * [`MonitorEvent::UpdateCompleted`] here, see [`ChannelMonitorUpdateErr::TemporaryFailure`].
+	 */
 	release_pending_monitor_events(): MonitorEvent[];
 }
 
@@ -293,6 +324,27 @@ class LDKWatchHolder {
 	held: Watch;
 }
 
+/**
+ * The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as
+ * blocks are connected and disconnected.
+ * 
+ * Each channel is associated with a [`ChannelMonitor`]. Implementations of this trait are
+ * responsible for maintaining a set of monitors such that they can be updated accordingly as
+ * channel state changes and HTLCs are resolved. See method documentation for specific
+ * requirements.
+ * 
+ * Implementations **must** ensure that updates are successfully applied and persisted upon method
+ * completion. If an update fails with a [`PermanentFailure`], then it must immediately shut down
+ * without taking any further action such as persisting the current state.
+ * 
+ * If an implementation maintains multiple instances of a channel's monitor (e.g., by storing
+ * backup copies), then it must ensure that updates are applied across all instances. Otherwise, it
+ * could result in a revoked transaction being broadcast, allowing the counterparty to claim all
+ * funds in the channel. See [`ChannelMonitorUpdateErr`] for more details about how to handle
+ * multiple instances.
+ * 
+ * [`PermanentFailure`]: ChannelMonitorUpdateErr::PermanentFailure
+ */
 export class Watch extends CommonBase {
 	/* @internal */
 	public bindings_instance?: bindings.LDKWatch;
@@ -303,7 +355,8 @@ export class Watch extends CommonBase {
 		this.bindings_instance = null;
 	}
 
-	static new_impl(arg: WatchInterface): Watch {
+	/** Creates a new instance of Watch from a given implementation */
+	public static new_impl(arg: WatchInterface): Watch {
 		const impl_holder: LDKWatchHolder = new LDKWatchHolder();
 		let structImplementation = {
 			watch_channel (funding_txo: number, monitor: number): number {
@@ -336,18 +389,52 @@ export class Watch extends CommonBase {
 		impl_holder.held.bindings_instance = structImplementation;
 		return impl_holder.held;
 	}
+
+	/**
+	 * Watches a channel identified by `funding_txo` using `monitor`.
+	 * 
+	 * Implementations are responsible for watching the chain for the funding transaction along
+	 * with any spends of outputs returned by [`get_outputs_to_watch`]. In practice, this means
+	 * calling [`block_connected`] and [`block_disconnected`] on the monitor.
+	 * 
+	 * Note: this interface MUST error with `ChannelMonitorUpdateErr::PermanentFailure` if
+	 * the given `funding_txo` has previously been registered via `watch_channel`.
+	 * 
+	 * [`get_outputs_to_watch`]: channelmonitor::ChannelMonitor::get_outputs_to_watch
+	 * [`block_connected`]: channelmonitor::ChannelMonitor::block_connected
+	 * [`block_disconnected`]: channelmonitor::ChannelMonitor::block_disconnected
+	 */
 	public watch_channel(funding_txo: OutPoint, monitor: ChannelMonitor): Result_NoneChannelMonitorUpdateErrZ {
 		const ret: number = bindings.Watch_watch_channel(this.ptr, funding_txo == null ? 0 : CommonBase.get_ptr_of(funding_txo) & ~1, monitor == null ? 0 : CommonBase.get_ptr_of(monitor) & ~1);
 		const ret_hu_conv: Result_NoneChannelMonitorUpdateErrZ = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret);
 		return ret_hu_conv;
 	}
 
+	/**
+	 * Updates a channel identified by `funding_txo` by applying `update` to its monitor.
+	 * 
+	 * Implementations must call [`update_monitor`] with the given update. See
+	 * [`ChannelMonitorUpdateErr`] for invariants around returning an error.
+	 * 
+	 * [`update_monitor`]: channelmonitor::ChannelMonitor::update_monitor
+	 */
 	public update_channel(funding_txo: OutPoint, update: ChannelMonitorUpdate): Result_NoneChannelMonitorUpdateErrZ {
 		const ret: number = bindings.Watch_update_channel(this.ptr, funding_txo == null ? 0 : CommonBase.get_ptr_of(funding_txo) & ~1, update == null ? 0 : CommonBase.get_ptr_of(update) & ~1);
 		const ret_hu_conv: Result_NoneChannelMonitorUpdateErrZ = Result_NoneChannelMonitorUpdateErrZ.constr_from_ptr(ret);
 		return ret_hu_conv;
 	}
 
+	/**
+	 * Returns any monitor events since the last call. Subsequent calls must only return new
+	 * events.
+	 * 
+	 * Note that after any block- or transaction-connection calls to a [`ChannelMonitor`], no
+	 * further events may be returned here until the [`ChannelMonitor`] has been fully persisted
+	 * to disk.
+	 * 
+	 * For details on asynchronous [`ChannelMonitor`] updating and returning
+	 * [`MonitorEvent::UpdateCompleted`] here, see [`ChannelMonitorUpdateErr::TemporaryFailure`].
+	 */
 	public release_pending_monitor_events(): MonitorEvent[] {
 		const ret: number = bindings.Watch_release_pending_monitor_events(this.ptr);
 		const ret_conv_14_len: number = bindings.getArrayLength(ret);
@@ -358,6 +445,7 @@ export class Watch extends CommonBase {
 			CommonBase.add_ref_from(ret_conv_14_hu_conv, this);
 			ret_conv_14_arr[o] = ret_conv_14_hu_conv;
 		}
+		bindings.freeWasmMemory(ret)
 		return ret_conv_14_arr;
 	}