diff --git a/skills/SKILL.md b/skills/SKILL.md deleted file mode 100644 index f3f04b82..00000000 --- a/skills/SKILL.md +++ /dev/null @@ -1,365 +0,0 @@ ---- -name: aitbc-operations -description: Complete AITBC software operations - marketplace (offers, deals, bids, orders), messaging, agent registration, coordinator, testing patterns. All operational information verified. Ships with AITBC software. -category: software-development ---- - -# AITBC Software Operations Skill - -Complete guide for Hermes agent to interact with AITBC (Agent Training Blockchain) software - marketplace, messaging, agent operations, testing patterns. **This skill ships with AITBC software repository.** - -## Trigger Conditions - -Load this skill when: -- User asks to "make deals, offers, trades, bids, msg" with AITBC software -- Need to interact with AITBC marketplace, coordinator, or messaging -- Working with aitbc1 node or localhost AITBC instance -- User mentions "aitbc software", "marketplace", "offers", "deals", "bids", "messages" -- Need to register agents or use coordinator -- Need to test AITBC operations or validate scenarios - -## Prerequisites - -- AITBC software installed at `/opt/aitbc` (cloned from repo) -- Wallet exists in `/var/lib/aitbc/keystore/` -- Password file at `/var/lib/aitbc/keystore/.genesis_password` -- Services running (verify: `systemctl status aitbc-marketplace`) - -## Step-by-Step Instructions - -### 1. CREATE OFFER (SELL) - Marketplace - -**CLI Command (localhost):** -```bash -cd /opt/aitbc -python3 cli/unified_cli.py market create \ - --wallet \ - --type \ - --price \ - --description -``` - -**CLI Command (aitbc1 node):** -```bash -cd /opt/aitbc -python3 cli/unified_cli.py market create \ - --wallet \ - --type \ - --price \ - --description \ - --marketplace-url http://aitbc1:8102 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py market create \ - --wallet hermes-final \ - --type "complete-demo" \ - --price 999 \ - --description "Full demo" \ - --marketplace-url http://aitbc1:8102 -``` - -**Result:** Returns offer ID (e.g., `0423942b3d4f4ec88968adc52fe4ba36`), provider, price, status (open) - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers` - ---- - -### 2. LIST OFFERS - Browse Marketplace - -**CLI Command:** -```bash -python3 cli/unified_cli.py market list --marketplace-url http://aitbc1:8102 -``` - -**API Endpoint:** `GET http://aitbc1:8102/v1/marketplace/offers` - -**Result:** JSON array of all offers (5+ verified working) - ---- - -### 3. BUY/DEAL (BID) - Execute Deals - -**CLI Command:** -```bash -python3 cli/unified_cli.py market buy \ - --item \ - --wallet \ - --password "$(cat /var/lib/aitbc/keystore/.genesis_password)" \ - --marketplace-url http://aitbc1:8102 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py market buy \ - --item "0423942b3d4f4ec88968adc52fe4ba36" \ - --wallet hermes-final \ - --password "$(cat /var/lib/aitbc/keystore/.genesis_password)" \ - --marketplace-url http://aitbc1:8102 -``` - -**Result:** Bid ID (e.g., `dc74b16ab952432e8cb9ff7a3f97df3d`), status (pending), message - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers/{offer_id}/book` - ---- - -### 4. LIST BIDS/ORDERS - Track Trades - -**CLI Command (Orders):** -```bash -python3 cli/unified_cli.py market orders \ - --wallet \ - --marketplace-url http://aitbc1:8102 -``` - -**API Endpoints:** -- Bids: `GET http://aitbc1:8102/v1/marketplace/bids` -- Orders: `GET http://aitbc1:8102/v1/marketplace/orders` - -**Result:** JSON array of bids/orders (2+ verified working) - ---- - -### 5. MESSAGES (MSG) - Forum Operations - -**CLI Commands:** -```bash -# List topics -python3 cli/unified_cli.py messaging topics --rpc-url http://aitbc1:8006 - -# Create topic -python3 cli/unified_cli.py messaging create-topic \ - --title "" \ - --content "<content>" \ - --rpc-url http://aitbc1:8006 - -# Post message to topic -python3 cli/unified_cli.py messaging post \ - --topic-id <topic_id> \ - --content "<message>" \ - --rpc-url http://aitbc1:8006 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py messaging topics --rpc-url http://aitbc1:8006 -``` - -**Result:** Topic ID (e.g., `topic_a89f0525b357a8aa`), title, total topics - -**API Endpoint:** `http://aitbc1:8006` (forum service) - -**Note:** Messaging requires agent registration first (see Step 6) - ---- - -### 6. AGENT REGISTRATION - Coordinator - -**API Command:** -```bash -curl -s -X POST http://aitbc1:9001/agents/register \ - -H "Content-Type: application/json" \ - -d '{ - "agent_id": "<agent_id>", - "agent_type": "worker", - "endpoint": "http://<host>:<port>", - "capabilities": ["marketplace", "messaging"] - }' -``` - -**Example (Verified):** -```bash -curl -s -X POST http://aitbc1:9001/agents/register \ - -H "Content-Type: application/json" \ - -d '{"agent_id":"hermes-aitbc1","agent_type":"worker","endpoint":"http://localhost:9997","capabilities":["marketplace","messaging"]}' -``` - -**Result:** `{"status":"success","message":"Agent X registered successfully",...}` - -**API Endpoint:** `POST http://aitbc1:9001/agents/register` - ---- - -## Authentication Requirements - -### Marketplace Operations: -- **Requires:** Wallet + Password -- **Wallet Location:** `/var/lib/aitbc/keystore/` -- **Password Location:** `/var/lib/aitbc/keystore/.genesis_password` - -### Messaging Operations: -- **Requires:** Agent registration with blockchain node -- **Registration:** Via coordinator `http://aitbc1:9001/agents/register` - -### Agent Operations: -- **Requires:** Agent ID + endpoint + capabilities -- **Coordinator:** `http://aitbc1:9001` - ---- - -## Cross-Node Operations - -### Key URLs (Use Hostname, NOT IP): -- **aitbc1 Marketplace:** `http://aitbc1:8102` (NOT `10.1.223.93:8102`) -- **aitbc1 Coordinator:** `http://aitbc1:9001` -- **aitbc1 Messaging:** `http://aitbc1:8006` -- **Redis (Cross-node Agent Discovery):** `10.1.223.93:6379` - -### Verified Cross-Node Operations: -- ✅ Topics created on localhost visible on aitbc1 (and vice versa) -- ✅ Agent registration on aitbc1 coordinator working -- ✅ Cross-node agent discovery via shared Redis - ---- - -## Testing Patterns - -### Verify Service Health -```bash -# Check all AITBC services -systemctl list-units --type=service | grep -E "aitbc|blockchain|coordinator" - -# Health checks -curl -s http://localhost:8006/health | jq . # Blockchain node -curl -s http://localhost:9001/health | jq . # Coordinator -curl -s http://localhost:8102/health | jq . # Marketplace -curl -s http://localhost:8101/health | jq . # GPU service -``` - -### Verify User Claims (Mandatory) -When user reports "FIXED" or "All issues resolved": -1. **ALWAYS test immediately** - don't trust the claim -2. **Pull latest code:** `cd /opt/aitbc && git pull origin main && git log --oneline -3` -3. **Restart service:** `ssh aitbc1 "sudo systemctl restart aitbc-marketplace.service"` -4. **Wait and test:** `sleep 3 && curl -s http://aitbc1:8102/health` -5. **Run actual test:** Execute the CLI command that was failing -6. **Check logs if still broken:** `ssh aitbc1 "journalctl -u aitbc-marketplace --since '1 minute ago'"` - -### CLI Command Discovery -```bash -# Check available commands -python3 /opt/aitbc/cli/unified_cli.py --help - -# Check subcommand help -python3 /opt/aitbc/cli/unified_cli.py market --help -python3 /opt/aitbc/cli/unified_cli.py messaging --help -``` - ---- - -## Pitfalls & Common Errors - -### 1. Using IP Instead of Hostname -**Error:** Connection timeout or failure -**Fix:** Use `aitbc1:8102`, NOT `10.1.223.93:8102` - -### 2. BUY Command Using Item Name Instead of Offer ID -**Error:** 404 or "Purchase failed" -**Fix:** Use full offer ID (e.g., `0423942b3d4f4ec88968adc52fe4ba36`), not item name - -### 3. Messaging Without Agent Registration -**Error:** `Invalid agent credentials` or `INVALID_AGENT` -**Fix:** Register agent first via `POST http://aitbc1:9001/agents/register` - -### 4. CLI Wrong Parameter Names -**Error:** `unrecognized arguments: --marketplace-url` -**Fix:** Check `--help` for correct parameter names per command - -### 5. Forgetting Wallet Password -**Error:** Authentication failure -**Fix:** Use `cat /var/lib/aitbc/keystore/.genesis_password` for password - -### 6. Marketplace CLI Parameter Names -**Error:** `unrecognized arguments: --item-type` -**Fix:** Use `--type` for item type, `--item` is not a valid arg for create -**Error:** `unrecognized arguments: --password-file` -**Fix:** Use `--password "$(cat /path/to/password-file)"` to inject credentials - -### 7. Service Restart Required After Code Changes -**Error:** New routes or endpoints return 404 after git pull -**Fix:** Restart service after pulling commits with route changes: `systemctl restart aitbc-agent-coordinator` - -### 8. Backend Router Incomplete -**Error:** CLI expects 6 endpoints but router only implements 1 -**Fix:** Check router file for ALL expected endpoints using `grep "@router\." <router.py>`, compare with CLI code, report missing endpoints - -### 9. Missing Imports in CLI Command Files -**Error:** `NameError: name 'httpx' is not defined` at runtime -**Fix:** Check for missing imports (httpx, json) in command files, add to imports section - -### 10. URL Configuration Mismatch -**Error:** CLI calls wrong backend service URL -**Fix:** Verify which port has the endpoint, check config.py for URL defaults - ---- - -## Verification Checklist - -Before using this skill, verify: -- [ ] AITBC repo cloned: `ls /opt/aitbc` -- [ ] aitbc1 marketplace running: `curl -s http://aitbc1:8102/health` -- [ ] Wallet exists: `ls /var/lib/aitbc/keystore/` -- [ ] Password file readable: `cat /var/lib/aitbc/keystore/.genesis_password` -- [ ] Coordinator accessible: `curl -s http://aitbc1:9001/health` -- [ ] Can create offer (test with `--price 100`) -- [ ] Can list offers (see 1+ offers) -- [ ] Can buy offer (creates bid with pending status) - ---- - -## Operations Matrix (All Verified) - -| Operation | aitbc1 Node | localhost | Status | -|-----------|--------------|-----------|--------| -| CREATE OFFER (SELL) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST OFFERS | ✅ WORKS | ✅ WORKS | BOTH WORK | -| BUY/DEAL (BID) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST BIDS | ✅ WORKS | ✅ WORKS | BOTH WORK | -| ORDERS CLI | ✅ WORKS | ✅ WORKS | BOTH WORK | -| MESSAGES (MSG) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| AGENT REGISTER | ✅ WORKS | ✅ WORKS | BOTH WORK | - ---- - -## Quick Reference - -```bash -# SELL (Create Offer) -market create --wallet X --type Y --price Z --marketplace-url http://aitbc1:8102 - -# LIST Offers -market list --marketplace-url http://aitbc1:8102 - -# BUY (Create Bid) -market buy --item <offer_id> --wallet X --password Y --marketplace-url http://aitbc1:8102 - -# LIST Bids/Orders -market orders --wallet X --marketplace-url http://aitbc1:8102 - -# MESSAGES -messaging topics --rpc-url http://aitbc1:8006 - -# AGENT REGISTER -curl -X POST http://aitbc1:9001/agents/register -H "Content-Type: application/json" -d '{"agent_id":"X","agent_type":"worker",...}' -``` - ---- - -## Status - -**AITBC Software: FULLY OPERATIONAL** - -- 24 services running -- All marketplace operations verified working -- Cross-node operations verified -- Production-ready system -- **This skill ships with AITBC software repository** - ---- - -**Generated by:** Hermes Instructor (localhost) -**Date:** 2026-05-08 -**Purpose:** Single comprehensive skill shipping with AITBC software -**Location:** `/opt/aitbc/skills/aitbc-operations/SKILL.md` diff --git a/skills/aitbc-ai-operations.md b/skills/aitbc-ai-operations.md new file mode 100644 index 00000000..79a00275 --- /dev/null +++ b/skills/aitbc-ai-operations.md @@ -0,0 +1,93 @@ +# AITBC AI Operations Skill + +## Trigger Conditions +Activate when user requests AI operations: job submission, status monitoring, results retrieval, resource allocation testing, or AI job monitoring. + +## Purpose +Submit, monitor, and optimize AITBC AI jobs with deterministic performance tracking and resource management. + +## Prerequisites +- AITBC CLI accessible at `/opt/aitbc/aitbc-cli` +- AI services operational (Ollama, coordinator, exchange) +- Wallet with sufficient balance for job payments +- Default test wallet: "genesis" (password from `/var/lib/aitbc/keystore/.genesis_password`) +- Resource allocation system functional + +## Operations + +### Submit AI Job +```bash +./aitbc-cli ai-ops submit \ + --wallet <wallet_name> \ + --type <job_type> \ + --prompt <prompt> \ + --payment <payment> \ + --password <password> \ + --rpc-url http://localhost:8006 +``` + +### Check AI Job Status +```bash +./aitbc-cli ai-ops status --job-id <job_id> --rpc-url http://localhost:8006 +``` + +### Job Types +- `inference` - AI model inference +- `training` - AI model training +- `multimodal` - Multi-modal AI processing +- `ollama` - Ollama-based operations +- `streaming` - Streaming AI responses +- `monitoring` - AI system monitoring + +### Resource Allocation +```bash +# Allocate resources for AI job +./aitbc-cli resource allocate \ + --agent-id <agent_id> \ + --gpu <gpu_count> \ + --memory <memory_mb> \ + --duration <seconds> +``` + +### Check Resource Status +```bash +./aitbc-cli resource status +``` + +### List Available Resources +```bash +./aitbc-cli resource list +``` + +## Common Pitfalls + +1. **Insufficient Wallet Balance:** Check wallet balance before job submission +2. **Invalid Job Type:** Ensure job type is valid (inference, training, multimodal, ollama, streaming, monitoring) +3. **Service Unavailability:** Verify Ollama, coordinator, and exchange services are running +4. **Resource Allocation Failures:** Check GPU and memory availability +5. **Job Timeout:** Monitor job progress and adjust timeout if needed +6. **Payment Issues:** Ensure payment amount covers job costs +7. **Invalid Job ID:** Verify job ID when checking status + +## Verification Checklist +- [ ] Job submission returns valid job ID +- [ ] Job status shows correct state (submitted, processing, completed, failed) +- [ ] Resource allocation succeeds +- [ ] Job completes within expected timeframe +- [ ] Results retrieved successfully +- [ ] Payment processed correctly + +## GPU Provider Testing +```bash +# Test GPU inference +python3 cli/unified_cli.py ollama gpu-test \ + --wallet genesis \ + --model llama2 \ + --prompt "test prompt" \ + --marketplace-url http://aitbc1:8102 +``` + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **Module:** `cli/unified_cli.py` is a module within the CLI tool for marketplace and GPU operations +- **Note:** For GPU provider operations, prefer `python3 cli/unified_cli.py` (verified working with 7 bugs fixed) diff --git a/skills/aitbc-basic-operations.md b/skills/aitbc-basic-operations.md new file mode 100644 index 00000000..be618bdb --- /dev/null +++ b/skills/aitbc-basic-operations.md @@ -0,0 +1,82 @@ +# AITBC Basic Operations Skill + +## Trigger Conditions +Activate when user requests basic AITBC operations: CLI validation, wallet operations, blockchain status, service health checks, or system verification. + +## Purpose +Test and validate AITBC basic CLI functionality, core blockchain operations, wallet operations, and service connectivity. + +## Prerequisites +- AITBC CLI accessible at `/opt/aitbc/aitbc-cli` +- Python venv activated for CLI operations +- Services running on ports 8011 (coordinator), 8001 (exchange), 8006 (blockchain RPC) +- Working directory: `/opt/aitbc` +- Default test wallet: "genesis" with password from `/var/lib/aitbc/keystore/.genesis_password` + +## Operations + +### CLI Validation +```bash +# Check CLI version +./aitbc-cli --version + +# Check CLI help +./aitbc-cli --help +``` + +### Wallet Operations +```bash +# List wallets +./aitbc-cli list + +# Check wallet balance +./aitbc-cli balance --name genesis + +# Create test wallet +./aitbc-cli create --name test-wallet --password "test123" +``` + +### Blockchain Operations +```bash +# Get blockchain info +./aitbc-cli chain + +# Get network status +./aitbc-cli network + +# Get analytics +./aitbc-cli analytics --type blocks --limit 10 +``` + +### Service Health Checks +```bash +# Check coordinator API (port 8011) +curl http://localhost:8011/health + +# Check exchange API (port 8001) +curl http://localhost:8001/health + +# Check blockchain RPC (port 8006) +curl http://localhost:8006/health +``` + +## Common Pitfalls + +1. **CLI Not Found:** Ensure `/opt/aitbc/aitbc-cli` exists and is executable +2. **Wallet Not Found:** Check wallet name spelling, verify keystore directory at `/var/lib/aitbc/keystore/` +3. **Service Unreachable:** Verify services are running: `systemctl status aitbc-*` +4. **Port Mismatch:** Coordinator API is on port 8011 (not 8000) +5. **Password Required:** Use password from `/var/lib/aitbc/keystore/.genesis_password` for genesis wallet + +## Verification Checklist +- [ ] CLI responds to `--version` and `--help` +- [ ] Wallet list shows available wallets +- [ ] Balance check returns valid AIT amount +- [ ] Blockchain info shows current height and hash +- [ ] Network status shows peer connections +- [ ] All three services (coordinator, exchange, blockchain) return healthy status + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **Module:** `cli/unified_cli.py` is a module within the CLI tool for marketplace and messaging operations +- **Note:** For marketplace operations, prefer `python3 cli/unified_cli.py` (verified working with 7 bugs fixed) diff --git a/skills/aitbc-blockchain-troubleshooting.md b/skills/aitbc-blockchain-troubleshooting.md new file mode 100644 index 00000000..1c93101b --- /dev/null +++ b/skills/aitbc-blockchain-troubleshooting.md @@ -0,0 +1,152 @@ +# AITBC Blockchain Troubleshooting Skill + +## Trigger Conditions +Activate when user requests blockchain troubleshooting: sync issues, P2P problems, service failures, data corruption, or blockchain recovery operations. + +## Purpose +Diagnose and troubleshoot AITBC blockchain issues including synchronization failures, P2P network problems, service failures, and data corruption. + +## Prerequisites +- SSH access to all nodes (aitbc, aitbc1, gitea-runner) +- Systemd services operational or accessible for debugging +- Log access at `/var/log/aitbc/` +- Data directory at `/var/lib/aitbc/` +- CLI accessible at `/opt/aitbc/aitbc-cli` + +## Operations + +### 1. Initial Diagnosis +```bash +# Check service status on all nodes +systemctl status aitbc-blockchain-node.service +ssh aitbc1 'systemctl status aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl status aitbc-blockchain-node.service' + +# Check blockchain RPC health +curl http://localhost:8006/health +curl http://10.1.223.40:8006/health +curl http://aitbc1:8006/health + +# Check P2P network status +netstat -an | grep 7070 +ssh aitbc1 'netstat -an | grep 7070' +``` + +### 2. Blockchain Sync Issues +```bash +# Check blockchain height on all nodes +./aitbc-cli chain +ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli chain' +ssh gitea-runner 'cd /opt/aitbc && ./aitbc-cli chain' + +# Check mempool status +./aitbc-cli mempool status +ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli mempool status' + +# Check P2P connections +./aitbc-cli network +ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli network' +``` + +### 3. P2P Network Problems +```bash +# Check P2P node IDs +cat /etc/aitbc/.env | grep p2p_node_id +ssh aitbc1 'cat /etc/aitbc/.env | grep p2p_node_id' + +# Generate unique node IDs if duplicates found +/opt/aitbc/scripts/utils/generate_unique_node_ids.py + +# Restart blockchain services +systemctl restart aitbc-blockchain-p2p.service +ssh aitbc1 'systemctl restart aitbc-blockchain-p2p.service' +``` + +### 4. Service Failures +```bash +# Check service logs +journalctl -u aitbc-blockchain-node.service -n 100 +journalctl -u aitbc-blockchain-p2p.service -n 100 +ssh aitbc1 'journalctl -u aitbc-blockchain-node.service -n 100' + +# Check application logs +tail -f /var/log/aitbc/blockchain-node.log +tail -f /var/log/aitbc/blockchain-p2p.log +ssh aitbc1 'tail -f /var/log/aitbc/blockchain-node.log' +``` + +### 5. Data Corruption +```bash +# Check database integrity +sqlite3 /var/lib/aitbc/data/blockchain.db "PRAGMA integrity_check;" + +# Check CoW status (Btrfs) +lsattr /var/lib/aitbc + +# Disable CoW if enabled +chattr +C /var/lib/aitbc + +# Enable WAL mode +sqlite3 /var/lib/aitbc/data/blockchain.db "PRAGMA journal_mode=WAL;" +``` + +### 6. Recovery Operations +```bash +# Stop blockchain services +systemctl stop aitbc-blockchain-node.service aitbc-blockchain-p2p.service +ssh aitbc1 'systemctl stop aitbc-blockchain-node.service aitbc-blockchain-p2p.service' + +# Backup current data +cp -r /var/lib/aitbc/data /var/lib/aitbc/data.backup + +# Restore from backup if needed +systemctl stop aitbc-blockchain-node.service +rm -rf /var/lib/aitbc/data/* +cp -r /var/lib/aitbc/data.backup/* /var/lib/aitbc/data/ +systemctl start aitbc-blockchain-node.service + +# Restart services +systemctl start aitbc-blockchain-node.service aitbc-blockchain-p2p.service +ssh aitbc1 'systemctl start aitbc-blockchain-node.service aitbc-blockchain-p2p.service' +``` + +### 7. Communication Test +```bash +# Run full communication test +./scripts/blockchain-communication-test.sh --full --debug + +# Verify all services are healthy +curl http://localhost:8006/health +curl http://aitbc1:8006/health +curl http://10.1.223.40:8001/health +curl http://10.1.223.40:8011/health + +# Check blockchain sync +NODE_URL=http://10.1.223.40:8006 ./aitbc-cli blockchain height +NODE_URL=http://aitbc1:8006 ./aitbc-cli blockchain height +``` + +## Common Pitfalls + +1. **Duplicate P2P Node IDs:** Check for duplicate p2p_node_id in `/etc/aitbc/.env` - generate unique IDs +2. **Btrfs CoW Corruption:** Disable CoW on `/var/lib/aitbc` with `chattr +C` +3. **SQLite Corruption:** Enable WAL mode and check database integrity +4. **Port Mismatches:** Coordinator API is on port 8011 (not 8000) +5. **Service Start Order:** Ensure P2P service starts before blockchain-node service +6. **Network Connectivity:** Verify P2P port 7070 is open and accessible +7. **Data Directory Permissions:** Ensure proper permissions on `/var/lib/aitbc/data` + +## Verification Checklist +- [ ] All blockchain services running +- [ ] Blockchain heights match across nodes +- [ ] P2P connections established (port 7070) +- [ ] RPC endpoints responding (port 8006) +- [ ] No duplicate P2P node IDs +- [ ] Database integrity check passes +- [ ] CoW disabled on data directory +- [ ] WAL mode enabled for database + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **RPC URL:** Default is `http://localhost:8006` +- **Coordinator API:** Port 8011 (not 8000) diff --git a/skills/aitbc-cli/SKILL.md b/skills/aitbc-cli/SKILL.md deleted file mode 100644 index 05de8c3b..00000000 --- a/skills/aitbc-cli/SKILL.md +++ /dev/null @@ -1,617 +0,0 @@ ---- -name: aitbc-cli -description: Complete guide for using the AITBC CLI tool - wallet management, transactions, blockchain analytics, marketplace, AI jobs, mining, agent operations, simulations -category: software-development ---- - -# AITBC CLI Tool Skill - -Complete guide for Hermes agent to use the AITBC CLI tool (`/opt/aitbc/aitbc-cli`) for blockchain operations, wallet management, marketplace, AI jobs, mining, and simulations. **This skill ships with AITBC software repository.** - -## Trigger Conditions - -Load this skill when: -- User asks to use "aitbc-cli" or "AITBC CLI" -- Need to manage wallets (create, import, export, delete, rename, list) -- Need to send transactions or check balances -- Need blockchain analytics or network status -- Need marketplace operations (listings, create, buy) -- Need AI compute job operations -- Need mining operations (start, stop, status) -- Need agent operations (create, execute, list, message) -- Need to run simulations (blockchain, wallets, price, network, AI jobs) - -## Prerequisites - -- AITBC software installed at `/opt/aitbc` -- Python 3.13+ with required dependencies -- Blockchain RPC service running (default: `http://localhost:8006`) -- Wallet keystore directory: `/var/lib/aitbc/keystore/` - -## CLI Location - -**Main CLI:** `/opt/aitbc/aitbc-cli` - -**Usage:** -```bash -cd /opt/aitbc -./aitbc-cli [command] [options] -``` - -## Step-by-Step Instructions - -### 1. Wallet Management - -#### Create Wallet -```bash -./aitbc-cli create --name <wallet_name> --password <password> -``` - -**Example:** -```bash -./aitbc-cli create --name my-wallet --password "securepassword123" -``` - -**Result:** Creates wallet with Ed25519 keypair, AES-256-GCM encryption, returns address - -#### Import Wallet -```bash -./aitbc-cli import --name <wallet_name> --private-key <hex_key> --password <password> -``` - -**Example:** -```bash -./aitbc-cli import --name imported-wallet --private-key "abc123..." --password "securepassword123" -``` - -#### Export Wallet (Private Key) -```bash -./aitbc-cli export --name <wallet_name> --password <password> -``` - -#### Delete Wallet -```bash -./aitbc-cli delete --name <wallet_name> -``` - -#### Rename Wallet -```bash -./aitbc-cli rename --old <old_name> --new <new_name> -``` - -#### List Wallets -```bash -./aitbc-cli list --format [table|json] -``` - -**Result:** Lists all wallets from keystore or wallet daemon - ---- - -### 2. Transaction Operations - -#### Send Transaction -```bash -./aitbc-cli send \ - --from <wallet_name> \ - --to <recipient_address> \ - --amount <amount> \ - --fee <fee> \ - --password <password> \ - --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli send \ - --from my-wallet \ - --to ait1abc123... \ - --amount 100.0 \ - --fee 10.0 \ - --password "securepassword123" \ - --rpc-url http://localhost:8006 -``` - -**Result:** Returns transaction hash - -#### Check Balance -```bash -./aitbc-cli balance --name <wallet_name> --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli balance --name my-wallet --rpc-url http://localhost:8006 -``` - -**Result:** Returns balance, nonce, address - -#### Get Transaction History -```bash -./aitbc-cli transactions --name <wallet_name> --limit <limit> --format [table|json] --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli transactions --name my-wallet --limit 10 --format table --rpc-url http://localhost:8006 -``` - ---- - -### 3. Blockchain Analytics - -#### Get Chain Information -```bash -./aitbc-cli chain --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli chain --rpc-url http://localhost:8006 -``` - -**Result:** Chain ID, height, hash, timestamp, proposer ID, supported chains - -#### Get Network Status -```bash -./aitbc-cli network --rpc-url <rpc_url> -``` - -**Result:** Head block information, network health - -#### Blockchain Analytics -```bash -./aitbc-cli analytics --type [blocks|supply|accounts] --limit <limit> --rpc-url <rpc_url> -``` - -**Types:** -- `blocks`: Recent blocks analytics -- `supply`: Total supply information -- `accounts`: Account statistics - -**Example:** -```bash -./aitbc-cli analytics --type blocks --limit 10 --rpc-url http://localhost:8006 -``` - ---- - -### 4. Mining Operations - -#### Start Mining -```bash -./aitbc-cli mine start --wallet <wallet_name> --threads <threads> --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli mine start --wallet my-wallet --threads 1 --rpc-url http://localhost:8006 -``` - -**Result:** Mining started with specified wallet - -#### Stop Mining -```bash -./aitbc-cli mine stop --rpc-url <rpc_url> -``` - -#### Get Mining Status -```bash -./aitbc-cli mine status --rpc-url <rpc_url> -``` - -**Result:** Mining active status, current height, blocks mined, rewards earned - ---- - -### 5. Marketplace Operations - -#### List Marketplace Items -```bash -./aitbc-cli marketplace --action list --rpc-url <rpc_url> -``` - -**Result:** List of available marketplace items - -#### Create Marketplace Listing -```bash -./aitbc-cli marketplace \ - --action create \ - --name <item_name> \ - --price <price> \ - --description <description> \ - --wallet <wallet_name> \ - --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli marketplace \ - --action create \ - --name "AI Compute Hour" \ - --price 100 \ - --description "GPU compute for AI training" \ - --wallet my-wallet \ - --rpc-url http://localhost:8006 -``` - ---- - -### 6. AI Compute Operations - -#### Submit AI Job -```bash -./aitbc-cli ai-ops submit \ - --wallet <wallet_name> \ - --type <job_type> \ - --prompt <prompt> \ - --payment <payment> \ - --password <password> \ - --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli ai-ops submit \ - --wallet my-wallet \ - --type "inference" \ - --prompt "Analyze this data" \ - --payment 50 \ - --password "securepassword123" \ - --rpc-url http://localhost:8006 -``` - -**Result:** Job ID, estimated time, payment amount - -#### Check AI Job Status -```bash -./aitbc-cli ai-ops status --job-id <job_id> --rpc-url <rpc_url> -``` - ---- - -### 7. Agent Operations - -#### Create Agent -```bash -./aitbc-cli agent create \ - --name <agent_name> \ - --verification <basic|advanced> \ - --max-execution-time <seconds> \ - --max-cost-budget <amount> -``` - -#### Execute Agent -```bash -./aitbc-cli agent execute \ - --name <agent_name> \ - --priority [low|medium|high] -``` - -#### List Agents -```bash -./aitbc-cli agent list --status [active|completed|failed] -``` - -**Note:** Uses coordinator API at `http://localhost:9001` for real agent discovery - -#### Send Message to Agent -```bash -./aitbc-cli agent message \ - --agent <agent_address> \ - --message <message_content> \ - --wallet <wallet_name> \ - --password <password> \ - --rpc-url <rpc_url> -``` - -**Example:** -```bash -./aitbc-cli agent message \ - --agent ait1abc123... \ - --message "Hello agent" \ - --wallet my-wallet \ - --password "securepassword123" \ - --rpc-url http://localhost:8006 -``` - -**Result:** Message sent via blockchain transaction, returns transaction hash - -#### Retrieve Agent Messages -```bash -./aitbc-cli agent messages --agent <agent_address> --rpc-url <rpc_url> -``` - -**Result:** Lists all messages sent to the agent from blockchain - ---- - -### 8. Hermes Training Operations - -#### Deploy Hermes Agent -```bash -./aitbc-cli hermes deploy --environment [dev|prod] -``` - -#### Monitor Hermes Agent -```bash -./aitbc-cli hermes monitor --agent-id <agent_id> --metrics [all|performance|cost] -``` - -#### Train Agent -```bash -./aitbc-cli hermes train \ - --train-action agent \ - --agent-id <agent_id> \ - --stage <stage_name> \ - --training-data <training_data_file> -``` - -**Example:** -```bash -./aitbc-cli hermes train \ - --train-action agent \ - --agent-id hermes-001 \ - --stage stage1_foundation \ - --training-data /opt/aitbc/docs/agent-training/stage1_foundation.json -``` - -**Note:** Executes training operations via hermes agent with allowlist enabled - ---- - -### 9. Workflow Operations - -#### Create Workflow -```bash -./aitbc-cli workflow create --name <workflow_name> --template [custom|standard] -``` - -#### Run Workflow -```bash -./aitbc-cli workflow run --name <workflow_name> --async-exec -``` - ---- - -### 10. Resource Operations - -#### Check Resource Status -```bash -./aitbc-cli resource status --type [all|cpu|memory|storage] -``` - -#### Allocate Resources -```bash -./aitbc-cli resource allocate \ - --agent-id <agent_id> \ - --cpu <cores> \ - --memory <gb> \ - --duration <minutes> -``` - -#### Optimize Resources -```bash -./aitbc-cli resource optimize --target [all|cpu|memory] --agent-id <agent_id> -``` - -#### Benchmark Resources -```bash -./aitbc-cli resource benchmark --type [all|cpu|memory|network] -``` - ---- - -### 11. Simulation Operations - -#### Simulate Blockchain -```bash -./aitbc-cli simulate blockchain \ - --blocks <number> \ - --transactions <per_block> \ - --delay <seconds> -``` - -**Example:** -```bash -./aitbc-cli simulate blockchain --blocks 10 --transactions 5 --delay 0.5 -``` - -**Result:** Simulates block production with transactions, shows statistics - -#### Simulate Wallets -```bash -./aitbc-cli simulate wallets \ - --wallets <number> \ - --balance <initial_balance> \ - --transactions <number> \ - --amount-range <min-max> -``` - -**Example:** -```bash -./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20 --amount-range 1-100 -``` - -#### Simulate Price -```bash -./aitbc-cli simulate price \ - --price <starting_price> \ - --volatility <percentage> \ - --timesteps <number> \ - --delay <seconds> -``` - -**Example:** -```bash -./aitbc-cli simulate price --price 100.0 --volatility 0.05 --timesteps 50 --delay 0.1 -``` - -#### Simulate Network -```bash -./aitbc-cli simulate network \ - --nodes <number> \ - --network-delay <seconds> \ - --failure-rate <percentage> -``` - -**Example:** -```bash -./aitbc-cli simulate network --nodes 10 --network-delay 0.5 --failure-rate 0.1 -``` - -#### Simulate AI Jobs -```bash -./aitbc-cli simulate ai-jobs \ - --jobs <number> \ - --models <model_list> \ - --duration-range <min-max_seconds> -``` - -**Example:** -```bash -./aitbc-cli simulate ai-jobs --jobs 20 --models "llama2,mistral,gemma" --duration-range 30-300 -``` - ---- - -## Default Configuration - -**Default RPC URL:** `http://localhost:8006` - -**Default Keystore Directory:** `/var/lib/aitbc/keystore/` - -**Default Wallet Daemon URL:** `http://localhost:8003` - -**CLI Version:** 2.1.0 - ---- - -## Authentication - -### Wallet Password -- Required for: create, import, export, send, ai-ops submit, agent message -- Can be provided via `--password` or `--password-file` -- Genesis password location: `/var/lib/aitbc/keystore/.genesis_password` - -### Password File Usage -```bash -# Using password file -./aitbc-cli send --from my-wallet --to ait1abc... --amount 100 --password-file /var/lib/aitbc/keystore/.genesis_password -``` - ---- - -## Chain ID Handling - -**Auto-Detection:** CLI automatically detects chain ID from blockchain RPC health endpoint - -**Override:** Use `--chain-id` to override auto-detection -```bash -./aitbc-cli --chain-id ait-mainnet [command] -``` - ---- - -## Pitfalls & Common Errors - -### 1. Wallet Not Found -**Error:** `Wallet 'wallet_name' not found` -**Fix:** Check wallet name spelling, verify keystore directory - -### 2. Invalid Password -**Error:** `Error decrypting wallet` -**Fix:** Verify password, check password file permissions - -### 3. Invalid Address -**Error:** `Invalid recipient address` -**Fix:** Verify address format (starts with `ait1`) - -### 4. Insufficient Balance -**Error:** Transaction failed (insufficient balance) -**Fix:** Check wallet balance before sending - -### 5. RPC Connection Failed -**Error:** `Network error` -**Fix:** Verify blockchain RPC service is running, check RPC URL - -### 6. Chain ID Mismatch -**Error:** Transaction rejected (wrong chain) -**Fix:** Use `--chain-id` to specify correct chain or verify auto-detection - -### 7. Nonce Issues -**Error:** Transaction rejected (invalid nonce) -**Fix:** CLI automatically fetches actual nonce from blockchain - -### 8. Private Key Format -**Error:** `Invalid private key` -**Fix:** Ensure private key is valid hex string (64 hex characters for Ed25519) - -### 9. Keystore Encryption -**Error:** `Unsupported cipher` -**Fix:** CLI supports AES-256-GCM (blockchain-node standard) and Fernet (scripts/utils standard) - -### 10. Agent Registration Required -**Error:** Agent operations fail -**Fix:** Register agent via coordinator before using agent commands - ---- - -## Quick Reference - -```bash -# Wallet Management -./aitbc-cli create --name <name> --password <password> -./aitbc-cli list --format [table|json] -./aitbc-cli balance --name <name> -./aitbc-cli send --from <name> --to <address> --amount <amount> --password <password> - -# Blockchain -./aitbc-cli chain --rpc-url http://localhost:8006 -./aitbc-cli network --rpc-url http://localhost:8006 -./aitbc-cli analytics --type blocks --limit 10 - -# Mining -./aitbc-cli mine start --wallet <name> --threads 1 -./aitbc-cli mine status -./aitbc-cli mine stop - -# Marketplace -./aitbc-cli marketplace --action list -./aitbc-cli marketplace --action create --name <name> --price <price> - -# AI Jobs -./aitbc-cli ai-ops submit --wallet <name> --type inference --prompt <text> --payment <amount> - -# Agents -./aitbc-cli agent list --status active -./aitbc-cli agent message --agent <address> --message <text> --wallet <name> --password <password> - -# Simulations -./aitbc-cli simulate blockchain --blocks 10 --transactions 5 -./aitbc-cli simulate wallets --wallets 5 --balance 1000 -./aitbc-cli simulate price --price 100 --volatility 0.05 -``` - ---- - -## Status - -**AITBC CLI Tool: FULLY OPERATIONAL** - -- Version: 2.1.0 -- All wallet operations working -- Blockchain analytics functional -- Marketplace operations supported -- AI job submission available -- Mining operations operational -- Agent operations with coordinator integration -- Simulation tools for testing and development -- **This skill ships with AITBC software repository** - ---- - -**Generated by:** Hermes Instructor (localhost) -**Date:** 2026-05-08 -**Purpose:** Single comprehensive skill for AITBC CLI tool operations -**Location:** `/opt/aitbc/skills/aitbc-cli/SKILL.md` diff --git a/skills/aitbc-marketplace.md b/skills/aitbc-marketplace.md new file mode 100644 index 00000000..3a68deda --- /dev/null +++ b/skills/aitbc-marketplace.md @@ -0,0 +1,104 @@ +# AITBC Marketplace Skill + +## Trigger Conditions +Activate when user requests marketplace operations: listing creation, price optimization, market analysis, trading operations, GPU provider registration, or marketplace status checks. + +## Purpose +Create, manage, and optimize AITBC marketplace listings with pricing strategies and competitive analysis. + +## Prerequisites +- AITBC CLI accessible at `/opt/aitbc/aitbc-cli` +- Wallet with sufficient balance for listing fees +- Marketplace service operational +- GPU provider marketplace operational for resource allocation (if using GPU features) + +## Operations + +### List Marketplace Items +```bash +# Via aitbc-cli +./aitbc-cli marketplace --action list --rpc-url http://localhost:8006 + +# Alternative command +./aitbc-cli market-list --rpc-url http://localhost:8006 +``` + +### Create Marketplace Listing +```bash +# Via aitbc-cli +./aitbc-cli marketplace \ + --action create \ + --name <item_name> \ + --price <price> \ + --description <description> \ + --wallet <wallet_name> \ + --rpc-url http://localhost:8006 + +# Alternative command +./aitbc-cli market-create \ + --wallet <wallet_name> \ + --type <service_type> \ + --price <price> \ + --description <description> \ + --password <password> \ + --rpc-url http://localhost:8006 +``` + +### Search Marketplace +```bash +./aitbc-cli marketplace --action search --name <search_term> --rpc-url http://localhost:8006 +``` + +### List My Listings +```bash +./aitbc-cli marketplace --action my-listings --wallet <wallet_name> --rpc-url http://localhost:8006 +``` + +### GPU Provider Registration +```bash +# Register as GPU provider +python3 cli/unified_cli.py market gpu-provider-register \ + --wallet <wallet_name> \ + --gpu-model <model_name> \ + --gpu-count <number> \ + --models <comma_separated_models> \ + --marketplace-url http://aitbc1:8102 +``` + +### Buy/Create Bid +```bash +python3 cli/unified_cli.py market buy \ + --item <offer_id> \ + --wallet <wallet_name> \ + --password "$(cat /var/lib/aitbc/keystore/.genesis_password)" \ + --marketplace-url http://aitbc1:8102 +``` + +### List Bids/Orders +```bash +python3 cli/unified_cli.py market orders \ + --wallet <wallet_name> \ + --marketplace-url http://aitbc1:8102 +``` + +## Common Pitfalls + +1. **Insufficient Balance:** Check wallet balance before creating listings +2. **Invalid Service Type:** Ensure service type is valid (ai-inference, ai-training, resource-compute, resource-storage, data-processing, gpu-provider) +3. **Marketplace URL:** Use correct marketplace URL (http://aitbc1:8102 for unified_cli.py) +4. **Password Required:** Use password from `/var/lib/aitbc/keystore/.genesis_password` for genesis wallet +5. **Listing Not Found:** Verify listing ID is correct when searching or bidding + +## Verification Checklist +- [ ] Marketplace list returns available items +- [ ] Listing creation returns valid listing ID +- [ ] My listings shows created listings +- [ ] Search returns matching items +- [ ] GPU provider registration returns provider ID +- [ ] Bid creation returns bid ID and status + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **Module:** `cli/unified_cli.py` is a module within the CLI tool for marketplace and messaging operations +- **Note:** For marketplace operations, prefer `python3 cli/unified_cli.py` (verified working with 7 bugs fixed) +- **Marketplace URL:** `http://aitbc1:8102` for unified_cli.py marketplace operations diff --git a/skills/aitbc-multi-node-operations.md b/skills/aitbc-multi-node-operations.md new file mode 100644 index 00000000..a20b71b1 --- /dev/null +++ b/skills/aitbc-multi-node-operations.md @@ -0,0 +1,132 @@ +# AITBC Multi-Node Operations Skill + +## Trigger Conditions +Activate when user requests multi-node operations: git synchronization, service restart across nodes, blockchain state sync, or coordinated actions across the AITBC multi-node deployment. + +## Purpose +Synchronize git changes, coordinate blockchain state, and manage multi-node operations across genesis (localhost), follower (aitbc1), and gitea-runner nodes. + +## Prerequisites +- SSH access configured between all nodes with key-based authentication +- Git remote configured: `origin` (Gitea) and `github` (GitHub) +- All nodes have AITBC repository at `/opt/aitbc` +- Systemd services operational on all nodes + +## Operations + +### Check Multi-Node Git Status +```bash +# Check all three nodes +cd /opt/aitbc +echo "=== Genesis ===" && git status --short && git rev-parse --short HEAD +echo "=== Follower ===" && ssh aitbc1 'cd /opt/aitbc && git status --short && git rev-parse --short HEAD' +echo "=== Gitea-Runner ===" && ssh gitea-runner 'cd /opt/aitbc && git status --short && git rev-parse --short HEAD' +``` + +### Sync All Nodes from Genesis +```bash +# 1. Commit and push from genesis +cd /opt/aitbc +git add . && git commit -m "feat: description" && git push origin main + +# 2. Pull on follower +ssh aitbc1 'cd /opt/aitbc && git pull origin main' + +# 3. Pull on gitea-runner +ssh gitea-runner 'cd /opt/aitbc && git pull origin main' + +# 4. Verify sync +# (use check status command above) +``` + +### Handle Sync Conflicts +```bash +# If git pull fails on remote node +ssh aitbc1 'cd /opt/aitbc && git checkout --force . && git clean -fd && git pull origin main' +ssh gitea-runner 'cd /opt/aitbc && git checkout --force . && git clean -fd && git pull origin main' +``` + +### Service Restart After Sync +```bash +# Restart services that need code updates +ssh aitbc1 'systemctl restart aitbc-agent-coordinator.service' +ssh aitbc1 'systemctl restart aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl restart aitbc-blockchain-node.service' +``` + +### Check Blockchain Sync Across Nodes +```bash +# Check block heights on all nodes +for node in localhost aitbc1 gitea-runner; do + echo "=== $node ===" + if [ "$node" = "localhost" ]; then + ./aitbc-cli chain + else + ssh "$node" 'cd /opt/aitbc && ./aitbc-cli chain' + fi +done +``` + +### Check Service Status on All Nodes +```bash +# Check blockchain services on all nodes +for node in localhost aitbc1 gitea-runner; do + echo "=== $node ===" + if [ "$node" = "localhost" ]; then + systemctl status aitbc-blockchain-node.service --no-pager + else + ssh "$node" "systemctl status aitbc-blockchain-node.service --no-pager" + fi +done +``` + +### Coordinated Service Restart +```bash +# Restart blockchain services on all nodes +systemctl restart aitbc-blockchain-node.service +ssh aitbc1 'systemctl restart aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl restart aitbc-blockchain-node.service' + +# Verify services are running +systemctl status aitbc-blockchain-node.service +ssh aitbc1 'systemctl status aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl status aitbc-blockchain-node.service' +``` + +## Common Pitfalls + +1. **Git Conflicts on Remote Nodes:** Use `--force` flag with caution, prefer manual resolution +2. **Service Start Order:** Ensure services restart in correct order (P2P before blockchain-node) +3. **SSH Connectivity Issues:** Verify SSH keys are configured at `/root/.ssh/` for passwordless access +4. **Sync Partial Failure:** Identify which node failed and retry individually +5. **Blockchain Height Mismatch:** Wait for sync to complete after service restart +6. **Port Mismatches:** Coordinator API is on port 8011 (not 8000) + +## Verification Checklist +- [ ] Git status consistent across all nodes +- [ ] Git HEAD matches across all nodes +- [ ] Services running on all nodes +- [ ] Blockchain heights match across nodes +- [ ] P2P connections established (port 7070) +- [ ] RPC endpoints responding (port 8006) + +## Node Architecture +- **Genesis Node** (localhost): `/opt/aitbc` - Primary development node +- **Follower Node** (aitbc1): `/opt/aitbc` - Secondary blockchain node +- **Gitea-Runner Node** (gitea-runner): `/opt/aitbc` - CI/CD runner node (also hosts aitbc2 blockchain) + +## Git Remote Strategy +- **Primary Remote:** `origin` (Gitea at `http://gitea.bubuit.net:3000/oib/aitbc.git`) - Daily development operations +- **Secondary Remote:** `github` (GitHub at `https://github.com/oib/AITBC.git`) - Milestone releases only + +## Best Practices +1. Always verify git status on all nodes before major changes +2. Push to Gitea first, then pull on remote nodes +3. Use `--force-with-lease` instead of `--force` when needed +4. Restart affected services after code sync +5. Verify service health after sync and restart +6. Check blockchain sync after service restarts + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **SSH Access:** Use `ssh aitbc1` for follower node, `ssh gitea-runner` for CI/CD node diff --git a/skills/aitbc-node-coordination.md b/skills/aitbc-node-coordination.md new file mode 100644 index 00000000..e989eb47 --- /dev/null +++ b/skills/aitbc-node-coordination.md @@ -0,0 +1,98 @@ +# AITBC Node Coordination Skill + +## Trigger Conditions +Activate when user requests cross-node operations: synchronization, coordination, messaging, or multi-node status checks. + +## Purpose +Coordinate cross-node operations, synchronize blockchain state, and manage inter-node messaging between genesis and follower nodes. + +## Prerequisites +- SSH access configured between genesis (aitbc) and follower (aitbc1) with key-based authentication +- Blockchain nodes operational on both nodes via systemd services +- P2P mesh network active on port 7070 with peer configuration +- Unique node IDs configured (proposer_id and p2p_node_id in `/etc/aitbc/.env` and `/etc/aitbc/node.env`) +- Git synchronization configured between nodes at `/opt/aitbc/.git` + +## Operations + +### Check Multi-Node Status +```bash +# Check all three nodes +cd /opt/aitbc +echo "=== Genesis ===" && git status --short && git rev-parse --short HEAD +echo "=== Follower ===" && ssh aitbc1 'cd /opt/aitbc && git status --short && git rev-parse --short HEAD' +echo "=== Gitea-Runner ===" && ssh gitea-runner 'cd /opt/aitbc && git status --short && git rev-parse --short HEAD' +``` + +### Sync All Nodes from Genesis +```bash +# 1. Commit and push from genesis +cd /opt/aitbc +git add . && git commit -m "feat: description" && git push origin main + +# 2. Pull on follower +ssh aitbc1 'cd /opt/aitbc && git pull origin main' + +# 3. Pull on gitea-runner +ssh gitea-runner 'cd /opt/aitbc && git pull origin main' +``` + +### Handle Sync Conflicts +```bash +# If git pull fails on remote node +ssh aitbc1 'cd /opt/aitbc && git checkout --force . && git clean -fd && git pull origin main' +ssh gitea-runner 'cd /opt/aitbc && git checkout --force . && git clean -fd && git pull origin main' +``` + +### Service Restart After Sync +```bash +# Restart services that need code updates +ssh aitbc1 'systemctl restart aitbc-agent-coordinator.service' +ssh aitbc1 'systemctl restart aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl restart aitbc-blockchain-node.service' +``` + +### Check Blockchain Sync Status +```bash +# Check blockchain height on all nodes +./aitbc-cli chain +ssh aitbc1 'cd /opt/aitbc && ./aitbc-cli chain' +ssh gitea-runner 'cd /opt/aitbc && ./aitbc-cli chain' +``` + +### Check Node Health +```bash +# Check service status on all nodes +systemctl status aitbc-blockchain-node.service +ssh aitbc1 'systemctl status aitbc-blockchain-node.service' +ssh gitea-runner 'systemctl status aitbc-blockchain-node.service' +``` + +## Common Pitfalls + +1. **SSH Connectivity Issues:** Verify SSH keys are configured at `/root/.ssh/` for passwordless access +2. **Git Conflicts:** Use `--force` flag with caution, prefer manual resolution +3. **P2P Handshake Rejection:** Check for duplicate p2p_node_id, run `/opt/aitbc/scripts/utils/generate_unique_node_ids.py` +4. **Service Restart Failures:** Check systemd logs: `journalctl -u aitbc-blockchain-node.service -n 50` +5. **Sync Partial Failure:** Identify which sync type failed (blockchain, mempool, configuration, git) + +## Verification Checklist +- [ ] SSH connectivity to all nodes verified +- [ ] Git status consistent across all nodes +- [ ] Blockchain heights match across nodes +- [ ] P2P mesh network operational (port 7070) +- [ ] Services running on all nodes +- [ ] Node IDs unique (no duplicate p2p_node_id) + +## Node Architecture +- **Genesis Node** (localhost): `/opt/aitbc` - Primary development node +- **Follower Node** (aitbc1): `/opt/aitbc` - Secondary blockchain node +- **Gitea-Runner Node** (gitea-runner): `/opt/aitbc` - CI/CD runner node (also hosts aitbc2 blockchain) + +## Git Remote Strategy +- **Primary Remote:** `origin` (Gitea) - Daily development operations +- **Secondary Remote:** `github` - Milestone releases only + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **SSH Access:** Use `ssh aitbc1` for follower node, `ssh gitea-runner` for CI/CD node diff --git a/skills/aitbc-operations/SKILL.md b/skills/aitbc-operations/SKILL.md deleted file mode 100644 index 05b8920d..00000000 --- a/skills/aitbc-operations/SKILL.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -name: aitbc-operations -description: Complete AITBC software operations - marketplace (offers, deals, bids, orders), messaging, agent registration, coordinator. All bugs fixed, production-ready. Ships with AITBC software. -category: software-development ---- - -# AITBC Software Operations Skill - -Complete guide for Hermes agent to interact with AITBC (Agent Training Blockchain) software - marketplace, messaging, and agent operations. **This skill ships with AITBC software repository.** - -## Trigger Conditions - -Load this skill when: -- User asks to "make deals, offers, trades, bids, msg" with AITBC software -- Need to interact with AITBC marketplace, coordinator, or messaging -- Working with aitbc1 node or localhost AITBC instance -- User mentions "aitbc software", "marketplace", "offers", "deals", "bids", "messages" -- Need to register agents or use coordinator - -## Prerequisites - -- AITBC software installed at `/opt/aitbc` (cloned from repo) -- Wallet exists in `/var/lib/aitbc/keystore/` -- Password file at `/var/lib/aitbc/keystore/.genesis_password` -- Services running (verify: `systemctl status aitbc-marketplace`) - -## Step-by-Step Instructions - -### 1. CREATE OFFER (SELL) - Marketplace - -**CLI Command (localhost):** -```bash -cd /opt/aitbc -python3 cli/unified_cli.py market create \ - --wallet <wallet_name> \ - --type <service_type> \ - --price <price_in_AIT> \ - --description <optional_desc> -``` - -**CLI Command (aitbc1 node):** -```bash -cd /opt/aitbc -python3 cli/unified_cli.py market create \ - --wallet <wallet_name> \ - --type <service_type> \ - --price <price_in_AIT> \ - --description <optional_desc> \ - --marketplace-url http://aitbc1:8102 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py market create \ - --wallet hermes-final \ - --type "complete-demo" \ - --price 999 \ - --description "Full demo" \ - --marketplace-url http://aitbc1:8102 -``` - -**Result:** Returns offer ID (e.g., `0423942b3d4f4ec88968adc52fe4ba36`), provider, price, status (open) - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers` - ---- - -### 2. LIST OFFERS - Browse Marketplace - -**CLI Command:** -```bash -python3 cli/unified_cli.py market list --marketplace-url http://aitbc1:8102 -``` - -**API Endpoint:** `GET http://aitbc1:8102/v1/marketplace/offers` - -**Result:** JSON array of all offers (5+ verified working) - ---- - -### 3. BUY/DEAL (BID) - Execute Deals - -**CLI Command:** -```bash -python3 cli/unified_cli.py market buy \ - --item <offer_id> \ - --wallet <wallet_name> \ - --password "$(cat /var/lib/aitbc/keystore/.genesis_password)" \ - --marketplace-url http://aitbc1:8102 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py market buy \ - --item "0423942b3d4f4ec88968adc52fe4ba36" \ - --wallet hermes-final \ - --password "$(cat /var/lib/aitbc/keystore/.genesis_password)" \ - --marketplace-url http://aitbc1:8102 -``` - -**Result:** Bid ID (e.g., `dc74b16ab952432e8cb9ff7a3f97df3d`), status (pending), message - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers/{offer_id}/book` - ---- - -### 4. LIST BIDS/ORDERS - Track Trades - -**CLI Command (Orders):** -```bash -python3 cli/unified_cli.py market orders \ - --wallet <wallet_name> \ - --marketplace-url http://aitbc1:8102 -``` - -**API Endpoints:** -- Bids: `GET http://aitbc1:8102/v1/marketplace/bids` -- Orders: `GET http://aitbc1:8102/v1/marketplace/orders` - -**Result:** JSON array of bids/orders (2+ verified) - ---- - -### 5. MESSAGES (MSG) - Forum Operations - -**CLI Commands:** -```bash -# List topics -python3 cli/unified_cli.py messaging topics --rpc-url http://aitbc1:8006 - -# Create topic -python3 cli/unified_cli.py messaging create-topic \ - --title "<title>" \ - --content "<content>" \ - --rpc-url http://aitbc1:8006 - -# Post message to topic -python3 cli/unified_cli.py messaging post \ - --topic-id <topic_id> \ - --content "<message>" \ - --rpc-url http://aitbc1:8006 -``` - -**Example (Verified):** -```bash -python3 cli/unified_cli.py messaging topics --rpc-url http://aitbc1:8006 -``` - -**Result:** Topic ID (e.g., `topic_a89f0525b357a8aa`), title, total topics - -**API Endpoint:** `http://aitbc1:8006` (forum service) - -**Note:** Messaging requires agent registration first (see Step 6) - ---- - -### 6. AGENT REGISTRATION - Coordinator - -**API Command:** -```bash -curl -s -X POST http://aitbc1:9001/agents/register \ - -H "Content-Type: application/json" \ - -d '{ - "agent_id": "<agent_id>", - "agent_type": "worker", - "endpoint": "http://<host>:<port>", - "capabilities": ["marketplace", "messaging"] - }' -``` - -**Example (Verified):** -```bash -curl -s -X POST http://aitbc1:9001/agents/register \ - -H "Content-Type: application/json" \ - -d '{"agent_id":"hermes-aitbc1","agent_type":"worker","endpoint":"http://localhost:9997","capabilities":["marketplace","messaging"]}' -``` - -**Result:** `{"status":"success","message":"Agent X registered successfully",...}` - -**API Endpoint:** `POST http://aitbc1:9001/agents/register` - ---- - -## Authentication Requirements - -### Marketplace Operations: -- **Requires:** Wallet + Password -- **Wallet Location:** `/var/lib/aitbc/keystore/` -- **Password Location:** `/var/lib/aitbc/keystore/.genesis_password` - -### Messaging Operations: -- **Requires:** Agent registration with blockchain node -- **Registration:** Via coordinator `http://aitbc1:9001/agents/register` - -### Agent Operations: -- **Requires:** Agent ID + endpoint + capabilities -- **Coordinator:** `http://aitbc1:9001` - ---- - -## Cross-Node Operations - -### Key URLs (Use Hostname, NOT IP): -- **aitbc1 Marketplace:** `http://aitbc1:8102` (NOT `10.1.223.93:8102`) -- **aitbc1 Coordinator:** `http://aitbc1:9001` -- **aitbc1 Messaging:** `http://aitbc1:8006` -- **Redis (Cross-node Agent Discovery):** `10.1.223.93:6379` - -### Verified Cross-Node Operations: -- ✅ Topics created on localhost visible on aitbc1 (and vice versa) -- ✅ Agent registration on aitbc1 coordinator working -- ✅ Cross-node agent discovery via shared Redis - ---- - -## Pitfalls & Common Errors - -### 1. Using IP Instead of Hostname -**Error:** Connection timeout or failure -**Fix:** Use `aitbc1:8102`, NOT `10.1.223.93:8102` - -### 2. BUY Command Using Item Name Instead of Offer ID -**Error:** 404 or "Purchase failed" -**Fix:** Use full offer ID (e.g., `0423942b3d4f4ec88968adc52fe4ba36`), not item name - -### 3. Messaging Without Agent Registration -**Error:** `Invalid agent credentials` or `INVALID_AGENT` -**Fix:** Register agent first via `POST http://aitbc1:9001/agents/register` - -### 4. CLI Wrong Parameter Names -**Error:** `unrecognized arguments: --marketplace-url` -**Fix:** Check `--help` for correct parameter names per command - -### 5. Forgetting Wallet Password -**Error:** Authentication failure -**Fix:** Use `cat /var/lib/aitbc/keystore/.genesis_password` for password - ---- - -## Bugs Fixed (All Verified) - -| # | Bug | Fix Commit | Status | -|---|-----|------------|--------| -| 1 | Async/Sync Session | 130a2953 | ✅ FIXED | -| 2 | Datetime Timezone | 6549483b | ✅ FIXED | -| 3 | Provider NULL | 528c822f | ✅ FIXED | -| 4 | JSON Serialization (list_offers) | 4ac23bf3 | ✅ FIXED | -| 5 | BUY/DEAL 404 | 58784193 | ✅ FIXED | -| 6 | JSON Serialization (list_bids) | fb09022e | ✅ FIXED | -| 7 | ORDERS CLI 404 | fb09022e | ✅ FIXED | - ---- - -## Verification Checklist - -Before using this skill, verify: -- [ ] AITBC repo cloned: `ls /opt/aitbc` -- [ ] aitbc1 marketplace running: `curl -s http://aitbc1:8102/health` -- [ ] Wallet exists: `ls /var/lib/aitbc/keystore/` -- [ ] Password file readable: `cat /var/lib/aitbc/keystore/.genesis_password` -- [ ] Coordinator accessible: `curl -s http://aitbc1:9001/health` -- [ ] Can create offer (test with `--price 100`) -- [ ] Can list offers (see 1+ offers) -- [ ] Can buy offer (creates bid with pending status) - ---- - -## Operations Matrix (All Verified) - -| Operation | aitbc1 Node | localhost | Status | -|-----------|--------------|-----------|--------| -| CREATE OFFER (SELL) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST OFFERS | ✅ WORKS | ✅ WORKS | BOTH WORK | -| BUY/DEAL (BID) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST BIDS | ✅ WORKS | ✅ WORKS | BOTH WORK | -| ORDERS CLI | ✅ WORKS | ✅ WORKS | BOTH WORK | -| MESSAGES (MSG) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| AGENT REGISTER | ✅ WORKS | ✅ WORKS | BOTH WORK | - ---- - -## Quick Reference - -```bash -# SELL (Create Offer) -market create --wallet X --type Y --price Z --marketplace-url http://aitbc1:8102 - -# LIST Offers -market list --marketplace-url http://aitbc1:8102 - -# BUY (Create Bid) -market buy --item <offer_id> --wallet X --password Y --marketplace-url http://aitbc1:8102 - -# LIST Bids/Orders -market orders --wallet X --marketplace-url http://aitbc1:8102 - -# MESSAGES -messaging topics --rpc-url http://aitbc1:8006 - -# AGENT REGISTER -curl -X POST http://aitbc1:9001/agents/register -H "Content-Type: application/json" -d '{"agent_id":"X","agent_type":"worker",...}' -``` - ---- - -## Status - -**AITBC Software: FULLY OPERATIONAL** - -- 24 services running -- All 7 bugs fixed (verified this session) -- Cross-node operations verified -- Production-ready system -- **This skill ships with AITBC software repository** - ---- - -**Generated by:** Hermes Instructor (localhost) -**Date:** 2026-05-08 -**Purpose:** Single comprehensive skill shipping with AITBC software -**Location:** `/opt/aitbc/skills/aitbc-operations/SKILL.md` diff --git a/skills/aitbc-wallet-management.md b/skills/aitbc-wallet-management.md new file mode 100644 index 00000000..adb49a21 --- /dev/null +++ b/skills/aitbc-wallet-management.md @@ -0,0 +1,95 @@ +# AITBC Wallet Management Skill + +## Trigger Conditions +Activate when user requests wallet operations: creation, listing, balance checking, wallet information retrieval, import, export, or deletion. + +## Purpose +Create, list, import, export, and manage AITBC blockchain wallets with deterministic validation. + +## Prerequisites +- AITBC CLI accessible at `/opt/aitbc/aitbc-cli` +- Python venv activated for CLI operations +- Keystore directory at `/var/lib/aitbc/keystore/` +- SSH access to follower node (aitbc1) for cross-node operations +- Default wallet password: from `/var/lib/aitbc/keystore/.genesis_password` + +## Operations + +### Create Wallet +```bash +./aitbc-cli create --name <wallet_name> --password <password> +``` + +### Import Wallet +```bash +./aitbc-cli import --name <wallet_name> --private-key <hex_key> --password <password> +``` + +### Export Wallet +```bash +./aitbc-cli export --name <wallet_name> --password <password> +``` + +### List Wallets +```bash +./aitbc-cli list + +# With JSON format +./aitbc-cli list --format json +``` + +### Check Wallet Balance +```bash +./aitbc-cli balance --name <wallet_name> +``` + +### Delete Wallet +```bash +./aitbc-cli delete --name <wallet_name> +``` + +### Rename Wallet +```bash +./aitbc-cli rename --old <old_name> --new <new_name> +``` + +### Get Transaction History +```bash +./aitbc-cli transactions --name <wallet_name> --limit <limit> --format [table|json] +``` + +## Common Pitfalls + +1. **Wallet Not Found:** Check wallet name spelling, verify keystore directory at `/var/lib/aitbc/keystore/` +2. **Invalid Password:** Verify password, check password file at `/var/lib/aitbc/keystore/.genesis_password` +3. **Invalid Private Key:** Ensure private key is valid hex string (64 hex characters for Ed25519) +4. **Wallet Already Exists:** Choose a different wallet name or delete existing wallet first +5. **Insufficient Balance:** Check wallet balance before sending transactions +6. **Keystore Encryption:** CLI supports AES-256-GCM and Fernet encryption +7. **Cross-Node Issues:** Verify SSH connectivity for operations on remote nodes + +## Verification Checklist +- [ ] Wallet created successfully and appears in list +- [ ] Wallet balance retrieved correctly +- [ ] Private key export works with correct password +- [ ] Import from private key creates valid wallet +- [ ] Wallet deletion removes wallet from list +- [ ] Transaction history shows past transactions + +## Wallet Naming Conventions +- Use alphanumeric characters, hyphens, and underscores only +- Avoid special characters and spaces +- Use descriptive names (e.g., "genesis", "hermes-trainee", "trading-wallet") +- Max length: 64 characters + +## Security Considerations +- Never share private keys +- Store passwords securely (use password file when possible) +- Backup keystore directory regularly +- Use strong passwords (minimum 12 characters) +- Enable encryption for sensitive wallets + +## CLI Tool Preference +- **Primary CLI:** `/opt/aitbc/aitbc-cli` is the single CLI entry point +- **Keystore Location:** `/var/lib/aitbc/keystore/` +- **Password File:** `/var/lib/aitbc/keystore/.genesis_password`