bitcoin-psbt

What this skill does

# PSBT (BIP174 / BIP370 / BIP371)

PSBT = a binary container for a transaction-in-progress, where one party
constructs the skeleton, others contribute signatures, and a finalizer
emits the broadcastable transaction.

## Versions

- **v0 (BIP174)** — original. Magic `psbt\xff`. Tx is fully serialized
  in `PSBT_GLOBAL_UNSIGNED_TX`.
- **v2 (BIP370)** — version field, per-input/output amount fields.
  Allows incremental construction without re-encoding the whole tx.
  Required for some workflows (BOLT12, advanced taproot).
- **BIP371** adds Taproot-specific fields (orthogonal to version).

## Roles

| Role | Responsibility |
|------|---------------|
| **Creator** | Builds initial PSBT skeleton (inputs, outputs, no sigs). |
| **Updater** | Adds metadata: `non_witness_utxo`, `witness_utxo`, derivation paths, redeem/witness scripts, taptree info. |
| **Signer** | Reads PSBT, produces partial sigs for inputs it controls. |
| **Combiner** | Merges multiple Signers' partial PSBTs into one. |
| **Finalizer** | Replaces partial sigs with `final_scriptSig` / `final_scriptWitness`. |
| **Extractor** | Pulls final tx from finalized PSBT for broadcast. |

Tools: `walletprocesspsbt`, `combinepsbt`, `finalizepsbt`,
`decodepsbt`, `analyzepsbt` (Bitcoin Core); `hwi signtx` (hardware
wallet); Sparrow/Specter/Caravan for coordination.

## Wire format (v0)

```
[5 bytes]  magic = b"psbt" + 0xff
[ globals section ]
[ for each input:  inputs section, terminated by 0x00 ]
[ for each output: outputs section, terminated by 0x00 ]
```

Each section is a series of `<key, value>` pairs:
```
[varint] key length
[1 byte] key type
[..]     key data
[varint] value length
[..]     value data
```

End of section = 0x00 byte (zero-length key).

## Required input fields by output type being spent

| Output type | Required |
|-------------|----------|
| **Legacy P2PKH/P2SH** | `non_witness_utxo` (full prev tx) |
| **SegWit v0 (P2WPKH/P2WSH)** | `witness_utxo` (just the spent output) **AND** `non_witness_utxo` recommended (defends against fee-bumping attack on signing devices) |
| **P2SH-wrapped SegWit** | both, plus `redeem_script` |
| **P2WSH** | `witness_script` |
| **Taproot key-path** | `witness_utxo` + `taproot_internal_key` + `tap_bip32_derivation` |
| **Taproot script-path** | above + `tap_leaf_script` (script + control block) + `tap_script_sig` |

Always include **all spent prevouts** for Taproot inputs — sighash
commits to all of them (BIP341).

## Key BIP174 fields (selected)

| Section | Type | Name |
|---------|------|------|
| Global | 0x00 | `PSBT_GLOBAL_UNSIGNED_TX` |
| Global | 0x01 | `PSBT_GLOBAL_XPUB` |
| Global | 0xfb | `PSBT_GLOBAL_VERSION` (v2 only) |
| Input | 0x00 | `PSBT_IN_NON_WITNESS_UTXO` |
| Input | 0x01 | `PSBT_IN_WITNESS_UTXO` |
| Input | 0x02 | `PSBT_IN_PARTIAL_SIG` |
| Input | 0x03 | `PSBT_IN_SIGHASH_TYPE` |
| Input | 0x04 | `PSBT_IN_REDEEM_SCRIPT` |
| Input | 0x05 | `PSBT_IN_WITNESS_SCRIPT` |
| Input | 0x06 | `PSBT_IN_BIP32_DERIVATION` |
| Input | 0x07 | `PSBT_IN_FINAL_SCRIPTSIG` |
| Input | 0x08 | `PSBT_IN_FINAL_SCRIPTWITNESS` |
| Input | 0x13 | `PSBT_IN_TAP_KEY_SIG` (BIP371) |
| Input | 0x14 | `PSBT_IN_TAP_SCRIPT_SIG` |
| Input | 0x15 | `PSBT_IN_TAP_LEAF_SCRIPT` |
| Input | 0x16 | `PSBT_IN_TAP_BIP32_DERIVATION` |
| Input | 0x17 | `PSBT_IN_TAP_INTERNAL_KEY` |
| Input | 0x18 | `PSBT_IN_TAP_MERKLE_ROOT` |
| Output | 0x00 | `PSBT_OUT_REDEEM_SCRIPT` |
| Output | 0x01 | `PSBT_OUT_WITNESS_SCRIPT` |
| Output | 0x02 | `PSBT_OUT_BIP32_DERIVATION` |
| Output | 0x05 | `PSBT_OUT_TAP_INTERNAL_KEY` |
| Output | 0x06 | `PSBT_OUT_TAP_TREE` |
| Output | 0x07 | `PSBT_OUT_TAP_BIP32_DERIVATION` |

Proprietary fields use type `0xfc` with key prefix.

## Encoding helpers

PSBT can be encoded as:
- Binary (canonical wire format).
- Base64 (most common transport between wallets).
- Hex (less common, larger).

A "PSBT object" with the right magic bytes round-trips losslessly.

## Common bugs

- Missing `non_witness_utxo` for SegWit inputs on hardware signers
  → device refuses to sign (post Coinkite/Trezor/Ledger fix for
  fee-bumping attack).
- Wrong `bip32_derivation` paths → device cannot find the key.
- Combining PSBTs from different versions (v0 ↔ v2) → format error.
- Missing `tap_internal_key` for Taproot inputs → finalizer cannot
  reconstruct script-path / verify key-path.
- Calling Finalizer before all required signers contributed → leaves
  partial sigs in place; tx will be invalid if extracted.

## See also

- [descriptors/SKILL.md](../descriptors/SKILL.md)
- [taproot/SKILL.md](../taproot/SKILL.md)
- [../../wallets/hd/SKILL.md](../../wallets/hd/SKILL.md)
- [../../hardware/psbt-flows/SKILL.md](../../hardware/psbt-flows/SKILL.md)