shll-skills 1.0.0

package/.env.example

@@ -0,0 +1,15 @@
+# ── Required ─────────────────────────────────────────────
+# Private key for the operator/renter wallet.
+# ⚠️  This key is used for: init (rent+fund), swap, wrap, unwrap, transfer, config.
+# ⚠️  Use a DEDICATED wallet with limited funds. Never use your main wallet.
+RUNNER_PRIVATE_KEY=0x_YOUR_PRIVATE_KEY_HERE
+
+# ── Optional Overrides ───────────────────────────────────
+# BSC RPC endpoint (default: public BSC RPC)
+# RPC_URL=https://bsc-dataseed.binance.org
+
+# AgentNFA contract address (default: mainnet deployment)
+# NFA_ADDRESS=0x...
+
+# PolicyGuardV4 contract address (default: mainnet deployment)
+# GUARD_ADDRESS=0x...

package/README.md

@@ -0,0 +1,79 @@
+# SHLL OpenClaw Skill (@shll/openclaw-skill)
+
+A native [OpenClaw](https://openclaw.ai) skill for the SHLL Agent Protocol. Execute DeFi transactions on BSC securely — every action goes through PolicyGuard.
+
+## 📦 Installation
+
+```bash
+cd repos/shll-openclaw-skill
+npm install && npm run build
+npm link                          # registers `shll-onchain-runner` CLI
+cp .env.example .env              # edit with your private key
+export RUNNER_PRIVATE_KEY="0x..."  # operator key
+```
+
+## 🚀 Quick Start
+
+```bash
+# 1. One-click onboarding: rent + authorize + fund
+shll-onchain-runner init --listing-id 0xABC...DEF --days 30 --fund 0.5
+# → Agent #5 is ready!
+
+# 2. Start trading
+shll-onchain-runner swap --from BNB --to USDC --amount 0.1 --token-id 5
+```
+
+## 📋 Full Command Reference
+
+### Onboarding
+| Command | Description |
+|---------|-------------|
+| `init --listing-id <ID> --days <N> [--fund <BNB>]` | Rent agent + authorize + fund vault |
+
+### Trading & Asset Management
+| Command | Description |
+|---------|-------------|
+| `swap --from <TOKEN> --to <TOKEN> --amount <N> -k <ID>` | Token swap via PancakeSwap V2 |
+| `wrap --amount <BNB> -k <ID>` | BNB → WBNB |
+| `unwrap --amount <BNB> -k <ID>` | WBNB → BNB |
+| `transfer --token <SYM> --amount <N> --to <ADDR> -k <ID>` | Transfer from vault |
+| `raw --target <ADDR> --data <HEX> -k <ID>` | Raw calldata execution |
+
+### Market Data (read-only, no key needed)
+| Command | Description |
+|---------|-------------|
+| `portfolio -k <ID>` | Vault holdings + USD values |
+| `price --token <SYM>` | Real-time price from DexScreener |
+| `search --query <TEXT>` | Find token by name on BSC |
+| `tokens` | List known token addresses |
+
+### Risk Management
+| Command | Description |
+|---------|-------------|
+| `policies -k <ID>` | View active policies & current settings |
+| `config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>` | Tighten risk parameters |
+
+## 🔧 What Happens Internally
+
+1. **Resolves tokens** — `BNB` → `0x0000...`, `USDC` → `0x8AC7...`
+2. **Builds path** — Auto-bridges through WBNB if needed
+3. **Gets quote** — On-chain `getAmountsOut()` for real-time pricing
+4. **Auto-approve** — Checks allowance, adds approve to batch if needed
+5. **Validates** — `PolicyClient.validate()` simulates against all policies
+6. **Executes** — Sends through `AgentNFA.execute()` → PolicyGuard → vault
+
+## 🛡️ Security
+
+- **PolicyGuard enforced** — Every transaction goes through on-chain policy validation (spending limits, cooldown, DEX whitelist, receiver guard)
+- **Vault isolation** — The operator key cannot directly access vault funds; all operations route through AgentNFA
+- **Renter-only config** — Risk parameters can only be tightened, never loosened beyond template ceiling
+- **⚠️ Use a dedicated wallet** for `RUNNER_PRIVATE_KEY` — this key pays gas for `init` and `config` transactions
+
+## 📄 Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `RUNNER_PRIVATE_KEY` | ✅ | Operator/renter private key |
+| `RPC_URL` | ❌ | BSC RPC (default: public endpoint) |
+| `NFA_ADDRESS` | ❌ | AgentNFA contract override |
+| `GUARD_ADDRESS` | ❌ | PolicyGuard contract override |

package/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: shll-onchain-runner
+description: Execute DeFi transactions on BSC via a SHLL AgentNFA. 12 commands covering onboarding (init), trading (swap, wrap, unwrap, transfer), market data (portfolio, price, search, tokens), risk management (policies, config), and raw execution. All write operations validated by on-chain PolicyGuard.
+version: 3.0.0
+author: SHLL Team
+repository: https://github.com/kledx/shll-skills.git
+install: |
+  git clone https://github.com/kledx/shll-skills.git /tmp/shll-skills
+  cd /tmp/shll-skills && npm install && npm run build && npm link
+requires:
+  - RUNNER_PRIVATE_KEY: Operator private key (required for write commands)
+---
+
+# SHLL On-Chain Runner
+
+A skill that allows OpenClaw to safely interact with DeFi protocols on BSC Mainnet using a SHLL Agent NFA.
+
+## 🎯 Purpose
+Use this skill when the user asks you to:
+- "Swap 0.5 BNB for USDC"
+- "Buy some CAKE using my SHLL agent"
+- "Swap 50 USDT for WBNB"
+
+## 🛠 Commands
+
+### Token Swap (recommended)
+```bash
+shll-onchain-runner swap --from <TOKEN> --to <TOKEN> --amount <AMOUNT> --token-id <NFA_ID>
+```
+
+**Parameters:**
+- `--from` / `-f`: Input token. Use a symbol (BNB, USDC, USDT, WBNB, CAKE, ETH, BTCB, DAI, BUSD) or a 0x address.
+- `--to` / `-t`: Output token (same format).
+- `--amount` / `-a`: Amount in human-readable format (e.g. `0.5`, `100`).
+- `--token-id` / `-k`: The user's Agent NFA Token ID.
+- `--slippage` / `-s`: Optional slippage % (default: 5).
+
+**Example:**
+```bash
+shll-onchain-runner swap --from BNB --to USDC --amount 0.1 --token-id 1
+shll-onchain-runner swap --from USDT --to CAKE --amount 50 --token-id 1
+```
+
+The script handles everything internally:
+1. Resolves token symbols to BSC addresses.
+2. Builds the optimal routing path (auto-bridges through WBNB).
+3. Queries PancakeSwap for a real-time price quote.
+4. Checks ERC20 allowance and auto-approves if needed (via atomic batch).
+5. Validates against PolicyGuard.
+6. Executes on-chain.
+
+### List Known Tokens
+```bash
+shll-onchain-runner tokens
+```
+
+### Wrap BNB → WBNB
+```bash
+shll-onchain-runner wrap --token-id <NFA_ID> --amount 0.5
+```
+
+### Unwrap WBNB → BNB
+```bash
+shll-onchain-runner unwrap --token-id <NFA_ID> --amount 0.5
+```
+
+### Transfer Tokens from Vault
+```bash
+shll-onchain-runner transfer --token-id <NFA_ID> --token USDC --amount 10 --to 0xRecipient
+```
+Note: ReceiverGuardPolicy may restrict which addresses can receive transfers.
+
+### Raw Transaction (advanced)
+```bash
+shll-onchain-runner raw --target <ADDRESS> --data <CALLDATA> --token-id <NFA_ID>
+```
+
+### One-Click Setup (first-time users)
+```bash
+shll-onchain-runner init --listing-id <LISTING_BYTES32> --days 30 --fund 0.5
+```
+This will:
+1. Rent an Agent from the template listing (pays rent in BNB)
+2. Authorize your key as the operator
+3. Fund the vault with BNB
+
+After init completes, it outputs the Token ID you need for `swap` commands.
+
+### Query Portfolio
+```bash
+shll-onchain-runner portfolio --token-id <NFA_ID>
+```
+Returns vault BNB balance + all ERC20 holdings with USD values.
+
+### Check Token Price
+```bash
+shll-onchain-runner price --token CAKE
+shll-onchain-runner price --token 0x0E09FaBB73Bd3Ade0a17ECC321fD13a19e81cE82
+```
+Returns real-time price, 24h volume, liquidity, and price change from DexScreener.
+
+### Search for a Token
+```bash
+shll-onchain-runner search --query "pancake"
+```
+Finds BSC tokens by name or symbol. Returns addresses and market data.
+
+### View Active Policies
+```bash
+shll-onchain-runner policies --token-id <NFA_ID>
+```
+Returns all active policies, whether they're configurable, and current settings (limits, cooldown).
+
+### Configure Risk Parameters
+```bash
+shll-onchain-runner config --token-id <NFA_ID> --tx-limit 0.5 --daily-limit 2 --cooldown 120
+```
+Adjusts SpendingLimitPolicy and CooldownPolicy. You can only tighten limits (not exceed template ceiling).
+
+## 🔐 Security
+The SHLL PolicyGuard smart contract will automatically reject any transaction that violates the agent's policies (spending limits, cooldown, blacklisted targets, etc.). You do NOT need to verify safety — just construct the intent and the on-chain guard handles the rest.
+
+## 📤 Output Format
+All output is JSON on stdout:
+- Success: `{ "status": "success", "hash": "0x..." }`
+- Rejected by policy: `{ "status": "rejected", "reason": "Exceeds per-tx limit" }`
+- Error: `{ "status": "error", "message": "..." }`
+- Quote info: `{ "status": "info", "message": "Quote: ..." }`

package/dist/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node