From ade015123b2bfdbca721602cda19191c6f12252d Mon Sep 17 00:00:00 2001
From: Jason Dreyzehner <jason@dreyzehner.com>
Date: Wed, 10 Apr 2024 18:11:50 -0400
Subject: [PATCH] Clarify generateDeterministicEntropy usage examples (#130)

---
 .changeset/orange-suits-impress.md |  5 +++++
 docs/keys.md                       | 14 ++++++++------
 src/lib/docs.spec.ts               | 15 +++++++++------
 3 files changed, 22 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/orange-suits-impress.md

diff --git a/.changeset/orange-suits-impress.md b/.changeset/orange-suits-impress.md
new file mode 100644
index 00000000..1959d212
--- /dev/null
+++ b/.changeset/orange-suits-impress.md
@@ -0,0 +1,5 @@
+---
+'@bitauth/libauth': patch
+---
+
+clarify `generateDeterministicEntropy` usage examples
diff --git a/docs/keys.md b/docs/keys.md
index fab6dea0..2eba7eef 100644
--- a/docs/keys.md
+++ b/docs/keys.md
@@ -119,12 +119,12 @@ const flip128 =
 
 const faces = 2;
 const events = splitEvery(flip128, 1).map(parseInt);
-// `assertSuccess` simply throws any errors
+/* `assertSuccess` simply throws any errors */
 const entropy = assertSuccess(generateDeterministicEntropy(faces, events));
-
-const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy));
+/* Slice produced entropy at 16 bytes (128 bits) for 12 words: */
+const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy.slice(0, 16)));
 console.log(phrase);
-// => "crawl actual tool rally crazy lab work paper fragile favorite draft initial amount lawsuit task pupil clean crater genre rotate shoulder plate prevent bone"
+// => "crawl actual tool rally crazy lab work paper fragile favorite draft income"
 ```
 
 Note that `generateDeterministicEntropy` will return an error if the provided events do not include sufficient entropy for safe key generation (configurable via [`requiredEntropyBits`](https://libauth.org/functions/generateDeterministicEntropy.html)):
@@ -164,9 +164,11 @@ const faces = 6;
 const entropy = assertSuccess(generateDeterministicEntropy(faces, events));
 console.log(binToHex(entropy));
 // => "8d270d32340c28d8708023a5becf5dd8d55da45808c2ba97cfb7c2b0dcfefad1"
-const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy));
+
+/* Slice produced entropy at 16 bytes (128 bits) for 12 words: */
+const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy.slice(0, 16)));
 console.log(phrase);
-// => "minor debris erode gym secret history search afford pizza wait student random fiction split gasp blue ritual salmon unknown lyrics assist legal twice cactus"
+// => "minor debris erode gym secret history search afford pizza wait student ranch"
 ```
 
 #### BIP39 Mnemonic Phrase to BCH Wallet
diff --git a/src/lib/docs.spec.ts b/src/lib/docs.spec.ts
index 4231f067..1a8bd24f 100644
--- a/src/lib/docs.spec.ts
+++ b/src/lib/docs.spec.ts
@@ -530,14 +530,16 @@ test('keys.md: BIP39 Mnemonic Phrase from Coin Flips', (t) => {
 
   const faces = 2;
   const events = splitEvery(flip128, 1).map(parseInt);
+  /* `assertSuccess` simply throws any errors */
   const entropy = assertSuccess(generateDeterministicEntropy(faces, events));
-  const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy));
+  /* Slice produced entropy at 16 bytes (128 bits) for 12 words: */
+  const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy.slice(0, 16)));
   // eslint-disable-next-line no-console
   console.log(phrase);
-  // => "crawl actual tool rally crazy lab work paper fragile favorite draft initial amount lawsuit task pupil clean crater genre rotate shoulder plate prevent bone"
+  // => "crawl actual tool rally crazy lab work paper fragile favorite draft income"
   t.deepEqual(
     phrase,
-    'crawl actual tool rally crazy lab work paper fragile favorite draft initial amount lawsuit task pupil clean crater genre rotate shoulder plate prevent bone',
+    'crawl actual tool rally crazy lab work paper fragile favorite draft income',
   );
 });
 
@@ -575,13 +577,14 @@ test('keys.md: BIP39 Mnemonic Phrase from Dice Rolls', (t) => {
     binToHex(entropy),
     '8d270d32340c28d8708023a5becf5dd8d55da45808c2ba97cfb7c2b0dcfefad1',
   );
-  const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy));
+  /* Slice produced entropy at 16 bytes (128 bits) for 12 words: */
+  const { phrase } = assertSuccess(encodeBip39Mnemonic(entropy.slice(0, 16)));
   // eslint-disable-next-line no-console
   console.log(phrase);
-  // => "minor debris erode gym secret history search afford pizza wait student random fiction split gasp blue ritual salmon unknown lyrics assist legal twice cactus"
+  // => "minor debris erode gym secret history search afford pizza wait student ranch"
   t.deepEqual(
     phrase,
-    'minor debris erode gym secret history search afford pizza wait student random fiction split gasp blue ritual salmon unknown lyrics assist legal twice cactus',
+    'minor debris erode gym secret history search afford pizza wait student ranch',
   );
 });