oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

feat: add pure AITBC software skills to skills/ directory
All checks were successful
Cross-Node Transaction Testing / transaction-test (push) Successful in 2s
Details
Deploy to Testnet / deploy-testnet (push) Successful in 1m10s
Details
Multi-Node Stress Testing / stress-test (push) Successful in 1s
Details
Node Failover Simulation / failover-test (push) Successful in 4s
Details

Browse Source 
- Create aitbc-basic-operations.md - Basic CLI validation, wallet operations, blockchain status, service health
- Create aitbc-marketplace.md - Marketplace operations: listings, GPU provider, trading
- Create aitbc-node-coordination.md - Multi-node coordination, blockchain sync, messaging
- Create aitbc-wallet-management.md - Wallet creation, import, export, balance, deletion
- Create aitbc-ai-operations.md - AI job submission, monitoring, resource allocation
- Create aitbc-blockchain-troubleshooting.md - Sync issues, P2P problems, service failures, data corruption
- Create aitbc-multi-node-operations.md - Git sync, service restart, coordinated actions across nodes
- Skills distilled from windsurf AITBC skills for Hermes agent use
- All skills include trigger conditions, operations, common pitfalls, verification checklists
This commit is contained in:
aitbc
2026-05-08 21:37:37 +02:00
parent da052cf14d
commit a428bb55a6
10 changed files with 756 additions and 1303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
skills/SKILL.md
View File

@@ -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 <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 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 "<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`

93
skills/aitbc-ai-operations.md Normal file
View File

@@ -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)

82
skills/aitbc-basic-operations.md Normal file
View File

@@ -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)

152
skills/aitbc-blockchain-troubleshooting.md Normal file
View File

@@ -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)

617
skills/aitbc-cli/SKILL.md
View File

@@ -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`

104
skills/aitbc-marketplace.md Normal file
View File

@@ -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

132
skills/aitbc-multi-node-operations.md Normal file
View File

@@ -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

98
skills/aitbc-node-coordination.md Normal file
View File

@@ -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

321
skills/aitbc-operations/SKILL.md
View File

@@ -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`

95
skills/aitbc-wallet-management.md Normal file
View File

@@ -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`