Skip to content

feat: make mnemonic loading format-first - #922

Draft
Naman015 wants to merge 9 commits into
selfcustody:developfrom
Naman015:feat/format-first-mnemonic-loading
Draft

feat: make mnemonic loading format-first#922
Naman015 wants to merge 9 commits into
selfcustody:developfrom
Naman015:feat/format-first-mnemonic-loading

Conversation

@Naman015

@Naman015 Naman015 commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

What is this PR for?

Load Mnemonic currently asks users to choose between camera, manual input, and storage before choosing the backup they recognise. This PR proposes a format-first start instead:

  1. QR Code
  2. Words
  3. From Storage
  4. Other Formats
  5. Back

Other Formats is one flat menu containing Tinyseed, Tinyseed (Bits), OneKey KeyTag, Binary Grid, Word Numbers, Stackbit 1248, and Back.

The intent is to remove one translation step from the common recovery paths without changing any decoder, validation, storage, keypad, or cryptographic behaviour. The same shared loader is used by Login and Mnemonic XOR.

Design reference: Direction 3: format-first mnemonic recovery

The common routes become shorter, while specialist formats move one level deeper:

Format Current actions Proposed actions
QR Code 2 1
Words 3 2
From Storage 3 3
Tinyseed 3 5
Tinyseed (Bits) 5 6
OneKey KeyTag 4 7
Binary Grid 5 8
Word Numbers 4 9
Stackbit 1248 6 10

The action count starts on the initially focused row and includes every navigation and Enter action.

Changes made to:

  • Code
  • Tests
  • Docs
  • CHANGELOG

Did you build the code and tested on device?

  • Yes, build and tested on TZT

Simulator acceptance completed on TZT, M5StickV, and Amigo. All 11 translation files were checked against M5StickV’s 135-pixel wrapping behaviour. Simulator captures cover every wrapping locale: es-MX, ko-KR, pt-BR, and tr-TR. All wraps are clean, with no clipping or overlap, and every menu item plus Back remains visible. Physical TZT testing confirmed QR Code, Words, From Storage, both Back levels, and button and touch navigation.

What is the purpose of this pull request?

  • Bug fix
  • New feature
  • Docs update
  • Other

Verification

  • 67 focused Login, Mnemonic XOR, and loader tests
  • 1,125 full-suite tests passed, with one expected failure and 97% coverage
  • Black formatting
  • Pylint 10.00/10
  • translation validation
  • Vulture

@codecov

codecov Bot commented Aug 8, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.47%. Comparing base (be5eda2) to head (53d96d8).
⚠️ Report is 5 commits behind head on develop.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #922      +/-   ##
===========================================
+ Coverage    97.42%   97.47%   +0.05%     
===========================================
  Files           83       84       +1     
  Lines        10880    10952      +72     
===========================================
+ Hits         10600    10676      +76     
+ Misses         280      276       -4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@qlrd

qlrd commented Aug 9, 2026

Copy link
Copy Markdown
Member

cACK. A doubt: the translation stress occured only in pt-BR and es-MX?

@Naman015
Naman015 force-pushed the feat/format-first-mnemonic-loading branch from 792ce93 to a34aa49 Compare August 9, 2026 10:22
@Naman015

Naman015 commented Aug 9, 2026

Copy link
Copy Markdown
Contributor Author

the translation stress occured only in pt-BR and es-MX?

I checked all 11 translations on M5StickV. Wrapping occurs in es-MX, ko-KR, pt-BR, and tr-TR. es-MX wraps From Storage, Binary Grid, and Word Numbers; ko-KR wraps From Storage; pt-BR and tr-TR wrap Word Numbers. They all fit cleanly with Back still visible. TZT and Amigo don't wrap. Thanks for pointing it, I updated the PR body now.

I also missed that Other Formats was still hard-coded in English, so I fixed that and refreshed the M5StickV captures.

@qlrd qlrd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

First round docs nits (no blockable):

Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/navigating-the-main-menu.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
Comment thread docs/getting-started/usage/loading-a-mnemonic.en.md Outdated
@Naman015

Copy link
Copy Markdown
Contributor Author

First round docs nits (no blockable):

Thank you, fixed the weird wrapping and punctuation nits in docs.

@qlrd qlrd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

overall LGTM. Tested with:

gh pr checkout 922
git submodule update --recursive
uv sync --frozen --reinstall-package=uUR
uv run poe pre-commit
./krux build-release
./build/ktool-linux -B {goE,dan}-b 1500000 ./krux-v28.06.0/maixpy_{amigo,wonder_mv}/kboot.kfpkg

so i would give a tACK 993acc6 with some minor nits (non-blockable, maybe worth of discussion)

Comment thread src/krux/pages/mnemonic_loader.py Outdated
@Naman015
Naman015 force-pushed the feat/format-first-mnemonic-loading branch from aac0b89 to 0940677 Compare August 18, 2026 03:55
@odudex

odudex commented Aug 18, 2026

Copy link
Copy Markdown
Member

tACK - tested on TZT

I like the rearrangement. Would only change 2 things:

  • To differentiate manual input from scans, add "scan" term on respective items of "Other Formats". "Scan Tinyseed", "Scan OneKey". Or "Tinyseed (scan)".
  • Take the opportunity to rename "Tinyseed (Bits)" to a more generic "Binary Grid", or even "Binary Grid (manual)"

@Naman015

Copy link
Copy Markdown
Contributor Author

tACK - tested on TZT

I like the rearrangement. Would only change 2 things:

  • To differentiate manual input from scans, add "scan" term on respective items of "Other Formats". "Scan Tinyseed", "Scan OneKey". Or "Tinyseed (scan)".
  • Take the opportunity to rename "Tinyseed (Bits)" to a more generic "Binary Grid", or even "Binary Grid (manual)"

Thanks for testing. Agreed, Binary Grid (manual/scan) makes more sense to me here and also keeps the name generic.

I’ve pushed the new labels:

  • Tinyseed (scan)
  • Binary Grid (manual)
  • OneKey KeyTag (scan)
  • Binary Grid (scan)

The translations, tests, docs and screenshots are updated too.

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.

3 participants