chainsafe/bls-keygen

Key management for BLS curves written in TypeScript and browser compatible

BLS Keygen

Utility functions for generating BLS secret keys, built for NodeJs and Browser.

• Create a master key from BIP-39 mnemonic or entropy.
• Create a derived child key from BIP-39 mnemonic, entropy, or a master key.
• Create Eth2 validator keys from a master key.

Implementation follows EIPS: EIP-2334, EIP-2333

For low-level EIP-2333 and EIP-2334 functionality, see @chainsafe/bls-hd-key.

Examples

import {
    generateRandomSecretKey,
    deriveKeyFromMnemonic,
    deriveKeyFromEntropy,
    deriveKeyFromMaster,
    deriveEth2ValidatorKeys,
} from "@chainsafe/bls-keygen";

// random secret key
const secretKey = generateRandomSecretKey();

...

// secret key from mnemonic and optional EIP-2334 path
const masterSecretKey = deriveKeyFromMnemonic(
  "impact exit example acquire drastic cement usage float mesh source private bulb twenty guitar neglect",
);

const childSecretKey = deriveKeyFromMnemonic(
  "impact exit example acquire drastic cement usage float mesh source private bulb twenty guitar neglect",
  "m/12381/3600/0/0"
);

...

// secret key from entropy and optional EIP-2334 path
const masterSecretKey = deriveKeyFromEntropy(entropy);

const childSecretKey = deriveKeyFromEntropy(
  entropy,
  "m/12381/3600/0/0"
);


...

// child secret key from master secret key and EIP-2334 path
const childSecretKey = deriveKeyFromMaster(
  masterSecretKey,
  "m/12381/3600/0/0"
);

...

// create multiple eth2 validator keys from a master secret key
const keys0 = deriveEth2ValidatorKeys(masterSecretKey, 0);
const keys1 = deriveEth2ValidatorKeys(masterSecretKey, 1);

const { signing, withdrawal } = keys0;

Contribution

Requirements:

• nodejs
• yarn

    yarn install
    yarn run test

Audit

This repo was audited by Least Authority as part of this security audit, released 2020-03-23. Commit 32b068 verified in the report.

License

Apache-2.0

bls-keygen's Issues

Bump @chainsafe/bls version to 1.x

deriveEth2ValidatorKeys signing key derivation path

bls-keygen/src/index.ts

Line 64 in 32b0682

signing: deriveKeyFromMaster(masterKey, `m/12381/3600/${validatorIndex}/0/0`),

Hi, when deriving eth2 validator keys, why the signing key derived from path m/12381/3600/${validatorIndex}/0/0 not m/12381/3600/${validatorIndex}/1, as eip-2334 specify m / purpose / coin_type / account / use format.

bcrypto with bn.js

bcrypto has an extended bn.js included in it with lots of new cryptographic operations. This would allow you do drop bn.js as a dependency. Note that the author of bn.js is the original author of bcoin.

https://github.com/indutny/bn.js
https://github.com/bcoin-org/bcoin/blob/master/package.json#L11
https://github.com/bcoin-org/bcrypto/blob/master/lib/js/bn.js

Derivation from Mnemonic Mismatch

I am having confusing results testing key generation using your library vs https://bls-keygen.com/

For example, using the generated mnemonic:
stereo hub fog giraffe street suspect foil scorpion dirt brave eyebrow always

The following code block does not match the generated master key from the website

const { validateMnemonic, mnemonicToSeedSync } = require('bip39');
const {
    deriveKeyFromMnemonic
} = require('@chainsafe/bls-keygen');

const {
    initBLS,
    generatePublicKey
} = require('@chainsafe/bls');

const mnemonic = 'stereo hub fog giraffe street suspect foil scorpion dirt brave eyebrow always';

async function run() {
    await initBLS();
    validateMnemonic(mnemonic);
    const masterPrivateKey = deriveKeyFromMnemonic(mnemonic);
    const masterPubkey = generatePublicKey(masterPrivateKey);
    console.log(`Seed: ${seed.toString('hex')}`);
    console.log(`Master Private Key: ${masterPrivateKey.toString('hex')}`);
    console.log(`Master Public Key: ${masterPubkey.toString('hex')}`);
}

run();

If I instead use

    const seed = bip39.mnemonicToSeedSync(mnemonic);
    const masterPrivateKey = deriveMasterSK(seed);

Then I get results that match the website.

I would have expected deriveKeyFromMnemonic(mnemonic) to do the job, and your documentation here suggests that, but if I actually took the mnemonic from bls-keygen.com and plug it directly into the code above, I get different results than keystore generated on the site.