Home

Awesome

CID (Content IDentifier) Specification

Self-describing content-addressed identifiers for distributed systems

Table of Contents

Motivation

CID is a format for referencing content in distributed information systems, like IPFS. It leverages content addressing, cryptographic hashing, and self-describing formats. It is the core identifier used by IPFS and IPLD. It uses a multicodec to indicate its version, making it fully self describing.

You can read an in-depth discussion on why this format was needed in IPFS here: https://github.com/ipfs/specs/issues/130 (first post reproduced here)

What is it?

A CID is a self-describing content-addressed identifier. It uses cryptographic hashes to achieve content addressing. It uses several multiformats to achieve flexible self-description, namely:

  1. multihash to hash content addressed, and
  2. multicodec to type that addressed content, to form a binary self-contained identifier, and optionally also
  3. multibase to encode that binary CID as a string.

Concretely, it's a typed content address: a tuple of (content-type, content-address).

How does it work?

Current version: CIDv1

CIDv1 is a binary format composed of unsigned varints prefixing a hash digest to form a self-describing "content address":

<cidv1> ::= <CIDv1-multicodec><content-type-multicodec><content-multihash>
# or, expanded:
<cidv1> ::= <`0x01`, the code for `CIDv1`><another code from `ipld` entries in multicodec table that signals content type of data being addressed><multihash of addressed data>

Where

Variant - Stringified Form

Since CIDs have many applications outside of binary-only contexts, a given CID may need to be base-encoded multiple ways for different consumers or for different transports. In such applications, CIDs are often expressed as a Unicode string rather than a bytestring, which adds a single code-point prefix. In these contexts, then, the full string form is:

<cidv1> ::= <multibase-codec><multibase-encoding(<CIDv1-multicodec><multicodec><multihash>)>

Where

Variant - Human-Readable Form

It is often advantageous to translate a CID, which is already modular and self-describing, into a human-readable expansion of its self-describing parts, for purposes such as debugging, unit testing, and documentation. We can easily transform a Stringified CID to a "Human-Readable CID" by translating and segmenting its constituent parts as follows:

<hr-cid> ::= <hr-mbc> "-" <hr-cid-mc> "-" <hr-mc> "-" <hr-mh>

Where each sub-component is replaced with its own human-readable form from the relevant registry:

For example:

# example CID
zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
# corresponding human readable CID
base58btc - cidv1 - raw - sha2-256-256-6e6ff7950a36187a801613426e858dce686cd7d7e3c0fc42ee0330072d245c95

See: https://cid.ipfs.io/#zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA

Design Considerations

CIDs design takes into account many difficult tradeoffs encountered while building IPFS. These are mostly coming from the multiformats project.

Versions

CIDv0

CIDv0 is a backwards-compatible version, where:

cidv0 ::= <multihash-content-address>

CIDv1

See the section: How does it work?

<cidv1> ::= <multibase-prefix><multicodec-cidv1><multicodec-content-type><multihash-content-address>

Decoding Algorithm

To decode a CID, follow the following algorithm:

  1. If it's a string (ASCII/UTF-8):
  1. Given a (binary) CID (cid):
    • If it's 34 bytes long with the leading bytes [0x12, 0x20, ...], it's a CIDv0.
      • The CID's multihash is cid.
      • The CID's multicodec is DagProtobuf
      • The CID's version is 0.
    • Otherwise, let N be the first varint in cid. This is the CID's version.
      • If N == 0x01 (CIDv1):
        • The CID's multicodec is the second varint in cid
        • The CID's multihash is the rest of the cid (after the second varint).
        • The CID's version is 1.
      • If N == 0x02 (CIDv2), or N == 0x03 (CIDv3), the CID version is reserved.
      • If N is equal to some other multicodec, the CID is malformed.

Implementations

FAQ

Q. I have questions on multicodec, multibase, or multihash.

Please check their repositories: multicodec, multibase, multihash.

Q. Why does CID exist?

We were using base58btc encoded multihashes in IPFS, and then we needed to switch formats to IPLD. We struggled with lots of problems of addressing data with different formats until we created CIDs. You can read the history of this format here: https://github.com/ipfs/specs/issues/130

Q. Is the use of multicodec similar to file extensions?

Yes, kind of! like a file extension, the multicodec identifier establishes the format of the data. Unlike file extensions, these are in the middle of the identifier and not meant to be changed by users. There is also a short table of supported formats.

Q. What formats (multicodec codes) does CID support?

We are figuring this out at this time. It will likely be a subset of multicodecs for secure distributed systems. So far, we want to address IPFS's UnixFS and raw blocks (dag-pb, raw), IPNS's libp2p-key, and IPLD's dag-json/dag-cbor formats.

Q. What is the process for updating CID specification (e.g., adding a new version)?

CIDs are a well established standard. IPFS uses CIDs for content-addressing and IPNS. Making changes to such key protocol requires a careful review which should include feedback from implementers and stakeholders across ecosystem.

Due to this, changes to CID specification MUST be submitted as an improvement proposal to ipfs/specs repository (PR with IPIP document), and follow the IPIP process described there.

Maintainers

Captain: @jbenet.

Contribute

Contributions welcome. Please check out the issues.

Check out our contributing document for more information on how we work, and about contributing in general. Please be aware that all interactions related to IPLD are subject to the IPFS Code of Conduct.

Small note: If editing the README, please conform to the standard-readme specification.

License

This repository is only for documents. These are licensed under a CC-BY 3.0 Unported License © 2016 Protocol Labs Inc.