功能描述

One-step Safe rebalancer using on-chain 31Third policies.

使用说明 (SKILL.md)

31Third Safe Rebalancer Simple

Name: 31Third Safe Rebalancer (Simple)
Author: phips0812

This skill is intentionally minimal for non-technical users.

Best practice: use only one command / one tool:

rebalance_now
verify_deployment_config (post-deploy troubleshooting)

If you are unsure, use the help command first:

npm run cli -- help

Prerequisites

Node.js 22+
npm

Local Setup

npm install
npm run build

Setup

Deploy your Safe + policies using the 31Third policy wizard: \x3Chttps://app.31third.com/safe-policy-deployer>
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.
Copy env vars from the final wizard overview.

Required env vars:

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 can be requested via \x3Chttps://31third.com/contact> or by emailing [email protected].

What rebalance_now does

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: 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..."

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:

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%

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.

安全使用建议

What to check before installing/using this skill: - The registry metadata claims no required env vars/credentials, but SKILL.md requires a private key (EXECUTOR_WALLET_PRIVATE_KEY), RPC_URL/CHAIN_ID and TOT_API_KEY — treat that as a red flag. Ask the publisher why metadata omits these sensitive requirements. - Do not use your Safe owner private key. Use a dedicated executor key with minimal privileges and limited balance for gas only; rotate or revoke it after testing. - Manually review package.json, package-lock.json and all CLI/source files (src/ and dist/) for network endpoints, telemetry, logging, or code that might exfiltrate secrets (HTTP POSTs, fetch/curl to unknown domains, encoded payloads). Pay attention to any code that sends data to endpoints other than official 31Third domains and your configured RPC. - Because SKILL.md instructs you to run npm install, consider auditing dependency tree or running in an isolated environment/VM/container before connecting real keys or funds. - The static scanner flagged a base64 prompt‑injection pattern — search the SKILL.md and included files for hidden/encoded instructions and remove/inspect any such blocks. - Prefer running first on a test Safe/testnet and verify behavior (no unexpected outbound traffic, correct on‑chain calls). If possible, request the canonical source repository (git) or a publisher identity proof (31third.com) and verify releases/tags match the packaged code. - If you are not comfortable auditing the code, do not provide the executor private key to this tool; instead use trusted, audited tooling or ask 31Third support for an official client.

功能分析

Type: OpenClaw Skill Name: 31third-safe-rebalancer-simple Version: 0.2.0 The skill is a legitimate tool for rebalancing Gnosis Safe wallets using the 31Third protocol. It manages sensitive credentials like private keys and API keys to interact with on-chain policies and the official 31Third API (api.31third.com). Security analysis of the source code (src/rebalance-now.ts and scripts/cli.ts) reveals no malicious behavior, and the CLI implementation includes proactive measures against path traversal attacks. The logic is consistent with the stated purpose of the skill.

能力评估

ℹ Purpose & Capability

The skill's name/description (Safe rebalancer using 31Third policies) matches the code and instructions: it reads on‑chain policies and signs transactions as an executor. However the registry metadata claims no required env vars/primary credential while SKILL.md clearly requires an executor private key, RPC_URL, CHAIN_ID and a 31Third TOT_API_KEY. That mismatch is unexpected and relevant to trust/provenance.

⚠ Instruction Scope

SKILL.md instructs the user/agent to set EXECUTOR_WALLET_PRIVATE_KEY and run npm run cli -- rebalance‑now which will use an ethers signer to calculate and execute trades. Those instructions are within the stated rebalancer scope, but they give the skill direct access to a sensitive private key and network RPC. SKILL.md also tells you to 'copy env vars from the wizard' — the agent could be given secrets not declared in registry metadata. Because the instructions rely on a private key and network RPC, you should audit the CLI code (included) for any unexpected network endpoints, logging, or exfiltration behavior before running.

ℹ Install Mechanism

There is no platform install spec (instruction‑only), which lowers installer risk, but the bundle includes full JS/TS source, dist files, package-lock.json and instructs the user to run npm install and npm run build. Running npm install will fetch dependencies from npm (not vetted by the platform); inspect package.json/package-lock.json and the codebase before installing to avoid malicious dependencies.

⚠ Credentials

The environment variables called out in SKILL.md (EXECUTOR_WALLET_PRIVATE_KEY, SAFE_ADDRESS, EXECUTOR_MODULE_ADDRESS, RPC_URL, CHAIN_ID, TOT_API_KEY) are all plausible and necessary for an on‑chain executor tool. The concern is that the skill's registry metadata advertises 'no required env vars' and 'no primary credential', which is inconsistent with the real requirements. The private key is high‑sensitivity; ensure it is an executor key with narrowly scoped privileges (not the Safe owner key) and consider a hardware or ephemeral signer.

✓ Persistence & Privilege

The skill does not request always:true and does not declare writing/modifying other skills or system settings. It appears to be invoked via CLI on demand; autonomous model invocation is enabled by default but is not combined here with 'always' or other elevated privileges.

版本历史

v0.2.0

**Summary:** Adds price oracle support and improves deployment safety checks. - Added PriceOracle contract ABI and integration. - Safety checks now correctly validate executor address against ExecutorModule.executor. - Price oracle references (from StaticAllocation and Slippage) are now used for pricing. - Deployment verification output updated to include PriceOracle and Executor fields. - New tests and refactored CLI tools for expanded deployment and policy validation.

v0.1.5

- Updated dependencies in package.json and package-lock.json. - Improvements made to CLI and troubleshooting scripts. - test/cli.test.ts updated to reflect latest CLI behaviors and options. - Metadata in skill.json and skill.yaml updated for consistency.

v0.1.4

New CLI command for policy deployment troubleshooting and verification. - Added `verify-deployment` CLI command to help diagnose deployment and configuration issues. - Introduced `verify_deployment_config` helper for post-deploy troubleshooting. - Expanded documentation with troubleshooting steps and usage examples. - Added tests and source files for deployment verification. - CLI now supports additional arguments for deployment checks and summaries.

v0.1.3

Version 0.1.3 - Updated dependencies in package.json and package-lock.json. - No changes to core functionality or documentation (SKILL.md unchanged). - Internal configuration and metadata were refreshed.

v0.1.2

- Added missing SlippagePolicy ABI file. - Updated documentation with clearer setup steps and local environment prerequisites. - Improved compatibility notes for Node.js and npm in SKILL.md. - General cleanup and minor updates across source, build, and test files.

v0.1.1

- Updated contact link for API key requests in documentation to https://31third.com/contact - Minor documentation improvements in SKILL.md for clarity and accuracy

v0.1.0

Initial release of 31third-safe-rebalancer-simple. - Provides a minimal, one-step Safe rebalancer using 31Third on-chain policies. - Main command: rebalance_now for non-technical users; all configuration via CLI and environment variables. - Safety checks on execution to prevent misconfiguration and unauthorized access. - Supports fallback behavior if certain policies aren’t deployed. - CLI allows optional manual specification of target entries.

元数据

Slug 31third-safe-rebalancer-simple

版本 0.2.0

许可证 MIT-0

累计安装 2

当前安装数 2

历史版本数 7

常见问题