+/**
+ * Implements [`Persist`] in a way that writes and reads both [`ChannelMonitor`]s and
+ * [`ChannelMonitorUpdate`]s.
+ *
+ * # Overview
+ *
+ * The main benefit this provides over the [`KVStore`]'s [`Persist`] implementation is decreased
+ * I/O bandwidth and storage churn, at the expense of more IOPS (including listing, reading, and
+ * deleting) and complexity. This is because it writes channel monitor differential updates,
+ * whereas the other (default) implementation rewrites the entire monitor on each update. For
+ * routing nodes, updates can happen many times per second to a channel, and monitors can be tens
+ * of megabytes (or more). Updates can be as small as a few hundred bytes.
+ *
+ * Note that monitors written with `MonitorUpdatingPersister` are _not_ backward-compatible with
+ * the default [`KVStore`]'s [`Persist`] implementation. They have a prepended byte sequence,
+ * [`MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL`], applied to prevent deserialization with other
+ * persisters. This is because monitors written by this struct _may_ have unapplied updates. In
+ * order to downgrade, you must ensure that all updates are applied to the monitor, and remove the
+ * sentinel bytes.
+ *
+ * # Storing monitors
+ *
+ * Monitors are stored by implementing the [`Persist`] trait, which has two functions:
+ *
+ * - [`Persist::persist_new_channel`], which persists whole [`ChannelMonitor`]s.
+ * - [`Persist::update_persisted_channel`], which persists only a [`ChannelMonitorUpdate`]
+ *
+ * Whole [`ChannelMonitor`]s are stored in the [`CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE`],
+ * using the familiar encoding of an [`OutPoint`] (for example, `[SOME-64-CHAR-HEX-STRING]_1`).
+ *
+ * Each [`ChannelMonitorUpdate`] is stored in a dynamic secondary namespace, as follows:
+ *
+ * - primary namespace: [`CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE`]
+ * - secondary namespace: [the monitor's encoded outpoint name]
+ *
+ * Under that secondary namespace, each update is stored with a number string, like `21`, which
+ * represents its `update_id` value.
+ *
+ * For example, consider this channel, named for its transaction ID and index, or [`OutPoint`]:
+ *
+ * - Transaction ID: `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef`
+ * - Index: `1`
+ *
+ * Full channel monitors would be stored at a single key:
+ *
+ * `[CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1`
+ *
+ * Updates would be stored as follows (with `/` delimiting primary_namespace/secondary_namespace/key):
+ *
+ * ```text
+ * [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/1
+ * [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/2
+ * [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/3
+ * ```
+ * ... and so on.
+ *
+ * # Reading channel state from storage
+ *
+ * Channel state can be reconstructed by calling
+ * [`MonitorUpdatingPersister::read_all_channel_monitors_with_updates`]. Alternatively, users can
+ * list channel monitors themselves and load channels individually using
+ * [`MonitorUpdatingPersister::read_channel_monitor_with_updates`].
+ *
+ * ## EXTREMELY IMPORTANT
+ *
+ * It is extremely important that your [`KVStore::read`] implementation uses the
+ * [`io::ErrorKind::NotFound`] variant correctly: that is, when a file is not found, and _only_ in
+ * that circumstance (not when there is really a permissions error, for example). This is because
+ * neither channel monitor reading function lists updates. Instead, either reads the monitor, and
+ * using its stored `update_id`, synthesizes update storage keys, and tries them in sequence until
+ * one is not found. All _other_ errors will be bubbled up in the function's [`Result`].
+ *
+ * # Pruning stale channel updates
+ *
+ * Stale updates are pruned when a full monitor is written. The old monitor is first read, and if
+ * that succeeds, updates in the range between the old and new monitors are deleted. The `lazy`
+ * flag is used on the [`KVStore::remove`] method, so there are no guarantees that the deletions
+ * will complete. However, stale updates are not a problem for data integrity, since updates are
+ * only read that are higher than the stored [`ChannelMonitor`]'s `update_id`.
+ *
+ * If you have many stale updates stored (such as after a crash with pending lazy deletes), and
+ * would like to get rid of them, consider using the
+ * [`MonitorUpdatingPersister::cleanup_stale_updates`] function.
+ */
+typedef struct MUST_USE_STRUCT LDKMonitorUpdatingPersister {
+ /**
+ * A pointer to the opaque Rust object.
+ * Nearly everywhere, inner must be non-null, however in places where
+ * the Rust equivalent takes an Option, it may be set to null to indicate None.
+ */
+ LDKnativeMonitorUpdatingPersister *inner;
+ /**
+ * Indicates that this is the only struct which contains the same pointer.
+ * Rust functions which take ownership of an object provided via an argument require
+ * this to be true and invalidate the object pointed to by inner.
+ */
+ bool is_owned;
+} LDKMonitorUpdatingPersister;
+
+/**
+ * `Persist` defines behavior for persisting channel monitors: this could mean
+ * writing once to disk, and/or uploading to one or more backup services.
+ *
+ * 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 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
+ */
+typedef struct LDKPersist {
+ /**
+ * An opaque pointer which is passed to your function implementations as an argument.
+ * This has no meaning in the LDK, and can be NULL or any other value.
+ */
+ void *this_arg;
+ /**
+ * 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
+ */
+ enum LDKChannelMonitorUpdateStatus (*persist_new_channel)(const void *this_arg, struct LDKOutPoint channel_id, const struct LDKChannelMonitor *NONNULL_PTR data, struct LDKMonitorUpdateId 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
+ */
+ enum LDKChannelMonitorUpdateStatus (*update_persisted_channel)(const void *this_arg, struct LDKOutPoint channel_id, struct LDKChannelMonitorUpdate update, const struct LDKChannelMonitor *NONNULL_PTR data, struct LDKMonitorUpdateId update_id);
+ /**
+ * Frees any resources associated with this object given its this_arg pointer.
+ * Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
+ */
+ void (*free)(void *this_arg);
+} LDKPersist;
+
+
+