The Hot Swaps plugin can be used to “redirect” a CID to another CID. This can be useful when you need to replace content without updaing the CID hash.

While it may seem like this undermines the benefits of IPFS’ imutable content system, it should be made clear that this only works on a per gateway level for those who install it. Additionally:

  • Any CID can be called by another gateway to view the original content
  • Pinata has an SDK method and API endpoint that any Pinata user can call to check the history of a swap
  • All gateway requests that have the hot swap plugin installed and are serving a swapped CID will have a header of etag that will have the CID that is currently being directed to.

To demonstrate how this plugin works, consider the following example:

import { PinataSDK } from "pinata-web3";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: "example.mypinata.cloud", // Gateway has Hot Swaps installed
});

async function main() {
  try {
    // Upload the first file
    const file = new File(["The original CID"], "cid.txt", {
      type: "text/plain",
    });
    const { IpfsHash: CID1 } = await pinata.upload.file(file);
    console.log("This is the original CID hash: ", CID1);

    // Upload a second file
    const file2 = new File(["The new CID"], "cid.txt", { type: "text/plain" });
    const { IpfsHash: CID2 } = await pinata.upload.file(file2);
    console.log("This is the new CID hash: ", CID2);

    // Create the swap, so when we visit CID1 we will get the content of CID2
    const swap = await pinata.gateways.swapCid({
      cid: CID1,
      swapCid: CID2,
    });
    console.log("Swap created: ", swap);

    // Fetch CID1 through our gateway that has Hot Swaps installed, get the content of CID2
    const data = await pinata.gateways.get(CID1);
    console.log("Result of requestingt CID1 through the gateway: ", data);
  } catch (error) {
    console.log(error);
  }
}

main();

​
Installation

Follow the steps in the Getting Started guide to install the Hot Swaps Plugin.

​
Usage

After installing the plugin you can then make CID swaps and have them reflect when making Gateway requests. The first parameter cid will be the original CID, and swapCid will be the content you want it to point to instead.

import { PinataSDK } from "pinata-web3";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: "example-gateway.mypinata.cloud",
});

const swap = await pinata.gateways.swapCid({
  cid: "bafkreibbvdqf5ekc2crouowv7vtjbcmbjoiysegslmmqc6jrxbaa43xske",
  swapCid: "bafkreihumyr3bgxulu45ghws33xokwjm5o7xnkkgakaz66ldtylwiecnhu"
})

You can fetch the history of CID swaps using the swapHistory method, passing in the cid of the original CID and the domain of the gateway that has the Hot Swaps plugin installed.

const history = await pinata.gateways.swapHistory({
  cid: "bafkreibbvdqf5ekc2crouowv7vtjbcmbjoiysegslmmqc6jrxbaa43xske",
  domain: "discordpinnie.mypinata.cloud"
})

// [
//   {
//     mappedCid: "bafkreihumyr3bgxulu45ghws33xokwjm5o7xnkkgakaz66ldtylwiecnhu",
//     createdAt: "2024-08-19T14:34:46.492432Z"
//   },
//   { mappedCid: null, createdAt: "2024-08-19T14:25:10.208726Z" },
//   {
//     mappedCid: "bafkreihumyr3bgxulu45ghws33xokwjm5o7xnkkgakaz66ldtylwiecnhu",
//     createdAt: "2024-08-19T00:23:41.755206Z"
//   }
// ]

To delete a CID swap you can simply use the deleteSwap method and pass in the CID.

const deleteSwap = await pinata.gateways.deleteSwap(
  "bafkreibbvdqf5ekc2crouowv7vtjbcmbjoiysegslmmqc6jrxbaa43xske"
)
// OK
Content AddressableWhat is IPFS?