@btc-vision/btc-runtime 1.10.10 → 1.10.11

package/docs/types/safe-math.md

@@ -0,0 +1,446 @@
+# SafeMath
+
+SafeMath provides overflow-safe arithmetic operations for `u256` and other numeric types. It's essential for all smart contract arithmetic to prevent silent overflow/underflow bugs.
+
+## Overview
+
+```typescript
+import { SafeMath } from '@btc-vision/btc-runtime/runtime';
+import { u256 } from '@btc-vision/as-bignum/assembly';
+
+const a = u256.fromU64(100);
+const b = u256.fromU64(50);
+
+// Safe operations
+const sum = SafeMath.add(a, b);       // 150
+const diff = SafeMath.sub(a, b);      // 50
+const product = SafeMath.mul(a, b);   // 5000
+const quotient = SafeMath.div(a, b);  // 2
+```
+
+## Why SafeMath?
+
+### The Problem
+
+Native arithmetic can overflow silently:
+
+```typescript
+// DANGEROUS: Silent overflow
+const max = u256.Max;
+const result = max + u256.One;  // Wraps to 0!
+
+// DANGEROUS: Silent underflow
+const zero = u256.Zero;
+const result = zero - u256.One;  // Wraps to u256.Max!
+```
+
+### The Solution
+
+SafeMath reverts on overflow/underflow:
+
+```typescript
+// SAFE: Reverts on overflow
+const max = u256.Max;
+const result = SafeMath.add(max, u256.One);  // Reverts!
+
+// SAFE: Reverts on underflow
+const zero = u256.Zero;
+const result = SafeMath.sub(zero, u256.One);  // Reverts!
+```
+
+## Basic Operations
+
+### Addition
+
+```typescript
+const sum = SafeMath.add(a, b);
+
+// Reverts if a + b > u256.Max
+// Equivalent to Solidity: a + b (with checked arithmetic)
+```
+
+### Subtraction
+
+```typescript
+const diff = SafeMath.sub(a, b);
+
+// Reverts if b > a (would underflow)
+// Equivalent to Solidity: a - b (with checked arithmetic)
+```
+
+### Multiplication
+
+```typescript
+const product = SafeMath.mul(a, b);
+
+// Reverts if a * b > u256.Max
+// Equivalent to Solidity: a * b (with checked arithmetic)
+```
+
+### Division
+
+```typescript
+const quotient = SafeMath.div(a, b);
+
+// Reverts if b == 0
+// Equivalent to Solidity: a / b
+```
+
+### Modulo
+
+```typescript
+const remainder = SafeMath.mod(a, b);
+
+// Reverts if b == 0
+// Equivalent to Solidity: a % b
+```
+
+## Advanced Operations
+
+### Power (Exponentiation)
+
+```typescript
+const base = u256.fromU64(2);
+const exp = u256.fromU64(10);
+
+const result = SafeMath.pow(base, exp);  // 2^10 = 1024
+
+// Reverts on overflow
+// Uses efficient exponentiation by squaring (binary exponentiation)
+```
+
+### Power of 10
+
+```typescript
+// Optimized function for 10^n
+const million = SafeMath.pow10(6);  // 10^6 = 1,000,000
+const ether = SafeMath.pow10(18);   // 10^18
+
+// Maximum safe exponent is 77 (10^78 > u256.Max)
+// Reverts if exponent > 77
+```
+
+### Square Root
+
+```typescript
+const value = u256.fromU64(144);
+const sqrt = SafeMath.sqrt(value);  // 12
+
+// Uses Newton-Raphson method
+// Returns floor of square root
+```
+
+### Increment and Decrement
+
+```typescript
+const value = u256.fromU64(100);
+
+// Safe increment (reverts at u256.Max)
+const incremented = SafeMath.inc(value);  // 101
+
+// Safe decrement (reverts at 0)
+const decremented = SafeMath.dec(value);  // 99
+```
+
+## Shift Operations
+
+### Left Shift
+
+```typescript
+const shifted = SafeMath.shl(value, 10);  // value << 10
+
+// WARNING: Unlike other SafeMath operations, bit shifts do NOT throw on overflow!
+// Bits shifted beyond the type width are SILENTLY LOST
+// Shifts >= 256 return 0
+// Negative shifts return 0 (defensive behavior)
+```
+
+### Right Shift
+
+```typescript
+const shifted = SafeMath.shr(value, 5);  // value >> 5
+
+// Right shift is always safe (can't overflow)
+// Equivalent to division by 2^bits
+```
+
+### Bitwise Operations
+
+```typescript
+// AND operation
+const result1 = SafeMath.and(a, b);  // a & b
+
+// OR operation
+const result2 = SafeMath.or(a, b);   // a | b
+
+// XOR operation
+const result3 = SafeMath.xor(a, b);  // a ^ b
+
+// Check if even
+const isEven = SafeMath.isEven(value);  // (value & 1) == 0
+```
+
+## Comparison Operations
+
+```typescript
+// Use u256 built-in comparison methods (not SafeMath)
+if (u256.lt(a, b)) { }   // Less than
+if (u256.le(a, b)) { }   // Less than or equal
+if (u256.gt(a, b)) { }   // Greater than
+if (u256.ge(a, b)) { }   // Greater than or equal
+if (u256.eq(a, b)) { }   // Equal
+if (u256.ne(a, b)) { }   // Not equal
+
+// SafeMath provides min/max operations
+const smaller = SafeMath.min(a, b);
+const larger = SafeMath.max(a, b);
+```
+
+## Specialized Functions
+
+### Modular Multiplication
+
+```typescript
+// (a * b) % n without intermediate overflow
+const result = SafeMath.mulmod(a, b, n);
+
+// Useful for cryptographic operations
+```
+
+### Modular Inverse
+
+```typescript
+// Find x such that (a * x) % n == 1
+const inverse = SafeMath.modInverse(a, n);
+
+// Used in elliptic curve operations
+// Reverts if inverse doesn't exist
+```
+
+### Logarithm Operations
+
+```typescript
+// Approximate log2 (returns floor of log2(x))
+// Fast O(1) using bit length calculation
+const log2 = SafeMath.approximateLog2(value);  // Returns u256
+
+// Precise natural log (ln) scaled by 10^6 for fixed-point precision
+// Higher accuracy but more gas intensive
+const lnScaled = SafeMath.preciseLog(value);  // ln(x) * 1e6
+
+// Approximate natural log scaled by 10^6
+// Uses bit length * ln(2) approximation
+const approxLn = SafeMath.approxLog(value);  // Approximate ln(x) * 1e6
+
+// Bit length (number of bits needed to represent value)
+const bits = SafeMath.bitLength256(value);  // Returns u32
+```
+
+## Operations for Other Integer Sizes
+
+SafeMath provides variants for u128 and u64 for more efficient operations when u256 is not needed:
+
+### u128 Operations
+
+```typescript
+import { u128 } from '@btc-vision/as-bignum/assembly';
+
+const a = u128.fromU64(100);
+const b = u128.fromU64(50);
+
+SafeMath.add128(a, b);    // Addition
+SafeMath.sub128(a, b);    // Subtraction
+SafeMath.mul128(a, b);    // Multiplication
+SafeMath.div128(a, b);    // Division
+SafeMath.min128(a, b);    // Minimum
+SafeMath.max128(a, b);    // Maximum
+SafeMath.shl128(a, 10);   // Left shift
+```
+
+### u64 Operations
+
+```typescript
+const x: u64 = 100;
+const y: u64 = 50;
+
+SafeMath.add64(x, y);     // Addition
+SafeMath.sub64(x, y);     // Subtraction
+SafeMath.mul64(x, y);     // Multiplication
+SafeMath.div64(x, y);     // Division
+SafeMath.min64(x, y);     // Minimum
+SafeMath.max64(x, y);     // Maximum
+```
+
+## Solidity Comparison
+
+| Solidity | SafeMath |
+|----------|----------|
+| `a + b` (checked) | `SafeMath.add(a, b)` |
+| `a - b` (checked) | `SafeMath.sub(a, b)` |
+| `a * b` (checked) | `SafeMath.mul(a, b)` |
+| `a / b` | `SafeMath.div(a, b)` |
+| `a % b` | `SafeMath.mod(a, b)` |
+| `a ** b` | `SafeMath.pow(a, b)` |
+| `mulmod(a, b, n)` | `SafeMath.mulmod(a, b, n)` |
+
+## SafeMathI128
+
+For signed 128-bit arithmetic:
+
+```typescript
+import { SafeMathI128 } from '@btc-vision/btc-runtime/runtime';
+import { i128 } from '@btc-vision/as-bignum/assembly';
+
+const a = i128.from(-100);
+const b = i128.from(50);
+
+const sum = SafeMathI128.add(a, b);  // -50
+const diff = SafeMathI128.sub(a, b); // -150
+
+// Handles signed overflow correctly
+```
+
+## Common Patterns
+
+### Percentage Calculation
+
+```typescript
+// Calculate percentage: (amount * percentage) / 100
+public calculatePercentage(amount: u256, percentage: u256): u256 {
+    const numerator = SafeMath.mul(amount, percentage);
+    return SafeMath.div(numerator, u256.fromU64(100));
+}
+
+// Example: 10% of 1000
+const result = calculatePercentage(u256.fromU64(1000), u256.fromU64(10));  // 100
+```
+
+### Fee Deduction
+
+```typescript
+// Deduct fee and return remaining
+public deductFee(amount: u256, feePercent: u256): u256 {
+    const fee = SafeMath.div(SafeMath.mul(amount, feePercent), u256.fromU64(100));
+    return SafeMath.sub(amount, fee);
+}
+```
+
+### Balance Updates
+
+```typescript
+// Safe balance increase
+private addToBalance(addr: Address, amount: u256): void {
+    const current = this.balances.get(addr);
+    const newBalance = SafeMath.add(current, amount);
+    this.balances.set(addr, newBalance);
+}
+
+// Safe balance decrease
+private subFromBalance(addr: Address, amount: u256): void {
+    const current = this.balances.get(addr);
+    if (current < amount) {
+        throw new Revert('Insufficient balance');
+    }
+    const newBalance = SafeMath.sub(current, amount);
+    this.balances.set(addr, newBalance);
+}
+```
+
+### Supply Cap Enforcement
+
+```typescript
+public mint(to: Address, amount: u256): void {
+    const currentSupply = this.totalSupply.value;
+    const maxSupply = this.maxSupply.value;
+
+    // Check supply cap
+    const newSupply = SafeMath.add(currentSupply, amount);
+    if (newSupply > maxSupply) {
+        throw new Revert('Exceeds max supply');
+    }
+
+    this.totalSupply.value = newSupply;
+    this.addToBalance(to, amount);
+}
+```
+
+## Edge Cases
+
+### Division by Zero
+
+```typescript
+// Always reverts
+SafeMath.div(u256.fromU64(100), u256.Zero);  // Reverts!
+SafeMath.mod(u256.fromU64(100), u256.Zero);  // Reverts!
+```
+
+### Power Edge Cases
+
+```typescript
+// 0^0 = 1 (mathematical convention)
+SafeMath.pow(u256.Zero, u256.Zero);  // Returns 1
+
+// n^0 = 1
+SafeMath.pow(u256.fromU64(5), u256.Zero);  // Returns 1
+
+// 0^n = 0 (for n > 0)
+SafeMath.pow(u256.Zero, u256.fromU64(5));  // Returns 0
+
+// 1^n = 1
+SafeMath.pow(u256.One, u256.fromU64(1000));  // Returns 1
+```
+
+### Maximum Values
+
+```typescript
+// Near max value operations
+const nearMax = SafeMath.sub(u256.Max, u256.fromU64(10));
+
+SafeMath.add(nearMax, u256.fromU64(5));   // OK: 5 from max
+SafeMath.add(nearMax, u256.fromU64(15));  // Reverts: would overflow
+```
+
+## Best Practices
+
+### 1. Always Use SafeMath
+
+```typescript
+// WRONG
+const sum = a + b;
+const diff = a - b;
+
+// CORRECT
+const sum = SafeMath.add(a, b);
+const diff = SafeMath.sub(a, b);
+```
+
+### 2. Validate Before Division
+
+```typescript
+// Explicit zero check for better error messages
+public divide(a: u256, b: u256): u256 {
+    if (b.isZero()) {
+        throw new Revert('Division by zero');
+    }
+    return SafeMath.div(a, b);
+}
+```
+
+### 3. Order Operations to Minimize Overflow
+
+```typescript
+// RISKY: Large intermediate value
+const result = SafeMath.div(SafeMath.mul(largeA, largeB), c);
+
+// BETTER: Divide first if possible
+const result = SafeMath.mul(SafeMath.div(largeA, c), largeB);
+
+// BEST: Use muldiv for multiplication then division
+const result = u128.muldiv(largeA, largeB, c);
+```
+
+---
+
+**Navigation:**
+- Previous: [Address](./address.md)
+- Next: [Calldata](./calldata.md)

package/package.json

@@ -1,36 +1,46 @@
 {
     "name": "@btc-vision/btc-runtime",
-    "version": "1.10.10",
-    "description": "Bitcoin Smart Contract Runtime",
+    "version": "1.10.11",
+    "description": "Bitcoin L1 Smart Contract Runtime for OPNet. Build decentralized applications on Bitcoin using AssemblyScript and WebAssembly. Fully audited.",
     "main": "btc/index.ts",
-    "scripts": {
-        "test": "asp --config as-pect.config.js --verbose --no-logo",
-        "test:ci": "asp --config as-pect.config.js --summary --no-logo"
-    },
     "types": "btc/index.ts",
+    "author": "OPNet <support@opnet.org>",
+    "license": "Apache-2.0",
+    "homepage": "https://opnet.org",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/btc-vision/btc-runtime.git"
+    },
+    "bugs": {
+        "url": "https://github.com/btc-vision/btc-runtime/issues"
+    },
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/btc-vision"
+    },
     "keywords": [
         "bitcoin",
-        "smart",
-        "contract",
+        "smart-contracts",
+        "blockchain",
         "runtime",
         "opnet",
-        "OP_NET"
+        "OP_NET",
+        "OP20",
+        "OP721",
+        "wasm",
+        "webassembly",
+        "assemblyscript",
+        "defi",
+        "tokens",
+        "nft",
+        "l1",
+        "layer1",
+        "deterministic",
+        "quantum-resistant"
     ],
-    "homepage": "https://opnet.org",
-    "author": "BlobMaster41",
-    "license": "MIT",
-    "devDependencies": {
-        "@btc-vision/as-covers-assembly": "^0.4.4",
-        "@btc-vision/as-covers-transform": "^0.4.4",
-        "@btc-vision/as-pect-assembly": "^8.2.0",
-        "@btc-vision/as-pect-cli": "^8.2.0",
-        "@btc-vision/as-pect-transform": "^8.2.0",
-        "@types/node": "^24.10.1",
-        "assemblyscript": "^0.28.9"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/btc-vision/btc-runtime"
+    "scripts": {
+        "test": "asp --config as-pect.config.js --verbose --no-logo",
+        "test:ci": "asp --config as-pect.config.js --summary --no-logo"
     },
     "type": "module",
     "files": [
@@ -40,16 +50,31 @@
         "runtime/**/*.ts",
         "!**/*.js.map",
         "!**/*.tsbuildinfo",
-        "test/*.ts"
+        "README.md",
+        "SECURITY.md",
+        "LICENSE",
+        "docs"
     ],
+    "engines": {
+        "node": ">=22.0.0"
+    },
     "dependencies": {
         "@assemblyscript/loader": "^0.28.9",
-        "@btc-vision/as-bignum": "^0.0.6",
+        "@btc-vision/as-bignum": "^0.0.7",
         "@btc-vision/opnet-transform": "^0.2.1",
         "@eslint/js": "9.39.1",
         "gulplog": "^2.2.0",
         "ts-node": "^10.9.2",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.46.3"
+    },
+    "devDependencies": {
+        "@btc-vision/as-covers-assembly": "^0.4.4",
+        "@btc-vision/as-covers-transform": "^0.4.4",
+        "@btc-vision/as-pect-assembly": "^8.2.0",
+        "@btc-vision/as-pect-cli": "^8.2.0",
+        "@btc-vision/as-pect-transform": "^8.2.0",
+        "@types/node": "^24.10.1",
+        "assemblyscript": "^0.28.9"
     }
 }

package/runtime/memory/MapOfMap.ts

@@ -1,5 +1,6 @@
 import { Address } from '../types/Address';
 import { Nested } from './Nested';
+import { Map } from '../generic/Map';
 
 @final
 export class MapOfMap<T> extends Map<Address, Nested<T>> {

package/LICENSE.md

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 [Orange Pill Labs Holding Ltd.]
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.