Symbol HD Wallets

Hyper-deterministic wallets generator library for Symbol.

This is a PoC to validate the proposed NIP6 Multi-Account Hierarchy for Deterministic Wallets. When stable, the repository will be moved to the nemtech organization.

NOTE: The author of this package cannot be held responsible for any loss of money or any malintentioned usage forms of this package. Please use this package with caution.

Requirements

• Node.js 12 LTS

Installation

npm install symbol-hd-wallets

Usage

Generating a mnemonic pass phrase

// examples/GeneratingAMnemonicPassPhrase.ts

import {MnemonicPassPhrase} from "../src/MnemonicPassPhrase";

// random 24-words mnemonic
MnemonicPassPhrase.createRandom();

// random 12-words mnemonic
MnemonicPassPhrase.createRandom('english', 128);

// random 24-words mnemonic with french wordlist
MnemonicPassPhrase.createRandom('french');

// random 24-words mnemonic with japanese wordlist
MnemonicPassPhrase.createRandom('japanese');

Generating a password-protected mnemonic pass phrase seed (for storage)

// examples/GeneratePasswordProtectedSeedForRandomPassPhrase.ts

import {MnemonicPassPhrase} from "../src/MnemonicPassPhrase";

const mnemonic = MnemonicPassPhrase.createRandom();
const secureSeedHex = mnemonic.toSeed('your-password');

// examples/GeneratePasswordProtectedSeedForRandomPassPhraseEmptyPassword.ts

import {MnemonicPassPhrase} from "../src/MnemonicPassPhrase";

// Example 2: empty password for password-protected seed
const mnemonic = MnemonicPassPhrase.createRandom();
const secureSeedHex = mnemonic.toSeed(); // omit password means empty password: ''

Generating a root (master) extended key

// examples/GeneratingARootMasterExtendedKeyForKnownPassPhrase.ts

import {MnemonicPassPhrase} from "../src/MnemonicPassPhrase";

// Example 2: generate BIP32 master seed for known pass phrase
const words = 'alpha pattern real admit vacuum wall ready code '
    + 'correct program depend valid focus basket whisper firm '
    + 'tray fit rally day dance demise engine mango';
const mnemonic = new MnemonicPassPhrase(words);

// the following seed can be used with `ExtendedKey.createFromSeed()`
const bip32Seed = mnemonic.toSeed(); // using empty password

// examples/GeneratingARootMasterExtendedKeyForRandomPassPhrase.ts

import {MnemonicPassPhrase} from "../src/MnemonicPassPhrase";

// Example 1: generate BIP32 master seed for random pass phrase
const mnemonic = MnemonicPassPhrase.createRandom();
const bip32Seed = mnemonic.toSeed();

Generating a hyper-deterministic wallet (CATAPULT mijin and mijinTest compatible)

// examples/GeneratingAHDWalletPrivateNetworkCompatible.ts

import {NetworkType} from 'symbol-sdk';
import {ExtendedKey} from "../src/ExtendedKey";
import {Wallet} from "../src/Wallet";
import {Network} from "../src/Network";

const xkey = ExtendedKey.createFromSeed('000102030405060708090a0b0c0d0e0f', Network.CATAPULT);
const wallet = new Wallet(xkey);

// get master account
const masterAccount = wallet.getAccount();

// get DEFAULT ACCOUNT
const defaultAccount = wallet.getChildAccount();

// derive specific child path
const childAccount = wallet.getChildAccount('m/44\'/43\'/0\'/0\'/0\'', NetworkType.MIJIN_TEST);

// get read-only wallet
const readOnlyWallet = new Wallet(xkey.getPublicNode());
const readOnlyAccount = readOnlyWallet.getPublicAccount(NetworkType.MIJIN_TEST);

// get read-only DEFAULT ACCOUNT
const readOnlyDefaultAccount = readOnlyWallet.getChildPublicAccount();

Generating a hyper-deterministic wallet (CATAPULT public and publicTest compatible)

// examples/GeneratingAHDWalletPublicNetworkCompatible.ts

import {Network} from "../src/Network";
import {NetworkType} from "symbol-sdk";
import {Wallet} from "../src/Wallet";
import {ExtendedKey} from "../src/ExtendedKey";

const xkey = ExtendedKey.createFromSeed('000102030405060708090a0b0c0d0e0f', Network.CATAPULT_PUBLIC);
const wallet = new Wallet(xkey);

// get master account
const masterAccount = wallet.getAccount();

// get DEFAULT ACCOUNT
const defaultAccount = wallet.getChildAccount();

// derive specific child path
const childAccount = wallet.getChildAccount('m/44\'/43\'/0\'/0\'/0\'', NetworkType.TEST_NET);

// get read-only wallet
const readOnlyWallet = new Wallet(xkey.getPublicNode());
const readOnlyAccount = readOnlyWallet.getPublicAccount(NetworkType.TEST_NET);

// get read-only DEFAULT ACCOUNT
const readOnlyDefaultAccount = readOnlyWallet.getChildPublicAccount();

Signing with a hyper-deterministic wallet (CATAPULT compatible)

// examples/SigningWithAHDWalletPrivateNetworkCompatible.ts

import {Account, Deadline, EmptyMessage, NetworkType, TransferTransaction} from "symbol-sdk";
import {Wallet} from "../src/Wallet";
import {ExtendedKey} from "../src/ExtendedKey";
import {Network} from "../src/Network";

const xkey = ExtendedKey.createFromSeed('000102030405060708090a0b0c0d0e0f', Network.CATAPULT_PUBLIC);
const wallet = new Wallet(xkey);

// derive specific child path
const childAccount = wallet.getChildAccount('m/44\'/43\'/0\'/0\'/0\'', NetworkType.TEST_NET);

// create a transfer object
const transfer = TransferTransaction.create(
    Deadline.create(),
    Account.generateNewAccount(NetworkType.TEST_NET).address,
    [],
    EmptyMessage,
    NetworkType.TEST_NET);

// sign the transaction with derived account
const generationHash = ''; // replace with network generation hash
const signedTx = childAccount.sign(transfer, generationHash);

Getting help

Use the following available resources to get help:

• Symbol Documentation
• Join the community slack group (#sig-client)
• If you found a bug, open a new issue

Contributing

This project is developed and maintained by NEM Foundation.

Contributions are welcome and appreciated. Check CONTRIBUTING for information on how to contribute.

License

Copyright (c) 2019, Grégory Saive

Licensed under the BSD-2 License.