]> git.bitcoin.ninja Git - rust-lightning/blob - lightning/src/lib.rs
Merge pull request #1964 from TheBlueMatt/2023-01-no-debug-panics
[rust-lightning] / 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, fuzzing, feature = "_test_utils")), forbid(unsafe_code))]
42
43 // Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
44 #![deny(broken_intra_doc_links)]
45 #![deny(private_intra_doc_links)]
46
47 // In general, rust is absolutely horrid at supporting users doing things like,
48 // for example, compiling Rust code for real environments. Disable useless lints
49 // that don't do anything but annoy us and cant actually ever be resolved.
50 #![allow(bare_trait_objects)]
51 #![allow(ellipsis_inclusive_range_patterns)]
52
53 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
54
55 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
56
57 #![cfg_attr(all(any(test, feature = "_test_utils"), feature = "_bench_unstable"), feature(test))]
58 #[cfg(all(any(test, feature = "_test_utils"), feature = "_bench_unstable"))] extern crate test;
59
60 #[cfg(not(any(feature = "std", feature = "no-std")))]
61 compile_error!("at least one of the `std` or `no-std` features must be enabled");
62
63 #[cfg(all(fuzzing, test))]
64 compile_error!("Tests will always fail with cfg=fuzzing");
65
66 #[macro_use]
67 extern crate alloc;
68 extern crate bitcoin;
69 #[cfg(any(test, feature = "std"))]
70 extern crate core;
71
72 #[cfg(any(test, feature = "_test_utils"))] extern crate hex;
73 #[cfg(any(test, fuzzing, feature = "_test_utils"))] extern crate regex;
74
75 #[cfg(not(feature = "std"))] extern crate core2;
76
77 #[macro_use]
78 pub mod util;
79 pub mod chain;
80 pub mod ln;
81 #[allow(unused)]
82 mod offers;
83 pub mod routing;
84 pub mod onion_message;
85
86 #[cfg(feature = "std")]
87 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
88 pub use std::io;
89 #[cfg(not(feature = "std"))]
90 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
91 pub use core2::io;
92
93 #[cfg(not(feature = "std"))]
94 mod io_extras {
95         use core2::io::{self, Read, Write};
96
97         /// A writer which will move data into the void.
98         pub struct Sink {
99                 _priv: (),
100         }
101
102         /// Creates an instance of a writer which will successfully consume all data.
103         pub const fn sink() -> Sink {
104                 Sink { _priv: () }
105         }
106
107         impl core2::io::Write for Sink {
108                 #[inline]
109                 fn write(&mut self, buf: &[u8]) -> core2::io::Result<usize> {
110                         Ok(buf.len())
111                 }
112
113                 #[inline]
114                 fn flush(&mut self) -> core2::io::Result<()> {
115                         Ok(())
116                 }
117         }
118
119         pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64, io::Error>
120                 where
121                 R: Read,
122                 W: Write,
123         {
124                 let mut count = 0;
125                 let mut buf = [0u8; 64];
126
127                 loop {
128                         match reader.read(&mut buf) {
129                                 Ok(0) => break,
130                                 Ok(n) => { writer.write_all(&buf[0..n])?; count += n as u64; },
131                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
132                                 Err(e) => return Err(e.into()),
133                         };
134                 }
135                 Ok(count)
136         }
137
138         pub fn read_to_end<D: io::Read>(mut d: D) -> Result<alloc::vec::Vec<u8>, io::Error> {
139                 let mut result = vec![];
140                 let mut buf = [0u8; 64];
141                 loop {
142                         match d.read(&mut buf) {
143                                 Ok(0) => break,
144                                 Ok(n) => result.extend_from_slice(&buf[0..n]),
145                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
146                                 Err(e) => return Err(e.into()),
147                         };
148                 }
149                 Ok(result)
150         }
151 }
152
153 #[cfg(feature = "std")]
154 mod io_extras {
155         pub fn read_to_end<D: ::std::io::Read>(mut d: D) -> Result<Vec<u8>, ::std::io::Error> {
156                 let mut buf = Vec::new();
157                 d.read_to_end(&mut buf)?;
158                 Ok(buf)
159         }
160
161         pub use std::io::{copy, sink};
162 }
163
164 mod prelude {
165         #[cfg(feature = "hashbrown")]
166         extern crate hashbrown;
167
168         pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
169         #[cfg(not(feature = "hashbrown"))]
170         pub use std::collections::{HashMap, HashSet, hash_map};
171         #[cfg(feature = "hashbrown")]
172         pub use self::hashbrown::{HashMap, HashSet, hash_map};
173
174         pub use alloc::borrow::ToOwned;
175         pub use alloc::string::ToString;
176 }
177
178 #[cfg(all(not(feature = "_bench_unstable"), feature = "backtrace", feature = "std", test))]
179 extern crate backtrace;
180
181 mod sync;