shll-skills 3.0.0 → 4.0.0

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: 4.1.0
+version: 5.0.0
 author: SHLL Team
 website: https://shll.run
 twitter: https://twitter.com/shllrun
@@ -144,6 +144,9 @@ Examples:
 - "Swap 0.1 BNB for USDC"
 - "What's my portfolio?"
 - "What's the price of CAKE?"
+- "Lend 10 USDT on Venus"
+- "How much am I earning on Venus?"
+- "Redeem my USDT from Venus"
 
 ---
 
@@ -161,12 +164,22 @@ Examples:
 ### Trading
 | Command | What it does |
 |---------|-------------|
-| `shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>` | Token swap on PancakeSwap |
+| `shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>` | Token swap (auto-routes PancakeSwap V2/V3) |
+| `shll-run swap ... --dex v3 --fee 500` | Force V3 with 0.05% fee tier |
 | `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>` | Send tokens from vault |
 | `shll-run raw --target <ADDR> --data <HEX> -k <ID>` | Raw calldata |
 
+### Lending (Venus Protocol)
+| Command | What it does |
+|---------|-------------|
+| `shll-run lend -t <TOKEN> -a <AMT> -k <ID>` | Supply tokens to Venus to earn yield |
+| `shll-run redeem -t <TOKEN> -a <AMT> -k <ID>` | Withdraw supplied tokens from Venus |
+| `shll-run lending-info -k <ID>` | Show supply balances + APY across Venus markets |
+
+Supported lending tokens: **BNB, USDT, USDC, BUSD**
+
 ### Market Data (read-only)
 | Command | What it does |
 |---------|-------------|
@@ -185,6 +198,9 @@ Examples:
 
 **Supported tokens:** BNB, USDC, USDT, WBNB, CAKE, ETH, BTCB, DAI, BUSD, or any 0x address.
 
+**Swap routing modes:** `--dex auto` (default: compares V2/V3 quotes), `--dex v2`, `--dex v3`.
+**V3 fee tiers:** `--fee 100` (0.01%), `--fee 500` (0.05%), `--fee 2500` (0.25%, default), `--fee 10000` (1%).
+
 ---
 
 ## HOW TO EXPLAIN THINGS TO USERS
@@ -201,7 +217,11 @@ Examples:
 ### "What are policies?"
 *"Policies are on-chain safety rules: how much you can spend per transaction, how often you can trade, which DEXs are allowed, etc. You can tighten these rules but never loosen them beyond the template ceiling."*
 
----
+### "What is Venus Protocol?"
+*"Venus is a decentralized lending protocol on BSC. When you 'lend' tokens to Venus, you deposit them into a supply pool and earn interest (APY). Other users borrow from the same pool and pay interest. You can withdraw (redeem) your tokens plus earned interest at any time. Your tokens stay on-chain in Venus smart contracts — SHLL does not hold them."*
+
+### "Is lending safe?"
+*"Venus is one of the most established protocols on BSC with over $1B TVL. However, DeFi lending always carries smart contract risk and market risk. Only lend amounts you're comfortable with. Your agent's DeFiGuard policy ensures only approved lending operations can be executed."*
 
 ## OUTPUT FORMAT
 All commands output JSON:

package/dist/chunk-EUGNHCIP.mjs

@@ -0,0 +1,502 @@
+// node_modules/shll-policy-sdk/dist/index.js
+import {
+  createPublicClient,
+  createWalletClient,
+  http
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { bsc, bscTestnet } from "viem/chains";
+var PolicyGuardV4Abi = [
+  {
+    name: "validate",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "nfa", type: "address" },
+      { name: "tokenId", type: "uint256" },
+      { name: "agentAccount", type: "address" },
+      { name: "caller", type: "address" },
+      {
+        name: "action",
+        type: "tuple",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [
+      { name: "ok", type: "bool" },
+      { name: "reason", type: "string" }
+    ]
+  },
+  {
+    name: "getActivePolicies",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "instanceId", type: "uint256" }],
+    outputs: [{ name: "", type: "address[]" }]
+  },
+  {
+    name: "getTemplatePolicies",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "templateId", type: "bytes32" }],
+    outputs: [{ name: "", type: "address[]" }]
+  },
+  {
+    name: "instanceTemplateId",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "instanceId", type: "uint256" }],
+    outputs: [{ name: "", type: "bytes32" }]
+  }
+];
+var AgentNFAAbi = [
+  {
+    name: "execute",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      { name: "tokenId", type: "uint256" },
+      {
+        name: "action",
+        type: "tuple",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [{ name: "result", type: "bytes" }]
+  },
+  {
+    name: "executeBatch",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      { name: "tokenId", type: "uint256" },
+      {
+        name: "actions",
+        type: "tuple[]",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [{ name: "results", type: "bytes[]" }]
+  },
+  {
+    name: "accountOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "userOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "userExpires",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "operatorOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "operatorExpiresOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "operatorNonceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "setOperatorWithSig",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "req",
+        type: "tuple",
+        components: [
+          { name: "tokenId", type: "uint256" },
+          { name: "renter", type: "address" },
+          { name: "operator", type: "address" },
+          { name: "expires", type: "uint64" },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" }
+        ]
+      },
+      { name: "signature", type: "bytes" }
+    ],
+    outputs: []
+  },
+  {
+    name: "clearOperator",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: []
+  }
+];
+var IPolicyAbi = [
+  {
+    name: "policyType",
+    type: "function",
+    stateMutability: "pure",
+    inputs: [],
+    outputs: [{ name: "", type: "bytes32" }]
+  },
+  {
+    name: "renterConfigurable",
+    type: "function",
+    stateMutability: "pure",
+    inputs: [],
+    outputs: [{ name: "", type: "bool" }]
+  },
+  {
+    name: "check",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "instanceId", type: "uint256" },
+      { name: "caller", type: "address" },
+      { name: "target", type: "address" },
+      { name: "selector", type: "bytes4" },
+      { name: "callData", type: "bytes" },
+      { name: "value", type: "uint256" }
+    ],
+    outputs: [
+      { name: "ok", type: "bool" },
+      { name: "reason", type: "string" }
+    ]
+  }
+];
+var POLICY_TYPE_NAMES = {
+  // keccak256(abi.encodePacked("spending_limit"))
+  "0xfc881f20d88f7ec7e942f0b796f40ce121974015a83f091cd5ef2cf146443d4e": "spending_limit",
+  // keccak256(abi.encodePacked("cooldown"))
+  "0x7230b2ae91f8efdf9ea182e9a9d1fef92adfda3e61d5512778c2f81580b13d10": "cooldown",
+  // keccak256(abi.encodePacked("receiver_guard"))
+  "0xccead04e892f4bd05d3e2491948809479bf4641d233bf37f3fac8411960a97de": "receiver_guard",
+  // keccak256(abi.encodePacked("dex_whitelist"))
+  "0xb5ba0ef255153fe2c4c7201fbd5f2658f86e25a723f1844d5bf64a5c48e0c9ed": "dex_whitelist",
+  // keccak256(abi.encodePacked("defi_guard"))
+  "0xe109b0d2bf06e570d9aecb2cd18dafe849a5c1d8b9b9f6ecd8b9ed727f816bb9": "defi_guard",
+  // keccak256(abi.encodePacked("token_whitelist"))
+  "0xf4717a1c69e76a67584dd6d514cc591ec961b52113ec085dfe157bd9e238e1f3": "token_whitelist"
+};
+var PolicyClient = class {
+  publicClient;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _walletClient;
+  _operatorAddress;
+  agentNfaAddress;
+  policyGuardAddress;
+  constructor(config) {
+    const chain = config.chainId === 97 ? bscTestnet : bsc;
+    this.publicClient = createPublicClient({
+      chain,
+      transport: http(config.rpcUrl)
+    });
+    this.agentNfaAddress = config.agentNfaAddress;
+    this.policyGuardAddress = config.policyGuardAddress;
+    if (config.operatorPrivateKey) {
+      const account = privateKeyToAccount(config.operatorPrivateKey);
+      this._operatorAddress = account.address;
+      this._walletClient = createWalletClient({
+        account,
+        chain,
+        transport: http(config.rpcUrl)
+      });
+    } else {
+      this._operatorAddress = null;
+      this._walletClient = null;
+    }
+  }
+  // ═══════════════════════════════════════════════════════
+  //                     VALIDATION
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Validate an action against all active on-chain policies.
+   * This is an off-chain simulation — saves gas by catching rejections before submission.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param action - The action to validate
+   * @param callerOverride - Optional caller address override (defaults to operator)
+   */
+  async validate(tokenId, action, callerOverride) {
+    const caller = callerOverride ?? this._operatorAddress;
+    if (!caller) {
+      return { ok: false, reason: "No caller address \u2014 provide operatorPrivateKey or callerOverride" };
+    }
+    const vault = await this.getVault(tokenId);
+    try {
+      const [ok, reason] = await this.publicClient.readContract({
+        address: this.policyGuardAddress,
+        abi: PolicyGuardV4Abi,
+        functionName: "validate",
+        args: [
+          this.agentNfaAddress,
+          tokenId,
+          vault,
+          caller,
+          { target: action.target, value: action.value, data: action.data }
+        ]
+      });
+      return { ok, reason: reason || void 0 };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Simulation reverted";
+      return { ok: false, reason: `Simulation reverted: ${message.slice(0, 300)}` };
+    }
+  }
+  // ═══════════════════════════════════════════════════════
+  //                     EXECUTION
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Execute a single action through AgentNFA.
+   * Simulates first, then submits if validation passes.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param action - The action to execute
+   * @param skipValidation - Skip pre-flight validation (default: false)
+   */
+  async execute(tokenId, action, skipValidation = false) {
+    this.requireWallet();
+    if (!skipValidation) {
+      const sim = await this.validate(tokenId, action);
+      if (!sim.ok) {
+        throw new Error(`Policy rejected: ${sim.reason}`);
+      }
+    }
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "execute",
+      args: [tokenId, { target: action.target, value: action.value, data: action.data }]
+    });
+    return { hash };
+  }
+  /**
+   * Execute multiple actions atomically via AgentNFA.executeBatch().
+   * Useful for approve+swap in a single transaction.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param actions - Array of actions to execute
+   * @param skipValidation - Skip per-action pre-flight validation (default: false)
+   */
+  async executeBatch(tokenId, actions, skipValidation = false) {
+    this.requireWallet();
+    if (!skipValidation) {
+      for (const action of actions) {
+        const sim = await this.validate(tokenId, action);
+        if (!sim.ok) {
+          throw new Error(`Policy rejected action (target=${action.target}): ${sim.reason}`);
+        }
+      }
+    }
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "executeBatch",
+      args: [
+        tokenId,
+        actions.map((a) => ({ target: a.target, value: a.value, data: a.data }))
+      ]
+    });
+    return { hash };
+  }
+  // ═══════════════════════════════════════════════════════
+  //                    POLICY QUERIES
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Get all active policies for an agent instance, with type info.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @returns Array of PolicyInfo objects
+   */
+  async getPolicies(tokenId) {
+    const addresses = await this.publicClient.readContract({
+      address: this.policyGuardAddress,
+      abi: PolicyGuardV4Abi,
+      functionName: "getActivePolicies",
+      args: [tokenId]
+    });
+    const results = [];
+    for (const addr of addresses) {
+      try {
+        const [policyType, renterConfigurable] = await Promise.all([
+          this.publicClient.readContract({
+            address: addr,
+            abi: IPolicyAbi,
+            functionName: "policyType"
+          }),
+          this.publicClient.readContract({
+            address: addr,
+            abi: IPolicyAbi,
+            functionName: "renterConfigurable"
+          })
+        ]);
+        const typeName = POLICY_TYPE_NAMES[policyType] ?? "unknown";
+        results.push({
+          address: addr,
+          policyType,
+          policyTypeName: typeName,
+          renterConfigurable
+        });
+      } catch {
+        results.push({
+          address: addr,
+          policyType: "0x",
+          policyTypeName: "unknown",
+          renterConfigurable: false
+        });
+      }
+    }
+    return results;
+  }
+  // ═══════════════════════════════════════════════════════
+  //                  OPERATOR PERMIT
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Read the current operator state for a token — useful for constructing permits.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @returns Current operator, renter, vault, and nonce info
+   */
+  async getOperatorState(tokenId) {
+    const [operator, operatorExpires, renter, renterExpires, vault, operatorNonce] = await Promise.all([
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorExpiresOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "userOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "userExpires",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "accountOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorNonceOf",
+        args: [tokenId]
+      })
+    ]);
+    return { operator, operatorExpires, renter, renterExpires, vault, operatorNonce };
+  }
+  /**
+   * Submit a signed OperatorPermit on-chain to authorize this runner as operator.
+   *
+   * @param permit - The OperatorPermit struct
+   * @param signature - EIP-712 signature from the renter
+   */
+  async setOperatorWithPermit(permit, signature) {
+    this.requireWallet();
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "setOperatorWithSig",
+      args: [
+        {
+          tokenId: permit.tokenId,
+          renter: permit.renter,
+          operator: permit.operator,
+          expires: permit.expires,
+          nonce: permit.nonce,
+          deadline: permit.deadline
+        },
+        signature
+      ]
+    });
+    return { hash };
+  }
+  /**
+   * Clear the operator permit for a token.
+   *
+   * @param tokenId - Agent NFA token ID
+   */
+  async clearOperator(tokenId) {
+    this.requireWallet();
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "clearOperator",
+      args: [tokenId]
+    });
+    return { hash };
+  }
+  // ═══════════════════════════════════════════════════════
+  //                      HELPERS
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Get the vault (AgentAccount) address for a token.
+   */
+  async getVault(tokenId) {
+    return await this.publicClient.readContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "accountOf",
+      args: [tokenId]
+    });
+  }
+  /**
+   * Get the operator address configured for this client.
+   */
+  getOperatorAddress() {
+    return this._operatorAddress;
+  }
+  requireWallet() {
+    if (!this._walletClient) {
+      throw new Error(
+        "PolicyClient: operatorPrivateKey is required for write operations (execute, setOperator)"
+      );
+    }
+  }
+};
+
+export {
+  PolicyClient
+};