@waiaas/skills 2.2.1 → 2.3.0-rc.1

package/README.md

@@ -0,0 +1,154 @@
+# WAIaaS
+
+**Wallet-as-a-Service for AI Agents**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-22_LTS-green.svg)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/Tests-3%2C599_passing-brightgreen.svg)](#)
+
+A self-hosted wallet daemon that lets AI agents perform on-chain transactions securely -- while the owner keeps full control of funds.
+
+## The Problem
+
+AI agents that need to transact on-chain face an impossible choice: hold private keys (and risk total loss if compromised) or depend on a centralized custodian (single point of failure, trust dependency).
+
+WAIaaS bridges the gap -- agents handle small transactions instantly, large amounts require owner approval, and everything runs on your machine with no third-party dependency.
+
+## How It Works
+
+WAIaaS is a local daemon that sits between your AI agent and the blockchain:
+
+- **3-tier authentication** -- Separate roles for the daemon operator (masterAuth), fund owner (ownerAuth), and AI agent (sessionAuth)
+- **4-tier policy engine** -- Transactions are auto-classified by USD value into INSTANT / NOTIFY / DELAY / APPROVAL tiers
+- **12 policy types** -- Cumulative spend limits, token allowlists, contract whitelists, approved spenders, and more
+- **Defense in depth** -- Kill Switch, AutoStop engine, audit logging, 4-channel notifications
+
+See [Security Model](docs/security-model.md) for full details.
+
+## Quick Start
+
+```bash
+npm install -g @waiaas/cli
+waiaas init                        # Create data directory + config.toml
+waiaas start                       # Start daemon (sets master password on first run)
+waiaas quickset --mode testnet     # Create wallets + MCP sessions in one step
+```
+
+The `quickset` command does everything you need to get started:
+
+1. Creates **Solana Devnet + EVM Sepolia** wallets automatically
+2. Issues **MCP session tokens** for each wallet
+3. Outputs a **Claude Desktop MCP config** snippet -- just copy and paste
+
+> Starting with mainnet? Use `waiaas quickset --mode mainnet` to create Solana Mainnet + EVM Ethereum Mainnet wallets instead. Mainnet mode recommends configuring spending limits and registering an owner wallet for high-value transaction approval.
+
+### Admin UI
+
+After starting the daemon, manage everything from the admin panel at `http://127.0.0.1:3100/admin` (masterAuth required).
+
+## Connect Your AI Agent
+
+After quickset, choose one of two integration paths:
+
+### Path A: MCP (Claude Desktop / Claude Code)
+
+For AI agents that support the [Model Context Protocol](https://modelcontextprotocol.io):
+
+```bash
+# quickset already printed the MCP config JSON -- paste it into
+# ~/Library/Application Support/Claude/claude_desktop_config.json
+# Or auto-register with all wallets:
+waiaas mcp setup --all
+```
+
+The daemon runs as an MCP server. Your agent calls wallet tools directly -- send tokens, check balances, manage policies -- all through the MCP protocol.
+
+### Path B: Skill Files (Any AI Agent)
+
+For agents that don't support MCP, or when you prefer REST API integration:
+
+```bash
+npx @waiaas/skills add all
+```
+
+This adds `.skill.md` instruction files to your project. Include them in your agent's context and it learns the WAIaaS API automatically. Available skills: `quickstart`, `wallet`, `transactions`, `policies`, `admin`, `actions`, `x402`.
+
+## Alternative: Docker
+
+```bash
+git clone https://github.com/minho-yoo/waiaas.git && cd waiaas
+docker compose up -d
+```
+
+The daemon listens on `http://127.0.0.1:3100`.
+
+## Using the SDK
+
+```typescript
+import { WAIaaSClient } from '@waiaas/sdk';
+
+const client = new WAIaaSClient({
+  baseUrl: 'http://127.0.0.1:3100',
+  sessionToken: process.env.WAIAAS_SESSION_TOKEN,
+});
+
+const balance = await client.getBalance();
+console.log(`Balance: ${balance.amount} SOL`);
+
+const tx = await client.sendToken({
+  to: 'recipient-address...',
+  amount: '0.1',
+});
+console.log(`Transaction: ${tx.signature}`);
+```
+
+## Admin UI
+
+Access the admin panel at `http://127.0.0.1:3100/admin` with your master password:
+
+- **Dashboard** -- System overview, wallet balances, recent transactions
+- **Wallets** -- Create, manage, and monitor wallets across chains; RPC endpoints, balance monitoring, and WalletConnect settings
+- **Sessions** -- Issue and revoke agent session tokens; session lifetime and rate limit settings
+- **Policies** -- Configure 12 policy types with visual form editors; default deny and tier settings
+- **Notifications** -- Channel status and delivery logs; Telegram, Discord, ntfy, and Slack settings
+- **Security** -- Kill Switch emergency controls, AutoStop protection rules, JWT rotation
+- **System** -- API keys, display currency, price oracle, rate limits, log level, and daemon shutdown
+
+Features include settings search (Ctrl+K / Cmd+K) and unsaved changes protection.
+
+Enabled by default (`admin_ui = true` in config.toml).
+
+## Supported Networks
+
+| Chain | Environment | Networks |
+|-------|-------------|----------|
+| Solana | mainnet | mainnet |
+| Solana | testnet | devnet, testnet |
+| EVM | mainnet | ethereum-mainnet, polygon-mainnet, arbitrum-mainnet, optimism-mainnet, base-mainnet |
+| EVM | testnet | ethereum-sepolia, polygon-amoy, arbitrum-sepolia, optimism-sepolia, base-sepolia |
+
+13 networks total (Solana 3 + EVM 10).
+
+## Features
+
+- **Self-hosted local daemon** -- No central server; keys never leave your machine
+- **Multi-chain** -- Solana (SPL / Token-2022) and EVM (ERC-20) via `IChainAdapter`
+- **Token, contract, and DeFi** -- Native transfers, token transfers, contract calls, approve, batch transactions, Action Provider plugins (Jupiter Swap, etc.)
+- **USD policy evaluation** -- Price oracles (CoinGecko / Pyth / Chainlink) evaluate all transactions in USD
+- **x402 payments** -- Automatic HTTP 402 payment handling with EIP-3009 signatures
+- **Multiple interfaces** -- REST API, TypeScript SDK, Python SDK, MCP server, CLI, Admin Web UI, Tauri Desktop, Telegram Bot
+- **Skill files** -- Pre-built instruction files that teach AI agents how to use the API
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Security Model](docs/security-model.md) | Authentication, policy engine, Kill Switch, AutoStop |
+| [Deployment Guide](docs/deployment.md) | Docker, npm, configuration reference |
+| [API Reference](docs/api-reference.md) | REST API endpoints and authentication |
+| [Why WAIaaS?](docs/why-waiaas/) | Background on AI agent wallet security |
+| [Contributing](CONTRIBUTING.md) | Development setup, code style, testing, PR guidelines |
+
+## License
+
+[MIT](LICENSE) -- Copyright (c) 2026 WAIaaS Contributors

package/dist/registry.js

@@ -3,7 +3,7 @@ export const SKILL_REGISTRY = [
     {
         name: "quickstart",
         filename: "quickstart.skill.md",
-        description: "End-to-end quickstart: create wallet, session, check balance, send first transfer",
+        description: "End-to-end quickset: create wallet, session, check balance, send first transfer",
     },
     {
         name: "wallet",

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,MAAM,CAAC,MAAM,cAAc,GAA0B;IACnD;QACE,IAAI,EAAE,YAAY;QAClB,QAAQ,EAAE,qBAAqB;QAC/B,WAAW,EACT,mFAAmF;KACtF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,iBAAiB;QAC3B,WAAW,EACT,oGAAoG;KACvG;IACD;QACE,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,uBAAuB;QACjC,WAAW,EACT,6GAA6G;KAChH;IACD;QACE,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,mBAAmB;QAC7B,WAAW,EACT,kLAAkL;KACrL;IACD;QACE,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,gBAAgB;QAC1B,WAAW,EACT,sIAAsI;KACzI;IACD;QACE,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,kBAAkB;QAC5B,WAAW,EACT,0GAA0G;KAC7G;IACD;QACE,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,eAAe;QACzB,WAAW,EACT,+EAA+E;KAClF;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACxD,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,MAAM,CAAC,MAAM,cAAc,GAA0B;IACnD;QACE,IAAI,EAAE,YAAY;QAClB,QAAQ,EAAE,qBAAqB;QAC/B,WAAW,EACT,iFAAiF;KACpF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,iBAAiB;QAC3B,WAAW,EACT,oGAAoG;KACvG;IACD;QACE,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,uBAAuB;QACjC,WAAW,EACT,6GAA6G;KAChH;IACD;QACE,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE,mBAAmB;QAC7B,WAAW,EACT,kLAAkL;KACrL;IACD;QACE,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,gBAAgB;QAC1B,WAAW,EACT,sIAAsI;KACzI;IACD;QACE,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,kBAAkB;QAC5B,WAAW,EACT,0GAA0G;KAC7G;IACD;QACE,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,eAAe;QACzB,WAAW,EACT,+EAA+E;KAClF;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@waiaas/skills",
-  "version": "2.2.1",
+  "version": "2.3.0-rc.1",
   "description": "WAIaaS skill files for AI agents - install via npx @waiaas/skills add <name>",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/minho-yoo/waiaas.git",
+    "url": "git+https://github.com/minhoyoo-iotrust/WAIaaS.git",
     "directory": "packages/skills"
   },
-  "homepage": "https://github.com/minho-yoo/waiaas#readme",
+  "homepage": "https://github.com/minhoyoo-iotrust/WAIaaS#readme",
+  "bugs": {
+    "url": "https://github.com/minhoyoo-iotrust/WAIaaS/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -20,14 +23,15 @@
     "dist",
     "skills"
   ],
+  "scripts": {
+    "prebuild": "node scripts/sync-version.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist"
+  },
   "engines": {
     "node": ">=22.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "clean": "rm -rf dist"
   }
-}
+}

package/skills/actions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Actions"
 description: "Action Provider framework: list providers, execute DeFi actions through the 6-stage transaction pipeline"
 category: "api"
 tags: [wallet, blockchain, defi, actions, waiass]
-version: "1.5.0"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/admin.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Admin"
 description: "Admin API: daemon status, kill switch, notifications, settings management, JWT rotation, shutdown, oracle status, API key management"
 category: "api"
 tags: [wallet, blockchain, admin, security, oracle, defi, waiass]
-version: "1.8.0"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/policies.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Policies"
 description: "Policy engine CRUD: 12 policy types for spending limits, whitelists, time restrictions, rate limits, token/contract/approve controls, network restrictions, x402 domain controls"
 category: "api"
 tags: [wallet, blockchain, policies, security, waiass]
-version: "1.5.3"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/quickstart.skill.md

@@ -1,18 +1,77 @@
 ---
-name: "WAIaaS Quickstart"
-description: "End-to-end quickstart: create wallet, session, check balance, send first transfer"
+name: "WAIaaS Quickset"
+description: "End-to-end quickset: create wallet, session, check balance, send first transfer"
 category: "api"
-tags: [wallet, blockchain, solana, ethereum, quickstart, waiass]
-version: "1.8.0"
+tags: [wallet, blockchain, solana, ethereum, quickset, quickstart, waiass]
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
 ---
 
-# WAIaaS Quickstart
+# WAIaaS Quickset
 
 WAIaaS (Wallet-as-a-Service for AI Agents) is a self-hosted local daemon that lets AI agents execute on-chain transactions on Solana and Ethereum with policy-based security controls. This guide walks through the complete workflow from creating your first wallet to sending a transaction.
 
+## 0. Connection Info
+
+### Magic Word (Agent Connection Prompt)
+
+If the user provides a `[WAIaaS Connection]` block, extract connection info and start API calls immediately:
+
+- `URL` -> API base URL
+- `Wallets` -> numbered list with wallet name, ID, network, session token
+- `Session` -> use as `Authorization: Bearer {token}` header
+
+Example format:
+```
+[WAIaaS Connection]
+- URL: http://localhost:3100
+
+Wallets:
+1. solana-testnet (019c6fb6-...) -- solana-devnet
+   Session: eyJhbG...
+```
+
+### Session Renewal
+
+On `401 Unauthorized` response:
+1. Extract `sessionId` from JWT payload `sub` claim
+2. `POST /v1/wallets/{walletId}/sessions/{sessionId}/renew`
+3. Use the new token from response for subsequent requests
+
+### No Connection Info?
+
+Ask the user:
+"WAIaaS connection info is needed. Copy the agent prompt from the Admin UI dashboard or from the `waiaas quickset` completion screen using 'Copy Agent Prompt' and paste it here."
+
+### Manual Discovery
+
+Check if the daemon is running and discover existing wallets before starting.
+
+#### Health Check
+
+```bash
+curl -s http://localhost:3100/health
+```
+
+If successful, you get `{"status":"ok", ...}`. If the daemon is not running, start it with `waiaas start`.
+
+#### List Existing Wallets (requires masterAuth)
+
+```bash
+curl -s http://localhost:3100/v1/wallets \
+  -H 'X-Master-Password: <master-password>'
+```
+
+This returns all wallets. If wallets already exist, you can skip to Step 3 (Create a Session) using an existing wallet ID.
+
+> **Note**: The master password is the value set during `waiaas init`.
+>
+> Skill files are API references. For interactive use with an AI agent,
+> set up the MCP server (`waiaas mcp setup`) or provide the daemon URL
+> and authentication credentials directly.
+
 ## Base URL
 
 ```
@@ -259,12 +318,12 @@ Transaction status values:
 - `FAILED` -- execution or confirmation failed
 - `CANCELLED` -- cancelled by wallet or owner
 
-## CLI Quickstart (Alternative)
+## CLI Quickset (Alternative)
 
 If you have the CLI installed, create wallets in one step:
 
 ```bash
-waiaas quickstart --mode testnet
+waiaas quickset --mode testnet
 ```
 
 This creates Solana + EVM wallets and prints MCP configuration.
@@ -304,3 +363,5 @@ Common error codes:
 - **transactions.skill.md** -- All 5 transaction types (TRANSFER, TOKEN_TRANSFER, CONTRACT_CALL, APPROVE, BATCH) with full parameters
 - **policies.skill.md** -- Policy management (spending limits, whitelists, rate limits, approval tiers)
 - **admin.skill.md** -- Admin operations (kill switch, status, settings, notifications)
+- **actions.skill.md** -- DeFi action providers: list and execute DeFi actions through the transaction pipeline
+- **x402.skill.md** -- x402 auto-payment protocol for fetching paid URLs with cryptocurrency

package/skills/transactions.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Transactions"
 description: "All 5 transaction types (TRANSFER, TOKEN_TRANSFER, CONTRACT_CALL, APPROVE, BATCH) with lifecycle management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, transactions, waiass]
-version: "1.5.3"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/wallet.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Wallet Management"
 description: "Wallet CRUD, asset queries, session management, token registry, MCP provisioning, owner management"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, sessions, tokens, mcp, waiass]
-version: "1.6.1"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/skills/x402.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS x402"
 description: "x402 auto-payment protocol: fetch URLs with automatic cryptocurrency payments"
 category: "api"
 tags: [wallet, blockchain, x402, payments, waiass]
-version: "1.5.1"
+version: "2.3.0-rc.1"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 WAIaaS Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.