Consolidate ReconstructedUtxos and Coin Types to Reduce Complexity

[Legend101Zz]

Background

Currently, our UTXO reconstruction logic involves an unnecessary three-step type conversion chain:

1. reconstructSingleUtxo returns a ReconstructedUtxos object
2. convertCaravanUtxoToCoin converts it to a Coin object
3. getUtxoFromCoin converts it back to a UTXO object

This creates a confusing data flow and highlights unnecessary complexity in our type system.

Problem

The ReconstructedUtxos and Coin types are conceptually the same thing with minor property naming differences:

ReconstructedUtxos:

{
  txid: string;
  index: number;
  amountSats: string;
  amount: string;
  confirmed: boolean;
  transactionHex: string;
  multisig: any;
  bip32Path: string;
  change: boolean;
}

Coin

{
  prevTxId: string;
  vout: number;
  address: string;
  value: string;
  prevTxHex: string;
  slice?: Slice;
}

Having two types for essentially the same concept leads to:

• Unnecessary conversions between types
• Harder maintenance - changes must be made in multiple places
• Cognitive overhead - developers must understand both types and conversion logic
• Reduced code clarity - the conversion chain makes the logic hard to follow

Proposed Solution

Consolidate these types into a single Coin type (or a unified type) that serves both purposes:

1. Update reconstructSingleUtxo → reconstructSingleCoin

   • Change return type from ReconstructedUtxos to Coin
   • Adjust property names to match Coin interface
   • Derive address from multisig.address

2. Update reconstructUtxosFromPendingTransactions

   • Change return type to use Coin[] instead of ReconstructedUtxos[]
   • Update all internal references

3. Eliminate convertCaravanUtxoToCoin

   • This function becomes unnecessary after consolidation

4. Update hook names and signatures:

   • Consider renaming useReconstructedUtxos to reflect coin terminology if appropriate
   • Update matchPsbtInputsToUtxos parameter types

5. Update buildUtxoFromSpendingTransaction

   • Simplify by removing the conversion step
   • Directly use reconstructed coin with getUtxoFromCoin

[TomLucasakaTGeek]

Hi @Legend101Zz @bucko13 , can I take this issue, I have understood the Proposed Solution.

[Legend101Zz]

@TomLucasakaTGeek thanks for your interest , sure please go ahead and, I'll assign the issue to you :)
You can ping me in the discord server or here if you face any issues or would like to discuss anything on the issue ...

[TomLucasakaTGeek]

Sir @Legend101Zz I can see in the file utxo.ts, you are converting the Coin back into a UTXO,

so the data goes from Utxo -> Coin -> Utxo, turning things upside down.

Will it require any "fixing" too, or I should not try to change it if its critical.

[TomLucasakaTGeek]

The main problem I am struggling with is creating a unified type having both required parameters of ReconstructedUtxo and Coins and also the ones that are important for processing, but later on are not really included in the Coin.

Essentially, which fields are essential and which are not.

The fields with cross ❌ are the ones that I am going to include in the consolidated coin ( they are also in the table on the right side for a more precise side-by-side comparison ),
The fields that are boxed are the ones I have no idea on where to put exactly @Legend101Zz @bucko13 .

[Legend101Zz]

Hey @TomLucasakaTGeek , let me walk you through the whole reconstruction logic because it's pretty involved and understanding why we even need it in the first place will help clarify the type consolidation problem we're trying to solve.

Why UTXO Reconstruction Exists

The fundamental issue stems from how Caravan works as a stateless multisig coordinator. We don't maintain a persistent database of UTXOs like a traditional wallet would. Instead, we connect to either a public blockchain explorer or a private Bitcoin Core node and request UTXO data on demand. This architecture keeps Caravan lightweight and privacy-focused, but it creates challenges when dealing with Replace-By-Fee transactions.

If you're not familiar with RBF, it's a mechanism defined in BIP-125 that allows you to replace an unconfirmed transaction with a new version that pays a higher fee. The way it works is you create a new transaction that spends the exact same inputs as the original transaction, but with higher fees. When miners see both versions, they'll prefer the higher-fee transaction and effectively invalidate the lower-fee one.

Here's where the problem hits us. When you create an RBF transaction in Caravan, those original UTXOs have already been consumed by the pending transaction sitting in the mempool. Bitcoin Core's listunspent RPC call won't return UTXOs that are already spent by pending transactions because that would enable double-spending. So from Caravan's perspective, those UTXOs have completely disappeared from the available UTXO set, even though we legitimately need to reference them again for the RBF transaction.

Seeing The Problem In Action

If you fire up Caravan locally and install the Redux DevTools extension, you can actually watch this happen. Navigate to the wallet state and expand the deposits section. You'll see all the UTXOs that your wallet currently owns listed there with their transaction IDs, output indices, amounts, and all the metadata we track.

Now create a transaction and broadcast it, but don't let it confirm yet. Go back to Redux DevTools and refresh the UTXO list. You'll notice those UTXOs that were consumed by your pending transaction are no longer in the deposits array. They've vanished from our wallet state because listunspent no longer returns them.

This is the core problem we're solving with reconstruction. We need to rebuild those missing UTXOs using only the information we have about the pending transaction that consumed them.

The Three-Step Conversion Dance

Our current implementation handles this through a somewhat convoluted three-step type conversion process. Let me walk through each step and what it's trying to accomplish.

The first step happens in apps/coordinator/src/utils/uxtoReconstruction.ts in the reconstructSingleUtxo function. This function takes the input details from the pending transaction, looks up the original transaction that created that UTXO, and rebuilds a ReconstructedUtxos object. This type was designed to mirror the shape of data that lives in our Redux wallet slices, so it includes everything we track about a UTXO including the confirmed status, both BTC and satoshi amounts, whether it's a change output, and the complete multisig configuration from the slice.

The second step converts that ReconstructedUtxos into a Coin object using the convertCaravanUtxoToCoin function in the same file. The Coin type was an attempt to create a universal UTXO format that could work across different parts of the application. It renames several fields to match Bitcoin Core's conventions, so txid becomes prevTxId, index becomes vout, amountSats becomes value, and transactionHex becomes prevTxHex. It also extracts the address from the nested multisig object and shoves the entire original object into a slice field using a type cast.

The third step happens in apps/coordinator/src/hooks/utxos.ts in the getUtxoFromCoin function. This converts the Coin into the final UTXO format that the transactions package actually needs for PSBT creation. It renames everything back to the original field names, then extracts the signing metadata from the slice object. Based on the address type, it constructs the proper combination of nonWitnessUtxo, witnessUtxo, redeemScript, and witnessScript fields that BIP-174 requires for PSBT signing.

Why This Is Problematic

The issue is that the Coin type in the middle doesn't actually provide any value. It's purely a renaming layer that forces us to rename fields twice - once when creating it from ReconstructedUtxos, and again when converting it to the final UTXO format. This makes the code harder to follow and introduces unnecessary complexity in the type system.

What Fields Actually Matter

When you're designing the unified type, you need to understand what's truly essential versus what's just metadata we accumulated over time. Let me break this down by category.

For transaction identification, you absolutely need the txid, the vout or index (pick one naming convention and stick with it), and the value in satoshis. These three fields uniquely identify which output you're spending and how much it's worth. Without them, Bitcoin Core has no idea what UTXO you're referencing.

For PSBT signing, you need the prevTxHex which contains the full previous transaction. This protects against fee attacks in PSBTs. You also need the bip32Derivations array so hardware wallets know which keys to use for signing. Then depending on your address type, you need different combinations of scripts. For P2SH addresses you need nonWitnessUtxo and redeemScript. For P2WSH you need witnessUtxo and witnessScript. For P2SH-P2WSH you need all four of those fields.

Right now the code extracts these signing fields from the slice object in the final conversion step. You can see this in getUtxoFromCoin where it parses the addressType from slice.multisig.braidDetails, then uses slice.multisig.bip32Derivation for the derivations and slice.multisig.redeem.output for both the redeemScript and witnessScript.

For wallet metadata like the confirmed flag, the BTC-formatted amount, the string bip32Path, the change flag, and the address, none of these are required for PSBT creation. They're helpful for UI display and validation, but the PSBT signing process doesn't care about them.

The slice field itself is interesting because it's essentially smuggling the entire Slice object through the conversion by casting it as unknown. This works because getUtxoFromCoin immediately extracts what it actually needs from that slice. So the slice itself isn't essential, but the data it carries is.

My Recommendation

The key insight is that your unified type should be as close to the final UTXO format as possible. Instead of nesting signing metadata inside a slice or multisig object, extract those fields directly into the unified type. This eliminates the need for getUtxoFromCoin to do transformation work at all.

Look at the UTXO type definition in packages/transactions/src/types.ts to see what the transactions package actually expects. Your unified type should match that structure as closely as possible, adding only the minimal wallet metadata fields that your UI actually uses.

Testing Your Changes

I strongly recommend creating an actual RBF transaction in your local development environment and stepping through the entire flow with your new unified type. Start with a confirmed transaction, then create a replacement transaction and watch how the reconstruction logic handles it. Check the Redux DevTools to see when UTXOs disappear and reappear. Use breakpoints in reconstructSingleUtxo, your new conversion function, and the PSBT creation code in packages/transactions/src/btcTransactionTemplate.ts where addInputToPsbt constructs the PSBT input data.

The files you'll want to pay close attention to are apps/coordinator/src/utils/uxtoReconstruction.ts for the reconstruction logic, apps/coordinator/src/hooks/utxos.ts for the current conversion functions, packages/transactions/src/types.ts for the target UTXO type definition, and packages/transactions/src/btcTransactionTemplate.ts for how those UTXOs actually get used in PSBT creation.

This is a pretty involved change that touches multiple layers of the application, so take your time with it and test thoroughly with actual RBF scenarios and please don't be shy to ask anything :)

[bucko13]

Great write up @Legend101Zz. Thank you for the summary!

My two sats, conceptually for names, this is how I think about it at a high level:

1. UTXO - Unspent Transaction Output
   This is a bitcoin protocol native data structure. It describes the data that is put into a transaction as the input. It implies a state (unspent - either in the utxo set or in the mempool) as well as a pointer to another data structure (an output).

2. Coin
   I think of this as a stateless data structure (it doesn't imply being spent or not for example). A coin is a stateless object that can be spent. it is not native to the blockchain so it can have "additional" metadata that describes what it needs to be spent. For me this is where we should be housing information like derivation paths since a signing device/keystore REQUIRES certain information to know how to spend a coin.

3. Slice
   This is somewhat ancillary to spending. It can be thought of as a data structure that represents an address. As @Legend101Zz pointed out, slices carry information that is required for a coin to be spent before it can be spent as an input in a transaction. A "Slice" comes from our "Braid model" which you can learn more about here. An "address" as an idea is insufficient for everything we need to know about an address. An address is just a serialization of a locking script. A Slice carries more information relevant to a wallet, like what the redeem script will look like, the keys involved in the wallet, etc. A slice can also have many UTXOs associated with it as well as Coins.

So effectively a UTXO is what you get from the blockchain and it has state (which is why they can "disappear" from certain queries). A coin is more stateless (though if we wanted we can track if it has been spent or not) and it is a UTXO with additional metadata (such as the information needed to spend it). A Slice is something that can have a one to many relationship with Coins and UTXOs and provides the information necessary to decorate a utxo to create a coin.