IPNS Tutorial

Why Should You Use IPNS?

So at this point you're able to add and pin content to the network using IPFS. That works great for something static like an image, but what if the content is expected to change over time?

Remember: a file's content identifier (CID) depends entirely on the 1's and 0's that make up that file; if the file changes at all then the link to that file will change, too. This presents a major problem if you're, say, writing a story that you want feedback on or publishing your blog to IPFS like I am. You don't want to hand out new links to your friends every time you write a new chapter to your book or edit your website's CSS.

IPNS gives us a way to assign a static address to dynamic content.

How Does IPNS work?

Every node on IPFS has a unique PeerID associated with it so that all the nodes on the network know who they're talking to. Really, each node has a public key and a private key (or key-pair) that they use to encrypt content that's sent between nodes; a node's PeerID is just a hash of its public key, but all that's important for us to know right now is that each node can be uniquely identified by other nodes.

IPNS takes advantage of these unique, unchanging identifiers to assign permanent addresses to ever-changing content.

How Do I Use It?

At your terminal, we're going to use the name publish command on a CID to generate a static address. Continuing from part one, if we have the CID /ipfs/QmX2PxhzBKVqnPzx5xAdoJVeSAq5dhKAAXqhPJf7tTQjy5 we'll type:

ipfs name publish /ipfs/QmX2PxhzBKVqnPzx5xAdoJVeSAq5dhKAAXqhPJf7tTQjy5

It may take a minute to create the address, but once it does your terminal should output something like:

Published to k51qzi5uqu5djzb2w72fezpsdcuv0okkp79xxamgumepp9i8bh3vcbfjhd01at: /ipfs/QmX2PxhzBKVqnPzx5xAdoJVeSAq5dhKAAXqhPJf7tTQjy5

You can test to see if this links to your original content by typing ipns://k51qzi5uqu5djzb2w72fezpsdcuv0okkp79xxamgumepp9i8bh3vcbfjhd01at into your IPFS-capable web browser.

Now you can update the content of your file and see if the IPNS name links to the newest version of that file. With your newly updated examplefile.txt you can add it to the network like before:

ipfs add examplefile.txt

Now pin it to your local node.

ipfs pin add QmPkfYbQkGBuSwJwboiXurGW753x5v5dV8ahx6ih28GMa7

And finally publish to IPNS.

ipfs name publish /ipfs/QmPkfYbQkGBuSwJwboiXurGW753x5v5dV8ahx6ih28GMa7

And there we have it: One link that pointed to two different versions of the same file.

Other Upsides

Since your node has a unique PeerID and only you have access to that node, publishing content through IPNS acts as a signature of sorts; meaning no one can falsely attribute content you didn't authorize to you, since they can't publish to your unique IPNS name without your node's unique key-pair.

This system also makes it very cheap and easy to host your content at home, be it a server for hosting your own personal website, streaming downloaded movies to your television, or whatever.

Some Pitfalls

Since IPNS depends on your node's PeerID, you need to publish your updated content to IPFS using the same node each time for the link to stay the same. However, there are ways to migrate your key-pairs to other machines to avoid this problem.

But these IPNS names are long and hard to read. They certainly aren't human-readable like houseofedwards.xyz. Is there any way to assign some sort of domain name to an IPNS address?

Why yes, yes there is. Follow me to my tutorial on the Ethereum Name Service to learn more.