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:
145
docs/5_reference/2_payment-architecture.md
Normal file
145
docs/5_reference/2_payment-architecture.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# AITBC Payment Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The AITBC platform uses a dual-currency system:
|
||||
- **AITBC Tokens**: For job payments and platform operations
|
||||
- **Bitcoin**: For purchasing AITBC tokens through the exchange
|
||||
|
||||
## Payment Flow
|
||||
|
||||
### 1. Job Payments (AITBC Tokens)
|
||||
```
|
||||
Client ──► Creates Job with AITBC Payment ──► Coordinator API
|
||||
│ │
|
||||
│ ▼
|
||||
│ Create Token Escrow
|
||||
│ │
|
||||
│ ▼
|
||||
│ Exchange API (Token)
|
||||
│ │
|
||||
▼ ▼
|
||||
Miner completes job ──► Release AITBC Escrow ──► Miner Wallet
|
||||
```
|
||||
|
||||
### 2. Token Purchase (Bitcoin → AITBC)
|
||||
```
|
||||
Client ──► Bitcoin Payment ──► Exchange API
|
||||
│ │
|
||||
│ ▼
|
||||
│ Process Bitcoin
|
||||
│ │
|
||||
▼ ▼
|
||||
Receive AITBC Tokens ◄─── Exchange Rate ◄─── 1 BTC = 100,000 AITBC
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Job Payment Structure
|
||||
```json
|
||||
{
|
||||
"payload": {...},
|
||||
"ttl_seconds": 900,
|
||||
"payment_amount": 100, // AITBC tokens
|
||||
"payment_currency": "AITBC" // Always AITBC for jobs
|
||||
}
|
||||
```
|
||||
|
||||
### Payment Methods
|
||||
- `aitbc_token`: Default for all job payments
|
||||
- `bitcoin`: Only used for exchange purchases
|
||||
|
||||
### Escrow System
|
||||
- **AITBC Token Escrow**: Managed by Exchange API
|
||||
- Endpoint: `/api/v1/token/escrow/create`
|
||||
- Timeout: 1 hour default
|
||||
- Release on job completion
|
||||
|
||||
- **Bitcoin Escrow**: Managed by Wallet Daemon
|
||||
- Endpoint: `/api/v1/escrow/create`
|
||||
- Only for token purchases
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Job Payment Endpoints
|
||||
- `POST /v1/jobs` - Create job with AITBC payment
|
||||
- `GET /v1/jobs/{id}/payment` - Get job payment status
|
||||
- `POST /v1/payments/{id}/release` - Release AITBC payment
|
||||
- `POST /v1/payments/{id}/refund` - Refund AITBC tokens
|
||||
|
||||
### Exchange Endpoints
|
||||
- `POST /api/exchange/purchase` - Buy AITBC with BTC
|
||||
- `GET /api/exchange/rate` - Get current rate (1 BTC = 100,000 AITBC)
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Job Payments Table
|
||||
```sql
|
||||
CREATE TABLE job_payments (
|
||||
id VARCHAR(255) PRIMARY KEY,
|
||||
job_id VARCHAR(255) NOT NULL,
|
||||
amount DECIMAL(20, 8) NOT NULL,
|
||||
currency VARCHAR(10) DEFAULT 'AITBC',
|
||||
payment_method VARCHAR(20) DEFAULT 'aitbc_token',
|
||||
status VARCHAR(20) DEFAULT 'pending',
|
||||
...
|
||||
);
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Token Validation**: All AITBC payments require valid token balance
|
||||
2. **Escrow Security**: Tokens held in smart contract escrow
|
||||
3. **Rate Limiting**: Exchange purchases limited per user
|
||||
4. **Audit Trail**: All transactions recorded on blockchain
|
||||
|
||||
## Example Flow
|
||||
|
||||
### 1. Client Creates Job
|
||||
```bash
|
||||
curl -X POST http://localhost:18000/v1/jobs \
|
||||
-H "X-Api-Key: ${CLIENT_API_KEY}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"payload": {
|
||||
"job_type": "ai_inference",
|
||||
"parameters": {"model": "gpt-4"}
|
||||
},
|
||||
"payment_amount": 100,
|
||||
"payment_currency": "AITBC"
|
||||
}'
|
||||
```
|
||||
|
||||
### 2. Response with Payment
|
||||
```json
|
||||
{
|
||||
"job_id": "abc123",
|
||||
"state": "queued",
|
||||
"payment_id": "pay456",
|
||||
"payment_status": "escrowed",
|
||||
"payment_currency": "AITBC"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Job Completion & Payment Release
|
||||
```bash
|
||||
curl -X POST http://localhost:18000/v1/payments/pay456/release \
|
||||
-H "X-Api-Key: ${CLIENT_API_KEY}" \
|
||||
-d '{"job_id": "abc123", "reason": "Job completed"}'
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Stable Pricing**: AITBC tokens provide stable job pricing
|
||||
2. **Fast Transactions**: Token payments faster than Bitcoin
|
||||
3. **Gas Optimization**: Batch operations reduce costs
|
||||
4. **Platform Control**: Token supply managed by platform
|
||||
|
||||
## Migration Path
|
||||
|
||||
1. **Phase 1**: Implement AITBC token payments for new jobs
|
||||
2. **Phase 2**: Migrate existing Bitcoin job payments to tokens
|
||||
3. **Phase 3**: Phase out Bitcoin for direct job payments
|
||||
4. **Phase 4**: Bitcoin only used for token purchases
|
||||
|
||||
This architecture ensures efficient job payments while maintaining Bitcoin as the entry point for platform participation.
|
||||
Reference in New Issue
Block a user