redshift

Stellar HD Accounts Generator - library.

$ npm i @stellar-fox/redshift

index

• hierarchical deterministic addresses
• multi-account hierarchy
• key derivation methods
• documentation
• experimenting in browser
• experimenting locally
• namespace
• examples
• tests
• support
• license

hierarchical deterministic addresses

Mnemonic (a lists of specially prepared words) can be used to generate deterministic series of account addresses. The method implemented here uses 24 (or 12) words to generate series of deterministic Stellar key pairs. 24 word mnemonics are also used by many hardware wallets (such as Ledger Nano S). This library can also be used to restore account based on the mnemonic that was generated earlier by either the hardware wallet or any other wallets compatible with BIP-0032, BIP-0039, BIP-0043, BIP-0044, SLIP-0010, SLIP-0044 and SEP-0005 specifications.

multi-account hierarchy for deterministic wallets

redshift library uses BIP-0032 path with a hardened derivation. One can choose to derive key pair for default account (with account number equal to 0) or select other account number in m / 44' / 148' / account' hierarchy. The upper limit of account number of child accounts is 2**31 (2'147'483'648).

key derivation methods for stellar accounts

Stellar Ecosystem Proposal describes implementation of deterministic key derivation for Stellar accounts based on word mnemonic of different lengths. redshift library uses 24 (or 12) word mnemonics.

documentation

API Reference

experimenting in browser

RunKit with @stellar-fox/redshift

• recovering stellar keypair based on known mnemonic, passphrase and an account number:

  https://runkit.com/xcmats/redshift.restore/

• generating a new stellar address:

  https://runkit.com/xcmats/redshift.new/

experimenting locally

$ git clone [email protected]:stellar-fox/redshift.git
Cloning into 'redshift'...
$ cd redshift/library/
$ npm i
$ npm start
Compiling for 'production' ...
Hash: 949571f79bbc31ee54e1
Version: webpack 4.28.1
Time: 1373ms
Built at: 2018-12-21 14:32:28
      Asset      Size  Chunks             Chunk Names
redshift.js  13.5 KiB       0  [emitted]  redshift
Entrypoint redshift = redshift.js
[0] external "@xcmats/js-toolbox" 42 bytes {0} [built]
[1] external "bip39" 42 bytes {0} [built]
[3] external "@babel/runtime/helpers/typeof" 42 bytes {0} [built]
[4] ./package.json 3.73 KiB {0} [built]
[5] external "stellar-sdk" 42 bytes {0} [built]
[6] ./src/index.js 4.11 KiB {0} [built]
    + 1 hidden module

namespace

redshift

{ ENTROPY: { HIGH: 256, MEDIUM: 128 },
  LANGUAGE:
   { CN: 'chinese_simplified',
     CT: 'chinese_traditional',
     EN: 'english',
     FR: 'french',
     IT: 'italian',
     JP: 'japanese',
     KR: 'korean',
     SP: 'spanish' },
  genMnemonic: [Function: genMnemonic],
  validateMnemonic: [Function: validateMnemonic],
  genKeypair: [Function: genKeypair],
  newAddress: [Function: newAddress],
  restoreAddress: [Function: restoreAddress],
  words: [Function words],
  mnemonicToSeedHex: [Function: mnemonicToSeedHex],
  version: [Getter] }

examples

• Randomly generate mnemonic of a high entropy using english words.

  redshift.genMnemonic().split(' ')

  [ 'eye',
  'urge',
  'child',
  'before',
  'sudden',
  'this',
  'assault',
  'else',
  'brisk',
  'twelve',
  'hair',
  'topic',
  'divert',
  'raw',
  'onion',
  'cattle',
  'result',
  'birth',
  'catalog',
  'dice',
  'auction',
  'sibling',
  'goat',
  'initial' ]

• Randomly generate mnemonic of a medium entropy in italian.

  redshift.genMnemonic(redshift.LANGUAGE.IT, redshift.ENTROPY.MEDIUM)

  'desumere sogno cuculo stirpe sepolto salmone elfico giocare ...'

• Generate hex seed from a given mnemonic.

  mnemonic = redshift.genMnemonic()

  'hold awful slender tide arrange window burden erase bamboo ...'

  seed = redshift.mnemonicToSeedHex(mnemonic)

  '016d98a5956955896613c59e277...8ca1e6d94f792316b8f5afa0d8f2dc6'

• Generate hex seed from a given mnemonic and a secret passphrase.

  mnemonic = redshift.genMnemonic()

  'ride throw body pet abstract gossip few online acoustic ...'

  seed = redshift.mnemonicToSeedHex(mnemonic, 'my secret phrase')

  '2b8b5c2a3bac1f54a5c716621e3...4d68f7e14402ac9ff76f1fcf92096e'

• Generate stellar keypair object from a given seed.

  kp = redshift.genKeypair(seed)

  Keypair {
  type: 'ed25519',
  _secretSeed: <Buffer ... >,
  _secretKey: <Buffer ... >,
  _publicKey: <Buffer ... > }

  kp.<press-TAB-key>

  kp.canSign  kp.publicKey     kp.rawPublicKey   kp.rawSecretKey
  kp.secret   kp.sign          kp.signDecorated  kp.signatureHint
  kp.verify   kp.xdrAccountId  kp.xdrPublicKey

  kp.publicKey()

  'GALJAMOTJC2OU6GRCGLOANONTMAVHI3ZD6PTTR7ED5NPSJV3D2VC37RL'

  kp.secret()

  'SCK2PGA6Q6YG6I77QLCW5ZENEWDDX4KHEBMT2AIV7FLAWCAGFCG2FZIT'

• Generate stellar keypair object from a given seed and an account number.

  kp = redshift.genKeypair(seed, 27)
  ...
  kp.publicKey()

  'GBDKU27YWDIRYDFAZF5J2JNPI2CPICSML4VBREP3SC45MKV433NHRNCR'

  kp.secret()

  'SBNWL6JJ3Q5CS6U4JUVUTOWIU24NDCWEI5P7BINENF4K3PHRST3QDOZH'

• Generate object with a new mnemonic of high entropy, resulting seed and stellar keypair. Optionally, passphrase and account number can be passed as an arguments.

  redshift.newAddress('strawberryFieldsF0R3V3R', 27)

  { mnemonic: 'spell crawl shiver swallow ecology mercy ...',
    passphrase: 'strawberryFieldsF0R3V3R',
    account: 27,
    seed: 'd3dbb69cf5a538ef8594fafd3...70a10a806b9a44be5157917',
    keypair:
     Keypair {
       type: 'ed25519',
       _secretSeed: <Buffer ... >,
       _publicKey: <Buffer ... > } }

• Restore address from a given mnemonic, passphrase and an account number.

  redshift.restoreAddress(
      'innocent yellow push captain end focus solution ...',
      's3cRET',
      3
  )

  { mnemonic: 'innocent yellow push captain end focus ...',
    passphrase: 's3cRET',
    account: 3,
    seed: 'ac16748b113fb3ca85fb5cac...5290d80bec70cd4fda0878',
    keypair:
     Keypair {
       type: 'ed25519',
       _secretSeed: <Buffer ... >,
       _secretKey: <Buffer ... >,
       _publicKey: <Buffer ... > } }

tests

Tested with SEP-0005 Vectors 3 and 4 (source)

$ npm run test:full

  Test Vector 3 (SEP-0005)
    Test Vector 3 Mnemonic Validation
      ✓ should be valid
    BIP39 Seed
      ✓ should return: 937ae91...f567866
    Public Key (m/44'/148'/0')
      ✓ should return: GC3MM...BTPJQ (58ms)
    Public Key (m/44'/148'/1')
      ✓ should return: GB3MT...YYISO
    Public Key (m/44'/148'/2')
      ✓ should return: GDYF7...DGAKU
   ...
      ✓ should return: SBSHU...2ZEO2
    Secret Key (m/44'/148'/7')
      ✓ should return: SC2QO...YWC6E
    Secret Key (m/44'/148'/8')
      ✓ should return: SCGMC...MAQST
    Secret Key (m/44'/148'/9')
      ✓ should return: SCPA5...C37GF

  Test Vector 4 (SEP-0005)
    Test Vector 4 Mnemonic Validation
      ✓ should be valid
    BIP39 Seed
      ✓ should return: d425d39...742a489
    Public Key (m/44'/148'/0')
      ✓ should return: GDAHP...B63EQ
    Public Key (m/44'/148'/1')
      ✓ should return: GDY47...4OJOC
    ...
    Secret Key (m/44'/148'/9')
      ✓ should return: SDXDY...UXNOS


  44 passing (516ms)

support

GAUWLOIHFR2E52DYNEYDO6ZADIDVWZKK3U77V7PMFBNOIOBNREQBHBRR

license

redshift is released under the Apache License, Version 2.0. See the LICENSE for more details.