safe: add DEX math functions for DRY consolidation

Added functions from node/vms/dexvm/math:
- Div64: safe division with error on zero
- MulBig: multiply uint64s returning big.Int
- MulDiv64: (a * b) / c without overflow
- MulDivRoundUp64: ceiling division variant
- BigMulDiv: big.Int multiplication+division
- BigMulDivRoundUp: big.Int ceiling variant
- Clamp: generic ordered type clamping

Also added common big.Int values (bigZero, bigOne, maxUint64Big)
for performance in division operations.

safe/safe.go

@@ -7,14 +7,21 @@ package safe
 import (
 	"errors"
 	"math"
+	"math/big"
 	"math/bits"
 
 	"golang.org/x/exp/constraints"
 )
 
 var (
-	ErrOverflow  = errors.New("overflow")
-	ErrUnderflow = errors.New("underflow")
+	ErrOverflow       = errors.New("overflow")
+	ErrUnderflow      = errors.New("underflow")
+	ErrDivisionByZero = errors.New("division by zero")
+
+	// Common big.Int values for performance.
+	bigZero      = big.NewInt(0)
+	bigOne       = big.NewInt(1)
+	maxUint64Big = new(big.Int).SetUint64(math.MaxUint64)
 )
 
 // Add64 returns a + b, or error if overflow.
@@ -79,3 +86,85 @@ func Max(a, b uint64) uint64 {
 	}
 	return b
 }
+
+// Div64 returns a / b, or error if division by zero.
+func Div64(a, b uint64) (uint64, error) {
+	if b == 0 {
+		return 0, ErrDivisionByZero
+	}
+	return a / b, nil
+}
+
+// MulBig returns a * b as a big.Int (no overflow possible).
+func MulBig(a, b uint64) *big.Int {
+	x := new(big.Int).SetUint64(a)
+	y := new(big.Int).SetUint64(b)
+	return x.Mul(x, y)
+}
+
+// MulDiv64 returns (a * b) / c without intermediate overflow.
+// Returns error if c is zero or result overflows uint64.
+func MulDiv64(a, b, c uint64) (uint64, error) {
+	if c == 0 {
+		return 0, ErrDivisionByZero
+	}
+	product := MulBig(a, b)
+	divisor := new(big.Int).SetUint64(c)
+	result := new(big.Int).Div(product, divisor)
+	if result.Cmp(maxUint64Big) > 0 {
+		return 0, ErrOverflow
+	}
+	return result.Uint64(), nil
+}
+
+// MulDivRoundUp64 returns ceil((a * b) / c) without intermediate overflow.
+// Returns error if c is zero or result overflows uint64.
+func MulDivRoundUp64(a, b, c uint64) (uint64, error) {
+	if c == 0 {
+		return 0, ErrDivisionByZero
+	}
+	product := MulBig(a, b)
+	divisor := new(big.Int).SetUint64(c)
+	// (product + divisor - 1) / divisor for ceiling division
+	product.Add(product, divisor)
+	product.Sub(product, bigOne)
+	result := product.Div(product, divisor)
+	if result.Cmp(maxUint64Big) > 0 {
+		return 0, ErrOverflow
+	}
+	return result.Uint64(), nil
+}
+
+// BigMulDiv returns (a * b) / c for big.Int values.
+// Returns nil if c is zero.
+func BigMulDiv(a, b, c *big.Int) *big.Int {
+	if c.Cmp(bigZero) == 0 {
+		return nil
+	}
+	result := new(big.Int).Mul(a, b)
+	return result.Div(result, c)
+}
+
+// BigMulDivRoundUp returns ceil((a * b) / c) for big.Int values.
+// Returns nil if c is zero.
+func BigMulDivRoundUp(a, b, c *big.Int) *big.Int {
+	if c.Cmp(bigZero) == 0 {
+		return nil
+	}
+	result := new(big.Int).Mul(a, b)
+	// (result + c - 1) / c for ceiling division
+	result.Add(result, c)
+	result.Sub(result, bigOne)
+	return result.Div(result, c)
+}
+
+// Clamp returns value clamped to [minVal, maxVal].
+func Clamp[T constraints.Ordered](value, minVal, maxVal T) T {
+	if value < minVal {
+		return minVal
+	}
+	if value > maxVal {
+		return maxVal
+	}
+	return value
+}