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.
12 use bitcoin::hashes::hex::ToHex;
14 use crate::prelude::{Vec, String};
15 use crate::routing::scoring::WriteableScore;
18 use crate::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
19 use crate::chain::chainmonitor::{Persist, MonitorUpdateId};
20 use crate::sign::{EntropySource, NodeSigner, WriteableEcdsaChannelSigner, SignerProvider};
21 use crate::chain::transaction::OutPoint;
22 use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate};
23 use crate::ln::channelmanager::ChannelManager;
24 use crate::routing::router::Router;
25 use crate::routing::gossip::NetworkGraph;
26 use crate::util::logger::Logger;
27 use crate::util::ser::Writeable;
29 /// The alphabet of characters allowed for namespaces and keys.
30 pub const KVSTORE_NAMESPACE_KEY_ALPHABET: &str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
32 /// The maximum number of characters namespaces and keys may have.
33 pub const KVSTORE_NAMESPACE_KEY_MAX_LEN: usize = 120;
35 /// The namespace under which the [`ChannelManager`] will be persisted.
36 pub const CHANNEL_MANAGER_PERSISTENCE_NAMESPACE: &str = "";
37 /// The sub-namespace under which the [`ChannelManager`] will be persisted.
38 pub const CHANNEL_MANAGER_PERSISTENCE_SUB_NAMESPACE: &str = "";
39 /// The key under which the [`ChannelManager`] will be persisted.
40 pub const CHANNEL_MANAGER_PERSISTENCE_KEY: &str = "manager";
42 /// The namespace under which [`ChannelMonitor`]s will be persisted.
43 pub const CHANNEL_MONITOR_PERSISTENCE_NAMESPACE: &str = "monitors";
44 /// The sub-namespace under which [`ChannelMonitor`]s will be persisted.
45 pub const CHANNEL_MONITOR_PERSISTENCE_SUB_NAMESPACE: &str = "";
47 /// The namespace under which the [`NetworkGraph`] will be persisted.
48 pub const NETWORK_GRAPH_PERSISTENCE_NAMESPACE: &str = "";
49 /// The sub-namespace under which the [`NetworkGraph`] will be persisted.
50 pub const NETWORK_GRAPH_PERSISTENCE_SUB_NAMESPACE: &str = "";
51 /// The key under which the [`NetworkGraph`] will be persisted.
52 pub const NETWORK_GRAPH_PERSISTENCE_KEY: &str = "network_graph";
54 /// The namespace under which the [`WriteableScore`] will be persisted.
55 pub const SCORER_PERSISTENCE_NAMESPACE: &str = "";
56 /// The sub-namespace under which the [`WriteableScore`] will be persisted.
57 pub const SCORER_PERSISTENCE_SUB_NAMESPACE: &str = "";
58 /// The key under which the [`WriteableScore`] will be persisted.
59 pub const SCORER_PERSISTENCE_KEY: &str = "scorer";
61 /// Provides an interface that allows storage and retrieval of persisted values that are associated
64 /// In order to avoid collisions the key space is segmented based on the given `namespace`s and
65 /// `sub_namespace`s. Implementations of this trait are free to handle them in different ways, as
66 /// long as per-namespace key uniqueness is asserted.
68 /// Keys and namespaces are required to be valid ASCII strings in the range of
69 /// [`KVSTORE_NAMESPACE_KEY_ALPHABET`] and no longer than [`KVSTORE_NAMESPACE_KEY_MAX_LEN`]. Empty
70 /// namespaces and sub-namespaces (`""`) are assumed to be a valid, however, if `namespace` is
71 /// empty, `sub_namespace` is required to be empty, too. This means that concerns should always be
72 /// separated by namespace first, before sub-namespaces are used. While the number of namespaces
73 /// will be relatively small and is determined at compile time, there may be many sub-namespaces
74 /// per namespace. Note that per-namespace uniqueness needs to also hold for keys *and*
75 /// namespaces/sub-namespaces in any given namespace/sub-namespace, i.e., conflicts between keys
76 /// and equally named namespaces/sub-namespaces must be avoided.
78 /// **Note:** Users migrating custom persistence backends from the pre-v0.0.117 `KVStorePersister`
79 /// interface can use a concatenation of `[{namespace}/[{sub_namespace}/]]{key}` to recover a `key` compatible with the
80 /// data model previously assumed by `KVStorePersister::persist`.
82 /// Returns the data stored for the given `namespace`, `sub_namespace`, and `key`.
84 /// Returns an [`ErrorKind::NotFound`] if the given `key` could not be found in the given
85 /// `namespace` and `sub_namespace`.
87 /// [`ErrorKind::NotFound`]: io::ErrorKind::NotFound
88 fn read(&self, namespace: &str, sub_namespace: &str, key: &str) -> io::Result<Vec<u8>>;
89 /// Persists the given data under the given `key`.
91 /// Will create the given `namespace` and `sub_namespace` if not already present in the store.
92 fn write(&self, namespace: &str, sub_namespace: &str, key: &str, buf: &[u8]) -> io::Result<()>;
93 /// Removes any data that had previously been persisted under the given `key`.
95 /// If the `lazy` flag is set to `true`, the backend implementation might choose to lazily
96 /// remove the given `key` at some point in time after the method returns, e.g., as part of an
97 /// eventual batch deletion of multiple keys. As a consequence, subsequent calls to
98 /// [`KVStore::list`] might include the removed key until the changes are actually persisted.
100 /// Note that while setting the `lazy` flag reduces the I/O burden of multiple subsequent
101 /// `remove` calls, it also influences the atomicity guarantees as lazy `remove`s could
102 /// potentially get lost on crash after the method returns. Therefore, this flag should only be
103 /// set for `remove` operations that can be safely replayed at a later time.
105 /// Returns successfully if no data will be stored for the given `namespace`, `sub_namespace`, and
106 /// `key`, independently of whether it was present before its invokation or not.
107 fn remove(&self, namespace: &str, sub_namespace: &str, key: &str, lazy: bool) -> io::Result<()>;
108 /// Returns a list of keys that are stored under the given `sub_namespace` in `namespace`.
110 /// Returns the keys in arbitrary order, so users requiring a particular order need to sort the
111 /// returned keys. Returns an empty list if `namespace` or `sub_namespace` is unknown.
112 fn list(&self, namespace: &str, sub_namespace: &str) -> io::Result<Vec<String>>;
115 /// Trait for a key-value store for persisting some writeable object at some key
116 /// Implementing `KVStorePersister` provides auto-implementations for [`Persister`]
117 /// and [`Persist`] traits. It uses "manager", "network_graph",
118 /// and "monitors/{funding_txo_id}_{funding_txo_index}" for keys.
119 pub trait KVStorePersister {
120 /// Persist the given writeable using the provided key
121 fn persist<W: Writeable>(&self, key: &str, object: &W) -> io::Result<()>;
124 /// Trait that handles persisting a [`ChannelManager`], [`NetworkGraph`], and [`WriteableScore`] to disk.
125 pub trait Persister<'a, M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref, S: WriteableScore<'a>>
126 where M::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::Signer>,
127 T::Target: 'static + BroadcasterInterface,
128 ES::Target: 'static + EntropySource,
129 NS::Target: 'static + NodeSigner,
130 SP::Target: 'static + SignerProvider,
131 F::Target: 'static + FeeEstimator,
132 R::Target: 'static + Router,
133 L::Target: 'static + Logger,
135 /// Persist the given ['ChannelManager'] to disk, returning an error if persistence failed.
136 fn persist_manager(&self, channel_manager: &ChannelManager<M, T, ES, NS, SP, F, R, L>) -> Result<(), io::Error>;
138 /// Persist the given [`NetworkGraph`] to disk, returning an error if persistence failed.
139 fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error>;
141 /// Persist the given [`WriteableScore`] to disk, returning an error if persistence failed.
142 fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error>;
145 impl<'a, A: KVStorePersister, 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
146 where M::Target: 'static + chain::Watch<<SP::Target as SignerProvider>::Signer>,
147 T::Target: 'static + BroadcasterInterface,
148 ES::Target: 'static + EntropySource,
149 NS::Target: 'static + NodeSigner,
150 SP::Target: 'static + SignerProvider,
151 F::Target: 'static + FeeEstimator,
152 R::Target: 'static + Router,
153 L::Target: 'static + Logger,
155 /// Persist the given ['ChannelManager'] to disk with the name "manager", returning an error if persistence failed.
156 fn persist_manager(&self, channel_manager: &ChannelManager<M, T, ES, NS, SP, F, R, L>) -> Result<(), io::Error> {
157 self.persist("manager", channel_manager)
160 /// Persist the given [`NetworkGraph`] to disk with the name "network_graph", returning an error if persistence failed.
161 fn persist_graph(&self, network_graph: &NetworkGraph<L>) -> Result<(), io::Error> {
162 self.persist("network_graph", network_graph)
165 /// Persist the given [`WriteableScore`] to disk with name "scorer", returning an error if persistence failed.
166 fn persist_scorer(&self, scorer: &S) -> Result<(), io::Error> {
167 self.persist("scorer", &scorer)
171 impl<ChannelSigner: WriteableEcdsaChannelSigner, K: KVStorePersister> Persist<ChannelSigner> for K {
172 // TODO: We really need a way for the persister to inform the user that its time to crash/shut
173 // down once these start returning failure.
174 // A PermanentFailure implies we should probably just shut down the node since we're
175 // force-closing channels without even broadcasting!
177 fn persist_new_channel(&self, funding_txo: OutPoint, monitor: &ChannelMonitor<ChannelSigner>, _update_id: MonitorUpdateId) -> chain::ChannelMonitorUpdateStatus {
178 let key = format!("monitors/{}_{}", funding_txo.txid.to_hex(), funding_txo.index);
179 match self.persist(&key, monitor) {
180 Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
181 Err(_) => chain::ChannelMonitorUpdateStatus::PermanentFailure,
185 fn update_persisted_channel(&self, funding_txo: OutPoint, _update: Option<&ChannelMonitorUpdate>, monitor: &ChannelMonitor<ChannelSigner>, _update_id: MonitorUpdateId) -> chain::ChannelMonitorUpdateStatus {
186 let key = format!("monitors/{}_{}", funding_txo.txid.to_hex(), funding_txo.index);
187 match self.persist(&key, monitor) {
188 Ok(()) => chain::ChannelMonitorUpdateStatus::Completed,
189 Err(_) => chain::ChannelMonitorUpdateStatus::PermanentFailure,