Manage User Wallet

This document outlines the steps to create, unlock and recover user wallet.

After authenticating with ZumoKit (see Getting Started), user has to create a new wallet if there is no wallet on file. If user already has a wallet he cannot create a new wallet, instead he has to unlock or recover existing wallet.

To check if user has a wallet use hasWallet helper method (attribute in React Native) on user object:

Android

iOS

React Native

boolean hasWallet = user.hasWallet();

BOOL hasWallet = [user hasWallet];

const hasWallet = user.hasWallet;

If user has a wallet, user and state objects are automatically populated with user's accounts (BTC, ETH, etc.). See View User Data for details.

Create Wallet

Wallet creation is a two stage process. First, a mnemonic seed phrase is generated. Once you have a seed phrase, this can then be used in tandem with a password to generate a new wallet.

The first step in creating a wallet is the generation of a mnemonic seed phrase. This is handled by the generateMnemonic method on the ZumoKit SDK utils class.

A single parameter can be provided which defines the number of words that should be generated. In the example below, you can see that 12 is the parameter provided to the generateMnemonic method. This is a sensible default but if security is paramount, this can be increased.

Android

iOS

React Native

Utils utils = zumoKit.utils();
String mnemonic = utils.generateMnemonic(12);

ZKUtils *utils = [zumoKit utils];
NSString *mnemonic = [utils generateMnemonic:12];

const mnemonic = await ZKUtility.generateMnemonic(12);

Once a mnemonic phrase has been generated, this can then be used to create a new wallet. To do this, provide mnemonic and password to the createWallet method on the user object.

Android

iOS

React Native

user.createWallet(mnemonic, password, new WalletCallback() {
    @Override
    public void onError(Exception e) {
        // Wallet not created. Check exception details.
    }

    @Override
    public void onSuccess(Wallet wallet) {
        // Wallet succesfully created!
    }
});

[user createWallet: mnemonic
          password:"password
        completion:^(ZKWallet * _Nullable wallet, NSError * _Nullable error){
    // Check if error is not nil to see if there was an issue creating wallet.
}];

try {
    const wallet = async user.createWallet(mnemonic, password);
} catch(error) {
    // Handle error creating wallet here.
}

Once wallet is created user and state objects are automatically populated with user's accounts (BTC, ETH, etc.). See View User Data for details. These accounts can be immediately shared as payment addresses.

When the accounts are funded, i.e. BTC, ETH and possible other funds are transferred to these accounts, user can start sending outgoing transactions.

Unlock Wallet

If user already has a wallet, this wallet has to be unlocked in order to send outgoing transactions.

Android

iOS

React Native

user.unlockWallet(password, new WalletCallback() {
    @Override
    public void onError(Exception e) {
       // Wallet not unlocked. Check exception details.
    }

    @Override
    public void onSuccess(Wallet wallet) {
       // Wallet succesfully unlocked!
    }
});

[user unlockWallet:password
         completion:^(ZKWallet * _Nullable wallet, NSError * _Nullable error) {
    // Check if error is not nil to see if there was an issue creating wallet.
}];

try {
    const wallet = async user.unlockWallet(password);
} catch(error) {
    // Handle error unlocking wallet here.
}

Reveal Mnemonic

Once user has created a wallet, he can use wallet unlock password to reveal his mnemonic.

Android

iOS

React Native

user.revealMnemonic(password, new MnemonicCallback() {
    @Override
    public void onError(Exception e) {
       // Mnemonic not decrypted. Check exception details.
    }

    @Override
    public void onSuccess(String mnemonic) {
       // Mnemonic succesfully decrypted!
    }
});

[user revealMnemonic:password
         completion:^(NSString * _Nullable mnemonic, NSError * _Nullable error) {
    // Check if error is not nil to see if there was an issue creating wallet.
}];

try {
    const mnemonic = async user.revealMnemonic(password);
} catch(error) {
    // Handle error decrypting mnemonic here.
}

Recover Wallet

User can recover his wallet even if he forgets his user password as long as he can provide the mnemonic phrase that was used for creating his wallet.

One can check if the mnemonic is correct by calling utility method isRecoveryMnemonic on user object:

Android

iOS

React Native

boolean isValidMnemonic = user.isRecoveryMnemonic(mnemonic);

BOOL isValidMnemonic = [user isRecoveryMnemonic:mnemonic];

const isValidMnemonic = user.isRecoveryMnemonic(mnemonic);

This can be useful when creating recovery form with realtime validation.

With a valid mnemonic wallet recovery process is identical to wallet creation method:

Android

iOS

React Native

user.recoverWallet(mnemonic, password, new WalletCallback() {
    @Override
    public void onError(Exception e) {
        // Wallet not recovered. Check exception details.
    }

    @Override
    public void onSuccess(Wallet wallet) {
        // Wallet succesfully recovered!
    }
});

[user recoverWallet: mnemonic
           password:"password
         completion:^(ZKWallet * _Nullable wallet, NSError * _Nullable error){
    // Check if error is not nil to see if there was an issue creating wallet.
}];

try {
    const wallet = async user.recoverWallet(mnemonic, password);
} catch(error) {
    // Handle error recovering wallet here.
}