SLIP-39 Wallet "Seed" Generation & Backup

To obtain the Seed in BIP-39 format, with its original "entropy" backed up using SLIP-39 (supporting any BIP-39 hardware wallet, and recoverable from the Mnemonic cards using SLIP-39), use the --using-bip39 option:

$ slip39 --using-bip39 Personal-BIP-39
2022-11-22 05:47:13 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0x927232296120343A89DeAb15F108a420087a2Ef3
2022-11-22 05:47:13 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qgs6xg5kvrrxp4579y22a4tf0d8me4dslwxjr9x
2022-11-22 05:47:15 slip39.layout    Writing SLIP39 backup for BIP-39-encoded wallet for 'Personal-BIP-39' to:\
Personal-BIP-39-2022-11-22+05.47.15-ETH-0x927232296120343A89DeAb15F108a420087a2Ef3.pdf

This is the best approach, if you want a new Seed and need to support a BIP-39-only Hardware Wallet. (If you already have a BIP-39 Mnemonic Phrase, see [[Pipelining Backup of a BIP-39 Mnemonic Phrase]])

The Trezor hardware wallet natively supports the input of SLIP-39 Mnemonics. However, most software wallets do not (yet) support SLIP-39. So, how do we load the Crypto wallets produced from our Seed into software wallets such as the Metamask plugin or the Brave browser, for example?

The slip39.gui (and the macOS/win32 SLIP-39.App) support output of standard BIP-38 encrypted wallets for Bitcoin-like cryptocurrencies such as BTC, LTC and DOGE. It also outputs encrypted Ethereum JSON wallets for ETH. Here is how to produce them (from a test secret Seed; exclude --secret ffff... for yours!):

slip39 -c ETH -c BTC -c DOGE -c LTC --secret ffffffffffffffffffffffffffffffff \
--no-card --wallet password --wallet-hint 'bad:pass...' 2>&1

2024-11-15 16:10:30 slip39           It is recommended to not use '-s|--secret <hex>'; specify '-' to read from input
2024-11-15 16:10:30 slip39           It is recommended to not use '-w|--wallet <password>'; specify '-' to read from input
2024-11-15 16:10:30 slip39           Generated 128-bit SLIP-39 Mnemonics w/ identifier 24706 requiring 2 of 4 (extendable) groups to recover
2024-11-15 16:10:30 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1
2024-11-15 16:10:30 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1q9yscq3l2yfxlvnlk3cszpqefparrv7tk24u6pl
2024-11-15 16:10:30 slip39.layout    DOGE   m/44'/3'/0'/0/0     : DN8PNN3dipSJpLmyxtGe4EJH38EhqF8Sfy
2024-11-15 16:10:30 slip39.layout    LTC    m/84'/2'/0'/0/0     : ltc1qe5m2mst9kjcqtfpapaanaty40qe8xtusmq4ake
2024-11-15 16:10:36 slip39.layout    Writing SLIP39-encoded wallet for 'SLIP39' to: SLIP39-2024-11-15+16.10.33-ETH-0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1.pdf

And what they look like:

To recover your real SLIP-39 Seed Entropy and print wallets, use the SLIP-39 App's "Recover" Controls, or to do so on the command-line, use slip39-recover:

slip39-recovery -v \
--mnemonic "material leaf acrobat romp charity capital omit skunk change firm eclipse crush fancy best tracks flip grownup plastic chew peanut" \
--mnemonic "material leaf beard romp disaster duke flame uncover group slice guest blue gums duckling total suitable trust guitar payment platform" \
    2>&1

2024-11-15 16:12:43 slip39.recovery  Recovered 128-bit Encrypted SLIP-39 Seed Entropy using 2 groups comprising 2 mnemonics
2024-11-15 16:12:43 slip39.recovery  Seed decoded from SLIP-39 Mnemonics w/ no passphrase
2024-11-15 16:12:43 slip39.recovery  Recovered SLIP-39 secret; To re-generate SLIP-39 wallet, send it to: python3 -m slip39 --secret -
ffffffffffffffffffffffffffffffff

You can run this as a command-line pipeline. Here, we use some SLIP-39 Mnemonics that encode the ffff... Seed Entropy; note that the wallets match those output above:

slip39-recovery \
--mnemonic "material leaf acrobat romp charity capital omit skunk change firm eclipse crush fancy best tracks flip grownup plastic chew peanut" \
--mnemonic "material leaf beard romp disaster duke flame uncover group slice guest blue gums duckling total suitable trust guitar payment platform" \
| slip39 -c ETH -c BTC -c DOGE -c LTC --secret - \
--no-card --wallet password --wallet-hint 'bad:pass...' \
    2>&1

2024-11-15 16:13:26 slip39           It is recommended to not use '-w|--wallet <password>'; specify '-' to read from input
2024-11-15 16:13:26 slip39           Generated 128-bit SLIP-39 Mnemonics w/ identifier 14481 requiring 2 of 4 (extendable) groups to recover
2024-11-15 16:13:26 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1
2024-11-15 16:13:26 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1q9yscq3l2yfxlvnlk3cszpqefparrv7tk24u6pl
2024-11-15 16:13:26 slip39.layout    DOGE   m/44'/3'/0'/0/0     : DN8PNN3dipSJpLmyxtGe4EJH38EhqF8Sfy
2024-11-15 16:13:26 slip39.layout    LTC    m/84'/2'/0'/0/0     : ltc1qe5m2mst9kjcqtfpapaanaty40qe8xtusmq4ake
2024-11-15 16:13:31 slip39.layout    Writing SLIP39-encoded wallet for 'SLIP39' to: SLIP39-2024-11-15+16.13.29-ETH-0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1.pdf

While the SLIP-39 Seed is not cryptocurrency-specific (any wallet for any cryptocurrency can be derived from it), each type of cryptocurrency has its own standard derivation path (eg. m/44'/3'/0'/0/0 for DOGE), and its own address representation (eg. Bech32 at m/84'/0'/0'/0/0 for BTC eg. bc1qcupw7k8enymvvsa7w35j5hq4ergtvus3zk8a8s).

When you import your SLIP-39 Seed into a Trezor, you gain access to all derived HD cryptocurrency wallets supported directly by that hardware wallet, and indirectly, to any coin and/or blockchain network supported by any wallet software (eg. Metamask).

The full command-line argument synopsis for slip39 is:

slip39 --help 2>&1                | sed 's/^/: /' # (just for output formatting)

usage: slip39 [-h] [-v] [-q] [-o OUTPUT] [-t THRESHOLD] [-g GROUP] [-f FORMAT]
              [-c CRYPTOCURRENCY] [-p PATH] [-j JSON] [-w WALLET]
              [--wallet-hint WALLET_HINT] [--wallet-format WALLET_FORMAT]
              [-s SECRET] [-e ENTROPY] [--show] [--no-show] [--bits BITS]
              [--using-bip39] [--passphrase PASSPHRASE] [-C CARD] [--no-card]
              [--paper PAPER] [--cover] [--no-cover] [--text]
              [--watermark WATERMARK] [--double-sided] [--no-double-sided]
              [--single-sided]
              [names ...]

Create and output SLIP-39 encoded Seeds and Paper Wallets to a PDF file.

positional arguments:
  names                 Account names to produce; if --secret Entropy is
                        supplied, only one is allowed.

options:
  -h, --help            show this help message and exit
  -v, --verbose         Display logging information.
  -q, --quiet           Reduce logging output.
  -o OUTPUT, --output OUTPUT
                        Output PDF to file or '-' (stdout); formatting w/
                        name, date, time, crypto, path, address allowed
  -t THRESHOLD, --threshold THRESHOLD
                        Number of groups required for recovery (default: half
                        of groups, rounded up)
  -g GROUP, --group GROUP
                        A group name[[<require>/]<size>] (default: <size> = 1,
                        <require> = half of <size>, rounded up, eg.
                        'Frens(3/5)' ).
  -f FORMAT, --format FORMAT
                        Specify crypto address formats: legacy, segwit,
                        bech32; default: ETH:legacy, BTC:bech32, LTC:bech32,
                        DOGE:legacy, BSC:legacy, XRP:legacy
  -c CRYPTOCURRENCY, --cryptocurrency CRYPTOCURRENCY
                        A crypto name and optional derivation path (eg.
                        '../<range>/<range>'); defaults: ETH:m/44'/60'/0'/0/0,
                        BTC:m/84'/0'/0'/0/0, LTC:m/84'/2'/0'/0/0,
                        DOGE:m/44'/3'/0'/0/0, BSC:m/44'/60'/0'/0/0,
                        XRP:m/44'/144'/0'/0/0
  -p PATH, --path PATH  Modify all derivation paths by replacing the final
                        segment(s) w/ the supplied range(s), eg. '.../1/-'
                        means .../1/[0,...)
  -j JSON, --json JSON  Save an encrypted JSON wallet for each Ethereum
                        address w/ this password, '-' reads it from stdin
                        (default: None)
  -w WALLET, --wallet WALLET
                        Produce paper wallets in output PDF; each wallet
                        private key is encrypted this password (use
                        --wallet="" for empty password)
  --wallet-hint WALLET_HINT
                        Paper wallets password hint
  --wallet-format WALLET_FORMAT
                        Paper wallet size; half, third, quarter or
                        '(<h>,<w>),<margin>' (default: quarter)
  -s SECRET, --secret SECRET
                        Use the supplied BIP-39 Mnemonic or 128-, 256- or
                        512-bit hex value as the secret seed; '-' reads it
                        from stdin (eg. output from slip39.recover)
  -e ENTROPY, --entropy ENTROPY
                        Additional entropy; if 0x... hex, used directly;
                        otherwise, UTF-8 stretched via SHA-512
  --show                Show derivation of master seed
  --no-show             Disable showing derivation of master seed
  --bits BITS           Ensure that the seed is of the specified bit length;
                        128, 256, 512 supported.
  --using-bip39         Generate Seed from secret Entropy using BIP-39
                        generation algorithm (encode as BIP-39 Mnemonics,
                        encrypted using --passphrase)
  --passphrase PASSPHRASE
                        Encrypt the master secret w/ this passphrase, '-'
                        reads it from stdin (default: None/'')
  -C CARD, --card CARD  Card size; business, credit, index, half, third,
                        quarter, photo or '(<h>,<w>),<margin>' (default:
                        business)
  --no-card             Disable PDF SLIP-39 mnemonic card output
  --paper PAPER         Paper size (default: Letter)
  --cover               Produce PDF SLIP-39 cover page
  --no-cover            Disable PDF SLIP-39 cover page
  --text                Enable textual SLIP-39 mnemonic output to stdout
  --watermark WATERMARK
                        Include a watermark on the output SLIP-39 mnemonic
                        cards
  --double-sided        Enable double-sided PDF (default)
  --no-double-sided     Disable double-sided PDF
  --single-sided        Enable single-sided PDF

python3 -m slip39.recovery --help 2>&1                | sed 's/^/: /' # (just for output formatting)

usage: __main__.py [-h] [-v] [-q] [-m MNEMONIC] [-e] [--no-entropy] [-b] [-u]
                   [--binary] [--language LANGUAGE] [-p PASSPHRASE]

Recover and output secret Seed from SLIP-39 or BIP-39 Mnemonics

options:
  -h, --help            show this help message and exit
  -v, --verbose         Display logging information.
  -q, --quiet           Reduce logging output.
  -m MNEMONIC, --mnemonic MNEMONIC
                        Supply another SLIP-39 (or a BIP-39) mnemonic phrase
  -e, --entropy         Return the BIP-39 Mnemonic Seed Entropy instead of the
                        generated Seed (default: True if --using-bip39 w/o
                        passphrase)
  --no-entropy          Return the BIP-39 Mnemonic generated Seed
  -b, --bip39           Recover Entropy and generate 512-bit secret Seed from
                        BIP-39 Mnemonic + passphrase
  -u, --using-bip39     Recover Entropy from SLIP-39, generate 512-bit secret
                        Seed using BIP-39 Mnemonic + passphrase
  --binary              Output seed in binary instead of hex
  --language LANGUAGE   BIP-39 Mnemonic language (default: english)
  -p PASSPHRASE, --passphrase PASSPHRASE
                        Decrypt the SLIP-39 or BIP-39 master secret w/ this
                        passphrase, '-' reads it from stdin (default: None/'')

If you obtain a threshold number of SLIP-39 mnemonics, you can recover the original
secret Seed Entropy, and then re-generate one or more wallets from it.

Enter the mnemonics when prompted and/or via the command line with -m |--mnemonic "...".

The secret Seed Entropy can then be used to generate a new SLIP-39 encoded wallet:

    python3 -m slip39 --secret = "ab04...7f"

SLIP-39 Mnemonics may be encrypted with a passphrase; this is *not* Ledger-compatible, so it rarely
recommended!  Typically, on a Trezor, you recover using your SLIP-39 Mnemonics, and then use the
"Hidden wallet" feature (passwords entered on the device) to produce alternative sets of accounts.

BIP-39 Mnemonics can be backed up as SLIP-39 Mnemonics, in two ways:

1) The actual BIP-39 standard 512-bit Seed can be generated by supplying --passphrase, but only at
the cost of 59-word SLIP-39 mnemonics.  This is because the *output* 512-bit BIP-39 Seed must be
stored in SLIP-39 -- not the *input* 128-, 160-, 192-, 224-, or 256-bit entropy used to create the
original BIP-39 mnemonic phrase.

2) The original BIP-39 12- or 24-word, 128- to 256-bit Seed Entropy can be recovered by supplying
--entropy.  This modifies the BIP-39 recovery to return the original BIP-39 Mnemonic Entropy, before
decryption and seed generation.  It has no effect for SLIP-39 recovery.

The tools can be used in a pipeline to avoid printing the secret. Here we generate some mnemonics, sorting them in reverse order so we need more than just the first couple to recover. Observe the Ethereum wallet address generated.

Then, we recover the master secret seed in hex with slip39-recovery, and finally send it to slip39 --secret - to re-generate the same wallet as we originally created.

( python3 -m slip39 --text --no-card \
 | ( sort -r  ; echo "...later, after recovering SLIP-39 mnemonics..." 1>&2 ) \
 | python3 -m slip39.recovery \
 | python3 -m slip39 --secret - --no-card \
) 2>&1

2024-11-15 16:14:29 slip39           Generated 128-bit SLIP-39 Mnemonics w/ identifier 26257 requiring 2 of 4 (extendable) groups to recover
2024-11-15 16:14:29 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0xa82995161ef5bf7647F224D3b83140b31787F078
2024-11-15 16:14:29 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qyefnnngkel3ee4sahd62ccucmpdmx02laryk4y
...later, after recovering SLIP-39 mnemonics...
2024-11-15 16:14:29 slip39           Generated 128-bit SLIP-39 Mnemonics w/ identifier 1514 requiring 2 of 4 (extendable) groups to recover
2024-11-15 16:14:29 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0xa82995161ef5bf7647F224D3b83140b31787F078
2024-11-15 16:14:29 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qyefnnngkel3ee4sahd62ccucmpdmx02laryk4y

A primary use case for python-slip39 will be to backup an existing BIP-39 Mnemonic Phrase to SLIP-39 cards, so here it is. Suppose you have some (arbitrary) way to recover (or generate) some Entropy; for example, by recovering the original seed entropy used to generate a BIP-39 Mhemonic:

( python3 -m slip39.recovery --bip39 --entropy \
--mnemonic "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" \
  | python3 -m slip39 --using-bip39 --secret - \
) 2>&1

2024-11-15 16:21:43 slip39           Assuming BIP-39 seed entropy: Ensure you recover and use via a BIP-39 Mnemonic
2024-11-15 16:21:43 slip39           Generated 128-bit SLIP-39 Mnemonics w/ identifier 31496 requiring 2 of 4 (extendable) groups to recover
2024-11-15 16:21:43 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E
2024-11-15 16:21:43 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2
2024-11-15 16:21:46 slip39.layout    Writing SLIP39 backup for BIP-39-encoded wallet for 'SLIP39' to: SLIP39-2024-11-15+16.21.46-ETH-0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E.pdf
SLIP39-2024-11-15+16.21.46-ETH-0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E.pdf

Better yet, if you already have a BIP-39 Mnemonic, you can just use that directly (we'll use a bit of "wrapping" around the filename output, so the first page shows up here):

echo -n "[[./$( \
python3 -m slip39 --secret "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" --output ./images/SLIP39-Example.pdf \
)]]"

../../images/SLIP39-Example.pdf

Note the presence of the BIP-39 recovery phrase on the cover sheet; this is recovered by round-tripping the original BIP-39 seed entropy, through SLIP-39, and re-encoding back to BIP-39.

slip39-generator --help --version         | sed 's/^/: /' # (just for output formatting)

usage: slip39-generator [-h] [-v] [-q] [-s SECRET] [-f FORMAT] [--xpub]
                        [--no-xpub] [-c CRYPTOCURRENCY] [--path PATH]
                        [-d DEVICE] [--baudrate BAUDRATE] [-e ENCRYPT]
                        [--decrypt ENCRYPT] [--enumerated] [--no-enumerate]
                        [--receive] [--corrupt CORRUPT]

Generate public wallet address(es) from a secret seed

options:
  -h, --help            show this help message and exit
  -v, --verbose         Display logging information.
  -q, --quiet           Reduce logging output.
  -s SECRET, --secret SECRET
                        Use the supplied 128-, 256- or 512-bit hex value as
                        the secret seed; '-' (default) reads it from stdin
                        (eg. output from slip39.recover)
  -f FORMAT, --format FORMAT
                        Specify crypto address formats: legacy, segwit,
                        bech32; default: ETH:legacy, BTC:bech32, LTC:bech32,
                        DOGE:legacy, BSC:legacy, XRP:legacy
  --xpub                Output xpub... instead of cryptocurrency wallet
                        address (and trim non-hardened default path segments)
  --no-xpub             Inhibit output of xpub (compatible w/ pre-v10.0.0)
  -c CRYPTOCURRENCY, --cryptocurrency CRYPTOCURRENCY
                        A crypto name and optional derivation path (default:
                        "ETH:{Account.path_default('ETH')}"), optionally w/
                        ranges, eg: ETH:../0/-
  --path PATH           Modify all derivation paths by replacing the final
                        segment(s) w/ the supplied range(s), eg. '.../1/-'
                        means .../1/[0,...)
  -d DEVICE, --device DEVICE
                        Use this serial device to transmit (or --receive)
                        records
  --baudrate BAUDRATE   Set the baud rate of the serial device (default:
                        115200)
  -e ENCRYPT, --encrypt ENCRYPT
                        Secure the channel from errors and/or prying eyes with
                        ChaCha20Poly1305 encryption w/ this password; '-'
                        reads from stdin
  --decrypt ENCRYPT
  --enumerated          Include an enumeration in each record output (required
                        for --encrypt)
  --no-enumerate        Disable enumeration of output records
  --receive             Receive a stream of slip.generator output
  --corrupt CORRUPT     Corrupt a percentage of output symbols

Once you have a secret seed (eg. from slip39.recovery), you can generate a sequence
of HD wallet addresses from it.  Emits rows in the form:

    <enumeration> [<address group(s)>]

If the output is to be transmitted by an insecure channel (eg. a serial port), which may insert
errors or allow leakage, it is recommended that the records be encrypted with a cryptographic
function that includes a message authentication code.  We use ChaCha20Poly1305 with a password and a
random nonce generated at program start time.  This nonce is incremented for each record output.

Since the receiver requires the nonce to decrypt, and we do not want to separately transmit the
nonce and supply it to the receiver, the first record emitted when --encrypt is specified is the
random nonce, encrypted with the password, itself with a known nonce of all 0 bytes.  The plaintext
data is random, while the nonce is not, but since this construction is only used once, it should be
satisfactory.  This first nonce record is transmitted with an enumeration prefix of "nonce".

Addresses can be produced in plaintext or encrypted, and output to stdout or to a serial port.

echo ffffffffffffffffffffffffffffffff | slip39-generator --secret - --path '../-3' 2>&1

    0: [["ETH", "m/44'/60'/0'/0/0", "0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1"], ["BTC", "m/84'/0'/0'/0/0", "bc1q9yscq3l2yfxlvnlk3cszpqefparrv7tk24u6pl"]]
    1: [["ETH", "m/44'/60'/0'/0/1", "0x8D342083549C635C0494d3c77567860ee7456963"], ["BTC", "m/84'/0'/0'/0/1", "bc1qnec684yvuhfrmy3q856gydllsc54p2tx9w955c"]]
    2: [["ETH", "m/44'/60'/0'/0/2", "0x52787E24965E1aBd691df77827A3CfA90f0166AA"], ["BTC", "m/84'/0'/0'/0/2", "bc1q2snj0zcg23dvjpw7m9lxtu0ap0hfl5tlddq07j"]]
    3: [["ETH", "m/44'/60'/0'/0/3", "0xc2442382Ae70c77d6B6840EC6637dB2422E1D44e"], ["BTC", "m/84'/0'/0'/0/3", "bc1qxwekjd46aa5n0s3dtsynvtsjwsne7c5f5w5dsd"]]

To produce accounts from a BIP-39 or SLIP-39 seed, recover it using slip39-recovery.

Here's an example of recovering a test BIP-39 seed; note that it yields the well-known ETH 0xfc20...1B5E and BTC bc1qk0...gnn2 accounts associated with this test Mnemonic:

( python3 -m slip39.recovery --bip39 --mnemonic 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| python3 -m slip39.generator --secret - --path '../-3' --format 'BTC:segwit' --crypto 'DOGE' ) 2>&1

    0: [["DOGE", "m/44'/3'/0'/0/0", "DTMaJd8wqye1fymnjxZ5Cc5QkN1w4pMgXT"], ["BTC", "m/49'/0'/0'/0/0", "3CfyLSjYFFV6MUAMh3auTK9kfpPscPCHth"]]
    1: [["DOGE", "m/44'/3'/0'/0/1", "DGkL2LD5FfccAaKtx8G7TST5iZwrNkecTY"], ["BTC", "m/49'/0'/0'/0/1", "31nD3MEioUDchu7bVaHUCdCa4vxxsqDYwu"]]
    2: [["DOGE", "m/44'/3'/0'/0/2", "DQa3SpFZH3fFpEFAJHTXZjam4hWiv9muJX"], ["BTC", "m/49'/0'/0'/0/2", "32pqj8rgW1BdXK2Cygwn2JVYPnVRknfTE4"]]
    3: [["DOGE", "m/44'/3'/0'/0/3", "DTW5tqLwspMY3NpW3RrgMfjWs5gnpXtfwe"], ["BTC", "m/49'/0'/0'/0/3", "3CimS2PfrNykKtJe1uxM4QtaDopaFHdVN1"]]

We can encrypt the output, to secure the sequence (and due to integrated MACs, ensures no errors occur over an insecure channel like a serial cable):

( slip39-recovery --bip39 --mnemonic 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| slip39-generator --secret - --path '../-3' --encrypt 'password' ) 2>&1 \
    | sed -E 's/^(.{100})(.{1,})$/\1.../'  # (shorten output)

nonce: bcfdddcb62fdfec1fb6cae6e44018a3281d290e5db44893be66513c2
    0: f7a1e078b97b61fb12837ae38ff8185d1c3446aa24065731b24472d6b7bbdcda5493cf48175900751703792f52233...
    1: 647cfe57ef7d2f236ec57eb9ed02fa699b1c3cec5c9f704fc792ff75cb0cbfee007a5082ade596f2a4dc62f94044a...
    2: 46af8608026a4046ca4727bfa66dabcd5491a11939e1ebd9d5aeeef17873d9c3bab4f8656b6379208ebab59a18429...
    3: 5e7c304d4555a2259d8ef4aaeb45ff3f1102c6d89fea0446aee4b6061bd9fe7631010721546774bb82cf6918fae1e...

On the receiving computer, we can decrypt and recover the stream of accounts from the wallet seed; any rows with errors are ignored:

( slip39-recovery --bip39 --mnemonic 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| slip39-generator --secret - --path '../-3' --encrypt 'password' \
| slip39-generator --receive --decrypt 'password' ) 2>&1

    0: [["ETH", "m/44'/60'/0'/0/0", "0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E"], ["BTC", "m/84'/0'/0'/0/0", "bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2"]]
    1: [["ETH", "m/44'/60'/0'/0/1", "0xd1a7451beB6FE0326b4B78e3909310880B781d66"], ["BTC", "m/84'/0'/0'/0/1", "bc1qkd33yck74lg0kaq4tdcmu3hk4yruhjayxpe9ug"]]
    2: [["ETH", "m/44'/60'/0'/0/2", "0x578270B5E5B53336baC354756b763b309eCA90Ef"], ["BTC", "m/84'/0'/0'/0/2", "bc1qvr7e5aytd0hpmtaz2d443k364hprvqpm3lxr8w"]]
    3: [["ETH", "m/44'/60'/0'/0/3", "0x909f59835A5a120EafE1c60742485b7ff0e305da"], ["BTC", "m/84'/0'/0'/0/3", "bc1q6t9vhestkcfgw4nutnm8y2z49n30uhc0kyjl0d"]]

If you prefer, you can output "xpub…" format public keys, instead of account addresses. By default, this will elide the non-hardened portion of the default addresses – use the "xpub…" keys to produce the remaining non-hardened portion of the HD wallet paths locally.

For example, assume you must produce a sequence of accounts for each client client of your company to deposit into. Your highly secure serial-connected "key enclave" system (which must know your HD wallet seed) emits a sequence of xpubkeys for each new client over a serial cable, to your accounting system:

( echo 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| python3 -m slip39.generator --secret - --xpub --path "../-2'"  --encrypt 'password' \
| python3 -m slip39.generator -v --receive --decrypt 'password' ) 2>&1

2024-11-15 16:22:52 slip39.generator Decrypting accountgroups with nonce: 54ef8298808e20661a0e3f98
    0: [["ETH", "m/44'/60'/0'", "xpub6C2y6te3rtGg9SspDDFbjGEgn7yxc5ZzzkBk62yz3GRKvuqdaMDS7NUbesTJ44FprxAE7hvm5ZQjDMbYWehdJQsyBCP3mL87nnB4cB47HGS"], ["BTC", "m/84'/0'/0'", "zpub6rD5AGSXPTDMSnpmczjENMT3NvVF7q5MySww6uxitUsBYgkZLeBywrcwUWhW5YkeY2aS7xc45APPgfA6s6wWfG2gnfABq6TDz9zqeMu2JCY"]]
    1: [["ETH", "m/44'/60'/1'", "xpub6C2y6te3rtGgCPb4Gi89Qin7Da2dvnnHSuR9rLQV6bWQKiyfKyjtVzr2n9mKmTEHzr4rzK78LmdSXLSzvpZqVs4ussUU8NyXpt9nWWbKG3C"], ["BTC", "m/84'/0'/1'", "zpub6rD5AGSXPTDMUaSe3aGDqWk4uMTwcrFwytkKuDGmi3ofUkJ4dQxXHZwiXWbHHrELJAor8xGs61F8sbKS2JdQkLZRnu5PGktmr6F32nEBUBb"]]
    2: [["ETH", "m/44'/60'/2'", "xpub6C2y6te3rtGgENnaK62SyPawqKvbde17wc2ndMGFWi2yAkk3piwEY9QK8egtE9ye9uoqiqs5WV3MTNCCP2qjUNDb8cmSg4ZsVnwQnkziXVh"], ["BTC", "m/84'/0'/2'", "zpub6rD5AGSXPTDMYx2sQPuZgceniniRXDK5tELiREjxfSGJENNxuQD3u2yfpRqnNE1JeH14Pa7MVGrofDJtyXw252ws9HgRcd82X2M4KzkUfpZ"]]

As required (throttled by hardward the serial cable RTS/CTS signals) your accounting system receives these "xpub…" addresses:

( echo 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| python3 -m slip39.generator --secret - --xpub --path "../-2'"  --encrypt 'password' \
| python3 -m slip39.generator -v --receive --decrypt 'password' \
| while IFS=':' read num json; do \
    echo "--- $(( num ))"; \
    echo "$json" | jq -c '.[]'; \
done \
) 2>&1

2024-11-15 16:22:56 slip39.generator Decrypting accountgroups with nonce: 72a74241ac0c7ad80848c735
--- 0
["ETH","m/44'/60'/0'","xpub6C2y6te3rtGg9SspDDFbjGEgn7yxc5ZzzkBk62yz3GRKvuqdaMDS7NUbesTJ44FprxAE7hvm5ZQjDMbYWehdJQsyBCP3mL87nnB4cB47HGS"]
["BTC","m/84'/0'/0'","zpub6rD5AGSXPTDMSnpmczjENMT3NvVF7q5MySww6uxitUsBYgkZLeBywrcwUWhW5YkeY2aS7xc45APPgfA6s6wWfG2gnfABq6TDz9zqeMu2JCY"]
--- 1
["ETH","m/44'/60'/1'","xpub6C2y6te3rtGgCPb4Gi89Qin7Da2dvnnHSuR9rLQV6bWQKiyfKyjtVzr2n9mKmTEHzr4rzK78LmdSXLSzvpZqVs4ussUU8NyXpt9nWWbKG3C"]
["BTC","m/84'/0'/1'","zpub6rD5AGSXPTDMUaSe3aGDqWk4uMTwcrFwytkKuDGmi3ofUkJ4dQxXHZwiXWbHHrELJAor8xGs61F8sbKS2JdQkLZRnu5PGktmr6F32nEBUBb"]
--- 2
["ETH","m/44'/60'/2'","xpub6C2y6te3rtGgENnaK62SyPawqKvbde17wc2ndMGFWi2yAkk3piwEY9QK8egtE9ye9uoqiqs5WV3MTNCCP2qjUNDb8cmSg4ZsVnwQnkziXVh"]
["BTC","m/84'/0'/2'","zpub6rD5AGSXPTDMYx2sQPuZgceniniRXDK5tELiREjxfSGJENNxuQD3u2yfpRqnNE1JeH14Pa7MVGrofDJtyXw252ws9HgRcd82X2M4KzkUfpZ"]

Then, it generates each client's sequence of addresses locally: you are creating HD wallet accounts from each "xpub…" key, and adding the remaining non-hardened HD wallet path segments:

( echo 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| python3 -m slip39.generator --secret - --xpub --path "../-2'"  --encrypt 'password' \
| python3 -m slip39.generator -v --receive --decrypt 'password' \
| while IFS=':' read num json; do \
    echo "--- $(( num ))"; \
    echo "$json" | jq -cr '.[]|"--crypto " + .[0] + " --secret " + .[2]' | while read command; do \
        python3 -m slip39.cli -v --no-json addresses $command --paths m/0/-2; \
    done; \
done \
) 2>&1

2024-11-15 16:23:16 slip39.generator Decrypting accountgroups with nonce: c9b8956d2cada2aa42bb7524
--- 0
ETH   m/0/0                0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E
ETH   m/0/1                0xd1a7451beB6FE0326b4B78e3909310880B781d66
ETH   m/0/2                0x578270B5E5B53336baC354756b763b309eCA90Ef
BTC   m/0/0                bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2
BTC   m/0/1                bc1qkd33yck74lg0kaq4tdcmu3hk4yruhjayxpe9ug
BTC   m/0/2                bc1qvr7e5aytd0hpmtaz2d443k364hprvqpm3lxr8w
--- 1
ETH   m/0/0                0x9176A747BA67C1d7F80AaDC930180b4183AfB5c4
ETH   m/0/1                0xa1409B655aC3e09eF261de00BAa4e85bD2820AA4
ETH   m/0/2                0xae22C13Ef5891Ed835C24Ed5090542DFa748c21F
BTC   m/0/0                bc1q8pqnqs573vx3qdp0xp6qdqzvnvy8px24rxh9lp
BTC   m/0/1                bc1qwtc58u4mmnxa29u8j07e6lmqpnrs38vefy3y24
BTC   m/0/2                bc1qg9s8qzm0lcetfv6umhlm3evtca5zsqv7elqd5s
--- 2
ETH   m/0/0                0x32A8b066c5dbD37147766491A32A612d313fda25
ETH   m/0/1                0xff8b88b975f9C296531C1E93d5e4f28757b4571A
ETH   m/0/2                0xc95Bdf50CA542E1B689f5C06e2D8bAd0625Dfa23
BTC   m/0/0                bc1q09zpchmkcnny90ghkg76gd69dvaf57qwcsrhes
BTC   m/0/1                bc1qjytdyw6zramwt4nvvpte93hfry2d4xhhqn0xg4
BTC   m/0/2                bc1qcummre0pxv5xj4gvyut0t84vfwjd6eu7r387v4

You'll notice that, after this elaborate exercise of generating xpubkeys, encrypted transmission and recovery, generating accounts from the xpubkeys, and producing multiples addresses using the remainder of the original HD wallet paths: the output addresses are identical to those generated directly from the BIP-39 Mnemonic Phrase:

secret='zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong'
for crypto in BTC ETH; do
python3 -m slip39.cli -v --no-json addresses --secret "$secret" --crypto $crypto --paths "../-2"
done

BTC   m/84'/0'/0'/0/0      bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2
BTC   m/84'/0'/0'/0/1      bc1qkd33yck74lg0kaq4tdcmu3hk4yruhjayxpe9ug
BTC   m/84'/0'/0'/0/2      bc1qvr7e5aytd0hpmtaz2d443k364hprvqpm3lxr8w
ETH   m/44'/60'/0'/0/0     0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E
ETH   m/44'/60'/0'/0/1     0xd1a7451beB6FE0326b4B78e3909310880B781d66
ETH   m/44'/60'/0'/0/2     0x578270B5E5B53336baC354756b763b309eCA90Ef

What if you or your company wants to accept Crypto payments, and needs to generate a sequence of wallets unique to each client? You can use an xpubkey and then generate a sequence of unique addresses from that, which doesn't disclose any of your private key material:

( python3 -m slip39.generator -q --secret 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
--xpub --path "../-2'" --crypto BTC
) 2>&1

    0: [["BTC", "m/84'/0'/0'", "zpub6rD5AGSXPTDMSnpmczjENMT3NvVF7q5MySww6uxitUsBYgkZLeBywrcwUWhW5YkeY2aS7xc45APPgfA6s6wWfG2gnfABq6TDz9zqeMu2JCY"]]
    1: [["BTC", "m/84'/0'/1'", "zpub6rD5AGSXPTDMUaSe3aGDqWk4uMTwcrFwytkKuDGmi3ofUkJ4dQxXHZwiXWbHHrELJAor8xGs61F8sbKS2JdQkLZRnu5PGktmr6F32nEBUBb"]]
    2: [["BTC", "m/84'/0'/2'", "zpub6rD5AGSXPTDMYx2sQPuZgceniniRXDK5tELiREjxfSGJENNxuQD3u2yfpRqnNE1JeH14Pa7MVGrofDJtyXw252ws9HgRcd82X2M4KzkUfpZ"]]

Since you have to generate such an xpubkey from a "hardened" path, such as with slip39.generate --xpub ..., you still need to run that tool chain on some secure "air gapped" computer. So, how do you do that safely, knowing that you need to input your SLIP-39 or BIP-39 Mnemonics on that computer? Especially, if you want to do this under any kind of automation, and deliver the output xpubkey to your insecure business computer systems?

One solution is to have the computer hosting your Seed or Mnemonic private key material only connected to your business computer systems with a guaranteed safe mechanism. Definitely not with any kind of general purpose network system!

The solution: The RS-232 Serial Port

With USB to DB-9 female to DB-9 male serial adapters, any small computer with USB ports (such as the Raspberry Pi 400) can be connected serially and serve as your "secure" computer, storing your Seed Mnemonic.

Remember to disable all other wired and wireless networking!

The RS-232 port on the "secure" computer can be protected from all incoming data transmissions, make an exploit effectively impossible, while still allowing outgoing data (the generated xpubkeys).

A DB-9 serial breakout board or custom serial adapter be easily constructed that disconnects pin 3 (TXD) on the "business" side from pin 2 (RXD) on the "secure" side, eliminating any chance of data being sent to the "secure" side. The only electronic connection that transmits data to the "secure" side is the hardware flow control pin 7 (RTS) to pin 8 (CTS). An exploit using this single-bit approach vector is … unlikely. :)

Creates a set of SLIP-39 groups and their mnemonics.

Outputs a slip39.Details namedtuple containing:

This is immediately usable to pass to slip39.output.

import codecs
import random
from tabulate import tabulate

#
# NOTE:
#
# We turn off randomness here during SLIP-39 generation to get deterministic phrases;
# during normal operation, secure entropy is used during mnemonic generation, yielding
# random phrases, even when the same seed is used multiple times.
# 
import shamir_mnemonic
shamir_mnemonic.shamir.RANDOM_BYTES = lambda n: b'\00' * n

import slip39

cryptopaths         = [("ETH","../-2"), ("BTC","../-2")]
master_secret       = b'\xFF' * 16
master_secret       = 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' 
passphrase          = b""
create_details      = slip39.create(
"Test", 2, { "Mine": (1,1), "Fam": (2,3) },
master_secret=master_secret, passphrase=passphrase, cryptopaths=cryptopaths )

[
[
    "Card", "Mnemonics 1 ", "Mnemonics 2", "Mnemonics 3"
],
None,
] + [
[
    f"{g_name}({g_of}/{len(g_mnems)}) #{g_n+1}:" if l_n == 0 else ""
] + words
for g_name,(g_of,g_mnems) in create_details.groups.items()
for g_n,mnem in enumerate( g_mnems )
for l_n,(line,words) in enumerate(slip39.organize_mnemonic(
        mnem, label=f"{g_name}({g_of}/{len(g_mnems)}) #{g_n+1}:" ))
]

Add the resultant HD Wallet addresses:

[
[ account.path, account.address ]
for group in create_details.accounts
for account in group
]

Layout and produce a PDF containing all the SLIP-39 details on cards for the crypto accounts, on the paper_format provided. Returns the paper (orientation,format) used, the FPDF, and passes through the supplied cryptocurrency accounts derived.

(paper_format,orientation),pdf,accounts = slip39.produce_pdf( *create_details )
pdf_binary = pdf.output()
[
[ "Orientation:",       orientation ],
[ "Paper:",             paper_format ],
[ "PDF Pages:",         pdf.pages_count ],
[ "PDF Size:",          len( pdf_binary )],
]

For each of the names provided, produces a separate PDF containing all the SLIP-39 details and optionally encrypted BIP-38 paper wallets and Ethereum JSON wallets for the specified cryptocurrency accounts derived from the seed, and writes the PDF and JSON wallets to the specified file name(s).

slip39.write_pdfs( ... )

Takes a number of SLIP-39 mnemonics, and if sufficient group_threshold groups' mnemonics are present (and the options passphrase is supplied), the master_secret is recovered. This can be used with slip39.accounts to directly obtain any Account data.

Note that the SLIP-39 passphrase is not checked; entering a different passphrase for the same set of mnemonics will recover a different wallet! This is by design; it allows the holder of the SLIP-39 mnemonic phrases to recover a "decoy" wallet by supplying a specific passphrase, while protecting the "primary" wallet.

Therefore, it is essential to remember any non-default (non-empty) passphrase used, separately and securely. Take great care in deciding if you wish to use a passphrase with your SLIP-39 wallet!

# Recover with the wrong password (on purpose, as a decoy wallet w/ a small amount)
recoverydecoy       = slip39.recover(
create_details.groups['Mine'][1][:] + create_details.groups['Fam'][1][:2],
passphrase=b"wrong!"
)
recoverydecoy_hex   = codecs.encode( recoverydecoy, 'hex_codec' ).decode( 'ascii' )

# But, recovering w/ correct passphrase yields our original Seed Entropy
recoveryvalid       = slip39.recover(
create_details.groups['Mine'][1][:] + create_details.groups['Fam'][1][:2],
passphrase=passphrase
)
recoveryvalid_hex   = codecs.encode( recoveryvalid, 'hex_codec' ).decode( 'ascii' )

[
[ f"{len(recoverydecoy)*8}-bit secret (decoy):", f"{recoverydecoy_hex}" ],
[ f"{len(recoveryvalid)*8}-bit secret recovered:", f"{recoveryvalid_hex}" ]
]

Generate the 512-bit Seed from a BIP-39 Mnemonic + passphrase. Or, return the original 128- to 256-bit Seed Entropy, if as_entropy is specified.

Produce a BIP-39 Mnemonic from the supplied 128- to 256-bit Seed Entropy.

BIP-39 uses a single set of 12, 15, 18, 21 or 24 BIP-39 words to carefully preserve a specific 128 to 256 bits of initial Seed Entropy. Here's a 128-bit (12-word) example using some fixed "entropy" 0xFFFF..FFFF. You'll note that, from the BIP-39 Mnemonic, we can either recover the original 128-bit Seed Entropy, or we can generate the resultant 512-bit Seed w/ the correct passphrase:

from mnemonic import Mnemonic
bip39_english     = Mnemonic("english")
entropy           = b'\xFF' * 16
entropy_hex       = codecs.encode( entropy, 'hex_codec' ).decode( 'ascii' )
entropy_mnemonic  = bip39_english.to_mnemonic( entropy )

recovered         = slip39.recover_bip39( entropy_mnemonic, as_entropy=True )
recovered_hex     = codecs.encode( recovered, 'hex_codec' ).decode( 'ascii' )

recovered_seed    = slip39.recover_bip39( entropy_mnemonic, passphrase=passphrase )
recovered_seed_hex= codecs.encode( recovered_seed, 'hex_codec' ).decode( 'ascii' )

[
[ "Original Entropy", entropy_hex ],
[ "BIP-39 Mnemonic", entropy_mnemonic ],
[ "Recovered Entropy", recovered_hex ],
[ "Recovered Seed", f"{recovered_seed_hex:.50}..." ],
]

Each word is one of a corpus of 2048 words; therefore, each word encodes 11 bits (2048 = 2**11) of entropy. So, we provided 128 bits, but 12*11 = 132. So where does the extra 4 bits of data come from?

It comes from the first few bits of a SHA256 hash of the entropy, which is added to the end of the supplied 128 bits, to reach the required 132 bits: 132 / 11 = 12 words.

This last 4 bits (up to 8 bits, for a 256-bit 24-word BIP-39) is checked, when validating the BIP-39 mnemonic. Therefore, making up a random BIP-39 mnemonic will succeed only 1 / 16 times on average, due to an incorrect checksum 4-bit (16 = 2**4) . Lets check:

def random_words( n, count=100 ):
for _ in range( count ):
    yield ' '.join( random.choice( bip39_english.wordlist ) for _ in range( n ))

successes           = sum(
bip39_english.check( m )
for i,m in enumerate( random_words( 12, 10000 ))) / 100

[
[ "Valid random 12-word mnemonics:", f"{successes}%" ],
[ "Or, about: ", f"1 / {100/successes:.3}" ],
]

Sure enough, about 1/16 random 12-word phrases are valid BIP-39 mnemonics. OK, we've got the contents of the BIP-39 phrase dialed in. How is it used to generate accounts?

Unfortunately, BIP-39 does not use the carefully preserved 128-bit entropy to generate the wallet! Nope, it is stretched to a 512-bit seed using PBKDF2 HMAC SHA512. The normalized text (not the Entropy bytes) of the 12-word mnemonic is then used (with a salt of "mnemonic" plus an optional passphrase, "" by default), to obtain the 512-bit seed:

seed                = bip39_english.to_seed( entropy_mnemonic )
seed_hex            = codecs.encode( seed, 'hex_codec' ).decode( 'ascii' )
[
[ f"{len(seed)*8}-bit seed:", f"{seed_hex:.50}..." ]
]

Finally, this 512-bit seed is used to derive HD wallet(s). The HD Wallet key derivation process consumes whatever seed entropy is provided (512 bits in the case of BIP-39), and uses HMAC SHA512 with a prefix of b"Bitcoin seed" to stretch the supplied seed entropy to 64 bytes (512 bits). Then, the HD Wallet path segments are iterated through, permuting the first 32 bytes of this material as the key with the second 32 bytes of material as the chain node, until finally the 32-byte (256-bit) Ethereum account private key is produced. We then use this private key to compute the rest of the Ethereum account details, such as its public address.

path                = "m/44'/60'/0'/0/0"
bip39_eth_hd        = slip39.account( seed, 'ETH', path )
[
[ f"{len(bip39_eth_hd.key)*4}-bit derived key path:", f"{path}" ],
[ "Produces private key: ", f"{bip39_eth_hd.key}" ],
[ "Yields Ethereum address:", f"{bip39_eth_hd.address}" ],
]

Thus, we see that while the 12-word BIP-39 mnemonic careful preserves the original 128-bit entropy, this data is not directly used to derive the wallet private key and address. Also, since an irreversible hash is used to derive the Seed from the Mnemonic, we can't reverse the process on the seed to arrive back at the BIP-39 mnemonic phrase.

Just like BIP-39 carefully preserves the original 128-bit Seed Entropy bytes in a single 12-word mnemonic phrase, SLIP-39 preserves the original 128- or 256-bit Seed Entropy in a set of 20- or 33-word Mnemonic phrases.

name,thrs,grps,acct,ub39 = slip39.create(
"Test", 2, { "Mine": (1,1), "Fam": (2,3) }, entropy )
[
[ f"{g_name}({g_of}/{len(g_mnems)}) #{g_n+1}:" if l_n == 0 else "" ] + words
for g_name,(g_of,g_mnems) in grps.items()
for g_n,mnem in enumerate( g_mnems )
for l_n,(line,words) in enumerate(slip39.organize_mnemonic(
        mnem, rows=7, cols=3, label=f"{g_name}({g_of}/{len(g_mnems)}) #{g_n+1}:" ))
]

Since there is some randomness used in the SLIP-39 mnemonics generation process, we would get a different set of words each time for the fixed "entropy" 0xFFFF..FF used in this example (if we hadn't manually disabled entropy for shamir_mnemonic, above), but we will always derive the same Ethereum account 0x824b..19a1 at the specified HD Wallet derivation path.

[
[ "Crypto", "HD Wallet Path:", "Ethereum Address:" ],
None,
] + [
[ account.crypto, account.path, account.address ]
for group in create_details.accounts
for account in group
]

Lets prove that we can actually recover the original Seed Entropy from the SLIP-39 recovery Mnemonics; in this case, we've specified a SLIP-39 group_threshold of 2 groups, so we'll use 1 Mnemonic from Mine, and 2 from the Fam group:

_,mnem_mine         = grps['Mine']
_,mnem_fam          = grps['Fam']
recseed             = slip39.recover( mnem_mine + mnem_fam[:2] )
recseed_hex         = codecs.encode( recseed, 'hex_codec' ).decode( 'ascii' )
[
[ f"{len(recseed)*8}-bit Seed:", f"{recseed_hex}" ]
]

And we'll use the same style of code as for the BIP-39 example above, to derive the Ethereum address directly from this recovered 128-bit seed:

slip39_eth_hd       = slip39.account( recseed, 'ETH', path )
[
[ f"{len(slip39_eth_hd.key)*4}-bit derived key path:", f"{path}" ],
[ "Produces private key: ", f"{slip39_eth_hd.key}" ],
[ "Yields Ethereum address:", f"{slip39_eth_hd.address}" ],
]

And we see that we obtain the same Ethereum address 0x824b..1a2b as we originally got from slip39.create above. However, this is not the same Ethereum wallet address obtained from BIP-39 with exactly the same 0xFFFF...FF Seed Entropy, which was 0xfc20..1B5E!

This is due to the fact that BIP-39 does not use the recovered Seed Entropy to produce the seed like SLIP-39 does, but applies additional one-way hashing of the Mnemonic to produce a 512-bit Seed.

There is one approach which can preserve an original BIP-39 generated wallet addresses, using SLIP-39 mnemonics.

It is clumsy, as it preserves the BIP-39 output 512-bit stretched seed, and the resultant 59-word SLIP-39 mnemonics cannot be used (at present) with the Trezor hardware wallet. They can, however, be used to recover the HD wallet private keys without access to the original BIP-39 Mnemonic phrase or passphrase – you could generate and distribute a set of more secure SLIP-39 Mnemonic phrases, instead of trying to secure the original BIP-39 mnemonic + passphrase – without abandoning your existing BIP-39 wallets.

We'll use slip39.recovery --bip39 ... to recover the 512-bit stretched seed from BIP-39:

( python3 -m slip39.recovery --bip39 -v \
--mnemonic "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" 
) 2>&1

2024-11-15 16:28:16 slip39.recovery  BIP-39 Language detected: english
2024-11-15 16:28:16 slip39.recovery  Recovered 512-bit BIP-39 secret from english mnemonic
2024-11-15 16:28:16 slip39.recovery  Recovered BIP-39 secret; To re-generate SLIP-39 wallet, send it to: python3 -m slip39 --secret -
b6a6d8921942dd9806607ebc2750416b289adea669198769f2e15ed926c3aa92bf88ece232317b4ea463e84b0fcd3b53577812ee449ccc448eb45e6f544e25b6

Then we can generate a 59-word SLIP-39 mnemonic set from the 512-bit secret:

( python3 -m slip39.recovery --bip39 \
--mnemonic "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" \
| python3 -m slip39 --secret - --no-card -v
) 2>&1 | tail -20

2024-11-15 16:28:24 slip39                7 identify  19 easel     31 stay      43 dough     55 extra     
2024-11-15 16:28:24 slip39                8 garbage   20 moisture  32 dining    44 energy    56 desktop   
2024-11-15 16:28:24 slip39                9 avoid     21 wisdom    33 alto      45 goat      57 exercise  
2024-11-15 16:28:24 slip39               10 velvet    22 mixture   34 inmate    46 costume   58 sugar     
2024-11-15 16:28:24 slip39               11 fawn      23 fluff     35 froth     47 knife     59 drink     
2024-11-15 16:28:24 slip39               12 retailer  24 snake     36 round     48 flash     
2024-11-15 16:28:24 slip39           6th  1 charity   13 space     25 safari    37 hairy     49 detailed  
2024-11-15 16:28:24 slip39                2 penalty   14 wits      26 prepare   38 golden    50 skunk     
2024-11-15 16:28:24 slip39                3 decision  15 ounce     27 liberty   39 scroll    51 mineral   
2024-11-15 16:28:24 slip39                4 spider    16 leader    28 expect    40 unknown   52 plunge    
2024-11-15 16:28:24 slip39                5 acne      17 exchange  29 join      41 chubby    53 square    
2024-11-15 16:28:24 slip39                6 alien     18 tenant    30 display   42 memory    54 adjust    
2024-11-15 16:28:24 slip39                7 estate    19 coastal   31 group     43 spill     55 vanish    
2024-11-15 16:28:24 slip39                8 leader    20 amazing   32 snake     44 helpful   56 unwrap    
2024-11-15 16:28:24 slip39                9 decision  21 retreat   33 trial     45 oven      57 tolerate  
2024-11-15 16:28:24 slip39               10 wireless  22 indicate  34 alpha     46 crisis    58 rival     
2024-11-15 16:28:24 slip39               11 phrase    23 acquire   35 harvest   47 intend    59 work      
2024-11-15 16:28:24 slip39               12 plastic   24 grill     36 custody   48 glen      
2024-11-15 16:28:24 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E
2024-11-15 16:28:24 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2

This 0xfc20..1B5E address is the same Ethereum address as is recovered on a Trezor using this BIP-39 mnemonic phrase. Thus, we can generate "Paper Wallets" for the desired Cryptocurrency accounts, and recover the funds.

So, this does the job:

• Uses our original BIP-39 Mnemonic
• Does not require remembering the BIP-39 passphrase
• Preserves all of the original wallets

But:

• The 59-word SLIP-39 Mnemonics cannot (yet) be imported into the Trezor
• The original BIP-39 Mnemonic phrase cannot be recovered, for any hardware wallet
• Must use the SLIP-39 App to generate "Paper Wallets", to recover the funds

So, this is a good "emergency backup" solution; you or your heirs would be able to recover the funds with a very high level of security and reliability.

The best solution is to use SLIP-39 to back up the original BIP-39 Seed Entropy (not the generated Seed), and then later recover that Seed Entropy and re-generate the BIP-39 Mnemonic phrase. You will continue to need to remember and use your original BIP-39 passphrase:

First, observe that we can recover the 128-bit Seed Entropy from the BIP-39 Mnemonic phrase (not the 512-bit generated Seed):

( python3 -m slip39.recovery --bip39 --entropy -v \
--mnemonic "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" 
) 2>&1

2024-11-15 16:28:29 slip39.recovery  BIP-39 Language detected: english
2024-11-15 16:28:29 slip39.recovery  Recovered 128-bit BIP-39 entropy from english mnemonic (no passphrase supported)
2024-11-15 16:28:29 slip39.recovery  Recovered BIP-39 secret; To re-generate SLIP-39 wallet, send it to: python3 -m slip39 --secret -
ffffffffffffffffffffffffffffffff

Now we generate SLIP-39 Mnemonics to recover the 128-bit Seed Entropy. Note that these are 20-word Mnemonics. However, these are NOT the wallets we expected! These are the well-known native SLIP-39 wallets from the 0xFFFF...FF Seed Entropy; not the well-known native BIP-39 wallets from that Seed Entropy, which generate the Ethereum wallet address 0xfc20..1B5E! Why not?

( python3 -m slip39.recovery --bip39 --entropy \
--mnemonic 'zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong' \
| python3 -m slip39 --secret - --no-card -v
) 2>&1 | tail -20

2024-11-15 16:28:50 slip39                4 skin      11 smear     18 volume    
2024-11-15 16:28:50 slip39                5 artwork   12 usher     19 arcade    
2024-11-15 16:28:50 slip39                6 season    13 raisin    20 training  
2024-11-15 16:28:50 slip39                7 exchange  14 uncover   
2024-11-15 16:28:50 slip39           5th  1 ceramic    8 scared    15 champion  
2024-11-15 16:28:50 slip39                2 industry   9 deal      16 literary  
2024-11-15 16:28:50 slip39                3 decision  10 hobo      17 dragon    
2024-11-15 16:28:50 slip39                4 snake     11 scene     18 axis      
2024-11-15 16:28:50 slip39                5 detailed  12 losing    19 result    
2024-11-15 16:28:50 slip39                6 shrimp    13 unfold    20 saver     
2024-11-15 16:28:50 slip39                7 hearing   14 slice     
2024-11-15 16:28:50 slip39           6th  1 ceramic    8 gray      15 judicial  
2024-11-15 16:28:50 slip39                2 industry   9 union     16 picture   
2024-11-15 16:28:50 slip39                3 decision  10 capture   17 frozen    
2024-11-15 16:28:50 slip39                4 spider    11 closet    18 spill     
2024-11-15 16:28:50 slip39                5 diagnose  12 quiet     19 either    
2024-11-15 16:28:50 slip39                6 width     13 extra     20 flip      
2024-11-15 16:28:50 slip39                7 fishing   14 wireless  
2024-11-15 16:28:50 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0x824b174803e688dE39aF5B3D7Cd39bE6515A19a1
2024-11-15 16:28:50 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1q9yscq3l2yfxlvnlk3cszpqefparrv7tk24u6pl

Because we must tell slip39 to that we're using the BIP-39 Mnemonic and Seed generation process to derived the wallet addresses from the Seed Entropy (not the SLIP-39 standard). So, we add the -using-bip39 option:

( python3 -m slip39.recovery --bip39 --entropy \
--mnemonic "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong" \
| python3 -m slip39 --secret - --no-card -v --using-bip39
) 2>&1 | tail -20

2024-11-15 16:29:06 slip39                4 skin      11 arena     18 warmth    
2024-11-15 16:29:06 slip39                5 debris    12 advocate  19 heat      
2024-11-15 16:29:06 slip39                6 client    13 taught    20 hush      
2024-11-15 16:29:06 slip39                7 expand    14 minister  
2024-11-15 16:29:06 slip39           5th  1 argue      8 reunion   15 detailed  
2024-11-15 16:29:06 slip39                2 withdraw   9 penalty   16 starting  
2024-11-15 16:29:06 slip39                3 decision  10 false     17 excuse    
2024-11-15 16:29:06 slip39                4 snake     11 ting      18 sheriff   
2024-11-15 16:29:06 slip39                5 depart    12 petition  19 dragon    
2024-11-15 16:29:06 slip39                6 papa      13 submit    20 browser   
2024-11-15 16:29:06 slip39                7 march     14 order     
2024-11-15 16:29:06 slip39           6th  1 argue      8 union     15 coding    
2024-11-15 16:29:06 slip39                2 withdraw   9 texture   16 bumpy     
2024-11-15 16:29:06 slip39                3 decision  10 equip     17 idle      
2024-11-15 16:29:06 slip39                4 spider    11 platform  18 slush     
2024-11-15 16:29:06 slip39                5 arena     12 party     19 theory    
2024-11-15 16:29:06 slip39                6 decrease  13 award     20 violence  
2024-11-15 16:29:06 slip39                7 pacific   14 nuclear   
2024-11-15 16:29:06 slip39.layout    ETH    m/44'/60'/0'/0/0    : 0xfc2077CA7F403cBECA41B1B0F62D91B5EA631B5E
2024-11-15 16:29:06 slip39.layout    BTC    m/84'/0'/0'/0/0     : bc1qk0a9hr7wjfxeenz9nwenw9flhq0tmsf6vsgnn2

And, there we have it – we've recovered exactly the same Ethereum and Bitcoin wallets as would a native BIP-39 hardware wallet like a Ledger Nano.

Collecting up all the clients' payments later is a manual process. If you wish to distribute the payments (say, to pay partners, or a licensor whose software you sub-licensed, or to ensure that you get paid should someone license your software), this must all be done manually.

If ERC-20 tokens are accepted into the generated EOA addresses, then you must transfer Ethereum into the account first, before transferring out the ERC-20 tokens. This requires at least one additional transfer fee, and since Gas fees are now variable, may result in a small amount of Ethereum abandoned in the account.

In any payment system with many clients paying for product(s), and fees being distributed to various payees, there are normally many trusted partners involved, and many manual (or automated) processes that can fail.

For example, what if a piece of software is created and distributed by some organization, and this software uses your licensed module? If the organization fails, or is deplatformed by a hostile government or corporation, or the software is abandoned, then clients who find the software and install it and want to pay for a license will probably not be able to pay the organization for it – and your license fees also will go unpaid.

Surely, there must be a way to deploy a sequence of interconnected Smart Contracts that can ensure that:

• Any new client can uniquely allocate (and optionally store some data with) a "Forwarder" address and pay for the product,
• Payment into that account address (and perhaps validation of its unique data) constitutes proof of licensing,
• Payees (direct and indirect) can flush any such payments through to themselves (and others)

These goals can be achieved using per-client "Forwarder" account addresses.

Once the product's MultiPayoutERC20 "Fee Distribution" contract address is identified, the act of obtaining a unique client payee "Forwarder" address is simple.

1. A "salt" value unique to the client is deduced, usually consisting of "something they know" (eg. a Public Key) plus "something they have" (eg. a Machine ID, or a User Name).
2. The salt is used to deduce the client's unique "Forwarder" address

#
# To create a new MultiPayoutERC20contract:
#
#     Provide yourself with a Goerli testnet account under your control;
# provide an "xpub..." key for it, or the BIP-39 Mnemonic phrase to
# derive its HD wallet.  Use the https://goerlifaucet.com to fund the
# account with some Goerli test Ethereum; requires you to set up an
# https://alchemy.com account, and put your API token in the
# ALCHEMY_API_TOKEN environment variable.
# 
#     If you have an Etherscan API token, put it in ETHERSCAN_API_TOKEN.
# This will be used to scan for any existing contracts already deployed by
# your Goerli testnet Ethernet address.
# 
import os
import logging

from web3 import Web3
import slip39
from slip39.invoice import MultiPayoutERC20, ethereum, Chain

goerli_xprvkey                  = os.getenv( 'GOERLI_XPRVKEY' )
if not goerli_xprvkey:
goerli_seed                 = os.getenv( 'GOERLI_SEED' )
print(f"Using Ethereum seed: {goerli_seed}")
if goerli_seed:
   try:
       # why m/44'/1'/... instead of m/44'/60'/...?  Dunno;
       # That's the derivation path that Trezor Suite uses for
       # Goerli testnet wallets...
        goerli_xprvkey = slip39.account(
            goerli_seed, crypto="ETH", path="m/44'/1'/0'"
        ).xprvkey
   except Exception as exc:
       print(f"Failed to deduce XPRVKEY from seed: {exc}")

contract                        = None
mp_found                        = None
if goerli_xprvkey:
# We have the means to authorize a transaction on an Ethereum account!
# Get the Account.address public from the xprvkey
goerli_src                  = slip39.account(
   goerli_xprvkey, crypto='ETH', path="m/0/0"
)
print(f"Using Ethereum address: {goerli_src}")

# eg. f"wss://eth-goerli.g.alchemy.com/v2/{os.getenv( 'ALCHEMY_API_TOKEN' )}"
provider_url                = ethereum.alchemy_url( ethereum.Chain.Goerli )
provider                    = Web3.WebsocketProvider( provider_url )

# Lets scan the address's transactions for any existing contract creations,
# and see if any match our MultiPayoutERC20 API.  Will automatically use the
# ETHERSCAN_API_TOKEN environment variable, if defined.
try:
   for tx in reversed(ethereum.ethertx( chain=Chain.Goerli, address=goerli_src.address )):
       if not ( contract := tx.get( 'contractAddress' )):
           continue
       try:
           mp_found = MultiPayoutERC20(
               provider,
               address     = Web3.to_checksum_address( contract ),
           )
       except Exception as exc:
           print( f"Contract {contract} is not a MultiPayoutERC20: {exc}" )
       else:
           print( f"Contract {contract} IS a MultiPayoutERC20" )
           break
   else:
       print( f"No MultiPayoutERC20 contracts found for Goerli address {goerli_src}" )
except Exception as exc:
   print( f"Failed to scan {goerli_src!r} for contracts: {exc}" )

f"MultiPayoutERC20 found: {contract}\n\n{mp_found}"

#
# Deploy a new MultiPayoutERC20, if necessary
#
mp_created			= None
if goerli_xprvkey and not contract:
destination                 = tuple(
   a.address
   for a in slip39.accounts( goerli_xprvkey, crypto="ETH", paths=f"m/0/1-3" )
)

payees                      = {
   address: share + 1
   for share,address in enumerate(destination)
}

tokens                      = list(
   ethereum.tokeninfo(
       t,
       chain               = ethereum.Chain.Goerli,
       w3_url              = provider_url,
       use_provider        = Web3.WebsocketProvider
   )
   for t in (
       "0xe802376580c10fE23F027e1E19Ed9D54d4C9311e", # USDT
       "0xde637d4C445cA2aae8F782FFAc8d2971b93A4998", # USDC
       "0xaFF4481D10270F50f203E0763e2597776068CBc5", # WEENUS
       "0x1f9061B953bBa0E36BF50F21876132DcF276fC6e", # ZEENUS
   )
)

# print( tabulate( [
#     [
#         [ "Token", "Decimals", "Contract"]
#     ] + [
#         [ t.name, t.decimals, t.contract ]
#         for t in tokens
#     ]
# ], tablefmt='orgtbl' ))

erc20s                      = list(
   t.contract
   for t in tokens
)

try:
   mp_created              = MultiPayoutERC20(
       provider,
       agent       = goerli_src.address,
       agent_prvkey= goerli_src.prvkey,
       payees      = payees,
       erc20s      = erc20s,
   )
except Exception as exc:
   print( f"Failed to deploy a new MultiPayoutERC20: {exc}" )
else:
   print( f"Success deploying a new MultiPayoutERC20: {mp_created}" )
   contract                = mp_created._address

   print("MultiPayoutERC20 Newly Deployed Contract Details:")

f"MultiPayoutERC20 deployed: {mp_created}"

if not contract:
# We haven't been able to create a contract; just show a pre-defined one.
contract                    = "0xbE69793974Fc55cD8B94Dac6b410827740Cc6d68"

#
# To examine an existing MultiPayoutERC20 contract, use:
#     https://goerli.etherscan.io/address/<contract>
mp                              = MultiPayoutERC20(
provider,
address         = Web3.to_checksum_address( contract ),
)

import hashlib
import uuid
username                        = "[email protected]"
machine_id                      = uuid.uuid4()
salt                            = hashlib.sha256(
f"{username}-{machine_id}".encode()
)
salt_int			= int.from_bytes( salt.digest(), byteorder='big' )
forwarder                       = mp.forwarder_address( salt_int )

(
f"MultiPayoutERC20 Contract & Forwarder Details:\n\n{mp}\n\n"
+ tabulate( [
[ "MultiPayoutERC20 Contract:", f"{contract}" ],
[ "Unique Client Salt:", f"{salt.hexdigest()}" ],
[ "Their Forwarder Contract:", f"{forwarder}" ],
], tablefmt='orgtbl' ))

One (or more) Smart Contracts move the funds from this account, into the payees' accounts/Contracts.

If multiple independent parties must be paid out of the proceeds from each client, receiving payments to a plain Account (for which you hold the private key) may not be acceptable to all parties involved. A product owner providing a licensee the capability to sub-licensing their product may, for example, charge a much better fee, if the licensee can prove that payments will automatically flow back to the license owner, every time the licensee sells their product which contains the sub-license.

There are ways to ensure that each client payment must be distributed to each payee, as agreed, using cryptocurrencies which implement Smart Contracts.

A Smart Contract can be created which guarantees that Cryptocurrency funds from a source address are distributed in a fixed proportion to several destination addresses.

A Contract is created that is unique to each set of payee accounts and (fractional) distribution of assets, containing a function something like this (in Solidity):

function payout_internal() private nonReentrant {
    move_but_x10000_to(  9310, payable( address( 0x7F7458EF9A583B95DFD90C048d4B2d2F09f6dA5b ))); //   6.900%
    move_but_x10000_to(  5703, payable( address( 0x94Da50738E09e2f9EA0d4c15cf8DaDfb4CfC672B ))); //  40.000%
    move_but_x10000_to(     0, payable( address( 0xa29618aBa937D2B3eeAF8aBc0bc6877ACE0a1955 ))); //  53.100%
}

(you can see the remaining Smart Contract code in the slip-39 source.)

This function can be executed in various ways.

The most expensive and least flexible method constructs, executes and selfdestructs this payout_internal Smart Contract function.

constructor() payable {
    payout_internal();
    selfdestruc
}

Guaranteeing that each client's payments always flow through to the designated tree of payees is the responsibility of the MultiPayoutERC20Forwarder (client "Forwarder" account) and MultiPayoutERC20 (product's "Fee Distribution") Smart Contracts.

Confirmation of Licensing is the responsibility of the client software. At software runtime, some checks are completed. At minimum, two pieces of data are loaded from storage:

• The Machine ID, and
• A Public Key and a Signature of the Machine ID (previously generated), or
• A Private Key (from which the Machine ID Signature can be generated)

Then, assuming:

• Accounts can be created uniquely for some pseudo-random client-specific identifying key

  • A public key for example

• Some data can be stored and later retrieved using that client key

  • The signature of some License text or the client-unique Machine ID (or a significant portion of it)
• Payments to the account can be queried from on the blockchain

The client software can check the blockchain to confirm payment to the account, and the saved data (eg. Signature) can be checked to confirm that this client is indeed the licensee. For example, the client's Private Key generates the Public Key, and the retrieved signature matches the Sgnature of the Machine ID.

If all of these tests pass, then the client software has confirmed that it is licensed.

If not, a licensing offer (invoice) can be generated, to allow the client to obtain a license.

A number of failure modes exist that can result in cryptocurrency lost in this client address:

• Only ETH supported at reasonable cost

• If an ERC-20 token transfer is invoked, the exact token must be known in advance.

  • Any other token or Ethereum deposited would be lost
• If the exact correct amount of Ethereum to pay for Gas is not deposited, the transaction will fail and will not be re-executable, resulting in loss of all funds at the address.

This idea is not possible using Bitcoin, due to its lack of general-purpose smart contracts, and the fact that one cannot "sign" transactions in advance to generate the "source" Account address: the transaction must contain specific information about the source UTXOs (Unspent TransaXion Outputs) being spent, which is of course unavailable in advance.

You can build the native macOS and win32 SLIP-39.app App.

This requires the official python.org/downloads installer; the homebrew [email protected] will not work for building the native app using either PyInstaller. (The py2app approach doesn't work in either version of Python).

$ git clone [email protected]:pjkundert/python-slip39.git
$ make -C python-slip39 app

Install Python from https://python.org/downloads, and the Microsoft C++ Build Tools via the Visual Studio Installer (required for installing some slip39 package dependencies).

To run the GUI, just install slip39 package from Pypi using pip, including the gui and wallet options. Building the Windows SLIP-39 executable GUI application requires the dev option.

PS C:\Users\IEUser> pip install slip39[gui,wallet,dev]

To work with the python-slip39 Git repo on Github, you'll also need to install Git from git-scm.com. Once installed, run "Git bash", and

$ ssh-keygen.exe -t ed25519

to create an id_ed25519.pub SSH identity, and import it into your Git Settings SSH keys. Then,

$ mkdir src
$ cd src
$ git clone [email protected]:pjkundert/python-slip39.git

Typically, you'll be using python-slip39's advanced features on an air-gapped computer. You do not want to visit websites from this computer. So, you obtain a sub-license from your primary computer's python-slip39 installation, and place it on your secure air-gapped computer (eg. using a USB stick).

Take note of the secondary machine's Agent ID (pubkey) and Machine ID. On your primary computer (with the "master" license), run:

python3 -m slip39.sublicense <agent-pubkey> <machine-id>

Take the output, and place it in the file ~/.crypto-licensing/python-slip39.crypto-license on your air-gapped computer.

On your primary computer, open the provided URL in a browser. The URL contains the details of the advanced feature desired.

This URL's web page will request an Ed25519 "Agent" public key to issue your "master" license to. This should be your primary user account's Ed25519 "Agent" public key – this master "Agent" will be issuing sub-licenses to any of your other SLIP-39 installations. You will be redirected to a URL that is unique to the advanced feature plus your Agent ID.

An invoice will be generated with unique Bitcoin, Ethereum and perhaps other cryptocurrency addresses. Pay the required amount of cryptocurrency to one of the provided wallet addresses. Within a few seconds, the cryptocurrency transfer will be confirmed.

Once the payment for the advanced feature is confirmed, the URL including your agent ID will always allow you to re-download the license. It is only usable by your Agent ID to issue sub-licenses to your python-slip39 installations on your machines.