feat: add Mnemonic XOR (SeedXOR) by qlrd · Pull Request #727 · selfcustody/krux

qlrd · 2025-09-21T13:23:55Z

What is this PR for?

This PR add an entry to Backup Mnemonics > Other formats menu as well add a new page class to src/krux/pages/seedxor_ui called SeedXOR. This class allow to choose between 2 up to 4 shares, add entropies from camera to the new shares as well show the mnemonic shares.

Close #384.

Changes made to:

Code
Tests
Docs
CHANGELOG

Did you build the code and tested on device?

Yes, build and tested on

What is the purpose of this pull request?

Bug fix
New feature
Docs update
Other

codecov · 2025-09-21T23:02:49Z

Codecov Report

❌ Patch coverage is 92.85714% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.06%. Comparing base (88aa221) to head (1aff195).
⚠️ Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/krux/pages/mnemonic_loader.py	90.90%	24 Missing ⚠️
src/krux/pages/home_pages/mnemonic_xor.py	98.68%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #727      +/-   ##
===========================================
+ Coverage    97.02%   97.06%   +0.03%     
===========================================
  Files           80       82       +2     
  Lines        10299    10395      +96     
===========================================
+ Hits          9993    10090      +97     
+ Misses         306      305       -1

☔ View full report in Codecov by Sentry.
📢 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.

jdlcdl · 2025-09-24T14:08:34Z

Played with this today, I like the flow. Used 3 XORed mnemonics to get to a my expected 4th, and was able to remove one or more to get back to a prior mix(es).

jdlcdl · 2025-10-01T15:03:21Z

I'm not sure I understand why MaixPy has changes. Please verify that this is intended, I suspect that this branch is pointing to an older MaixPy.

I like that there is a check for the result of another XOR not altering the mnemonic (as if someone used all 0x00s "abandon " * 11 + "about"). Shows error ValueError('XORed mnemonic didn't changed')

I'm wondering if it could also be useful (to avoid confusion and silly errors) to also check for:

does the result of another XOR produce all 0xFFs like "zoo " * 11 + "wrong", which would happen if someone inverted their mnemonic via that key.
does the result of another XOR produce all 0x00s like "abandon " * 11 + "about", which would happen if someone used the existing mnemonic.

Attentive users could notice that the new mnemonic is low entropy, but those with hide-mnemonic turned on couldn't.

Similarly, these 3 (or 4) checks could be done earlier, instead of waiting to see what the result of the xor will be, simply by using the arguments passed into xor and failing early.

Is either of the mnemonic entropies all 0x00 bytes (then this will result: "mnemonic unchanged")
is A == B (then this will result in 0x00 bytes: "low entropy mnemonic")
Is xor(A, 0xff bytes) == B (then this will result in all 0xff bytes: "low entropy mnemonic")
is either of the mnenonics all 0xff bytes (then inverted entropy is result: "mnemonic inverted").

I play with the following for testing:

qlrd · 2025-10-01T21:12:29Z

I'm not sure I understand why MaixPy has changes. Please verify that this is intended, I suspect that this branch is pointing to an older MaixPy.

I think was a mistake when pushing. Maybe forgot to make submodules stuff. I will check that

qlrd · 2025-10-02T11:48:01Z

Is either of the mnemonic entropies all 0x00 bytes (then this will result: "mnemonic unchanged")

is A == B (then this will result in 0x00 bytes: "low entropy mnemonic")

Is xor(A, 0xff bytes) == B (then this will result in all 0xff bytes: "low entropy mnemonic")

is either of the mnenonics all 0xff bytes (then inverted entropy is result: "mnemonic inverted").

Amazing observations. I will try that and update the PR.

This commit add test cases to be compliant with coldcard specification, mostly with 12w/24w with "parts" each (the result mnemonic was derived from another 3 mnemonics that are XORed).

This commit applies i18n for `Mnemonic XOR` menu entries as well messages and prompts.

This commit add a entry to docs in `docs/getting-started/features/mnemonic-xor.en.md` explaining why we choose `Mnemonic XOR` term instead `SeedXOR`, the overall algorithm's perspective and the usage on krux firmware.

qlrd · 2025-10-10T15:28:32Z

I play with the following for testing:

should we add on docs the test vectors showed by @jdlcdl (from CC docs)?

odudex · 2025-10-10T16:14:19Z

should we add on docs the test vectors showed by @jdlcdl (from CC docs)?

Test vectors that ensure compatibility are good to be added on tests. But I wouldn't use the same example on docs.

qlrd · 2025-10-10T17:28:04Z

should we add on docs the test vectors showed by @jdlcdl (from CC docs)?

Test vectors that ensure compatibility are good to be added on tests. But I wouldn't use the same example on docs.

All tests are made with CC mnemonic vectors (12 and 24 words)

qlrd · 2025-10-10T20:13:27Z

Tested live on device with test vectors

jdlcdl · 2025-10-11T09:07:41Z

Tested live on device with test vectors

I've tried as well this morning, on Amigo.

jdlcdl · 2025-10-11T09:57:43Z

@@ -0,0 +1,82 @@
+# What's the Mnemonic XOR?
+
+It's a implementation of [XOR logical gate](https://www.geeksforgeeks.org/digital-logic/xor-gate/) to operate, indefinitely, an [exclusive OR](https://en.wikipedia.org/wiki/Exclusive_or) upon a loaded mnemonic, based on [Coinkite's SeedXOR](https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md).


suggest:

Compatible with Coinkite's SeedXOR, this feature applies the binary-XOR operator between entropy bytes of your loaded mnemonic and another, resulting in -- and optionally loading, a new mnemonic which acquires an interesting lossless hiding attribute from the XOR operation.

jdlcdl · 2025-10-11T11:08:18Z

+
+# How it works
+
+To derive a new mnemonic (and thus, a new seed) from other mnemonics, an operation occurs with the **mnemonic's entropy bytes**.


suggest:

XOR is an operation that takes two independent 0 or 1 inputs, and results 1 if both are the same 0 if they are different.

Mnemonic XOR effectively masks your loaded mnemonic with another, resulting in a new mnemonic that can restore either of its input mnemonics by providing the other input mnemonic.

Using BIP39 entropy-bytes between two mnemonics, XOR is applied to each bit so that the result is the set of both entropy-bytes. This can be repeated with more unique mnemonics, indefinitely, and each of its input mnemonics can be restored from the result by providing all of the other input mnemonics. We can XOR mnemonic A with B, creating C, and then we can XOR mnemonic C with A to restore B -- or with B to restore A.

jdlcdl · 2025-10-11T11:49:06Z

+
+<img src="../../../img/mnemonic_xor.png" align="center">
+
+- We get two different mnemonics (A and B), extract their *entropy bytes*;


Using entropy bytes of two independent mnemonics A and B,

jdlcdl · 2025-10-11T11:49:56Z

+<img src="../../../img/mnemonic_xor.png" align="center">
+
+- We get two different mnemonics (A and B), extract their *entropy bytes*;
+- validate the input entropies to avoid useless or dangerous operations:


validation of each input mnemonic's entropy-bytes,

jdlcdl · 2025-10-11T11:51:08Z

+- validate the input entropies to avoid useless or dangerous operations:
+  - `A XOR B = A`: it will not change the XORed mnemonic;
+  - `A XOR B = A'` where `A'` is a "inverse" version of `A`;
+- once the inputs are checked, krux will apply a XOR between the *entropy bytes*;


apply binary XOR between the input mnemonics' entropy-bytes,

jdlcdl · 2025-10-11T11:51:54Z

+  - `A XOR B = A`: it will not change the XORed mnemonic;
+  - `A XOR B = A'` where `A'` is a "inverse" version of `A`;
+- once the inputs are checked, krux will apply a XOR between the *entropy bytes*;
+- validate the output entropy (same as above);


validate resulting output entropy bytes,

jdlcdl · 2025-10-11T11:53:56Z

+If `A XOR B = C`, then `B XOR C = A`.
+
+- **A**: Your original mnemonic (the secret to protect);
+- **B**: A newly generated, random mnemonic (Share 1);


B: Another backed-up, random mnemonic;

jdlcdl · 2025-10-11T11:54:15Z

+
+- **A**: Your original mnemonic (the secret to protect);
+- **B**: A newly generated, random mnemonic (Share 1);
+- **C**: The resulting mnemonic from the XOR operation (Share 2).


C: The resulting mnemonic from the XOR operation

odudex · 2025-10-11T13:40:10Z

Great work @qlrd ! Thank you!

qlrd force-pushed the feat/seedxor branch 2 times, most recently from 39cbcfd to 80224ef Compare September 21, 2025 22:58

qlrd changed the title ~~feat: add seedxor as option to backup mnemonics~~ feat: add Mnemonic XOR (SeedXOR) Sep 21, 2025

qlrd force-pushed the feat/seedxor branch 5 times, most recently from 518302c to 13be4fa Compare September 24, 2025 12:53

qlrd force-pushed the feat/seedxor branch 13 times, most recently from 769fc17 to 05b6742 Compare September 30, 2025 17:16

qlrd marked this pull request as ready for review September 30, 2025 17:30

qlrd force-pushed the feat/seedxor branch from 05b6742 to e98e59a Compare October 2, 2025 11:41

qlrd force-pushed the feat/seedxor branch from e98e59a to a6620d9 Compare October 2, 2025 13:48

qlrd marked this pull request as draft October 2, 2025 13:50

qlrd added 2 commits October 9, 2025 14:52

test: add tests cases for Mnemonic XOR

deb7902

This commit add test cases to be compliant with coldcard specification, mostly with 12w/24w with "parts" each (the result mnemonic was derived from another 3 mnemonics that are XORed).

i18n: add translations for Mnemonic XOR feat

c53b97e

This commit applies i18n for `Mnemonic XOR` menu entries as well messages and prompts.

qlrd force-pushed the feat/seedxor branch 2 times, most recently from c231ab8 to 2a18e31 Compare October 9, 2025 18:41

qlrd requested a review from odudex October 9, 2025 18:42

odudex reviewed Oct 9, 2025

View reviewed changes

Comment thread docs/getting-started/features/mnemonic-xor/index.en.md Outdated

odudex reviewed Oct 9, 2025

View reviewed changes

Comment thread docs/getting-started/features/mnemonic-xor/three-shares.en.md Outdated

qlrd added 2 commits October 10, 2025 12:23

docs: add user documentation about Mnemonic XOR feat

b8a3100

This commit add a entry to docs in `docs/getting-started/features/mnemonic-xor.en.md` explaining why we choose `Mnemonic XOR` term instead `SeedXOR`, the overall algorithm's perspective and the usage on krux firmware.

chore: add a description about Mnemonic XOR in CHANGELOG.md

1aff195

qlrd force-pushed the feat/seedxor branch from 0b91ba0 to 1aff195 Compare October 10, 2025 15:24

qlrd requested a review from odudex October 10, 2025 15:25

jdlcdl reviewed Oct 11, 2025

View reviewed changes

Comment thread CHANGELOG.md

jdlcdl reviewed Oct 11, 2025

View reviewed changes

odudex merged commit cc32f6d into selfcustody:develop Oct 11, 2025
7 checks passed

qlrd mentioned this pull request Oct 21, 2025

fix: low entropy calc when using Mnemonic XOR #745

Open

9 tasks

tadeubas mentioned this pull request Oct 27, 2025

Add option to generate mnemonic from camera feed #38

Closed

qlrd deleted the feat/seedxor branch January 8, 2026 12:48

		@@ -0,0 +1,82 @@
		# What's the Mnemonic XOR?

		It's a implementation of [XOR logical gate](https://www.geeksforgeeks.org/digital-logic/xor-gate/) to operate, indefinitely, an [exclusive OR](https://en.wikipedia.org/wiki/Exclusive_or) upon a loaded mnemonic, based on [Coinkite's SeedXOR](https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md).


		# How it works

		To derive a new mnemonic (and thus, a new seed) from other mnemonics, an operation occurs with the mnemonic's entropy bytes.


		<img src="../../../img/mnemonic_xor.png" align="center">

		- We get two different mnemonics (A and B), extract their entropy bytes;

Conversation

qlrd commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is this PR for?

Changes made to:

Did you build the code and tested on device?

What is the purpose of this pull request?

Uh oh!

codecov Bot commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jdlcdl commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdlcdl commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qlrd commented Oct 1, 2025

Uh oh!

qlrd commented Oct 2, 2025

Uh oh!

Uh oh!

Uh oh!

qlrd commented Oct 10, 2025

Uh oh!

odudex commented Oct 10, 2025

Uh oh!

qlrd commented Oct 10, 2025

Uh oh!

qlrd commented Oct 10, 2025

Uh oh!

jdlcdl commented Oct 11, 2025

Uh oh!

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

jdlcdl Oct 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

odudex commented Oct 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

qlrd commented Sep 21, 2025 •

edited

Loading

codecov Bot commented Sep 21, 2025 •

edited

Loading

jdlcdl commented Sep 24, 2025 •

edited

Loading

jdlcdl commented Oct 1, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading

jdlcdl Oct 11, 2025 •

edited

Loading