shll-skills 6.0.3 → 6.0.4

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.2
+version: 6.0.4
 author: SHLL Team
 website: https://shll.run
 twitter: https://twitter.com/shllrun
@@ -31,6 +31,90 @@ credentials:
     The operator wallet is NOT the owner wallet, NOT the vault, NOT the Agent NFT holder.
 ---
 
+# SHLL — Contract-Enforced Safe Execution for AI Agents on BNB Chain
+
+## What is SHLL?
+
+SHLL is a DeFi execution layer for AI agents on BNB Chain with **on-chain safety enforcement**.
+Unlike off-chain filters that can be bypassed, SHLL uses smart contracts to enforce
+spending limits, trade intervals, protocol whitelists, and receiver restrictions.
+Every AI agent action is validated by an immutable PolicyGuard contract before execution.
+
+Key facts:
+- Network: BSC mainnet
+- 27 CLI + MCP tools for DeFi operations (swap, lend, meme trading, portfolio)
+- Supports PancakeSwap V2/V3, Venus Protocol, Four.meme
+- MCP Server compatible with Claude, Cursor, OpenClaw, and any MCP-compatible agent
+- npm package: `shll-skills` | Website: https://shll.run
+
+## Security Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        SHLL Architecture                        │
+│                                                                 │
+│  ┌──────────┐    ┌───────────────┐    ┌──────────────────────┐  │
+│  │  User     │    │  AI Agent     │    │  On-Chain Contracts  │  │
+│  │ (Owner)   │    │ (Operator)    │    │                      │  │
+│  │           │    │               │    │  ┌────────────────┐  │  │
+│  │ • Holds   │    │ • Executes    │    │  │  PolicyGuard   │  │  │
+│  │   Agent   │    │   trades via  │    │  │  (Validator)   │  │  │
+│  │   NFT     │    │   restricted  │    │  │                │  │  │
+│  │ • Sets    │    │   permissions │    │  │  4 Policy      │  │  │
+│  │   policy  │    │               │    │  │  Checks:       │  │  │
+│  │   rules   │───▶│ SHLL Skills   │───▶│  │                │  │  │
+│  │ • Full    │    │ (CLI / MCP)   │    │  │  1.Spending    │  │  │
+│  │   asset   │    │               │    │  │    Limit       │  │  │
+│  │   control │    │ Cannot:       │    │  │  2.Cooldown    │  │  │
+│  │           │    │ • Withdraw    │    │  │  3.DeFi Guard  │  │  │
+│  │           │    │   vault funds │    │  │  4.Receiver    │  │  │
+│  │           │    │ • Change      │    │  │    Guard       │  │  │
+│  │           │    │   policies    │    │  └───────┬────────┘  │  │
+│  │           │    │ • Transfer    │    │          │            │  │
+│  │           │    │   NFT         │    │   ┌─────▼──────┐     │  │
+│  │           │    │               │    │   │   Vault     │     │  │
+│  │           │    │               │    │   │ (Agent      │     │  │
+│  │           │    │               │    │   │  Account)   │     │  │
+│  │           │    │               │    │   │             │     │  │
+│  │           │    │               │    │   │ Holds funds │     │  │
+│  └──────────┘    └───────────────┘    │   └─────────────┘     │  │
+│                                       └──────────────────────┘  │
+│  Dual-Wallet Isolation:                                         │
+│  • Owner wallet = asset control (human)                         │
+│  • Operator wallet = restricted execution (AI)                  │
+│  • Even if operator key leaks, PolicyGuard still limits actions │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 4-Policy PolicyGuard Stack
+
+All policies are enforced ON-CHAIN by smart contract. They cannot be bypassed by the AI.
+
+| Policy | Contract | What It Does |
+|--------|----------|-------------|
+| SpendingLimitV2 | On-chain | Per-transaction and daily spending caps in BNB |
+| CooldownPolicy | On-chain | Minimum time gap between consecutive trades |
+| DeFiGuardV2 | On-chain | Whitelist of approved DeFi protocols and functions |
+| ReceiverGuardV2 | On-chain | Only approved receiver addresses can receive funds |
+
+When a policy rejects an action:
+- The transaction is NOT executed
+- The vault funds remain SAFE
+- The rejection reason is returned from the smart contract
+- The rejection is logged and auditable
+- The `enforcement` field in the response is always `on-chain`
+
+## Why On-Chain Enforcement Matters
+
+Most AI agent platforms use off-chain safety filters:
+- Off-chain: AI or backend decides → **can be bypassed** by prompt injection, API manipulation, or code bugs
+- On-chain (SHLL): Smart contract decides → **cannot be bypassed** — the blockchain enforces the rules
+
+PolicyGuard contract: `0x25d17eA0e3Bcb8CA08a2BFE917E817AFc05dbBB3`
+Verify on BscScan: https://bscscan.com/address/0x25d17eA0e3Bcb8CA08a2BFE917E817AFc05dbBB3
+
+---
+
 # SHLL Skill Usage Guide
 
 This file defines how an AI agent should use `shll-run` and `shll-mcp` safely.
@@ -68,7 +152,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.2)
+## Current Critical Constraints (v6.0.4)
 
 1. `init` command is disabled. Do not use it.
 2. Raw calldata remains high risk; rely on strict recipient safety checks.

package/dist/{chunk-TH3ENDDM.mjs → chunk-IKVUDAK6.mjs}

@@ -6,8 +6,8 @@ var MEV_PROTECTED_RPC = "https://bscrpc.pancakeswap.finance";
 var DEFAULT_LISTING_MANAGER = "0x1f9CE85bD0FF75acc3D92eB79f1Eb472f0865071";
 var DEFAULT_LISTING_ID = "0x64083b44e38db02749e6e16bf84ce6c19146cc42a108e53324e11f250b15a0b7";
 var DEFAULT_INDEXER = "https://indexer-mainnet.shll.run";
-var SKILL_VERSION = "6.0.2";
-var BINDINGS_UPDATED_AT = "2026-03-06";
+var SKILL_VERSION = "6.0.4";
+var BINDINGS_UPDATED_AT = "2026-03-07";
 var PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 var PANCAKE_V3_SMART_ROUTER = "0x13f4EA83D0bd40E75C8222255bc855a974568Dd4";
 var V3_QUOTER = "0xB048Bbc1Ee6b733FFfCFb9e9CeF7375518e25997";
@@ -1239,6 +1239,9 @@ async function validateActionsOrThrow(policyClient, tokenId, actions) {
         "POLICY_REJECTED",
         "Policy rejected transaction",
         {
+          enforcement: "on-chain",
+          policyGuardContract: DEFAULT_GUARD,
+          verifyOnChain: `https://bscscan.com/address/${DEFAULT_GUARD}`,
           failedActionIndex: index,
           failedActionTarget: action.target,
           failedActionSelector: getActionSelector(action),

package/dist/index.js

@@ -12,8 +12,8 @@ var MEV_PROTECTED_RPC = "https://bscrpc.pancakeswap.finance";
 var DEFAULT_LISTING_MANAGER = "0x1f9CE85bD0FF75acc3D92eB79f1Eb472f0865071";
 var DEFAULT_LISTING_ID = "0x64083b44e38db02749e6e16bf84ce6c19146cc42a108e53324e11f250b15a0b7";
 var DEFAULT_INDEXER = "https://indexer-mainnet.shll.run";
-var SKILL_VERSION = "6.0.2";
-var BINDINGS_UPDATED_AT = "2026-03-06";
+var SKILL_VERSION = "6.0.4";
+var BINDINGS_UPDATED_AT = "2026-03-07";
 var PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 var PANCAKE_V3_SMART_ROUTER = "0x13f4EA83D0bd40E75C8222255bc855a974568Dd4";
 var V3_QUOTER = "0xB048Bbc1Ee6b733FFfCFb9e9CeF7375518e25997";
@@ -1260,6 +1260,9 @@ async function validateActionsOrThrow(policyClient, tokenId, actions) {
         "POLICY_REJECTED",
         "Policy rejected transaction",
         {
+          enforcement: "on-chain",
+          policyGuardContract: DEFAULT_GUARD,
+          verifyOnChain: `https://bscscan.com/address/${DEFAULT_GUARD}`,
           failedActionIndex: index,
           failedActionTarget: action.target,
           failedActionSelector: getActionSelector(action),

package/dist/index.mjs

@@ -27,7 +27,7 @@ import {
   transferFromVault,
   unwrapWbnb,
   wrapBnb
-} from "./chunk-TH3ENDDM.mjs";
+} from "./chunk-IKVUDAK6.mjs";
 
 // src/index.ts
 import { Command as Command9 } from "commander";

package/dist/mcp.js

@@ -12,7 +12,7 @@ var MEV_PROTECTED_RPC = "https://bscrpc.pancakeswap.finance";
 var DEFAULT_LISTING_MANAGER = "0x1f9CE85bD0FF75acc3D92eB79f1Eb472f0865071";
 var DEFAULT_LISTING_ID = "0x64083b44e38db02749e6e16bf84ce6c19146cc42a108e53324e11f250b15a0b7";
 var DEFAULT_INDEXER = "https://indexer-mainnet.shll.run";
-var SKILL_VERSION = "6.0.2";
+var SKILL_VERSION = "6.0.4";
 var PANCAKE_V2_ROUTER = "0x10ED43C718714eb63d5aA57B78B54704E256024E";
 var PANCAKE_V3_SMART_ROUTER = "0x13f4EA83D0bd40E75C8222255bc855a974568Dd4";
 var V3_QUOTER = "0xB048Bbc1Ee6b733FFfCFb9e9CeF7375518e25997";
@@ -1240,6 +1240,9 @@ async function validateActionsOrThrow(policyClient, tokenId, actions) {
         "POLICY_REJECTED",
         "Policy rejected transaction",
         {
+          enforcement: "on-chain",
+          policyGuardContract: DEFAULT_GUARD,
+          verifyOnChain: `https://bscscan.com/address/${DEFAULT_GUARD}`,
           failedActionIndex: index,
           failedActionTarget: action.target,
           failedActionSelector: getActionSelector(action),

package/dist/mcp.mjs

@@ -26,7 +26,7 @@ import {
   transferFromVault,
   unwrapWbnb,
   wrapBnb
-} from "./chunk-TH3ENDDM.mjs";
+} from "./chunk-IKVUDAK6.mjs";
 
 // src/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shll-skills",
-    "version": "6.0.3",
+    "version": "6.0.4",
     "description": "SHLL DeFi Agent - CLI + MCP Server for BSC",
     "main": "dist/index.js",
     "bin": {