feat: add frigate electrum based RPC methods

[sdmg15]

This PR adds supports for additional RPC methods provided by Frigate electrum based RPC server.

The added methods are:

• server.version: This is the first message sent to establish connection with server
• blockchain.silentpayments.subscribe: This takes a spend public key and a scan private key and return outputs belonging to the them.
• blockchain.silentpayments.unsubscribe: This takes a spend public key and a scan private key and unsubscribe from notifications.

Some context:
This is useful for the PR opened at bitcoindevkit/bdk-sp#48 which is doing integration of frigate ephemeral scanning.
Opening this PR in order to receive feedback.

Reference:
https://github.com/sparrowwallet/frigate/

Supported Frigate version 1.3.2

[evanlinjin]

Thanks for the PR! Note that it needs a rebase now with the recent merges.

[oleonardolima]

In https://github.com/sparrowwallet/frigate#serverfeatures it mentions the new field in server.features, is it not needed by bdk-sp ?

[oleonardolima]

The server.version is not an exclusive method of frigate, so I don't think the feature is needed here. Also, if it lands after #11, it'll already be covered.

[sdmg15]

Yes indeed, we just need to coordinate which lands first so that I can remove it here.

[oleonardolima]

In https://github.com/sparrowwallet/frigate#blockchainsilentpaymentssubscribe it also mentions that start_height could be a string in the form FROM-TO, is that format intended to be ignored ?

[sdmg15]

It's true it's not mentioned anywhere here but the initial code was for version 1.3.2 (https://github.com/sparrowwallet/frigate/tree/5124333b145acc2a6385f5cd4aeb918c8c896cd7#blockchainsilentpaymentssubscribe)
There has been quite some updates in the meantime. I'm just realising too :)

[oleonardolima]

@sdmg15 I just thought this now during the call, but you could also try adding support for these in https://github.com/bitcoindevkit/rust-electrum-client, not sure if the architecture there supports it though.

[noahjoeris]

I think it's good for consistency to use the same pattern as the other notifications.

pub struct SpNotification {
    param_0: SpSubscription,
    param_1: f32,
    param_2: Vec<TxTweak>,
}

#[cfg(feature = "frigate")]
impl SpNotification {
	/// Returns the subscription this notification belongs to.
    pub fn subscription(&self) -> &SpSubscription {
        &self.param_0
    }
	/// Returns the scan progress, where `1.0` means up to date.
    pub fn progress(&self) -> f32 {
        self.param_1
    }
	/// Returns the transactions discovered by this notification.
    pub fn history(&self) -> &[TxTweak] {
        &self.param_2
    }
}

[noahjoeris]

Let's rename it to SpSubscribeResp for consistency and move to src/response.rs

[noahjoeris]

This should be SpSubscription (see here)

[sdmg15]

Sorry for not mentioning this earlier but the implemented version here 1.3.2
I just updated the PR description to be clear on that.

https://github.com/sparrowwallet/frigate/tree/5124333b145acc2a6385f5cd4aeb918c8c896cd7#blockchainsilentpaymentssubscribe

[noahjoeris]

Ah I see. I'll have another look then :)

[noahjoeris]

Thanks for updating @sdmg15 !
I left a few more comments

[noahjoeris]

Because we don't add the latest version let's specify what's supported here in the docs.
I think we support up to v1.4.1 so we might add something like: Supported Frigate: ≤ 1.4.1

[sdmg15]

I think I'd be better to put the link to the referenced tag like: https://github.com/sparrowwallet/frigate/tree/1.4.1#blockchainsilentpaymentssubscribe Wdyt?

[noahjoeris]

Let's avoid having 2 feature lists by updating the macro to support cfg feature

So we can add:

    #[cfg(feature = "frigate")] Version,
    #[cfg(feature = "frigate")] SpSubscribe,
    #[cfg(feature = "frigate")] SpUnSubscribe,

Macro:

macro_rules! gen_pending_request_types {
    ($($(#[$attr:meta])* $name:ident),* $(,)?) => {
        /// A successfully handled request and its decoded server response.
        ///
        /// This enum is returned when a request has been fully processed and the server replied
        /// with a valid `result`. It contains both the original request and the corresponding
        /// response.
        ///
        /// `CompletedRequest` is used by the [`Event::Response`] variant to expose typed
        /// request-response pairs to the caller.
        ///
        /// You typically don't construct this manually — it is created internally by the client
        /// after decoding JSON-RPC responses.
        ///
        /// [`Event::Response`]: crate::Event::Response
        #[derive(Debug, Clone)]
        pub enum CompletedRequest {
            $(
                $(#[$attr])*
                $name {
                    req: crate::request::$name,
                    resp: <crate::request::$name as Request>::Response,
                },
            )*
        }

        /// A request that received an error response from the Electrum server.
        ///
        /// This enum represents a completed request where the server returned a JSON-RPC error
        /// instead of a `result`. It contains both the original request and the associated error.
        ///
        /// This is used by the [`Event::ResponseError`] variant to expose server-side failures
        /// in a typed manner.
        ///
        /// Like [`CompletedRequest`], this is created internally by the client during response
        /// processing.
        ///
        /// [`Event::ResponseError`]: crate::Event::ResponseError
        #[derive(Debug, Clone)]
        pub enum FailedRequest {
            $(
                $(#[$attr])*
                $name {
                    req: crate::request::$name,
                    error: ResponseError,
                },
            )*
        }

        impl core::fmt::Display for FailedRequest {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                match self {
                    $(
                        $(#[$attr])*
                        Self::$name { req, error } => {
                            write!(f, "Server responsed to {:?} with error: {}", req, error)
                        }
                    )*
                }
            }
        }

        impl std::error::Error for FailedRequest {}

        $(
            $(#[$attr])*
            impl RequestExt for crate::request::$name {
                fn into_completed(self, resp: <Self as Request>::Response) -> CompletedRequest {
                    CompletedRequest::$name { req: self, resp }
                }
                fn into_failed(self, error: ResponseError) -> FailedRequest {
                    FailedRequest::$name { req: self, error }
                }
            }
        )*
    };
}

[sdmg15]

@noahjoeris Thanks for the reviews. I've applied the changes.