Skip to content

Latest commit

 

History

History
164 lines (112 loc) · 4.58 KB

README.md

File metadata and controls

164 lines (112 loc) · 4.58 KB
Raw

Ceramic StreamID

License Crates.io

This package contains Ceramic StreamID and CommitID implementation.

Implements Ceramic streamIDs as defined in ceramic spec and CIP, represented as [StreamId] and [StreamId] for API clarity.

[StreamId] represents a reference to a stream as a whole, thus does not contain commit information.

[CommitId] represents a reference to a particular commit in the stream evolution.

<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes>

or including [StreamId] commit

<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes><commit-cid-bytes>

Getting started

Installation

$ cargo add streamid

Usage

See the ceramic developer site for more details about how to use this package.

To reference a stream as a whole, use [StreamId]. You can create an instance from the parts. stream type string or integer and CID instance or string are required.

use std::str::FromStr;

use cid::Cid;
use streamid::*;

const CID_STRING: &str = "bagcqcerakszw2vsovxznyp5gfnpdj4cqm2xiv76yd24wkjewhhykovorwo6a";
const STREAM_ID_STRING: &str = "kjzl6cwe1jw147dvq16zluojmraqvwdmbh61dx9e0c59i344lcrsgqfohexp60s";

let stream_id = StreamId::from_str(STREAM_ID_STRING).unwrap();

assert_eq!(stream_id.stream_type(), StreamType::Tile);
assert_eq!(stream_id.stream_type().to_string(), "tile");
assert_eq!(stream_id.cid().to_string(), CID_STRING);
assert_eq!(stream_id.to_string(), STREAM_ID_STRING);
assert_eq!(stream_id.to_url(), format!("ceramic://{STREAM_ID_STRING}"));

You can also create StreamId instance from StreamId string or bytes.

use std::str::FromStr;

use streamid::*;

const STREAM_ID_STRING: &str = "kjzl6cwe1jw147dvq16zluojmraqvwdmbh61dx9e0c59i344lcrsgqfohexp60s";

let stream_id = StreamId::from_str(STREAM_ID_STRING).unwrap();
use streamid::*;

let stream_id = StreamId::from_slice(vec![]).unwrap();

To reference particular point in a stream evolution, use [CommitId]. In addition to stream type ([StreamType]) and genesis reference ([Cid]), one is expected to provide a reference to commit ([Cid]). If you pass [None], this would reference a genesis commit.

use std::str::FromStr;

use streamid::*;

const BASE_CID_STRING: &str = "bagcqcerakszw2vsovxznyp5gfnpdj4cqm2xiv76yd24wkjewhhykovorwo6a";
const COMMIT_CID_STRING: &str = "bagjqcgzaday6dzalvmy5ady2m5a5legq5zrbsnlxfc2bfxej532ds7htpova";
const COMMIT_ID_STRING: &str =
  "k1dpgaqe3i64kjqcp801r3sn7ysi5i0k7nxvs7j351s7kewfzr3l7mdxnj7szwo4kr9mn2qki5nnj0cv836ythy1t1gya9s25cn1nexst3jxi5o3h6qprfyju";

let commit_id = CommitId::from_str(COMMIT_ID_STRING).unwrap();

assert_eq!(commit_id.stream_type(), StreamType::Tile);
assert_eq!(commit_id.stream_type().to_string(), "tile");
assert_eq!(commit_id.cid().to_string(), BASE_CID_STRING);
assert_eq!(commit_id.commit().to_string(), COMMIT_CID_STRING);
assert_eq!(commit_id.to_string(), COMMIT_ID_STRING);
assert_eq!(commit_id.to_url(), format!("ceramic://{COMMIT_ID_STRING}"));

To reference specific CID from [StreamId] or to change commit reference in [CommitId], use [StreamRefExt::at_commit] method:

use streamid::StreamRefExt;

commit_id.at_commit("bagcqcerakszw2vsov..."); // #=> new CommitId for the same stream
stream_id.at_commit("bagcqcerakszw2vsov..."); // #=> new CommitId for the same stream

[CommitId] ([StreamId] for compatibility also) can get you base [StreamId] via [StreamRefExt::to_base_id]:

use streamid::StreamRefExt;

commit_id.to_base_id(); // #=> StreamID reference to the stream
stream_id.to_base_id(); // #=> new StreamID reference to the same stream, effectively a shallow clone.

To parse an unknown input into proper [CommitId] or [StreamId], you could use StreamRef::from_str:

use std::str::FromStr;

use streamid::StreamRef;

let input = "bagcqcerakszw2vsov...";
let stream_id_or_commit_id = StreamRef::from_str(input).unwrap();

Development

Run tests:

cargo test

Run linter:

cargo clippy
cargo fmt

Contributing

We are happy to accept small and large contributions. Make sure to check out the Ceramic specifications for details of how the protocol works.

License

MIT or Apache-2.0