Features

Mutability

Data on Irys is immutable. However, you can simulate mutability using mutable references.

With mutable references, you create a single, static URL linked to a sequential series of transactions. You can add new transactions to the series at any time, and the URL will always resolve to the most recent transaction in the chain.

Creating a Mutable Reference

To create a mutable reference:

1. Upload a base transaction to Irys and reference it using a URL in the following format: https://gateway.irys.xyz/mutable/:txId

Note

Use a token-specific version of getIrysUploader() to connect to an Irys Bundler before uploading. Choose one from the SDK setup documentation.

const irysUploader = await getIrysUploader();
const receiptOne = await irysUploader.upload("First TX");
console.log(`TX 1 uploaded https://gateway.irys.xyz/mutable/${receiptOne.id}`);

2. Upload an addition to the series as a new transaction, and add a tag named Root-TX with the value of the original transaction ID.

const tags = [{ name: "Root-TX", value: receiptOne.id }];
const receiptTwo = await irysUploader.upload("Second TX", { tags: tags });
console.log(`TX 2 uploaded https://gateway.irys.xyz/mutable/${receiptOne.id}`);

The original URL (https://gateway.irys.xyz/mutable/:txId) now resolves to the second transaction in the chain.

Note

Additions must use the same wallet that created the original transaction to prevent unauthorized actors from maliciously modifying someone else's transaction chain.

Granularity

Mutable references are based on Irys's millisecond-accurate timestamps. You can publish multiple sequential updates and be confident the /mutable/ endpoint will always serve the most recent chronological transaction.

Versions

While https://gateway.irys.xyz/mutable/:txId always resolves to the most recent transaction, you can directly access any transaction in a chain using https://gateway.irys.xyz/:id.

Query a version chain using GraphQL:

query getChain {
  transactions(
    tags: [
      {
        name: "Root-TX"
        values: ["WF--VR1ZERvABYy1aNYD3QJ0OAVDSUF8dTlg6zFKveQ"]
      }
    ]
    owners: ["0x591b5ce7ca10a55a9b5d1516ef89693d5b3586b8"]
    order: ASC
  ) {
    edges {
      node {
        id
        timestamp
      }
    }
  }
}

Use Cases

Irys's mutable references open up new opportunities for builders, including:

• Gaming NFTs
  Metadata changes based on in-game actions
• Dynamic NFTs
  Images change based on onchain activity
• Software distribution
  Latest versions available via the same link
• Content publishing / social media
  Users always receive the most recent version
• Website hosting / dApp front-ends
  Updates possible without changing the main URL