IPNS

Principles of the InterPlanetary Naming System (IPNS)

January 21, 2021

IPFS uses content-based addressing to create an address of an object added on the network. This address or CID, a long string of seemingly random numbers and letters, is generated from the content of the object. If you were to share the IPFS address /ipfs/QmbezGequPwcsWo8UL4wDF6a8hYwM1hmbzYv2mnKkEWaUp with someone, not only is it hard to read, but you need to give the person a new link everytime you update the content.

The InterPlanetary Naming System (IPNS) solves these issues by creating, reading, and updating mutable addresses. IPNS consists of a public/private asymmetric cryptographic key pair, a record type and a protocol. The protocol involves a routing layer that is used for the distribution and discovery of new or updated IPNS records.

Structure of an IPNS Record

An IPNS record is a data structure containing the following fields:

  • privateKey (PrivKey RSA Instance): is the key to be used for cryptographic operations.
  • value (string): the ipfs path of the object to be published.
  • sequenceNumber (Number): is the number representing the current version of the record.
  • lifetime (string): is the lifetime of the record (in milliseconds).
  • expiration (Date): is the date object for the record's End-of-Life/EOL.
  • publicKey (PubKey RSA Instance): key to be used for cryptographic operations.

These records are stored locally, as well as republished by peers other than the peer that originated the record. This implies that as long as a peer has an IPNS record it can be made available to other peers.

Currently you can create two types of IPNS records, a _lifetime_ record or a record _with_expiration. On the IPNS node module for example, a lifetime record is created using the function: 

ipns.create(privateKey, value, sequenceNumber, lifetime, [callback])

while an IPNS record with expiration is created using the function:

ipns.createWithExpiration(rsa, value, sequenceNumber, expiration, [callback])

where the callback (function) is the operation result.

IPNS can also validate a record using the function:

ipns.validate(publicKey, ipnsEntry, [callback])

where ipnsEntry (Object) is the ipns entry record (obtained using the create function) and `callback (function)` is the operation result.

This structured data is stored using Protocol Buffers which is a language-neutral, platform neutral extensible mechanism for serializing structured data.

Working with IPNS

IPNS provides a transport-agnostic and self-certifying way to resolve a name to the most recent content published. A name in IPNS is the hash of a public key. It is associated with a record containing information about the hash it links to that is signed by the corresponding private key. New records can be signed and published at any time.

In both publish and resolve, the default name used is the node's own PeerID, which is the hash of its public key.

Publish with IPNS

IPNS is accessible through the IPFS CLI, the command to publish an object takes the format ipfs name publish _ipfs-path_ which returns the output Published to _peer-id_: /ipfs/_ipfs-path_. For instance if you want to publish an object mysite with the CID QmatmE9msSfkKxof9Bud6YoPab52vpyfpHwNLNKgwZG8eT run the command: 

ipfs name publish QmatmE9msSfkKxof9Bud6YoPab52vpyfpHwNLNKgwZG8eT

this will run for a few minutes and return:

Published to QmSrPmbaUKA3ZodhzPWZnpFgcPMFWF4QsxXbkWfEptTBJd: 
/ipfs/QmatmE9msSfkKxof9Bud6YoPab52vpyfpHwNLNKgwZG8eT

Resolve using IPNS

If you need to change or update the content on your site, add the new site version to ipfs and publish it again. You can do this by running: 

ipfs add -r my-site/
ipfs name publish _new-cid_

You can check the current CID linked to your peerID by running the command:

ipfs name resolve QmSrPmbaUKA3ZodhzPWZnpFgcPMFWF4QsxXbkWfEptTBJd

which returns the link to your latest published site with the format

/ipfs/QmSiTko9JZyabH56y2fussEt1A5oDqsFXB3CkvAqraFryz

You can also resolve the value of other names or PeerIDs using the same command ipfs name resolve _peerId_.

When looking up an IPNS address, use the /ipns/ prefix, for instance:

/ipns/QmSrPmbaUKA3ZodhzPWZnpFgcPMFWF4QsxXbkWfEptTBJd

In the same way, you can republish a new version of your website under the same address. By default, ipfs name publish will use the Peer ID for updating the IPNS record.

IPNS can also resolve IPFS sites mapped to domains like .eth, .crypto, and .zil. To resolve a site mapped on .eth for instance, simply run: 

ipfs resolve -r /ipns/RandomPlanetFacts.eth
> /ipfs/QmW7S5HRLkP4XtPNyT1vQSjP3eRdtZaVtF6FAPvUfduMjA

Using IPFS Key

You can also use different keys for different content and/or contexts. For example, you could publish a website using one key, and a blog using another. Use the ipfs key command to list and generate more names and their respective keys.

To generate a new key for an object, myblog run the command:

ipfs key gen --type=rsa --size=2048 myblog

This will generate a 2048 bit RSA keypair and the resulting hash will be associated with the object to publish.

You can publish the object myblog using the command:

ipfs name publish --key=myblog _cid-to-myblog_

Example:

$ ipfs key gen --type=rsa --size=2048 myblog
$ ipfs name publish --key=myblog /ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
Published to QmSrPmbaUKA3ZodhzPWZnpFgcPMFWF4QsxXbkWfEptTBJd: 
/ipfs/QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy

Alternatives to IPNS

IPNS is not the only way to create mutable addresses on IPFS. Work is still going on to optimize naming in IPFS and enable browsing of /ipfs and /ipns paths. Some services have already launched efforts to bridge this gap.

Opera for Android has added built-in default support for IPFS with a native handler for ipfs:// addresses that redirects to the HTTP gateway of your choosing. You can register decentralized domain names that map to IPFS addresses using services like Unstoppable Domains or the Ethereum Name System (ENS).

You can also use DNSLink, which is currently much faster than IPNS and also uses more human-readable names. You can find additional resources to familiarize with IPNS at: