Skip to content
BranchesTags

Repository files navigation

GasFree CLI

命令行工具，用于基于 @gasfree/gasfree-sdk 进行零 Gas 转账。

环境要求

Node.js

本 CLI 需要 Node.js >= 18.19.0。

使用 nvm 管理 Node.js（推荐）：

# 安装 nvm（如果未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 加载 nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh"

# 安装 Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

运行脚本时： 如果使用 nvm，需先加载 nvm：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && source "$NVM_DIR/nvm.sh"
./quick-transfer.sh <address> <amount>

🚀 快速转账脚本

为了方便快速执行转账，我们提供了自动化脚本：

快速开始

# 1. 设置环境变量（首次使用）
source setup-env.sh

# 2. 执行转账（脚本会自动加载 .env 文件）
./quick-transfer.sh <接收地址> <金额(USDT)>

# 示例：转账 10 USDT
./quick-transfer.sh TA4nhXUwmdGeoBh75hDh7LAarKVP1JbjJQ 10

注意: 脚本会自动加载当前目录的 .env 文件，无需手动 source .env。

脚本文件

脚本 说明
quick-activate.sh 🔑 账户激活脚本
quick-transfer.sh ⭐ 简化版转账脚本（推荐）
gasfree-transfer.sh 完整版转账脚本（详细日志）
setup-env.sh 环境变量设置向导
.env.example 环境变量配置示例

安全特性

  • ✅ 强制使用环境变量（拒绝硬编码敏感信息）
  • ✅ 自动验证环境变量配置
  • ✅ .env 文件已在 .gitignore 中排除
  • ✅ 自动设置文件权限（600）

查看 SCRIPTS_GUIDE.md 了解更多。

📚 文档导航

📖 文档索引: docs/DOCS_INDEX.md - 从这里开始

👤 用户文档

文档 说明 适合人群
docs/USER_GUIDE.md 📖 完整使用说明 所有用户（首选）
docs/SCRIPTS_GUIDE.md ⭐ 脚本快速指南 脚本用户

👨‍💻 技术文档

文档 说明 适合人群
docs/TECHNICAL_DOCS.md 🔧 技术文档（架构、API、安全） 开发者/架构师
docs/API_REFERENCE.md 📖 Provider API 参考手册 集成开发者
docs/DEVELOPER_GUIDE.md 👨‍💻 开发者快速入门 贡献者

⚙️ 配置文件

文件 说明
.env.example 环境变量配置模板
docs/DOCS_INDEX.md 📚 文档索引

自动加载环境变量

CLI 会自动从以下位置加载 .env 文件（按优先级）：

  1. 当前工作目录 .env
  2. CLI 安装目录 .env

设置方法：

# 1. 复制示例文件
cp .env.example .env

# 2. 编辑 .env 文件
vim .env

# 3. 直接使用 CLI（无需 source .env）
node dist/index.js query tokens --chain nile

环境变量列表：

# GasFree API 凭证
GASFREE_API_KEY=your_api_key_here
GASFREE_API_SECRET=your_api_secret_here

# 私钥（可选，也可使用交互式输入）
GASFREE_PRIVATE_KEY=your_private_key_here

安装

cd cli
npm install

构建

npm run build

使用方法

全局安装（可选）

npm link

安装后可以直接使用 gasfree 命令。

命令

1. 转账命令 transfer

创建 GasFree 转账交易。

交互式模式（推荐）：

gasfree transfer

命令行参数模式：

gasfree transfer \
  --chain nile \
  --token TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf \
  --receiver TJM1BE5wq1VdHh3gwjUeyaVkvZp9DVYCfC \
  --amount 100.5 \
  --decimals 6

使用环境变量：

export GASFREE_PRIVATE_KEY=your_private_key
gasfree transfer --token TXYZ... --receiver TJM1... --amount 100

参数说明：

-c, --chain <chain>           网络 (mainnet|shasta|nile)
-t, --token <address>         TRC20 代币合约地址
-r, --receiver <address>      接收地址
-a, --amount <amount>         转账金额（人类可读格式）
-d, --decimals <number>       代币精度（默认: 6）
-f, --max-fee <amount>        最大 Gas 费（默认: 0.001 TRX）
-s, --service-provider <addr> 服务提供者地址
-n, --nonce <number>          交易 nonce（默认: 0）
-D, --deadline <minutes>      交易有效期（分钟，默认: 30）
-p, --private-key <key>       私钥（不推荐，使用环境变量）
-o, --output <file>           输出到 JSON 文件
--no-prompt                   跳过交互式提示
--dry-run                     仅组装，不签名

2. 地址生成命令 address

从用户地址生成对应的 GasFree 地址。

gasfree address TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC

指定网络：

gasfree address -c mainnet TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC

3. 账户激活命令 activate

激活 GasFree 账户（首次转账包含激活费用）。

交互式模式（推荐）：

gasfree activate

自动提交模式：

gasfree activate --chain nile --submit

使用快速脚本：

# 1. 设置环境变量
source setup-env.sh

# 2. 运行激活脚本
./quick-activate.sh

参数说明：

-c, --chain <chain>               网络 (mainnet|shasta|nile)
-t, --token <address>             TRC20 代币合约地址
-a, --amount <amount>             转账金额（人类可读格式）
-d, --decimals <number>           代币精度（默认: 从 API 获取）
-s, --service-provider <address>  服务提供者地址
-p, --private-key <key>           私钥（不推荐，使用环境变量）
--auto-query                      从 API 查询账户信息和 tokens
--submit                          自动提交激活到 Provider

激活说明：

  • 首次激活需要支付激活费用（约 2 USDT，具体金额由 Provider 设定）
  • 激活后账户才能进行 GasFree 转账
  • 建议先在测试网激活测试

4. 查询命令 query

查询 GasFree 相关信息。

# 查询支持的 tokens
gasfree query tokens --chain nile

# 查询服务提供者
gasfree query providers --chain nile

# 查询账户信息
gasfree query address TTT28SJtLjqAY6geqZMtoJdQhjvyJKF42t --chain nile

5. 提交命令 submit

将签名的转账授权提交给 Provider。

# 从文件提交
gasfree submit transfer.json --chain nile

# 交互式提交
gasfree submit --chain nile

6. 状态查询命令 status

查询转账状态。

gasfree status <traceId> --chain nile

安全建议

  1. 不要在命令行中直接传递私钥

    • 命令行参数会被记录在 shell 历史中
    • 使用交互式输入或环境变量

  2. 主网交易警告

    • 主网交易会显示警告并需要确认
    • 建议先在测试网测试

  3. 私钥存储

    • 不要将私钥存储在代码或配置文件中
    • 使用环境变量或安全存储工具

开发

本地运行

# 开发模式（不编译）
npm run dev -- transfer

# 编译后运行
npm run build
npm start -- transfer

项目结构

cli/
├── bin/
│   └── gasfree                    # 可执行入口
├── src/
│   ├── index.ts                   # CLI 入口
│   ├── commands/
│   │   ├── transfer.ts            # 转账命令
│   │   └── address.ts             # 生成地址命令
│   ├── services/
│   │   ├── wallet.service.ts      # 私钥处理
│   │   ├── transaction.service.ts # 交易组装
│   │   ├── signature.service.ts   # TIP712 签名
│   │   └── validation.service.ts  # 输入验证
│   ├── utils/
│   │   ├── logger.ts              # 彩色输出
│   │   └── error-handler.ts       # 错误处理
│   └── types/
│       └── cli-types.ts           # 类型定义
├── package.json
├── tsconfig.json
└── README.md

支持的网络

网络 Chain ID 说明
mainnet 0x2b6653dc TRON 主网
shasta 0x94a9059e Shasta 测试网
nile 0xcd8690dc Nile 测试网（推荐用于测试）

示例

交互式转账

$ gasfree transfer

? Select network: Nile Testnet (Recommended for testing)
? Enter your private key: ********
✅ User Address: TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC
? Enter TRC20 token contract address: TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf
? Enter receiver address: TJM1BE5wq1VdHh3gwjUeyaVkvZp9DVYCfC
? Enter transfer amount (human-readable format): 100.5
? Enter token decimals (default: 6): 6
? Enter max gas fee in TRX (default: 0.001): 0.001
? Use your address as service provider? Yes
? Enter transaction nonce (default: 0): 0
? Enter transaction deadline in minutes (default: 30): 30

✅ GasFree 转账创建成功！

干运行（不签名）

gasfree transfer --dry-run --token TXYZ... --amount 100

保存结果到文件

gasfree transfer --output my-transfer.json

故障排除

私钥格式错误

确保私钥是 64 位十六进制字符串：

正确的格式: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
错误的格式: 0x0123...abc（缺少字符）

地址格式错误

TRON 地址必须以 "T" 开头，长度为 34 位：

正确的格式: TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC
错误的格式: 0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf（这是以太坊地址）

License

Apache License Version 2.0

About

CLI tool for TRON GasFree protocol - zero-gas TRC20 transfers with account activation

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages