naming: SEED is used for different things

[SCBuergel]

The word seed is used for different things which leads to confusion for new users:

1. The entropy that is passed to mnemonic-new is called seed.
2. It is used for the value that is more commonly called seed, e.g. derived via mnemonic-to-seed which might get a password and thus is not the same as the seed above.

I propose to adjust the documentation for the former and call the input to mnemonic-new not SEED but entropy.

[thecodefactory]

Thanks for noting. Perhaps bx seed could use a new name as well, since it's generating entropy.

[evoskuil]

Originally, based on Electrum and before bip-39 these were in fact the same, the seed is round-tripped. BIP39 formalized a one-way multi-“seed” derivation scheme. But these are not properly a seed. The seed is the single starting point of a tree. Also, the term seed is used in many libbitcoin commands in this context. So while it’s a reasonable concern, I would suggest addressing it by renaming the other use of seed in this limited context. Otherwise there are a lot of things that need to be renamed, and a new inconsistency.

[SCBuergel]

As someone who is digging through the libbitcoin workflow for the first time I find this highly confusing and can only encourage to do a cleanup even if that means a lot of things need to be renamed.

[evoskuil]

Pull requests are always welcome.

[evoskuil]

After reviewing the integrated documentation and other commands I notice that we are consistently using the term "entropy" in the comments for [SEED] on command lines, but the bx seed command should also document this is "entropy" for consistency. We could certainly rename the seed command to entropy and rename all of the other command parameters accordingly. But if we do that the BIP-39 commands will be confusing because the BIP-39 commands would map to entropy and have no "seed". This would be inconsistent, so we would have to also rename mnemonic-to-seed to mnemonic-to-entropy. So to resolve this inconsistency clearly we need to rename two commands and rename all [SEED] parameters to [ENTROPY] (leaving "seed" terminology to BIP39 commands exclusively), and update all comments.

[kenorb]

I would rename:

• mnemonic-new -> entropy-to-mnemonic (BIP39 Mnemonic)

as per Mnemonic Code Converter site, where 'BIP39 Mnemonic' are words, and Entropy (Show entropy details) is hex representation of mnemonic words. I've tested and it produces the same results.

As per this logic, mnemonic-to-seed shouldn't be renamed to mnemonic-to-entropy (as per above comment), because it produces seed. You can test that at the above linked page (mnemonic words will produce BIP39 Seed).

[evoskuil]

A pending libbitcoin-system PR has redesigned all three mnemonics implementations, with terminology consistent with: https://github.com/libbitcoin/libbitcoin-system/wiki/Mnemonics-Unraveled

BX updates forthcoming.