31Third Safe Rebalancer Simple

本技能专为非技术人员设计，力求极简。

最佳实践：每次仅使用一个命令 / 一个工具：

• rebalance_now
• verify_deployment_config（部署后问题排查）

如不确定如何操作，请先使用帮助命令：

• npm run cli -- help

前置条件

• Node.js 22+
• npm

本地环境搭建

npm install
npm run build

配置步骤

1. 使用 31Third 策略向导部署您的 Safe 及相关策略：
   https://app.31third.com/safe-policy-deployer
2. 您至少需要两个钱包：
   • Safe 所有者钱包：切勿分享该私钥。
   • 执行者钱包（Executor wallet）：在向导中配置于 ExecutorModule；本技能将使用该钱包的私钥。
3. 从向导最终概览页复制环境变量。

必需的环境变量：

SAFE_ADDRESS=0xYourSafe
EXECUTOR_MODULE_ADDRESS=0xYourExecutorModule
EXECUTOR_WALLET_PRIVATE_KEY=0x...
TOT_API_KEY=your_31third_api_key
RPC_URL=https://mainnet.base.org
CHAIN_ID=8453

TOT_API_KEY 可通过 https://31third.com/contact 申请，或发送邮件至 dev@31third.com 获取。

rebalance_now 的作用

1. 从 ExecutorModule 中读取 AssetUniverse 和 StaticAllocation 策略状态。
2. 基于当前 Safe 账户余额，为 AssetUniverse 中所列代币构建 baseEntries。
3. 基于链上 StaticAllocation 目标值构建 targetEntries。
4. 调用 SDK 的 calculateRebalancing(...) 方法。
5. 使用 ethers wallet signer，通过 SDK 的 executeRebalancing(...) 方法执行再平衡操作。
6. 等待交易确认，并返回交易哈希（tx hash）。

安全校验机制：

• 若执行者钱包地址与 ExecutorModule.executor 不一致，则操作失败。
• 若必需策略缺失，则操作失败。
• 从 StaticAllocation 加载 driftThresholdBps，当实际偏离值低于阈值时跳过执行。
• 使用 StaticAllocation.priceOracle 或 Slippage.priceOracle 进行价格查询。
• 从 SlippagePolicy 加载 maxSlippageBps，并采用以下值：
  • maxSlippage = policySlippage - 0.1%
  • maxPriceImpact = policySlippage - 0.1%
• 默认使用 minTradeValue = 0.1。

部分策略部署时的行为：

• 若未部署 AssetUniverse，则 baseEntries 默认为空数组 []。
• 若未部署 SlippagePolicy，则使用已配置或默认的滑点参数。
• 若未部署 StaticAllocation，则无法自动获取目标分配。这是唯一允许传入手动 targetEntries 的回退场景，仅适用于您**有意不部署** StaticAllocation 策略的情况。
  CLI 回退示例：
  npm run cli -- rebalance-now --target-entries '[{"tokenAddress":"0x...","allocation":0.5},{"tokenAddress":"0x...","allocation":0.5}]'

CLI 命令

npm run cli -- help
npm run cli -- rebalance-now
npm run cli -- rebalance-now --target-entries '[{"tokenAddress":"0x...","allocation":0.5},{"tokenAddress":"0x...","allocation":0.5}]'
npm run cli -- verify-deployment --troubleshooting-file ./summary.txt
npm run cli -- verify-deployment --troubleshooting-summary "Safe=0x..."

故障排查与最佳实践

若再平衡操作失败，请检查以下常见问题：

1. 核对已部署合约与当前环境配置

使用 verify-deployment 工具验证已部署合约是否与您的环境变量匹配。
请从 Safe Policy Deployer（第 4 步或第 5 步）中复制故障排查信息。其格式如下：

Safe=0x123...456
ExecutorModule=0x123...456 | Deployed
Executor=0x123...456
BatchTrade=0xD20c024560ccA40288C05BAB650ac087ae9b0f6e
PriceOracle=0x123...456
FeedRegistry=0x1d4999242A24C8588c4f5dB7dFF1D74Df6bC746A
CooldownSec=3600

AssetUniversePolicy=0x123...456 | Deployed
AssetUniverseAssets:
- USDC | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
- WETH | 0x4200000000000000000000000000000000000006

StaticAllocationPolicy=0x123...456 | Deployed
StaticAllocationDriftThresholdPercent=0.50%
StaticAllocationToleranceThresholdPercent=0.50%
StaticAllocationTargets:
- USDC | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | AllocationPercent=10.00%
- WETH | 0x4200000000000000000000000000000000000006 | AllocationPercent=90.00%

SlippagePolicy=0x123...456 | Deployed
MaxSlippagePercent=0.50%

重要提示：框架通过 Safe 批量交易部署。在此过程中，某个内部交易可能因 Gas 不足而失败，但整个批量交易仍会成功。此时，部分策略可能未被成功部署，从而导致再平衡执行失败。

2. “Policy failed: to token not allowed”

您的 AssetUniverse 策略阻止了该笔交易。

• 解决方法：仅对策略中允许的代币执行再平衡操作。

3. “Policy failed: minToReceive below...”

交易滑点过高。

• 原因：该代币对流动性不足（常见于 Aave aTokens 或新链上的封装资产）。
• 解决方法：在调用 calculateRebalancing 时，尝试降低 maxSlippage 和 maxPriceImpact 的设定值。

4. “Missing StaticAllocation policy”

脚本无法在链上找到目标分配配置。

• 解决方法：运行 verify-deployment；若确认该策略系有意未部署，则可在 AssetUniverse 允许范围内对任意资产组合执行再平衡。