Implement XOR and test it

Cargo.toml

@@ -2,6 +2,14 @@
 name = "seed-xor"
 version = "0.1.0"
 edition = "2018"
+authors = ["KaiWitt <kaiwitt@protonmail.com>"]
+description = "XOR 24-word bip39 mnemonics."
+readme = "README.md"
+repository = "https://github.com/KaiWitt/seed-xor"
+license = "MIT"
+keywords = ["bitcoin", "seed", "mnemonic", "bip39", "xor"]
+categories = ["cryptography::cryptocurrencies"]
+publish = true
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

README.md

@@ -1 +1,29 @@
  # seed-xor
+
+ seed-xor builds on top of [rust-bip39](https://github.com/rust-bitcoin/rust-bip39/)
+ and lets you XOR 24-word mnemonics as defined in [Coldcard docs](https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md).
+
+
+ Future versions will also allow you to XOR different seed lengths.
+
+
+ ## Example
+
+ ```rust
+ // Coldcard example: https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md
+ let a_str = "romance wink lottery autumn shop bring dawn tongue range crater truth ability miss spice fitness easy legal release recall obey exchange recycle dragon room";
+ let b_str = "lion misery divide hurry latin fluid camp advance illegal lab pyramid unaware eager fringe sick camera series noodle toy crowd jeans select depth lounge";
+ let c_str = "vault nominee cradle silk own frown throw leg cactus recall talent worry gadget surface shy planet purpose coffee drip few seven term squeeze educate";
+ let result_str = "silent toe meat possible chair blossom wait occur this worth option bag nurse find fish scene bench asthma bike wage world quit primary indoor";
+
+ let a = Mnemonic::from_str(a_str).unwrap();
+ let b = Mnemonic::from_str(b_str).unwrap();
+ let c = Mnemonic::from_str(c_str).unwrap();
+ let result = Mnemonic::from_str(result_str).unwrap();
+
+ assert_eq!(result, a ^ b ^ c);
+ ```
+
+ ## Useful resources
+ - Coldcard docs: https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md
+ - Easy mnemonic seed explanation: https://learnmeabitcoin.com/technical/mnemonic

src/lib.rs

@@ -1,314 +1,218 @@
-use bip39::Mnemonic;
+//! # seed-xor
+//!
+//! seed-xor builds on top of [rust-bip39](https://github.com/rust-bitcoin/rust-bip39/)
+//! and lets you XOR 24-word mnemonics as defined in [Coldcards docs](https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md).
+//!
+//!
+//! Future versions will also allow you to XOR different seed lengths.
+//!
+//!
+//! ## Example
+//!
+//! ```rust
+//! // Coldcard example: https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md
+//! let a_str = "romance wink lottery autumn shop bring dawn tongue range crater truth ability miss spice fitness easy legal release recall obey exchange recycle dragon room";
+//! let b_str = "lion misery divide hurry latin fluid camp advance illegal lab pyramid unaware eager fringe sick camera series noodle toy crowd jeans select depth lounge";
+//! let c_str = "vault nominee cradle silk own frown throw leg cactus recall talent worry gadget surface shy planet purpose coffee drip few seven term squeeze educate";
+//! let result_str = "silent toe meat possible chair blossom wait occur this worth option bag nurse find fish scene bench asthma bike wage world quit primary indoor";
+//!
+//! // Mnemonic is a wrapper for bip39::Mnemonic which ensures a 24 word seed length.
+//! // Mnemonics can also be created from 256bit entropy.
+//! let a = Mnemonic::from_str(a_str).unwrap();
+//! let b = Mnemonic::from_str(b_str).unwrap();
+//! let c = Mnemonic::from_str(c_str).unwrap();
+//! let result = Mnemonic::from_str(result_str).unwrap();
+//!
+//! assert_eq!(result, a ^ b ^ c);
+//! ```
+//!
+use std::{
+    fmt,
+    ops::{BitXor, BitXorAssign},
+    str::FromStr,
+};
 
-// TODO: calculate/guess last word
+use bip39::Mnemonic as Inner;
-// TODO: Remove unwrap and other panicky funk
+
-// TODO: Documentation
+/// Maximal number of words in a mnemonic.
-// TODO: Write tests
+const MAX_MNEMONIC_LENGTH: usize = 24;
-// TODO: make macro
+
-pub fn seed_xor(mnemonic1: &Mnemonic, mnemonic2: &Mnemonic) -> Result<Mnemonic, &'static str> {
+/// Errors same as [bip39::Error] but specifically for 24 word mnemonics.
-    if mnemonic1.word_count() == mnemonic2.word_count() {
+#[derive(Debug, Clone, PartialEq, Eq, Copy)]
-        return Err("XOR for different word lenghts are not defined");
+pub enum SeedXorError {
+    /// Mnemonic has a word count that is not 24.
+    WordCountNot24,
+    /// Mnemonic contains an unknown word.
+    /// Error contains the index of the word.
+    UnknownWord(usize),
+    /// Entropy was not a 256 bits in length.
+    EntropyBitsNot256,
+    /// The mnemonic has an invalid checksum.
+    InvalidChecksum,
+    /// The mnemonic can be interpreted as multiple languages.
+    AmbiguousLanguages,
 }
 
-    let mut words = convert_words_to_bytes(mnemonic1.word_iter())?;
+impl From<bip39::Error> for SeedXorError {
-    let words2 = convert_words_to_bytes(mnemonic2.word_iter())?;
+    fn from(err: bip39::Error) -> Self {
-
+        match err {
-    for (i, word) in words.iter_mut().enumerate() {
+            bip39::Error::BadEntropyBitCount(_) => return Self::EntropyBitsNot256,
-        *word ^= words2.get(i).unwrap();
+            bip39::Error::BadWordCount(_) => return Self::WordCountNot24,
-    }
+            bip39::Error::UnknownWord(i) => return Self::UnknownWord(i),
-    Ok(convert_bytes_to_mnemonic(&words)?)
+            bip39::Error::InvalidChecksum => return Self::InvalidChecksum,
-}
+            bip39::Error::AmbiguousLanguages(_) => Self::AmbiguousLanguages,
-
-fn convert_bytes_to_mnemonic(bytes: &Vec<u8>) -> Result<Mnemonic, &'static str> {
-    let mut indexes = Vec::<usize>::with_capacity(24);
-
-    let mut helper: u16 = 0;
-    let mut cut: u8 = 0;
-    for (i, byte) in bytes.iter().enumerate() {
-        match i % 3 {
-            0 => {
-                helper = (*byte as u16) << 4;
-            }
-            1 => {
-                helper |= (byte >> 4) as u16; // wrap or no wrap???
-                cut = byte << 4;
-                indexes.push(helper.into());
-            }
-            // Only 2?
-            _ => {
-                helper = (cut << 8) as u16;
-                helper |= *byte as u16;
-                indexes.push(helper.into());
         }
     }
 }
 
-    let words: Vec<&str> = indexes.into_iter().map(|i| WORDS[i]).collect();
+impl fmt::Display for SeedXorError {
-    return Ok(Mnemonic::parse(words.join(" ")).unwrap());
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match *self {
+            SeedXorError::WordCountNot24 => {
+                write!(f, "Mnemonic has a word count that is not 24",)
+            }
+            SeedXorError::UnknownWord(i) => {
+                write!(f, "Mnemonic contains an unknown word (word {})", i,)
+            }
+            SeedXorError::EntropyBitsNot256 => write!(f, "Entropy was not between 256 bits",),
+            SeedXorError::InvalidChecksum => write!(f, "Mnemonic has an invalid checksum"),
+            SeedXorError::AmbiguousLanguages => write!(f, "Ambiguous language"),
+        }
+    }
 }
 
-// TODO: return iterator?
+/// Wrapper for a [bip39::Mnemonic] which is aliased as `Inner`
-// TODO: enumerate and check mod 2 instead of first_word variable
+#[derive(Clone, PartialEq, Eq, Debug, Hash, PartialOrd, Ord)]
-/// One word is represented with 3 hex = 1.5 Bytes, we need 2 words = 6 hex = 3bytes
+pub struct Mnemonic {
-fn convert_words_to_bytes<'a, W>(words: W) -> Result<Vec<u8>, &'static str>
+    inner: Inner,
-where
-    W: Iterator<Item = &'a str>,
-{
-    // max words 24 á 3 bytes = 36 bytes
-    let mut result = Vec::<u8>::with_capacity(36);
-    let mut wordlist = WORDS.iter();
-    let mut first_word = None::<&str>;
-    for word in words {
-        if first_word.is_none() {
-            first_word = Some(word);
-            continue;
-        }
-        let first: u32;
-        let second: u32;
-        match wordlist.position(|&w| w == first_word.unwrap()) {
-            Some(index) => {
-                first = index as u32 & TWELVE_BITS;
-            }
-            None => return Err(ERR),
-        }
-        match wordlist.position(|&w| w == word) {
-            Some(index) => {
-                second = index as u32 & TWELVE_BITS;
-            }
-            None => return Err(ERR),
 }
 
-        let bytes: [u8; 4] = ((first << 12) & second).to_be_bytes();
+impl Mnemonic {
-        bytes[1..].iter().for_each(|b| result.push(*b));
+    /// Private constructor which ensures that a new [Mnemonic] instance has 24 words.
+    fn new(inner: Inner) -> Result<Self, SeedXorError> {
+        ensure_24_words(&inner)?;
 
-        first_word = None;
+        Ok(Mnemonic { inner })
     }
 
-    Ok(result)
+    /// Access the inner [bip39::Mnemonic] for more functionality.
+    pub fn inner(&self) -> &Inner {
+        &self.inner
     }
 
-const ERR: &str = "Words contains a word which is not in the standard word list";
+    /// Wrapper for the same method as in [bip39::Mnemonic]
+    /// but it returns an `Err` if the entropy does not result in a 24 word mnemonic.
+    pub fn from_entropy(entropy: &[u8]) -> Result<Self, SeedXorError> {
+        match Inner::from_entropy(entropy) {
+            Ok(inner) => return Ok(Mnemonic::new(inner)?),
+            Err(err) => return Err(SeedXorError::from(err)),
+        }
+    }
 
-const TWELVE_BITS: u32 = 0b111111111111;
+    /// XOR two [Mnemonic]s without consuming them.
+    /// If consumption is not of relevance the XOR operator `^` and XOR assigner `^=` can be used as well.
+    fn xor(&self, rhs: &Self) -> Self {
+        let mut xor_result = Vec::with_capacity(MAX_MNEMONIC_LENGTH);
 
-const WORDS: [&str; 2048] = [
+        // XOR self's and other's entropy and push result
-    "abandon", "ability", "able", "about", "above", "absent", "absorb", "abstract", "absurd",
+        self.inner
-    "abuse", "access", "accident", "account", "accuse", "achieve", "acid", "acoustic", "acquire",
+            .to_entropy()
-    "across", "act", "action", "actor", "actress", "actual", "adapt", "add", "addict", "address",
+            .iter()
-    "adjust", "admit", "adult", "advance", "advice", "aerobic", "affair", "afford", "afraid",
+            .zip(rhs.inner.to_entropy().iter())
-    "again", "age", "agent", "agree", "ahead", "aim", "air", "airport", "aisle", "alarm", "album",
+            .for_each(|(a, b)| xor_result.push(a ^ b));
-    "alcohol", "alert", "alien", "all", "alley", "allow", "almost", "alone", "alpha", "already",
+
-    "also", "alter", "always", "amateur", "amazing", "among", "amount", "amused", "analyst",
+        // We unwrap here because xor_result has as many bytes as self and rhs
-    "anchor", "ancient", "anger", "angle", "angry", "animal", "ankle", "announce", "annual",
+        // which in turn have a valid number of bytes
-    "another", "answer", "antenna", "antique", "anxiety", "any", "apart", "apology", "appear",
+        Mnemonic::from_entropy(&xor_result).unwrap()
-    "apple", "approve", "april", "arch", "arctic", "area", "arena", "argue", "arm", "armed",
+    }
-    "armor", "army", "around", "arrange", "arrest", "arrive", "arrow", "art", "artefact", "artist",
+}
-    "artwork", "ask", "aspect", "assault", "asset", "assist", "assume", "asthma", "athlete",
+
-    "atom", "attack", "attend", "attitude", "attract", "auction", "audit", "august", "aunt",
+impl FromStr for Mnemonic {
-    "author", "auto", "autumn", "average", "avocado", "avoid", "awake", "aware", "away", "awesome",
+    type Err = SeedXorError;
-    "awful", "awkward", "axis", "baby", "bachelor", "bacon", "badge", "bag", "balance", "balcony",
+
-    "ball", "bamboo", "banana", "banner", "bar", "barely", "bargain", "barrel", "base", "basic",
+    fn from_str(mnemonic: &str) -> Result<Self, <Self as FromStr>::Err> {
-    "basket", "battle", "beach", "bean", "beauty", "because", "become", "beef", "before", "begin",
+        match Inner::from_str(mnemonic) {
-    "behave", "behind", "believe", "below", "belt", "bench", "benefit", "best", "betray", "better",
+            Ok(inner) => return Ok(Mnemonic::new(inner)?),
-    "between", "beyond", "bicycle", "bid", "bike", "bind", "biology", "bird", "birth", "bitter",
+            Err(err) => Err(SeedXorError::from(err)),
-    "black", "blade", "blame", "blanket", "blast", "bleak", "bless", "blind", "blood", "blossom",
+        }
-    "blouse", "blue", "blur", "blush", "board", "boat", "body", "boil", "bomb", "bone", "bonus",
+    }
-    "book", "boost", "border", "boring", "borrow", "boss", "bottom", "bounce", "box", "boy",
+}
-    "bracket", "brain", "brand", "brass", "brave", "bread", "breeze", "brick", "bridge", "brief",
+
-    "bright", "bring", "brisk", "broccoli", "broken", "bronze", "broom", "brother", "brown",
+impl fmt::Display for Mnemonic {
-    "brush", "bubble", "buddy", "budget", "buffalo", "build", "bulb", "bulk", "bullet", "bundle",
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-    "bunker", "burden", "burger", "burst", "bus", "business", "busy", "butter", "buyer", "buzz",
+        for (i, word) in self.inner.word_iter().enumerate() {
-    "cabbage", "cabin", "cable", "cactus", "cage", "cake", "call", "calm", "camera", "camp", "can",
+            if i > 0 {
-    "canal", "cancel", "candy", "cannon", "canoe", "canvas", "canyon", "capable", "capital",
+                f.write_str(" ")?;
-    "captain", "car", "carbon", "card", "cargo", "carpet", "carry", "cart", "case", "cash",
+            }
-    "casino", "castle", "casual", "cat", "catalog", "catch", "category", "cattle", "caught",
+            f.write_str(word)?;
-    "cause", "caution", "cave", "ceiling", "celery", "cement", "census", "century", "cereal",
+        }
-    "certain", "chair", "chalk", "champion", "change", "chaos", "chapter", "charge", "chase",
+        Ok(())
-    "chat", "cheap", "check", "cheese", "chef", "cherry", "chest", "chicken", "chief", "child",
+    }
-    "chimney", "choice", "choose", "chronic", "chuckle", "chunk", "churn", "cigar", "cinnamon",
+}
-    "circle", "citizen", "city", "civil", "claim", "clap", "clarify", "claw", "clay", "clean",
+
-    "clerk", "clever", "click", "client", "cliff", "climb", "clinic", "clip", "clock", "clog",
+impl BitXor for Mnemonic {
-    "close", "cloth", "cloud", "clown", "club", "clump", "cluster", "clutch", "coach", "coast",
+    type Output = Self;
-    "coconut", "code", "coffee", "coil", "coin", "collect", "color", "column", "combine", "come",
+
-    "comfort", "comic", "common", "company", "concert", "conduct", "confirm", "congress",
+    fn bitxor(self, rhs: Self) -> Self::Output {
-    "connect", "consider", "control", "convince", "cook", "cool", "copper", "copy", "coral",
+        self.xor(&rhs)
-    "core", "corn", "correct", "cost", "cotton", "couch", "country", "couple", "course", "cousin",
+    }
-    "cover", "coyote", "crack", "cradle", "craft", "cram", "crane", "crash", "crater", "crawl",
+}
-    "crazy", "cream", "credit", "creek", "crew", "cricket", "crime", "crisp", "critic", "crop",
+
-    "cross", "crouch", "crowd", "crucial", "cruel", "cruise", "crumble", "crunch", "crush", "cry",
+impl BitXorAssign for Mnemonic {
-    "crystal", "cube", "culture", "cup", "cupboard", "curious", "current", "curtain", "curve",
+    fn bitxor_assign(&mut self, rhs: Self) {
-    "cushion", "custom", "cute", "cycle", "dad", "damage", "damp", "dance", "danger", "daring",
+        *self = self.xor(&rhs)
-    "dash", "daughter", "dawn", "day", "deal", "debate", "debris", "decade", "december", "decide",
+    }
-    "decline", "decorate", "decrease", "deer", "defense", "define", "defy", "degree", "delay",
+}
-    "deliver", "demand", "demise", "denial", "dentist", "deny", "depart", "depend", "deposit",
+
-    "depth", "deputy", "derive", "describe", "desert", "design", "desk", "despair", "destroy",
+/// Ensures that an [Inner] is a 24 word mnemonic for wrapping into a [Mnemonic].
-    "detail", "detect", "develop", "device", "devote", "diagram", "dial", "diamond", "diary",
+fn ensure_24_words(inner: &Inner) -> Result<(), SeedXorError> {
-    "dice", "diesel", "diet", "differ", "digital", "dignity", "dilemma", "dinner", "dinosaur",
+    if inner.word_count() != MAX_MNEMONIC_LENGTH {
-    "direct", "dirt", "disagree", "discover", "disease", "dish", "dismiss", "disorder", "display",
+        return Err(SeedXorError::WordCountNot24);
-    "distance", "divert", "divide", "divorce", "dizzy", "doctor", "document", "dog", "doll",
+    }
-    "dolphin", "domain", "donate", "donkey", "donor", "door", "dose", "double", "dove", "draft",
+
-    "dragon", "drama", "drastic", "draw", "dream", "dress", "drift", "drill", "drink", "drip",
+    Ok(())
-    "drive", "drop", "drum", "dry", "duck", "dumb", "dune", "during", "dust", "dutch", "duty",
+}
-    "dwarf", "dynamic", "eager", "eagle", "early", "earn", "earth", "easily", "east", "easy",
-    "echo", "ecology", "economy", "edge", "edit", "educate", "effort", "egg", "eight", "either",
-    "elbow", "elder", "electric", "elegant", "element", "elephant", "elevator", "elite", "else",
-    "embark", "embody", "embrace", "emerge", "emotion", "employ", "empower", "empty", "enable",
-    "enact", "end", "endless", "endorse", "enemy", "energy", "enforce", "engage", "engine",
-    "enhance", "enjoy", "enlist", "enough", "enrich", "enroll", "ensure", "enter", "entire",
-    "entry", "envelope", "episode", "equal", "equip", "era", "erase", "erode", "erosion", "error",
-    "erupt", "escape", "essay", "essence", "estate", "eternal", "ethics", "evidence", "evil",
-    "evoke", "evolve", "exact", "example", "excess", "exchange", "excite", "exclude", "excuse",
-    "execute", "exercise", "exhaust", "exhibit", "exile", "exist", "exit", "exotic", "expand",
-    "expect", "expire", "explain", "expose", "express", "extend", "extra", "eye", "eyebrow",
-    "fabric", "face", "faculty", "fade", "faint", "faith", "fall", "false", "fame", "family",
-    "famous", "fan", "fancy", "fantasy", "farm", "fashion", "fat", "fatal", "father", "fatigue",
-    "fault", "favorite", "feature", "february", "federal", "fee", "feed", "feel", "female",
-    "fence", "festival", "fetch", "fever", "few", "fiber", "fiction", "field", "figure", "file",
-    "film", "filter", "final", "find", "fine", "finger", "finish", "fire", "firm", "first",
-    "fiscal", "fish", "fit", "fitness", "fix", "flag", "flame", "flash", "flat", "flavor", "flee",
-    "flight", "flip", "float", "flock", "floor", "flower", "fluid", "flush", "fly", "foam",
-    "focus", "fog", "foil", "fold", "follow", "food", "foot", "force", "forest", "forget", "fork",
-    "fortune", "forum", "forward", "fossil", "foster", "found", "fox", "fragile", "frame",
-    "frequent", "fresh", "friend", "fringe", "frog", "front", "frost", "frown", "frozen", "fruit",
-    "fuel", "fun", "funny", "furnace", "fury", "future", "gadget", "gain", "galaxy", "gallery",
-    "game", "gap", "garage", "garbage", "garden", "garlic", "garment", "gas", "gasp", "gate",
-    "gather", "gauge", "gaze", "general", "genius", "genre", "gentle", "genuine", "gesture",
-    "ghost", "giant", "gift", "giggle", "ginger", "giraffe", "girl", "give", "glad", "glance",
-    "glare", "glass", "glide", "glimpse", "globe", "gloom", "glory", "glove", "glow", "glue",
-    "goat", "goddess", "gold", "good", "goose", "gorilla", "gospel", "gossip", "govern", "gown",
-    "grab", "grace", "grain", "grant", "grape", "grass", "gravity", "great", "green", "grid",
-    "grief", "grit", "grocery", "group", "grow", "grunt", "guard", "guess", "guide", "guilt",
-    "guitar", "gun", "gym", "habit", "hair", "half", "hammer", "hamster", "hand", "happy",
-    "harbor", "hard", "harsh", "harvest", "hat", "have", "hawk", "hazard", "head", "health",
-    "heart", "heavy", "hedgehog", "height", "hello", "helmet", "help", "hen", "hero", "hidden",
-    "high", "hill", "hint", "hip", "hire", "history", "hobby", "hockey", "hold", "hole", "holiday",
-    "hollow", "home", "honey", "hood", "hope", "horn", "horror", "horse", "hospital", "host",
-    "hotel", "hour", "hover", "hub", "huge", "human", "humble", "humor", "hundred", "hungry",
-    "hunt", "hurdle", "hurry", "hurt", "husband", "hybrid", "ice", "icon", "idea", "identify",
-    "idle", "ignore", "ill", "illegal", "illness", "image", "imitate", "immense", "immune",
-    "impact", "impose", "improve", "impulse", "inch", "include", "income", "increase", "index",
-    "indicate", "indoor", "industry", "infant", "inflict", "inform", "inhale", "inherit",
-    "initial", "inject", "injury", "inmate", "inner", "innocent", "input", "inquiry", "insane",
-    "insect", "inside", "inspire", "install", "intact", "interest", "into", "invest", "invite",
-    "involve", "iron", "island", "isolate", "issue", "item", "ivory", "jacket", "jaguar", "jar",
-    "jazz", "jealous", "jeans", "jelly", "jewel", "job", "join", "joke", "journey", "joy", "judge",
-    "juice", "jump", "jungle", "junior", "junk", "just", "kangaroo", "keen", "keep", "ketchup",
-    "key", "kick", "kid", "kidney", "kind", "kingdom", "kiss", "kit", "kitchen", "kite", "kitten",
-    "kiwi", "knee", "knife", "knock", "know", "lab", "label", "labor", "ladder", "lady", "lake",
-    "lamp", "language", "laptop", "large", "later", "latin", "laugh", "laundry", "lava", "law",
-    "lawn", "lawsuit", "layer", "lazy", "leader", "leaf", "learn", "leave", "lecture", "left",
-    "leg", "legal", "legend", "leisure", "lemon", "lend", "length", "lens", "leopard", "lesson",
-    "letter", "level", "liar", "liberty", "library", "license", "life", "lift", "light", "like",
-    "limb", "limit", "link", "lion", "liquid", "list", "little", "live", "lizard", "load", "loan",
-    "lobster", "local", "lock", "logic", "lonely", "long", "loop", "lottery", "loud", "lounge",
-    "love", "loyal", "lucky", "luggage", "lumber", "lunar", "lunch", "luxury", "lyrics", "machine",
-    "mad", "magic", "magnet", "maid", "mail", "main", "major", "make", "mammal", "man", "manage",
-    "mandate", "mango", "mansion", "manual", "maple", "marble", "march", "margin", "marine",
-    "market", "marriage", "mask", "mass", "master", "match", "material", "math", "matrix",
-    "matter", "maximum", "maze", "meadow", "mean", "measure", "meat", "mechanic", "medal", "media",
-    "melody", "melt", "member", "memory", "mention", "menu", "mercy", "merge", "merit", "merry",
-    "mesh", "message", "metal", "method", "middle", "midnight", "milk", "million", "mimic", "mind",
-    "minimum", "minor", "minute", "miracle", "mirror", "misery", "miss", "mistake", "mix", "mixed",
-    "mixture", "mobile", "model", "modify", "mom", "moment", "monitor", "monkey", "monster",
-    "month", "moon", "moral", "more", "morning", "mosquito", "mother", "motion", "motor",
-    "mountain", "mouse", "move", "movie", "much", "muffin", "mule", "multiply", "muscle", "museum",
-    "mushroom", "music", "must", "mutual", "myself", "mystery", "myth", "naive", "name", "napkin",
-    "narrow", "nasty", "nation", "nature", "near", "neck", "need", "negative", "neglect",
-    "neither", "nephew", "nerve", "nest", "net", "network", "neutral", "never", "news", "next",
-    "nice", "night", "noble", "noise", "nominee", "noodle", "normal", "north", "nose", "notable",
-    "note", "nothing", "notice", "novel", "now", "nuclear", "number", "nurse", "nut", "oak",
-    "obey", "object", "oblige", "obscure", "observe", "obtain", "obvious", "occur", "ocean",
-    "october", "odor", "off", "offer", "office", "often", "oil", "okay", "old", "olive", "olympic",
-    "omit", "once", "one", "onion", "online", "only", "open", "opera", "opinion", "oppose",
-    "option", "orange", "orbit", "orchard", "order", "ordinary", "organ", "orient", "original",
-    "orphan", "ostrich", "other", "outdoor", "outer", "output", "outside", "oval", "oven", "over",
-    "own", "owner", "oxygen", "oyster", "ozone", "pact", "paddle", "page", "pair", "palace",
-    "palm", "panda", "panel", "panic", "panther", "paper", "parade", "parent", "park", "parrot",
-    "party", "pass", "patch", "path", "patient", "patrol", "pattern", "pause", "pave", "payment",
-    "peace", "peanut", "pear", "peasant", "pelican", "pen", "penalty", "pencil", "people",
-    "pepper", "perfect", "permit", "person", "pet", "phone", "photo", "phrase", "physical",
-    "piano", "picnic", "picture", "piece", "pig", "pigeon", "pill", "pilot", "pink", "pioneer",
-    "pipe", "pistol", "pitch", "pizza", "place", "planet", "plastic", "plate", "play", "please",
-    "pledge", "pluck", "plug", "plunge", "poem", "poet", "point", "polar", "pole", "police",
-    "pond", "pony", "pool", "popular", "portion", "position", "possible", "post", "potato",
-    "pottery", "poverty", "powder", "power", "practice", "praise", "predict", "prefer", "prepare",
-    "present", "pretty", "prevent", "price", "pride", "primary", "print", "priority", "prison",
-    "private", "prize", "problem", "process", "produce", "profit", "program", "project", "promote",
-    "proof", "property", "prosper", "protect", "proud", "provide", "public", "pudding", "pull",
-    "pulp", "pulse", "pumpkin", "punch", "pupil", "puppy", "purchase", "purity", "purpose",
-    "purse", "push", "put", "puzzle", "pyramid", "quality", "quantum", "quarter", "question",
-    "quick", "quit", "quiz", "quote", "rabbit", "raccoon", "race", "rack", "radar", "radio",
-    "rail", "rain", "raise", "rally", "ramp", "ranch", "random", "range", "rapid", "rare", "rate",
-    "rather", "raven", "raw", "razor", "ready", "real", "reason", "rebel", "rebuild", "recall",
-    "receive", "recipe", "record", "recycle", "reduce", "reflect", "reform", "refuse", "region",
-    "regret", "regular", "reject", "relax", "release", "relief", "rely", "remain", "remember",
-    "remind", "remove", "render", "renew", "rent", "reopen", "repair", "repeat", "replace",
-    "report", "require", "rescue", "resemble", "resist", "resource", "response", "result",
-    "retire", "retreat", "return", "reunion", "reveal", "review", "reward", "rhythm", "rib",
-    "ribbon", "rice", "rich", "ride", "ridge", "rifle", "right", "rigid", "ring", "riot", "ripple",
-    "risk", "ritual", "rival", "river", "road", "roast", "robot", "robust", "rocket", "romance",
-    "roof", "rookie", "room", "rose", "rotate", "rough", "round", "route", "royal", "rubber",
-    "rude", "rug", "rule", "run", "runway", "rural", "sad", "saddle", "sadness", "safe", "sail",
-    "salad", "salmon", "salon", "salt", "salute", "same", "sample", "sand", "satisfy", "satoshi",
-    "sauce", "sausage", "save", "say", "scale", "scan", "scare", "scatter", "scene", "scheme",
-    "school", "science", "scissors", "scorpion", "scout", "scrap", "screen", "script", "scrub",
-    "sea", "search", "season", "seat", "second", "secret", "section", "security", "seed", "seek",
-    "segment", "select", "sell", "seminar", "senior", "sense", "sentence", "series", "service",
-    "session", "settle", "setup", "seven", "shadow", "shaft", "shallow", "share", "shed", "shell",
-    "sheriff", "shield", "shift", "shine", "ship", "shiver", "shock", "shoe", "shoot", "shop",
-    "short", "shoulder", "shove", "shrimp", "shrug", "shuffle", "shy", "sibling", "sick", "side",
-    "siege", "sight", "sign", "silent", "silk", "silly", "silver", "similar", "simple", "since",
-    "sing", "siren", "sister", "situate", "six", "size", "skate", "sketch", "ski", "skill", "skin",
-    "skirt", "skull", "slab", "slam", "sleep", "slender", "slice", "slide", "slight", "slim",
-    "slogan", "slot", "slow", "slush", "small", "smart", "smile", "smoke", "smooth", "snack",
-    "snake", "snap", "sniff", "snow", "soap", "soccer", "social", "sock", "soda", "soft", "solar",
-    "soldier", "solid", "solution", "solve", "someone", "song", "soon", "sorry", "sort", "soul",
-    "sound", "soup", "source", "south", "space", "spare", "spatial", "spawn", "speak", "special",
-    "speed", "spell", "spend", "sphere", "spice", "spider", "spike", "spin", "spirit", "split",
-    "spoil", "sponsor", "spoon", "sport", "spot", "spray", "spread", "spring", "spy", "square",
-    "squeeze", "squirrel", "stable", "stadium", "staff", "stage", "stairs", "stamp", "stand",
-    "start", "state", "stay", "steak", "steel", "stem", "step", "stereo", "stick", "still",
-    "sting", "stock", "stomach", "stone", "stool", "story", "stove", "strategy", "street",
-    "strike", "strong", "struggle", "student", "stuff", "stumble", "style", "subject", "submit",
-    "subway", "success", "such", "sudden", "suffer", "sugar", "suggest", "suit", "summer", "sun",
-    "sunny", "sunset", "super", "supply", "supreme", "sure", "surface", "surge", "surprise",
-    "surround", "survey", "suspect", "sustain", "swallow", "swamp", "swap", "swarm", "swear",
-    "sweet", "swift", "swim", "swing", "switch", "sword", "symbol", "symptom", "syrup", "system",
-    "table", "tackle", "tag", "tail", "talent", "talk", "tank", "tape", "target", "task", "taste",
-    "tattoo", "taxi", "teach", "team", "tell", "ten", "tenant", "tennis", "tent", "term", "test",
-    "text", "thank", "that", "theme", "then", "theory", "there", "they", "thing", "this",
-    "thought", "three", "thrive", "throw", "thumb", "thunder", "ticket", "tide", "tiger", "tilt",
-    "timber", "time", "tiny", "tip", "tired", "tissue", "title", "toast", "tobacco", "today",
-    "toddler", "toe", "together", "toilet", "token", "tomato", "tomorrow", "tone", "tongue",
-    "tonight", "tool", "tooth", "top", "topic", "topple", "torch", "tornado", "tortoise", "toss",
-    "total", "tourist", "toward", "tower", "town", "toy", "track", "trade", "traffic", "tragic",
-    "train", "transfer", "trap", "trash", "travel", "tray", "treat", "tree", "trend", "trial",
-    "tribe", "trick", "trigger", "trim", "trip", "trophy", "trouble", "truck", "true", "truly",
-    "trumpet", "trust", "truth", "try", "tube", "tuition", "tumble", "tuna", "tunnel", "turkey",
-    "turn", "turtle", "twelve", "twenty", "twice", "twin", "twist", "two", "type", "typical",
-    "ugly", "umbrella", "unable", "unaware", "uncle", "uncover", "under", "undo", "unfair",
-    "unfold", "unhappy", "uniform", "unique", "unit", "universe", "unknown", "unlock", "until",
-    "unusual", "unveil", "update", "upgrade", "uphold", "upon", "upper", "upset", "urban", "urge",
-    "usage", "use", "used", "useful", "useless", "usual", "utility", "vacant", "vacuum", "vague",
-    "valid", "valley", "valve", "van", "vanish", "vapor", "various", "vast", "vault", "vehicle",
-    "velvet", "vendor", "venture", "venue", "verb", "verify", "version", "very", "vessel",
-    "veteran", "viable", "vibrant", "vicious", "victory", "video", "view", "village", "vintage",
-    "violin", "virtual", "virus", "visa", "visit", "visual", "vital", "vivid", "vocal", "voice",
-    "void", "volcano", "volume", "vote", "voyage", "wage", "wagon", "wait", "walk", "wall",
-    "walnut", "want", "warfare", "warm", "warrior", "wash", "wasp", "waste", "water", "wave",
-    "way", "wealth", "weapon", "wear", "weasel", "weather", "web", "wedding", "weekend", "weird",
-    "welcome", "west", "wet", "whale", "what", "wheat", "wheel", "when", "where", "whip",
-    "whisper", "wide", "width", "wife", "wild", "will", "win", "window", "wine", "wing", "wink",
-    "winner", "winter", "wire", "wisdom", "wise", "wish", "witness", "wolf", "woman", "wonder",
-    "wood", "wool", "word", "work", "world", "worry", "worth", "wrap", "wreck", "wrestle", "wrist",
-    "write", "wrong", "yard", "year", "yellow", "you", "young", "youth", "zebra", "zero", "zone",
-    "zoo",
-];
 
 #[cfg(test)]
 mod tests {
+    use crate::Mnemonic;
+    use std::str::FromStr;
+
     #[test]
-    fn it_works() {
+    fn seed_xor_works() {
-        assert_eq!(2 + 2, 4);
+        // Coldcard example: https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md
+        let a_str = "romance wink lottery autumn shop bring dawn tongue range crater truth ability miss spice fitness easy legal release recall obey exchange recycle dragon room";
+        let b_str = "lion misery divide hurry latin fluid camp advance illegal lab pyramid unaware eager fringe sick camera series noodle toy crowd jeans select depth lounge";
+        let c_str = "vault nominee cradle silk own frown throw leg cactus recall talent worry gadget surface shy planet purpose coffee drip few seven term squeeze educate";
+        let result_str = "silent toe meat possible chair blossom wait occur this worth option bag nurse find fish scene bench asthma bike wage world quit primary indoor";
+
+        let a = Mnemonic::from_str(a_str).unwrap();
+        let b = Mnemonic::from_str(b_str).unwrap();
+        let c = Mnemonic::from_str(c_str).unwrap();
+        let result = Mnemonic::from_str(result_str).unwrap();
+
+        assert_eq!(result, a.clone() ^ b.clone() ^ c.clone());
+
+        // Different order
+        assert_eq!(result, b ^ c ^ a);
+    }
+
+    #[test]
+    fn seed_xor_assignment_works() {
+        // Coldcard example: https://github.com/Coldcard/firmware/blob/master/docs/seed-xor.md
+        let a_str = "romance wink lottery autumn shop bring dawn tongue range crater truth ability miss spice fitness easy legal release recall obey exchange recycle dragon room";
+        let b_str = "lion misery divide hurry latin fluid camp advance illegal lab pyramid unaware eager fringe sick camera series noodle toy crowd jeans select depth lounge";
+        let c_str = "vault nominee cradle silk own frown throw leg cactus recall talent worry gadget surface shy planet purpose coffee drip few seven term squeeze educate";
+        let result_str = "silent toe meat possible chair blossom wait occur this worth option bag nurse find fish scene bench asthma bike wage world quit primary indoor";
+
+        let a = Mnemonic::from_str(a_str).unwrap();
+        let b = Mnemonic::from_str(b_str).unwrap();
+        let c = Mnemonic::from_str(c_str).unwrap();
+        let result = Mnemonic::from_str(result_str).unwrap();
+
+        let mut assigned = a.xor(&b); // XOR without consuming
+        assigned ^= c;
+
+        assert_eq!(result, assigned);
     }
 }