Skip to content

docs: explain MnemonicSwift pitfall AFE-172 #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: explain MnemonicSwift pitfall AFE-172 #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8feb15b
docs: explain MnemonicSwift pitfall
HashMapsData2Value Jan 20, 2025
41531d8
fix: CI setup-swift name
HashMapsData2Value Jan 27, 2025
a647024
chore: swiftformat
HashMapsData2Value Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/swift-test-and-build.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ jobs:
uses: actions/checkout@v2

- name: Install Swift
uses: swift-actions/setup@v2
uses: swift-actions/setup-swift@v2
with:
swift-version: "5.9"

Expand Down
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,11 @@ cp git-hooks/* .git/hooks/

## How to Use

NOTE: In the example below we are using the library MnemonicSwift for BIP-39 support. Essentially it can be used to turn a mnemonic of 24 words (corresponding to an _entropy_) into a seed, by running it through a PBKDF2 in accordance with [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#from-mnemonic-to-seed). You are free to pick another library or use another method to produce the seed, but BIP-39 is an industry standard.
In the example below we are using the library MnemonicSwift for BIP-39 support. Essentially it can be used to turn a mnemonic of 24 words (corresponding to an _entropy_) into a derived seed, by running it through a PBKDF2 in accordance with [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki#from-mnemonic-to-seed). You are free to pick another library or use another method to produce the seed, but BIP-39 is an industry standard.

Note: MnemonicSwift can be used to randomly generate words and transform them into the derived seed. A derived seed can not be reversed into the mnemonic. Unfortunately, MnemonicSwift can currently not be used to to transform the 24 words into the entropy bytes (from which the bytes could then).
Copy link

@PhearZero PhearZero Jan 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, MnemonicSwift can currently not be used to to transform the 24 words into the entropy bytes

We may want to clarify here, since the seedBytes are deterministic. I may be misunderstanding but it seems to be a 1-1 for the Seed/Entropy to Mnemonic conversions.

It looks like the interface only supports hex encoding though, luckily it's attached to the response of deterministicSeedBytes. You can see the hex property being used in deterministicSeedString, that could be the input to mnemonicString

(from which the bytes could then).

Looks like this is missing some statements?

Copy link
Collaborator Author

@HashMapsData2Value HashMapsData2Value Jan 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a one way function:

Mnemonic --> "seedBytes"
seedBytes --//--> Mnemonics

Because of this line right here: https://github.com/Electric-Coin-Company/MnemonicSwift/blob/716a2c32ac2bbd8a1499ac834077df42b75edc85/MnemonicSwift/Mnemonic.swift#L135

The PBKDF2 involves hashing.

To contextualize what I wrote (which could probably be reworded and made clearer), look at this BIP39 NPM package: https://github.com/bitcoinjs/bip39/blob/a7ecbfe2e60d0214ce17163d610cad9f7b23140c/src/index.js#L38

They have:

  • Mnemonic to Seed
  • Mnemonic to Entropy
  • Entropy to Mnemonic

But there is no Seed to Mnemonic or Seed to Entropy.

Meanwhile the MnemonicSwift library doesn't even have Entropy <-> Mnemonic. It's all Mnemonic --> Determinstic SeedBytes.

Copy link

@PhearZero PhearZero Jan 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MnemonicSwift does have Entropy <-> Mnemonic via the string utilities. Looks like they return Data that has a toBitArray method

The initial guide on the project may be the culprit for this particular issue, maybe we go with something like the following:

  • Create Mnemonic and explain how to store it and use it in HDWallets
  • Convert deriving a seed from the Mnemonic using the library as optional step (may not be necessary?)

That way they can still handle the entropy bytes in a sane way then decide if they want to derive keys using MnemonicSwift. Deriving a seed as the first step leads to this footgun where they expect to recover the inputs of the seed.


That means that if you want to show the user their 24 words, you will need to store them as a string (and not as entropy bytes). From a security perspective it does not make things more or less secure.

To initialize a wallet (using MnemmonicSwift for BIP-39 support, which you can import using your own package manager) from a seed phrase:

Expand Down
2 changes: 1 addition & 1 deletion Tests/x-hd-wallet-apiTests/x-hd-wallet-apiTests.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
*/

import BigInt
@testable import x_hd_wallet_api
import MessagePack
import MnemonicSwift
@testable import x_hd_wallet_api
import XCTest

enum MyError: Error {
Expand Down