From 3735cd35a77303b6f6e4c44bd4863173da81cf39 Mon Sep 17 00:00:00 2001 From: aitbc Date: Fri, 8 May 2026 22:12:35 +0200 Subject: [PATCH] docs: move skill documentation files from docs/ to docs/skills/ directory - Move aitbc-ai-operations.md to docs/skills/ - Move aitbc-basic-operations.md to docs/skills/ - Move aitbc-blockchain-troubleshooting.md to docs/skills/ - Move aitbc-cli.md to docs/skills/ - Move aitbc-marketplace.md to docs/skills/ - Move aitbc-multi-node-operations.md to docs/skills/ - Move aitbc-node-coordination.md to docs/skills/ - Move aitbc-wallet-management.md to docs/skills/ - Move aitbc.md to docs/skills/ - All --- docs/aitbc-ai-operations.md | 93 ---- docs/aitbc-basic-operations.md | 82 --- docs/aitbc-blockchain-troubleshooting.md | 152 ------ docs/aitbc-cli.md | 657 ----------------------- docs/aitbc-marketplace.md | 104 ---- docs/aitbc-multi-node-operations.md | 132 ----- docs/aitbc-node-coordination.md | 98 ---- docs/aitbc-wallet-management.md | 95 ---- docs/aitbc.md | 351 ------------ 9 files changed, 1764 deletions(-) delete mode 100644 docs/aitbc-ai-operations.md delete mode 100644 docs/aitbc-basic-operations.md delete mode 100644 docs/aitbc-blockchain-troubleshooting.md delete mode 100644 docs/aitbc-cli.md delete mode 100644 docs/aitbc-marketplace.md delete mode 100644 docs/aitbc-multi-node-operations.md delete mode 100644 docs/aitbc-node-coordination.md delete mode 100644 docs/aitbc-wallet-management.md delete mode 100644 docs/aitbc.md diff --git a/docs/aitbc-ai-operations.md b/docs/aitbc-ai-operations.md deleted file mode 100644 index 79a00275..00000000 --- a/docs/aitbc-ai-operations.md +++ /dev/null @@ -1,93 +0,0 @@ -# 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 \ - --type \ - --prompt \ - --payment \ - --password \ - --rpc-url http://localhost:8006 -``` - -### Check AI Job Status -```bash -./aitbc-cli ai-ops status --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 \ - --gpu \ - --memory \ - --duration -``` - -### 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/docs/aitbc-basic-operations.md b/docs/aitbc-basic-operations.md deleted file mode 100644 index be618bdb..00000000 --- a/docs/aitbc-basic-operations.md +++ /dev/null @@ -1,82 +0,0 @@ -# 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/docs/aitbc-blockchain-troubleshooting.md b/docs/aitbc-blockchain-troubleshooting.md deleted file mode 100644 index 1c93101b..00000000 --- a/docs/aitbc-blockchain-troubleshooting.md +++ /dev/null @@ -1,152 +0,0 @@ -# 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/docs/aitbc-cli.md b/docs/aitbc-cli.md deleted file mode 100644 index 7d71ae53..00000000 --- a/docs/aitbc-cli.md +++ /dev/null @@ -1,657 +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 --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 --private-key --password -``` - -**Example:** -```bash -./aitbc-cli import --name imported-wallet --private-key "abc123..." --password "securepassword123" -``` - -#### Export Wallet (Private Key) -```bash -./aitbc-cli export --name --password -``` - -#### Delete Wallet -```bash -./aitbc-cli delete --name -``` - -#### Rename Wallet -```bash -./aitbc-cli rename --old --new -``` - -#### 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 \ - --to \ - --amount \ - --fee \ - --password \ - --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 --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 --limit --format [table|json] --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 -``` - -**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 -``` - -**Result:** Head block information, network health - -#### Blockchain Analytics -```bash -./aitbc-cli analytics --type [blocks|supply|accounts] --limit --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 --threads --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 -``` - -#### Get Mining Status -```bash -./aitbc-cli mine status --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 -``` - -**Alternative command:** -```bash -./aitbc-cli market-list --rpc-url -``` - -**Result:** List of available marketplace items - -#### Create Marketplace Listing -```bash -./aitbc-cli marketplace \ - --action create \ - --name \ - --price \ - --description \ - --wallet \ - --rpc-url -``` - -**Alternative command:** -```bash -./aitbc-cli market-create \ - --wallet \ - --type \ - --price \ - --description \ - --password \ - --rpc-url -``` - -**Example:** -```bash -./aitbc-cli market-create \ - --wallet my-wallet \ - --type "gpu-compute" \ - --price 100 \ - --description "GPU compute for AI training" \ - --password "securepassword123" \ - --rpc-url http://localhost:8006 -``` - -**Result:** Returns listing ID, provider, price, status - -#### Search Marketplace -```bash -./aitbc-cli marketplace --action search --name --rpc-url -``` - -#### List My Listings -```bash -./aitbc-cli marketplace --action my-listings --wallet --rpc-url -``` - ---- - -### 6. AI Compute Operations - -#### Submit AI Job -```bash -./aitbc-cli ai-ops submit \ - --wallet \ - --type \ - --prompt \ - --payment \ - --password \ - --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 --rpc-url -``` - ---- - -### 7. Agent Operations - -#### Create Agent -```bash -./aitbc-cli agent create \ - --name \ - --verification \ - --max-execution-time \ - --max-cost-budget -``` - -#### Execute Agent -```bash -./aitbc-cli agent execute \ - --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 \ - --message \ - --wallet \ - --password \ - --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 --rpc-url -``` - -**Result:** Lists all messages sent to the agent from blockchain - -#### Register Agent (via CLI) -```bash -# CLI method for agent registration -python3 cli/unified_cli.py agent register \ - --agent-id \ - --agent-type worker \ - --endpoint \ - --capabilities marketplace,messaging -``` - -**Note:** For API-based registration, see aitbc.md skill - ---- - -### 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 --metrics [all|performance|cost] -``` - -#### Train Agent -```bash -./aitbc-cli hermes train \ - --train-action agent \ - --agent-id \ - --stage \ - --training-data -``` - -**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 --template [custom|standard] -``` - -#### Run Workflow -```bash -./aitbc-cli workflow run --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 \ - --cpu \ - --memory \ - --duration -``` - -#### Optimize Resources -```bash -./aitbc-cli resource optimize --target [all|cpu|memory] --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 \ - --transactions \ - --delay -``` - -**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 \ - --balance \ - --transactions \ - --amount-range -``` - -**Example:** -```bash -./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20 --amount-range 1-100 -``` - -#### Simulate Price -```bash -./aitbc-cli simulate price \ - --price \ - --volatility \ - --timesteps \ - --delay -``` - -**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 \ - --network-delay \ - --failure-rate -``` - -**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 \ - --models \ - --duration-range -``` - -**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 --password -./aitbc-cli list --format [table|json] -./aitbc-cli balance --name -./aitbc-cli send --from --to
--amount --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 --threads 1 -./aitbc-cli mine status -./aitbc-cli mine stop - -# Marketplace -./aitbc-cli marketplace --action list -./aitbc-cli marketplace --action create --name --price - -# AI Jobs -./aitbc-cli ai-ops submit --wallet --type inference --prompt --payment - -# Agents -./aitbc-cli agent list --status active -./aitbc-cli agent message --agent
--message --wallet --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/docs/aitbc-marketplace.md b/docs/aitbc-marketplace.md deleted file mode 100644 index 3a68deda..00000000 --- a/docs/aitbc-marketplace.md +++ /dev/null @@ -1,104 +0,0 @@ -# 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 \ - --price \ - --description \ - --wallet \ - --rpc-url http://localhost:8006 - -# Alternative command -./aitbc-cli market-create \ - --wallet \ - --type \ - --price \ - --description \ - --password \ - --rpc-url http://localhost:8006 -``` - -### Search Marketplace -```bash -./aitbc-cli marketplace --action search --name --rpc-url http://localhost:8006 -``` - -### List My Listings -```bash -./aitbc-cli marketplace --action my-listings --wallet --rpc-url http://localhost:8006 -``` - -### GPU Provider Registration -```bash -# Register as GPU provider -python3 cli/unified_cli.py market gpu-provider-register \ - --wallet \ - --gpu-model \ - --gpu-count \ - --models \ - --marketplace-url http://aitbc1:8102 -``` - -### Buy/Create Bid -```bash -python3 cli/unified_cli.py market buy \ - --item \ - --wallet \ - --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 \ - --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/docs/aitbc-multi-node-operations.md b/docs/aitbc-multi-node-operations.md deleted file mode 100644 index a20b71b1..00000000 --- a/docs/aitbc-multi-node-operations.md +++ /dev/null @@ -1,132 +0,0 @@ -# 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/docs/aitbc-node-coordination.md b/docs/aitbc-node-coordination.md deleted file mode 100644 index e989eb47..00000000 --- a/docs/aitbc-node-coordination.md +++ /dev/null @@ -1,98 +0,0 @@ -# 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/docs/aitbc-wallet-management.md b/docs/aitbc-wallet-management.md deleted file mode 100644 index adb49a21..00000000 --- a/docs/aitbc-wallet-management.md +++ /dev/null @@ -1,95 +0,0 @@ -# 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 --password -``` - -### Import Wallet -```bash -./aitbc-cli import --name --private-key --password -``` - -### Export Wallet -```bash -./aitbc-cli export --name --password -``` - -### List Wallets -```bash -./aitbc-cli list - -# With JSON format -./aitbc-cli list --format json -``` - -### Check Wallet Balance -```bash -./aitbc-cli balance --name -``` - -### Delete Wallet -```bash -./aitbc-cli delete --name -``` - -### Rename Wallet -```bash -./aitbc-cli rename --old --new -``` - -### Get Transaction History -```bash -./aitbc-cli transactions --name --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` diff --git a/docs/aitbc.md b/docs/aitbc.md deleted file mode 100644 index d0d6d5cc..00000000 --- a/docs/aitbc.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -name: aitbc-operations -description: AITBC software service operations - marketplace API endpoints, coordinator API, messaging API, cross-node operations, testing patterns. All operational information verified. Ships with AITBC software. -category: software-development ---- - -# AITBC Software Service Operations Skill - -Complete guide for Hermes agent to interact with AITBC (Agent Training Blockchain) software via API endpoints and service operations - marketplace, coordinator, messaging, cross-node operations, testing patterns. **This skill ships with AITBC software repository.** - -**Note:** For CLI commands, use the aitbc-cli.md skill. This skill focuses on API endpoints and service operations. - -## Trigger Conditions - -Load this skill when: -- Need to interact with AITBC marketplace, coordinator, or messaging via API -- Working with aitbc1 node or localhost AITBC instance -- Need to register agents via coordinator API -- Need to test AITBC service operations or validate scenarios -- Need cross-node operations verification -- User mentions "API", "endpoint", "service health", "cross-node" - -## Prerequisites - -- AITBC software installed at `/opt/aitbc` (cloned from repo) -- Services running (verify: `systemctl status aitbc-marketplace`) -- For CLI commands, see aitbc-cli.md skill - -## Step-by-Step Instructions - -### 1. Marketplace API Operations - -#### Create Offer (API) -```bash -curl -s -X POST http://aitbc1:8102/v1/marketplace/offers \ - -H "Content-Type: application/json" \ - -d '{ - "provider": "", - "item_type": "", - "price": , - "description": "" - }' -``` - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers` - -**Result:** Returns offer ID, provider, price, status (open) - -#### List Offers (API) -```bash -curl -s http://aitbc1:8102/v1/marketplace/offers -``` - -**API Endpoint:** `GET http://aitbc1:8102/v1/marketplace/offers` - -**Result:** JSON array of all offers - -#### Buy/Create Bid (API) -```bash -curl -s -X POST http://aitbc1:8102/v1/marketplace/offers/{offer_id}/book \ - -H "Content-Type: application/json" \ - -d '{ - "buyer": "", - "bid_amount": - }' -``` - -**API Endpoint:** `POST http://aitbc1:8102/v1/marketplace/offers/{offer_id}/book` - -**Result:** Bid ID, status (pending), message - -#### List Bids/Orders (API) -```bash -# Bids -curl -s http://aitbc1:8102/v1/marketplace/bids - -# Orders -curl -s http://aitbc1:8102/v1/marketplace/orders -``` - -**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. Messaging API Operations - -#### List Topics (API) -```bash -curl -s http://aitbc1:8006/topics -``` - -**API Endpoint:** `http://aitbc1:8006` (forum service) - -**Result:** Topic ID, title, total topics - -#### Create Topic (API) -```bash -curl -s -X POST http://aitbc1:8006/topics \ - -H "Content-Type: application/json" \ - -d '{ - "title": "", - "content": "<content>" - }' -``` - -#### Post Message to Topic (API) -```bash -curl -s -X POST http://aitbc1:8006/topics/{topic_id}/messages \ - -H "Content-Type: application/json" \ - -d '{ - "content": "<message>" - }' -``` - -**Note:** Messaging requires agent registration first (see Agent Registration section) - ---- - -### 3. Agent Registration (Coordinator API) - -#### Register Agent -```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 - -### API Operations: -- **Marketplace API:** May require wallet address for provider field -- **Coordinator API:** Agent registration requires agent_id, endpoint, capabilities -- **Messaging API:** Requires agent registration first - -### For CLI Authentication: -- See aitbc-cli.md skill for wallet password and CLI authentication - ---- - -## 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. Agent Registration Required -**Error:** `Invalid agent credentials` or `INVALID_AGENT` -**Fix:** Register agent first via `POST http://aitbc1:9001/agents/register` - -### 3. 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` - -### 4. Backend Router Incomplete -**Error:** API expects 6 endpoints but router only implements 1 -**Fix:** Check router file for ALL expected endpoints using `grep "@router\." <router.py>`, compare with API code, report missing endpoints - -### 5. URL Configuration Mismatch -**Error:** API calls wrong backend service URL -**Fix:** Verify which port has the endpoint, check config.py for URL defaults - -### 6. Empty File Validation -**Error:** API checks `if not file.exists()` but misses empty files (0 bytes) -**Fix:** Check file size too: `if not file.exists() or file.stat().st_size == 0:` - -### 7. Backend Response Format Mismatch -**Error:** API expects dict of dicts but backend returns strings -**Fix:** Check backend response with `curl -s http://localhost:PORT/endpoint | python3 -m json.tool`, compare with API code - -### 8. Missing Imports in API Files -**Error:** `NameError: name 'httpx' is not defined` at runtime -**Fix:** Check for missing imports (httpx, json) in API files, add to imports section - -**Note:** For CLI-specific pitfalls (wallet password, parameter names, etc.), see aitbc-cli.md skill - ---- - -## Verification Checklist - -Before using this skill, verify: -- [ ] AITBC repo cloned: `ls /opt/aitbc` -- [ ] aitbc1 marketplace running: `curl -s http://aitbc1:8102/health` -- [ ] Coordinator accessible: `curl -s http://aitbc1:9001/health` -- [ ] Messaging service accessible: `curl -s http://aitbc1:8006/health` -- [ ] Can list offers via API: `curl -s http://aitbc1:8102/v1/marketplace/offers` -- [ ] Can register agent via API: `curl -s -X POST http://aitbc1:9001/agents/register` - -**Note:** For wallet and CLI verification, see aitbc-cli.md skill - ---- - -## Operations Matrix (All Verified) - -| Operation | aitbc1 Node | localhost | Status | -|-----------|--------------|-----------|--------| -| CREATE OFFER (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST OFFERS (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| BUY/DEAL (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| LIST BIDS (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| ORDERS (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| MESSAGES (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | -| AGENT REGISTER (API) | ✅ WORKS | ✅ WORKS | BOTH WORK | - ---- - -## Quick Reference - -```bash -# CREATE OFFER (API) -curl -X POST http://aitbc1:8102/v1/marketplace/offers -H "Content-Type: application/json" -d '{"provider":"...","item_type":"...","price":...}' - -# LIST OFFERS (API) -curl http://aitbc1:8102/v1/marketplace/offers - -# BUY/DEAL (API) -curl -X POST http://aitbc1:8102/v1/marketplace/offers/{id}/book -H "Content-Type: application/json" -d '{"buyer":"...","bid_amount":...}' - -# LIST BIDS/ORDERS (API) -curl http://aitbc1:8102/v1/marketplace/bids -curl http://aitbc1:8102/v1/marketplace/orders - -# MESSAGES (API) -curl http://aitbc1:8006/topics -curl -X POST http://aitbc1:8006/topics -H "Content-Type: application/json" -d '{"title":"...","content":"..."}' - -# AGENT REGISTER (API) -curl -X POST http://aitbc1:9001/agents/register -H "Content-Type: application/json" -d '{"agent_id":"...","agent_type":"worker","endpoint":"...","capabilities":["marketplace","messaging"]}' -``` - -**Note:** For CLI commands, use `python3 cli/unified_cli.py` instead of `aitbc-cli`. See CLI Tool Preference section below. - ---- - -## CLI Tool Preference - -**For marketplace operations, use `python3 cli/unified_cli.py` which is the verified marketplace module within the AITBC CLI.** - -The unified CLI (`cli/unified_cli.py`) has been verified working (all 7 bugs fixed in session 2026-05-08). This is the marketplace module used by the main AITBC CLI entry point. - -**Entry Point:** `/opt/aitbc/aitbc-cli` is the single CLI entry point -**Marketplace Module:** `cli/unified_cli.py` (verified working) -**Verified Commands:** `python3 cli/unified_cli.py market create/list/buy/orders` -**Verification Status:** ✅ All marketplace operations working -**Bugs Fixed:** See Bugs Fixed section below - ---- - -## Bugs Fixed (Session 2026-05-08) - -| # | Bug | Commit | Status | -|---|-----|--------|--------| -| 1 | Async/Sync Session Management | 130a2953 | ✅ FIXED | -| 2 | Datetime Timezone Error | 6549483b | ✅ FIXED | -| 3 | Provider NULL Mapping | 528c822f | ✅ FIXED | -| 4 | JSON Serialization (SQLAlchemy models) | 4ac23bf3 | ✅ FIXED | -| 5 | JSON Serialization (list_bids) | fb09022e | ✅ FIXED | -| 6 | Book Endpoint 404 | 58784193 | ✅ FIXED | -| 7 | Orders Endpoint 404 | fb09022e | ✅ FIXED | - -**Summary:** All 7 marketplace service bugs fixed. CLI `unified_cli.py` verified working after fixes. - ---- - -## Status - -**AITBC Software Service Operations: FULLY OPERATIONAL** - -- 24 services running -- All marketplace API 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:** API and service operations skill shipping with AITBC software -**Location:** `/opt/aitbc/skills/aitbc.md`