BIP39 Java

Java 17 library and CLI for generating, validating, and converting BIP39 English mnemonics

---

Project Overview

This repository provides the following capabilities for English BIP39 mnemonics:

• Convert entropy to a mnemonic sentence
• Convert a mnemonic sentence back to entropy
• Derive a 64-byte seed from a mnemonic and passphrase
• Validate mnemonic structure, word membership, and checksum
• Normalize compatibility input explicitly
• Generate entropy with a secure random source
• Use the implementation from a Java CLI

Scope

This repository targets BIP39 only.

• The supported wordlist is English only
• BIP32, derivation paths, address generation, and full wallet UX are out of scope
• mnemonicToSeed intentionally does not validate mnemonic semantic correctness by itself

Requirements

• Java 17
• Maven 3.9.6 or later

The repository includes the Maven Wrapper, so ./mvnw is the preferred way to run builds.

Setup

./mvnw -B -ntp test

You can also use the provided Makefile.

make test
make verify

Main targets:

• make test - Run unit tests
• make verify - Run Spotless, SpotBugs, and tests
• make format - Apply Spotless formatting
• make lint - Run Spotless and SpotBugs checks
• make clean - Remove build outputs
• make cli ARGS="..." - Run the CLI

CLI

The CLI entry point is src/main/java/com/example/bip39/cli/Bip39Cli.java.

Show help

make cli ARGS="help"

Generate a 12-word mnemonic

make cli ARGS="generate --words 12"

Generate a 24-word mnemonic and print entropy too

make cli ARGS="generate --words 24 --show-entropy"

Convert a mnemonic back to entropy

make cli ARGS='to-entropy "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"'

Derive a seed from a mnemonic and passphrase

make cli ARGS='to-seed --passphrase TREZOR "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"'

Validate a mnemonic

make cli ARGS='validate "abandon ability able"'

Normalize compatibility input

make cli ARGS=$'normalize "  ABANDON\tabandon\nABANDON\rABOUT  "'

Run the JAR directly

./mvnw -B -ntp -DskipTests package
java -jar target/bip39-java-0.1.0-SNAPSHOT.jar help

Java API

The public API is defined in src/main/java/com/example/bip39/api/Bip39Service.java.

import com.example.bip39.api.Bip39Service;
import com.example.bip39.api.DefaultBip39Service;
import java.util.HexFormat;

Bip39Service service = new DefaultBip39Service();

byte[] entropy = new byte[16];
String mnemonic = service.entropyToMnemonic(entropy);
byte[] roundTrip = service.mnemonicToEntropy(mnemonic);
byte[] seed = service.mnemonicToSeed(mnemonic, "TREZOR");

System.out.println(mnemonic);
System.out.println(HexFormat.of().formatHex(roundTrip));
System.out.println(seed.length);
System.out.println(service.validateMnemonic(mnemonic));

Implementation Notes

Strict parsing APIs

mnemonicToEntropy and validateMnemonic are strict.

• They only accept normalized lowercase English mnemonics
• Tabs, newlines, repeated spaces, and leading or trailing spaces fail as-is
• If needed, run the input through the normalization layer first

Compatibility normalization

The compatibility input adapter lives in src/main/java/com/example/bip39/normalize/MnemonicInputNormalizer.java.

It performs the following steps:

• Trim leading and trailing whitespace
• Replace tabs, newlines, and carriage returns with SPACE
• Collapse repeated spaces to a single SPACE
• Apply Unicode NFKD
• Lowercase for the English profile

Seed derivation

mnemonicToSeed follows the BIP39 contract.

• It returns 64 bytes
• It uses NFKD + UTF-8 + PBKDF2-HMAC-SHA512
• It does not automatically validate mnemonic semantic correctness

Call validateMnemonic first if your application requires validation before seed derivation.

Testing

This repository includes tests for:

• English wordlist and pinned asset integrity
• Bit-level conversion helpers
• Official entropyToMnemonic vectors
• Official mnemonicToEntropy vectors
• Official mnemonicToSeed vectors
• Fixed failure cases and error priority
• Compatibility normalization
• Entropy generation boundaries
• CLI behavior

Structure

.
├── src/main/java/com/example/bip39/
│   ├── api/                          # Public API
│   ├── bit/                          # Bit-level helpers
│   ├── cli/                          # CLI
│   ├── crypto/                       # SHA-256 / PBKDF2-HMAC-SHA512
│   ├── entropy/                      # SecureRandom-based entropy generation
│   ├── error/                        # Error codes and exceptions
│   ├── integration/                  # Thin UI / external integration helpers
│   ├── model/                        # ValidationResult and related types
│   ├── normalize/                    # Compatibility normalization
│   ├── parser/                       # Strict mnemonic parsing
│   ├── util/                         # Constants
│   └── wordlist/                     # English wordlist handling
├── src/main/resources/bip39/         # Pinned normative assets
├── src/test/java/com/example/bip39/  # Tests
├── Makefile
├── pom.xml
└── README.md

Security Notes

• Generated mnemonics and seeds are secrets
• Do not log them, screenshot them, or commit them to source control
• All command examples in this README assume Java 17

License

Apache License 2.0 - see LICENSE.