stacksagent 1.4.0 → 1.5.0

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.
Files changed (5) hide show
  1. package/README.md +193 -101
  2. package/dist/assets/.shared/stacks-agent/data/oracles.csv +31 -0
  3. package/dist/assets/.shared/stacks-agent/scripts/core.py +4 -2
  4. package/dist/index.js +0 -0
  5. package/package.json +3 -2
package/README.md CHANGED
@@ -1,179 +1,271 @@
1
- # stacksagent
1
+ <!--
2
+ This README is the single source of truth.
3
+ It's automatically copied to cli/README.md during `npm run build`
4
+ -->
2
5
 
3
- > AI Skill CLI installer for building Stacks blockchain applications
6
+ # Stacks Agent
4
7
 
5
- [![npm version](https://img.shields.io/npm/v/stacksagent.svg)](https://www.npmjs.com/package/stacksagent)
6
- [![npm downloads](https://img.shields.io/npm/dm/stacksagent.svg)](https://www.npmjs.com/package/stacksagent)
7
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+ > AI Skill for building Stacks blockchain applications - Bitcoin's most powerful smart contract layer
8
9
 
9
- Transform your AI coding assistant into a Stacks blockchain expert with 170+ searchable knowledge entries.
10
+ An intelligent AI assistant that provides development guidance for Clarity smart contracts, DeFi integration, and blockchain development on Stacks. Works with **Claude Code, Cursor, Windsurf, Antigravity, GitHub Copilot, Kiro, and Codex**.
10
11
 
11
- ## 🎯 Supported AI Platforms
12
+ ![Stacks Agent](https://img.shields.io/npm/v/stacks-agent?color=blue&label=stacks-agent)
13
+ ![License](https://img.shields.io/npm/l/stacks-agent)
14
+ ![Downloads](https://img.shields.io/npm/dm/stacks-agent)
12
15
 
13
- - **Claude Code** - Claude's official CLI
14
- - **Cursor** - AI-first code editor
15
- - **Windsurf** - AI coding assistant
16
- - **Antigravity** - AI development tool
17
- - **GitHub Copilot** - GitHub's AI assistant
18
- - **Kiro** - AI coding helper
19
- - **Codex** - OpenAI Codex integration
16
+ ## ✨ Features
17
+
18
+ **495+ Knowledge Base Entries Across 15 Domains:**
19
+
20
+ ### Core Language & Tools (175 entries)
21
+ - **🔷 61 Clarity Functions** - Complete language reference with examples
22
+ - **⚛️ 75 Stacks.js Utilities** - Wallet, transactions, CV constructors, API integration
23
+ - **📋 14 Contract Templates** - SIP-010, SIP-009, DAO, Vault, Marketplace, Stacking
24
+ - **🚀 25 Deployment Steps** - Testnet, mainnet, and devnet workflows
25
+
26
+ ### Domain-Specific Integrations (185 entries)
27
+ - **🌐 21 BNS Operations** - Name registration, resolution (Clarity + JS + API)
28
+ - **💰 25 Stacking Guides** - PoX stacking and pool delegation (Clarity + JS + API)
29
+ - **🔄 25 DeFi Protocols** - Alex, Velar, Bitflow, Zest, StackingDAO (Clarity + JS + API)
30
+ - **🎨 30 NFT Operations** - SIP-009, minting, marketplace patterns (Clarity + JS + API)
31
+ - **💎 40 Token Operations** - SIP-010 fungible tokens, DeFi integrations (Clarity + JS + API)
32
+ - **🔐 14 Authentication** - Gaia storage, wallet auth, JWT, token-gating (Clarity + JS + API)
33
+ - **📊 30 Oracle Integration** - Pyth Network price feeds, VAA handling, Hermes API (Clarity + JS + API)
34
+
35
+ ### Advanced & Specialized (135 entries)
36
+ - **🛡️ 15 Security Patterns** - Common vulnerabilities and secure implementations
37
+ - **🎯 40 Advanced Patterns** - Pagination, SWR, presales, lotteries, vesting, CSV export
38
+ - **🔗 30 Chainhooks** - Event indexing, webhooks, predicates, ordinals tracking
39
+ - **🤖 50 Trading Bots** - Automated trading, wallet SDKs, Privy, bonding curves
40
+
41
+ ## 🎯 Use Cases
42
+
43
+ - Generate Clarity smart contracts from natural language
44
+ - Audit contracts for security vulnerabilities
45
+ - Integrate with DeFi protocols (swaps, liquidity, lending)
46
+ - Integrate Pyth Network oracle for price feeds
47
+ - Deploy to testnet/mainnet
48
+ - Build dApps with Stacks.js
49
+ - Implement stacking and BNS features
20
50
 
21
51
  ## 📦 Installation
22
52
 
53
+ ### Using CLI (Recommended)
54
+
23
55
  ```bash
56
+ # Install globally
24
57
  npm install -g stacksagent
58
+
59
+ # Go to your project
60
+ cd /path/to/your/project
61
+
62
+ # Install for your AI assistant
63
+ stacksagent init --ai claude # Claude Code
64
+ stacksagent init --ai cursor # Cursor
65
+ stacksagent init --ai windsurf # Windsurf
66
+ stacksagent init --ai antigravity # Antigravity
67
+ stacksagent init --ai copilot # GitHub Copilot
68
+ stacksagent init --ai kiro # Kiro
69
+ stacksagent init --ai codex # OpenAI Codex
70
+ stacksagent init --ai all # All platforms
25
71
  ```
26
72
 
27
- ## 🚀 Usage
73
+ ### Manual Installation
28
74
 
29
- ### Install for Your AI Platform
75
+ Copy the appropriate folders to your project:
30
76
 
31
- ```bash
32
- # Claude Code
33
- stacksagent init --ai claude
77
+ | AI Assistant | Folders to Copy |
78
+ | --------------- | -------------------------------------------------------- |
79
+ | Claude Code | `.claude/skills/stacks-agent/` |
80
+ | Cursor | `.cursor/commands/stacks-agent.md` + `.shared/stacks-agent/` |
81
+ | Windsurf | `.windsurf/workflows/stacks-agent.md` + `.shared/stacks-agent/` |
82
+ | Antigravity | `.agent/workflows/stacks-agent.md` + `.shared/stacks-agent/` |
83
+ | GitHub Copilot | `.github/prompts/stacks-agent.prompt.md` + `.shared/stacks-agent/` |
84
+ | Kiro | `.kiro/steering/stacks-agent.md` + `.shared/stacks-agent/` |
85
+ | Codex | `.codex/skills/stacks-agent/` |
34
86
 
35
- # Cursor
36
- stacksagent init --ai cursor
87
+ ## 🚀 Usage
37
88
 
38
- # Windsurf
39
- stacksagent init --ai windsurf
89
+ ### Claude Code
40
90
 
41
- # Antigravity
42
- stacksagent init --ai antigravity
91
+ The skill activates automatically when you request Stacks development work:
43
92
 
44
- # GitHub Copilot
45
- stacksagent init --ai copilot
93
+ ```
94
+ Create a meme token called PEPE with 1 billion supply
95
+ ```
46
96
 
47
- # Kiro
48
- stacksagent init --ai kiro
97
+ ### Cursor / Windsurf / Antigravity
49
98
 
50
- # Codex
51
- stacksagent init --ai codex
99
+ Use the slash command:
52
100
 
53
- # All platforms at once
54
- stacksagent init --ai all
101
+ ```
102
+ /stacks-agent Create a meme token called PEPE with 1 billion supply
55
103
  ```
56
104
 
57
- ### Force Overwrite
105
+ ### GitHub Copilot
58
106
 
59
- ```bash
60
- stacksagent init --ai claude --force
107
+ Reference in chat:
108
+
109
+ ```
110
+ @stacks-agent How do I swap tokens on Alex?
61
111
  ```
62
112
 
63
- ### Check Version
113
+ ## 💡 Example Prompts
64
114
 
65
- ```bash
66
- stacksagent --version
115
+ ```
116
+ "Create a SIP-010 token with burn mechanism"
117
+ "Build an NFT collection with royalties"
118
+ "Audit this Clarity contract for security issues"
119
+ "Show me how to integrate Alex swap in my dApp"
120
+ "How do I get BTC/USD price from Pyth oracle?"
121
+ "Deploy my contract to testnet"
122
+ "How do I implement stacking in my app?"
123
+ "Generate a DAO contract with proposal voting"
67
124
  ```
68
125
 
69
- ### Update to Latest
126
+ ## 🔍 Knowledge Base Search
127
+
128
+ The skill includes a powerful BM25-based search engine:
70
129
 
71
130
  ```bash
72
- stacksagent update
73
- ```
131
+ # Auto-detect domain
132
+ python3 .claude/skills/stacks-agent/scripts/search.py "define-public"
74
133
 
75
- ### List Available Versions
134
+ # Search specific domain
135
+ python3 .claude/skills/stacks-agent/scripts/search.py "swap tokens" --domain defi
76
136
 
77
- ```bash
78
- stacksagent versions
137
+ # Get more results
138
+ python3 .claude/skills/stacks-agent/scripts/search.py "security" --domain security -n 10
139
+
140
+ # JSON output
141
+ python3 .claude/skills/stacks-agent/scripts/search.py "stx transfer" --domain stacksjs -f json
79
142
  ```
80
143
 
81
- ## 💡 What Gets Installed
144
+ **Available domains**:
145
+ - `clarity` - Syntax and functions
146
+ - `templates` - Contract templates
147
+ - `security` - Security patterns
148
+ - `defi` - DeFi protocols
149
+ - `stacksjs` - JavaScript snippets
150
+ - `bns` - BNS operations
151
+ - `stacking` - Stacking guides
152
+ - `deployment` - Deployment steps
153
+ - `auto` - Auto-detect (default)
82
154
 
83
- The CLI installs platform-specific skill files in your project:
155
+ ## 📚 Knowledge Base Contents
84
156
 
85
- - **Claude Code**: `.claude/skills/stacks-agent/`
86
- - **Cursor**: `.cursor/commands/` + `.shared/stacks-agent/`
87
- - **Windsurf**: `.windsurf/workflows/` + `.shared/stacks-agent/`
88
- - **Antigravity**: `.agent/workflows/` + `.shared/stacks-agent/`
89
- - **Copilot**: `.github/prompts/` + `.shared/stacks-agent/`
90
- - **Kiro**: `.kiro/steering/` + `.shared/stacks-agent/`
91
- - **Codex**: `.codex/skills/stacks-agent/`
157
+ ### Clarity Language (61 entries)
158
+ Types, functions, control flow, arithmetic, comparisons, maps, tokens, STX operations
92
159
 
93
- ## 📚 Knowledge Base
160
+ ### Contract Templates (14 entries)
161
+ - **Tokens**: SIP-010 basic, mintable, burnable, capped
162
+ - **NFTs**: SIP-009 basic, mintable, royalties
163
+ - **DeFi**: Vault basic/timelocked, liquidity pool
164
+ - **DAO**: Basic DAO, treasury management
165
+ - **Other**: Marketplace, stacking pool
94
166
 
95
- 170+ entries across 8 domains:
167
+ ### Security Patterns (15 entries)
168
+ - Critical: Access control, unchecked transfers
169
+ - High: Reentrancy, arithmetic safety
170
+ - Medium: Input validation, front-running
171
+ - Low: Code style, gas optimization
96
172
 
97
- - **Clarity** (61) - Language syntax and functions
98
- - **Templates** (14) - Contract templates (SIP-010, SIP-009, DAO, Vault)
99
- - **Security** (15) - Vulnerability patterns and fixes
100
- - **DeFi** (15) - Protocol integrations (Alex, Velar, Bitflow, Zest)
101
- - **Stacks.js** (30) - Frontend integration snippets
102
- - **BNS** (10) - Bitcoin Name System operations
103
- - **Stacking** (15) - PoX stacking guides
104
- - **Deployment** (25) - Testnet/mainnet deployment steps
173
+ ### DeFi Protocols (15 entries)
174
+ Alex, Velar, Bitflow, Zest, StackingDAO, Boost, Faktory integration patterns
105
175
 
106
- ## 🔍 Search Knowledge Base
176
+ ### Stacks.js (30 entries)
177
+ Wallet connection, transactions, Clarity values, API calls, post-conditions
107
178
 
108
- After installation, search the knowledge base:
179
+ ### BNS (10 entries)
180
+ Name resolution, registration, transfer, updates
109
181
 
110
- ```bash
111
- python3 .claude/skills/stacks-agent/scripts/search.py "your query"
182
+ ### Stacking (15 entries)
183
+ Direct stacking, delegation, pools, rewards
112
184
 
113
- # Search specific domain
114
- python3 .claude/skills/stacks-agent/scripts/search.py "swap tokens" --domain defi
115
-
116
- # Get more results
117
- python3 .claude/skills/stacks-agent/scripts/search.py "security" -n 10
185
+ ### Deployment (25 entries)
186
+ Testnet, mainnet, devnet workflows with Clarinet
118
187
 
119
- # JSON output
120
- python3 .claude/skills/stacks-agent/scripts/search.py "stx transfer" -f json
121
- ```
188
+ ## 🛡️ Security Best Practices
122
189
 
123
- ## 💬 Example Prompts
190
+ All generated contracts include:
124
191
 
125
- After installing the skill, ask your AI assistant:
192
+ - ✅ Access control (`tx-sender` validation)
193
+ - ✅ Error handling (`try!`, `unwrap!`)
194
+ - ✅ Input validation (`asserts!`)
195
+ - ✅ Named error constants
196
+ - ✅ Kebab-case naming
197
+ - ✅ Network compatibility checks
126
198
 
127
- - "Create a SIP-010 token with burn mechanism"
128
- - "Build an NFT collection with royalties"
129
- - "Audit this Clarity contract for security issues"
130
- - "Show me how to integrate Alex swap"
131
- - "Deploy my contract to testnet"
132
- - "How do I implement stacking?"
199
+ ## 🌐 Networks
133
200
 
134
- ## 🛠️ Development
201
+ - **Mainnet**: Production (SP... addresses)
202
+ - **Testnet**: Testing (ST... addresses, free STX)
203
+ - **Devnet**: Local development (Clarinet)
135
204
 
136
- ### Requirements
205
+ ## 🔧 Prerequisites
137
206
 
138
- - Node.js 18+
139
207
  - Python 3.x (for search functionality)
140
-
141
- ### Build from Source
208
+ - Node.js 18+ (for CLI installation)
142
209
 
143
210
  ```bash
144
- git clone https://github.com/kai-builder/stacksagent.git
145
- cd stacksagent/cli
146
- npm install
147
- npm run build
148
- npm link
211
+ python3 --version
212
+ node --version
149
213
  ```
150
214
 
151
215
  ## 📖 Documentation
152
216
 
153
- - [Main Repository](https://github.com/kai-builder/stacksagent)
154
217
  - [Stacks Docs](https://docs.stacks.co)
155
218
  - [Clarity Reference](https://docs.stacks.co/clarity)
156
219
  - [Hiro Platform](https://platform.hiro.so)
220
+ - [Explorer (Mainnet)](https://explorer.hiro.so)
221
+ - [Explorer (Testnet)](https://explorer.hiro.so/?chain=testnet)
222
+
223
+ ## 🔗 DeFi Resources
224
+
225
+ - [Alex DEX](https://app.alexlab.co)
226
+ - [Velar DEX](https://app.velar.co)
227
+ - [Bitflow DEX](https://app.bitflow.finance)
228
+ - [Zest Protocol](https://www.zestprotocol.com)
157
229
 
158
230
  ## 🤝 Contributing
159
231
 
160
- Contributions welcome! Please see [Contributing Guide](https://github.com/kai-builder/stacksagent/blob/main/CONTRIBUTING.md).
232
+ Contributions are welcome! Please:
233
+
234
+ 1. Fork the repository
235
+ 2. Create a feature branch
236
+ 3. Make your changes
237
+ 4. Add knowledge entries to appropriate CSV files
238
+ 5. Test the search functionality
239
+ 6. Submit a pull request
161
240
 
162
241
  ## 📄 License
163
242
 
164
- MIT License - see [LICENSE](LICENSE) for details.
243
+ MIT License - see [LICENSE](LICENSE) file for details
165
244
 
166
- ## 🙏 Credits
245
+ ## 🙏 Acknowledgments
167
246
 
168
247
  Built for the Stacks community with:
169
- - [Stacks.js](https://github.com/hirosystems/stacks.js)
248
+ - [Stacks.js](https://github.com/hirosystems/stacks.js) by Hiro Systems
170
249
  - [Stacks Blockchain](https://www.stacks.co)
171
250
  - [Clarity Language](https://docs.stacks.co/clarity)
172
251
 
173
252
  ## 📞 Support
174
253
 
175
- - **GitHub Issues**: [Report bugs or request features](https://github.com/kai-builder/stacksagent/issues)
176
- - **Stacks Discord**: [Join the community](https://discord.gg/stacks)
254
+ - GitHub Issues: [Report bugs or request features](https://github.com/kai-builder/stacks-agent/issues)
255
+ - Stacks Discord: [Join the community](https://discord.gg/stacks)
256
+ - Twitter: [@kai_builder](https://twitter.com/kai_builder)
257
+
258
+ ## 🎯 Roadmap
259
+
260
+ - [x] Multi-platform AI skill support
261
+ - [x] 170+ knowledge base entries
262
+ - [x] BM25 search engine
263
+ - [x] CLI installer
264
+ - [ ] Web-based search interface
265
+ - [ ] VSCode extension
266
+ - [ ] Real-time contract analysis
267
+ - [ ] Community knowledge contributions
268
+ - [ ] Multi-language support
177
269
 
178
270
  ---
179
271
 
package/dist/assets/.shared/stacks-agent/data/oracles.csv ADDED
@@ -0,0 +1,31 @@
1
+ id,language,oracle,category,name,description,code,imports_or_contract,notes
2
+ 1,clarity,pyth,setup,mainnet-contract,"Pyth Oracle V4 mainnet contract","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Mainnet: SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Storage: pyth-storage-v4; Decoder: pyth-pnau-decoder-v3; Wormhole: wormhole-core-v4"
3
+ 2,clarity,pyth,setup,testnet-contract,"Pyth Oracle V4 testnet contract","STR738QQX1PVTM6WTDF833Z18T8R0ZB791TCNEFM.pyth-oracle-v4","Testnet: STR738QQX1PVTM6WTDF833Z18T8R0ZB791TCNEFM.pyth-oracle-v4","Same trait contract names as mainnet (pyth-storage-v4 etc)"
4
+ 3,clarity,pyth,read,decode-price-feeds,"Decode VAA bytes to extract price info","(contract-call? .pyth-oracle-v4 decode-price-feeds vaa-buffer trait-tuple)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns price ema-price conf ema-conf expo publish-time; Read-only no fee"
5
+ 4,clarity,pyth,write,verify-and-update-price-feeds,"Verify VAA signatures and update on-chain prices","(contract-call? .pyth-oracle-v4 verify-and-update-price-feeds vaa-buffer trait-tuple)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Costs 1 STX fee; Updates stored price feeds; Verifies Wormhole signatures"
6
+ 5,clarity,pyth,read,read-price-feed,"Read stored on-chain price for a feed ID","(contract-call? .pyth-oracle-v4 read-price-feed feed-id-buffer storage-trait)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns stored price data; Must be updated first via verify-and-update"
7
+ 6,clarity,pyth,read,get-price,"Get current price value for a feed","(contract-call? .pyth-oracle-v4 get-price feed-id-buffer storage-trait)","SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4","Returns (ok {price ema-price conf ema-conf expo publish-time prev-publish-time})"
8
+ 7,clarity,pyth,trait,trait-tuple,"Build trait tuple for Pyth calls","(tuple (pyth-storage-contract (contract-principal .pyth-storage-v4)) (pyth-decoder-contract (contract-principal .pyth-pnau-decoder-v3)) (wormhole-core-contract (contract-principal .wormhole-core-v4)))","Trait implementor contracts","Required for all Pyth contract calls; Use same address as oracle contract"
9
+ 8,clarity,pyth,feed-id,btc-usd-feed,"BTC/USD price feed ID","0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43","Pyth mainnet feed ID","Use bufferCV(hexToBuff(feedId)) in contract calls"
10
+ 9,clarity,pyth,feed-id,stx-usd-feed,"STX/USD price feed ID","0xec7a775f46379b5e943c3526b1c8d54cd49749176b0b98e02dde68d1bd335c17","Pyth mainnet feed ID","Primary feed for STX price oracle"
11
+ 10,clarity,pyth,feed-id,eth-usd-feed,"ETH/USD price feed ID","0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace","Pyth mainnet feed ID","Standard Ethereum price feed"
12
+ 11,clarity,pyth,feed-id,usdc-usd-feed,"USDC/USD price feed ID","0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a","Pyth mainnet feed ID","Stablecoin price feed"
13
+ 12,javascript,pyth,decode,decode-price-call,"Call decode-price-feeds from JS","const { request } = await import('@stacks/connect'); const vaa = bufferCV(hexToBuff(vaaHex)); const traits = tupleCV({...traitTuple}); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'decode-price-feeds' functionArgs: [vaa traits].map(cvToHex) network})","import { bufferCV tupleCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Returns decoded price data; Read-only transaction"
14
+ 13,javascript,pyth,update,verify-update-call,"Call verify-and-update-price-feeds from JS","const { request } = await import('@stacks/connect'); const vaa = bufferCV(hexToBuff(vaaHex)); const traits = tupleCV({...traitTuple}); const pc = Pc.principal(userAddr).willSendLte(1000000).ustx(); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'verify-and-update-price-feeds' functionArgs: [vaa traits].map(cvToHex) postConditions: [pc] network})","import { bufferCV tupleCV cvToHex Pc } from '@stacks/transactions'; import { request } from '@stacks/connect'","Requires 1 STX fee; Add post-condition for safety"
15
+ 14,javascript,pyth,read,read-price-call,"Call read-price-feed from JS","const { request } = await import('@stacks/connect'); const feedId = bufferCV(hexToBuff(feedIdHex)); const storage = contractPrincipalCV(address 'pyth-storage-v4'); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'read-price-feed' functionArgs: [feedId storage].map(cvToHex) network})","import { bufferCV contractPrincipalCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Read stored price; Must be updated first"
16
+ 15,javascript,pyth,read,get-price-call,"Call get-price from JS","const { request } = await import('@stacks/connect'); const feedId = bufferCV(hexToBuff(feedIdHex)); const storage = contractPrincipalCV(address 'pyth-storage-v4'); await request('stx_callContract' {contract: `${addr}.${name}` functionName: 'get-price' functionArgs: [feedId storage].map(cvToHex) network})","import { bufferCV contractPrincipalCV cvToHex } from '@stacks/transactions'; import { request } from '@stacks/connect'","Returns current price with all metadata"
17
+ 16,javascript,pyth,util,hex-to-buffer,"Convert hex string to buffer for Pyth calls","function hexToBuff(hexWith0x) { const h = hexWith0x.startsWith('0x') ? hexWith0x.slice(2) : hexWith0x; return Buffer.from(h 'hex') }","import { Buffer } from 'buffer'","Required to convert feed IDs and VAA hex to buffers"
18
+ 17,javascript,pyth,util,trait-tuple-builder,"Build trait tuple for contract calls","function traitTuple(network) { const addr = getContractAddress(network); return tupleCV({ 'pyth-storage-contract': contractPrincipalCV(addr 'pyth-storage-v4') 'pyth-decoder-contract': contractPrincipalCV(addr 'pyth-pnau-decoder-v3') 'wormhole-core-contract': contractPrincipalCV(addr 'wormhole-core-v4') }) }","import { tupleCV contractPrincipalCV } from '@stacks/transactions'","Use same address as oracle contract; Required for decode and verify calls"
19
+ 18,api,pyth,hermes,fetch-latest-vaa,"Fetch latest VAA from Hermes API","const feedId = '0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43'; const url = `https://hermes.pyth.network/api/latest_vaas?ids[]=${encodeURIComponent(feedId)}`; const res = await fetch(url); const vaas = await res.json(); const vaaHex = base64ToHex(vaas[0])","fetch or axios","Returns base64-encoded VAA; Convert to hex before using in contract calls"
20
+ 19,api,pyth,hermes,hermes-client-sdk,"Use Hermes client SDK to fetch VAA","import { HermesClient } from '@pythnetwork/hermes-client'; const hermes = new HermesClient('https://hermes.pyth.network'); const vaas = await hermes.getLatestVaas({ids: [feedId]}); const vaaHex = base64ToHex(vaas[0])","npm install @pythnetwork/hermes-client","SDK handles VAA fetching; Still need to convert base64 to hex"
21
+ 20,javascript,pyth,util,base64-to-hex,"Convert base64 VAA to hex","function base64ToHex(b64) { const binStr = atob(b64); let hex = '0x'; for (let i = 0; i < binStr.length; i++) { hex += (binStr.charCodeAt(i) & 0xff).toString(16).padStart(2 '0') } return hex }","Native JavaScript","Required to convert Hermes VAA response to hex for contract calls"
22
+ 21,javascript,pyth,parse,parse-price-result,"Parse price data from contract result","function parsePriceFromResult(repr) { const tupleMatch = repr.match(/\(ok \((?:tuple|list.*tuple) \(([\s\S]*?)\)\)\)/); if (!tupleMatch) return null; const content = tupleMatch[1]; return { price: parseInt(content.match(/price (\d+|u\d+)/)?.[1] || 0) emaPrice: parseInt(content.match(/ema-price (\d+)/)?.[1] || 0) conf: parseInt(content.match(/conf u(\d+)/)?.[1] || 0) emaConf: parseInt(content.match(/ema-conf u(\d+)/)?.[1] || 0) expo: parseInt(content.match(/expo (-?\d+)/)?.[1] || 0) publishTime: parseInt(content.match(/publish-time u(\d+)/)?.[1] || 0) } }","None","Parse transaction result repr string to extract price data"
23
+ 22,javascript,pyth,calc,calculate-actual-price,"Calculate actual price from price data","function calculateActualPrice(priceData) { return priceData.emaPrice / Math.pow(10 Math.abs(priceData.expo)) }","None","Formula: ema-price / 10^|expo|; Expo is typically -8 so divide by 10^8"
24
+ 23,javascript,pyth,parse,parse-update-event,"Parse price from verify-and-update event","function parsePriceUpdateEvent(events) { for (const event of events) { if (event.event_type === 'smart_contract_log' && event.contract_log) { const repr = event.contract_log.value.repr; if (repr.includes('action \"updated\"') && repr.includes('type \"price-feed\"')) { const dataMatch = repr.match(/data \(tuple ([\s\S]*?)\)\)/); if (dataMatch) { return parsePriceFromResult(`(ok (tuple ${dataMatch[1]}))`); } } } } return null }","None","Extract price data from contract log events after verify-and-update"
25
+ 24,api,pyth,hiro,fetch-transaction-result,"Fetch and parse transaction from Hiro API","async function getTxResult(txId network) { const baseUrl = network === 'mainnet' ? 'https://api.mainnet.hiro.so' : 'https://api.testnet.hiro.so'; const res = await fetch(`${baseUrl}/extended/v1/tx/${txId}`); const tx = await res.json(); if (tx.tx_status === 'success' && tx.tx_result?.repr) { return parsePriceFromResult(tx.tx_result.repr) } return null }","fetch or axios","Wait ~10s after tx submit for indexing; Parse result to get price data"
26
+ 25,clarity,pyth,example,full-oracle-integration,"Complete price oracle integration example","(define-read-only (get-btc-price) (let ((feed-id 0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43)) (match (contract-call? 'SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-oracle-v4 get-price feed-id 'SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-storage-v4) success (ok (get ema-price success)) error (err u404))))","Pyth oracle contract","Read-only function to get BTC price; Returns ema-price or error"
27
+ 26,javascript,pyth,example,full-update-flow,"Complete flow to update price on-chain","// 1. Fetch VAA from Hermes; const hermes = new HermesClient('https://hermes.pyth.network'); const vaas = await hermes.getLatestVaas({ids: [feedId]}); const vaaHex = base64ToHex(vaas[0]); // 2. Update price on-chain; const { request } = await import('@stacks/connect'); const tx = await request('stx_callContract' {...}); // 3. Wait and fetch result; setTimeout(async () => { const result = await getTxResult(tx.txid 'mainnet'); const price = calculateActualPrice(result) } 10000)","Multiple imports","Complete workflow: fetch VAA update on-chain parse result calculate price"
28
+ 27,javascript,pyth,feeds,price-feed-constants,"Common Pyth price feed IDs","const PRICE_FEEDS = { BTC_USD: '0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43' STX_USD: '0xec7a775f46379b5e943c3526b1c8d54cd49749176b0b98e02dde68d1bd335c17' ETH_USD: '0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace' USDC_USD: '0xeaa020c61cc479712813461ce153894a96a6c00b21ed0cfc2798d1f9a9e9c94a' BNB_USD: '0x2f95862b045670cd22bee3114c39763a4a08beeb663b145d283c31d7d1101c4f' LINK_USD: '0x8ac0c70fff57e9aefdf5edf44b51d62c2d433653cbb2cf5cc06bb115af04d221' }","None","Mainnet feed IDs; Find more at pyth.network/price-feeds"
29
+ 28,javascript,pyth,wallet,connect-for-oracle,"Connect wallet for oracle transactions","import { connect isConnected getLocalStorage } from '@stacks/connect'; const appDetails = { name: 'My Pyth App' icon: window.location.origin + '/icon.png' }; const response = await connect(); const stxAddress = response.addresses.stx[0].address","npm install @stacks/connect","Required for verify-and-update transactions (read-only calls work without wallet)"
30
+ 29,api,pyth,hermes,hermes-endpoints,"Pyth Hermes API endpoints","// Latest VAA: https://hermes.pyth.network/api/latest_vaas?ids[]={feedId}; // Latest price updates: https://hermes.pyth.network/api/latest_price_feeds?ids[]={feedId}; // All feed IDs: https://hermes.pyth.network/api/price_feed_ids","Hermes REST API","Free API; No authentication required; Mainnet production endpoint"
31
+ 30,clarity,pyth,price-calc,price-calculation,"Price calculation in Clarity","(define-read-only (calculate-price (price-data (tuple (ema-price int) (expo int)))) (let ((ema (get ema-price price-data)) (exp (get expo price-data))) (if (< exp 0) (/ ema (pow u10 (to-uint (- 0 exp)))) (* ema (pow u10 (to-uint exp))))))","None","Convert raw price with exponent; Handle negative exponents (most common)"
package/dist/assets/.shared/stacks-agent/scripts/core.py CHANGED
@@ -24,7 +24,8 @@ DOMAINS = {
24
24
  'auth': 'authentication.csv',
25
25
  'advanced': 'advanced-patterns.csv',
26
26
  'chainhooks': 'chainhooks.csv',
27
- 'trading': 'trading-bots.csv'
27
+ 'trading': 'trading-bots.csv',
28
+ 'oracles': 'oracles.csv'
28
29
  }
29
30
 
30
31
  # Auto-detection keywords
@@ -42,7 +43,8 @@ DOMAIN_KEYWORDS = {
42
43
  'auth': ['jwt', 'middleware', 'encrypt', 'decrypt', 'access-control', 'token-gate', 'nft-gate', 'protected-route', 'verify-signature'],
43
44
  'advanced': ['pagination', 'swr', 'activity', 'presale', 'lottery', 'portfolio', 'wizard', 'launchpad', 'template', 'milestone', 'vesting', 'export', 'csv', 'modal', 'confirmation'],
44
45
  'chainhooks': ['chainhook', 'webhook', 'txid', 'contract-call', 'print-event', 'ft-event', 'nft-event', 'stx-event', 'predicate', 'hiro', 'indexing', 'ordinals'],
45
- 'trading': ['trading', 'bot', 'automated', 'wallet-sdk', 'privy', 'buy', 'sell', 'swap', 'dex', 'post-condition', 'broadcast', 'signature', 'recovery', 'txOptions', 'makeContractCall', 'bonding']
46
+ 'trading': ['trading', 'bot', 'automated', 'wallet-sdk', 'privy', 'buy', 'sell', 'swap', 'dex', 'post-condition', 'broadcast', 'signature', 'recovery', 'txOptions', 'makeContractCall', 'bonding'],
47
+ 'oracles': ['oracle', 'pyth', 'price', 'feed', 'vaa', 'hermes', 'wormhole', 'verify', 'update', 'decode']
46
48
  }
47
49
 
48
50
 
package/dist/index.js CHANGED
File without changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stacksagent",
3
- "version": "1.4.0",
3
+ "version": "1.5.0",
4
4
  "description": "AI Skill for building Stacks blockchain applications - CLI installer",
5
5
  "bin": {
6
6
  "stacksagent": "./dist/index.js"
@@ -11,7 +11,8 @@
11
11
  "README.md"
12
12
  ],
13
13
  "scripts": {
14
- "build": "tsc && npm run copy-assets",
14
+ "build": "npm run copy-readme && tsc && npm run copy-assets",
15
+ "copy-readme": "cp ../README.md ./README.md",
15
16
  "copy-assets": "cp -r src/assets dist/",
16
17
  "dev": "tsc --watch",
17
18
  "prepublishOnly": "npm run build"