功能描述

Policy-aware Safe portfolio rebalancing assistant for 31Third ExecutorModule.

使用说明 (SKILL.md)

31Third Safe Rebalancer

Name: 31Third Safe Rebalancer
Author: phips0812

This skill helps you monitor portfolio drift and prepare/execute policy-compliant rebalances on a Gnosis Safe through the 31Third ExecutorModule.

Best-practice usage:

Use one-step execution by default: npm run cli -- rebalance-now.
Only use separated tools (check_drift, plan_rebalance, execute_rebalance, etc.) if you explicitly understand each step and want manual control.
If unsure, run help first (npm run cli -- help) and follow that guidance.

Prerequisites

Node.js 22+
npm

Local Setup

npm install
npm run build

Getting Started

If you have not deployed your policy stack yet, deploy it first: \x3Chttps://app.31third.com/safe-policy-deployer>

Set required environment variables:

SAFE_ADDRESS=0xYourSafe
CHAIN_ID=8453
TOT_API_KEY=your_api_key
RPC_URL=https://mainnet.base.org
EXECUTOR_MODULE_ADDRESS=0xYourExecutorModule
EXECUTOR_WALLET_PRIVATE_KEY=0x...
ORACLE_MAX_AGE_SECONDS=3600
HEARTBEAT_INTERVAL_SECONDS=21600

TOT_API_KEY (31Third API key) can be requested via \x3Chttps://31third.com/contact> or by emailing [email protected].

Wallet model and key handling:

Safe owner wallet: controls Safe ownership/governance operations. Never share this private key with the skill.
Executor wallet: configured as executor on ExecutorModule in the wizard. This private key is required by the skill for execute_rebalance.
The final step of the 31Third wizard provides an overview of all required environment variables. Use that as source of truth when configuring this skill.

What This Skill Does

Reads active on-chain policies from ExecutorModule.
Computes current-vs-target drift (check_drift).
Validates trades against Asset Universe + Slippage boundaries (validate_trade).
Runs a configurable heartbeat monitor (automation) and returns an alert payload when drift exceeds threshold.
Simulates and executes approved rebalance batches (execute_rebalance) with pre-execution checkPoliciesVerbose validation and one retry on unknown execution failures.
Accepts SDK plan_rebalance output directly for execution (txData + requiredAllowances) and decodes batch trade calldata internally.
Fast-fails execution if scheduler != registry on the ExecutorModule, printing both addresses.
Generates SDK-based policy-aware trade plans (plan_rebalance) using current Safe balances (bounded by Asset Universe when present) as baseEntries.
Provides one-command execution (rebalance_now) for non-technical users: drift check -> SDK plan -> execution.
Returns setup and capability guidance (help).

Execution Safety

Before execution, the agent provides a clear reason, for example:

BTC is at 54.00%, target is 50.00% (drift 400 bps). Rebalance required.

The skill uses:

Viem publicClient for all reads.
Viem walletClient for execution.

Execution Contract (Important)

When using SDK/trading-api rebalancing output, execution must follow this exact pattern:

Build approvals from requiredAllowances as (tokenAddress, neededAllowance).
Decode txData as batchTrade(trades, config).
Re-encode encodedTradeData as ABI tuple:
- tuple(string,address,uint256,address,uint256,bytes,bytes)[]
- tuple(bool,bool)
Run checkPoliciesVerbose(tradesInput, configInput) before submitting.
Read scheduler and registry from ExecutorModule.
Ensure the signing executor wallet address equals registry (required by onlyRegistry).
Only execute immediate path (executeTradeNow(approvals, encodedTradeData)) when scheduler == registry.
If scheduler != registry, fail fast and show both addresses.

This is the required execution semantics for this skill and should not be changed to raw passthrough calldata execution.

CLI

Run the bundled CLI:

npm run cli -- help
npm run cli -- check-drift
npm run cli -- automation --last-heartbeat-ms 0
npm run cli -- plan-rebalance --signer 0xYourSigner --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"}]}'

Read-only smoke preflight:

npm run smoke -- --signer 0xYourSigner
npm run smoke -- --trades '[...]' --approvals '[...]'

Notes

This skill is automation infrastructure, not investment advice.
Validate behavior in test/staging before running in production.

安全使用建议

This skill appears to implement the rebalancer it claims, but there are important mismatches and sensitive requirements you should address before installing: - Confirm metadata vs SKILL.md: the registry lists no required env vars and 'instruction-only', but SKILL.md and the package require many env vars and include Node code. Ask the publisher to correct the manifest to list required envs and the primary credential. - Protect private keys: the skill asks for an EXECUTOR_WALLET_PRIVATE_KEY. Never provide your Safe owner key. Use an executor key with strictly limited permissions, prefer an HSM/hardware signer or ephemeral signing account, and test in staging. - Audit the code & dependencies: the package includes many source/dist files and a package-lock.json. Review the code (or have a trusted reviewer do so) and inspect npm dependencies and any npm scripts before running npm install / npm run build. Running 'npm' will execute third-party code on your machine. - Investigate the scan-finding: ask the publisher to explain the base64-block scanner hit and provide a clean SKILL.md without opaque embedded blocks. If you can't locate the block, avoid using the skill until clarified. - Test in sandbox: exercise the CLI in read-only/smoke modes and on a testnet or staging Safe before any production run. Verify the execution semantics (scheduler==registry, checkPoliciesVerbose, approval flows) in a controlled environment. If the publisher can update the manifest to declare required envs and primary credential, and you or a reviewer confirm there are no hidden payloads and dependencies are safe, this skill is plausible to use — but do not supply high-privilege keys until those checks are done.

功能分析

Type: OpenClaw Skill Name: 31third-safe-rebalancer Version: 0.2.0 The skill is a legitimate automation tool designed to rebalance Gnosis Safe portfolios using the 31Third protocol. It handles sensitive data, specifically the EXECUTOR_WALLET_PRIVATE_KEY, which is used locally via the 'viem' library to sign transactions for the on-chain ExecutorModule. The code includes several safety mechanisms, such as verifying that the provided private key matches the authorized executor address on-chain and performing verbose policy checks and simulations before submitting transactions. Communication is limited to the specified blockchain RPC and the official 31Third API (api.31third.com). No evidence of malicious intent, secret exfiltration, or unauthorized execution was found across the source files (index.ts, src/executor.ts, src/balancer.ts).

能力评估

⚠ Purpose & Capability

Name/description match the included code (balancer, executor, policies, ABIs) and the SKILL.md. However the registry metadata declared 'Required env vars: none' and 'instruction-only', while the SKILL.md explicitly lists multiple required environment variables (SAFE_ADDRESS, CHAIN_ID, TOT_API_KEY, RPC_URL, EXECUTOR_MODULE_ADDRESS, EXECUTOR_WALLET_PRIVATE_KEY, etc.) and the repo includes full source and ABI files. That mismatch (metadata says no envs / instruction-only; package contains code and demands sensitive envs) is disproportionate and unexplained.

ℹ Instruction Scope

SKILL.md provides concrete CLI and execution steps (npm run cli commands, how to build approvals, decode/encode calldata, checkPoliciesVerbose, require scheduler==registry, etc.). The instructions are narrowly scoped to on-chain reads and executing rebalance batches, which is coherent with the stated purpose. However instructions require providing an executor private key for signing transactions, and recommend running npm scripts which will execute bundled code — both are legitimate for this use but increase risk and should be handled securely.

ℹ Install Mechanism

No installer spec in registry (instruction-only), but the skill bundle actually contains Node.js source, dist files, package.json and a package-lock. SKILL.md tells users to run 'npm install' and 'npm run build'. This is a moderate-risk pattern: installing npm deps executes third-party code and scripts. There are no external download URLs or extract steps, but running npm build/cli will execute the shipped code on the host.

⚠ Credentials

SKILL.md legitimately requires RPC_URL, CHAIN_ID, TOT_API_KEY, SAFE_ADDRESS, EXECUTOR_MODULE_ADDRESS and an executor private key for signing on-chain transactions. Those variables are appropriate for a rebalancer. The problem: the skill metadata did not declare any required env vars or primary credential. A skill that needs an executor private key should declare that as its primary credential so users know up-front. Requiring a private key is sensitive; ensure it's an executor-only key with limited permissions and not the Safe owner key. No unrelated credentials are requested.

✓ Persistence & Privilege

The skill does not request 'always: true', does not claim to modify other skills or system-wide configs, and follows the normal autonomous-invocation defaults. No additional persistence or elevated platform privileges are requested in the manifest.

版本历史

v0.2.0

- Added PriceOracle ABI support to policy execution and simulation layers. - Updated contract ABIs and related TypeScript/JavaScript modules for improved compatibility and coverage. - Expanded and revised internal and test files across balancer, executor, and policy components to support new policy modules. - No changes to command-line interface or user workflow.

v0.1.3

- Added Node.js (22+) and npm version requirements under "Prerequisites". - Introduced explicit local setup instructions (`npm install`, `npm run build`). - Minor formatting and heading tweaks for clarity. - No changes to functionality or features.

v0.1.2

- Updated the 31Third API key request link in documentation from https://31third.com to https://31third.com/contact. - No functional or code-level changes; this release is focused on minor documentation improvements.

v0.1.1

- Adds a new one-step `rebalance-now` CLI command for simplified execution. - Execution now accepts SDK/trading-api rebalancing output directly (`txData` + `requiredAllowances`) and decodes batch trade calldata internally. - Enforces robust execution contract: validates trades with `checkPoliciesVerbose`, verifies `scheduler == registry`, and fast-fails with diagnostic output if not. - Includes one retry on unknown execution failures. - Improves documentation with best-practice usage guidance and expanded execution contract details.

v0.1.0

Initial release with significant project restructuring and enhanced features. - Major refactor: improved documentation, reorganized project structure, and clarified setup instructions. - New CLI supports drift checks, trade validation, rebalance planning, batch execution, heartbeat automation, and help command. - Enhanced policy integration: reads active policies, simulates trades, monitors drift, and manages automation heartbeats. - Updated environment variable requirements; see 31Third deployment wizard for guidance. - Removed legacy scripts and internal references; streamlined for reliability and maintainability.

v0.1.0-alpha.0

31Third Safe Rebalancer initial release. - Execute policy-guarded token swaps and portfolio rebalancing for a Safe using 31Third's infrastructure on EVM chains. - Includes strict daily limits, allowlists, and slippage checks prior to execution. - Provides CLI scripts for swaps, portfolio rebalancing, and policy inspection. - Outlines required environment variables and setup process for secure operation. - Not intended as financial, legal, or tax advice; operators are responsible for compliance and security.

元数据

Slug 31third-safe-rebalancer

版本 0.2.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 6

常见问题