feat(bip0039): add Language::words() plan and expose per-language words() (#124)

- Add English::words() and other built-in language words() accessors
- Refactor wordlist checksum test to be table-driven and validate words()/word_of/index_of
- Extract checksum helper and tighten internal Wordlist.words type to [&str; 2048]
- Document planned breaking Language::words() API in comments

Author: koushiro

bip0039/build.rs

@@ -100,7 +100,6 @@ fn generate_one(out_dir: &Path, lang: &str, input_path: &Path) -> Result<()> {
         f,
         "// AUTO-GENERATED by build.rs. DO NOT EDIT.\n\
          // Source: {}\n\
-         \n\
          ",
         input_path.file_name().and_then(OsStr::to_str).unwrap_or("<unknown>")
     )

bip0039/src/language/mod.rs

@@ -25,6 +25,17 @@ use self::wordlist::*;
 /// - `index_of(word)` must return the correct index (BIP-0039 order) for all words in the language
 ///   wordlist; return `None` for unknown words.
 pub trait Language: Sized {
+    // NOTE (planned breaking change): we intend to add the following method in the next
+    // minor release (e.g. `0.14.0`), and treat it as a breaking change for external
+    // `Language` implementations:
+    //
+    // /// Returns the full BIP-0039 word list for this language (2048 words) in BIP-0039 order.
+    // ///
+    // /// Notes:
+    // /// - This returns the full underlying word list, not just a view of a specific mnemonic.
+    // /// - The returned words must be NFKD-normalized and unique.
+    // fn words() -> &'static [&'static str; 2048];
+
     /// Returns the word at `index` (BIP-0039 order).
     fn word_of(index: usize) -> &'static str;
 
@@ -33,6 +44,10 @@ pub trait Language: Sized {
 }
 
 impl<T: WordlistProvider> Language for T {
+    // fn words() -> &'static [&'static str; 2048] {
+    //     <T as WordlistProvider>::wordlist().words
+    // }
+
     #[inline]
     fn word_of(index: usize) -> &'static str {
         debug_assert!(index < 2048, "Invalid wordlist index");
@@ -59,6 +74,14 @@ impl WordlistProvider for English {
     }
 }
 
+impl English {
+    /// Returns the full BIP-0039 English word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::english::WORDS
+    }
+}
+
 /// The `Simplified Chinese` language.
 #[cfg(feature = "chinese-simplified")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -72,6 +95,15 @@ impl WordlistProvider for ChineseSimplified {
     }
 }
 
+#[cfg(feature = "chinese-simplified")]
+impl ChineseSimplified {
+    /// Returns the full BIP-0039 Simplified Chinese word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::chinese_simplified::WORDS
+    }
+}
+
 /// The `Traditional Chinese` language.
 #[cfg(feature = "chinese-traditional")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -85,6 +117,15 @@ impl WordlistProvider for ChineseTraditional {
     }
 }
 
+#[cfg(feature = "chinese-traditional")]
+impl ChineseTraditional {
+    /// Returns the full BIP-0039 Traditional Chinese word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::chinese_traditional::WORDS
+    }
+}
+
 /// The `Czech` language.
 #[cfg(feature = "czech")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -98,6 +139,15 @@ impl WordlistProvider for Czech {
     }
 }
 
+#[cfg(feature = "czech")]
+impl Czech {
+    /// Returns the full BIP-0039 Czech word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::czech::WORDS
+    }
+}
+
 /// The `French` language.
 #[cfg(feature = "french")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -111,6 +161,15 @@ impl WordlistProvider for French {
     }
 }
 
+#[cfg(feature = "french")]
+impl French {
+    /// Returns the full BIP-0039 French word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::french::WORDS
+    }
+}
+
 /// The `Italian` language.
 #[cfg(feature = "italian")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -124,6 +183,15 @@ impl WordlistProvider for Italian {
     }
 }
 
+#[cfg(feature = "italian")]
+impl Italian {
+    /// Returns the full BIP-0039 Italian word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::italian::WORDS
+    }
+}
+
 /// The `Japanese` language.
 #[cfg(feature = "japanese")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -137,6 +205,15 @@ impl WordlistProvider for Japanese {
     }
 }
 
+#[cfg(feature = "japanese")]
+impl Japanese {
+    /// Returns the full BIP-0039 Japanese word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::japanese::WORDS
+    }
+}
+
 /// The `Korean` language.
 #[cfg(feature = "korean")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -150,6 +227,15 @@ impl WordlistProvider for Korean {
     }
 }
 
+#[cfg(feature = "korean")]
+impl Korean {
+    /// Returns the full BIP-0039 Korean word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::korean::WORDS
+    }
+}
+
 /// The `Portuguese` language.
 #[cfg(feature = "portuguese")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -163,6 +249,15 @@ impl WordlistProvider for Portuguese {
     }
 }
 
+#[cfg(feature = "portuguese")]
+impl Portuguese {
+    /// Returns the full BIP-0039 Portuguese word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::portuguese::WORDS
+    }
+}
+
 /// The `Spanish` language.
 #[cfg(feature = "spanish")]
 #[derive(Copy, Clone, Debug, Ord, PartialOrd, Eq, PartialEq, Hash)]
@@ -176,118 +271,164 @@ impl WordlistProvider for Spanish {
     }
 }
 
+#[cfg(feature = "spanish")]
+impl Spanish {
+    /// Returns the full BIP-0039 Spanish word list (2048 words) in BIP-0039 order.
+    #[inline]
+    pub fn words() -> &'static [&'static str; 2048] {
+        &wordlists::spanish::WORDS
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use sha2::{Digest, Sha256};
-
     use super::*;
 
-    // Check the sha256sum of the word lists.
-    //
-    // They are as follows in the [bips](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md):
-    //
-    // Chinese(simplified):     5c5942792bd8340cb8b27cd592f1015edf56a8c5b26276ee18a482428e7c5726
-    // Chinese(traditional):    417b26b3d8500a4ae3d59717d7011952db6fc2fb84b807f3f94ac734e89c1b5f
-    // Czech:                   7e80e161c3e93d9554c2efb78d4e3cebf8fc727e9c52e03b83b94406bdcc95fc
-    // English:                 2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda
-    // French:                  ebc3959ab7801a1df6bac4fa7d970652f1df76b683cd2f4003c941c63d517e59
-    // Italian:                 d392c49fdb700a24cd1fceb237c1f65dcc128f6b34a8aacb58b59384b5c648c2
-    // Japanese:                2eed0aef492291e061633d7ad8117f1a2b03eb80a29d0e4e3117ac2528d05ffd
-    // Korean:                  9e95f86c167de88f450f0aaf89e87f6624a57f973c67b516e338e8e8b8897f60
-    // Portuguese:              2685e9c194c82ae67e10ba59d9ea5345a23dc093e92276fc5361f6667d79cd3f
-    // Spanish:                 46846a5a0139d1e3cb77293e521c2865f7bcdb82c44e8d0a06a2cd0ecba48c0b
-    struct Case {
-        name: &'static str,
-        expected_hex_sha256: &'static str,
-        actual_hex_sha256: fn() -> String,
-    }
+    fn calculate_checksum(name: &str, words: &[&'static str; 2048]) -> String {
+        use sha2::{Digest, Sha256};
 
-    fn actual_checksum<L: WordlistProvider>() -> String {
         let mut digest = Sha256::new();
-        for &word in <L as WordlistProvider>::wordlist().words {
-            assert!(unicode_normalization::is_nfkd(word));
-            digest.update(format!("{}\n", word));
+
+        for (i, &word) in words.iter().enumerate() {
+            assert!(
+                unicode_normalization::is_nfkd(word),
+                "word list '{name}' is not NFKD normalized at index {i}",
+            );
+            digest.update(word.as_bytes());
+            digest.update(b"\n");
         }
+
         const_hex::encode(digest.finalize())
     }
 
     #[test]
     fn validate_word_list_checksums() {
+        // Check the sha256sum of the word lists.
+        //
+        // They are as follows in the [bips](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md):
+        //
+        // Chinese(simplified):     5c5942792bd8340cb8b27cd592f1015edf56a8c5b26276ee18a482428e7c5726
+        // Chinese(traditional):    417b26b3d8500a4ae3d59717d7011952db6fc2fb84b807f3f94ac734e89c1b5f
+        // Czech:                   7e80e161c3e93d9554c2efb78d4e3cebf8fc727e9c52e03b83b94406bdcc95fc
+        // English:                 2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda
+        // French:                  ebc3959ab7801a1df6bac4fa7d970652f1df76b683cd2f4003c941c63d517e59
+        // Italian:                 d392c49fdb700a24cd1fceb237c1f65dcc128f6b34a8aacb58b59384b5c648c2
+        // Japanese:                2eed0aef492291e061633d7ad8117f1a2b03eb80a29d0e4e3117ac2528d05ffd
+        // Korean:                  9e95f86c167de88f450f0aaf89e87f6624a57f973c67b516e338e8e8b8897f60
+        // Portuguese:              2685e9c194c82ae67e10ba59d9ea5345a23dc093e92276fc5361f6667d79cd3f
+        // Spanish:                 46846a5a0139d1e3cb77293e521c2865f7bcdb82c44e8d0a06a2cd0ecba48c0b
+        struct Case {
+            name: &'static str,
+            expected_hex_checksum: &'static str,
+            words: fn() -> &'static [&'static str; 2048],
+            word_of: fn(usize) -> &'static str,
+            index_of: fn(&str) -> Option<usize>,
+        }
+
         let mut cases: Vec<Case> = Vec::new();
 
         cases.push(Case {
             name: "english",
-            expected_hex_sha256: "2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda",
-            actual_hex_sha256: actual_checksum::<English>,
+            expected_hex_checksum: "2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda",
+            words: English::words,
+            word_of: <English as Language>::word_of,
+            index_of: <English as Language>::index_of,
         });
 
         #[cfg(feature = "chinese-simplified")]
         cases.push(Case {
             name: "chinese-simplified",
-            expected_hex_sha256: "5c5942792bd8340cb8b27cd592f1015edf56a8c5b26276ee18a482428e7c5726",
-            actual_hex_sha256: actual_checksum::<ChineseSimplified>,
+            expected_hex_checksum: "5c5942792bd8340cb8b27cd592f1015edf56a8c5b26276ee18a482428e7c5726",
+            words: ChineseSimplified::words,
+            word_of: <ChineseSimplified as Language>::word_of,
+            index_of: <ChineseSimplified as Language>::index_of,
         });
 
         #[cfg(feature = "chinese-traditional")]
         cases.push(Case {
             name: "chinese-traditional",
-            expected_hex_sha256: "417b26b3d8500a4ae3d59717d7011952db6fc2fb84b807f3f94ac734e89c1b5f",
-            actual_hex_sha256: actual_checksum::<ChineseTraditional>,
+            expected_hex_checksum: "417b26b3d8500a4ae3d59717d7011952db6fc2fb84b807f3f94ac734e89c1b5f",
+            words: ChineseTraditional::words,
+            word_of: <ChineseTraditional as Language>::word_of,
+            index_of: <ChineseTraditional as Language>::index_of,
         });
 
         #[cfg(feature = "czech")]
         cases.push(Case {
             name: "czech",
-            expected_hex_sha256: "7e80e161c3e93d9554c2efb78d4e3cebf8fc727e9c52e03b83b94406bdcc95fc",
-            actual_hex_sha256: actual_checksum::<Czech>,
+            expected_hex_checksum: "7e80e161c3e93d9554c2efb78d4e3cebf8fc727e9c52e03b83b94406bdcc95fc",
+            words: Czech::words,
+            word_of: <Czech as Language>::word_of,
+            index_of: <Czech as Language>::index_of,
         });
 
         #[cfg(feature = "french")]
         cases.push(Case {
             name: "french",
-            expected_hex_sha256: "ebc3959ab7801a1df6bac4fa7d970652f1df76b683cd2f4003c941c63d517e59",
-            actual_hex_sha256: actual_checksum::<French>,
+            expected_hex_checksum: "ebc3959ab7801a1df6bac4fa7d970652f1df76b683cd2f4003c941c63d517e59",
+            words: French::words,
+            word_of: <French as Language>::word_of,
+            index_of: <French as Language>::index_of,
         });
 
         #[cfg(feature = "italian")]
         cases.push(Case {
             name: "italian",
-            expected_hex_sha256: "d392c49fdb700a24cd1fceb237c1f65dcc128f6b34a8aacb58b59384b5c648c2",
-            actual_hex_sha256: actual_checksum::<Italian>,
+            expected_hex_checksum: "d392c49fdb700a24cd1fceb237c1f65dcc128f6b34a8aacb58b59384b5c648c2",
+            words: Italian::words,
+            word_of: <Italian as Language>::word_of,
+            index_of: <Italian as Language>::index_of,
         });
 
         #[cfg(feature = "japanese")]
         cases.push(Case {
             name: "japanese",
-            expected_hex_sha256: "2eed0aef492291e061633d7ad8117f1a2b03eb80a29d0e4e3117ac2528d05ffd",
-            actual_hex_sha256: actual_checksum::<Japanese>,
+            expected_hex_checksum: "2eed0aef492291e061633d7ad8117f1a2b03eb80a29d0e4e3117ac2528d05ffd",
+            words: Japanese::words,
+            word_of: <Japanese as Language>::word_of,
+            index_of: <Japanese as Language>::index_of,
         });
 
         #[cfg(feature = "korean")]
         cases.push(Case {
             name: "korean",
-            expected_hex_sha256: "9e95f86c167de88f450f0aaf89e87f6624a57f973c67b516e338e8e8b8897f60",
-            actual_hex_sha256: actual_checksum::<Korean>,
+            expected_hex_checksum: "9e95f86c167de88f450f0aaf89e87f6624a57f973c67b516e338e8e8b8897f60",
+            words: Korean::words,
+            word_of: <Korean as Language>::word_of,
+            index_of: <Korean as Language>::index_of,
         });
 
         #[cfg(feature = "portuguese")]
         cases.push(Case {
             name: "portuguese",
-            expected_hex_sha256: "2685e9c194c82ae67e10ba59d9ea5345a23dc093e92276fc5361f6667d79cd3f",
-            actual_hex_sha256: actual_checksum::<Portuguese>,
+            expected_hex_checksum: "2685e9c194c82ae67e10ba59d9ea5345a23dc093e92276fc5361f6667d79cd3f",
+            words: Portuguese::words,
+            word_of: <Portuguese as Language>::word_of,
+            index_of: <Portuguese as Language>::index_of,
         });
 
         #[cfg(feature = "spanish")]
         cases.push(Case {
             name: "spanish",
-            expected_hex_sha256: "46846a5a0139d1e3cb77293e521c2865f7bcdb82c44e8d0a06a2cd0ecba48c0b",
-            actual_hex_sha256: actual_checksum::<Spanish>,
+            expected_hex_checksum: "46846a5a0139d1e3cb77293e521c2865f7bcdb82c44e8d0a06a2cd0ecba48c0b",
+            words: Spanish::words,
+            word_of: <Spanish as Language>::word_of,
+            index_of: <Spanish as Language>::index_of,
         });
 
         for case in cases {
-            let actual = (case.actual_hex_sha256)();
+            let words = (case.words)();
+            assert_eq!(words.len(), 2048);
+
+            let actual_hex_checksum = calculate_checksum(case.name, words);
+
+            for (i, &word) in words.iter().enumerate() {
+                assert_eq!((case.word_of)(i), word);
+                assert_eq!((case.index_of)(word), Some(i));
+            }
+
             assert_eq!(
-                actual, case.expected_hex_sha256,
+                actual_hex_checksum, case.expected_hex_checksum,
                 "checksum mismatch for language '{}'",
                 case.name
             );