IPIP-499: UnixFS CID Profiles

src/ipips/ipip-0499.md

@@ -0,0 +1,102 @@
+---
+# IPIP number should  match its pull request number. After you open a PR,
+# please update title and update the filename to `ipip0000`.
+title: "IPIP-0499: CID Profiles"
+date: 2025-04-03
+ipip: proposal
+editors:
+  - name: Michelle Lee
+relatedIssues:
+  - n/a
+order: 0000
+tags: ['ipips']
+---
+
+## Summary
+
+<!--One paragraph explanation of the IPIP.-->
+This proposal introduces profiles for IPFS CIDs. Profiles explicitly define CID version, hash algorithm, chunk size, DAG width, layout, and other parameters. 
+
+## Motivation
+
+Currently, CIDs can be generated with a variety of settings and optimizations for chunking, DAG width, and more. This means the same file can yield multiple, different CIDs depending on which tools and settings are used, and it is not possible to reliably reproduce or verify the CID. Profiles offer With profiles, following the same profile will produce identical CIDs for identical content, whic makes verification regardless of implementation.
+
+## Detailed design
+
+We introduce a profile naming system, 
+
+Each profile must specify the following characteristics:
+
+1. CID version (CIDv0 or CIDv1)
+2. Hash algorithm
+3. Chunk size
+4. DAG width
+5. DAG layout
+6. Required
+
+Additional profiles can be added at a future date. Profile names may be chosen from the names of any botanical tree with compound leaves.
+
+|             | Helia default | Kubo default                | Storacha default | "test-cid-v1" profile | DASL          |
+|-------------|---------------|-----------------------------|------------------|-----------------------|---------------|
+| CID version | CIDv1         | CIDv1                       | CIDv1            | CIDv1                 | CIDv1         |
+| Hash Algo   | sha-256       | sha-256                     | sha-256          | sha-256               | sha-256       |
+| Chunk size  | 1MiB          | 256KiB                      | 1MiB             | 1MiB                  | not specified |
+| DAG width   | 1024          | 174 (but it's complicated*) | 1024             | 174                   | not specified |
+| DAG layout  | balanced      | balanced                    | balanced         | balanced              | not specified |
+
+
+
+This would be specified as a table in (forthcoming UnixFS spec).
+
+
+
+## Design rationale
+
+The profile names are chosen to be easy to pronounce. 
+
+Here is a summary table of current defaults, thanks to input & clarifications from @2color @achingbrain @lidel:
+
+|             | Helia default | Kubo default                | Storacha default | "test-cid-v1" profile | DASL          |
+|-------------|---------------|-----------------------------|------------------|-----------------------|---------------|
+| CID version | CIDv1         | CIDv1                       | CIDv1            | CIDv1                 | CIDv1         |
+| Hash Algo   | sha-256       | sha-256                     | sha-256          | sha-256               | sha-256       |
+| Chunk size  | 1MiB          | 256KiB                      | 1MiB             | 1MiB                  | not specified |
+| DAG width   | 1024          | 174 (but it's complicated*) | 1024             | 174                   | not specified |
+| DAG layout  | balanced      | balanced                    | balanced         | balanced              | not specified |
+
+* Kubo has 2 different default DAG widths:
+  * For HAMT-sharded directories, the `DefaultShardWidth` [here](https://github.com/ipfs/boxo/blob/f1d5312e3be45d151bb9c8f11c9283820687bea3/ipld/unixfs/io/directory.go#L30) is 256. 
+  * For files, `DefaultLinksPerBlock` [here](https://github.com/ipfs/boxo/blob/v0.29.0/ipld/unixfs/importer/helpers/helpers.go#L30) is ~174
+
+See related discussion at https://discuss.ipfs.tech/t/should-we-profile-cids/18507/
+
+### User benefit
+
+Reliable, deterministic CIDs allow independent verification of content across tools and ipmlementations.
+
+### Compatibility
+
+Implementations will need to (1) make CID generation settings configurable and (2) support user setting of profiles.
+
+Kubo currently has no CLI / RPC / Config option to control DAG width in Kubo. https://github.com/ipfs/kubo/issues/10751 is the starting point to add that ability. 
+
+### Security
+
+TODO
+
+### Alternatives
+
+Another approach could be to name profiles based on the key UnixFS/CID parameters, e.g. v1-sha256-balanced-1mib-1024w-raw. This is longer and more convoluted.
+
+## Test fixtures
+
+TODO
+
+List relevant CIDs. Describe how implementations can use them to determine
+specification compliance. This section can be skipped if IPIP does not deal
+with the way IPFS handles content-addressed data, or the modified specification
+file already includes this information.
+
+### Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).