diff --git a/Cargo.toml b/Cargo.toml index e40832a3..f684c210 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,8 @@ members = [ "backends/blindbit-v1", "spdk-wallet", "silentpayments", - "scanners/local", + "scanners/local", + "scanners/remote/frigate", ] resolver = "3" @@ -36,6 +37,7 @@ reqwest = { version = "0.12.4", features = [ "gzip", ], default-features = false } secp256k1 = { version = "0.29.0" } +electrum_streaming_client = { git = "https://github.com/bitcoindevkit/electrum_streaming_client", rev = "01a6d42aac33f86b2bc647e7fc702067be99c9c7", features = ["frigate"]} [workspace.package] edition = "2024" diff --git a/scanners/remote/frigate/.gitignore b/scanners/remote/frigate/.gitignore new file mode 100644 index 00000000..ea8c4bf7 --- /dev/null +++ b/scanners/remote/frigate/.gitignore @@ -0,0 +1 @@ +/target diff --git a/scanners/remote/frigate/Cargo.toml b/scanners/remote/frigate/Cargo.toml new file mode 100644 index 00000000..e51289f2 --- /dev/null +++ b/scanners/remote/frigate/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "frigate" +version = "0.1.0" +edition.workspace = true +repository.workspace = true +authors.workspace = true +license.workspace = true + +[dependencies] +electrum_streaming_client.workspace = true +spdk-core.workspace = true +silentpayments.workspace = true + +bitcoin.workspace = true +futures.workspace = true +tokio = { version = "1", features = ["macros", "rt-multi-thread", "net", "time"] } +log.workspace = true +anyhow.workspace = true + +[dev-dependencies] +spdk-wallet.workspace = true +env_logger = "0.11" + +[lints] +workspace = true diff --git a/scanners/remote/frigate/examples/frigate_scanner.rs b/scanners/remote/frigate/examples/frigate_scanner.rs new file mode 100644 index 00000000..6cde0fac --- /dev/null +++ b/scanners/remote/frigate/examples/frigate_scanner.rs @@ -0,0 +1,63 @@ +use std::collections::{HashMap, HashSet}; + +use bitcoin::absolute::Height; +use bitcoin::secp256k1::SecretKey; +use bitcoin::{BlockHash, Network, OutPoint}; +use frigate::Scanner; +use spdk_core::scanner::{DiscoveredOutput, Scanner as _}; +use spdk_wallet::client::{SpClient, SpendKey}; + +const NETWORK: Network = Network::Signet; +const FRIGATE_BACKEND_URL: &str = "100.81.213.115:50102"; +// scan range settings +const SCAN_START_HEIGHT: u32 = 326_000; +const SCAN_END_HEIGHT: u32 = 326_595; + +// scan & spend key bytes, these should be randomly generated, +// but for this example we use simple byte arrays +const SCAN_SK_BYTES: [u8; 32] = [0x01; 32]; +const SPEND_SK_BYTES: [u8; 32] = [0x02; 32]; + +#[derive(Debug)] +pub struct UpdateResult { + pub blkheight: Height, + pub blkhash: BlockHash, + pub discovered_inputs: HashSet, + pub discovered_outputs: HashMap, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + env_logger::init(); + let scan_sk = SecretKey::from_slice(&SCAN_SK_BYTES)?; + let spend_sk = SecretKey::from_slice(&SPEND_SK_BYTES)?; + + let sp_client = SpClient::new(scan_sk, SpendKey::Secret(spend_sk), NETWORK)?; + let sp_receiver = sp_client.receiver(); + + let frigate_scanner = Scanner::new( + FRIGATE_BACKEND_URL.to_owned(), + scan_sk, + sp_receiver, + None, + HashSet::new(), + ) + .await?; + + println!("Receiving code for this key pair + network:"); + println!("{}", sp_client.receiving_code()); + + let start = Height::from_consensus(SCAN_START_HEIGHT)?; + let end = Height::from_consensus(SCAN_END_HEIGHT)?; + + // It's important to note that `scan_blocks` will not monitor scripts outputs. + // Call `scan_blocks_with_spent_outputs` instead if you want to monitor spent outputs as well. + let mut rx = frigate_scanner.scan_blocks(start..=end); + + while let Ok(update) = rx.recv().await { + // print all received updates + println!("{update:#?}"); + } + + Ok(()) +} diff --git a/scanners/remote/frigate/src/client.rs b/scanners/remote/frigate/src/client.rs new file mode 100644 index 00000000..6f9b8b30 --- /dev/null +++ b/scanners/remote/frigate/src/client.rs @@ -0,0 +1,190 @@ +use std::time::Duration; + +use bitcoin::Txid; +use electrum_streaming_client::response::{FullTx, HeaderResp}; +use electrum_streaming_client::{ + AsyncClient, ElectrumScriptHash, ElectrumScriptStatus, Event, request, +}; +use futures::channel::mpsc::UnboundedReceiver; +use log::{debug, info}; +use tokio::net::TcpStream; +use tokio::task::JoinHandle; +use tokio::time::timeout; + +#[expect(unused, reason = "worker is used to keep the connection alive")] +pub struct FrigateClient { + pub client: AsyncClient, + pub events: UnboundedReceiver, + pub worker: JoinHandle>, + pub request_timeout: Duration, + protocol_version: Option, +} + +#[derive(Debug)] +pub enum FrigateError { + Connection(String), + Timeout(String), + Request(String), +} + +type Result = std::result::Result; + +impl std::fmt::Display for FrigateError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::Connection(msg) => write!(f, "connection error: {msg}"), + Self::Timeout(msg) => write!(f, "request timeout: {msg}"), + Self::Request(msg) => write!(f, "request error: {msg}"), + } + } +} + +impl std::error::Error for FrigateError {} + +impl FrigateClient { + pub async fn connect(host_url: &str) -> Result { + let stream = TcpStream::connect(host_url).await.map_err(|err| { + FrigateError::Connection(format!("can't connect to socket '{host_url}': {err}")) + })?; + + let (reader, writer) = stream.into_split(); + let (client, events, worker) = AsyncClient::new_tokio(reader, writer); + + let worker = tokio::spawn(worker); + + Ok(Self { + client, + events, + worker, + request_timeout: Duration::from_secs(10), + protocol_version: None, + }) + } + + /// Sets a custom request timeout for this client. + #[expect(unused, reason = "tbd")] + pub const fn with_timeout(mut self, timeout: Duration) -> Self { + self.request_timeout = timeout; + self + } + + pub async fn get_block_header(&mut self, height: u32) -> Result { + self.version().await?; + + let res = timeout( + self.request_timeout, + self.client.send_request(request::Header { height }), + ) + .await + .map_err(|_| FrigateError::Timeout("Header request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("Header request failed: {e}")))?; + Ok(res) + } + + pub async fn get_transaction(&mut self, txid: Txid) -> Result { + self.version().await?; + + let res = timeout( + self.request_timeout, + self.client.send_request(request::GetTx { txid }), + ) + .await + .map_err(|_| FrigateError::Timeout("GetTx request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("GetTx request failed: {e}")))?; + Ok(res) + } + + /// Negotiate the Frigate protocol version once and cache the result. + /// + /// The negotiation is sent as the first request on the connection. Later calls return the + /// cached version without sending another request. + pub async fn version(&mut self) -> Result { + if let Some(protocol_version) = &self.protocol_version { + return Ok(protocol_version.clone()); + } + + debug!("Sending version request to Frigate server..."); + let res = timeout( + self.request_timeout, + self.client.send_request(request::ServerVersion { + client_name: "spdk".into(), + protocol_version: request::SupportedVersion::Range([ + "1.3.2".into(), + "1.4.1".into(), + ]), + }), + ) + .await + .map_err(|_| FrigateError::Timeout("Version request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("Version request failed: {e}")))?; + self.protocol_version = Some(res.protocol_version.clone()); + Ok(res.protocol_version) + } + + /// Make a request to the Frigate electrum server to subscribe to the outputs beloging to the + /// given silent payment address Once the server receives the request notification will be + /// sent to the client everytime an ouput is found. + /// + /// See: + pub async fn subscribe(&mut self, subscribe_req: request::SpSubscribe) -> Result { + self.version().await?; + debug!("Sending subscribe event request..."); + + let res = timeout( + self.request_timeout, + self.client.send_request(subscribe_req), + ) + .await + .map_err(|_| FrigateError::Timeout("Subscribe request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("Subscribe request failed: {e}")))?; + + info!("Subscribed to silent payment address: {res}"); + Ok(res) + } + + #[expect(unused, reason = "tbd")] + pub async fn unsubscribe(&mut self, unsub_req: request::SpUnsubscribe) -> Result<()> { + self.version().await?; + + let res = timeout(self.request_timeout, self.client.send_request(unsub_req)) + .await + .map_err(|_| FrigateError::Timeout("Unsubscribe request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("Unsubscribe request failed: {e}")))?; + + info!("Unsubscribed to silent payment address: {res:?}"); + Ok(()) + } + + pub async fn scripthash_subscribe( + &mut self, + sub_req: request::ScriptHashSubscribe, + ) -> Result> { + self.version().await?; + let res = timeout(self.request_timeout, self.client.send_request(sub_req)) + .await + .map_err(|_| FrigateError::Timeout("Script hash subscription timed out".to_owned()))? + .map_err(|e| { + FrigateError::Request(format!("Script hash subscription request failed: {e}")) + })?; + + info!("Subscribed to script: {res:?}"); + Ok(res) + } + + pub async fn get_history( + &mut self, + script_hash: ElectrumScriptHash, + ) -> Result> { + self.version().await?; + + let res = timeout( + self.request_timeout, + self.client + .send_request(request::GetHistory { script_hash }), + ) + .await + .map_err(|_| FrigateError::Timeout("Script history request timed out".to_owned()))? + .map_err(|e| FrigateError::Request(format!("Script history request failed: {e}")))?; + Ok(res) + } +} diff --git a/scanners/remote/frigate/src/lib.rs b/scanners/remote/frigate/src/lib.rs new file mode 100644 index 00000000..6f9104d0 --- /dev/null +++ b/scanners/remote/frigate/src/lib.rs @@ -0,0 +1,3 @@ +mod client; +mod scanner; +pub use scanner::FrigateScanner as Scanner; diff --git a/scanners/remote/frigate/src/scanner.rs b/scanners/remote/frigate/src/scanner.rs new file mode 100644 index 00000000..d0a20682 --- /dev/null +++ b/scanners/remote/frigate/src/scanner.rs @@ -0,0 +1,377 @@ +use std::collections::{BTreeMap, HashMap, HashSet}; + +use bitcoin::absolute::Height; +use bitcoin::secp256k1::{PublicKey, SecretKey}; +use bitcoin::{OutPoint, ScriptBuf, Transaction, TxOut, Txid, XOnlyPublicKey}; +use electrum_streaming_client::notification::Notification; +use electrum_streaming_client::{ElectrumScriptHash, Event, request}; +use futures::channel::mpsc::{Receiver, channel}; +use futures::{SinkExt as _, StreamExt as _}; +use log::{debug, error, info, warn}; +use silentpayments::receiving::Receiver as SpReceiver; +use silentpayments::utils::receiving::{ + calculate_ecdh_shared_secret, generate_script_pubkey_from_output_key, +}; +use spdk_core::scanner::{DiscoveredOutput, ScanResult, Scanner}; + +use crate::client::FrigateClient; + +pub struct FrigateScanner { + client: FrigateClient, + b_scan: SecretKey, + sp_receiver: SpReceiver, + labels: Option>, + owned_outpoints: HashSet, +} + +impl FrigateScanner { + pub async fn new( + host_url: String, + b_scan: SecretKey, + sp_receiver: SpReceiver, + labels: Option>, + owned_outpoints: HashSet, + ) -> anyhow::Result { + let client = FrigateClient::connect(&host_url).await?; + Ok(Self { + client, + b_scan, + sp_receiver, + labels, + owned_outpoints, + }) + } + + /// Starts a scan and keeps listening for confirmed spends of discovered outputs. + /// + /// The scan receiver is closed when the historical scan reaches progress `1.0`. The spent + /// receiver remains open for subsequent script-hash notifications. + pub fn scan_blocks_with_spent_outputs( + self, + range: std::ops::RangeInclusive, + ) -> (Receiver, Receiver>) { + self.start_scan(range, true) + } + + #[expect( + clippy::too_many_lines, + reason = "scan orchestration will be refactored later" + )] + fn start_scan( + mut self, + range: std::ops::RangeInclusive, + monitor_spent: bool, + ) -> (Receiver, Receiver>) { + let subscribe_params = request::SpSubscribe { + scan_priv_key: self.b_scan, + spend_pub_key: self.sp_receiver.receiving_code().m_pubkey(), + start_height: Some(range.start().to_consensus_u32()), + labels: self.labels, + }; + + info!( + "start: {} end: {}", + range.start().to_consensus_u32(), + range.end().to_consensus_u32(), + ); + + let (scan_tx, scan_rx) = channel(100_000); + let (mut spent_tx, spent_rx) = channel(100_000); + + tokio::spawn(async move { + let mut scan_tx = Some(scan_tx); + let mut tracked_scripts: HashMap> = + HashMap::new(); + let mut inspected_txids: HashMap> = HashMap::new(); + + match self.client.subscribe(subscribe_params).await { + Ok(sp_address) => info!("Subscribed to silent payments address {sp_address}"), + Err(e) => { + error!("Unable to subscribe to silent payments: {e}"); + return; + } + } + + while let Some(event) = self.client.events.next().await { + let Event::Notification(notification) = event else { + continue; + }; + + match notification { + Notification::SpSubscribe(sp_subscribe_notification) => { + let histories = sp_subscribe_notification.history; + let progress = sp_subscribe_notification.progress; + let mut secrets_by_height: BTreeMap> = + BTreeMap::new(); + + debug!("Received history {histories:#?}"); + info!("Found a total of {} output(s)", histories.len()); + + for history in &histories { + if history.height == 0 { + debug!("Skipping mempool transaction {}", history.tx_hash); + continue; + } + + secrets_by_height + .entry(history.height) + .or_default() + .insert(history.tx_hash, history.tweak_key); + } + + for (height, tx_tweaks) in secrets_by_height { + let blk_header = match self.client.get_block_header(height).await { + Ok(header) => header, + Err(e) => { + error!("Unable to fetch block header at height {height}: {e}"); + return; + } + }; + let blkheight = match Height::from_consensus(height) { + Ok(height) => height, + Err(e) => { + error!( + "Invalid block height {height} received from Frigate: {e}" + ); + return; + } + }; + + for (txid, tweak) in tx_tweaks { + let full_tx = match self.client.get_transaction(txid).await { + Ok(full_tx) => full_tx, + Err(e) => { + warn!( + "Skipping transaction {txid} after fetch failure: {e}" + ); + continue; + } + }; + let discovered_outputs = match process_outputs( + &full_tx.tx, + &self.b_scan, + &self.sp_receiver, + &tweak, + ) { + Ok(outputs) => outputs, + Err(e) => { + warn!("Skipping malformed transaction {txid}: {e}"); + continue; + } + }; + + self.owned_outpoints.extend(discovered_outputs.keys()); + + if monitor_spent { + subscribe_outputs( + &mut self.client, + &mut tracked_scripts, + &discovered_outputs, + ) + .await; + } + + let scan_res = ScanResult { + blkheight, + blkhash: blk_header.header.block_hash(), + discovered_inputs: HashSet::new(), + discovered_outputs, + }; + + if let Some(sender) = scan_tx.as_mut() { + if let Err(e) = sender.send(scan_res).await { + error!( + "Unable to send scan result: {e}; stopping scan output" + ); + scan_tx = None; + if !monitor_spent { + return; + } + } else { + info!("Scan result sent!"); + } + } + } + } + + if progress >= 1.0f32 { + if !monitor_spent { + info!("Scan completed!"); + break; + } + + if scan_tx.take().is_some() { + info!("Scan completed, monitoring spent outputs"); + } + } + } + Notification::ScriptHash(notification) if monitor_spent => { + let script_hash = notification.script_hash(); + let spent = match confirmed_spent_outpoints( + &mut self.client, + script_hash, + &tracked_scripts, + &mut inspected_txids, + ) + .await + { + Ok(spent) => spent, + Err(e) => { + error!( + "Unable to inspect history for script hash {script_hash}: {e}" + ); + continue; + } + }; + + if spent.is_empty() { + continue; + } + + self.owned_outpoints + .retain(|outpoint| !spent.contains(outpoint)); + for outpoints in tracked_scripts.values_mut() { + outpoints.retain(|outpoint| !spent.contains(outpoint)); + } + tracked_scripts.retain(|_, outpoints| !outpoints.is_empty()); + + if let Err(e) = spent_tx.send(spent).await { + error!("Unable to send spent output update: {e}; stopping monitor"); + return; + } + } + Notification::ScriptHash(_) => { + debug!("Ignoring script-hash notification after finite scan"); + } + notification => { + debug!("Ignoring unsupported notification: {notification:?}"); + } + } + } + }); + + (scan_rx, spent_rx) + } +} + +impl Scanner for FrigateScanner { + fn scan_blocks(self, range: std::ops::RangeInclusive) -> Receiver { + let (scan_rx, spent_rx) = self.start_scan(range, false); + drop(spent_rx); + scan_rx + } +} + +async fn subscribe_outputs( + client: &mut FrigateClient, + tracked_scripts: &mut HashMap>, + discovered_outputs: &HashMap, +) { + for (outpoint, output) in discovered_outputs { + let script_hash = ElectrumScriptHash::from(output.txout.script_pubkey.as_script()); + let first_output_for_script = !tracked_scripts.contains_key(&script_hash); + tracked_scripts + .entry(script_hash) + .or_default() + .insert(*outpoint); + + if !first_output_for_script { + continue; + } + + let request = request::ScriptHashSubscribe { script_hash }; + if let Err(e) = client.scripthash_subscribe(request).await { + error!("Unable to subscribe to script hash {script_hash}: {e}"); + } + } +} + +async fn confirmed_spent_outpoints( + client: &mut FrigateClient, + script_hash: ElectrumScriptHash, + tracked_scripts: &HashMap>, + inspected_txids: &mut HashMap>, +) -> anyhow::Result> { + let Some(owned_outpoints) = tracked_scripts.get(&script_hash) else { + return Ok(HashSet::new()); + }; + + let inspected_for_script = inspected_txids.entry(script_hash).or_default(); + let mut spent = HashSet::new(); + for history_entry in client.get_history(script_hash).await? { + if history_entry.confirmation_height().is_none() { + continue; + } + + let txid = history_entry.txid(); + if inspected_for_script.contains(&txid) { + continue; + } + + let full_tx = client.get_transaction(txid).await?; + for input in full_tx.tx.input { + if owned_outpoints.contains(&input.previous_output) { + spent.insert(input.previous_output); + } + } + inspected_for_script.insert(txid); + } + + Ok(spent) +} + +fn process_outputs( + tx: &Transaction, + b_scan: &SecretKey, + sp_receiver: &SpReceiver, + tweak: &PublicKey, +) -> anyhow::Result> { + let secret = calculate_ecdh_shared_secret(tweak, b_scan); + let txid: Txid = tx.compute_txid(); + let outputs_to_check = tx + .output + .iter() + .enumerate() + .filter(|(_idx, x)| x.script_pubkey.is_p2tr()) + .map(|(idx, txout)| { + let output_key = XOnlyPublicKey::from_slice(&txout.script_pubkey.as_bytes()[2..]) + .map_err(|e| anyhow::anyhow!("invalid Taproot output key at index {idx}: {e}"))?; + let vout = u32::try_from(idx) + .map_err(|e| anyhow::anyhow!("output index {idx} does not fit in u32: {e}"))?; + Ok((vout, txout.value, output_key)) + }) + .collect::>>()?; + + let output_keys: Vec = outputs_to_check + .iter() + .map(|(_, _, output_key)| *output_key) + .collect(); + + let ours = sp_receiver.scan_transaction(&secret, &output_keys)?; + + let mut res = HashMap::new(); + for (vout, value, output_key) in outputs_to_check { + for (label, map) in &ours { + if let Some(tweak) = map.get(&output_key) { + let outpoint = OutPoint { txid, vout }; + let spk_bytes = generate_script_pubkey_from_output_key(output_key); + let script_pubkey = ScriptBuf::from_bytes(spk_bytes.to_vec()); + + res.insert( + outpoint, + DiscoveredOutput { + txout: TxOut { + value, + script_pubkey, + }, + tweak: *tweak, + label: label.clone(), + }, + ); + break; + } + } + } + + Ok(res) +}