frozenkrill 🧊🦐

A minimalist Bitcoin wallet focused on cold storage

Loved both by whales 🐋 and small fish 🐟

⚠️ WARNING: this software should be considered beta, proceed with caution

Features

• Brute-force/dictionary attack protection through argon2id (for the key derivation algorithm) with a paranoid tuning
  • Minimum 20 seconds/512MB of RAM to derive a key using a modern CPU on default --difficulty normal, up to 40 minutes/2GB RAM on --difficulty veryhard
• Safe BIP-39 seed generation with the option for the user to input 12/24 words (complete seed) or 11/23 words (automatically generation of the last word/checksum)
• Also implements the following wallet standards:
  • BIP-84 for singlesig
  • BIP-48 for multisig
  • Output Descriptors for future-proof compatibility
• Support for any number of keyfiles, including large ones
• Single, lightweight binary with reduced dependencies
• Simple CLI-interface that makes easy to do safe operations and hard to make unsafe ones
  • Including a password strength checker based on Dropbox's one
• Encrypted files are small and look like random data, there are no headers or magic numbers, making it easier to hide them
• Tries to be future-proof by using algorithms with multiple open-source implementations in many languages

More details on technical details section

What is a cold storage wallet?

A cold storage wallet is used to receive and store bitcoins without an internet connection.

If the wallet is manipulated (created or read) in a safe environment, like a trusted offline computer running an ephemeral (no disk installation), minimalist, open-source Unix distribution (Linux/BSD), it's almost impossible to leak the private keys (seed phrases/mnemonics).

Therefore, it's a safe way to hodl bitcoins in the long term.

Self custody

99% of people holding crypto on their own will end up losing it

-- Old Chinese curse

Being able to secure the keys of a wallet without losing it is the most challenging aspect of Bitcoin from an user's perspective.

If it's too easy to retrieve the keys, then anyone can do it, therefore the funds will be stolen.

If it's too hard, then even the owner may eventually be unable to do it, causing the funds to be lost.

frozenkrill tries to improve the "retrievability" of bitcoin keys by creating an encrypted file that can be backed up to any digital medium securely.

How frozenkrill works?

frozenkrill is a simple executable that:

1. Generates a strongly encrypted file containing the standard BIP-39 seeds
2. Generate the receiving addresses/xpub from these seeds (and other useful parameters like derivation paths)
3. Can sign any PSBT using the encrypted wallet

If a keyfile and a strong password is used, coupled with the builtin brute force protections, it's possible to save the wallet file in relatively unsafe storage system (like cloud providers, email or with friends).

What are keyfiles?

Please read this section.

frozenkrill vs hardware wallets

Before anything, it isn't about using frozenkrill or a hardware wallet. The idea is to combine both. In fact, ideally, frozenkrill would run inside a hardware wallet.

For an in depth discussion see this document

Duress wallet (aka plausible deniability aka decoy wallet)

See our document about this feature.

Installation

The recommended way is to download and boot our minimalist Alpine distribution without an internet connection on a computer you trust.

For more security considerations, see this document

Alternatively download the source code or Linux binary on GitHub Releases

To build from sources, install rust (use rustup), then run on the source directory:

$ cargo build --release

This will create the binary in target/release/frozenkrill

Which can be just executed. For instance, to get the help:

$ target/release/frozenkrill --help

To be sure everything is okay on your platform, run the unit and integrations tests with:

$ cargo test --release --workspace

Other ways of installing

https://github.com/planktonlabs/frozenkrill and https://github.com/planktonlabs/bootable-frozenkrill are the only official repositories.

There are no other official installation alternatives. Don't trust binaries in package managers or found anywhere else on Internet.

In future official packages may be added to some Linux/BSD distributions if it makes sense (e.g Tails)

Does it run on Windows, MacOS, Android/iOS, etc?

Note that frozenkrill isn't a general purpose software wallet. It's focused on a very specific use case. The focus is to provide a secure solution to generate private keys that can be stored in digital mediums. It's an alternative to current-gen hardware wallets for some users

For PC users, our ISO image should be good enough to everyone. (if it's not, open an issue describing your use case so we can improve it)

Regarding smartphones, supporting an open-source Android distribution focused on security (e.g GrapheneOS) is an interesting possibility, but completely untested.

It may run on other operating systems, but in this case a hardware wallet will probably be a better solution.

Quick-start in interactive mode

Just type frozenkrill interactive and choose the options.

(note: difficulty easy is used in these examples just for demonstration purposes, better leave it at the default normal level in real world usage)

Generating a wallet

Generating QR code to receive payments

Signing a PSBT

Show the secrets

This will show the seed phrase and the private key (xpriv). Should be used only on special circumstances. The above method of signing a PSBT is the recommended way to make a transaction.

CLI examples

Generate a wallet with a keyfile

$ frozenkrill singlesig-generate --keyfile cuteimage.jpg mywallet

This example uses keyfiles, the parameter is optional but recommended. It can be called multiple times and also reference directories (that will be transversed recursively), like --keyfile file1.txt --keyfile file2.jpg --keyfile secretfolder

The generated encrypted wallet file is mywallet. This file should be backed up to multiple places. If you lose it, you lose any balance on your wallet.

The mywallet_pub.json will be the file containing the receiving addresses, public keys and other information. I can be generated again if needed with the command frozenkrill singlesig-open mywallet --keyfile cuteimage.jpg export-public-info.

Let's take a look at it:

$ head -n 21 mywallet_pub.json 
{
  "version": 0,
  "sigtype": "singlesig",
  "master_fingerprint": "84577e03",
  "singlesig_xpub": "zpub6rerbAfYxT86ZiHXkVYcJJLMFZzy5MF1gLmjuDFNxwN3NPZEC5PesEhzm5AYY7TJixkEAeFrNFRWEyRKLN9jLtNLeZkk2YchzaPkyL7eXqw",
  "singlesig_derivation_path": "84'/0'/0'",
  "multisig_xpub": "Zpub75EVv3vodU4dLT8VaR4eworLZJY1gnKyE1thSST7oQNMvPheFPLNfZhj9em55PyMtcju8A3DzTP3n8HCwgK7JbLJ6KKZf22f4Lw9ouMS2C2",
  "multisig_derivation_path": "48'/0'/0'/2'",
  "singlesig_receiving_output_descriptor": "wpkh([84577e03/84'/0'/0']xpub6CzKyqKif638s7uJ5myMt89Ludi5C7G1r7jJLRTcCvcHGBvmgm4Xd7PiifFNYJ9TugWcfh4jSviQUQCBtyKhkR18utMtriyjT8GUCAqCaC7/0/*)#x703tmpk",
  "singlesig_change_output_descriptor": "wpkh([84577e03/84'/0'/0']xpub6CzKyqKif638s7uJ5myMt89Ludi5C7G1r7jJLRTcCvcHGBvmgm4Xd7PiifFNYJ9TugWcfh4jSviQUQCBtyKhkR18utMtriyjT8GUCAqCaC7/1/*)#h22skw3w",
  "script_type": "segwit-native",
  "network": "bitcoin",
  "receiving_addresses": [
    {
      "address": "bc1qrmyaygpejj2kczmuxc29g4mtust8058xz5tuay",
      "derivation_path": "84'/0'/0'/0/0"
    },
    {
      "address": "bc1q5shm02hkpexm6mwt695t5hmmsc7lkd4rl0af2n",
      "derivation_path": "84'/0'/0'/0/1"
    },

The singlesig_xpub can be used to generate any address if imported in another wallet. But this isn't necessary as we have already generate many receiving addresses (default: 100). So you can just pick an address and send bitcoins to it.

Signing a PSBT (Partially Signed Bitcoin Transaction)

Using another wallet (like electrum) to generate a PSBT (wallet_1-00aacc123.psbt here), then we can load the encrypted wallet to sign it:

$ frozenkrill singlesig-open mywallet --keyfile cuteimage.jpg sign-psbt wallet_1-00aacc123.psbt

This will generate wallet_1-00aacc123_signed.psbt. Which can be loaded again on a wallet connected to a bitcoin node to be broadcasted.

Generating 3 wallets in a batch, each one containing a 12 word seed phrase

$ frozenkrill singlesig-batch-generate-export --wallets-quantity 3 --use-12-words

For instance this generates:

$ ls
wallet_1xyk7ma3kh6d5z9x  walle