Add sent_and_received_txouts methods to SPK and Keychain TxOut indexes

[notmandatory]

Description

Implement sent_and_received_txouts methods on SpkTxOutIndex and KeychainTxOutIndex. These methods return actual TxOut structs allowing callers to access complete transaction output information including script pubkeys and values.

Notes to the reviewers

This info is useful to users who use the new WalletEvent data in bitcoindevkit/bdk_wallet#319. In particular to determine the addresses and amounts for TxOuts that are sent/spent or have been received in a newly seen or confirmed transaction. See: bdk_wallet#319 comment

If/when this PR is merged I'll make a corresponding one to add a Wallet::sent_and_received_txouts method.

Changelog notice

Added

• New sent_and_received_txouts methods on SpkTxOutIndex and KeychainTxOutIndex.

Checklists

All Submissions:

• I followed the contribution guidelines

New Features:

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

[notmandatory]

@tnull would this information be useful for LDKnode when handling the transactions in WalletEvents ?

[tnull]

Ah, yes, that would be very helpful, we just recently got requests to be able to see which address was sent to: lightningdevkit/ldk-node#684

Do you happen to see a way to include the output's index in this API, too? (cf. lightningdevkit/ldk-node#717). Maybe the return type could be (Vec<(usize, TxOut)>, Vec<(usize, TxOut)>), or a similar struct representation?

[notmandatory]

Good idea, since the input & output Vecs of Transaction are in the correct order I'm able to return the index info with the TxOuts. See 6ff9f26.

[notmandatory]

@tnull did you get a chance to look at this again? it now returns the index and TxOut as you suggested.

[tnull]

Cool, thank you! Looks good!

[evanlinjin]

Thanks for this, Steve. The motivation is solid. I have some API design suggestions that I think would make this more ergonomic and precise.

Split into two methods: spent_txouts and created_txouts

"Sent" and "received" are wallet-UX terms that obscure what's actually happening at this layer. "Spent" and "created" map directly to Bitcoin's model—consuming existing UTXOs and creating new ones. This makes the API more self-documenting.

Splitting also means callers only pay for what they need. If someone only cares about detecting which UTXOs got consumed, they shouldn't have to iterate outputs too.

Return OutPoints, not just indices

For spent outputs, the caller almost certainly wants to know which UTXO was consumed. The current implementation gives the input index, but what you really need is txin.previous_output. Making the caller fish that out separately is awkward when the method already has that information.

For created outputs, returning the OutPoint (txid + vout) means callers can immediately track or spend that output without computing the txid themselves.

Use structs instead of tuples

pub struct SpentTxOut<I> {
    pub txout: TxOut,
    // Have a method: .outpoint()
    pub spending_input: TxIn,
    pub spending_input_index: usize,
    pub spk_index: I,
}

pub struct CreatedTxOut<I> {
    pub outpoint: OutPoint,
    pub txout: TxOut,
    pub spk_index: I,
}

spent.outpoint() is immediately clear. spent.0 requires checking docs every time.

Return iterators instead of Vec

More idiomatic, no upfront allocation, composable with .filter(), .map(), etc. If someone wants a Vec, they can .collect().

Drop the range parameter

The range conflates two concerns. Filtering by SPK index is trivial with iterators:

index.spent_txouts(&tx)
    .filter(|s| my_range.contains(&s.spk_index))