seed-phrases-for-stellar 0.1

Utility for generating Stellar accounts from BIP39/Electrum seed phrases

<!---
[](https://travis-ci.org/reverbel/seed-phrases-for-stellar)
--->
seed-phrases-for-stellar
========================

Command-line script and Python library package for generating Stellar accounts
from BIP39/Electrum seed phrases

This software performs deterministic generation of Stellar account keys
from mnemonic seed phrases. Each seed phrase may optionally be extended with
custom words that play the role of an additional passphrase.
seed-phrases-for-stellar accepts two kinds of mnemonic seed phrases:
* seed phrases that comply with the BIP-0039 specification
(https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki), and
* seed phrases generated by the Electrum Bitcoin wallet (https://electrum.org/).

Since these are the two major standards for wallet seed phrases,
seed-phrases-for-stellar accepts nearly all mnemonic phrases generated by
cryptocurrency wallets. Note, however, that this software does NOT perform
random generation of high-entropy seed phrases. Its main purpose is to allow
cryptocurrency wallet users to derive Stellar account keys from high-entropy
seed phrases that they already have and that probably were created by their
wallets.

By following either BIP-0039 or Electrum, `seed-phrases-for-stellar`
derives a binary seed from a mnemonic seed phrase. Then it derives
Stellar keys from the binary seed, as specified by SEP-0005
(https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0005.md),
SLIP-0010 (https://github.com/satoshilabs/slips/blob/master/slip-0010.md) and
BIP-0044 (https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki).

# Installation
pip install seed-phrases-for-stellar

# Command-line usage

seed-phrase-to-stellar-keys -h

produces the following output:

usage: seed-phrase-to-stellar-keys [-h] [-m] [-s] [-l] [-v] [-F] [language]

positional arguments:
language language for BIP-0039 seed phrases (default: english)

optional arguments:
-h, --help show this help message and exit
-m, --multiple_accs show keys for ten accounts
-s, --show_seed show the standard BIP-0039 or Electrum seed
-l, --list_languages list available languages for BIP-0039 phrases and exit
-v, --version show program's version number and exit
-F, --force force keypair generation from phrase of unknown type

## Examples

#### 1. Key derivation from a BIP-0039 seed phrase
```
$ seed-phrase-to-stellar-keys

Enter the seed phrase:
illness spike retreat truth genius clock brain pass fit cave bargain toe

Enter optional custom words (passphrase) to extend the seed phrase:


seed phrase: 'illness spike retreat truth genius clock brain pass fit cave bargain toe'
custom words: ''
seed phrase type: BIP-0039

primary account:
public key: GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOOHSUJUJ6
private seed: SBGWSG6BTNCKCOB3DIFBGCVMUPQFYPA2G4O34RMTB343OYPXU5DJDVMN

```

#### 2. Same example as above, now showing the BIP-0039 seed and ten accounts
```
$ seed-phrase-to-stellar-keys -s

Enter the seed phrase:
illness spike retreat truth genius clock brain pass fit cave bargain toe
illness spike retreat truth genius clock brain pass fit cave bargain toe

Enter optional custom words (passphrase) to extend the seed phrase:


seed phrase: 'illness spike retreat truth genius clock brain pass fit cave bargain toe'
custom words: ''
seed phrase type: BIP-0039
BIP-0039 seed: e4a5a632e70943ae7f07659df1332160937fad82587216a4c64315a0fb39497ee4a01f76ddab4cba68147977f3a147b6ad584c41808e8238a07f6cc4b582f186

account #0: ------------- this is the primary account --------------
public key: GDRXE2BQUC3AZNPVFSCEZ76NJ3WWL25FYFK6RGZGIEKWE4SOOHSUJUJ6
private seed: SBGWSG6BTNCKCOB3DIFBGCVMUPQFYPA2G4O34RMTB343OYPXU5DJDVMN

account #1:
public key: GBAW5XGWORWVFE2XTJYDTLDHXTY2Q2MO73HYCGB3XMFMQ562Q2W2GJQX
private seed: SCEPFFWGAG5P2VX5DHIYK3XEMZYLTYWIPWYEKXFHSK25RVMIUNJ7CTIS

account #2:
public key: GAY5PRAHJ2HIYBYCLZXTHID6SPVELOOYH2LBPH3LD4RUMXUW3DOYTLXW
private seed: SDAILLEZCSA67DUEP3XUPZJ7NYG7KGVRM46XA7K5QWWUIGADUZCZWTJP

account #3:
public key: GAOD5NRAEORFE34G5D4EOSKIJB6V4Z2FGPBCJNQI6MNICVITE6CSYIAE
private seed: SBMWLNV75BPI2VB4G27RWOMABVRTSSF7352CCYGVELZDSHCXWCYFKXIX

account #4:
public key: GBCUXLFLSL2JE3NWLHAWXQZN6SQC6577YMAU3M3BEMWKYPFWXBSRCWV4
private seed: SCPCY3CEHMOP2TADSV2ERNNZBNHBGP4V32VGOORIEV6QJLXD5NMCJUXI

account #5:
public key: GBRQY5JFN5UBG5PGOSUOL4M6D7VRMAYU6WW2ZWXBMCKB7GPT3YCBU2XZ
private seed: SCK27SFHI3WUDOEMJREV7ZJQG34SCBR6YWCE6OLEXUS2VVYTSNGCRS6X

account #6:
public key: GBY27SJVFEWR3DUACNBSMJB6T4ZPR4C7ZXSTHT6GMZUDL23LAM5S2PQX
private seed: SDJ4WDPOQAJYR3YIAJOJP3E6E4BMRB7VZ4QAEGCP7EYVDW6NQD3LRJMZ

account #7:
public key: GAY7T23Z34DWLSTEAUKVBPHHBUE4E3EMZBAQSLV6ZHS764U3TKUSNJOF
private seed: SA3HXJUCE2N27TBIZ5JRBLEBF3TLPQEBINP47E6BTMIWW2RJ5UKR2B3L

account #8:
public key: GDJTCF62UUYSAFAVIXHPRBR4AUZV6NYJR75INVDXLLRZLZQ62S44443R
private seed: SCD5OSHUUC75MSJG44BAT3HFZL2HZMMQ5M4GPDL7KA6HJHV3FLMUJAME

account #9:
public key: GBTVYYDIYWGUQUTKX6ZMLGSZGMTESJYJKJWAATGZGITA25ZB6T5REF44
private seed: SCJGVMJ66WAUHQHNLMWDFGY2E72QKSI3XGSBYV6BANDFUFE7VY4XNXXR

```

#### 3. Key derivation from an Electrum seed phrase, showing the Electrum seed
```
$ seed-phrase-to-stellar-keys -s

Enter the seed phrase:
write long buzz fork domain forget punch child entry object load north

Enter optional custom words (passphrase) to extend the seed phrase:


seed phrase: 'write long buzz fork domain forget punch child entry object load north'
custom words: ''
seed phrase type: Electrum standard
Electrum seed: 4eb18cab8eaa91a4486bb0ef9ad814f3e40f946235ef7996c8e7b2a4186fdde3a841b501a12728d6ffe323c8272957e35334c684576087dee710d09d518bd9b2

primary account:
public key: GAF273TDSINGAMNL7OCMFYIBTUIRPFSXUQ6EYPJMVOOCQ3Z5ICSIBBLD
private seed: SCCK6VFCREX4BFIHIHYX2O6AIIRSEID7HOI47YPB5XNSYLG7SI45D5RT

```
Note that `seed-phrase-to-stellar-keys` automatically detects the seed phrase
type. Electrum seed phrases have specific subtypes: old (pre 2.0) Electrum,
standard (Electrum 2.0 or later), segwit, and 2FA. In addition to
distinguishing BIP-0039 seed phrases from Electrum seed phrases,
`seed-phrase-to-stellar-keys` shows the specific subtype of an Electrum seed
phrase. This information has no importance for the derivation of Stellar
account keys, but it may be helpful to prevent typos from going unnoticed.

#### 4. Key derivation from an Electrum segwit seed phrase, showing also the Electrum seed:

```
$ seed-phrase-to-stellar-keys -s

Enter the seed phrase:
nerve museum sort subject call unable double rally wheat drip tiger kitchen

Enter optional custom words (passphrase) to extend the seed phrase:


seed phrase: 'nerve museum sort subject call unable double rally wheat drip tiger kitchen'
custom words: ''
seed phrase type: Electrum segwit
Electrum seed: 68d1e21953e934a7ff2f7d852e4a05d9fd12fbb86e1c49fb822c214a5ce57ee64c714b447ce23edb878cdc99d8adf4e29c3f9c9d237986ef9ac557fa60f37965

primary account:
public key: GBJM3LGVJLCM3YNH2IZ3I6U2HTAGKQVFITWWM5X3T4VE5CGNSDAKKG6K
private seed: SALX6MN3OKWH6WIDYOUJTXOVJUWCYBHP7JNQUFUUD56WOATQVKKDMADE

```

#### 5. Key derivation from a phrase that is both a valid BIP-0039 seed phrase and an Electrum seed

BIP-0039 and Electrum seed phrases are not disjoint sets. In the case of a
phrase that belongs to both sets, `seed-phrase-to-stellar-keys` performs the
BIP-0039 derivation and, if invoked with the '`-s`' option (as in the example
below), shows the BIP-0039 seed.
```
$ seed-phrase-to-stellar-keys -s

Enter the seed phrase:
ivory hollow predict error front energy invite differ general depart repeat prize

Enter optional custom words (passphrase) to extend the seed phrase:
s0me p4ssphr4se

seed phrase: 'ivory hollow predict error front energy invite differ general depart repeat prize'
custom words: 's0me p4ssphr4se'
seed phrase type: BIP-0039 and Electrum standard
BIP-0039 seed: c1a65a79988348c001593e22737f285dc49c054b2265394c5dbddf296c89bf5f0af5f8b3b6e231b8711314da6894a816320fb5cedbd99484f9da81dd9a261812

primary account:
public key: GDNRZZR5GU6QG5KQUWFE3WWD5L57JQAYC7CBLOIP5GQR2X7C4ZZJBWDR
private seed: SDUNJQZRBESMERRIJCSIOKCS7K4VQKGM5BT6CLUX7FEQ3STVUAHIVH2V

```