Wallet Creation

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

When creating a wallet, each of these items need to be generated. However, what we do with them post-generation is different for each item and dependent on your user experience. Skip down to some examples below to see what the UX might be like for your users.

Key Generation

The first thing we need to do is create keys for your wallet holders to sign transactions. Our HD wallet architecture means that a wallet holder will have multiple key pairs as part of their wallet.

When your user creates a wallet, a private key pair for signing is created as needed for each supported blockchain. The different signing keys all roll up to a single seed phrase as described in Key Architecture Overview.

Once the wallet creation operation is complete, the seed phrase is encrypted and sent to the client. Then all other keys are discarded. We do not store or transport private keys.

Seed Phrase Generation

Within our cross chain key architecture, the mnemonic is at the heart of our key management system. In addition to private keys, when the wallet is initialized, the mnemonic aka the seed phrase for that wallet is created. When a wallet is created (not imported), our seed phrases are 24 words.

Unlike the private keys, the mnemonic is transported. However, it is not stored.

Asset Initialization

Finally, once your seed and key pairs are set up, we initialize assets that belong to a wallet. The assets that are setup by default can be configured in the enterprise portal as described in Getting Started..

Use Case Examples

Because any tokenized asset can be associated with a user's wallet, the point in which it makes the most sense for a user to create a wallet can be custom to your platform.

Standard implementation of wallet creation within the account setup process. You may require additional steps depending on your security requirements.

Our wallet is designed to be embedded into your existing product wherever it makes sense. In some cases, it may make sense to add it directly into your account creation process. In other cases, it may make sense to delay it to a later step such as when a user is creating their first character in a game or when a user is making their first investment.

Custom implementation of a wallet used as the backpack of an online game character.

Start creating wallets

If you proceed with creating a wallet from scratch, you will create a new seed phrase for the user. If instead you would like to...

1. create a new wallet from an existing seed phrase, please use Wallet Import.

2. fetch a user's preexisting wallet, please use Wallet Recovery.

To actually get started, you'll need to determine whether you want to use our SDK or our APIs directly. In order to determine which product is right for you, take a look at SDK vs API.

SDK

With our SDK, you will always use the create function with a unique identifier from your system to represent the user. Implementation is described in more detail in in the developer docs: Creating 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 a new 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 create a wallet for that user.

3. If we detect that a user with this unique identifier does already exist and has a wallet, then we sign them in and create an additional wallet for that user.

   1. 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 create multichain, HD wallets that have full access to our services and data layer with some additional development work.

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 create a wallet via API, you simply need to call the create wallet APIs with valid authentication - system and user level auth. For more implementation information go to Creating a wallet with APIs.

3. 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

4. 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, create a 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. create a wallet

   1. create wallet utilizing authentication from step 1

3. encrypt and store the mnemonic

   1. decrypt the seed phrase

   2. display it to the user

   3. encrypt it with desired encryption factors

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

   5. discard it from memory

4. encrypt and store the private key

   1. encrypt client auth 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, create a new 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 encrypted seed phrases.