Wallet recovery
There are several reasons why a user might need to restore their bitcoin wallet. They may have lost their phone or accidentally deleted their wallet application. Perhaps they have simply bought a new phone and wish to migrate their wallet over. Regardless of why, it’s important that your wallet application has an easy way for users to recover their funds.
This wallet is designed to make the recovery process as easy as possible for the user. It can pull the user’s channel state from the cloud backup, allowing the user to pick up right where they left off. It will also sync contacts and metadata from the cloud backup, so there is no loss of useful transaction history. The recovery phrase can be pulled from a cloud backup or manually provided by the user.
Recovery Scenarios
While it may not be possible to account for every possible scenario, this wallet attempts to solve for a variety of scenarios that fall into one of two categories.
Basic Recovery
“Basic recovery scenarios” are somewhat expected situations for a person with a mobile device.
- The user loses their phone
- The user upgrades to a new phone
- The user accidentally deletes the wallet app
Emergency Recovery
“Emergency recovery scenarios” include situations where a user may need to recover their funds in a hostile or catastrophic situation. Examples include:
- App provider or LSP goes out of business
- App provider or LSP becomes malicious
- App provider or LSP has a serious technical malfunction
While this may seem outside the scope of normal thinking for a product, it is reasonable in this situation due to the collaborative nature of lightning channels. While it should be within the incentive of a business such as the LSP or the app developer to always want to help their customer, that can not always be guaranteed. Therefore, this product equips the user to protect their funds even from a failure of the business creating the product. This demonstrates serious commitment to design principles!
Recovering with an automatic cloud backup
This is by far the simplest way to recover the wallet. The user opts to restore from their cloud backup. The app checks the cloud account for a backup and restores the lightning node on the user’s device. This works great for basic recovery scenarios.
Beginning of the restore flow.
App searches for the cloud backup.
Wallet restores from cloud backup.
Wallet is finished being restored.
The wallet has been successfully restored.
Recovering with a manual backup
This involves a few more steps, but should work just as well as the auto cloud backup. This works great for basic recovery scenarios. In the manual restore, the primary difference is that the app asks the user to type in their recovery phrase. It will attempt to automatically pull their lightning channel state from cloud backup.
User selects "advanced" from the restore screen, and is taken here.
User enters their recovery phrase. The app can notify them if a word is incorrect before they have finished typing it.
User enters their recovery phrase. The app can autocomplete words for the user.
User successfully enters their entire recovery phrase.
App begins to restore, pulling the channels backup automatically from the cloud.
Wallet is finished being restored.
The wallet has been successfully restored.
Use autocomplete
This wallet makes the recovery process easier for the user by autocompleting the words of their recovery phrase as they type. Since recovery phrases are comprised of words from a predefined dictionary of 2,048 words, the app is usually able to autocomplete or detect a typo with only 3 or 4 letters typed.
Other situations
Cloud backup screws up
While this wallet will attempt to pull channel state from a cloud backup, there may be situations in which this does not work automatically. A simple example would be if the user set up the wallet on iOS, but is migrating to Android. This could be remedied by allowing the user to specify another cloud account to use.
The user has finished entering their recovery phrase and taps "Next".
The app fails to automatically find a channel state backup in the user’s cloud account. User chooses to try another cloud account.
User chooses their cloud provider.
User authenticats with the cloud provider, finds the backup file, etc.
The app checks the backup file the user has selected.
The app determines this is a valid channel state backup.
App begins to restore, pulling the channels backup automatically from the cloud.
Wallet is finished being restored.
The wallet has been successfully restored.
A more complicated and unlikely scenario is one in which the channel’s backup has gotten corrupted in the user’s cloud account or deleted somehow. In this situation, the LSP can force close the channels for the user. This would send the user’s funds to an on-chain address. Once those funds are confirmed on-chain, the wallet will then automatically use those funds to open fresh channels with the LSP for the user. However, this will take some time, so the wallet is very clear in letting the user know that this will take longer.
The app fails to automatically find a channel state backup in the user’s cloud account. User chooses "I can’t find it".
The app offers to help the user restore anyways, but warns that there will be a delay in accessing funds.
App sends a signal back to the LSP to attempt to force close the channels.
The force close has been initiated, so the restore has effectively worked.
App reminds the user of the delay in accessing funds.
The delay is also indicated on the homescreen of the app.
Handling emergency scenarios
In a situation where the app provider or LSP is offline or uncooperative, the user will have no assistance in getting their funds. While this situation is unlikely, it should be prepared for.
This wallet offers an open source wallet recovery tool. This tool is available on GitHub and linked to from their website. In the event that the app is taken down from app stores or the LSP’s node is down for an extended period of time, the user can use their backup to force close their channels and have all their bitcoin sent to an on-chain address.
Hopefully the user would never encounter a situation like this. However, if we treat bitcoin as digital cash, then we must take these sorts of situations into account when designing for the lightning network.
Next, let’s take a deep dive into requesting bitcoin.