lightning/
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
32#![cfg_attr(not(any(test, fuzzing, feature = "_test_utils")), deny(missing_docs))]
33#![cfg_attr(not(any(test, feature = "_test_utils")), forbid(unsafe_code))]
34
35#![deny(rustdoc::broken_intra_doc_links)]
36#![deny(rustdoc::private_intra_doc_links)]
37
38// In general, rust is absolutely horrid at supporting users doing things like,
39// for example, compiling Rust code for real environments. Disable useless lints
40// that don't do anything but annoy us and cant actually ever be resolved.
41#![allow(bare_trait_objects)]
42#![allow(ellipsis_inclusive_range_patterns)]
43
44#![cfg_attr(docsrs, feature(doc_auto_cfg))]
45
46#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
47
48#[cfg(all(fuzzing, test))]
49compile_error!("Tests will always fail with cfg=fuzzing");
50
51#[macro_use]
52extern crate alloc;
53
54pub extern crate lightning_types as types;
55
56pub extern crate bitcoin;
57
58pub extern crate lightning_invoice as bolt11_invoice;
59
60#[cfg(any(test, feature = "std"))]
61extern crate core;
62
63#[cfg(any(test, feature = "_test_utils"))] extern crate regex;
64
65#[cfg(not(feature = "std"))] extern crate libm;
66
67#[cfg(ldk_bench)] extern crate criterion;
68
69#[cfg(all(feature = "std", test))] extern crate parking_lot;
70
71#[macro_use]
72pub mod util;
73pub mod chain;
74pub mod ln;
75pub mod offers;
76pub mod routing;
77pub mod sign;
78pub mod onion_message;
79pub mod blinded_path;
80pub mod events;
81
82pub(crate) mod crypto;
83
84/// Extension of the bitcoin::io module
85pub mod io;
86
87#[doc(hidden)]
88/// IO utilities public only for use by in-crate macros. These should not be used externally
89///
90/// This is not exported to bindings users as it is not intended for public consumption.
91pub mod io_extras {
92	use bitcoin::io::{self, Read, Write};
93
94	/// Creates an instance of a writer which will successfully consume all data.
95	pub use bitcoin::io::sink;
96
97	pub fn copy<R: ?Sized, W: ?Sized>(reader: &mut R, writer: &mut W) -> Result<u64, io::Error>
98		where
99		R: Read,
100		W: Write,
101	{
102		let mut count = 0;
103		let mut buf = [0u8; 64];
104
105		loop {
106			match reader.read(&mut buf) {
107				Ok(0) => break,
108				Ok(n) => { writer.write_all(&buf[0..n])?; count += n as u64; },
109				Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
110				Err(e) => return Err(e.into()),
111			};
112		}
113		Ok(count)
114	}
115
116	pub fn read_to_end<D: Read>(d: &mut D) -> Result<alloc::vec::Vec<u8>, io::Error> {
117		let mut result = vec![];
118		let mut buf = [0u8; 64];
119		loop {
120			match d.read(&mut buf) {
121				Ok(0) => break,
122				Ok(n) => result.extend_from_slice(&buf[0..n]),
123				Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {},
124				Err(e) => return Err(e.into()),
125			};
126		}
127		Ok(result)
128	}
129}
130
131mod prelude {
132	#![allow(unused_imports)]
133
134	pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
135
136	pub use alloc::borrow::ToOwned;
137	pub use alloc::string::ToString;
138
139	pub use core::convert::{AsMut, AsRef, TryFrom, TryInto};
140	pub use core::default::Default;
141	pub use core::marker::Sized;
142
143	pub(crate) use crate::util::hash_tables::*;
144}
145
146#[cfg(all(not(ldk_bench), feature = "backtrace", feature = "std", test))]
147extern crate backtrace;
148
149mod sync;