Repository files navigation

Iroh gives you an API for dialing by public key.You say “connect to that phone”, iroh will find & maintain the fastest connection for you, regardless of where it is.

The fastest route is a direct connection, so if necessary, iroh tries to hole-punch.Should this fail, it can fall back to an open ecosystem of public relay servers.To ensure these connections are as fast as possible, wecontinuously measure iroh.

Iroh usesQuinn to establishQUIC connections between nodes.This way you get authenticated encryption, concurrent streams with stream priorities, a datagram transport and avoid head-of-line-blocking out of the box.

Use pre-existing protocols built on iroh instead of writing your own:

• iroh-blobs forBLAKE3-based content-addressed blob transfer scaling from kilobytes to terabytes
• iroh-gossip for establishing publish-subscribe overlay networks that scale, requiring only resources that your average phone can handle
• iroh-docs for an eventually-consistent key-value store ofiroh-blobs blobs
• iroh-willow for an (in-construction) implementation of thewillow protocol

It's easiest to use iroh from rust.Install it usingcargo add iroh, then on the connecting side:

constALPN:&[u8] =b"iroh-example/echo/0";let endpoint =Endpoint::builder().discovery_n0().bind().await?;// Open a connection to the accepting nodelet conn = endpoint.connect(addr,ALPN).await?;// Open a bidirectional QUIC streamlet(mut send,mut recv) = conn.open_bi().await?;// Send some data to be echoedsend.write_all(b"Hello, world!").await?;send.finish()?;// Receive the echolet response = recv.read_to_end(1000).await?;assert_eq!(&response,b"Hello, world!");// As the side receiving the last application data - say goodbyeconn.close(0u32.into(),b"bye!");// Close the endpoint and all its connectionsendpoint.close().await;

And on the accepting side:

let endpoint =Endpoint::builder().discovery_n0().bind().await?;let router =Router::builder(endpoint).accept(ALPN.to_vec(),Arc::new(Echo)).spawn().await?;// The protocol definition:#[derive(Debug,Clone)]structEcho;implProtocolHandlerforEcho{asyncfnaccept(&self,connection:Connection) ->Result<()>{let(mut send,mut recv) = connection.accept_bi().await?;// Echo any bytes received back directly.let bytes_sent = tokio::io::copy(&mut recv,&mut send).await?;        send.finish()?;        connection.closed().await;Ok(())}}

The full example code with more comments can be found atecho.rs.

Or use one of the pre-existing protocols, e.g.iroh-blobs oriroh-gossip.

If you want to use iroh from other languages, make sure to check outiroh-ffi, the repository for FFI bindings.

• Introducing Iroh (video)
• Iroh Documentation
• Iroh Examples
• Iroh Experiments

This repository contains a workspace of crates:

• iroh: The core library for hole-punching & communicating with relays.
• iroh-relay: The relay server implementation. This is the code we run in production (and you can, too!).
• iroh-base: Common types likeHash, key types orRelayUrl.
• iroh-dns-server: DNS server implementation powering then0_discovery for NodeIds, running at dns.iroh.link.
• iroh-net-report: Analyzes your host's networking ability & NAT.

Copyright 2024 N0, INC.

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.