Onchain Storage

Guides

Practical guides for building with Irys, covering framework integration, NFT workflows, DePIN data storage, AI prompt archiving, balance monitoring, and encryption.

Using Irys With React (create-react-app)

Integrate Irys into a React project created with npx create-react-app. This setup requires additional webpack configuration for polyfills.

Create a new React project:

mkdir irys-react
cd irys-react
npx create-react-app .

Install Irys dependencies:

npm install \
  @irys/web-upload \
  @irys/web-upload-ethereum \
  @irys/web-upload-ethereum-ethers-v6 \
  ethers@6 \
  axios

Install polyfill tools:

npm install react-app-rewired
npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process
npm install browserify-zlib path-browserify path
npm install node-polyfill-webpack-plugin --save-dev

Create a config-overrides.js at the project root to configure polyfills for Node.js modules (crypto, stream, buffer, path, etc.). Then update your package.json scripts to replace react-scripts with react-app-rewired for the start, build, and test commands.

Note

For Vite-based React projects, polyfills are handled differently. See the Vite guide below.

Using Irys With React + Vite

Set up Irys in a React project using Vite. Vite does not automatically polyfill Node.js core modules like crypto, stream, os, or path.

Initialize a new Vite project, then install dependencies:

npm install \
  @irys/web-upload \
  @irys/web-upload-ethereum \
  @irys/web-upload-ethereum-ethers-v6 \
  ethers@6 \
  axios

Install the required polyfill packages and update vite.config.js to incorporate vite-plugin-node-polyfills with specific globals and module aliases. Restart the development server with npm run dev.

Storing DePIN Data

DePIN networks require trustworthy data infrastructure. Irys enables permanent onchain storage with millisecond-accurate timestamps, allowing protocols to verify data integrity, prevent tampering, and maintain chronological ordering across any blockchain.

Upload DePIN data (such as weather sensor readings) using the CLI or SDK. Tag uploads with metadata like device-id, data-type, and location for searchable organization. Query stored data using GraphQL to search for specific tags and order results by timestamp.

Storing AI Prompts

Irys enables permanent onchain storage of AI prompts and results with signed receipts containing millisecond-accurate timestamps, creating verifiable and immutable audit trails.

Intellectual property protection
Records prove which specific inputs generated particular outputs against specific models, helping resolve IP disputes.
Model evolution and accountability
Since AI models change through updates and retraining, storing prompts with metadata preserves the conditions under which outputs were generated.
Compliance and transparency
Organizations may soon need to demonstrate how and why AI-generated content was created for regulatory compliance.

For large outputs like images or videos, storing a hash rather than the full content is more efficient. Upload JSON objects via the Irys CLI or SDK.

Monitor Account Balance

Track your Irys account balance using JavaScript, CLI with bash scripts, or cURL requests. This is useful because Irys's upfront funding model lets you pre-fund uploads.

JavaScript
Use getLoadedBalance() and utils.fromAtomic() to check balance, with setInterval() for periodic monitoring.
CLI bash script
Call irys balance with a public wallet address. No private key exposure needed. Schedule via cron.
cURL
Make direct HTTP requests to https://<node-address>/account/balance/<token>?address=<address>. No private key or provider URL required.

Uploading NFTs

Store NFT assets permanently and immutably using Irys. NFTs consist of three parts: a smart contract, NFT metadata, and NFT assets. The smart contract stores a pointer to the NFT metadata, and the metadata contains links to the assets.

Upload assets to Irys
Embed asset URLs in NFT metadata
Upload metadata to Irys
Use the metadata URL to mint the NFT

Dynamic NFTs

Dynamic NFTs are non-fungible tokens whose metadata evolves over time. Irys supports this through mutable references: upload an initial transaction, then post new transactions tagged with the root transaction ID. The original URL always resolves to the most recent version. Only the original wallet creator can modify the chain.

Access the mutable reference at https://gateway.irys.xyz/mutable/[TRANSACTION_ID].

Note

Files under 100 KiB incur no upload cost. Additions must be made using the same wallet that created the original transaction.

Encrypting Onchain Data With Lit Protocol

Integrate Lit Protocol (a decentralized key management network) with Irys to create secure, encrypted applications. Lit Protocol enables you to encrypt data and set custom decryption rules, such as owning specific NFTs, maintaining an ERC20 token balance, or any other logic you define. Only users who meet the defined decryption rules can access the data stored on Irys.

Content access gating
Securing DePIN and AI data
Encrypted social media content
Decentralized identity verification
Private data marketplaces
Exclusive NFT creation

The encryption process involves three steps: obtain a wallet signature (AuthSig), define access control conditions, and connect to a Lit node for encryption. Decryption follows the same pattern in reverse. Code examples are available for both Node.js and Next.js/React implementations.

PreviousREST API NextDownloading