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
This commit is contained in:
oib
31
docs/8_development/0_index.md
Normal file
31
docs/8_development/0_index.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Developer Documentation
|
||||
|
||||
Build on the AITBC platform: APIs, SDKs, and contribution guides.
|
||||
|
||||
## Reading Order
|
||||
|
||||
| # | File | What you learn |
|
||||
|---|------|----------------|
|
||||
| 1 | [1_overview.md](./1_overview.md) | Platform architecture for developers |
|
||||
| 2 | [2_setup.md](./2_setup.md) | Dev environment setup |
|
||||
| 3 | [3_contributing.md](./3_contributing.md) | How to contribute |
|
||||
| 4 | [4_examples.md](./4_examples.md) | Code examples |
|
||||
| 5 | [5_developer-guide.md](./5_developer-guide.md) | SDKs, APIs, bounties |
|
||||
| 6 | [6_api-authentication.md](./6_api-authentication.md) | Auth flow and tokens |
|
||||
| 7 | [7_payments-receipts.md](./7_payments-receipts.md) | Payment system internals |
|
||||
| 8 | [8_blockchain-node-deployment.md](./8_blockchain-node-deployment.md) | Deploy a node |
|
||||
| 9 | [9_block-production-runbook.md](./9_block-production-runbook.md) | Block production ops |
|
||||
| 10 | [10_bitcoin-wallet-setup.md](./10_bitcoin-wallet-setup.md) | BTC wallet integration |
|
||||
| 11 | [11_marketplace-backend-analysis.md](./11_marketplace-backend-analysis.md) | Marketplace internals |
|
||||
| 12 | [12_marketplace-extensions.md](./12_marketplace-extensions.md) | Build marketplace plugins |
|
||||
| 13 | [13_user-interface-guide.md](./13_user-interface-guide.md) | Trade exchange UI |
|
||||
| 14 | [14_user-management-setup.md](./14_user-management-setup.md) | User management system |
|
||||
| 15 | [15_ecosystem-initiatives.md](./15_ecosystem-initiatives.md) | Ecosystem roadmap |
|
||||
| 16 | [16_local-assets.md](./16_local-assets.md) | Local asset management |
|
||||
| 17 | [17_windsurf-testing.md](./17_windsurf-testing.md) | Testing with Windsurf |
|
||||
|
||||
## Related
|
||||
|
||||
- [Architecture](../6_architecture/) — System design docs
|
||||
- [Deployment](../7_deployment/) — Production deployment guides
|
||||
- [CLI Reference](../5_reference/1_cli-reference.md) — Full CLI docs
|
||||
141
docs/8_development/10_bitcoin-wallet-setup.md
Normal file
141
docs/8_development/10_bitcoin-wallet-setup.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Bitcoin Wallet Integration for AITBC Trade Exchange
|
||||
|
||||
## Overview
|
||||
The AITBC Trade Exchange now supports Bitcoin payments for purchasing AITBC tokens. Users can send Bitcoin to a generated address and receive AITBC tokens after confirmation.
|
||||
|
||||
## Current Implementation
|
||||
|
||||
### Frontend Features
|
||||
- **Payment Request Generation**: Users enter the amount of AITBC they want to buy
|
||||
- **Dynamic QR Code**: A QR code is generated with the Bitcoin address and amount
|
||||
- **Payment Monitoring**: The system automatically checks for payment confirmation
|
||||
- **Real-time Updates**: Users see payment status updates in real-time
|
||||
|
||||
### Backend Features
|
||||
- **Payment API**: `/api/exchange/create-payment` creates payment requests
|
||||
- **Status Tracking**: `/api/exchange/payment-status/{id}` checks payment status
|
||||
- **Exchange Rates**: `/api/exchange/rates` provides current BTC/AITBC rates
|
||||
|
||||
## Configuration
|
||||
|
||||
### Bitcoin Settings
|
||||
```python
|
||||
BITCOIN_CONFIG = {
|
||||
'testnet': True, # Using Bitcoin testnet
|
||||
'main_address': 'tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
|
||||
'exchange_rate': 100000, # 1 BTC = 100,000 AITBC
|
||||
'min_confirmations': 1,
|
||||
'payment_timeout': 3600 # 1 hour expiry
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
BITCOIN_TESTNET=true
|
||||
BITCOIN_ADDRESS=tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
|
||||
BITCOIN_PRIVATE_KEY=your_private_key
|
||||
BLOCKCHAIN_API_KEY=your_blockchain_api_key
|
||||
WEBHOOK_SECRET=your_webhook_secret
|
||||
MIN_CONFIRMATIONS=1
|
||||
BTC_TO_AITBC_RATE=100000
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **User Initiates Purchase**
|
||||
- Enters AITBC amount or BTC amount
|
||||
- System calculates the conversion
|
||||
- Creates a payment request
|
||||
|
||||
2. **Payment Address Generated**
|
||||
- Unique payment address (demo: uses fixed address)
|
||||
- QR code generated with `bitcoin:` URI
|
||||
- Payment details displayed
|
||||
|
||||
3. **Payment Monitoring**
|
||||
- System checks blockchain every 30 seconds
|
||||
- Updates payment status automatically
|
||||
- Notifies user when confirmed
|
||||
|
||||
4. **Token Minting**
|
||||
- Upon confirmation, AITBC tokens are minted
|
||||
- Tokens credited to user's wallet
|
||||
- Transaction recorded
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Current (Demo) Implementation
|
||||
- Uses a fixed Bitcoin testnet address
|
||||
- No private key integration
|
||||
- Manual payment confirmation for demo
|
||||
|
||||
### Production Requirements
|
||||
- HD wallet for unique address generation
|
||||
- Blockchain API integration (Blockstream, BlockCypher, etc.)
|
||||
- Webhook signatures for payment notifications
|
||||
- Multi-signature wallet support
|
||||
- Cold storage for funds
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Create Payment Request
|
||||
```http
|
||||
POST /api/exchange/create-payment
|
||||
{
|
||||
"user_id": "user_wallet_address",
|
||||
"aitbc_amount": 1000,
|
||||
"btc_amount": 0.01
|
||||
}
|
||||
```
|
||||
|
||||
### Check Payment Status
|
||||
```http
|
||||
GET /api/exchange/payment-status/{payment_id}
|
||||
```
|
||||
|
||||
### Get Exchange Rates
|
||||
```http
|
||||
GET /api/exchange/rates
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Testnet Bitcoin
|
||||
- Use Bitcoin testnet for testing
|
||||
- Get testnet Bitcoin from faucets:
|
||||
- https://testnet-faucet.mempool.co/
|
||||
- https://coinfaucet.eu/en/btc-testnet/
|
||||
|
||||
### Demo Mode
|
||||
- Currently running in demo mode
|
||||
- Payments are simulated
|
||||
- Use admin API to manually confirm payments
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Production Wallet Integration**
|
||||
- Implement HD wallet (BIP32/BIP44)
|
||||
- Connect to mainnet/testnet
|
||||
- Secure private key storage
|
||||
|
||||
2. **Blockchain API Integration**
|
||||
- Real-time transaction monitoring
|
||||
- Webhook implementation
|
||||
- Confirmation tracking
|
||||
|
||||
3. **Enhanced Security**
|
||||
- Multi-signature support
|
||||
- Cold storage integration
|
||||
- Audit logging
|
||||
|
||||
4. **User Experience**
|
||||
- Payment history
|
||||
- Refund mechanism
|
||||
- Email notifications
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Check the logs: `journalctl -u aitbc-coordinator -f`
|
||||
- API documentation: `https://aitbc.bubuit.net/api/docs`
|
||||
- Admin panel: `https://aitbc.bubuit.net/admin/stats`
|
||||
267
docs/8_development/11_marketplace-backend-analysis.md
Normal file
267
docs/8_development/11_marketplace-backend-analysis.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Marketplace Backend Analysis
|
||||
|
||||
## Current Implementation Status
|
||||
|
||||
### ✅ Implemented Features
|
||||
|
||||
#### 1. Basic Marketplace Offers
|
||||
- **Endpoint**: `GET /marketplace/offers`
|
||||
- **Service**: `MarketplaceService.list_offers()`
|
||||
- **Status**: ✅ Implemented (returns mock data)
|
||||
- **Notes**: Returns hardcoded mock offers, not from database
|
||||
|
||||
#### 2. Marketplace Statistics
|
||||
- **Endpoint**: `GET /marketplace/stats`
|
||||
- **Service**: `MarketplaceService.get_stats()`
|
||||
- **Status**: ✅ Implemented
|
||||
- **Features**:
|
||||
- Total offers count
|
||||
- Open capacity
|
||||
- Average price
|
||||
- Active bids count
|
||||
|
||||
#### 3. Marketplace Bids
|
||||
- **Endpoint**: `POST /marketplace/bids`
|
||||
- **Service**: `MarketplaceService.create_bid()`
|
||||
- **Status**: ✅ Implemented
|
||||
- **Features**: Create bids with provider, capacity, price, and notes
|
||||
|
||||
#### 4. Miner Offer Synchronization
|
||||
- **Endpoint**: `POST /marketplace/sync-offers`
|
||||
- **Service**: Creates offers from registered miners
|
||||
- **Status**: ✅ Implemented (admin only)
|
||||
- **Features**:
|
||||
- Syncs online miners to marketplace offers
|
||||
- Extracts GPU capabilities from miner attributes
|
||||
- Creates offers with pricing, GPU model, memory, etc.
|
||||
|
||||
#### 5. Miner Offers List
|
||||
- **Endpoint**: `GET /marketplace/miner-offers`
|
||||
- **Service**: Lists offers created from miners
|
||||
- **Status**: ✅ Implemented
|
||||
- **Features**: Returns offers with detailed GPU information
|
||||
|
||||
### ❌ Missing Features (Expected by CLI)
|
||||
|
||||
#### 1. GPU-Specific Endpoints
|
||||
The CLI expects a `/v1/marketplace/gpu/` prefix for all operations, but these are **NOT IMPLEMENTED**:
|
||||
|
||||
- `POST /v1/marketplace/gpu/register` - Register GPU in marketplace
|
||||
- `GET /v1/marketplace/gpu/list` - List available GPUs
|
||||
- `GET /v1/marketplace/gpu/{gpu_id}` - Get GPU details
|
||||
- `POST /v1/marketplace/gpu/{gpu_id}/book` - Book/reserve a GPU
|
||||
- `POST /v1/marketplace/gpu/{gpu_id}/release` - Release a booked GPU
|
||||
- `GET /v1/marketplace/gpu/{gpu_id}/reviews` - Get GPU reviews
|
||||
- `POST /v1/marketplace/gpu/{gpu_id}/reviews` - Add GPU review
|
||||
|
||||
#### 2. GPU Booking System
|
||||
- **Status**: ❌ Not implemented
|
||||
- **Missing Features**:
|
||||
- GPU reservation/booking logic
|
||||
- Booking duration tracking
|
||||
- Booking status management
|
||||
- Automatic release after timeout
|
||||
|
||||
#### 3. GPU Reviews System
|
||||
- **Status**: ❌ Not implemented
|
||||
- **Missing Features**:
|
||||
- Review storage and retrieval
|
||||
- Rating aggregation
|
||||
- Review moderation
|
||||
- Review-per-gpu association
|
||||
|
||||
#### 4. GPU Registry
|
||||
- **Status**: ❌ Not implemented
|
||||
- **Missing Features**:
|
||||
- Individual GPU registration
|
||||
- GPU specifications storage
|
||||
- GPU status tracking (available, booked, offline)
|
||||
- GPU health monitoring
|
||||
|
||||
#### 5. Order Management
|
||||
- **Status**: ❌ Not implemented
|
||||
- **CLI expects**: `GET /v1/marketplace/orders`
|
||||
- **Missing Features**:
|
||||
- Order creation from bookings
|
||||
- Order tracking
|
||||
- Order history
|
||||
- Order status updates
|
||||
|
||||
#### 6. Pricing Information
|
||||
- **Status**: ❌ Not implemented
|
||||
- **CLI expects**: `GET /v1/marketplace/pricing/{model}`
|
||||
- **Missing Features**:
|
||||
- Model-specific pricing
|
||||
- Dynamic pricing based on demand
|
||||
- Historical pricing data
|
||||
- Price recommendations
|
||||
|
||||
### 🔧 Data Model Issues
|
||||
|
||||
#### 1. MarketplaceOffer Model Limitations
|
||||
Current model lacks GPU-specific fields:
|
||||
```python
|
||||
class MarketplaceOffer(SQLModel, table=True):
|
||||
id: str
|
||||
provider: str # Miner ID
|
||||
capacity: int # Number of concurrent jobs
|
||||
price: float # Price per hour
|
||||
sla: str
|
||||
status: str # open, closed, etc.
|
||||
created_at: datetime
|
||||
attributes: dict # Contains GPU info but not structured
|
||||
```
|
||||
|
||||
**Missing GPU-specific fields**:
|
||||
- `gpu_id`: Unique GPU identifier
|
||||
- `gpu_model`: GPU model name
|
||||
- `gpu_memory`: GPU memory in GB
|
||||
- `gpu_status`: available, booked, offline
|
||||
- `booking_expires`: When current booking expires
|
||||
- `total_bookings`: Number of times booked
|
||||
- `average_rating`: Aggregated review rating
|
||||
|
||||
#### 2. No Booking/Order Models
|
||||
Missing models for:
|
||||
- `GPUBooking`: Track GPU reservations
|
||||
- `GPUOrder`: Track completed GPU usage
|
||||
- `GPUReview`: Store GPU reviews
|
||||
- `GPUPricing`: Store pricing tiers
|
||||
|
||||
### 📊 API Endpoint Comparison
|
||||
|
||||
| CLI Command | Expected Endpoint | Implemented | Status |
|
||||
|-------------|------------------|-------------|---------|
|
||||
| `aitbc marketplace gpu register` | `POST /v1/marketplace/gpu/register` | ❌ | Missing |
|
||||
| `aitbc marketplace gpu list` | `GET /v1/marketplace/gpu/list` | ❌ | Missing |
|
||||
| `aitbc marketplace gpu details` | `GET /v1/marketplace/gpu/{id}` | ❌ | Missing |
|
||||
| `aitbc marketplace gpu book` | `POST /v1/marketplace/gpu/{id}/book` | ❌ | Missing |
|
||||
| `aitbc marketplace gpu release` | `POST /v1/marketplace/gpu/{id}/release` | ❌ | Missing |
|
||||
| `aitbc marketplace reviews` | `GET /v1/marketplace/gpu/{id}/reviews` | ❌ | Missing |
|
||||
| `aitbc marketplace review add` | `POST /v1/marketplace/gpu/{id}/reviews` | ❌ | Missing |
|
||||
| `aitbc marketplace orders list` | `GET /v1/marketplace/orders` | ❌ | Missing |
|
||||
| `aitbc marketplace pricing` | `GET /v1/marketplace/pricing/{model}` | ❌ | Missing |
|
||||
|
||||
### 🚀 Recommended Implementation Plan
|
||||
|
||||
#### Phase 1: Core GPU Marketplace
|
||||
1. **Create GPU Registry Model**:
|
||||
```python
|
||||
class GPURegistry(SQLModel, table=True):
|
||||
gpu_id: str = Field(primary_key=True)
|
||||
miner_id: str
|
||||
gpu_model: str
|
||||
gpu_memory_gb: int
|
||||
cuda_version: str
|
||||
status: str # available, booked, offline
|
||||
current_booking_id: Optional[str] = None
|
||||
booking_expires: Optional[datetime] = None
|
||||
attributes: dict = Field(default_factory=dict)
|
||||
```
|
||||
|
||||
2. **Implement GPU Endpoints**:
|
||||
- Add `/v1/marketplace/gpu/` router
|
||||
- Implement all CRUD operations for GPUs
|
||||
- Add booking/unbooking logic
|
||||
|
||||
3. **Create Booking System**:
|
||||
```python
|
||||
class GPUBooking(SQLModel, table=True):
|
||||
booking_id: str = Field(primary_key=True)
|
||||
gpu_id: str
|
||||
client_id: str
|
||||
job_id: Optional[str]
|
||||
duration_hours: float
|
||||
start_time: datetime
|
||||
end_time: datetime
|
||||
total_cost: float
|
||||
status: str # active, completed, cancelled
|
||||
```
|
||||
|
||||
#### Phase 2: Reviews and Ratings
|
||||
1. **Review System**:
|
||||
```python
|
||||
class GPUReview(SQLModel, table=True):
|
||||
review_id: str = Field(primary_key=True)
|
||||
gpu_id: str
|
||||
client_id: str
|
||||
rating: int = Field(ge=1, le=5)
|
||||
comment: str
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
2. **Rating Aggregation**:
|
||||
- Add `average_rating` to GPURegistry
|
||||
- Update rating on each new review
|
||||
- Implement rating history tracking
|
||||
|
||||
#### Phase 3: Orders and Pricing
|
||||
1. **Order Management**:
|
||||
```python
|
||||
class GPUOrder(SQLModel, table=True):
|
||||
order_id: str = Field(primary_key=True)
|
||||
booking_id: str
|
||||
client_id: str
|
||||
gpu_id: str
|
||||
status: str
|
||||
created_at: datetime
|
||||
completed_at: Optional[datetime]
|
||||
```
|
||||
|
||||
2. **Dynamic Pricing**:
|
||||
```python
|
||||
class GPUPricing(SQLModel, table=True):
|
||||
id: str = Field(primary_key=True)
|
||||
model_name: str
|
||||
base_price: float
|
||||
current_price: float
|
||||
demand_multiplier: float
|
||||
updated_at: datetime
|
||||
```
|
||||
|
||||
### 🔍 Integration Points
|
||||
|
||||
#### 1. Miner Registration
|
||||
- When miners register, automatically create GPU entries
|
||||
- Sync GPU capabilities from miner registration
|
||||
- Update GPU status based on miner heartbeat
|
||||
|
||||
#### 2. Job Assignment
|
||||
- Check GPU availability before job assignment
|
||||
- Book GPU for job duration
|
||||
- Release GPU on job completion or failure
|
||||
|
||||
#### 3. Billing Integration
|
||||
- Calculate costs from booking duration
|
||||
- Create orders from completed bookings
|
||||
- Handle refunds for early releases
|
||||
|
||||
### 📝 Implementation Notes
|
||||
|
||||
1. **API Versioning**: Use `/v1/marketplace/gpu/` as expected by CLI
|
||||
2. **Authentication**: Use existing API key system
|
||||
3. **Error Handling**: Follow existing error patterns
|
||||
4. **Metrics**: Add Prometheus metrics for GPU operations
|
||||
5. **Testing**: Create comprehensive test suite
|
||||
6. **Documentation**: Update OpenAPI specs
|
||||
|
||||
### 🎯 Priority Matrix
|
||||
|
||||
| Feature | Priority | Effort | Impact |
|
||||
|---------|----------|--------|--------|
|
||||
| GPU Registry | High | Medium | High |
|
||||
| GPU Booking | High | High | High |
|
||||
| GPU List/Details | High | Low | High |
|
||||
| Reviews System | Medium | Medium | Medium |
|
||||
| Order Management | Medium | High | Medium |
|
||||
| Dynamic Pricing | Low | High | Low |
|
||||
|
||||
### 💡 Quick Win
|
||||
|
||||
The fastest way to make the CLI work is to:
|
||||
1. Create a new router `/v1/marketplace/gpu/`
|
||||
2. Implement basic endpoints that return mock data
|
||||
3. Map existing marketplace offers to GPU format
|
||||
4. Add simple in-memory booking tracking
|
||||
|
||||
This would allow the CLI to function while the full backend is developed.
|
||||
631
docs/8_development/12_marketplace-extensions.md
Normal file
631
docs/8_development/12_marketplace-extensions.md
Normal file
@@ -0,0 +1,631 @@
|
||||
# Building Marketplace Extensions in AITBC
|
||||
|
||||
This tutorial shows how to extend the AITBC marketplace with custom features, plugins, and integrations.
|
||||
|
||||
## Overview
|
||||
|
||||
The AITBC marketplace is designed to be extensible. You can add:
|
||||
- Custom auction types
|
||||
- Specialized service categories
|
||||
- Advanced filtering and search
|
||||
- Integration with external systems
|
||||
- Custom pricing models
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 16+
|
||||
- AITBC marketplace source code
|
||||
- Understanding of React/TypeScript
|
||||
- API development experience
|
||||
|
||||
## Step 1: Create a Custom Auction Type
|
||||
|
||||
Let's create a Dutch auction extension:
|
||||
|
||||
```typescript
|
||||
// src/extensions/DutchAuction.ts
|
||||
import { Auction, Bid, MarketplacePlugin } from '../types';
|
||||
|
||||
interface DutchAuctionConfig {
|
||||
startPrice: number;
|
||||
reservePrice: number;
|
||||
decrementRate: number;
|
||||
decrementInterval: number; // in seconds
|
||||
}
|
||||
|
||||
export class DutchAuction implements MarketplacePlugin {
|
||||
config: DutchAuctionConfig;
|
||||
currentPrice: number;
|
||||
lastDecrement: number;
|
||||
|
||||
constructor(config: DutchAuctionConfig) {
|
||||
this.config = config;
|
||||
this.currentPrice = config.startPrice;
|
||||
this.lastDecrement = Date.now();
|
||||
}
|
||||
|
||||
async updatePrice(): Promise<void> {
|
||||
const now = Date.now();
|
||||
const elapsed = (now - this.lastDecrement) / 1000;
|
||||
|
||||
if (elapsed >= this.config.decrementInterval) {
|
||||
const decrements = Math.floor(elapsed / this.config.decrementInterval);
|
||||
this.currentPrice = Math.max(
|
||||
this.config.reservePrice,
|
||||
this.currentPrice - (decrements * this.config.decrementRate)
|
||||
);
|
||||
this.lastDecrement = now;
|
||||
}
|
||||
}
|
||||
|
||||
async validateBid(bid: Bid): Promise<boolean> {
|
||||
await this.updatePrice();
|
||||
return bid.amount >= this.currentPrice;
|
||||
}
|
||||
|
||||
async getCurrentState(): Promise<any> {
|
||||
await this.updatePrice();
|
||||
return {
|
||||
type: 'dutch',
|
||||
currentPrice: this.currentPrice,
|
||||
nextDecrement: this.config.decrementInterval -
|
||||
((Date.now() - this.lastDecrement) / 1000)
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Register the Extension
|
||||
|
||||
```typescript
|
||||
// src/extensions/index.ts
|
||||
import { DutchAuction } from './DutchAuction';
|
||||
import { MarketplaceRegistry } from '../core/MarketplaceRegistry';
|
||||
|
||||
const registry = new MarketplaceRegistry();
|
||||
|
||||
// Register Dutch auction
|
||||
registry.registerAuctionType('dutch', DutchAuction, {
|
||||
defaultConfig: {
|
||||
startPrice: 1000,
|
||||
reservePrice: 100,
|
||||
decrementRate: 10,
|
||||
decrementInterval: 60
|
||||
},
|
||||
validation: {
|
||||
startPrice: { type: 'number', min: 0 },
|
||||
reservePrice: { type: 'number', min: 0 },
|
||||
decrementRate: { type: 'number', min: 0 },
|
||||
decrementInterval: { type: 'number', min: 1 }
|
||||
}
|
||||
});
|
||||
|
||||
export default registry;
|
||||
```
|
||||
|
||||
## Step 3: Create UI Components
|
||||
|
||||
```tsx
|
||||
// src/components/DutchAuctionCard.tsx
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import { Card, Button, Progress, Typography } from 'antd';
|
||||
import { useMarketplace } from '../hooks/useMarketplace';
|
||||
|
||||
const { Title, Text } = Typography;
|
||||
|
||||
interface DutchAuctionCardProps {
|
||||
auction: any;
|
||||
}
|
||||
|
||||
export const DutchAuctionCard: React.FC<DutchAuctionCardProps> = ({ auction }) => {
|
||||
const [currentState, setCurrentState] = useState<any>(null);
|
||||
const [timeLeft, setTimeLeft] = useState<number>(0);
|
||||
const { placeBid } = useMarketplace();
|
||||
|
||||
useEffect(() => {
|
||||
const updateState = async () => {
|
||||
const state = await auction.getCurrentState();
|
||||
setCurrentState(state);
|
||||
setTimeLeft(state.nextDecrement);
|
||||
};
|
||||
|
||||
updateState();
|
||||
const interval = setInterval(updateState, 1000);
|
||||
|
||||
return () => clearInterval(interval);
|
||||
}, [auction]);
|
||||
|
||||
const handleBid = async () => {
|
||||
try {
|
||||
await placeBid(auction.id, currentState.currentPrice);
|
||||
} catch (error) {
|
||||
console.error('Bid failed:', error);
|
||||
}
|
||||
};
|
||||
|
||||
if (!currentState) return <div>Loading...</div>;
|
||||
|
||||
const priceProgress =
|
||||
((currentState.currentPrice - auction.config.reservePrice) /
|
||||
(auction.config.startPrice - auction.config.reservePrice)) * 100;
|
||||
|
||||
return (
|
||||
<Card title={auction.title} extra={`Auction #${auction.id}`}>
|
||||
<div className="mb-4">
|
||||
<Title level={4}>Current Price: {currentState.currentPrice} AITBC</Title>
|
||||
<Progress
|
||||
percent={100 - priceProgress}
|
||||
status="active"
|
||||
format={() => `${timeLeft}s until next drop`}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div className="flex justify-between items-center">
|
||||
<Text type="secondary">
|
||||
Reserve Price: {auction.config.reservePrice} AITBC
|
||||
</Text>
|
||||
<Button
|
||||
type="primary"
|
||||
onClick={handleBid}
|
||||
disabled={currentState.currentPrice <= auction.config.reservePrice}
|
||||
>
|
||||
Buy Now
|
||||
</Button>
|
||||
</div>
|
||||
</Card>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Step 4: Add Backend API Support
|
||||
|
||||
```python
|
||||
# apps/coordinator-api/src/app/routers/marketplace_extensions.py
|
||||
from fastapi import APIRouter, Depends, HTTPException
|
||||
from pydantic import BaseModel
|
||||
from typing import Dict, Any, List
|
||||
import asyncio
|
||||
|
||||
router = APIRouter(prefix="/marketplace/extensions", tags=["marketplace-extensions"])
|
||||
|
||||
class DutchAuctionRequest(BaseModel):
|
||||
title: str
|
||||
description: str
|
||||
start_price: float
|
||||
reserve_price: float
|
||||
decrement_rate: float
|
||||
decrement_interval: int
|
||||
|
||||
class DutchAuctionState(BaseModel):
|
||||
auction_id: str
|
||||
current_price: float
|
||||
next_decrement: int
|
||||
total_bids: int
|
||||
|
||||
@router.post("/dutch-auction/create")
|
||||
async def create_dutch_auction(request: DutchAuctionRequest) -> Dict[str, str]:
|
||||
"""Create a new Dutch auction."""
|
||||
|
||||
# Validate auction parameters
|
||||
if request.reserve_price >= request.start_price:
|
||||
raise HTTPException(400, "Reserve price must be less than start price")
|
||||
|
||||
# Create auction in database
|
||||
auction_id = await marketplace_service.create_extension_auction(
|
||||
type="dutch",
|
||||
config=request.dict()
|
||||
)
|
||||
|
||||
# Start price decrement task
|
||||
asyncio.create_task(start_price_decrement(auction_id))
|
||||
|
||||
return {"auction_id": auction_id}
|
||||
|
||||
@router.get("/dutch-auction/{auction_id}/state")
|
||||
async def get_dutch_auction_state(auction_id: str) -> DutchAuctionState:
|
||||
"""Get current state of a Dutch auction."""
|
||||
|
||||
auction = await marketplace_service.get_auction(auction_id)
|
||||
if not auction or auction.type != "dutch":
|
||||
raise HTTPException(404, "Dutch auction not found")
|
||||
|
||||
current_price = calculate_current_price(auction)
|
||||
next_decrement = calculate_next_decrement(auction)
|
||||
|
||||
return DutchAuctionState(
|
||||
auction_id=auction_id,
|
||||
current_price=current_price,
|
||||
next_decrement=next_decrement,
|
||||
total_bids=auction.bid_count
|
||||
)
|
||||
|
||||
async def start_price_decrement(auction_id: str):
|
||||
"""Background task to decrement auction price."""
|
||||
while True:
|
||||
await asyncio.sleep(60) # Check every minute
|
||||
|
||||
auction = await marketplace_service.get_auction(auction_id)
|
||||
if not auction or auction.status != "active":
|
||||
break
|
||||
|
||||
new_price = calculate_current_price(auction)
|
||||
await marketplace_service.update_auction_price(auction_id, new_price)
|
||||
|
||||
if new_price <= auction.config["reserve_price"]:
|
||||
await marketplace_service.close_auction(auction_id)
|
||||
break
|
||||
```
|
||||
|
||||
## Step 5: Add Custom Service Category
|
||||
|
||||
```typescript
|
||||
// src/extensions/ServiceCategories.ts
|
||||
export interface ServiceCategory {
|
||||
id: string;
|
||||
name: string;
|
||||
icon: string;
|
||||
description: string;
|
||||
requirements: ServiceRequirement[];
|
||||
pricing: PricingModel;
|
||||
}
|
||||
|
||||
export interface ServiceRequirement {
|
||||
type: 'gpu' | 'cpu' | 'memory' | 'storage';
|
||||
minimum: number;
|
||||
recommended: number;
|
||||
unit: string;
|
||||
}
|
||||
|
||||
export interface PricingModel {
|
||||
type: 'fixed' | 'hourly' | 'per-unit';
|
||||
basePrice: number;
|
||||
unitPrice?: number;
|
||||
}
|
||||
|
||||
export const AI_INFERENCE_CATEGORY: ServiceCategory = {
|
||||
id: 'ai-inference',
|
||||
name: 'AI Inference',
|
||||
icon: 'brain',
|
||||
description: 'Large language model and neural network inference',
|
||||
requirements: [
|
||||
{ type: 'gpu', minimum: 8, recommended: 24, unit: 'GB' },
|
||||
{ type: 'memory', minimum: 16, recommended: 64, unit: 'GB' },
|
||||
{ type: 'cpu', minimum: 4, recommended: 16, unit: 'cores' }
|
||||
],
|
||||
pricing: {
|
||||
type: 'hourly',
|
||||
basePrice: 10,
|
||||
unitPrice: 0.5
|
||||
}
|
||||
};
|
||||
|
||||
// Category registry
|
||||
export const SERVICE_CATEGORIES: Record<string, ServiceCategory> = {
|
||||
'ai-inference': AI_INFERENCE_CATEGORY,
|
||||
'video-rendering': {
|
||||
id: 'video-rendering',
|
||||
name: 'Video Rendering',
|
||||
icon: 'video',
|
||||
description: 'High-quality video rendering and encoding',
|
||||
requirements: [
|
||||
{ type: 'gpu', minimum: 12, recommended: 24, unit: 'GB' },
|
||||
{ type: 'memory', minimum: 32, recommended: 128, unit: 'GB' },
|
||||
{ type: 'storage', minimum: 100, recommended: 1000, unit: 'GB' }
|
||||
],
|
||||
pricing: {
|
||||
type: 'per-unit',
|
||||
basePrice: 5,
|
||||
unitPrice: 0.1
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Step 6: Create Advanced Search Filters
|
||||
|
||||
```tsx
|
||||
// src/components/AdvancedSearch.tsx
|
||||
import React, { useState } from 'react';
|
||||
import { Select, Slider, Input, Button, Space } from 'antd';
|
||||
import { SERVICE_CATEGORIES } from '../extensions/ServiceCategories';
|
||||
|
||||
const { Option } = Select;
|
||||
const { Search } = Input;
|
||||
|
||||
interface SearchFilters {
|
||||
category?: string;
|
||||
priceRange: [number, number];
|
||||
gpuMemory: [number, number];
|
||||
providerRating: number;
|
||||
}
|
||||
|
||||
export const AdvancedSearch: React.FC<{
|
||||
onSearch: (filters: SearchFilters) => void;
|
||||
}> = ({ onSearch }) => {
|
||||
const [filters, setFilters] = useState<SearchFilters>({
|
||||
priceRange: [0, 1000],
|
||||
gpuMemory: [0, 24],
|
||||
providerRating: 0
|
||||
});
|
||||
|
||||
const handleSearch = () => {
|
||||
onSearch(filters);
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="p-4 bg-gray-50 rounded-lg">
|
||||
<Space direction="vertical" className="w-full">
|
||||
<Search
|
||||
placeholder="Search services..."
|
||||
onSearch={(value) => setFilters({ ...filters, query: value })}
|
||||
style={{ width: '100%' }}
|
||||
/>
|
||||
|
||||
<Select
|
||||
placeholder="Select category"
|
||||
style={{ width: '100%' }}
|
||||
onChange={(value) => setFilters({ ...filters, category: value })}
|
||||
allowClear
|
||||
>
|
||||
{Object.values(SERVICE_CATEGORIES).map(category => (
|
||||
<Option key={category.id} value={category.id}>
|
||||
{category.name}
|
||||
</Option>
|
||||
))}
|
||||
</Select>
|
||||
|
||||
<div>
|
||||
<label>Price Range: {filters.priceRange[0]} - {filters.priceRange[1]} AITBC</label>
|
||||
<Slider
|
||||
range
|
||||
min={0}
|
||||
max={1000}
|
||||
value={filters.priceRange}
|
||||
onChange={(value) => setFilters({ ...filters, priceRange: value })}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label>GPU Memory: {filters.gpuMemory[0]} - {filters.gpuMemory[1]} GB</label>
|
||||
<Slider
|
||||
range
|
||||
min={0}
|
||||
max={24}
|
||||
value={filters.gpuMemory}
|
||||
onChange={(value) => setFilters({ ...filters, gpuMemory: value })}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label>Minimum Provider Rating: {filters.providerRating} stars</label>
|
||||
<Slider
|
||||
min={0}
|
||||
max={5}
|
||||
step={0.5}
|
||||
value={filters.providerRating}
|
||||
onChange={(value) => setFilters({ ...filters, providerRating: value })}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<Button type="primary" onClick={handleSearch} block>
|
||||
Apply Filters
|
||||
</Button>
|
||||
</Space>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Step 7: Add Integration with External Systems
|
||||
|
||||
```python
|
||||
# apps/coordinator-api/src/app/integrations/slack.py
|
||||
import httpx
|
||||
from typing import Dict, Any
|
||||
|
||||
class SlackIntegration:
|
||||
def __init__(self, webhook_url: str):
|
||||
self.webhook_url = webhook_url
|
||||
|
||||
async def notify_new_auction(self, auction: Dict[str, Any]) -> None:
|
||||
"""Send notification about new auction to Slack."""
|
||||
message = {
|
||||
"text": f"New auction created: {auction['title']}",
|
||||
"blocks": [
|
||||
{
|
||||
"type": "section",
|
||||
"text": {
|
||||
"type": "mrkdwn",
|
||||
"text": f"*New Auction Alert*\n\n*Title:* {auction['title']}\n"
|
||||
f"*Starting Price:* {auction['start_price']} AITBC\n"
|
||||
f"*Category:* {auction.get('category', 'General')}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "actions",
|
||||
"elements": [
|
||||
{
|
||||
"type": "button",
|
||||
"text": {"type": "plain_text", "text": "View Auction"},
|
||||
"url": f"https://aitbc.bubuit.net/marketplace/auction/{auction['id']}"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
await client.post(self.webhook_url, json=message)
|
||||
|
||||
async def notify_bid_placed(self, auction_id: str, bid_amount: float) -> None:
|
||||
"""Notify when a bid is placed."""
|
||||
message = {
|
||||
"text": f"New bid of {bid_amount} AITBC placed on auction {auction_id}"
|
||||
}
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
await client.post(self.webhook_url, json=message)
|
||||
|
||||
# Integration with Discord
|
||||
class DiscordIntegration:
|
||||
def __init__(self, webhook_url: str):
|
||||
self.webhook_url = webhook_url
|
||||
|
||||
async def send_embed(self, title: str, description: str, fields: list) -> None:
|
||||
"""Send rich embed message to Discord."""
|
||||
embed = {
|
||||
"title": title,
|
||||
"description": description,
|
||||
"fields": fields,
|
||||
"color": 0x00ff00
|
||||
}
|
||||
|
||||
payload = {"embeds": [embed]}
|
||||
|
||||
async with httpx.AsyncClient() as client:
|
||||
await client.post(self.webhook_url, json=payload)
|
||||
```
|
||||
|
||||
## Step 8: Create Custom Pricing Model
|
||||
|
||||
```typescript
|
||||
// src/extensions/DynamicPricing.ts
|
||||
export interface PricingRule {
|
||||
condition: (context: PricingContext) => boolean;
|
||||
calculate: (basePrice: number, context: PricingContext) => number;
|
||||
}
|
||||
|
||||
export interface PricingContext {
|
||||
demand: number;
|
||||
supply: number;
|
||||
timeOfDay: number;
|
||||
dayOfWeek: number;
|
||||
providerRating: number;
|
||||
serviceCategory: string;
|
||||
}
|
||||
|
||||
export class DynamicPricingEngine {
|
||||
private rules: PricingRule[] = [];
|
||||
|
||||
addRule(rule: PricingRule) {
|
||||
this.rules.push(rule);
|
||||
}
|
||||
|
||||
calculatePrice(basePrice: number, context: PricingContext): number {
|
||||
let finalPrice = basePrice;
|
||||
|
||||
for (const rule of this.rules) {
|
||||
if (rule.condition(context)) {
|
||||
finalPrice = rule.calculate(finalPrice, context);
|
||||
}
|
||||
}
|
||||
|
||||
return Math.round(finalPrice * 100) / 100;
|
||||
}
|
||||
}
|
||||
|
||||
// Example pricing rules
|
||||
export const DEMAND_SURGE_RULE: PricingRule = {
|
||||
condition: (ctx) => ctx.demand / ctx.supply > 2,
|
||||
calculate: (price) => price * 1.5, // 50% surge
|
||||
};
|
||||
|
||||
export const PEAK_HOURS_RULE: PricingRule = {
|
||||
condition: (ctx) => ctx.timeOfDay >= 9 && ctx.timeOfDay <= 17,
|
||||
calculate: (price) => price * 1.2, // 20% peak hour premium
|
||||
};
|
||||
|
||||
export const TOP_PROVIDER_RULE: PricingRule = {
|
||||
condition: (ctx) => ctx.providerRating >= 4.5,
|
||||
calculate: (price) => price * 1.1, // 10% premium for top providers
|
||||
};
|
||||
|
||||
// Usage
|
||||
const pricingEngine = new DynamicPricingEngine();
|
||||
pricingEngine.addRule(DEMAND_SURGE_RULE);
|
||||
pricingEngine.addRule(PEAK_HOURS_RULE);
|
||||
pricingEngine.addRule(TOP_PROVIDER_RULE);
|
||||
|
||||
const finalPrice = pricingEngine.calculatePrice(100, {
|
||||
demand: 100,
|
||||
supply: 30,
|
||||
timeOfDay: 14,
|
||||
dayOfWeek: 2,
|
||||
providerRating: 4.8,
|
||||
serviceCategory: 'ai-inference'
|
||||
});
|
||||
```
|
||||
|
||||
## Testing Your Extensions
|
||||
|
||||
```typescript
|
||||
// src/extensions/__tests__/DutchAuction.test.ts
|
||||
import { DutchAuction } from '../DutchAuction';
|
||||
|
||||
describe('DutchAuction', () => {
|
||||
let auction: DutchAuction;
|
||||
|
||||
beforeEach(() => {
|
||||
auction = new DutchAuction({
|
||||
startPrice: 1000,
|
||||
reservePrice: 100,
|
||||
decrementRate: 10,
|
||||
decrementInterval: 60
|
||||
});
|
||||
});
|
||||
|
||||
test('should start with initial price', () => {
|
||||
expect(auction.currentPrice).toBe(1000);
|
||||
});
|
||||
|
||||
test('should decrement price after interval', async () => {
|
||||
// Mock time passing
|
||||
jest.spyOn(Date, 'now').mockReturnValue(Date.now() + 60000);
|
||||
|
||||
await auction.updatePrice();
|
||||
expect(auction.currentPrice).toBe(990);
|
||||
});
|
||||
|
||||
test('should not go below reserve price', async () => {
|
||||
// Mock significant time passing
|
||||
jest.spyOn(Date, 'now').mockReturnValue(Date.now() + 600000);
|
||||
|
||||
await auction.updatePrice();
|
||||
expect(auction.currentPrice).toBe(100);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
1. **Build your extensions**:
|
||||
```bash
|
||||
npm run build:extensions
|
||||
```
|
||||
|
||||
2. **Deploy to production**:
|
||||
```bash
|
||||
# Copy extension files
|
||||
cp -r src/extensions/* /var/www/aitbc.bubuit.net/marketplace/extensions/
|
||||
|
||||
# Update API
|
||||
scp apps/coordinator-api/src/app/routers/marketplace_extensions.py \
|
||||
aitbc:/opt/coordinator-api/src/app/routers/
|
||||
|
||||
# Restart services
|
||||
ssh aitbc "sudo systemctl restart coordinator-api"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Modular Design** - Keep extensions independent
|
||||
2. **Backward Compatibility** - Ensure extensions work with existing marketplace
|
||||
3. **Performance** - Optimize for high-frequency operations
|
||||
4. **Security** - Validate all inputs and permissions
|
||||
5. **Documentation** - Document extension APIs and usage
|
||||
|
||||
## Conclusion
|
||||
|
||||
This tutorial covered creating marketplace extensions including custom auction types, service categories, advanced search, and external integrations. You can now build powerful extensions to enhance the AITBC marketplace functionality.
|
||||
|
||||
For more examples and community contributions, visit the marketplace extensions repository.
|
||||
153
docs/8_development/13_user-interface-guide.md
Normal file
153
docs/8_development/13_user-interface-guide.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# AITBC Trade Exchange - User Interface Guide
|
||||
|
||||
## Overview
|
||||
The AITBC Trade Exchange features a modern, intuitive interface with user authentication, wallet management, and trading capabilities.
|
||||
|
||||
## Navigation
|
||||
|
||||
### Main Menu
|
||||
Located in the top header, you'll find:
|
||||
- **Trade**: Buy and sell AITBC tokens
|
||||
- **Marketplace**: Browse GPU computing offers
|
||||
- **Wallet**: View your profile and wallet information
|
||||
|
||||
### User Status
|
||||
- **Not Connected**: Shows "Connect Wallet" button
|
||||
- **Connected**: Shows your username with profile and logout icons
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Connect Your Wallet
|
||||
1. Click the "Connect Wallet" button in the navigation bar
|
||||
2. A demo wallet will be automatically created for you
|
||||
3. Your user profile will be displayed with:
|
||||
- Unique username (format: `user_[random]`)
|
||||
- User ID (UUID)
|
||||
- Member since date
|
||||
|
||||
### 2. View Your Profile
|
||||
Click on "Wallet" in the navigation to see:
|
||||
- **User Profile Card**: Your account information
|
||||
- **AITBC Wallet**: Your wallet address and balance
|
||||
- **Transaction History**: Your trading activity
|
||||
|
||||
## Trading AITBC
|
||||
|
||||
### Buy AITBC with Bitcoin
|
||||
1. Navigate to the **Trade** section
|
||||
2. Enter the amount of AITBC you want to buy
|
||||
3. The system calculates the equivalent Bitcoin amount
|
||||
4. Click "Create Payment Request"
|
||||
5. A QR code and payment address will be displayed
|
||||
6. Send Bitcoin to the provided address
|
||||
7. Wait for confirmation (1 confirmation needed)
|
||||
8. AITBC tokens will be credited to your wallet
|
||||
|
||||
### Exchange Rates
|
||||
- **Current Rate**: 1 BTC = 100,000 AITBC
|
||||
- **Fee**: 0.5% transaction fee
|
||||
- **Updates**: Prices refresh every 30 seconds
|
||||
|
||||
## Wallet Features
|
||||
|
||||
### User Profile
|
||||
- **Username**: Auto-generated unique identifier
|
||||
- **User ID**: Your unique UUID in the system
|
||||
- **Member Since**: When you joined the platform
|
||||
- **Logout**: Securely disconnect from the exchange
|
||||
|
||||
### AITBC Wallet
|
||||
- **Address**: Your unique AITBC wallet address
|
||||
- **Balance**: Current AITBC token balance
|
||||
- **USD Value**: Approximate value in USD
|
||||
|
||||
### Transaction History
|
||||
- **Date/Time**: When transactions occurred
|
||||
- **Type**: Buy, sell, deposit, withdrawal
|
||||
- **Amount**: Quantity of AITBC tokens
|
||||
- **Status**: Pending, completed, or failed
|
||||
|
||||
## Security Features
|
||||
|
||||
### Session Management
|
||||
- **Token-based Authentication**: Secure session tokens
|
||||
- **24-hour Expiry**: Automatic session timeout
|
||||
- **Logout**: Manual session termination
|
||||
|
||||
### Privacy
|
||||
- **Individual Accounts**: Each user has isolated data
|
||||
- **Secure API**: All requests require authentication
|
||||
- **No Passwords**: Wallet-based authentication
|
||||
|
||||
## Tips for Users
|
||||
|
||||
### First Time
|
||||
1. Click "Connect Wallet" to create your account
|
||||
2. Your wallet and profile are created automatically
|
||||
3. No registration or password needed
|
||||
|
||||
### Trading
|
||||
1. Always check the current exchange rate
|
||||
2. Bitcoin payments require 1 confirmation
|
||||
3. AITBC tokens are credited automatically
|
||||
|
||||
### Security
|
||||
1. Logout when done trading
|
||||
2. Your session expires after 24 hours
|
||||
3. Each wallet connection creates a new session
|
||||
|
||||
## Demo Features
|
||||
|
||||
### Test Mode
|
||||
- **Testnet Bitcoin**: Uses Bitcoin testnet for safe testing
|
||||
- **Demo Wallets**: Auto-generated wallet addresses
|
||||
- **Simulated Trading**: No real money required
|
||||
|
||||
### Getting Testnet Bitcoin
|
||||
1. Visit a testnet faucet (e.g., https://testnet-faucet.mempool.co/)
|
||||
2. Enter your testnet address
|
||||
3. Receive free testnet Bitcoin for testing
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
- Refresh the page and try connecting again
|
||||
- Check your internet connection
|
||||
- Ensure JavaScript is enabled
|
||||
|
||||
### Balance Not Showing
|
||||
- Try refreshing the page
|
||||
- Check if you're logged in
|
||||
- Contact support if issues persist
|
||||
|
||||
### Payment Problems
|
||||
- Ensure you send the exact amount
|
||||
- Wait for at least 1 confirmation
|
||||
- Check the transaction status on the blockchain
|
||||
|
||||
## Support
|
||||
|
||||
For help or questions:
|
||||
- **API Docs**: https://aitbc.bubuit.net/api/docs
|
||||
- **Admin Panel**: https://aitbc.bubuit.net/admin/stats
|
||||
- **Platform**: https://aitbc.bubuit.net/Exchange
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
- **Ctrl+K**: Quick navigation (coming soon)
|
||||
- **Esc**: Close modals
|
||||
- **Enter**: Confirm actions
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
Works best with modern browsers:
|
||||
- Chrome 90+
|
||||
- Firefox 88+
|
||||
- Safari 14+
|
||||
- Edge 90+
|
||||
|
||||
## Mobile Support
|
||||
|
||||
- Responsive design for tablets and phones
|
||||
- Touch-friendly interface
|
||||
- Mobile wallet support (coming soon)
|
||||
210
docs/8_development/14_user-management-setup.md
Normal file
210
docs/8_development/14_user-management-setup.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# User Management System for AITBC Trade Exchange
|
||||
|
||||
## Overview
|
||||
The AITBC Trade Exchange now includes a complete user management system that allows individual users to have their own wallets, balances, and transaction history. Each user is identified by their wallet address and has a unique session for secure operations.
|
||||
|
||||
## Features Implemented
|
||||
|
||||
### 1. User Registration & Login
|
||||
- **Wallet-based Authentication**: Users connect with their wallet address
|
||||
- **Auto-registration**: New wallets automatically create a user account
|
||||
- **Session Management**: Secure token-based sessions (24-hour expiry)
|
||||
- **User Profiles**: Each user has a unique ID, email, and username
|
||||
|
||||
### 2. Wallet Management
|
||||
- **Individual Wallets**: Each user gets their own AITBC wallet
|
||||
- **Balance Tracking**: Real-time balance updates
|
||||
- **Address Generation**: Unique wallet addresses for each user
|
||||
|
||||
### 3. Transaction History
|
||||
- **Personal Transactions**: Each user sees only their own transactions
|
||||
- **Transaction Types**: Buy, sell, deposit, withdrawal tracking
|
||||
- **Status Updates**: Real-time transaction status
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### User Authentication
|
||||
```http
|
||||
POST /api/users/login
|
||||
{
|
||||
"wallet_address": "aitbc1abc123..."
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"user_id": "uuid",
|
||||
"email": "wallet@aitbc.local",
|
||||
"username": "user_abc123",
|
||||
"created_at": "2025-12-28T...",
|
||||
"session_token": "sha256_token"
|
||||
}
|
||||
```
|
||||
|
||||
### User Profile
|
||||
```http
|
||||
GET /api/users/me
|
||||
Headers: X-Session-Token: <token>
|
||||
```
|
||||
|
||||
### User Balance
|
||||
```http
|
||||
GET /api/users/{user_id}/balance
|
||||
Headers: X-Session-Token: <token>
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"user_id": "uuid",
|
||||
"address": "aitbc_uuid123",
|
||||
"balance": 1000.0,
|
||||
"updated_at": "2025-12-28T..."
|
||||
}
|
||||
```
|
||||
|
||||
### Transaction History
|
||||
```http
|
||||
GET /api/users/{user_id}/transactions
|
||||
Headers: X-Session-Token: <token>
|
||||
```
|
||||
|
||||
### Logout
|
||||
```http
|
||||
POST /api/users/logout
|
||||
Headers: X-Session-Token: <token>
|
||||
```
|
||||
|
||||
## Frontend Implementation
|
||||
|
||||
### 1. Connect Wallet Flow
|
||||
1. User clicks "Connect Wallet"
|
||||
2. Generates a demo wallet address
|
||||
3. Calls `/api/users/login` with wallet address
|
||||
4. Receives session token and user data
|
||||
5. Updates UI with user info
|
||||
|
||||
### 2. UI Components
|
||||
- **Wallet Section**: Shows address, username, balance
|
||||
- **Connect Button**: Visible when not logged in
|
||||
- **Logout Button**: Clears session and resets UI
|
||||
- **Balance Display**: Real-time AITBC balance
|
||||
|
||||
### 3. Session Management
|
||||
- Session token stored in JavaScript variable
|
||||
- Token sent with all API requests
|
||||
- Automatic logout on token expiry
|
||||
- Manual logout option
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Users Table
|
||||
- `id`: UUID (Primary Key)
|
||||
- `email`: Unique string
|
||||
- `username`: Unique string
|
||||
- `status`: active/inactive/suspended
|
||||
- `created_at`: Timestamp
|
||||
- `last_login`: Timestamp
|
||||
|
||||
### Wallets Table
|
||||
- `id`: Integer (Primary Key)
|
||||
- `user_id`: UUID (Foreign Key)
|
||||
- `address`: Unique string
|
||||
- `balance`: Float
|
||||
- `created_at`: Timestamp
|
||||
- `updated_at`: Timestamp
|
||||
|
||||
### Transactions Table
|
||||
- `id`: UUID (Primary Key)
|
||||
- `user_id`: UUID (Foreign Key)
|
||||
- `wallet_id`: Integer (Foreign Key)
|
||||
- `type`: deposit/withdrawal/purchase/etc.
|
||||
- `status`: pending/completed/failed
|
||||
- `amount`: Float
|
||||
- `fee`: Float
|
||||
- `created_at`: Timestamp
|
||||
- `confirmed_at`: Timestamp
|
||||
|
||||
## Security Features
|
||||
|
||||
### 1. Session Security
|
||||
- SHA-256 hashed tokens
|
||||
- 24-hour automatic expiry
|
||||
- Server-side session validation
|
||||
- Secure token invalidation on logout
|
||||
|
||||
### 2. API Security
|
||||
- Session token required for protected endpoints
|
||||
- User isolation (users can only access their own data)
|
||||
- Input validation and sanitization
|
||||
|
||||
### 3. Future Enhancements
|
||||
- JWT tokens for better scalability
|
||||
- Multi-factor authentication
|
||||
- Biometric wallet support
|
||||
- Hardware wallet integration
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. First Time User
|
||||
1. User connects wallet
|
||||
2. System creates new user account
|
||||
3. Wallet is created and linked to user
|
||||
4. Session token issued
|
||||
5. User can start trading
|
||||
|
||||
### 2. Returning User
|
||||
1. User connects wallet
|
||||
2. System finds existing user
|
||||
3. Updates last login
|
||||
4. Issues new session token
|
||||
5. User sees their balance and history
|
||||
|
||||
### 3. Trading
|
||||
1. User initiates purchase
|
||||
2. Payment request created with user_id
|
||||
3. Bitcoin payment processed
|
||||
4. AITBC credited to user's wallet
|
||||
5. Transaction recorded
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Users
|
||||
Each wallet connection creates a unique user:
|
||||
- Address: `aitbc1wallet_[random]x...`
|
||||
- Email: `wallet@aitbc.local`
|
||||
- Username: `user_[last_8_chars]`
|
||||
|
||||
### Demo Mode
|
||||
- No real registration required
|
||||
- Instant wallet creation
|
||||
- Testnet Bitcoin support
|
||||
- Simulated balance updates
|
||||
|
||||
## Next Steps
|
||||
|
||||
### 1. Enhanced Features
|
||||
- Email verification
|
||||
- Password recovery
|
||||
- 2FA authentication
|
||||
- Profile customization
|
||||
|
||||
### 2. Advanced Trading
|
||||
- Limit orders
|
||||
- Stop-loss
|
||||
- Trading history analytics
|
||||
- Portfolio tracking
|
||||
|
||||
### 3. Integration
|
||||
- MetaMask support
|
||||
- WalletConnect protocol
|
||||
- Hardware wallets (Ledger, Trezor)
|
||||
- Mobile wallet apps
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Check the logs: `journalctl -u aitbc-coordinator -f`
|
||||
- API endpoints: `https://aitbc.bubuit.net/api/docs`
|
||||
- Trade Exchange: `https://aitbc.bubuit.net/Exchange`
|
||||
317
docs/8_development/15_ecosystem-initiatives.md
Normal file
317
docs/8_development/15_ecosystem-initiatives.md
Normal file
@@ -0,0 +1,317 @@
|
||||
# AITBC Ecosystem Initiatives - Implementation Summary
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The AITBC ecosystem initiatives establish a comprehensive framework for driving community growth, fostering innovation, and ensuring sustainable development. This document summarizes the implemented systems for hackathons, grants, marketplace extensions, and analytics that form the foundation of AITBC's ecosystem strategy.
|
||||
|
||||
## Initiative Overview
|
||||
|
||||
### 1. Hackathon Program
|
||||
**Objective**: Drive innovation and build high-quality marketplace extensions through themed developer events.
|
||||
|
||||
**Key Features**:
|
||||
- Quarterly themed hackathons (DeFi, Enterprise, Developer Experience, Cross-Chain)
|
||||
- 1-week duration with hybrid virtual/local format
|
||||
- Bounty board for high-value extensions ($5k-$10k standing rewards)
|
||||
- Tiered prize structure with deployment grants and mentorship
|
||||
- Comprehensive judging criteria (40% ecosystem impact, 30% technical, 20% innovation, 10% usability)
|
||||
|
||||
**Implementation**:
|
||||
- Complete organizational framework in `/docs/hackathon-framework.md`
|
||||
- Template-based project scaffolding
|
||||
- Automated judging and submission tracking
|
||||
- Post-event support and integration assistance
|
||||
|
||||
**Success Metrics**:
|
||||
- Target: 100-500 participants per event
|
||||
- Goal: 40% project deployment rate
|
||||
- KPI: Network effects created per project
|
||||
|
||||
### 2. Grant Program
|
||||
**Objective**: Provide ongoing funding for ecosystem-critical projects with accountability.
|
||||
|
||||
**Key Features**:
|
||||
- Hybrid model: Rolling micro-grants ($1k-5k) + Quarterly standard grants ($10k-50k)
|
||||
- Milestone-based disbursement (50% upfront, 50% on delivery)
|
||||
- Retroactive grants for proven projects
|
||||
- Category focus: Extensions (40%), Analytics (30%), Dev Tools (20%), Research (10%)
|
||||
- Comprehensive support package (technical, business, community)
|
||||
|
||||
**Implementation**:
|
||||
- Detailed program structure in `/docs/grant-program.md`
|
||||
- Lightweight application process for micro-grants
|
||||
- Rigorous review for strategic grants
|
||||
- Automated milestone tracking and payments
|
||||
|
||||
**Success Metrics**:
|
||||
- Target: 50+ grants annually
|
||||
- Goal: 85% project success rate
|
||||
- ROI: 2.5x average return on investment
|
||||
|
||||
### 3. Marketplace Extension SDK
|
||||
**Objective**: Enable developers to easily build and deploy extensions for the AITBC marketplace.
|
||||
|
||||
**Key Features**:
|
||||
- Cookiecutter-based project scaffolding
|
||||
- Service-based architecture with Docker containers
|
||||
- Extension.yaml manifest for lifecycle management
|
||||
- Built-in metrics and health checks
|
||||
- Multi-language support (Python first, expanding to Java/JS)
|
||||
|
||||
**Implementation**:
|
||||
- Templates in `/ecosystem-extensions/template/`
|
||||
- Based on existing Python SDK patterns
|
||||
- Comprehensive documentation and examples
|
||||
- Automated testing and deployment pipelines
|
||||
|
||||
**Extension Types**:
|
||||
- Payment processors (Stripe, PayPal, Square)
|
||||
- ERP connectors (SAP, Oracle, NetSuite)
|
||||
- Analytics tools (dashboards, reporting)
|
||||
- Developer tools (IDE plugins, frameworks)
|
||||
|
||||
**Success Metrics**:
|
||||
- Target: 25+ extensions in first year
|
||||
- Goal: 50k+ downloads
|
||||
- KPI: Developer satisfaction >4.5/5
|
||||
|
||||
### 4. Analytics Service
|
||||
**Objective**: Measure ecosystem growth and make data-driven decisions.
|
||||
|
||||
**Key Features**:
|
||||
- Real-time metric collection from all initiatives
|
||||
- Comprehensive dashboard with KPIs
|
||||
- ROI analysis for grants and hackathons
|
||||
- Adoption tracking for extensions
|
||||
- Network effects measurement
|
||||
|
||||
**Implementation**:
|
||||
- Service in `/ecosystem-analytics/analytics_service.py`
|
||||
- Plotly-based visualizations
|
||||
- Export capabilities (CSV, JSON, Excel)
|
||||
- Automated insights and recommendations
|
||||
|
||||
**Tracked Metrics**:
|
||||
- Hackathon participation and outcomes
|
||||
- Grant ROI and impact
|
||||
- Extension adoption and usage
|
||||
- Developer engagement
|
||||
- Cross-chain activity
|
||||
|
||||
**Success Metrics**:
|
||||
- Real-time visibility into ecosystem health
|
||||
- Predictive analytics for growth
|
||||
- Automated reporting for stakeholders
|
||||
|
||||
## Architecture Integration
|
||||
|
||||
### System Interconnections
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Hackathons │───▶│ Extensions │───▶│ Analytics │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Grants │───▶│ Marketplace │───▶│ KPI Dashboard │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
1. **Hackathons** generate projects → **Extensions** SDK scaffolds them
|
||||
2. **Grants** fund promising projects → **Analytics** tracks ROI
|
||||
3. **Extensions** deployed to marketplace → **Analytics** measures adoption
|
||||
4. **Analytics** provides insights → All initiatives optimize based on data
|
||||
|
||||
### Technology Stack
|
||||
- **Backend**: Python with async/await
|
||||
- **Database**: PostgreSQL with SQLAlchemy
|
||||
- **Analytics**: Pandas, Plotly for visualization
|
||||
- **Infrastructure**: Docker containers
|
||||
- **CI/CD**: GitHub Actions
|
||||
- **Documentation**: GitHub Pages
|
||||
|
||||
## Operational Framework
|
||||
|
||||
### Team Structure
|
||||
- **Ecosystem Lead**: Overall strategy and partnerships
|
||||
- **Program Manager**: Hackathon and grant execution
|
||||
- **Developer Relations**: Community engagement and support
|
||||
- **Data Analyst**: Metrics and reporting
|
||||
- **Technical Support**: Extension development assistance
|
||||
|
||||
### Budget Allocation
|
||||
- **Hackathons**: $100k-200k per event
|
||||
- **Grants**: $1M annually
|
||||
- **Extension SDK**: $50k development
|
||||
- **Analytics**: $100k infrastructure
|
||||
- **Team**: $500k annually
|
||||
|
||||
### Timeline
|
||||
- **Q1 2024**: Launch first hackathon, open grant applications
|
||||
- **Q2 2024**: Deploy extension SDK, analytics dashboard
|
||||
- **Q3 2024**: Scale to 100+ extensions, 50+ grants
|
||||
- **Q4 2024**: Optimize based on metrics, expand globally
|
||||
|
||||
## Success Stories (Projected)
|
||||
|
||||
### Case Study 1: DeFi Innovation Hackathon
|
||||
- **Participants**: 250 developers from 30 countries
|
||||
- **Projects**: 45 submissions, 20 deployed
|
||||
- **Impact**: 3 projects became successful startups
|
||||
- **ROI**: 5x return on investment
|
||||
|
||||
### Case Study 2: SAP Connector Grant
|
||||
- **Grant**: $50,000 awarded to enterprise team
|
||||
- **Outcome**: Production-ready connector in 3 months
|
||||
- **Adoption**: 50+ enterprise customers
|
||||
- **Revenue**: $500k ARR generated
|
||||
|
||||
### Case Study 3: Analytics Extension
|
||||
- **Development**: Built using extension SDK
|
||||
- **Features**: Real-time dashboard, custom metrics
|
||||
- **Users**: 1,000+ active installations
|
||||
- **Community**: 25 contributors, 500+ GitHub stars
|
||||
|
||||
## Risk Management
|
||||
|
||||
### Identified Risks
|
||||
1. **Low Participation**
|
||||
- Mitigation: Strong marketing, partner promotion
|
||||
- Backup: Merge with next event, increase prizes
|
||||
|
||||
2. **Poor Quality Submissions**
|
||||
- Mitigation: Better guidelines, mentor support
|
||||
- Backup: Pre-screening, focused workshops
|
||||
|
||||
3. **Grant Underperformance**
|
||||
- Mitigation: Milestone-based funding, due diligence
|
||||
- Backup: Recovery clauses, project transfer
|
||||
|
||||
4. **Extension Security Issues**
|
||||
- Mitigation: Security reviews, certification program
|
||||
- Backup: Rapid response team, bug bounties
|
||||
|
||||
### Contingency Plans
|
||||
- **Financial**: 20% reserve fund
|
||||
- **Technical**: Backup infrastructure, disaster recovery
|
||||
- **Legal**: Compliance framework, IP protection
|
||||
- **Reputation**: Crisis communication, transparency
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Phase 2 (2025)
|
||||
- **Global Expansion**: Regional hackathons, localized grants
|
||||
- **Advanced Analytics**: Machine learning predictions
|
||||
- **Enterprise Program**: Dedicated support for large organizations
|
||||
- **Education Platform**: Courses, certifications, tutorials
|
||||
|
||||
### Phase 3 (2026)
|
||||
- **DAO Governance**: Community decision-making
|
||||
- **Token Incentives**: Reward ecosystem contributions
|
||||
- **Cross-Chain Grants**: Multi-chain ecosystem projects
|
||||
- **Venture Studio**: Incubator for promising projects
|
||||
|
||||
## Measuring Success
|
||||
|
||||
### Key Performance Indicators
|
||||
|
||||
#### Developer Metrics
|
||||
- Active developers: Target 5,000 by end of 2024
|
||||
- GitHub contributors: Target 1,000 by end of 2024
|
||||
- Extension submissions: Target 100 by end of 2024
|
||||
|
||||
#### Business Metrics
|
||||
- Marketplace revenue: Target $1M by end of 2024
|
||||
- Enterprise customers: Target 100 by end of 2024
|
||||
- Transaction volume: Target $100M by end of 2024
|
||||
|
||||
#### Community Metrics
|
||||
- Discord members: Target 10,000 by end of 2024
|
||||
- Event attendance: Target 2,000 cumulative by end of 2024
|
||||
- Grant ROI: Average 2.5x by end of 2024
|
||||
|
||||
### Reporting Cadence
|
||||
- **Weekly**: Internal metrics dashboard
|
||||
- **Monthly**: Community update
|
||||
- **Quarterly**: Stakeholder report
|
||||
- **Annually**: Full ecosystem review
|
||||
|
||||
## Integration with AITBC Platform
|
||||
|
||||
### Technical Integration
|
||||
- Extensions integrate via gRPC/REST APIs
|
||||
- Metrics flow to central analytics database
|
||||
- Authentication through AITBC identity system
|
||||
- Deployment through AITBC infrastructure
|
||||
|
||||
### Business Integration
|
||||
- Grants funded from AITBC treasury
|
||||
- Hackathons sponsored by ecosystem partners
|
||||
- Extensions monetized through marketplace
|
||||
- Analytics inform platform roadmap
|
||||
|
||||
### Community Integration
|
||||
- Developers participate in governance
|
||||
- Grant recipients become ecosystem advocates
|
||||
- Hackathon winners join mentorship program
|
||||
- Extension maintainers form technical council
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### What Worked Well
|
||||
1. **Theme-focused hackathons** produce higher quality than open-ended
|
||||
2. **Milestone-based grants** prevent fund misallocation
|
||||
3. **Extension SDK** dramatically lowers barrier to entry
|
||||
4. **Analytics** enable data-driven optimization
|
||||
|
||||
### Challenges Faced
|
||||
1. **Global time zones** require asynchronous participation
|
||||
2. **Legal compliance** varies by jurisdiction
|
||||
3. **Quality control** needs continuous improvement
|
||||
4. **Scalability** requires automation
|
||||
|
||||
### Iterative Improvements
|
||||
1. Added retroactive grants based on feedback
|
||||
2. Enhanced SDK with more templates
|
||||
3. Improved analytics with predictive capabilities
|
||||
4. Expanded sponsor categories
|
||||
|
||||
## Conclusion
|
||||
|
||||
The AITBC ecosystem initiatives provide a comprehensive framework for sustainable growth through community engagement, strategic funding, and developer empowerment. The integrated approach ensures that hackathons, grants, extensions, and analytics work together to create network effects and drive adoption.
|
||||
|
||||
Key success factors:
|
||||
- **Clear strategy** with measurable goals
|
||||
- **Robust infrastructure** that scales
|
||||
- **Community-first** approach to development
|
||||
- **Data-driven** decision making
|
||||
- **Iterative improvement** based on feedback
|
||||
|
||||
The ecosystem is positioned to become a leading platform for decentralized business applications, with a vibrant community of developers and users driving innovation and adoption.
|
||||
|
||||
## Appendices
|
||||
|
||||
### A. Quick Start Guide
|
||||
1. **For Developers**: Use extension SDK to build your first connector
|
||||
2. **For Entrepreneurs**: Apply for grants to fund your project
|
||||
3. **For Participants**: Join next hackathon to showcase skills
|
||||
4. **For Partners**: Sponsor events to reach top talent
|
||||
|
||||
### B. Contact Information
|
||||
- **Ecosystem Team**: ecosystem@aitbc.io
|
||||
- **Hackathons**: hackathons@aitbc.io
|
||||
- **Grants**: grants@aitbc.io
|
||||
- **Extensions**: extensions@aitbc.io
|
||||
- **Analytics**: analytics@aitbc.io
|
||||
|
||||
### C. Additional Resources
|
||||
- [Hackathon Framework](/docs/hackathon-framework.md)
|
||||
- [Grant Program Details](/docs/grant-program.md)
|
||||
- [Extension SDK Documentation](/ecosystem-extensions/README.md)
|
||||
- [Analytics API Reference](/ecosystem-analytics/API.md)
|
||||
|
||||
---
|
||||
|
||||
*This document represents the current state of AITBC ecosystem initiatives as of January 2024. For the latest updates, visit [aitbc.io/ecosystem](https://aitbc.io/ecosystem).*
|
||||
62
docs/8_development/16_local-assets.md
Normal file
62
docs/8_development/16_local-assets.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Local Assets Implementation Summary
|
||||
|
||||
## ✅ Completed Tasks
|
||||
|
||||
### 1. Downloaded All External Assets
|
||||
- **Tailwind CSS**: `/assets/js/tailwind.js`
|
||||
- **Axios**: `/assets/js/axios.min.js`
|
||||
- **Lucide Icons**: `/assets/js/lucide.js`
|
||||
- **Font Awesome**: `/assets/js/fontawesome.js`
|
||||
- **Custom CSS**: `/assets/css/tailwind.css`
|
||||
|
||||
### 2. Updated All Pages
|
||||
- **Main Website** (`/var/www/html/index.html`)
|
||||
- Removed: `https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css`
|
||||
- Added: `/assets/css/tailwind.css` and `/assets/js/fontawesome.js`
|
||||
|
||||
- **Exchange Page** (`/root/aitbc/apps/trade-exchange/index.html`)
|
||||
- Removed: `https://cdn.tailwindcss.com`
|
||||
- Removed: `https://unpkg.com/axios/dist/axios.min.js`
|
||||
- Removed: `https://unpkg.com/lucide@latest`
|
||||
- Added: `/assets/js/tailwind.js`, `/assets/js/axios.min.js`, `/assets/js/lucide.js`
|
||||
|
||||
- **Marketplace Page** (`/root/aitbc/apps/marketplace-ui/index.html`)
|
||||
- Removed: `https://cdn.tailwindcss.com`
|
||||
- Removed: `https://unpkg.com/axios/dist/axios.min.js`
|
||||
- Removed: `https://unpkg.com/lucide@latest`
|
||||
- Added: `/assets/js/tailwind.js`, `/assets/js/axios.min.js`, `/assets/js/lucide.js`
|
||||
|
||||
### 3. Nginx Configuration
|
||||
- Added location block for `/assets/` with:
|
||||
- 1-year cache expiration
|
||||
- Gzip compression
|
||||
- Security headers
|
||||
- Updated Referrer-Policy to `strict-origin-when-cross-origin`
|
||||
|
||||
### 4. Asset Locations
|
||||
- Primary: `/var/www/aitbc.bubuit.net/assets/`
|
||||
- Backup: `/var/www/html/assets/`
|
||||
|
||||
## 🎯 Benefits Achieved
|
||||
|
||||
1. **No External Dependencies** - All assets served locally
|
||||
2. **Faster Loading** - No DNS lookups for external CDNs
|
||||
3. **Better Security** - No external network requests
|
||||
4. **Offline Capability** - Site works without internet connection
|
||||
5. **No Console Warnings** - All CDN warnings eliminated
|
||||
6. **GDPR Compliant** - No external third-party requests
|
||||
|
||||
## 📊 Verification
|
||||
|
||||
All pages now load without any external requests:
|
||||
- ✅ Main site: https://aitbc.bubuit.net/
|
||||
- ✅ Exchange: https://aitbc.bubuit.net/Exchange
|
||||
- ✅ Marketplace: https://aitbc.bubuit.net/Marketplace
|
||||
|
||||
## 🚀 Production Ready
|
||||
|
||||
The implementation is now production-ready with:
|
||||
- Local asset serving
|
||||
- Proper caching headers
|
||||
- Optimized gzip compression
|
||||
- Security headers configured
|
||||
215
docs/8_development/17_windsurf-testing.md
Normal file
215
docs/8_development/17_windsurf-testing.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Windsurf Testing Integration Guide
|
||||
|
||||
This guide explains how to use Windsurf's integrated testing features with the AITBC project.
|
||||
|
||||
## ✅ What's Been Configured
|
||||
|
||||
### 1. VS Code Settings (`.vscode/settings.json`)
|
||||
- ✅ Pytest enabled (unittest disabled)
|
||||
- ✅ Test discovery configured
|
||||
- ✅ Auto-discovery on save enabled
|
||||
- ✅ Debug port configured
|
||||
|
||||
### 2. Debug Configuration (`.vscode/launch.json`)
|
||||
- ✅ Debug Python Tests
|
||||
- ✅ Debug All Tests
|
||||
- ✅ Debug Current Test File
|
||||
- ✅ Uses `debugpy` (not deprecated `python`)
|
||||
|
||||
### 3. Task Configuration (`.vscode/tasks.json`)
|
||||
- ✅ Run All Tests
|
||||
- ✅ Run Tests with Coverage
|
||||
- ✅ Run Unit Tests Only
|
||||
- ✅ Run Integration Tests
|
||||
- ✅ Run Current Test File
|
||||
- ✅ Run Test Suite Script
|
||||
|
||||
### 4. Pytest Configuration
|
||||
- ✅ `pyproject.toml` - Main configuration with markers
|
||||
- ✅ `pytest.ini` - Moved to project root with custom markers
|
||||
- ✅ `tests/conftest.py` - Fixtures with fallback mocks
|
||||
|
||||
### 5. Test Scripts (2026-01-29)
|
||||
- ✅ `scripts/testing/` - All test scripts moved here
|
||||
- ✅ `test_ollama_blockchain.py` - Complete GPU provider test
|
||||
- ✅ `test_block_import.py` - Blockchain block import testing
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Test Discovery
|
||||
1. Open Windsurf
|
||||
2. Click the **Testing panel** (beaker icon in sidebar)
|
||||
3. Tests will be automatically discovered
|
||||
4. See all `test_*.py` files listed
|
||||
|
||||
### Running Tests
|
||||
|
||||
#### Option 1: Testing Panel
|
||||
- Click the **play button** next to any test
|
||||
- Click the **play button** at the top to run all tests
|
||||
- Right-click on a test folder for more options
|
||||
|
||||
#### Option 2: Command Palette
|
||||
- `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
|
||||
- Search for "Python: Run All Tests"
|
||||
- Or search for "Python: Run Test File"
|
||||
|
||||
#### Option 3: Tasks
|
||||
- `Ctrl+Shift+P` → "Tasks: Run Test Task"
|
||||
- Select the desired test task
|
||||
|
||||
#### Option 4: Keyboard Shortcuts
|
||||
- `F5` - Debug current test
|
||||
- `Ctrl+F5` - Run without debugging
|
||||
|
||||
### Debugging Tests
|
||||
1. Click the **debug button** next to any test
|
||||
2. Set breakpoints in your test code
|
||||
3. Press `F5` to start debugging
|
||||
4. Use the debug panel to inspect variables
|
||||
|
||||
### Test Coverage
|
||||
1. Run the "Run Tests with Coverage" task
|
||||
2. Open `htmlcov/index.html` in your browser
|
||||
3. See detailed coverage reports
|
||||
|
||||
## 📁 Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── test_basic_integration.py # Basic integration tests
|
||||
├── test_discovery.py # Simple discovery tests
|
||||
├── test_windsurf_integration.py # Windsurf integration tests
|
||||
├── unit/ # Unit tests
|
||||
│ ├── test_coordinator_api.py
|
||||
│ ├── test_wallet_daemon.py
|
||||
│ └── test_blockchain_node.py
|
||||
├── integration/ # Integration tests
|
||||
│ └── test_full_workflow.py
|
||||
├── e2e/ # End-to-end tests
|
||||
│ └── test_user_scenarios.py
|
||||
└── security/ # Security tests
|
||||
└── test_security_comprehensive.py
|
||||
```
|
||||
|
||||
## 🏷️ Test Markers
|
||||
|
||||
Tests are marked with:
|
||||
- `@pytest.mark.unit` - Unit tests
|
||||
- `@pytest.mark.integration` - Integration tests
|
||||
- `@pytest.mark.e2e` - End-to-end tests
|
||||
- `@pytest.mark.security` - Security tests
|
||||
- `@pytest.mark.performance` - Performance tests
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Tests Not Discovered?
|
||||
1. Check that files start with `test_*.py`
|
||||
2. Verify pytest is enabled in settings
|
||||
3. Run `python -m pytest --collect-only` to debug
|
||||
|
||||
### Import Errors?
|
||||
1. The fixtures include fallback mocks
|
||||
2. Check `tests/conftest.py` for path configuration
|
||||
3. Use the mock clients if full imports fail
|
||||
|
||||
### Debug Not Working?
|
||||
1. Ensure `debugpy` is installed
|
||||
2. Check `.vscode/launch.json` uses `type: debugpy`
|
||||
3. Verify test has a debug configuration
|
||||
|
||||
## 📝 Example Test
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from unittest.mock import patch
|
||||
|
||||
@pytest.mark.unit
|
||||
def test_example_function():
|
||||
"""Example unit test"""
|
||||
result = add(2, 3)
|
||||
assert result == 5
|
||||
|
||||
@pytest.mark.integration
|
||||
def test_api_endpoint(coordinator_client):
|
||||
"""Example integration test using fixture"""
|
||||
response = coordinator_client.get("/docs")
|
||||
assert response.status_code == 200
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Use descriptive test names** - `test_specific_behavior`
|
||||
2. **Add appropriate markers** - `@pytest.mark.unit`
|
||||
3. **Use fixtures** - Don't repeat setup code
|
||||
4. **Mock external dependencies** - Keep tests isolated
|
||||
5. **Test edge cases** - Not just happy paths
|
||||
6. **Keep tests fast** - Unit tests should be < 1 second
|
||||
|
||||
## 📊 Running Specific Tests
|
||||
|
||||
```bash
|
||||
# Run all unit tests
|
||||
pytest -m unit
|
||||
|
||||
# Run specific file
|
||||
pytest tests/unit/test_coordinator_api.py
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=apps tests/
|
||||
|
||||
# Run in parallel
|
||||
pytest -n auto tests/
|
||||
```
|
||||
|
||||
## 🎉 Success!
|
||||
|
||||
Your Windsurf testing integration is now fully configured! You can:
|
||||
- Discover tests automatically
|
||||
- Run tests with a click
|
||||
- Debug tests visually
|
||||
- Generate coverage reports
|
||||
- Use all pytest features
|
||||
|
||||
Happy testing! 🚀
|
||||
|
||||
---
|
||||
|
||||
## Issue
|
||||
Unittest discovery errors when using Windsurf's test runner with the `tests/` folder.
|
||||
|
||||
## Solution
|
||||
1. **Updated pyproject.toml** - Added `tests` to the testpaths configuration
|
||||
2. **Created minimal conftest.py** - Removed complex imports that were causing discovery failures
|
||||
3. **Test discovery now works** for files matching `test_*.py` pattern
|
||||
|
||||
## Current Status
|
||||
- ✅ Test discovery works for simple tests (e.g., `tests/test_discovery.py`)
|
||||
- ✅ All `test_*.py` files are discovered by pytest
|
||||
- ⚠️ Tests with complex imports may fail during execution due to module path issues
|
||||
|
||||
## Running Tests
|
||||
|
||||
### For test discovery only (Windsurf integration):
|
||||
```bash
|
||||
cd /home/oib/windsurf/aitbc
|
||||
python -m pytest --collect-only tests/
|
||||
```
|
||||
|
||||
### For running all tests (with full setup):
|
||||
```bash
|
||||
cd /home/oib/windsurf/aitbc
|
||||
python run_tests.py tests/
|
||||
```
|
||||
|
||||
## Test Files Found
|
||||
- `tests/e2e/test_wallet_daemon.py`
|
||||
- `tests/integration/test_blockchain_node.py`
|
||||
- `tests/security/test_confidential_transactions.py`
|
||||
- `tests/unit/test_coordinator_api.py`
|
||||
- `tests/test_discovery.py` (simple test file)
|
||||
|
||||
## Notes
|
||||
- The original `conftest_full.py` contains complex fixtures requiring full module setup
|
||||
- To run tests with full functionality, restore `conftest_full.py` and use the wrapper script
|
||||
- For Windsurf's test discovery, the minimal `conftest.py` provides better experience
|
||||
269
docs/8_development/1_overview.md
Normal file
269
docs/8_development/1_overview.md
Normal file
@@ -0,0 +1,269 @@
|
||||
---
|
||||
title: Developer Overview
|
||||
description: Introduction to developing on the AITBC platform
|
||||
---
|
||||
|
||||
# Developer Overview
|
||||
|
||||
Welcome to the AITBC developer documentation! This guide will help you understand how to build applications and services on the AITBC blockchain platform.
|
||||
|
||||
## What You Can Build on AITBC
|
||||
|
||||
### AI/ML Applications
|
||||
- **Inference Services**: Deploy and monetize AI models
|
||||
- **Training Services**: Offer distributed model training
|
||||
- **Data Processing**: Build data pipelines with verifiable computation
|
||||
|
||||
### DeFi Applications
|
||||
- **Prediction Markets**: Create markets for AI predictions
|
||||
- **Computational Derivatives**: Financial products based on AI outcomes
|
||||
- **Staking Pools**: Earn rewards by providing compute resources
|
||||
|
||||
### NFT & Gaming
|
||||
- **Generative Art**: Create AI-powered NFT generators
|
||||
- **Dynamic NFTs**: NFTs that evolve based on AI computations
|
||||
- **AI Gaming**: Games with AI-driven mechanics
|
||||
|
||||
### Infrastructure Tools
|
||||
- **Oracles**: Bridge real-world data to blockchain
|
||||
- **Monitoring Tools**: Track network performance
|
||||
- **Development Tools**: SDKs, frameworks, and utilities
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Developer Tools"
|
||||
A[Python SDK] --> E[Coordinator API]
|
||||
B[JS SDK] --> E
|
||||
C[CLI Tools] --> E
|
||||
D[Smart Contracts] --> F[Blockchain]
|
||||
end
|
||||
|
||||
subgraph "AITBC Platform"
|
||||
E --> G[Marketplace]
|
||||
F --> H[Miners/Validators]
|
||||
G --> I[Job Execution]
|
||||
end
|
||||
|
||||
subgraph "External Services"
|
||||
J[AI Models] --> I
|
||||
K[Storage] --> I
|
||||
L[Oracles] --> F
|
||||
end
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Jobs
|
||||
Jobs are the fundamental unit of computation on AITBC. They represent AI tasks that need to be executed by miners.
|
||||
|
||||
### Smart Contracts
|
||||
AITBC uses smart contracts for:
|
||||
- Marketplace operations
|
||||
- Payment processing
|
||||
- Dispute resolution
|
||||
- Governance
|
||||
|
||||
### Proofs & Receipts
|
||||
All computations generate cryptographic proofs:
|
||||
- **Execution Proofs**: Verify correct computation
|
||||
- **Receipts**: Proof of job completion
|
||||
- **Attestations**: Multiple validator signatures
|
||||
|
||||
### Tokens & Economics
|
||||
- **AITBC Token**: Native utility token
|
||||
- **Job Payments**: Pay for computation
|
||||
- **Staking**: Secure the network
|
||||
- **Rewards**: Earn for providing services
|
||||
|
||||
## Development Stack
|
||||
|
||||
### Core Technologies
|
||||
- **Blockchain**: Custom PoS consensus
|
||||
- **Smart Contracts**: Solidity-compatible
|
||||
- **APIs**: RESTful with OpenAPI specs
|
||||
- **WebSockets**: Real-time updates
|
||||
|
||||
### Languages & Frameworks
|
||||
- **Python**: Primary SDK and ML support
|
||||
- **JavaScript/TypeScript**: Web and Node.js support
|
||||
- **Rust**: High-performance components
|
||||
- **Go**: Infrastructure services
|
||||
|
||||
### Tools & Libraries
|
||||
- **Docker**: Containerization
|
||||
- **Kubernetes**: Orchestration
|
||||
- **Prometheus**: Monitoring
|
||||
- **Grafana**: Visualization
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Set Up Development Environment
|
||||
|
||||
```bash
|
||||
# Install AITBC CLI
|
||||
pip install aitbc-cli
|
||||
|
||||
# Initialize project
|
||||
aitbc init my-project
|
||||
cd my-project
|
||||
|
||||
# Start local development
|
||||
aitbc dev start
|
||||
```
|
||||
|
||||
### 2. Choose Your Path
|
||||
|
||||
#### AI/ML Developer
|
||||
- Focus on model integration
|
||||
- Learn about job specifications
|
||||
- Understand proof generation
|
||||
|
||||
#### DApp Developer
|
||||
- Study smart contract patterns
|
||||
- Master the SDKs
|
||||
- Build user interfaces
|
||||
|
||||
#### Infrastructure Developer
|
||||
- Run a node or miner
|
||||
- Build tools and utilities
|
||||
- Contribute to core protocol
|
||||
|
||||
### 3. Build Your First Application
|
||||
|
||||
Choose a tutorial based on your interest:
|
||||
|
||||
- [AI Inference Service](./12_marketplace-extensions.md)
|
||||
- [Marketplace Bot](./4_examples.md)
|
||||
- [Mining Operation](../3_miners/1_quick-start.md)
|
||||
|
||||
## Developer Resources
|
||||
|
||||
### Documentation
|
||||
- [API Reference](../api/)
|
||||
- [SDK Guides](sdks/)
|
||||
- [Examples](examples.md)
|
||||
- [Best Practices](best-practices.md)
|
||||
|
||||
### Tools
|
||||
- [AITBC CLI](tools/cli.md)
|
||||
- [IDE Plugins](tools/ide-plugins.md)
|
||||
- [Testing Framework](tools/testing.md)
|
||||
|
||||
### Community
|
||||
- [Discord](https://discord.gg/aitbc)
|
||||
- [GitHub Discussions](https://github.com/aitbc/discussions)
|
||||
- [Stack Overflow](https://stackoverflow.com/questions/tagged/aitbc)
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Local Development
|
||||
```bash
|
||||
# Start local testnet
|
||||
aitbc dev start
|
||||
|
||||
# Run tests
|
||||
aitbc test
|
||||
|
||||
# Deploy locally
|
||||
aitbc deploy --local
|
||||
```
|
||||
|
||||
### 2. Testnet Deployment
|
||||
```bash
|
||||
# Configure for testnet
|
||||
aitbc config set network testnet
|
||||
|
||||
# Deploy to testnet
|
||||
aitbc deploy --testnet
|
||||
|
||||
# Verify deployment
|
||||
aitbc status
|
||||
```
|
||||
|
||||
### 3. Production Deployment
|
||||
```bash
|
||||
# Configure for mainnet
|
||||
aitbc config set network mainnet
|
||||
|
||||
# Deploy to production
|
||||
aitbc deploy --mainnet
|
||||
|
||||
# Monitor deployment
|
||||
aitbc monitor
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Smart Contract Security
|
||||
- Follow established patterns
|
||||
- Use audited libraries
|
||||
- Test thoroughly
|
||||
- Consider formal verification
|
||||
|
||||
### API Security
|
||||
- Use API keys properly
|
||||
- Implement rate limiting
|
||||
- Validate inputs
|
||||
- Use HTTPS everywhere
|
||||
|
||||
### Key Management
|
||||
- Never commit private keys
|
||||
- Use hardware wallets
|
||||
- Implement multi-sig
|
||||
- Regular key rotation
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Job Optimization
|
||||
- Minimize computation overhead
|
||||
- Use efficient data formats
|
||||
- Batch operations when possible
|
||||
- Profile and benchmark
|
||||
|
||||
### Cost Optimization
|
||||
- Optimize resource usage
|
||||
- Use spot instances when possible
|
||||
- Implement caching
|
||||
- Monitor spending
|
||||
|
||||
## Contributing to AITBC
|
||||
|
||||
We welcome contributions! Areas where you can help:
|
||||
|
||||
### Core Protocol
|
||||
- Consensus improvements
|
||||
- New cryptographic primitives
|
||||
- Performance optimizations
|
||||
- Bug fixes
|
||||
|
||||
### Developer Tools
|
||||
- SDK improvements
|
||||
- New language support
|
||||
- Better documentation
|
||||
- Tooling enhancements
|
||||
|
||||
### Ecosystem
|
||||
- Sample applications
|
||||
- Tutorials and guides
|
||||
- Community support
|
||||
- Integration examples
|
||||
|
||||
See our [Contributing Guide](contributing.md) for details.
|
||||
|
||||
## Support
|
||||
|
||||
- 📖 [Documentation](../)
|
||||
- 💬 [Discord](https://discord.gg/aitbc)
|
||||
- 🐛 [Issue Tracker](https://github.com/aitbc/issues)
|
||||
- 📧 [dev-support@aitbc.io](mailto:dev-support@aitbc.io)
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. [Set up your environment](setup.md)
|
||||
2. [Learn about authentication](api-authentication.md)
|
||||
3. [Choose an SDK](sdks/)
|
||||
4. [Build your first app](../../tutorials/)
|
||||
|
||||
Happy building! 🚀
|
||||
76
docs/8_development/2_setup.md
Normal file
76
docs/8_development/2_setup.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: Development Setup
|
||||
description: Set up your development environment for AITBC
|
||||
---
|
||||
|
||||
# Development Setup
|
||||
|
||||
This guide helps you set up a development environment for building on AITBC.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.8+
|
||||
- Git
|
||||
- Docker (optional)
|
||||
- Node.js 16+ (for frontend development)
|
||||
|
||||
## Local Development
|
||||
|
||||
### 1. Clone Repository
|
||||
```bash
|
||||
git clone https://github.com/aitbc/aitbc.git
|
||||
cd aitbc
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
```bash
|
||||
# Python dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Development dependencies
|
||||
pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
### 3. Start Services
|
||||
```bash
|
||||
# Using Docker Compose
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
|
||||
# Or start individually
|
||||
aitbc dev start
|
||||
```
|
||||
|
||||
### 4. Verify Setup
|
||||
```bash
|
||||
# Check services
|
||||
aitbc status
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
```
|
||||
|
||||
## IDE Setup
|
||||
|
||||
### VS Code
|
||||
Install extensions:
|
||||
- Python
|
||||
- Docker
|
||||
- GitLens
|
||||
|
||||
### PyCharm
|
||||
Configure Python interpreter and enable Docker integration.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Create `.env` file:
|
||||
```bash
|
||||
AITBC_API_KEY=your_dev_key
|
||||
AITBC_BASE_URL=http://localhost:8011
|
||||
AITBC_NETWORK=testnet
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [API Authentication](api-authentication.md)
|
||||
- [Python SDK](sdks/python.md)
|
||||
- [Examples](examples.md)
|
||||
99
docs/8_development/3_contributing.md
Normal file
99
docs/8_development/3_contributing.md
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: Contributing
|
||||
description: How to contribute to the AITBC project
|
||||
---
|
||||
|
||||
# Contributing to AITBC
|
||||
|
||||
We welcome contributions from the community! This guide will help you get started.
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
### Code Contributions
|
||||
- Fix bugs
|
||||
- Add features
|
||||
- Improve performance
|
||||
- Write tests
|
||||
|
||||
### Documentation
|
||||
- Improve docs
|
||||
- Add examples
|
||||
- Translate content
|
||||
- Fix typos
|
||||
|
||||
### Community
|
||||
- Answer questions
|
||||
- Report issues
|
||||
- Share feedback
|
||||
- Organize events
|
||||
|
||||
## Getting Started
|
||||
|
||||
### 1. Fork Repository
|
||||
```bash
|
||||
git clone https://github.com/your-username/aitbc.git
|
||||
cd aitbc
|
||||
```
|
||||
|
||||
### 2. Setup Development Environment
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Start development server
|
||||
aitbc dev start
|
||||
```
|
||||
|
||||
### 3. Create Branch
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Code Style
|
||||
- Follow PEP 8 for Python
|
||||
- Use ESLint for JavaScript
|
||||
- Write clear commit messages
|
||||
- Add tests for new features
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run specific test
|
||||
pytest tests/test_jobs.py
|
||||
|
||||
# Check coverage
|
||||
pytest --cov=aitbc
|
||||
```
|
||||
|
||||
### Submitting Changes
|
||||
1. Push to your fork
|
||||
2. Create pull request
|
||||
3. Wait for review
|
||||
4. Address feedback
|
||||
5. Merge!
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
- Use GitHub Issues
|
||||
- Provide clear description
|
||||
- Include reproduction steps
|
||||
- Add relevant logs
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Please read and follow our [Code of Conduct](https://github.com/aitbc/blob/main/CODE_OF_CONDUCT.md).
|
||||
|
||||
## Getting Help
|
||||
|
||||
- Discord: https://discord.gg/aitbc
|
||||
- Email: dev@aitbc.io
|
||||
- Documentation: https://docs.aitbc.io
|
||||
|
||||
Thank you for contributing! 🎉
|
||||
131
docs/8_development/4_examples.md
Normal file
131
docs/8_development/4_examples.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: Code Examples
|
||||
description: Practical examples for building on AITBC
|
||||
---
|
||||
|
||||
# Code Examples
|
||||
|
||||
This section provides practical examples for common tasks on the AITBC platform.
|
||||
|
||||
## Python Examples
|
||||
|
||||
### Basic Job Submission
|
||||
```python
|
||||
from aitbc import AITBCClient
|
||||
|
||||
client = AITBCClient(api_key="your_key")
|
||||
|
||||
job = client.jobs.create({
|
||||
"name": "image-classification",
|
||||
"type": "ai-inference",
|
||||
"model": {
|
||||
"type": "python",
|
||||
"entrypoint": "model.py",
|
||||
"requirements": ["torch", "pillow"]
|
||||
}
|
||||
})
|
||||
|
||||
result = client.jobs.wait_for_completion(job["job_id"])
|
||||
```
|
||||
|
||||
### Batch Job Processing
|
||||
```python
|
||||
import asyncio
|
||||
from aitbc import AsyncAITBCClient
|
||||
|
||||
async def process_images(image_paths):
|
||||
client = AsyncAITBCClient(api_key="your_key")
|
||||
|
||||
tasks = []
|
||||
for path in image_paths:
|
||||
job = await client.jobs.create({
|
||||
"name": f"process-{path}",
|
||||
"type": "image-analysis"
|
||||
})
|
||||
tasks.append(client.jobs.wait_for_completion(job["job_id"]))
|
||||
|
||||
results = await asyncio.gather(*tasks)
|
||||
return results
|
||||
```
|
||||
|
||||
## JavaScript Examples
|
||||
|
||||
### React Component
|
||||
```jsx
|
||||
import React, { useState, useEffect } from 'react';
|
||||
import { AITBCClient } from '@aitbc/client';
|
||||
|
||||
function JobList() {
|
||||
const [jobs, setJobs] = useState([]);
|
||||
const client = new AITBCClient({ apiKey: 'your_key' });
|
||||
|
||||
useEffect(() => {
|
||||
async function fetchJobs() {
|
||||
const jobList = await client.jobs.list();
|
||||
setJobs(jobList);
|
||||
}
|
||||
fetchJobs();
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<div>
|
||||
{jobs.map(job => (
|
||||
<div key={job.jobId}>
|
||||
<h3>{job.name}</h3>
|
||||
<p>Status: {job.status}</p>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket Integration
|
||||
```javascript
|
||||
const client = new AITBCClient({ apiKey: 'your_key' });
|
||||
const ws = client.websocket.connect();
|
||||
|
||||
ws.on('jobUpdate', (data) => {
|
||||
console.log(`Job ${data.jobId} updated to ${data.status}`);
|
||||
});
|
||||
|
||||
ws.subscribe('jobs');
|
||||
ws.start();
|
||||
```
|
||||
|
||||
## CLI Examples
|
||||
|
||||
### Job Management
|
||||
```bash
|
||||
# Create job from file
|
||||
aitbc job create job.yaml
|
||||
|
||||
# List all jobs
|
||||
aitbc job list --status running
|
||||
|
||||
# Monitor job progress
|
||||
aitbc job watch <job_id>
|
||||
|
||||
# Download results
|
||||
aitbc job download <job_id> --output ./results/
|
||||
```
|
||||
|
||||
### Marketplace Operations
|
||||
```bash
|
||||
# List available offers
|
||||
aitbc marketplace list --type image-classification
|
||||
|
||||
# Create offer as miner
|
||||
aitbc marketplace create-offer offer.yaml
|
||||
|
||||
# Accept offer
|
||||
aitbc marketplace accept <offer_id> --job-id <job_id>
|
||||
```
|
||||
|
||||
## Complete Examples
|
||||
|
||||
Find full working examples in our GitHub repositories:
|
||||
- [Python SDK Examples](https://github.com/aitbc/python-sdk/tree/main/examples)
|
||||
- [JavaScript SDK Examples](https://github.com/aitbc/js-sdk/tree/main/examples)
|
||||
- [CLI Examples](https://github.com/aitbc/cli/tree/main/examples)
|
||||
- [Smart Contract Examples](https://github.com/aitbc/contracts/tree/main/examples)
|
||||
259
docs/8_development/5_developer-guide.md
Normal file
259
docs/8_development/5_developer-guide.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Developer Documentation - AITBC
|
||||
|
||||
Build on the AITBC platform: SDKs, APIs, bounties, and resources for developers.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Git
|
||||
- Docker and Docker Compose
|
||||
- Node.js 18+ (for frontend)
|
||||
- Python 3.9+ (for AI services)
|
||||
- Rust 1.70+ (for blockchain)
|
||||
|
||||
### Setup Development Environment
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/oib/AITBC.git
|
||||
cd aitbc
|
||||
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# Check status
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The AITBC platform consists of:
|
||||
|
||||
- **Blockchain Node** (Rust) - PoA/PoS consensus layer
|
||||
- **Coordinator API** (Python/FastAPI) - Job orchestration
|
||||
- **Marketplace Web** (TypeScript/Vite) - User interface
|
||||
- **Miner Daemons** (Go) - GPU compute providers
|
||||
- **Wallet Daemon** (Go) - Secure wallet management
|
||||
|
||||
## Contributing
|
||||
|
||||
### How to Contribute
|
||||
|
||||
1. Fork the repository on GitHub
|
||||
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
||||
3. Make your changes
|
||||
4. Add tests for new functionality
|
||||
5. Ensure all tests pass: `make test`
|
||||
6. Submit a pull request
|
||||
|
||||
### Code Style
|
||||
|
||||
- **Rust**: Use `rustfmt` and `clippy`
|
||||
- **Python**: Follow PEP 8, use `black` and `flake8`
|
||||
- **TypeScript**: Use Prettier and ESLint
|
||||
- **Go**: Use `gofmt`
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
1. Update documentation for any changes
|
||||
2. Add unit tests for new features
|
||||
3. Ensure CI/CD pipeline passes
|
||||
4. Request review from core team
|
||||
5. Address feedback promptly
|
||||
|
||||
## Bounty Program
|
||||
|
||||
Get paid to contribute to AITBC! Check open bounties on GitHub.
|
||||
|
||||
### Current Bounties
|
||||
|
||||
- **$500** - Implement REST API rate limiting
|
||||
- **$750** - Add Python async SDK support
|
||||
- **$1000** - Optimize ZK proof generation
|
||||
- **$1500** - Implement cross-chain bridge
|
||||
- **$2000** - Build mobile wallet app
|
||||
|
||||
### Research Grants
|
||||
|
||||
- **$5000** - Novel consensus mechanisms
|
||||
- **$7500** - Privacy-preserving ML
|
||||
- **$10000** - Quantum-resistant cryptography
|
||||
|
||||
### How to Apply
|
||||
|
||||
1. Check open issues on GitHub
|
||||
2. Comment on the issue you want to work on
|
||||
3. Submit your solution
|
||||
4. Get reviewed by core team
|
||||
5. Receive payment in AITBC tokens
|
||||
|
||||
> **New Contributor Bonus:** First-time contributors get a 20% bonus on their first bounty!
|
||||
|
||||
## Join the Community
|
||||
|
||||
### Developer Channels
|
||||
|
||||
- **Discord #dev** - General development discussion
|
||||
- **Discord #core-dev** - Core protocol discussions
|
||||
- **Discord #bounties** - Bounty program updates
|
||||
- **Discord #research** - Research discussions
|
||||
|
||||
### Events & Programs
|
||||
|
||||
- **Weekly Dev Calls** - Every Tuesday 14:00 UTC
|
||||
- **Hackathons** - Quarterly with prizes
|
||||
- **Office Hours** - Meet the core team
|
||||
- **Mentorship Program** - Learn from experienced devs
|
||||
|
||||
### Recognition
|
||||
|
||||
- Top contributors featured on website
|
||||
- Monthly contributor rewards
|
||||
- Special Discord roles
|
||||
- Annual developer summit invitation
|
||||
- Swag and merchandise
|
||||
|
||||
## Developer Resources
|
||||
|
||||
### Documentation
|
||||
|
||||
- [Full API Documentation](full-documentation.md)
|
||||
- [Architecture Guide](architecture.md)
|
||||
- [Protocol Specification](protocol.md)
|
||||
- [Security Best Practices](security.md)
|
||||
|
||||
### Tools & SDKs
|
||||
|
||||
- [Python SDK](sdks/python.md)
|
||||
- [JavaScript SDK](sdks/javascript.md)
|
||||
- [Go SDK](sdks/go.md)
|
||||
- [Rust SDK](sdks/rust.md)
|
||||
- [CLI Tools](cli-tools.md)
|
||||
|
||||
### Development Environment
|
||||
|
||||
- [Docker Compose Setup](setup/docker-compose.md)
|
||||
- [Local Testnet](setup/testnet.md)
|
||||
- [Faucet for Test Tokens](setup/faucet.md)
|
||||
- [Block Explorer](tools/explorer.md)
|
||||
|
||||
### Learning Resources
|
||||
|
||||
- [Video Tutorials](tutorials/videos.md)
|
||||
- [Workshop Materials](tutorials/workshops.md)
|
||||
- [Blog Posts](blog/index.md)
|
||||
- [Research Papers](research/papers.md)
|
||||
|
||||
## Example: Adding a New API Endpoint
|
||||
|
||||
The coordinator-api uses Python with FastAPI. Here's how to add a new endpoint:
|
||||
|
||||
### 1. Define the Schema
|
||||
|
||||
```python
|
||||
# File: coordinator-api/src/app/schemas.py
|
||||
|
||||
from pydantic import BaseModel
|
||||
from typing import Optional
|
||||
|
||||
class NewFeatureRequest(BaseModel):
|
||||
"""Request model for new feature."""
|
||||
name: str
|
||||
value: int
|
||||
options: Optional[dict] = None
|
||||
|
||||
class NewFeatureResponse(BaseModel):
|
||||
"""Response model for new feature."""
|
||||
id: str
|
||||
status: str
|
||||
result: dict
|
||||
```
|
||||
|
||||
### 2. Create the Router
|
||||
|
||||
```python
|
||||
# File: coordinator-api/src/app/routers/new_feature.py
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException
|
||||
from ..schemas import NewFeatureRequest, NewFeatureResponse
|
||||
from ..services.new_feature import NewFeatureService
|
||||
|
||||
router = APIRouter(prefix="/v1/features", tags=["features"])
|
||||
|
||||
@router.post("/", response_model=NewFeatureResponse)
|
||||
async def create_feature(
|
||||
request: NewFeatureRequest,
|
||||
service: NewFeatureService = Depends()
|
||||
):
|
||||
"""Create a new feature."""
|
||||
try:
|
||||
result = await service.process(request)
|
||||
return NewFeatureResponse(
|
||||
id=result.id,
|
||||
status="success",
|
||||
result=result.data
|
||||
)
|
||||
except ValueError as e:
|
||||
raise HTTPException(status_code=400, detail=str(e))
|
||||
```
|
||||
|
||||
### 3. Write Tests
|
||||
|
||||
```python
|
||||
# File: coordinator-api/tests/test_new_feature.py
|
||||
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
from src.app.main import app
|
||||
|
||||
client = TestClient(app)
|
||||
|
||||
def test_create_feature_success():
|
||||
"""Test successful feature creation."""
|
||||
response = client.post(
|
||||
"/v1/features/",
|
||||
json={"name": "test", "value": 123}
|
||||
)
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert data["status"] == "success"
|
||||
assert "id" in data
|
||||
|
||||
def test_create_feature_invalid():
|
||||
"""Test validation error."""
|
||||
response = client.post(
|
||||
"/v1/features/",
|
||||
json={"name": ""} # Missing required field
|
||||
)
|
||||
assert response.status_code == 422
|
||||
```
|
||||
|
||||
> **💡 Pro Tip:** Run `make test` locally before pushing. The CI pipeline will also run all tests automatically on your PR.
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### General
|
||||
|
||||
- **How do I start contributing?** - Check our "Getting Started" guide and pick an issue that interests you.
|
||||
- **Do I need to sign anything?** - Yes, you'll need to sign our CLA (Contributor License Agreement).
|
||||
- **Can I be paid for contributions?** - Yes! Check our bounty program or apply for grants.
|
||||
|
||||
### Technical
|
||||
|
||||
- **What's the tech stack?** - Rust for blockchain, Go for services, Python for AI, TypeScript for frontend.
|
||||
- **How do I run tests?** - Use `make test` or check specific component documentation.
|
||||
- **Where can I ask questions?** - Discord #dev channel is the best place.
|
||||
|
||||
### Process
|
||||
|
||||
- **How long does PR review take?** - Usually 1-3 business days.
|
||||
- **Can I work on multiple issues?** - Yes, but submit one PR per feature.
|
||||
- **What if I need help?** - Ask in Discord or create a "help wanted" issue.
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Documentation**: [https://docs.aitbc.bubuit.net](https://docs.aitbc.bubuit.net)
|
||||
- **Discord**: [Join our server](https://discord.gg/aitbc)
|
||||
- **Email**: [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
|
||||
- **Issues**: [Report on GitHub](https://github.com/oib/AITBC/issues)
|
||||
85
docs/8_development/6_api-authentication.md
Normal file
85
docs/8_development/6_api-authentication.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: API Authentication
|
||||
description: Understanding and implementing API authentication
|
||||
---
|
||||
|
||||
# API Authentication
|
||||
|
||||
All AITBC API endpoints require authentication using API keys.
|
||||
|
||||
## Getting API Keys
|
||||
|
||||
### Production
|
||||
1. Visit the [AITBC Dashboard](https://dashboard.aitbc.io)
|
||||
2. Create an account or sign in
|
||||
3. Navigate to API Keys section
|
||||
4. Generate a new API key
|
||||
|
||||
### Testing/Development
|
||||
For integration tests and development, these test keys are available:
|
||||
- `${CLIENT_API_KEY}` - For client API access
|
||||
- `${MINER_API_KEY}` - For miner registration
|
||||
- `test-tenant` - Default tenant ID for testing
|
||||
|
||||
## Using API Keys
|
||||
|
||||
### HTTP Header
|
||||
```http
|
||||
X-API-Key: your_api_key_here
|
||||
X-Tenant-ID: your_tenant_id # Optional for multi-tenant
|
||||
```
|
||||
|
||||
### Environment Variable
|
||||
```bash
|
||||
export AITBC_API_KEY="your_api_key_here"
|
||||
```
|
||||
|
||||
### SDK Configuration
|
||||
```python
|
||||
from aitbc import AITBCClient
|
||||
|
||||
client = AITBCClient(api_key="your_api_key")
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- Never commit API keys to version control
|
||||
- Use environment variables in production
|
||||
- Rotate keys regularly
|
||||
- Use different keys for different environments
|
||||
- Monitor API key usage
|
||||
|
||||
## Rate Limits
|
||||
|
||||
API requests are rate-limited based on your plan:
|
||||
- Free: 60 requests/minute
|
||||
- Pro: 600 requests/minute
|
||||
- Enterprise: 6000 requests/minute
|
||||
|
||||
## Error Handling
|
||||
|
||||
```python
|
||||
from aitbc.exceptions import AuthenticationError
|
||||
|
||||
try:
|
||||
client.jobs.create({...})
|
||||
except AuthenticationError:
|
||||
print("Invalid API key")
|
||||
```
|
||||
|
||||
## Key Management
|
||||
|
||||
### View Your Keys
|
||||
```bash
|
||||
aitbc api-keys list
|
||||
```
|
||||
|
||||
### Revoke a Key
|
||||
```bash
|
||||
aitbc api-keys revoke <key_id>
|
||||
```
|
||||
|
||||
### Regenerate a Key
|
||||
```bash
|
||||
aitbc api-keys regenerate <key_id>
|
||||
```
|
||||
156
docs/8_development/7_payments-receipts.md
Normal file
156
docs/8_development/7_payments-receipts.md
Normal 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](../6_architecture/4_blockchain-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](../5_reference/5_zk-proofs.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
|
||||
144
docs/8_development/8_blockchain-node-deployment.md
Normal file
144
docs/8_development/8_blockchain-node-deployment.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Blockchain Node Deployment Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- SQLite 3.35+
|
||||
- 512 MB RAM minimum (1 GB recommended)
|
||||
- 10 GB disk space
|
||||
|
||||
## Configuration
|
||||
|
||||
All settings via environment variables or `.env` file:
|
||||
|
||||
```bash
|
||||
# Core
|
||||
CHAIN_ID=ait-devnet
|
||||
DB_PATH=./data/chain.db
|
||||
PROPOSER_ID=ait-devnet-proposer
|
||||
BLOCK_TIME_SECONDS=2
|
||||
|
||||
# RPC
|
||||
RPC_BIND_HOST=0.0.0.0
|
||||
RPC_BIND_PORT=8080
|
||||
|
||||
# Block Production
|
||||
MAX_BLOCK_SIZE_BYTES=1000000
|
||||
MAX_TXS_PER_BLOCK=500
|
||||
MIN_FEE=0
|
||||
|
||||
# Mempool
|
||||
MEMPOOL_BACKEND=database # "memory" or "database"
|
||||
MEMPOOL_MAX_SIZE=10000
|
||||
|
||||
# Circuit Breaker
|
||||
CIRCUIT_BREAKER_THRESHOLD=5
|
||||
CIRCUIT_BREAKER_TIMEOUT=30
|
||||
|
||||
# Sync
|
||||
TRUSTED_PROPOSERS=proposer-a,proposer-b
|
||||
MAX_REORG_DEPTH=10
|
||||
SYNC_VALIDATE_SIGNATURES=true
|
||||
|
||||
# Gossip
|
||||
GOSSIP_BACKEND=memory # "memory" or "broadcast"
|
||||
GOSSIP_BROADCAST_URL= # Required for broadcast backend
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
cd apps/blockchain-node
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Running
|
||||
|
||||
### Development
|
||||
```bash
|
||||
uvicorn aitbc_chain.app:app --host 127.0.0.1 --port 8080 --reload
|
||||
```
|
||||
|
||||
### Production
|
||||
```bash
|
||||
uvicorn aitbc_chain.app:app \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080 \
|
||||
--workers 1 \
|
||||
--timeout-keep-alive 30 \
|
||||
--access-log \
|
||||
--log-level info
|
||||
```
|
||||
|
||||
**Note:** Use `--workers 1` because the PoA proposer must run as a single instance.
|
||||
|
||||
### Systemd Service
|
||||
```ini
|
||||
[Unit]
|
||||
Description=AITBC Blockchain Node
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=aitbc
|
||||
WorkingDirectory=/opt/aitbc/apps/blockchain-node
|
||||
EnvironmentFile=/opt/aitbc/.env
|
||||
ExecStart=/opt/aitbc/venv/bin/uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8080 --workers 1
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/health` | Health check |
|
||||
| GET | `/metrics` | Prometheus metrics |
|
||||
| GET | `/rpc/head` | Chain head |
|
||||
| GET | `/rpc/blocks/{height}` | Block by height |
|
||||
| GET | `/rpc/blocks` | Latest blocks |
|
||||
| GET | `/rpc/tx/{hash}` | Transaction by hash |
|
||||
| POST | `/rpc/sendTx` | Submit transaction |
|
||||
| POST | `/rpc/importBlock` | Import block from peer |
|
||||
| GET | `/rpc/syncStatus` | Sync status |
|
||||
| POST | `/rpc/admin/mintFaucet` | Mint devnet funds |
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
### Key Metrics
|
||||
- `poa_proposer_running` — 1 if proposer is active
|
||||
- `chain_head_height` — Current block height
|
||||
- `mempool_size` — Pending transactions
|
||||
- `circuit_breaker_state` — 0=closed, 1=open
|
||||
- `rpc_requests_total` — Total RPC requests
|
||||
- `rpc_rate_limited_total` — Rate-limited requests
|
||||
|
||||
### Alerting Rules (Prometheus)
|
||||
```yaml
|
||||
- alert: ProposerDown
|
||||
expr: poa_proposer_running == 0
|
||||
for: 1m
|
||||
|
||||
- alert: CircuitBreakerOpen
|
||||
expr: circuit_breaker_state == 1
|
||||
for: 30s
|
||||
|
||||
- alert: HighErrorRate
|
||||
expr: rate(rpc_server_errors_total[5m]) > 0.1
|
||||
for: 2m
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Proposer not producing blocks**: Check `poa_proposer_running` metric, review logs for DB errors
|
||||
- **Rate limiting**: Increase `max_requests` in middleware or add IP allowlist
|
||||
- **DB locked**: Switch to `MEMPOOL_BACKEND=database` for separate mempool DB
|
||||
- **Sync failures**: Check `TRUSTED_PROPOSERS` config, verify peer connectivity
|
||||
94
docs/8_development/9_block-production-runbook.md
Normal file
94
docs/8_development/9_block-production-runbook.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Block Production Operational Runbook
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Clients → RPC /sendTx → Mempool → PoA Proposer → Block (with Transactions)
|
||||
↓
|
||||
Circuit Breaker
|
||||
(graceful degradation)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Setting | Default | Env Var | Description |
|
||||
|---------|---------|---------|-------------|
|
||||
| `block_time_seconds` | 2 | `BLOCK_TIME_SECONDS` | Block interval |
|
||||
| `max_block_size_bytes` | 1,000,000 | `MAX_BLOCK_SIZE_BYTES` | Max block size (1 MB) |
|
||||
| `max_txs_per_block` | 500 | `MAX_TXS_PER_BLOCK` | Max transactions per block |
|
||||
| `min_fee` | 0 | `MIN_FEE` | Minimum fee to accept into mempool |
|
||||
| `mempool_backend` | memory | `MEMPOOL_BACKEND` | "memory" or "database" |
|
||||
| `mempool_max_size` | 10,000 | `MEMPOOL_MAX_SIZE` | Max pending transactions |
|
||||
| `circuit_breaker_threshold` | 5 | `CIRCUIT_BREAKER_THRESHOLD` | Failures before circuit opens |
|
||||
| `circuit_breaker_timeout` | 30 | `CIRCUIT_BREAKER_TIMEOUT` | Seconds before half-open retry |
|
||||
|
||||
## Mempool Backends
|
||||
|
||||
### In-Memory (default)
|
||||
- Fast, no persistence
|
||||
- Lost on restart
|
||||
- Suitable for devnet/testnet
|
||||
|
||||
### Database-backed (SQLite)
|
||||
- Persistent across restarts
|
||||
- Shared between services via file
|
||||
- Set `MEMPOOL_BACKEND=database`
|
||||
|
||||
## Monitoring Metrics
|
||||
|
||||
### Block Production
|
||||
- `blocks_proposed_total` — Total blocks proposed
|
||||
- `chain_head_height` — Current chain height
|
||||
- `last_block_tx_count` — Transactions in last block
|
||||
- `last_block_total_fees` — Total fees in last block
|
||||
- `block_build_duration_seconds` — Time to build last block
|
||||
- `block_interval_seconds` — Time between blocks
|
||||
|
||||
### Mempool
|
||||
- `mempool_size` — Current pending transaction count
|
||||
- `mempool_tx_added_total` — Total transactions added
|
||||
- `mempool_tx_drained_total` — Total transactions included in blocks
|
||||
- `mempool_evictions_total` — Transactions evicted (low fee)
|
||||
|
||||
### Circuit Breaker
|
||||
- `circuit_breaker_state` — 0=closed, 1=open
|
||||
- `circuit_breaker_trips_total` — Times circuit breaker opened
|
||||
- `blocks_skipped_circuit_breaker_total` — Blocks skipped due to open circuit
|
||||
|
||||
### RPC
|
||||
- `rpc_send_tx_total` — Total transaction submissions
|
||||
- `rpc_send_tx_success_total` — Successful submissions
|
||||
- `rpc_send_tx_rejected_total` — Rejected (fee too low, validation)
|
||||
- `rpc_send_tx_failed_total` — Failed (mempool unavailable)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Empty blocks (tx_count=0)
|
||||
1. Check mempool size: `GET /metrics` → `mempool_size`
|
||||
2. Verify transactions are being submitted: `rpc_send_tx_total`
|
||||
3. Check if fees meet minimum: `rpc_send_tx_rejected_total`
|
||||
4. Verify block size limits aren't too restrictive
|
||||
|
||||
### Circuit breaker open
|
||||
1. Check `circuit_breaker_state` metric (1 = open)
|
||||
2. Review logs for repeated failures
|
||||
3. Check database connectivity
|
||||
4. Wait for timeout (default 30s) for automatic half-open retry
|
||||
5. If persistent, restart the node
|
||||
|
||||
### Mempool full
|
||||
1. Check `mempool_size` vs `MEMPOOL_MAX_SIZE`
|
||||
2. Low-fee transactions are auto-evicted
|
||||
3. Increase `MEMPOOL_MAX_SIZE` or raise `MIN_FEE`
|
||||
|
||||
### High block build time
|
||||
1. Check `block_build_duration_seconds`
|
||||
2. Reduce `MAX_TXS_PER_BLOCK` if too slow
|
||||
3. Consider database mempool for large volumes
|
||||
4. Check disk I/O if using SQLite backend
|
||||
|
||||
### Transaction not included in block
|
||||
1. Verify transaction was accepted: check `tx_hash` in response
|
||||
2. Check fee is competitive (higher fee = higher priority)
|
||||
3. Check transaction size vs `MAX_BLOCK_SIZE_BYTES`
|
||||
4. Transaction may be queued — check `mempool_size`
|
||||
Reference in New Issue
Block a user