eth2-wallet-js

VanillaJS implementation of an Ethereum 2 Wallet keystore.

**USE AT YOUR OWN RISK**

• Highlights
• Dependencies
• Install
• Test
• Module Usage
  • Basic NodeJS
  • Instance Options
  • Functions
  • Custom Store
  • Custom Key
• CLI Usage
• Notes/Limitations
• Roadmap
• Thanks

Highlights

• Use as Module and/or CLI
• EIP-2335 compatible.
• Supports Customizable Store and Key implementations. Write your own Storage or Key classes.
• Default Storage in ~/.eth2-wallet-js

Dependencies

• Nodejs >= 12.0.0

Install

NodeJS Module

yarn add https://github.com/copernicrypt/eth2-wallet-js
yarn install

CLI

git clone https://github.com/copernicrypt/eth2-wallet-js
yarn install

Test

yarn test

Module Usage

Basic NodeJS Usage

import { Wallet } from 'eth2-wallet-js';

let w = new Wallet();
await w.init();
let wallet = await w.walletCreate();
let key = await w.keyCreate(wallet, 'mypassword');

Instance Options

See Custom Key and Custom Store documentation on writing your own key/store implementations.

import { Wallet } from 'eth2-wallet-js';
import { CustomStore } from 'custom-store';
import { CustomKey } from 'custom-key';

const cStore = new CustomStore();
const cKey = new CustomKey();

let opts = {
  algorithm: 'aes-256-cbc', // Used to encrypt keys and mnemonic
  wallet_path: '~/.eth2-wallet-js/wallet',
  fork_version: 'pyrmont', // or 'mainnet' or 'medalla'
  store: cStore,
  key: cKey
}

let w = new Wallet(opts);
await w.init();

Functions

Wallet

• Wallet
  • .Wallet : Object
    • .init() ⇒ Null
    • .depositData(walletId, keyId, password, withdrawalOpts, [forkVersion]) ⇒ Object | String
    • .keyCreate(wallet_id, password) ⇒ Object
    • .keyDelete(walletId, keyId, password) ⇒ Boolean
    • .keyImport(walletId, privateKey, password) ⇒ Object
    • .keyList(id) ⇒ Array
    • .keyPrivate(walletId, keyId, password) ⇒ String
    • .keySearch(search, walletId) ⇒ Object
    • .parsePasswordFile(file, wallet, key) ⇒ String
    • .sign(message, walletId, search, password) ⇒ Array
    • .walletBackup(walletId, [destination]) ⇒ Promise
    • .walletCreate([opts]) ⇒ String
    • .walletDelete(id) ⇒ Boolean
    • .walletList() ⇒ Array
    • .walletMnemonic(walletId, password) ⇒ String
    • .walletRestore(source, [wallet]) ⇒ Boolean

Wallet.Wallet : Object

An implementation of ETH2 Wallet

Kind: static class of Wallet

• .Wallet : Object
  • .init() ⇒ Null
  • .depositData(walletId, keyId, password, withdrawalOpts, [forkVersion]) ⇒ Object | String
  • .keyCreate(wallet_id, password) ⇒ Object
  • .keyDelete(walletId, keyId, password) ⇒ Boolean
  • .keyImport(walletId, privateKey, password) ⇒ Object
  • .keyList(id) ⇒ Array
  • .keyPrivate(walletId, keyId, password) ⇒ String
  • .keySearch(search, walletId) ⇒ Object
  • .parsePasswordFile(file, wallet, key) ⇒ String
  • .sign(message, walletId, search, password) ⇒ Array
  • .walletBackup(walletId, [destination]) ⇒ Promise
  • .walletCreate([opts]) ⇒ String
  • .walletDelete(id) ⇒ Boolean
  • .walletList() ⇒ Array
  • .walletMnemonic(walletId, password) ⇒ String
  • .walletRestore(source, [wallet]) ⇒ Boolean

wallet.init() ⇒ Null

This just awaits the initialization of the BLS package.

Kind: instance method of Wallet

wallet.depositData(walletId, keyId, password, withdrawalOpts, [forkVersion]) ⇒ Object | String

Gets the deposit data fields for a validator deposit on the ETH1 chain.

Kind: instance method of Wallet
Returns: Object | String - Either an object containing the depoosit fields, or the raw TX data string.

| Param | Type | Default | Description | | --- | --- | --- | --- | | walletId | String | | The wallet ID where the validator key is stored. | | keyId | String | | The key ID of the validator to generate data for. | | password | String | | The password of the validator key. | | withdrawalOpts | Object | | Withdrawal Parameters. Either withdrawalOpts.withdrawal_public_key, withdrawalOpts.withdrawal_key_id or withdrawalOpts.withdrawal_key_wallet must be specified. | | [withdrawalOpts.withdrawal_key_id] | String | <keyId> | The keyID of the Withdrawal key. | | [withdrawalOpts.withdrawal_key_wallet] | String | <walletId> | The wallet ID where the withdrawal key is stored. | | [withdrawalOpts.withdrawal_public_key] | String | | The public key of the withdrawal key. Overrides withdrawal_key_wallet and withdrawal_key_id. | | [forkVersion] | String | | Optionally override the Instance fork version. |

wallet.keyCreate(wallet_id, password) ⇒ Object

Creates a new ETH2 keypair.

Kind: instance method of Wallet
Returns: Object - An object containing the wallet_id, key_id and public_key.
Throws: On failure

| Param | Type | Default | Description | | --- | --- | --- | --- | | wallet_id | String | | The name of the wallet to create an key in. | | password | String | | The password to protect the key. | | [opts.keyId] | String | UUID | The name of the key to create. | | [opts.walletPassword] | String | | Wallet password for HD wallets. |

wallet.keyDelete(walletId, keyId, password) ⇒ Boolean

Removes a key from a wallet.

Kind: instance method of Wallet
Returns: Boolean - True on successful deletion.
Throws: On failure

| Param | Type | Description | | --- | --- | --- | | walletId | String | The wallet ID. | | keyId | String | The Key ID. | | password | String | The password protecting the key. |

wallet.keyImport(walletId, privateKey, password) ⇒ Object

Import a private key into the keystore

Kind: instance method of Wallet
Returns: Object - An object containing the walletId key ID and public key <48-byte HEX>
Throws: On failure

| Param | Type | Description | | --- | --- | --- | | walletId | String | The wallet to import into. | | privateKey | String | A 32byte HEX-format private key | | password | String | A password to protect the key. | | [opts.keyId] | String | The ID reference for the key. | | [opts.path] | String | Optional derivation path reference. |

wallet.keyList(id) ⇒ Array

List of available keys in a wallet.

Kind: instance method of Wallet
Returns: Array - An array of key objects.

| Param | Type | Description | | --- | --- | --- | | id | String | The wallet ID to search |

wallet.keyPrivate(walletId, keyId, password) ⇒ String

Get a private key

Kind: instance method of Wallet
Returns: String - The 64-byte HEX formatted private key.
Throws: On failure

| Param | Type | Description | | --- | --- | --- | | walletId | String | The wallet ID. | | keyId | String | The Key ID. | | password | String | The password protecting the key. |

wallet.keySearch(search, walletId) ⇒ Object

Finds a key in the store.

Kind: instance method of Wallet
Returns: Object - The key object.

| Param | Type | Description | | --- | --- | --- | | search | String | The keyId or public key to search for. | | walletId | String | The wallet storing the key. |

wallet.sign(message, walletId, search, password) ⇒ Array

Signs a generic message with a private key.

Kind: instance method of Wallet
Returns: Array - The 96-byte BLS signature.

| Param | Type | Description | | --- | --- | --- | | message | String | The message to sign (32-Byte HEX) | | walletId | String | Wallet ID where the key is stored. | | search | String | The key to search for. Accepts keyID, publicKey, and privateKey. | | password | String | Password protecting the signing key. |

wallet.walletBackup(walletId, [destination]) ⇒ Promise

Creates a wallet backup file

Kind: instance method of Wallet
Returns: Promise - Resolves to save destination path on success.

| Param | Type | Default | Description | | --- | --- | --- | --- | | walletId | String | | The ID of the wallet to backup. | | [destination] | String | | The destination to write the backup file. |

wallet.walletCreate([opts]) ⇒ String

Creates a new wallet to store keys.

Kind: instance method of Wallet
Returns: String - The wallet identifier.
Throws: On failure

| Param | Type | Default | Description | | --- | --- | --- | --- | | [opts] | Object | {} | Optional parameters. | | [opts.wallet_id] | String | uuidv4 | Wallet identifer. If not provided, will be random. | | [opts.type] | String | 1 | The type of wallet to create. 1=Simple, 2=Hierarchical deterministic. | | [opts.password] | String | | Password for HD wallets. | | [opts.mnemonic] | String | | BIP39 mnemonic for HD wallets. |

wallet.walletDelete(id) ⇒ Boolean

Delete a wallet

Kind: instance method of Wallet
Returns: Boolean - True if the delete was successful.
Throws: On failure

| Param | Type | Description | | --- | --- | --- | | id | String | The wallet identifier |

wallet.walletList() ⇒ Array

Return a list of available wallet IDs

Kind: instance method of Wallet
Returns: Array - A list of wallet IDs.
Throws: On failure

wallet.walletMnemonic(walletId, password) ⇒ String

Returns the wallet mnemonic phrase.

Kind: instance method of Wallet
Returns: String - The mnemonic phrase.

| Param | Type | Description | | --- | --- | --- | | walletId | String | The wallet ID. | | password | String | The password protecting the mnemonic. |

wallet.walletRestore(source, [opts]) ⇒ Object

Restores a wallet from file.

Kind: instance method of Wallet
Returns: Boolean - Returns true on success.
Throws: On failure.

| Param | Type | Default | Description | | --- | --- | --- | --- | | source | String | | The absolute path of the source file. | | [wallet] | String | | Optional wallet name to import into. Defaults to filename. | | [opts] | Object | {} | Optional parameters. | | [opts.wallet] | String | null | Optional wallet name to import into. Defaults to filename. | | [opts.rebuild] | Boolean | false | Whether to rebuild the index. Useful if importing from a different wallet provider like the official CLI. |

Custom Store

Standard Javascript Class. See examples in src/store.

Specifications

• Implements:
  • indexAccountNext([path=null]) returns Integer
  • indexCreate([path=null], [keyType=1]) returns Object
  • indexExists([path=null]) returns Boolean
  • keyDelete(<search>, [path=null]) returns Boolean | throws
  • keyList([path=null]) returns Array | throws
  • keySearch(<search>, [path=null]) returns { key_id, public_key, key_object } | throws
  • keyWrite(<keyData>, [opts={ keyId, publicKey, path }]) returns Boolean | throws
  • mnemonicCreate(<mnemonic>, [path=null]) returns Boolean | throws
  • mnemonicGet([path=null]) returns Object | String | throws
  • pathBackup(<path>, [destination=null]) returns undefined | throws
  • pathDelete([path=null]) returns Boolean | throws
  • pathList([path=null]) returns Array | throws
  • pathRestore(<source>, [opts]) returns Boolean | throws

Custom Key

Standard Javascript Class. See examples in src/key.

Specifications

• JSON formatted
• Properties: One of key_id or uuid
• constructor(<algorithm>, <version>)
  • algorithm: Encryption algorithm protecting the key.
  • version: Key version
• Implements encrypt and decrypt functions
  • encrypt(<privateKey>, <password>, <publicKey>, [opts]) returns <jsonObject>
  • decrypt(<jsonObject>, <password>) returns <privateKey>

CLI Usage

The CLI can be invoked using yarn or npm:

yarn run cli <command> [...args]

• <parameters> are required.
• [options] are optional.

keyCreate <wallet> <password> [key] [walletPassword]

Imports a private key into a wallet. HD Wallets require the --walletPassword flag.

$ yarn run cli keyCreate --wallet=primary --password=testpassword --key=testaccountID
{
  wallet_id: "primary",
  public_key: "b6de3f6dd56a863f69bca81af4dc9877d04a81df361bbe555d6944b9d84fce18fdfb939d9ef3c312ead638b759b207c9",
  key_id: "testaccoundID"
}

keyDelete <wallet> <key> <password>

Deletes a key from a wallet. Not available for HD Wallets

$ yarn run cli keyDelete --wallet=primary --key=testaccountID --password=testpassword
Key Deleted: testaccountID ---- Wallet: primary

keyImport <wallet> <privatekey> <password> [key]

Imports a private key into a wallet. Not available for HD Wallets

$ yarn run cli keyImport --wallet=primary --privatekey=1e16b2c1947fd9fd4045a88177313db10198ed6abd1b0f165d49cd13a72546e2 --password=testpassword --key=testaccountID
{
  wallet_id: "primary",
  public_key: "b6de3f6dd56a863f69bca81af4dc9877d04a81df361bbe555d6944b9d84fce18fdfb939d9ef3c312ead638b759b207c9",
  key_id: "testaccoundID"
}

keyList <wallet>

Lists all keys for a given wallet.

$ yarn run cli keyList --wallet=test
[
  'test',
  'test2'
]

keyPrivate <wallet> <key> <password>

Returns a private key HEX.

$ yarn run cli keyPrivate --wallet=primary --key=testaccountID --password=testpassword
1e16b2c1947fd9fd4045a88177313db10198ed6abd1b0f165d49cd13a72546e2

keySearch <wallet> <search>

Finds a key by search term. Accepts key ID or public key.

$ yarn run cli keySearch --wallet=primary --search=testaccountID
{
  public_key: "HEX",
  key_id: "testaccoundID"
}

sign <message> <wallet> <search> <password>

Signs a generic message with a key.

$ yarn run cli sign --message=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 --wallet=primary --search=key1 --password=test

walletBackup <wallet>\ [destination=null]

Backs up a wallet to file.

$ yarn run cli walletBackup --wallet=test
Wallet "test" successfully backed up.

walletCreate [wallet=UUID][type=1][password]

Creates a new wallet.

Available Types: 1 (Random) or 2 (HD) HD wallets require the --password flag

$ yarn run cli walletCreate --wallet=test
Created wallet: test

$ yarn run cli walletCreate --wallet=HDTest --password=protectMnemonic
Created wallet: HDTest

walletDelete <wallet>

Deletes a wallet.

$ yarn run cli walletDelete --wallet=test
Deleted wallet: test

walletList

Lists all available wallets

$ yarn run cli walletList
[
  'test',
  'test2'
]

walletMnemonic

Returns the mnemonic for a wallet. Not available for Simple Wallets

$ yarn run cli walletMnemonic --wallet=test --password=test
explain fix pink title village payment sell under critic adapt zone upset explain fix pink title village payment sell under critic adapt zone upset

walletRestore <source> [wallet=null] [rebuild=false]

Restores a wallet from file. If you want to import from the official Launchpad CLI, simply place all of the keys in the top-level path of a zip file and import with the --rebuild=true option.

$ yarn run cli walletRestore --source=/user/home/test.zip
Wallet "test" successfully restored.

depositData <wallet> <password> <key> [withdrawalwallet=<wallet>] [withdrawalkey=<key>] [withdrawalpublickey=null] [amount=32000000000] [raw=false] [fork=null]

Generates deposit data for submitting to the deposit contract.

$ yarn run cli depositData --wallet=primary --password=testpassword --key=testaccountId --withdrawalpublickey=b6de3f6dd56a863f69bca81af4dc9877d04a81df361bbe555d6944b9d84fce18fdfb939d9ef3c312ead638b759b207c9 --fork=mainnet
{
  pubkey: 'b88f5ff7e293d26d24a2655a8c72c8b92d495393548f7b86a31c2fe0923fd1ba292f31c11bb740e8acd7f599fb2ae06d',
  withdrawal_credentials: '00756e0bd4defe8a84f4303f6004e7f1b6978ddbe7fc7d22e2b0bd5f1c895e4c',
  signature: '92543970b5d2ab17666c9db957252d3a46ebf47782dfd8c53fc74d3cdce99883f35468d07d48094cfb8c986569e54f4619cdc64242e3c478a3899e4264a8d6d6a872311523c60f39b788d0398da77322dd2b8922e6f7b7ce4a8696b625bb59a3',
  amount: '32000000000',
  deposit_data_root: 'ea0c696c122426c32e5d6abe3caa4334cdc22fb08caa2601a6737e842fa73554'
}

$ yarn run cli depositData --wallet=primary --password=testpassword --key=testaccountId --withdrawalpublickey=b6de3f6dd56a863f69bca81af4dc9877d04a81df361bbe555d6944b9d84fce18fdfb939d9ef3c312ead638b759b207c9 --raw
0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120ea0c696c122426c32e5d6abe3caa4334cdc22fb08caa2601a6737e842fa735540000000000000000000000000000000000000000000000000000000000000030b88f5ff7e293d26d24a2655a8c72c8b92d495393548f7b86a31c2fe0923fd1ba292f31c11bb740e8acd7f599fb2ae06d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000756e0bd4defe8a84f4303f6004e7f1b6978ddbe7fc7d22e2b0bd5f1c895e4c000000000000000000000000000000000000000000000000000000000000006092543970b5d2ab17666c9db957252d3a46ebf47782dfd8c53fc74d3cdce99883f35468d07d48094cfb8c986569e54f4619cdc64242e3c478a3899e4264a8d6d6a872311523c60f39b788d0398da77322dd2b8922e6f7b7ce4a8696b625bb59a3

Notes/Limitations

• Use at your own risk.

Roadmap

• ~Implement EIP-2335~
• ~Add Import/Export function~
• ~Add support for BIP-39 HD wallets~
• Add support for password files

Thanks

Would not be possible without the work being done by @chainsafe and @herumi