@waiaas/skills 2.6.0-rc → 2.6.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waiaas/skills",
-  "version": "2.6.0-rc",
+  "version": "2.6.0-rc.2",
   "description": "WAIaaS skill files for AI agents - install via npx @waiaas/skills add <name>",
   "license": "MIT",
   "type": "module",

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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -11,6 +11,8 @@ dispatch:
 
 # WAIaaS Admin API
 
+> **Operator only.** All admin endpoints require masterAuth (X-Master-Password). AI agents must NOT use these endpoints — they are for the Operator via Admin UI or CLI.
+
 Admin endpoints for daemon operations management. Covers health monitoring, emergency kill switch, notification channels, settings (RPC, security, notifications), JWT secret rotation, and graceful shutdown.
 
 ## Base URL

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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -11,6 +11,8 @@ dispatch:
 
 # WAIaaS Policy Management
 
+> **Policy CRUD (create/update/delete) is Operator only** (requires masterAuth). AI agents can read policies via GET endpoints with sessionAuth, but cannot modify them.
+
 Policy engine for enforcing rules on wallet operations. Policies control spending limits, allowed recipients, time windows, rate limits, token whitelists, contract access, approval requirements, and network restrictions.
 
 ## Base URL
@@ -160,26 +162,50 @@ Maximum spend per tier. Amounts are digit strings in the chain's smallest unit (
   "notify_max_usd": 100,
   "delay_max_usd": 1000,
   "daily_limit_usd": 500,
-  "monthly_limit_usd": 5000
+  "monthly_limit_usd": 5000,
+  "token_limits": {
+    "native:solana": {"instant_max": "1", "notify_max": "10", "delay_max": "50"},
+    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": {"instant_max": "100", "notify_max": "1000", "delay_max": "10000"}
+  }
 }
 ```
 
 | Field               | Type   | Required | Description                                          |
 | ------------------- | ------ | -------- | ---------------------------------------------------- |
-| `instant_max`       | string | Yes      | Max amount for INSTANT tier (digit string).          |
-| `notify_max`        | string | Yes      | Max amount for NOTIFY tier (digit string).           |
-| `delay_max`         | string | Yes      | Max amount for DELAY tier (digit string).            |
+| `instant_max`       | string | No       | Max amount for INSTANT tier (digit string, raw units). Optional when token_limits or USD thresholds are set. |
+| `notify_max`        | string | No       | Max amount for NOTIFY tier (digit string, raw units). Optional when token_limits or USD thresholds are set. |
+| `delay_max`         | string | No       | Max amount for DELAY tier (digit string, raw units). Optional when token_limits or USD thresholds are set. |
 | `delay_seconds`     | number | No       | Cooldown for DELAY tier (seconds). Min 60, default: 900. |
 | `instant_max_usd`   | number | No       | Max USD amount for INSTANT tier (oracle-based).      |
 | `notify_max_usd`    | number | No       | Max USD amount for NOTIFY tier.                      |
 | `delay_max_usd`     | number | No       | Max USD amount for DELAY tier.                       |
 | `daily_limit_usd`   | number | No       | Cumulative USD spending limit in 24h rolling window. Exceeding escalates to APPROVAL. |
 | `monthly_limit_usd` | number | No       | Cumulative USD spending limit in 30d rolling window. Exceeding escalates to APPROVAL. |
+| `token_limits`      | object | No       | Token-specific spending limits in human-readable units, keyed by CAIP-19 asset identifier. See Token-Specific Limits below. |
 
 **Tier assignment:** Amount <= instant_max -> INSTANT. Amount <= notify_max -> NOTIFY. Amount <= delay_max -> DELAY. Amount > delay_max -> APPROVAL (requires owner approval). USD tiers (if set) are evaluated via price oracle and take precedence over native amount tiers.
 
 **Cumulative limit evaluation:** After per-transaction tier assignment, if `daily_limit_usd` or `monthly_limit_usd` is set, the engine checks rolling-window cumulative USD spending (confirmed + pending reserved amounts). If cumulative + current transaction exceeds the limit, the tier is escalated to APPROVAL regardless of the per-transaction tier. The `TX_APPROVAL_REQUIRED` notification includes a `reason` field (`per_tx`, `cumulative_daily`, or `cumulative_monthly`).
 
+**Token-specific limits (token_limits):**
+
+When `token_limits` is set, the policy engine evaluates transaction amounts against per-token thresholds in human-readable units (e.g., SOL, USDC) instead of raw smallest-unit amounts. Each key is a CAIP-19 asset identifier or native token shorthand.
+
+**Key format:**
+- `"native"` -- native token of the policy's network (only valid when policy has `network` set)
+- `"native:{chain}"` -- native token of a specific chain (e.g., `"native:solana"` for SOL, `"native:ethereum"` for ETH)
+- `"{caip19}"` -- CAIP-19 asset ID for a specific token (e.g., `"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"` for USDC on Solana)
+
+**Matching priority:** exact CAIP-19 asset ID > `native:{chain}` > `native` shorthand > raw field fallback.
+
+**Value format:** Each value is an object with `instant_max`, `notify_max`, `delay_max` as human-readable decimal strings (e.g., `"1.5"` for 1.5 SOL, `"1000"` for 1000 USDC).
+
+**Fallback behavior:** When a transaction's token does not match any `token_limits` key, the engine falls back to raw fields (`instant_max`/`notify_max`/`delay_max`). When raw fields are also absent, the native tier defaults to INSTANT (most permissive), and USD thresholds alone determine the tier.
+
+**Scope:** `token_limits` applies to TRANSFER, TOKEN_TRANSFER, and APPROVE transactions. CONTRACT_CALL and BATCH use raw/USD evaluation only.
+
+**Interaction with USD and cumulative limits:** Per-transaction tier = `max(USD tier, token/native tier)`. Cumulative limits (`daily_limit_usd`, `monthly_limit_usd`) are evaluated independently after per-transaction tier assignment and are unaffected by `token_limits`.
+
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
@@ -266,7 +292,7 @@ Token whitelist for TOKEN_TRANSFER transactions. **Default deny**: tokens not li
 {
   "tokens": [
     {"address": "<mint-or-contract>", "symbol": "USDC", "chain": "solana"},
-    {"address": "<erc20-address>", "symbol": "USDT", "chain": "ethereum"}
+    {"address": "<erc20-address>", "symbol": "USDT", "chain": "ethereum", "assetId": "eip155:1/erc20:<erc20-address>"}
   ]
 }
 ```
@@ -277,6 +303,9 @@ Token whitelist for TOKEN_TRANSFER transactions. **Default deny**: tokens not li
 | `address` | string | Yes      | Token mint (Solana) or contract address (EVM).   |
 | `symbol`  | string | No       | Token symbol for display (e.g., "USDC").         |
 | `chain`   | string | No       | "solana" or "ethereum". For documentation only.  |
+| `assetId` | string | No       | CAIP-19 asset identifier. Enables cross-chain matching. |
+
+**CAIP-19 matching:** When `assetId` is present in both the policy token entry and the transaction's token object, exact CAIP-19 matching is used (highest confidence). When only one side has `assetId`, the daemon extracts and compares addresses. When neither has `assetId`, legacy address-only matching is used. All 4 scenarios are backward compatible.
 
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
@@ -500,12 +529,12 @@ If no policies of a given default-deny type exist for a wallet, the check is ski
 
 ### Allow USDC token transfers
 
-1. Create ALLOWED_TOKENS policy to whitelist USDC:
+1. Create ALLOWED_TOKENS policy to whitelist USDC (with optional CAIP-19 assetId):
 ```bash
 curl -s -X POST http://localhost:3100/v1/policies \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: <password>' \
-  -d '{"walletId":"<uuid>","type":"ALLOWED_TOKENS","rules":{"tokens":[{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","symbol":"USDC"}]}}'
+  -d '{"walletId":"<uuid>","type":"ALLOWED_TOKENS","rules":{"tokens":[{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","symbol":"USDC","assetId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}]}}'
 ```
 
 2. Send TOKEN_TRANSFER (see `transactions.skill.md` for full transaction reference):
@@ -513,7 +542,7 @@ curl -s -X POST http://localhost:3100/v1/policies \
 curl -s -X POST http://localhost:3100/v1/transactions/send \
   -H 'Content-Type: application/json' \
   -H 'X-Master-Password: <password>' \
-  -d '{"type":"TOKEN_TRANSFER","to":"<recipient>","amount":"5000000","token":{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6,"symbol":"USDC"}}'
+  -d '{"type":"TOKEN_TRANSFER","to":"<recipient>","amount":"5000000","token":{"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","decimals":6,"symbol":"USDC","assetId":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}'
 ```
 
 ### Allow Uniswap contract calls
@@ -578,6 +607,19 @@ curl -s -X POST http://localhost:3100/v1/policies \
 
 When cumulative spending exceeds the limit, the transaction is escalated to APPROVAL. Owner can then approve, reject, or increase the limit.
 
+### Set token-specific spending limits
+
+```bash
+# Set per-token limits: 1 SOL instant, 10 SOL notify, 50 SOL delay for native Solana
+# Plus 100 USDC instant, 1000 USDC notify, 10000 USDC delay for USDC
+curl -s -X POST http://localhost:3100/v1/policies \
+  -H 'Content-Type: application/json' \
+  -H 'X-Master-Password: <password>' \
+  -d '{"walletId":"<uuid>","type":"SPENDING_LIMIT","rules":{"token_limits":{"native:solana":{"instant_max":"1","notify_max":"10","delay_max":"50"},"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v":{"instant_max":"100","notify_max":"1000","delay_max":"10000"}},"daily_limit_usd":500}}'
+```
+
+Native SOL transfers of <= 1 SOL are INSTANT. USDC transfers of <= 100 USDC are INSTANT. Both respect the $500/day cumulative limit.
+
 ---
 
 ## 5. Error Reference

package/skills/quickstart.skill.md

@@ -3,7 +3,7 @@ name: "WAIaaS Quickset"
 description: "End-to-end quickset: create wallet, session, check balance, send first transfer"
 category: "api"
 tags: [wallet, blockchain, solana, ethereum, quickset, quickstart, waiass]
-version: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -25,13 +25,13 @@ All endpoints use this base. The daemon runs locally on port 3100 by default.
 
 WAIaaS uses two authentication methods:
 
-| Auth Type | Header | Used For |
-|-----------|--------|----------|
-| **masterAuth** | `X-Master-Password: <password>` | Wallet creation, session creation, wallet listing, token registry, MCP provisioning, admin |
-| **sessionAuth** | `Authorization: Bearer <token>` | Balance queries, transactions, wallet updates/deletion, session renewal |
+| Auth Type | Header | Used For | Who |
+|-----------|--------|----------|-----|
+| **masterAuth** | `X-Master-Password: <password>` | Wallet creation, session creation, policy config, admin | **Operator only** |
+| **sessionAuth** | `Authorization: Bearer <token>` | Balance queries, transactions, wallet info, session renewal | AI agents |
 
-- **masterAuth** is for administrative operations. The master password is set in `config.toml` or via `WAIAAS_SECURITY_MASTER_PASSWORD` env var.
-- **sessionAuth** is for wallet-scoped operations. You get a JWT token by creating a session (Step 3 below). Each session is bound to one wallet.
+- **masterAuth** is for administrative operations performed by the **Operator** via Admin UI or CLI. AI agents must NEVER request or use the master password.
+- **sessionAuth** is for wallet-scoped operations. AI agents operate exclusively with session tokens (Bearer wai_sess_...).
 
 ## Self-Discovery (Recommended First Step)
 
@@ -325,3 +325,31 @@ 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)
+
+## Asset Identification (CAIP-19)
+
+WAIaaS supports CAIP-19 standard asset identifiers for unambiguous cross-chain token identification. When sending token transfers, you can include an optional `assetId` field in the token object:
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "TOKEN_TRANSFER",
+    "to": "9aE476sH92Vz7DMPyq5WLPkrKWivxeuTKEFKd2sZZcde",
+    "amount": "5000000",
+    "token": {
+      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+    }
+  }'
+```
+
+CAIP-19 format: `{chain_id}/{asset_namespace}:{asset_reference}`
+- EVM tokens: `eip155:{chainId}/erc20:{lowercase_address}`
+- Solana tokens: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:{base58_address}`
+- Native assets: `{chain_id}/slip44:{coin_type}` (ETH=60, SOL=501, POL=966)
+
+The `assetId` field is optional and backward compatible. See **transactions.skill.md** section 13 for full CAIP-19 reference.

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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -138,6 +138,7 @@ Parameters:
   - `address` (required): mint address (SPL) or contract address (ERC-20)
   - `decimals` (required): integer, 0-18
   - `symbol` (required): string, 1-10 characters
+  - `assetId` (optional): CAIP-19 asset identifier (e.g., `"eip155:1/erc20:0xa0b8..."`). Cross-validated against `address` when provided.
 - `memo` (optional): string, max 256 characters
 - `network` (optional): target network for this transaction. Defaults to wallet's default network. Must be valid for the wallet's environment.
 
@@ -264,6 +265,7 @@ Parameters:
   - `address` (required): token contract/mint address
   - `decimals` (required): integer, 0-18
   - `symbol` (required): string, 1-10 characters
+  - `assetId` (optional): CAIP-19 asset identifier. Cross-validated against `address` when provided.
 - `amount` (required): string of digits, max approval amount in token's smallest unit
 - `network` (optional): target network for this transaction. Defaults to wallet's default network. Must be valid for the wallet's environment.
 
@@ -719,3 +721,72 @@ curl -s -X POST http://localhost:3100/v1/utils/encode-calldata \
 - Python: `await client.encode_calldata(abi, function_name, args)`
 
 **MCP Tool:** `encode_calldata` with parameters `abi`, `functionName`, `args`
+
+## 13. CAIP-19 Asset Identification
+
+WAIaaS supports [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-19.md) standard asset identifiers for cross-chain token identification. The `assetId` field is an optional addition to token objects in TOKEN_TRANSFER and APPROVE requests.
+
+### Format
+
+```
+{CAIP-2 chain ID}/{asset namespace}:{asset reference}
+```
+
+### Examples by Chain
+
+| Chain | Type | assetId | Description |
+|-------|------|---------|-------------|
+| Ethereum | ERC-20 | `eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48` | USDC on Ethereum Mainnet |
+| Polygon | ERC-20 | `eip155:137/erc20:0x3c499c542cef5e3811e1192ce70d8cc03d5c3359` | USDC on Polygon |
+| Solana | SPL | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | USDC on Solana Mainnet |
+| Ethereum | Native | `eip155:1/slip44:60` | ETH (native) |
+| Solana | Native | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501` | SOL (native) |
+| Polygon | Native | `eip155:137/slip44:966` | POL (native) |
+
+**Important:** EVM addresses in CAIP-19 must be **lowercase** (not checksummed).
+
+### Usage in TOKEN_TRANSFER
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "TOKEN_TRANSFER",
+    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD16",
+    "amount": "5000000",
+    "token": {
+      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+    }
+  }'
+```
+
+### Usage in APPROVE
+
+```bash
+curl -s -X POST http://localhost:3100/v1/transactions/send \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer wai_sess_eyJ...' \
+  -d '{
+    "type": "APPROVE",
+    "spender": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
+    "token": {
+      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      "decimals": 6,
+      "symbol": "USDC",
+      "assetId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
+    },
+    "amount": "1000000000"
+  }'
+```
+
+### Cross-Validation
+
+When both `address` and `assetId` are provided, the daemon extracts the address from the CAIP-19 URI and validates it matches `token.address` (case-insensitive for EVM). If they don't match, the request is rejected with `ACTION_VALIDATION_FAILED`.
+
+### Backward Compatibility
+
+`assetId` is fully optional. Existing requests without `assetId` continue to work unchanged. You can gradually adopt CAIP-19 identifiers without breaking existing integrations.

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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]
@@ -15,13 +15,13 @@ Complete reference for wallet CRUD operations, asset queries, session management
 
 ## Permissions
 
-### Agent (sessionAuth)
+### Agent (sessionAuth) — AI agents use these
 - Query wallet balance, assets, address, nonce, and info
 - Send transactions via transaction endpoints (see transactions.skill.md)
 - Get registered tokens via `GET /v1/tokens`
 - Get applied policies via `GET /v1/policies`
 
-### Admin (masterAuth)
+### Operator only (masterAuth) — NOT for AI agents
 - Create/list/update/delete wallets
 - Create/list/delete sessions, manage session-wallet links
 - Create/delete MCP tokens
@@ -29,6 +29,8 @@ Complete reference for wallet CRUD operations, asset queries, session management
 - Set owner addresses, default network, additional networks
 - WalletConnect pairing management
 
+> AI agents must NEVER request the master password. Use only your session token.
+
 ## 1. Wallet CRUD
 
 All wallet CRUD endpoints require **masterAuth** (`X-Master-Password` header), except `PUT /v1/wallets/{id}` and `DELETE /v1/wallets/{id}` which require **sessionAuth** (`Authorization: Bearer <token>`).

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: "2.6.0-rc"
+version: "2.6.0-rc.2"
 dispatch:
   kind: "tool"
   allowedCommands: ["curl"]