git.bitcoin.ninja 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, 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 pub mod routing;
  82 pub mod onion_message;
  83
  84 #[cfg(feature = "std")]
  85 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
  86 pub use std::io;
  87 #[cfg(not(feature = "std"))]
  88 /// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
  89 pub use core2::io;
  90
  91 #[cfg(not(feature = "std"))]
  92 mod io_extras {
  93         use core2::io::{self, Read, Write};
  94
  95         /// A writer which will move data into the void.
  96         pub struct Sink {
  97                 _priv: (),
  98         }
  99
 100         /// Creates an instance of a writer which will successfully consume all data.
 101         pub const fn sink() -> Sink {
 102                 Sink { _priv: () }
 103         }
 104
 105         impl core2::io::Write for Sink {
 106                 #[inline]
 107                 fn write(&mut self, buf: &[u8]) -> core2::io::Result<usize> {
 108                         Ok(buf.len())
 109                 }
 110
 111                 #[inline]
 112                 fn flush(&mut self) -> core2::io::Result<()> {
 113                         Ok(())
 114                 }
 115         }
 116
 117         pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64, io::Error>
 118                 where
 119                 R: Read,
 120                 W: Write,
 121         {
 122                 let mut count = 0;
 123                 let mut buf = [0u8; 64];
 124
 125                 loop {
 126                         match reader.read(&mut buf) {
 127                                 Ok(0) => break,
 128                                 Ok(n) => { writer.write_all(&buf[0..n])?; count += n as u64; },
 129                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
 130                                 Err(e) => return Err(e.into()),
 131                         };
 132                 }
 133                 Ok(count)
 134         }
 135
 136         pub fn read_to_end<D: io::Read>(mut d: D) -> Result<alloc::vec::Vec<u8>, io::Error> {
 137                 let mut result = vec![];
 138                 let mut buf = [0u8; 64];
 139                 loop {
 140                         match d.read(&mut buf) {
 141                                 Ok(0) => break,
 142                                 Ok(n) => result.extend_from_slice(&buf[0..n]),
 143                                 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
 144                                 Err(e) => return Err(e.into()),
 145                         };
 146                 }
 147                 Ok(result)
 148         }
 149 }
 150
 151 #[cfg(feature = "std")]
 152 mod io_extras {
 153         pub fn read_to_end<D: ::std::io::Read>(mut d: D) -> Result<Vec<u8>, ::std::io::Error> {
 154                 let mut buf = Vec::new();
 155                 d.read_to_end(&mut buf)?;
 156                 Ok(buf)
 157         }
 158
 159         pub use std::io::{copy, sink};
 160 }
 161
 162 mod prelude {
 163         #[cfg(feature = "hashbrown")]
 164         extern crate hashbrown;
 165
 166         pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
 167         #[cfg(not(feature = "hashbrown"))]
 168         pub use std::collections::{HashMap, HashSet, hash_map};
 169         #[cfg(feature = "hashbrown")]
 170         pub use self::hashbrown::{HashMap, HashSet, hash_map};
 171
 172         pub use alloc::borrow::ToOwned;
 173         pub use alloc::string::ToString;
 174 }
 175
 176 #[cfg(all(not(feature = "_bench_unstable"), feature = "std", test))]
 177 mod debug_sync;
 178 #[cfg(all(not(feature = "_bench_unstable"), feature = "backtrace", feature = "std", test))]
 179 extern crate backtrace;
 180
 181 #[cfg(feature = "std")]
 182 mod sync {
 183         #[cfg(all(not(feature = "_bench_unstable"), test))]
 184         pub use crate::debug_sync::*;
 185         #[cfg(any(feature = "_bench_unstable", not(test)))]
 186         pub use ::std::sync::{Arc, Mutex, Condvar, MutexGuard, RwLock, RwLockReadGuard, RwLockWriteGuard};
 187         #[cfg(any(feature = "_bench_unstable", not(test)))]
 188         pub use crate::util::fairrwlock::FairRwLock;
 189 }
 190
 191 #[cfg(not(feature = "std"))]
 192 mod sync;