feat: default new repos to CIDv1

[lidel]

Problem

Making CIDv1 (base32 bafy...) the default has been tracked in #4143 for years, and the groundwork already landed: both CID versions work throughout, the CLI and gateway render base32, and Kubo 0.29's Import config (#10421) together with IPIP-499's unixfs-v0-2015 / unixfs-v1-2025 profiles pin the parameters so any implementation can reproduce the same CIDs. The one remaining gap was the default itself: ipfs init wrote no Import.*, so new repos fell back to CIDv0 Qm....

Some users also lean on CIDs as if they were deterministic hashes. That is a misunderstanding of what a CID is, but breaking them isn't the goal, so existing repos need agency to move to CIDv1 on their own schedule.

Fix

ipfs init now applies the unixfs-v1-2025 profile to the config it writes, so a fresh repo produces CIDv1 everywhere. This is deliberately the least disruptive way to flip the default:

• Only fresh repos change. The switch lives in what ipfs init writes, not a code-level fallback. A pre-existing repo with empty or absent Import.* still resolves to CIDv0 exactly as before, with no migration and no repo-version bump.
• Every import path follows the repo's config, not just ipfs add: ipfs files, the MFS root, the gateway, and the client/rpc Go library all produce the configured CID version. Requesting a version explicitly (--cid-version, or a non-sha2-256 hash) uses that version's natural leaves; contradictions like --cid-version=0 --raw-leaves, or a config pairing Import.CidVersion=0 with Import.UnixFSRawLeaves=true, are rejected rather than emitting a surprising CID.
• Import.* is the single source of truth, including whether the startup notice appears. If any CID-profile field is still unset, ipfs daemon prints a one-time notice nudging the operator to pin a profile; once explicit, it stops.
• Users choose, explicitly. New repos get unixfs-v1-2025; ipfs init --profile unixfs-v0-2015 keeps CIDv0; existing-repo operators are nudged to record their choice rather than lean on an implicit default that could shift across releases.

This respects user agency and avoids breaking legacy datasets, while making CIDv1 what new users get out of the box.

References

• Context
  • Spec: IPIP-499: UnixFS CID Profiles (ipfs/specs#499) defines the unixfs-v0-2015 and unixfs-v1-2025 profiles this PR applies.
  • Enabling work: #10421 added the Import config section; #11148 added its IPIP-499 profile fields.
  • Groundwork: defaulting to CIDv1 became practical once base32 (#6220) and subdomain gateways (#6498) shipped.
  • Supersedes: #8886, #8896, and #8898, three earlier attempts at CIDv1-by-default.
  • Interop: ipfs/helia#1083 updates the Helia interop suite for the new default.
• Closes Make base32 CIDv1 the default (Kubo 1.0) #4143
• Closes Migration to CIDv1 (default base32) specs#247

Demo

A fresh repo now defaults to CIDv1. ipfs init writes the unixfs-v1-2025 profile, so ipfs add, ipfs files, and the MFS root produce base32 bafy.../bafk... out of the box instead of Qm...:

$ ipfs init          # writes the unixfs-v1-2025 profile
$ ipfs config Import.CidVersion
1
$ echo -n "hello, CIDv1!" | ipfs add -q
bafkreifriwiigahgxhtea4usek2ew2hr4vtnzsj7m6jy6n5iusfporvs2e   # was QmNbyD5G... before

Existing repos are untouched. A repo whose Import.* is empty or absent keeps producing the exact same CIDs. The only new thing its operator sees is a one-time notice at ipfs daemon startup, until a profile is pinned:

$ ipfs daemon
Initializing daemon...
...
⚠️ This repository relies on implicit UnixFS Import.* config defaults,
⚠️ so the CIDs it produces can change between Kubo releases. Pin
⚠️ them by applying a profile (this also silences this notice):
⚠️   $ ipfs config profile apply unixfs-v1-2025   # recommended, modern CIDv1
⚠️   $ ipfs config profile apply unixfs-v0-2015   # legacy, CIDv0 "Qm.." format
⚠️ Use the legacy profile only to keep reproducing existing CIDs.
⚠️ See IPIP-499: https://specs.ipfs.tech/ipips/ipip-0499/
...
Daemon is ready

Once the operator applies a profile (or runs ipfs init --profile ... on a new repo), Import.* is explicit and the notice stops.

TODO

• land fix: pin kubo interop node to unixfs-v1-2025 helia#1083 first

[lidel]

• revert this if/once fix: pin kubo interop node to unixfs-v1-2025 helia#1083 lands

[guillaumemichel]

IIUC add and MFS disagree when a CidVersion=0 config meets a non-sha2-256 hash?

With {"Import": {"CidVersion": 0, "HashFunction": "blake3"}} (which ValidateImportConfig accepts), this emits CidVersion(0) and L85 emits Hash(blake3) — and UnixfsAddOptions rejects that pair outright:

kubo/core/coreiface/options/unixfs.go

Lines 130 to 131 in 13ad613

	case 0:
	return nil, cid.Prefix{}, errors.New("CIDv0 only supports sha2-256")

Whereas UnixFSCidBuilder silently bumps v0 → v1 for the same config, so ipfs files write succeeds and emits CIDv1. Same repo, same config: add errors, MFS quietly changes version.

This inconsistency predates this PR, but it may be a good opportunity to address it?

[guillaumemichel]

Wouldn't it be possible to have the root with CIDv0 and still pass --raw-leaves, encoding the leaves using CIDv1? I just want to make sure we don't break any existing use cases.

IIUC the sharness suite already asserts exactly that shape, in files this PR doesn't touch:

• t0040-add-and-cat.sh:911 — test_add_cat_5MB --raw-leaves "QmabWSFaPusmiZaaVZLhEUtHcj8CCvVeUfkBpKqAkKVMiS"
• t0040-add-and-cat.sh:860-863 — add_directory '--raw-leaves' expects PLANETS="QmfWfQfKCY5Ukv9peBbxM5vqWM9BzmqUSXvdCgjT2wsiBT" with MARS/VENUS as bafkrei..., i.e. a CIDv0 dag-pb root linking CIDv1 raw leaves
• t0270-filestore.sh:16 — EXPHASH="QmXKtATsEt42CF5JoSsmzJstrvwEB5P89YQtdX4mdf9E3M" from ipfs add --raw-leaves --nocopy

And these two still reach that shape without tripping the check:

• ipfs add --raw-leaves on a unixfs-v0-2015 repo — cidVersionSetByUser is false, so the guard is skipped
• ipfs add --cid-version=0 --nocopy — --raw-leaves is never passed so rawblks is false, and UnixfsAddOptions then auto-enables raw leaves for nocopy

Am I missing something about the intent? If the goal is to steer people toward unixfs-v1-2025 rather than to forbid the shape outright, a warning might fit better than a hard error. Otherwise we could simply drop the check, the combination is well-defined and already exercised in the suite.

[guillaumemichel]

IIUC chunker and hash are still forwarded unconditionally here, so the daemon's Import defaults never reach client/rpc callers?

L32's caopts.UnixfsAddOptions(opts...) materializes the library defaults, so even when the caller passes no options at all, options.Chunker is "size-262144" and mht is "sha2-256", and both go on the wire regardless. But the daemon reads an empty value as "not set, use config":

kubo/core/commands/add.go

Lines 487 to 498 in 13ad613

	// Forward hash and chunker only when set on the CLI; otherwise
	// UnixfsAPI.Add applies the Import config default.
	if hashFunStr != "" {
	hashFunCode, ok := mh.Names[strings.ToLower(hashFunStr)]
	if !ok {
	return fmt.Errorf("unrecognized hash function: %q", strings.ToLower(hashFunStr))
	}
	opts = append(opts, options.Unixfs.Hash(hashFunCode))
	}
	if chunker != "" {
	opts = append(opts, options.Unixfs.Chunker(chunker))
	}

Since the request always carries a non-empty value, != "" is always true there and the "otherwise UnixfsAPI.Add applies the Import config default" path never runs for RPC callers. So on a fresh unixfs-v1-2025 repo (UnixFSChunker = "size-1048576"), ipfs add chunks at 1 MiB while api.Unixfs().Add(ctx, f) against that same daemon chunks at 256 KiB, leading to different CIDs for anything over 256 KiB.

Would adding ChunkerSet/MhTypeSet to UnixfsAddSettings and gating these two the same way as CidVersionSet just below be the right fix? hash looks harmless today since both profiles pin sha2-256, but a repo with a custom Import.HashFunction would hit the same issue.