Skip to content

Clarify psbt_parser.py docstrings and comments; minor cleanup - #1027

Merged
newtonick merged 2 commits into
SeedSigner:devfrom
kdmukai:psbt_parser_docstrings
Sep 4, 2026
Merged

newtonick merged 2 commits into
SeedSigner:devfrom
kdmukai:psbt_parser_docstrings

Conversation

@kdmukai

@kdmukai kdmukai commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Clarification and cleanup after #1013 and before the next planned PR in the sequence.

Some docstrings were unnecessarily over-explaining or re-explaining things that were covered elsewhere.

Other comments were rewritten to be easier to understand and/or trim unnecessary terminology.

No behavior changes.

Summary by Claude:


Docstrings and comments

  • Ownership-claim exceptions. PSBTOutputOwnershipClaimError and PSBTInputOwnershipClaimError each now state the condition they signal. Both drop prose speculating about how that condition arises in practice; the concrete cases already have tests with real fixtures, including a brute-forced colliding fingerprint pair.
  • _get_seed_derivation_path. Drops a restatement of the output-versus-input severity split. _verify_claimed_derivation_paths already gives it, in the function that orders the two and therefore owns that policy.
  • verified_input_derivation_paths / verified_output_derivation_paths. The comment says what an entry holds. It no longer explains the None case, which the positive statement already implies.
  • parse() steps 1 and 2. Step 1 said "scopes the seed provably derives", but the check is per key, so it now says so. Step 2 drops a redundant "scope" and states the raise more directly.
  • _parse_inputs. Gains a docstring. It was undocumented, and the fact that it raises RuntimeError unless every input resolves to the same policy was recorded only in parse()'s summary.
  • Single-sig branch comment. Names the three script types it covers, and notes that taproot is handled separately below.

Naming

  • _parse_multisig. The sc parameter becomes multisig_script, matching what both call sites already name it. Module-local, not part of any public signature.
  • _get_policy. A TODO marking its local script variable, which shadows the script module imported at the top of the file. It is harmless today only because nothing after that line needs the module. Left as a marker rather than renamed, since there is other in-flight work in this function and a one-line note survives a rebase more reliably than a rename.

This pull request is categorized as a:

  • Documentation

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.

  • N/A

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

  • N/A

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.

No behavior change. Corrects prose that had drifted from what the code
does, and addresses two local names for the same reason.

Docstrings and comments:
- The two ownership-claim exceptions state the condition each signals,
  without speculating about how it arises.
- _get_seed_derivation_path drops the output-versus-input severity
  split, which _verify_claimed_derivation_paths already states.
- The verified_*_derivation_paths comment says what an entry holds, and
  no longer explains the None the positive statement already implies.
- parse() steps 1 and 2 name the per-key condition instead of "scopes".
- _parse_inputs gains a docstring covering the amount total and the
  one-shared-policy requirement.
- The single-sig branch comment names the script types it covers.

Naming:
- _parse_multisig's `sc` parameter becomes `multisig_script`.
- A TODO marks _get_policy's local `script`, which shadows the embit
  module imported at the top of the file.

@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. Verified this is comments and one param rename only, and the comments look good.

"An output scope claims..." reads no better than "An output claims...".
The word is doing no work in a sentence about what the output says, and
the psbt-scope sense it borrows is not the one the reader needs there.
@kdmukai

kdmukai commented Aug 30, 2026

Copy link
Copy Markdown
Contributor Author

Two more trivial edits in 8574c13

@jdlcdl

jdlcdl commented Sep 2, 2026 •

Copy link
Copy Markdown

ACK. I too have read this as no functional changes; comment improvements and a better varname for an internal method.

@newtonick

Copy link
Copy Markdown
Collaborator

ACK

@newtonick
newtonick merged commit 85cd9a0 into SeedSigner:dev Sep 4, 2026
2 checks passed
@Chaitanya-Keyal Chaitanya-Keyal moved this from 0.8.8 Needs Review to 0.8.8 Merged in @SeedSigner Development Board Sep 4, 2026
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