_ Git - rust-lightning/blob - lightning/src/lib.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
   5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
   7 // You may not use this file except in accordance with one or both of these
   8 // licenses.
   9
  10 #![crate_name = "lightning"]
  11
  12 //! Rust-Lightning, not Rusty's Lightning!
  13 //!
  14 //! A full-featured but also flexible lightning implementation, in library form. This allows the
  15 //! user (you) to decide how they wish to use it instead of being a fully self-contained daemon.
  16 //! This means there is no built-in threading/execution environment and it's up to the user to
  17 //! figure out how best to make networking happen/timers fire/things get written to disk/keys get
  18 //! generated/etc. This makes it a good candidate for tight integration into an existing wallet
  19 //! instead of having a rather-separate lightning appendage to a wallet.
  20 //!
  21 //! `default` features are:
  22 //!
  23 //! * `std` - enables functionalities which require `std`, including `std::io` trait implementations and things which utilize time
  24 //! * `grind_signatures` - enables generation of [low-r bitcoin signatures](https://bitcoin.stackexchange.com/questions/111660/what-is-signature-grinding),
  25 //! which saves 1 byte per signature in 50% of the cases (see [bitcoin PR #13666](https://github.com/bitcoin/bitcoin/pull/13666))
  26 //!
  27 //! Available features are:
  28 //!
  29 //! * `std`
  30 //! * `grind_signatures`
  31 //! * `no-std ` - exposes write trait implementations from the `core2` crate (at least one of `no-std` or `std` are required)
  32 //! * Skip logging of messages at levels below the given log level:
  33 //!     * `max_level_off`
  34 //!     * `max_level_error`
  35 //!     * `max_level_warn`
  36 //!     * `max_level_info`
  37 //!     * `max_level_debug`
  38 //!     * `max_level_trace`
  39
  40 #![cfg_attr(not(any(test, fuzzing, feature = "_test_utils")), deny(missing_docs))]
  41 #![cfg_attr(not(any(test, feature = "_test_utils")), forbid(unsafe_code))]
  42
  43 #![deny(rustdoc::broken_intra_doc_links)]
  44 #![deny(rustdoc::private_intra_doc_links)]
  45
  46 // In general, rust is absolutely horrid at supporting users doing things like,
  47 // for example, compiling Rust code for real environments. Disable useless lints
  48 // that don't do anything but annoy us and cant actually ever be resolved.
  49 #![allow(bare_trait_objects)]
  50 #![allow(ellipsis_inclusive_range_patterns)]
  51
  52 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
  53
  54 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
  55
  56 #[cfg(not(any(feature = "std", feature = "no-std")))]
  57 compile_error!("at least one of the `std` or `no-std` features must be enabled");
  58
  59 #[cfg(all(fuzzing, test))]
  60 compile_error!("Tests will always fail with cfg=fuzzing");
  61
  62 #[macro_use]
  63 extern crate alloc;
  64 extern crate bitcoin;
  65 #[cfg(any(test, feature = "std"))]
  66 extern crate core;
  67
  68 extern crate hex;
  69 #[cfg(any(test, feature = "_test_utils"))] extern crate regex;
  70
  71 #[cfg(not(feature = "std"))] extern crate core2;
  72 #[cfg(not(feature = "std"))] extern crate libm;
  73
  74 #[cfg(ldk_bench)] extern crate criterion;
  75
  76 #[macro_use]
  77 pub mod util;
  78 pub mod chain;
  79 pub mod ln;
  80 pub mod offers;
  81 pub mod routing;
  82 pub mod sign;
  83 pub mod onion_message;
  84 pub mod blinded_path;
  85 pub mod events;
  86
  87 pub(crate) mod crypto;
  88
  89 #[cfg(feature = "std")]
  90 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
  91 pub use std::io;
  92 #[cfg(not(feature = "std"))]
  93 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
  94 pub use core2::io;
  95
  96 #[cfg(not(feature = "std"))]
  97 mod io_extras {
  98         use core2::io::{self, Read, Write};
  99
 100         /// A writer which will move data into the void.
 101         pub struct Sink {
 102                 _priv: (),
 103         }
 104
 105         /// Creates an instance of a writer which will successfully consume all data.
 106         pub const fn sink() -> Sink {
 107                 Sink { _priv: () }
 108         }
 109
 110         impl core2::io::Write for Sink {
 111                 #[inline]
 112                 fn write(&mut self, buf: &[u8]) -> core2::io::Result<usize> {
 113                         Ok(buf.len())
 114                 }
 115
 116                 #[inline]
 117                 fn flush(&mut self) -> core2::io::Result<()> {
 118                         Ok(())
 119                 }
 120         }
 121
 122         pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64, io::Error>
 123                 where
 124                 R: Read,
 125                 W: Write,
 126         {
 127                 let mut count = 0;
 128                 let mut buf = [0u8; 64];
 129
 130                 loop {
 131                         match reader.read(&mut buf) {
 132                                 Ok(0) => break,
 133                                 Ok(n) => { writer.write_all(&buf[0..n])?; count += n as u64; },
 134                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
 135                                 Err(e) => return Err(e.into()),
 136                         };
 137                 }
 138                 Ok(count)
 139         }
 140
 141         pub fn read_to_end<D: io::Read>(mut d: D) -> Result<alloc::vec::Vec<u8>, io::Error> {
 142                 let mut result = vec![];
 143                 let mut buf = [0u8; 64];
 144                 loop {
 145                         match d.read(&mut buf) {
 146                                 Ok(0) => break,
 147                                 Ok(n) => result.extend_from_slice(&buf[0..n]),
 148                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
 149                                 Err(e) => return Err(e.into()),
 150                         };
 151                 }
 152                 Ok(result)
 153         }
 154 }
 155
 156 #[cfg(feature = "std")]
 157 mod io_extras {
 158         pub fn read_to_end<D: ::std::io::Read>(mut d: D) -> Result<Vec<u8>, ::std::io::Error> {
 159                 let mut buf = Vec::new();
 160                 d.read_to_end(&mut buf)?;
 161                 Ok(buf)
 162         }
 163
 164         pub use std::io::{copy, sink};
 165 }
 166
 167 mod prelude {
 168         #[cfg(feature = "hashbrown")]
 169         extern crate hashbrown;
 170         #[cfg(feature = "ahash")]
 171         extern crate ahash;
 172
 173         pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
 174
 175         pub use alloc::borrow::ToOwned;
 176         pub use alloc::string::ToString;
 177
 178         // For no-std builds, we need to use hashbrown, however, by default, it doesn't randomize the
 179         // hashing and is vulnerable to HashDoS attacks. Thus, when not fuzzing, we use its default
 180         // ahash hashing algorithm but randomize, opting to not randomize when fuzzing to avoid false
 181         // positive branch coverage.
 182
 183         #[cfg(not(feature = "hashbrown"))]
 184         mod std_hashtables {
 185                 pub(crate) use std::collections::{HashMap, HashSet, hash_map};
 186
 187                 pub(crate) type OccupiedHashMapEntry<'a, K, V> =
 188                         std::collections::hash_map::OccupiedEntry<'a, K, V>;
 189                 pub(crate) type VacantHashMapEntry<'a, K, V> =
 190                         std::collections::hash_map::VacantEntry<'a, K, V>;
 191         }
 192         #[cfg(not(feature = "hashbrown"))]
 193         pub(crate) use std_hashtables::*;
 194
 195         #[cfg(feature = "hashbrown")]
 196         pub(crate) use self::hashbrown::hash_map;
 197
 198         #[cfg(all(feature = "hashbrown", fuzzing))]
 199         mod nonrandomized_hashbrown {
 200                 pub(crate) use hashbrown::{HashMap, HashSet};
 201
 202                 pub(crate) type OccupiedHashMapEntry<'a, K, V> =
 203                         hashbrown::hash_map::OccupiedEntry<'a, K, V, hashbrown::hash_map::DefaultHashBuilder>;
 204                 pub(crate) type VacantHashMapEntry<'a, K, V> =
 205                         hashbrown::hash_map::VacantEntry<'a, K, V, hashbrown::hash_map::DefaultHashBuilder>;
 206         }
 207         #[cfg(all(feature = "hashbrown", fuzzing))]
 208         pub(crate) use nonrandomized_hashbrown::*;
 209
 210
 211         #[cfg(all(feature = "hashbrown", not(fuzzing)))]
 212         mod randomized_hashtables {
 213                 use super::*;
 214                 use ahash::RandomState;
 215
 216                 pub(crate) type HashMap<K, V> = hashbrown::HashMap<K, V, RandomState>;
 217                 pub(crate) type HashSet<K> = hashbrown::HashSet<K, RandomState>;
 218
 219                 pub(crate) type OccupiedHashMapEntry<'a, K, V> =
 220                         hashbrown::hash_map::OccupiedEntry<'a, K, V, RandomState>;
 221                 pub(crate) type VacantHashMapEntry<'a, K, V> =
 222                         hashbrown::hash_map::VacantEntry<'a, K, V, RandomState>;
 223
 224                 pub(crate) fn new_hash_map<K, V>() -> HashMap<K, V> {
 225                         HashMap::with_hasher(RandomState::new())
 226                 }
 227                 pub(crate) fn hash_map_with_capacity<K, V>(cap: usize) -> HashMap<K, V> {
 228                         HashMap::with_capacity_and_hasher(cap, RandomState::new())
 229                 }
 230                 pub(crate) fn hash_map_from_iter<K: core::hash::Hash + Eq, V, I: IntoIterator<Item=(K, V)>>(iter: I) -> HashMap<K, V> {
 231                         let iter = iter.into_iter();
 232                         let min_size = iter.size_hint().0;
 233                         let mut res = HashMap::with_capacity_and_hasher(min_size, RandomState::new());
 234                         res.extend(iter);
 235                         res
 236                 }
 237
 238                 pub(crate) fn new_hash_set<K>() -> HashSet<K> {
 239                         HashSet::with_hasher(RandomState::new())
 240                 }
 241                 pub(crate) fn hash_set_with_capacity<K>(cap: usize) -> HashSet<K> {
 242                         HashSet::with_capacity_and_hasher(cap, RandomState::new())
 243                 }
 244                 pub(crate) fn hash_set_from_iter<K: core::hash::Hash + Eq, I: IntoIterator<Item=K>>(iter: I) -> HashSet<K> {
 245                         let iter = iter.into_iter();
 246                         let min_size = iter.size_hint().0;
 247                         let mut res = HashSet::with_capacity_and_hasher(min_size, RandomState::new());
 248                         res.extend(iter);
 249                         res
 250                 }
 251         }
 252
 253         #[cfg(any(not(feature = "hashbrown"), fuzzing))]
 254         mod randomized_hashtables {
 255                 use super::*;
 256
 257                 pub(crate) fn new_hash_map<K, V>() -> HashMap<K, V> { HashMap::new() }
 258                 pub(crate) fn hash_map_with_capacity<K, V>(cap: usize) -> HashMap<K, V> {
 259                         HashMap::with_capacity(cap)
 260                 }
 261                 pub(crate) fn hash_map_from_iter<K: core::hash::Hash + Eq, V, I: IntoIterator<Item=(K, V)>>(iter: I) -> HashMap<K, V> {
 262                         HashMap::from_iter(iter)
 263                 }
 264
 265                 pub(crate) fn new_hash_set<K>() -> HashSet<K> { HashSet::new() }
 266                 pub(crate) fn hash_set_with_capacity<K>(cap: usize) -> HashSet<K> {
 267                         HashSet::with_capacity(cap)
 268                 }
 269                 pub(crate) fn hash_set_from_iter<K: core::hash::Hash + Eq, I: IntoIterator<Item=K>>(iter: I) -> HashSet<K> {
 270                         HashSet::from_iter(iter)
 271                 }
 272         }
 273
 274         pub(crate) use randomized_hashtables::*;
 275 }
 276
 277 #[cfg(all(not(ldk_bench), feature = "backtrace", feature = "std", test))]
 278 extern crate backtrace;
 279
 280 mod sync;