Permanent, pay-once decentralized storage network. Data is stored 'forever' (200+ year endowment model). Most apps upload via Irys (formerly Bundlr) for cheap bundled, multi-token-paid uploads.
- 01permanent NFT metadata and media
- 02immutable archival storage
- 03permaweb-hosted frontends
- 04auditable historical records
- 05AO / decentralized compute data layer
- pnpm add @irys/sdk arweave
| Variable | Scope | Description |
|---|---|---|
| IRYS_PRIVATE_KEY | Server | Funded private key (any supported chain — Ethereum, Solana, etc.) used by the Irys node to pay for bundled Arweave uploads. Server-side only. |
| NEXT_PUBLIC_ARWEAVE_GATEWAY | Client | Arweave gateway base URL for reads (e.g. `https://arweave.net` or your own AR.IO gateway). |
For uploads, use Irys (formerly Bundlr) — `@irys/sdk` — instead of writing AR transactions directly. Initialize server-side with `new Irys({ url: 'https://node1.irys.xyz', token: 'ethereum', key: process.env.IRYS_PRIVATE_KEY })`, fund once with `irys.fund(price)`, then `irys.upload(data, { tags: [{ name: 'Content-Type', value: 'application/json' }] })` or `irys.uploadFile(path)` — the returned `id` is the Arweave transaction ID and is permanent. Read via any Arweave gateway: `${NEXT_PUBLIC_ARWEAVE_GATEWAY}/{txId}`. Use the `arweave` package only when you need to query GraphQL (`/graphql`) for tag-based discovery or sign native AR transactions. Always set descriptive tags (`App-Name`, `Content-Type`, `Type`) — they're how anyone (including you) finds your data later.
- ⚑Bundlr was renamed to Irys in 2023 — the old `@bundlr-network/client` package is deprecated. Use `@irys/sdk`. Don't paste pre-2024 Bundlr tutorials.
- ⚑Storage is permanent and immutable — you cannot delete or update. Re-uploading creates a new txId; if your app caches the old id, you've effectively orphaned data. Plan for versioning via tags or a manifest.
- ⚑Pricing is paid up-front per-byte at upload time and depends on the AR price — small files <100KB are free on Irys (free tier), but bulk uploads need a funded balance. Check `irys.getPrice(bytes)` first.
- ⚑Confirmation is two-stage: Irys returns instantly with a receipt, but the data takes ~10–30 minutes to be mined into Arweave and ~1 hour to fully propagate to all gateways. Don't surface the URL to users until you've polled `/{txId}` for 200.
- ⚑Gateway centralization risk — `arweave.net` is the canonical gateway but is operated by a single team; AR.IO is rolling out a decentralized gateway network, but your reads should fall back across gateways.
- ⚑Anything uploaded is public, permanent, and impossible to redact — never upload PII, copyrighted material you don't own, or anything that could be subject to legal removal requests.