bisq-bot/bot/ARCHITECTURE.md

Bisq Bot Architecture

Overview

The Bisq Bot is a Nostr-based application that queries a local Bisq daemon and provides marketplace information to Nostr users. It's designed as a modular, async-first system with support for multiple Nostr relays.

High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                  BisqBot (Main Orchestrator)            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────┐  ┌──────────────────────────────┐ │
│  │ NostrHandler    │  │ BisqClient                   │ │
│  ├─────────────────┤  ├──────────────────────────────┤ │
│  │ • Multi-relay   │  │ • bisq-cli wrapper           │ │
│  │   management    │  │ • Async queries              │ │
│  │ • Event sub     │  │ • Error handling             │ │
│  │ • Publishing    │  │ • Data parsing               │ │
│  │ • Dedup         │  │                              │ │
│  └────────┬────────┘  └──────────────┬───────────────┘ │
│           │                          │                 │
│           └──────────┬───────────────┘                 │
│                      │                                 │
│  ┌─────────────────────────────────────────────────┐  │
│  │           MessageParser                         │  │
│  │  • Command extraction from Nostr mentions       │  │
│  │  • Pattern matching                             │  │
│  │  • Query normalization                          │  │
│  └─────────────────────────────────────────────────┘  │
│                      │                                 │
│  ┌─────────────────────────────────────────────────┐  │
│  │           Formatter                             │  │
│  │  • Response formatting for Nostr publication    │  │
│  │  • Error message formatting                     │  │
│  │  • Output sanitization                          │  │
│  └─────────────────────────────────────────────────┘  │
│                                                     │
└─────────────────────────────────────────────────────┘
        │                                    │
        ▼                                    ▼
    ┌─────────────────┐            ┌──────────────┐
    │  Nostr Relays   │            │ Bisq Daemon  │
    │ (Multiple in    │            │   (RPC)      │
    │  parallel)      │            │              │
    └─────────────────┘            └──────────────┘

Component Details

1. NostrHandler (src/nostr_handler.py)

Purpose: Manages all Nostr relay connections and event lifecycle

Key Features:

• Multi-relay support: Maintains simultaneous connections to multiple relays
• Relay options: Configurable read/write settings per relay
• Event subscription: Filters for specific event kinds and tags
• Event publishing: Publishes events to all connected relays
• Deduplication: Prevents duplicate processing from multiple relay sources
• Async operations: Non-blocking, efficient event handling

API:

# Initialize with private key and relay list
handler = NostrHandler(private_key_hex, relays=["wss://relay.damus.io", ...])

# Connect to relays
await handler.connect()

# Subscribe to mentions
await handler.subscribe_to_mentions(bot_pubkey)

# Register event handlers
handler.on_event(async_callback)

# Publish events
event_id = await handler.publish_event(content, kind=1, tags=[...])

# Check status
status = handler.get_relay_status()

Multi-Relay Design:

• Each relay added with add_relay_with_opts()
• Client handles multiplexing internally
• Events can arrive from any relay (race condition handled)
• Publishing sends to all relays simultaneously
• If relay disconnects, others continue working

2. BisqClient (src/bisq_client.py)

Purpose: Provides async interface to local Bisq daemon via bisq-cli

Key Features:

• Subprocess wrapper: Safely runs bisq-cli commands
• JSON parsing: Parses Bisq responses
• Error handling: Timeout and error detection
• Data models: Offer dataclass for type safety
• Sorting: Offers sorted by price for readability
• Async-compatible: Returns immediately, doesn't block event loop

API:

client = BisqClient(host="127.0.0.1", port=4848)

# Get marketplace offers
offers = await client.get_offers(
    direction=Direction.BUY,
    currency_code="USD",
    limit=10
)

# Get market statistics
stats = await client.get_market_stats()

# Get supported currencies
currencies = await client.get_supported_currencies()

Error Handling:

• Command timeouts (30 second limit)
• Invalid JSON responses
• Non-zero exit codes
• Missing fields in data

Data Models:

@dataclass
class Offer:
    id: str                  # Offer ID
    direction: str          # BUY or SELL
    price: float            # Price per BTC
    amount: float           # Amount in BTC
    currency_code: str      # Currency (USD, EUR, etc.)
    payment_method: str     # Payment method

3. MessageParser (src/message_parser.py)

Purpose: Extracts structured commands from Nostr mention text

Key Features:

• Pattern matching: Regex-based command detection
• Flexible parsing: Multiple input formats supported
• Fallback parsing: Handles simple "USD BUY" format
• Command types: Enum-based command classification
• Mention detection: Finds bot mentions in event content

Supported Commands:

GET_OFFERS:  "USD BUY", "get EUR sell", "show GBP buy"
GET_STATS:   "stats", "market", "prices"
HELP:        "help"
UNKNOWN:     Unrecognized input

API:

parsed = MessageParser.parse_command(event, bot_pubkey)
if parsed and parsed.command_type == CommandType.GET_OFFERS:
    print(f"{parsed.direction} {parsed.currency_code}")

Parsing Flow:

1. Extract text after bot mention
2. Normalize (lowercase, trim)
3. Try regex patterns
4. Fall back to simple "CURRENCY DIRECTION" format
5. Return ParsedCommand or None

4. Formatter (src/formatter.py)

Purpose: Formats data into Nostr-compatible messages

Key Features:

• Message formatting: Readable output for various data types
• Length checking: Respects Nostr message size limits
• Error formatting: User-friendly error messages
• Date formatting: Human-readable timestamps
• Price formatting: Readable currency display

API:

# Format offers
response = Formatter.format_offers(offers, "USD", Direction.BUY)

# Format error
error_msg = Formatter.format_error("Bisq daemon offline")

# Format stats
stats_msg = Formatter.format_market_stats(stats_dict)

# Format help
help_text = Formatter.format_help_message()

5. BisqBot (src/bot.py)

Purpose: Main orchestration class coordinating all components

Responsibilities:

• Initialize all components
• Set up event handlers
• Coordinate request-response flow
• Handle errors gracefully
• Manage bot lifecycle

Event Flow:

User mention
    ↓
NostrHandler receives event
    ↓
BisqBot.handle_message()
    ↓
MessageParser.parse_command()
    ↓
BisqBot._process_command()
    ↓
BisqClient queries Bisq
    ↓
Formatter formats response
    ↓
NostrHandler publishes event
    ↓
Response arrives on Nostr relays

API:

bot = BisqBot()
await bot.start()  # Runs indefinitely
await bot.stop()   # Graceful shutdown

6. Config (src/config.py)

Purpose: Centralized configuration management

Features:

• Environment variable loading
• Validation of required parameters
• Type-safe configuration object
• Sensible defaults

Environment Variables:

NOSTR_RELAYS           # Comma-separated relay URLs
BOT_PRIVATE_KEY        # Hex-encoded Nostr private key
BISQ_PORT              # Bisq RPC port (default: 4848)
BISQ_HOST              # Bisq RPC host (default: 127.0.0.1)
BOT_NAME               # Display name (default: bisqbot)
REQUEST_TIMEOUT        # Request timeout in seconds (default: 10)

Data Flow Examples

Example 1: User Queries Offers

Timeline:
T0: User publishes note "USD BUY @bisqbot" to Nostr
T1: Nostr relays propagate event
T2: Bot's NostrHandler receives event from relay (could be any relay)
T3: Bot's event handler invoked
T4: MessageParser extracts: command=GET_OFFERS, currency=USD, direction=BUY
T5: Bot queries BisqClient
T6: BisqClient runs: bisq-cli --port=4848 getoffers --direction=BUY --currency-code=USD
T7: Bisq daemon responds with JSON
T8: BisqClient parses offers, sorts by price, returns top 10
T9: Formatter creates readable message
T10: Bot publishes response to all configured relays
T11: User's Nostr client receives response (from any relay)
T12: User reads offer list

Latency: Typically 2-5 seconds (dominated by Bisq query time)

Example 2: Bot Connects to Multiple Relays

Configuration:
NOSTR_RELAYS=wss://relay.damus.io,wss://relay.nostr.band,wss://nos.lol

Bot startup:
1. NostrHandler.connect() called
2. Client created with bot's keypair
3. Relay 1 (damus): add_relay_with_opts() - SUCCESS
4. Relay 2 (nostr.band): add_relay_with_opts() - SUCCESS
5. Relay 3 (nos.lol): add_relay_with_opts() - TIMEOUT, logged as warning
6. await client.connect() - connects all added relays
7. Bot subscribes to mentions with filter kind=1, p_tag=bot_pubkey

User interaction:
- User posts mention on Nostr
- Event propagates to all relays
- Bot receives event from first relay to deliver it
- Bot deduplicates if event arrives from other relays
- Bot publishes response
- Response sent to all 3 relays (damus, nostr.band, nos.lol)
- Response eventually arrives at user's relay (may be different from where they posted)

Error Handling Strategy

Bisq Daemon Errors

• Not running: Return user-friendly "Bisq unavailable" message
• Timeout: Return "Bisq query timed out" after 30 seconds
• Invalid output: Return "Invalid response from Bisq"
• No offers: Return "No offers available" (not an error)

Nostr Relay Errors

• Connection failed: Log warning, try next relay (graceful degradation)
• Publish failed: Log error, inform user in response
• Subscription failed: Log error, attempt reconnect with backoff

Message Parsing Errors

• Unrecognized command: Ignore message (not an error)
• Invalid parameters: Handled in command processing

Performance Characteristics

Query Performance

Operation	Time	Notes
NostrHandler.connect()	2-5s	Per relay
Bisq query	1-3s	Via bisq-cli
Message parsing	<10ms	Regex matching
Formatter	<10ms	String building
Nostr publish	<1s	Network round-trip
Total response	2-10s	Typically 3-5s

Memory Usage

Component	Memory	Notes
NostrHandler	5-10 MB	Per relay connection
BisqClient	<1 MB	Subprocess wrapper
Event dedup cache	5-10 MB	Up to 10k events
Total base	~50 MB	Minimal overhead

Concurrency

• Multiple users: Each query fully async, non-blocking
• Multiple relays: All relays read simultaneously
• Event loop: Single-threaded async with no blocking I/O
• Scalability: Can handle thousands of queries without issue

Extension Points

Adding New Commands

1. Update CommandType enum

   class CommandType(Enum):
       NEW_COMMAND = "new_command"
   

2. Add pattern to MessageParser

   COMMAND_PATTERNS = {
       "new_command": r"pattern.*regex",
   }
   

3. Add handler to BisqBot

   if parsed_cmd.command_type == CommandType.NEW_COMMAND:
       return await self._handle_new_command()
   

4. Add formatter to Formatter

   @staticmethod
   def format_new_command(data):
       return "Formatted output"
   

Adding New Relays

No code changes needed - just add to NOSTR_RELAYS in .env:

NOSTR_RELAYS=wss://relay1.com,wss://relay2.com,wss://relay3.com

Customizing Response Format

Edit Formatter methods to change output style, language, or information included.

Adding Database Support

For Phase 3, a PostgreSQL layer can be added:

• Between BisqClient and cache
• Store offers, statistics, user interactions
• Enable historical analysis and trends
• Time-series data collection

Testing Strategy (Phase 2)

Unit Tests

• BisqClient: Mock bisq-cli commands
• MessageParser: Test various input formats
• Formatter: Validate output format
• Config: Test environment loading

Integration Tests

• End-to-end message flow
• Multi-relay connection handling
• Error scenarios

Mock Components

• Mock Nostr relays for fast testing
• Mock bisq-cli responses
• Isolated event handling

Deployment Architecture

Single-Node Deployment

Debian VM
├── Python 3.11
├── Virtual environment
├── Bisq bot service (systemd)
├── Bisq daemon (separate)
└── PostgreSQL (Phase 3)

High-Availability (Future)

Load Balancer
├── Bot Instance 1 (Primary)
├── Bot Instance 2 (Secondary)
└── Shared Database (PostgreSQL)

Security Considerations

Private Key Management

• Stored in .env file (excluded from git)
• Never logged or displayed
• Loaded once at startup
• Used only for signing responses

Input Validation

• Commands parsed carefully
• Regex patterns prevent injection
• All data sanitized before display

Relay Security

• Relays added explicitly (no discovery)
• TLS connections (wss://)
• Relay authentication possible (future)

System Security

• Runs as dedicated bisq user (not root)
• Filesystem permissions restricted
• Resource limits enforced (RAM, CPU)
• Logs don't contain sensitive data

Monitoring and Observability

Logging

• Structured logs with timestamps
• Error stack traces for debugging
• Event tracing for request flow
• Relay connection status

Metrics (Future)

• Response time histograms
• Error rates by type
• Relay health metrics
• Query volume trends

Next Phases

Phase 2: Advanced Interactions

• DM-based conversations
• Multi-turn dialogues
• User authentication
• Price alerts and subscriptions

Phase 3: Scheduled Tasks

• Daily market statistics
• Historical data collection
• Database persistence
• Trend analysis

Phase 4: Analytics

• Market dashboards
• Volume analysis
• Price trends
• Trading insights