Onchain Storage

Migrating to the Irys L1

The Irys upload SDK provides a core package and payment-token adapters. This guide shows the package and configuration changes for integrations moving from the older SDK to the current upload packages.

Start by identifying your application's existing endpoint and intended storage network. uploader.irys.xyz sends new uploads to Irys L1 mainnet. The legacy endpoints node1.irys.xyz and mainnet.arweave.irys.xyz send uploads to Arweave and will be retired on 1 November 2026.

If future uploads should go to Irys L1, configure the supported Irys L1 bundler and test the integration. If your application requires future uploads to remain on Arweave, choose and validate an Arweave-compatible upload path before the retirement date. Switching to the Irys L1 endpoint changes the destination for new uploads.

An SDK migration does not move historical data between networks. Before rollout, verify existing transaction IDs, retrieval URLs and new-upload behavior for your application. Do not assume testnet data has become permanent mainnet data.

This migration guide covers storage uploads. Programmable Data, the native contract-read interface, is coming soon; see Programmable Data status for its current state.

NodeJS Migration

Before:

import Irys from "@irys/sdk";

const getIrys = async () => {
  const irys = new Irys({
    network: "mainnet",
    token: "ethereum",
    key: process.env.PRIVATE_KEY,
  });
  return irys;
};

After:

import { Uploader } from "@irys/upload";
import { Ethereum } from "@irys/upload-ethereum";

const getIrysUploader = async () => {
  const irysUploader = await Uploader(Ethereum).withWallet(process.env.PRIVATE_KEY);
  return irysUploader;
};

Note

The above code is for ethereum only, we also have examples covering all supported tokens.

Browser Migration

Before:

import { WebIrys } from "@irys/sdk";
import { ethers } from "ethers";

const getWebIrys = async () => {
  await window.ethereum.enable();
  const provider = new providers.Web3Provider(window.ethereum);
  const wallet = { rpcUrl: rpcUrl, name: "ethersv5", provider: provider };
  const webIrys = new WebIrys({ network: "mainnet", token: "ethereum", wallet });
  await webIrys.ready();

  return webIrys;
};

After:

import { WebUploader } from "@irys/web-upload";
import { WebEthereum } from "@irys/web-upload-ethereum";
import { EthereumEthersv5 } from "@irys/web-upload-ethereum-ethers-v5";

const getIrysUploader = async () => {
  const provider = new ethers.providers.Web3Provider(window.ethereum);
  const irysUploader = await WebUploader(WebEthereum).withProvider(EthereumEthersv5(provider));
  return irysUploader;
};

Note

The above code is for ethereum with ethers v5 only, we also have examples covering all supported tokens and providers.

Need help or have questions? Come find us in Discord.