Rust IPFS

The Interplanetary File System (IPFS), implemented in Rust

Description

This repository contains the crates for the IPFS core implementation which includes a blockstore, libp2p integration, and HTTP API bindings. Our goal is to leverage both the unique properties of Rust to create powerful, performant software that works even in resource-constrained environments while maximizing interoperability with the other "flavors" of IPFS, namely JavaScript and Go.

Project Status - Pre-Alpha

There's a lot of great work in here, and a lot more coming that isn't implemented yet. Recently, this project was awarded a dev grant from Protocol Labs, empowering us to raise our level of conformance. After the grant work is complete the project will achieve alpha stage.

You can help.

PRs and Issues accepted for any of the following. See the contributing docs for more info.

• Implement endpoints not covered by the devgrant proposal. See the roadmap section below
• Back the project financially by reaching out or by becoming a backer on OpenCollective

What is IPFS?

IPFS is a global, versioned, peer-to-peer filesystem. It combines good ideas from previous systems such Git, BitTorrent, Kademlia, SFS, and the Web. It is like a single bittorrent swarm, exchanging git objects. IPFS provides an interface as simple as the HTTP web, but with permanence built in. You can also mount the world at /ipfs.

For more info see: https://docs.ipfs.io/introduction/overview/

Table of Contents

• Description
  • Project Status
  • You can help
  • What is IPFS?
• Install
• Getting Started
• Roadmap
• Maintainers
• License
• Trademarks

Install

The rust-ipfs binaries can be built from source. Our goal is to always be compatible with the stable release of Rust.

$ git clone https://github.com/ipfs-rust/rust-ipfs && cd rust-ipfs
$ cargo build --workspace

You will then find the binaries inside of the project root's /target/debug folder.

Note: binaries available via cargo install is coming soon.

Getting started

use async_std::task;
use futures::join;
use ipfs::{IpfsOptions, IpfsPath, Ipld, Types, UninitializedIpfs};
use libipld::ipld;

fn main() {
    env_logger::init();
    let options = IpfsOptions::<Types>::default();

    task::block_on(async move {
        // Start daemon and initialize repo
        let (ipfs, fut) = UninitializedIpfs::new(options).await.start().await.unwrap();
        task::spawn(fut);

        // Create a DAG
        let f1 = ipfs.put_dag(ipld!("block1"));
        let f2 = ipfs.put_dag(ipld!("block2"));
        let (res1, res2) = join!(f1, f2);
        let root = ipld!([res1.unwrap(), res2.unwrap()]);
        let cid = ipfs.put_dag(root).await.unwrap();
        let path = IpfsPath::from(cid);

        // Query the DAG
        let path1 = path.sub_path("0").unwrap();
        let path2 = path.sub_path("1").unwrap();
        let f1 = ipfs.get_dag(path1);
        let f2 = ipfs.get_dag(path2);
        let (res1, res2) = join!(f1, f2);
        println!("Received block with contents: {:?}", res1.unwrap());
        println!("Received block with contents: {:?}", res2.unwrap());

        // Exit
        ipfs.exit_daemon();
    });
}

More usage examples coming soon 👍

Roadmap

A large portion of this work is covered by an IPFS Devgrant from Protocol Labs. In the proposal, we discussed using implemented HTTP API endpoints as a metric to determine progress. There are always opportunities for community members to contribute by helping out with endpoints not covered in the grant.

Devgrant Phase 1 - Complete

• Project Setup
• Testing Setup
  • Conformance testing
• HTTP API Scaffolding
• /pubsub/{ publish, subscribe, unsubscribe, peers, ls }
• /swarm/{connect, peers, addrs, localAddrs, disconnect }
• /id
• /version
• /stop
• /block/{ get, add, rm, stat }
• /dag/{ put, resolve }
• /refs and /refs/local
• /bitswap/{ stat, wantlist }

Work still required (APIs)

• Interop testing
• /pin
• /bootstrap
• /dht
• /name
• /ping
• /key
• /config
• /stats
• /files (regular and mfs)
• a few other miscellaneous endpoints not enumerated here

Maintainers

Rust IPFS is currently actively maintained by @dvc94ch, @koivunej, and @aphelionz. Special thanks is given to Protocol Labs, Equilibrium Labs, and MRH.io.

License

Dual licensed under MIT or Apache License (Version 2.0). See LICENSE-MIT and LICENSE-APACHE for more details.

Trademarks

The Rust logo and wordmark are trademarks owned and protected by the Mozilla Foundation. The Rust and Cargo logos (bitmap and vector) are owned by Mozilla and distributed under the terms of the Creative Commons Attribution license (CC-BY).