Add Multisig Wallet Support (configurable M-of-N, PSBT compatible)

[jamespepper81]

Add native multisignature wallet support to BitSleuth Wallet so users can create and manage M-of-N multisig wallets, coordinate signing with cosigners (including hardware wallets), and securely produce and broadcast transactions using PSBT workflows.

Motivation

Multisig increases security for users, organizations, and custodial setups by requiring multiple keys to sign a transaction. Supporting multisig will make BitSleuth suitable for higher-value use cases, shared wallets, and institutional workflows.

Goals

• Let users create multisig wallets with configurable M-of-N parameters (e.g., 2-of-3 recommended; allow user to select any M and N up to a practical limit).
• Explicitly support hardware wallets: Ledger, Trezor, Coldcard for signing workflows.
• Allow import of cosigner public keys (xpubs/ypub/zpub) and QR/PSBT exchange flows.
• Support PSBT creation, signing, merging, and finalization (hardware wallet compatible).
• Provide UX for cosigner coordination (export/scan QR, file, or air-gapped workflow).
• Maintain existing coin-control and fee-management features for multisig.

Non-goals

• Building a custodial multisig coordination server. All coordination will be peer-driven (QR, file, PSBT) in-app.
• Non-Bitcoin chains (focus on Bitcoin: legacy/nested SegWit/native SegWit).

User stories

• As a user, I can create a new multisig wallet, choose M and N (with 2-of-3 recommended as default), and add cosigner xpubs.
• As a user, I can import an existing multisig wallet from a set of cosigner xpubs or an extended descriptor.
• As a cosigner, I can receive a PSBT via QR/file and sign it with my private key (including from Ledger, Trezor, or Coldcard hardware wallets).
• As a user, I can see the signing progress and which cosigners have signed.
• As a user, I can finalize and broadcast a fully-signed PSBT.

Acceptance criteria

• Create multisig wallets with configurable M-of-N (N up to a practical limit, e.g., 5 maximum); recommend 2-of-3 but allow user selection.
• Import cosigner descriptors/xpubs with validation checks (key fingerprints, derivation paths).
• Generate wallet receive addresses according to the multisig policy and derivation path; addresses are compatible with Bitcoin Core / common wallets.
• Send workflow produces PSBT; app can export PSBT (QR or file) and import partially-signed PSBTs.
• App can merge multiple partial signatures, finalize, and broadcast a fully-signed transaction.
• PSBT support compatible with major hardware wallets (Ledger, Trezor, Coldcard) and with existing PSBT tooling.
• UI shows clear status, required remaining signatures, and identifies cosigners (if named).
• Unit and integration tests for key derivation, address generation, PSBT creation/merge/finalize, and coin selection in multisig context.
• Documentation and an end-user guide for creating and using multisig wallets and PSBT workflows.

Technical notes / implementation plan

• Data model
  • Store multisig wallet metadata: m, n, list of cosigner descriptors/xpubs, derivation scheme, address type (p2sh-p2wpkh, p2wsh, p2sh), wallet fingerprint(s).
  • Optionally store named cosigners and their fingerprints.
• Address and descriptor support
  • Prefer output scripts/descriptors that match address type selection; ensure compatibility with other wallets.
• Key handling
  • Never store private keys for cosigners other than the local key; local private keys handled using existing secure storage (encrypted + biometric unlock).
• PSBT workflow
  • Implement PSBT creation (with coin selection/fee control), export (file and QR split if large), import, sign (locally or via Ledger, Trezor, or Coldcard integration), merge, finalize, broadcast.
  • Support PSBT v2 compatibility considerations if relevant.
• Hardware wallet integration
  • Ensure compatibility layers for hardware signing (Ledger, Trezor, Coldcard PSBT flows) or allow export that those devices accept.
• Coin control
  • Reuse existing coin control logic with multisig-aware UTXO handling (scriptPubKey + descriptor).
• Compatibility
  • Validate addresses/derivations against standard multisig implementations (Bitcoin Core, Electrum, Sparrow).
• Edge cases
  • Handle cosigner xpub swapping, changing thresholds (migration), and missing cosigners gracefully.

Security considerations

• Never export or transmit private keys.
• Ensure secure storage of local private keys (same app protections).
• Warn users about risks of losing cosigner keys; provide backup recommendations.
• Validate cosigner xpubs/fingerprints to avoid typosquatting attacks.
• Consider UX warnings for reusing cosigners or derivation mismatches.

UX / flows

• Create multisig:
  • Choose name → choose M-of-N (2-of-3 recommended default, fully configurable) → choose address type (Nested SegWit / Native SegWit) → for each cosigner, add xpub (QR/scan/manual) and optional name/fingerprint → create wallet with sample receive address.
• Receive:
  • Show receive addresses for that multisig account with copy/QR.
• Send:
  • Create transaction with coin control and fee options → produce PSBT → show “Awaiting signatures (k of M)” with options to export PSBT (file/QR/share).
• Sign:
  • Import PSBT → sign with local key (biometric) OR pass to hardware wallet (Ledger, Trezor, Coldcard) flow → output partially-signed PSBT for distribution.
• Finalize:
  • When enough signatures collected, merge/finalize and broadcast.
• Import existing:
  • Import by cosigner xpubs or by descriptor; validate network/type and show derived addresses for verification.

Migration / Backwards compatibility

• Existing single-sig wallets remain unchanged.
• Clear migration steps if converting from single-sig to multisig (likely not automatic — create new multisig wallet and move funds).

Testing

• Unit tests for descriptor parsing, address derivation, PSBT creation/sign/merge/finalize.
• Integration tests including simulated cosigner flows and hardware signing (mocked for Ledger, Trezor, Coldcard).
• End-to-end manual test doc for QA.

Docs & examples

• Add a new multisig user guide covering creation, backup, signing (including hardware), and recovery.
• Provide example PSBT exchange steps (QR, file).

Suggested labels

• enhancement
• multisig
• feature
• needs-design (if UX work remains)
• priority:medium or priority:high (choose)

Suggested checklist to include in the issue

• Design/UX mockups for create/send/sign flows
• Implementation plan (data model + PSBT module)
• Hardware wallet compatibility checks (Ledger, Trezor, Coldcard)
• Unit tests
• Integration tests
• Documentation and user guide

Suggested follow-ups / break-down (possible sub-issues)

• Design and UX for multisig flows
• Descriptor/xpub import validation module
• PSBT handling module (create/sign/merge/finalize)
• Hardware wallet signing adapters (Ledger, Trezor, Coldcard)
• Testing + QA plan
• Documentation / user guide