# Compatibility Roadmap: Multisig and TrustedCoin (2FA) Wallets

Status document, 2026-07-19. Companion to [`COMPATIBILITY.md`](COMPATIBILITY.md):
that file states *what* is supported today; this one explains *why* multisig and
TrustedCoin (2FA) wallets are currently unsupported and *how* support can be
added.

## Root cause (common to both)

BAL currently does two things that are only valid for standard
(single-signature) wallets:

1. **It builds transactions itself** with `PartialTransaction.from_io(...)`
   (`bal/core/will.py`), bypassing `wallet.make_unsigned_transaction`.
2. **It signs with a single call** — `wallet.sign_transaction(tx, password)`
   (`bal/gui/qt/window.py`, `sign_transactions`) — and considers the will ready
   when `tx.is_complete()` is true.

On a standard wallet one signature completes the transaction. On multisig and
2FA wallets **one signature is not enough**: the transaction stays incomplete,
is never marked `COMPLETE`, and can never be pushed to will-executors.

A secondary single-sig assumption: `plugin.py` uses `wallet.get_keystore()`
(singular); multisig wallets expose `get_keystores()` (plural).

## Multisig wallets — solvable, medium/large effort

A 2-of-3 multisig wallet typically holds **only one** of the required private
keys locally; the other cosigners hold theirs. `wallet.sign_transaction` adds
the local signature only, and BAL has no flow to collect the missing ones.

**Proposed solution: the standard PSBT coordination round** (the same flow
Electrum itself uses for multisig spending):

1. Build and sign locally as today.
2. If the transaction is not complete, **export the partially-signed
   transaction(s)** (file and/or QR) and mark the will with a new status such
   as `WAITING_COSIGNERS`.
3. Each cosigner signs in their own Electrum (native feature — no new
   software needed on their side).
4. BAL **re-imports and merges the signatures**; once complete, the will is
   pushed to will-executors as today.

Notes and caveats:

- **Chained will transactions** (a will tx spending the change of a previous
  will tx) remain workable: with segwit, the txid of an unsigned/partially
  signed transaction is already stable, so the whole chain can be exported as
  a batch of PSBTs in one round.
- **Every rebuild requires a new cosigner round.** Check Alive postponements
  and balance-change rebuilds re-sign the will, so each of them needs the
  cosigners again. This is inherent to multisig and must be clearly
  communicated in the UI.
- Implementation surface: export/import/merge pipeline, GUI for it, the new
  status in the transaction list, and tests.

Target: **next plugin release**, as announced.

## TrustedCoin (2FA) wallets — harder, with one blocking unknown

An Electrum 2FA wallet (`Wallet_2fa`, defined in Electrum's `trustedcoin`
plugin) is technically a **2-of-3 multisig whose second signer is the
TrustedCoin server**:

- signing requires a **one-time password (OTP) per transaction**
  (`server.sign(short_id, raw_tx, otp)`);
- the server co-signs only transactions that include **its billing fee**,
  which Electrum adds inside `Wallet_2fa.make_unsigned_transaction` — a code
  path BAL currently bypasses (see root cause #1).

So today: no billing output, no OTP prompt, local signature only → incomplete
transaction.

Even with full integration (building via the wallet's
`make_unsigned_transaction`, adding the OTP prompt flow), one **decisive
unknown** remains: will transactions carry a **locktime years in the future**.
Whether the TrustedCoin server agrees to co-sign a transaction with such a
far-future `nLockTime` is an undocumented server-side policy. If it refuses,
2FA support is **not achievable** without TrustedCoin's cooperation. This is
why `COMPATIBILITY.md` marks 2FA as *unknown*.

**Proposed plan:**

1. **Empirical test on testnet** (cheap, decisive): create a test 2FA wallet,
   build a far-future-locktime transaction through the proper 2FA path, and
   check whether the server signs it.
2. If it signs → implement support: build via `make_unsigned_transaction`
   (billing output included), integrate the OTP prompt, and document that
   every rebuild costs one OTP round and TrustedCoin fees.
3. If it refuses → document 2FA as unsupported, with the practical
   workaround: Electrum allows disabling 2FA by restoring the wallet from the
   full seed, which turns it into a standard wallet — fully supported by BAL.

## Recommended order of work

1. **Multisig first**: deterministic path, standard Electrum tooling, already
   announced for the next release.
2. **TrustedCoin empirical test in parallel**: low cost, and its outcome
   decides whether 2FA support is feasible at all.