feat: integration of frigate ephemeral scanning

[sdmg15]

Description

This PR integrates the experimental Frigate scanning server with ephemeral client keys.

This was tested with Frigate version 1.3.2 and 1.4.1

Notes to the reviewers

The specification and how to run a frigate server can be found at: https://github.com/sparrowwallet/frigate/tree/1.4.1

Changelog notice

Checklists

All Submissions:

• I've signed all my commits
• I followed the conventional commit guidelines
• I ran just p (fmt, clippy and test) before committing

[nymius]

I have tried the command without success. Could you provide me some examples to try?

If you could create an executable step by step example like the built in doc/tabconf7 would be great.

Notice it builds a container with frigate on it. You only have to expose the ports to be able to communicate with it from outside of the container.

[sdmg15]

Thanks for a quick round of review, I noticed I have some unpushed changes which I just did.
I tried the containers commands but they took too long to build and I thought I'd just test "manually" by running frigate and rpc outside of it. But I'll give it another try from there will give you the commands to run.

[sdmg15]

@nymius the latest commit 6518059 is in a testable state.
I wasn't able to use the regtest playbook, due to issues mentionned in #49.

The only new command to what is inside regtest_playbook.sh is:
cargo run scan-frigate --url 127.0.0.1:57001 --start 0 assuming that that the Frigate client is running on port 57001

[nymius]

I fixed the issue with bdk-tx. You should rebase.

Successfully executed scanning on regtest:

$ REGTEST_ADDRESS=$(regtest-bdk unused_address | jq -r '.address' | tr -d '\n')
$ just mine 1 $REGTEST_ADDRESS
[
  "5e724d83a5e8999874ec679ed5823962f56c82bf4810be937b248dc5a08b15cb"
]
$ just mine 101 2>&1 >/dev/null
$ regtest-bdk sync
{}
$ regtest-bdk balance
{
  "satoshi": {
    "confirmed": 5000000000,
    "immature": 0,
    "trusted_pending": 0,
    "untrusted_pending": 0
  }
}
$ SP_CODE=$(regtest-sp code | jq -r '.silent_payment_code' | tr -d '\n')
$ RAW_TX=$(regtest-bdk create_sp_tx --to-sp $SP_CODE:10000 --fee_rate 5 | jq -r '.raw_tx' | tr -d '\n')
$ TXID=$(regtest-bdk broadcast --tx $RAW_TX | jq -r '.txid' | tr -d '\n')
$ just mine 1
[
  "2c28f3fa2cdd742a3e5e564f770802c558324506ea6db3ab6c0cea85ab83c0c3"
]
$ regtest-bdk sync
{}
$ regtest-bdk balance
{
  "satoshi": {
    "confirmed": 4999989228,
    "immature": 0,
    "trusted_pending": 0,
    "untrusted_pending": 0
  }
}
$ regtest-sp scan-frigate --url 127.0.0.1:57001 --start 0
2026-02-12T19:10:12.162809Z  WARN bdk_sp_oracles::frigate: Read bytes from stream 59
2026-02-12T19:10:12.183998Z  WARN bdk_sp_oracles::frigate: Read bytes from stream 156
2026-02-12T19:10:12.184062Z  INFO bdk_sp_oracles::frigate: Subscribed to silent payment address: String("sprt1qqvf42gn2770nwf8jvalczzv80ad8p9zseahnleklzzklqxkg5s80wqa7xxx58l2wvumjlmrzy9eed4vsd647jcmp6jg5tr08unyhex7u5chnkk64")
2026-02-12T19:10:12.184092Z  INFO sp_cli2: Starting frigate scanning loop...
2026-02-12T19:10:12.361669Z  WARN bdk_sp_oracles::frigate: Read bytes from stream 461
2026-02-12T19:10:12.414640Z  WARN bdk_sp_oracles::frigate: Read bytes from stream 200
2026-02-12T19:10:12.474964Z  WARN bdk_sp_oracles::frigate: Read bytes from stream 448
2026-02-12T19:10:12.475701Z  INFO sp_cli2: Progress 1
2026-02-12T19:10:12.475740Z  WARN sp_cli2: Scanning completed
$ echo $SP_CODE
sprt1qqvf42gn2770nwf8jvalczzv80ad8p9zseahnleklzzklqxkg5s80wqa7xxx58l2wvumjlmrzy9eed4vsd647jcmp6jg5tr08unyhex7u5chnkk64
$ regtest-sp balance
{
  "confirmed": {
    "immature": 0,
    "spendable": 0,
    "total": 0
  }
}
{
  "unconfirmed": {
    "total": 10000,
    "trusted": 0,
    "untrusted": 10000
  }
}

Notice the balance appears as unconfirmed because the block to which the transaction is anchored doesn't belong to the wallet local chain. I left a comment in the code mentioning how to fix that.

I think that Read bytes from stream {bytes} belongs to the DEBUG scope, rather than WARN. I would also print a one line log of the balance, after each execution of the command.

Could you give me more information about the issues that are preventing you from testing with the playbooks? Could you setup nix?

Good work!

[sdmg15]

Added a new playbook 59a1128. It's important to note that for this work we need to update Frigate to 1.3.2

[nymius]

I've checked the frigate_playbook.sh execution and it works great. I'm glad you were able to replicate it.

I recommend you to rebase and check each commit individually and:

• execute git show --check and fix any issue arising.
• execute just p and implement fixes and apply formatting.
• rewrite commits to use conventional commit format. Look at commit history to understand the conventions and scopes used.
• squash the commits into a single one.

[nymius]

I've pushed fixes and new changes to work on this from the nix environment, please rebase.

[sdmg15]

@nymius I addressed the comments in a separate commit 7c1cd05. Once approved I'll squash.

[nymius]

Hi @sdmg15, I think we should simplify this and avoid implementing JSON-RPC
code as much as possible. Your approach is working, locally, but the protocol
has some nuances that should be carefully considered.

I suggest you to have a look at electrum_streaming_client, it has:

• notification management:
  • Treates notifications as a different thing than responses:
    https://github.com/bitcoindevkit/electrum_streaming_client/blob/master/src/state.rs#L143,
    https://github.com/bitcoindevkit/electrum_streaming_client/blob/master/src/client.rs#L168-L194
• JSON encoding/decoding is done
  following JSON: RFC 4627 as specified by JSON-RPC protocol, in its overview:
  • Expects JSON encoded bytes in buffers and doesn't treat TCP block chunks
    indifferently:
    https://github.com/bitcoindevkit/electrum_streaming_client/blob/master/src/io.rs#L86
• Requests and responses are tracked and matched by their id, as
  expected:
  https://github.com/bitcoindevkit/electrum_streaming_client/blob/master/src/state.rs#L97-L128
  In your code, you're expecting the latest response to automatically match the
  id of the last request, which is going to work because you're not sending
  multiple request at the same time, but then, what's the point of implementing
  an asynchronous client anyway?

I recommend you to register the Frigate endpoints in a separate fork of
electrum_streaming_client (as a gated feature) and consider carefully how to
match the code conventions of the host repository. Then you can use that code
as a git dependency here.

[sdmg15]

Alright thanks for checking @nymius, I'll do that and let you know the outcome.

[nymius]

I will hold on this until electrum_streaming_client changes are stable.

[sdmg15]

By stable you mean once the opened PR there is merged?

[nymius]

By stable you mean once the opened PR there is merged?

Yes, or requested changed don't require breaking changes.

[sdmg15]

Hey @nymius, the PR inside bitcoindevkit/electrum_streaming_client#16 is already in a good shape. So I went ahead and updated the code with the final approved version.

[nymius]

Hey @nymius, the PR inside bitcoindevkit/electrum_streaming_client#16 is already in a good shape. So I went ahead and updated the code with the final approved version.

Thanks for the heads up, I will review both next week.

[nymius]

On top of d1d99ac, using the following patch:

diff --git a/cli/v2/Cargo.toml b/cli/v2/Cargo.toml
--- a/cli/v2/Cargo.toml
+++ b/cli/v2/Cargo.toml
@@ -21,6 +21,6 @@ rand = "0.9.0"
 indexer = { version = "0.1.0", path = "../../indexer", features = ["serde"]}
 bdk_sp_wallet = { version = "0.1.0", path = "../../wallet", features = ["serde"]}
 bdk_sp_oracles = { version = "0.1.0", path = "../../oracles" }
-electrum_streaming_client = { git = "https://github.com/sdmg15/electrum_streaming_client", rev = "f8e9178bf2f67af98364363028d909a65d741834", features = ["frigate"]}
+electrum_streaming_client = { git = "https://github.com/bitcoindevkit/electrum_streaming_client", rev = "01a6d42aac33f86b2bc647e7fc702067be99c9c7", features = ["frigate"]}
 tracing = "0.1.41"
 tracing-subscriber = "0.3.19"
diff --git a/cli/v2/src/main.rs b/cli/v2/src/main.rs
index d92eab6..1f6ccbc 100644
--- a/cli/v2/src/main.rs
+++ b/cli/v2/src/main.rs
@@ -224,7 +224,10 @@ pub enum Commands {

 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    let subscriber = tracing_subscriber::FmtSubscriber::new();
+    let subscriber = tracing_subscriber::FmtSubscriber::builder()
+    .with_max_level(tracing::Level::DEBUG)
+    .finish();
+
     tracing::subscriber::set_global_default(subscriber).unwrap();

     let db_path = if let Ok(db_path) = env::var("DB_PATH") {

I get:

$ RUST_LOG=debug just regtest-sp scan-frigate --url "127.0.0.1:57001"
2026-09-21T13:47:24.331395Z DEBUG bdk_sp_oracles::frigate: Worker task started
2026-09-21T13:47:24.338702Z DEBUG bdk_sp_oracles::frigate: Sending subscribe event request...
2026-09-21T13:47:24.341420Z DEBUG bdk_sp_oracles::frigate: Worker task completed successfully
Error: Request satisfied with error: Response.error: {"code":-32602,"message":"Invalid params"}

[sdmg15]

I included the patch in ca1f0fb and was able to rerun everything well.

Maybe you did not update the dependency in all the Cargo.toml?

[nymius]

Checked behavior against 1.4.1 version.