852f2e5a8a
Some checks failed
Cross-Node Transaction Testing / transaction-test (push) Has been cancelled
Deploy to Testnet / deploy-testnet (push) Has been cancelled
Documentation Validation / validate-docs (push) Has been cancelled
Documentation Validation / validate-policies-strict (push) Has been cancelled
Multi-Node Stress Testing / stress-test (push) Has been cancelled
Node Failover Simulation / failover-test (push) Has been cancelled
Integration Tests / test-service-integration (push) Has been cancelled
Security Scanning / security-scan (push) Has been cancelled
Python Tests / test-python (push) Has been cancelled
CLI Tests / test-cli (push) Has been cancelled
Blockchain Synchronization Verification / sync-verification (push) Successful in 11s
Contract Performance Benchmarks / benchmark-gas-usage (push) Successful in 1m36s
Contract Performance Benchmarks / benchmark-execution-time (push) Successful in 1m24s
Contract Performance Benchmarks / benchmark-throughput (push) Successful in 1m25s
Cross-Chain Functionality Tests / test-cross-chain-sync (push) Successful in 2s
Cross-Chain Functionality Tests / test-cross-chain-transactions (push) Successful in 5s
Cross-Chain Functionality Tests / test-cross-chain-bridge (push) Has been skipped
Cross-Chain Functionality Tests / test-multi-chain-consensus (push) Successful in 3s
Cross-Chain Functionality Tests / aggregate-results (push) Has been skipped
Multi-Chain Island Architecture Tests / test-multi-chain-island (push) Successful in 2s
Multi-Node Blockchain Health Monitoring / health-check (push) Successful in 3s
P2P Network Verification / p2p-verification (push) Successful in 2s
Smart Contract Tests / test-solidity (map[name:aitbc-contracts path:contracts]) (push) Failing after 1m28s
Smart Contract Tests / test-solidity (map[name:aitbc-token path:packages/solidity/aitbc-token]) (push) Successful in 21s
Smart Contract Tests / test-foundry (push) Failing after 20s
Smart Contract Tests / lint-solidity (push) Successful in 30s
Smart Contract Tests / deploy-contracts (push) Successful in 1m40s
Systemd Sync / sync-systemd (push) Successful in 26s
Contract Performance Benchmarks / compare-benchmarks (push) Successful in 4s
- Update workflow paths from docs/openclaw to docs/hermes - Rename skill prefixes from openclaw-* to hermes-* - Update agent skill references in refactoring and analysis docs - Rename OPENCLAW_AITBC_MASTERY_PLAN.md to reflect hermes branding - Update CLI examples and command references throughout documentation
136 lines
4.3 KiB
Markdown
136 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
poetry run uvicorn blockchain_event_bridge.main:app --reload --host 127.0.0.1 --port 8204
|
|
```
|
|
|
|
### Production (Systemd)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|