Ceramic Document Ids

Usage no npm install needed!

<script type="module">
  import ceramicnetworkDocid from 'https://cdn.skypack.dev/@ceramicnetwork/docid';


Ceramic DocId

This package contains Ceramic DocID and CommitID implementation.

Implements Ceramic DocIDs as defined in ceramic spec and CIP, represented as DocID and CommitID for API clarity.

DocID represents a reference to a document as a whole, thus does not contain commit information.

CommitID represents a reference to a particular commit in the document evolution.

<docid> ::= <multibase-prefix><multicodec-docid><doctype><genesis-cid-bytes>

or including DocID commit

<docid> ::= <multibase-prefix><multicodec-docid><doctype><genesis-cid-bytes><commit-cid-bytes>

Getting started


$ npm install @ceramicnetwork/docid


To reference a document as a whole, use DocID. You can create an instance from the parts. Document type string or integer and CID instance or string are required.

import DocID from '@ceramicnetwork/docid';
// alternatively: import { DocID } from '@ceramicnetwork/docid'

const docid = new DocId('tile', 'bagcqcerakszw2vsov...');

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

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

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

To reference particular point in a document evolution, use CommitID. In addition to document 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/docid';

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 DocID or to change commit reference in CommitID, use atCommit method:

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

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

commitId.baseID; // #=> DocID reference to the document
docId.baseID; // #=> new DocID reference to the same document, effectively a shallow clone.

To parse an unknown input into proper CommitID or DocID, you could use DocRef.from:

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


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