shll-skills 6.0.0 → 6.0.2

package/README.md

@@ -1,13 +1,13 @@
 # SHLL Skills — AI Agent DeFi Toolkit on BSC
 
-[![Website](https://img.shields.io/badge/Website-shll.run-blue)](https://shll.run) [![Twitter](https://img.shields.io/badge/Twitter-@shllrun-1DA1F2)](https://twitter.com/shllrun) [![npm](https://img.shields.io/npm/v/shll-skills)](https://www.npmjs.com/package/shll-skills)
+[![Website](https://img.shields.io/badge/Website-shll.run-blue)](https://shll.run) [![Twitter](https://img.shields.io/badge/Twitter-@shllrun-1DA1F2)](https://twitter.com/shllrun) [![npm](https://img.shields.io/npm/v/shll-skills)](https://www.npmjs.com/package/shll-skills) [![ClawHub](https://img.shields.io/badge/ClawHub-shll--skills-orange)](https://clawhub.ai/kledx/shll-skills)
 
-A **CLI + MCP Server** toolkit that gives any AI agent the ability to execute DeFi operations on BSC Mainnet securely. Supports PancakeSwap V2/V3 swaps, Venus lending, Four.meme bonding curve trades, setup flows, and raw calldata execution through PolicyGuard.
-
-Version `6.0.0` finalizes the modular layout:
-- `shared/*` for constants, clients, schemas, errors, ABIs, and cross-cutting helpers
-- `services/*` for single-source business logic
-- `commands/*` and `tools/*` as thin CLI/MCP adapters
+A **CLI + MCP Server** toolkit that gives any AI agent the ability to execute DeFi operations on BSC Mainnet securely. Supports PancakeSwap V2/V3 swaps, Venus lending, Four.meme bonding curve trades, setup flows, and raw calldata execution through PolicyGuard.
+
+Version `6.0.0` finalizes the modular layout:
+- `shared/*` for constants, clients, schemas, errors, ABIs, and cross-cutting helpers
+- `services/*` for single-source business logic
+- `commands/*` and `tools/*` as thin CLI/MCP adapters
 
 ## Install
 
@@ -74,32 +74,32 @@ The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to d
 
 ### Available MCP Tools (24 total)
 
-| Tool | Type | Description |
-|------|------|-------------|
-| `portfolio` | Read | Vault holdings + token balances |
-| `balance` | Read | BNB or token balance of the agent vault |
-| `price` | Read | Real-time token price (DexScreener) |
-| `search` | Read | Search token by name/symbol on BSC |
-| `tokens` | Read | List known token symbols + addresses |
-| `policies` | Read | View active on-chain policies + config |
-| `status` | Read | One-shot readiness overview with blockers, warnings, and next actions |
-| `history` | Read | Recent transactions + policy rejections |
-| `token_restriction` | Read | View token whitelist restriction status + whitelisted tokens |
-| `listings` | Read | Available agent templates for rent |
-| `four_info` | Read | Query Four.meme bonding curve token info |
-| `swap` | Write | PancakeSwap V2/V3 auto-routing swap |
-| `wrap` | Write | BNB → WBNB in vault |
-| `unwrap` | Write | WBNB → BNB in vault |
-| `lend` | Write | Supply tokens to Venus for yield |
-| `redeem` | Write | Withdraw from Venus |
-| `transfer` | Write | Send BNB or ERC20 from vault |
-| `four_buy` | Write | Buy a Four.meme bonding-curve token |
-| `four_sell` | Write | Sell a Four.meme bonding-curve token |
-| `config` | Write | Configure risk parameters (spending limits, cooldown) |
-| `setup_guide` | Info | Generate dual-wallet onboarding URL + steps |
-| `generate_wallet` | Info | Create new operator wallet (not the owner, mint, or vault wallet) |
-| `execute_calldata` | Write | Execute raw calldata from any source through PolicyGuard |
-| `execute_calldata_batch` | Write | Execute multiple calldata actions atomically through PolicyGuard |
+| Tool | Type | Description |
+|------|------|-------------|
+| `portfolio` | Read | Vault holdings + token balances |
+| `balance` | Read | BNB or token balance of the agent vault |
+| `price` | Read | Real-time token price (DexScreener) |
+| `search` | Read | Search token by name/symbol on BSC |
+| `tokens` | Read | List known token symbols + addresses |
+| `policies` | Read | View active on-chain policies + config |
+| `status` | Read | One-shot readiness overview with blockers, warnings, and next actions |
+| `history` | Read | Recent transactions + policy rejections |
+| `token_restriction` | Read | View token whitelist restriction status + whitelisted tokens |
+| `listings` | Read | Available agent templates for rent |
+| `four_info` | Read | Query Four.meme bonding curve token info |
+| `swap` | Write | PancakeSwap V2/V3 auto-routing swap |
+| `wrap` | Write | BNB → WBNB in vault |
+| `unwrap` | Write | WBNB → BNB in vault |
+| `lend` | Write | Supply tokens to Venus for yield |
+| `redeem` | Write | Withdraw from Venus |
+| `transfer` | Write | Send BNB or ERC20 from vault |
+| `four_buy` | Write | Buy a Four.meme bonding-curve token |
+| `four_sell` | Write | Sell a Four.meme bonding-curve token |
+| `config` | Write | Configure risk parameters (spending limits, cooldown) |
+| `setup_guide` | Info | Generate dual-wallet onboarding URL + steps |
+| `generate_wallet` | Info | Create new operator wallet (not the owner, mint, or vault wallet) |
+| `execute_calldata` | Write | Execute raw calldata from any source through PolicyGuard |
+| `execute_calldata_batch` | Write | Execute multiple calldata actions atomically through PolicyGuard |
 
 ---
 
@@ -109,58 +109,58 @@ For OpenClaw, shell scripts, or manual use.
 
 ### Quick Start
 
-```bash
-# 1. Generate an operator wallet (AI-only hot wallet)
-shll-run generate-wallet
-export RUNNER_PRIVATE_KEY="0x..."
-
-# 2. Get setup link (user completes on shll.run with their OWNER wallet)
-shll-run setup-guide -l 0xABC...DEF -d 30
-
-# 3. After the user sends back token-id, verify readiness
-shll-run status -k 5
-shll-run portfolio -k 5
-
-# 4. Trade
-shll-run swap -f BNB -t USDC -a 0.1 -k 5
-```
-
-In OpenClaw, AI should set `RUNNER_PRIVATE_KEY` for the current session automatically. Do not ask the user to edit environment variables manually during chat onboarding.
+```bash
+# 1. Generate an operator wallet (AI-only hot wallet)
+shll-run generate-wallet
+export RUNNER_PRIVATE_KEY="0x..."
+
+# 2. Get setup link (user completes on shll.run with their OWNER wallet)
+shll-run setup-guide -l 0xABC...DEF -d 30
+
+# 3. After the user sends back token-id, verify readiness
+shll-run status -k 5
+shll-run portfolio -k 5
+
+# 4. Trade
+shll-run swap -f BNB -t USDC -a 0.1 -k 5
+```
+
+In OpenClaw, AI should set `RUNNER_PRIVATE_KEY` for the current session automatically. Do not ask the user to edit environment variables manually during chat onboarding.
 
 ### Commands
 
 #### Trading
 ```bash
-shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>              # Auto V2/V3 routing
-shll-run swap -f BNB -t USDT -a 0.1 -k 5 -v v3 -s 2           # Use V3 with 2% slippage
-shll-run wrap -a <BNB> -k <ID>                                # BNB -> WBNB
-shll-run unwrap -a <BNB> -k <ID>                              # WBNB -> BNB
-shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>
-shll-run four_buy --token <ADDR> -a <BNB> -k <ID>            # Buy on Four.meme bonding curve
-shll-run four_sell --token <ADDR> -a <TOKEN_AMT> -k <ID>     # Sell on Four.meme bonding curve
+shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>              # Auto V2/V3 routing
+shll-run swap -f BNB -t USDT -a 0.1 -k 5 -v v3 -s 2           # Use V3 with 2% slippage
+shll-run wrap -a <BNB> -k <ID>                                # BNB -> WBNB
+shll-run unwrap -a <BNB> -k <ID>                              # WBNB -> BNB
+shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>
+shll-run four_buy --token <ADDR> -a <BNB> -k <ID>            # Buy on Four.meme bonding curve
+shll-run four_sell --token <ADDR> -a <TOKEN_AMT> -k <ID>     # Sell on Four.meme bonding curve
 ```
 
 #### Lending (Venus Protocol)
 ```bash
-shll-run lend -t USDT -a 100 -k <ID>      # Supply to Venus
-shll-run redeem -t USDT -a 50 -k <ID>     # Withdraw from Venus
+shll-run lend -t USDT -a 100 -k <ID>      # Supply to Venus
+shll-run redeem -t USDT -a 50 -k <ID>     # Withdraw from Venus
 ```
 
 #### Market Data (read-only)
 ```bash
-shll-run portfolio -k <ID>        # Vault holdings + USD values
-shll-run price --token <SYM>      # Real-time price (DexScreener)
-shll-run search --query <TEXT>     # Find token by name
-shll-run tokens                   # List known tokens
-shll-run four_info --token <ADDR> # Four.meme token status
+shll-run portfolio -k <ID>        # Vault holdings + USD values
+shll-run price --token <SYM>      # Real-time price (DexScreener)
+shll-run search --query <TEXT>     # Find token by name
+shll-run tokens                   # List known tokens
+shll-run four_info --token <ADDR> # Four.meme token status
 ```
 
 #### Risk Management
-```bash
-shll-run policies -k <ID>         # View active on-chain policies
-shll-run status -k <ID>           # Readiness, blockers, warnings, next actions
-shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>
-```
+```bash
+shll-run policies -k <ID>         # View active on-chain policies
+shll-run status -k <ID>           # Readiness, blockers, warnings, next actions
+shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>
+```
 
 ---
 
@@ -173,34 +173,34 @@ AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vaul
 1. AI constructs a tool call (MCP) or CLI command
 2. `PolicyClient.validate()` simulates against all on-chain policies
 3. If approved, `AgentNFA.execute()` routes through PolicyGuard → vault
-4. PolicyGuard enforces: spending limits, cooldowns, recipient checks, and protocol rules
+4. PolicyGuard enforces: spending limits, cooldowns, recipient checks, and protocol rules
 
 ## Security: Dual-Wallet Architecture
 
-| | Owner Wallet | Operator Wallet (RUNNER_PRIVATE_KEY) |
-|---|---|---|
-| **Who holds it** | User (MetaMask/hardware) | AI agent |
-| **Use it for** | Rent or mint the agent, hold the Agent NFT, authorize operator | Pay gas and execute policy-limited actions |
-| **Can trade** | — | ✅ Within PolicyGuard limits |
-| **Can withdraw vault** | ✅ | ❌ |
-| **Can transfer NFT** | ✅ | ❌ |
-| **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
-
-Do not use the operator wallet to mint or rent the agent. Do not hold the Agent NFT in the operator wallet. Keep only a small BNB balance there for gas.
-
-After setup, run `status` first. It returns a machine-friendly readiness object with:
-- `readiness.ready`
-- `readiness.blockers`
-- `readiness.warnings`
-- `readiness.nextActions`
-
-This is the intended handoff for AI onboarding flows before any trading command.
+| | Owner Wallet | Operator Wallet (RUNNER_PRIVATE_KEY) |
+|---|---|---|
+| **Who holds it** | User (MetaMask/hardware) | AI agent |
+| **Use it for** | Rent or mint the agent, hold the Agent NFT, authorize operator | Pay gas and execute policy-limited actions |
+| **Can trade** | — | ✅ Within PolicyGuard limits |
+| **Can withdraw vault** | ✅ | ❌ |
+| **Can transfer NFT** | ✅ | ❌ |
+| **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
+
+Do not use the operator wallet to mint or rent the agent. Do not hold the Agent NFT in the operator wallet. Keep only a small BNB balance there for gas.
+
+After setup, run `status` first. It returns a machine-friendly readiness object with:
+- `readiness.ready`
+- `readiness.blockers`
+- `readiness.warnings`
+- `readiness.nextActions`
+
+This is the intended handoff for AI onboarding flows before any trading command.
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `RUNNER_PRIVATE_KEY` | Yes for write ops and agent-linked reads | Operator wallet key (~$1 BNB for gas) |
+| `RUNNER_PRIVATE_KEY` | Yes for write ops and agent-linked reads | Operator wallet key (~$1 BNB for gas) |
 | `SHLL_RPC` | No | BSC RPC URL override. Recommended: use a private RPC (e.g. QuickNode, Alchemy, GetBlock) for better reliability and speed |
 
 > **Note:** Contract addresses (AgentNFA, PolicyGuard) are hardcoded for security reasons. Override env vars are intentionally not supported to prevent supply-chain attacks.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shll-run
 description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands and users only need to chat.
-version: 6.0.0
+version: 6.0.2
 author: SHLL Team
 website: https://shll.run
 twitter: https://twitter.com/shllrun
@@ -68,7 +68,7 @@ On-chain guardrails:
 - Spending limits, cooldowns, whitelist rules, and protocol rules are enforced on-chain.
 - Raw calldata is blocked if the recipient cannot be decoded safely.
 
-## Current Critical Constraints (v6.0.0)
+## Current Critical Constraints (v6.0.2)
 
 1. `init` command is disabled. Do not use it.
 2. Raw calldata remains high risk; rely on strict recipient safety checks.
@@ -146,11 +146,10 @@ Write commands include:
 - `raw`
 - `lend`
 - `redeem`
-- `config`
 - `four_buy`
 - `four_sell`
 
-Read-only commands do not require confirmation.
+Read-only commands (no confirmation needed): `config`, `policies`, `status`, `history`, `portfolio`, `price`, `tokens`, `search`, `balance`, `four_info`.
 
 ## CLI Commands
 
@@ -187,6 +186,7 @@ If `-l/--listing` is omitted, `setup-guide` auto-selects an active listing from
 
 ### Read-only and audit
 
+- `shll-run config -k <tokenId>` (view-only; modify via web console)
 - `shll-run portfolio -k <tokenId>`
 - `shll-run price --token <symbolOrAddress>`
 - `shll-run search --query <text>`
@@ -239,10 +239,13 @@ When the user provides a token address:
 5. `Unable to decode recipient from calldata`
 - Use built-in command flow or provide calldata with a decodable vault recipient.
 
-6. `init command is disabled`
+6. `No V2/V3 liquidity or direct path found`
+- The pair does not exist or lacks liquidity. DO NOT tell the user to wrap BNB to WBNB; the `swap` command handles native BNB automatically via `swapExactETHForTokens`. If a swap fails, it's because the direct pool is empty or invalid, not because BNB is unplugged.
+
+7. `init command is disabled`
 - Use `setup-guide` instead.
 
-7. Unsure what is broken
+8. Unsure what is broken
 - Check the structured `errorCode`, `message`, and `details` fields in the JSON response first.
 
 ## Product UX Rules