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 handlng mechanism, see 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 more. All three take a mpsc::Sender<()> which is sent into every time something occurs which may result in lightning Events. The call site should, thus, look something like this:

use tokio::sync::mpsc;
use std::net::TcpStream;
use bitcoin::secp256k1::key::PublicKey;
use lightning::util::events::EventsProvider;
use std::net::SocketAddr;
use std::sync::Arc;

// Define concrete types for our high-level objects:
type TxBroadcaster = dyn lightning::chain::chaininterface::BroadcasterInterface;
type FeeEstimator = dyn lightning::chain::chaininterface::FeeEstimator;
type Logger = dyn lightning::util::logger::Logger;
type ChainAccess = dyn lightning::chain::Access;
type ChainFilter = dyn lightning::chain::Filter;
type DataPersister = dyn lightning::chain::channelmonitor::Persist<lightning::chain::keysinterface::InMemorySigner>;
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) {
    let (sender, mut receiver) = mpsc::channel(2);
    lightning_net_tokio::connect_outbound(peer_manager, sender, their_node_id, addr).await;
    loop {
        receiver.recv().await;
        for _event in channel_manager.get_and_clear_pending_events().drain(..) {
            // Handle the event!
        }
        for _event in chain_monitor.get_and_clear_pending_events().drain(..) {
            // Handle the event!
        }
    }
}

// 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) {
    let (sender, mut receiver) = mpsc::channel(2);
    lightning_net_tokio::setup_inbound(peer_manager, sender, socket);
    loop {
        receiver.recv().await;
        for _event in channel_manager.get_and_clear_pending_events().drain(..) {
            // Handle the event!
        }
        for _event in chain_monitor.get_and_clear_pending_events().drain(..) {
            // Handle the event!
        }
    }
}

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).