bisq-bot/bot/RELAY_STRATEGY.md

Multi-Relay Strategy

Comprehensive guide to the bot's multi-relay architecture and how to configure it for optimal performance.

Why Multiple Relays?

Redundancy

• If one relay goes offline, bot continues working
• Users connected to different relays can still see responses
• Single relay failure doesn't break the service

Coverage

• Reaches users subscribed to different relays
• Different relays have different user bases
• Increases discoverability

Performance

• Can read from fastest relay (parallel queries)
• Publish to all relays ensures delivery
• No single point of failure

Resilience

• Automatic reconnection with exponential backoff
• Graceful degradation if relay is slow
• Event deduplication prevents duplicates from multiple sources

Architecture

Connection Model

              ┌──────────────────────┐
              │   BisqBot Service    │
              └──────────────────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
         ▼            ▼            ▼
    ┌────────┐  ┌────────┐  ┌────────┐
    │Relay A │  │Relay B │  │Relay C │
    │(damus) │  │(nostr) │  │(nos)   │
    └────────┘  └────────┘  └────────┘
         │            │            │
         └────────────┼────────────┘
                      │
                ┌─────▼─────┐
                │  Bisq DM  │
                └───────────┘

Read Path (Parallel)

User publishes note mentioning bot
    ↓
Nostr network propagates
    ↓
┌───────────────────────────────────┐
│  Relays receive and store event   │
│  • Relay A: event arrives at T=100ms
│  • Relay B: event arrives at T=150ms
│  • Relay C: event arrives at T=200ms
└───────────────────────────────────┘
    ↓
┌───────────────────────────────────┐
│  Bot subscribes to all relays     │
│  (simultaneous subscriptions)     │
└───────────────────────────────────┘
    ↓
┌───────────────────────────────────┐
│  Bot receives from fastest relay  │
│  (T=100ms from Relay A)           │
│  • Bot processes immediately      │
│  • Event deduplication prevents   │
│    duplicate processing from B, C │
└───────────────────────────────────┘

Write Path (Broadcast)

Bot generates response
    ↓
Publish event to all relays (simultaneous)
    ↓
┌───────────────────────────────────┐
│  Relay A: published (T=50ms)      │
│  Relay B: published (T=55ms)      │
│  Relay C: published (T=60ms)      │
└───────────────────────────────────┘
    ↓
Nostr network propagates response
    ↓
User's client (subscribed to any relay) receives response

Configuration

Basic Setup (Recommended)

Default includes 3 geographically diverse, well-established relays:

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

Why these?

• relay.nostr.band: Low latency, excellent uptime, global CDN
• relay.damus.io: Early, stable, reliable, strong community
• nos.lol: Fast, good coverage, uptime focus

Expected uptime: 99.5%+ (all three running)

Adding More Relays

For higher coverage or geographic redundancy:

NOSTR_RELAYS=wss://relay.nostr.band,wss://relay.damus.io,wss://nos.lol,wss://offchain.pub,wss://nostr.wine,wss://relay.current.fyi

Additional relays:

• offchain.pub: Strong Bitcoin community
• nostr.wine: EU-based, good latency from Europe
• relay.current.fyi: Well-maintained, good uptime

High-Performance Setup

For maximum throughput with focus on reliability:

NOSTR_RELAYS=wss://relay.nostr.band,wss://relay.damus.io,wss://nos.lol,wss://nostr-pub.semisol.dev

Keep to 4-5 relays max for operational sanity.

Minimal Setup

For testing or resource-constrained environments:

NOSTR_RELAYS=wss://relay.nostr.band

Trade-off: Single point of failure, but simplest setup for testing.

Performance Characteristics

Latency

With 3 relays configured (typical):

Operation	Latency	Notes
Connection	2-5s	Per relay, parallel
Event receipt	50-200ms	From fastest relay
Subscription	1s	Per relay, parallel
Publish	<1s	Simultaneous to all
Total response	2-10s	Bisq query dominates

Bandwidth

Per user interaction:

• Download: ~2KB per event (Nostr event JSON)
• Upload: ~1KB per response
• Per relay: x3 for 3 relays

Monthly estimate for 100 users/day:

• 3KB/user/interaction × 100 users/day × 30 days = 9 MB (negligible)

Memory

Multi-relay impact:

Component	Memory per relay
Connection	1-2 MB
Subscription	<1 MB
Event buffer	Variable
Total per relay	~5-10 MB

With 5 relays: ~50 MB total (acceptable)

CPU

Minimal impact from extra relays:

• Most work in async event handling (I/O bound)
• Event deduplication is O(1) hash lookup
• CPU usage remains under 5% with 5 relays

Relay Health Monitoring

Check Relay Status

The bot logs connection status at startup:

journalctl -u bisq-bot -n 20 | grep -i relay

Output:

Added relay: wss://relay.nostr.band
Added relay: wss://relay.damus.io
Added relay: wss://nos.lol
Connected to Nostr relays
Subscribing to mentions of abc123...

Manual Relay Testing

Test individual relay connectivity:

# Install nostr-tools CLI (if available)
npm install -g nostr-tools

# Or test with curl
curl -I wss://relay.nostr.band

Monitor Relay Health Over Time

Check logs for relay-specific messages:

# Look for connection issues
journalctl -u bisq-bot -n 100 | grep -i "failed\|error\|timeout"

# Look for relay-specific problems
journalctl -u bisq-bot -n 100 | grep "relay"

Handling Relay Failures

Automatic Recovery

The bot handles failures gracefully:

Relay fails
    ↓
NostrHandler logs error
    ↓
Continues with remaining relays
    ↓
Reconnection attempt (with backoff)
    ↓
Service continues normally

No manual intervention needed.

Single Relay Down

With 3 relays configured, if one is down:

• ✅ Bot continues functioning
• ✅ Events still delivered to other relays
• ✅ Users on down relay won't see responses until it recovers
• ✅ Automatic reconnection restores functionality

Multiple Relays Down

If 2+ relays are down:

• ⚠️ Bot still functions with remaining relay
• ⚠️ Coverage is reduced
• ✅ Service doesn't stop
• ✅ Manual intervention usually not needed

All Relays Down

Unlikely (requires multiple independent failures):

• ❌ Bot can't publish or receive
• ✅ Local daemon operations continue
• ✅ Manual intervention: restart bot or fix relays

Mitigation: Add more relays to reduce probability.

Optimization Strategies

For Latency

1. Use geographically local relays

   NOSTR_RELAYS=wss://relay.example.com  # Your region
   

2. Monitor event receipt times

   journalctl -u bisq-bot | grep "Received event"
   

3. Consider relay round-trip time

   ping relay.nostr.band
   

For Coverage

1. Add relays targeting different user bases

   • European focus: nostr.wine, offchain.pub
   • US focus: relay.damus.io
   • Global: relay.nostr.band

2. Include specialized relays if appropriate

   • Bitcoin relay for Bisq audience
   • Privacy relay for privacy-conscious users

3. Monitor user request sources

   • Which relay do most users connect through?
   • Add that relay if missing

For Reliability

1. Use established relays with high uptime

   • Check status pages: https://nostr-status.org
   • Avoid experimental/new relays in production

2. Add N+1 redundancy

   • If 2 relays needed, configure 3
   • If 3 relays needed, configure 4

3. Monitor relay health proactively

   • Set up monitoring (future phase)
   • Check logs regularly

Cost Implications

Bandwidth

Multi-relay increases bandwidth:

• 1 relay: baseline
• 3 relays: 3x bandwidth
• Typical usage: <100 MB/month

Cost: Negligible for most setups

Infrastructure

No additional infrastructure needed:

• All relays are external (managed by relay operators)
• Bot only needs outgoing websocket connections
• Standard firewall rules apply

Operational Overhead

Minimal additional complexity:

• Add relays in .env (one-liner)
• Monitoring logic built-in
• No additional tools needed

Advanced Scenarios

Relay Preference

For some use cases, relay selection matters:

Bitcoin-focused community:

NOSTR_RELAYS=wss://bitcoinfeed.example.com,wss://relay.nostr.band,wss://relay.damus.io

European users:

NOSTR_RELAYS=wss://relay.nostr.band,wss://nostr.wine,wss://offchain.pub

Privacy-focused:

NOSTR_RELAYS=wss://relay.nostr.band,wss://privacy-relay.example.com

Relay Switching (Phase 2+)

Potential future features:

• Publish to relay subset based on event type
• Different relays for different content types
• Geographic relay selection based on request origin

Load Balancing (Phase 3+)

For high-traffic scenarios:

• Multiple bot instances
• Distributed relay subscriptions
• Shared event cache
• Load balancer frontend

Best Practices

Configuration

✅ Do:

• Start with 3 relays (good balance)
• Use established, high-uptime relays
• Monitor relay status regularly
• Update relay list if needed

❌ Don't:

• Use too many relays (>10)
• Use only experimental relays
• Ignore relay failures
• Change relays without testing

Monitoring

✅ Do:

• Check logs weekly
• Monitor response times
• Track relay connectivity
• Alert on failures

❌ Don't:

• Ignore error messages
• Leave failing relays in config indefinitely
• Assume all relays have equal performance
• Forget to test new relay additions

Troubleshooting

When relay issues occur:

1. Check logs first

   journalctl -u bisq-bot -f
   

2. Test relay connectivity

   curl -I wss://relay.example.com
   

3. Check relay status page

   • Visit relay's web interface
   • Look for maintenance notices

4. Test with fewer relays

   • Temporarily reduce to 1 relay
   • Confirms if relay issue or bot issue

5. Restart bot if stuck

   sudo systemctl restart bisq-bot
   

References

Relay Lists

• Relay Status
• Relay Directory
• Popular Relays

Documentation

• NIP-01: Basic Protocol
• Relay Recommendations

Tools

• NoStr Relay Checker
• Relay Uptime Monitor

Summary

The Bisq Bot's multi-relay architecture provides:

• ✅ Redundancy: Service continues if relay fails
• ✅ Coverage: Reaches users on different relays
• ✅ Performance: Read from fastest, publish to all
• ✅ Simplicity: Just list relays in .env
• ✅ Scalability: Works with 1 to 10+ relays

Recommended production setup:

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

This balance provides excellent coverage with minimal overhead.