Wallet Recovery

Although the wallet holder is not required to input their seed phrase with each use of their wallet, it is highly recommended that you display the seed phrase during the wallet creation process. This is because our system requires the wallet holder's seed phrase in order to later recover a wallet.

When to recover a wallet

Both wallet recovery and wallet import require your seed phrase. However, wallet recovery retrieves the specific instance of that wallet which includes wallet data, wallet addresses, and user data.

Importing a wallet creates a new instance of that wallet even if another wallet with that seed phrase exists. Any wallet data would have to be recreated or fetched again from the blockchain. Wallet services that require approvals would need to be reverified.

Use Case Examples

If the current user already has an associated wallet within your system, then you would want to utilize wallet recovery. Examples:

1. if an existing wallet holder is setting up their account on a new device

2. if the existing wallet holder lost access to an encryption factor such as their wallet password

Context Specific Recovery

Although, you may also choose to customize the page depending on the scenario. We recommend catching missing or corrupted keys with a generic flow upon landing on any wallet related page.

Generic Recovery Screen

Alternatives to the Seed Phrase

Although the seed phrase is the ultimate backup for your wallet and we highly recommend exposing it to the user to maintain interoperability, we've created a seed phrase recovery service which allows you to create key shares that can be used to regenerate your seed phrase on demand. This makes the seed phrase optional, as long as the minimum threshold of key shares are accessible.

The key share scheme is customizable and these key shares can be distributed and stored as desired which allows you to innovate on backup mechanisms. Read more in Seed Phrase Recovery (Beta).

How to recover a wallet

In order to recover a wallet, you must determine whether you would like to do so with the SDK or with the APIs. If you chose to create a wallet with the SDK, we recommend using the SDK for recovery. If you chose to create a wallet with the APIs, you will need to use take the same approach to recovery.

SDK

With our SDK, you will always use the recover function regardless of the scenario where recovery is needed. You will be responsible for detecting that the keys in storage are not found or are corrupted.

The recover function of the SDK handles

1. authentication,

2. initiating recovery from Wallaby,

3. seed phrase encryption and transportion to Wallaby

4. seed phrase decryption from Wallaby

5. client side seed phrase encryption and storage

Implementation is described in more detail in in the developer docs: Recovering a wallet with the SDK

Expected Behavior

You should expect the following behavior when using this function:

1. (Happy path) If we detect that a wallet with the given seed phrase/user id combo already exists, then we recover it.

2. If we detect that the wallet with a given seed phrase does not exist, then we throw an error.

3. If we detect that the given seed phrase does not match that user, then we ?

4. If we try to store the seed phrase, but find that it already exists, then we ?

API

If you've chosen to take an API approach to wallet creation, you will also need to use the same approach for recovery. This does require additional development work described below.

Flow of Operations

Although the SDK, wraps up the complexity described below into streamlined functions, the SDK may not be the right fit depending on your use case. If that's the case, you can still utilize the APIs to recover existing wallets with some additional development work. That includes:

1. Wallaby Authentication

Wallaby requires both an API key and an access token in order to utilize our APIs. With both those requirements fulfilled, we are able to authenticate your system to utilize the Wallaby APIs. However, we still need to authenticate the user themselves. Wallaby's authentication system for end users utilizes SRP protocol. Read more about it in . For more implementation information, go to .

2. Initiating Recovery

In order to recover a wallet via API, you need to initiate the process with the current external user id and the client auth public key. This will provide you with a transport key for the seed phrase. For more implementation information go to Recovering a wallet with APIs.

3. Seed Phrase Encryption/Transportation to Wallaby

To keep the the user's seed phrase secure, you will need to encrypt it first. In order to do this, you should utilize the Wallaby auth public key you retrieved in the recovery initiation process. Read more about this in . After the seed phrase is encrypted, you can send it to wallaby via the recover API.

4. Seed Phrase Decryption

When wallet creation is complete, you will receive the encrypted seed phrase and the assets associated with the newly created wallet. In order to display the seed phrase to the wallet holder for storage, you will need to decrypt it using the client auth private key. Read more about this in

5. Seed Phrase Encryption/Storage

Finally, when wallet recovery is complete, you will receive the encrypted seed phrase and the assets associated with the recovered wallet. Depending on the security level required, the encryption factors may vary. The SDK utilizes three encryption factors a user input (password/pin), a salt value inaccessible without client side authentication, and an additional authentication key stored on the user's device. Read more in API only: Choosing encryption factors for the seed phrase

Scenarios

Successful Recovery

For wallet recovery, we can assume this is an existing user in Wallaby...

1. authenticate

   1. generate a (client) public key and private key

   2. generate a signature message using the public key

   3. generate a signature using the private key

   4. sign in with the public key, message, and the signature

2. initialize wallet recovery

   1. create wallet utilizing authentication from step 1

3. recover the wallet

   1. encrypt seed phrase with wallabyAuthPubKey from step 2

   2. send to wallaby with recover API

4. encrypt and store the returned wallet

   1. encrypt private key with desired encryption factors

   2. store it in desired storage location

   3. discard it from memory

Unsuccessful Recovery

Steps 1-3 are the same, but for step 4 you will receive an error which you will have to handle. One example may be their is no wallet with that seed phrase belonging to the current user.