IPNS: Mutable Pointers to Immutable IPFS Content

IPNS exists to solve a problem this series has run into repeatedly: a CID changes the instant its content does, which is exactly what makes content addressing trustworthy, and exactly what makes it useless as a stable address for anything that needs to be updated. IPNS (the InterPlanetary Name System) is IPFS's answer, a name that stays constant while pointing at a different CID over time, without giving up the verifiability content addressing is built on.

TL;DR:

• A CID is immutable by design; change the content and the CID changes with it, so a CID alone can't serve as a stable address for anything that gets updated
• An IPNS name solves this differently than you'd expect: it isn't assigned or registered anywhere, it's the hash of a public key, derived the same trustless way a CID is derived from content
• Publishing an IPNS record means signing a statement, "this name currently points to this CID," with the matching private key; anyone can verify that signature without trusting whoever handed them the record
• IPNS records aren't permanent either: kubo's current defaults expire a DHT-published record after 48 hours and republish it every 22 hours, well inside that window, so a name stays resolvable as long as its holder keeps republishing
• AIOZ Pin pins by CID, which is immutable by nature. IPNS is a separate, general IPFS-layer technique for anyone who wants one stable address over pinned content that changes across versions, not a feature AIOZ Pin manages on your behalf

The Problem: Content Addressing Doesn't Do Mutable

Every article in this series up to this point has treated a CID's immutability as a feature, and it is: it's what makes tamper-evidence and trustless verification possible. But that same property means a CID cannot double as a stable pointer to something that changes. A website that gets updated, a dataset that gets a new version, an NFT's metadata that needs a correction, all of these need one address that keeps working even as what it points to changes underneath it. A CID structurally cannot do that; the moment the content changes, so does the address.

IPNS: A Name Derived From a Key, Not From Content

IPNS solves this by naming something that doesn't change even when the content does: a public key. An IPNS name is the hash of a public key, formatted as a CID in its own right, one whose multihash happens to be a key's fingerprint rather than a block's content hash. The person holding the matching private key can publish a record saying "this name currently resolves to this CID," and update that record as often as they want, with the name itself never changing, because the name was never derived from the content to begin with.

How a Record Gets Published and Verified

Publishing an IPNS update means constructing a record, current CID, a validity window, and a sequence number, and signing it with the private key that corresponds to the name. That signature is what makes the record self-certifying: anyone who receives it can verify it was produced by the actual key holder without needing to trust whoever relayed it to them, the same trustless-verification pattern this series' content-verification article covers, applied to a name instead of a file. The sequence number matters specifically for freshness: if two records for the same name show up, the one with the higher sequence number is the current one, which prevents an old, stale record from silently overriding a newer update.

Records Expire Too: Publishing and Republishing

An IPNS record is not permanent once published; it carries an expiry, and if nobody republishes it before that expiry passes, it stops resolving. Kubo's current defaults set a DHT-published provider record's expiration at 48 hours, with a background reprovide cycle running every 22 hours, comfortably inside that window, so an active node keeps its records fresh without ever letting one lapse. This means an IPNS name is only as reliable as whatever keeps republishing it; a name published once from a laptop that then goes offline for a few days will stop resolving, the same availability dependency this series' pinning and content-addressing articles already cover, just applied to the record instead of the content itself.

Two Transports: DHT and PubSub

IPNS records can be published two ways. Over the DHT, the same provider-record mechanism this series' DHT article describes, just storing a signed name-to-CID mapping instead of a content-provider claim. Over PubSub, a topic-based publish-subscribe channel among peers actively interested in a given name, which can propagate updates faster to peers already listening, at the cost of not helping a peer that wasn't already subscribed. Most practical setups lean on the DHT path since it doesn't require a listener to already be watching.

DNSLink: The Other Way to Get a Stable Name

IPNS is not the only way to get a human-friendly, updatable address over IPFS content, DNSLink, covered in the next article in this series, does the same job through ordinary DNS TXT records instead of a signed cryptographic name. The two are frequently combined: a DNS TXT record pointing at an IPNS name gets the update-without-changing-the-link property of IPNS with the memorability of a real domain name.

Where This Fits an AIOZ Pin Workflow

AIOZ Pin's own pinning model operates on CIDs, which stay immutable by design, that's the whole basis for the persistence and verification guarantees covered elsewhere in this series. IPNS sits one layer above that as a general IPFS technique, not something AIOZ Pin manages for you. Someone building on top of pinned content who wants one address that keeps working across versions, redeploying a static site's new build, updating a dataset, correcting a metadata file, would generate their own IPNS key pair, publish records pointing at whichever CID they've currently pinned, and simply re-publish a new record each time they pin an updated version.

Frequently Asked Questions

What does IPNS actually solve? It gives you one address that stays the same even as the content behind it changes, something a CID cannot do on its own since a CID is derived from the content itself.

Where does an IPNS name come from? It's the hash of a public key, not assigned by any registry. Whoever holds the matching private key can publish signed updates to what the name currently resolves to.

How does IPNS stay trustless if anyone can relay a record? Every record is signed by the name's private key, so a receiver can verify authenticity directly, without trusting whoever passed the record along.

Do IPNS records last forever once published? No. Kubo's current defaults expire a DHT record after 48 hours, with automatic republishing every 22 hours to keep an actively-maintained name resolvable.

Is IPNS the same as DNSLink? No. IPNS is a cryptographic name derived from a key pair; DNSLink uses ordinary DNS TXT records. They're often combined, a domain's TXT record pointing at an IPNS name, for the benefits of both.

Does AIOZ Pin manage IPNS names for pinned content? No. AIOZ Pin pins by CID, which is immutable. IPNS is a separate, general IPFS technique anyone can layer on top of pinned content themselves if they want one stable address across versions.

Related Reading

• How IPFS Verifies Content Without Trusting the Gateway - the same signature-based trustless verification pattern applied here to names instead of files
• Content Addressing vs. Location Addressing: Why IPFS Needs Pinning - why a CID can never be mutable, the exact problem IPNS exists to solve
• How IPFS Finds and Retrieves Your Files: DHT Provider Records and Bitswap Explained - the DHT mechanism IPNS records are commonly published through
• How IPFS Really Works: Merkle DAGs, Chunking, and Content Routing Explained - the series overview this article builds on
• IPFS Immutability: Why You Can't Edit a File in Place - the underlying problem this article's mutable pointer solves, explained from the immutability side

References

• IPFS Docs: IPNS
• ipfs/kubo Issue #9389: Provider Record Republish and Expiration defaults