docs: Fill in the iroh-net README a little

* iroh-net readme language tweaks, add links, examples section (#1253) Co-authored-by: b5 <sparkle_pony_2000@qri.io>
n0-computer · Jul 17, 2023 · c5e4c1b · c5e4c1b
1 parent f9a49c5
commit c5e4c1b
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 1 deletion.
diff --git a/iroh-net/Cargo.toml b/iroh-net/Cargo.toml
@@ -3,7 +3,7 @@ name = "iroh-net"
 version = "0.4.1"
 edition = "2021"
 readme = "README.md"
-description = "IPFS reimagined"
+description = "networking support for iroh"
 license = "MIT/Apache-2.0"
 authors = ["dignifiedquire <me@dignifiedquire.com>", "n0 team"]
 repository = "/~https://github.com/n0-computer/iroh"

diff --git a/iroh-net/README.md b/iroh-net/README.md
@@ -1,5 +1,16 @@
 # iroh-net
 
+This crate contains the networking support for iroh. Iroh networking is built on direct peer-to-peer [QUIC](https://en.wikipedia.org/wiki/QUIC) connections that use relays and holepunching. The main structure for connection is the `MagicEndpoint` entrypoint.
+
+Peer to peer connectivity is established with the help of a _DERP server_ or _derper_. The DERP server provides Session Traversal Utilities for NAT [(STUN)](https://en.wikipedia.org/wiki/STUN) for the peers and connection coordination using the [DERP protocol](https://pkg.go.dev/tailscale.com/derp) (Designated Relay for Encrypted Packets protocol). If no direct connection can be established, the connection is relayed via the DERP server.
+
+Peers must know and do verify the PeerID of each other before they can connect. When using a DERP server to aid the connection establishment they will register with a home DERP server using their PeerId.  Other peers which can not establish a direct connection can then establish connection via this DERP server.  This will try to assist establishing a direct connection using STUN and holepunching but continue relaying if not possible.
+
+Peers can also connect directly without using a DERP server. For this, however the listening peer must be directly reachable by the connecting peer via one of it's addresses.
+
+## Examples
+
+Examples for `iroh-net` are in `iroh-net/examples`, run them with `cargo run --example $NAME`. Details for each example are in the file/directory itself.
 
 # License