Skip to content
This repository was archived by the owner on Jun 2, 2020. It is now read-only.

Commit 9b6a698

Browse files
authored
Improve CID concept doc for #95
1 parent a92f8ee commit 9b6a698

File tree

1 file changed

+28
-7
lines changed

1 file changed

+28
-7
lines changed

content/guides/concepts/cid.md

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,39 @@ menu:
55
parent: concepts
66
---
77

8-
A *content identifier* is a value that addresses a single piece of content in IPFS. It is mainly a cryptographic hash of the content, but is encoded as a [multihash](https://github.com/multiformats/multihash) and [multicodec](https://github.com/multiformats/multicodec). (Note: older CIDs have a different design — see [version 0](#version-0) below.)
8+
## Summary
99

10-
<!-- TODO: explain more of the details of how CID v1 is composed here. -->
10+
A *content identifier*, or CID, is a label used for addressing content in IPFS. CID's are used as a standard way of pointing to pieces of information. CID's identify specific pieces of content stored in IPFS.
1111

12-
You can read up on the details in the [CID spec](https://github.com/ipld/cid). You might also want to check out the [CID inspector](http://cid-utils.ipfs.team/#zb2rhiVd5G2DSpnbYtty8NhYHeDvNkPxjSqA7YbDPuhdihj9L) for an interactive breakdown of CIDs.
12+
CID's are based on that content's cryptographic hash - a different piece of content will have a different hash and will produce different CID's.
1313

14-
## Version 1
14+
## Format of CID's
15+
16+
CID's can take a few different forms, each easy for humans and/or software to decode. Any specific CID can be transformed to other equivalent CID representations (for example, using different base, CID version or codec).
17+
18+
CID v1 and later are comprised of some leading identifiers making it easy to identify which representation is used, along with the content-hash itself. In v1 and later, these include a multibase identifier, [multicodec](https://github.com/multiformats/multicodec) identifier, and CID version-identifier:
19+
20+
* The multibase identifier specifies the encoding being used for the CID
21+
* The CID identifer indicates which version of CID is encoded
22+
* The multicodec identifier indicates the format of the target content - it helps people and software to know how to interpret that content after the content is fetched
23+
24+
These leading identifiers provide support for different formats to be used in future versions. Older CIDs have a different design that omits these identifiers — see [version 0](#version-0) below.
25+
26+
Using the first few bytes of the CID, the CID can easily be interpreted; the content can be fetched from IPFS, then decoded with the correct codec. For more details, check out the [CID specification](https://github.com/ipld/cid). It includes a [decoding algorithm](https://github.com/ipld/cid/blob/ef1b2002394b15b1e6c26c30545fd485f2c4c138/README.md#decoding-algorithm) and links to existing software implementations for decoding CID's.
27+
28+
You might also want to check out the [CID inspector](http://cid-utils.ipfs.team/#zb2rhiVd5G2DSpnbYtty8NhYHeDvNkPxjSqA7YbDPuhdihj9L) for an interactive breakdown of differently-formatted CIDs.
29+
30+
## CID Versions
31+
### Version 1
1532

1633
Version 1 is the latest version of CID. It is used by default for `files` ([MFS](/concepts/mfs)) and `object` operations.
1734

18-
## Version 0
35+
### Future versions
36+
37+
Future versions of CID may be created to adapt to new requirements or learnings, and the leading identifiers will be used to easily identify the need to apply any new parsing semantics.
38+
39+
### Version 0
1940

20-
When IPFS was first designed, we used base 58-encoded multihashes as the content identifiers. (This is simpler, but much less flexible than newer CIDs.) It is still used by default when adding files and blocks to IPFS, so you should generally try to support them.
41+
When IPFS was first designed, we specified the consistent use of base 58-encoded multihashes as the content identifiers. While this is s simpler, it is also much less flexible than newer CIDs. CIDv0 is still used by default when adding files and blocks to IPFS, so you should generally try to support them.
2142

22-
The CID specification includes a [decoding algorithm](https://github.com/ipld/cid/blob/ef1b2002394b15b1e6c26c30545fd485f2c4c138/README.md#decoding-algorithm) you can use to distinguish CID v0 from newer versions.
43+
There is a [decoding algorithm](https://github.com/ipld/cid/blob/ef1b2002394b15b1e6c26c30545fd485f2c4c138/README.md#decoding-algorithm) that shows how you can distinguish CID v0 from newer versions.

0 commit comments

Comments
 (0)