{"id":13726345,"url":"https://github.com/multiformats/cid","last_synced_at":"2025-10-05T19:12:06.632Z","repository":{"id":49738085,"uuid":"67813060","full_name":"multiformats/cid","owner":"multiformats","description":"Self-describing content-addressed identifiers for distributed systems","archived":false,"fork":false,"pushed_at":"2025-04-28T15:57:33.000Z","size":61,"stargazers_count":451,"open_issues_count":13,"forks_count":82,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-05-22T16:06:59.068Z","etag":null,"topics":["cid","ipfs","ipld","multiformats"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/multiformats.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-09T16:04:53.000Z","updated_at":"2025-05-20T06:45:35.000Z","dependencies_parsed_at":"2023-12-15T04:31:39.309Z","dependency_job_id":"f540d886-893c-4bcb-a062-d9757a66fdf0","html_url":"https://github.com/multiformats/cid","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/multiformats/cid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiformats%2Fcid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiformats%2Fcid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiformats%2Fcid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiformats%2Fcid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multiformats","download_url":"https://codeload.github.com/multiformats/cid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiformats%2Fcid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278504347,"owners_count":25997929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cid","ipfs","ipld","multiformats"],"created_at":"2024-08-03T01:03:00.309Z","updated_at":"2025-10-05T19:12:06.582Z","avatar_url":"https://github.com/multiformats.png","language":null,"funding_links":[],"categories":["Algorithms","ipfs","Others","miscellaneous"],"sub_categories":["Distributed Ledger Technology (DLT)"],"readme":"# CID (Content IDentifier) Specification\n\n[![](https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat-square)](https://protocol.ai/)\n[![](https://img.shields.io/badge/project-ipld-blue.svg?style=flat-square)](https://github.com/ipld/ipld)\n[![](https://img.shields.io/badge/freenode-%23ipfs-blue.svg?style=flat-square)](https://webchat.freenode.net/?channels=%23ipfs)\n\n\u003e Self-describing content-addressed identifiers for distributed systems\n\n## Table of Contents\n\n  - [Motivation](#motivation)\n  - [What is it?](#what-is-it)\n  - [How does it work?](#how-does-it-work)\n  - [Design Considerations](#design-considerations)\n  - [Variant Representation - Internal CID](#variant-representation---internal-cid)\n  - [Variant Representation - Human Readable CID](#variant-representation---human-readable-cid)\n  - [Versions](#versions)\n    - [CIDv0](#cidv0)\n    - [CIDv1](#cidv1)\n  - [Decoding Algorithm](#decoding-algorithm)\n  - [Implementations](#implementations)\n  - [FAQ](#faq)\n  - [Maintainers](#maintainers)\n  - [Contribute](#contribute)\n  - [License](#license)\n\n## Motivation\n\n[**CID**](https://github.com/ipld/cid) is a format for referencing content in distributed information systems, like [IPFS](https://ipfs.io). \nIt leverages [content addressing](https://en.wikipedia.org/wiki/Content-addressable_storage), [cryptographic hashing](https://simple.wikipedia.org/wiki/Cryptographic_hash_function), and [self-describing formats](https://github.com/multiformats/multiformats). \nIt is the core identifier used by [IPFS](https://ipfs.io) and [IPLD](https://ipld.io). \nIt uses a [multicodec](https://github.com/multiformats/multicodec) to indicate its version, making it fully self describing.\n\n**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](./original-rfc.md))**\n\n## What is it?\n\nA CID is a self-describing content-addressed identifier. \nIt uses cryptographic hashes to achieve content addressing. It uses several [multiformats](https://github.com/multiformats/multiformats) to achieve flexible self-description, namely:\n1. [multihash](https://github.com/multiformats/multihash) to hash content addressed, and\n2. [multicodec](https://github.com/multiformats/multicodec) to type that addressed content,\nto form a binary self-contained identifier, and optionally also\n3. [multibase](https://github.com/multiformats/multibase) to encode that binary CID as a  string.\n\nConcretely, it's a *typed* content address: a tuple of `(content-type, content-address)`.\n\n## How does it work?\n\nCurrent version: CIDv1\n\nCIDv1 is a **binary** format composed of [unsigned varints](https://github.com/multiformats/unsigned-varint) prefixing a hash digest to form a self-describing \"content address\":\n\n```text\n\u003ccidv1\u003e ::= \u003cCIDv1-multicodec\u003e\u003ccontent-type-multicodec\u003e\u003ccontent-multihash\u003e\n# or, expanded:\n\u003ccidv1\u003e ::= \u003c`0x01`, the code for `CIDv1`\u003e\u003canother code from `ipld` entries in multicodec table that signals content type of data being addressed\u003e\u003cmultihash of addressed data\u003e\n```\n\nWhere\n\n- `\u003cmulticodec-cidv1\u003e` is a [multicodec](https://github.com/multiformats/multicodec) representing the version of CID, here for upgradability purposes.\n- `\u003cmulticodec-content-type\u003e` is a [multicodec](https://github.com/multiformats/multicodec) code representing the content type or format of the data being addressed.\n- `\u003cmultihash-content-address\u003e` is a [multihash](https://github.com/multiformats/multihash) value, which uses a registry of hash function abbreviations to prefix a cryptographic hash of the content being addressed, thus making it self-describing.\n\n## Variant - Stringified Form\n\nSince 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. \nIn such applications, CIDs are often expressed as a Unicode *string* rather than a bytestring, which adds a single code-point prefix. \nIn these contexts, then, the full string form is:\n\n```text\n\u003ccidv1\u003e ::= \u003cmultibase-codec\u003e\u003cmultibase-encoding(\u003cCIDv1-multicodec\u003e\u003cmulticodec\u003e\u003cmultihash\u003e)\u003e\n```\n\nWhere\n\n- `\u003cmultibase-codec\u003e` is a [multibase](https://github.com/multiformats/multibase) prefix  (1 Unicode code point in length) that renders the base-encoded unicode string following it self-describing for simpler conversion back to binary.\n\n## Variant - Human-Readable Form\n\nIt 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. \nWe can easily transform a Stringified CID to a \"Human-Readable CID\" by translating and segmenting its constituent parts as follows:\n\n```text\n\u003chr-cid\u003e ::= \u003chr-mbc\u003e \"-\" \u003chr-cid-mc\u003e \"-\" \u003chr-mc\u003e \"-\" \u003chr-mh\u003e\n```\nWhere each sub-component is replaced with its own human-readable form from the relevant registry:\n\n- `\u003chr-mbc\u003e` is the name of the multibase code (eg `z`--\u003e `base58btc`)\n- `\u003chr-cid-mc\u003e` is the name of the multicodec for the version of CID used (eg `0x01` --\u003e `cidv1`)\n- `\u003chr-mc\u003e` is the name of the multicodec code (eg `0x51` --\u003e `cbor`)\n- `\u003chr-mh\u003e` is the name of the multihash code (eg `sha2-256-256`) followed by a final dash and the hash itself `-abcdef0123456789...`)\n\nFor example:\n\n```text\n# example CID\nzb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA\n# corresponding human readable CID\nbase58btc - cidv1 - raw - sha2-256-256-6e6ff7950a36187a801613426e858dce686cd7d7e3c0fc42ee0330072d245c95\n```\nSee: https://cid.ipfs.io/#zb2rhe5P4gXftAwvA4eXQ5HJwsER2owDyS9sKaQRRVQPn93bA\n\n## Design Considerations\n\nCIDs design takes into account many difficult tradeoffs encountered while building [IPFS](https://ipfs.tech). These are mostly coming from the multiformats project.\n\n- Compactness: CIDs are binary in nature to ensure these are as compact as possible, as they're meant to be part of longer path identifiers or URIs.\n- Transport friendliness (or \"copy-pastability\"): CIDs are encoded with multibase to allow choosing the best base for transporting. For example, CIDs can be encoded into base58btc to yield shorter and easily-copy-pastable hashes.\n- Versatility: CIDs are meant to be able to represent values of any format with any cryptographic hash.\n- Avoid Lock-in: CIDs prevent lock-in to old, potentially-outdated decisions.\n- Upgradability: CIDs encode a version to ensure the CID format itself can evolve.\n\n## Versions\n\n### CIDv0\n\nCIDv0 is a backwards-compatible version, where:\n- the `multibase` of the string representation is always `base58btc` and implicit (not written)\n- the `multicodec` is always `dag-pb` and implicit (not written)\n- the `cid-version` is always `cidv0` and implicit (not written)\n- the `multihash` is written as is but is always a full (length 32) sha256 hash.\n\n```text\ncidv0 ::= \u003cmultihash-content-address\u003e\n```\n\n### CIDv1\n\nSee the section: [How does it work?](#how-does-it-work)\n\n```text\n\u003ccidv1\u003e ::= \u003cmultibase-prefix\u003e\u003cmulticodec-cidv1\u003e\u003cmulticodec-content-type\u003e\u003cmultihash-content-address\u003e\n```\n\n## Decoding Algorithm\n\nTo decode a CID, follow the following algorithm:\n\n1. If it's a string (ASCII/UTF-8):\n  * If it is 46 characters long and starts with `Qm...`, it's a CIDv0. Decode it as base58btc and continue to step 2.\n  * Otherwise, decode it according to the multibase spec and:\n    * If the first decoded byte is 0x12, return an error. CIDv0 CIDs may not be multibase encoded and there will be no CIDv18 (0x12 = 18) to prevent ambiguity with decoded CIDv0s.\n    * Otherwise, you now have a binary CID. Continue to step 2.\n2. Given a (binary) CID (`cid`):\n   * If it's 34 bytes long with the leading bytes `[0x12, 0x20, ...]`, it's a CIDv0.\n     * The CID's multihash is `cid`.\n     * The CID's multicodec is DagProtobuf\n     * The CID's version is 0.\n   * Otherwise, let `N` be the first varint in `cid`. This is the CID's version.\n     * If `N == 0x01` (CIDv1):\n       * The CID's multicodec is the second varint in `cid`\n       * The CID's multihash is the rest of the `cid` (after the second varint).\n       * The CID's version is 1.\n     * If `N == 0x02` (CIDv2), or `N == 0x03` (CIDv3), the CID version is reserved.\n     * If `N` is equal to some other multicodec, the CID is malformed.\n\n## Implementations\n\n- [go-cid](https://github.com/ipfs/go-cid)\n- [java-cid](https://github.com/ipld/java-cid)\n- [js-multiformats](https://github.com/multiformats/js-multiformats)\n- [rust-cid](https://github.com/multiformats/rust-cid)\n- [py-multiformats-cid](https://github.com/pinnaculum/py-multiformats-cid)\n- [elixir-cid](https://github.com/nocursor/ex-cid)\n- [dart_cid](https://github.com/dwyl/dart_cid)\n- [zig_cid](https://github.com/zen-eth/multiformats-zig)\n- [Add yours today!](https://github.com/multiformats/cid/edit/master/README.md)\n\n## FAQ\n\n\u003e **Q. I have questions on multicodec, multibase, or multihash.**\n\nPlease check their repositories: [multicodec](https://github.com/multiformats/multicodec), [multibase](https://github.com/multiformats/multibase), [multihash](https://github.com/multiformats/multihash).\n\n\u003e **Q. Why does CID exist?**\n\nWe were using base58btc encoded multihashes in IPFS, and then we needed to switch formats to IPLD. \nWe struggled with lots of problems of addressing data with different formats until we created CIDs. \nYou can read the history of this format here: https://github.com/ipfs/specs/issues/130\n\n\u003e **Q. Is the use of multicodec similar to file extensions?**\n\nYes, kind of! like a file extension, the multicodec identifier establishes the format of the data. \nUnlike file extensions, these are in the middle of the identifier and not meant to be changed by users.\nThere is also a short table of supported formats.\n\n\u003e **Q. What formats (multicodec codes) does CID support?**\n\nWe are figuring this out at this time. \nIt will likely be a subset of [multicodecs](https://github.com/multiformats/multicodec/blob/master/table.csv) for secure distributed systems. \nSo far, we want to address IPFS's UnixFS and raw blocks ([`dag-pb`](https://ipld.io/specs/codecs/dag-pb/spec/), [`raw`](https://www.iana.org/assignments/media-types/application/vnd.ipld.raw)), IPNS's [`libp2p-key`](https://github.com/libp2p/specs/blob/master/RFC/0001-text-peerid-cid.md), and IPLD's [`dag-json`](https://ipld.io/specs/codecs/dag-json/spec/)/[`dag-cbor`](https://ipld.io/specs/codecs/dag-cbor/spec/) formats.\n\n\u003e **Q. What is the process for updating CID specification (e.g., adding a new version)?**\n\nCIDs are a well established standard. \nIPFS uses CIDs for content-addressing and IPNS.\nMaking changes to such key protocol requires a careful review which should include feedback from implementers and stakeholders across ecosystem.\n\nDue to this, changes to CID specification MUST be submitted as an improvement proposal to [ipfs/specs](https://github.com/ipfs/specs/tree/main/IPIP) repository (PR with [IPIP document](https://github.com/ipfs/specs/blob/main/IPIP/0000-template.md)), and follow the IPIP process described there. \n\n## Maintainers\n\nCaptain: [@jbenet](https://github.com/jbenet).\n\n## Contribute\n\nContributions welcome. Please check out [the issues](https://github.com/ipld/cid/issues).\n\nCheck out our [contributing document](https://github.com/ipld/ipld/blob/master/contributing.md) for more information on how we work, and about contributing in general.\nPlease be aware that all interactions related to IPLD are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).\n\nSmall note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.\n\n## License\n\nThis repository is only for documents.\nThese are licensed under a [CC-BY 3.0 Unported](LICENSE) License © 2016 Protocol Labs Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiformats%2Fcid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultiformats%2Fcid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiformats%2Fcid/lists"}