Crate lnsocket

LNSocket

lnsocket is an async Lightning Network socket library implementing the BOLT 8 Noise handshake and typed Lightning wire message framing over TCP, using tokio.

This crate is a minimal, opinionated wrapper around [PeerChannelEncryptor] that:

• Resolves a host:port string into a socket address,
• Opens a TCP connection (no retries or built-in timeouts),
• Completes the three-act Noise handshake (act1, act2, act3),
• Optionally exchanges init messages (LNSocket::perform_init),
• Provides typed read/write helpers for Lightning wire messages.

⚠️ Notes

• Key management is the caller’s responsibility.
• This crate does not handle reconnect logic, backpressure, or keepalives.
• LNSocket::perform_init uses minimal feature negotiation by design.

Related modules

• LNSocket — Low-level Lightning Network TCP + Noise socket
• CommandoClient — Simple client for Core Lightning Commando RPC

Example

use bitcoin::secp256k1::{SecretKey, PublicKey, rand};
use lnsocket::LNSocket;

let our_key = SecretKey::new(&mut rand::thread_rng());
let mut sock = LNSocket::connect_and_init(our_key, their_pubkey, "ln.example.com:9735").await?;
// write/read Lightning wire messages

See CommandoClient for sending RPC calls over the socket.

Re-exports

pub use commando::CommandoClient;

pub use error::Error;

pub use lnsocket::LNSocket;

pub use bitcoin;

Modules

commando

error

ln

lnsocket

Macros

decode_tlv_stream

Implements the TLVs deserialization part in a Readable implementation of a struct.

encode_tlv_stream

Implements the TLVs serialization part in a Writeable implementation of a struct.

impl_writeable_msg

Implements LengthReadable/Writeable for a message struct that may include non-TLV and TLV-encoded parts.

impl_writeable_tlv_based

Implements Readable/Writeable for a struct storing it as a set of TLVs. Each TLV is read/written in the order they appear and contains a type number, a field name, and a de/serialization method, from the following:

impl_writeable_tlv_based_enum

Implement Readable and Writeable for an enum, with struct variants stored as TLVs and tuple variants stored directly.

impl_writeable_tlv_based_enum_upgradable

Implement MaybeReadable and Writeable for an enum, with struct variants stored as TLVs and tuple variants stored directly.

read_tlv_fields

Reads a suffix added by write_tlv_fields.

write_tlv_fields

Writes out a suffix to an object as a length-prefixed TLV stream which contains potentially backwards-compatible, optional fields which old nodes can happily ignore.