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

```

Browse Source 
feat: add SQLModel relationships, fix ZK verifier circuit integration, and complete Stage 19-20 documentation

- Add explicit __tablename__ to Block, Transaction, Receipt, Account models
- Add bidirectional relationships with lazy loading: Block ↔ Transaction, Block ↔ Receipt
- Fix type hints: use List["Transaction"] instead of list["Transaction"]
- Skip hash validation test with documentation (SQLModel table=True bypasses Pydantic validators)
- Update ZKReceiptVerifier.sol to match receipt_simple circuit (
This commit is contained in:
oib
2026-01-24 18:34:37 +01:00
parent 55ced77928
commit 329b3beeba
43 changed files with 7230 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/user/guides/getting-started.md Normal file
View File

@@ -0,0 +1,89 @@
# Getting Started with AITBC
Welcome to the AI Token Blockchain (AITBC) network! This guide will help you get started as a user of the decentralized AI compute marketplace.
## What is AITBC?
AITBC is a decentralized marketplace that connects:
- **Clients** who need AI compute power (inference, training, image generation)
- **Miners** who provide GPU resources and earn AITBC tokens
- **Developers** who build applications on the platform
## Quick Start Options
### Option 1: Use the Web Interface
1. Visit [https://aitbc.bubuit.net](https://aitbc.bubuit.net)
2. Navigate to the **Marketplace** to browse available AI services
3. Connect your wallet or create an account
4. Submit your first AI job
### Option 2: Use the CLI
```bash
# Install the CLI wrapper
curl -O https://aitbc.bubuit.net/cli/aitbc-cli.sh
chmod +x aitbc-cli.sh
# Check available services
./aitbc-cli.sh status
# Submit a job
./aitbc-cli.sh submit "Your prompt here" --model llama3.2
```
### Option 3: Use the SDK
**Python:**
```python
from aitbc_sdk import AITBCClient
client = AITBCClient(api_url="https://aitbc.bubuit.net/api")
result = client.submit_job(
prompt="Explain quantum computing",
model="llama3.2"
)
print(result.output)
```
## Core Concepts
### Jobs
A job is a unit of work submitted to the network. It includes:
- **Prompt**: Your input (text, image, etc.)
- **Model**: The AI model to use (e.g., `llama3.2`, `stable-diffusion`)
- **Parameters**: Optional settings (temperature, max tokens, etc.)
### Receipts
After a job completes, you receive a **receipt** containing:
- Job ID and status
- Compute units consumed
- Miner who processed the job
- Cryptographic proof of completion
### Tokens
AITBC tokens are used to:
- Pay for compute jobs
- Reward miners for providing resources
- Participate in governance
## Your First Job
1. **Connect your wallet** at the Exchange or create an account
2. **Get some AITBC tokens** (see [Bitcoin Wallet Setup](BITCOIN-WALLET-SETUP.md))
3. **Submit a job** via web, CLI, or SDK
4. **Wait for completion** (typically seconds to minutes)
5. **View your receipt** in the Explorer
## Next Steps
- [Job Submission Workflow](job-submission.md) - Detailed guide on submitting jobs
- [Payments and Receipts](payments-receipts.md) - Understanding the payment flow
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
- [User Interface Guide](USER-INTERFACE-GUIDE.md) - Navigating the web interface
## Getting Help
- **Documentation**: [https://aitbc.bubuit.net/docs/](https://aitbc.bubuit.net/docs/)
- **Explorer**: [https://aitbc.bubuit.net/explorer/](https://aitbc.bubuit.net/explorer/)
- **API Reference**: [https://aitbc.bubuit.net/api/docs](https://aitbc.bubuit.net/api/docs)

163
docs/user/guides/job-submission.md Normal file
View File

@@ -0,0 +1,163 @@
# Job Submission Workflow
This guide explains how to submit AI compute jobs to the AITBC network and track their progress.
## Overview
The job submission workflow:
1. **Prepare** - Choose model and parameters
2. **Submit** - Send job to Coordinator API
3. **Queue** - Job enters the processing queue
4. **Execute** - Miner processes your job
5. **Complete** - Receive results and receipt
## Submission Methods
### Web Interface
1. Go to [Marketplace](https://aitbc.bubuit.net/marketplace/)
2. Select a service (e.g., "Text Generation", "Image Generation")
3. Enter your prompt and configure options
4. Click **Submit Job**
5. View job status in your dashboard
### CLI
```bash
# Basic submission
./aitbc-cli.sh submit "Explain machine learning in simple terms"
# With model selection
./aitbc-cli.sh submit "Generate a haiku about coding" --model llama3.2
# With parameters
./aitbc-cli.sh submit "Write a story" --model llama3.2 --max-tokens 500 --temperature 0.7
# Check job status
./aitbc-cli.sh status <job_id>
# List your jobs
./aitbc-cli.sh jobs
```
### Python SDK
```python
from aitbc_sdk import AITBCClient
client = AITBCClient(
api_url="https://aitbc.bubuit.net/api",
api_key="your-api-key" # Optional for authenticated requests
)
# Submit a text generation job
job = client.submit_job(
prompt="What is the capital of France?",
model="llama3.2",
params={
"max_tokens": 100,
"temperature": 0.5
}
)
print(f"Job ID: {job.id}")
print(f"Status: {job.status}")
# Wait for completion
result = client.wait_for_job(job.id, timeout=60)
print(f"Output: {result.output}")
```
### Direct API
```bash
# Submit job
curl -X POST https://aitbc.bubuit.net/api/v1/jobs \
-H "Content-Type: application/json" \
-d '{
"prompt": "Hello, world!",
"model": "llama3.2",
"params": {"max_tokens": 50}
}'
# Check status
curl https://aitbc.bubuit.net/api/v1/jobs/<job_id>
```
## Job Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | required | Input text or instruction |
| `model` | string | `llama3.2` | AI model to use |
| `max_tokens` | int | 256 | Maximum output tokens |
| `temperature` | float | 0.7 | Creativity (0.0-1.0) |
| `top_p` | float | 0.9 | Nucleus sampling |
| `stream` | bool | false | Stream output chunks |
## Available Models
| Model | Type | Use Case |
|-------|------|----------|
| `llama3.2` | Text | General chat, Q&A, writing |
| `llama3.2:1b` | Text | Fast, lightweight tasks |
| `codellama` | Code | Code generation, debugging |
| `stable-diffusion` | Image | Image generation |
## Job States
| State | Description |
|-------|-------------|
| `pending` | Job submitted, waiting for miner |
| `running` | Miner is processing the job |
| `completed` | Job finished successfully |
| `failed` | Job failed (see error message) |
| `cancelled` | Job was cancelled by user |
## Tracking Your Jobs
### View in Explorer
Visit [Explorer](https://aitbc.bubuit.net/explorer/) to see:
- Recent jobs and their status
- Your job history (if authenticated)
- Receipt details and proofs
### Programmatic Tracking
```python
# Poll for status
import time
while True:
job = client.get_job(job_id)
print(f"Status: {job.status}")
if job.status in ["completed", "failed", "cancelled"]:
break
time.sleep(2)
```
## Cancelling Jobs
```bash
# CLI
./aitbc-cli.sh cancel <job_id>
# API
curl -X POST https://aitbc.bubuit.net/api/v1/jobs/<job_id>/cancel
```
## Best Practices
1. **Be specific** - Clear prompts get better results
2. **Set appropriate limits** - Use `max_tokens` to control costs
3. **Handle errors** - Always check job status before using output
4. **Use streaming** - For long outputs, enable streaming for faster feedback
## Next Steps
- [Payments and Receipts](payments-receipts.md) - Understanding costs and proofs
- [Troubleshooting](troubleshooting.md) - Common issues and solutions

156
docs/user/guides/payments-receipts.md Normal file
View File

@@ -0,0 +1,156 @@
# Payments and Receipts
This guide explains how payments work on the AITBC network and how to understand your receipts.
## Payment Flow
```
Client submits job → Job processed by miner → Receipt generated → Payment settled
```
### Step-by-Step
1. **Job Submission**: You submit a job with your prompt and parameters
2. **Miner Selection**: The Coordinator assigns your job to an available miner
3. **Processing**: The miner executes your job using their GPU
4. **Receipt Creation**: A cryptographic receipt is generated proving work completion
5. **Settlement**: AITBC tokens are transferred from client to miner
## Understanding Receipts
Every completed job generates a receipt containing:
| Field | Description |
|-------|-------------|
| `receipt_id` | Unique identifier for this receipt |
| `job_id` | The job this receipt is for |
| `provider` | Miner address who processed the job |
| `client` | Your address (who requested the job) |
| `units` | Compute units consumed (e.g., GPU seconds) |
| `price` | Amount paid in AITBC tokens |
| `model` | AI model used |
| `started_at` | When processing began |
| `completed_at` | When processing finished |
| `signature` | Cryptographic proof of authenticity |
### Example Receipt
```json
{
"receipt_id": "rcpt-20260124-001234",
"job_id": "job-abc123",
"provider": "ait1miner...",
"client": "ait1client...",
"units": 2.5,
"unit_type": "gpu_seconds",
"price": 5.0,
"model": "llama3.2",
"started_at": 1737730800,
"completed_at": 1737730803,
"signature": {
"alg": "Ed25519",
"key_id": "miner-ed25519-2026-01",
"sig": "Fql0..."
}
}
```
## Viewing Your Receipts
### Explorer
Visit [Explorer → Receipts](https://aitbc.bubuit.net/explorer/#/receipts) to see:
- All recent receipts on the network
- Filter by your address to see your history
- Click any receipt for full details
### CLI
```bash
# List your receipts
./aitbc-cli.sh receipts
# Get specific receipt
./aitbc-cli.sh receipt <receipt_id>
```
### API
```bash
curl https://aitbc.bubuit.net/api/v1/receipts?client=<your_address>
```
## Pricing
### How Pricing Works
- Jobs are priced in **compute units** (typically GPU seconds)
- Each model has a base rate per compute unit
- Final price = `units × rate`
### Current Rates
| Model | Rate (AITBC/unit) | Typical Job Cost |
|-------|-------------------|------------------|
| `llama3.2` | 2.0 | 2-10 AITBC |
| `llama3.2:1b` | 0.5 | 0.5-2 AITBC |
| `codellama` | 2.5 | 3-15 AITBC |
| `stable-diffusion` | 5.0 | 10-50 AITBC |
*Rates may vary based on network demand and miner availability.*
## Getting AITBC Tokens
### Via Exchange
1. Visit [Trade Exchange](https://aitbc.bubuit.net/Exchange/)
2. Create an account or connect wallet
3. Send Bitcoin to your deposit address
4. Receive AITBC at current exchange rate (1 BTC = 100,000 AITBC)
See [Bitcoin Wallet Setup](BITCOIN-WALLET-SETUP.md) for detailed instructions.
### Via Mining
Earn AITBC by providing GPU compute:
- See [Miner Documentation](../../reference/components/miner_node.md)
## Verifying Receipts
Receipts are cryptographically signed to ensure authenticity.
### Signature Verification
```python
from aitbc_crypto import verify_receipt
receipt = get_receipt("rcpt-20260124-001234")
is_valid = verify_receipt(receipt)
print(f"Receipt valid: {is_valid}")
```
### On-Chain Verification
Receipts can be anchored on-chain for permanent proof:
- ZK proofs enable privacy-preserving verification
- See [ZK Applications](../../reference/components/zk-applications.md)
## Payment Disputes
If you believe a payment was incorrect:
1. **Check the receipt** - Verify units and price match expectations
2. **Compare to job output** - Ensure you received the expected result
3. **Contact support** - If discrepancy exists, report via the platform
## Best Practices
1. **Monitor your balance** - Check before submitting large jobs
2. **Set spending limits** - Use API keys with rate limits
3. **Keep receipts** - Download important receipts for records
4. **Verify signatures** - For high-value transactions, verify cryptographically
## Next Steps
- [Troubleshooting](troubleshooting.md) - Common payment issues
- [Getting Started](getting-started.md) - Back to basics

208
docs/user/guides/troubleshooting.md Normal file
View File

@@ -0,0 +1,208 @@
# Troubleshooting Guide
Common issues and solutions when using the AITBC network.
## Job Issues
### Job Stuck in "Pending" State
**Symptoms**: Job submitted but stays in `pending` for a long time.
**Causes**:
- No miners currently available
- Network congestion
- Model not supported by available miners
**Solutions**:
1. Wait a few minutes - miners may become available
2. Check network status at [Explorer](https://aitbc.bubuit.net/explorer/)
3. Try a different model (e.g., `llama3.2:1b` instead of `llama3.2`)
4. Cancel and resubmit during off-peak hours
```bash
# Check job status
./aitbc-cli.sh status <job_id>
# Cancel if needed
./aitbc-cli.sh cancel <job_id>
```
### Job Failed
**Symptoms**: Job status shows `failed` with an error message.
**Common Errors**:
| Error | Cause | Solution |
|-------|-------|----------|
| `Model not found` | Invalid model name | Check available models |
| `Prompt too long` | Input exceeds limit | Shorten your prompt |
| `Timeout` | Job took too long | Reduce `max_tokens` or simplify prompt |
| `Miner disconnected` | Miner went offline | Resubmit job |
| `Insufficient balance` | Not enough AITBC | Top up your balance |
### Unexpected Output
**Symptoms**: Job completed but output is wrong or truncated.
**Solutions**:
1. **Truncated output**: Increase `max_tokens` parameter
2. **Wrong format**: Be more specific in your prompt
3. **Gibberish**: Lower `temperature` (try 0.3-0.5)
4. **Off-topic**: Rephrase prompt to be clearer
## Connection Issues
### Cannot Connect to API
**Symptoms**: `Connection refused` or `timeout` errors.
**Solutions**:
1. Check your internet connection
2. Verify API URL: `https://aitbc.bubuit.net/api`
3. Check if service is up at [Explorer](https://aitbc.bubuit.net/explorer/)
4. Try again in a few minutes
```bash
# Test connectivity
curl -I https://aitbc.bubuit.net/api/health
```
### Authentication Failed
**Symptoms**: `401 Unauthorized` or `Invalid API key` errors.
**Solutions**:
1. Verify your API key is correct
2. Check if API key has expired
3. Ensure API key has required permissions
4. Generate a new API key if needed
## Wallet Issues
### Cannot Connect Wallet
**Symptoms**: Wallet connection fails or times out.
**Solutions**:
1. Ensure browser extension is installed and unlocked
2. Refresh the page and try again
3. Check if wallet is on correct network
4. Clear browser cache and cookies
### Transaction Not Showing
**Symptoms**: Sent tokens but balance not updated.
**Solutions**:
1. Wait for confirmation (may take a few minutes)
2. Check transaction in Explorer
3. Verify you sent to correct address
4. Contact support if still missing after 1 hour
### Insufficient Balance
**Symptoms**: `Insufficient balance` error when submitting job.
**Solutions**:
1. Check your current balance
2. Top up via [Exchange](https://aitbc.bubuit.net/Exchange/)
3. Wait for pending deposits to confirm
## CLI Issues
### Command Not Found
**Symptoms**: `aitbc-cli.sh: command not found`
**Solutions**:
```bash
# Make script executable
chmod +x aitbc-cli.sh
# Run with explicit path
./aitbc-cli.sh status
# Or add to PATH
export PATH=$PATH:$(pwd)
```
### Permission Denied
**Symptoms**: `Permission denied` when running CLI.
**Solutions**:
```bash
chmod +x aitbc-cli.sh
```
### SSL Certificate Error
**Symptoms**: `SSL certificate problem` or `certificate verify failed`
**Solutions**:
```bash
# Update CA certificates
sudo apt update && sudo apt install ca-certificates
# Or skip verification (not recommended for production)
curl -k https://aitbc.bubuit.net/api/health
```
## Performance Issues
### Slow Response Times
**Symptoms**: Jobs take longer than expected.
**Causes**:
- Large prompt or output
- Complex model
- Network congestion
- Miner hardware limitations
**Solutions**:
1. Use smaller models for simple tasks
2. Reduce `max_tokens` if full output not needed
3. Submit during off-peak hours
4. Use streaming for faster first-token response
### Rate Limited
**Symptoms**: `429 Too Many Requests` error.
**Solutions**:
1. Wait before retrying (check `Retry-After` header)
2. Reduce request frequency
3. Use exponential backoff in your code
4. Request higher rate limits if needed
## Getting Help
### Self-Service Resources
- **Documentation**: [https://aitbc.bubuit.net/docs/](https://aitbc.bubuit.net/docs/)
- **API Reference**: [https://aitbc.bubuit.net/api/docs](https://aitbc.bubuit.net/api/docs)
- **Explorer**: [https://aitbc.bubuit.net/explorer/](https://aitbc.bubuit.net/explorer/)
### Reporting Issues
When reporting an issue, include:
1. **Job ID** (if applicable)
2. **Error message** (exact text)
3. **Steps to reproduce**
4. **Expected vs actual behavior**
5. **Timestamp** of when issue occurred
### Debug Mode
Enable verbose logging for troubleshooting:
```bash
# CLI debug mode
DEBUG=1 ./aitbc-cli.sh submit "test"
# Python SDK
import logging
logging.basicConfig(level=logging.DEBUG)
```