Standard library of Tolk

Tolk provides many functions for everyday use, available out of the box. They are called “standard library”, or “stdlib”.

An IDE auto-completes all functions. With Cmd+Click or Ctrl+Click, navigate to any function/method and read detailed comments right in an editor.

Compile-time calculations and embeds

Constant data can be embedded into a contract by dedicated functions.

address(“UQ…”)

A function address() embeds a constant address:

const REFUND_ADDR = address("EQCRDM9h4k3UJdOePPuyX40mCgA4vxge5Dc5vjBR8djbEKC5")

stringCrc32(“some_str”) and other

Several functions operate on strings. They all expect a constant literal and are evaluated to int at compile-time.

// calculates crc32 of a string
const crc32 = stringCrc32("some_str") // = 4013618352 = 0xEF3AF4B0

// calculates crc16 (XMODEM) of a string
const crc16 = stringCrc16("some_str") // = 53407 = 0xD09F

// calculates sha256 of a string and returns 256-bit integer
const hash = stringSha256("some_crypto_key")

// calculates sha256 of a string and takes the first 32 bits
const minihash = stringSha256_32("some_crypto_key")

// interprets an N-chars ascii string as a number in base 256
const base256 = stringToBase256("AB") // = 16706 (65*256 + 66)

ton(“0.05”)

Calculates “nanotoncoins” at compile-time.

const ONE_TON = ton("1");     // `coins`, value: 1000000000

fun calcCost() {
    val cost = ton("0.05");   // `coins`, value: 50000000
    return ONE_TON + cost;
}

Common functions, available always

All the functions in this section are visible everywhere. Actually, they are placed in @stdlib/common.tolk, which is auto-imported.

Tuples

Tuple-related functions allow interacting with tuple types (a dynamic container up to 255 elements).

createEmptyTuple

Creates a tuple with zero elements.

tuple.push, tuple.get, etc.

An IDE suggests all methods after a dot:

fun demo() {
    var t = createEmptyTuple();
    t.push(123);
    return t.get<int>(0);       // 123
}

T.toTuple and T.fromTuple

Packs any object from a stack into a tuple (and back). If a value occupies N stack slots, the resulting tuple has size N.

struct Point {
    x: int
    y: int
}

fun demo() {
    var p: Point = { x: 1, y: 2 };
    var t = p.toTuple();     // [ 1 2 ]
    p = Point.fromTuple(t);  // restored
    t.get<int>(0);           // 1
}

Mathematical primitives

These functions accept and return integers unless stated otherwise. All integers are 257-bit, see numbers.

min(x, y)

Computes the minimum of two integers.

max(x, y)

Computes the maximum of two integers.

minMax(x, y)

Returns (int, int) — a tensor (smallest, largest).

abs(x)

Computes the absolute value of an integer.

sign(x)

Returns the sign of an integer value:

• -1 if x < 0
• 0 if x == 0
• 1 if x > 0

divMod(x, y)

Returns (int, int) — the quotient and remainder of x / y.

Example: divMod(112, 3) = (37, 1).

modDiv(x, y)

Returns (int, int) — the remainder and quotient of x / y.

Example: modDiv(112, 3) = (1, 37).

mulDivFloor(x, y, z)

Computes multiple-then-divide: floor(x * y / z). The intermediate result is stored in a 513-bit integer to prevent precision loss.

mulDivRound(x, y, z)

Similar to mulDivFloor, but rounds the result: round(x * y / z).

mulDivCeil(x, y, z)

Similar to mulDivFloor, but ceils the result: ceil(x * y / z).

mulDivMod(x, y, z)

Returns (int, int) — the quotient and remainder of (x * y / z).

Example: mulDivMod(112, 3, 10) = (33, 6).

Global getters and setters of current contract state

All these functions are actually methods of the empty struct contract.

contract.getAddress

Returns address — the internal address of the current smart contract. It can be parsed further using address.getWorkchain and others.

contract.getOriginalBalance

Returns coins — the balance (in nanotoncoins) of the smart contract at the start of Computation Phase.

contract.getOriginalBalanceWithExtraCurrencies

Returns [coins, ExtraCurrenciesMap] — similar to contract.getOriginalBalance, but also returns extra currencies.

contract.getData

Returns cell — the persistent contract storage cell. Typically, its result is used as Storage.fromCell(). See contract storage.

contract.setData(cell)

Sets the persistent contract storage. Typically, the argument is storageObject.toCell(). See contract storage.

contract.getCode

Returns cell — the code of the smart contract from a TVM register c7.

contract.setCodePostponed(newCodeCell)

Creates an output action that would change this smart contract code after successful termination of the current run.

Global getters of the blockchain (environment) state

Most of these functions are methods of the empty struct blockchain.

blockchain.now

Returns int — current Unix timestamp (in seconds).

blockchain.logicalTime

Returns int — the logical time of the current transaction.

blockchain.currentBlockLogicalTime

Returns int — the starting logical time of the current block.

blockchain.configParam(i)

Returns cell? — the value of the global configuration parameter with integer index i, or null if not exists.

commitContractDataAndActions

Commits current state of TVM registers c4 (persistent data) and c5 (actions), so that the current execution is considered “successful” with the saved values even if an exception in Computation Phase is thrown later.

Signature checks, hashing, cryptography

Functions and methods for hashing, verifying, and randomization.

cell.hash

Returns uint256 — the representation hash of a cell. Useful for signing and checking signatures of arbitrary entities represented by a tree of cells.

slice.hash

Returns uint256 — the hash of data in a slice. The same as cell.hash for a cell containing data and references from this slice.

builder.hash

Returns uint256 — the hash of data in a builder. The same as “transform builder to cell + calc hash of that cell”, but without cell creation.

slice.bitsHash

Returns uint256 — sha256 of the data bits of a slice (without refs). If the bit length is not divisible by eight, throws a cell underflow exception.

isSignatureValid(hash, signatureSlice, publicKey)

Checks the Ed25519 - signatureSlice of a hash (an integer, usually computed as the hash of some data) using publicKey (also uint256). The signature must contain at least 512 data bits; only the first 512 bits are used. Returns bool.

isSliceSignatureValid(dataSlice, signatureSlice, publicKey)

Similar to the above, but accepts a slice instead of an already-calculated integer hash. If the bit length of data is not divisible by eight, throws a cell underflow exception.

random.uint256

Returns uint256 — a new pseudo-random number.

Ensure you’ve called random.initialize to make it unpredictable!

random.range(limit)

Returns int — a new pseudo-random integer z in the range 0..limit−1 (or limit..−1 if negative). More precisely, an unsigned random value x is generated, then z := x * limit / 2^256 is computed.

Ensure you’ve called random.initialize to make it unpredictable!

random.getSeed

Returns uint256 — the current random seed used to generate pseudo-random numbers.

random.setSeed(newSeed)

Sets the random seed to the provided value.

random.initializeBy(mixSeedWith)

Initializes (mixes) the random seed with the provided value.

random.initialize

Initializes the seed with current time to make randomization unpredictable.

Call this function once before using random.uint256 or random.range.

Size computation primitives

May be useful for computing storage fees of user-provided data.

cell.calculateSize(maxCells)

Returns (x, y, z, -1) or (null, null, null, 0). Recursively computes the count of distinct cells x, data bits y, and cell references z in a tree of cells. The total count of visited cells x cannot exceed non-negative maxCells; otherwise a zero flag is returned to indicate failure.

slice.calculateSize(maxCells)

Similar to cell.calculateSize, but accepting a slice instead of a cell. The returned value x does count the cell that contains the slice itself.

cell.calculateSizeStrict(maxCells)

A non-quiet version of cell.calculateSize that throws a cell overflow exception on failure.

slice.calculateSizeStrict(maxCells)

A non-quiet version of slice.calculateSize that throws a cell overflow exception on failure.

cell.depth

Returns int — the depth of a cell: 0 if no references, otherwise 1 + maximum of depths of all references.

slice.depth

Returns int — the depth of a slice, like cell.depth.

builder.depth

Returns int — the depth of a builder, like cell.depth.

sizeof<T>(anyVariable)

Returns int — the number of stack slots anyVariable occupies (works at compile-time).

Debug primitives

Only work for local TVM execution with debug level verbosity.

debug.print<T>(anyVariable)

Dump a variable to the debug log.

debug.printString(str)

Dump a string to the debug log.

debug.dumpStack

Dump the stack (at most the top 255 values) and show its depth.

Slice primitives: parsing cells

cell.beginParse() converts a cell into a slice.

slice.loadAddress and other loadXXX methods are automatically suggested after a dot.

Prefer automatic serialization to manual working with slices.

Builder primitives: constructing cells

beginCell() creates a builder.

builder.storeAddress and other storeXXX methods are automatically suggested after a dot.

builder.endCell() composes a cell from the data written.

Prefer automatic serialization to manual working with builders.

Address manipulation primitives

Methods for address and any_address (see address types) are suggested after a dot.

address.fromWorkchainAndHash(wc, hash)

A static method of address — constructs an internal address (267 bits) from arguments.

fun demo() {
    val a = address.fromWorkchainAndHash(0, somehash);
    a.getWorkchain() == BASECHAIN;   // true
}

address.getWorkchain

Returns int8 — workchain from a standard (internal) address.

address.getWorkchainAndHash

Returns (int8, uint256) — workchain and hash from a standard (internal) address.

address.calculateSameAddressInAnotherShard(options)

Given an internal address A=“aaaa…a” returns “bbaa…a” (D bits from address B, 256-D from A).

createAddressNone

Returns any_address — holding a slice ‘00’ (two zero bits) at runtime. It means “none address”.

fun demo() {
    val none = createAddressNone();  // it's `any_address`
    none.isInternal();      // false
    none.isNone();          // true
}

It's a rarely used `any_address`, NOT `address`

Use it in combination with external addresses only. E.g., pass “none” to createExternalLogMessage, which accepts any_address.

To represent “internal or none”, use address? (nullable) and null accordingly. See address.

any_address.isNone / isInternal / isExternal

Tests which specific blockchain address is contained in “any”.

any_address.castToInternal

Casts any_address to address checking that “any” is actually “internal”. To skip the runtime check, use an unsafe cast: addr = myAny as address.

Reserving Toncoins on contract’s balance

Stdlib contains several constants RESERVE_MODE_XXX for reserve modes. As well as a couple of functions:

reserveToncoinsOnBalance

Creates an output action which would reserve Toncoins on balance.

reserveExtraCurrenciesOnBalance

Similar to reserveToncoinsOnBalance, but also accepts a dictionary extraAmount.

Creating and sending messages

Stdlib contains several constants SEND_MODE_XXX for sending modes.

Composing message cells is encapsulated with a power function createMessage, see message sending.

For externals (createExternalLogMessage), follow the same link.

A low-level function sendRawMessage also exists, but its use is not recommended.

---

Modules requiring explicit imports

Besides “always-available” functions from common.tolk, Tolk has separate files that must be imported in order to be used.

import "@stdlib/gas-payments"

Gas- and payment-related primitives. All these functions have detailed comments, see them in an IDE.

• getGasConsumedAtTheMoment
• acceptExternalMessage
• setGasLimitToMaximum
• setGasLimit
• calculateGasFee
• calculateGasFeeWithoutFlatPrice
• calculateStorageFee
• calculateForwardFee
• calculateForwardFeeWithoutLumpPrice
• contract.getStorageDuePayment
• contract.getStoragePaidPayment

import "@stdlib/exotic-cells"

Functions for loading and parsing exotic cells and particularly library references.

import "@stdlib/lisp-lists"

Lisp-style lists are nested two-element tuples: [1, [2, [3, null]]] represents the list [1, 2, 3]. They are used rarely nowadays.

import "@stdlib/tvm-dicts"

Low-level API for working with TVM dictionaries. Not recommended to use — enjoy built-in maps instead.

import "@stdlib/tvm-lowlevel"

Functions for working with TVM registers and the stack.

Q: Why are some functions builtin?

Many functions in common.tolk don’t provide asm instructions:

@pure
fun slice.loadInt(mutate self, len: int): int
    builtin

This is done for optimization — the compiler generates different assembler code depending on arguments. For example, if len is constant (say, 32), loadUint is translated to 32 LDU, but if it’s a variable, it’s taken from a stack, and the LDUX instruction is emitted.

Another example — builder.storeUint(1, 32).storeUint(2, 64) is not translated to 32 STU and 64 STU. Instead, these calls are merged into a single STSLICECONST.

See compiler optimizations for details.

Appendix: How the embedded stdlib works

The stdlib is bundled with the compiler — it’s a folder tolk-stdlib/, automatically discovered. An import @stdlib/xxx actually loads {STLIB_PATH}/xxx.tolk.

Here is how the folder is discovered:

1. The compiler searches in predefined and relative paths.

   For example, when launched from a system-installed package, e.g., /usr/bin/tolk, the stdlib is located in /usr/share/ton/smartcont.

   For custom installations, the TOLK_STDLIB environment variable can be set. This is standard practice for compilers.

2. The WASM wrapper tolk-js also includes the stdlib, so it’s already installed when using blueprint.

3. IDE plugins automatically locate the stdlib to provide auto-completion.

   Blueprint installs tolk-js, creating the node_modules/@ton/tolk-js/ folder in the project structure.

   It contains common.tolk, tvm-dicts.tolk, and other files.