shll-skills 5.2.1 → 5.3.1

package/dist/mcp.js

@@ -613,7 +613,12 @@ var WBNB_ABI = [
 ];
 var SPENDING_LIMIT_ABI = [
   { type: "function", name: "setLimits", inputs: [{ name: "instanceId", type: "uint256" }, { name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], outputs: [], stateMutability: "nonpayable" },
-  { type: "function", name: "instanceLimits", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], stateMutability: "view" }
+  { type: "function", name: "instanceLimits", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], stateMutability: "view" },
+  { type: "function", name: "tokenRestrictionEnabled", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "bool" }], stateMutability: "view" },
+  { type: "function", name: "getTokenList", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "address[]" }], stateMutability: "view" },
+  { type: "function", name: "addToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" },
+  { type: "function", name: "removeToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" },
+  { type: "function", name: "setTokenRestriction", inputs: [{ name: "instanceId", type: "uint256" }, { name: "enabled", type: "bool" }], outputs: [], stateMutability: "nonpayable" }
 ];
 var COOLDOWN_ABI = [
   { type: "function", name: "setCooldown", inputs: [{ name: "instanceId", type: "uint256" }, { name: "seconds_", type: "uint256" }], outputs: [], stateMutability: "nonpayable" },
@@ -683,9 +688,28 @@ async function checkAgentExpiry(tokenId) {
   }
   return { expired: false };
 }
+function policyRejectionHelp(reason, tokenId) {
+  const consoleUrl = `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${tokenId}/console/safety`;
+  const r = reason ?? "";
+  if (r.includes("Approve spender not allowed"))
+    return { explanation: "The DEX router address is not in the approved spender whitelist. This is a platform-level security setting.", action: "Contact the Agent owner to approve this router, or use a different DEX.", consoleUrl };
+  if (r.includes("Target not allowed"))
+    return { explanation: "The contract address is not in the DeFi target whitelist.", action: "Enable the corresponding DeFi Pack in Console > Safety, or contact the Agent owner.", consoleUrl };
+  if (r.includes("Token not in whitelist"))
+    return { explanation: "Token restriction is ON and this token is not whitelisted.", action: `Add the token to the whitelist or disable token restriction at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Exceeds per-tx limit"))
+    return { explanation: "Transaction value exceeds the per-transaction spending limit.", action: `Reduce the amount, or increase the limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Daily limit"))
+    return { explanation: "Daily spending limit would be exceeded.", action: `Wait until tomorrow, or increase the daily limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Approve exceeds limit"))
+    return { explanation: "The approve amount exceeds the configured approve limit.", action: `Reduce the amount, or increase the approve limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Cooldown"))
+    return { explanation: "Cooldown period has not elapsed since the last transaction.", action: "Wait for the cooldown to expire before retrying.", consoleUrl };
+  return { explanation: "Transaction was rejected by an on-chain security policy.", action: `Review your security settings at: ${consoleUrl}`, consoleUrl };
+}
 var server = new import_mcp.McpServer({
   name: "shll-defi",
-  version: "5.2.0"
+  version: "5.3.0"
 });
 server.tool(
   "portfolio",
@@ -850,7 +874,44 @@ server.tool(
     }
     for (const action of actions) {
       const sim = await policyClient.validate(tokenId, action);
-      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+      if (!sim.ok) {
+        if (useV3 && sim.reason?.includes("Approve spender not allowed") && v2Available) {
+          const v2Actions = [];
+          const v2Router = PANCAKE_V2_ROUTER;
+          const v2MinOut = v2Quote * BigInt(100 - slippage) / 100n;
+          if (!isNativeIn) {
+            const allow = await publicClient.readContract({ address: fromToken.address, abi: ERC20_ABI, functionName: "allowance", args: [vault, v2Router] }).catch(() => 0n);
+            if (allow < amountIn) {
+              v2Actions.push({ target: fromToken.address, value: 0n, data: (0, import_viem2.encodeFunctionData)({ abi: ERC20_ABI, functionName: "approve", args: [v2Router, amountIn] }) });
+            }
+          }
+          const v2Path = tokenInAddr.toLowerCase() !== WBNB.toLowerCase() && tokenOutAddr.toLowerCase() !== WBNB.toLowerCase() ? [tokenInAddr, WBNB, tokenOutAddr] : [tokenInAddr, tokenOutAddr];
+          if (isNativeIn) {
+            v2Actions.push({ target: v2Router, value: amountIn, data: (0, import_viem2.encodeFunctionData)({ abi: SWAP_EXACT_ETH_ABI, functionName: "swapExactETHForTokens", args: [v2MinOut, v2Path, vault, deadline] }) });
+          } else {
+            v2Actions.push({ target: v2Router, value: 0n, data: (0, import_viem2.encodeFunctionData)({ abi: SWAP_EXACT_TOKENS_ABI, functionName: "swapExactTokensForTokens", args: [amountIn, v2MinOut, v2Path, vault, deadline] }) });
+          }
+          for (const v2a of v2Actions) {
+            const v2Sim = await policyClient.validate(tokenId, v2a);
+            if (!v2Sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: v2Sim.reason, ...policyRejectionHelp(v2Sim.reason, token_id) }) }] };
+          }
+          const v2Result = v2Actions.length === 1 ? await policyClient.execute(tokenId, v2Actions[0], true) : await policyClient.executeBatch(tokenId, v2Actions, true);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "success",
+                hash: v2Result.hash,
+                dex: "v2",
+                quote: v2Quote.toString(),
+                minOut: v2MinOut.toString(),
+                note: "V3 was rejected by policy (Approve spender not allowed). Auto-switched to V2."
+              })
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
+      }
     }
     const result = actions.length === 1 ? await policyClient.execute(tokenId, actions[0], true) : await policyClient.executeBatch(tokenId, actions, true);
     return {
@@ -899,7 +960,7 @@ server.tool(
     }
     for (const action of actions) {
       const sim = await policyClient.validate(tokenId, action);
-      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     }
     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, protocol: "venus", action: "supply", token: symbol, amount }) }] };
@@ -926,7 +987,7 @@ server.tool(
     const data = (0, import_viem2.encodeFunctionData)({ abi: VTOKEN_ABI, functionName: "redeemUnderlying", args: [amt] });
     const action = { target: vTokenAddr, value: 0n, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, protocol: "venus", action: "redeem", token: symbol, amount }) }] };
   }
@@ -991,7 +1052,7 @@ server.tool(
       action = { target: tokenInfo.address, value: 0n, data };
     }
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, token, amount, to: recipient }) }] };
   }
@@ -1078,7 +1139,7 @@ server.tool(
     const data = (0, import_viem2.encodeFunctionData)({ abi: WBNB_ABI, functionName: "deposit" });
     const action = { target: WBNB, value: amt, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, message: `Wrapped ${amount} BNB \u2192 WBNB` }) }] };
   }
@@ -1099,7 +1160,7 @@ server.tool(
     const data = (0, import_viem2.encodeFunctionData)({ abi: WBNB_ABI, functionName: "withdraw", args: [amt] });
     const action = { target: WBNB, value: 0n, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, message: `Unwrapped ${amount} WBNB \u2192 BNB` }) }] };
   }
@@ -1155,7 +1216,15 @@ server.tool(
           const [maxPerTx, maxPerDay, maxSlippageBps] = limits;
           const txBnb = (Number(maxPerTx) / 1e18).toFixed(4);
           const dayBnb = (Number(maxPerDay) / 1e18).toFixed(4);
-          entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString() };
+          let tokenRestriction = {};
+          try {
+            const enabled = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] });
+            const tokenList = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] });
+            tokenRestriction = { tokenRestrictionEnabled: enabled, whitelistedTokens: tokenList, whitelistedTokenCount: tokenList.length };
+            summaryParts.push(enabled ? `Token whitelist ON (${tokenList.length} tokens)` : "Token whitelist OFF (any token allowed)");
+          } catch {
+          }
+          entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString(), ...tokenRestriction };
           summaryParts.push(`Max ${txBnb} BNB/tx, ${dayBnb} BNB/day, slippage ${maxSlippageBps}bps`);
         } catch {
         }
@@ -1179,6 +1248,38 @@ server.tool(
     return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, humanSummary, securityNote: "Operator wallet CANNOT withdraw vault funds or transfer Agent NFT.", policies: enriched }) }] };
   }
 );
+server.tool(
+  "token_restriction",
+  "Check token whitelist restriction status. Shows whether token trading is restricted and which tokens are whitelisted.",
+  { token_id: import_zod.z.string().describe("Agent NFA Token ID") },
+  async ({ token_id }) => {
+    const { publicClient, policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const policies = await policyClient.getPolicies(tokenId);
+    const spendingPolicy = policies.find((p) => p.policyTypeName === "spending_limit");
+    if (!spendingPolicy) {
+      return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, error: "No spending_limit policy found \u2014 token restriction is not available for this agent." }) }] };
+    }
+    try {
+      const [enabled, tokenList] = await Promise.all([
+        publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] }),
+        publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] })
+      ]);
+      const result = {
+        tokenId: token_id,
+        tokenRestrictionEnabled: enabled,
+        status: enabled ? "ON \u2014 only whitelisted tokens can be traded" : "OFF \u2014 any token can be traded",
+        whitelistedTokens: tokenList,
+        whitelistedTokenCount: tokenList.length,
+        manageUrl: `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${token_id}/console/safety`,
+        note: enabled ? "To add/remove tokens or disable restriction, visit the management URL above (requires connected wallet as renter/owner)." : "Token restriction is disabled. The agent can trade any token. To enable, visit the management URL."
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    } catch {
+      return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, error: "Failed to read token restriction \u2014 the SpendingLimitPolicy may not support this feature." }) }] };
+    }
+  }
+);
 server.tool(
   "status",
   "One-shot security overview: vault balance, operator status, policies, and recent activity",

package/dist/mcp.mjs

@@ -124,7 +124,12 @@ var WBNB_ABI = [
 ];
 var SPENDING_LIMIT_ABI = [
   { type: "function", name: "setLimits", inputs: [{ name: "instanceId", type: "uint256" }, { name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], outputs: [], stateMutability: "nonpayable" },
-  { type: "function", name: "instanceLimits", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], stateMutability: "view" }
+  { type: "function", name: "instanceLimits", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], stateMutability: "view" },
+  { type: "function", name: "tokenRestrictionEnabled", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "bool" }], stateMutability: "view" },
+  { type: "function", name: "getTokenList", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "address[]" }], stateMutability: "view" },
+  { type: "function", name: "addToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" },
+  { type: "function", name: "removeToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" },
+  { type: "function", name: "setTokenRestriction", inputs: [{ name: "instanceId", type: "uint256" }, { name: "enabled", type: "bool" }], outputs: [], stateMutability: "nonpayable" }
 ];
 var COOLDOWN_ABI = [
   { type: "function", name: "setCooldown", inputs: [{ name: "instanceId", type: "uint256" }, { name: "seconds_", type: "uint256" }], outputs: [], stateMutability: "nonpayable" },
@@ -194,9 +199,28 @@ async function checkAgentExpiry(tokenId) {
   }
   return { expired: false };
 }
+function policyRejectionHelp(reason, tokenId) {
+  const consoleUrl = `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${tokenId}/console/safety`;
+  const r = reason ?? "";
+  if (r.includes("Approve spender not allowed"))
+    return { explanation: "The DEX router address is not in the approved spender whitelist. This is a platform-level security setting.", action: "Contact the Agent owner to approve this router, or use a different DEX.", consoleUrl };
+  if (r.includes("Target not allowed"))
+    return { explanation: "The contract address is not in the DeFi target whitelist.", action: "Enable the corresponding DeFi Pack in Console > Safety, or contact the Agent owner.", consoleUrl };
+  if (r.includes("Token not in whitelist"))
+    return { explanation: "Token restriction is ON and this token is not whitelisted.", action: `Add the token to the whitelist or disable token restriction at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Exceeds per-tx limit"))
+    return { explanation: "Transaction value exceeds the per-transaction spending limit.", action: `Reduce the amount, or increase the limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Daily limit"))
+    return { explanation: "Daily spending limit would be exceeded.", action: `Wait until tomorrow, or increase the daily limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Approve exceeds limit"))
+    return { explanation: "The approve amount exceeds the configured approve limit.", action: `Reduce the amount, or increase the approve limit at: ${consoleUrl}`, consoleUrl };
+  if (r.includes("Cooldown"))
+    return { explanation: "Cooldown period has not elapsed since the last transaction.", action: "Wait for the cooldown to expire before retrying.", consoleUrl };
+  return { explanation: "Transaction was rejected by an on-chain security policy.", action: `Review your security settings at: ${consoleUrl}`, consoleUrl };
+}
 var server = new McpServer({
   name: "shll-defi",
-  version: "5.2.0"
+  version: "5.3.0"
 });
 server.tool(
   "portfolio",
@@ -361,7 +385,44 @@ server.tool(
     }
     for (const action of actions) {
       const sim = await policyClient.validate(tokenId, action);
-      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+      if (!sim.ok) {
+        if (useV3 && sim.reason?.includes("Approve spender not allowed") && v2Available) {
+          const v2Actions = [];
+          const v2Router = PANCAKE_V2_ROUTER;
+          const v2MinOut = v2Quote * BigInt(100 - slippage) / 100n;
+          if (!isNativeIn) {
+            const allow = await publicClient.readContract({ address: fromToken.address, abi: ERC20_ABI, functionName: "allowance", args: [vault, v2Router] }).catch(() => 0n);
+            if (allow < amountIn) {
+              v2Actions.push({ target: fromToken.address, value: 0n, data: encodeFunctionData({ abi: ERC20_ABI, functionName: "approve", args: [v2Router, amountIn] }) });
+            }
+          }
+          const v2Path = tokenInAddr.toLowerCase() !== WBNB.toLowerCase() && tokenOutAddr.toLowerCase() !== WBNB.toLowerCase() ? [tokenInAddr, WBNB, tokenOutAddr] : [tokenInAddr, tokenOutAddr];
+          if (isNativeIn) {
+            v2Actions.push({ target: v2Router, value: amountIn, data: encodeFunctionData({ abi: SWAP_EXACT_ETH_ABI, functionName: "swapExactETHForTokens", args: [v2MinOut, v2Path, vault, deadline] }) });
+          } else {
+            v2Actions.push({ target: v2Router, value: 0n, data: encodeFunctionData({ abi: SWAP_EXACT_TOKENS_ABI, functionName: "swapExactTokensForTokens", args: [amountIn, v2MinOut, v2Path, vault, deadline] }) });
+          }
+          for (const v2a of v2Actions) {
+            const v2Sim = await policyClient.validate(tokenId, v2a);
+            if (!v2Sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: v2Sim.reason, ...policyRejectionHelp(v2Sim.reason, token_id) }) }] };
+          }
+          const v2Result = v2Actions.length === 1 ? await policyClient.execute(tokenId, v2Actions[0], true) : await policyClient.executeBatch(tokenId, v2Actions, true);
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                status: "success",
+                hash: v2Result.hash,
+                dex: "v2",
+                quote: v2Quote.toString(),
+                minOut: v2MinOut.toString(),
+                note: "V3 was rejected by policy (Approve spender not allowed). Auto-switched to V2."
+              })
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
+      }
     }
     const result = actions.length === 1 ? await policyClient.execute(tokenId, actions[0], true) : await policyClient.executeBatch(tokenId, actions, true);
     return {
@@ -410,7 +471,7 @@ server.tool(
     }
     for (const action of actions) {
       const sim = await policyClient.validate(tokenId, action);
-      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+      if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     }
     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, protocol: "venus", action: "supply", token: symbol, amount }) }] };
@@ -437,7 +498,7 @@ server.tool(
     const data = encodeFunctionData({ abi: VTOKEN_ABI, functionName: "redeemUnderlying", args: [amt] });
     const action = { target: vTokenAddr, value: 0n, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, protocol: "venus", action: "redeem", token: symbol, amount }) }] };
   }
@@ -502,7 +563,7 @@ server.tool(
       action = { target: tokenInfo.address, value: 0n, data };
     }
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, token, amount, to: recipient }) }] };
   }
@@ -589,7 +650,7 @@ server.tool(
     const data = encodeFunctionData({ abi: WBNB_ABI, functionName: "deposit" });
     const action = { target: WBNB, value: amt, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, message: `Wrapped ${amount} BNB \u2192 WBNB` }) }] };
   }
@@ -610,7 +671,7 @@ server.tool(
     const data = encodeFunctionData({ abi: WBNB_ABI, functionName: "withdraw", args: [amt] });
     const action = { target: WBNB, value: 0n, data };
     const sim = await policyClient.validate(tokenId, action);
-    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+    if (!sim.ok) return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
     const result = await policyClient.execute(tokenId, action, true);
     return { content: [{ type: "text", text: JSON.stringify({ status: "success", hash: result.hash, message: `Unwrapped ${amount} WBNB \u2192 BNB` }) }] };
   }
@@ -666,7 +727,15 @@ server.tool(
           const [maxPerTx, maxPerDay, maxSlippageBps] = limits;
           const txBnb = (Number(maxPerTx) / 1e18).toFixed(4);
           const dayBnb = (Number(maxPerDay) / 1e18).toFixed(4);
-          entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString() };
+          let tokenRestriction = {};
+          try {
+            const enabled = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] });
+            const tokenList = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] });
+            tokenRestriction = { tokenRestrictionEnabled: enabled, whitelistedTokens: tokenList, whitelistedTokenCount: tokenList.length };
+            summaryParts.push(enabled ? `Token whitelist ON (${tokenList.length} tokens)` : "Token whitelist OFF (any token allowed)");
+          } catch {
+          }
+          entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString(), ...tokenRestriction };
           summaryParts.push(`Max ${txBnb} BNB/tx, ${dayBnb} BNB/day, slippage ${maxSlippageBps}bps`);
         } catch {
         }
@@ -690,6 +759,38 @@ server.tool(
     return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, humanSummary, securityNote: "Operator wallet CANNOT withdraw vault funds or transfer Agent NFT.", policies: enriched }) }] };
   }
 );
+server.tool(
+  "token_restriction",
+  "Check token whitelist restriction status. Shows whether token trading is restricted and which tokens are whitelisted.",
+  { token_id: z.string().describe("Agent NFA Token ID") },
+  async ({ token_id }) => {
+    const { publicClient, policyClient } = createClients();
+    const tokenId = BigInt(token_id);
+    const policies = await policyClient.getPolicies(tokenId);
+    const spendingPolicy = policies.find((p) => p.policyTypeName === "spending_limit");
+    if (!spendingPolicy) {
+      return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, error: "No spending_limit policy found \u2014 token restriction is not available for this agent." }) }] };
+    }
+    try {
+      const [enabled, tokenList] = await Promise.all([
+        publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] }),
+        publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] })
+      ]);
+      const result = {
+        tokenId: token_id,
+        tokenRestrictionEnabled: enabled,
+        status: enabled ? "ON \u2014 only whitelisted tokens can be traded" : "OFF \u2014 any token can be traded",
+        whitelistedTokens: tokenList,
+        whitelistedTokenCount: tokenList.length,
+        manageUrl: `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${token_id}/console/safety`,
+        note: enabled ? "To add/remove tokens or disable restriction, visit the management URL above (requires connected wallet as renter/owner)." : "Token restriction is disabled. The agent can trade any token. To enable, visit the management URL."
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    } catch {
+      return { content: [{ type: "text", text: JSON.stringify({ tokenId: token_id, error: "Failed to read token restriction \u2014 the SpendingLimitPolicy may not support this feature." }) }] };
+    }
+  }
+);
 server.tool(
   "status",
   "One-shot security overview: vault balance, operator status, policies, and recent activity",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shll-skills",
-    "version": "5.2.1",
+    "version": "5.3.1",
     "description": "SHLL DeFi Agent — CLI + MCP Server for BSC",
     "main": "dist/index.js",
     "bin": {
@@ -24,4 +24,4 @@
         "tsup": "^8.0.2",
         "typescript": "^5.4.5"
     }
-}
+}

package/src/mcp.ts

@@ -153,6 +153,11 @@ const WBNB_ABI = [
 const SPENDING_LIMIT_ABI = [
     { type: "function" as const, name: "setLimits", inputs: [{ name: "instanceId", type: "uint256" }, { name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], outputs: [], stateMutability: "nonpayable" as const },
     { type: "function" as const, name: "instanceLimits", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "maxPerTx", type: "uint256" }, { name: "maxPerDay", type: "uint256" }, { name: "maxSlippageBps", type: "uint256" }], stateMutability: "view" as const },
+    { type: "function" as const, name: "tokenRestrictionEnabled", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "bool" }], stateMutability: "view" as const },
+    { type: "function" as const, name: "getTokenList", inputs: [{ name: "instanceId", type: "uint256" }], outputs: [{ name: "", type: "address[]" }], stateMutability: "view" as const },
+    { type: "function" as const, name: "addToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" as const },
+    { type: "function" as const, name: "removeToken", inputs: [{ name: "instanceId", type: "uint256" }, { name: "token", type: "address" }], outputs: [], stateMutability: "nonpayable" as const },
+    { type: "function" as const, name: "setTokenRestriction", inputs: [{ name: "instanceId", type: "uint256" }, { name: "enabled", type: "bool" }], outputs: [], stateMutability: "nonpayable" as const },
 ] as const;
 
 const COOLDOWN_ABI = [
@@ -234,13 +239,34 @@ async function checkAgentExpiry(tokenId: bigint) {
     return { expired: false };
 }
 
+// Policy rejection → actionable user guidance
+function policyRejectionHelp(reason: string | undefined, tokenId: string): Record<string, string> {
+    const consoleUrl = `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${tokenId}/console/safety`;
+    const r = reason ?? "";
+    if (r.includes("Approve spender not allowed"))
+        return { explanation: "The DEX router address is not in the approved spender whitelist. This is a platform-level security setting.", action: "Contact the Agent owner to approve this router, or use a different DEX.", consoleUrl };
+    if (r.includes("Target not allowed"))
+        return { explanation: "The contract address is not in the DeFi target whitelist.", action: "Enable the corresponding DeFi Pack in Console > Safety, or contact the Agent owner.", consoleUrl };
+    if (r.includes("Token not in whitelist"))
+        return { explanation: "Token restriction is ON and this token is not whitelisted.", action: `Add the token to the whitelist or disable token restriction at: ${consoleUrl}`, consoleUrl };
+    if (r.includes("Exceeds per-tx limit"))
+        return { explanation: "Transaction value exceeds the per-transaction spending limit.", action: `Reduce the amount, or increase the limit at: ${consoleUrl}`, consoleUrl };
+    if (r.includes("Daily limit"))
+        return { explanation: "Daily spending limit would be exceeded.", action: `Wait until tomorrow, or increase the daily limit at: ${consoleUrl}`, consoleUrl };
+    if (r.includes("Approve exceeds limit"))
+        return { explanation: "The approve amount exceeds the configured approve limit.", action: `Reduce the amount, or increase the approve limit at: ${consoleUrl}`, consoleUrl };
+    if (r.includes("Cooldown"))
+        return { explanation: "Cooldown period has not elapsed since the last transaction.", action: "Wait for the cooldown to expire before retrying.", consoleUrl };
+    return { explanation: "Transaction was rejected by an on-chain security policy.", action: `Review your security settings at: ${consoleUrl}`, consoleUrl };
+}
+
 // ═══════════════════════════════════════════════════════
 //                    MCP Server
 // ═══════════════════════════════════════════════════════
 
 const server = new McpServer({
     name: "shll-defi",
-    version: "5.2.0",
+    version: "5.3.0",
 });
 
 // ── Tool: portfolio ─────────────────────────────────────
@@ -421,10 +447,48 @@ server.tool(
             }
         }
 
-        // Validate + execute
+        // Validate + execute (with V3→V2 fallback on approve rejection)
         for (const action of actions) {
             const sim = await policyClient.validate(tokenId, action);
-            if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+            if (!sim.ok) {
+                // If V3 approve was rejected, try V2 fallback
+                if (useV3 && sim.reason?.includes("Approve spender not allowed") && v2Available) {
+                    const v2Actions: Action[] = [];
+                    const v2Router = PANCAKE_V2_ROUTER as Address;
+                    const v2MinOut = (v2Quote * BigInt(100 - slippage)) / 100n;
+                    if (!isNativeIn) {
+                        const allow = await publicClient.readContract({ address: fromToken.address, abi: ERC20_ABI, functionName: "allowance", args: [vault, v2Router] }).catch(() => 0n);
+                        if (allow < amountIn) {
+                            v2Actions.push({ target: fromToken.address, value: 0n, data: encodeFunctionData({ abi: ERC20_ABI, functionName: "approve", args: [v2Router, amountIn] }) });
+                        }
+                    }
+                    const v2Path: Address[] = tokenInAddr.toLowerCase() !== WBNB.toLowerCase() && tokenOutAddr.toLowerCase() !== WBNB.toLowerCase()
+                        ? [tokenInAddr, WBNB as Address, tokenOutAddr] : [tokenInAddr, tokenOutAddr];
+                    if (isNativeIn) {
+                        v2Actions.push({ target: v2Router, value: amountIn, data: encodeFunctionData({ abi: SWAP_EXACT_ETH_ABI, functionName: "swapExactETHForTokens", args: [v2MinOut, v2Path, vault, deadline] }) });
+                    } else {
+                        v2Actions.push({ target: v2Router, value: 0n, data: encodeFunctionData({ abi: SWAP_EXACT_TOKENS_ABI, functionName: "swapExactTokensForTokens", args: [amountIn, v2MinOut, v2Path, vault, deadline] }) });
+                    }
+                    // Validate V2 fallback
+                    for (const v2a of v2Actions) {
+                        const v2Sim = await policyClient.validate(tokenId, v2a);
+                        if (!v2Sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: v2Sim.reason, ...policyRejectionHelp(v2Sim.reason, token_id) }) }] };
+                    }
+                    const v2Result = v2Actions.length === 1
+                        ? await policyClient.execute(tokenId, v2Actions[0], true)
+                        : await policyClient.executeBatch(tokenId, v2Actions, true);
+                    return {
+                        content: [{
+                            type: "text" as const, text: JSON.stringify({
+                                status: "success", hash: v2Result.hash, dex: "v2",
+                                quote: v2Quote.toString(), minOut: v2MinOut.toString(),
+                                note: "V3 was rejected by policy (Approve spender not allowed). Auto-switched to V2.",
+                            })
+                        }]
+                    };
+                }
+                return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
+            }
         }
 
         const result = actions.length === 1
@@ -477,7 +541,7 @@ server.tool(
 
         for (const action of actions) {
             const sim = await policyClient.validate(tokenId, action);
-            if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+            if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
         }
 
         const result = actions.length === 1
@@ -511,7 +575,7 @@ server.tool(
         const action: Action = { target: vTokenAddr, value: 0n, data };
 
         const sim = await policyClient.validate(tokenId, action);
-        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
 
         const result = await policyClient.execute(tokenId, action, true);
         return { content: [{ type: "text" as const, text: JSON.stringify({ status: "success", hash: result.hash, protocol: "venus", action: "redeem", token: symbol, amount }) }] };
@@ -585,7 +649,7 @@ server.tool(
         }
 
         const sim = await policyClient.validate(tokenId, action);
-        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
 
         const result = await policyClient.execute(tokenId, action, true);
         return { content: [{ type: "text" as const, text: JSON.stringify({ status: "success", hash: result.hash, token, amount, to: recipient }) }] };
@@ -678,7 +742,7 @@ server.tool(
         const action: Action = { target: WBNB as Address, value: amt, data };
 
         const sim = await policyClient.validate(tokenId, action);
-        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
 
         const result = await policyClient.execute(tokenId, action, true);
         return { content: [{ type: "text" as const, text: JSON.stringify({ status: "success", hash: result.hash, message: `Wrapped ${amount} BNB → WBNB` }) }] };
@@ -702,7 +766,7 @@ server.tool(
         const action: Action = { target: WBNB as Address, value: 0n, data };
 
         const sim = await policyClient.validate(tokenId, action);
-        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason }) }] };
+        if (!sim.ok) return { content: [{ type: "text" as const, text: JSON.stringify({ status: "rejected", reason: sim.reason, ...policyRejectionHelp(sim.reason, token_id) }) }] };
 
         const result = await policyClient.execute(tokenId, action, true);
         return { content: [{ type: "text" as const, text: JSON.stringify({ status: "success", hash: result.hash, message: `Unwrapped ${amount} WBNB → BNB` }) }] };
@@ -768,7 +832,15 @@ server.tool(
                     const [maxPerTx, maxPerDay, maxSlippageBps] = limits;
                     const txBnb = (Number(maxPerTx) / 1e18).toFixed(4);
                     const dayBnb = (Number(maxPerDay) / 1e18).toFixed(4);
-                    entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString() };
+                    // Also read token restriction status
+                    let tokenRestriction: Record<string, unknown> = {};
+                    try {
+                        const enabled = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] }) as boolean;
+                        const tokenList = await publicClient.readContract({ address: p.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] }) as string[];
+                        tokenRestriction = { tokenRestrictionEnabled: enabled, whitelistedTokens: tokenList, whitelistedTokenCount: tokenList.length };
+                        summaryParts.push(enabled ? `Token whitelist ON (${tokenList.length} tokens)` : "Token whitelist OFF (any token allowed)");
+                    } catch { /* token restriction not available on this version */ }
+                    entry.currentConfig = { maxPerTx: maxPerTx.toString(), maxPerTxBnb: txBnb, maxPerDay: maxPerDay.toString(), maxPerDayBnb: dayBnb, maxSlippageBps: maxSlippageBps.toString(), ...tokenRestriction };
                     summaryParts.push(`Max ${txBnb} BNB/tx, ${dayBnb} BNB/day, slippage ${maxSlippageBps}bps`);
                 } catch { /* policy read failed */ }
             }
@@ -793,6 +865,42 @@ server.tool(
     }
 );
 
+// ── Tool: token_restriction ─────────────────────────────
+server.tool(
+    "token_restriction",
+    "Check token whitelist restriction status. Shows whether token trading is restricted and which tokens are whitelisted.",
+    { token_id: z.string().describe("Agent NFA Token ID") },
+    async ({ token_id }) => {
+        const { publicClient, policyClient } = createClients();
+        const tokenId = BigInt(token_id);
+        const policies = await policyClient.getPolicies(tokenId);
+        const spendingPolicy = policies.find(p => p.policyTypeName === "spending_limit");
+        if (!spendingPolicy) {
+            return { content: [{ type: "text" as const, text: JSON.stringify({ tokenId: token_id, error: "No spending_limit policy found — token restriction is not available for this agent." }) }] };
+        }
+        try {
+            const [enabled, tokenList] = await Promise.all([
+                publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "tokenRestrictionEnabled", args: [tokenId] }) as Promise<boolean>,
+                publicClient.readContract({ address: spendingPolicy.address, abi: SPENDING_LIMIT_ABI, functionName: "getTokenList", args: [tokenId] }) as Promise<string[]>,
+            ]);
+            const result = {
+                tokenId: token_id,
+                tokenRestrictionEnabled: enabled,
+                status: enabled ? "ON — only whitelisted tokens can be traded" : "OFF — any token can be traded",
+                whitelistedTokens: tokenList,
+                whitelistedTokenCount: tokenList.length,
+                manageUrl: `https://shll.run/agent/0xE98DCdbf370D7b52c9A2b88F79bEF514A5375a2b/${token_id}/console/safety`,
+                note: enabled
+                    ? "To add/remove tokens or disable restriction, visit the management URL above (requires connected wallet as renter/owner)."
+                    : "Token restriction is disabled. The agent can trade any token. To enable, visit the management URL.",
+            };
+            return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+        } catch {
+            return { content: [{ type: "text" as const, text: JSON.stringify({ tokenId: token_id, error: "Failed to read token restriction — the SpendingLimitPolicy may not support this feature." }) }] };
+        }
+    }
+);
+
 // ── Tool: status ────────────────────────────────────────
 server.tool(
     "status",