Irys 完整工具箱

🇺🇸 English | 🇨🇳 中文

Irys（前身为 Bundlr）完整工具箱，这是一个功能全面的一站式工具包，用于与世界首个可编程数据链进行交互。本工具箱提供了将永久数据存储集成到您的应用程序中所需的一切功能。 效果图：

🌟 功能特色

• 🔧 完整的 SDK 支持: 支持所有 Token 的 Node.js 和浏览器 SDK
• ⚛️ React 集成: 为 React 开发提供的 Hooks 和组件
• 🗃️ GraphQL 客户端: 具有分页和过滤功能的高级查询能力
• 🌐 REST API 客户端: 完整的 REST API 集成，带有错误处理
• 💻 CLI 包装器: 对 Irys CLI 操作的编程访问
• 🛠️ 实用函数: 数据处理、验证、格式化等功能
• 📱 多链支持: 支持 Ethereum、Solana、Polygon、Arbitrum 等 17+ 种区块链
• 🎨 NFT 工具: NFT 元数据和铸造的专用实用程序
• 🔄 可变引用: 支持可更新内容
• 💰 余额管理: 资金、授权和余额检查

🚀 快速开始

🌐 网页演示 (小白推荐)

最简单的开始方式 - 零编程知识要求！

# 一键启动网页演示
npm run web-demo

# 启动并自动打开浏览器  
npm run web-demo:open

访问 http://localhost:3000 查看完整的交互式演示！

✨ 网页演示特色:

• 🎯 小白友好 - 点击即用，可视化界面
• 🛠️ 实时测试 - 在线测试所有工具函数
• 📚 完整教程 - 涵盖所有功能和使用方法
• 🎮 交互体验 - 无需编程即可体验 Irys 强大功能

📦 安装

# 基础安装
npm install irys-complete-toolkit

# 构建项目
npm run build

🔧 环境配置

重要: 使用官方 Irys 公共节点

# 复制环境变量模板
cp env.example .env

# 编辑 .env 文件，添加您的私钥

推荐配置:

# 使用官方 Irys 公共节点（推荐）
IRYS_RPC_URL=https://node1.irys.xyz

# 添加您的私钥（测试网络）
ETHEREUM_PRIVATE_KEY=your_ethereum_private_key_here
SOLANA_PRIVATE_KEY=your_solana_private_key_here

📋 可用脚本

# 🌐 网页演示
npm run web-demo              # 启动网页演示 (推荐!)
npm run web-demo:open         # 启动并打开浏览器

# 📝 示例脚本
npm run example:node          # Node.js 完整功能演示
npm run example:sdk           # SDK 核心功能演示
npm run example:utils         # 工具函数演示
npm run example:clients       # API 客户端演示
npm run example:types         # TypeScript 类型演示
npm run example:cli           # CLI 使用示例
npm run example:react         # React 设置指南

# 🛠️ 开发工具
npm run build                 # 构建 TypeScript
npm run dev                   # 监听模式构建
npm run test                  # 运行测试
npm run lint                  # 代码检查

# 📦 安装选项
npm run install:basic         # 基础安装（无可选依赖）
npm run install:react         # React 相关依赖
npm run install:solana        # Solana 钱包适配器
npm run install:aptos         # Aptos 钱包适配器
npm run install:all           # 所有可选依赖

💰 支持的 Token (17种)

| 区块链 | Token | 符号 | 精度 | 类型 | |--------|-------|------|------|------| | Ethereum | Ethereum | ETH | 18 | EVM | | Polygon | Polygon | MATIC | 18 | EVM | | Arbitrum | Arbitrum | ETH | 18 | EVM | | Avalanche | Avalanche | AVAX | 18 | EVM | | BNB Chain | BNB | BNB | 18 | EVM | | Base | Base | ETH | 18 | EVM | | Linea | Linea | ETH | 18 | EVM | | Scroll | Scroll | ETH | 18 | EVM | | IoTeX | IoTeX | IOTX | 18 | EVM | | Solana | Solana | SOL | 9 | Solana | | Aptos | Aptos | APT | 8 | Aptos | | Near | Near | NEAR | 24 | Near | | Algorand | Algorand | ALGO | 6 | Algorand | | USDC (Ethereum) | USDC | USDC | 6 | ERC20 | | USDC (Polygon) | USDC | USDC | 6 | ERC20 | | USDC (Solana) | USDC | USDC | 6 | SPL |

🔧 使用示例

Node.js SDK

const { createNodeSDK } = require('irys-complete-toolkit');

// 创建 SDK 实例
const irys = createNodeSDK({
  token: 'ethereum',
  network: 'devnet',
  privateKey: process.env.ETHEREUM_PRIVATE_KEY,
  rpcUrl: 'https://node1.irys.xyz'
});

// 初始化
await irys.ready();

// 上传数据
const receipt = await irys.upload("Hello Irys!", {
  tags: [
    { name: "Content-Type", value: "text/plain" },
    { name: "App-Name", value: "My-App" }
  ]
});

console.log(`上传成功! 访问: https://gateway.irys.xyz/${receipt.id}`);

Web SDK (浏览器)

import { createWebSDK } from 'irys-complete-toolkit';

// 连接钱包
const irys = createWebSDK({
  token: 'ethereum',
  network: 'devnet',
  wallet: window.ethereum,
  rpcUrl: 'https://node1.irys.xyz'
});

await irys.ready();

// 上传文件
const file = document.getElementById('file-input').files[0];
const receipt = await irys.uploadFile(file);
console.log(`文件已上传: ${receipt.id}`);

GraphQL 查询

const { createGraphQLClient } = require('irys-complete-toolkit');

const client = createGraphQLClient();

// 查询最近的交易
const result = await client.query(`
  query {
    transactions(first: 10, order: DESC) {
      edges {
        node {
          id
          owner
          tags {
            name
            value
          }
        }
      }
    }
  }
`);

工具函数

const { Formatter, Validator, DataProcessor } = require('irys-complete-toolkit');

// 格式化金额
const formatted = Formatter.formatTokenAmount('1000000000000000000', 18);
console.log(formatted); // "1 ETH"

// 验证地址
const isValid = Validator.isValidAddress('0x...', 'ethereum');
console.log(isValid); // true/false

// 处理数据
const size = DataProcessor.getDataSize('Hello World');
const contentType = DataProcessor.guessContentType('data.json');

🎨 NFT 工作流程

// 1. 上传图片
const imageFile = document.getElementById('image').files[0];
const imageReceipt = await irys.uploadFile(imageFile);

// 2. 创建元数据
const metadata = {
  name: "我的 NFT",
  description: "使用 Irys 创建",
  image: `https://gateway.irys.xyz/${imageReceipt.id}`,
  attributes: [
    { trait_type: "Framework", value: "Irys" },
    { trait_type: "Chain", value: "Ethereum" }
  ]
};

// 3. 上传元数据
const metadataReceipt = await irys.upload(JSON.stringify(metadata), {
  tags: [
    { name: "Content-Type", value: "application/json" },
    { name: "App-Name", value: "NFT-Creator" }
  ]
});

console.log(`NFT 元数据: https://gateway.irys.xyz/${metadataReceipt.id}`);

🔄 可变引用

// 创建可更新的数据引用
const data1 = { version: 1, content: "初始内容" };
const receipt1 = await irys.upload(JSON.stringify(data1), {
  tags: [
    { name: "Root-TX", value: "my-app-data" },
    { name: "Content-Type", value: "application/json" }
  ]
});

// 更新数据（使用相同的 Root-TX）
const data2 = { version: 2, content: "更新内容" };
const receipt2 = await irys.upload(JSON.stringify(data2), {
  tags: [
    { name: "Root-TX", value: "my-app-data" },
    { name: "Content-Type", value: "application/json" }
  ]
});

// 访问最新版本
const latestUrl = `https://gateway.irys.xyz/mutable/my-app-data`;

⚛️ React 集成

import { useIrys, IrysUploader } from 'irys-complete-toolkit';

function MyApp() {
  const { irys, connect, isConnected, upload } = useIrys({
    token: 'ethereum',
    network: 'devnet'
  });

  return (
    <div>
      {!isConnected ? (
        <button onClick={connect}>连接钱包</button>
      ) : (
        <IrysUploader
          onUpload={(receipt) => console.log('上传成功:', receipt)}
          acceptedFileTypes={['image/*', 'text/*']}
        />
      )}
    </div>
  );
}

🌐 API 客户端

REST API

const { createRestClient } = require('irys-complete-toolkit');

const client = createRestClient();

// 获取节点信息
const info = await client.getInfo();

// 查询价格
const price = await client.getPrice(1024); // 1KB

// 查询余额
const balance = await client.getBalance('0x...');

GraphQL 高级查询

// 按标签查询
const transactions = await client.getTransactionsByTags([
  { name: "Content-Type", values: ["image/png"] },
  { name: "App-Name", values: ["MyApp"] }
]);

// 按所有者查询
const userTxs = await client.getTransactionsByOwner('0x...');

// 按ID批量查询
const specificTxs = await client.getTransactionsByIds(['tx1', 'tx2']);

💻 CLI 使用

const { createCLI } = require('irys-complete-toolkit');

const cli = createCLI();

// 查询余额
await cli.balance('ethereum');

// 上传文件
await cli.upload('./file.txt', {
  token: 'ethereum',
  tags: [{ name: "App-Name", value: "CLI-Tool" }]
});

// 资金充值
await cli.fund('0.1');

🛠️ 高级功能

批量上传

const files = ['file1.txt', 'file2.jpg', 'file3.json'];
const receipts = [];

for (const file of files) {
  const data = fs.readFileSync(file);
  const receipt = await irys.upload(data, {
    tags: [
      { name: "File-Name", value: path.basename(file) },
      { name: "Batch-Upload", value: "true" }
    ]
  });
  receipts.push(receipt);
}

文件夹上传

// 上传文件夹结构
const folderManifest = {
  "index.html": "QmHash1...",
  "style.css": "QmHash2...",
  "script.js": "QmHash3..."
};

const manifestReceipt = await irys.upload(JSON.stringify(folderManifest), {
  tags: [
    { name: "Type", value: "manifest" },
    { name: "Folder-Name", value: "my-website" }
  ]
});

错误处理

try {
  const receipt = await irys.upload(data);
  console.log('上传成功:', receipt.id);
} catch (error) {
  if (error.name === 'InsufficientFundsError') {
    console.log('余额不足，需要充值');
  } else if (error.name === 'NetworkError') {
    console.log('网络错误，请重试');
  } else {
    console.log('未知错误:', error.message);
  }
}

📊 性能优化

数据压缩

import { gzip } from 'zlib';
import { promisify } from 'util';

const gzipAsync = promisify(gzip);

// 压缩大文件
const data = fs.readFileSync('large-file.json');
const compressed = await gzipAsync(data);

const receipt = await irys.upload(compressed, {
  tags: [
    { name: "Content-Type", value: "application/json" },
    { name: "Content-Encoding", value: "gzip" }
  ]
});

并发上传

const uploadPromises = files.map(file => 
  irys.upload(file.data, { tags: file.tags })
);

const receipts = await Promise.all(uploadPromises);

🔒 安全最佳实践

1. 私钥管理

   • 使用环境变量存储私钥
   • 测试网络使用测试私钥
   • 生产环境使用硬件钱包

2. 数据验证

   • 上传前验证数据完整性
   • 使用适当的 Content-Type
   • 验证文件大小限制

3. 网络配置

   • 使用官方节点: https://node1.irys.xyz
   • 设置适当的超时时间
   • 实现重试机制

📚 文档和资源

• 官方文档
• API 参考
• GitHub 仓库
• Discord 社区

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解详情。

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

🆘 支持

• 📧 邮件: [email protected]
• 💬 Discord: Irys 社区
• 🐛 问题反馈: GitHub Issues

🏷️ 版本历史

v1.0.0

• ✅ 初始发布
• ✅ 支持 17 种区块链 Token
• ✅ 完整的 SDK、API 客户端和工具函数
• ✅ React 集成
• ✅ 网页演示系统
• ✅ CLI 包装器
• ✅ 完整的文档和示例

Made with ❤️ by the Irys Community

Irys - 世界首个可编程数据链，让永久数据存储变得简单。