@chainsafe/bls-keygen - npm Package Compare versions

Comparing version 0.0.2 to 0.1.0

lib/index.d.ts

@@ -7,9 +7,28 @@ /// <reference types="node" />
 export declare function generateRandomSecretKey(entropy?: Buffer): Buffer;
-export declare function mnemonicToSecretKey(mnemonic: string, path?: string | null): Buffer;
 /**
- * Derive child key from seed and path.
- * If path is omitted seed will be converted to valid secret key
- * @param seed
- * @param path
+ * Derive a secret key from a BIP39 mnemonic seed and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
  */
-export declare function deriveKey(seed: Buffer, path?: string | null): Buffer;
+export declare function deriveKeyFromMnemonic(mnemonic: string, path?: string): Buffer;
+/**
+ * Derive a secret key from entropy and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
+ */
+export declare function deriveKeyFromEntropy(entropy: Buffer, path?: string): Buffer;
+/**
+ * Derive a child secret key from a master secret key
+ * @param masterKey master secret key
+ * @param path EIP-2334 path to child
+ */
+export declare function deriveKeyFromMaster(masterKey: Buffer, path: string): Buffer;
+export interface IEth2ValidatorKeys {
+    withdrawal: Buffer;
+    signing: Buffer;
+}
+/**
+ * Derive Eth2 validator secret keys from a single master secret key
+ * @param masterKey master secret key
+ */
+export declare function deriveEth2ValidatorKeys(masterKey: Buffer, validatorIndex: number): IEth2ValidatorKeys;

lib/index.js

@@ -7,4 +7,6 @@ "use strict";
 exports.generateRandomSecretKey = generateRandomSecretKey;
-exports.mnemonicToSecretKey = mnemonicToSecretKey;
-exports.deriveKey = deriveKey;
+exports.deriveKeyFromMnemonic = deriveKeyFromMnemonic;
+exports.deriveKeyFromEntropy = deriveKeyFromEntropy;
+exports.deriveKeyFromMaster = deriveKeyFromMaster;
+exports.deriveEth2ValidatorKeys = deriveEth2ValidatorKeys;
 
@@ -34,6 +36,12 @@ var _random = require("bcrypto/lib/random");
 
-  return deriveKey(ikm, null);
+  return deriveKeyFromEntropy(ikm);
 }
+/**
+ * Derive a secret key from a BIP39 mnemonic seed and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
+ */
 
-function mnemonicToSecretKey(mnemonic, path = "m/12381/3600/0/0") {
+
+function deriveKeyFromMnemonic(mnemonic, path) {
   (0, _assert.default)((0, _bip.validateMnemonic)(mnemonic), "invalid mnemonic");
@@ -43,17 +51,16 @@
 
-  return deriveKey(ikm, path);
+  return deriveKeyFromEntropy(ikm, path);
 }
 /**
- * Derive child key from seed and path.
- * If path is omitted seed will be converted to valid secret key
- * @param seed
- * @param path
+ * Derive a secret key from entropy and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
  */
 
 
-function deriveKey(seed, path = "m/12381/3600/0/0") {
-  const masterKey = (0, _blsHdKey.deriveMasterSK)(_buffer.Buffer.from(seed));
+function deriveKeyFromEntropy(entropy, path) {
+  const masterKey = (0, _blsHdKey.deriveMasterSK)(_buffer.Buffer.from(entropy));
 
   if (path) {
-    return (0, _blsHdKey.deriveChildSKMultiple)(masterKey, (0, _blsHdKey.pathToIndices)(path));
+    return deriveKeyFromMaster(masterKey, path);
   }
@@ -63,2 +70,23 @@
 }
+/**
+ * Derive a child secret key from a master secret key
+ * @param masterKey master secret key
+ * @param path EIP-2334 path to child
+ */
+
+
+function deriveKeyFromMaster(masterKey, path) {
+  return (0, _blsHdKey.deriveChildSKMultiple)(masterKey, (0, _blsHdKey.pathToIndices)(path));
+}
+
+/**
+ * Derive Eth2 validator secret keys from a single master secret key
+ * @param masterKey master secret key
+ */
+function deriveEth2ValidatorKeys(masterKey, validatorIndex) {
+  return {
+    withdrawal: deriveKeyFromMaster(masterKey, `m/12381/3600/${validatorIndex}/0`),
+    signing: deriveKeyFromMaster(masterKey, `m/12381/3600/${validatorIndex}/0/0`)
+  };
+}
 //# sourceMappingURL=index.js.map

package.json

 {
     "name": "@chainsafe/bls-keygen",
-    "version": "0.0.2",
+    "version": "0.1.0",
     "description": "Typescript key management tool that works in the browser",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

@@ -1,2 +0,2 @@
-# BLS TypeScript Key Management
+# BLS Keygen
 
@@ -7,15 +7,25 @@ ![npm (tag)](https://img.shields.io/npm/v/@chainsafe/bls-keygen/latest)
 
-Utility methods for generating valid BLS keys from random bytes or mnemonic for NodeJs and Browser.
+Utility functions for generating BLS secret keys, built for NodeJs and Browser.
 
-Implementation is following EIPS: [EIP-2334](https://github.com/ethereum/EIPs/pull/2334), [EIP-2333](https://github.com/ethereum/EIPs/pull/2333)
+- 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.
 
-For low level methods of [EIP-2333](https://github.com/ethereum/EIPs/pull/2333), check out [@chainsafe/bls-hd-key](https://github.com/chainsafe/bls-hd-key).
+Implementation follows EIPS: [EIP-2334](https://github.com/ethereum/EIPs/pull/2334), [EIP-2333](https://github.com/ethereum/EIPs/pull/2333)
 
-### How to use?
+For low-level [EIP-2333](https://github.com/ethereum/EIPs/pull/2333) and [EIP-2334](https://github.com/ethereum/EIPs/pull/2334) functionality, see [@chainsafe/bls-hd-key](https://github.com/chainsafe/bls-hd-key).
+
+### Examples
 ```typescript
 
 
-import {generateRandomSecretKey, mnemonicToSecretKey, deriveKey} from "@chainsafe/bls-keygen";
+import {
+    generateRandomSecretKey,
+    deriveKeyFromMnemonic,
+    deriveKeyFromEntropy,
+    deriveKeyFromMaster,
+    deriveEth2ValidatorKeys,
+} from "@chainsafe/bls-keygen";
 
-//random secret key
+// random secret key
 const secretKey = generateRandomSecretKey();
@@ -25,15 +35,39 @@
 
-//secret key from mnemonic and path
-const secretKey = mnemonicToSecretKey(
-    "impact exit example acquire drastic cement usage float mesh source private bulb twenty guitar neglect",
-    "m/12381/3600/0/0"    
+// 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 seed and path
-const secretKey = deriveKey(
-    seed,
-    "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;
+
 ```
@@ -51,1 +85,5 @@
 ```
+
+### License
+
+Apache-2.0

src/index.ts

@@ -16,23 +16,52 @@ import {randomBytes} from "bcrypto/lib/random";
   }
-  return deriveKey(ikm, null);
+  return deriveKeyFromEntropy(ikm);
 }
 
-export function mnemonicToSecretKey(mnemonic: string, path: string | null = "m/12381/3600/0/0"): Buffer {
+/**
+ * Derive a secret key from a BIP39 mnemonic seed and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
+ */
+export function deriveKeyFromMnemonic(mnemonic: string, path?: string): Buffer {
   assert(validateMnemonic(mnemonic), "invalid mnemonic");
   const ikm = Buffer.from(mnemonicToSeedSync(mnemonic));
-  return deriveKey(ikm, path);
+  return deriveKeyFromEntropy(ikm, path);
 }
 
 /**
- * Derive child key from seed and path.
- * If path is omitted seed will be converted to valid secret key
- * @param seed
- * @param path
+ * Derive a secret key from entropy and optionally an EIP-2334 path.
+ * If path is included, the derived key will be the child secret key at that path,
+ * otherwise, the derived key will be the master secret key
  */
-export function deriveKey(seed: Buffer, path: string | null = "m/12381/3600/0/0"): Buffer {
-  const masterKey = deriveMasterSK(Buffer.from(seed));
+export function deriveKeyFromEntropy(entropy: Buffer, path?: string): Buffer {
+  const masterKey = deriveMasterSK(Buffer.from(entropy));
   if(path) {
-    return deriveChildSKMultiple(masterKey, pathToIndices(path));
+    return deriveKeyFromMaster(masterKey, path);
   }
   return masterKey;
-}
+}
+
+/**
+ * Derive a child secret key from a master secret key
+ * @param masterKey master secret key
+ * @param path EIP-2334 path to child
+ */
+export function deriveKeyFromMaster(masterKey: Buffer, path: string): Buffer {
+  return deriveChildSKMultiple(masterKey, pathToIndices(path));
+}
+
+export interface IEth2ValidatorKeys {
+  withdrawal: Buffer;
+  signing: Buffer;
+}
+
+/**
+ * Derive Eth2 validator secret keys from a single master secret key
+ * @param masterKey master secret key
+ */
+export function deriveEth2ValidatorKeys(masterKey: Buffer, validatorIndex: number): IEth2ValidatorKeys {
+  return {
+    withdrawal: deriveKeyFromMaster(masterKey, `m/12381/3600/${validatorIndex}/0`),
+    signing: deriveKeyFromMaster(masterKey, `m/12381/3600/${validatorIndex}/0/0`),
+  };
+}

test/index.spec.ts

@@ -1,2 +0,2 @@
-import {mnemonicToSecretKey, generateRandomSecretKey, deriveKey} from "../src";
+import {deriveKeyFromMnemonic, generateRandomSecretKey, deriveKeyFromEntropy} from "../src";
 import {expect} from "chai";
@@ -23,6 +23,6 @@ import {generateMnemonic} from "bip39";
 
-  it("should generate using default path", function () {
+  it("should generate master key", function () {
     const mnemonic = generateMnemonic();
-    const key = mnemonicToSecretKey(mnemonic);
-    const key1 = mnemonicToSecretKey(mnemonic);
+    const key = deriveKeyFromMnemonic(mnemonic);
+    const key1 = deriveKeyFromMnemonic(mnemonic);
     expect(key).to.not.be.null;
@@ -34,4 +34,4 @@ expect(key.toString("hex")).to.be.equal(key1.toString("hex"));
     const mnemonic = generateMnemonic();
-    const key = mnemonicToSecretKey(mnemonic, "m/12381/3600/0/1");
-    const key1 = mnemonicToSecretKey(mnemonic, "m/12381/3600/0/2");
+    const key = deriveKeyFromMnemonic(mnemonic, "m/12381/3600/0/1");
+    const key1 = deriveKeyFromMnemonic(mnemonic, "m/12381/3600/0/2");
     expect(key).to.not.be.null;
@@ -43,8 +43,8 @@ expect(key.toString("hex")).to.not.be.equal(key1.toString("hex"));
 
-describe("private key from seed", function () {
+describe("private key from entropy", function () {
 
-  it("should generate using default path", function () {
+  it("should generate master key", function () {
     const seed = Buffer.alloc(32, 1);
-    const key = deriveKey(seed);
-    const key1 = deriveKey(seed);
+    const key = deriveKeyFromEntropy(seed);
+    const key1 = deriveKeyFromEntropy(seed);
     expect(key).to.not.be.null;
@@ -54,6 +54,6 @@ expect(key.toString("hex")).to.be.equal(key1.toString("hex"));
 
-  it("should generate using given path", function () {
+  it("should generate child key using given path", function () {
     const seed = Buffer.alloc(32, 2);
-    const key = deriveKey(seed, "m/12381/3600/0/1");
-    const key1 = deriveKey(seed, "m/12381/3600/0/2");
+    const key = deriveKeyFromEntropy(seed, "m/12381/3600/0/1");
+    const key1 = deriveKeyFromEntropy(seed, "m/12381/3600/0/2");
     expect(key).to.not.be.null;
@@ -63,2 +63,2 @@ expect(key.toString("hex")).to.not.be.equal(key1.toString("hex"));
 
-});
+});

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

39534

increased by17.33%

Number of package files

24

increased by4.35%

Lines of code

441

increased by19.19%

Number of lines in readme file

87

increased by77.55%

No dependency changes