shll-skills 5.0.1 → 5.1.0

package/README.md

@@ -65,7 +65,7 @@ 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 (20 total)
+### Available MCP Tools (22 total)
 
 | Tool | Type | Description |
 |------|------|-------------|
@@ -89,6 +89,8 @@ The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to d
 | `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 |
 
 ---
 

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
@@ -249,6 +249,27 @@ If the user has multiple DeFi skills installed, understand the architectural dif
 
 **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

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.1",
+    "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",