oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity
Files
a77eae95171eebc72f0bdee15358b3c155dca5dd
aitbc/docs/5_reference/3_wallet-coordinator-integration.md
oib 06e48ef34b 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
2026-02-13 22:39:43 +01:00

5.2 KiB
Raw Blame History

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