TypeScript icon, indicating that this package has built-in type declarations

4.1.0 • Public • Published

Ceramic StreamID

ceramicnetwork MIT license Twitter

This package contains Ceramic StreamID and CommitID implementation.

Implements Ceramic streamIDs as defined in ceramic spec and CIP, represented as StreamID and CommitID 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


$ npm install @ceramicnetwork/streamid


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.

import { StreamID } from '@ceramicnetwork/streamid';

const streamid = new StreamID('tile', 'bagcqcerakszw2vsov...');

streamid.type; // 0
streamid.typeName; // 'tile'
streamid.bytes; // Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...]
streamid.cid; // CID('bagcqcerakszw2vsov...')

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

const streamid = StreamID.fromString('k3y52l7mkcvtg023bt9txe...');
const streamid = StreamID.fromBytes(Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...])

To reference particular point in a stream evolution, use CommitID. In addition to stream type (string or integer) and genesis reference (CID instance or string), one is expected to provide a reference to commit (CID instance or string). If you pass 0 or '0' (as string), null or just omit the value, this would reference a genesis commit.

import { CommitID } from '@ceramicnetwork/streamid';

const commitId = new CommitID('tile', 'bagcqcerakszw2vsov...', 'bagcqcerakszw2vsov...');

commitId.type; // 0
commitId.typeName; // 'tile'
commitId.bytes; // Uint8Array(41) [ 206,   1,   0,   0,   1, 133,   1, ...]
commitId.cid; // CID('bagcqcerakszw2vsov...')
commitId.commit; // CID('bagcqcerakszw2vsov...')

// k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws
// ceramic://k3y52l7mkcvtg023bt9txegccxe1bah8os3naw5asin3baf3l3t54atn0cuy98yws?version=k3y52l7mkcvt...

To reference specific CID from StreamID or to change commit reference in CommitID, use atCommit method:

commitId.atCommit('bagcqcerakszw2vsov...'); // #=> new CommitID for the same stream
streamId.atCommit('bagcqcerakszw2vsov...'); // #=> new CommitID for the same stream

CommitID (StreamID for compatibility also) can get you base StreamID via #baseID:

commitId.baseID; // #=> StreamID reference to the stream
streamId.baseID; // #=> 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:

import { streamRef } from '@ceramicnetwork/streamid';
const input = 'bagcqcerakszw2vsov...' // could be instance of Uint8Array, StreamID, CommitID either; or in URL form
const streamIdOrCommitId = streamRef.from(input) // throws if can not properly parse it into CommitID or StreamID


Run tests:

npm test

Run linter:

npm run lint


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


MIT or Apache-2.0



Package Sidebar


npm i @ceramicnetwork/streamid

Weekly Downloads





(Apache-2.0 OR MIT)

Unpacked Size

67.5 kB

Total Files


Last publish


  • dav1do
  • ceramic-velvetshark
  • cb3box
  • jpham2023
  • npm.3box
  • smrz2001
  • oed
  • paul_lecam
  • stbrody
  • ukstv