README.md

A cryptographic framework for building secure messaging protocols

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

---

About

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

As a framework, Streams allows developers to build protocols for their specific needs.

This process will be documented as the development progresses. However, since this crate is in an alpha stage of development it is still likely to change.

At the moment, IOTA Streams includes the following crates:

• Channels Application featuring Channels Application.
• Core layers featuring spongos automaton for sponge-based authenticated encryption, pre-shared keys, pseudo-random generator;
• Keccak for core layers featuring Keccak-F[1600] as spongos transform;
• Curve25519 asymmetric crypto featuring Ed25519 signature and X25519 key exchange;
• DDML featuring data definition and manipulation language for protocol messages;
• Application layer common Application definitions.
• 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 dependancy 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. However 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/iotaledger/streams", branch  = "master"}

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 = "1.0.0", 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 Channels protocol to create a new author and subscriber like so:

use iota_streams::app_channels::api::tangle::{Author, Subscriber};
use iota_streams::app::transport::tangle::PAYLOAD_BYTES;
use iota_streams::app::transport::tangle::client::Client;

fn main() {
    let node = "http://localhost:14265";
    let client = Client::new_from_url(node);

    let encoding = "utf-8";
    let multi_branching_flag = true;

    let mut author = Author::new("AUTHORSSEED", encoding, PAYLOAD_BYTES, multi_branching_flag, client);
    
    let mut subscriber = Subscriber::new("MYSUBSCRIBERSECRETSTRING", encoding, PAYLOAD_BYTES, client);
}

For a more detailed guide, go to our documentation portal.

API reference

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

cargo doc --open

Examples

We have an example in the examples directory. that you can use as a reference when developing your own protocols with IOTA Streams.

A no_std version can be found in iota-streams-app-channels-example directory

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.

Joining the discussion

If you want to get involved in discussions about this technology, or you're looking for support, go to the #streams-discussion channel on Discord.