Relay Manager

This module provides a management layer for handling multiple Nostr relay connections. It offers features for connection pooling and failover management to ensure reliable and efficient communication with the Nostr network.

class agentstr.relay_manager.RelayManager(relays: list[str], private_key: str | 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: str | 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, event_ref: 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, event_ref: 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, event_ref: 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.