Quickstart

Let's dive into iroh by building a simple peer-to-peer file transfer tool in rust!

What we'll build

At the end we should be able to transfer a file from one device by running this:

$ cargo run -- send ./file.txt
Indexing file.
File analyzed. Fetch this file by running:
cargo run -- receive blobabvojvy[...] file.txt

And then fetch it on any other device like so:

$ cargo run -- receive blobabvojvy[...] file.txt
Starting download.
Finished download.
Copying to destination.
Finished copying.
Shutting down.

In this guide we'll be omitting the import statements required to get this working. If you're ever confused about what to import, take a look at the imports in the complete example.

Get set up

We'll assume you've set up rust and cargo on your machine.

Initialize a new project by running cargo init file-transfer, then cd file-transfer and install all the packages we're going to use: cargo add iroh iroh-base tokio anyhow && cargo add iroh-blobs --features rpc.

From here on we'll be working inside the src/main.rs file.

Create an iroh::Endpoint

To start interacting with other iroh nodes, we need to build an iroh::Endpoint. This is what manages the possibly changing network underneath, maintains a connection to the closest relay, and finds ways to address devices by NodeId.

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create an endpoint, it allows creating and accepting
    // connections in the iroh p2p world
    let endpoint = Endpoint::builder().discovery_n0().bind().await?;

    // ...

    Ok(())
}

There we go, this is all we need to open connections or accept them.

Using an existing protocol: iroh-blobs

Instead of writing our own protocol from scratch, let's use iroh-blobs, which already does what we want: It loads files from your file system and provides a protocol for seekable, resumable downloads of these files.

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create an endpoint, it allows creating and accepting
    // connections in the iroh p2p world
    let endpoint = Endpoint::builder().discovery_n0().bind().await?;

    // We initialize the Blobs protocol in-memory
    let blobs = Blobs::memory().build(&endpoint);

    // ...

    Ok(())
}

With these two lines, we've initialized iroh-blobs and gave it access to our Endpoint.

This is not quite enough to make it answer requests from the network, for that we need to configure a so-called Router for protocols. Similar to routers in webserver libraries, it runs a loop accepting incoming connections and routes them to the specific handler. However, instead of handlers being organized by HTTP paths, it routes based on "ALPNs". Read more about ALPNs and the router on the protocol and router documentation pages.

Now, using the Router we can finish the skeleton of our application integrating iroh and iroh-blobs:

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create an endpoint, it allows creating and accepting
    // connections in the iroh p2p world
    let endpoint = Endpoint::builder().discovery_n0().bind().await?;

    // We initialize the Blobs protocol in-memory
    let blobs = Blobs::memory().build(&endpoint);

    // Now we build a router that accepts blobs connections & routes them
    // to the blobs protocol.
    let router = Router::builder(endpoint)
        .accept(iroh_blobs::ALPN, blobs.clone())
        .spawn();

    // do *something*

    // Gracefully shut down the router
    println!("Shutting down.");
    router.shutdown().await?;

    Ok(())
}

I've also taken the liberty to make sure that we're gracefully shutting down the Router and all its protocols with it, in this case that's only iroh-blobs.

Doing something

So far, this code works, but doesn't actually do anything besides spinning up a node and immediately shutting down. If we put in a tokio::time::timeout or tokio::signal::ctrl_c().await in there, although it would actually respond to network requests for the blobs protocol, these responses are practically useless as we've stored no blobs to respond with.

Here's our plan for turning this into a CLI that actually does what we set out to build:

1. We'll grab a Blobs::client to interact with the iroh-blobs node we're running locally.
2. We check the CLI arguments to find out whether you ran cargo run -- send [PATH] or cargo run -- receive [TICKET] [PATH].
3. If we're supposed to send data:

• we'll use add_from_path to index local data and make it available,
• print instructions for fetching said file,
• and then wait for Ctrl+C.

4. If we're supposed to receive data:

• we'll parse the ticket out of the CLI arguments,
• download the file using download,
• and copy the result the local file system.

Phew okay! Here's how we'll grab an iroh-blobs client and look at the CLI arguments:

// We use a blobs client to interact with the blobs protocol we're running locally:
let blobs_client = blobs.client();

// Grab all passed in arguments, the first one is the binary itself, so we skip it.
let args: Vec<String> = std::env::args().skip(1).collect();
// Convert to &str, so we can pattern-match easily:
let arg_refs: Vec<&str> = args.iter().map(String::as_str).collect();

match arg_refs.as_slice() {
    ["send", filename] => {
        todo!();
    }
    ["receive", ticket, filename] => {
        todo!();
    }
    _ => {
        println!("Couldn't parse command line arguments: {args:?}");
        println!("Usage:");
        println!("    # to send:");
        println!("    cargo run --example transfer -- send [FILE]");
        println!("    # this will print a ticket.");
        println!();
        println!("    # to receive:");
        println!("    cargo run --example transfer -- receive [TICKET] [FILE]");
    }
}

Now all we need to do is fill in the todo!()s one-by-one:

Getting ready to send

If we want to make a file available over the network with iroh-blobs, we first need to hash this file.

let filename: PathBuf = filename.parse()?;
let abs_path = std::path::absolute(&filename)?;

println!("Hashing file.");

// keep the file in place and link it, instead of copying it into the in-memory blobs database
let in_place = true;
let blob = blobs_client
    .add_from_path(abs_path, in_place, SetTagOption::Auto, WrapOption::NoWrap)
    .await?
    .finish()
    .await?;

The WrapOption::NoWrap is just an indicator that we don't want to wrap the file with some metadata information about its file name. We keep it simple here for now!

Now, we'll print a BlobTicket. This ticket contains the NodeId of our Endpoint as well as the file's BLAKE3 hash.

let node_id = router.endpoint().node_id();
let ticket = BlobTicket::new(node_id.into(), blob.hash, blob.format)?;

println!("File hashed. Fetch this file by running:");
println!("cargo run --example transfer -- receive {ticket} {path}");

tokio::signal::ctrl_c().await?;

And as you can see, as a final step we wait for the user to stop the file providing side by hitting Ctrl+C in the console.

Connecting to the other side to receive

On the connection side, we got the ticket and the path from the CLI arguments and we can parse them into their struct versions.

With them parsed, we can call blobs.download with the information contained in the ticket and wait for the download to finish:

let filename: PathBuf = filename.parse()?;
let abs_path = std::path::absolute(filename)?;
let ticket: BlobTicket = ticket.parse()?;

println!("Starting download.");

blobs_client
    .download(ticket.hash(), ticket.node_addr().clone())
    .await?
    .finish()
    .await?;

println!("Finished download.");

As a final step, we'll export the file we just downloaded into our blobs database to the desired file path:

println!("Copying to destination.");

blobs_client
    .export(
        ticket.hash(),
        abs_path,
        ExportFormat::Blob,
        ExportMode::Copy,
    )
    .await?
    .finish()
    .await?;

println!("Finished copying.");

That's it!

You've now successfully built a small tool for peer-to-peer file transfers! 🎉

The full example with the very latest version of iroh and iroh-blobs can be viewed on github.

If you're hungry for more, check out

• the iroh rust documentation,
• other examples, or
• other available protocols.