@taquito/sapling 24.3.1-beta.1 → 25.0.0-beta.1

package/dist/taquito-sapling.umd.js

@@ -3453,73 +3453,196 @@
     _SaplingTransactionBuilder_inMemorySpendingKey = new WeakMap(), _SaplingTransactionBuilder_inMemoryProvingKey = new WeakMap(), _SaplingTransactionBuilder_saplingForger = new WeakMap(), _SaplingTransactionBuilder_contractAddress = new WeakMap(), _SaplingTransactionBuilder_saplingId = new WeakMap(), _SaplingTransactionBuilder_memoSize = new WeakMap(), _SaplingTransactionBuilder_readProvider = new WeakMap(), _SaplingTransactionBuilder_saplingWrapper = new WeakMap(), _SaplingTransactionBuilder_chainId = new WeakMap(), _SaplingTransactionBuilder_saplingState = new WeakMap();
 
     /**
-     * Utilities for hex, bytes, CSPRNG.
-     * @module
+     * Checks if something is Uint8Array. Be careful: nodejs Buffer will return true.
+     * @param a - value to test
+     * @returns `true` when the value is a Uint8Array-compatible view.
+     * @example
+     * Check whether a value is a Uint8Array-compatible view.
+     * ```ts
+     * isBytes(new Uint8Array([1, 2, 3]));
+     * ```
      */
-    /*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
-    /** Checks if something is Uint8Array. Be careful: nodejs Buffer will return true. */
     function isBytes(a) {
-        return a instanceof Uint8Array || (ArrayBuffer.isView(a) && a.constructor.name === 'Uint8Array');
+        // Plain `instanceof Uint8Array` is too strict for some Buffer / proxy / cross-realm cases.
+        // The fallback still requires a real ArrayBuffer view, so plain
+        // JSON-deserialized `{ constructor: ... }` spoofing is rejected, and
+        // `BYTES_PER_ELEMENT === 1` keeps the fallback on byte-oriented views.
+        return (a instanceof Uint8Array ||
+            (ArrayBuffer.isView(a) &&
+                a.constructor.name === 'Uint8Array' &&
+                'BYTES_PER_ELEMENT' in a &&
+                a.BYTES_PER_ELEMENT === 1));
     }
-    /** Asserts something is positive integer. */
+    /**
+     * Asserts something is a non-negative integer.
+     * @param n - number to validate
+     * @param title - label included in thrown errors
+     * @throws On wrong argument types. {@link TypeError}
+     * @throws On wrong argument ranges or values. {@link RangeError}
+     * @example
+     * Validate a non-negative integer option.
+     * ```ts
+     * anumber(32, 'length');
+     * ```
+     */
     function anumber(n, title = '') {
+        if (typeof n !== 'number') {
+            const prefix = title && `"${title}" `;
+            throw new TypeError(`${prefix}expected number, got ${typeof n}`);
+        }
         if (!Number.isSafeInteger(n) || n < 0) {
             const prefix = title && `"${title}" `;
-            throw new Error(`${prefix}expected integer >= 0, got ${n}`);
+            throw new RangeError(`${prefix}expected integer >= 0, got ${n}`);
         }
     }
-    /** Asserts something is Uint8Array. */
+    /**
+     * Asserts something is Uint8Array.
+     * @param value - value to validate
+     * @param length - optional exact length constraint
+     * @param title - label included in thrown errors
+     * @returns The validated byte array.
+     * @throws On wrong argument types. {@link TypeError}
+     * @throws On wrong argument ranges or values. {@link RangeError}
+     * @example
+     * Validate that a value is a byte array.
+     * ```ts
+     * abytes(new Uint8Array([1, 2, 3]));
+     * ```
+     */
     function abytes(value, length, title = '') {
         const bytes = isBytes(value);
         const len = value?.length;
         const needsLen = length !== undefined;
-        if (!bytes || (needsLen && len !== length)) {
+        if (!bytes || (needsLen)) {
             const prefix = title && `"${title}" `;
-            const ofLen = needsLen ? ` of length ${length}` : '';
+            const ofLen = '';
             const got = bytes ? `length=${len}` : `type=${typeof value}`;
-            throw new Error(prefix + 'expected Uint8Array' + ofLen + ', got ' + got);
+            const message = prefix + 'expected Uint8Array' + ofLen + ', got ' + got;
+            if (!bytes)
+                throw new TypeError(message);
+            throw new RangeError(message);
         }
         return value;
     }
-    /** Asserts something is hash */
+    /**
+     * Asserts something is a wrapped hash constructor.
+     * @param h - hash constructor to validate
+     * @throws On wrong argument types or invalid hash wrapper shape. {@link TypeError}
+     * @throws On invalid hash metadata ranges or values. {@link RangeError}
+     * @throws If the hash metadata allows empty outputs or block sizes. {@link Error}
+     * @example
+     * Validate a callable hash wrapper.
+     * ```ts
+     * import { ahash } from '@noble/hashes/utils.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
+     * ahash(sha256);
+     * ```
+     */
     function ahash(h) {
         if (typeof h !== 'function' || typeof h.create !== 'function')
-            throw new Error('Hash must wrapped by utils.createHasher');
+            throw new TypeError('Hash must wrapped by utils.createHasher');
         anumber(h.outputLen);
         anumber(h.blockLen);
+        // HMAC and KDF callers treat these as real byte lengths; allowing zero lets fake wrappers pass
+        // validation and can produce empty outputs instead of failing fast.
+        if (h.outputLen < 1)
+            throw new Error('"outputLen" must be >= 1');
+        if (h.blockLen < 1)
+            throw new Error('"blockLen" must be >= 1');
     }
-    /** Asserts a hash instance has not been destroyed / finished */
+    /**
+     * Asserts a hash instance has not been destroyed or finished.
+     * @param instance - hash instance to validate
+     * @param checkFinished - whether to reject finalized instances
+     * @throws If the hash instance has already been destroyed or finalized. {@link Error}
+     * @example
+     * Validate that a hash instance is still usable.
+     * ```ts
+     * import { aexists } from '@noble/hashes/utils.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
+     * const hash = sha256.create();
+     * aexists(hash);
+     * ```
+     */
     function aexists(instance, checkFinished = true) {
         if (instance.destroyed)
             throw new Error('Hash instance has been destroyed');
         if (checkFinished && instance.finished)
             throw new Error('Hash#digest() has already been called');
     }
-    /** Asserts output is properly-sized byte array */
+    /**
+     * Asserts output is a sufficiently-sized byte array.
+     * @param out - destination buffer
+     * @param instance - hash instance providing output length
+     * Oversized buffers are allowed; downstream code only promises to fill the first `outputLen` bytes.
+     * @throws On wrong argument types. {@link TypeError}
+     * @throws On wrong argument ranges or values. {@link RangeError}
+     * @example
+     * Validate a caller-provided digest buffer.
+     * ```ts
+     * import { aoutput } from '@noble/hashes/utils.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
+     * const hash = sha256.create();
+     * aoutput(new Uint8Array(hash.outputLen), hash);
+     * ```
+     */
     function aoutput(out, instance) {
         abytes(out, undefined, 'digestInto() output');
         const min = instance.outputLen;
         if (out.length < min) {
-            throw new Error('"digestInto() output" expected to be of length >=' + min);
+            throw new RangeError('"digestInto() output" expected to be of length >=' + min);
         }
     }
-    /** Zeroize a byte array. Warning: JS provides no guarantees. */
+    /**
+     * Zeroizes typed arrays in place. Warning: JS provides no guarantees.
+     * @param arrays - arrays to overwrite with zeros
+     * @example
+     * Zeroize sensitive buffers in place.
+     * ```ts
+     * clean(new Uint8Array([1, 2, 3]));
+     * ```
+     */
     function clean(...arrays) {
         for (let i = 0; i < arrays.length; i++) {
             arrays[i].fill(0);
         }
     }
-    /** Create DataView of an array for easy byte-level manipulation. */
+    /**
+     * Creates a DataView for byte-level manipulation.
+     * @param arr - source typed array
+     * @returns DataView over the same buffer region.
+     * @example
+     * Create a DataView over an existing buffer.
+     * ```ts
+     * createView(new Uint8Array(4));
+     * ```
+     */
     function createView(arr) {
         return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
     }
     /**
      * There is no setImmediate in browser and setTimeout is slow.
-     * Call of async fn will return Promise, which will be fullfiled only on
-     * next scheduler queue processing step and this is exactly what we need.
+     * This yields to the Promise/microtask scheduler queue, not to timers or the
+     * full macrotask event loop.
+     * @example
+     * Yield to the next scheduler tick.
+     * ```ts
+     * await nextTick();
+     * ```
      */
     const nextTick = async () => { };
-    /** Returns control to thread each 'tick' ms to avoid blocking. */
+    /**
+     * Returns control to the Promise/microtask scheduler every `tick`
+     * milliseconds to avoid blocking long loops.
+     * @param iters - number of loop iterations to run
+     * @param tick - maximum time slice in milliseconds
+     * @param cb - callback executed on each iteration
+     * @example
+     * Run a loop that periodically yields back to the event loop.
+     * ```ts
+     * await asyncLoop(2, 0, () => {});
+     * ```
+     */
     async function asyncLoop(iters, tick, cb) {
         let ts = Date.now();
         for (let i = 0; i < iters; i++) {
@@ -3535,41 +3658,101 @@
     /**
      * Converts string to bytes using UTF8 encoding.
      * Built-in doesn't validate input to be string: we do the check.
-     * @example utf8ToBytes('abc') // Uint8Array.from([97, 98, 99])
+     * Non-ASCII details are delegated to the platform `TextEncoder`.
+     * @param str - string to encode
+     * @returns UTF-8 encoded bytes.
+     * @throws On wrong argument types. {@link TypeError}
+     * @example
+     * Encode a string as UTF-8 bytes.
+     * ```ts
+     * utf8ToBytes('abc'); // Uint8Array.from([97, 98, 99])
+     * ```
      */
     function utf8ToBytes(str) {
         if (typeof str !== 'string')
-            throw new Error('string expected');
+            throw new TypeError('string expected');
         return new Uint8Array(new TextEncoder().encode(str)); // https://bugzil.la/1681809
     }
     /**
-     * Helper for KDFs: consumes uint8array or string.
-     * When string is passed, does utf8 decoding, using TextDecoder.
+     * Helper for KDFs: consumes Uint8Array or string.
+     * String inputs are UTF-8 encoded; byte-array inputs stay aliased to the caller buffer.
+     * @param data - user-provided KDF input
+     * @param errorTitle - label included in thrown errors
+     * @returns Byte representation of the input.
+     * @throws On wrong argument types. {@link TypeError}
+     * @example
+     * Normalize KDF input to bytes.
+     * ```ts
+     * kdfInputToBytes('password');
+     * ```
      */
     function kdfInputToBytes(data, errorTitle = '') {
         if (typeof data === 'string')
             return utf8ToBytes(data);
         return abytes(data, undefined, errorTitle);
     }
-    /** Merges default options and passed options. */
+    /**
+     * Merges default options and passed options.
+     * @param defaults - base option object
+     * @param opts - user overrides
+     * @returns Merged option object. The merge mutates `defaults` in place.
+     * @throws On wrong argument types. {@link TypeError}
+     * @example
+     * Merge user overrides onto default options.
+     * ```ts
+     * checkOpts({ dkLen: 32 }, { asyncTick: 10 });
+     * ```
+     */
     function checkOpts(defaults, opts) {
         if (opts !== undefined && {}.toString.call(opts) !== '[object Object]')
-            throw new Error('options must be object or undefined');
+            throw new TypeError('options must be object or undefined');
         const merged = Object.assign(defaults, opts);
         return merged;
     }
-    /** Creates function with outputLen, blockLen, create properties from a class constructor. */
+    /**
+     * Creates a callable hash function from a stateful class constructor.
+     * @param hashCons - hash constructor or factory
+     * @param info - optional metadata such as DER OID
+     * @returns Frozen callable hash wrapper with `.create()`.
+     *   Wrapper construction eagerly calls `hashCons(undefined)` once to read
+     *   `outputLen` / `blockLen`, so constructor side effects happen at module
+     *   init time.
+     * @example
+     * Wrap a stateful hash constructor into a callable helper.
+     * ```ts
+     * import { createHasher } from '@noble/hashes/utils.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
+     * const wrapped = createHasher(sha256.create, { oid: sha256.oid });
+     * wrapped(new Uint8Array([1]));
+     * ```
+     */
     function createHasher(hashCons, info = {}) {
-        const hashC = (msg, opts) => hashCons(opts).update(msg).digest();
+        const hashC = (msg, opts) => hashCons(opts)
+            .update(msg)
+            .digest();
         const tmp = hashCons(undefined);
         hashC.outputLen = tmp.outputLen;
         hashC.blockLen = tmp.blockLen;
+        hashC.canXOF = tmp.canXOF;
         hashC.create = (opts) => hashCons(opts);
         Object.assign(hashC, info);
         return Object.freeze(hashC);
     }
-    /** Creates OID opts for NIST hashes, with prefix 06 09 60 86 48 01 65 03 04 02. */
+    /**
+     * Creates OID metadata for NIST hashes with prefix `06 09 60 86 48 01 65 03 04 02`.
+     * @param suffix - final OID byte for the selected hash.
+     *   The helper accepts any byte even though only the documented NIST hash
+     *   suffixes are meaningful downstream.
+     * @returns Object containing the DER-encoded OID.
+     * @example
+     * Build OID metadata for a NIST hash.
+     * ```ts
+     * oidNist(0x01);
+     * ```
+     */
     const oidNist = (suffix) => ({
+        // Current NIST hashAlgs suffixes used here fit in one DER subidentifier octet.
+        // Larger suffix values would need base-128 OID encoding and a different length byte.
         oid: Uint8Array.from([0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, suffix]),
     });
 
@@ -3577,12 +3760,17 @@
      * HMAC: RFC2104 message authentication code.
      * @module
      */
-    /** Internal class for HMAC. */
+    /**
+     * Internal class for HMAC.
+     * Accepts any byte key, although RFC 2104 §3 recommends keys at least
+     * `HashLen` bytes long.
+     */
     class _HMAC {
         oHash;
         iHash;
         blockLen;
         outputLen;
+        canXOF = false;
         finished = false;
         destroyed = false;
         constructor(hash, key) {
@@ -3600,7 +3788,8 @@
             for (let i = 0; i < pad.length; i++)
                 pad[i] ^= 0x36;
             this.iHash.update(pad);
-            // By doing update (processing of first block) of outer hash here we can re-use it between multiple calls via clone
+            // By doing update (processing of the first block) of the outer hash here,
+            // we can re-use it between multiple calls via clone.
             this.oHash = hash.create();
             // Undo internal XOR && apply outer XOR
             for (let i = 0; i < pad.length; i++)
@@ -3615,11 +3804,14 @@
         }
         digestInto(out) {
             aexists(this);
-            abytes(out, this.outputLen, 'output');
+            aoutput(out, this);
             this.finished = true;
-            this.iHash.digestInto(out);
-            this.oHash.update(out);
-            this.oHash.digestInto(out);
+            const buf = out.subarray(0, this.outputLen);
+            // Reuse the first outputLen bytes for the inner digest; the outer hash consumes them before
+            // overwriting that same prefix with the final tag, leaving any oversized tail untouched.
+            this.iHash.digestInto(buf);
+            this.oHash.update(buf);
+            this.oHash.digestInto(buf);
             this.destroy();
         }
         digest() {
@@ -3628,7 +3820,8 @@
             return out;
         }
         _cloneInto(to) {
-            // Create new instance without calling constructor since key already in state and we don't know it.
+            // Create new instance without calling constructor since the key
+            // is already in state and we don't know it.
             to ||= Object.create(Object.getPrototypeOf(this), {});
             const { oHash, iHash, finished, destroyed, blockLen, outputLen } = this;
             to = to;
@@ -3649,18 +3842,11 @@
             this.iHash.destroy();
         }
     }
-    /**
-     * HMAC: RFC2104 message authentication code.
-     * @param hash - function that would be used e.g. sha256
-     * @param key - message key
-     * @param message - message data
-     * @example
-     * import { hmac } from '@noble/hashes/hmac';
-     * import { sha256 } from '@noble/hashes/sha2';
-     * const mac1 = hmac(sha256, 'key', 'message');
-     */
-    const hmac = (hash, key, message) => new _HMAC(hash, key).update(message).digest();
-    hmac.create = (hash, key) => new _HMAC(hash, key);
+    const hmac = /* @__PURE__ */ (() => {
+        const hmac_ = ((hash, key, message) => new _HMAC(hash, key).update(message).digest());
+        hmac_.create = (hash, key) => new _HMAC(hash, key);
+        return hmac_;
+    })();
 
     /**
      * PBKDF (RFC 2898). Can be used to create a key from password and salt.
@@ -3676,16 +3862,26 @@
         anumber(asyncTick, 'asyncTick');
         if (c < 1)
             throw new Error('iterations (c) must be >= 1');
+        // RFC 8018 §5.2 defines `dkLen` as "a positive integer".
+        if (dkLen < 1)
+            throw new Error('"dkLen" must be >= 1');
+        // RFC 8018 §5.2 step 1 requires rejecting oversize `dkLen`
+        // before allocating the destination buffer.
+        if (dkLen > (2 ** 32 - 1) * hash.outputLen)
+            throw new Error('derived key too long');
         const password = kdfInputToBytes(_password, 'password');
         const salt = kdfInputToBytes(_salt, 'salt');
         // DK = PBKDF2(PRF, Password, Salt, c, dkLen);
         const DK = new Uint8Array(dkLen);
         // U1 = PRF(Password, Salt + INT_32_BE(i))
         const PRF = hmac.create(hash, password);
+        // Cache PRF(P, S || ...) prefix state so each block only appends INT_32_BE(i).
         const PRFSalt = PRF._cloneInto().update(salt);
         return { c, dkLen, asyncTick, DK, PRF, PRFSalt };
     }
     function pbkdf2Output(PRF, PRFSalt, DK, prfW, u) {
+        // Shared sync/async cleanup point: wipe transient PRF state
+        // while preserving the derived key buffer.
         PRF.destroy();
         PRFSalt.destroy();
         if (prfW)
@@ -3694,13 +3890,22 @@
         return DK;
     }
     /**
-     * PBKDF2-HMAC: RFC 2898 key derivation function
+     * PBKDF2-HMAC: RFC 8018 key derivation function.
      * @param hash - hash function that would be used e.g. sha256
-     * @param password - password from which a derived key is generated
-     * @param salt - cryptographic salt
-     * @param opts - {c, dkLen} where c is work factor and dkLen is output message size
+     * @param password - password from which a derived key is generated;
+     *   JS string inputs are UTF-8 encoded first
+     * @param salt - cryptographic salt; JS string inputs are UTF-8 encoded first
+     * @param opts - PBKDF2 work factor and output settings. `dkLen`, if provided,
+     *   must be `>= 1` per RFC 8018 §5.2. See {@link Pbkdf2Opt}.
+     * @returns Derived key bytes.
+     * @throws If the PBKDF2 iteration count or derived-key settings are invalid. {@link Error}
      * @example
+     * PBKDF2-HMAC: RFC 2898 key derivation function.
+     * ```ts
+     * import { pbkdf2 } from '@noble/hashes/pbkdf2.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
      * const key = pbkdf2(sha256, 'password', 'salt', { dkLen: 32, c: Math.pow(2, 18) });
+     * ```
      */
     function pbkdf2(hash, password, salt, opts) {
         const { c, dkLen, DK, PRF, PRFSalt } = pbkdf2Init(hash, password, salt, opts);
@@ -3711,6 +3916,8 @@
         // DK = T1 + T2 + ⋯ + Tdklen/hlen
         for (let ti = 1, pos = 0; pos < dkLen; ti++, pos += PRF.outputLen) {
             // Ti = F(Password, Salt, c, i)
+            // The last Ti view can be shorter than hLen, which applies
+            // RFC 8018 §5.2 step 4's T_l<0..r-1> truncation without extra copies.
             const Ti = DK.subarray(pos, pos + PRF.outputLen);
             view.setInt32(0, ti, false);
             // F(Password, Salt, c, i) = U1 ^ U2 ^ ⋯ ^ Uc
@@ -3727,9 +3934,24 @@
         return pbkdf2Output(PRF, PRFSalt, DK, prfW, u);
     }
     /**
-     * PBKDF2-HMAC: RFC 2898 key derivation function. Async version.
+     * PBKDF2-HMAC: RFC 8018 key derivation function. Async version.
+     * @param hash - hash function that would be used e.g. sha256
+     * @param password - password from which a derived key is generated;
+     *   JS string inputs are UTF-8 encoded first
+     * @param salt - cryptographic salt; JS string inputs are UTF-8 encoded first
+     * @param opts - PBKDF2 work factor and output settings. `dkLen`, if provided,
+     *   must be `>= 1` per RFC 8018 §5.2. `asyncTick` is only a local
+     *   scheduler-yield knob for this JS wrapper, not part of RFC 8018.
+     *   See {@link Pbkdf2Opt}.
+     * @returns Promise resolving to derived key bytes.
+     * @throws If the PBKDF2 iteration count or derived-key settings are invalid. {@link Error}
      * @example
-     * await pbkdf2Async(sha256, 'password', 'salt', { dkLen: 32, c: 500_000 });
+     * PBKDF2-HMAC: RFC 2898 key derivation function.
+     * ```ts
+     * import { pbkdf2Async } from '@noble/hashes/pbkdf2.js';
+     * import { sha256 } from '@noble/hashes/sha2.js';
+     * const key = await pbkdf2Async(sha256, 'password', 'salt', { dkLen: 32, c: 500_000 });
+     * ```
      */
     async function pbkdf2Async(hash, password, salt, opts) {
         const { c, dkLen, asyncTick, DK, PRF, PRFSalt } = pbkdf2Init(hash, password, salt, opts);
@@ -3740,6 +3962,8 @@
         // DK = T1 + T2 + ⋯ + Tdklen/hlen
         for (let ti = 1, pos = 0; pos < dkLen; ti++, pos += PRF.outputLen) {
             // Ti = F(Password, Salt, c, i)
+            // The last Ti view can be shorter than hLen, which applies
+            // RFC 8018 §5.2 step 4's T_l<0..r-1> truncation without extra copies.
             const Ti = DK.subarray(pos, pos + PRF.outputLen);
             view.setInt32(0, ti, false);
             // F(Password, Salt, c, i) = U1 ^ U2 ^ ⋯ ^ Uc
@@ -3763,10 +3987,25 @@
     /**
      * Merkle-Damgard hash construction base class.
      * Could be used to create MD5, RIPEMD, SHA1, SHA2.
+     * Accepts only byte-aligned `Uint8Array` input, even when the underlying spec describes bit
+     * strings with partial-byte tails.
+     * @param blockLen - internal block size in bytes
+     * @param outputLen - digest size in bytes
+     * @param padOffset - trailing length field size in bytes
+     * @param isLE - whether length and state words are encoded in little-endian
+     * @example
+     * Use a concrete subclass to get the shared Merkle-Damgard update/digest flow.
+     * ```ts
+     * import { _SHA1 } from '@noble/hashes/legacy.js';
+     * const hash = new _SHA1();
+     * hash.update(new Uint8Array([97, 98, 99]));
+     * hash.digest();
+     * ```
      */
     class HashMD {
         blockLen;
         outputLen;
+        canXOF = false;
         padOffset;
         isLE;
         // For partial updates less than block size
@@ -3791,7 +4030,8 @@
             const len = data.length;
             for (let pos = 0; pos < len;) {
                 const take = Math.min(blockLen - this.pos, len - pos);
-                // Fast path: we have at least one block in input, cast it to view and process
+                // Fast path only when there is no buffered partial block: `take === blockLen` implies
+                // `this.pos === 0`, so we can process full blocks directly from the input view.
                 if (take === blockLen) {
                     const dataView = createView(data);
                     for (; blockLen <= len - pos; pos += blockLen)
@@ -3831,9 +4071,9 @@
             // Pad until full block byte with zeros
             for (let i = pos; i < blockLen; i++)
                 buffer[i] = 0;
-            // Note: sha512 requires length to be 128bit integer, but length in JS will overflow before that
-            // You need to write around 2 exabytes (u64_max / 8 / (1024**6)) for this to happen.
-            // So we just write lowest 64 bits of that value.
+            // `padOffset` reserves the whole length field. For SHA-384/512 the high 64 bits stay zero from
+            // the padding fill above, and JS will overflow before user input can make that half non-zero.
+            // So we only need to write the low 64 bits here.
             view.setBigUint64(blockLen - 8, BigInt(this.length * 8), isLE);
             this.process(view, 0);
             const oview = createView(out);
@@ -3851,6 +4091,8 @@
         digest() {
             const { buffer, outputLen } = this;
             this.digestInto(buffer);
+            // Copy before destroy(): subclasses wipe `buffer` during cleanup, but `digest()` must return
+            // fresh bytes to the caller.
             const res = buffer.slice(0, outputLen);
             this.destroy();
             return res;
@@ -3863,6 +4105,8 @@
             to.finished = finished;
             to.length = length;
             to.pos = pos;
+            // Only partial-block bytes need copying: when `length % blockLen === 0`, `pos === 0` and
+            // later `update()` / `digestInto()` overwrite `to.buffer` from the start before reading it.
             if (length % blockLen)
                 to.buffer.set(buffer);
             return to;
@@ -3871,24 +4115,26 @@
             return this._cloneInto();
         }
     }
-    /** Initial SHA512 state. Bits 0..64 of frac part of sqrt of primes 2..19 */
+    /** Initial SHA512 state from RFC 6234 §6.3: eight RFC 64-bit `H(0)` words stored as sixteen
+     * big-endian 32-bit halves. Derived from the fractional parts of the square roots of the first
+     * eight prime numbers. Exported as a shared table; callers must treat it as read-only because
+     * constructors copy halves from it by index. */
     const SHA512_IV = /* @__PURE__ */ Uint32Array.from([
         0x6a09e667, 0xf3bcc908, 0xbb67ae85, 0x84caa73b, 0x3c6ef372, 0xfe94f82b, 0xa54ff53a, 0x5f1d36f1,
         0x510e527f, 0xade682d1, 0x9b05688c, 0x2b3e6c1f, 0x1f83d9ab, 0xfb41bd6b, 0x5be0cd19, 0x137e2179,
     ]);
 
-    /**
-     * Internal helpers for u64. BigUint64Array is too slow as per 2025, so we implement it using Uint32Array.
-     * @todo re-check https://issues.chromium.org/issues/42212588
-     * @module
-     */
     const U32_MASK64 = /* @__PURE__ */ BigInt(2 ** 32 - 1);
     const _32n = /* @__PURE__ */ BigInt(32);
+    // Split bigint into two 32-bit halves. With `le=true`, returned fields become `{ h: low, l: high
+    // }` to match little-endian word order rather than the property names.
     function fromBig(n, le = false) {
         if (le)
             return { h: Number(n & U32_MASK64), l: Number((n >> _32n) & U32_MASK64) };
         return { h: Number((n >> _32n) & U32_MASK64) | 0, l: Number(n & U32_MASK64) | 0 };
     }
+    // Split bigint list into `[highWords, lowWords]` when `le=false`; with `le=true`, the first array
+    // holds the low halves because `fromBig(...)` swaps the semantic meaning of `h` and `l`.
     function split(lst, le = false) {
         const len = lst.length;
         let Ah = new Uint32Array(len);
@@ -3899,39 +4145,49 @@
         }
         return [Ah, Al];
     }
-    // for Shift in [0, 32)
+    // High 32-bit half of a 64-bit logical right shift for `s` in `0..31`.
     const shrSH = (h, _l, s) => h >>> s;
+    // Low 32-bit half of a 64-bit logical right shift, valid for `s` in `1..31`.
     const shrSL = (h, l, s) => (h << (32 - s)) | (l >>> s);
-    // Right rotate for Shift in [1, 32)
+    // High 32-bit half of a 64-bit right rotate, valid for `s` in `1..31`.
     const rotrSH = (h, l, s) => (h >>> s) | (l << (32 - s));
+    // Low 32-bit half of a 64-bit right rotate, valid for `s` in `1..31`.
     const rotrSL = (h, l, s) => (h << (32 - s)) | (l >>> s);
-    // Right rotate for Shift in (32, 64), NOTE: 32 is special case.
+    // High 32-bit half of a 64-bit right rotate, valid for `s` in `33..63`; `32` uses `rotr32*`.
     const rotrBH = (h, l, s) => (h << (64 - s)) | (l >>> (s - 32));
+    // Low 32-bit half of a 64-bit right rotate, valid for `s` in `33..63`; `32` uses `rotr32*`.
     const rotrBL = (h, l, s) => (h >>> (s - 32)) | (l << (64 - s));
-    // JS uses 32-bit signed integers for bitwise operations which means we cannot
-    // simple take carry out of low bit sum by shift, we need to use division.
+    // Add two split 64-bit words and return the split `{ h, l }` sum.
+    // JS uses 32-bit signed integers for bitwise operations, so we cannot simply shift the carry out
+    // of the low sum and instead use division.
     function add(Ah, Al, Bh, Bl) {
         const l = (Al >>> 0) + (Bl >>> 0);
         return { h: (Ah + Bh + ((l / 2 ** 32) | 0)) | 0, l: l | 0 };
     }
     // Addition with more than 2 elements
+    // Unmasked low-word accumulator for 3-way addition; pass the raw result into `add3H(...)`.
     const add3L = (Al, Bl, Cl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0);
+    // High-word finalize step for 3-way addition; `low` must be the untruncated output of `add3L(...)`.
     const add3H = (low, Ah, Bh, Ch) => (Ah + Bh + Ch + ((low / 2 ** 32) | 0)) | 0;
+    // Unmasked low-word accumulator for 4-way addition; pass the raw result into `add4H(...)`.
     const add4L = (Al, Bl, Cl, Dl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0);
+    // High-word finalize step for 4-way addition; `low` must be the untruncated output of `add4L(...)`.
     const add4H = (low, Ah, Bh, Ch, Dh) => (Ah + Bh + Ch + Dh + ((low / 2 ** 32) | 0)) | 0;
+    // Unmasked low-word accumulator for 5-way addition; pass the raw result into `add5H(...)`.
     const add5L = (Al, Bl, Cl, Dl, El) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0) + (El >>> 0);
+    // High-word finalize step for 5-way addition; `low` must be the untruncated output of `add5L(...)`.
     const add5H = (low, Ah, Bh, Ch, Dh, Eh) => (Ah + Bh + Ch + Dh + Eh + ((low / 2 ** 32) | 0)) | 0;
 
     /**
      * SHA2 hash function. A.k.a. sha256, sha384, sha512, sha512_224, sha512_256.
      * SHA256 is the fastest hash implementable in JS, even faster than Blake3.
-     * Check out [RFC 4634](https://www.rfc-editor.org/rfc/rfc4634) and
-     * [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf).
+     * Check out {@link https://www.rfc-editor.org/rfc/rfc4634 | RFC 4634} and
+     * {@link https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf | FIPS 180-4}.
      * @module
      */
     // SHA2-512 is slower than sha256 in js because u64 operations are slow.
-    // Round contants
-    // First 32 bits of the fractional parts of the cube roots of the first 80 primes 2..409
+    // SHA-384 / SHA-512 round constants from RFC 6234 §5.2:
+    // 80 full 64-bit words split into high/low halves.
     // prettier-ignore
     const K512 = /* @__PURE__ */ (() => split([
         '0x428a2f98d728ae22', '0x7137449123ef65cd', '0xb5c0fbcfec4d3b2f', '0xe9b5dba58189dbbc',
@@ -3957,10 +4213,11 @@
     ].map(n => BigInt(n))))();
     const SHA512_Kh = /* @__PURE__ */ (() => K512[0])();
     const SHA512_Kl = /* @__PURE__ */ (() => K512[1])();
-    // Reusable temporary buffers
+    // Reusable high-half schedule buffer for the RFC 6234 §6.4 64-bit `W_t` words.
     const SHA512_W_H = /* @__PURE__ */ new Uint32Array(80);
+    // Reusable low-half schedule buffer for the RFC 6234 §6.4 64-bit `W_t` words.
     const SHA512_W_L = /* @__PURE__ */ new Uint32Array(80);
-    /** Internal 64-byte base SHA2 hash class. */
+    /** Internal SHA-384 / SHA-512 compression engine from RFC 6234 §6.4. */
     class SHA2_64B extends HashMD {
         constructor(outputLen) {
             super(128, outputLen, 16, false);
@@ -4006,7 +4263,7 @@
                 const W2l = SHA512_W_L[i - 2] | 0;
                 const s1h = rotrSH(W2h, W2l, 19) ^ rotrBH(W2h, W2l, 61) ^ shrSH(W2h, W2l, 6);
                 const s1l = rotrSL(W2h, W2l, 19) ^ rotrBL(W2h, W2l, 61) ^ shrSL(W2h, W2l, 6);
-                // SHA256_W[i] = s0 + s1 + SHA256_W[i - 7] + SHA256_W[i - 16];
+                // SHA512_W[i] = s0 + s1 + SHA512_W[i - 7] + SHA512_W[i - 16];
                 const SUMl = add4L(s0l, s1l, SHA512_W_L[i - 7], SHA512_W_L[i - 16]);
                 const SUMh = add4H(SUMl, s0h, s1h, SHA512_W_H[i - 7], SHA512_W_H[i - 16]);
                 SHA512_W_H[i] = SUMh | 0;
@@ -4063,11 +4320,14 @@
             clean(SHA512_W_H, SHA512_W_L);
         }
         destroy() {
+            // HashMD callers route post-destroy usability through `destroyed`; zeroizing alone still leaves
+            // update()/digest() callable on reused instances.
+            this.destroyed = true;
             clean(this.buffer);
             this.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
         }
     }
-    /** Internal SHA2-512 hash class. */
+    /** Internal SHA-512 hash class grounded in RFC 6234 §6.3 and §6.4. */
     class _SHA512 extends SHA2_64B {
         Ah = SHA512_IV[0] | 0;
         Al = SHA512_IV[1] | 0;
@@ -4089,7 +4349,16 @@
             super(64);
         }
     }
-    /** SHA2-512 hash function from RFC 4634. */
+    /**
+     * SHA2-512 hash function from RFC 4634.
+     * @param msg - message bytes to hash
+     * @returns Digest bytes.
+     * @example
+     * Hash a message with SHA2-512.
+     * ```ts
+     * sha512(new Uint8Array([97, 98, 99]));
+     * ```
+     */
     const sha512 = /* @__PURE__ */ createHasher(() => new _SHA512(), 
     /* @__PURE__ */ oidNist(0x03));
 
@@ -4201,11 +4470,15 @@
     // so that any two texts that are equivalent will be reduced
     // to the same sequence of code points, called the normal form of the original text.
     // https://tonsky.me/blog/unicode/#why-is-a----
+    // BIP-39 requires UTF-8 NFKD for localized wordlists and mnemonic sentences.
+    // It also applies NFKD to the "mnemonic" + passphrase salt.
     function nfkd(str) {
         if (typeof str !== 'string')
             throw new TypeError('invalid mnemonic type: ' + typeof str);
         return str.normalize('NFKD');
     }
+    // BIP-39 mnemonics are consumed in NFKD form.
+    // They must contain 12, 15, 18, 21, or 24 words before checksum validation.
     function normalize(str) {
         const norm = nfkd(str);
         const words = norm.split(' ');
@@ -4213,19 +4486,30 @@
             throw new Error('Invalid mnemonic');
         return { nfkd: norm, words };
     }
+    // BIP-39 salts PBKDF2 with the UTF-8 NFKD string "mnemonic" + passphrase.
     const psalt = (passphrase) => nfkd('mnemonic' + passphrase);
     /**
      * Irreversible: Uses KDF to derive 64 bytes of key data from mnemonic + optional password.
-     * @param mnemonic 12-24 words
-     * @param passphrase string that will additionally protect the key
-     * @returns 64 bytes of key data
+     * @param mnemonic - 12-24 words.
+     * @param passphrase - String that will additionally protect the key.
+     * @returns 64 bytes of key data.
+     * @throws If the mnemonic shape is invalid. {@link Error}
+     * @throws On wrong argument types. {@link TypeError}
      * @example
+     * Derive a seed from a mnemonic with the async PBKDF2 helper.
+     * ```ts
      * const mnem = 'legal winner thank year wave sausage worth useful legal winner thank yellow';
-     * await mnemonicToSeed(mnem, 'password');
-     * // new Uint8Array([...64 bytes])
+     * const seed = await mnemonicToSeed(mnem, 'password');
+     * // => new Uint8Array([...64 bytes])
+     * ```
      */
+    // BIP-39 seed derivation is independent from mnemonic generation.
+    // These helpers normalize the phrase but do not verify checksum or wordlist membership.
     function mnemonicToSeed(mnemonic, passphrase = '') {
-        return pbkdf2Async(sha512, normalize(mnemonic).nfkd, psalt(passphrase), { c: 2048, dkLen: 64 });
+        return pbkdf2Async(sha512, normalize(mnemonic).nfkd, psalt(passphrase), {
+            c: 2048,
+            dkLen: 64,
+        });
     }
 
     var _InMemorySpendingKey_spendingKeyBuf, _InMemorySpendingKey_saplingViewingKey;