- Prior reading
- Use case
- Process overview
- Creating the wallet
- Co-signer wallet import
- Spending from the wallet
- Managing the recovery path
- Wallet recovery
In this reference design, we look at a variation of the savings wallet reference design. Specifically, we design a wallet application that allows users to enable a simple recovery path in order to provide even more fault tolerance than a regular multi-key wallet.
Prior reading #
The use case for this design is relatively simple. However, we will be referencing some advanced bitcoin concepts and capabilities that are provided by Miniscript. If you are unfamiliar with the topic, please read the custom spending conditions page before diving deeper into this reference design.
Use case #
A multi-key wallet offers a number of advantages, especially for storing large amounts of bitcoin. Therefore, Bob and Alice, want to create a 2-of-3 multi-key wallet for their savings. Bob will hold the first key while his wife, Alice, will hold a second key. In addition, they have the third key locked away in a safe location.
However, the couple worries about a situation where they lose access to two of the keys. In that case, they would lose all of their savings. To protect themselves against this scenario, our application offers them the possibility to enable a recovery path, which automatically lowers the amount of signatures needed to 1-of-3 after 6 months. This will allow them to lose two keys (including their respective backups) and still be able to recover their savings.
Process overview #
Below is a description of the high-level phases involved in setting up and using the wallet described above. For this reference design, we will be focusing mainly on the user flows for wallet creation.
- Wallet creation
- Choose the primary key scheme used for spending under normal circumstances (2-of-3 in our case).
- Register the signing devices to the wallet by importing the three extended public keys keys.
- Enable the recovery path.
- Wallet backup
- Cosigner onboarding
- Regular recovery path refresh
The following prototype includes wallet creation, cosigner onboarding and recovery path refresh, which are explained in detail further below.
Creating the wallet #
The process for creating the wallet is very similar to the one that is covered in the savings wallet reference design. The main differences for this design is that all signing keys are hardware wallets (external signers) and that our application offers a recovery path.
The primary key scheme #
Let’s start creating the wallet. For our product, we assume that our users already have a basic understanding of how bitcoin wallets work. Therefore, the application lets them choose from a couple of the most common key schemes.
Other users may need help deciding on the best solution for them. Our application gives them an option to run through a set of questions about their specific needs and suggests a setup based on the answers. Power users will find a “Custom” option, which gives them the freedom to define a key scheme from scratch. If you are designing your own product, it is important to think about the target audience to determine the options that you offer.
Importing the co-signer public keys #
After the basics have been defined, the extended public keys (XPUBs) of the signing devices need to be imported to the wallet application. First, Bob imports the XPUB from his Trezor by connecting it to his phone. He does the same with the ColdCard that will be placed in the safety deposit box. After that, he hands the phone to Alice, so that she can connect her BitBox.
Another way to do this would be for Alice to export her XPUB and send it to Bob over a secure channel.
Enabling the recovery path #
The final step of the wallet creation flow is to enable the recovery path. Although they are a great way to increase fault tolerance, and thus prevent loss of funds, we want this option to be treated as an optional feature.
If the recovery path is enabled, our application uses smart defaults to propose a suitable key scheme, based on the primary wallet configuration. Since we are creating a 2-of-3 wallet, the application will suggest a 1-of-3 recovery path.
It also suggests that the recovery path will be unlocked if the wallet has not been used for 6 months. However, users can override this default with a different timeframe that better suits their situation. In addition, our application also provides users with the option to set reminders at different times before the recovery path unlocks.
Note that the scope of this feature is quite narrow because it is aimed at an audience with basic knowledge of bitcoin. You might want to offer more customization options, based on your own target audience.
Save for later #
As you can see, creating a multi-key wallet involves a lot of steps in the wallet application as well as on the corresponding signing devices. This can take quite a while, depending on the chosen key scheme. It also requires that users have all extended public keys ready and available beforehand.
It is likely that not all users will be able or willing to go through the entire process in one setting. This is why our application offers a feature called “Save for later”. It allows users to pause the wallet creation process at any time and pick it up later. The application saves the current state of the wallet locally on the device.
Wallet backup #
After the wallet has been created, our application prompts the user to download the wallet backup file. This is important because, for multi-key wallets, it is not enough for the user to back up their own private key to recover the wallet. They need at least all the extended public keys as well.
The backup file contains all the information necessary to recover the wallet, except the private keys. This means that it is ok to store the file digitally in a password manager, for example. However, since it contains all extended public keys, anybody who finds this file can potentially monitor all transactions in real time.
Because users might not want to back up the wallet right away, they will also be able to access the backup file and other important information on the wallet settings page at any time.
Co-signer wallet import #
There is one final step before Alice and Bob can start using their new savings wallet: Alice needs to import wallet configuration to the wallet application on her phone. To make this experience easy, the application allows Bob to share the wallet configuration with Alice in two main ways:
- By displaying a QR code that Alice scans with her app.
- By sharing the wallet backup file.
A less convenient but more trustless way would be for Alice to configure the wallet on her phone herself. She would have to be careful, though, to use the exact same configuration and add the public keys in the same order as Bob did. Otherwise a different wallet would be created.
Spending from the wallet #
Creating transactions and spending from the wallet works like with any other multi-key wallet. We have covered how this works on the savings wallet reference design, if you would like to learn more.
Managing the recovery path #
As mentioned above, recovery paths are powered by timelocks. Technically, however, these timelocks are not applied at the wallet level but at the UTXO level. This means that every UTXO has its own timelock, based on the time when it was deposited into the wallet.
To prevent the recovery path from kicking in and refreshing the timelock, a UTXO has to be spent and re-deposited back into the wallet. Please refer to the custom spending conditions page for more information about how timelocks work.
Preventing recovery path activation #
So if Bob has three UTXOs in his wallet which he received at different times, he technically needs to refresh three different timelocks. This can quickly become cumbersome and costly, as every refresh transaction implies on-chain transaction fees.
To reduce this complexity, our application offers a unified reset experience by default. This simply means that it uses the UTXO that is closest to being unlocked as the trigger to start the process. In the background, however, all UTXOs are automatically batched together.
This allows us to show only one timelock, which makes it easier to understand for users and is more in line with their expectations. An added benefit of this approach is that, as a result, Bob has only one UTXO in his wallet after the recovery path has been reset.
To give users additional flexibility, our application allows them to selectively manage the refresh behavior for individual UTXOs via the advanced options feature. This is similar to the coin control functionality available in many wallet applications.
Resetting an activated recovery path #
Just because a recovery path has been activated does not mean that it’s too late. Bob can always refresh it simply by creating the same self-transfer outlined above.
In the screen flow below, Bob uses the unified “reset all funds” feature to reset the recovery path. This means that the corresponding transaction requires two signatures, because for some of the funds the recovery path is not yet unlocked.
If he choses to reset the unlocked funds only, he will need only one signature. However, this would not reset and consolidate all UTXOs.
Wallet recovery #
Switching to a new phone or computer #
One of the most likely reasons to recover a wallet is that users switch to a new phone or computer. This means that they have to re-install the wallet application and recover the wallet. As long as Alice is using the same signing device as before, all she has to do is to import the wallet in the same way as described in the co-signer onboarding section above.
Replacing a signing device (using the same private key) #
If Bob wants to replace one of the signing devices he can use the new device with the same wallet, as long as it uses the same private key as the original one. This might become necessary because the original device is broken or Bob just wants to use a newer model. To do that, he will need to:
- Restore the private key on the new signing device, using the seed phrase backup.
- Pair the new signing device.
Design considerations #
- Preventing recovery key sets from activating unnecessarily is an important aspect.
- Understanding the concept of timelocks and UTXOs, as well as how they relate to each other, is a challenging topic for most users.
- Well-crafted educational and help content will be critical.
- Guide users to not create overly complex setups with too many key sets or activation rules.
- Allow for unified timelock reset experience.
- Provide templates for easy access to common key set configurations.
Technical considerations #
- Complexities of multi-key setups.
- Saving not yet created wallet configurations on the application layer.
- Using Taproot for better privacy and transaction economics.
- Batching transactions to consolidate UTXOs vs. coin control and selective timelock refresh.