!!! Attention: This is a continuation of the IOTA Streams library for use in the Digital MRV ecosystem, and is not fully compatible with existing stardust implementations with IOTA nodes

A cryptographic framework for building secure messaging protocols

About ◈ Prerequisites ◈ Installation ◈ Getting started ◈ API reference ◈ Examples ◈ Supporting the project

---

About

Streams is a work-in-progress framework for building cryptographic messaging protocols. Streams ships with a built-in protocol for sending authenticated messages between two or more parties on a DAG network (like the IOTA Tangle).

At the moment, IOTA Streams includes the following crates:

• Application Logic featuring User and high level messaging logic.
• Spongos featuring data definition and manipulation language for protocol messages;
• LETS featuring the building blocks for application logic, including low level messaging logic.
• C Bindings.

Prerequisites

To use IOTA Streams, you need the following:

• Rust
• (Optional) An IDE that supports Rust autocompletion. We recommend Visual Studio Code with the rust-analyzer extension

We also recommend updating Rust to the latest stable version:

rustup update stable

Installation

To use the library in your crate you need to add it as a dependency in the Cargo.toml file.

Because the library is not on crates.io, you need to use the Git repository either remotely or locally.

no_std is currently supported for standard seed based Users, but not if the did feature is enabled. Cargo nightly must be used to build with no_std feature.

Getting started

If you don't have a rust project setup yet you can create one by running,

cargo new my-library

Remote Add the following to your Cargo.toml file:

[dependencies]
anyhow = { version = "1.0", default-features = false }
iota-streams = { git = "https://github.com/Immutable-Futures/streams", branch  = "develop"}

Local

1. Clone this repository

   git clone https://github.com/iotaledger/streams

2. Add the following to your Cargo.toml file:

   [dependencies]
   iota-streams = { version = "0.2.1", path = "../streams" }

Getting started

After you've installed the library, you can use it in your own Cargo project.

For example, you may want to use the application protocol to create a new user like so:

use streams::{
    transport::utangle,
    id::Ed25519,
    User
};

#[tokio::main] 
async fn main() {
   let node = "http://localhost:14265";
   let transport = utangle::Client::new(node);
   let mut author = User::builder()
     .with_identity(Ed25519::from_seed("A cryptographically secure seed"))
     .with_transport(transport)
     .build();

   // A new stream, or branch within a stream will require a Topic label
   let topic = "BASE_BRANCH"
   let announcement = author.create_stream(topic).await?;
}

For a more detailed guide, go to the legacy IOTA documentation portal. Currently, this guide is parity with the current functionality. A future portal is in the works.

API reference

To generate the API reference and display it in a web browser, do the following:

cargo doc --open

Examples

We have several examples in the examples directory, which you can use as a reference when developing your own protocols with IOTA Streams.

You can run the examples yourself on a local bucket test instance by running:

cargo run --example full-example --features="bucket" 

If you would like to run them using an existing node, you can do so by copying the example.env file and updating the URL variable to the appropriate node url, and changing the TRANSPORT variable to utangle. Run the above command in --release mode.

Supporting the project

Please see our contribution guidelines for all the ways in which you can contribute.

Running tests

We use code comments to write tests. You can run all tests by doing the following from the streams directory:

cargo test --all

Updating documentation

If you want to improve the code comments, please do so according to the guidelines in RFC 1574.