aitbc/docs/apps/blockchain/blockchain-event-bridge.md

Blockchain Event Bridge

Bridge between AITBC blockchain events and hermes agent triggers using a hybrid event-driven and polling approach.

Overview

This service connects AITBC blockchain events (blocks, transactions, smart contract events) to hermes agent actions through:

• Event-driven: Subscribe to gossip broker topics for real-time critical triggers
• Polling: Periodic checks for batch operations and conditions
• Smart Contract Events: Monitor contract events via blockchain RPC (Phase 2)

Features

• Subscribes to blockchain block events via gossip broker
• Subscribes to transaction events (when available)
• Monitors smart contract events via blockchain RPC:
  • AgentStaking (stake creation, rewards, tier updates)
  • PerformanceVerifier (performance verification, penalties, rewards)
  • AgentServiceMarketplace (service listings, purchases)
  • BountyIntegration (bounty creation, completion)
  • CrossChainBridge (bridge initiation, completion)
• Triggers coordinator API actions based on blockchain events
• Triggers agent daemon actions for agent wallet transactions
• Triggers marketplace state updates
• Configurable action handlers (enable/disable per type)
• Prometheus metrics for monitoring
• Health check endpoint

Installation

cd apps/blockchain-event-bridge
poetry install

Configuration

Environment variables:

• BLOCKCHAIN_RPC_URL - Blockchain RPC endpoint (default: http://localhost:8006)
• GOSSIP_BACKEND - Gossip broker backend: memory, broadcast, or redis (default: memory)
• GOSSIP_BROADCAST_URL - Broadcast URL for Redis backend (optional)
• COORDINATOR_API_URL - Coordinator API endpoint (default: http://localhost:8011)
• COORDINATOR_API_KEY - Coordinator API key (optional)
• SUBSCRIBE_BLOCKS - Subscribe to block events (default: true)
• SUBSCRIBE_TRANSACTIONS - Subscribe to transaction events (default: true)
• ENABLE_AGENT_DAEMON_TRIGGER - Enable agent daemon triggers (default: true)
• ENABLE_COORDINATOR_API_TRIGGER - Enable coordinator API triggers (default: true)
• ENABLE_MARKETPLACE_TRIGGER - Enable marketplace triggers (default: true)
• ENABLE_POLLING - Enable polling layer (default: false)
• POLLING_INTERVAL_SECONDS - Polling interval in seconds (default: 60)

Running

Development

poetry run uvicorn blockchain_event_bridge.main:app --reload --host 127.0.0.1 --port 8204

Production (Systemd)

sudo systemctl start aitbc-blockchain-event-bridge
sudo systemctl enable aitbc-blockchain-event-bridge

API Endpoints

• GET / - Service information
• GET /health - Health check
• GET /metrics - Prometheus metrics

Architecture

blockchain-event-bridge/
├── src/blockchain_event_bridge/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings
│   ├── bridge.py            # Core bridge logic
│   ├── metrics.py           # Prometheus metrics
│   ├── event_subscribers/   # Event subscription modules
│   ├── action_handlers/     # Action handler modules
│   └── polling/             # Polling modules
└── tests/

Event Flow

1. Blockchain publishes block event to gossip broker (topic: "blocks")
2. Block event subscriber receives event
3. Bridge parses block data and extracts transactions
4. Bridge triggers appropriate action handlers:
   • Coordinator API handler for AI jobs, agent messages
   • Agent daemon handler for agent wallet transactions
   • Marketplace handler for marketplace listings
5. Action handlers make HTTP calls to respective services
6. Metrics are recorded for monitoring

CLI Commands

The blockchain event bridge service includes CLI commands for management and monitoring:

# Health check
aitbc-cli bridge health

# Get Prometheus metrics
aitbc-cli bridge metrics

# Get detailed service status
aitbc-cli bridge status

# Show current configuration
aitbc-cli bridge config

# Restart the service (via systemd)
aitbc-cli bridge restart

All commands support --test-mode flag for testing without connecting to the service.

Testing

poetry run pytest

Future Enhancements

• Phase 2: Smart contract event subscription
• Phase 3: Enhanced polling layer for batch operations
• WebSocket support for real-time event streaming
• Event replay for missed events