aitbc/docs/reference/3_wallet-coordinator-integration.md

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

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

{
    "job_id": "abc123",
    "state": "queued",
    "payment_id": "pay456",
    "payment_status": "escrowed",
    ...
}

Release Payment

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

   -- Apply migration 004_payments.sql
   

2. Start Wallet Daemon

   # Ensure wallet daemon is running on port 20000
   ./scripts/wallet-daemon.sh start
   

3. Test Payment Flow

   # 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