3.0 by reez · Pull Request #971 · bitcoindevkit/bdk-ffi

reez · 2026-03-11T19:32:55Z

Description

Exposing 3.0 items.

Notes to the reviewers

Documentation

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing
I've added a changelog in the next release tracking issue (see example)
I've linked the relevant upstream docs or specs above

New Features:

I've added tests for the new feature
I've added docs for the new feature

Bugfixes:

This pull request breaks the existing API
I've added tests to reproduce the issue which are now passing
I'm linking the issue being fixed by this PR

thunderbiscuit · 2026-03-11T19:39:16Z

🚀 🚀 🚀 🚀 🚀

reez · 2026-03-17T15:46:08Z

bitcoindevkit/bdk-kyoto#155 I opened this Draft PR (and a related issue)

Just using my fork of bdk-kyoto with the change rn

reez · 2026-04-13T16:08:18Z

updated to official 3.0

rustaceanrob · 2026-04-14T10:20:28Z

bdk_kyoto = 0.16.0 is out and includes the 3.0.0 release

reez · 2026-04-14T15:39:54Z

bdk_kyoto = 0.16.0 is out and includes the 3.0.0 release

thanks I updated to 0.16.0 and made one small change update_rx: Mutex<UpdateSubscriber<bdk_kyoto::wallets::Single>> necessary along with it in 27be17f

thunderbiscuit

I compiled and ran Rust tests locally today. Just started looking at this and left a few comments. I haven't gone through all files yet (tx_builder, types, wallet left to do). I'll try and migrate the Android app to this potential alpha to see how the migration goes! Looks like it should be pretty smooth.

thunderbiscuit · 2026-04-15T18:51:28Z

 [package]
 name = "bdk-ffi"
-version = "2.4.0-alpha.0"
+version = "3.0.0"


This one here I think should read 3.0.0-alpha.0 since this would merge on master.

Ahhh, I guess I did no -alpha just because in my head I was thinking we only bumped to -alpha after the release work was merged to master and the release was cut, but I might have been remembering that wrong.

No strong opinion from me, just wanted to double check w ya, but im good with whatever you comment back on this for me to change it to.

(go w thunders suggestion here)

updated w commit 061266b

thunderbiscuit · 2026-04-15T18:56:37Z

        let secp = Secp256k1::new();
-        let (extended_descriptor, key_map) = descriptor.into_wallet_descriptor(&secp, network)?;
+        let (extended_descriptor, key_map) =
+            descriptor.into_wallet_descriptor(&secp, network.into())?;


I still need to get to grips with the NetworkKind type. Are there situations where we'd like to use that instead of the Network for example? Not sure.

I don’t have any concrete ffi facing cases that come to mind, since NetworkKind only has Main and Test... I’ve been thinking of it as mostly an internal/upstream type for apis that only care about that distinction, where bdk-ffi consumers would usually want the full Network to preserve the actual chain. But I need to keep thinking about it more too so im glad you commented on it here

thunderbiscuit · 2026-04-15T19:05:23Z

+#[derive(Debug, Clone, uniffi::Record)]
+pub struct PreV1WalletKeychain {
+    /// The wallet keychain.
+    pub keychain: bdk_wallet::KeychainKind,


Can we use our own KeychainKind from the types module here? I think they're functionally equivalent because it's using remote enums in uniffi, but could still be a tiny cleanup unless I am missing something.

I think the small uniffi wrinkle i found here was crate::types::KeychainKind isn’t currently usable from this module because the backing alias in types.rs is private so switching this line wasn't a easy one line cleanup, and since the rest of the code was also using bdk_wallet::KeychainKind directly I decided to leave it as is in this PR.

But its definitely something we could do, it just seemed like it might end up needing to be a separate/bigger refactor

Ok this is so confusing to me 😆😆😆.

You're right most of the codebase uses the Rust type directly! But it's also... a trick!? I was confused by this ability to just use the Rust enum without any other fanfare (maybe a new feature from 0.30 I didn't know about?), especially that when you look at the generated bindings Kotlin code, the enum used in types.rs is the same enum used in say descriptors.rs, when in fact looking at the code those are two completely different types (one is custom made by us, one is the bdk_wallet library's type).

And so I was like "ok let's just cut it completely then!", but if you try to do that (remove the KeychainKind from types.rs), you actually get errors at the uniffi level, saying that KeychainKind is undefined. But wait it's just using the one from bdk_wallet... mmmmm

So it turns out that it doesn't. All files rely on our KeychainKind in types.rs, and I think this is related to how the visibility modifiers in Rust are disregarded by uniffi. You're correct it's not public, and yet the sort of type alias or whatever is used wherever you use KeychainKind.

I was able to clean this up and reconcile this is by simply making the type public and cleaning up the misleading imports in files that use the type. You're right it's sort of a sidequest, so I'll open a separate PR for it.

thunderbiscuit · 2026-04-15T19:06:34Z

    }
+
+    /// Retrieve keychain metadata from a pre-v1 BDK SQLite wallet database.
+    pub fn get_pre_v1_wallet_keychains(


I'd love to see a test for this one in the Android or Swift parts of the codebase if possible.

Yeah, that makes sense. I looked around the code and I think we already have Swift/Android persistence tests but I don’t think we had a pre-v1 SQLite database in the repo, so adding a bindings test for this I think would have meant adding that first. And then also I wasn't totally sure if we were going to expose this in 3.0 or not.

But im with you on if we do want to expose this for sure in our ffi 3.0 (or whenever we expose it in a release) that it would be quite nice to have a test for this, and prob worth putting in time to figure out how to test it well

thunderbiscuit · 2026-04-15T19:09:50Z


+/// Metadata describing a keychain in a pre-v1 BDK SQLite wallet database.
+#[derive(Debug, Clone, uniffi::Record)]
+pub struct PreV1WalletKeychain {


I was looking at the Rust code for this type and I see that the API docs have changed since you added it I think. See here.

this is deep in the weeds, I love it, good catch!

updated in 6cca30e

reez · 2026-04-20T17:20:57Z

@thunderbiscuit I rebased onto current master and dropped commits superseded by #978

reez · 2026-04-23T15:51:12Z

rebased

j-kon · 2026-04-29T11:43:34Z

+
+    if utxos.is_empty() {
+        println!("No UTXOs available, skipping sighash PSBT assertion");
+        return;


Nice addition covering the new sighash API.

One small test concern: this can pass without actually exercising the new behavior if the synced wallet has no UTXOs, because the test returns before checking input.sighash_type.

Would it be better to make the funded-wallet precondition explicit, or structure this so the test cannot silently skip the PSBT assertion?

yeah, updated the test now

reez · 2026-04-29T17:22:29Z

rebased again

thunderbiscuit

Still working through it but here are some thoughts!

thunderbiscuit · 2026-04-29T18:23:03Z

+    ///
+    /// [`apply_unconfirmed_txs`]: Self::apply_unconfirmed_txs
+    /// [`apply_update_events`]: Self::apply_update_events
+    pub fn apply_unconfirmed_txs_events(


I'm looking at this and the sister method apply_unconfirmed_txs(), and I'm wondering: how would you come across an UnconfirmedTx? We only use them as inputs to these two methods, and so someone would need to create one to them apply it? Wondering what the workflow is

I think this one is mostly for custom mempool/backend flows, not really the normal esplora/electrum sync -> apply_update path. (UnconfirmedTx is basically just the ffi version of upstream’s (tx, last_seen) tuple.) So the workflow in my mind would be something like: your app/backend sees a raw mempool tx, parses it into a Transaction, pairs it with the unix timestamp for when it saw it, and passes that in here.

thunderbiscuit · 2026-04-29T18:31:28Z

+    /// Retrieve keychain metadata from a pre-v1 BDK SQLite wallet database.
+    pub fn get_pre_v1_wallet_keychains(
+        &self,
+    ) -> Result<Vec<PreV1WalletKeychain>, PreV1MigrationError> {


The method is on the Persister type, but in the Rust library it's just a standalone function. I'm wondering if there is an advantage to this approach of making it into a associated fuction or some other reason you had in mind.

yeah I was thinking of Persister as the FFI stand in for the rusqlite::Connection here. Since upstream takes &mut Connection (and bdk-ffi hides that behind Persister) putting it there let callers run the migration helper against the same sqlite persister they already use for loading/persisting.

BUT I see the downside that it shows up on custom persisters too and then needs the SqliteOnly error. I don’t feel super strongly about it. What ideas are you thiniking about that are better, im def open to them

thunderbiscuit · 2026-04-29T18:49:03Z

+#[derive(Debug, Clone, uniffi::Record)]
+pub struct PreV1WalletKeychain {
+    /// The wallet keychain.
+    pub keychain: bdk_wallet::KeychainKind,


Ok this is so confusing to me 😆😆😆.

You're right most of the codebase uses the Rust type directly! But it's also... a trick!? I was confused by this ability to just use the Rust enum without any other fanfare (maybe a new feature from 0.30 I didn't know about?), especially that when you look at the generated bindings Kotlin code, the enum used in types.rs is the same enum used in say descriptors.rs, when in fact looking at the code those are two completely different types (one is custom made by us, one is the bdk_wallet library's type).

And so I was like "ok let's just cut it completely then!", but if you try to do that (remove the KeychainKind from types.rs), you actually get errors at the uniffi level, saying that KeychainKind is undefined. But wait it's just using the one from bdk_wallet... mmmmm

So it turns out that it doesn't. All files rely on our KeychainKind in types.rs, and I think this is related to how the visibility modifiers in Rust are disregarded by uniffi. You're correct it's not public, and yet the sort of type alias or whatever is used wherever you use KeychainKind.

I was able to clean this up and reconcile this is by simply making the type public and cleaning up the misleading imports in files that use the type. You're right it's sort of a sidequest, so I'll open a separate PR for it.

reez · 2026-04-29T20:31:26Z

#971 (comment)

@thunderbiscuit

Yeah agree, ack'd it

github-project-automation Bot added this to BDK-Bindings Mar 11, 2026

reez changed the title ~~(DRAFT) Rc1~~ (DRAFT) 3.0 Rc1 Mar 11, 2026

reez changed the title ~~(DRAFT) 3.0 Rc1~~ (DRAFT) 3.0 RC's Mar 27, 2026

reez linked an issue Mar 30, 2026 that may be closed by this pull request

bdk_wallet 3.0 #869

Open

reez changed the title ~~(DRAFT) 3.0 RC's~~ (DRAFT) 3.0 Apr 14, 2026

thunderbiscuit reviewed Apr 15, 2026

View reviewed changes

reez mentioned this pull request Apr 16, 2026

chore: bump bdk_wallet 3.0.0 and bdk_kyoto 0.16.0 #978

Merged

14 tasks

reez force-pushed the rc1 branch from 061266b to df64127 Compare April 20, 2026 17:19

reez changed the title ~~(DRAFT) 3.0~~ 3.0 Apr 20, 2026

reez marked this pull request as ready for review April 20, 2026 17:19

reez force-pushed the rc1 branch 2 times, most recently from 4e416f7 to 0fd82f2 Compare April 23, 2026 15:50

j-kon reviewed Apr 29, 2026

View reviewed changes

reez force-pushed the rc1 branch from 0fd82f2 to 2f033f9 Compare April 29, 2026 17:20

reez added 9 commits April 29, 2026 12:21

feat(wallet): expose apply_unconfirmed_txs_events

339152d

feat(wallet): expose apply_evicted_txs_events

00e1c49

feat(wallet): expose checkpoints

eb20784

feat(wallet): expose start_sync_with_revealed_spks_at

e60ac9d

feat(wallet): expose start_full_scan_at

1d837f4

feat(tx-builder): expose sighash

435f26e

feat(tx-builder): expose add_foreign_utxo_with_sequence

73d0e92

feat(tx-builder): expose ordering

5898df3

feat(wallet): expose locked outpoints and persist them in changesets

7f85d73

feat(store): expose pre-v1 sqlite migration helper

befe729

reez force-pushed the rc1 branch from 2f033f9 to befe729 Compare April 29, 2026 17:21

j-kon approved these changes Apr 29, 2026

View reviewed changes

thunderbiscuit reviewed Apr 29, 2026

View reviewed changes

thunderbiscuit mentioned this pull request Apr 29, 2026

refactor: use types::KeychainKind where appropriate #985

Merged

14 tasks

Conversation

reez commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Documentation

Checklists

All Submissions:

New Features:

Bugfixes:

Uh oh!

thunderbiscuit commented Mar 11, 2026

Uh oh!

reez commented Mar 17, 2026

Uh oh!

reez commented Apr 13, 2026

Uh oh!

rustaceanrob commented Apr 14, 2026

Uh oh!

reez commented Apr 14, 2026

Uh oh!

thunderbiscuit left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reez commented Apr 20, 2026

Uh oh!

reez commented Apr 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reez commented Apr 29, 2026

Uh oh!

thunderbiscuit left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reez commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

reez commented Mar 11, 2026 •

edited

Loading

reez commented Apr 29, 2026 •

edited

Loading