update

Author: okdistribute

connecting/creating-endpoint.mdx

@@ -1,7 +1,11 @@
 ---
-title: "Creating an endpoint"
+title: "Creating an Endpoint"
 ---
 
+An endpoint is the core building block of an iroh node. It manages network
+connections, handles incoming and outgoing traffic, and provides the necessary
+infrastructure for implementing protocols.
+
 To create an endpoint in Iroh, you can use the `Endpoint::bind` method. This
 method initializes a new endpoint and binds it to a local address, allowing it
 to listen for incoming connections.
@@ -17,10 +21,9 @@ async fn main() {
 ```
 
 
-Breaking that down, `bind` creates the endpoint and starts listening for
-incoming connections, while the `await` keyword is used to wait for the endpoint
+1. `bind` creates the endpoint and starts listening for
+incoming connections
+2. `await` keyword is used to wait for the endpoint
 to be created in an asynchronous context.
-
-
-Once you have an endpoint, you can use it to create connections to other
-endpoints, or accept incoming connections from other endpoints.
+3. Once you have an endpoint, you can use it to create connections to other
+endpoints, or accept incoming connections from other endpoints.

connecting/dht-discovery.mdx

@@ -0,0 +1,26 @@
+---
+title: "DHT"
+---
+
+Discovery via DHT in iroh uses the [BitTorrent Mainline](https://en.wikipedia.org/wiki/Mainline_DHT) distributed hash table (DHT) to publish & resolve EndpointIds.
+
+DHT Discovery is _not_ enabled by default, and must be enabled by the user. You'll need to add the `discovery-pkarr-dht` feature flag to your `Cargo.toml` to use it.
+
+```toml
+[dependencies]
+# Make sure to use the most recent version here instead of nn. (at the time of writing: 0.32)
+iroh = { version = "0.nn", features = ["discovery-pkarr-dht"] }
+```
+
+Then configure your endpoint to use DHT discovery concurrently with mDNS discovery, but not with the default DNS discovery, use the `Endpoint::empty_builder` method. This requires specifying a `RelayMode`, which in this example we will keep default.
+
+```rust
+use iroh::Endpoint;
+
+let dht_discovery = iroh::discovery::dht::DhtDiscovery::builder();
+let mdns = iroh::discovery::mdns::MdnsDiscovery::builder();
+let ep = Endpoint::empty_builder(iroh::RelayMode::Default)
+    .discovery(dnt_discovery)
+    .bind()
+    .await?;
+```

connecting/dns-discovery.mdx

@@ -0,0 +1,48 @@
+---
+title: "DNS"
+---
+
+By Default, iroh uses the DNS discovery system to find other peers with a given EndpointId. 
+
+iroh will use a standard DNS server to publish and resolve EndpointIds to their
+home relay addresses. This allows any iroh endpoint to be discoverable globally,
+as long as they are connected to the same relay that is reachable from the public
+internet.
+
+```rust
+use iroh::Endpoint;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let endpoint = Endpoint::bind().await?;
+
+    println!("endpoint id: {:?}", endpoint.id());
+    Ok(())
+}
+```
+
+TODO: example of looking up another endpoint via dns
+
+## Dedicated DNS Server
+
+By default, iroh will look up the endpoint on a public shared instance of the
+DNS discovery server. If you'd like to run your own private DNS discovery server
+for more guaranteed privacy and uptime guarantees, you can configure iroh to use
+it.
+
+
+TODO: rust code for custom dns server
+
+## Important notes 
+
+1. DNS discovery is the default discovery mechanism in iroh, so you don't need
+   to do anything special to enable it.
+2. DNS discovery only publishes the home relay of an endpoint, not its direct
+   addresses. 
+3. DNS discovery is opt-out, so if you don't want your endpoint to be
+   discoverable via DNS, you can disable it by using the
+   `Endpoint::empty_builder` method instead of `Endpoint::builder`.
+4. Two nodes must connect to the same DNS discovery server to find each other using DNS discovery.
+
+
+

connecting/global-discovery.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Broadcast via gossip topics"
+title: "Gossip Broadcast"
 ---
 
 Gossip protocols let peers broadcast messages to subscribers of a topic

connecting/gossip.mdx

@@ -1,16 +1,15 @@
 ---
-title: "Local discovery"
+title: "mDNS and Bluetooth"
 ---
 
-Placeholder: Using mDNS for local peer discovery and network config notes.
+Local discovery adds the ability to use physical radios to discover other iroh
+endpoints. This is useful for local networks where the internet may not be available or reliable.
 
+Local connections can be faster and more reliable than internet-based connections, especially in
+environments with poor connectivity. They also enhance privacy by keeping communications within a local area.
 
 ## mDNS
 
-Local discovery adds the ability to scan local networks for other iroh
-endpoints, using Local Swarm Discovery. This is useful for local networks, or
-for bootstrapping a network before a relay is available.
-
 Local Discovery is _not_ enabled by default, and must be enabled by the user.
 You'll need to add the `discovery-local-network` feature flag to your
 `Cargo.toml` to use it.
@@ -34,4 +33,7 @@ let ep = Endpoint::builder()
 ```
 
 
-## Bluetooth, and P2P WiFi
+## Bluetooth
+
+Bluetooth discovery is currently under development and will be available in a
+future release of iroh. For more information, please [contact us](https://cal.com/team/number-0/n0-protocol-services).

connecting/local-discovery.mdx

@@ -20,6 +20,7 @@
               "quickstart",
             {
               "group": "Concepts",
+              "expanded": true,
               "pages": [
                 "concepts/endpoints",
                 "concepts/discovery",
@@ -31,10 +32,11 @@
             ]
           },
           {
-            "group": "Connecting Peers",
+            "group": "Forming a Network",
             "pages": [
               "connecting/creating-endpoint",
-              "connecting/global-discovery",
+              "connecting/dns-discovery",
+              "connecting/dht-discovery",
               "connecting/local-discovery",
               "connecting/gossip"
             ]