Wallet Import

As defined in our core wallet module, a Wallaby wallet consists of three parts:

1. a set of (multiple) key pairs used to sign onchain transactions

2. a master seed phrase

3. assets associated with your wallet

In standard wallet creation, each of these parts are generated from scratch. However, since the Wallaby platform was designed with interoperability in mind, we allow you to import a seed phrase instead of generating a new one.

Key Differences Wallet Creation vs Import

When importing a wallet, we do not generate a seed phrase for you. Instead we utilize the given seed phrase. This means that the underlying transaction signing keys and addresses associated with that seed phrase will be the same as the imported wallet. However, for blockchains where the given seed phrase {question for Eddy} is not compatible, we generate new keys that are accessible within our system with that same seed.

{image of key differences}

Import does not impact asset initialization so wallets that are imported will still have the same default associated assets as newly created wallets.

Key Differences Wallet Recovery vs Import

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

Like most standard wallets, you can add the wallet import capability side-by-side to the new wallet creation flow.

{Wireframe Example}

However, if there are scenarios where you know a user will have a pre-existing wallet, you can create an import only flow for them.

{Wireframe Example}

How to import

SDK

With our SDK, you will always use the import function with a unique identifier from your system to represent the user. Implementation is described in more detail in in the developer docs: Importing a wallet with the SDK.

Expected Behavior

You should expect the following behavior when using this function:

1. If we detect that a user with this unique identifier does not already exist, then we will create a new account and import the wallet.

2. If we detect that a user with this unique identifier does already exist, but does not have a wallet, then we sign them in and import the wallet for that user.

3. If we detect that a user with this unique identifier does already exist and has a wallet, then we check if they already have a wallet with that seed phrase.

   1. If they don't, sign them in and create an additional wallet for that user. **

   2. If they do already have a wallet with that seed phrase, you will see an error telling you to recover the wallet instead.

   ** If you would like to restrict a user from having multiple wallets, you will need to create this restriction on your end.

API

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 import a wallet which converts it to a multichain, HD Wallaby wallet.

Flow of Operations

1. Wallaby Authentication

Wallaby requires both an API key and an access token in order to utilize our APIs. With both those requirements, 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. Wallet Creation

In order to import a wallet via API, you simply need to call the import wallet APIs with valid authentication - system and user level auth. For more implementation information go to Import a wallet with APIs.

3. Seed Phrase Storage

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 about this in API only: Choosing encryption factors for the seed phrase &

Scenarios to Handle

New User Without a Wallet

In this scenario, you are handling a brand new user without a wallet. In order to do this, you need to create a new account, import the new wallet, and securely encrypt and store the mnemonic.

If the user does not already exists, you will need to

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 up with the public key, message, and the signature

2. import a wallet

   1. import wallet utilizing authentication from step 1

3. encrypt and store the mnemonic

   1. encrypt it with desired encryption factors

   2. store it in desired storage location (not on your system!)

   3. discard it from memory

4. encrypt and store the private key

   1. encrypt private key with desired encryption factors

   2. store it in desired storage location

   3. discard it from memory

Existing User without a wallet

In this scenario, you are handling an existing user without a wallet. In order to do this, you need to fetch the existing account, import the wallet, and securely encrypt and store the mnemonic. Same process as stated above, however, authentication differs. Instead for authentication you will..

1. retrieve your (client) public key and encrypted private key,

2. decrypt the private key,

3. generate a signature message using the public key,

4. generate a signature using the private key,

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

Existing User with an Existing wallet

In this scenario, you are handling an existing user with an existing wallet. In order to do this, you need to fetch the existing account, create a second wallet, and securely encrypt and store the mnemonic. The main difference from above is that if you plan to utilize more than one wallet per user, you should be distinguishing additional wallets from the original when storing the encrypted seed phrases.

You should also handle the error scenario where the user already has a wallet with that seed phrase. In this case, we return an error requesting that you recover the wallet instead.