196 lines
5.2 KiB
Markdown
196 lines
5.2 KiB
Markdown
# Wallet-Coordinator Integration Implementation
|
|
|
|
## Overview
|
|
|
|
This document describes the implementation of wallet-coordinator integration for job payments in the AITBC platform.
|
|
|
|
## Implemented Features
|
|
|
|
### ✅ 1. Payment Endpoints in Coordinator API
|
|
|
|
#### New Routes Added:
|
|
- `POST /v1/payments` - Create payment for a job
|
|
- `GET /v1/payments/{payment_id}` - Get payment details
|
|
- `GET /v1/jobs/{job_id}/payment` - Get payment for a specific job
|
|
- `POST /v1/payments/{payment_id}/release` - Release payment from escrow
|
|
- `POST /v1/payments/{payment_id}/refund` - Refund payment
|
|
- `GET /v1/payments/{payment_id}/receipt` - Get payment receipt
|
|
|
|
### ✅ 2. Escrow Service
|
|
|
|
#### Features:
|
|
- Automatic escrow creation for Bitcoin payments
|
|
- Timeout-based escrow expiration (default 1 hour)
|
|
- Integration with wallet daemon for escrow management
|
|
- Status tracking (pending → escrowed → released/refunded)
|
|
|
|
### ✅ 3. Wallet Daemon Integration
|
|
|
|
#### Integration Points:
|
|
- HTTP client communication with wallet daemon at `http://127.0.0.1:20000`
|
|
- Escrow creation via `/api/v1/escrow/create`
|
|
- Payment release via `/api/v1/escrow/release`
|
|
- Refunds via `/api/v1/refund`
|
|
|
|
### ✅ 4. Payment Status Tracking
|
|
|
|
#### Job Model Updates:
|
|
- Added `payment_id` field to track associated payment
|
|
- Added `payment_status` field for status visibility
|
|
- Relationship with JobPayment model
|
|
|
|
### ✅ 5. Refund Mechanism
|
|
|
|
#### Features:
|
|
- Automatic refund for failed/cancelled jobs
|
|
- Refund to specified address
|
|
- Transaction hash tracking for refunds
|
|
|
|
### ✅ 6. Payment Receipt Generation
|
|
|
|
#### Features:
|
|
- Detailed payment receipts with verification status
|
|
- Transaction hash inclusion
|
|
- Timestamp tracking for all payment events
|
|
|
|
### ✅ 7. Integration Test Updates
|
|
|
|
#### Test: `test_job_payment_flow`
|
|
- Creates job with payment amount
|
|
- Verifies payment creation
|
|
- Tests payment status tracking
|
|
- Attempts payment release (gracefully handles wallet daemon unavailability)
|
|
|
|
## Database Schema
|
|
|
|
### New Tables:
|
|
|
|
#### `job_payments`
|
|
- id (PK)
|
|
- job_id (indexed)
|
|
- amount (DECIMAL(20,8))
|
|
- currency
|
|
- status
|
|
- payment_method
|
|
- escrow_address
|
|
- refund_address
|
|
- transaction_hash
|
|
- refund_transaction_hash
|
|
- Timestamps (created, updated, escrowed, released, refunded, expires)
|
|
|
|
#### `payment_escrows`
|
|
- id (PK)
|
|
- payment_id (indexed)
|
|
- amount
|
|
- currency
|
|
- address
|
|
- Status flags (is_active, is_released, is_refunded)
|
|
- Timestamps
|
|
|
|
### Updated Tables:
|
|
|
|
#### `job`
|
|
- Added payment_id (FK to job_payments)
|
|
- Added payment_status (VARCHAR)
|
|
|
|
## API Examples
|
|
|
|
### Create Job with Payment
|
|
```json
|
|
POST /v1/jobs
|
|
{
|
|
"payload": {
|
|
"job_type": "ai_inference",
|
|
"parameters": {"model": "gpt-4", "prompt": "Hello"}
|
|
},
|
|
"ttl_seconds": 900,
|
|
"payment_amount": 0.001,
|
|
"payment_currency": "BTC"
|
|
}
|
|
```
|
|
|
|
### Response with Payment Info
|
|
```json
|
|
{
|
|
"job_id": "abc123",
|
|
"state": "queued",
|
|
"payment_id": "pay456",
|
|
"payment_status": "escrowed",
|
|
...
|
|
}
|
|
```
|
|
|
|
### Release Payment
|
|
```json
|
|
POST /v1/payments/pay456/release
|
|
{
|
|
"job_id": "abc123",
|
|
"reason": "Job completed successfully"
|
|
}
|
|
```
|
|
|
|
## Files Created/Modified
|
|
|
|
### New Files:
|
|
- `apps/coordinator-api/src/app/schemas/payments.py` - Payment schemas
|
|
- `apps/coordinator-api/src/app/domain/payment.py` - Payment domain models
|
|
- `apps/coordinator-api/src/app/services/payments.py` - Payment service
|
|
- `apps/coordinator-api/src/app/routers/payments.py` - Payment endpoints
|
|
- `apps/coordinator-api/migrations/004_payments.sql` - Database migration
|
|
|
|
### Modified Files:
|
|
- `apps/coordinator-api/src/app/domain/job.py` - Added payment tracking
|
|
- `apps/coordinator-api/src/app/schemas.py` - Added payment fields to JobCreate/JobView
|
|
- `apps/coordinator-api/src/app/services/jobs.py` - Integrated payment creation
|
|
- `apps/coordinator-api/src/app/routers/client.py` - Added payment handling
|
|
- `apps/coordinator-api/src/app/main.py` - Added payments router
|
|
- `apps/coordinator-api/src/app/routers/__init__.py` - Exported payments router
|
|
- `tests/integration/test_full_workflow.py` - Updated payment test
|
|
|
|
## Next Steps
|
|
|
|
1. **Deploy Database Migration**
|
|
```sql
|
|
-- Apply migration 004_payments.sql
|
|
```
|
|
|
|
2. **Start Wallet Daemon**
|
|
```bash
|
|
# Ensure wallet daemon is running on port 20000
|
|
./scripts/wallet-daemon.sh start
|
|
```
|
|
|
|
3. **Test Payment Flow**
|
|
```bash
|
|
# Run the updated integration test
|
|
python -m pytest tests/integration/test_full_workflow.py::TestWalletToCoordinatorIntegration::test_job_payment_flow -v
|
|
```
|
|
|
|
4. **Configure Production**
|
|
- Update wallet daemon URL in production
|
|
- Set appropriate escrow timeouts
|
|
- Configure payment thresholds
|
|
|
|
## Security Considerations
|
|
|
|
- All payment endpoints require API key authentication
|
|
- Payment amounts are validated as positive numbers
|
|
- Escrow addresses are generated securely by wallet daemon
|
|
- Refunds only go to specified refund addresses
|
|
- Transaction hashes provide audit trail
|
|
|
|
## Monitoring
|
|
|
|
Payment events should be monitored:
|
|
- Failed escrow creations
|
|
- Expired escrows
|
|
- Refund failures
|
|
- Payment status transitions
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Multi-currency Support** - Add support for AITBC tokens
|
|
2. **Payment Routing** - Route payments through multiple providers
|
|
3. **Batch Payments** - Support batch release/refund operations
|
|
4. **Payment History** - Enhanced payment tracking and reporting
|