# SafeMath API Reference

The `SafeMath` class provides overflow-safe arithmetic operations for `u256` values.

## Import

```typescript
import { SafeMath } from '@btc-vision/btc-runtime/runtime';
import { u256 } from '@btc-vision/as-bignum/assembly';
```

## Basic Operations

### add

Adds two u256 values with overflow checking.

```typescript
static add(a: u256, b: u256): u256
```

```typescript
const sum = SafeMath.add(u256.fromU64(100), u256.fromU64(50));  // 150
```

**Throws:** `Revert` if result overflows

### sub

Subtracts b from a with underflow checking.

```typescript
static sub(a: u256, b: u256): u256
```

```typescript
const diff = SafeMath.sub(u256.fromU64(100), u256.fromU64(30));  // 70
```

**Throws:** `Revert` if b > a (underflow)

### mul

Multiplies two u256 values with overflow checking.

```typescript
static mul(a: u256, b: u256): u256
```

```typescript
const product = SafeMath.mul(u256.fromU64(100), u256.fromU64(5));  // 500
```

**Throws:** `Revert` if result overflows

### div

Divides a by b.

```typescript
static div(a: u256, b: u256): u256
```

```typescript
const quotient = SafeMath.div(u256.fromU64(100), u256.fromU64(4));  // 25
```

**Throws:** `Revert` if b is zero

### mod

Returns remainder of a divided by b.

```typescript
static mod(a: u256, b: u256): u256
```

```typescript
const remainder = SafeMath.mod(u256.fromU64(100), u256.fromU64(30));  // 10
```

**Throws:** `Revert` if b is zero

## Advanced Operations

### pow

Raises base to power exponent using binary exponentiation.

```typescript
static pow(base: u256, exponent: u256): u256
```

```typescript
const power = SafeMath.pow(u256.fromU64(2), u256.fromU64(10));  // 1024
```

**Throws:** `Revert` on overflow

### pow10

Computes 10^exponent (optimized for base 10).

```typescript
static pow10(exponent: u8): u256
```

```typescript
const million = SafeMath.pow10(6);  // 1,000,000
```

**Throws:** `Revert` if exponent > 77 (would overflow)

### sqrt

Computes square root using Newton-Raphson method.

```typescript
static sqrt(a: u256): u256
```

```typescript
const root = SafeMath.sqrt(u256.fromU64(144));  // 12
```

### min

Returns smaller of two values.

```typescript
static min(a: u256, b: u256): u256
```

```typescript
const smaller = SafeMath.min(u256.fromU64(100), u256.fromU64(50));  // 50
```

### max

Returns larger of two values.

```typescript
static max(a: u256, b: u256): u256
```

```typescript
const larger = SafeMath.max(u256.fromU64(100), u256.fromU64(50));  // 100
```

### inc

Increments value by 1 with overflow protection.

```typescript
static inc(value: u256): u256
```

```typescript
const incremented = SafeMath.inc(u256.fromU64(100));  // 101
```

**Throws:** `Revert` if value equals u256.Max

### dec

Decrements value by 1 with underflow protection.

```typescript
static dec(value: u256): u256
```

```typescript
const decremented = SafeMath.dec(u256.fromU64(100));  // 99
```

**Throws:** `Revert` if value is zero

## Cryptographic Operations

### mulmod

Computes (a * b) % modulus without intermediate overflow.

```typescript
static mulmod(a: u256, b: u256, modulus: u256): u256
```

```typescript
// For cryptographic operations where intermediate product would overflow
const result = SafeMath.mulmod(largeA, largeB, prime);
```

**Use case:** Elliptic curve operations, modular arithmetic

### modInverse

Computes modular multiplicative inverse.

```typescript
static modInverse(a: u256, modulus: u256): u256
```

```typescript
// Find x such that (a * x) % modulus = 1
const inverse = SafeMath.modInverse(value, prime);
```

**Throws:** If inverse doesn't exist

## Logarithm Operations

### approximateLog2

Returns floor of base-2 logarithm (position of highest set bit).

```typescript
static approximateLog2(x: u256): u256
```

```typescript
const log = SafeMath.approximateLog2(u256.fromU64(1024));  // 10
const log2 = SafeMath.approximateLog2(u256.fromU64(1000)); // 9 (floor)
```

**Returns:** 0 for both input 0 and input 1

### preciseLog

Computes natural logarithm (ln) with high precision.

```typescript
static preciseLog(x: u256): u256
```

```typescript
// Returns ln(x) scaled by 10^6 for fixed-point precision
const lnScaled = SafeMath.preciseLog(u256.fromU64(10));  // ~2,302,585
```

**Returns:** ln(x) * 1,000,000

### approxLog

Computes approximate natural logarithm using bit length.

```typescript
static approxLog(x: u256): u256
```

```typescript
// Uses bitLength * ln(2) approximation, scaled by 10^6
const approxLn = SafeMath.approxLog(u256.fromU64(8));  // ~2,079,441 (3 * ln(2))
```

**Returns:** Approximate ln(x) * 1,000,000

### bitLength256

Returns number of bits needed to represent the value.

```typescript
static bitLength256(x: u256): u32
```

```typescript
const bits = SafeMath.bitLength256(u256.fromU64(255));  // 8
const bits2 = SafeMath.bitLength256(u256.fromU64(256)); // 9
```

## Bitwise Operations

### shl

Shifts left by specified bits.

```typescript
static shl(value: u256, shift: i32): u256
```

```typescript
const shifted = SafeMath.shl(u256.fromU64(1), 10);  // 1024
```

**Warning:** Unlike other SafeMath operations, bits shifted beyond type width are silently lost (no throw). Shifts >= 256 return 0.

### shl128

Shifts a u128 value left by specified bits.

```typescript
static shl128(value: u128, shift: i32): u128
```

**Warning:** Same behavior as shl - overflow bits are silently lost.

### shr

Shifts right by specified bits.

```typescript
static shr(value: u256, shift: i32): u256
```

```typescript
const shifted = SafeMath.shr(u256.fromU64(1024), 5);  // 32
```

### and

Performs bitwise AND.

```typescript
static and(a: u256, b: u256): u256
```

### or

Performs bitwise OR.

```typescript
static or(a: u256, b: u256): u256
```

### xor

Performs bitwise XOR.

```typescript
static xor(a: u256, b: u256): u256
```

### isEven

Checks if value is even.

```typescript
static isEven(a: u256): bool
```

```typescript
if (SafeMath.isEven(value)) {
    // Value is even
}
```

## Comparison Operations

SafeMath does not provide comparison methods. Use the built-in u256 methods instead:

```typescript
// Use u256 built-in comparison methods
u256.eq(a, b)   // Equal
u256.ne(a, b)   // Not equal
u256.lt(a, b)   // Less than
u256.le(a, b)   // Less than or equal
u256.gt(a, b)   // Greater than
u256.ge(a, b)   // Greater than or equal
```

### min

Returns the smaller of two u256 values.

```typescript
static min(a: u256, b: u256): u256
```

### max

Returns the larger of two u256 values.

```typescript
static max(a: u256, b: u256): u256
```

### 128-bit and 64-bit variants

```typescript
// u128 min/max
SafeMath.min128(a: u128, b: u128): u128
SafeMath.max128(a: u128, b: u128): u128

// u64 min/max
SafeMath.min64(a: u64, b: u64): u64
SafeMath.max64(a: u64, b: u64): u64
```

## u128 Operations

All u256 operations have u128 variants for better gas efficiency with smaller values:

```typescript
import { u128 } from '@btc-vision/as-bignum/assembly';

SafeMath.add128(a: u128, b: u128): u128    // Addition
SafeMath.sub128(a: u128, b: u128): u128    // Subtraction
SafeMath.mul128(a: u128, b: u128): u128    // Multiplication
SafeMath.div128(a: u128, b: u128): u128    // Division
SafeMath.min128(a: u128, b: u128): u128    // Minimum
SafeMath.max128(a: u128, b: u128): u128    // Maximum
SafeMath.shl128(value: u128, shift: i32): u128  // Left shift
```

## u64 Operations

Native u64 variants for optimal performance:

```typescript
SafeMath.add64(a: u64, b: u64): u64    // Addition
SafeMath.sub64(a: u64, b: u64): u64    // Subtraction
SafeMath.mul64(a: u64, b: u64): u64    // Multiplication
SafeMath.div64(a: u64, b: u64): u64    // Division
SafeMath.min64(a: u64, b: u64): u64    // Minimum
SafeMath.max64(a: u64, b: u64): u64    // Maximum
```

## SafeMathI128

For signed 128-bit operations (separate module):

```typescript
import { SafeMathI128 } from '@btc-vision/btc-runtime/runtime';
import { i128 } from '@btc-vision/as-bignum/assembly';
```

See the SafeMathI128 module for signed integer operations.

## Common Patterns

### Percentage Calculation

```typescript
// Calculate 5% fee
const FEE_PERCENT = u256.fromU64(5);
const HUNDRED = u256.fromU64(100);

function calculateFee(amount: u256): u256 {
    return SafeMath.div(SafeMath.mul(amount, FEE_PERCENT), HUNDRED);
}
```

### Basis Points

```typescript
// 100 basis points = 1%
const BPS = u256.fromU64(10000);

function applyBps(amount: u256, bps: u256): u256 {
    return SafeMath.div(SafeMath.mul(amount, bps), BPS);
}
```

### Fixed-Point Multiplication

```typescript
const PRECISION = u256.fromU64(1_000_000);  // 6 decimals

function mulFixed(a: u256, b: u256): u256 {
    return SafeMath.div(SafeMath.mul(a, b), PRECISION);
}
```

### Average Without Overflow

```typescript
function average(a: u256, b: u256): u256 {
    // (a + b) / 2 without overflow
    return SafeMath.add(
        SafeMath.shr(a, 1),
        SafeMath.add(
            SafeMath.shr(b, 1),
            SafeMath.mul(
                SafeMath.mod(a, u256.fromU64(2)),
                SafeMath.mod(b, u256.fromU64(2))
            )
        )
    );
}
```

## Error Handling

All SafeMath operations throw `Revert` on error:

```typescript
try {
    const result = SafeMath.div(amount, u256.Zero);
} catch (e) {
    // Division by zero caught
}
```

## 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)` |
| `Math.sqrt(a)` | `SafeMath.sqrt(a)` |
| `mulmod(a, b, m)` | `SafeMath.mulmod(a, b, m)` |

---

**Navigation:**
- Previous: [OP721 API](./op721.md)
- Next: [Storage API](./storage.md)