bitcoin-hardware-psbt-flows

v2026.09.24

PSBT signing flow patterns across HW vendors: USB direct, microSD airgap, QR airgap, NFC, multi-device coordination, silent-payment PSBT fields (BIP375/BIP376). USE WHEN: designing HW signing UX, debugging cross-device PSBT flow, supporting multi-vendor multisig or silent payments.

GitHub
安装命令
npx skhub add claude-dev-suite/bitcoin-hardware-psbt-flows
Markdown
SKILL.md

PSBT Signing Flow Patterns

A summary of how PSBTs flow through different hardware wallet transports.

Flow types

USB direct (online signer)

Host wallet ──── PSBT ────► HW (via USB)
            ◄── signed PSBT

Wallets: Trezor, Ledger, BitBox02, Coldcard via USB, Jade USB, Keystone (charging only).

Pro: fastest. Con: USB connectivity = potentially compromised host.

microSD airgap (true offline)

Host wallet → save PSBT to SD → eject → insert into HW → sign on
HW → eject → insert into Host

Wallets: Coldcard, Passport Core, Jade (with SD), Keystone.

Pro: no USB connection; truly airgapped. Con: SD card handling overhead.

QR airgap (animated QR / BCUR)

Host wallet displays animated QR → HW reads via camera
→ HW signs → HW displays animated QR → Host reads

Wallets: Passport Core, Coldcard Q, Jade, Keystone, SeedSigner, Krux. Passport Prime scans QR too, but its USB-C data port, NFC and Bluetooth are all live (as of September 2026), so QR on Prime is a transport, not an airgap.

Pro: no physical connection. Con: scan time for big PSBTs.

BCUR (Blockchain Commons UR Format) is the standard encoding for multi-frame QR. Compatible wallets must understand BCUR.

NFC tap

Host (phone) → NFC tap to HW → HW signs → NFC tap back

Wallets: Coldcard Mk4 / Q, some others. Not Passport: Core has no radios at all (power-only USB-C, QR + microSD), and Prime's NFC carries only its Shamir backup KeyCards, not PSBTs (as of September 2026).

Pro: convenient with Android. Con: iOS NFC limited; PSBT size limits.

Coordinator role

For multisig, a coordinator wallet handles:

  1. Build PSBT.
  2. Send to signer 1, get partial sig.
  3. Send to signer 2, get partial sig.
  4. Combine + finalize.
  5. Broadcast.

Coordinators:

  • Sparrow Desktop — best for cross-vendor multisig.
  • Specter Desktop — multisig + multiple HW.
  • Caravan — web-based multisig.
  • Bitcoin Core with HWI external signer — but HWI entered a maintenance-only wind-down in August 2026 (no new features, no new devices, repo to be archived once a drop-in replacement is ready), so weigh it before building on it: hwi/SKILL.md.

PSBT versions

  • v0 (BIP174): widely supported; still the safe interop default as of September 2026.
  • v2 (BIP370): required for the silent-payment fields below. Coldcard has parsed v2 since firmware 5.2.0 (October 2023); Sparrow made v2 its internal PSBT representation in 2.4.0 (February 2026).

For multi-device multisig, all signers must agree on PSBT version or coordinator transcodes between them.

Silent payments (BIP352) on hardware

Three BIPs carry silent payments into the hardware signing path. All of their new fields are PSBTv2-only — BIP375 and BIP376 both mark them as requiring exclusion from v0.

Sending: BIP375

BIP375 ("Sending Silent Payments with PSBTs", number assigned January 2025) lets a PSBT name a recipient by silent-payment code rather than by script, because the output script cannot be computed until every input is known.

  • PSBT_OUT_SP_V0_INFO = 0x09 — 33-byte scan key + 33-byte spend key. PSBT_OUT_SCRIPT becomes optional when this is present.
  • PSBT_OUT_SP_V0_LABEL = 0x0a — label index, so a signer can verify that a silent-payment output is its own change.
  • PSBT_IN_SP_ECDH_SHARE = 0x1d / PSBT_GLOBAL_SP_ECDH_SHARE = 0x07 — a*B_scan for one input, or for the sum over all eligible inputs.
  • PSBT_IN_SP_DLEQ = 0x1e / PSBT_GLOBAL_SP_DLEQ = 0x08 — a 64-byte BIP374 discrete-log-equality proof for the matching ECDH share.

The DLEQ proof is what makes this safe on a device: a signer that does not hold every input key can still verify the other signers' shares before it computes and commits to PSBT_OUT_SCRIPT. Extra signer rules that trip devices:

  • Fail if any input spends a segwit version > 1 output.
  • SIGHASH_ALL only — output scripts are derived from the number and position of the codes, which NONE/SINGLE would let move.
  • No signature until every silent-payment output has a computed PSBT_OUT_SCRIPT; whoever fills those in must clear the Inputs Modifiable and Outputs Modifiable flags.

Spending: BIP376

BIP376 ("Spending Silent Payment outputs with PSBTs", assigned February 2026, merged to the BIPs repo April 2026) covers the other direction:

  • PSBT_IN_SP_TWEAK = 0x20 — the 32-byte tweak recovered during scanning.
  • PSBT_IN_SP_SPEND_BIP32_DERIVATION = 0x1f — fingerprint + path for the 33-byte spend key. It cannot reuse PSBT_IN_TAP_BIP32_DERIVATION, whose keydata is a 32-byte x-only key.

The signer derives d = (b_spend + tweak) mod n, negates d if d*G has an odd y-coordinate, and must fail if x(d*G) does not equal the output key P in the witness UTXO — the tweak comes from the Updater, and signing on an unverified one produces a valid signature for a key the device does not control. Finalizers strip PSBT_IN_SP_TWEAK and PSBT_IN_SP_SPEND_BIP32_DERIVATION once PSBT_IN_FINAL_SCRIPTWITNESS is built.

Why an airgapped signer can sign but cannot scan

The BIP376 tweak is handed to the device. Recovering it means scanning the chain with the scan private key, which an offline signer cannot do. BIP392 (sp() output descriptors, merged March 2026) encodes the split directly: its spscan key expression holds the scan private key plus the spend public key — exactly a watch-only coordinator — while spspend holds both private keys. So the coordinator scans and supplies tweaks; the hardware signer only ever sees a spend-key derivation and a 32-byte tweak that it re-verifies.

Shipping support (as of September 2026)

  • BitBox02 firmware v9.21.0 (September 2024) — sending to BIP352 addresses. The device returns a 33-byte ECDH share plus a 64-byte DLEQ proof over its own USB protocol so the host can re-derive and check the generated output; the same construction BIP375 later standardised as PSBT fields.
  • Sparrow 2.3.0 (October 2025) — sending to silent-payment addresses; 2.4.0 (February 2026) — BIP375 PSBT fields and DLEQ proof verification for hardware-wallet sends; 2.5.0 (May 2026) — silent-payment receiving wallets, including airgapped hardware signers.

BIP374, BIP375, BIP376 and BIP392 are all still Draft status as of September 2026.

Cross-vendor multisig

Best practice: use descriptors with key origins:

wsh(sortedmulti(2,
  [fp1/48'/0'/0'/2']xpub1.../<0;1>/*,
  [fp2/48'/0'/0'/2']xpub2.../<0;1>/*,
  [fp3/48'/0'/0'/2']xpub3.../<0;1>/*
))#chk

Each signer's device must:

  • Have its xpub at the declared path.
  • Match key origin fingerprint.
  • Recognize the wallet policy (Ledger requires explicit registration with HMAC).

Common pitfalls

  • PSBT missing data: device rejects if non_witness_utxo or tap_internal_key missing for the input type.
  • Path mismatch: device can't find the key for declared derivation.
  • Multi-vendor wallet policy registration: Ledger requires explicit wallet-policy + HMAC registration before multisig signing.
  • Stale PSBT: signer signed an old version; coordinator must reconcile.
  • Silent-payment PSBT downgraded to v0: the BIP375/BIP376 fields are v2-only, so a coordinator that transcodes down silently drops the ECDH shares, DLEQ proofs and tweaks.
  • Air-gap delays: long PSBTs via QR/SD take minutes; users abandon.

See also

发现
标签

此技能尚未发布标签。

版本
最新版本元数据

版本

v2026.09.24

发布时间

2026年9月24日

分类

未分类

许可证

MIT

源路径

skills/bitcoin/hardware/psbt-flows

默认分支

main

最新提交

9496306

Tree SHA

fe4e2f1