Crate ln_types

Source
Expand description

Warning: while in a good state, this is still considered a preview version! There are some planned changes.

This library aims to provide Rust-idiomatic, ergonomic, and reasonably performant implementation of primitives used in applications interacting with Lightning Network. That means, they are not just types used to implement LN itself, they are supposed to be useful to any application that e.g. communicates with an LN implementation. Of course, they should still be useful for an LN implementation itself.

§Important types

The most important types currently available:

Note: invoice is not here and isn’t planned because it already exists in a separate crate.

§Integrations

The crate aims to be interoperable with other crates via optional dependencies.

§Supported external crates

Ativate using features of the same name.

  • std - enables P2PAddress and implements std::error::Error for error types. Enabled by default, implies `alloc.
  • alloc - enables conversions from/to heap-allocated types as well as additional error information.
  • [bitcoin-units] - converting between types
  • serde - serialization and deserialization of types
  • postgres-types - storing and retrieving from SQL
  • parse_arg - parsing arguments into types in this crate
  • secp256k1 - provides NodePubkey
  • slog - provides slog::Value and (where relevant) slog::KV implementations for the types

Important: some combinations may benefit from additional features! See below.

§Additional features

  • hex-conservative - improves the performance of displaying NodeId/NodePubkey at the cost of additional dependency
  • node_pubkey_verify - convenience function for verifying messages signed with NodePubkey, implies secp256k1/bitcoin_hashes
  • node_pubkey_recovery - convenience function for verifying lightning messages signed with NodePubkey, implies node_pubkey_verify and secp256k1/recovery
  • secp256k1_std - required for node_pubkey::ParseError to return secp256k1::Error from source() method of std::error::Error
  • serde_alloc - required for specialization of serde::de::Visitor::visit_string method to avoid allocation
  • slog_std - required for error types to use [slog::Serializer::emit_error] for logging

Feel free to contribute your own!

Disclaimer: Inclusion of any crate here is neither endorsment nor guarantee of it being secure, honest, non-backdoored or functioning! You’re required to do your own review of any external crate.

The rules around adding a new integration are lax: the dependency must be optional, must not be obviously broken or surprising, and must not interact with other implementations in surprising ways.

§no_std support

This crate works without std or alloc with these limitations/differences:

  • P2PAddress is unavailable without std on Rust versions older than 1.77
  • Resolving a socket address requires std
  • Without std all error types display all sources delimited by : , with std they are returned from the source() method instead.

§Versioning

This crate uses standard Rust Semver with one special exception: Matching on fully private structs is not allowed and so changing an all-private struct to an enum is considered non-breaking change even though the consumer code matching on it would break!

See Rust internals discussion to learn more.

§MSRV

The minimum supported Rust version is 1.56 and will be increased to 1.63 soon. Generally, the intention is to support at least the latest Debian stable.

Note that external libraries may have higher MSRV - this is not considered a breakage.

§License

MIT

Re-exports§

pub extern crate alloc;
pub extern crate bitcoin_units;
pub extern crate parse_arg;
pub extern crate postgres_types_real as postgres_types;
pub extern crate secp256k1;
pub extern crate serde;
pub extern crate slog;
pub extern crate std;
pub use node_id::NodeId;
pub use p2p_address::P2PAddress;std or rust_v_1_77
pub use amount::Amount;
pub use node_pubkey::NodePubkey;secp256k1

Modules§

amount
Bitcoin amount with millisatoshi precision.
node_id
Node identifier (encoded pubkey)
node_pubkeysecp256k1
Newtype over PublicKey and corresponding error types.
p2p_addressstd or rust_v_1_77
P2P address (node_id@host:port)