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

const Keystore = require('jwallet-web-keystore')

const keystore = new Keystore(props)

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
salt	String	Salt for enforcing of password
address	String	Address of wallet
customType	String	User-friendly type of wallet
isReadOnly	Boolean	Read-only flag of wallet
addressIndex	Number	Current index of address of mnemonic wallet
derivationPath	String	Derivation path for generating of addresses from mnemonic
bip32XPublicKey	String	BIP32 Extended Public Key
encrypted	Object	Container of encrypted data
encrypted.privateKey	Object	Encrypted private key
encrypted.mnemonic	Object	Encrypted mnemonic

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)

Public API definitions

See mocha tests for examples of usage.

new Keystore(props)

Instantiates Keystore object with provided props.

Parameters

Param	Type	Default	Description
props	Object	{}	Constructor properties
props.defaultDerivationPath	String	"m/44'/60'/0'/0"	Default derivation path for new Mnemonic wallets
props.defaultEncryptionType	String	'nacl.secretbox'	Default encryption type. Currently nacl.secretbox is only one supported
props.paddedMnemonicLength	Number	120	Mnemonic will be padded left with this size before encryption
props.saltByteCount	Number	32	Count of bytes of generated salt for password strength
props.scryptParams	Object	{ N: 2 ** 18, r: 8, p: 1 }	Scrypt params for key deriving
props.derivedKeyLength	String	32	Derived key length
props.passwordConfig	Object	{}	Options to test password strength

Returns

New instance of Keystore class.

Example

const keystore = new Keystore({ defaultDerivationPath: "m/44'/61'/0'/0" })

Instance methods

getWallets()

Returns

Wallets list presented in keystore.

Example

const wallets = keystore.getWallets()

getWallet(walletId)

Parameters

Wallet ID.

Returns

Wallet found by its ID.

Example

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

createWallet(props)

Parameters

wallet properties(Wallet properties):

• type
• name
• address
• mnemonic
• isReadOnly
• privateKey
• derivationPath
• bip32XPublicKey

Returns

Unique ID of created wallet

Example

const walletId = keystore.createWallet({
  type: 'address',
  name: 'My wallet',
  isReadonly: false,
  password: 'JHJ23jG^*DGHj667s',
  privateKey: '0x8a02a99cc7a801da6996a2dacc406ffa5190dc9c8a02a99cc7a801da6996a2da',
})

removeWallet(walletId)

Parameters

Param	Type	Description
walletId	String	Unique ID of wallet

Returns

Removed wallet data.

Example

const removedWallet = keystore.removeWallet('110ec58a-a0f2-4ac4-8393-c977d813b8d1') // data

removeWallets()

Example

keystore.removeWallets() // ok, wallets were removed

setWalletName(walletId, newName)

Parameters

Param	Type	Description
walletId	String	Unique ID of wallet
newName	String	New wallet name

Returns

Updated wallet.

Example

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

getPrivateKey(password, walletId)

Parameters

Param	Type	Description
password	String	Wallet password
walletId	String	Unique ID of wallet

Returns

Decrypted private key.

Example

const privateKey = keystore.getPrivateKey('JHJ23jG^*DGHj667s', '110ec58a-a0f2-4ac4-8393-c977d813b8d1')

setDerivationPath(password, walletId, newDerivationPath)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
password	String	Wallet password
walletId	String	Unique ID of wallet
newDerivationPath	String	New derivation path

Note: default derivation path that will be assigned to all new created wallets can be managed by defaultDerivationPath constructor parameter.

Returns

Updated wallet.

Example

const updatedWallet = keystore.setDerivationPath('JHJ23jG^*DGHj667s', '110ec58a-a0f2-4ac4-8393-c977d813b8d1', "m/44'/61'/0'/0")

getMnemonic(password, walletId)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
password	String	Wallet password
walletId	String	Unique ID of wallet

Returns

Decrypted mnemonic.

Example

const mnemonic = keystore.getMnemonic('JHJ23jG^*DGHj667s', '110ec58a-a0f2-4ac4-8393-c977d813b8d1')

getAddressesFromMnemonic(walletId, iteration, limit)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
walletId	String	Unique ID of wallet
iteration	Number	Iteration index (aka page for pagination) to generate bunch of addresses
limit	Number	Count of addresses to generate from mnemonic per one page / iteration

Returns

List of generated addresses.

Example

const addresses = keystore.getAddressesFromMnemonic('110ec58a-a0f2-4ac4-8393-c977d813b8d1', 3, 10)

getAddress(walletId, addressIndex)

Parameters

Param	Type	Description
walletId	String	Unique ID of wallet

Returns

Current address of wallet.

Example

const address = keystore.getAddress('110ec58a-a0f2-4ac4-8393-c977d813b8d1')

setAddressIndex(walletId, addressIndex)

Note: used only for mnemonic wallets.

Parameters

Param	Type	Description
walletId	String	Unique ID of wallet
addressIndex	String	Index of address to derive from mnemonic / bip32XPublicKey

Returns

Updated wallet.

Example

const updatedWallet = keystore.setAddress('110ec58a-a0f2-4ac4-8393-c977d813b8d1', 5)

serialize()

Returns

Serialized keystore data for backup.

Example

const keystoreSerializedData = keystore.serialize()

deserialize(backupData)

Parameters

Param	Type	Description
backupData	String	Keystore serialized data

Example

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

getDecryptedWallet(password, walletId)

Parameters

Param	Type	Description
password	String	Wallet password
walletId	String	Unique ID of wallet

Returns

Wallet with decrypted data.

Example

const decryptedWallet = keystore.getDecryptedWallets('JHJ23jG^*DGHj667s', '110ec58a-a0f2-4ac4-8393-c977d813b8d1')

setPassword(password, newPassword, walletId)

Parameters

Param	Type	Description
password	String	Wallet password
newPassword	String	New keystore password
walletId	String	Unique ID of wallet

Example

keystore.setPassword('JHJ23jG^*DGHj667s', 'Tw5E^g7djfd(29j', '110ec58a-a0f2-4ac4-8393-c977d813b8d1')

Static methods

generateMnemonic(entropy, randomBufferLength)

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

Returns

Mnemonic - 12 English words splited by space.

Example

const mnemonic = Keystore.generateMnemonic()

isMnemonicValid(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.isMnemonicValid(mnemonic) // true

isBip32XPublicKeyValid(bip32XPublicKey)

Param	Type	Description
bip32XPublicKey	String	BIP32 Extended Public Key

Returns

true if bip32XPublicKey is valid and false otherwise.

Example

const isValid = Keystore.isBip32XPublicKeyValid('xpub...')

isAddressValid(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.isAddressValid('0x8a02a99ee7a801da6996a2dacc406ffa5190dc9c')

isPrivateKeyValid(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.isPrivateKeyValid(pk)

isDerivationPathValid(derivationPath)

Param	Type	Description
derivationPath	String	Derivation path

Returns

true if derivationPath is valid and false otherwise.

Example

const isValid = Keystore.isDerivationPathValid("m/44'/60'/0'/0")

testPassword(password, passwordConfig)

Param	Type	Default	Description
password	String		Wallet password
passwordConfig	Object	{}	Password options container
passwordConfig.minLength	Number	10	Min length for password
passwordConfig.minLength	Number	128	Max length for password

Returns

Object that contains following fields:

• errors - error messages array
• failedTests - failed test names array
• passedTests - passed test names array

Example

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