kotlin-bip39

Introduction
A concise implementation of BIP-0039 in Kotlin for Android.
Only about 30kB in total size. For comparison, the entire library is about 3X the size of this README file (because there are no dependencies)!
Motivation
Consequently, this library strives to use both idiomatic Kotlin and CharArrays whenever possible. It also aims to be concise and thoroughly tested. As a pure kotlin library, it probably also works outside of Android but that is not an explicit goal (Update: confirmed to also work on a Ktor server).
Plus, it uses a permissive MIT license and no dependencies beyond Kotlin's stdlib!
Getting Started
Gradle
Add dependencies (see Maven badge above for latest version number):
dependencies {
implementation "cash.z.ecc.android:kotlin-bip39:${latestVersion}"
}
repository {
mavenCentral()
}
Usage
This library prefers CharArrays over Strings for added security.
Note: If strings or lists are desired, it is very easy (but not recommended) to convert to/from a CharArray via String(charArray) or String(charArray).split(' ').
- Create new 24-word mnemonic phrase
import cash.z.ecc.android.bip39.Mnemonics.MnemonicCode
val mnemonicCode: MnemonicCode = MnemonicCode(WordCount.COUNT_24)
val seed: ByteArray = mnemonicCode.toSeed()
- Generate seed from existing mnemonic
val preExistingPhraseString = "scheme spot photo card baby mountain device kick cradle pact join borrow"
val preExistingPhraseChars = validPhraseString.toCharArray()
seed = MnemonicCode(preExistingPhraseChars).toSeed()
seed = MnemonicCode(preExistingPhraseString).toSeed()
- Generate seed with passphrase
val passphrase = "bitcoin".toCharArray()
mnemonicCode.toSeed(passphrase)
charArrayOf('z', 'c', 'a', 's', 'h').let { passphrase ->
mnemonicCode.toSeed(passphrase)
passphrase.fill('0')
}
- Generate raw entropy for a corresponding word count
val entropy: ByteArray = WordCount.COUNT_18.toEntropy()
val mnemonicCode = MnemonicCode(entropy)
MnemonicCode(WordCount.COUNT_18)
- Validate pre-existing or user-provided mnemonic
(NOTE: mnemonics generated by the library "from scratch" are valid, by definition)
mnemonicCode.validate()
for (word in mnemonicCode) {
println(word)
}
mnemonicCode.forEach { word ->
println(word)
}
mnemonicCode.clear()
Advanced Usage
These generated codes are compatible with kotlin's scoped resource usage
- Leverage
use to automatically clean-up after use
MnemonicCode(WordCount.COUNT_24).use {
}
- Generate original entropy that was used to create the mnemonic
(or throw exception if the mnemonic is invalid).
- Note: Calling this function only succeeds when the entropy is valid so it also can be used, indirectly, for validation. In fact, currently, it is called as part of the
MnemonicCode::validate() function.
val entropy: ByteArray = MnemonicCode(preExistingPhraseString).toEntropy()
- Mnemonics generated by the library do not need to be validated while creating the corresponding seed. That step can be skipped for a little added speed and security (because validation generates strings on the heap--which might get improved in a future release).
seed = MnemonicCode(WordCount.COUNT_24).toSeed(validate = false)
- Other languages are not yet supported but the API for them is in place. It accepts any
ISO 639-1 language code. For now, using it with anything other than "en" will result in an UnsupportedOperationException.
val mnemonicCode = MnemonicCode(WordCount.COUNT_24, languageCode = Locale.GERMAN.language)
val mnemonicCode = MnemonicCode(WordCount.COUNT_24, languageCode = Locale.ENGLISH.language)
Credits
- zcash/ebfull - Zcash core dev and BIP-0039 co-author who inspired creation of this library