nwc: add notifications support

Closes #952

Pull-Request: #953
Signed-off-by: Yuki Kishimoto <[email protected]>

Author: frnandu

crates/nostr/src/event/kind.rs

@@ -123,6 +123,7 @@ kind_variants! {
     Authentication => 22242, "Client Authentication", "<https://github.com/nostr-protocol/nips/blob/master/42.md>",
     WalletConnectRequest => 23194, "Wallet Connect Request", "<https://github.com/nostr-protocol/nips/blob/master/47.md>",
     WalletConnectResponse => 23195, "Wallet Connect Response", "<https://github.com/nostr-protocol/nips/blob/master/47.md>",
+    WalletConnectNotification => 23196, "Wallet Connect Notification", "<https://github.com/nostr-protocol/nips/blob/master/47.md>",
     NostrConnect => 24133, "Nostr Connect", "<https://github.com/nostr-protocol/nips/blob/master/47.md>",
     LiveEvent => 30311, "Live Event", "<https://github.com/nostr-protocol/nips/blob/master/53.md>",
     LiveEventMessage => 1311, "Live Event Message", "<https://github.com/nostr-protocol/nips/blob/master/53.md>",

crates/nwc/CHANGELOG.md

@@ -23,6 +23,12 @@
 
 -->
 
+## Unreleased
+
+### Added
+
+- Add notification support for real-time payment updates (https://github.com/rust-nostr/nostr/pull/953)
+
 ## v0.42.0 - 2025/05/20
 
 No notable changes in this release.

crates/nwc/Cargo.toml

@@ -22,5 +22,5 @@ nostr-relay-pool.workspace = true
 tracing = { workspace = true, features = ["std"] }
 
 [dev-dependencies]
-tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
-tracing-subscriber.workspace = true
+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "signal"] }
+tracing-subscriber = { workspace = true, features = ["env-filter", "fmt"] }

crates/nwc/README.md

@@ -4,6 +4,13 @@
 
 NWC client and zapper backend for Nostr apps
 
+## Notifications Support
+
+NWC supports real-time payment notifications as specified in NIP-47.
+
+This allows applications to receive instant updates when payments are sent or received.
+See [`examples/notifications.rs`](examples/notifications.rs) for a simple example of how to use this feature.
+
 ## Changelog
 
 All notable changes to this library are documented in the [CHANGELOG.md](CHANGELOG.md).

crates/nwc/examples/notifications.rs

@@ -0,0 +1,93 @@
+// Copyright (c) 2022-2023 Yuki Kishimoto
+// Copyright (c) 2023-2025 Rust Nostr Developers
+// Distributed under the MIT software license
+
+use std::env;
+use std::str::FromStr;
+
+use nostr::nips::nip47::{NotificationType, PaymentNotification};
+use nwc::prelude::*;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let log_level = env::var("RUST_LOG")
+        .unwrap_or_else(|_| "info,nwc=debug,nostr_relay_pool=debug".to_string());
+
+    tracing_subscriber::fmt()
+        .with_env_filter(log_level)
+        .with_target(true)
+        .with_line_number(true)
+        .init();
+
+    let uri_str = env::args()
+        .nth(1)
+        .or_else(|| env::var("NWC_URI").ok())
+        .ok_or("Please provide NWC URI as argument or set NWC_URI environment variable")?;
+
+    let uri =
+        NostrWalletConnectURI::from_str(&uri_str).map_err(|e| format!("Invalid NWC URI: {}", e))?;
+
+    println!("📡 Relay: {:?}", uri.relays);
+    println!("🔑 Wallet pubkey: {}", uri.public_key);
+
+    println!("🔗 Connecting to wallet service...");
+
+    let nwc = NWC::new(uri);
+
+    nwc.subscribe_to_notifications().await?;
+
+    println!("✅ NWC client started and listening for notifications...");
+    println!("📱 Wallet notifications will appear here in real-time");
+    println!("💡 Try making or receiving payments with your wallet");
+    println!("🛑 Press Ctrl+C to stop");
+
+    let shutdown = tokio::signal::ctrl_c();
+    tokio::pin!(shutdown);
+
+    tokio::select! {
+        _ = shutdown => {
+            println!("\n👋 Shutting down...");
+        }
+
+        result = nwc.handle_notifications(|notification| async move {
+            match notification.notification_type {
+                NotificationType::PaymentReceived => {
+                    if let Ok(payment) = notification.to_pay_notification() {
+                        println!("🟢 Payment Received!");
+                        print_payment_details(&payment);
+                    }
+                }
+                NotificationType::PaymentSent => {
+                    if let Ok(payment) = notification.to_pay_notification() {
+                        println!("🔴 Payment Sent!");
+                        print_payment_details(&payment);
+                    }
+                }
+            }
+            Ok(false) // Continue processing
+        }) => {
+            if let Err(e) = result {
+                eprintln!("Error handling notifications: {}", e);
+            }
+        }
+    }
+
+    nwc.unsubscribe_from_notifications().await?;
+
+    nwc.shutdown().await;
+
+    Ok(())
+}
+
+fn print_payment_details(payment: &PaymentNotification) {
+    println!("  💰 Amount: {} msat", payment.amount);
+    if let Some(description) = &payment.description {
+        println!("  📝 Description: {}", description);
+    }
+    println!("  🔗 Payment Hash: {}", payment.payment_hash);
+    println!("  📅 Settled At: {}", payment.settled_at);
+    if payment.fees_paid > 0 {
+        println!("  💸 Fees: {} msat", payment.fees_paid);
+    }
+    println!();
+}

crates/nwc/src/error.rs

@@ -20,6 +20,8 @@ pub enum Error {
     PrematureExit,
     /// Request timeout
     Timeout,
+    /// Handler error
+    Handler(String),
 }
 
 impl std::error::Error for Error {}
@@ -31,6 +33,7 @@ impl fmt::Display for Error {
             Self::Pool(e) => write!(f, "{e}"),
             Self::PrematureExit => write!(f, "premature exit"),
             Self::Timeout => write!(f, "timeout"),
+            Self::Handler(e) => write!(f, "handler error: {e}"),
         }
     }
 }

crates/nwc/src/lib.rs

@@ -12,13 +12,14 @@
 #![allow(clippy::arc_with_non_send_sync)]
 
 use std::collections::HashMap;
+use std::future::Future;
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Arc;
 
 pub extern crate nostr;
 
 use async_utility::time;
-use nostr::nips::nip47::{Request, Response};
+use nostr::nips::nip47::{Notification, Request, Response};
 use nostr_relay_pool::prelude::*;
 
 pub mod error;
@@ -31,6 +32,7 @@ pub use self::error::Error;
 pub use self::options::NostrWalletConnectOptions;
 
 const ID: &str = "nwc";
+const NOTIFICATIONS_ID: &str = "nwc-notifications";
 
 /// Nostr Wallet Connect client
 #[derive(Debug, Clone)]
@@ -39,6 +41,7 @@ pub struct NWC {
     pool: RelayPool,
     opts: NostrWalletConnectOptions,
     bootstrapped: Arc<AtomicBool>,
+    notifications_subscribed: Arc<AtomicBool>,
 }
 
 impl NWC {
@@ -55,6 +58,7 @@ impl NWC {
             pool: RelayPool::default(),
             opts,
             bootstrapped: Arc::new(AtomicBool::new(false)),
+            notifications_subscribed: Arc::new(AtomicBool::new(false)),
         }
     }
 
@@ -191,6 +195,118 @@ impl NWC {
         Ok(res.to_get_info()?)
     }
 
+    /// Subscribe to wallet notifications
+    pub async fn subscribe_to_notifications(&self) -> Result<(), Error> {
+        if self.notifications_subscribed.load(Ordering::SeqCst) {
+            tracing::debug!("Already subscribed to notifications");
+            return Ok(());
+        }
+
+        tracing::info!("Subscribing to wallet notifications...");
+
+        self.bootstrap().await?;
+
+        let client_keys = Keys::new(self.uri.secret.clone());
+        let client_pubkey = client_keys.public_key();
+
+        tracing::debug!("Client pubkey: {}", client_pubkey);
+        tracing::debug!("Wallet service pubkey: {}", self.uri.public_key);
+
+        let notification_filter = Filter::new()
+            .author(self.uri.public_key)
+            .pubkey(client_pubkey)
+            .kind(Kind::WalletConnectNotification)
+            .since(Timestamp::now());
+
+        tracing::debug!("Notification filter: {:?}", notification_filter);
+
+        self.pool
+            .subscribe_with_id(
+                SubscriptionId::new(NOTIFICATIONS_ID),
+                notification_filter,
+                SubscribeOptions::default(),
+            )
+            .await?;
+
+        self.notifications_subscribed.store(true, Ordering::SeqCst);
+
+        tracing::info!("Successfully subscribed to notifications");
+        Ok(())
+    }
+
+    /// Handle incoming notifications with a callback function
+    pub async fn handle_notifications<F, Fut>(&self, func: F) -> Result<(), Error>
+    where
+        F: Fn(Notification) -> Fut,
+        Fut: Future<Output = Result<bool>>,
+    {
+        let mut notifications = self.pool.notifications();
+
+        while let Ok(notification) = notifications.recv().await {
+            tracing::trace!("Received relay pool notification: {:?}", notification);
+
+            match notification {
+                RelayPoolNotification::Event {
+                    subscription_id,
+                    event,
+                    ..
+                } => {
+                    tracing::debug!(
+                        "Received event: kind={}, author={}, id={}",
+                        event.kind,
+                        event.pubkey,
+                        event.id
+                    );
+
+                    if subscription_id.as_str() != NOTIFICATIONS_ID {
+                        tracing::trace!("Ignoring event with subscription id: {}", subscription_id);
+                        continue;
+                    }
+
+                    if event.kind != Kind::WalletConnectNotification {
+                        tracing::trace!("Ignoring event with kind: {}", event.kind);
+                        continue;
+                    }
+
+                    tracing::info!("Processing wallet notification event");
+
+                    match Notification::from_event(&self.uri, &event) {
+                        Ok(nip47_notification) => {
+                            tracing::info!(
+                                "Successfully parsed notification: {:?}",
+                                nip47_notification.notification_type
+                            );
+                            let exit: bool = func(nip47_notification)
+                                .await
+                                .map_err(|e| Error::Handler(e.to_string()))?;
+                            if exit {
+                                break;
+                            }
+                        }
+                        Err(e) => {
+                            tracing::error!("Failed to parse notification: {}", e);
+                            tracing::debug!("Event content: {}", event.content);
+                            return Err(Error::from(e));
+                        }
+                    }
+                }
+                RelayPoolNotification::Shutdown => break,
+                _ => {}
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Unsubscribe from notifications
+    pub async fn unsubscribe_from_notifications(&self) -> Result<(), Error> {
+        self.pool
+            .unsubscribe(&SubscriptionId::new(NOTIFICATIONS_ID))
+            .await;
+        self.notifications_subscribed.store(false, Ordering::SeqCst);
+        Ok(())
+    }
+
     /// Completely shutdown [NWC] client
     #[inline]
     pub async fn shutdown(self) {