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

package/dist/taquito-timelock.umd.js

@@ -5,22 +5,62 @@
 })(this, (function (exports, nacl, bigInt) { 'use strict';
 
     /**
-     * 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;
@@ -29,64 +69,171 @@
             const prefix = title && `"${title}" `;
             const ofLen = needsLen ? ` of length ${length}` : '';
             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 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);
         }
     }
-    /** Cast u8 / u16 / u32 to u32. */
+    /**
+     * Casts a typed array view to Uint32Array.
+     * `arr.byteOffset` must already be 4-byte aligned or the platform
+     * Uint32Array constructor will throw.
+     * @param arr - source typed array
+     * @returns Uint32Array view over the same buffer.
+     * @example
+     * Reinterpret a byte array as 32-bit words.
+     * ```ts
+     * u32(new Uint8Array(8));
+     * ```
+     */
     function u32(arr) {
         return new Uint32Array(arr.buffer, arr.byteOffset, Math.floor(arr.byteLength / 4));
     }
-    /** 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);
         }
     }
-    /** Is current platform little-endian? Most are. Big-Endian platform: IBM */
+    /** Whether the current platform is little-endian. */
     const isLE = /* @__PURE__ */ (() => new Uint8Array(new Uint32Array([0x11223344]).buffer)[0] === 0x44)();
-    /** The byte swap operation for uint32 */
+    /**
+     * Byte-swap operation for uint32 values.
+     * @param word - source word
+     * @returns Word with reversed byte order.
+     * @example
+     * Reverse the byte order of a 32-bit word.
+     * ```ts
+     * byteSwap(0x11223344);
+     * ```
+     */
     function byteSwap(word) {
         return (((word << 24) & 0xff000000) |
             ((word << 8) & 0xff0000) |
             ((word >>> 8) & 0xff00) |
             ((word >>> 24) & 0xff));
     }
-    /** Conditionally byte swap if on a big-endian platform */
+    /**
+     * Conditionally byte-swaps one 32-bit word on big-endian platforms.
+     * @param n - source word
+     * @returns Original or byte-swapped word depending on platform endianness.
+     * @example
+     * Normalize a 32-bit word for host endianness.
+     * ```ts
+     * swap8IfBE(0x11223344);
+     * ```
+     */
     const swap8IfBE = isLE
         ? (n) => n
-        : (n) => byteSwap(n);
-    /** In place byte swap for Uint32Array */
+        : (n) => byteSwap(n) >>> 0;
+    /**
+     * Byte-swaps every word of a Uint32Array in place.
+     * @param arr - array to mutate
+     * @returns The same array after mutation; callers pass live state arrays here.
+     * @example
+     * Reverse the byte order of every word in place.
+     * ```ts
+     * byteSwap32(new Uint32Array([0x11223344]));
+     * ```
+     */
     function byteSwap32(arr) {
         for (let i = 0; i < arr.length; i++) {
             arr[i] = byteSwap(arr[i]);
         }
         return arr;
     }
+    /**
+     * Conditionally byte-swaps a Uint32Array on big-endian platforms.
+     * @param u - array to normalize for host endianness
+     * @returns Original or byte-swapped array depending on platform endianness.
+     *   On big-endian runtimes this mutates `u` in place via `byteSwap32(...)`.
+     * @example
+     * Normalize a word array for host endianness.
+     * ```ts
+     * swap32IfBE(new Uint32Array([0x11223344]));
+     * ```
+     */
     const swap32IfBE = isLE
         ? (u) => u
         : byteSwap32;
-    /** 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);
@@ -97,8 +244,10 @@
      * @module
      */
     /**
-     * Internal blake variable.
-     * For BLAKE2b, the two extra permutations for rounds 10 and 11 are SIGMA[10..11] = SIGMA[0..1].
+     * Internal blake permutation table.
+     * Rows `0..9` serve BLAKE2s, rows `0..11` serve BLAKE2b with `10..11 = 0..1`, and Blake1 also
+     * reuses the later rows shown below. Blake1 expands rounds `10..15` as `SIGMA[i % 10]`, so rows
+     * `10..15` intentionally repeat rows `0..5` for the 14-round (256) and 16-round (512) variants.
      */
     // prettier-ignore
     const BSIGMA = /* @__PURE__ */ Uint8Array.from([
@@ -121,35 +270,38 @@
         2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9,
     ]);
 
-    /**
-     * 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 };
     }
-    // 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));
-    // Right rotate for shift===32 (just swaps l&h)
+    // High 32-bit half of a 64-bit right rotate for `s === 32`; this is just the swapped low half.
     const rotr32H = (_h, l) => l;
+    // Low 32-bit half of a 64-bit right rotate for `s === 32`; this is just the swapped high half.
     const rotr32L = (h, _l) => h;
-    // 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;
 
     /**
@@ -157,14 +309,15 @@
      * b could have been faster, but there is no fast u64 in js, so s is 1.5x faster.
      * @module
      */
-    // Same as SHA512_IV, but swapped endianness: LE instead of BE. iv[1] is iv[0], etc.
+    // Same IV words as `SHA512_IV`, but endian-swapped into LE u32 low/high halves
+    // for the BLAKE2b u64 helpers below.
     const B2B_IV = /* @__PURE__ */ Uint32Array.from([
         0xf3bcc908, 0x6a09e667, 0x84caa73b, 0xbb67ae85, 0xfe94f82b, 0x3c6ef372, 0x5f1d36f1, 0xa54ff53a,
         0xade682d1, 0x510e527f, 0x2b3e6c1f, 0x9b05688c, 0xfb41bd6b, 0x1f83d9ab, 0x137e2179, 0x5be0cd19,
     ]);
-    // Temporary buffer
+    // Shared synchronous BLAKE2b work vector as LE u32 low/high halves.
     const BBUF = /* @__PURE__ */ new Uint32Array(32);
-    // Mixing function G splitted in two halfs
+    // BLAKE2b G mix split into two half-rounds over LE u32 low/high limbs.
     function G1b(a, b, c, d, msg, x) {
         // NOTE: V is LE here
         const Xl = msg[x], Xh = msg[x + 1]; // prettier-ignore
@@ -189,6 +342,7 @@
         ((BBUF[2 * c] = Cl), (BBUF[2 * c + 1] = Ch));
         ((BBUF[2 * d] = Dl), (BBUF[2 * d + 1] = Dh));
     }
+    // Second half-round of the same LE-limb BLAKE2b G mix; `x` is the message word offset.
     function G2b(a, b, c, d, msg, x) {
         // NOTE: V is LE here
         const Xl = msg[x], Xh = msg[x + 1]; // prettier-ignore
@@ -215,9 +369,11 @@
     }
     function checkBlake2Opts(outputLen, opts = {}, keyLen, saltLen, persLen) {
         anumber(keyLen);
-        if (outputLen < 0 || outputLen > keyLen)
+        // RFC 7693 §2.1 requires digest length nn in 1..keyLen.
+        if (outputLen <= 0 || outputLen > keyLen)
             throw new Error('outputLen bigger than keyLen');
         const { key, salt, personalization } = opts;
+        // This API uses `undefined` for the RFC 7693 `kk = 0` case, so a provided key must be non-empty.
         if (key !== undefined && (key.length < 1 || key.length > keyLen))
             throw new Error('"key" expected to be undefined or of length=1..' + keyLen);
         if (salt !== undefined)
@@ -235,6 +391,7 @@
         pos = 0;
         blockLen;
         outputLen;
+        canXOF = false;
         constructor(blockLen, outputLen) {
             anumber(blockLen);
             anumber(outputLen);
@@ -264,7 +421,7 @@
                 }
                 const take = Math.min(blockLen - this.pos, len - pos);
                 const dataOffset = offset + pos;
-                // full block && aligned to 4 bytes && not last in input
+                // Zero-copy only for full, 4-byte-aligned, non-final blocks.
                 if (take === blockLen && !(dataOffset % 4) && pos + take < len) {
                     const data32 = new Uint32Array(buf, dataOffset, Math.floor((len - pos) / 4));
                     swap32IfBE(data32);
@@ -292,18 +449,33 @@
             swap32IfBE(buffer32);
             this.compress(buffer32, 0, true);
             swap32IfBE(buffer32);
+            // Reject unaligned views explicitly instead of hiding them behind a full scratch copy.
+            if (out.byteOffset & 3)
+                throw new RangeError('"digestInto() output" expected 4-byte aligned byteOffset, got ' + out.byteOffset);
+            const state = this.get();
             const out32 = u32(out);
-            this.get().forEach((v, i) => (out32[i] = swap8IfBE(v)));
+            const full = Math.floor(this.outputLen / 4);
+            for (let i = 0; i < full; i++)
+                out32[i] = swap8IfBE(state[i]);
+            const tail = this.outputLen % 4;
+            if (!tail)
+                return;
+            const off = full * 4;
+            const word = state[full];
+            for (let i = 0; i < tail; i++)
+                out[off + i] = word >>> (8 * i);
         }
         digest() {
             const { buffer, outputLen } = this;
             this.digestInto(buffer);
+            // Return a copy so callers do not alias the instance scratch buffer used during finalization.
             const res = buffer.slice(0, outputLen);
             this.destroy();
             return res;
         }
         _cloneInto(to) {
             const { buffer, length, finished, destroyed, outputLen, pos } = this;
+            // Recreate only `dkLen`; key/salt/personalization are already absorbed into the copied state.
             to ||= new this.constructor({ dkLen: outputLen });
             to.set(...this.get());
             to.buffer.set(buffer);
@@ -319,9 +491,9 @@
             return this._cloneInto();
         }
     }
-    /** Internal blake2b hash class. */
+    /** Internal blake2b hash class with state stored as LE u32 low/high halves. */
     class _BLAKE2b extends _BLAKE2 {
-        // Same as SHA-512, but LE
+        // Same IV words as SHA-512 / BLAKE2b, encoded as LE u32 low/high halves.
         v0l = B2B_IV[0] | 0;
         v0h = B2B_IV[1] | 0;
         v1l = B2B_IV[2] | 0;
@@ -348,6 +520,8 @@
                 abytes(key, undefined, 'key');
                 keyLength = key.length;
             }
+            // RFC 7693 §2.5: xor `p[0] = 0x0101kknn` into the low 32 bits of `h[0]`;
+            // the high 32 bits stay at `IV[0]`.
             this.v0l ^= this.outputLen | (keyLength << 8) | (0x01 << 16) | (0x01 << 24);
             if (salt !== undefined) {
                 abytes(salt, undefined, 'salt');
@@ -409,6 +583,8 @@
             }
             let j = 0;
             const s = BSIGMA;
+            // SIGMA selects 64-bit message words; multiply by 2 because `msg` stores
+            // each word as [low32, high32].
             for (let i = 0; i < 12; i++) {
                 G1b(0, 4, 8, 12, msg, offset + 2 * s[j++]);
                 G2b(0, 4, 8, 12, msg, offset + 2 * s[j++]);
@@ -454,7 +630,15 @@
     /**
      * Blake2b hash function. 64-bit. 1.5x slower than blake2s in JS.
      * @param msg - message that would be hashed
-     * @param opts - dkLen output length, key for MAC mode, salt, personalization
+     * @param opts - Optional output, MAC, salt, and personalization settings.
+     *   `dkLen` must be 1..64 bytes; `salt` and `personalization`, if present,
+     *   must be 16 bytes each. See {@link Blake2Opts}.
+     * @returns Digest bytes.
+     * @example
+     * Hash a message with Blake2b.
+     * ```ts
+     * blake2b(new Uint8Array([97, 98, 99]));
+     * ```
      */
     const blake2b = /* @__PURE__ */ createHasher((opts) => new _BLAKE2b(opts));