Skip to content
The Interplanetary File System (IPFS), implemented in Rust
Rust
Branch: master
Clone or download

README.md


Rust IPFS

The Interplanetary File System (IPFS), implemented in Rust

standard-readme compliant Back on OpenCollective Matrix Discord

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

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.0 - Complete

  • Project Setup
  • Testing Setup
    • Conformance testing
    • Interop testing
  • HTTP API Scaffolding

Devgrant Phase 1.1 - Complete

  • Blockstore implementation
  • /pubsub
  • /swarm
  • /version
  • /id

Devgrant Phase 1.2 - In Progress

  • Bitswap updates
  • /block
  • /dag
  • /refs
  • /bitswap

Work not covered by the grant

  • /object
  • /pin
  • /bootstrap
  • /dht
  • /name
  • /ping
  • /key
  • /config
  • /stats
  • /files (regular and mfs)
  • a few othrer miscellaneous endpoints as well 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).

You can’t perform that action at this time.