Skip to content

feat: expose Wallet::try_finalize_psbt outcomes - #1144

Merged
thunderbiscuit merged 1 commit into
bitcoindevkit:masterfrom
j-kon:feat/1059-try-finalize-psbt
Nov 17, 2026
Merged

thunderbiscuit merged 1 commit into
bitcoindevkit:masterfrom
j-kon:feat/1059-try-finalize-psbt

Conversation

@j-kon

@j-kon j-kon commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Description

Closes #1059. Intended for 3.2.0.

Expose Wallet::try_finalize_psbt from bdk_wallet 3.2.0 without changing the existing finalize_psbt API.

  • Return a FinalizePsbtOutcome record containing is_finalized and an input-indexed map of typed outcomes.
  • Preserve all four upstream outcome variants, reusing MiniscriptError for CouldNotSatisfy.
  • Return FinalizePsbtError::InputIndexOutOfBounds with both index and length for malformed PSBTs.
  • Add Rust coverage and network-free Swift/Kotlin binding tests.

Notes to the reviewers

Keeping this in draft for API-shape feedback and CI validation.

The method mutates the supplied PSBT in place. Per-input failures are outcomes, not thrown errors. As upstream specifies, timelocks are evaluated from transaction fields and output metadata is not cleared. No SignOptions argument is added.

The outcome is an FFI record rather than an object; is_finalized is a snapshot field and input indices use u64. The existing PsbtFinalizeError belongs to Psbt::finalize; this additive wallet API has its own error type to preserve upstream index/length details without changing existing variants.

Validation

  • cargo test --locked: 86 passed, 6 existing network-dependent tests ignored.
  • cargo fmt --check and cargo clippy --locked --all-targets -- -D warnings: passed.
  • Generated Swift bindings and ran swift test against a locally built macOS-only debug XCFramework: 22 passed. The local linker emitted deployment-target warnings for native dependency objects; this was not a release artifact build.
  • Generated and compiled Kotlin bindings with JNA 5.14.0; a Kotlin/JVM smoke test exercised the native finalization call and outcome map successfully.
  • Android instrumentation test added but not run locally. Full platform/release builds remain for CI.

Rust tests cover successful finalization and PSBT mutation, repeated finalization, unchanged output metadata, missing descriptors, unsatisfied inputs, and malformed input-map index details. Binding tests currently cover mixed MissingDescriptor/AlreadyFinalized outcomes.

Documentation

Changelog

changelog: added (maintainer label requested).

Checklists

  • Signed all commits
  • Followed contribution guidelines
  • Ran formatting and Clippy
  • Added exactly one changelog label
  • Linked upstream documentation
  • Added tests and API documentation

@thunderbiscuit thunderbiscuit left a comment •

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.

Awesome stuff! Thanks for working on this. I left a bunch of little comments to address or discuss. Of course @reez is the king of this upstream PR so I defer to him in case anything here in my comments/review is wrong.

Annex

I propose a more explicit Kotlin test that showcases a PSBT going from CouldNotSatisfy to Finalized to AlreadyFinalized. Let me know what you think.

@Test
fun tryFinalizePsbtFailsOnUnsignedInputs() {
    runBlocking {
        val regtestEnv = RegEnv.connectTo(
            host = "10.0.2.2",
            walletName = "faucet",
            username = "regtest",
            password = "password",
        )
        val wallet = Wallet(
            descriptor = BIP84_DESCRIPTOR,
            changeDescriptor = BIP84_CHANGE_DESCRIPTOR,
            network = Network.REGTEST,
            persister = Persister.newInMemory()
        )

        // Fund the wallet and sync it.
        val address = wallet.revealNextAddress(KeychainKind.EXTERNAL).address
        val txid = Txid.fromString(regtestEnv.send(address.toString(), 0.001, 2.0))
        regtestEnv.mine(1)
        val esploraClient = EsploraClient(ESPLORA_REGTEST_URL)
        // Wait for the Esplora client to see the transaction. Try 5x per second for 20 seconds.
        for (i in 0..99) {
            if (esploraClient.getTx(txid) != null) break
            delay(200.milliseconds)
        }
        val update = esploraClient.fullScan(wallet.startFullScan().build(), 10uL, 1uL)
        wallet.applyUpdate(update)

        // Build a transaction but don't sign it.
        val recipient = wallet.revealNextAddress(KeychainKind.EXTERNAL).address.scriptPubkey()
        val psbt = TxBuilder()
            .addRecipient(recipient, Amount.fromSat(10_000uL))
            .finish(wallet)

        // Every input is ours, but none can be satisfied without a signature.
        val unsigned = wallet.tryFinalizePsbt(psbt)
        assertFalse(unsigned.isFinalized)
        assertTrue(unsigned.outcomes.isNotEmpty())
        unsigned.outcomes.values.forEach { assertIs<FinalizeInputOutcome.CouldNotSatisfy>(it) }

        // Once signed (without finalizing), the same inputs finalize.
        wallet.sign(
            psbt,
            SignOptions(
                trustWitnessUtxo = false,
                assumeHeight = null,
                allowAllSighashes = false,
                tryFinalize = false,
                signWithTapInternalKey = true,
                allowGrinding = true,
            )
        )
        val signed = wallet.tryFinalizePsbt(psbt)
        assertTrue(signed.isFinalized)
        assertEquals(unsigned.outcomes.keys, signed.outcomes.keys)
        signed.outcomes.values.forEach { assertEquals(FinalizeInputOutcome.Finalized, it) }

        // Finalizing again leaves the PSBT finalized, with every input already finalized.
        val again = wallet.tryFinalizePsbt(psbt)
        assertTrue(again.isFinalized)
        assertEquals(signed.outcomes.keys, again.outcomes.keys)
        again.outcomes.values.forEach { assertEquals(FinalizeInputOutcome.AlreadyFinalized, it) }
    }
}

Comment thread bdk-ffi/src/types.rs Resolved
Comment thread bdk-ffi/src/types.rs Resolved
Comment thread bdk-ffi/src/types.rs Resolved
Comment thread bdk-ffi/src/types.rs Resolved
Comment thread bdk-ffi/src/types.rs Resolved
Comment thread bdk-ffi/src/wallet.rs Resolved
@j-kon
j-kon marked this pull request as ready for review October 16, 2026 04:47
@j-kon
j-kon requested a review from a team as a code owner October 16, 2026 04:47

@thunderbiscuit thunderbiscuit left a comment

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 ready to go IMO. Please squash all 3 commits into one. Thanks for this!

@reez reez left a comment

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.

ACK 527ad97

Expose detailed per-input finalization outcomes without changing the
existing finalize_psbt API. Preserve malformed input index and length
errors and cover finalization, failure mapping, output metadata, and
Swift/Kotlin binding round trips.
@thunderbiscuit
thunderbiscuit force-pushed the feat/1059-try-finalize-psbt branch from 527ad97 to c990031 Compare November 17, 2026 14:21

@thunderbiscuit thunderbiscuit left a comment

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.

ACK c990031.

@thunderbiscuit
thunderbiscuit merged commit c990031 into bitcoindevkit:master Nov 17, 2026
8 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in BDK-Bindings Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Expose Wallet::try_finalize_psbt API

3 participants