One of the main benefits of the InterPlanetary File System (IPFS) is its immutability. Content Identifiers (CIDs) are powerful primitives, and it’s exactly what we’ve built Pinata’s entire business around. And you know what they say? When you’ve got a good thing going, change it.

No one says that, and we’re not actually changing the core principles of IPFS and immutability. We are, however, acting on years of customer research to introduce a new way to give IPFS CIDs mutable properties. Starting today, customers on our paid plans can install a new Gateway Plugin called Hot Swaps. Hot Swaps will allow you to replace the underlying content associated with a CID with another file.

What Exactly Is Hot Swaps?

If you install the Hot Swaps Gateway Plugin, you will be able to map a CID to another CID. This can be done in the web app, or it can be done programmatically through the API. In the web app, navigate to the Files page, click the context menu, and click the Swap button.

A CID can only be mapped to one other CID at a time. If you have a CID mapped already and choose another CID as the target, it will replace the old target.

If you’re a developer using our API, you can programmatically update the contents of a CID with a simple API call.

In either case, every time the file is loaded through the Dedicated Gateway on which you’ve installed the plugin, the mapped content will be retrieved instead of the original file.

Why Is This Important?

While content addressability and immutability are important, the practical requirements of app development often demand being able to change things. Historically, developers would have to store a reference to their files somewhere else and they’d upload the new content, update the reference, then load the content from the new reference point. This adds latency to applications.

Being able to track the original CID while allowing the underlying content to be updated is a compromise that provides the benefits of auditability and mutability. In practice, it creates a fantastic developer experience and end user experience.

Imagine this scenario: A developer has built a notes app. Each note is stored as a file on the IPFS network, but the developer also stores an index file on IPFS. The index file has metadata about every note. Things like:

[{
  name: "My note", 
  updated_at: "01-08-24", 
  tags: ["pets"], 
  cid: "Qm..."
}]

Every time a user adds a new note, updates an existing note, or deletes a note, that index file needs to be updated and stored on IPFS. Then the developer has to update their code to pull from the new file’s CID.

With Hot Swaps, the developer could hardcode the original reference CID and use Hot Swaps to update the underlying file that CID points to. This makes the developer’s life easier and improves app performance by reducing latency.

Doesn’t This Break IPFS?

Hot Swaps is a Gateway-level plugin. That means it only impacts the Gateway the plugin is installed on. Everyone else’s Dedicated Gateways and Public IPFS Gateways are not impacted. Additionally, when a Hot Swap plugin is installed and the content being retrieved has been mapped, a header is sent in the file’s response that indicates what the currently mapped CID is.

This is an entirely opt-in solution, so it doesn’t break the underlying properties of IPFS. Much like Gateway Access Controls are a feature on top of IPFS gateways, Hot Swaps is a layer that can be used or ignored.

Next Steps

Developers can start using Hot Swaps today. We already know plenty of you have use cases for this. Go out and build, but please share the results. We want to see your creativity. You can find the docs here.

Happy Swapping!