shll-skills 5.0.0 → 5.1.0

package/README.md

@@ -65,18 +65,32 @@ RUNNER_PRIVATE_KEY=0x... shll-mcp
 
 The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to discover all available tools.
 
-### Available MCP Tools
+### Available MCP Tools (22 total)
 
 | Tool | Type | Description |
 |------|------|-------------|
 | `portfolio` | Read | Vault holdings + token balances |
 | `balance` | Read | Operator wallet gas balance |
 | `price` | Read | Real-time token price (DexScreener) |
+| `search` | Read | Search token by name/symbol on BSC |
+| `tokens` | Read | List known token symbols + addresses |
 | `lending_info` | Read | Venus Protocol supply balances + APY |
+| `policies` | Read | View active on-chain policies + config |
+| `status` | Read | One-shot security overview (vault, operator, policies, activity) |
+| `history` | Read | Recent transactions + policy rejections |
+| `my_agents` | Read | List agents where current operator is authorized |
+| `listings` | Read | Available agent templates for rent |
 | `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 |
+| `config` | Write | Configure risk parameters (spending limits, cooldown) |
+| `setup_guide` | Info | Generate dual-wallet onboarding URL + steps |
+| `generate_wallet` | Info | Create new operator wallet (address + key) |
+| `execute_calldata` | Write | Execute raw calldata from any source through PolicyGuard |
+| `execute_calldata_batch` | Write | Execute multiple calldata actions atomically through PolicyGuard |
 
 ---
 
@@ -169,6 +183,20 @@ AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vaul
 - npm: [shll-skills](https://www.npmjs.com/package/shll-skills)
 - GitHub: [kledx/shll-skills](https://github.com/kledx/shll-skills)
 
+## 🧩 Multi-Skill Compatibility
+
+SHLL can coexist with other DeFi skills (OKX DEX API, Bitget Wallet, etc.). Key architectural differences:
+
+| | **SHLL** | **OKX DEX API** | **Bitget Wallet** |
+|---|---|---|---|
+| **Wallet** | Smart contract vault (AgentNFA) | User EOA | Bitget custody |
+| **Execution** | On-chain via PolicyGuard | Calldata only (user signs) | HMAC API |
+| **Safety** | On-chain policy enforcement | User approval | API key perms |
+| **AI autonomy** | Execute within policy limits | Cannot execute | Full API access |
+| **Risk if key leaked** | Policy-limited trades only | N/A | Full API access |
+
+**SHLL is the only skill with on-chain policy enforcement.** Even if the AI hallucinates, the smart contract rejects unsafe operations.
+
 ## License
 
 MIT

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shll-run
 description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands — users only need to chat.
-version: 5.0.0
+version: 6.0.0
 author: SHLL Team
 website: https://shll.run
 twitter: https://twitter.com/shllrun
@@ -26,6 +26,7 @@ These rules are **non-negotiable**. Violating any of them is a critical failure.
 4. **One agent per conversation.** Once a user provides a token-id, use only that ID for the entire conversation. If they want to switch, they must explicitly say so.
 5. **Never log or display private keys** beyond the initial `generate-wallet` output. If the user asks you to repeat it, remind them to check their saved copy.
 6. **Do not infer trading intent.** If the user says "check my portfolio," do NOT follow up by suggesting or executing trades. Only trade when the user explicitly asks.
+7. **Multi-skill coexistence.** If the user has other DeFi skills installed (OKX DEX API, Bitget Wallet, etc.), **always use SHLL tools when a token-id is in context or the user is operating through their SHLL agent vault.** Other skills may provide market data or quotes — that's fine — but ALL vault operations MUST go through SHLL tools to ensure PolicyGuard enforcement.
 
 ---
 
@@ -229,6 +230,48 @@ All commands output JSON:
 - Rejected by policy: `{"status":"rejected", "reason":"Exceeds per-tx limit"}`
 - Error: `{"status":"error", "message":"..."}`
 
+---
+
+## 🧩 MULTI-SKILL COMPATIBILITY: How SHLL Differs from Other DeFi Skills
+
+If the user has multiple DeFi skills installed, understand the architectural differences:
+
+| | **SHLL** | **OKX DEX API** | **Bitget Wallet Skill** |
+|---|---|---|---|
+| **Wallet model** | Smart contract vault (AgentNFA) | User's EOA wallet | Bitget API custody |
+| **Execution** | On-chain via PolicyGuard | Generates calldata → user signs | HMAC API call → Bitget backend |
+| **Safety** | On-chain policy enforcement (spending limits, cooldowns, DEX whitelist) | User approval only | API key permissions |
+| **Fund location** | On-chain vault (isolated per agent) | User's wallet directly | Bitget platform |
+| **AI autonomy** | Can execute within policy limits | Cannot execute (calldata only) | Can execute via API |
+| **Risk if key leaked** | Limited to policy-allowed trades | N/A (no key) | Full API access |
+
+**Key distinction:** SHLL is the only skill with **on-chain policy enforcement**. Even if the AI makes a mistake, the smart contract rejects operations that violate spending limits or cooldowns. Other skills rely on the user or platform to gatekeep.
+
+**Routing rule:** When the user's intent involves their SHLL agent vault (identified by token-id), ALWAYS use SHLL tools. It's fine to use other skills for price quotes, market research, or operations outside SHLL.
+
+### Cross-Skill Execution Pattern
+
+If another skill provides **calldata** (e.g. OKX DEX API returns a swap route), you can execute it through SHLL's safety layer:
+
+1. **Get calldata from other skill** → e.g., OKX returns `{to: "0xDEX...", data: "0xABC...", value: "100000..."}`
+2. **Execute via SHLL** → use `execute_calldata` tool with the target, data, and value
+3. **PolicyGuard validates** → spending limits, cooldowns, whitelists enforced
+4. **Vault executes** → transaction runs from the agent vault
+
+Example flow:
+```
+User: "Use OKX to find the best swap route for 0.5 BNB to USDT, then execute it"
+
+Step 1: Call OKX DEX API skill → get calldata
+Step 2: Call SHLL execute_calldata(token_id, target, data, value) → PolicyGuard validated execution
+```
+
+**This pattern gives you the best of both worlds:** superior routing from specialized DEX aggregators + SHLL's on-chain policy enforcement.
+
+For multi-step transactions (e.g. approve + swap), use `execute_calldata_batch` to execute atomically.
+
+---
+
 ## LINKS
 - Website: https://shll.run
 - Twitter: @shllrun

package/dist/mcp.js

@@ -1314,6 +1314,96 @@ server.tool(
     };
   }
 );
+server.tool(
+  "execute_calldata",
+  "Execute raw calldata through PolicyGuard safety layer. Use this to execute transactions from other DeFi skills (OKX DEX API, Bitget, 1inch, etc.) with SHLL on-chain policy enforcement. All actions are validated against spending limits, cooldowns, and whitelists before execution.",
+  {
+    token_id: import_zod.z.string().describe("Agent NFA Token ID"),
+    target: import_zod.z.string().describe("Target contract address (0x...)"),
+    data: import_zod.z.string().describe("Transaction calldata hex string"),
+    value: import_zod.z.string().default("0").describe("Native BNB value in wei (default: 0)")
+  },
+  async ({ token_id, target, data, value }) => {
+    const { policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const action = {
+      target,
+      value: BigInt(value),
+      data
+    };
+    const sim = await policyClient.validate(tokenId, action);
+    if (!sim.ok) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "rejected",
+            reason: sim.reason,
+            note: "PolicyGuard rejected this calldata. The target contract or operation may not be whitelisted, or it exceeds spending/cooldown limits."
+          })
+        }]
+      };
+    }
+    const result = await policyClient.execute(tokenId, action, true);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "success",
+          hash: result.hash,
+          note: "Calldata executed through PolicyGuard. Transaction validated against all on-chain policies."
+        })
+      }]
+    };
+  }
+);
+server.tool(
+  "execute_calldata_batch",
+  "Execute multiple raw calldata actions atomically through PolicyGuard. Useful for approve+swap patterns from external DEX aggregators.",
+  {
+    token_id: import_zod.z.string().describe("Agent NFA Token ID"),
+    actions: import_zod.z.array(import_zod.z.object({
+      target: import_zod.z.string().describe("Target contract address"),
+      data: import_zod.z.string().describe("Calldata hex"),
+      value: import_zod.z.string().default("0").describe("BNB value in wei")
+    })).describe("Array of actions to execute atomically")
+  },
+  async ({ token_id, actions: rawActions }) => {
+    const { policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const actions = rawActions.map((a) => ({
+      target: a.target,
+      value: BigInt(a.value || "0"),
+      data: a.data
+    }));
+    for (let i = 0; i < actions.length; i++) {
+      const sim = await policyClient.validate(tokenId, actions[i]);
+      if (!sim.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "rejected",
+              failedActionIndex: i,
+              reason: sim.reason
+            })
+          }]
+        };
+      }
+    }
+    const result = actions.length === 1 ? await policyClient.execute(tokenId, actions[0], true) : await policyClient.executeBatch(tokenId, actions, true);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "success",
+          hash: result.hash,
+          actionsExecuted: actions.length
+        })
+      }]
+    };
+  }
+);
 server.tool(
   "generate_wallet",
   "Generate a new operator wallet (address + private key) for AI to use. This is a HOT wallet for trading only.",

package/dist/mcp.mjs

@@ -825,6 +825,96 @@ server.tool(
     };
   }
 );
+server.tool(
+  "execute_calldata",
+  "Execute raw calldata through PolicyGuard safety layer. Use this to execute transactions from other DeFi skills (OKX DEX API, Bitget, 1inch, etc.) with SHLL on-chain policy enforcement. All actions are validated against spending limits, cooldowns, and whitelists before execution.",
+  {
+    token_id: z.string().describe("Agent NFA Token ID"),
+    target: z.string().describe("Target contract address (0x...)"),
+    data: z.string().describe("Transaction calldata hex string"),
+    value: z.string().default("0").describe("Native BNB value in wei (default: 0)")
+  },
+  async ({ token_id, target, data, value }) => {
+    const { policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const action = {
+      target,
+      value: BigInt(value),
+      data
+    };
+    const sim = await policyClient.validate(tokenId, action);
+    if (!sim.ok) {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "rejected",
+            reason: sim.reason,
+            note: "PolicyGuard rejected this calldata. The target contract or operation may not be whitelisted, or it exceeds spending/cooldown limits."
+          })
+        }]
+      };
+    }
+    const result = await policyClient.execute(tokenId, action, true);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "success",
+          hash: result.hash,
+          note: "Calldata executed through PolicyGuard. Transaction validated against all on-chain policies."
+        })
+      }]
+    };
+  }
+);
+server.tool(
+  "execute_calldata_batch",
+  "Execute multiple raw calldata actions atomically through PolicyGuard. Useful for approve+swap patterns from external DEX aggregators.",
+  {
+    token_id: z.string().describe("Agent NFA Token ID"),
+    actions: z.array(z.object({
+      target: z.string().describe("Target contract address"),
+      data: z.string().describe("Calldata hex"),
+      value: z.string().default("0").describe("BNB value in wei")
+    })).describe("Array of actions to execute atomically")
+  },
+  async ({ token_id, actions: rawActions }) => {
+    const { policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const actions = rawActions.map((a) => ({
+      target: a.target,
+      value: BigInt(a.value || "0"),
+      data: a.data
+    }));
+    for (let i = 0; i < actions.length; i++) {
+      const sim = await policyClient.validate(tokenId, actions[i]);
+      if (!sim.ok) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "rejected",
+              failedActionIndex: i,
+              reason: sim.reason
+            })
+          }]
+        };
+      }
+    }
+    const result = actions.length === 1 ? await policyClient.execute(tokenId, actions[0], true) : await policyClient.executeBatch(tokenId, actions, true);
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "success",
+          hash: result.hash,
+          actionsExecuted: actions.length
+        })
+      }]
+    };
+  }
+);
 server.tool(
   "generate_wallet",
   "Generate a new operator wallet (address + private key) for AI to use. This is a HOT wallet for trading only.",

package/package.json

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

package/src/mcp.ts

@@ -968,6 +968,107 @@ server.tool(
     }
 );
 
+// ── Tool: execute_calldata ──────────────────────────────
+// Universal safety execution layer: accepts calldata from ANY source
+// (OKX DEX API, Bitget, 1inch, etc.) and routes through PolicyGuard
+server.tool(
+    "execute_calldata",
+    "Execute raw calldata through PolicyGuard safety layer. Use this to execute transactions from other DeFi skills (OKX DEX API, Bitget, 1inch, etc.) with SHLL on-chain policy enforcement. All actions are validated against spending limits, cooldowns, and whitelists before execution.",
+    {
+        token_id: z.string().describe("Agent NFA Token ID"),
+        target: z.string().describe("Target contract address (0x...)"),
+        data: z.string().describe("Transaction calldata hex string"),
+        value: z.string().default("0").describe("Native BNB value in wei (default: 0)"),
+    },
+    async ({ token_id, target, data, value }) => {
+        const { policyClient } = createClients();
+        const tokenId = BigInt(token_id);
+        const action: Action = {
+            target: target as Address,
+            value: BigInt(value),
+            data: data as Hex,
+        };
+
+        // Validate through PolicyGuard (spending limits, cooldowns, whitelists)
+        const sim = await policyClient.validate(tokenId, action);
+        if (!sim.ok) {
+            return {
+                content: [{
+                    type: "text" as const, text: JSON.stringify({
+                        status: "rejected",
+                        reason: sim.reason,
+                        note: "PolicyGuard rejected this calldata. The target contract or operation may not be whitelisted, or it exceeds spending/cooldown limits.",
+                    })
+                }]
+            };
+        }
+
+        const result = await policyClient.execute(tokenId, action, true);
+        return {
+            content: [{
+                type: "text" as const, text: JSON.stringify({
+                    status: "success",
+                    hash: result.hash,
+                    note: "Calldata executed through PolicyGuard. Transaction validated against all on-chain policies.",
+                })
+            }]
+        };
+    }
+);
+
+// ── Tool: execute_calldata_batch ─────────────────────────
+server.tool(
+    "execute_calldata_batch",
+    "Execute multiple raw calldata actions atomically through PolicyGuard. Useful for approve+swap patterns from external DEX aggregators.",
+    {
+        token_id: z.string().describe("Agent NFA Token ID"),
+        actions: z.array(z.object({
+            target: z.string().describe("Target contract address"),
+            data: z.string().describe("Calldata hex"),
+            value: z.string().default("0").describe("BNB value in wei"),
+        })).describe("Array of actions to execute atomically"),
+    },
+    async ({ token_id, actions: rawActions }) => {
+        const { policyClient } = createClients();
+        const tokenId = BigInt(token_id);
+        const actions: Action[] = rawActions.map(a => ({
+            target: a.target as Address,
+            value: BigInt(a.value || "0"),
+            data: a.data as Hex,
+        }));
+
+        // Validate all actions
+        for (let i = 0; i < actions.length; i++) {
+            const sim = await policyClient.validate(tokenId, actions[i]);
+            if (!sim.ok) {
+                return {
+                    content: [{
+                        type: "text" as const, text: JSON.stringify({
+                            status: "rejected",
+                            failedActionIndex: i,
+                            reason: sim.reason,
+                        })
+                    }]
+                };
+            }
+        }
+
+        const result = actions.length === 1
+            ? await policyClient.execute(tokenId, actions[0], true)
+            : await policyClient.executeBatch(tokenId, actions, true);
+
+        return {
+            content: [{
+                type: "text" as const, text: JSON.stringify({
+                    status: "success",
+                    hash: result.hash,
+                    actionsExecuted: actions.length,
+                })
+            }]
+        };
+    }
+);
+
 // ── Tool: generate_wallet ───────────────────────────────
 server.tool(
     "generate_wallet",