31Third 安全再平衡器

此技能帮助您监控投资组合偏离度，并通过 31Third 的 ExecutorModule 在 Gnosis Safe 上准备和执行符合策略的再平衡操作。

最佳实践用法：

• 默认使用一步执行：npm run cli -- rebalance-now。
• 仅当您明确理解每个步骤并希望手动控制时，才使用分离的工具（check_drift、plan_rebalance、execute_rebalance 等）。
• 如果不确定，先运行 help（npm run cli -- help）并遵循相关指导。

先决条件

• Node.js 22+
• npm

本地设置

npm install
npm run build

入门指南

如果您尚未部署策略栈，请先部署：
https://app.31third.com/safe-policy-deployer

设置所需的环境变量：

SAFE_ADDRESS=0x您的Safe地址
CHAIN_ID=8453
TOT_API_KEY=您的API密钥
RPC_URL=https://mainnet.base.org
EXECUTOR_MODULE_ADDRESS=0x您的ExecutorModule地址
EXECUTOR_WALLET_PRIVATE_KEY=0x...
ORACLE_MAX_AGE_SECONDS=3600
HEARTBEAT_INTERVAL_SECONDS=21600

TOT_API_KEY（31Third API 密钥）可通过 https://31third.com/contact 或发送邮件至 dev@31third.com 申请。

钱包模型和密钥处理：

• Safe 所有者钱包：控制 Safe 所有权/治理操作。切勿与此技能共享此私钥。
• 执行器钱包：在向导中配置为 ExecutorModule 上的执行器。此技能在执行 execute_rebalance 时需要此私钥。
• 31Third 向导的最后一步提供了所有必需环境变量的概览。配置此技能时，应以此作为事实来源。

此技能的功能

• 从 ExecutorModule 读取活跃的链上策略。
• 计算当前与目标之间的偏离度（check_drift）。
• 根据资产池和滑点边界验证交易（validate_trade）。
• 运行可配置的心跳监控（automation），并在偏离度超过阈值时返回警报负载。
• 模拟并执行已批准的再平衡批次（execute_rebalance），执行前使用 checkPoliciesVerbose 进行验证，并在未知执行失败时重试一次。
• 直接接受 SDK plan_rebalance 的输出（txData + requiredAllowances）进行执行，并在内部解码批量交易调用数据。
• 如果在 ExecutorModule 上 scheduler != registry，则快速失败执行，并显示两个地址。
• 使用当前 Safe 余额（如果存在资产池则受其限制）作为 baseEntries，生成基于 SDK 的策略感知交易计划（plan_rebalance）。
• 为非技术用户提供单命令执行（rebalance_now）：检查偏离度 -> SDK 计划 -> 执行。
• 返回设置和能力指导（help）。

执行安全性

在执行前，智能体提供明确的理由，例如：

• BTC 当前占比 54.00%，目标为 50.00%（偏离 400 基点）。需要进行再平衡。

该技能使用：

• Viem publicClient 进行所有读取操作。
• Viem walletClient 进行执行操作。

执行合约（重要）

当使用 SDK/交易 API 的再平衡输出时，执行必须遵循此精确模式：

1. 从 requiredAllowances 构建授权信息，格式为 (tokenAddress, neededAllowance)。
2. 将 txData 解码为 batchTrade(trades, config)。
3. 将 encodedTradeData 重新编码为 ABI 元组：
   • tuple(string,address,uint256,address,uint256,bytes,bytes)[]
   • tuple(bool,bool)
4. 在提交前运行 checkPoliciesVerbose(tradesInput, configInput)。
5. 从 ExecutorModule 读取 scheduler 和 registry。
6. 确保签名的执行器钱包地址等于 registry（onlyRegistry 所需）。
7. 仅当 scheduler == registry 时，才执行即时路径（executeTradeNow(approvals, encodedTradeData)）。
8. 如果 scheduler != registry，快速失败并显示两个地址。

这是此技能所需的执行语义，不应更改为原始透传调用数据执行。

CLI 命令行

运行捆绑的 CLI：

npm run cli -- help
npm run cli -- check-drift
npm run cli -- automation --last-heartbeat-ms 0
npm run cli -- plan-rebalance --signer 0x您的签名者地址 --min-trade-value 100
npm run cli -- rebalance-now
npm run cli -- validate-trade --trade '{"from":"0x...","to":"0x...","fromAmount":"1000000000000000000","minToReceiveBeforeFees":"990000000000000000"}'
npm run cli -- execute-rebalance --trades '[{"exchangeName":"0x","from":"0x...","fromAmount":"1000000000000000000","to":"0x...","minToReceiveBeforeFees":"990000000000000000","data":"0x...","signature":"0x..."}]' --approvals '[{"token":"0x...","amount":"1000000000000000000"}]'
npm run cli -- execute-rebalance --rebalancing '{"txData":"0x...","requiredAllowances":[{"token":{"address":"0x..."},"neededAllowance":"1000000000000000000"}]}'

只读预检：

npm run smoke -- --signer 0x您的签名者地址
npm run smoke -- --trades '[...]' --approvals '[...]'

注意事项

• 此技能是自动化基础设施，而非投资建议。
• 在生产环境运行前，请在测试/预演环境中验证行为。