31Third Safe Rebalancer Simple

This skill is intentionally minimal for non-technical users.

Best practice: use only one command / one tool:

- INLINECODE0
INLINECODE1 (post-deploy troubleshooting)

If you are unsure, use the help command first:

- INLINECODE2

Prerequisites

- Node.js 22+
npm

Local Setup

CODEBLOCK0

Setup

1. Deploy your Safe + policies using the 31Third policy wizard:

2. You need at least two wallets:

- Safe owner wallet: never share this private key. - Executor wallet: configured in the wizard on ExecutorModule; this private key is used by this skill.

3. Copy env vars from the final wizard overview.

Required env vars:

CODEBLOCK1

INLINECODE4 can be requested via or by emailing dev@31third.com.

What rebalance_now does

1. Reads AssetUniverse and StaticAllocation policy state from ExecutorModule.
Builds baseEntries from current Safe balances for AssetUniverse tokens.
Builds targetEntries from on-chain StaticAllocation targets.
Calls SDK calculateRebalancing(...).
Executes via SDK executeRebalancing(...) using ethers wallet signer.
Waits for confirmation and returns tx hash.

Safety checks:

- Fails if executor wallet is not equal to ExecutorModule.executor.
Fails if required policies are missing.
Loads driftThresholdBps from StaticAllocation and skips execution when drift is below threshold.
Uses StaticAllocation.priceOracle / Slippage.priceOracle for pricing.
Loads maxSlippageBps from SlippagePolicy and uses:

- maxSlippage = policySlippage - 0.1% - maxPriceImpact = policySlippage - 0.1%

- Uses default minTradeValue = 0.1.

Partial policy deployment behavior:

- If AssetUniverse is not deployed, base entries default to [].
If SlippagePolicy is not deployed, configured/default slippage values are used.
If StaticAllocation is not deployed, auto target fetch is not possible.

This is the only fallback case where you should pass manual targetEntries. Do this only when StaticAllocation policy is intentionally not deployed. CLI fallback example: INLINECODE23

CLI

CODEBLOCK2

Troubleshooting & Best Practices

If your rebalance fails, check these common issues:

1. Verify the deployed contracts vs your environment

Use the verify-deployment tool to verify the deployed contracts against your environment. Copy the troubleshooting info from the Safe Policy Deployer (Step 4 or Step 5). It has the following schema:

CODEBLOCK3

IMPORTANT: The framework is deployed with a Safe batch transaction. It might happen that an internal transaction runs
out of gas and fails. The batch transaction itself still succeeds, but not all policies might be deployed. In this case,
execution of rebalancings might fail.

2. "Policy failed: to token not allowed"

Your AssetUniverse policy is blocking the trade.

- Fix: Just use tokens that are allowed by the policy for rebalancing.

3. "Policy failed: minToReceive below..."

The trade slippage is too high.

- Cause: Low liquidity for the token pair (common with Aave aTokens or wrapped assets on new chains).
Fix: Try setting maxSlippage and maxPriceImpact lower on the rebalancing calculation call.

4. "Missing StaticAllocation policy"

The script can't find a target allocation on-chain.

- Fix: Run verify-deployment and if policy not deployed on purpose you can rebalance into any allocation within the AssetUniverse.

31Third 安全再平衡器（简易版）

本技能专为非技术用户设计，功能极简。

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

- rebalancenow
verifydeployment_config（部署后故障排查）

如果不确定，请先使用帮助命令：

- npm run cli -- help

前置条件

- Node.js 22+
npm

本地设置

bash
npm install
npm run build

设置步骤

1. 使用 31Third 策略向导部署您的 Safe 及策略：

2. 您至少需要两个钱包：

- Safe 所有者钱包：切勿分享此私钥。 - 执行者钱包：在向导的 ExecutorModule 中配置；本技能使用此私钥。

3. 从最终向导概览中复制环境变量。

所需环境变量：

bash
SAFE_ADDRESS=0x您的Safe地址
EXECUTORMODULEADDRESS=0x您的ExecutorModule地址
EXECUTORWALLETPRIVATE_KEY=0x...
TOTAPIKEY=您的31thirdapikey
RPC_URL=https://mainnet.base.org
CHAIN_ID=8453

TOTAPIKEY 可通过或发送邮件至 dev@31third.com 申请。

rebalance_now 的功能

1. 从 ExecutorModule 读取 AssetUniverse 和 StaticAllocation 策略状态。
根据当前 Safe 中 AssetUniverse 代币的余额构建 baseEntries。
根据链上 StaticAllocation 目标构建 targetEntries。
调用 SDK 的 calculateRebalancing(...)。
使用 ethers 钱包签名者通过 SDK 的 executeRebalancing(...) 执行。
等待确认并返回交易哈希。

安全检查：

- 如果执行者钱包不等于 ExecutorModule.executor，则失败。
如果缺少必要策略，则失败。
从 StaticAllocation 加载 driftThresholdBps，当偏差低于阈值时跳过执行。
使用 StaticAllocation.priceOracle / Slippage.priceOracle 进行定价。
从 SlippagePolicy 加载 maxSlippageBps，并使用：

- maxSlippage = 策略滑点 - 0.1% - maxPriceImpact = 策略滑点 - 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

bash
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 | 已部署
Executor=0x123...456
BatchTrade=0xD20c024560ccA40288C05BAB650ac087ae9b0f6e
PriceOracle=0x123...456
FeedRegistry=0x1d4999242A24C8588c4f5dB7dFF1D74Df6bC746A
CooldownSec=3600

AssetUniversePolicy=0x123...456 | 已部署
AssetUniverseAssets:

- USDC | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
WETH | 0x4200000000000000000000000000000000000006

StaticAllocationPolicy=0x123...456 | 已部署
StaticAllocationDriftThresholdPercent=0.50%
StaticAllocationToleranceThresholdPercent=0.50%
StaticAllocationTargets:

- USDC | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | AllocationPercent=10.00%
WETH | 0x4200000000000000000000000000000000000006 | AllocationPercent=90.00%

SlippagePolicy=0x123...456 | 已部署
MaxSlippagePercent=0.50%

重要提示：框架通过 Safe 批量交易部署。内部交易可能因 gas 不足而失败。批量交易本身可能成功，但并非所有策略都能成功部署。在这种情况下，再平衡的执行可能会失败。

2. 策略失败：目标代币不被允许

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

- 解决方法： 仅使用策略允许的代币进行再平衡。

3. 策略失败：最小接收量低于...

交易滑点过高。

- 原因： 代币对流动性不足（常见于 Aave 的 aTokens 或新链上的封装资产）。
解决方法： 尝试在再平衡计算调用中设置更低的 maxSlippage 和 maxPriceImpact。

4. 缺少 StaticAllocation 策略

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

- 解决方法： 运行 verify-deployment，如果策略并非故意未部署，您可以在 AssetUniverse 内再平衡到任意配置。

31third-safe-rebalancer-simple31Third安全再平衡器