IPNS: Immutable Link with Mutable Data in IPFS

IPFS (InterPlanetary File System) is a popular solution for storing NFT files and metadata. One of its main advantages — every file has a unique hash that can not be tampered with. Even a one-pixel change in the image will result in a completely different computed hash.

However, sometimes other business cases require to have an immutable link for mutable data (e.g. saving metadata folder in blockchain but having its contents changed or new information with versions added). In that case, IPNS (InterPlanetary Name System) functionality with an immutable pointer to a mutable object is used.

This short guide will cover IPFS + IPNS API with examples.

IPNS Idea: same link previously pointed to the v1 picture now refers to the v2 file

IPNS API Endpoints

For simplicity, the example will cover two images: pink and red hearts. However, a similar approach can be used for text files (e.g. metadata) and other forms of media.

List of IPFS endpoints used:

• /api/v0/add — adds and pins (unless chosen otherwise) files to IPFS;
• /api/v0/key/gen — generates new IPNS hash based on human-readable key;
• /api/v0/name/publish — links IPNS key to IPFS file.

Steps

Assigning the new key and linking it to the existing IPFS file

STEP 1. Add the first version of the file (using IPFS /add endpoint):

Request example:

/api/v0/add 
#multipart request with added file Heart.png

Result:

{
 "Name": "Heart.png",
 "Hash": "QmZ78EGtbYYjki7sYDZwpgMnhNjo4BoBqj5c3HjVy6o3GZ",
 "Size": "1573"
}

The file can be fetched using any accessible public or local IPFS gateway: https://ipfs.msvstj.com/ipfs/QmZ7…o3GZ

STEP 2. Generate an IPNS key (human-readable form) to create an immutable IPNS hash:

Request example:

/api/v0/key/gen?arg=<ipns_human_readable_key*>

*ipns_human_readable_key = heart

Result:

{
 "Name": "heart",
 "Id": "k51qzi5uqu5dkipjak3bnm8n5i1fsqbv7w9jjx27bciozowsj84jx8ynnit497"
}

k51qzi…it497 is an immutable link that points to mutable data.

STEP 3. Link the file with the immutable IPNS key:

Request example:

/api/v0/name/publish?arg=<file_hash*>&key=<ipns_human_readable_key**>

*file_hash = QmZ78EGtbYYjki7sYDZwpgMnhNjo4BoBqj5c3HjVy6o3GZ
**ipns_human_readable_key = heart

Result (might take a while):

{
 "Name": "k51qzi5uqu5dkipjak3bnm8n5i1fsqbv7w9jjx27bciozowsj84jx8ynnit497",
 "Value": "/ipfs/QmZ78EGtbYYjki7sYDZwpgMnhNjo4BoBqj5c3HjVy6o3GZ"
}

The immutable link will look like this:
https://domain.name/ipns/k51q…it497

STEP 4. To link the immutable key to another file, repeat steps 1 and 3:

Assigning the existing key and linking it to the NEW IPFS file

• Add a new file to IPFS (from step 1). New file hash result:

{
 "Name": "Heart_Red.png",
 "Hash": "QmV25FyEkkyyARdh9praYgmnqhLpA63LpnQu7a2vVX8DzK",
 "Size": "1513"
}

https://ipfs.msvstj.com/ipfs/QmV2…8DzK

• Request key pointer change (from step 3):

/api/v0/name/publish?arg=<file_hash*>&key=heart

*file_hash = QmV25FyEkkyyARdh9praYgmnqhLpA63LpnQu7a2vVX8DzK

IPNS link remains the same, however, it points to the RED heart now:
https://ipfs.msvstj.com/ipns/k51q…nit497

That is it :)

To summarize, in order to have an immutable link — the IPNS key has to be generated. This key can then be linked to any IPFS file or folder. Some points to note:

• The human-readable form of the IPNS key (in this case) is “heart’ and it is used for API requests;
• Non-human-readable IPNS key (in this case) is k51qzi5uqu5dm5eqc9xi8owbejz4i2ynt1c0jkkyub9rs84fmu8ocp4rqogv8p and it is used as a link to retrieve content.

Thank you for reading, hope this was helpful to some :) Next time will cover other IPFS functionality that might help manage a large amount of data files.

References and Links

1. InterPlanetary File System website: https://ipfs.tech/
2. InterPlanetary Name System documentation: https://docs.ipfs.tech/concepts/ipns/
3. IPFS Pink Image Example: https://ipfs.msvstj.com/ipfs/QmZ78EGtbYYjki7sYDZwpgMnhNjo4BoBqj5c3HjVy6o3GZ
4. IPNS Link Example: https://ipfs.msvstj.com/ipns/k51qzi5uqu5dkipjak3bnm8n5i1fsqbv7w9jjx27bciozowsj84jx8ynnit497