Table of Contents
Specification for how to encode a Stream Id (StreamID)
A StreamID is composed of a streamid-multicodec, a stream type varint, and a CID.
A specific encoding for StreamIDs allows us to distinguish them from CIDs as well as provide more information about the given stream. CommitIDs are a subset of a StreamID which refers to a specific commit in a stream.
StreamIDs are defined as:
<streamid> ::= <multibase-prefix><multicodec-streamid><stream-type><genesis-cid-bytes> # e.g. using CIDv1 <streamid> ::= <multibase-prefix><multicodec-streamid><stream-type><multicodec-cidv1><multicodec-content-type><multihash-content-address>
<multibase-prefix>is a multibase code (1 or 2 bytes), to ease encoding StreamIDs into various bases. NOTE: Binary (not text-based) protocols and formats may omit the multibase prefix when the encoding is unambiguous.
<multicodec-streamid>is a multicodec used to indicate that it’s a StreamID.
<stream-type>is a varint representing the stream type of the stream.
<genesis-cid-bytes>is the bytes from the CID of the genesis record, stripped of the multibase prefix.
The CommitID adds some additional information at the end. If it represents the genesis commit the zero byte is added (
0x00) otherwise the CID that represents the commit is added.
CommitIDs are defined as:
<streamid> ::= <multibase-prefix><multicodec-streamid><stream-type><genesis-cid-bytes><commit-reference> # e.g. using CIDv1 and representing the genesis commit <streamid> ::= <multibase-prefix><multicodec-streamid><stream-type><multicodec-cidv1><multicodec-content-type><multihash-content-address><0x00> # e.g. using CIDv1 and representing the an arbitrary commit in the log <streamid> ::= <multibase-prefix><multicodec-streamid><stream-type><multicodec-cidv1><multicodec-content-type-1><multihash-content-address-1><multicodec-cidv1><multicodec-content-type-2><multihash-content-address-2>
<commit-reference>is either the zero byte (
0x00) or a CID.
The multicodec for StreamID is
For compatibility with browser urls it’s recommended to encode the StreamID using
Using the table linked below stream types can be be publicly registered by submitting a new CIP that adds it to the table.
A Ceramic stream can be identified using the CID of the genesis commit of the event log, as well as the stream type of the stream. Using the StreamID a Ceramic node can query the network for the latest tip of the stream.
By having the stream type in the StreamID, Ceramic implementations can be optimize to use the correct stream type handler before needing to sync parts of the event log.
Previously testnet versions of Ceramic has been using CIDs to represent StreamIDs. This is a breaking change to only allow the StreamID format specified above.
Copyright and related rights waived via CC0.
Please cite this document as:
Joel Thorstensson, "CIP-59: StreamID encoding," Ceramic Improvement Proposals, no. 59, August 2020. [Online serial]. Available: https://github.com/ceramicnetwork/CIPs/blob/main/CIPs/cip-59.md