IPFS on Bitsy Wiki

Content Identifiers

Mon, 01 Jan 0001 00:00:00 +0000

A content identifier (CID) is the name IPFS gives a block. It is not a bare hash: it is a hash wrapped in enough metadata to say which hash function produced it, how long the digest is, how the bytes it names should be interpreted, and which alphabet the whole thing is written in. Every one of those is a decision that would otherwise have to be agreed out of band, and baking them into the identifier is what lets the format change without breaking the names already in circulation.

UnixFS and Chunking

Mon, 01 Jan 0001 00:00:00 +0000

A hash names one block. A film does not fit in one block, and neither does a directory of ten thousand files. UnixFS is the layout that turns files and directories into a Merkle DAG of blocks, and it is the reason IPFS can hand out a single content identifier (CID) for something far larger than anything it moves in one piece.

The chunker#

Import starts by cutting the byte stream into chunks. Kubo’s default is size-262144 — fixed 256 KiB pieces, cut at offsets that ignore the content entirely.

Content Routing and Bitswap

Mon, 01 Jan 0001 00:00:00 +0000

Fetching a content identifier (CID) is two problems that IPFS solves with two separate subsystems. Routing answers “which peers claim to have this block”. Transfer gets the bytes from one of them. Neither is guaranteed to succeed, and they fail for unrelated reasons — which is why a CID that stops resolving is rarely a storage problem.

Provider records and the Amino DHT#

The public IPFS distributed hash table (DHT), named Amino in 2023 to separate the specific network from the Kademlia protocol it runs, maps a multihash — the raw digest inside the CID, without the version and codec wrapper — to a list of peers advertising it. A node holding a block provides it by writing a record to the peers whose IDs sit closest to that multihash in the keyspace. Keying on the digest rather than the whole CID means two CIDs over the same bytes, differing only in codec or base, share one set of provider records.

IPNS and DNSLink

Mon, 01 Jan 0001 00:00:00 +0000

A content identifier (CID) is a hash, so publishing a new version of anything produces a new name. Every real deployment on IPFS therefore needs a second layer: a stable name that points at a CID and can be repointed. Three mechanisms do this, and they differ in who is allowed to repoint, how fast the change propagates, and what has to be trusted for the answer to be right.

IPNS#

The InterPlanetary Name System (IPNS) names content by a key pair. The name is the CID of the public key under the libp2p-key codec, written in base36 by default — k51qzi5uqu5... — and the base36 choice is a consequence of the default key type. An Ed25519 public key is small enough that libp2p embeds it in the identifier verbatim, under the identity multihash, rather than hashing it. That makes the CID 40 bytes, which comes to 65 characters in base32 including the multibase prefix — over the 63-character limit on a domain label, and therefore unusable as a subdomain gateway host. The same 40 bytes in base36 come to 62. An RSA key is too large to embed and gets hashed instead, producing the shorter 59-character base32 form that never had the problem.

Gateways

Mon, 01 Jan 0001 00:00:00 +0000

A gateway is an HTTP server that speaks IPFS so the client does not have to. It accepts a URL containing a content identifier (CID), fetches the blocks over the peer-to-peer network, reassembles them, and returns an ordinary HTTP response. Every browser follows such a link with no extension, no daemon, and no awareness that any of this happened.

Three URL shapes#

1
2
3

https://ipfs.io/ipfs/<cid>/logo.png                path gateway
https://<cid>.ipfs.dweb.link/logo.png              subdomain gateway
https://example.com/logo.png                       DNSLink gateway

The path form is the one people paste, and it puts every CID on the network under a single browser origin. Anything served from ipfs.io/ipfs/ shares cookies, local storage, and permissions with everything else served from ipfs.io/ipfs/, so one hostile page can read another page’s state. The subdomain form exists to fix exactly that: each CID gets its own origin, and the browser’s same-origin policy does the isolation it was designed to do. ipfs.io and dweb.link redirect path requests into the subdomain form for this reason. Only a version-1 CID in lowercase base32 can appear in that hostname, because a domain label is case-insensitive and capped at 63 characters, so a Qm link still works and is converted on the way through.