Crate cometbft_p2p

Crate cometbft_p2p 

Source
Expand description

§cometbft-p2p

Crate Docs Apache 2.0 Licensed MSRV

Pure Rust implementation of the Secret Connection transport encryption protocol used by CometBFT for peer-to-peer (P2P) connections.

§Features

  • Synchronous SecretConnection implementation for std::io (e.g. TcpStream)
  • AsyncSecretConnection implementation based on tokio
  • Protobuf Message-oriented interface which abstracts away low-level buffering/framing
  • Support for splitting connections into separate readers/writers that can be used concurrently
  • Self-contained with no dependencies on legacy tendermint-rs

§Compatibility

Tested in production with CometBFT v0.37, v0.38, and v1.0.

Should also be compatible with legacy Tendermint versions v0.34+, as well as earlier versions of CometBFT.

§Cryptographic algorithms

The Secret Connection protocol uses the following cryptographic algorithms:

  • Identity: Ed25519
  • Key exchange: X25519
  • Packet encryption: ChaCha20Poly1305

§License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

§Usage

The following example illustrates how to use the SecretConnection type as a TCP client which receives a hypothetical ExampleMessage type which is expected to impl the prost::Message trait:

use std::net::TcpStream;
use cometbft_p2p::{SecretConnection, IdentitySecret, ReadMsg, rand_core::OsRng};

let node_identity = IdentitySecret::generate(&mut OsRng);
let tcp_sock = TcpStream::connect("example.com:26656")?;
let mut conn = SecretConnection::new(tcp_sock, &node_identity)?;

// Verify remote peer ID (optional but highly encouraged)
conn.peer_public_key().peer_id().verify(expected_peer_id)?;

// Read Protobuf message from the remote peer
// (note: you could also write here if initiating a request, see `WriteMsg`)
let msg: ExampleMessage = conn.read_msg()?;

The SecretConnection type (conn) impls the ReadMsg and WriteMsg traits which can be used to receive and send Protobuf messages which impl the prost::Message trait.

§Async usage

Enable the async crate feature to take advantage of the async support in this crate, which is implemented using the Tokio async runtime:

use tokio::net::TcpStream;
use cometbft_p2p::{AsyncSecretConnection, IdentitySecret, AsyncReadMsg, rand_core::OsRng};

let node_identity = IdentitySecret::generate(&mut OsRng);
let tcp_sock = TcpStream::connect("example.com:26656").await?;
let mut conn = AsyncSecretConnection::new(tcp_sock, &node_identity).await?;

// Verify remote peer ID (optional but highly encouraged)
conn.peer_public_key().peer_id().verify(expected_peer_id)?;

// Read Protobuf message from the remote peer
// (note: you could also write here if initiating a request, see `AsyncWriteMsg`)
let msg: ExampleMessage = conn.read_msg().await?;

The AsyncSecretConnection type (conn) impls the AsyncReadMsg and AsyncWriteMsg traits which can be used to asynchronously receive and send Protobuf messages which impl the prost::Message trait.

§Splitting connections

The SecretConnection::split and AsyncSecretConnection::split methods can be used to split a connection into separate read and write halves. This is particularly useful with async to be able to simultaneously read and write to a connection.

Re-exports§

pub use rand_core;

Structs§

AsyncSecretConnectionasync
Encrypted connection between peers in a CometBFT network, implemented using asynchronous I/O provided by the Tokio async runtime.
AsyncSecretReaderasync
Async encrypted message reader type which wraps the read-half of an underlying I/O object.
AsyncSecretWriterasync
Async encrypted message writer type which wraps the write-half of an underlying I/O object.
CryptoError
Opaque type for cryptographic errors which still internally tracks what went wrong for debugging purposes.
PeerId
Secret Connection peer IDs (i.e. key fingerprints)
SecretConnection
Encrypted connection between peers in a CometBFT network.
SecretReader
Encrypted message reader type which wraps the read-half of an underlying I/O object.
SecretWriter
Encrypted message writer type which wraps the write-half of an underlying I/O object.
VerifyPeerError
Peer verification error.

Enums§

Error
Error type
PublicKey
Secret Connection peer identity public keys (signing, presently Ed25519-only)

Constants§

MAX_MSG_LEN
Message size limit which applies to length-delimited messages read via the ReadMsg trait.

Traits§

AsyncReadMsgasync
Read the given Protobuf message from the underlying I/O object (async).
AsyncWriteMsgasync
Write the given Protobuf message to the underlying I/O object (async).
ReadMsg
Read the given Protobuf message from the underlying I/O object.
TryCloneIo
Attempt to clone an I/O object, returning an io::Result.
WriteMsg
Write the given Protobuf message to the underlying I/O object.

Type Aliases§

IdentitySecret
Secret Connection node identity secret keys.
Result
Result type for the cometbft-p2p crate.