jwallet-web-keystore

Library for ethereum blockchain wallets management.

About

Keystore can hold read only / full access wallets of two types:

• privateKey / address
• mnemonic / bip32XPublicKey

Also Keystore API provides several utility methods for working with mnemonics / hashes / passwords.

Get Started

npm install jwallet-web-keystore

import keystore from 'jwallet-web-keystore'

Available npm scripts:

• lint: check code-style errors
• test: run mocha tests
• clean: clean ./lib dir
• compile: clean, then compile library
• build: lint & compile & test

Wallet properties

Property	Type	Description
id	String	Unique ID of wallet
type	String	Type of wallet (mnemonic / address)
name	String	Wallet name
address	String	Address of wallet
customType	String	User-friendly type of wallet
isReadOnly	Boolean	Read-only flag of wallet
bip32XPublicKey	String	BIP32 Extended Public Key
addressIndex	Number	Current index of address of mnemonic wallet
passwordOptions	Object	Container with options for password management
passwordOptions.salt	String	Salt for enforcing of password
passwordOptions.encryptionType	String	Type of encryption
passwordOptions.saltBytesCount	Number	Number of bytes for salt parameter
passwordOptions.derivedKeyLength	Number	Size of derived from password key
passwordOptions.scryptParams	Object	Scrypt function params, that used for password key derivation
passwordOptions.scryptParams.N	Number	CPU/memory cost parameter
passwordOptions.scryptParams.r	Number	The blocksize parameter
passwordOptions.scryptParams.p	Number	Parallelization parameter
mnemonicOptions	Object	Container with options for mnemonic management
mnemonicOptions.network	String	Network (e.g. 'livenet' or 'testnet')
mnemonicOptions.passphrase	String	BIP39 passphrase
mnemonicOptions.derivationPath	String	Path for derivation of keys from BIP32 Extended Key
mnemonicOptions.paddedMnemonicLength	Number	Fixed mnemonic length after leftpad with spaces
encrypted	Object	Container of encrypted data
encrypted.mnemonic	Object	Encrypted mnemonic
encrypted.privateKey	Object	Encrypted private key

Notes:

• isReadOnly - flag means that wallet can be used only for balance / transactions checking
• bip32XPublicKey - xpub... key that used for deriving of public keys (addresses)
• encrypted data(mnemonic/privateKey fields) - it is object, that looks like:

encrypted.mnemonic = {
  data: base64 string (encrypted),
  nonce: base64 string,
}

Public API definitions

See mocha tests for examples of usage.

Methods for wallets management

getWallet(wallets, walletId)

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet

Returns

Wallet found by its ID, otherwise exception will be thrown.

Example

const wallets = keystore.createWallet(...)
const wallet = keystore.getWallet(wallets, 'JHJ23jG^*DGHj667s')

createWallet(wallets, props, password)

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
props	Object	New wallet data
props.scryptParams (optional)	Object	scrypt function params (see wallet properties)
props.data	String	main wallet data: address/privateKey/mnemonic/bip32XPublicKey
props.name (optional)	String	name of new wallet
props.network (optional)	String	network
props.passphrase (optional)	String	BIP39 passphrase
props.derivationPath (optional)	String	derivation path
props.encryptionType (optional)	String	encryption type
props.saltBytesCount (optional)	Number	size of salt for password
props.derivedKeyLength (optional)	Number	size of key, derived from password with scrypt function
props.paddedMnemonicLength (optional)	Number	size of mnemonic phrase before encryption
password	String	wallet password. Used only for full access wallets: mnemonic/privateKey

Returns

List of wallets with new created one, otherwise exception will be thrown.

Example

const password = 'JHJ23jG^*DGHj667s'

const walletsOne = keystore.createWallet(wallets, {
  name: 'My privateKey wallet',
  data: '0x8a02a99cc7a801da6996a2dacc406ffa5190dc9c8a02a99cc7a801da6996a2da',
}, password)

const walletsTwo = keystore.createWallet(walletsOne, {
  name: 'My address wallet',
  data: '0x8a02a99ee7a801da6996a2dacc406ffa5190dc9c',
}, password)

const walletsThree = keystore.createWallet(walletsTwo, {
  name: 'My xpub wallet',
  data: 'xpub...',
}, password)

const walletsFour = keystore.createWallet(walletsThree, {
  name: 'My mnemonic wallet',
  data: '<mnemonic phrase here>',
}, password)

removeWallet(wallets, walletId)

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet

Returns

List of wallets without removed one, otherwise exception will be thrown.

Example

const walletsNew = keystore.removeWallet(wallets, '110ec58a-a0f2-4ac4-8393-c977d813b8d1')

addMnemonic(wallets, walletId, mnemonic, password)

Note: used only for read-only mnemonic wallets.

This method is used to extend bip32Xpub wallet permissions (to make it full-access wallet).

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
mnemonic	String	New mnemonic for wallet (from which bip32XPublicKey was derived)
password	String	New password for wallet

Returns

List of wallets with updated one, otherwise exception will be thrown.

Example

const walletsNew = keystore.addMnemonic(wallets, walletId, mnemonic, password)

addPrivateKey(wallets, walletId, privateKey, password)

Note: used only for read-only address wallets.

This method is used to extend address wallet permissions (to make it full-access wallet).

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
privateKey	String	New privateKey for wallet (from which address was obtained)
password	String	New password for wallet

Returns

List of wallets with updated one, otherwise exception will be thrown.

Example

const walletsNew = keystore.addPrivateKey(wallets, walletId, privateKey, password)

setWalletName(wallets, walletId, name)

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
name	String	New wallet name

Returns

List of wallets with new updated one, otherwise exception will be thrown.

Example

const walletId = '110ec58a-a0f2-4ac4-8393-c977d813b8d1'
const name = 'New wallet name'
const walletsNew = keystore.setWalletName(wallets, walletId, name)

setAddressIndex(wallets, walletId, addressIndex)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
addressIndex (optional)	Number	Index of address to derive from mnemonic / bip32XPublicKey

Returns

List of wallets with new updated one, otherwise exception will be thrown.

Example

const walletsNew = keystore.setAddressIndex(wallets, walletId, addressIndex)

setDerivationPath(wallets, walletId, password, derivationPath)

Note: used only for full-access mnemonic wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password
derivationPath	String	New derivation path

Returns

List of wallets with new updated one, otherwise exception will be thrown.

Example

const derivationPath = 'm/44\'/61\'/0\'/0'
const walletsNew = keystore.setDerivationPath(wallets, walletId, password, derivationPath)

setMnemonicPassphrase(wallets, walletId, password, passphrase)

Note: used only for full-access mnemonic wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password
passphrase	String	BIP39 passphrase

Returns

List of wallets with new updated one, otherwise exception will be thrown.

Example

const passphrase = 'somepassphrase'
const walletsNew = keystore.setMnemonicPassphrase(wallets, walletId, password, passphrase)

setPassword(wallets, walletId, password, newPassword)

Note: not available for read-only wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password
newPassword	String	New keystore password

Returns

List of wallets with new updated one, otherwise exception will be thrown.

Example

const newPassword = 'Tw5E^g7djfd(29j'
const walletsNew = keystore.setPassword(wallets, walletId, password, newPassword)

getAddress(wallets, walletId)

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet

Returns

Current address of wallet.

Example

const address = keystore.getAddress(wallets, walletId)

getAddresses(wallets, walletId, startIndex, endIndex)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
startIndex	Number	Start index of address to derive
endIndex	Number	Finish index of address to derive

Returns

List of derived addresses, otherwise exception will be thrown.

Example

const startIndex = 3
const endIndex = 10
const addresses = keystore.getAddressesFromMnemonic(wallets, walletId, startIndex, endIndex)

getPrivateKey(wallets, walletId, password)

Note: not available for read-only wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password

Returns

Decrypted private key, otherwise exception will be thrown.

Example

const privateKey = keystore.getPrivateKey(wallets, walletId, password)

getMnemonic(wallets, walletId, password)

Note: used only for full-access mnemonic wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password

Returns

Decrypted mnemonic, otherwise exception will be thrown.

Example

const mnemonic = keystore.getMnemonic(wallets, walletId, password)

getWalletData(wallets, walletId, password)

Note: password required only for full-access wallets.

Parameters

Param	Type	Description
wallets	Array	List of existed wallets
walletId	String	Unique ID of wallet
password	String	Wallet password

Returns

Wallet with decrypted data, otherwise exception will be thrown.

Example

const walletData = keystore.getWalletData(wallets, walletId, password)

serialize()

Returns

Serialized keystore data for backup.

Example

const keystoreSerializedData = keystore.serialize(wallets)

deserialize(backupData)

Parameters

Param	Type	Description
backupData	String	Keystore serialized data

Example

const backupData = '{"wallets":[{"type":"mnemonic","id":"2e820ddb-a9ce-43e1-b7ec-dbed59eec7e9",...'
const keystoreDeserializedData = keystore.deserialize(backupData)

Utility methods

testPassword(password)

Param	Type	Description
password	String	Wallet password

Returns

Object that contains following fields:

• score - estimated strength index
• feedback - verbal feedback to help choose better passwords. set when score < 3
  • warning - explains what's wrong
  • suggestions - a possibly-empty list of suggestions to help choose a less guessable password

Example

const result = keystore.testPassword('JHJ23jG^*DGHj667s')

generateMnemonic(entropy, randomBufferLength)

Param	Type	Description
entropy (optional)	String	Entropy for mnemonic initialisation (see new Mnemonic)
randomBufferLength (optional)	Number	Buffer length (if entropy param is used)

Returns

Mnemonic - string with 12 English words splited by space.

Example

const mnemonic = keystore.generateMnemonic()

checkMnemonicValid(mnemonic)

Parameters

Param	Type	Description
mnemonic	String	Mnemonic to check

Returns

true if mnemonic is valid and false otherwise.

Example

const mnemonic = 'come average primary sunny profit eager toy pulp struggle hazard tourist round'
const isValid = keystore.checkMnemonicValid(mnemonic) // true

checkBip32XPublicKeyValid(bip32XPublicKey)

Param	Type	Description
bip32XPublicKey	String	BIP32 Extended Public Key

Returns

true if bip32XPublicKey is valid and false otherwise.

Example

const isValid = keystore.checkBip32XPublicKeyValid('xpub...')

checkAddressValid(address)

Param	Type	Description
address	String	Address to check. Accepts checksummed addresses too

Returns

true if address is valid and false otherwise.

Example

const isValid = keystore.checkAddressValid('0x8a02a99ee7a801da6996a2dacc406ffa5190dc9c')

checkChecksumAddressValid(address)

Param	Type	Description
address	String	Address to check

Returns

true if address contains checksum and false otherwise.

Example

const isValid = keystore.checkChecksumAddressValid('0x8a02a99ee7a801da6996a2dacc406ffa5190dc9c')

checkPrivateKeyValid(privateKey)

Param	Type	Description
privateKey	String	Private Key to check

Returns

true if privateKey is valid and false otherwise.

Example

const pk = '0xa7fcb4efc392d2c8983cbfe64063f994f85120e60843407af95907d905d0dc9f'
const isValid = keystore.checkPrivateKeyValid(pk)

checkDerivationPathValid(derivationPath)

Param	Type	Description
derivationPath	String	Derivation path

Returns

true if derivationPath is valid and false otherwise.

Example

const isValid = keystore.checkDerivationPathValid("m/44'/60'/0'/0")