shll-skills 5.4.2 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/SKILL.md +250 -296
- package/dist/index.js +821 -199
- package/dist/index.mjs +823 -201
- package/dist/mcp.js +576 -36
- package/dist/mcp.mjs +577 -36
- package/package.json +1 -1
- package/src/index.ts +1080 -387
- package/src/mcp.ts +732 -125
package/SKILL.md
CHANGED
|
@@ -1,296 +1,250 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: shll-run
|
|
3
|
-
description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands
|
|
4
|
-
version: 5.
|
|
5
|
-
author: SHLL Team
|
|
6
|
-
website: https://shll.run
|
|
7
|
-
twitter: https://twitter.com/shllrun
|
|
8
|
-
repository: https://github.com/kledx/shll-skills.git
|
|
9
|
-
install: npm install -g shll-skills --registry https://registry.npmjs.org
|
|
10
|
-
update: npm update -g shll-skills --registry https://registry.npmjs.org
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# SHLL
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
shll-run balance
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
shll-run
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
-
|
|
148
|
-
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
-
|
|
235
|
-
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
**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.
|
|
253
|
-
|
|
254
|
-
**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.
|
|
255
|
-
|
|
256
|
-
### Cross-Skill Execution Pattern
|
|
257
|
-
|
|
258
|
-
If another skill provides **calldata** (e.g. OKX DEX API returns a swap route), you can execute it through SHLL's safety layer:
|
|
259
|
-
|
|
260
|
-
1. **Get calldata from other skill** → e.g., OKX returns `{to: "0xDEX...", data: "0xABC...", value: "100000..."}`
|
|
261
|
-
2. **Execute via SHLL** → use `execute_calldata` tool with the target, data, and value
|
|
262
|
-
3. **PolicyGuard validates** → spending limits, cooldowns, whitelists enforced
|
|
263
|
-
4. **Vault executes** → transaction runs from the agent vault
|
|
264
|
-
|
|
265
|
-
Example flow:
|
|
266
|
-
```
|
|
267
|
-
User: "Use OKX to find the best swap route for 0.5 BNB to USDT, then execute it"
|
|
268
|
-
|
|
269
|
-
Step 1: Call OKX DEX API skill → get calldata
|
|
270
|
-
Step 2: Call SHLL execute_calldata(token_id, target, data, value) → PolicyGuard validated execution
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
**This pattern gives you the best of both worlds:** superior routing from specialized DEX aggregators + SHLL's on-chain policy enforcement.
|
|
274
|
-
|
|
275
|
-
For multi-step transactions (e.g. approve + swap), use `execute_calldata_batch` to execute atomically.
|
|
276
|
-
|
|
277
|
-
⚠️ **CRITICAL SECURITY: Verify Recipient Address**
|
|
278
|
-
|
|
279
|
-
Before executing calldata from an external source, you **MUST verify** that any `recipient`, `to`, or `receiver` address embedded in the calldata matches the agent's vault address. Use the `portfolio` tool to get the vault address first.
|
|
280
|
-
|
|
281
|
-
**Why:** A compromised or malicious API could return valid-looking swap calldata but with the recipient set to an attacker's address. PolicyGuard validates the target contract and spending limits, but does NOT parse internal calldata fields like `recipient`.
|
|
282
|
-
|
|
283
|
-
```
|
|
284
|
-
Step 0: portfolio(token_id) → get vault address
|
|
285
|
-
Step 1: Get calldata from OKX/Bitget/1inch
|
|
286
|
-
Step 2: Verify that 'recipient' in calldata == vault address
|
|
287
|
-
Step 3: execute_calldata(token_id, target, data, value)
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
---
|
|
291
|
-
|
|
292
|
-
## LINKS
|
|
293
|
-
- Website: https://shll.run
|
|
294
|
-
- Twitter: @shllrun
|
|
295
|
-
- npm: https://www.npmjs.com/package/shll-skills
|
|
296
|
-
- GitHub: https://github.com/kledx/shll-skills
|
|
1
|
+
---
|
|
2
|
+
name: shll-run
|
|
3
|
+
description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands and users only need to chat.
|
|
4
|
+
version: 5.5.1
|
|
5
|
+
author: SHLL Team
|
|
6
|
+
website: https://shll.run
|
|
7
|
+
twitter: https://twitter.com/shllrun
|
|
8
|
+
repository: https://github.com/kledx/shll-skills.git
|
|
9
|
+
install: npm install -g shll-skills --registry https://registry.npmjs.org
|
|
10
|
+
update: npm update -g shll-skills --registry https://registry.npmjs.org
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# SHLL Skill Usage Guide
|
|
14
|
+
|
|
15
|
+
This file defines how an AI agent should use `shll-run` and `shll-mcp` safely.
|
|
16
|
+
|
|
17
|
+
## Scope
|
|
18
|
+
|
|
19
|
+
- Network: BSC mainnet
|
|
20
|
+
- Runtime:
|
|
21
|
+
- CLI: `shll-run` (alias: `shll-onchain-runner`)
|
|
22
|
+
- MCP: `shll-mcp`
|
|
23
|
+
- Security layer: SHLL PolicyGuard
|
|
24
|
+
|
|
25
|
+
The user should not be asked to run CLI commands directly. The AI runs commands and explains results.
|
|
26
|
+
|
|
27
|
+
## Mandatory Safety Rules
|
|
28
|
+
|
|
29
|
+
1. Token ID must come from the user. Never guess, scan, or enumerate IDs.
|
|
30
|
+
2. Use one token ID per conversation unless the user explicitly switches.
|
|
31
|
+
3. Confirm before each write operation.
|
|
32
|
+
4. Never ask for or handle the owner wallet private key.
|
|
33
|
+
5. Do not repeat private keys after initial `generate-wallet` output.
|
|
34
|
+
6. If multiple DeFi skills are available, use SHLL for vault operations when token ID context exists.
|
|
35
|
+
7. Treat raw calldata as high risk. Use strict recipient checks.
|
|
36
|
+
8. Do not bypass security controls for convenience.
|
|
37
|
+
|
|
38
|
+
## Security Model
|
|
39
|
+
|
|
40
|
+
SHLL uses dual wallets:
|
|
41
|
+
|
|
42
|
+
- Owner wallet (user): controls high-risk operations such as ownership and vault-level admin actions.
|
|
43
|
+
- Operator wallet (`RUNNER_PRIVATE_KEY`): used by AI to execute allowed trades only.
|
|
44
|
+
|
|
45
|
+
On-chain guardrails:
|
|
46
|
+
|
|
47
|
+
- PolicyGuard validates each action (`validate`) before execution (`execute` / `executeBatch`).
|
|
48
|
+
- Spending limits, cooldowns, whitelist rules, and protocol rules are enforced on-chain.
|
|
49
|
+
- Raw calldata path is guarded by recipient safety checks before on-chain execution.
|
|
50
|
+
|
|
51
|
+
## Current Critical Constraints (v5.5.1)
|
|
52
|
+
|
|
53
|
+
1. `init` command is disabled. Do not use it.
|
|
54
|
+
2. CLI `raw` requires `--i-understand-the-risk`.
|
|
55
|
+
3. MCP `execute_calldata` and `execute_calldata_batch` do not support `allow_undecoded`.
|
|
56
|
+
4. If calldata recipient cannot be decoded, execution is blocked.
|
|
57
|
+
5. Core contract addresses are pinned in code, not user-overridable at runtime.
|
|
58
|
+
|
|
59
|
+
## Prerequisites
|
|
60
|
+
|
|
61
|
+
1. Install:
|
|
62
|
+
```bash
|
|
63
|
+
npm install -g shll-skills --registry https://registry.npmjs.org
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
2. Set operator private key:
|
|
67
|
+
```bash
|
|
68
|
+
export RUNNER_PRIVATE_KEY="0x..."
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
3. Optional custom RPC:
|
|
72
|
+
```bash
|
|
73
|
+
export SHLL_RPC="https://bsc-dataseed1.binance.org"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
4. Ensure operator wallet has small BNB balance for gas.
|
|
77
|
+
|
|
78
|
+
## Onboarding Flow (AI-driven)
|
|
79
|
+
|
|
80
|
+
1. Check or create operator wallet:
|
|
81
|
+
- Use `shll-run generate-wallet` only if user has no operator wallet.
|
|
82
|
+
- Immediately instruct user to store the key securely.
|
|
83
|
+
|
|
84
|
+
2. Verify gas:
|
|
85
|
+
- Run `shll-run balance`.
|
|
86
|
+
|
|
87
|
+
3. If user has no token ID:
|
|
88
|
+
- Run `shll-run listings`.
|
|
89
|
+
- Ask user to choose template and rental days.
|
|
90
|
+
- Run `shll-run setup-guide --listing-id <id> --days <days>`.
|
|
91
|
+
- Send `setupUrl` to user for browser completion.
|
|
92
|
+
|
|
93
|
+
4. User returns with token ID:
|
|
94
|
+
- Run `shll-run portfolio -k <tokenId>`.
|
|
95
|
+
- Confirm readiness and proceed with requested operation.
|
|
96
|
+
|
|
97
|
+
## Write Confirmation Policy
|
|
98
|
+
|
|
99
|
+
Before any write command, present:
|
|
100
|
+
|
|
101
|
+
- token ID
|
|
102
|
+
- action type
|
|
103
|
+
- token/amount/target
|
|
104
|
+
- risk note
|
|
105
|
+
|
|
106
|
+
Then wait for explicit user approval.
|
|
107
|
+
|
|
108
|
+
Write commands include:
|
|
109
|
+
|
|
110
|
+
- `swap`
|
|
111
|
+
- `wrap`
|
|
112
|
+
- `unwrap`
|
|
113
|
+
- `transfer`
|
|
114
|
+
- `raw`
|
|
115
|
+
- `lend`
|
|
116
|
+
- `redeem`
|
|
117
|
+
- `config`
|
|
118
|
+
- `four-buy`
|
|
119
|
+
- `four-sell`
|
|
120
|
+
|
|
121
|
+
Read-only commands do not require confirmation.
|
|
122
|
+
|
|
123
|
+
## CLI Commands
|
|
124
|
+
|
|
125
|
+
### Setup and account
|
|
126
|
+
|
|
127
|
+
- `shll-run generate-wallet`
|
|
128
|
+
- `shll-run balance`
|
|
129
|
+
- `shll-run doctor`
|
|
130
|
+
- `shll-run listings`
|
|
131
|
+
- `shll-run setup-guide [-l <listingId>] [-d <days>]`
|
|
132
|
+
- `shll-run init` (disabled)
|
|
133
|
+
|
|
134
|
+
If `-l/--listing-id` is omitted, `setup-guide` auto-selects an active listing from indexer.
|
|
135
|
+
|
|
136
|
+
### Trading and vault ops
|
|
137
|
+
|
|
138
|
+
- `shll-run swap -f <from> -t <to> -a <amount> -k <tokenId>`
|
|
139
|
+
- `shll-run wrap -a <bnb> -k <tokenId>`
|
|
140
|
+
- `shll-run unwrap -a <bnb> -k <tokenId>`
|
|
141
|
+
- `shll-run transfer --token <symbolOrAddress> -a <amount> --to <address> -k <tokenId>`
|
|
142
|
+
- `shll-run raw --target <address> --data <hex> -k <tokenId> --i-understand-the-risk`
|
|
143
|
+
|
|
144
|
+
### Lending (Venus)
|
|
145
|
+
|
|
146
|
+
- `shll-run lend -t <token> -a <amount> -k <tokenId>`
|
|
147
|
+
- `shll-run redeem -t <token> -a <amount> -k <tokenId>`
|
|
148
|
+
- `shll-run lending-info -k <tokenId>`
|
|
149
|
+
|
|
150
|
+
### Four.meme
|
|
151
|
+
|
|
152
|
+
- `shll-run four-info --token <address>`
|
|
153
|
+
- `shll-run four-buy --token <address> -a <bnb> -k <tokenId>`
|
|
154
|
+
- `shll-run four-sell --token <address> -a <tokenAmount> -k <tokenId>`
|
|
155
|
+
|
|
156
|
+
### Read-only and audit
|
|
157
|
+
|
|
158
|
+
- `shll-run portfolio -k <tokenId>`
|
|
159
|
+
- `shll-run price --token <symbolOrAddress>`
|
|
160
|
+
- `shll-run search --query <text>`
|
|
161
|
+
- `shll-run tokens`
|
|
162
|
+
- `shll-run policies -k <tokenId>`
|
|
163
|
+
- `shll-run status -k <tokenId>`
|
|
164
|
+
- `shll-run history -k <tokenId> [--limit N]`
|
|
165
|
+
- `shll-run my-agents`
|
|
166
|
+
|
|
167
|
+
## MCP Tools: Cross-skill Execution
|
|
168
|
+
|
|
169
|
+
For external aggregator calldata (OKX, 1inch, etc.):
|
|
170
|
+
|
|
171
|
+
1. Get quote/calldata from external source.
|
|
172
|
+
2. Execute through SHLL MCP:
|
|
173
|
+
- `execute_calldata`
|
|
174
|
+
- `execute_calldata_batch`
|
|
175
|
+
3. Let PolicyGuard enforce on-chain policy checks.
|
|
176
|
+
|
|
177
|
+
For onboarding via MCP, `setup_guide` can auto-select an active listing when `listing_id` is omitted.
|
|
178
|
+
|
|
179
|
+
Security requirements:
|
|
180
|
+
|
|
181
|
+
1. Recipient must resolve to the vault address.
|
|
182
|
+
2. Undecodable recipient calldata is blocked.
|
|
183
|
+
3. Do not ask for "unsafe bypass" parameters.
|
|
184
|
+
|
|
185
|
+
## Smart Routing Rule
|
|
186
|
+
|
|
187
|
+
When user provides a token address:
|
|
188
|
+
|
|
189
|
+
1. Run `four-info --token <addr>`.
|
|
190
|
+
2. If `tradingPhase` is bonding curve, use `four-buy` / `four-sell`.
|
|
191
|
+
3. If `tradingPhase` is DEX (or unsupported), use `swap`.
|
|
192
|
+
|
|
193
|
+
## Common Errors and Fixes
|
|
194
|
+
|
|
195
|
+
1. `RUNNER_PRIVATE_KEY environment variable is missing`
|
|
196
|
+
- Set `RUNNER_PRIVATE_KEY` and retry.
|
|
197
|
+
- Or run `shll-run doctor` to get guided next steps.
|
|
198
|
+
|
|
199
|
+
2. `NOT authorized for token-id`
|
|
200
|
+
- Operator wallet is not authorized; use setup guide or set operator in console.
|
|
201
|
+
|
|
202
|
+
3. `rental has EXPIRED` or `operator authorization has EXPIRED`
|
|
203
|
+
- Renew subscription/authorization first.
|
|
204
|
+
|
|
205
|
+
4. `status: rejected`
|
|
206
|
+
- PolicyGuard rejected action; inspect `reason` and adjust limits/whitelists/cooldown.
|
|
207
|
+
|
|
208
|
+
5. `Unable to decode recipient from calldata`
|
|
209
|
+
- Use built-in command flow or provide calldata with decodable vault recipient.
|
|
210
|
+
|
|
211
|
+
6. `init command is disabled`
|
|
212
|
+
- Use `setup-guide` flow instead.
|
|
213
|
+
|
|
214
|
+
7. Unsure what is broken
|
|
215
|
+
- Run `shll-run doctor` for one-shot environment, wallet, RPC, and optional token-id checks.
|
|
216
|
+
|
|
217
|
+
## Redeploy Checklist (When Contracts Change)
|
|
218
|
+
|
|
219
|
+
If AgentNFA / PolicyGuard / ListingManagerV2 / default listing changes:
|
|
220
|
+
|
|
221
|
+
1. Update constants in:
|
|
222
|
+
- `src/index.ts`
|
|
223
|
+
- `src/mcp.ts`
|
|
224
|
+
|
|
225
|
+
2. Validate ABIs if function signatures changed.
|
|
226
|
+
|
|
227
|
+
3. Rebuild:
|
|
228
|
+
```bash
|
|
229
|
+
npx tsc --noEmit
|
|
230
|
+
npm run build
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
4. Smoke test:
|
|
234
|
+
- `shll-run init` returns disabled error
|
|
235
|
+
- `shll-run raw` blocks without risk flag
|
|
236
|
+
- basic read commands still work
|
|
237
|
+
|
|
238
|
+
## Expected Output Format
|
|
239
|
+
|
|
240
|
+
All runtime responses should stay machine-friendly JSON:
|
|
241
|
+
|
|
242
|
+
- Success: `{"status":"success", ...}`
|
|
243
|
+
- Rejected: `{"status":"rejected","reason":"..."}`
|
|
244
|
+
- Error: `{"status":"error","message":"..."}`
|
|
245
|
+
|
|
246
|
+
## Links
|
|
247
|
+
|
|
248
|
+
- Website: https://shll.run
|
|
249
|
+
- npm: https://www.npmjs.com/package/shll-skills
|
|
250
|
+
- Repo: https://github.com/kledx/shll-skills
|