From f2ed4e797076891edb004f33a1b9c1e73cfd6e69 Mon Sep 17 00:00:00 2001
From: Chris Duncan <chris@zoso.dev>
Date: Wed, 30 Jul 2025 09:55:09 -0700
Subject: [PATCH] Update mnemonic class comments.

---
 src/lib/bip39-mnemonic.ts | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/src/lib/bip39-mnemonic.ts b/src/lib/bip39-mnemonic.ts
index 758bf3e..a8dab41 100644
--- a/src/lib/bip39-mnemonic.ts
+++ b/src/lib/bip39-mnemonic.ts
@@ -28,10 +28,11 @@ export class Bip39Mnemonic {
 	/**
 	* Derives a mnemonic phrase from source of entropy or seed.
 	*
-	* The entropy must be between 32-64 characters to stay within the defined
-	* limit of 128-256 bits. Typically wallets use the maximum entropy allowed.
+	* The entropy must be between 16-32 bytes (32-64 characters) to stay within
+	* the limit of 128-256 bits defined in BIP-39. Typically, wallets use the
+	* maximum entropy allowed.
 	*
-	* @param {string} entropy - Hexadecimal string
+	* @param {(string|Uint8Array<ArrayBuffer>)} entropy - Cryptographically secure random value
 	* @returns {string} Mnemonic phrase created using the BIP-39 wordlist
 	*/
 	static async fromEntropy (entropy: string | Uint8Array<ArrayBuffer>): Promise<Bip39Mnemonic> {
@@ -62,7 +63,7 @@ export class Bip39Mnemonic {
 	/**
 	* Imports and validates an existing mnemonic phrase.
 	*
-	* The phrase must be valid according to the BIP-39 specification. Typically
+	* The phrase must be valid according to the BIP-39 specification. Typically,
 	* wallets use the maximum of 24 words.
 	*
 	* @param {string} phrase - String of 12, 15, 18, 21, or 24 words
@@ -81,7 +82,7 @@ export class Bip39Mnemonic {
 	}
 
 	/**
-	* Validates a mnemonic phrase.
+	* Validates a mnemonic phrase meets the BIP-39 specification.
 	*
 	* @param {string} mnemonic - Mnemonic phrase to validate
 	* @returns {boolean} True if the mnemonic phrase is valid
@@ -142,8 +143,7 @@ export class Bip39Mnemonic {
 	}
 
 	/**
-	* Erases seed bytes and releases variable references to allow garbage
-	* collection.
+	* Erases seed bytes and releases variable references.
 	*/
 	destroy () {
 		bytes.erase(this.#bip39Seed)
@@ -153,6 +153,15 @@ export class Bip39Mnemonic {
 		this.#phrase = undefined
 	}
 
+	/**
+	* Converts the mnemonic phrase to a BIP-39 seed.
+	*
+	* A passphrase string can be specified. If the passphrase is undefined, null,
+	* or not a string, the empty string ("") is used instead.
+	*
+	* @param {string} [passphrase=''] - Used as the PBKDF2 salt. Default: ""
+	* @returns {Promise<Uint8Array<ArrayBuffer>>} Promise for seed as bytes
+	*/
 	async toBip39Seed (passphrase: string): Promise<Uint8Array<ArrayBuffer>>
 	/**
 	* Converts the mnemonic phrase to a BIP-39 seed.
@@ -161,10 +170,10 @@ export class Bip39Mnemonic {
 	* or not a string, the empty string ("") is used instead.
 	*
 	* @param {string} [passphrase=''] - Used as the PBKDF2 salt. Default: ""
-	* @returns {string} Hexadecimal seed
+	* @returns {Promise<string>}  Promise for seed as hexadecimal string
 	*/
 	async toBip39Seed (passphrase: string, format: 'hex'): Promise<string>
-	async toBip39Seed (passphrase: string, format?: 'hex'): Promise<string | Uint8Array> {
+	async toBip39Seed (passphrase: string, format?: 'hex'): Promise<string | Uint8Array<ArrayBuffer>> {
 		if (this.phrase == null) {
 			throw new Error('BIP-39 mnemonic phrase not found')
 		}
@@ -205,6 +214,7 @@ export class Bip39Mnemonic {
 	/**
 	* Converts the mnemonic phrase to a BLAKE2b seed.
 	*
+	* @param {string} format
 	* @returns {Promise<string>} Promise for seed as hexadecimal string
 	*/
 	async toBlake2bSeed (format: 'hex'): Promise<string>
-- 
2.47.3