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