Improve mnemonic logging, add multi-language support, and enhance BIP39 test coverage

Author: bernardladenthin

src/main/java/net/ladenthin/bitcoinaddressfinder/BIP39Wordlist.java

@@ -0,0 +1,124 @@
+// @formatter:off
+/**
+ * Copyright 2025 Bernard Ladenthin [email protected]
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+// @formatter:on
+package net.ladenthin.bitcoinaddressfinder;
+
+import java.io.InputStream;
+
+public enum BIP39Wordlist {
+    
+    CHINESE_SIMPLIFIED("chinese_simplified.txt"),
+    CHINESE_TRADITIONAL("chinese_traditional.txt"),
+    CZECH("czech.txt"),
+    ENGLISH("english.txt"),
+    FRENCH("french.txt"),
+    ITALIAN("italian.txt"),
+    JAPANESE("japanese.txt"),
+    KOREAN("korean.txt"),
+    PORTUGUESE("portuguese.txt"),
+    RUSSIAN("russian.txt"),
+    SPANISH("spanish.txt"),
+    TURKISH("turkish.txt");
+    
+    /**
+     * Unicode character for an ideographic space (U+3000), used in East Asian languages such as Japanese.
+     * This space is wider than a standard space and is required for correct formatting of Japanese mnemonics.
+     */
+    public static final String IDEOGRAPHIC_SPACE = "\u3000";
+
+    /**
+     * Standard ASCII space character (U+0020).
+     * Used as the default separator between words in most BIP39 wordlists, such as English.
+     */
+    public static final String NORMAL_SPACE = " ";
+    
+    /**
+    * The name of the wordlist file associated with this BIP39 language.
+    * <p>
+    * This filename is used to locate the corresponding wordlist resource file in the
+    * {@code /mnemonic/wordlist/} directory of the classpath (e.g., {@code english.txt}).
+    */
+    private final String fileName;
+    
+    /**
+     * Constructs a BIP39 wordlist enum constant with the associated filename.
+     *
+     * @param fileName the name of the wordlist file (e.g., {@code "english.txt"}), which is used
+     *                 to load the corresponding wordlist resource from the classpath
+     */
+    BIP39Wordlist(String fileName) {
+        this.fileName = fileName;
+    }
+
+    /**
+    * Loads the BIP39 wordlist file as an {@link InputStream} for this language.
+    * <p>
+    * The wordlist file is expected to be located in the resource path:
+    * {@code /mnemonic/wordlist/{fileName}}, where {@code fileName} corresponds
+    * to the file name associated with the enum constant (e.g. {@code english.txt}).
+    * <p>
+    * This method is used to initialize a {@link MnemonicCode} instance with the correct
+    * wordlist for a given language.
+    *
+    * @return the input stream of the wordlist file for this language, or {@code null}
+    *         if the resource is not found.
+    */
+    public InputStream getWordListStream() {
+        return BIP39Wordlist.class.getResourceAsStream("/mnemonic/wordlist/" + fileName);
+    }
+    
+    /**
+     * Converts a filename-like language name into the corresponding {@link BIP39Wordlist} enum constant.
+     * <p>
+     * The input typically comes from wordlist filenames in the format {@code mnemonic/wordlist/{language}.txt},
+     * for example:
+     * <ul>
+     *   <li>{@code chinese_simplified.txt} → {@code CHINESE_SIMPLIFIED}</li>
+     *   <li>{@code english.txt} → {@code ENGLISH}</li>
+     * </ul>
+     * <p>
+     * To perform the conversion, this method:
+     * <ul>
+     *   <li>Converts the name to upper case</li>
+     *   <li>Replaces hyphens with underscores (if any)</li>
+     * </ul>
+     * This enables consistent mapping between file-based wordlist identifiers and enum values.
+     *
+     * @param name the lowercase filename-based language identifier, e.g. {@code "english"} or {@code "chinese_simplified"}
+     * @return the corresponding {@link BIP39Wordlist} enum constant
+     * @throws IllegalArgumentException if no matching enum exists
+     */
+    public static BIP39Wordlist fromLanguageName(String name) {
+        return valueOf(name.toUpperCase().replace('-', '_'));
+    }
+    
+    /**
+    * Returns the word separator used in the mnemonic phrase for the given language.
+    * <p>
+    * Most languages use a single space (" ") as the separator between words.
+    * However, Japanese uses the IDEOGRAPHIC SPACE (U+3000) to conform with the official BIP39 specification.
+    *
+    * @return the word separator specific to the language
+    */
+    public String getSeparator() {
+        if (this == JAPANESE) {
+            return IDEOGRAPHIC_SPACE;
+        }
+        return NORMAL_SPACE;
+    }
+}

src/main/java/net/ladenthin/bitcoinaddressfinder/ConsumerJava.java

@@ -261,7 +261,23 @@ public boolean containsAddress(ByteBuffer threadLocalReuseableByteBuffer, byte[]
     }
 
     /**
-     * Try to log safe informations which may not thrown an exception.
+     * Logs key information in a safe and robust way to avoid losing critical data
+     * in case of a runtime exception.
+     * <p>
+     * The primary goal of this method is to ensure that if a valid secret key (i.e., a hit)
+     * is found, its corresponding BigInteger value is immediately logged. Since logging a
+     * BigInteger is unlikely to fail, this is the first and most essential piece of information.
+     * <p>
+     * Logging additional details such as the uncompressed/compressed public keys and their
+     * hash160 values may theoretically trigger runtime exceptions (e.g., due to malformed data
+     * or encoding issues). To mitigate the risk of losing the crucial secret value in such rare
+     * cases, it is logged first.
+     * <p>
+     * All logs are prefixed consistently with {@code HIT_SAFE_PREFIX} to make hits easily searchable.
+     *
+     * @param publicKeyBytes         the public key bytes wrapper
+     * @param hash160Uncompressed    the hash160 of the uncompressed public key
+     * @param hash160Compressed      the hash160 of the compressed public key
      */
     private void safeLog(PublicKeyBytes publicKeyBytes, byte[] hash160Uncompressed, byte[] hash160Compressed) {
         logger.info(HIT_SAFE_PREFIX +"publicKeyBytes.getSecretKey(): " + publicKeyBytes.getSecretKey());

src/main/java/net/ladenthin/bitcoinaddressfinder/KeyUtility.java

@@ -18,6 +18,7 @@
 // @formatter:on
 package net.ladenthin.bitcoinaddressfinder;
 
+import java.io.IOException;
 import java.math.BigInteger;
 import java.nio.ByteBuffer;
 import java.util.Arrays;
@@ -43,8 +44,6 @@ public class KeyUtility {
     @NonNull
     public final Network network;
     public final ByteBufferUtility byteBufferUtility;
-    
-    private final MnemonicCode mnemonicCode = MnemonicCode.INSTANCE;
 
     public KeyUtility(Network network, ByteBufferUtility byteBufferUtility) {
         this.network = network;
@@ -148,13 +147,37 @@ public String createKeyDetails(ECKey key) throws MnemonicException.MnemonicLengt
         String logPublicKeyHash160 = "publicKeyHash160Hex: [" + publicKeyHash160Hex + "]";
         String logPublicKeyHash160Base58 = "publicKeyHash160Base58: [" + publicKeyHash160Base58 + "]";
         String logCompressed = "Compressed: [" + key.isCompressed() + "]";
-        List<String> mnemonic = mnemonicCode.toMnemonic(privateKeyBytes);
-        String logMnemonic = "Mnemonic: " + mnemonic.toString();
+        String logMnemonic = createMnemonics(privateKeyBytes);
 
         String space = " ";
         return logprivateKeyBigInteger + space + logprivateKeyBytes + space + logprivateKeyHex + space + logWiF + space + logPublicKeyAsHex + space + logPublicKeyHash160 + space + logPublicKeyHash160Base58 + space + logCompressed + space + logMnemonic;
     }
 
+    public String createMnemonics(byte[] privateKeyBytes) {
+        StringBuilder logMnemonic = new StringBuilder("Mnemonic:");
+        for (BIP39Wordlist wordList : BIP39Wordlist.values()) {
+            try {
+                MnemonicCode mnemonicCode = new MnemonicCode(wordList.getWordListStream(), null);
+                List<String> mnemonics = mnemonicCode.toMnemonic(privateKeyBytes);
+                logMnemonic.append(" ");
+                logMnemonic.append(wordList.name());
+                logMnemonic.append(": [");
+                boolean first = true;
+                for(String mnemonic : mnemonics) {
+                    if (!first) {
+                        logMnemonic.append(wordList.getSeparator());
+                    }
+                    logMnemonic.append(mnemonic);
+                    first = false;
+                }
+                logMnemonic.append("]");
+            } catch (IOException | IllegalArgumentException ex) {
+                throw new RuntimeException(ex);
+            }
+        }
+        return logMnemonic.toString();
+    }
+
     // <editor-fold defaultstate="collapsed" desc="ByteBuffer LegacyAddress conversion">
     public ByteBuffer addressToByteBuffer(LegacyAddress address) {
         ByteBuffer byteBuffer = byteBufferUtility.byteArrayToByteBuffer(address.getHash());