@btc-vision/btc-runtime 1.10.11 → 1.11.0-alpha

package/runtime/types/ExtendedAddressCache.ts

@@ -0,0 +1,27 @@
+let _cachedDeadAddress: usize = 0;
+let _cachedZeroAddress: usize = 0;
+
+export function getCachedDeadAddress(): usize {
+    return _cachedDeadAddress;
+}
+
+export function setCachedDeadAddress(addr: usize): void {
+    _cachedDeadAddress = addr;
+}
+
+export function getCachedZeroAddress(): usize {
+    return _cachedZeroAddress;
+}
+
+export function setCachedZeroAddress(addr: usize): void {
+    _cachedZeroAddress = addr;
+}
+
+export const DEAD_ARRAY: u8[] = [
+    40, 74, 228, 172, 219, 50, 169, 155, 163, 235, 250, 102, 169, 29, 219, 65, 167, 183, 161, 210,
+    254, 244, 21, 57, 153, 34, 205, 138, 4, 72, 92, 2,
+];
+
+export const ZERO_ARRAY: u8[] = [
+    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+];

package/runtime/types/SafeMath.ts

@@ -967,6 +967,7 @@ export class SafeMath {
      *
      * @param x - The input value
      * @returns floor(log2(x)) as u256
+     * @throws {Revert} When x is zero (log of zero)
      *
      * @example
      * ```typescript
@@ -975,11 +976,6 @@ export class SafeMath {
      * const log_1000 = SafeMath.approximateLog2(u256.fromU32(1000)); // Returns 9 (floor of 9.97...)
      * ```
      *
-     * @warning Returns 0 for both input 0 and input 1. While log2(0) is mathematically
-     * undefined and log2(1) = 0, this implementation returns 0 for both cases
-     * to avoid reverts and maintain gas efficiency in smart contracts. Callers
-     * requiring mathematical precision should handle these edge cases explicitly.
-     *
      * @security Extensively tested for monotonicity and consistency. Critical for:
      * - Binary search algorithms in sorted data structures
      * - Bit manipulation operations requiring position of highest bit
@@ -996,7 +992,7 @@ export class SafeMath {
      */
     public static approximateLog2(x: u256): u256 {
         const bitLen = SafeMath.bitLength256(x);
-        if (bitLen == 0) return u256.Zero;
+        if (bitLen === 0) throw new Revert('SafeMath: log of zero');
         return u256.fromU32(bitLen - 1);
     }
 
@@ -1005,6 +1001,7 @@ export class SafeMath {
      *
      * @param x - The input value (must be ≥ 1)
      * @returns ln(x) scaled by 10^6 for fixed-point precision
+     * @throws {Revert} When x is zero (log of zero)
      *
      * @example
      * ```typescript
@@ -1036,19 +1033,19 @@ export class SafeMath {
      * - Algorithm: Decomposes x = 2^k * (1 + r) where 0 ≤ r < 1
      * - Then: ln(x) = k*ln(2) + ln(1+r)
      * - Uses polyLn1p3 for accurate ln(1+r) approximation
-     * - Returns 0 for inputs 0 or 1 (mathematically ln(1) = 0)
      * - Result scaled by 10^6 to maintain 6 decimal places of precision
      * - Gas cost increases logarithmically with input magnitude
      * - Maximum theoretical input: u256.Max (though precision may degrade)
      * - Monotonicity guaranteed across entire input range
      */
     public static preciseLog(x: u256): u256 {
-        if (x.isZero() || u256.eq(x, SafeMath.ONE)) {
-            return u256.Zero;
+        const bitLen = SafeMath.bitLength256(x);
+
+        if (bitLen === 0) {
+            throw new Revert('SafeMath: log of zero');
         }
 
-        const bitLen = SafeMath.bitLength256(x);
-        if (bitLen <= 1) {
+        if (bitLen === 1) {
             return u256.Zero;
         }
 
@@ -1079,6 +1076,7 @@ export class SafeMath {
      *
      * @param x - The input value
      * @returns ln(x) scaled by 10^6 for fixed-point precision
+     * @throws {Revert} When x is zero (log of zero)
      *
      * @example
      * ```typescript
@@ -1102,18 +1100,18 @@ export class SafeMath {
      * @remarks
      * - Algorithm: ln(x) ≈ (bitLength(x) - 1) * ln(2)
      * - Exact for all powers of 2
-     * - Returns 0 for inputs 0 and 1
      * - Result scaled by 10^6 for 6 decimal places of precision
      * - O(1) complexity, extremely gas efficient
      * - Monotonically non-decreasing (required for security)
      */
     public static approxLog(x: u256): u256 {
-        if (x.isZero() || u256.eq(x, SafeMath.ONE)) {
-            return u256.Zero;
+        const bitLen: u32 = SafeMath.bitLength256(x);
+
+        if (bitLen === 0) {
+            throw new Revert('SafeMath: log of zero');
         }
 
-        const bitLen: u32 = SafeMath.bitLength256(x);
-        if (bitLen <= 1) {
+        if (bitLen === 1) {
             return u256.Zero;
         }
 
@@ -1246,10 +1244,103 @@ export class SafeMath {
 
         // Sum and apply final scaling
         const atanhSum: u64 = wScaled + t3 + t5 + t7 + t9;
-        return atanhSum << 1; // Multiply by 2 using bit shift
+        const result: u64 = atanhSum << 1; // Multiply by 2 using bit shift
+
+        // Preserve monotonicity for tiny positive inputs that would round to zero
+        return result == 0 ? 1 : result;
     }
 
-    // ==================== Internal Helper Functions ====================
+    /**
+     * Calculate ln(a/b) with precision, avoiding bit-length mismatch issues.
+     * Returns the result scaled by 1e6 (i.e., ln(a/b) * 1,000,000)
+     *
+     * This function correctly handles the case where a and b have different
+     * bit lengths, which would cause incorrect results if computing
+     * preciseLog(a) - preciseLog(b) directly.
+     *
+     * @param a - Numerator (must be > 0)
+     * @param b - Denominator (must be > 0)
+     * @returns ln(a/b) * 1,000,000
+     * @throws {Revert} When:
+     * - a is zero (log of zero)
+     * - b is zero (division by zero)
+     * - result is negative (return type is unsigned)
+     */
+    public static preciseLogRatio(a: u256, b: u256): u256 {
+        if (b.isZero()) {
+            throw new Revert('SafeMath: division by zero');
+        }
+
+        if (a.isZero()) {
+            throw new Revert('SafeMath: log of zero');
+        }
+
+        // If a == b, ln(1) = 0
+        if (u256.eq(a, b)) {
+            return u256.Zero;
+        }
+
+        const SCALE = u256.fromU64(1_000_000);
+        const LN2_SCALED = u256.fromU64(693147); // ln(2) * 1e6
+
+        // Compute ratio = a / b with scaling to preserve precision
+        // scaledRatio = (a * SCALE) / b represents (a/b) * SCALE
+        const scaledRatio = SafeMath.div(SafeMath.mul(a, SCALE), b);
+
+        if (scaledRatio.isZero()) {
+            // a/b is very small, return negative (but we only handle positive ln)
+            throw new Revert('SafeMath: negative log result');
+        }
+
+        // If scaledRatio == SCALE, then a/b == 1, ln = 0
+        if (u256.eq(scaledRatio, SCALE)) {
+            return u256.Zero;
+        }
+
+        // If scaledRatio < SCALE (i.e., a < b), ln is negative
+        if (u256.lt(scaledRatio, SCALE)) {
+            throw new Revert('SafeMath: negative log result');
+        }
+
+        // Now scaledRatio > SCALE, meaning a/b > 1, so ln(a/b) > 0
+        // We want to compute ln(scaledRatio / SCALE) = ln(scaledRatio) - ln(SCALE)
+        // But we do this correctly by computing ln(1 + (scaledRatio - SCALE) / SCALE)
+
+        // fraction = (scaledRatio - SCALE) / SCALE = (a/b - 1)
+        // fractionScaled = scaledRatio - SCALE represents fraction * SCALE
+        const fractionScaled = SafeMath.sub(scaledRatio, SCALE);
+
+        // For small fractions (a/b < 2, i.e., fractionScaled < SCALE), use the stable polyLn1p3 approximation
+        // Note: Use strict less-than to ensure ratio = 2 uses the k*ln(2) decomposition
+        // This ensures continuity at the boundary - both paths give ln(2) for ratio = 2
+        if (u256.lt(fractionScaled, SCALE)) {
+            return u256.fromU64(SafeMath.polyLn1p3(fractionScaled.toU64()));
+        }
+
+        // For ratios >= 2, use the decomposition:
+        // ln(a/b) = k * ln(2) + ln(normalized)
+        // where normalized = (a/b) / 2^k is in range [1, 2)
+
+        // Find k such that scaledRatio / 2^k is in [SCALE, 2*SCALE)
+        let temp = scaledRatio;
+        let k: u32 = 0;
+        const twoScale = SafeMath.mul(SCALE, u256.fromU32(2));
+
+        while (u256.ge(temp, twoScale)) {
+            temp = SafeMath.shr(temp, 1);
+            k++;
+        }
+
+        // Now temp is in [SCALE, 2*SCALE), representing a value in [1, 2)
+        // ln(a/b) = k * ln(2) + ln(temp/SCALE)
+        // temp/SCALE is in [1, 2), so (temp - SCALE)/SCALE is in [0, 1)
+
+        const normalizedFraction = SafeMath.sub(temp, SCALE);
+        const lnNormalized = SafeMath.polyLn1p3(normalizedFraction.toU64());
+        const base = SafeMath.mul(u256.fromU32(k), LN2_SCALED);
+
+        return SafeMath.add(base, u256.fromU64(lnNormalized));
+    }
 
     /**
      * @internal

package/runtime/types/SchnorrSignature.ts

@@ -0,0 +1,44 @@
+import { ExtendedAddress } from './ExtendedAddress';
+
+/**
+ * Represents a Schnorr signature paired with the signer's ExtendedAddress.
+ *
+ * This class bundles a 64-byte Schnorr signature with its associated
+ * ExtendedAddress (64 bytes), providing a complete signed data structure
+ * for Bitcoin Taproot-compatible signatures.
+ *
+ * @example
+ * ```typescript
+ * // Reading a Schnorr signature from calldata
+ * const sig = calldata.readSchnorrSignature();
+ * const signer = sig.address;
+ * const signature = sig.signature;
+ *
+ * // Verify the signature
+ * const isValid = Blockchain.verifySignature(signer, signature, messageHash);
+ * ```
+ */
+@final
+export class SchnorrSignature {
+    /**
+     * The signer's ExtendedAddress (64 bytes).
+     * Contains both the tweaked Schnorr public key and ML-DSA key hash.
+     */
+    public readonly address: ExtendedAddress;
+
+    /**
+     * The 64-byte Schnorr signature.
+     */
+    public readonly signature: Uint8Array;
+
+    /**
+     * Creates a new SchnorrSignature instance.
+     *
+     * @param address - The signer's ExtendedAddress
+     * @param signature - The 64-byte Schnorr signature
+     */
+    constructor(address: ExtendedAddress, signature: Uint8Array) {
+        this.address = address;
+        this.signature = signature;
+    }
+}

package/runtime/utils/lengths.ts

@@ -1,4 +1,6 @@
 export const ADDRESS_BYTE_LENGTH: i32 = 32;
+export const EXTENDED_ADDRESS_BYTE_LENGTH: i32 = 64;
+export const SCHNORR_SIGNATURE_BYTE_LENGTH: i32 = 64;
 export const SELECTOR_BYTE_LENGTH: i32 = 4;
 
 export const U256_BYTE_LENGTH: i32 = 32;