1 // This file is Copyright its original authors, visible in version control
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
10 #![crate_name = "lightning"]
12 //! Rust-Lightning, not Rusty's Lightning!
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.
21 //! `default` features are:
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))
27 //! Available features are:
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:
34 //! * `max_level_error`
35 //! * `max_level_warn`
36 //! * `max_level_info`
37 //! * `max_level_debug`
38 //! * `max_level_trace`
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))]
43 #![deny(rustdoc::broken_intra_doc_links)]
44 #![deny(rustdoc::private_intra_doc_links)]
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)]
52 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
54 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
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");
59 #[cfg(all(fuzzing, test))]
60 compile_error!("Tests will always fail with cfg=fuzzing");
65 #[cfg(any(test, feature = "std"))]
69 #[cfg(any(test, feature = "_test_utils"))] extern crate regex;
71 #[cfg(not(feature = "std"))] extern crate core2;
72 #[cfg(not(feature = "std"))] extern crate libm;
74 #[cfg(ldk_bench)] extern crate criterion;
83 pub mod onion_message;
87 pub(crate) mod crypto;
89 #[cfg(feature = "std")]
90 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
92 #[cfg(not(feature = "std"))]
93 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
96 #[cfg(not(feature = "std"))]
98 use core2::io::{self, Read, Write};
100 /// A writer which will move data into the void.
105 /// Creates an instance of a writer which will successfully consume all data.
106 pub const fn sink() -> Sink {
110 impl core2::io::Write for Sink {
112 fn write(&mut self, buf: &[u8]) -> core2::io::Result<usize> {
117 fn flush(&mut self) -> core2::io::Result<()> {
122 pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64, io::Error>
128 let mut buf = [0u8; 64];
131 match reader.read(&mut buf) {
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()),
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];
145 match d.read(&mut buf) {
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()),
156 #[cfg(feature = "std")]
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)?;
164 pub use std::io::{copy, sink};
168 #[cfg(feature = "hashbrown")]
169 extern crate hashbrown;
170 #[cfg(feature = "ahash")]
173 pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
175 pub use alloc::borrow::ToOwned;
176 pub use alloc::string::ToString;
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.
183 #[cfg(not(feature = "hashbrown"))]
185 pub(crate) use std::collections::{HashMap, HashSet, hash_map};
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>;
192 #[cfg(not(feature = "hashbrown"))]
193 pub(crate) use std_hashtables::*;
195 #[cfg(feature = "hashbrown")]
196 pub(crate) use self::hashbrown::hash_map;
198 #[cfg(all(feature = "hashbrown", fuzzing))]
199 mod nonrandomized_hashbrown {
200 pub(crate) use hashbrown::{HashMap, HashSet};
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>;
207 #[cfg(all(feature = "hashbrown", fuzzing))]
208 pub(crate) use nonrandomized_hashbrown::*;
211 #[cfg(all(feature = "hashbrown", not(fuzzing)))]
212 mod randomized_hashtables {
214 use ahash::RandomState;
216 pub(crate) type HashMap<K, V> = hashbrown::HashMap<K, V, RandomState>;
217 pub(crate) type HashSet<K> = hashbrown::HashSet<K, RandomState>;
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>;
224 pub(crate) fn new_hash_map<K, V>() -> HashMap<K, V> {
225 HashMap::with_hasher(RandomState::new())
227 pub(crate) fn hash_map_with_capacity<K, V>(cap: usize) -> HashMap<K, V> {
228 HashMap::with_capacity_and_hasher(cap, RandomState::new())
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());
238 pub(crate) fn new_hash_set<K>() -> HashSet<K> {
239 HashSet::with_hasher(RandomState::new())
241 pub(crate) fn hash_set_with_capacity<K>(cap: usize) -> HashSet<K> {
242 HashSet::with_capacity_and_hasher(cap, RandomState::new())
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());
253 #[cfg(any(not(feature = "hashbrown"), fuzzing))]
254 mod randomized_hashtables {
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)
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)
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)
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)
274 pub(crate) use randomized_hashtables::*;
277 #[cfg(all(not(ldk_bench), feature = "backtrace", feature = "std", test))]
278 extern crate backtrace;