IPFS and content addressing, explained without the mythology

When someone tells you that a website will be published to IPFS, they are usually trying to convey something about resilience, integrity, or independence from central servers. Those benefits are real. They are also qualified in ways that matter if you are advising on a publishing decision, drafting terms for an operator, or managing a website published on an onchain TLD.

The problem is the shorthand. Three words travel with IPFS, the InterPlanetary File System, wherever it is mentioned: permanent, uncensorable, free. Each has accumulated enough mythology that it now does more work than the technology can support. The underlying protocol is useful, and understanding what it actually does separates the real advantages from the folklore.

This article builds the concept patiently, from the most ordinary web request to the specifics of how IPFS stores and retrieves data. By the end, you will be able to say what IPFS gives a publisher, what it cannot promise, and where a name fits into the picture.

How the ordinary web finds a page

Every URL you type into a browser is a set of directions: go to this server, at this path, and fetch whatever is there. The address describes a location, not a thing. When you request a document from a company’s website, you are asking the server that answers for that domain to give you whatever it holds at that path at the moment you ask.

This is location addressing. It has two notable properties, both worth understanding before comparing anything to it.

First, the content can change without the address changing. The server owner can replace the document with a different file, and you will receive the new version using the same URL. There is no mechanism in the URL itself that tells you whether the file has been altered since the last time you visited. If you received a link and saved it, you are trusting the operator of that server to serve the same content you originally saw.

Second, availability depends entirely on the server. If the server goes offline, if the domain name lapses, or if the operator simply removes the file, the URL stops working. The content does not move to another server automatically. The address pointed to a place, and the place is gone.

Neither of these is a flaw so much as a design decision. The location-based model built the web as it exists and handles the vast majority of use cases well. A page that must change every hour, a login area, a search function: all of these depend on an address that stays fixed while the answer behind it varies. The two properties are simply the right starting points for understanding what content addressing does differently.

Content addressing: finding a file by its fingerprint

A content identifier, or CID, is the label used to point to material in IPFS. It does not indicate where the content is stored. It is an address built from the content itself.

When you add a file to IPFS, the protocol splits it into blocks and computes a cryptographic hash of each. Those hashes are combined into a single top-level CID that names the whole file. A cryptographic hash function takes any input (a PDF, an image, an HTML page) and produces a fixed-length string of characters. In practice, two different inputs do not produce the same output, and the same input always produces the same output.

This means the CID is a fingerprint derived mathematically from the file’s contents. Any difference in the content produces a different CID. The same content added by two different IPFS nodes using the same settings produces the same CID, wherever and whenever each of them does it.

To retrieve the file, you give the network the CID. IPFS locates peers that hold the matching blocks, using a distributed hash table (a shared index spread across the participating nodes), fetches the blocks, and reassembles the file. The file can come from any node that holds it, not from one designated server. The CID does not care which node responds.

Because the CID is derived from the content, the device that receives the blocks can hash them again and confirm that the result matches what was asked for. If even one bit were altered, the hash would differ and the alteration would be obvious. This is the core of what content addressing gives you: a verifiable description of the thing itself, where a URL gives you only directions to a place.

What changes when the content changes

This is the property that surprises people most often. Because the CID is derived from the content, changing the content changes the address. Every version of a file has its own CID, and each is distinct.

Content addressed in this way is immutable by nature. You cannot edit the file behind a CID. You can only publish a new file, which receives a new CID, while the old CID continues to describe the old file exactly.

This immutability is a feature, but it creates a practical problem. A website is not a static object. Pages are updated, products change, policies are revised. A site published as a set of files has one CID for the whole set, so correcting a single comma on one page produces a new CID for the entire site. It would be impractical to hand every visitor a new identifier each time that happens.

The answer is a pointer that can move. The InterPlanetary Name System, or IPNS, is the protocol’s own mechanism for this: an IPNS name is a stable address whose target CID the publisher can update. Each version of the content keeps its own immutable CID. The IPNS name simply moves forward as new versions are published.

For someone used to the DNS, the nearest parallel is a domain name that keeps the same spelling while the server behind it is replaced. The pointer stays constant and the content it resolves to changes. The important difference is that each snapshot remains independently verifiable by its CID, which no ordinary URL can offer.

Who keeps the file available, and why someone must

In IPFS, data is not stored in one central location. It is held by whichever nodes of the network have chosen to keep it. Nothing in that arrangement guarantees how long a given file stays available. A file that no active node is hosting cannot be retrieved, however valid its CID.

This is the operational reality that the mythology tends to obscure. IPFS is a protocol for finding and transferring content-addressed data between willing nodes. It is not a storage service with a contractual obligation to keep your files available. A node that fetches content may keep a cached copy for a while, and may later delete it to free space through a process called garbage collection. The way to make content persist on a node is to pin it.

Pinning is an instruction to a node to keep certain data and exempt it from garbage collection, regardless of how often it is requested or how much time passes. A pinned file is stored on that node for as long as the pin stays in place and the node stays online.

Pinning can be done locally or remotely. Local pinning is done on the publisher’s own node. It is limited by the publisher’s own resources, including storage space, bandwidth, and power. A pinning service is a third party that runs nodes with dedicated resources and keeps data pinned on the publisher’s behalf.

A pin on a single node is also a single point of failure. If that node goes offline, the files it pins go with it, unless another node happens to hold a copy. Copies cached elsewhere may exist, but nobody has promised to keep them.

The implication for anyone commissioning or operating an IPFS-hosted site is straightforward: availability is an operational concern, not a property of the protocol. A well-designed deployment has the content pinned in more than one place, for example with a pinning service and on a node the publisher controls. That responsibility does not disappear because the hosting model is distributed. It only changes shape: with a conventional host you ask about uptime, and with IPFS you ask who holds the pins and what happens when one of them stops.

Gateways: how a standard browser reaches IPFS content

Most browsers do not speak the IPFS protocol on their own. An IPFS gateway bridges that gap. It is an HTTP server that fetches IPFS content on behalf of clients that only speak HTTP: browsers, image viewers, video players, anything that cannot follow an ipfs:// address by itself.

The gateway accepts a standard web request, looks up the CID on the IPFS network, and returns the content over HTTP. From the visitor’s perspective, it looks like any other web request, with no specialized software or configuration.

The gateway is also a point of centralization worth understanding. A gateway has an ordinary location-based address, so reaching it depends on the DNS and on HTTPS, which in turn rely on certificate authorities. If the gateway operator withdraws its service, or is required to block specific CIDs, visitors relying on that gateway lose access to the content, even if the content is still pinned and available on the IPFS network through other paths.

There is a second consequence. A visitor who goes through a gateway is trusting the gateway to return the right content, unless the visitor’s own software checks the result against the CID. The integrity guarantee described earlier belongs to whoever performs the verification. Behind a gateway, that is often the gateway and not the reader.

Several public gateways exist, and any IPFS node can also act as one. Gateways reach the widest audience, while software that speaks IPFS natively can fetch and verify content directly. A careful publisher therefore makes the original ipfs:// address available alongside any gateway link, so that neither audience depends on the other’s path.

For a publisher operating under an onchain name, this matters because a visitor’s path usually has two parts: resolving the name, then fetching the content. The first part is where an onchain name differs from a gateway address: it is resolved outside the ICANN DNS root, which means an ordinary browser needs added support before it will open one. Some wallets and browser extensions resolve them, as the page on names that resolve in wallets describes. Coverage is partial and it changes, so the list of capabilities that are live, with their sources is more reliable than any general statement about browser support.

What content addressing gives a publisher

Two properties stand out as useful for a publisher, and both flow directly from the CID being derived from the content.

Integrity. When software requests a file by its CID and checks what it receives, a file altered in transit or at the source fails the check and is rejected. No certificate authority or other trusted third party is needed for that test.

This is structurally different from a conventional HTTPS connection, where the assurance is about the server’s identity and the channel: you know whom you are talking to, and you trust that party to serve the document you expect. With a CID, the address itself is the test. A client that verifies receives either the exact file or an error, never a quietly substituted version.

Verifiability and audit. Because every version of a file has its own CID, a publisher can keep a record of which CID was live at each point in time. That record becomes a chain of published versions that others can check. For legal or compliance teams, a disagreement about what a page said can be narrowed considerably: if the CID in use at the time is known, anyone can retrieve the content and confirm it matches. The CID proves what the content was. It does not, by itself, prove when it was published, so the dating has to come from a separate record. What weight such a record carries in a dispute varies by country, and your own counsel decides.

An onchain record can supply that separate record. Storing whole documents directly on a blockchain is expensive and inefficient, so the common pattern is to keep the content on IPFS and store only its CID in an onchain record. The content stays offchain, and the pointer is public. For an operator issuing names under a TLD, this means the record that connects a name to its content can be read by anyone on a block explorer, without relying on the operator’s own assurances.

The myths: permanent, uncensorable, free

These three claims circulate in any conversation about IPFS. Each contains enough truth to be tempting and enough imprecision to cause problems.

On permanence

The CID lasts because it is a mathematical description, and a description does not wear out. But a description of a file that no reachable node holds is not useful to a visitor. Permanence is something a publisher must engineer and maintain. It also cuts the other way: once other nodes have copied a file, the publisher cannot be sure of withdrawing it, a point taken up in the questions at the end.

On censorship resistance

The resistance IPFS offers comes from replication. Content that several independent nodes hold cannot be removed by acting against one of them, and a node in one country is not bound by an order made in another. This is a meaningful property in specific contexts.

It should not be confused with legal immunity. Pinning services and gateway operators are ordinary businesses with ordinary legal obligations. An order addressed to every provider a publisher uses, or to the gateways that serve a particular market, can be effective. The resilience depends on copies existing somewhere the restriction does not reach, and a publisher who has pinned in one place has no such copies. IPFS also provides no secrecy: content and the nodes that provide it are visible to the network.

On cost

A pinning service runs nodes and keeps content available, and it generally does so for a fee. Reliable availability has infrastructure behind it, and infrastructure costs money, whether it appears as a subscription or as servers the publisher runs. A publisher relying on a single free arrangement for content the organization cannot afford to lose has not accounted for this correctly.

Pointing a name at content, and updating it

A bare CID is not a user-facing address. Visitors do not type hashes into browsers. A publisher makes IPFS content reachable under a readable name by storing a pointer to it in a name record.

The name record contains the current CID. It may sit in a DNS text record, in an IPNS name, or in the onchain record of a name. When a resolver looks up the name, it finds the CID and fetches the content from IPFS. Updating the site means publishing the new version to IPFS, which produces a new CID, then updating the name record to point at it. The old CID and its content remain retrievable for anyone who knows it, for as long as a node keeps them. The name now points forward.

A mutable pointer of this kind has three properties. The address itself is stable. It can be pointed at a new CID at any time. And only whoever controls the name can update it. For onchain names, the record that connects the name to the content lives in the registry: publicly readable, and changeable only from the wallet that holds the name.

For a brand operating under its own TLD, with a site at a name such as pay.yourbrand, that last point is central. Whoever controls the wallet controls what every visitor to the name sees. Who holds that wallet, who can approve a change, and what happens when a member of the team leaves are part of operational planning from the first day. A multisignature wallet, which requires several approvals before a change takes effect, is one common way to avoid depending on a single person.

Freename’s website builder follows this architecture. It lets a holder build pages and publish them to IPFS, and the site is then reached through the holder’s onchain name in browsers that support it. The content lives on IPFS under its CID, the name leads to that content, and a new version of the site means new content and an updated pointer.

Three questions to ask when you are told the site is on IPFS

The claims table becomes practical once it is turned into questions. A legal or brand team that has been told the new site is on IPFS needs three answers, and none of them is technical in the sense of requiring an engineer to understand the reply.

First: who pins it, and what is the arrangement with that party? The answer determines whether the content actually persists. A named service under contract, with a second copy elsewhere, is an answer. “The network” is not.

Second: which gateways serve it to ordinary visitors, and what is the fallback if one becomes unavailable? The answer determines how wide the effective audience is and where the availability dependencies sit. It also tells you whose terms of service govern the path most visitors will take.

Third: what is the update workflow, and specifically which party controls the name record and by what process? The answer determines how quickly content can be corrected, who can publish in the organization’s name, and who is responsible if a correction cannot be made.

None of these questions challenges IPFS as a technology. They are the operational questions any serious deployment has to answer, and they are the same questions you would put to a conventional host in different words: where is it stored, how is it served, who can change it. They become easier to ask when the mythology is set aside.

When IPFS is the right tool

Content addressing is well suited to a set of publishing problems, and less well suited to others. Being precise about the distinction is more useful than a general endorsement.

IPFS fits when integrity matters at the point of retrieval. Legal documents, published standards, archival records, and anything where a reader should be able to confirm that what they received is exactly what was published are candidates. The CID provides that confirmation without requiring trust in the serving infrastructure.

IPFS fits when independence from a single hosting provider matters. A publisher whose hosting arrangements may not be stable benefits from a model where the content is not tied to one provider’s continued cooperation, and where moving to another provider does not change the address of the content.

IPFS fits content that is versioned, where historical versions must remain retrievable. Altering a single character changes the resulting CID, so any workflow in which “what did version 3 say?” must have a verifiable answer finds a natural home here, provided the old versions stay pinned.

IPFS fits less well when a site depends on frequent dynamic updates driven by a backend database: accounts, baskets, search, personalized pages. The mutable-pointer mechanisms work, but they add operational complexity that a conventional hosting stack does not require. For a marketing site that changes daily, the overhead may not be justified unless the integrity and independence properties are also valued. Where the DNS and an ordinary host do the job, they are often simply the better choice, and nothing prevents an organization from using both: a conventional site for what changes constantly, and content-addressed publication for what must be provable.

For brands and operators building under an onchain TLD, these are the decisions that putting a TLD to work after the transfer involves: what to pin, who controls the name record, and how updates are handled. The glossary defines the terms used on the site, and the Launch Roadmap tool builds a launch roadmap for a newly acquired TLD.

If you are still assessing whether an onchain presence is appropriate, the comparison between an ICANN dotBrand and an onchain TLD is a useful reference. Hush Partners is a private desk for onchain TLDs, and it is reached through the contact form only.

Questions people ask

Can content be deleted from IPFS once it is published?

You can remove your own pins, and ask any service you use to remove theirs. Once no node holds the content, it is unreachable. What you cannot do is oblige a node you do not control to delete a copy it has chosen to keep. For content published in error, or content that includes personal data, this is the point to raise with your own counsel before publication and not after.

What happens to old versions of a site when it is updated?

Old CIDs remain valid, and the content they describe remains retrievable as long as at least one node keeps those versions. Whether old versions stay pinned is an operational choice the publisher makes. A publisher who wants a verifiable history keeps them pinned and keeps a record of which CID was live when. A publisher who does not can let them go, with the caveat in the previous answer.

Who can see content published to IPFS?

IPFS content is public by default. Anyone who knows a CID can request and view the corresponding data. There is no access control at the protocol level. If content should be restricted, it must be encrypted before it is added to IPFS. The CID then addresses the encrypted form, and only parties with the decryption key can make use of what they retrieve.

Is IPFS the same as blockchain storage?

No. IPFS is a peer-to-peer system for storing and transferring files. A blockchain is a ledger. They are complementary, which is why the two are so often mentioned together: the ledger holds a small public record, such as a CID, and IPFS carries the content that the record points to. Saying that a site is “on the blockchain” usually means that its pointer is, and its files are not.