Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ members = [
"backends/blindbit-v1",
"spdk-wallet",
"silentpayments",
"scanners/local",
"scanners/local",
"scanners/remote/frigate",
]
resolver = "3"

Expand Down Expand Up @@ -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"
Expand Down
1 change: 1 addition & 0 deletions scanners/remote/frigate/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/target
25 changes: 25 additions & 0 deletions scanners/remote/frigate/Cargo.toml
Original file line number Diff line number Diff line change
@@ -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
63 changes: 63 additions & 0 deletions scanners/remote/frigate/examples/frigate_scanner.rs
Original file line number Diff line number Diff line change
@@ -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";

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could replace these with the 2140 frigate server (frigate.2140.dev), alternatively we could host our own signet frigate server. I think for an example file, using the 2140.dev server is probably the most useful.

// 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<OutPoint>,
pub discovered_outputs: HashMap<OutPoint, DiscoveredOutput>,
}

#[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.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scan_blocks api currently expects that we're also scanning the inputs for spent scripts within this block range. If this is hard to do for the Frigate scanner, we could reconsider the Scanner api.

Currently the scan_blocks function is intended to be something a wallet calls in order to synchronize the changes that occur within a given block range. After all blocks are processed, the wallet is considered 'up to date' until this latest block height. Afterwards, the job of the scanner is completed. It does not monitor the blockchain any longer. We could call this a 'one-and-done' approach.

Electrum (and by extension, Frigate) takes a 'monitoring' approach, where we subscribe to a set of scripts, and continuously monitor the blockchain for changes.

Just to make the difference more explicit, this is how Dana does it:

  1. Dana comes online, for example after the user opens the app, or a background process wakes up the app
  2. Dana checks the current block_height from the chain backend api, and checks the stored last_height (the last known block height)
  3. if last_height < block_height, Dana creates a scanner object and initiates a scan for range last_height+1..=block_height.
  4. After the scan is complete, the scanner's job is finished and is dropped.
  5. If Dana is in the background, it goes back to sleep. If the app is currently open, Dana will fetch the current block_height every 10 seconds. Once Dana reads that a new block has been confirmed (block_height is increased), go back to step (3)

Most importantly, it is not the Scanner that monitors the blockchain for new blocks. The wallet (Dana) monitors the blockchain, and when it detects a new block, it kick-starts the scanning process.

We could change this, so that the Scanner becomes responsible for monitoring when new blocks arrive. I suspect this change would be much more compatible with the Electrum/Frigate approach, as the Scanner will now be the one to continuously monitor the blockchain. This also means the scanner can optionally notify the wallet of unconfirmed incoming payments.

So with this new approach, how Dana would work:

  1. Dana comes online, either by the user opening the app or the background process wakes up
  2. Dana reads last_height from storage, and makes a new Scanner with begin_height = last_scan+1
  3. The scanner now checks the block_height. If we are behind on block_height, Scanner initiates a scan of these blocks, and feeds Dana the updates (through the Receiver channels).
  4. If the scanner has reached the chain tip, one of things can occur:
    • (a) If the wallet is currently open, keep monitoring the scripts for changes (very similar to the native Electrum approach)
    • (b) If the wallet is currently operating as a background process, we have to terminate the scanner and go back to sleep. We tell the Scanner to unsubscribe from the scripts. The next time the app wakes up, start again from (1)

From the perspective of Dana as a background process, the 'one-and-done' approach is easier to reason about. This is because Dana is expected to wake up every hour or so, do the scanning, and then terminate the scanner and go back to sleep. However I'm sure it's possible, and allowing for continuous monitoring has other benefits as well, so I'm not opposed to making this change.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the detailed explanation. What you said here clearly summarizes the difference in approaches. It now makes much more sense on to why the scanner was taken by value.

(b) If the wallet is currently operating as a background process, we have to terminate the scanner and go back to sleep. We tell the Scanner to unsubscribe from the scripts. The next time the app wakes up, start again from (1)

I think here that on waking up there will need to be subscribe requests to the scripts known, at least for the Frigate/Electrum approach else you won't be able to know whether something is spent or not.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is because Dana is expected to wake up every hour or so, do the scanning, and then terminate the scanner and go back to sleep.

I'm pretty sure that foreground service would allow us to keep the subscription to frigate open and allow for the continuous monitoring approach. We had to use that polling approach for blindbit because of the way the v1 works, not because of android foreground services.

let mut rx = frigate_scanner.scan_blocks(start..=end);

while let Ok(update) = rx.recv().await {
// print all received updates
println!("{update:#?}");
}

Ok(())
}
190 changes: 190 additions & 0 deletions scanners/remote/frigate/src/client.rs
Original file line number Diff line number Diff line change
@@ -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<Event>,
pub worker: JoinHandle<Result<(), std::io::Error>>,
pub request_timeout: Duration,
protocol_version: Option<String>,
}

#[derive(Debug)]
pub enum FrigateError {
Connection(String),

@cygnet3 cygnet3 Oct 22, 2026 •

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking of switching to the thiserror crate, this might be a good time to introduce that to get rid of some of the boilerplate code.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes as we proposed as we discussed I'll work on that but after this PR. I'll have a follow up where I get rid of anyhow in the whole project

Timeout(String),
Request(String),
}

type Result<T, E = FrigateError> = std::result::Result<T, E>;

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<Self> {
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<HeaderResp> {
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<FullTx> {
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<String> {
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(),

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why have 1.4.1 be the last supported version? The 'main' public frigate server (frigate.2140.dev) runs version 1.6.0, I think it makes sense to target that

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we allow version more than 1.4.1, the negotiation will happen but we will send invalid requests.
There are few differences that make v1.4.1 and latest in the payload returned payloads incompatible.

We're using electrum_streaming_client to make requests to the frigate server, which for now is capped at v1.4.1
we could easily extend that but I suggest to keep the PR scope small let's allow this here and in subsequent one we will support more recent version.

]),
}),
)
.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: <https://github.com/sparrowwallet/frigate#blockchainsilentpaymentssubscribe>
pub async fn subscribe(&mut self, subscribe_req: request::SpSubscribe) -> Result<String> {
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<Option<ElectrumScriptStatus>> {
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<Vec<electrum_streaming_client::response::Tx>> {
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)
}
}
3 changes: 3 additions & 0 deletions scanners/remote/frigate/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
mod client;
mod scanner;
pub use scanner::FrigateScanner as Scanner;
Loading
Loading