Crate lightning_net_tokio

A socket handling library for those running in Tokio environments who wish to use rust-lightning with native TcpStreams.

Designed to be as simple as possible, the high-level usage is almost as simple as “hand over a TcpStream and a reference to a PeerManager and the rest is handled”, except for the Event handling mechanism; see example below.

The PeerHandler, due to the fire-and-forget nature of this logic, must be an Arc, and must use the SocketDescriptor provided here as the PeerHandler’s SocketDescriptor.

Three methods are exposed to register a new connection for handling in tokio::spawn calls; see their individual docs for details.

Example

use std::net::TcpStream;
use bitcoin::secp256k1::PublicKey;
use lightning::util::events::{Event, EventHandler, EventsProvider};
use std::net::SocketAddr;
use std::sync::Arc;

// Define concrete types for our high-level objects:
type TxBroadcaster = dyn lightning::chain::chaininterface::BroadcasterInterface + Send + Sync;
type FeeEstimator = dyn lightning::chain::chaininterface::FeeEstimator + Send + Sync;
type Logger = dyn lightning::util::logger::Logger + Send + Sync;
type ChainAccess = dyn lightning::chain::Access + Send + Sync;
type ChainFilter = dyn lightning::chain::Filter + Send + Sync;
type DataPersister = dyn lightning::chain::chainmonitor::Persist<lightning::chain::keysinterface::InMemorySigner> + Send + Sync;
type ChainMonitor = lightning::chain::chainmonitor::ChainMonitor<lightning::chain::keysinterface::InMemorySigner, Arc<ChainFilter>, Arc<TxBroadcaster>, Arc<FeeEstimator>, Arc<Logger>, Arc<DataPersister>>;
type ChannelManager = Arc<lightning::ln::channelmanager::SimpleArcChannelManager<ChainMonitor, TxBroadcaster, FeeEstimator, Logger>>;
type PeerManager = Arc<lightning::ln::peer_handler::SimpleArcPeerManager<lightning_net_tokio::SocketDescriptor, ChainMonitor, TxBroadcaster, FeeEstimator, ChainAccess, Logger>>;

// Connect to node with pubkey their_node_id at addr:
async fn connect_to_node(peer_manager: PeerManager, chain_monitor: Arc<ChainMonitor>, channel_manager: ChannelManager, their_node_id: PublicKey, addr: SocketAddr) {
	lightning_net_tokio::connect_outbound(peer_manager, their_node_id, addr).await;
	loop {
		let event_handler = |event: &Event| {
			// Handle the event!
		};
		channel_manager.await_persistable_update();
		channel_manager.process_pending_events(&event_handler);
		chain_monitor.process_pending_events(&event_handler);
	}
}

// Begin reading from a newly accepted socket and talk to the peer:
async fn accept_socket(peer_manager: PeerManager, chain_monitor: Arc<ChainMonitor>, channel_manager: ChannelManager, socket: TcpStream) {
	lightning_net_tokio::setup_inbound(peer_manager, socket);
	loop {
		let event_handler = |event: &Event| {
			// Handle the event!
		};
		channel_manager.await_persistable_update();
		channel_manager.process_pending_events(&event_handler);
		chain_monitor.process_pending_events(&event_handler);
	}
}

Structs

SocketDescriptor

The SocketDescriptor used to refer to sockets by a PeerHandler. This is pub only as it is a type in the template of PeerHandler.

Functions

connect_outbound

Process incoming messages and feed outgoing messages on a new connection made to the given socket address which is expected to be accepted by a peer with the given public key (by scheduling futures with tokio::spawn).

setup_inbound

Process incoming messages and feed outgoing messages on the provided socket generated by accepting an incoming connection.

setup_outbound

Process incoming messages and feed outgoing messages on the provided socket generated by making an outbound connection which is expected to be accepted by a peer with the given public key. The relevant processing is set to run free (via tokio::spawn).