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")