Relay Manager

This module provides a management layer for handling multiple Nostr relay connections.

Overview

The RelayManager class manages connections to multiple Nostr relays, handling message passing, event fetching, and event publishing across all of them.

Typical usage:

import asyncio
from pynostr.key import PrivateKey
from pynostr.filters import Filters
from agentstr.relays.relay_manager import RelayManager

async def main():
    # A list of public relays
    relay_urls = ["wss://relay.damus.io", "wss://relay.primal.net"]

    # Generate a new private key for demonstration
    private_key = PrivateKey()

    # Initialize the RelayManager
    relay_manager = RelayManager(relay_urls, private_key)

    # Create filters to fetch recent text notes
    filters = Filters(kinds=[1], limit=5)

    # Fetch events from all relays
    events = await relay_manager.get_events(filters)

    if events:
        print(f"Fetched {len(events)} unique events from {len(relay_urls)} relays:")
        for event in events:
            print(f" - Event content: {event.content}")
    else:
        print("No events found.")

if __name__ == "__main__":
    asyncio.run(main())

Reference

class agentstr.relays.relay_manager.RelayManager(relays: list[str], private_key: PrivateKey | None = None)

Bases: object

Manages connections to multiple Nostr relays and handles message passing.

Parameters:

• relays – List of relay URLs to connect to.

• private_key – Optional private key for signing events.

__init__(relays: list[str], private_key: PrivateKey | None = None)

property relays: list[EventRelay]

Get a list of connected EventRelay instances.

Returns:

A list of EventRelay instances, one for each relay URL.

async get_events(filters: Filters, limit: int = 10, timeout: int = 30, close_on_eose: bool = True) → list[Event]

Fetch events matching the given filters from connected relays.

Parameters:

• filters – The filters to apply when fetching events.

• limit – Maximum number of events to return. Defaults to 10.

• timeout – Maximum time to wait for events in seconds. Defaults to 30.

• close_on_eose – Whether to close the subscription after EOSE. Defaults to True.

Returns:

A list of up to limit unique events that match the filters.

Note

Stops early if enough events are found before the timeout.

async get_event(filters: Filters, timeout: int = 30, close_on_eose: bool = True) → Event

Get a single event matching the filters or None if not found.

async send_event(event: Event) → Event

Send an event to all connected relays.

encrypt_message(message: str | dict, recipient_pubkey: str, tags: dict[str, str] | None = None) → Event

Encrypt a message for the recipient and prepare it as a Nostr event.

async send_message(message: str | dict, recipient_pubkey: str, tags: dict[str, str] | None = None) → Event

Send an encrypted message to a recipient through all connected relays.

async receive_message(author_pubkey: str, timestamp: int | None = None, timeout: int = 30) → DecryptedMessage | None

Wait for and return the next message from the specified author.

async send_receive_message(message: str | dict, recipient_pubkey: str, timeout: int = 3, tags: dict[str, str] | None = None) → DecryptedMessage | None

Send a message and wait for a response from the recipient.

Returns the first response received within the timeout period.

async event_listener(filters: Filters, callback: Callable[[Event], None])

Start listening for events matching the given filters.

The callback will be called for each matching event.

async direct_message_listener(filters: Filters, callback: Callable[[Event, str], None])

Start listening for direct messages.

The callback will be called with each received message and its decrypted content.

async get_following(pubkey: str | None = None) → list[str]

Get the list of public keys that the specified user follows.

async set_following(pubkey: str | None = None, following: list[str] | None = None)

Set the list of public keys that the specified user follows.

async add_following(pubkey: str | None = None, following: list[str] | None = None)

Add a list of public keys to the specified user’s following list.