Netts Energy Orchestrator

Netts Energy Orchestrator 是一个使用 Go 实现的独立服务，用于为自动到账系统中的 TRON 地址自动租赁能量。它集成了 Netts API v2，支持地址自动加入 Host Mode、轮询剩余能量周期并按需购买能量租赁周期，从而显著降低 TRC20 归集的手续费。

功能亮点

• ✅ Netts API 集成：封装 usdt/analyze、time/add、time/status、time/order 等核心接口。
• 🔁 自动周期管理：当剩余周期低于阈值时自动补充，可选自动 Host Mode 注册。
• 🧩 独立微服务：提供 REST API (POST /api/v1/energy/rent)，便于与现有到账平台对接。
• ⚙️ 可配置化：通过 config.yaml 或环境变量管理 API Key、阈值、重试策略等。
• 📈 可观察性：结构化日志、健康检查接口，易于纳入现有监控体系。

快速开始

1. 复制配置模板：

   cp config.example.yaml config.yaml
   

2. 编辑 config.yaml，填入 Netts API Key、白名单 IP、Host Mode 回调地址等；或通过环境变量覆盖：

   export NETTS_API_KEY=your-key
   export NETTS_REAL_IP=1.2.3.4
   

3. 运行服务：

   go run ./cmd/server -config config.yaml
   

4. 调用接口租赁能量：

   curl -X POST http://localhost:8080/api/v1/energy/rent \
     -H "Content-Type: application/json" \
     -d '{
       "from_address": "Txxx", 
       "to_address": "Tyyy",
       "amount": "200.0"
     }'
   

   返回值包含分析结果、是否新增 Host Mode、下单详情以及最新剩余周期。

配置说明

参见 config.example.yaml，主要段落如下：

• server：HTTP 服务监听地址、超时等。
• netts：Netts API 参数（apiKey 可通过 NETTS_API_KEY 覆盖）。
• energy：
  • autoAddHost：是否自动调用 time/add 把地址加入 Host Mode。
  • minCycles / targetCycles：低于最小阈值时补足到目标阈值。
  • postOrderWait：下单后等待能量生效的时间。
• logging：日志级别与输出格式（text/json）。

更多环境变量详见 internal/config/config.go 中的 envPrefix 定义。

REST API

POST /api/v1/energy/rent

{
  "from_address": "源地址（监控地址）",
  "to_address": "归集地址",
  "amount": "USDT 数量，可选，默认 100",
  "callback_url": "可选，覆盖 config 默认回调"
}

响应字段包括推荐能量、下单情况、当前 Host Mode 状态等，详细 schema 请见 docs/api.md。

测试与质量

go test ./...
golangci-lint run        # 若本地已安装，可执行静态检查

CI 流程（.github/workflows/ci.yaml）会执行 go fmt, go vet, go test。

与自动到账系统的集成

• 对接点：在归集服务中，当检测到能量不足（或计划归集）时调用本服务接口即可。
• 配置建议：将主系统的数据库中保存的地址同步到 Netts Host Mode，或在首次归集前调用 rent 接口，由服务自动注册/购买能量。
• 监控：可通过 /healthz 结合现有 Prometheus/Consul 健康检查；同时建议订阅 Netts 提供的 webhook 以获知能量下发事件。

更多架构细节、部署流程以及 CI/CD 建议请参阅 docs/architecture.md 与 docs/deployment.md。

Netts 平台接入流程

在部署本服务之前，请确保完成 Netts Workspace 的账号准备（详见 docs/deployment.md 中的“Netts 账号准备流程”）：

1. 注册并登录 https://netts.io/workspace，生成 API Key；
2. 在 Wallet 页面充值 TRX，保证账户余额可覆盖租赁费用；
3. 在 API 设置中配置服务器出口 IP 白名单；
4. 将 API Key、Real IP、回调地址写入 config.yaml 或环境变量；
5. 通过 curl https://netts.io/apiv2/userinfo（携带 X-API-KEY 与 X-Real-IP）验证连通性。

完成上述步骤后，才可由本服务调用 Netts 接口完成能量租赁。