Math

Various math helper functions.

min

fun min(x: Int, y: Int): Int;

Computes and returns the minimum (opens in a new tab) of two Int values x and y.

Usage examples:

min(1, 2);        // 1
min(2, 2);        // 2
min(007, 3);      // 3
min(0x45, 3_0_0); // 69, nice
//  ↑     ↑
//  69    300

max

fun max(x: Int, y: Int): Int;

Computes and returns the maximum (opens in a new tab) of two Int values x and y.

Usage examples:

max(1, 2);        // 2
max(2, 2);        // 2
max(007, 3);      // 7
max(0x45, 3_0_0); // 300
//  ↑     ↑
//  69    300

abs

fun abs(x: Int): Int

Computes and returns the absolute value (opens in a new tab) of the Int value x.

Usage examples:

abs(42);        // 42
abs(-42);       // 42
abs(-(-(-42))); // 42

log

fun log(num: Int, base: Int): Int;

Computes and returns the logarithm (opens in a new tab) of a number num $> 0$ to the base base $≥ 1$ . Results are rounded down (opens in a new tab). Passing a non-positive num value or a base less than $1$ throws an error with exit code 5: Integer out of expected range.

Usage examples:

log(1000, 10); // 3, as 10^3 is 1000
//  ↑     ↑             ↑       ↑
//  num   base          base    num
 
log(1001, 10);  // 3
log(999, 10);   // 2
try {
  log(-1000, 10); // throws exit code 5 because of the non-positive num
}
log(1024, 2);   // 10
try {
  log(1024, -2);  // throws exit code 5 because of the base less than 1
}

💡

Note, that if you only need to obtain logarithms to the base $2$ , use the log2() function, as it's more gas-efficient.

log2

fun log2(num: Int): Int;

Similar to log(), but sets the base to $2$ .

Usage example:

log2(1024); // 10, as 2^10 is 1024
//   ↑                ↑       ↑
//   num              base₂   num

💡

In order to reduce gas usage, prefer using this function over calling log() when you only need to obtain logarithms to the base $2$ .

pow

fun pow(base: Int, exp: Int): Int;

Computes and returns the exponentiation (opens in a new tab) involving two numbers: the base and the exponent (or power) exp. Exponent exp must be non-negative, otherwise an error with exit code 5 will be thrown: Integer out of expected range.

Note, that this function works both at run-time and at compile-time.

Usage example:

contract Example {
    // Persistent state variables
    p23: Int = pow(2, 3); // raises 2 to the 3rd power, which is 8
    one: Int = pow(5, 0); // raises 5 to the power 0, which always produces 1
                          // works at compile-time!
 
    // Internal message receiver, which accepts message ExtMsg
    receive() {
        pow(self.p23, self.one + 1); // 64, works at run-time too!
        pow(0, -1);                  // ERROR! Exit code 5: Integer out of expected range
    }
}

💡

Note, that if you only need to obtain powers of $2$ , use the pow2() function, as it's more gas-efficient.

💡

List of functions, that only work at compile-time: API Comptime.

pow2

fun pow2(exp: Int): Int;

Similar to pow(), but sets the base to $2$ . Works both at run-time and at compile-time.

Usage examples:

contract Example {
    // Persistent state variables
    p23: Int = pow2(3); // raises 2 to the 3rd power, which is 8
    one: Int = pow2(0); // raises 2 to the power 0, which always produces 1
                        // works at compile-time!
 
    // Internal message receiver, which accepts message ExtMsg
    receive() {
        pow2(self.one + 1); // 4, works at run-time too!
        pow2(-1);           // ERROR! Exit code 5: Integer out of expected range
    }
}

💡

In order to reduce gas usage, prefer using this function over calling pow() when you only need to obtain powers of $2$ .

💡

List of functions, that only work at compile-time: API Comptime.

checkSignature

fun checkSignature(hash: Int, signature: Slice, public_key: Int): Bool;

Checks the Ed25519 (opens in a new tab) signature of the $256$ -bit unsigned Int hash using a public_key, represented by a $256$ -bit unsigned Int too. The signature must contain at least $512$ bits of data, but only the first $512$ bits are used.

Returns true if the signature is valid, false otherwise.

Usage example:

message ExtMsg {
    signature: Slice;
    data: Cell;
}
 
contract Showcase {
    // Persistent state variables
    pub: Int as uint256; // public key as an 256-bit unsigned Int
 
    // Constructor function init(), where all the variables are initialized
    init(pub: Int) {
        self.pub = pub; // storing the public key upon contract initialization
    }
 
    // External message receiver, which accepts message ExtMsg
    external(msg: ExtMsg) {
        let hash: Int = beginCell().storeRef(msg.data).endCell().hash();
        let check: Bool = checkSignature(hash, msg.signature, self.pub);
        //                               ----  -------------  --------
        //                               ↑     ↑              ↑
        //                               |     |              public_key, stored in our contract
        //                               |     signature, obtained from the received message
        //                               hash, calculated using the data from the received message
        // ... follow-up logic ...
    }
}

checkDataSignature

fun checkDataSignature(data: Slice, signature: Slice, public_key: Int): Bool;

Checks the Ed25519 (opens in a new tab) signature of the data using a public_key, similar to checkSignature(). If the bit length of data is not divisible by $8$ , this functions throws an error with exit code 9: Cell underflow. Verification itself is being done indirectly: on a SHA-256 (opens in a new tab) hash of the data.

Returns true if the signature is valid, false otherwise.

Usage example:

let data: Slice = ...;
let signature: Slice = ...;
let publicKey: Int = ...;
 
let check: Bool = checkSignature(data, signature, publicKey);

sha256

fun sha256(data: Slice): Int;
fun sha256(data: String): Int;

Computes and returns the SHA-256 (opens in a new tab) hash as an $256$ -bit unsigned Int from a passed Slice or String data.

In case data is a String it should have a number of bits divisible by $8$ , and in case it's a Slice it must also have no references (i.e. only up to 1023 bits of data in total).

This function tries to resolve constant string values in compile-time whenever possible.

Usage examples:

sha256(beginCell().asSlice());
sha256("Hello, world!"); // will be resolved in compile-time
sha256(someVariableElsewhere); // will try to resolve at compile-time,
                               // and fallback to run-time evaluation

Random Strings and StringBuilders