Skip to content

[security] Verify nested single sig change that omits its redeem script - #1046

Merged
newtonick merged 3 commits into
SeedSigner:devfrom
kdmukai:2026_09_psbt_nested_singlesig_change
Oct 3, 2026
Merged

newtonick merged 3 commits into
SeedSigner:devfrom
kdmukai:2026_09_psbt_nested_singlesig_change

Conversation

@kdmukai

@kdmukai kdmukai commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Human-friendly overview:

The Problem

A nested single sig (p2sh-p2wpkh) output can omit its redeem script (it's optional per BIP-174). Such outputs are interpreted as plain p2sh and so they fail the initial possible change check (p2sh fails to match p2sh-p2wpkh). That creates two undesirable possible outcomes:

  • The user's own change would be displayed as an external spend.
    • Note: BlueWallet produces such psbts.
  • A specific type of deceptive claim that we could have detected is not inspected and is allowed to pass as an external spend.
    • I don't think there's a clear reason to structure an attack this way, but it would require:
      • The output's bip32_derivations specify a key that the user's seed does actually own, making it look like it really is their own change.
      • But the redeem script is omitted and the output's actual scriptPubKey is a p2sh-p2wpkh hash that pays to an attacker's key.

The Solution

Allow nested single sig outputs to be considered possible change when the redeem script is omitted. Those outputs will then be subject to our deeper validity checks.

The vital insight here is that the redeem script for nested single sig is trivially reproducible. Even when the psbt supplies it, we ignore it during our change verification and just regenerate it ourselves. And once we rebuild the redeem script, we can use it to produce what the scriptPubKey would be if the output is our change and see if it matches the scriptPubKey in the psbt.

If it matches, the output is our change. If it doesn't match while the output claims our seed, that claim is deceptive and the psbt is refused.

But if there is no deceptive claim and the scriptPubKey doesn't match, the output simply is not our change.


More precise description below by Claude, primarily intended to be consumed by other AIs

Mechanism

_get_policy types an output from what that output supplies. A p2sh-p2wpkh output's scriptPubKey
is a bare p2sh hash, so the redeem script is the only field separating it from plain p2sh. Drop it
and the output's policy is {type: p2sh}, which does not match the wallet's p2sh-p2wpkh policy.

Nested single sig is the only script type where this can happen, because it is the only one whose
identity depends on a field its proof never reads. The proof rebuilds p2sh(p2wpkh(K)) from
our own seed at the claimed path and from the inputs' policy, so the omitted field is a
discriminator rather than evidence. For p2sh-p2wsh the discriminator and the proof material are
the same field, so its absence is genuine silence and correctly out of reach. For p2wpkh, p2pkh,
and p2tr the scriptPubKey announces the type on its own.


Implementation

_policy_shape_matches becomes _is_change_candidate, an instance method, since it now reads the
inputs' policy and the output's redeem script alongside the output's own policy.

In addition to the unchanged shape comparison it admits an output on all three of:

self.policy["type"] == "p2sh-p2wpkh"    # Input is nested single sig
and out_policy["type"] == "p2sh"        # Output parses as plain p2sh
and out.redeem_script is None           # Output omits its redeem script

The admission does not look at the output's derivation path entries. The rebuild derives our key
at the entry's path whatever fingerprint it lists, and the rebuild decides. Everything below the
candidacy test is unchanged.

Two files change: src/seedsigner/models/psbt_parser.py and tests/test_psbt_parser.py. The
first commit message states the mechanism in prose. The second supersedes it on which conditions
the admission checks, and says why each dropped condition went.

Links below are pinned to this PR's head commit, so they stay correct as the branch moves.

Read for Source
The three clauses, each with its rationale as a trailing comment _is_change_candidate, L733-739
Why the candidacy test exists at all and what it does not decide that method's docstring, L712-732
The trust model this rests on parse's process docstring, L225-283
The verdict table: when an output is change, a spend, or refused _parse_outputs's docstring, L363-393
Where an admitted output is proved or refused, single sig arm _parse_outputs, L443-458
p2sh(p2wpkh(K)) construction _build_singlesig_script, L748-768
The contradiction refusal this change makes reachable, with the taproot exemption _parse_outputs, L588-608
Honest change counted as change test, L2065
Repointed output refused test, L2089
Output paying this seed under another seed's key refused test, L2108
Each condition pinned by a payment to another wallet of this seed test, L2134

Which coordinators emit this

The opening names BlueWallet. Source-level survey, repos read at HEAD 2026-09-24, asking one
question: does the coordinator write PSBT_OUT_REDEEM_SCRIPT on a p2sh-p2wpkh change output?

Coordinator Writes it Where
BlueWallet (BIP 49) No abstract-hd-electrum-wallet.ts, createTransaction
Bitcoin Core Yes FromSignatureData, from ProduceSignature's sigdata
Specter Desktop Yes drives Core's engine
Nunchuk Yes drives Core's engine
Sparrow Yes drongo's PSBT constructor, for WalletNodeOutput change
Electrum Yes add_output_info sets script_descriptor, whose setter fills redeem_script

BlueWallet's HDsegwitP2SHWallet is segwitType: "p2sh(p2wpkh)" at m/49'/0'/0'. It extends
AbstractHDElectrumWallet and overrides _addPsbtInput() but not createTransaction(), so its
change output takes the inherited path, which passes bip32Derivation and no redeemScript.

Two limits on that survey. Bitcoin Keeper's single-sig vault change output has the same shape
(addOutput({ ...output, bip32Derivation }), no redeem script), but this survey did not establish
whether those vaults are p2sh-p2wpkh rather than native segwit or taproot, so it is not counted;
its non-vault wallets annotate no output at all, which puts them outside this entirely. Zeus and
Caravan were not reached; Caravan is legacy multisig only in any case. This is a read of source,
not a capture of real psbts.


Design Consideration

Why the admission is narrow

Each condition keeps a payment to another wallet of this seed, annotated with our key, a spend.
Measured by removing that one condition:

  • Nested single sig inputs. Without it, a native segwit wallet paying this seed's own nested
    address is refused as a contradiction, and the suite's honest multisig fixtures fail too.
  • A bare p2sh output. Without it, a nested single sig wallet paying this seed's own native
    segwit address is refused as a contradiction.
  • An omitted redeem script keeps a legacy p2sh multisig, which supplies its redeem script, out
    of the rebuild. Without it, a payment into a legacy multisig this seed belongs to is refused.
    For an output parsed as plain p2sh this admits exactly what an m-of-n check would, since a
    supplied multisig redeem script is the only source of an m-of-n there (measured on the suite's
    three p2sh fixtures, with each of their scripts kept or omitted).

A separate source-level survey of which outputs coordinators annotate found one honest emitter of
an annotation paying another account of the same seed: a Bitcoin Core wallet holding more than
one of the seed's account descriptors, which a user assembles by hand.

The admission does not look at the entries. An output that pays our key while its entry lists
another seed's key and fingerprint reaches the rebuild and is refused, exactly as the same output
is when its redeem script is present. An output carrying more than one entry is refused by the
single sig surplus check before the rebuild runs.

Accepted: a bare p2sh output with several entries is refused

Under nested single sig inputs, a plain p2sh output that omits its redeem script and carries more
than one derivation path entry now ends on PSBTSurplusDerivationPathsView, a structural warning,
where it was previously shown as a spend. That is the shape of a multisig output annotated with
its keys but stripped of its scripts, or a payment annotated with several of a recipient's keys. No
surveyed coordinator emits either. The one that omits an output's redeem script, BlueWallet, does
so only on its own single sig change, which carries one entry. The output-annotation survey read
Sparrow, Bitcoin Core (and Specter, which drives it), Electrum, Nunchuk, Bitcoin Keeper,
BlueWallet, Zeus with its embedded LND, and Caravan at source; wallets outside that set were not
read, so this is a small false-refusal risk rather than none.

What this does not defend against

An output paying a script type this wallet never scans is still outside the change check, because
the type genuinely differs. Catching that would mean rebuilding the seed's key under every script
type.


Screenshots

No screen changes. The refusals reach the existing PSBTOutputOwnershipContradictionView and
PSBTSurplusDerivationPathsView.


Testing

Note that testqrs.com has been updated with this PR's test scenarios.

pytest passes at 273. Four new parser tests: the honest output, the repointed output, an output
that pays this seed but lists another seed's key and fingerprint, and one test with a step per
admission condition, each a payment to another wallet of this seed that stays a spend.

Before this change, measured on a nested single sig fixture with its redeem script removed: change
0, spend 10,000, with the user's own change address listed as the destination.

Mutation checks, full suite each time:

Mutation Result
Remove the new p2sh case from _is_change_candidate The three single-output tests fail
Drop the nested single sig inputs condition The other-wallets test fails at its inputs step, and three multisig fixture tests fail
Drop the bare p2sh output condition The other-wallets test fails at its output type step
Drop the redeem script condition The other-wallets test fails at its redeem script step
Also require the entry to claim this seed's fingerprint The lists-another-key test fails
Also require exactly one derivation path entry Suite passes; the refusal a multi-entry output reaches is covered by the existing single-key surplus test, on a native segwit output

Other Notes

  • The cross-reference in parse's process docstring follows the rename.

This pull request is categorized as a:

  • Other: Security hardening

Checklist

I ran pytest locally

  • All tests passed before submitting the PR

I included screenshots of any new or modified screens

Should be part of the PR description above.

  • N/A

I added or updated tests

Any new or altered functionality should be covered in a unit test. Any new or updated sequences require FlowTests.

  • Yes

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


I have reviewed these notes:

  • Keep your changes limited in scope.
  • If you uncover other issues or improvements along the way, ideally submit those as a separate PR.
  • The more complicated the PR, the harder it is to review, test, and merge.
  • We appreciate your efforts, but we're a small team of volunteers so PR review can be a very slow process.
  • Please only "@" mention a contributor if their input is truly needed to enable further progress.
  • I understand

Thank you! Please join our Devs' Telegram group to get more involved.

@kdmukai kdmukai moved this to 0.8.8 Needs Review in @SeedSigner Development Board Sep 24, 2026
@kdmukai
kdmukai force-pushed the 2026_09_psbt_nested_singlesig_change branch 2 times, most recently from eb3091c to 81ae37a Compare September 25, 2026 19:27
@kdmukai
kdmukai marked this pull request as ready for review September 26, 2026 20:49
@newtonick newtonick added this to the 0.8.8 milestone Sep 28, 2026
Comment thread src/seedsigner/models/psbt_parser.py Outdated
"""
# The outlier: a single sig p2sh output when the inputs are p2sh-p2wpkh.
if (
self.policy["type"] == "p2sh-p2wpkh" # Input policy criteria

@newtonick newtonick Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion for a future PR: rename self.policy to self.input_policy to make it less ambiguous.

Comment thread src/seedsigner/models/psbt_parser.py Outdated
Comment on lines +717 to +719
Note: A multisig's input or output policy can also include the cosigners if
they're supplied in the global xpubs. But this function does not take the
cosigners into account; cosigner information, if provided, is evaluated later.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some good information in the previous doc string about WHY the global xpubs are not used here is lost. Might be worth adding back this part:

Those are never authoritative here, and comparing them would let a psbt decide which of its own outputs get verified.

"Those" referring to global xpubs. So something like:

But this function does not take the cosigners into account; cosigner information, if provided, is evaluated later. Comparing global xpubs here would let a psbt decide which of its own outputs get verified: one misannotated fingerprint makes that output's cosigners fail to resolve, the output stops matching the inputs' policy, and it skips the ownership check entirely.

Would bring back this useful context.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a modified version of your suggested text in f5cbc18.

See the commit message; there's a subtle correction after PR #1032.

@newtonick

newtonick commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

I was just about to make a comment related to the changes you just made in 5bb2947 but you changed the very thing I was going to suggest :-D

@Chaitanya-Keyal Chaitanya-Keyal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK at 5bb2947.

Could you rebase onto dev? #1044 has merged, but the PR is still diffing against the old base, so it shows its 4 commits and +363/-161 when only the last 2 commits (+138/-14) are new.

@newtonick

Copy link
Copy Markdown
Collaborator

ACK and reviewed 5bb2947

A p2sh-p2wpkh output's scriptPubKey is a bare p2sh hash. BIP-174 leaves the
redeem script optional on an output, and without it _get_policy types the output
as plain p2sh, which does not match a p2sh-p2wpkh wallet policy. The output then
never reaches the ownership check at all. Two things follow. The user's own
change is displayed as a payment out to a stranger. And an output that keeps a
genuine claim on this seed while repointing its scriptPubKey escapes the
ownership-contradiction refusal by dropping one optional field.

Nested single sig is the only script type whose identity depends on an optional
field its proof does not read: the rebuild is p2sh(p2wpkh(K)) from our own seed
at the claimed path and the inputs' policy, so the missing field is a
discriminator rather than evidence. For p2sh-p2wsh the discriminator and the
proof material are the same field, so its absence is genuine silence and
correctly out of reach.

_policy_shape_matches becomes _is_change_candidate, an instance method, since it
now reads the inputs' policy and the output's verified derivation paths. Beside
the unchanged shape comparison it admits a bare p2sh output under a p2sh-p2wpkh
wallet that carries no m-of-n, supplies exactly one derivation path entry, and
holds one verified claim on this seed. Everything below is unchanged: the
rebuild decides, honest change is counted as change, and a repointed output
raises PSBTOutputOwnershipContradictionError.

The single-entry conditions are what keep that refusal safe. A genuine multisig
output carries one derivation path entry per cosigner, so it never reaches the
contradiction check by this route. The shape that would is a bare p2sh output
withholding both scripts while annotating a single key of a multisig, and no
surveyed coordinator emits one. Every coordinator but Bitcoin Core annotates
only its own change output. Core annotates an output because a descriptor solved
its script, so it holds all n key origins and writes them.
The nested single sig outlier in change candidacy also required the
output's one derivation path entry to claim this seed's fingerprint.
That kept an output paying our key under another seed's key and
fingerprint out of the rebuild, so it was shown as a spend to the
user's own address, while the same output with its redeem script
present is refused as a contradiction. The rebuild derives our key at
the entry's path whatever fingerprint it lists, so the outlier drops
the condition and _is_change_candidate drops the verified derivation
paths it read for it.

The outlier also required exactly one derivation path entry. It only
kept out bare p2sh outputs annotated with several keys while omitting
their scripts, which no surveyed coordinator emits, and the single sig
surplus check now refuses those.

The m-of-n exclusion becomes a check that the output omits its redeem
script. For an output parsed as plain p2sh the two admit the same
outputs, since a supplied multisig redeem script is the only source of
an m-of-n there, and the new check states what the outlier is for.

New tests refuse an output that pays this seed but lists another key,
and pin each of the three remaining conditions: a payment to another
wallet of this seed, annotated with our key, stays a spend.
@kdmukai
kdmukai force-pushed the 2026_09_psbt_nested_singlesig_change branch from 5bb2947 to f04675e Compare September 29, 2026 17:06
@kdmukai

kdmukai commented Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

@Chaitanya-Keyal: PR rebased!

Renaming _policy_shape_matches to _is_change_candidate dropped the
reason the candidacy test compares shape alone. Without it, adding the
cosigners to the comparison reads as a harmless tightening.

The old wording named a misannotated fingerprint as what breaks an
output's cosigner resolution. Since SeedSigner#1032, _get_cosigners matches each
key to a global xpub by derivation path alone and never reads the
fingerprint, so the restored note names a misannotated derivation path
instead.
@kdmukai

kdmukai commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Tested f5cbc18 on device via testqrs.com and verified all expected behavior.

@newtonick

Copy link
Copy Markdown
Collaborator

ACK f5cbc18

@newtonick
newtonick merged commit b2199c6 into SeedSigner:dev Oct 3, 2026
2 checks passed
@jdlcdl

jdlcdl commented Nov 5, 2026

Copy link
Copy Markdown

Regarding proposed embit pr152

I have tested seedsigner as of Nov 1 (last merge pr1047), using pr152 atop embit 0.8.2, instead of embit 0.8.0.

All tests for this pr at testqrs dot com still behave exactly as expected.

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

Labels

None yet

Projects

Status: 0.8.8 Merged

Development

Successfully merging this pull request may close these issues.

4 participants