Skip to main content

Irys quickstart

Irys makes it easy to store your data onchain by supporting payments with ETH on Linea. With a single upfront payment, you can upload data, with guaranteed retrieval for a duration you set at the upload time — from a few days to forever.

Irys SDK​

Install the SDK​

Install using npm:

npm install @irys/upload @irys/upload-ethereum

or yarn:

yarn add @irys/upload @irys/upload-ethereum

Import​

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

Connect to Irys​

On the server​

When connecting to Irys on the server, provide a private key linked to a wallet funded with linea-eth. This wallet will be used to pay for uploads and to sign transactions.

Using ETH on Linea:

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

Or use the Irys devnet with Linea Sepolia ETH:

Uploads to the Irys devnet are purged after 60 days

const getIrysUploader = async () => {
  const providerUrl = "https://rpc.sepolia.linea.build";
  const irysUploader = await Uploader(Ethereum)
    .withWallet(process.env.PRIVATE_KEY)
    .withRpc(rpcURL)
    .devnet();
 
  return irysUploader;
};

In the browser​

When using Irys in the browser, the wallet browser extension injects a signer into the browser. This signer is used to pay for uploads and sign transactions.

Irys supports:

  • Ethers v5
  • Ethers v6
  • Viem v2
  • Privy

The following code example is for Ethers v6. For other providers, see Irys's docs.

import { WebUploader } from "@irys/web-upload";
import { WebLineaEth } from "@irys/web-upload-ethereum";
import { EthersV6Adapter } from "@irys/web-upload-ethereum-ethers-v6";
import { ethers } from "ethers";
 
const getIrysUploader = async () => {
  const provider = new ethers.BrowserProvider(window.ethereum);
  const irysUploader = await WebUploader(WebLineaEth).withAdapter(EthersV6Adapter(provider));
 
  return irysUploader;
};

Fund your account​

When you use Irys to upload data, you pay once and the data is guaranteed to be retrievable forever. The fee is based on the number of bytes uploaded.

When calling fund() pass a value in atomic units. Use the utility functions utils.toAtomic() and utils.fromAtomic() to convert between atomic and standard units.

You can fund up-front, allowing you send over enough tokens to cover all of a project’s uploads.

try {
  const irysUploader = await getIrysUploader();

  const fundTx = await irysUploader.fund(irysUploader.utils.toAtomic(0.05));
  console.log(
    `Successfully funded ${irysUploader.utils.fromAtomic(fundTx.quantity)} ${
      irysUploader.token
    }`,
  );
} catch (e) {
  console.log("Error funding node ", e);
}

Or lazy-fund and fund per upload:

try {
  const irysUploader = await getIrysUploader();

  const pathToFile = "./myNFT.png";
  const { size } = await fs.promises.stat(pathToFile);
  const price = await irysUploader.getPrice(size);
  await irysUploader.fund(price);

  const { id } = await irysUploader.uploadFile(pathToFile);
  console.log(`${pathToFile} --> Uploaded to https://gateway.irys.xyz/${id}`);
} catch (e) {
  console.log("Error funding node ", e);
}

Upload data​

const uploadData = async () => {
  const irys = await getIrysUploader();
  const dataToUpload = "GM world.";
  try {
    const tags = [{ name: "Content-Type", value: "text/plain" }];

    const receipt = await irys.upload(dataToUpload, { tags });
    console.log(`Data uploaded ==> https://gateway.irys.xyz/${receipt.id}`);
  } catch (e) {
    console.log("Error uploading data ", e);
  }
};

Upload a file​

const uploadFile = async () => {
  const irys = await getIrysUploader();
  const fileToUpload = "./myImage.png";

  const tags = [{ name: "application-id", value: "MyNFTDrop" }];

  try {
    const receipt = await irys.uploadFile(fileToUpload, { tags: tags });
    console.log(`File uploaded ==> https://gateway.irys.xyz/${receipt.id}`);
  } catch (e) {
    console.log("Error uploading file ", e);
  }
};

Upload a folder​

You can upload a group of files as a single transaction from both the server and the browser.

On the server​

const uploadFolder = async () => {
  const irysUploader = await getIrysUploader();

  // Upload an entire folder
  const folderToUpload = "./my-images/"; // Path to folder
  try {
    const receipt = await irysUploader.uploadFolder("./" + folderToUpload, {
      indexFile: "", // Optional index file (file the user will load when accessing the manifest)
      batchSize: 50, // Number of items to upload at once
      keepDeleted: false, // Whether to keep now deleted items from previous uploads
    });

    console.log(`Files uploaded. Manifest ID ${receipt.id}`);
  } catch (e) {
    console.log("Error uploading file ", e);
  }
};

In the browser​

const irysUploader = await getIrysUploder();

const files: File[] = [];
const tags: { name: string, value: string }[][] = [];

// Convert Files to TaggedFiles
const taggedFiles = files.map((f: TaggedFile, i: number) => {
  f.tags = tags[i];
  return f;
});

const response = await irysUploader.uploadFolder(taggedFiles);

Irys CLI​

Install the CLI​

Install using npm with the -g global flag.

npm i -g @irys/cli

Depending on your setup, you may need to use the sudo command.

sudo npm i -g @irys/cli

Use private keys​

When executing CLI commands involving funding nodes or signing transactions, you must provide a private key.

Use the -w flag to specify a private key along with the -t flag to indicate the token you'll use.

irys -w <wallet-file-name> -t linea-eth

Devnet​

To use Irys's devnet where uploads are kept for ~60 and you pay with Linea Sepolia ETH, append -n devnet to any of the commands below.

Fund a node​

Use the fund command to fund a node.

irys fund 1000000000000000 \
  -t linea-eth \
  -w bf20......c9885307

Withdraw funds​

Use the withdraw command to withdraw funds from a node.

irys withdraw 1000000000000000 \
  -t linea-eth \
  -w bf20......c9885307

Upload a file​

Use the upload command to upload a file.

irys upload myImage.png \
  -t linea-eth \
  -w bf20......c9885307 \
  --tags tagName1 tagValue1 tagName2 tagValue2

Upload a folder​

Use the upload-dir command to upload a folder.

irys upload-dir ./myImages \
  -t linea-eth \
  -w bf20......c9885307

Use tags​

Use the -t option, followed by a series of name / value pairs to append metadata tags to your upload.

Irys supports adding any optional metadata tags to each upload. When uploading files with a filename extension, the related Content-Type (MIME type) tag is automatically added.

irys upload myImage.png \
  -t linea-eth \
  -w bf20......c9885307 \
  --tags tagName1 tagValue1 tagName2 tagValue2

Pricing​

Use the price command, followed by a number of bytes to get the cost to upload that number of bytes. You must also provide a token (-t) and a node URL (-h)

irys price 1000000 \
  -t linea-eth \
  -n devnet \
  --provider-url https://rpc.sepolia.dev

Download data​

When you upload data to Irys, you're given a receipt containing a transaction ID. Use this ID to download your data from the Irys gateway by creating a URL in the format:

https://gateway.irys.xyz/:txId