Struct Client

pub struct Client { /* private fields */ }

Nostr client

Implementations

impl Client

pub fn new<T>(signer: T) -> Self

where T: IntoNostrSigner,

Construct client with signer

To construct a client without signer use Client::default.

Example

use nostr_sdk::prelude::*;

let keys = Keys::generate();
let client = Client::new(keys);

pub fn builder() -> ClientBuilder

Construct client

Example

use std::time::Duration;

use nostr_sdk::prelude::*;

let signer = Keys::generate();
let opts = ClientOptions::default().gossip(true);
let client: Client = Client::builder().signer(signer).opts(opts).build();

pub fn update_min_pow_difficulty(&self, _difficulty: u8)

👎Deprecated since 0.40.0: This no longer works, please use AdmitPolicy instead.

Update minimum POW difficulty for received events

Events with a POW lower than the current value will be ignored to prevent resources exhaustion.

pub fn automatic_authentication(&self, enable: bool)

Auto authenticate to relays (default: true)

https://github.com/nostr-protocol/nips/blob/master/42.md

pub async fn has_signer(&self) -> bool

Check if signer is configured

pub async fn signer(&self) -> Result<Arc<dyn NostrSigner>, Error>

Get current nostr signer

Errors

Returns an error if the signer isn’t set.

pub async fn set_signer<T>(&self, signer: T)

where T: IntoNostrSigner,

Set nostr signer

pub async fn unset_signer(&self)

Unset nostr signer

pub fn pool(&self) -> &RelayPool

Get RelayPool

pub fn database(&self) -> &Arc<dyn NostrDatabase>

Get database

pub fn monitor(&self) -> Option<&Monitor>

Get the relay monitor

pub async fn reset(&self)

Reset the client

This method resets the client to simplify the switch to another account.

This method will:

• unsubscribe from all subscriptions
• disconnect and force remove all relays
• unset the signer

This method will NOT:

• reset ClientOptions
• remove the database
• clear the gossip graph

pub async fn shutdown(&self)

Completely shutdown client

pub fn notifications(&self) -> Receiver<RelayPoolNotification>

Get new notification listener

When you call this method, you subscribe to the notifications channel from that precise moment. Anything received by relay/s before that moment is not included in the channel!

pub async fn relays(&self) -> HashMap<RelayUrl, Relay>

Get relays with RelayServiceFlags::READ or RelayServiceFlags::WRITE flags

Call RelayPool::all_relays to get all relays or RelayPool::relays_with_flag to get relays with specific RelayServiceFlags.

pub async fn relay<U>(&self, url: U) -> Result<Relay, Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Get a previously added Relay

pub async fn add_relay<U>(&self, url: U) -> Result<bool, Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Add relay

Relays added with this method will have both RelayServiceFlags::READ and RelayServiceFlags::WRITE flags enabled.

If the relay already exists, the flags will be updated and false returned.

If are set pool subscriptions, the new added relay will inherit them. Use Client::subscribe_to method instead of Client::subscribe, to avoid to set pool subscriptions.

This method use previously set or default ClientOptions to configure the Relay (ex. set proxy, set min POW, set relay limits, …). To use custom RelayOptions use RelayPool::add_relay.

Connection is NOT automatically started with relay, remember to call Client::connect!

pub async fn add_discovery_relay<U>(&self, url: U) -> Result<bool, Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Add discovery relay

If relay already exists, this method automatically add the RelayServiceFlags::DISCOVERY flag to it and return false.

https://github.com/nostr-protocol/nips/blob/master/65.md

pub async fn add_read_relay<U>(&self, url: U) -> Result<bool, Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Add read relay

If relay already exists, this method add the RelayServiceFlags::READ flag to it and return false.

If are set pool subscriptions, the new added relay will inherit them. Use subscribe_to method instead of subscribe, to avoid to set pool subscriptions.

pub async fn add_write_relay<U>(&self, url: U) -> Result<bool, Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Add write relay

If relay already exists, this method add the RelayServiceFlags::WRITE flag to it and return false.

pub async fn remove_relay<U>(&self, url: U) -> Result<(), Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Remove and disconnect relay

If the relay has RelayServiceFlags::GOSSIP, it will not be removed from the pool and its flags will be updated (remove RelayServiceFlags::READ, RelayServiceFlags::WRITE and RelayServiceFlags::DISCOVERY flags).

To force remove the relay, use Client::force_remove_relay.

pub async fn force_remove_relay<U>(&self, url: U) -> Result<(), Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Force remove and disconnect relay

Note: this method will remove the relay, also if it’s in use for the gossip model or other service!

pub async fn remove_all_relays(&self)

Disconnect and remove all relays

Some relays used by some services could not be disconnected with this method (like the ones used for gossip). Use Client::force_remove_all_relays to remove every relay.

pub async fn force_remove_all_relays(&self)

Disconnect and force remove all relays

pub async fn connect_relay<U>(&self, url: U) -> Result<(), Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Connect to a previously added relay

Check RelayPool::connect_relay docs to learn more.

pub async fn try_connect_relay<U>( &self, url: U, timeout: Duration, ) -> Result<(), Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Try to connect to a previously added relay

For further details, see the documentation of RelayPool::try_connect_relay.

pub async fn disconnect_relay<U>(&self, url: U) -> Result<(), Error>

where U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Disconnect relay

pub async fn connect(&self)

Connect to all added relays

Attempts to initiate a connection for every relay currently in RelayStatus::Initialized or RelayStatus::Terminated. A background connection task is spawned for each such relay, which then tries to establish the connection. Any relay not in one of these two statuses is skipped.

For further details, see the documentation of Relay::connect.

pub async fn wait_for_connection(&self, timeout: Duration)

Waits for relays connections

Wait for relays connections at most for the specified timeout. The code continues when the relays are connected or the timeout is reached.

pub async fn try_connect(&self, timeout: Duration) -> Output<()>

Try to establish a connection with the relays.

Attempts to establish a connection for every relay currently in RelayStatus::Initialized or RelayStatus::Terminated without spawning the connection task if it fails. This means that if the connection fails, no automatic retries are scheduled. Use Client::connect if you want to immediately spawn a connection task, regardless of whether the initial connection succeeds.

For further details, see the documentation of Relay::try_connect.

pub async fn connect_with_timeout(&self, timeout: Duration)

👎Deprecated since 0.39.0: Use connect + wait_for_connection instead.

Connect to all added relays

Try to connect to the relays and wait for them to be connected at most for the specified timeout. The code continues if the timeout is reached or if all relays connect.

pub async fn disconnect(&self)

Disconnect from all relays

pub async fn subscriptions( &self, ) -> HashMap<SubscriptionId, HashMap<RelayUrl, Filter>>

Get subscriptions

pub async fn subscription( &self, id: &SubscriptionId, ) -> HashMap<RelayUrl, Filter>

Get subscription

pub async fn subscribe( &self, filter: Filter, opts: Option<SubscribeAutoCloseOptions>, ) -> Result<Output<SubscriptionId>, Error>

Subscribe to filters

This method create a new subscription. None of the previous subscriptions will be edited/closed when you call this! So remember to unsubscribe when you no longer need it. You can get all your active (non-auto-closing) subscriptions by calling client.subscriptions().await.

If gossip is enabled (see ClientOptions::gossip) the events will be requested also to NIP65 relays (automatically discovered) of public keys included in filters (if any).

Auto-closing subscription

It’s possible to automatically close a subscription by configuring the SubscribeAutoCloseOptions.

Note: auto-closing subscriptions aren’t saved in subscriptions map!

Example

// Compose filter
let subscription = Filter::new()
    .pubkeys(vec![keys.public_key()])
    .since(Timestamp::now());

// Subscribe
let output = client.subscribe(subscription, None).await?;
println!("Subscription ID: {}", output.val);

// Auto-closing subscription
let id = SubscriptionId::generate();
let subscription = Filter::new().kind(Kind::TextNote).limit(10);
let opts = SubscribeAutoCloseOptions::default().exit_policy(ReqExitPolicy::ExitOnEOSE);
let output = client.subscribe(subscription, Some(opts)).await?;
println!("Subscription ID: {} [auto-closing]", output.val);

pub async fn subscribe_with_id( &self, id: SubscriptionId, filter: Filter, opts: Option<SubscribeAutoCloseOptions>, ) -> Result<Output<()>, Error>

Subscribe to filters with custom SubscriptionId

If gossip is enabled (see ClientOptions::gossip) the events will be requested also to NIP65 relays (automatically discovered) of public keys included in filters (if any).

Auto-closing subscription

It’s possible to automatically close a subscription by configuring the SubscribeAutoCloseOptions.

Note: auto-closing subscriptions aren’t saved in subscriptions map!

pub async fn subscribe_to<I, U>( &self, urls: I, filter: Filter, opts: Option<SubscribeAutoCloseOptions>, ) -> Result<Output<SubscriptionId>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Subscribe to filters to specific relays

This method create a new subscription. None of the previous subscriptions will be edited/closed when you call this! So remember to unsubscribe when you no longer need it.

Auto-closing subscription

It’s possible to automatically close a subscription by configuring the SubscribeAutoCloseOptions.

pub async fn subscribe_with_id_to<I, U>( &self, urls: I, id: SubscriptionId, filter: Filter, opts: Option<SubscribeAutoCloseOptions>, ) -> Result<Output<()>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Subscribe to filter with custom SubscriptionId to specific relays

Auto-closing subscription

It’s possible to automatically close a subscription by configuring the SubscribeAutoCloseOptions.

pub async fn subscribe_targeted<I, U>( &self, id: SubscriptionId, targets: I, opts: SubscribeOptions, ) -> Result<Output<()>, Error>

where I: IntoIterator<Item = (U, Filter)>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Targeted subscription

Subscribe to specific relays with specific filters

pub async fn unsubscribe(&self, id: &SubscriptionId)

Unsubscribe

pub async fn unsubscribe_all(&self)

Unsubscribe from all subscriptions

pub async fn sync( &self, filter: Filter, opts: &SyncOptions, ) -> Result<Output<Reconciliation>, Error>

Sync events with relays (negentropy reconciliation)

If gossip is enabled (see ClientOptions::gossip) the events will be reconciled also from NIP65 relays (automatically discovered) of public keys included in filters (if any).

https://github.com/hoytech/negentropy

pub async fn sync_with<I, U>( &self, urls: I, filter: Filter, opts: &SyncOptions, ) -> Result<Output<Reconciliation>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Sync events with specific relays (negentropy reconciliation)

https://github.com/hoytech/negentropy

pub async fn fetch_events( &self, filter: Filter, timeout: Duration, ) -> Result<Events, Error>

Fetch events from relays

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. To use another exit policy, check RelayPool::fetch_events. For long-lived subscriptions, check Client::subscribe.

Gossip

If gossip is enabled (see ClientOptions::gossip) the events will be requested also to NIP65 relays (automatically discovered) of public keys included in filters (if any).

Example

let subscription = Filter::new()
    .pubkeys(vec![keys.public_key()])
    .since(Timestamp::now());

let _events = client
    .fetch_events(subscription, Duration::from_secs(10))
    .await
    .unwrap();

pub async fn fetch_events_from<I, U>( &self, urls: I, filter: Filter, timeout: Duration, ) -> Result<Events, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Fetch events from specific relays

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. To use another exit policy, check RelayPool::fetch_events_from. For long-lived subscriptions, check Client::subscribe_to.

pub async fn fetch_combined_events( &self, filter: Filter, timeout: Duration, ) -> Result<Events, Error>

Get events both from database and relays

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. For long-lived subscriptions, check Client::subscribe.

Gossip

If gossip is enabled (see ClientOptions::gossip) the events will be requested also to NIP65 relays (automatically discovered) of public keys included in filters (if any).

Notes and alternative example

This method will be deprecated in the future! This is a temporary solution for who still want to query events both from database and relays and merge the result. The optimal solution is to execute a Client::sync to reconcile missing events, Client::subscribe to get all new future events, NostrDatabase::query to query stored events and Client::handle_notifications to listen-for/handle new events (i.e. to know when update the UI). This will allow very fast queries, low bandwidth usage (depending on how many events the client have to reconcile) and a lower load on the relays.

You can obtain the same result with:

// Query database
let stored_events: Events = client.database().query(filter.clone()).await?;

// Query relays
let fetched_events: Events = client.fetch_events(filter, Duration::from_secs(10)).await?;

// Merge result
let events: Events = stored_events.merge(fetched_events);

// Iter and print result
for event in events.into_iter() {
    println!("{}", event.as_json());
}

pub async fn stream_events( &self, filter: Filter, timeout: Duration, ) -> Result<ReceiverStream<Event>, Error>

Stream events from relays

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. To use another exit policy, check RelayPool::stream_events. For long-lived subscriptions, check Client::subscribe.

Gossip

If gossip is enabled (see ClientOptions::gossip) the events will be streamed also from NIP65 relays (automatically discovered) of public keys included in filters (if any).

pub async fn stream_events_from<I, U>( &self, urls: I, filter: Filter, timeout: Duration, ) -> Result<ReceiverStream<Event>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Stream events from specific relays

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. To use another exit policy, check RelayPool::stream_events_from. For long-lived subscriptions, check Client::subscribe_to.

pub async fn stream_events_targeted( &self, targets: HashMap<RelayUrl, Filter>, timeout: Duration, ) -> Result<ReceiverStream<Event>, Error>

Stream events from specific relays with specific filters

Overview

This is an auto-closing subscription and will be closed automatically on EOSE. To use another exit policy, check RelayPool::stream_events_targeted. For long-lived subscriptions, check Client::subscribe_targeted.

pub async fn send_msg_to<I, U>( &self, urls: I, msg: ClientMessage<'_>, ) -> Result<Output<()>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Send the client message to a specific relays

pub async fn batch_msg_to<I, U>( &self, urls: I, msgs: Vec<ClientMessage<'_>>, ) -> Result<Output<()>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Batch send client messages to specific relays

pub async fn send_event(&self, event: &Event) -> Result<Output<EventId>, Error>

Send the event to relays

Overview

Send the Event to all relays with RelayServiceFlags::WRITE flag.

Gossip

If gossip is enabled (see ClientOptions::gossip):

• the Event will be sent also to NIP65 relays (automatically discovered);
• the gossip data will be updated, if the Event is a NIP17/NIP65 relay list.

pub async fn send_event_to<I, U>( &self, urls: I, event: &Event, ) -> Result<Output<EventId>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Send event to specific relays

Gossip

If gossip is enabled (see ClientOptions::gossip) and the Event is a NIP17/NIP65 relay list, the gossip data will be updated.

pub async fn sign_event_builder( &self, builder: EventBuilder, ) -> Result<Event, Error>

Build, sign and return Event

This method requires a NostrSigner.

pub async fn send_event_builder( &self, builder: EventBuilder, ) -> Result<Output<EventId>, Error>

Take an EventBuilder, sign it by using the NostrSigner and broadcast to relays.

This method requires a NostrSigner.

Check Client::send_event from more details.

pub async fn send_event_builder_to<I, U>( &self, urls: I, builder: EventBuilder, ) -> Result<Output<EventId>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, Error: From<<U as TryIntoUrl>::Err>,

Take an EventBuilder, sign it by using the NostrSigner and broadcast to specific relays.

This method requires a NostrSigner.

Check Client::send_event_to from more details.

pub async fn fetch_metadata( &self, public_key: PublicKey, timeout: Duration, ) -> Result<Option<Metadata>, Error>

Fetch the newest public key metadata from relays.

Returns None if the Metadata of the PublicKey has not been found.

Check Client::fetch_events for more details.

If you only want to consult stored data, consider client.database().profile(PUBKEY).

https://github.com/nostr-protocol/nips/blob/master/01.md

pub async fn set_metadata( &self, metadata: &Metadata, ) -> Result<Output<EventId>, Error>

Update metadata

This method requires a NostrSigner.

https://github.com/nostr-protocol/nips/blob/master/01.md

Example

let metadata = Metadata::new()
    .name("username")
    .display_name("My Username")
    .about("Description")
    .picture(Url::parse("https://example.com/avatar.png").unwrap())
    .nip05("username@example.com");

client.set_metadata(&metadata).await.unwrap();

pub async fn get_contact_list( &self, timeout: Duration, ) -> Result<Vec<Contact>, Error>

Get the contact list from relays.

This method requires a NostrSigner.

https://github.com/nostr-protocol/nips/blob/master/02.md

pub async fn get_contact_list_public_keys( &self, timeout: Duration, ) -> Result<Vec<PublicKey>, Error>

Get contact list public keys from relays.

This method requires a NostrSigner.

https://github.com/nostr-protocol/nips/blob/master/02.md

pub async fn get_contact_list_metadata( &self, timeout: Duration, ) -> Result<HashMap<PublicKey, Metadata>, Error>

Get contact list Metadata from relays.

This method requires a NostrSigner.

pub async fn send_private_msg<S, I>( &self, receiver: PublicKey, message: S, rumor_extra_tags: I, ) -> Result<Output<EventId>, Error>

where S: Into<String>, I: IntoIterator<Item = Tag>,

Available on crate feature nip59 only.

Send a private direct message

If gossip is enabled (see ClientOptions::gossip) the message will be sent to the NIP17 relays (automatically discovered). If gossip is not enabled will be sent to all relays with RelayServiceFlags::WRITE flag.

This method requires a NostrSigner.

Errors

Returns Error::PrivateMsgRelaysNotFound if the receiver hasn’t set the NIP17 list, meaning that is not ready to receive private messages.

https://github.com/nostr-protocol/nips/blob/master/17.md

pub async fn send_private_msg_to<I, S, U, IT>( &self, urls: I, receiver: PublicKey, message: S, rumor_extra_tags: IT, ) -> Result<Output<EventId>, Error>

where I: IntoIterator<Item = U>, S: Into<String>, U: TryIntoUrl, IT: IntoIterator<Item = Tag>, Error: From<<U as TryIntoUrl>::Err>,

Available on crate feature nip59 only.

Send a private direct message to specific relays

This method requires a NostrSigner.

https://github.com/nostr-protocol/nips/blob/master/17.md

pub async fn gift_wrap<I>( &self, receiver: &PublicKey, rumor: UnsignedEvent, extra_tags: I, ) -> Result<Output<EventId>, Error>

where I: IntoIterator<Item = Tag>,

Available on crate feature nip59 only.

Construct Gift Wrap and send to relays

This method requires a NostrSigner.

Check Client::send_event to know how sending events works.

https://github.com/nostr-protocol/nips/blob/master/59.md

pub async fn gift_wrap_to<I, U, IT>( &self, urls: I, receiver: &PublicKey, rumor: UnsignedEvent, extra_tags: IT, ) -> Result<Output<EventId>, Error>

where I: IntoIterator<Item = U>, U: TryIntoUrl, IT: IntoIterator<Item = Tag>, Error: From<<U as TryIntoUrl>::Err>,

Available on crate feature nip59 only.

Construct Gift Wrap and send to specific relays

This method requires a NostrSigner.

https://github.com/nostr-protocol/nips/blob/master/59.md

pub async fn unwrap_gift_wrap( &self, gift_wrap: &Event, ) -> Result<UnwrappedGift, Error>

Available on crate feature nip59 only.

Unwrap Gift Wrap event

This method requires a NostrSigner.

Check UnwrappedGift::from_gift_wrap to learn more.

https://github.com/nostr-protocol/nips/blob/master/59.md

pub async fn handle_notifications<F, Fut>(&self, func: F) -> Result<(), Error>

where F: Fn(RelayPoolNotification) -> Fut, Fut: Future<Output = Result<bool>>,

Handle notifications

The closure function expects a bool as output: return true to exit from the notification loop.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Client

fn default() -> Self

Returns the “default value” for a type.