Reference
Math

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> 0 to the base base 1≥ 1. Results are rounded down (opens in a new tab). Passing a non-positive num value or a base less than 11 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 22, use the log2() function, as it's more gas-efficient.

log2

fun log2(num: Int): Int;

Similar to log(), but sets the base to 22.

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 22.

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 22, 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 22. 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 22.

💡

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 256256-bit unsigned Int hash using a public_key, represented by a 256256-bit unsigned Int too. The signature must contain at least 512512 bits of data, but only the first 512512 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 88, 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 256256-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 88, 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