_ Git - rust-lightning/blob - lightning/src/util/persist.rs

   1 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   2 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   3 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   4 // You may not use this file except in accordance with one or both of these
   5 // licenses.
   6
   7 //! This module contains a simple key-value store trait [`KVStore`] that
   8 //! allows one to implement the persistence for [`ChannelManager`], [`NetworkGraph`],
   9 //! and [`ChannelMonitor`] all in one place.
  10
  11 use core::cmp;
  12 use core::convert::{TryFrom, TryInto};
  13 use core::ops::Deref;
  14 use core::str::FromStr;
  15 use bitcoin::{BlockHash, Txid};
  16
  17 use crate::{io, log_error};
  18 use crate::alloc::string::ToString;
  19 use crate::prelude::*;
  20
  21 use crate::chain;
  22 use crate::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
  23 use crate::chain::chainmonitor::{Persist, MonitorUpdateId};
  24 use crate::sign::{EntropySource, NodeSigner, ecdsa::WriteableEcdsaChannelSigner, SignerProvider};
  25 use crate::chain::transaction::OutPoint;
  26 use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, CLOSED_CHANNEL_UPDATE_ID};
  27 use crate::ln::channelmanager::ChannelManager;
  28 use crate::routing::router::Router;
  29 use crate::routing::gossip::NetworkGraph;
  30 use crate::routing::scoring::WriteableScore;
  31 use crate::util::logger::Logger;
  32 use crate::util::ser::{Readable, ReadableArgs, Writeable};
  33
  34 /// The alphabet of characters allowed for namespaces and keys.
  35 pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
  36
  37 /// The maximum number of characters namespaces and keys may have.
  38 pub const KVSTORE_NAMESPACE_KEY_MAX_LEN: usize = 120;
  39
  40 /// The primary namespace under which the [`ChannelManager`] will be persisted.
  41 pub const CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
  42 /// The secondary namespace under which the [`ChannelManager`] will be persisted.
  43 pub const CHANNEL_MANAGER_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
  44 /// The key under which the [`ChannelManager`] will be persisted.
  45 pub const CHANNEL_MANAGER_PERSISTENCE_KEY: &str = "manager";
  46
  47 /// The primary namespace under which [`ChannelMonitor`]s will be persisted.
  48 pub const CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE: &str = "monitors";
  49 /// The secondary namespace under which [`ChannelMonitor`]s will be persisted.
  50 pub const CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
  51 /// The primary namespace under which [`ChannelMonitorUpdate`]s will be persisted.
  52 pub const CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE: &str = "monitor_updates";
  53
  54 /// The primary namespace under which the [`NetworkGraph`] will be persisted.
  55 pub const NETWORK_GRAPH_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
  56 /// The secondary namespace under which the [`NetworkGraph`] will be persisted.
  57 pub const NETWORK_GRAPH_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
  58 /// The key under which the [`NetworkGraph`] will be persisted.
  59 pub const NETWORK_GRAPH_PERSISTENCE_KEY: &str = "network_graph";
  60
  61 /// The primary namespace under which the [`WriteableScore`] will be persisted.
  62 pub const SCORER_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
  63 /// The secondary namespace under which the [`WriteableScore`] will be persisted.
  64 pub const SCORER_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
  65 /// The key under which the [`WriteableScore`] will be persisted.
  66 pub const SCORER_PERSISTENCE_KEY: &str = "scorer";
  67
  68 /// A sentinel value to be prepended to monitors persisted by the [`MonitorUpdatingPersister`].
  69 ///
  70 /// This serves to prevent someone from accidentally loading such monitors (which may need
  71 /// updates applied to be current) with another implementation.
  72 pub const MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL: &[u8] = &[0xFF; 2];
  73
  74 /// Provides an interface that allows storage and retrieval of persisted values that are associated
  75 /// with given keys.
  76 ///
  77 /// In order to avoid collisions the key space is segmented based on the given `primary_namespace`s
  78 /// and `secondary_namespace`s. Implementations of this trait are free to handle them in different
  79 /// ways, as long as per-namespace key uniqueness is asserted.
  80 ///
  81 /// Keys and namespaces are required to be valid ASCII strings in the range of
  82 /// [`KVSTORE_NAMESPACE_KEY_ALPHABET`] and no longer than [`KVSTORE_NAMESPACE_KEY_MAX_LEN`]. Empty
  83 /// primary namespaces and secondary namespaces (`""`) are assumed to be a valid, however, if
  84 /// `primary_namespace` is empty, `secondary_namespace` is required to be empty, too. This means
  85 /// that concerns should always be separated by primary namespace first, before secondary
  86 /// namespaces are used. While the number of primary namespaces will be relatively small and is
  87 /// determined at compile time, there may be many secondary namespaces per primary namespace. Note
  88 /// that per-namespace uniqueness needs to also hold for keys *and* namespaces in any given
  89 /// namespace, i.e., conflicts between keys and equally named
  90 /// primary namespaces/secondary namespaces must be avoided.
  91 ///
  92 /// **Note:** Users migrating custom persistence backends from the pre-v0.0.117 `KVStorePersister`
  93 /// interface can use a concatenation of `[{primary_namespace}/[{secondary_namespace}/]]{key}` to
  94 /// recover a `key` compatible with the data model previously assumed by `KVStorePersister::persist`.
  95 pub trait KVStore {
  96         /// Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
  97         /// `key`.
  98         ///
  99         /// Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
 100         /// `primary_namespace` and `secondary_namespace`.
 101         ///
 102         /// [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
 103         fn read(&self, primary_namespace: &str, secondary_namespace: &str, key: &str) -> Result<Vec<u8>, io::Error>;
 104         /// Persists the given data under the given `key`.
 105         ///
 106         /// Will create the given `primary_namespace` and `secondary_namespace` if not already present
 107         /// in the store.
 108         fn write(&self, primary_namespace: &str, secondary_namespace: &str, key: &str, buf: &[u8]) -> Result<(), io::Error>;
 109         /// Removes any data that had previously been persisted under the given `key`.
 110         ///
 111         /// If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
 112         /// remove the given `key` at some point in time after the method returns, e.g., as part of an
 113         /// eventual batch deletion of multiple keys. As a consequence, subsequent calls to
 114         /// [`KVStore::list`] might include the removed key until the changes are actually persisted.
 115         ///
 116         /// Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
 117         /// `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
 118         /// potentially get lost on crash after the method returns. Therefore, this flag should only be
 119         /// set for `remove` operations that can be safely replayed at a later time.
 120         ///
 121         /// Returns successfully if no data will be stored for the given `primary_namespace`,
 122         /// `secondary_namespace`, and `key`, independently of whether it was present before its
 123         /// invokation or not.
 124         fn remove(&self, primary_namespace: &str, secondary_namespace: &str, key: &str, lazy: bool) -> Result<(), io::Error>;
 125         /// Returns a list of keys that are stored under the given `secondary_namespace` in
 126         /// `primary_namespace`.
 127         ///
 128         /// Returns the keys in arbitrary order, so users requiring a particular order need to sort the
 129         /// returned keys. Returns an empty list if `primary_namespace` or `secondary_namespace` is unknown.
 130         fn list(&self, primary_namespace: &str, secondary_namespace: &str) -> Result<Vec<String>, io::Error>;
 131 }
 132
 133 /// Trait that handles persisting a [`ChannelManager`], [`NetworkGraph`], and [`WriteableScore`] to disk.
 134 pub trait Persister<'a, M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref, S: WriteableScore<'a>>
 135         where M::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::EcdsaSigner>,
 136                 T::Target: 'static + BroadcasterInterface,
 137                 ES::Target: 'static + EntropySource,
 138                 NS::Target: 'static + NodeSigner,
 139                 SP::Target: 'static + SignerProvider,
 140                 F::Target: 'static + FeeEstimator,
 141                 R::Target: 'static + Router,
 142                 L::Target: 'static + Logger,
 143 {
 144         /// Persist the given ['ChannelManager'] to disk, returning an error if persistence failed.
 145         fn persist_manager(&self, channel_manager: &ChannelManager<M, T, ES, NS, SP, F, R, L>) -> Result<(), io::Error>;
 146
 147         /// Persist the given [`NetworkGraph`] to disk, returning an error if persistence failed.
 148         fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error>;
 149
 150         /// Persist the given [`WriteableScore`] to disk, returning an error if persistence failed.
 151         fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error>;
 152 }
 153
 154
 155 impl<'a, A: KVStore, M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref, S: WriteableScore<'a>> Persister<'a, M, T, ES, NS, SP, F, R, L, S> for A
 156         where M::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::EcdsaSigner>,
 157                 T::Target: 'static + BroadcasterInterface,
 158                 ES::Target: 'static + EntropySource,
 159                 NS::Target: 'static + NodeSigner,
 160                 SP::Target: 'static + SignerProvider,
 161                 F::Target: 'static + FeeEstimator,
 162                 R::Target: 'static + Router,
 163                 L::Target: 'static + Logger,
 164 {
 165         /// Persist the given [`ChannelManager`] to disk, returning an error if persistence failed.
 166         fn persist_manager(&self, channel_manager: &ChannelManager<M, T, ES, NS, SP, F, R, L>) -> Result<(), io::Error> {
 167                 self.write(CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE,
 168                         CHANNEL_MANAGER_PERSISTENCE_SECONDARY_NAMESPACE,
 169                         CHANNEL_MANAGER_PERSISTENCE_KEY,
 170                         &channel_manager.encode())
 171         }
 172
 173         /// Persist the given [`NetworkGraph`] to disk, returning an error if persistence failed.
 174         fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error> {
 175                 self.write(NETWORK_GRAPH_PERSISTENCE_PRIMARY_NAMESPACE,
 176                         NETWORK_GRAPH_PERSISTENCE_SECONDARY_NAMESPACE,
 177                         NETWORK_GRAPH_PERSISTENCE_KEY,
 178                         &network_graph.encode())
 179         }
 180
 181         /// Persist the given [`WriteableScore`] to disk, returning an error if persistence failed.
 182         fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error> {
 183                 self.write(SCORER_PERSISTENCE_PRIMARY_NAMESPACE,
 184                         SCORER_PERSISTENCE_SECONDARY_NAMESPACE,
 185                         SCORER_PERSISTENCE_KEY,
 186                         &scorer.encode())
 187         }
 188 }
 189
 190 impl<ChannelSigner: WriteableEcdsaChannelSigner, K: KVStore> Persist<ChannelSigner> for K {
 191         // TODO: We really need a way for the persister to inform the user that its time to crash/shut
 192         // down once these start returning failure.
 193         // Then we should return InProgress rather than UnrecoverableError, implying we should probably
 194         // just shut down the node since we're not retrying persistence!
 195
 196         fn persist_new_channel(&self, funding_txo: OutPoint, monitor: &ChannelMonitor<ChannelSigner>, _update_id: MonitorUpdateId) -> chain::ChannelMonitorUpdateStatus {
 197                 let key = format!("{}_{}", funding_txo.txid.to_string(), funding_txo.index);
 198                 match self.write(
 199                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 200                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 201                         &key, &monitor.encode())
 202                 {
 203                         Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
 204                         Err(_) => chain::ChannelMonitorUpdateStatus::UnrecoverableError
 205                 }
 206         }
 207
 208         fn update_persisted_channel(&self, funding_txo: OutPoint, _update: Option<&ChannelMonitorUpdate>, monitor: &ChannelMonitor<ChannelSigner>, _update_id: MonitorUpdateId) -> chain::ChannelMonitorUpdateStatus {
 209                 let key = format!("{}_{}", funding_txo.txid.to_string(), funding_txo.index);
 210                 match self.write(
 211                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 212                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 213                         &key, &monitor.encode())
 214                 {
 215                         Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
 216                         Err(_) => chain::ChannelMonitorUpdateStatus::UnrecoverableError
 217                 }
 218         }
 219 }
 220
 221 /// Read previously persisted [`ChannelMonitor`]s from the store.
 222 pub fn read_channel_monitors<K: Deref, ES: Deref, SP: Deref>(
 223         kv_store: K, entropy_source: ES, signer_provider: SP,
 224 ) -> Result<Vec<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>, io::Error>
 225 where
 226         K::Target: KVStore,
 227         ES::Target: EntropySource + Sized,
 228         SP::Target: SignerProvider + Sized,
 229 {
 230         let mut res = Vec::new();
 231
 232         for stored_key in kv_store.list(
 233                 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE, CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE)?
 234         {
 235                 if stored_key.len() < 66 {
 236                         return Err(io::Error::new(
 237                                 io::ErrorKind::InvalidData,
 238                                 "Stored key has invalid length"));
 239                 }
 240
 241                 let txid = Txid::from_str(stored_key.split_at(64).0).map_err(|_| {
 242                         io::Error::new(io::ErrorKind::InvalidData, "Invalid tx ID in stored key")
 243                 })?;
 244
 245                 let index: u16 = stored_key.split_at(65).1.parse().map_err(|_| {
 246                         io::Error::new(io::ErrorKind::InvalidData, "Invalid tx index in stored key")
 247                 })?;
 248
 249                 match <(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>::read(
 250                         &mut io::Cursor::new(
 251                                 kv_store.read(CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE, CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE, &stored_key)?),
 252                         (&*entropy_source, &*signer_provider),
 253                 ) {
 254                         Ok((block_hash, channel_monitor)) => {
 255                                 if channel_monitor.get_funding_txo().0.txid != txid
 256                                         || channel_monitor.get_funding_txo().0.index != index
 257                                 {
 258                                         return Err(io::Error::new(
 259                                                 io::ErrorKind::InvalidData,
 260                                                 "ChannelMonitor was stored under the wrong key",
 261                                         ));
 262                                 }
 263                                 res.push((block_hash, channel_monitor));
 264                         }
 265                         Err(_) => {
 266                                 return Err(io::Error::new(
 267                                         io::ErrorKind::InvalidData,
 268                                         "Failed to read ChannelMonitor"
 269                                 ))
 270                         }
 271                 }
 272         }
 273         Ok(res)
 274 }
 275
 276 /// Implements [`Persist`] in a way that writes and reads both [`ChannelMonitor`]s and
 277 /// [`ChannelMonitorUpdate`]s.
 278 ///
 279 /// # Overview
 280 ///
 281 /// The main benefit this provides over the [`KVStore`]'s [`Persist`] implementation is decreased
 282 /// I/O bandwidth and storage churn, at the expense of more IOPS (including listing, reading, and
 283 /// deleting) and complexity. This is because it writes channel monitor differential updates,
 284 /// whereas the other (default) implementation rewrites the entire monitor on each update. For
 285 /// routing nodes, updates can happen many times per second to a channel, and monitors can be tens
 286 /// of megabytes (or more). Updates can be as small as a few hundred bytes.
 287 ///
 288 /// Note that monitors written with `MonitorUpdatingPersister` are _not_ backward-compatible with
 289 /// the default [`KVStore`]'s [`Persist`] implementation. They have a prepended byte sequence,
 290 /// [`MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL`], applied to prevent deserialization with other
 291 /// persisters. This is because monitors written by this struct _may_ have unapplied updates. In
 292 /// order to downgrade, you must ensure that all updates are applied to the monitor, and remove the
 293 /// sentinel bytes.
 294 ///
 295 /// # Storing monitors
 296 ///
 297 /// Monitors are stored by implementing the [`Persist`] trait, which has two functions:
 298 ///
 299 ///   - [`Persist::persist_new_channel`], which persists whole [`ChannelMonitor`]s.
 300 ///   - [`Persist::update_persisted_channel`], which persists only a [`ChannelMonitorUpdate`]
 301 ///
 302 /// Whole [`ChannelMonitor`]s are stored in the [`CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE`],
 303 /// using the familiar encoding of an [`OutPoint`] (for example, `[SOME-64-CHAR-HEX-STRING]_1`).
 304 ///
 305 /// Each [`ChannelMonitorUpdate`] is stored in a dynamic secondary namespace, as follows:
 306 ///
 307 ///   - primary namespace: [`CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE`]
 308 ///   - secondary namespace: [the monitor's encoded outpoint name]
 309 ///
 310 /// Under that secondary namespace, each update is stored with a number string, like `21`, which
 311 /// represents its `update_id` value.
 312 ///
 313 /// For example, consider this channel, named for its transaction ID and index, or [`OutPoint`]:
 314 ///
 315 ///   - Transaction ID: `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef`
 316 ///   - Index: `1`
 317 ///
 318 /// Full channel monitors would be stored at a single key:
 319 ///
 320 /// `[CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1`
 321 ///
 322 /// Updates would be stored as follows (with `/` delimiting primary_namespace/secondary_namespace/key):
 323 ///
 324 /// ```text
 325 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/1
 326 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/2
 327 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/3
 328 /// ```
 329 /// ... and so on.
 330 ///
 331 /// # Reading channel state from storage
 332 ///
 333 /// Channel state can be reconstructed by calling
 334 /// [`MonitorUpdatingPersister::read_all_channel_monitors_with_updates`]. Alternatively, users can
 335 /// list channel monitors themselves and load channels individually using
 336 /// [`MonitorUpdatingPersister::read_channel_monitor_with_updates`].
 337 ///
 338 /// ## EXTREMELY IMPORTANT
 339 ///
 340 /// It is extremely important that your [`KVStore::read`] implementation uses the
 341 /// [`io::ErrorKind::NotFound`] variant correctly: that is, when a file is not found, and _only_ in
 342 /// that circumstance (not when there is really a permissions error, for example). This is because
 343 /// neither channel monitor reading function lists updates. Instead, either reads the monitor, and
 344 /// using its stored `update_id`, synthesizes update storage keys, and tries them in sequence until
 345 /// one is not found. All _other_ errors will be bubbled up in the function's [`Result`].
 346 ///
 347 /// # Pruning stale channel updates
 348 ///
 349 /// Stale updates are pruned when the consolidation threshold is reached according to `maximum_pending_updates`.
 350 /// Monitor updates in the range between the latest `update_id` and `update_id - maximum_pending_updates`
 351 /// are deleted.
 352 /// The `lazy` flag is used on the [`KVStore::remove`] method, so there are no guarantees that the deletions
 353 /// will complete. However, stale updates are not a problem for data integrity, since updates are
 354 /// only read that are higher than the stored [`ChannelMonitor`]'s `update_id`.
 355 ///
 356 /// If you have many stale updates stored (such as after a crash with pending lazy deletes), and
 357 /// would like to get rid of them, consider using the
 358 /// [`MonitorUpdatingPersister::cleanup_stale_updates`] function.
 359 pub struct MonitorUpdatingPersister<K: Deref, L: Deref, ES: Deref, SP: Deref>
 360 where
 361         K::Target: KVStore,
 362         L::Target: Logger,
 363         ES::Target: EntropySource + Sized,
 364         SP::Target: SignerProvider + Sized,
 365 {
 366         kv_store: K,
 367         logger: L,
 368         maximum_pending_updates: u64,
 369         entropy_source: ES,
 370         signer_provider: SP,
 371 }
 372
 373 #[allow(dead_code)]
 374 impl<K: Deref, L: Deref, ES: Deref, SP: Deref>
 375         MonitorUpdatingPersister<K, L, ES, SP>
 376 where
 377         K::Target: KVStore,
 378         L::Target: Logger,
 379         ES::Target: EntropySource + Sized,
 380         SP::Target: SignerProvider + Sized,
 381 {
 382         /// Constructs a new [`MonitorUpdatingPersister`].
 383         ///
 384         /// The `maximum_pending_updates` parameter controls how many updates may be stored before a
 385         /// [`MonitorUpdatingPersister`] consolidates updates by writing a full monitor. Note that
 386         /// consolidation will frequently occur with fewer updates than what you set here; this number
 387         /// is merely the maximum that may be stored. When setting this value, consider that for higher
 388         /// values of `maximum_pending_updates`:
 389         ///
 390         ///   - [`MonitorUpdatingPersister`] will tend to write more [`ChannelMonitorUpdate`]s than
 391         /// [`ChannelMonitor`]s, approaching one [`ChannelMonitor`] write for every
 392         /// `maximum_pending_updates` [`ChannelMonitorUpdate`]s.
 393         ///   - [`MonitorUpdatingPersister`] will issue deletes differently. Lazy deletes will come in
 394         /// "waves" for each [`ChannelMonitor`] write. A larger `maximum_pending_updates` means bigger,
 395         /// less frequent "waves."
 396         ///   - [`MonitorUpdatingPersister`] will potentially have more listing to do if you need to run
 397         /// [`MonitorUpdatingPersister::cleanup_stale_updates`].
 398         pub fn new(
 399                 kv_store: K, logger: L, maximum_pending_updates: u64, entropy_source: ES,
 400                 signer_provider: SP,
 401         ) -> Self {
 402                 MonitorUpdatingPersister {
 403                         kv_store,
 404                         logger,
 405                         maximum_pending_updates,
 406                         entropy_source,
 407                         signer_provider,
 408                 }
 409         }
 410
 411         /// Reads all stored channel monitors, along with any stored updates for them.
 412         ///
 413         /// It is extremely important that your [`KVStore::read`] implementation uses the
 414         /// [`io::ErrorKind::NotFound`] variant correctly. For more information, please see the
 415         /// documentation for [`MonitorUpdatingPersister`].
 416         pub fn read_all_channel_monitors_with_updates<B: Deref, F: Deref>(
 417                 &self, broadcaster: &B, fee_estimator: &F,
 418         ) -> Result<Vec<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>, io::Error>
 419         where
 420                 B::Target: BroadcasterInterface,
 421                 F::Target: FeeEstimator,
 422         {
 423                 let monitor_list = self.kv_store.list(
 424                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 425                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 426                 )?;
 427                 let mut res = Vec::with_capacity(monitor_list.len());
 428                 for monitor_key in monitor_list {
 429                         res.push(self.read_channel_monitor_with_updates(
 430                                 broadcaster,
 431                                 fee_estimator,
 432                                 monitor_key,
 433                         )?)
 434                 }
 435                 Ok(res)
 436         }
 437
 438         /// Read a single channel monitor, along with any stored updates for it.
 439         ///
 440         /// It is extremely important that your [`KVStore::read`] implementation uses the
 441         /// [`io::ErrorKind::NotFound`] variant correctly. For more information, please see the
 442         /// documentation for [`MonitorUpdatingPersister`].
 443         ///
 444         /// For `monitor_key`, channel storage keys be the channel's transaction ID and index, or
 445         /// [`OutPoint`], with an underscore `_` between them. For example, given:
 446         ///
 447         ///   - Transaction ID: `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef`
 448         ///   - Index: `1`
 449         ///
 450         /// The correct `monitor_key` would be:
 451         /// `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1`
 452         ///
 453         /// Loading a large number of monitors will be faster if done in parallel. You can use this
 454         /// function to accomplish this. Take care to limit the number of parallel readers.
 455         pub fn read_channel_monitor_with_updates<B: Deref, F: Deref>(
 456                 &self, broadcaster: &B, fee_estimator: &F, monitor_key: String,
 457         ) -> Result<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>), io::Error>
 458         where
 459                 B::Target: BroadcasterInterface,
 460                 F::Target: FeeEstimator,
 461         {
 462                 let monitor_name = MonitorName::new(monitor_key)?;
 463                 let (block_hash, monitor) = self.read_monitor(&monitor_name)?;
 464                 let mut current_update_id = monitor.get_latest_update_id();
 465                 loop {
 466                         current_update_id = match current_update_id.checked_add(1) {
 467                                 Some(next_update_id) => next_update_id,
 468                                 None => break,
 469                         };
 470                         let update_name = UpdateName::from(current_update_id);
 471                         let update = match self.read_monitor_update(&monitor_name, &update_name) {
 472                                 Ok(update) => update,
 473                                 Err(err) if err.kind() == io::ErrorKind::NotFound => {
 474                                         // We can't find any more updates, so we are done.
 475                                         break;
 476                                 }
 477                                 Err(err) => return Err(err),
 478                         };
 479
 480                         monitor.update_monitor(&update, broadcaster, fee_estimator, &self.logger)
 481                                 .map_err(|e| {
 482                                         log_error!(
 483                                                 self.logger,
 484                                                 "Monitor update failed. monitor: {} update: {} reason: {:?}",
 485                                                 monitor_name.as_str(),
 486                                                 update_name.as_str(),
 487                                                 e
 488                                         );
 489                                         io::Error::new(io::ErrorKind::Other, "Monitor update failed")
 490                                 })?;
 491                 }
 492                 Ok((block_hash, monitor))
 493         }
 494
 495         /// Read a channel monitor.
 496         fn read_monitor(
 497                 &self, monitor_name: &MonitorName,
 498         ) -> Result<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>), io::Error> {
 499                 let outpoint: OutPoint = monitor_name.try_into()?;
 500                 let mut monitor_cursor = io::Cursor::new(self.kv_store.read(
 501                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 502                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 503                         monitor_name.as_str(),
 504                 )?);
 505                 // Discard the sentinel bytes if found.
 506                 if monitor_cursor.get_ref().starts_with(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL) {
 507                         monitor_cursor.set_position(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL.len() as u64);
 508                 }
 509                 match <(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>::read(
 510                         &mut monitor_cursor,
 511                         (&*self.entropy_source, &*self.signer_provider),
 512                 ) {
 513                         Ok((blockhash, channel_monitor)) => {
 514                                 if channel_monitor.get_funding_txo().0.txid != outpoint.txid
 515                                         || channel_monitor.get_funding_txo().0.index != outpoint.index
 516                                 {
 517                                         log_error!(
 518                                                 self.logger,
 519                                                 "ChannelMonitor {} was stored under the wrong key!",
 520                                                 monitor_name.as_str()
 521                                         );
 522                                         Err(io::Error::new(
 523                                                 io::ErrorKind::InvalidData,
 524                                                 "ChannelMonitor was stored under the wrong key",
 525                                         ))
 526                                 } else {
 527                                         Ok((blockhash, channel_monitor))
 528                                 }
 529                         }
 530                         Err(e) => {
 531                                 log_error!(
 532                                         self.logger,
 533                                         "Failed to read ChannelMonitor {}, reason: {}",
 534                                         monitor_name.as_str(),
 535                                         e,
 536                                 );
 537                                 Err(io::Error::new(io::ErrorKind::InvalidData, "Failed to read ChannelMonitor"))
 538                         }
 539                 }
 540         }
 541
 542         /// Read a channel monitor update.
 543         fn read_monitor_update(
 544                 &self, monitor_name: &MonitorName, update_name: &UpdateName,
 545         ) -> Result<ChannelMonitorUpdate, io::Error> {
 546                 let update_bytes = self.kv_store.read(
 547                         CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 548                         monitor_name.as_str(),
 549                         update_name.as_str(),
 550                 )?;
 551                 ChannelMonitorUpdate::read(&mut io::Cursor::new(update_bytes)).map_err(|e| {
 552                         log_error!(
 553                                 self.logger,
 554                                 "Failed to read ChannelMonitorUpdate {}/{}/{}, reason: {}",
 555                                 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 556                                 monitor_name.as_str(),
 557                                 update_name.as_str(),
 558                                 e,
 559                         );
 560                         io::Error::new(io::ErrorKind::InvalidData, "Failed to read ChannelMonitorUpdate")
 561                 })
 562         }
 563
 564         /// Cleans up stale updates for all monitors.
 565         ///
 566         /// This function works by first listing all monitors, and then for each of them, listing all
 567         /// updates. The updates that have an `update_id` less than or equal to than the stored monitor
 568         /// are deleted. The deletion can either be lazy or non-lazy based on the `lazy` flag; this will
 569         /// be passed to [`KVStore::remove`].
 570         pub fn cleanup_stale_updates(&self, lazy: bool) -> Result<(), io::Error> {
 571                 let monitor_keys = self.kv_store.list(
 572                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 573                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 574                 )?;
 575                 for monitor_key in monitor_keys {
 576                         let monitor_name = MonitorName::new(monitor_key)?;
 577                         let (_, current_monitor) = self.read_monitor(&monitor_name)?;
 578                         let updates = self
 579                                 .kv_store
 580                                 .list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str())?;
 581                         for update in updates {
 582                                 let update_name = UpdateName::new(update)?;
 583                                 // if the update_id is lower than the stored monitor, delete
 584                                 if update_name.0 <= current_monitor.get_latest_update_id() {
 585                                         self.kv_store.remove(
 586                                                 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 587                                                 monitor_name.as_str(),
 588                                                 update_name.as_str(),
 589                                                 lazy,
 590                                         )?;
 591                                 }
 592                         }
 593                 }
 594                 Ok(())
 595         }
 596 }
 597
 598 impl<ChannelSigner: WriteableEcdsaChannelSigner, K: Deref, L: Deref, ES: Deref, SP: Deref>
 599         Persist<ChannelSigner> for MonitorUpdatingPersister<K, L, ES, SP>
 600 where
 601         K::Target: KVStore,
 602         L::Target: Logger,
 603         ES::Target: EntropySource + Sized,
 604         SP::Target: SignerProvider + Sized,
 605 {
 606         /// Persists a new channel. This means writing the entire monitor to the
 607         /// parametrized [`KVStore`].
 608         fn persist_new_channel(
 609                 &self, funding_txo: OutPoint, monitor: &ChannelMonitor<ChannelSigner>,
 610                 _monitor_update_call_id: MonitorUpdateId,
 611         ) -> chain::ChannelMonitorUpdateStatus {
 612                 // Determine the proper key for this monitor
 613                 let monitor_name = MonitorName::from(funding_txo);
 614                 // Serialize and write the new monitor
 615                 let mut monitor_bytes = Vec::with_capacity(
 616                         MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL.len() + monitor.serialized_length(),
 617                 );
 618                 monitor_bytes.extend_from_slice(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL);
 619                 monitor.write(&mut monitor_bytes).unwrap();
 620                 match self.kv_store.write(
 621                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 622                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 623                         monitor_name.as_str(),
 624                         &monitor_bytes,
 625                 ) {
 626                         Ok(_) => {
 627                                 chain::ChannelMonitorUpdateStatus::Completed
 628                         }
 629                         Err(e) => {
 630                                 log_error!(
 631                                         self.logger,
 632                                         "Failed to write ChannelMonitor {}/{}/{} reason: {}",
 633                                         CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
 634                                         CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
 635                                         monitor_name.as_str(),
 636                                         e
 637                                 );
 638                                 chain::ChannelMonitorUpdateStatus::UnrecoverableError
 639                         }
 640                 }
 641         }
 642
 643         /// Persists a channel update, writing only the update to the parameterized [`KVStore`] if possible.
 644         ///
 645         /// In some cases, this will forward to [`MonitorUpdatingPersister::persist_new_channel`]:
 646         ///
 647         ///   - No full monitor is found in [`KVStore`]
 648         ///   - The number of pending updates exceeds `maximum_pending_updates` as given to [`Self::new`]
 649         ///   - LDK commands re-persisting the entire monitor through this function, specifically when
 650         ///     `update` is `None`.
 651         ///   - The update is at [`CLOSED_CHANNEL_UPDATE_ID`]
 652         fn update_persisted_channel(
 653                 &self, funding_txo: OutPoint, update: Option<&ChannelMonitorUpdate>,
 654                 monitor: &ChannelMonitor<ChannelSigner>, monitor_update_call_id: MonitorUpdateId,
 655         ) -> chain::ChannelMonitorUpdateStatus {
 656                 // IMPORTANT: monitor_update_call_id: MonitorUpdateId is not to be confused with
 657                 // ChannelMonitorUpdate's update_id.
 658                 if let Some(update) = update {
 659                         if update.update_id != CLOSED_CHANNEL_UPDATE_ID
 660                                 && update.update_id % self.maximum_pending_updates != 0
 661                         {
 662                                 let monitor_name = MonitorName::from(funding_txo);
 663                                 let update_name = UpdateName::from(update.update_id);
 664                                 match self.kv_store.write(
 665                                         CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 666                                         monitor_name.as_str(),
 667                                         update_name.as_str(),
 668                                         &update.encode(),
 669                                 ) {
 670                                         Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
 671                                         Err(e) => {
 672                                                 log_error!(
 673                                                         self.logger,
 674                                                         "Failed to write ChannelMonitorUpdate {}/{}/{} reason: {}",
 675                                                         CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 676                                                         monitor_name.as_str(),
 677                                                         update_name.as_str(),
 678                                                         e
 679                                                 );
 680                                                 chain::ChannelMonitorUpdateStatus::UnrecoverableError
 681                                         }
 682                                 }
 683                         } else {
 684                                 let monitor_name = MonitorName::from(funding_txo);
 685                                 // In case of channel-close monitor update, we need to read old monitor before persisting
 686                                 // the new one in order to determine the cleanup range.
 687                                 let maybe_old_monitor = match monitor.get_latest_update_id() {
 688                                         CLOSED_CHANNEL_UPDATE_ID => self.read_monitor(&monitor_name).ok(),
 689                                         _ => None
 690                                 };
 691
 692                                 // We could write this update, but it meets criteria of our design that calls for a full monitor write.
 693                                 let monitor_update_status = self.persist_new_channel(funding_txo, monitor, monitor_update_call_id);
 694
 695                                 if let chain::ChannelMonitorUpdateStatus::Completed = monitor_update_status {
 696                                         let cleanup_range = if monitor.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
 697                                                 // If there is an error while reading old monitor, we skip clean up.
 698                                                 maybe_old_monitor.map(|(_, ref old_monitor)| {
 699                                                         let start = old_monitor.get_latest_update_id();
 700                                                         // We never persist an update with update_id = CLOSED_CHANNEL_UPDATE_ID
 701                                                         let end = cmp::min(
 702                                                                 start.saturating_add(self.maximum_pending_updates),
 703                                                                 CLOSED_CHANNEL_UPDATE_ID - 1,
 704                                                         );
 705                                                         (start, end)
 706                                                 })
 707                                         } else {
 708                                                 let end = monitor.get_latest_update_id();
 709                                                 let start = end.saturating_sub(self.maximum_pending_updates);
 710                                                 Some((start, end))
 711                                         };
 712
 713                                         if let Some((start, end)) = cleanup_range {
 714                                                 self.cleanup_in_range(monitor_name, start, end);
 715                                         }
 716                                 }
 717
 718                                 monitor_update_status
 719                         }
 720                 } else {
 721                         // There is no update given, so we must persist a new monitor.
 722                         self.persist_new_channel(funding_txo, monitor, monitor_update_call_id)
 723                 }
 724         }
 725 }
 726
 727 impl<K: Deref, L: Deref, ES: Deref, SP: Deref> MonitorUpdatingPersister<K, L, ES, SP>
 728 where
 729         ES::Target: EntropySource + Sized,
 730         K::Target: KVStore,
 731         L::Target: Logger,
 732         SP::Target: SignerProvider + Sized
 733 {
 734         // Cleans up monitor updates for given monitor in range `start..=end`.
 735         fn cleanup_in_range(&self, monitor_name: MonitorName, start: u64, end: u64) {
 736                 for update_id in start..=end {
 737                         let update_name = UpdateName::from(update_id);
 738                         if let Err(e) = self.kv_store.remove(
 739                                 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 740                                 monitor_name.as_str(),
 741                                 update_name.as_str(),
 742                                 true,
 743                         ) {
 744                                 log_error!(
 745                                         self.logger,
 746                                         "Failed to clean up channel monitor updates for monitor {}, reason: {}",
 747                                         monitor_name.as_str(),
 748                                         e
 749                                 );
 750                         };
 751                 }
 752         }
 753 }
 754
 755 /// A struct representing a name for a monitor.
 756 #[derive(Debug)]
 757 struct MonitorName(String);
 758
 759 impl MonitorName {
 760         /// Constructs a [`MonitorName`], after verifying that an [`OutPoint`] can
 761         /// be formed from the given `name`.
 762         pub fn new(name: String) -> Result<Self, io::Error> {
 763                 MonitorName::do_try_into_outpoint(&name)?;
 764                 Ok(Self(name))
 765         }
 766         /// Convert this monitor name to a str.
 767         pub fn as_str(&self) -> &str {
 768                 &self.0
 769         }
 770         /// Attempt to form a valid [`OutPoint`] from a given name string.
 771         fn do_try_into_outpoint(name: &str) -> Result<OutPoint, io::Error> {
 772                 let mut parts = name.splitn(2, '_');
 773                 let txid = if let Some(part) = parts.next() {
 774                         Txid::from_str(part).map_err(|_| {
 775                                 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx ID in stored key")
 776                         })?
 777                 } else {
 778                         return Err(io::Error::new(
 779                                 io::ErrorKind::InvalidData,
 780                                 "Stored monitor key is not a splittable string",
 781                         ));
 782                 };
 783                 let index = if let Some(part) = parts.next() {
 784                         part.parse().map_err(|_| {
 785                                 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx index in stored key")
 786                         })?
 787                 } else {
 788                         return Err(io::Error::new(
 789                                 io::ErrorKind::InvalidData,
 790                                 "No tx index value found after underscore in stored key",
 791                         ));
 792                 };
 793                 Ok(OutPoint { txid, index })
 794         }
 795 }
 796
 797 impl TryFrom<&MonitorName> for OutPoint {
 798         type Error = io::Error;
 799
 800         fn try_from(value: &MonitorName) -> Result<Self, io::Error> {
 801                 MonitorName::do_try_into_outpoint(&value.0)
 802         }
 803 }
 804
 805 impl From<OutPoint> for MonitorName {
 806         fn from(value: OutPoint) -> Self {
 807                 MonitorName(format!("{}_{}", value.txid.to_string(), value.index))
 808         }
 809 }
 810
 811 /// A struct representing a name for an update.
 812 #[derive(Debug)]
 813 struct UpdateName(u64, String);
 814
 815 impl UpdateName {
 816         /// Constructs an [`UpdateName`], after verifying that an update sequence ID
 817         /// can be derived from the given `name`.
 818         pub fn new(name: String) -> Result<Self, io::Error> {
 819                 match name.parse::<u64>() {
 820                         Ok(u) => Ok(u.into()),
 821                         Err(_) => {
 822                                 Err(io::Error::new(io::ErrorKind::InvalidData, "cannot parse u64 from update name"))
 823                         }
 824                 }
 825         }
 826
 827         /// Convert this monitor update name to a &str
 828         pub fn as_str(&self) -> &str {
 829                 &self.1
 830         }
 831 }
 832
 833 impl From<u64> for UpdateName {
 834         fn from(value: u64) -> Self {
 835                 Self(value, value.to_string())
 836         }
 837 }
 838
 839 #[cfg(test)]
 840 mod tests {
 841         use super::*;
 842         use crate::chain::chainmonitor::Persist;
 843         use crate::chain::ChannelMonitorUpdateStatus;
 844         use crate::events::{ClosureReason, MessageSendEventsProvider};
 845         use crate::ln::functional_test_utils::*;
 846         use crate::util::test_utils::{self, TestLogger, TestStore};
 847         use crate::{check_added_monitors, check_closed_broadcast};
 848
 849         const EXPECTED_UPDATES_PER_PAYMENT: u64 = 5;
 850
 851         #[test]
 852         fn converts_u64_to_update_name() {
 853                 assert_eq!(UpdateName::from(0).as_str(), "0");
 854                 assert_eq!(UpdateName::from(21).as_str(), "21");
 855                 assert_eq!(UpdateName::from(u64::MAX).as_str(), "18446744073709551615");
 856         }
 857
 858         #[test]
 859         fn bad_update_name_fails() {
 860                 assert!(UpdateName::new("deadbeef".to_string()).is_err());
 861                 assert!(UpdateName::new("-1".to_string()).is_err());
 862         }
 863
 864         #[test]
 865         fn monitor_from_outpoint_works() {
 866                 let monitor_name1 = MonitorName::from(OutPoint {
 867                         txid: Txid::from_str("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap(),
 868                         index: 1,
 869                 });
 870                 assert_eq!(monitor_name1.as_str(), "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1");
 871
 872                 let monitor_name2 = MonitorName::from(OutPoint {
 873                         txid: Txid::from_str("f33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeef").unwrap(),
 874                         index: u16::MAX,
 875                 });
 876                 assert_eq!(monitor_name2.as_str(), "f33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeef_65535");
 877         }
 878
 879         #[test]
 880         fn bad_monitor_string_fails() {
 881                 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef".to_string()).is_err());
 882                 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_65536".to_string()).is_err());
 883                 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_21".to_string()).is_err());
 884         }
 885
 886         // Exercise the `MonitorUpdatingPersister` with real channels and payments.
 887         #[test]
 888         fn persister_with_real_monitors() {
 889                 // This value is used later to limit how many iterations we perform.
 890                 let persister_0_max_pending_updates = 7;
 891                 // Intentionally set this to a smaller value to test a different alignment.
 892                 let persister_1_max_pending_updates = 3;
 893                 let chanmon_cfgs = create_chanmon_cfgs(4);
 894                 let persister_0 = MonitorUpdatingPersister {
 895                         kv_store: &TestStore::new(false),
 896                         logger: &TestLogger::new(),
 897                         maximum_pending_updates: persister_0_max_pending_updates,
 898                         entropy_source: &chanmon_cfgs[0].keys_manager,
 899                         signer_provider: &chanmon_cfgs[0].keys_manager,
 900                 };
 901                 let persister_1 = MonitorUpdatingPersister {
 902                         kv_store: &TestStore::new(false),
 903                         logger: &TestLogger::new(),
 904                         maximum_pending_updates: persister_1_max_pending_updates,
 905                         entropy_source: &chanmon_cfgs[1].keys_manager,
 906                         signer_provider: &chanmon_cfgs[1].keys_manager,
 907                 };
 908                 let mut node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
 909                 let chain_mon_0 = test_utils::TestChainMonitor::new(
 910                         Some(&chanmon_cfgs[0].chain_source),
 911                         &chanmon_cfgs[0].tx_broadcaster,
 912                         &chanmon_cfgs[0].logger,
 913                         &chanmon_cfgs[0].fee_estimator,
 914                         &persister_0,
 915                         &chanmon_cfgs[0].keys_manager,
 916                 );
 917                 let chain_mon_1 = test_utils::TestChainMonitor::new(
 918                         Some(&chanmon_cfgs[1].chain_source),
 919                         &chanmon_cfgs[1].tx_broadcaster,
 920                         &chanmon_cfgs[1].logger,
 921                         &chanmon_cfgs[1].fee_estimator,
 922                         &persister_1,
 923                         &chanmon_cfgs[1].keys_manager,
 924                 );
 925                 node_cfgs[0].chain_monitor = chain_mon_0;
 926                 node_cfgs[1].chain_monitor = chain_mon_1;
 927                 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
 928                 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
 929                 let broadcaster_0 = &chanmon_cfgs[2].tx_broadcaster;
 930                 let broadcaster_1 = &chanmon_cfgs[3].tx_broadcaster;
 931
 932                 // Check that the persisted channel data is empty before any channels are
 933                 // open.
 934                 let mut persisted_chan_data_0 = persister_0.read_all_channel_monitors_with_updates(
 935                         &broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
 936                 assert_eq!(persisted_chan_data_0.len(), 0);
 937                 let mut persisted_chan_data_1 = persister_1.read_all_channel_monitors_with_updates(
 938                         &broadcaster_1, &&chanmon_cfgs[1].fee_estimator).unwrap();
 939                 assert_eq!(persisted_chan_data_1.len(), 0);
 940
 941                 // Helper to make sure the channel is on the expected update ID.
 942                 macro_rules! check_persisted_data {
 943                         ($expected_update_id: expr) => {
 944                                 persisted_chan_data_0 = persister_0.read_all_channel_monitors_with_updates(
 945                                         &broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
 946                                 // check that we stored only one monitor
 947                                 assert_eq!(persisted_chan_data_0.len(), 1);
 948                                 for (_, mon) in persisted_chan_data_0.iter() {
 949                                         // check that when we read it, we got the right update id
 950                                         assert_eq!(mon.get_latest_update_id(), $expected_update_id);
 951
 952                                         // if the CM is at consolidation threshold, ensure no updates are stored.
 953                                         let monitor_name = MonitorName::from(mon.get_funding_txo().0);
 954                                         if mon.get_latest_update_id() % persister_0_max_pending_updates == 0
 955                                                         || mon.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
 956                                                 assert_eq!(
 957                                                         persister_0.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 958                                                                 monitor_name.as_str()).unwrap().len(),
 959                                                         0,
 960                                                         "updates stored when they shouldn't be in persister 0"
 961                                                 );
 962                                         }
 963                                 }
 964                                 persisted_chan_data_1 = persister_1.read_all_channel_monitors_with_updates(
 965                                         &broadcaster_1, &&chanmon_cfgs[1].fee_estimator).unwrap();
 966                                 assert_eq!(persisted_chan_data_1.len(), 1);
 967                                 for (_, mon) in persisted_chan_data_1.iter() {
 968                                         assert_eq!(mon.get_latest_update_id(), $expected_update_id);
 969                                         let monitor_name = MonitorName::from(mon.get_funding_txo().0);
 970                                         // if the CM is at consolidation threshold, ensure no updates are stored.
 971                                         if mon.get_latest_update_id() % persister_1_max_pending_updates == 0
 972                                                         || mon.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
 973                                                 assert_eq!(
 974                                                         persister_1.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
 975                                                                 monitor_name.as_str()).unwrap().len(),
 976                                                         0,
 977                                                         "updates stored when they shouldn't be in persister 1"
 978                                                 );
 979                                         }
 980                                 }
 981                         };
 982                 }
 983
 984                 // Create some initial channel and check that a channel was persisted.
 985                 let _ = create_announced_chan_between_nodes(&nodes, 0, 1);
 986                 check_persisted_data!(0);
 987
 988                 // Send a few payments and make sure the monitors are updated to the latest.
 989                 send_payment(&nodes[0], &vec![&nodes[1]][..], 8_000_000);
 990                 check_persisted_data!(EXPECTED_UPDATES_PER_PAYMENT);
 991                 send_payment(&nodes[1], &vec![&nodes[0]][..], 4_000_000);
 992                 check_persisted_data!(2 * EXPECTED_UPDATES_PER_PAYMENT);
 993
 994                 // Send a few more payments to try all the alignments of max pending updates with
 995                 // updates for a payment sent and received.
 996                 let mut sender = 0;
 997                 for i in 3..=persister_0_max_pending_updates * 2 {
 998                         let receiver;
 999                         if sender == 0 {
1000                                 sender = 1;
1001                                 receiver = 0;
1002                         } else {
1003                                 sender = 0;
1004                                 receiver = 1;
1005                         }
1006                         send_payment(&nodes[sender], &vec![&nodes[receiver]][..], 21_000);
1007                         check_persisted_data!(i * EXPECTED_UPDATES_PER_PAYMENT);
1008                 }
1009
1010                 // Force close because cooperative close doesn't result in any persisted
1011                 // updates.
1012                 nodes[0].node.force_close_broadcasting_latest_txn(&nodes[0].node.list_channels()[0].channel_id, &nodes[1].node.get_our_node_id()).unwrap();
1013
1014                 check_closed_event(&nodes[0], 1, ClosureReason::HolderForceClosed, false, &[nodes[1].node.get_our_node_id()], 100000);
1015                 check_closed_broadcast!(nodes[0], true);
1016                 check_added_monitors!(nodes[0], 1);
1017
1018                 let node_txn = nodes[0].tx_broadcaster.txn_broadcast();
1019                 assert_eq!(node_txn.len(), 1);
1020
1021                 connect_block(&nodes[1], &create_dummy_block(nodes[0].best_block_hash(), 42, vec![node_txn[0].clone(), node_txn[0].clone()]));
1022
1023                 check_closed_broadcast!(nodes[1], true);
1024                 check_closed_event(&nodes[1], 1, ClosureReason::CommitmentTxConfirmed, false, &[nodes[0].node.get_our_node_id()], 100000);
1025                 check_added_monitors!(nodes[1], 1);
1026
1027                 // Make sure everything is persisted as expected after close.
1028                 check_persisted_data!(CLOSED_CHANNEL_UPDATE_ID);
1029
1030                 // Make sure the expected number of stale updates is present.
1031                 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1032                 let (_, monitor) = &persisted_chan_data[0];
1033                 let monitor_name = MonitorName::from(monitor.get_funding_txo().0);
1034                 // The channel should have 0 updates, as it wrote a full monitor and consolidated.
1035                 assert_eq!(persister_0.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str()).unwrap().len(), 0);
1036                 assert_eq!(persister_1.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str()).unwrap().len(), 0);
1037         }
1038
1039         // Test that if the `MonitorUpdatingPersister`'s can't actually write, trying to persist a
1040         // monitor or update with it results in the persister returning an UnrecoverableError status.
1041         #[test]
1042         fn unrecoverable_error_on_write_failure() {
1043                 // Set up a dummy channel and force close. This will produce a monitor
1044                 // that we can then use to test persistence.
1045                 let chanmon_cfgs = create_chanmon_cfgs(2);
1046                 let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
1047                 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
1048                 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
1049                 let chan = create_announced_chan_between_nodes(&nodes, 0, 1);
1050                 nodes[1].node.force_close_broadcasting_latest_txn(&chan.2, &nodes[0].node.get_our_node_id()).unwrap();
1051                 check_closed_event(&nodes[1], 1, ClosureReason::HolderForceClosed, false, &[nodes[0].node.get_our_node_id()], 100000);
1052                 {
1053                         let mut added_monitors = nodes[1].chain_monitor.added_monitors.lock().unwrap();
1054                         let update_map = nodes[1].chain_monitor.latest_monitor_update_id.lock().unwrap();
1055                         let update_id = update_map.get(&added_monitors[0].1.channel_id()).unwrap();
1056                         let cmu_map = nodes[1].chain_monitor.monitor_updates.lock().unwrap();
1057                         let cmu = &cmu_map.get(&added_monitors[0].1.channel_id()).unwrap()[0];
1058                         let test_txo = OutPoint { txid: Txid::from_str("8984484a580b825b9972d7adb15050b3ab624ccd731946b3eeddb92f4e7ef6be").unwrap(), index: 0 };
1059
1060                         let ro_persister = MonitorUpdatingPersister {
1061                                 kv_store: &TestStore::new(true),
1062                                 logger: &TestLogger::new(),
1063                                 maximum_pending_updates: 11,
1064                                 entropy_source: node_cfgs[0].keys_manager,
1065                                 signer_provider: node_cfgs[0].keys_manager,
1066                         };
1067                         match ro_persister.persist_new_channel(test_txo, &added_monitors[0].1, update_id.2) {
1068                                 ChannelMonitorUpdateStatus::UnrecoverableError => {
1069                                         // correct result
1070                                 }
1071                                 ChannelMonitorUpdateStatus::Completed => {
1072                                         panic!("Completed persisting new channel when shouldn't have")
1073                                 }
1074                                 ChannelMonitorUpdateStatus::InProgress => {
1075                                         panic!("Returned InProgress when shouldn't have")
1076                                 }
1077                         }
1078                         match ro_persister.update_persisted_channel(test_txo, Some(cmu), &added_monitors[0].1, update_id.2) {
1079                                 ChannelMonitorUpdateStatus::UnrecoverableError => {
1080                                         // correct result
1081                                 }
1082                                 ChannelMonitorUpdateStatus::Completed => {
1083                                         panic!("Completed persisting new channel when shouldn't have")
1084                                 }
1085                                 ChannelMonitorUpdateStatus::InProgress => {
1086                                         panic!("Returned InProgress when shouldn't have")
1087                                 }
1088                         }
1089                         added_monitors.clear();
1090                 }
1091                 nodes[1].node.get_and_clear_pending_msg_events();
1092         }
1093
1094         // Confirm that the `clean_stale_updates` function finds and deletes stale updates.
1095         #[test]
1096         fn clean_stale_updates_works() {
1097                 let test_max_pending_updates = 7;
1098                 let chanmon_cfgs = create_chanmon_cfgs(3);
1099                 let persister_0 = MonitorUpdatingPersister {
1100                         kv_store: &TestStore::new(false),
1101                         logger: &TestLogger::new(),
1102                         maximum_pending_updates: test_max_pending_updates,
1103                         entropy_source: &chanmon_cfgs[0].keys_manager,
1104                         signer_provider: &chanmon_cfgs[0].keys_manager,
1105                 };
1106                 let persister_1 = MonitorUpdatingPersister {
1107                         kv_store: &TestStore::new(false),
1108                         logger: &TestLogger::new(),
1109                         maximum_pending_updates: test_max_pending_updates,
1110                         entropy_source: &chanmon_cfgs[1].keys_manager,
1111                         signer_provider: &chanmon_cfgs[1].keys_manager,
1112                 };
1113                 let mut node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
1114                 let chain_mon_0 = test_utils::TestChainMonitor::new(
1115                         Some(&chanmon_cfgs[0].chain_source),
1116                         &chanmon_cfgs[0].tx_broadcaster,
1117                         &chanmon_cfgs[0].logger,
1118                         &chanmon_cfgs[0].fee_estimator,
1119                         &persister_0,
1120                         &chanmon_cfgs[0].keys_manager,
1121                 );
1122                 let chain_mon_1 = test_utils::TestChainMonitor::new(
1123                         Some(&chanmon_cfgs[1].chain_source),
1124                         &chanmon_cfgs[1].tx_broadcaster,
1125                         &chanmon_cfgs[1].logger,
1126                         &chanmon_cfgs[1].fee_estimator,
1127                         &persister_1,
1128                         &chanmon_cfgs[1].keys_manager,
1129                 );
1130                 node_cfgs[0].chain_monitor = chain_mon_0;
1131                 node_cfgs[1].chain_monitor = chain_mon_1;
1132                 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
1133                 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
1134
1135                 let broadcaster_0 = &chanmon_cfgs[2].tx_broadcaster;
1136
1137                 // Check that the persisted channel data is empty before any channels are
1138                 // open.
1139                 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1140                 assert_eq!(persisted_chan_data.len(), 0);
1141
1142                 // Create some initial channel
1143                 let _ = create_announced_chan_between_nodes(&nodes, 0, 1);
1144
1145                 // Send a few payments to advance the updates a bit
1146                 send_payment(&nodes[0], &vec![&nodes[1]][..], 8_000_000);
1147                 send_payment(&nodes[1], &vec![&nodes[0]][..], 4_000_000);
1148
1149                 // Get the monitor and make a fake stale update at update_id=1 (lowest height of an update possible)
1150                 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1151                 let (_, monitor) = &persisted_chan_data[0];
1152                 let monitor_name = MonitorName::from(monitor.get_funding_txo().0);
1153                 persister_0
1154                         .kv_store
1155                         .write(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(1).as_str(), &[0u8; 1])
1156                         .unwrap();
1157
1158                 // Do the stale update cleanup
1159                 persister_0.cleanup_stale_updates(false).unwrap();
1160
1161                 // Confirm the stale update is unreadable/gone
1162                 assert!(persister_0
1163                         .kv_store
1164                         .read(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(1).as_str())
1165                         .is_err());
1166
1167                 // Force close.
1168                 nodes[0].node.force_close_broadcasting_latest_txn(&nodes[0].node.list_channels()[0].channel_id, &nodes[1].node.get_our_node_id()).unwrap();
1169                 check_closed_event(&nodes[0], 1, ClosureReason::HolderForceClosed, false, &[nodes[1].node.get_our_node_id()], 100000);
1170                 check_closed_broadcast!(nodes[0], true);
1171                 check_added_monitors!(nodes[0], 1);
1172
1173                 // Write an update near u64::MAX
1174                 persister_0
1175                         .kv_store
1176                         .write(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(u64::MAX - 1).as_str(), &[0u8; 1])
1177                         .unwrap();
1178
1179                 // Do the stale update cleanup
1180                 persister_0.cleanup_stale_updates(false).unwrap();
1181
1182                 // Confirm the stale update is unreadable/gone
1183                 assert!(persister_0
1184                         .kv_store
1185                         .read(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(u64::MAX - 1).as_str())
1186                         .is_err());
1187         }
1188 }