Crate lnsocket 

LNSocket

lnsocket is a minimal, async Lightning Network socket library built on tokio. It implements the BOLT 8 Noise handshake and typed Lightning wire framing, and it stays out of your way: no global state, no TLS, no heavy deps.

What this crate gives you

• LNSocket – connect over TCP, perform Noise (act1/2/3), and read/write typed BOLT#1 messages.
• CommandoClient – a small client for Core Lightning Commando over a live LNSocket, with a background pump, auto-reconnect, and retry/resend semantics.

Design philosophy

• Keep the transport tight and explicit. You own key management, policies, and backpressure.
• Avoid surprises: I/O errors return an Error that carries io::ErrorKind only.

Quick starts

Low-level: just a Lightning socket

use bitcoin::secp256k1::{SecretKey, PublicKey, rand};
use lnsocket::{LNSocket, ln::msgs};
let our_key = SecretKey::new(&mut rand::thread_rng());
let mut sock = LNSocket::connect_and_init(our_key, their_pubkey, "node.example.com:9735").await?;
sock.write(&msgs::Ping { ponglen: 4, byteslen: 8 }).await?;
let _msg = sock.read().await?; // e.g. expect a Pong

Higher-level: Commando over LNSocket

use bitcoin::secp256k1::{SecretKey, PublicKey, rand};
use lnsocket::{LNSocket, CommandoClient};
use serde_json::json;
let key = SecretKey::new(&mut rand::thread_rng());
let sock = LNSocket::connect_and_init(key, their_pubkey, "ln.example.com:9735").await?;

// Spawns a background pump task. IDs are generated internally.
let commando = CommandoClient::spawn(sock, rune);

// Simple call with crate defaults (30s timeout, auto-reconnect, retry up to 3 times).
let info = commando.call("getinfo", json!({})).await?;
println!("getinfo: {}", info);

Footguns & non-goals

• No built-in keepalives/backpressure – handle in your app.
• Reconnection logic lives in CommandoClient, not LNSocket.
• LNSocket::perform_init performs a minimal init exchange by design.

Re-exports

pub use commando::CallOpts;

pub use commando::CommandoClient;

pub use error::Error;

pub use error::RpcError;

pub use lnsocket::LNSocket;

pub use bitcoin;

Modules

commando

Commando client over an LNSocket.

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.