X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-java;a=blobdiff_plain;f=ts%2Fstructs%2FWatch.mts;h=736d77ee4984f19cb966015eaaea67a7219cdfdb;hp=a810173cc4d4d5fdff953e85bb5bcad087d1769d;hb=c629a01650402c8e2f9b9db8ced9ed63ce687727;hpb=2a65456aa0b540060dcf3ca707a54dc98cc3f38a diff --git a/ts/structs/Watch.mts b/ts/structs/Watch.mts index a810173c..736d77ee 100644 --- a/ts/structs/Watch.mts +++ b/ts/structs/Watch.mts @@ -280,13 +280,43 @@ import { MultiThreadedLockableScore } from '../structs/MultiThreadedLockableScor import CommonBase from './CommonBase.mjs'; import * as bindings from '../bindings.mjs' -import * as InternalUtils from '../InternalUtils.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[]; } @@ -294,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; @@ -304,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 { @@ -325,9 +377,9 @@ export class Watch extends CommonBase { const result: number = ret == null ? 0 : ret.clone_ptr(); return result; }, - release_pending_monitor_events (): number[] { + release_pending_monitor_events (): number { const ret: MonitorEvent[] = arg.release_pending_monitor_events(); - const result: number[] = ret != null ? ret.map(ret_conv_14 => ret_conv_14 == null ? 0 : ret_conv_14.clone_ptr()) : null; + const result: number = bindings.encodeUint32Array(ret != null ? ret.map(ret_conv_14 => ret_conv_14 == null ? 0 : ret_conv_14.clone_ptr()) : null); return result; }, } as bindings.LDKWatch; @@ -337,27 +389,63 @@ 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_arr: MonitorEvent[] = new Array(ret.length).fill(null); - for (var o = 0; o < ret.length; o++) { - const ret_conv_14: number = ret[o]; + const ret: number = bindings.Watch_release_pending_monitor_events(this.ptr); + const ret_conv_14_len: number = bindings.getArrayLength(ret); + const ret_conv_14_arr: MonitorEvent[] = new Array(ret_conv_14_len).fill(null); + for (var o = 0; o < ret_conv_14_len; o++) { + const ret_conv_14: number = bindings.getU32ArrayElem(ret, o); const ret_conv_14_hu_conv: MonitorEvent = MonitorEvent.constr_from_ptr(ret_conv_14); 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; }