aboutsummaryrefslogtreecommitdiff
path: root/p2p
diff options
context:
space:
mode:
Diffstat (limited to 'p2p')
-rw-r--r--p2p/README.md133
1 files changed, 133 insertions, 0 deletions
diff --git a/p2p/README.md b/p2p/README.md
new file mode 100644
index 0000000..6db3f19
--- /dev/null
+++ b/p2p/README.md
@@ -0,0 +1,133 @@
+# karyons p2p
+
+karyons p2p serves as the foundational stack for the karyons project. It
+offers a modular, lightweight, and customizable p2p network stack that
+seamlessly integrates with any p2p project.
+
+## Architecture
+
+### Discovery
+
+karyons p2p uses a customized version of the Kademlia for discovering new peers
+in the network. This approach is based on Kademlia but with several significant
+differences and optimizations. Some of the main changes:
+
+1. karyons p2p uses TCP for the lookup process, while UDP is used for
+ validating and refreshing the routing table. The reason for this choice is
+ that the lookup process is infrequent, and the work required to manage
+ messages with UDP is largely equivalent to using TCP for this purpose.
+ However, for the periodic and efficient sending of numerous Ping messages to
+ the entries in the routing table during refreshing, it makes sense to
+ use UDP.
+
+2. In contrast to traditional Kademlia, which often employs 160 buckets,
+ karyons p2p reduces the number of buckets to 32. This optimization is a
+ result of the observation that most nodes tend to map into the last few
+ buckets, with the majority of other buckets remaining empty.
+
+3. While Kademlia typically uses a 160-bit key to identify a peer, karyons p2p
+ uses a 256-bit key.
+
+> Despite criticisms of Kademlia's vulnerabilities, particularly concerning
+> Sybil and Eclipse attacks [[1]](https://eprint.iacr.org/2018/236.pdf)
+> [[2]](https://arxiv.org/abs/1908.10141), we chose to use Kademlia because our
+> main goal is to build an infrastructure focused on sharing data. This choice
+> may also assist us in supporting sharding in the future. However, we have made
+> efforts to mitigate most of its vulnerabilities. Several projects, including
+> BitTorrent, Ethereum, IPFS, and Storj, still rely on Kademlia.
+
+### Peer IDs
+
+Peers in the karyons p2p network are identified by their 256-bit (32-byte) Peer IDs.
+
+### Seeding
+
+At the network's initiation, the client populates the routing table with peers
+closest to its key(PeerID) through a seeding process. Once this process is
+complete, and the routing table is filled, the client selects a random peer
+from the routing table and establishes an outbound connection. This process
+continues until all outbound slots are occupied.
+
+The client can optionally provide a listening endpoint to accept inbound
+connections.
+
+### Handshake
+
+When an inbound or outbound connection is established, the client initiates a
+handshake with that connection. If the handshake is successful, the connection
+is added to the PeerPool.
+
+### Protocols
+
+In the karyons p2p network, we have two types of protocols: core protocols and
+custom protocols. Core protocols are prebuilt into karyons p2p, such as the
+Ping protocol used to maintain connections. Custom protocols, on the other
+hand, are protocols that you define for your application to provide its core
+functionality.
+
+Here's an example of a custom protocol:
+
+```rust
+pub struct NewProtocol {
+ peer: ArcPeer,
+}
+
+impl NewProtocol {
+ fn new(peer: ArcPeer) -> ArcProtocol {
+ Arc::new(Self {
+ peer,
+ })
+ }
+}
+
+#[async_trait]
+impl Protocol for NewProtocol {
+ async fn start(self: Arc<Self>, ex: Arc<Executor<'_>>) -> Result<(), P2pError> {
+ let listener = self.peer.register_listener::<Self>().await;
+ loop {
+ let event = listener.recv().await.unwrap();
+
+ match event {
+ ProtocolEvent::Message(msg) => {
+ println!("{:?}", msg);
+ }
+ ProtocolEvent::Shutdown => {
+ break;
+ }
+ }
+ }
+
+ listener.cancel().await;
+ Ok(())
+ }
+
+ fn version() -> Result<Version, P2pError> {
+ "0.2.0, >0.1.0".parse()
+ }
+
+ fn id() -> ProtocolID {
+ "NEWPROTOCOLID".into()
+ }
+}
+
+```
+
+Whenever a new peer is added to the PeerPool, all the protocols, including
+your custom protocols, will automatically start running with the newly connected peer.
+
+## Network Security
+
+It's obvious that connections in karyons p2p are not secure at the moment, as
+it currently only supports TCP connections. However, we are currently working
+on adding support for TLS connections.
+
+## Usage
+
+You can check out the examples [here](./examples).
+
+If you have tmux installed, you can run the network simulation script in the
+examples directory to run 12 peers simultaneously.
+
+```bash
+$ RUST_LOG=karyons=debug ./net_simulation.sh
+```