Skip to content

PSBT flow: fix signer routing and change detection - #451

Open
kkdao wants to merge 10 commits into
3rdIteration:devfrom
kkdao:fix/psbt-review-paths
Open

kkdao wants to merge 10 commits into
3rdIteration:devfrom
kkdao:fix/psbt-review-paths

Conversation

@kkdao

@kkdao kkdao commented Sep 20, 2026 •

Copy link
Copy Markdown

Description

Problem or Issue being addressed

Signer routing and change detection in the PSBT flow, rebased onto the B13 release:

  1. The card flow read the first input's account path, not the one the card holds.
  2. "Retry (higher timeout)" raised the timeout from the setting, not from the one that expired.
  3. A parser rebuild dropped the card's key data, and the overview's shortcut for a dropped card parser treated every card as a multisig, so a single-sig card was parsed with no key and raised; storing a seed did not always leave card mode; flow state was reset in several places, not one.
  4. Change was labelled without checking our key can spend it, and without binding it to this seed's own derivation.
  5. For rootless (card) multisig, a loaded descriptor that identified nothing could not be replaced without abandoning the transaction, swapping descriptors crashed change details, and the change screen showed the first path listed rather than the one the descriptor matched.
  6. The card's parsers, single-sig and multisig, were built without the clock, so locktime warnings never fired.

Solution

Ten commits, one per item above (git log has the details). Every parser is now built through one function, with the network, the loaded descriptor and the clock.

B13 already requires a known descriptor before a rootless multisig output counts as change, so that half of item 5 was dropped in the rebase, and B13 stores verified derivation paths as lists, which "bind change to this seed's own derivation" and "show the change path the descriptor matched" now read. Part of "label change only when our key can spend it" was dropped in an earlier rebase: #453's ownership scan already covers seeded m-of-n membership.

Additional Information

Not changed: CHANGE_INDEX_TOO_FAR cannot fire in the rootless card multisig flow, because no input indices are verified there.

Screenshots

N/A, no new screens.


This pull request is categorized as a:

  • New feature
  • Bug fix
  • Code refactor
  • Documentation
  • Other

Checklist

I ran pytest locally

  • All tests passed before submitting the PR
  • I couldn't run the tests
  • N/A

Local full suite: 2,410 passed, 435 skipped, 0 failed. Fork CI has not started for this revision, so CI remains unverified. Upstream CI is pending the PR branch update.

I included screenshots of any new or modified screens

  • Yes
  • No
  • N/A

I added or updated tests

  • Yes
  • No, I'm a fool
  • N/A

I tested this PR hands-on on the following platform(s):

  • Raspberry Pi OS
  • SeedSigner OS on a Pi0/Pi0W board
  • Emulator

Unit and flow tests only, on mocked cards: no Keycard is available here, and the Satochip paths changed are routing and parser construction.

I have reviewed these notes:

  • I understand

@kkdao
kkdao marked this pull request as draft September 21, 2026 17:29
@kkdao
kkdao force-pushed the fix/psbt-review-paths branch from 0d8d0ed to ffab106 Compare September 22, 2026 09:19
@kkdao
kkdao marked this pull request as ready for review September 22, 2026 09:20
@kkdao
kkdao force-pushed the fix/psbt-review-paths branch from ffab106 to 93390e1 Compare September 25, 2026 21:08
kkdao added 10 commits October 16, 2026 08:46
The card flow took the account path from the first bip32 derivation of
input 0. An input can legitimately carry no ECDSA derivation -- a
taproot input, or one another wallet has already signed -- and
next(iter({}.values())) then raised a bare StopIteration, which reaches
the user as a crash rather than as a refusal.

The first input that does carry one is not the answer either. A psbt
may spend from several wallets, and another signer's path exports an
account this card has no part in, which then rejects the input it could
have signed. Ask the card for its master fingerprint first and read the
account only from derivations naming it. No input naming that
fingerprint means the card is not a signer here, which is a refusal,
not a fallback.

A zero fingerprint is still read when nothing names the card. A
coordinator given only an xpub writes 00000000 for the master it was
never told, and the parser already backfills it wherever the card's key
derives the input; skipping it refused a psbt the card can sign.
"Retry (higher timeout)" computed the new timeout from the configured
setting rather than from the timeout that had just expired, so every
retry landed on the same value and pressing it twice changed nothing.
The screen quoted the setting too, naming a timeout the user had
already moved past. And the raised value was cleared only when signing
produced no signatures, so a successful sign left it on the controller
for the next PSBT to inherit.

Track the used timeout, raise from it, quote it, and clear it whenever
the flow ends.
PSBTOverviewView rebuilds the PSBTParser whenever the parser does not
match psbt_seed, passing seed=psbt_seed. In the card flow that is None
-- the card holds the key, not a seed -- so the rebuilt parser had no
root to derive with: the review screens showed a transaction with no
inputs, outputs or fee, and the flow failed further along. Loading a
multisig descriptor is the ordinary way to reach that rebuild.

Remember what the card's parser was built from and reuse it. The
multisig card branch builds its parser with no key material on purpose,
a multisig being reviewed against its descriptor rather than against
one cosigner's xpub, so it records an empty dict and a rebuild
reproduces that parser. Only an unset record -- a card flow whose key
data is gone -- is refused, with a reason, instead of parsing blind.

A parser built without key material does not parse on construction, so
the rebuild has to finish the job. Unparsed it reports no inputs, no
outputs and no fee, which is the same empty review by another route.

That rebuild covers the card's multisig too, which the overview had a
shortcut for: a dropped parser in any card flow was rebuilt seedless,
as if every card signed a multisig. A single-sig card reaching it had
its psbt parsed with no key, which raises rather than refuses. The
shortcut goes, and both card flows rebuild from what they recorded.
Choosing "sign with card" sets psbt_sign_with_satochip, and nothing
cleared it. Going BACK from the card flow and selecting a seed set
psbt_seed but left the flag standing, so finalizing still routed to the
card -- signing with a key the user had just navigated away from, or
failing outright when no card was present.

Every view that picks a signer stores it in psbt_seed: the stored-seed
list, a scanned or typed seed, WIF and BIP38 keys and a Satodime slot
among them. Clearing the flag in each of those views is a line the
next one added will miss, so it is cleared where the seed lands, in the
psbt_seed setter. Clearing the seed is not choosing one: the card flow
sets psbt_seed to None on its way in and keeps its own state.

The screenshot generator patched psbt_seed with patch.object. Where
the instance holds no value of its own, patch.object undoes itself by
deleting the attribute, and a property with no deleter refuses: the
generator failed at its first psbt screen. It patches the field behind
the property instead.
The parser proves a script-hash output is ours only for an m-of-n,
by finding our key among its cosigners. A wallet whose script is
anything else still reached that proof: its policy records the type
alone, so any two such policies matched whatever their scripts said.
The parse then crashed, rebuilding a scriptPubKey from a missing
witness script or parsing a non-multisig script as an m-of-n, and a
WIF signer took the output as change.

Finding our key's bytes in the script would not settle it, because a
key can sit in a script that cannot spend with it:

    <our key> OP_DROP <their key> OP_CHECKSIG

pushes our key only to throw it away. So a script-hash policy with no
m-of-n matches nothing, and the output is a payment.

WIF and BIP38 signing has no tree to derive from, but it does hold one
key, and that key either is a cosigner of the script or is not. Taking
every multisig of the right shape as change hid an attacker's payment
behind the change screen. Only a parser with no key material at all,
the card's seedless pre-parse, has nothing to test with.
Change binding measured every derivation on the output, cosigners'
included, against the account prefixes gathered from the inputs. Those
prefixes only ever come from keys this seed owns, so a cosigner's path
could never match one: a multisig whose members keep the wallet at
different account indices -- m/48h/0h/0h/2h here, m/48h/0h/1h/2h there,
routine across vendors -- had its change refused as outside the wallet,
and the psbt could not be signed at all.

Measure the path this seed was verified to own against the inputs, and
hold every other path on the output to ours on the last two levels. A
cosigner's account index says nothing about whether our wallet finds
our change, but the branch and index do: a multisig address is built
from all the cosigners at once, so one moved to 1/9999 while we sit at
1/0 gives an address no member's change scan will ever generate. The
spliced and off-branch paths the check exists for are refused as
before.
Start-up, Home and the inactivity wipe each cleared their own subset of
the psbt signing flow's leftovers, so anything added later reached only
some of them. Two things were reaching none: the card's account xpub,
and the raised value behind "Retry (higher timeout)". Pressing Home
after a card flow left both standing: the xpub of a card the user had
walked away from stayed in memory past Home and the wipe, and the next
psbt timed out on a value another transaction had set.

Put the list in one method and call it from all three. A refusal keeps
the psbt so another signer can be chosen, and clears both by hand. BACK
from the approval screen keeps the review, and the card key data a
rebuild of that review needs, so it clears only the raised timeout.
With no BIP32 tree to derive from (the card's multisig flow, WIF or
BIP38 signing), only the descriptor the user loaded can identify a
multisig output as change. Loading the wrong one is the ordinary way
to reach the screen that says it identifies nothing, and that screen
offered only "Continue": the right descriptor could not be loaded
without abandoning the transaction. Offer to load one there too.

Swapping in a descriptor that does not own the output empties the
change list while change details is still being asked for change 0.
Report that as the mismatch it is, rather than crash on the missing
entry.
With no BIP32 tree to derive from, the change screen took its path
from the first derivation the psbt lists on the output. The descriptor
that admits the output skips every entry whose fingerprint names none
of its keys, so an entry listed first for a key it never checked chose
the title, path and index the user saw: "Your Change" at 1/0, while the
funds went to receive index 50000.

Show the path the descriptor matched, and hold the output to what a
seeded parse asks once it finds our key there: no more entries than
the script has keys, and every entry on that path's branch and index.
A psbt loaded from microSD is dated by its file, and the review uses
that date to flag a locktime years in the future. The card's parsers,
single-sig and multisig, are built in the signer menu and the overview
keeps them, and they were built there without the clock. A lock nearly
three years out that the seed flow warned about reached the approval
screen unmentioned when a card signed the same psbt.

Build every parser through one function that takes the network, the
loaded descriptor and the clock from the controller and the settings,
so the signer menu and the overview cannot pass different lists again.
@kkdao
kkdao force-pushed the fix/psbt-review-paths branch from 93390e1 to f13c7da Compare October 16, 2026 07:34

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant