chore: standardize configuration, logging, and error handling across blockchain node and coordinator API

- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks - Change blockchain node mempool backend default from memory to database for persistence - Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator) - Add structured logging fields: service, module, function, line number - Unify coordinator config with Database
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
--- a/docs/0_getting_started/1_intro.md
+++ b/docs/0_getting_started/1_intro.md
@@ -0,0 +1,47 @@
+# What is AITBC?
+
+AITBC is a decentralized GPU computing platform that connects AI workloads with GPU providers through a blockchain-coordinated marketplace.
+
+| Role | What you do |
+|------|-------------|
+| **Client** | Rent GPU power, submit AI/ML jobs, pay with AITBC tokens |
+| **Miner** | Provide GPU resources, process jobs, earn AITBC tokens |
+| **Node Operator** | Run blockchain infrastructure, validate transactions |
+
+## Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| Coordinator API | Job orchestration, miner matching, receipt management |
+| Blockchain Node | PoA consensus, transaction ledger, token transfers |
+| Marketplace Web | GPU offer/bid UI, stats dashboard |
+| Trade Exchange | BTC-to-AITBC trading, QR payments |
+| Wallet | Key management, staking, multi-sig support |
+| CLI | 90+ commands across 12 groups for all roles |
+
+## Quick Start by Role
+
+**Clients** → [2_clients/1_quick-start.md](../2_clients/1_quick-start.md)
+```bash
+pip install -e .
+aitbc config set coordinator_url http://localhost:8000
+aitbc client submit --prompt "What is AI?"
+```
+
+**Miners** → [3_miners/1_quick-start.md](../3_miners/1_quick-start.md)
+```bash
+aitbc miner register --name my-gpu --gpu a100 --count 1
+aitbc miner poll
+```
+
+**Node Operators** → [4_blockchain/1_quick-start.md](../4_blockchain/1_quick-start.md)
+```bash
+aitbc-node init --chain-id ait-devnet
+aitbc-node start
+```
+
+## Next Steps
+
+- [2_installation.md](./2_installation.md) — Install all components
+- [3_cli.md](./3_cli.md) — Full CLI usage guide
+- [../README.md](../README.md) — Documentation navigation
--- a/docs/0_getting_started/2_installation.md
+++ b/docs/0_getting_started/2_installation.md
@@ -0,0 +1,71 @@
+# Installation
+
+## Prerequisites
+
+- Python 3.10+
+- Git
+- (Optional) PostgreSQL 14+ for production
+- (Optional) NVIDIA GPU + CUDA for mining
+
+## Monorepo Install
+
+```bash
+git clone https://github.com/oib/AITBC.git
+cd aitbc
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+This installs the CLI, coordinator API, and blockchain node from the monorepo.
+
+## Environment Configuration
+
+### Coordinator API
+
+Create `apps/coordinator-api/.env`:
+```env
+JWT_SECRET=your-secret-key
+DATABASE_URL=sqlite:///./data/coordinator.db   # or postgresql://user:pass@localhost/aitbc
+LOG_LEVEL=INFO
+```
+
+### Blockchain Node
+
+Create `apps/blockchain-node/.env`:
+```env
+CHAIN_ID=ait-devnet
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8080
+MEMPOOL_BACKEND=database
+```
+
+## Systemd Services (Production)
+
+```bash
+sudo cp systemd/aitbc-*.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now aitbc-coordinator-api
+sudo systemctl enable --now aitbc-blockchain-node-1
+```
+
+## Verify
+
+```bash
+systemctl status aitbc-coordinator-api
+curl http://localhost:8000/v1/health
+aitbc blockchain status
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Port in use | `sudo lsof -i :8000` then `kill` the PID |
+| DB corrupt | `rm -f data/coordinator.db && python -m app.storage init` |
+| Module not found | Ensure venv is active: `source .venv/bin/activate` |
+
+## Next Steps
+
+- [3_cli.md](./3_cli.md) — CLI usage guide
+- [../2_clients/1_quick-start.md](../2_clients/1_quick-start.md) — Client quick start
+- [../3_miners/1_quick-start.md](../3_miners/1_quick-start.md) — Miner quick start
--- a/docs/0_getting_started/3_cli.md
+++ b/docs/0_getting_started/3_cli.md
@@ -0,0 +1,73 @@
+# CLI Usage
+
+## Setup
+
+```bash
+pip install -e .                                    # from monorepo root
+aitbc config set coordinator_url http://localhost:8000
+export AITBC_API_KEY=your-key                       # or use --api-key
+```
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--url URL` | Coordinator API URL |
+| `--api-key KEY` | API key for authentication |
+| `--output table\|json\|yaml` | Output format |
+| `-v / -vv / -vvv` | Verbosity level |
+| `--debug` | Debug mode |
+
+## Command Groups
+
+| Group | Key commands |
+|-------|-------------|
+| `client` | `submit`, `status`, `list`, `cancel`, `download`, `batch-submit` |
+| `miner` | `register`, `poll`, `mine`, `earnings`, `deregister` |
+| `wallet` | `balance`, `send`, `stake`, `backup`, `multisig-create` |
+| `auth` | `login`, `logout`, `token`, `keys` |
+| `blockchain` | `status`, `blocks`, `transaction`, `validators` |
+| `marketplace` | `gpu list`, `gpu book`, `orders`, `reviews` |
+| `admin` | `status`, `jobs`, `miners`, `audit-log` |
+| `config` | `set`, `show`, `profiles`, `secrets` |
+| `monitor` | `dashboard`, `metrics`, `alerts`, `webhooks` |
+| `simulate` | `workflow`, `load-test`, `scenario` |
+
+## Client Workflow
+
+```bash
+aitbc wallet balance                                # check funds
+aitbc client submit --prompt "What is AI?"          # submit job
+aitbc client status --job-id <JOB_ID>               # check progress
+aitbc client download --job-id <JOB_ID> --output ./ # get results
+```
+
+## Miner Workflow
+
+```bash
+aitbc miner register --name gpu-1 --gpu a100 --count 4
+aitbc miner poll                                    # start accepting jobs
+aitbc wallet balance                                # check earnings
+```
+
+## Configuration
+
+Config file: `~/.aitbc/config.yaml`
+```yaml
+coordinator_url: http://localhost:8000
+api_key: your-api-key
+output_format: table
+log_level: INFO
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| Auth error | `export AITBC_API_KEY=your-key` or `aitbc auth login` |
+| Connection refused | Check coordinator: `curl http://localhost:8000/v1/health` |
+| Unknown command | Update CLI: `pip install -e .` from monorepo root |
+
+## Full Reference
+
+See [5_reference/1_cli-reference.md](../5_reference/1_cli-reference.md) for all 90+ commands with detailed options.