Add caveat about CID determinism #2217
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
🚀 Build Preview on IPFS ready
|
- add "Why the hashes differ" section explaining root block hashing - document when CID hash equals file hash (raw codec, single block) - list factors affecting CID: chunk size, DAG layout, codec, version, hash - explain flexibility as feature with tradeoffs for different use cases - add DAG Explorer link alongside CID Inspector in quickstart - link quickstart caveat to detailed explanation in concepts - add public gateways link to public-utilities page
lidel
force-pushed
the
cid-clarifications
branch
from
947b103 to
549ce0a
Compare
lidel
approved these changes
Dec 12, 2025
|
|
||
| :::callout | ||
| The transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. Many CLI tools perform this transformation locally before uploading. | ||
| **Important caveat:** Two identical files can produce different CIDs. The CID reflects the contents *and* how the file is processed: chunk size, DAG layout, hash algorithm, CID version, and other [UnixFS](https://specs.ipfs.tech/unixfs/) parameters. The same file processed with different parameters will produce different CIDs. See [CIDs are not file hashes](../concepts/content-addressing.md#cids-are-not-file-hashes) for details. |
Member
There was a problem hiding this comment.
ℹ️ we already had "CIDs are not file hashes" content elsewhere, so adjusted this to link there + expanded there
|
|
||
| As we can see, the hash included in the CID does NOT match the hash of the input file `ubuntu-20.04.1-desktop-amd64.iso`. | ||
|
|
||
| ### Why the hashes differ |
Member
There was a problem hiding this comment.
@mishmosh @aschmahmann does this extra explainer sound good?
The main point I want to make here is that this is a feature, not a limitation. And at the end we mention community-provided profiles for cases where specific preset is required.
lidel
force-pushed
the
cid-clarifications
branch
from
549ce0a to
9c8406c
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Per discussion with @aschmahmann