textury/arlocal

arlocal

镜像概述和主要用途

arlocal是一个本地Arweave网关类服务器，为Arweave开发提供本地测试环境。它允许开发者在本地模拟Arweave网络，进行交易测试、智能合约部署、GraphQL请求验证等开发工作，无需连接真实Arweave主网，大幅降低开发测试成本。

核心功能和特性

• 极速性能：相比其他测试方案，运行速度显著提升
• 开源免费：社区构建，源代码开放且完全免费使用
• 轻量依赖：仅需NodeJS + NPM环境，无需其他外部资源
• 全面支持：可测试交易、SmartWeave合约、GraphQL请求、NFT部署等多种场景
• 跨平台兼容：支持Windows、Mac、Linux、树莓派等所有安装NodeJS的环境

使用场景和适用范围

• Arweave应用程序开发过程中的本地功能测试
• SmartWeave智能合约的开发、调试与验证
• NFT项目在部署到主网前的本地功能验证
• Arweave交易流程的单元测试和集成测试
• 学习Arweave网络功能的本地实验环境

使用方法和配置说明

作为CLI工具使用

确保已安装NodeJS和NPM环境，通过npx直接运行最新版本：

bash
npx arlocal

默认将在http://localhost:1984启动本地网关服务。

自定义端口

如需指定端口，在命令后添加端口号：

bash
npx arlocal 8080

这将在8080端口启动arlocal服务。

其他选项

• --hidelogs：隐藏arlocal的运行日志输出

作为NodeJS库使用

可将arlocal集成到代码中，确保开发和测试环境一致性。

安装依赖

bash
# 使用yarn
yarn add arlocal -D

# 或使用npm
npm install arlocal --save-dev

基础使用示例

typescript
import ArLocal from 'arlocal';

(async () => {
  // 创建ArLocal实例
  const arLocal = new ArLocal();

  // 启动服务（异步操作）
  await arLocal.start();

  // 执行测试代码...
  console.log(`ArLocal running on http://localhost:${arLocal.port}`);

  // 测试完成后停止服务
  await arLocal.stop();
})();

配置选项

ArLocal类构造函数支持以下可选参数：

typescript
ArLocal(port = 1984, showLogs = true, dbPath = '.db', persist = false)

• port：服务端口，默认为1984
• showLogs：是否显示运行日志，默认为true
• dbPath：数据库临时存储目录，默认为.db
• persist：是否在服务器重启后保留数据，默认为false（不保留）

发送交易流程

1. 铸造AR***：向指定地址铸造AR，访问端点/mint/<address>/<balance>（例如http://localhost:1984/mint/your-wallet-address/1000000000000）

2. 创建并发送交易：使用ArweaveJS创建、签名并发送交易，流程与主网网关完全一致

3. 确认交易：通过访问/mine端点确认（挖矿）交易：

   • 挖矿1个区块：访问http://localhost:1984/mine
   • 挖矿多个区块：访问http://localhost:1984/mine/{blocks}（如/mine/5挖矿5个区块）

Docker部署示例

基本docker run命令

bash
# 默认配置运行（端口1984，显示日志）
docker run -p 1984:1984 node npx arlocal

# 自定义端口运行
docker run -p 8080:8080 node npx arlocal 8080

# 隐藏日志运行
docker run -p 1984:1984 node npx arlocal --hidelogs

docker-compose配置示例

yaml
version: '3'
services:
  arlocal:
    image: node:latest
    container_name: arlocal
    ports:
      - "1984:1984"
    command: npx arlocal
    # 可选：持久化数据（需设置persist=true）
    volumes:
      - ./arlocal-db:/root/.db
    environment:
      - NODE_ENV=development
    restart: unless-stopped

贡献指南

arlocal欢迎社区贡献，帮助完善这一重要开发工具。提交PR前请注意：实现网关路由或现有功能时，需保持与Arweave主网网关相同的路径和默认值（例如/tx路径应保持不变），以减少用户在单元测试与主网交易之间的修改成本。

贡献步骤：

1. Fork本项目
2. 创建特性分支：git checkout -b my-feature
3. 提交修改：git commit -am 'Add some feature'
4. 推送分支：git push origin my-new-feature
5. 提交Pull Request