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
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.
11 //! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
15 use core::str::FromStr;
16 use bitcoin::{BlockHash, Txid};
18 use crate::{io, log_error};
19 use crate::prelude::*;
22 use crate::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
23 use crate::chain::chainmonitor::Persist;
24 use crate::sign::{EntropySource, ecdsa::EcdsaChannelSigner, SignerProvider};
25 use crate::chain::transaction::OutPoint;
26 use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, CLOSED_CHANNEL_UPDATE_ID};
27 use crate::ln::channelmanager::AChannelManager;
28 use crate::routing::gossip::NetworkGraph;
29 use crate::routing::scoring::WriteableScore;
30 use crate::util::logger::Logger;
31 use crate::util::ser::{Readable, ReadableArgs, Writeable};
33 /// The alphabet of characters allowed for namespaces and keys.
34 pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
36 /// The maximum number of characters namespaces and keys may have.
37 pub const KVSTORE_NAMESPACE_KEY_MAX_LEN: usize = 120;
39 /// The primary namespace under which the [`ChannelManager`] will be persisted.
41 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
42 pub const CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
43 /// The secondary namespace under which the [`ChannelManager`] will be persisted.
45 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
46 pub const CHANNEL_MANAGER_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
47 /// The key under which the [`ChannelManager`] will be persisted.
49 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
50 pub const CHANNEL_MANAGER_PERSISTENCE_KEY: &str = "manager";
52 /// The primary namespace under which [`ChannelMonitor`]s will be persisted.
53 pub const CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE: &str = "monitors";
54 /// The secondary namespace under which [`ChannelMonitor`]s will be persisted.
55 pub const CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
56 /// The primary namespace under which [`ChannelMonitorUpdate`]s will be persisted.
57 pub const CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE: &str = "monitor_updates";
59 /// The primary namespace under which archived [`ChannelMonitor`]s will be persisted.
60 pub const ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE: &str = "archived_monitors";
61 /// The secondary namespace under which archived [`ChannelMonitor`]s will be persisted.
62 pub const ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
64 /// The primary namespace under which the [`NetworkGraph`] will be persisted.
65 pub const NETWORK_GRAPH_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
66 /// The secondary namespace under which the [`NetworkGraph`] will be persisted.
67 pub const NETWORK_GRAPH_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
68 /// The key under which the [`NetworkGraph`] will be persisted.
69 pub const NETWORK_GRAPH_PERSISTENCE_KEY: &str = "network_graph";
71 /// The primary namespace under which the [`WriteableScore`] will be persisted.
72 pub const SCORER_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
73 /// The secondary namespace under which the [`WriteableScore`] will be persisted.
74 pub const SCORER_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
75 /// The key under which the [`WriteableScore`] will be persisted.
76 pub const SCORER_PERSISTENCE_KEY: &str = "scorer";
78 /// The primary namespace under which [`OutputSweeper`] state will be persisted.
80 /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper
81 pub const OUTPUT_SWEEPER_PERSISTENCE_PRIMARY_NAMESPACE: &str = "";
82 /// The secondary namespace under which [`OutputSweeper`] state will be persisted.
84 /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper
85 pub const OUTPUT_SWEEPER_PERSISTENCE_SECONDARY_NAMESPACE: &str = "";
86 /// The secondary namespace under which [`OutputSweeper`] state will be persisted.
87 /// The key under which [`OutputSweeper`] state will be persisted.
89 /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper
90 pub const OUTPUT_SWEEPER_PERSISTENCE_KEY: &str = "output_sweeper";
92 /// A sentinel value to be prepended to monitors persisted by the [`MonitorUpdatingPersister`].
94 /// This serves to prevent someone from accidentally loading such monitors (which may need
95 /// updates applied to be current) with another implementation.
96 pub const MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL: &[u8] = &[0xFF; 2];
98 /// Provides an interface that allows storage and retrieval of persisted values that are associated
101 /// In order to avoid collisions the key space is segmented based on the given `primary_namespace`s
102 /// and `secondary_namespace`s. Implementations of this trait are free to handle them in different
103 /// ways, as long as per-namespace key uniqueness is asserted.
105 /// Keys and namespaces are required to be valid ASCII strings in the range of
106 /// [`KVSTORE_NAMESPACE_KEY_ALPHABET`] and no longer than [`KVSTORE_NAMESPACE_KEY_MAX_LEN`]. Empty
107 /// primary namespaces and secondary namespaces (`""`) are assumed to be a valid, however, if
108 /// `primary_namespace` is empty, `secondary_namespace` is required to be empty, too. This means
109 /// that concerns should always be separated by primary namespace first, before secondary
110 /// namespaces are used. While the number of primary namespaces will be relatively small and is
111 /// determined at compile time, there may be many secondary namespaces per primary namespace. Note
112 /// that per-namespace uniqueness needs to also hold for keys *and* namespaces in any given
113 /// namespace, i.e., conflicts between keys and equally named
114 /// primary namespaces/secondary namespaces must be avoided.
116 /// **Note:** Users migrating custom persistence backends from the pre-v0.0.117 `KVStorePersister`
117 /// interface can use a concatenation of `[{primary_namespace}/[{secondary_namespace}/]]{key}` to
118 /// recover a `key` compatible with the data model previously assumed by `KVStorePersister::persist`.
120 /// Returns the data stored for the given `primary_namespace`, `secondary_namespace`, and
123 /// Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
124 /// `primary_namespace` and `secondary_namespace`.
126 /// [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
127 fn read(&self, primary_namespace: &str, secondary_namespace: &str, key: &str) -> Result<Vec<u8>, io::Error>;
128 /// Persists the given data under the given `key`.
130 /// Will create the given `primary_namespace` and `secondary_namespace` if not already present
132 fn write(&self, primary_namespace: &str, secondary_namespace: &str, key: &str, buf: &[u8]) -> Result<(), io::Error>;
133 /// Removes any data that had previously been persisted under the given `key`.
135 /// If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
136 /// remove the given `key` at some point in time after the method returns, e.g., as part of an
137 /// eventual batch deletion of multiple keys. As a consequence, subsequent calls to
138 /// [`KVStore::list`] might include the removed key until the changes are actually persisted.
140 /// Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
141 /// `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
142 /// potentially get lost on crash after the method returns. Therefore, this flag should only be
143 /// set for `remove` operations that can be safely replayed at a later time.
145 /// Returns successfully if no data will be stored for the given `primary_namespace`,
146 /// `secondary_namespace`, and `key`, independently of whether it was present before its
147 /// invokation or not.
148 fn remove(&self, primary_namespace: &str, secondary_namespace: &str, key: &str, lazy: bool) -> Result<(), io::Error>;
149 /// Returns a list of keys that are stored under the given `secondary_namespace` in
150 /// `primary_namespace`.
152 /// Returns the keys in arbitrary order, so users requiring a particular order need to sort the
153 /// returned keys. Returns an empty list if `primary_namespace` or `secondary_namespace` is unknown.
154 fn list(&self, primary_namespace: &str, secondary_namespace: &str) -> Result<Vec<String>, io::Error>;
157 /// Trait that handles persisting a [`ChannelManager`], [`NetworkGraph`], and [`WriteableScore`] to disk.
159 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
160 pub trait Persister<'a, CM: Deref, L: Deref, S: WriteableScore<'a>>
162 CM::Target: 'static + AChannelManager,
163 L::Target: 'static + Logger,
165 /// Persist the given ['ChannelManager'] to disk, returning an error if persistence failed.
167 /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
168 fn persist_manager(&self, channel_manager: &CM) -> Result<(), io::Error>;
170 /// Persist the given [`NetworkGraph`] to disk, returning an error if persistence failed.
171 fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error>;
173 /// Persist the given [`WriteableScore`] to disk, returning an error if persistence failed.
174 fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error>;
178 impl<'a, A: KVStore + ?Sized, CM: Deref, L: Deref, S: WriteableScore<'a>> Persister<'a, CM, L, S> for A
180 CM::Target: 'static + AChannelManager,
181 L::Target: 'static + Logger,
183 fn persist_manager(&self, channel_manager: &CM) -> Result<(), io::Error> {
184 self.write(CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE,
185 CHANNEL_MANAGER_PERSISTENCE_SECONDARY_NAMESPACE,
186 CHANNEL_MANAGER_PERSISTENCE_KEY,
187 &channel_manager.get_cm().encode())
190 fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error> {
191 self.write(NETWORK_GRAPH_PERSISTENCE_PRIMARY_NAMESPACE,
192 NETWORK_GRAPH_PERSISTENCE_SECONDARY_NAMESPACE,
193 NETWORK_GRAPH_PERSISTENCE_KEY,
194 &network_graph.encode())
197 fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error> {
198 self.write(SCORER_PERSISTENCE_PRIMARY_NAMESPACE,
199 SCORER_PERSISTENCE_SECONDARY_NAMESPACE,
200 SCORER_PERSISTENCE_KEY,
205 impl<ChannelSigner: EcdsaChannelSigner, K: KVStore + ?Sized> Persist<ChannelSigner> for K {
206 // TODO: We really need a way for the persister to inform the user that its time to crash/shut
207 // down once these start returning failure.
208 // Then we should return InProgress rather than UnrecoverableError, implying we should probably
209 // just shut down the node since we're not retrying persistence!
211 fn persist_new_channel(&self, funding_txo: OutPoint, monitor: &ChannelMonitor<ChannelSigner>) -> chain::ChannelMonitorUpdateStatus {
212 let key = format!("{}_{}", funding_txo.txid.to_string(), funding_txo.index);
214 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
215 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
216 &key, &monitor.encode())
218 Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
219 Err(_) => chain::ChannelMonitorUpdateStatus::UnrecoverableError
223 fn update_persisted_channel(&self, funding_txo: OutPoint, _update: Option<&ChannelMonitorUpdate>, monitor: &ChannelMonitor<ChannelSigner>) -> chain::ChannelMonitorUpdateStatus {
224 let key = format!("{}_{}", funding_txo.txid.to_string(), funding_txo.index);
226 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
227 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
228 &key, &monitor.encode())
230 Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
231 Err(_) => chain::ChannelMonitorUpdateStatus::UnrecoverableError
235 fn archive_persisted_channel(&self, funding_txo: OutPoint) {
236 let monitor_name = MonitorName::from(funding_txo);
237 let monitor = match self.read(
238 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
239 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
240 monitor_name.as_str(),
242 Ok(monitor) => monitor,
246 ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
247 ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
248 monitor_name.as_str(),
255 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
256 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
257 monitor_name.as_str(),
263 /// Read previously persisted [`ChannelMonitor`]s from the store.
264 pub fn read_channel_monitors<K: Deref, ES: Deref, SP: Deref>(
265 kv_store: K, entropy_source: ES, signer_provider: SP,
266 ) -> Result<Vec<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>, io::Error>
269 ES::Target: EntropySource + Sized,
270 SP::Target: SignerProvider + Sized,
272 let mut res = Vec::new();
274 for stored_key in kv_store.list(
275 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE, CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE)?
277 if stored_key.len() < 66 {
278 return Err(io::Error::new(
279 io::ErrorKind::InvalidData,
280 "Stored key has invalid length"));
283 let txid = Txid::from_str(stored_key.split_at(64).0).map_err(|_| {
284 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx ID in stored key")
287 let index: u16 = stored_key.split_at(65).1.parse().map_err(|_| {
288 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx index in stored key")
291 match <(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>::read(
292 &mut io::Cursor::new(
293 kv_store.read(CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE, CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE, &stored_key)?),
294 (&*entropy_source, &*signer_provider),
296 Ok((block_hash, channel_monitor)) => {
297 if channel_monitor.get_funding_txo().0.txid != txid
298 || channel_monitor.get_funding_txo().0.index != index
300 return Err(io::Error::new(
301 io::ErrorKind::InvalidData,
302 "ChannelMonitor was stored under the wrong key",
305 res.push((block_hash, channel_monitor));
308 return Err(io::Error::new(
309 io::ErrorKind::InvalidData,
310 "Failed to read ChannelMonitor"
318 /// Implements [`Persist`] in a way that writes and reads both [`ChannelMonitor`]s and
319 /// [`ChannelMonitorUpdate`]s.
323 /// The main benefit this provides over the [`KVStore`]'s [`Persist`] implementation is decreased
324 /// I/O bandwidth and storage churn, at the expense of more IOPS (including listing, reading, and
325 /// deleting) and complexity. This is because it writes channel monitor differential updates,
326 /// whereas the other (default) implementation rewrites the entire monitor on each update. For
327 /// routing nodes, updates can happen many times per second to a channel, and monitors can be tens
328 /// of megabytes (or more). Updates can be as small as a few hundred bytes.
330 /// Note that monitors written with `MonitorUpdatingPersister` are _not_ backward-compatible with
331 /// the default [`KVStore`]'s [`Persist`] implementation. They have a prepended byte sequence,
332 /// [`MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL`], applied to prevent deserialization with other
333 /// persisters. This is because monitors written by this struct _may_ have unapplied updates. In
334 /// order to downgrade, you must ensure that all updates are applied to the monitor, and remove the
337 /// # Storing monitors
339 /// Monitors are stored by implementing the [`Persist`] trait, which has two functions:
341 /// - [`Persist::persist_new_channel`], which persists whole [`ChannelMonitor`]s.
342 /// - [`Persist::update_persisted_channel`], which persists only a [`ChannelMonitorUpdate`]
344 /// Whole [`ChannelMonitor`]s are stored in the [`CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE`],
345 /// using the familiar encoding of an [`OutPoint`] (for example, `[SOME-64-CHAR-HEX-STRING]_1`).
347 /// Each [`ChannelMonitorUpdate`] is stored in a dynamic secondary namespace, as follows:
349 /// - primary namespace: [`CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE`]
350 /// - secondary namespace: [the monitor's encoded outpoint name]
352 /// Under that secondary namespace, each update is stored with a number string, like `21`, which
353 /// represents its `update_id` value.
355 /// For example, consider this channel, named for its transaction ID and index, or [`OutPoint`]:
357 /// - Transaction ID: `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef`
360 /// Full channel monitors would be stored at a single key:
362 /// `[CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1`
364 /// Updates would be stored as follows (with `/` delimiting primary_namespace/secondary_namespace/key):
367 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/1
368 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/2
369 /// [CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE]/deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1/3
373 /// # Reading channel state from storage
375 /// Channel state can be reconstructed by calling
376 /// [`MonitorUpdatingPersister::read_all_channel_monitors_with_updates`]. Alternatively, users can
377 /// list channel monitors themselves and load channels individually using
378 /// [`MonitorUpdatingPersister::read_channel_monitor_with_updates`].
380 /// ## EXTREMELY IMPORTANT
382 /// It is extremely important that your [`KVStore::read`] implementation uses the
383 /// [`io::ErrorKind::NotFound`] variant correctly: that is, when a file is not found, and _only_ in
384 /// that circumstance (not when there is really a permissions error, for example). This is because
385 /// neither channel monitor reading function lists updates. Instead, either reads the monitor, and
386 /// using its stored `update_id`, synthesizes update storage keys, and tries them in sequence until
387 /// one is not found. All _other_ errors will be bubbled up in the function's [`Result`].
389 /// # Pruning stale channel updates
391 /// Stale updates are pruned when the consolidation threshold is reached according to `maximum_pending_updates`.
392 /// Monitor updates in the range between the latest `update_id` and `update_id - maximum_pending_updates`
394 /// The `lazy` flag is used on the [`KVStore::remove`] method, so there are no guarantees that the deletions
395 /// will complete. However, stale updates are not a problem for data integrity, since updates are
396 /// only read that are higher than the stored [`ChannelMonitor`]'s `update_id`.
398 /// If you have many stale updates stored (such as after a crash with pending lazy deletes), and
399 /// would like to get rid of them, consider using the
400 /// [`MonitorUpdatingPersister::cleanup_stale_updates`] function.
401 pub struct MonitorUpdatingPersister<K: Deref, L: Deref, ES: Deref, SP: Deref>
405 ES::Target: EntropySource + Sized,
406 SP::Target: SignerProvider + Sized,
410 maximum_pending_updates: u64,
416 impl<K: Deref, L: Deref, ES: Deref, SP: Deref>
417 MonitorUpdatingPersister<K, L, ES, SP>
421 ES::Target: EntropySource + Sized,
422 SP::Target: SignerProvider + Sized,
424 /// Constructs a new [`MonitorUpdatingPersister`].
426 /// The `maximum_pending_updates` parameter controls how many updates may be stored before a
427 /// [`MonitorUpdatingPersister`] consolidates updates by writing a full monitor. Note that
428 /// consolidation will frequently occur with fewer updates than what you set here; this number
429 /// is merely the maximum that may be stored. When setting this value, consider that for higher
430 /// values of `maximum_pending_updates`:
432 /// - [`MonitorUpdatingPersister`] will tend to write more [`ChannelMonitorUpdate`]s than
433 /// [`ChannelMonitor`]s, approaching one [`ChannelMonitor`] write for every
434 /// `maximum_pending_updates` [`ChannelMonitorUpdate`]s.
435 /// - [`MonitorUpdatingPersister`] will issue deletes differently. Lazy deletes will come in
436 /// "waves" for each [`ChannelMonitor`] write. A larger `maximum_pending_updates` means bigger,
437 /// less frequent "waves."
438 /// - [`MonitorUpdatingPersister`] will potentially have more listing to do if you need to run
439 /// [`MonitorUpdatingPersister::cleanup_stale_updates`].
441 kv_store: K, logger: L, maximum_pending_updates: u64, entropy_source: ES,
444 MonitorUpdatingPersister {
447 maximum_pending_updates,
453 /// Reads all stored channel monitors, along with any stored updates for them.
455 /// It is extremely important that your [`KVStore::read`] implementation uses the
456 /// [`io::ErrorKind::NotFound`] variant correctly. For more information, please see the
457 /// documentation for [`MonitorUpdatingPersister`].
458 pub fn read_all_channel_monitors_with_updates<B: Deref, F: Deref>(
459 &self, broadcaster: &B, fee_estimator: &F,
460 ) -> Result<Vec<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>, io::Error>
462 B::Target: BroadcasterInterface,
463 F::Target: FeeEstimator,
465 let monitor_list = self.kv_store.list(
466 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
467 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
469 let mut res = Vec::with_capacity(monitor_list.len());
470 for monitor_key in monitor_list {
471 res.push(self.read_channel_monitor_with_updates(
480 /// Read a single channel monitor, along with any stored updates for it.
482 /// It is extremely important that your [`KVStore::read`] implementation uses the
483 /// [`io::ErrorKind::NotFound`] variant correctly. For more information, please see the
484 /// documentation for [`MonitorUpdatingPersister`].
486 /// For `monitor_key`, channel storage keys be the channel's transaction ID and index, or
487 /// [`OutPoint`], with an underscore `_` between them. For example, given:
489 /// - Transaction ID: `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef`
492 /// The correct `monitor_key` would be:
493 /// `deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1`
495 /// Loading a large number of monitors will be faster if done in parallel. You can use this
496 /// function to accomplish this. Take care to limit the number of parallel readers.
497 pub fn read_channel_monitor_with_updates<B: Deref, F: Deref>(
498 &self, broadcaster: &B, fee_estimator: &F, monitor_key: String,
499 ) -> Result<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>), io::Error>
501 B::Target: BroadcasterInterface,
502 F::Target: FeeEstimator,
504 let monitor_name = MonitorName::new(monitor_key)?;
505 let (block_hash, monitor) = self.read_monitor(&monitor_name)?;
506 let mut current_update_id = monitor.get_latest_update_id();
508 current_update_id = match current_update_id.checked_add(1) {
509 Some(next_update_id) => next_update_id,
512 let update_name = UpdateName::from(current_update_id);
513 let update = match self.read_monitor_update(&monitor_name, &update_name) {
514 Ok(update) => update,
515 Err(err) if err.kind() == io::ErrorKind::NotFound => {
516 // We can't find any more updates, so we are done.
519 Err(err) => return Err(err),
522 monitor.update_monitor(&update, broadcaster, fee_estimator, &self.logger)
526 "Monitor update failed. monitor: {} update: {} reason: {:?}",
527 monitor_name.as_str(),
528 update_name.as_str(),
531 io::Error::new(io::ErrorKind::Other, "Monitor update failed")
534 Ok((block_hash, monitor))
537 /// Read a channel monitor.
539 &self, monitor_name: &MonitorName,
540 ) -> Result<(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>), io::Error> {
541 let outpoint: OutPoint = monitor_name.try_into()?;
542 let mut monitor_cursor = io::Cursor::new(self.kv_store.read(
543 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
544 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
545 monitor_name.as_str(),
547 // Discard the sentinel bytes if found.
548 if monitor_cursor.get_ref().starts_with(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL) {
549 monitor_cursor.set_position(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL.len() as u64);
551 match <(BlockHash, ChannelMonitor<<SP::Target as SignerProvider>::EcdsaSigner>)>::read(
553 (&*self.entropy_source, &*self.signer_provider),
555 Ok((blockhash, channel_monitor)) => {
556 if channel_monitor.get_funding_txo().0.txid != outpoint.txid
557 || channel_monitor.get_funding_txo().0.index != outpoint.index
561 "ChannelMonitor {} was stored under the wrong key!",
562 monitor_name.as_str()
565 io::ErrorKind::InvalidData,
566 "ChannelMonitor was stored under the wrong key",
569 Ok((blockhash, channel_monitor))
575 "Failed to read ChannelMonitor {}, reason: {}",
576 monitor_name.as_str(),
579 Err(io::Error::new(io::ErrorKind::InvalidData, "Failed to read ChannelMonitor"))
584 /// Read a channel monitor update.
585 fn read_monitor_update(
586 &self, monitor_name: &MonitorName, update_name: &UpdateName,
587 ) -> Result<ChannelMonitorUpdate, io::Error> {
588 let update_bytes = self.kv_store.read(
589 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
590 monitor_name.as_str(),
591 update_name.as_str(),
593 ChannelMonitorUpdate::read(&mut io::Cursor::new(update_bytes)).map_err(|e| {
596 "Failed to read ChannelMonitorUpdate {}/{}/{}, reason: {}",
597 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
598 monitor_name.as_str(),
599 update_name.as_str(),
602 io::Error::new(io::ErrorKind::InvalidData, "Failed to read ChannelMonitorUpdate")
606 /// Cleans up stale updates for all monitors.
608 /// This function works by first listing all monitors, and then for each of them, listing all
609 /// updates. The updates that have an `update_id` less than or equal to than the stored monitor
610 /// are deleted. The deletion can either be lazy or non-lazy based on the `lazy` flag; this will
611 /// be passed to [`KVStore::remove`].
612 pub fn cleanup_stale_updates(&self, lazy: bool) -> Result<(), io::Error> {
613 let monitor_keys = self.kv_store.list(
614 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
615 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
617 for monitor_key in monitor_keys {
618 let monitor_name = MonitorName::new(monitor_key)?;
619 let (_, current_monitor) = self.read_monitor(&monitor_name)?;
622 .list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str())?;
623 for update in updates {
624 let update_name = UpdateName::new(update)?;
625 // if the update_id is lower than the stored monitor, delete
626 if update_name.0 <= current_monitor.get_latest_update_id() {
627 self.kv_store.remove(
628 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
629 monitor_name.as_str(),
630 update_name.as_str(),
640 impl<ChannelSigner: EcdsaChannelSigner, K: Deref, L: Deref, ES: Deref, SP: Deref>
641 Persist<ChannelSigner> for MonitorUpdatingPersister<K, L, ES, SP>
645 ES::Target: EntropySource + Sized,
646 SP::Target: SignerProvider + Sized,
648 /// Persists a new channel. This means writing the entire monitor to the
649 /// parametrized [`KVStore`].
650 fn persist_new_channel(
651 &self, funding_txo: OutPoint, monitor: &ChannelMonitor<ChannelSigner>
652 ) -> chain::ChannelMonitorUpdateStatus {
653 // Determine the proper key for this monitor
654 let monitor_name = MonitorName::from(funding_txo);
655 // Serialize and write the new monitor
656 let mut monitor_bytes = Vec::with_capacity(
657 MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL.len() + monitor.serialized_length(),
659 monitor_bytes.extend_from_slice(MONITOR_UPDATING_PERSISTER_PREPEND_SENTINEL);
660 monitor.write(&mut monitor_bytes).unwrap();
661 match self.kv_store.write(
662 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
663 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
664 monitor_name.as_str(),
668 chain::ChannelMonitorUpdateStatus::Completed
673 "Failed to write ChannelMonitor {}/{}/{} reason: {}",
674 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
675 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
676 monitor_name.as_str(),
679 chain::ChannelMonitorUpdateStatus::UnrecoverableError
684 /// Persists a channel update, writing only the update to the parameterized [`KVStore`] if possible.
686 /// In some cases, this will forward to [`MonitorUpdatingPersister::persist_new_channel`]:
688 /// - No full monitor is found in [`KVStore`]
689 /// - The number of pending updates exceeds `maximum_pending_updates` as given to [`Self::new`]
690 /// - LDK commands re-persisting the entire monitor through this function, specifically when
691 /// `update` is `None`.
692 /// - The update is at [`CLOSED_CHANNEL_UPDATE_ID`]
693 fn update_persisted_channel(
694 &self, funding_txo: OutPoint, update: Option<&ChannelMonitorUpdate>,
695 monitor: &ChannelMonitor<ChannelSigner>
696 ) -> chain::ChannelMonitorUpdateStatus {
697 if let Some(update) = update {
698 if update.update_id != CLOSED_CHANNEL_UPDATE_ID
699 && update.update_id % self.maximum_pending_updates != 0
701 let monitor_name = MonitorName::from(funding_txo);
702 let update_name = UpdateName::from(update.update_id);
703 match self.kv_store.write(
704 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
705 monitor_name.as_str(),
706 update_name.as_str(),
709 Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
713 "Failed to write ChannelMonitorUpdate {}/{}/{} reason: {}",
714 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
715 monitor_name.as_str(),
716 update_name.as_str(),
719 chain::ChannelMonitorUpdateStatus::UnrecoverableError
723 let monitor_name = MonitorName::from(funding_txo);
724 // In case of channel-close monitor update, we need to read old monitor before persisting
725 // the new one in order to determine the cleanup range.
726 let maybe_old_monitor = match monitor.get_latest_update_id() {
727 CLOSED_CHANNEL_UPDATE_ID => self.read_monitor(&monitor_name).ok(),
731 // We could write this update, but it meets criteria of our design that calls for a full monitor write.
732 let monitor_update_status = self.persist_new_channel(funding_txo, monitor);
734 if let chain::ChannelMonitorUpdateStatus::Completed = monitor_update_status {
735 let cleanup_range = if monitor.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
736 // If there is an error while reading old monitor, we skip clean up.
737 maybe_old_monitor.map(|(_, ref old_monitor)| {
738 let start = old_monitor.get_latest_update_id();
739 // We never persist an update with update_id = CLOSED_CHANNEL_UPDATE_ID
741 start.saturating_add(self.maximum_pending_updates),
742 CLOSED_CHANNEL_UPDATE_ID - 1,
747 let end = monitor.get_latest_update_id();
748 let start = end.saturating_sub(self.maximum_pending_updates);
752 if let Some((start, end)) = cleanup_range {
753 self.cleanup_in_range(monitor_name, start, end);
757 monitor_update_status
760 // There is no update given, so we must persist a new monitor.
761 self.persist_new_channel(funding_txo, monitor)
765 fn archive_persisted_channel(&self, funding_txo: OutPoint) {
766 let monitor_name = MonitorName::from(funding_txo);
767 let monitor = match self.read_monitor(&monitor_name) {
768 Ok((_block_hash, monitor)) => monitor,
771 match self.kv_store.write(
772 ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
773 ARCHIVED_CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
774 monitor_name.as_str(),
780 let _ = self.kv_store.remove(
781 CHANNEL_MONITOR_PERSISTENCE_PRIMARY_NAMESPACE,
782 CHANNEL_MONITOR_PERSISTENCE_SECONDARY_NAMESPACE,
783 monitor_name.as_str(),
789 impl<K: Deref, L: Deref, ES: Deref, SP: Deref> MonitorUpdatingPersister<K, L, ES, SP>
791 ES::Target: EntropySource + Sized,
794 SP::Target: SignerProvider + Sized
796 // Cleans up monitor updates for given monitor in range `start..=end`.
797 fn cleanup_in_range(&self, monitor_name: MonitorName, start: u64, end: u64) {
798 for update_id in start..=end {
799 let update_name = UpdateName::from(update_id);
800 if let Err(e) = self.kv_store.remove(
801 CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
802 monitor_name.as_str(),
803 update_name.as_str(),
808 "Failed to clean up channel monitor updates for monitor {}, reason: {}",
809 monitor_name.as_str(),
817 /// A struct representing a name for a monitor.
819 struct MonitorName(String);
822 /// Constructs a [`MonitorName`], after verifying that an [`OutPoint`] can
823 /// be formed from the given `name`.
824 pub fn new(name: String) -> Result<Self, io::Error> {
825 MonitorName::do_try_into_outpoint(&name)?;
828 /// Convert this monitor name to a str.
829 pub fn as_str(&self) -> &str {
832 /// Attempt to form a valid [`OutPoint`] from a given name string.
833 fn do_try_into_outpoint(name: &str) -> Result<OutPoint, io::Error> {
834 let mut parts = name.splitn(2, '_');
835 let txid = if let Some(part) = parts.next() {
836 Txid::from_str(part).map_err(|_| {
837 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx ID in stored key")
840 return Err(io::Error::new(
841 io::ErrorKind::InvalidData,
842 "Stored monitor key is not a splittable string",
845 let index = if let Some(part) = parts.next() {
846 part.parse().map_err(|_| {
847 io::Error::new(io::ErrorKind::InvalidData, "Invalid tx index in stored key")
850 return Err(io::Error::new(
851 io::ErrorKind::InvalidData,
852 "No tx index value found after underscore in stored key",
855 Ok(OutPoint { txid, index })
859 impl TryFrom<&MonitorName> for OutPoint {
860 type Error = io::Error;
862 fn try_from(value: &MonitorName) -> Result<Self, io::Error> {
863 MonitorName::do_try_into_outpoint(&value.0)
867 impl From<OutPoint> for MonitorName {
868 fn from(value: OutPoint) -> Self {
869 MonitorName(format!("{}_{}", value.txid.to_string(), value.index))
873 /// A struct representing a name for an update.
875 struct UpdateName(u64, String);
878 /// Constructs an [`UpdateName`], after verifying that an update sequence ID
879 /// can be derived from the given `name`.
880 pub fn new(name: String) -> Result<Self, io::Error> {
881 match name.parse::<u64>() {
882 Ok(u) => Ok(u.into()),
884 Err(io::Error::new(io::ErrorKind::InvalidData, "cannot parse u64 from update name"))
889 /// Convert this monitor update name to a &str
890 pub fn as_str(&self) -> &str {
895 impl From<u64> for UpdateName {
896 fn from(value: u64) -> Self {
897 Self(value, value.to_string())
904 use crate::chain::ChannelMonitorUpdateStatus;
905 use crate::events::{ClosureReason, MessageSendEventsProvider};
906 use crate::ln::functional_test_utils::*;
907 use crate::util::test_utils::{self, TestLogger, TestStore};
908 use crate::{check_added_monitors, check_closed_broadcast};
909 use crate::sync::Arc;
910 use crate::util::test_channel_signer::TestChannelSigner;
912 const EXPECTED_UPDATES_PER_PAYMENT: u64 = 5;
915 fn converts_u64_to_update_name() {
916 assert_eq!(UpdateName::from(0).as_str(), "0");
917 assert_eq!(UpdateName::from(21).as_str(), "21");
918 assert_eq!(UpdateName::from(u64::MAX).as_str(), "18446744073709551615");
922 fn bad_update_name_fails() {
923 assert!(UpdateName::new("deadbeef".to_string()).is_err());
924 assert!(UpdateName::new("-1".to_string()).is_err());
928 fn monitor_from_outpoint_works() {
929 let monitor_name1 = MonitorName::from(OutPoint {
930 txid: Txid::from_str("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef").unwrap(),
933 assert_eq!(monitor_name1.as_str(), "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_1");
935 let monitor_name2 = MonitorName::from(OutPoint {
936 txid: Txid::from_str("f33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeef").unwrap(),
939 assert_eq!(monitor_name2.as_str(), "f33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeeff33dbeef_65535");
943 fn bad_monitor_string_fails() {
944 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef".to_string()).is_err());
945 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_65536".to_string()).is_err());
946 assert!(MonitorName::new("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef_21".to_string()).is_err());
949 // Exercise the `MonitorUpdatingPersister` with real channels and payments.
951 fn persister_with_real_monitors() {
952 // This value is used later to limit how many iterations we perform.
953 let persister_0_max_pending_updates = 7;
954 // Intentionally set this to a smaller value to test a different alignment.
955 let persister_1_max_pending_updates = 3;
956 let chanmon_cfgs = create_chanmon_cfgs(4);
957 let persister_0 = MonitorUpdatingPersister {
958 kv_store: &TestStore::new(false),
959 logger: &TestLogger::new(),
960 maximum_pending_updates: persister_0_max_pending_updates,
961 entropy_source: &chanmon_cfgs[0].keys_manager,
962 signer_provider: &chanmon_cfgs[0].keys_manager,
964 let persister_1 = MonitorUpdatingPersister {
965 kv_store: &TestStore::new(false),
966 logger: &TestLogger::new(),
967 maximum_pending_updates: persister_1_max_pending_updates,
968 entropy_source: &chanmon_cfgs[1].keys_manager,
969 signer_provider: &chanmon_cfgs[1].keys_manager,
971 let mut node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
972 let chain_mon_0 = test_utils::TestChainMonitor::new(
973 Some(&chanmon_cfgs[0].chain_source),
974 &chanmon_cfgs[0].tx_broadcaster,
975 &chanmon_cfgs[0].logger,
976 &chanmon_cfgs[0].fee_estimator,
978 &chanmon_cfgs[0].keys_manager,
980 let chain_mon_1 = test_utils::TestChainMonitor::new(
981 Some(&chanmon_cfgs[1].chain_source),
982 &chanmon_cfgs[1].tx_broadcaster,
983 &chanmon_cfgs[1].logger,
984 &chanmon_cfgs[1].fee_estimator,
986 &chanmon_cfgs[1].keys_manager,
988 node_cfgs[0].chain_monitor = chain_mon_0;
989 node_cfgs[1].chain_monitor = chain_mon_1;
990 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
991 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
992 let broadcaster_0 = &chanmon_cfgs[2].tx_broadcaster;
993 let broadcaster_1 = &chanmon_cfgs[3].tx_broadcaster;
995 // Check that the persisted channel data is empty before any channels are
997 let mut persisted_chan_data_0 = persister_0.read_all_channel_monitors_with_updates(
998 &broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
999 assert_eq!(persisted_chan_data_0.len(), 0);
1000 let mut persisted_chan_data_1 = persister_1.read_all_channel_monitors_with_updates(
1001 &broadcaster_1, &&chanmon_cfgs[1].fee_estimator).unwrap();
1002 assert_eq!(persisted_chan_data_1.len(), 0);
1004 // Helper to make sure the channel is on the expected update ID.
1005 macro_rules! check_persisted_data {
1006 ($expected_update_id: expr) => {
1007 persisted_chan_data_0 = persister_0.read_all_channel_monitors_with_updates(
1008 &broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1009 // check that we stored only one monitor
1010 assert_eq!(persisted_chan_data_0.len(), 1);
1011 for (_, mon) in persisted_chan_data_0.iter() {
1012 // check that when we read it, we got the right update id
1013 assert_eq!(mon.get_latest_update_id(), $expected_update_id);
1015 // if the CM is at consolidation threshold, ensure no updates are stored.
1016 let monitor_name = MonitorName::from(mon.get_funding_txo().0);
1017 if mon.get_latest_update_id() % persister_0_max_pending_updates == 0
1018 || mon.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
1020 persister_0.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
1021 monitor_name.as_str()).unwrap().len(),
1023 "updates stored when they shouldn't be in persister 0"
1027 persisted_chan_data_1 = persister_1.read_all_channel_monitors_with_updates(
1028 &broadcaster_1, &&chanmon_cfgs[1].fee_estimator).unwrap();
1029 assert_eq!(persisted_chan_data_1.len(), 1);
1030 for (_, mon) in persisted_chan_data_1.iter() {
1031 assert_eq!(mon.get_latest_update_id(), $expected_update_id);
1032 let monitor_name = MonitorName::from(mon.get_funding_txo().0);
1033 // if the CM is at consolidation threshold, ensure no updates are stored.
1034 if mon.get_latest_update_id() % persister_1_max_pending_updates == 0
1035 || mon.get_latest_update_id() == CLOSED_CHANNEL_UPDATE_ID {
1037 persister_1.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE,
1038 monitor_name.as_str()).unwrap().len(),
1040 "updates stored when they shouldn't be in persister 1"
1047 // Create some initial channel and check that a channel was persisted.
1048 let _ = create_announced_chan_between_nodes(&nodes, 0, 1);
1049 check_persisted_data!(0);
1051 // Send a few payments and make sure the monitors are updated to the latest.
1052 send_payment(&nodes[0], &vec![&nodes[1]][..], 8_000_000);
1053 check_persisted_data!(EXPECTED_UPDATES_PER_PAYMENT);
1054 send_payment(&nodes[1], &vec![&nodes[0]][..], 4_000_000);
1055 check_persisted_data!(2 * EXPECTED_UPDATES_PER_PAYMENT);
1057 // Send a few more payments to try all the alignments of max pending updates with
1058 // updates for a payment sent and received.
1060 for i in 3..=persister_0_max_pending_updates * 2 {
1069 send_payment(&nodes[sender], &vec![&nodes[receiver]][..], 21_000);
1070 check_persisted_data!(i * EXPECTED_UPDATES_PER_PAYMENT);
1073 // Force close because cooperative close doesn't result in any persisted
1076 let error_message = "Channel force-closed";
1077 nodes[0].node.force_close_broadcasting_latest_txn(&nodes[0].node.list_channels()[0].channel_id, &nodes[1].node.get_our_node_id(), error_message.to_string()).unwrap();
1079 check_closed_event(&nodes[0], 1, ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(true) }, false, &[nodes[1].node.get_our_node_id()], 100000);
1080 check_closed_broadcast!(nodes[0], true);
1081 check_added_monitors!(nodes[0], 1);
1083 let node_txn = nodes[0].tx_broadcaster.txn_broadcast();
1084 assert_eq!(node_txn.len(), 1);
1086 connect_block(&nodes[1], &create_dummy_block(nodes[0].best_block_hash(), 42, vec![node_txn[0].clone(), node_txn[0].clone()]));
1088 check_closed_broadcast!(nodes[1], true);
1089 check_closed_event(&nodes[1], 1, ClosureReason::CommitmentTxConfirmed, false, &[nodes[0].node.get_our_node_id()], 100000);
1090 check_added_monitors!(nodes[1], 1);
1092 // Make sure everything is persisted as expected after close.
1093 check_persisted_data!(CLOSED_CHANNEL_UPDATE_ID);
1095 // Make sure the expected number of stale updates is present.
1096 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1097 let (_, monitor) = &persisted_chan_data[0];
1098 let monitor_name = MonitorName::from(monitor.get_funding_txo().0);
1099 // The channel should have 0 updates, as it wrote a full monitor and consolidated.
1100 assert_eq!(persister_0.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str()).unwrap().len(), 0);
1101 assert_eq!(persister_1.kv_store.list(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str()).unwrap().len(), 0);
1104 // Test that if the `MonitorUpdatingPersister`'s can't actually write, trying to persist a
1105 // monitor or update with it results in the persister returning an UnrecoverableError status.
1107 fn unrecoverable_error_on_write_failure() {
1108 // Set up a dummy channel and force close. This will produce a monitor
1109 // that we can then use to test persistence.
1110 let chanmon_cfgs = create_chanmon_cfgs(2);
1111 let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
1112 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
1113 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
1114 let chan = create_announced_chan_between_nodes(&nodes, 0, 1);
1115 let error_message = "Channel force-closed";
1116 nodes[1].node.force_close_broadcasting_latest_txn(&chan.2, &nodes[0].node.get_our_node_id(), error_message.to_string()).unwrap();
1117 check_closed_event(&nodes[1], 1, ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(true) }, false, &[nodes[0].node.get_our_node_id()], 100000);
1119 let mut added_monitors = nodes[1].chain_monitor.added_monitors.lock().unwrap();
1120 let cmu_map = nodes[1].chain_monitor.monitor_updates.lock().unwrap();
1121 let cmu = &cmu_map.get(&added_monitors[0].1.channel_id()).unwrap()[0];
1122 let test_txo = OutPoint { txid: Txid::from_str("8984484a580b825b9972d7adb15050b3ab624ccd731946b3eeddb92f4e7ef6be").unwrap(), index: 0 };
1124 let ro_persister = MonitorUpdatingPersister {
1125 kv_store: &TestStore::new(true),
1126 logger: &TestLogger::new(),
1127 maximum_pending_updates: 11,
1128 entropy_source: node_cfgs[0].keys_manager,
1129 signer_provider: node_cfgs[0].keys_manager,
1131 match ro_persister.persist_new_channel(test_txo, &added_monitors[0].1) {
1132 ChannelMonitorUpdateStatus::UnrecoverableError => {
1135 ChannelMonitorUpdateStatus::Completed => {
1136 panic!("Completed persisting new channel when shouldn't have")
1138 ChannelMonitorUpdateStatus::InProgress => {
1139 panic!("Returned InProgress when shouldn't have")
1142 match ro_persister.update_persisted_channel(test_txo, Some(cmu), &added_monitors[0].1) {
1143 ChannelMonitorUpdateStatus::UnrecoverableError => {
1146 ChannelMonitorUpdateStatus::Completed => {
1147 panic!("Completed persisting new channel when shouldn't have")
1149 ChannelMonitorUpdateStatus::InProgress => {
1150 panic!("Returned InProgress when shouldn't have")
1153 added_monitors.clear();
1155 nodes[1].node.get_and_clear_pending_msg_events();
1158 // Confirm that the `clean_stale_updates` function finds and deletes stale updates.
1160 fn clean_stale_updates_works() {
1161 let test_max_pending_updates = 7;
1162 let chanmon_cfgs = create_chanmon_cfgs(3);
1163 let persister_0 = MonitorUpdatingPersister {
1164 kv_store: &TestStore::new(false),
1165 logger: &TestLogger::new(),
1166 maximum_pending_updates: test_max_pending_updates,
1167 entropy_source: &chanmon_cfgs[0].keys_manager,
1168 signer_provider: &chanmon_cfgs[0].keys_manager,
1170 let persister_1 = MonitorUpdatingPersister {
1171 kv_store: &TestStore::new(false),
1172 logger: &TestLogger::new(),
1173 maximum_pending_updates: test_max_pending_updates,
1174 entropy_source: &chanmon_cfgs[1].keys_manager,
1175 signer_provider: &chanmon_cfgs[1].keys_manager,
1177 let mut node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
1178 let chain_mon_0 = test_utils::TestChainMonitor::new(
1179 Some(&chanmon_cfgs[0].chain_source),
1180 &chanmon_cfgs[0].tx_broadcaster,
1181 &chanmon_cfgs[0].logger,
1182 &chanmon_cfgs[0].fee_estimator,
1184 &chanmon_cfgs[0].keys_manager,
1186 let chain_mon_1 = test_utils::TestChainMonitor::new(
1187 Some(&chanmon_cfgs[1].chain_source),
1188 &chanmon_cfgs[1].tx_broadcaster,
1189 &chanmon_cfgs[1].logger,
1190 &chanmon_cfgs[1].fee_estimator,
1192 &chanmon_cfgs[1].keys_manager,
1194 node_cfgs[0].chain_monitor = chain_mon_0;
1195 node_cfgs[1].chain_monitor = chain_mon_1;
1196 let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
1197 let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
1199 let broadcaster_0 = &chanmon_cfgs[2].tx_broadcaster;
1201 // Check that the persisted channel data is empty before any channels are
1203 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1204 assert_eq!(persisted_chan_data.len(), 0);
1206 // Create some initial channel
1207 let _ = create_announced_chan_between_nodes(&nodes, 0, 1);
1209 // Send a few payments to advance the updates a bit
1210 send_payment(&nodes[0], &vec![&nodes[1]][..], 8_000_000);
1211 send_payment(&nodes[1], &vec![&nodes[0]][..], 4_000_000);
1213 // Get the monitor and make a fake stale update at update_id=1 (lowest height of an update possible)
1214 let persisted_chan_data = persister_0.read_all_channel_monitors_with_updates(&broadcaster_0, &&chanmon_cfgs[0].fee_estimator).unwrap();
1215 let (_, monitor) = &persisted_chan_data[0];
1216 let monitor_name = MonitorName::from(monitor.get_funding_txo().0);
1219 .write(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(1).as_str(), &[0u8; 1])
1222 // Do the stale update cleanup
1223 persister_0.cleanup_stale_updates(false).unwrap();
1225 // Confirm the stale update is unreadable/gone
1228 .read(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(1).as_str())
1232 let error_message = "Channel force-closed";
1233 nodes[0].node.force_close_broadcasting_latest_txn(&nodes[0].node.list_channels()[0].channel_id, &nodes[1].node.get_our_node_id(), error_message.to_string()).unwrap();
1234 check_closed_event(&nodes[0], 1, ClosureReason::HolderForceClosed { broadcasted_latest_txn: Some(true) }, false, &[nodes[1].node.get_our_node_id()], 100000);
1235 check_closed_broadcast!(nodes[0], true);
1236 check_added_monitors!(nodes[0], 1);
1238 // Write an update near u64::MAX
1241 .write(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(u64::MAX - 1).as_str(), &[0u8; 1])
1244 // Do the stale update cleanup
1245 persister_0.cleanup_stale_updates(false).unwrap();
1247 // Confirm the stale update is unreadable/gone
1250 .read(CHANNEL_MONITOR_UPDATE_PERSISTENCE_PRIMARY_NAMESPACE, monitor_name.as_str(), UpdateName::from(u64::MAX - 1).as_str())
1254 fn persist_fn<P: Deref, ChannelSigner: EcdsaChannelSigner>(_persist: P) -> bool where P::Target: Persist<ChannelSigner> {
1259 fn kvstore_trait_object_usage() {
1260 let store: Arc<dyn KVStore + Send + Sync> = Arc::new(TestStore::new(false));
1261 assert!(persist_fn::<_, TestChannelSigner>(store.clone()));