Name: cid
Owner: IPLD
Description: Self-describing content-addressed identifiers for distributed systems
Created: 2016-09-09 16:04:53.0
Updated: 2018-05-21 16:58:04.0
Pushed: 2018-05-12 12:33:44.0
Size: 30
Language: null
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
Self-describing content-addressed identifiers for distributed systems
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.
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)
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 multihash for hashes, multicodec for data content types, and multibase to encode the CID itself into strings.
Current version: CIDv1
A CIDv1 has four parts:
v1> ::= <mb><version><mc><mh>
, expanded:
v1> ::= <multibase-prefix><cid-version><multicodec-content-type><multihash-content-address>
Where
<multibase-prefix>
is a multibase code (1 or 2 bytes), to ease encoding CIDs into various bases.<cid-version>
is a varint representing the version of CID, here for upgradability purposes.<multicodec-content-type>
is a multicodec code representing the content type or format of the data being addressed.<multihash-content-address>
is a multihash value, representing the cryptographic hash of the content being addressed. Multihash enables CIDs to use many different cryptographic hash function, for upgradability and protocol agility purposes.That's it!
CIDs design takes into account many difficult tradeoffs encountered while building IPFS. These are mostly coming from the multiformats project.
It is advantageous to have a human readable description of a CID, solely for the purposes of debugging and explanation. We can easily transform a CID to a “Human Readable CID” as follows:
cid> ::= <hr-mbc> "-" <hr-cid-version> "-" <hr-mc> "-" <hr-mh>
Where each sub-component is represented with its own human-readable form:
<hr-mbc>
is a human-readable multibase code (eg base58btc
)<hr-cid-version>
is the string cidv#
(eg cidv1
or cidv2
)<hr-mc>
is a human-readable multicodec code (eg cbor
)<hr-mh>
is a human-readable multihash (eg sha2-256-256-abcdef0123456789...
)For example:
ample CID
he5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
rresponding human readable CID
58btc - cidv1 - raw - sha2-256-256-6e6ff7950a36187a801613426e858dce686cd7d7e3c0fc42ee0330072d245c95
See: http://cid-utils.ipfs.team/#zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA
CIDv0 is a backwards-compatible version, where:
multibase
is always base58btc
and implicit (not written)multicodec
is always protobuf-mdag
and implicit (not written)cid-version
is always cidv0
and implicit (not written)multihash
is written as is but is always a full (length 32) sha256 hash.0 ::= <multihash-content-address>
See the section: How does it work? - Protocol Description
v1> ::= <multibase-prefix><cid-version><multicodec-content-type><multihash-content-address>
To decode a CID, follow the following algorithm:
Qm...
, it's a CIDv0. Decode it as base58btc and continue to step 2.cid
):[0x12, 0x20, ...]
, it's a CIDv0.cid
.N
be the first varint in cid
. This is the CID's version.N == 1
(CIDv1):cid
cid
(after the second varint).N <= 0
, the CID is malformed.N > 1
, the CID version is reserved.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 table of formats for secure distributed systems. So far, we want to address: IPFS's original protobuf format, the new IPLD CBOR format, git, bitcoin, and ethereum objects.
Captain: @jbenet.
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.
This repository is only for documents. These are licensed under a CC-BY 3.0 Unported License © 2016 Protocol Labs Inc.