This update marks a significant milestone in the journey of Cashu. Cashu aims to be an open ecash protocol for the web built on Bitcoin. In order to fulfill this promise, ecash must become easy and safe to use. One of the big challenges for ecash lies in its barer asset nature: if you lose your wallet, your funds are gone. Not anymore!
Background: Deterministic secret derivation
Typically, ecash is minted by generating random data and receiving a mint's blind signature on it. However, we can also derive the data deterministically from a root private key using a standardized BIP32-compatible derivation path. This allows us to derive the root private key as a BIP39 seed phrase (mnemonic) and to derive the same (pseudo-random) data over and over again. If a user loses access to their wallet, we can use this to re-generate all tokens (more precisely the blinded messages) and re-request the mint's signatures on them. Currently, this works over API calls to the mint but we plan to add the ability to restore all ecash from a public copy of the mint's database which will improve the user's privacy during the restore process. See this PR for more details.
Generating a seed phrase
The seed phrase (or mnemonic) is generated when you start the wallet for the first time. To see the seed phrase, enter the following command and write it down somewhere.
cashu info --mnemonicNote: You can use multiple wallets with Nutshell by using the flag --wallet wallet_name. Every wallet will have its own mnemonic.
Restoring from a backup
If you lose your wallet and want to restore your balance, first make sure that you did not initialize a wallet already. Backup restore will only work if your wallet is completely fresh. To be sure of that, you can move your local wallet data directory to another place: cp -r ~/.cashu/wallet ~/.cashu/wallet_bak. If you used a custom wallet name, replace wallet with the name of your wallet.
When your data directory is empty (i.e. no wallet is initialized yet) you are ready to restore your ecash. Enter the following command to restore your backup.
cashu restoreYou will be prompted to enter your mnemonic. After doing so, press enter and you should soon see your balance restored.
Important notes
No backups of old ecash
The seed phrase is generated upon the first startup of the updated wallet. From that moment on, all new ecash will be derived deterministically and can be restored from the seed phrase. This means that, without any further action, you will not be able to restore your old balance in case of a loss of your wallet! In order to be able to restore your old balance as well, you can make one self-payment with your entire balance for each mint. Simply enter cashu send <your_balance> and cashu receive <token>. You need to repeat this step for every mint you are using.
Avoid concurrent use in multiple wallets
Since the BIP32 derivation is stateful (i.e., a counter needs to be kept track of), the same mnemonic should not be used across multiple wallets at the same time. That means, if you restore your backup on a new device, you must not keep using the same mnemonic on your old device in the future. Using the same seed phrase over multiple wallets will lead to unpredictable behavior and should be avoided at all times!
New Contributors
Full Changelog: 0.12.3...0.13.0