Crate peerlink

Peerlink

Peerlink is a low-level network client for Bitcoin. It is designed to abstract away and hide networking logic and allow the consumer to focus on communicating with other peers on the network. Message streaming, buffering and basic peer management is handled by the library.

The way to use this crate is to create a Reactor instance, acquire its messaging handle and let the reactor run on its own thread. The API consumer then communicates with the reactor using a Handle instance.

User Agent Handling

While Peerlink does not enforce any particular user agent string format when sending out version messages, please use the user_agent function in the crate root to create a well formatted BIP0014 UA string. Doing so ensures that Peerlink is identifying itself properly to the network.

Example

The following example covers connecting to a Bitcoin node running on localhost, sending a message and then shutting down the reactor.

let config = peerlink::Config {
    // empty vec means we aren't listening for inbound connections
    bind_addr: vec![],
    ..Default::default()
};

let (reactor, handle) = peerlink::Reactor::new(config)?;

// start the reactor (spawns its own thread)
let reactor_join_handle = reactor.run();

// issue a command to connect to our peer
handle.send(peerlink::Command::Connect("127.0.0.1:8333".parse().unwrap()))?;

// expect a `ConnectedTo` event if everything went well
let peer = match handle.receive()? {
    peerlink::Event::ConnectedTo { addr, result: Ok(peer)} => {
        println!("Connected to peer {} at address {}", peer, addr);
        peer
    }
    _ => panic!("not interested in other messages yet"),
};

// send a message to the peer and perform other operations...
handle.send(peerlink::Command::Message(peer, RawNetworkMessage {magic: todo!(), payload: todo!()}))?;

// When done, shut down the reactor and join with its thread
handle.send(peerlink::Command::Shutdown)?;  
let _ = reactor_join_handle.join();

Re-exports

• pub use bitcoin;
• pub use reactor::Command;
• pub use reactor::Connector;
• pub use reactor::Event;
• pub use reactor::Reactor;

Modules

• reactor

Structs

• Config
  Configuration parameters for the reactor.
• PeerId
  Unique peer identifier. These are unique for the lifetime of the process and strictly incrementing for each new connection. Even if the same peer (in terms of socket address) connects multiple times, a new PeerId instance will be issued for each connection.
• StreamConfig
  Stream related configuration parameters.
• TcpStream
  A non-blocking TCP stream between a local socket and a remote socket.

Functions

• user_agent
  Creates a well formed BIP0014 user agent string that should be used with version messages. For instance, if app_name is supernode and app_version is 0.6.5 and the version of Peerlink being used is 0.4.0, the resulting string will be /peerlink:0.4.0/supernode:0.6.5/.