@btc-vision/btc-runtime 1.10.12 → 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,7 +1244,10 @@ 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;
     }
 
     /**
@@ -1260,10 +1261,18 @@ export class SafeMath {
      * @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 (a.isZero() || b.isZero()) {
-            return u256.Zero;
+        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
@@ -1280,8 +1289,7 @@ export class SafeMath {
 
         if (scaledRatio.isZero()) {
             // a/b is very small, return negative (but we only handle positive ln)
-            // For a < b, ln(a/b) < 0. Return 0 or handle separately if needed.
-            return u256.Zero;
+            throw new Revert('SafeMath: negative log result');
         }
 
         // If scaledRatio == SCALE, then a/b == 1, ln = 0
@@ -1290,9 +1298,8 @@ export class SafeMath {
         }
 
         // If scaledRatio < SCALE (i.e., a < b), ln is negative
-        // We only return positive values, so return 0 for this case
         if (u256.lt(scaledRatio, SCALE)) {
-            return u256.Zero;
+            throw new Revert('SafeMath: negative log result');
         }
 
         // Now scaledRatio > SCALE, meaning a/b > 1, so ln(a/b) > 0
@@ -1303,11 +1310,11 @@ export class SafeMath {
         // fractionScaled = scaledRatio - SCALE represents fraction * SCALE
         const fractionScaled = SafeMath.sub(scaledRatio, SCALE);
 
-        // For small fractions (a/b < 2, i.e., fractionScaled < SCALE), use Taylor series
+        // 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 this.calculateLnOnePlusFraction(fractionScaled, SCALE);
+            return u256.fromU64(SafeMath.polyLn1p3(fractionScaled.toU64()));
         }
 
         // For ratios >= 2, use the decomposition:
@@ -1329,10 +1336,10 @@ export class SafeMath {
         // temp/SCALE is in [1, 2), so (temp - SCALE)/SCALE is in [0, 1)
 
         const normalizedFraction = SafeMath.sub(temp, SCALE);
-        const lnNormalized = this.calculateLnOnePlusFraction(normalizedFraction, SCALE);
+        const lnNormalized = SafeMath.polyLn1p3(normalizedFraction.toU64());
         const base = SafeMath.mul(u256.fromU32(k), LN2_SCALED);
 
-        return SafeMath.add(base, lnNormalized);
+        return SafeMath.add(base, u256.fromU64(lnNormalized));
     }
 
     /**
@@ -1354,40 +1361,4 @@ export class SafeMath {
         const mMinusX = u256.sub(m, x);
         return u256.ge(x, mMinusX) ? u256.sub(x, mMinusX) : u256.add(x, x);
     }
-
-    // ==================== Internal Helper Functions ====================
-
-    /**
-     * Helper function: Calculate ln(1 + x) where x is provided as xScaled = x * scale
-     * Returns the result scaled by scale (i.e., ln(1+x) * scale)
-     *
-     * Uses Taylor series: ln(1+x) ≈ x - x²/2 + x³/3 - x⁴/4 + x⁵/5
-     * Valid for 0 <= x <= 1 (i.e., xScaled <= scale)
-     */
-    private static calculateLnOnePlusFraction(xScaled: u256, scale: u256): u256 {
-        if (xScaled.isZero()) {
-            return u256.Zero;
-        }
-
-        // x² scaled
-        const x2 = SafeMath.div(SafeMath.mul(xScaled, xScaled), scale);
-
-        // x³ scaled
-        const x3 = SafeMath.div(SafeMath.mul(x2, xScaled), scale);
-
-        // x⁴ scaled
-        const x4 = SafeMath.div(SafeMath.mul(x3, xScaled), scale);
-
-        // x⁵ scaled
-        const x5 = SafeMath.div(SafeMath.mul(x4, xScaled), scale);
-
-        // ln(1+x) ≈ x - x²/2 + x³/3 - x⁴/4 + x⁵/5
-        let result = xScaled;
-        result = SafeMath.sub(result, SafeMath.div(x2, u256.fromU32(2)));
-        result = SafeMath.add(result, SafeMath.div(x3, u256.fromU32(3)));
-        result = SafeMath.sub(result, SafeMath.div(x4, u256.fromU32(4)));
-        result = SafeMath.add(result, SafeMath.div(x5, u256.fromU32(5)));
-
-        return result;
-    }
 }

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;