Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
Tolk provides a standard library or stdlib that includes commonly used functions.
## Compile-time calculations and embedding
Constant values can be embedded into a contract using dedicated functions.
### `address()`
The `address()` function embeds a constant address:
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const REFUND_ADDR = address("EQCRDM9h4k3UJdOePPuyX40mCgA4vxge5Dc5vjBR8djbEKC5")
```
### Compile-time string methods
Several methods operate on constant [string](/languages/tolk/types/strings) literals. They require constant inputs and are evaluated at compile time.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// calculates crc32 of a string
const crc32 = "some_str".crc32() // = 4013618352 = 0xEF3AF4B0
// calculates crc16 (XMODEM) of a string
const crc16 = "some_str".crc16() // = 53407 = 0xD09F
// calculates sha256 of a string and returns 256-bit integer
const hash = "some_crypto_key".sha256()
// calculates sha256 of a string and takes the first 32 bits
const minihash = "some_crypto_key".sha256_32()
// interprets an N-chars ascii string as a number in base 256
const base256 = "AB".toBase256() // = 16706 (65*256 + 66)
// a slice with 2 bytes: 16, 32 (constructed from hex)
const hexSlice = "1020".hexToSlice()
// a slice with 4 bytes: 97, 98, 99, 100
const rawSlice = "abcd".literalSlice()
```
### `ton()`
Calculates nanotoncoins at compile time.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const ONE_TON = ton("1"); // `coins`, value: 1000000000
fun calcCost() {
val cost = ton("0.05"); // `coins`, value: 50000000
return ONE_TON + cost;
}
```
## Common functions
All functions in this section are available everywhere. They are defined in `@stdlib/common.tolk`, which is auto-imported.
### Arrays
Array-related methods allow interacting with [`array`](/languages/tolk/types/tuples) — dynamically sized containers of up to 255 elements backed by TVM tuples.
#### Creating arrays
Use `[...]` to create arrays. See the [arrays](/languages/tolk/types/tuples#creating-arrays-with) page for details.
#### `array.push`, `array.get`, and other array methods
An IDE suggests available methods after a dot `.`:
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun demo() {
var nums: array = [];
nums.push(123);
return nums.get(0); // 123
}
```
#### `T.toTuple` and `T.fromTuple`
Packs an object from the stack into a tuple and converts it back. If a value occupies N stack slots, the resulting tuple has size N.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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(0) as int; // 1
}
```
### Mathematical primitives
These functions accept and return integers unless stated otherwise. All [integers](/languages/tolk/types/numbers) are 257-bit.
#### `min(x, y)`
Returns the minimum of two integers.
#### `max(x, y)`
Returns the maximum of two integers.
#### `minMax(x, y)`
Returns `(int, int)` – a tensor `(smallest, largest)`.
#### `abs(x)`
Returns 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 functions in this section are methods of the empty struct `contract`.
#### `contract.getAddress`
Returns `address` — the internal address of the current smart contract. It can be further parsed using `address.getWorkchain` and others.
#### `contract.getOriginalBalance`
Returns `coins` — the balance of the smart contract in nanotoncoins at the start of the [compute phase](/tvm/exit-codes#compute-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()`](/languages/tolk/features/contract-storage).
#### `contract.setData(cell)`
Sets the persistent contract storage. Typically, the argument is [`storageObject.toCell()`](/languages/tolk/features/contract-storage).
#### `contract.getCode`
Returns `cell` — the smart contract code stored in TVM [register `c7`](/tvm/registers).
#### `contract.setCodePostponed(newCodeCell)`
Creates an output action that updates the smart contract code after successful termination of the current execution.
### Global getters of the blockchain (environment) state
Most functions in this section are methods of the empty struct `blockchain`.
#### `blockchain.now`
Returns `int` — the 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](/foundations/config) with integer index `i`, or `null` if not exists.
#### `commitContractDataAndActions`
Commits the current state of TVM registers `c4` persistent data and `c5` actions, so the current execution is considered successful with these values even if an exception is thrown later during the compute phase.
### Signature checks, hashing, cryptography
Functions and methods for hashing, signature verification, 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 the data in a builder. Equivalent to converting the builder to a cell and hashing it, without creating a cell.
#### `slice.bitsHash`
Returns `uint256` — the SHA-256 hash of the data bits in a slice, excluding references. If the bit length is not divisible by eight, throws a cell underflow exception.
#### `isSignatureValid(hash, signatureSlice, publicKey)`
Verifies an Ed25519 signature. Checks `signatureSlice` against `hash` using `publicKey`, both of type `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 `isSignatureValid`, but accepts a `slice` instead of a precomputed 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 value.
Call `random.initialize` to make randomization 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.
Call `random.initialize` to make randomization 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)`
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
Can 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` includes the cell that contains the slice.
#### `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, equivalent to `cell.depth`.
#### `builder.depth`
Returns `int` — the depth of a builder, equivalent to `cell.depth`.
### Debug primitives
Only work for local TVM execution with debug–level verbosity.
#### `debug.print(anyVariable)`
Dumps a variable to the debug log.
#### `debug.printString(str)`
Dumps a string to the debug log.
#### `debug.dumpStack`
Dumps the stack, at most the top 255 values, and shows its depth.
### Slice primitives: parsing cells
`cell.beginParse()` converts a cell into a slice.
`slice.loadAddress` and other `loadXXX` methods are suggested by the IDE after a dot.
Prefer [automatic serialization](/languages/tolk/features/auto-serialization) over manual slice parsing.
### Builder primitives: constructing cells
`beginCell()` creates a builder.
`builder.storeAddress` and other `storeXXX` methods are suggested by the IDE after a dot.
`builder.endCell()` constructs a cell from the written data.
Prefer [automatic serialization](/languages/tolk/features/auto-serialization)
over manual builder construction.
### Address manipulation primitives
Methods for [`address` and `any_address`](/languages/tolk/types/address) are suggested by the IDE after a dot.
#### `address.fromWorkchainAndHash(wc, hash)`
A static method of `address` — constructs an internal address with a size of 267 bits from arguments.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun demo() {
val a = address.fromWorkchainAndHash(0, somehash);
a.getWorkchain() == BASECHAIN; // true
}
```
#### `address.getWorkchain`
Returns `int8` — the workchain from an [internal address](/foundations/addresses/formats).
#### `address.getWorkchainAndHash`
Returns `(int8, uint256)` — the workchain and hash from an internal address.
#### `address.calculateSameAddressInAnotherShard(options)`
Given an internal address A = `"aaaa...a"`, returns `"bbaa...a"`. The result consists of `D` bits from address B and `256 - D` bits from address A.
#### `createAddressNone`
Returns any\_address holding a slice `00`, which is two zero bits, at runtime. This value represents a none address.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun demo() {
val none = createAddressNone(); // it's `any_address`
none.isInternal(); // false
none.isNone(); // true
}
```
This is a rarely used `any_address`, not `address`. Use it only in combination with external addresses. For example, pass a `none` to `createExternalLogMessage`, which accepts `any_address`.
To represent [internal or none](/languages/tolk/types/address) , use `address?` and `null`.
#### `any_address.isNone`, `any_address.isInternal`, `any_address.isExternal`
Checks which specific blockchain address is contained in `any_address`.
#### `any_address.castToInternal`
Casts `any_address` to `address`, with a runtime check that the value is internal. To skip the check, use an [unsafe cast](/languages/tolk/types/type-checks-and-casts):
`addr = myAny as address`.
### Reserving Toncoin on the contract balance
The standard library provides several `RESERVE_MODE_XXX` constants for [reserve modes](/foundations/actions/reserve), as well as the following functions.
#### `reserveToncoinsOnBalance`
Creates an output action that reserves Toncoin on the contract balance.
#### `reserveExtraCurrenciesOnBalance`
Similar to `reserveToncoinsOnBalance`, but also accepts a dictionary `extraAmount`.
### Creating and sending messages
Stdlib provides several `SEND_MODE_XXX` constants for [sending modes](/foundations/messages/modes).
[Message cell composition](/languages/tolk/features/message-sending) is encapsulated by the `createMessage` function.
A low-level function, `sendRawMessage`, is also available, but its use is not recommended.
## Modules requiring explicit imports
In addition to the always-available functions from `common.tolk`, Tolk provides several modules that must be explicitly imported before use.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/strings"
```
[String](/languages/tolk/types/strings) utilities: `StringBuilder` for concatenation, `string.calculateLength`, `string.equalTo`, and other.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/reflection"
```
Compile-time reflection utilities. All functions are evaluated at compile time and can be used in general-purpose frameworks or for low-level tasks.
* `reflect.typeNameOf()` — human-readable type name of `T`.
* `reflect.typeNameOfObject(value)` — human-readable type name of any object.
* `reflect.stackSizeOf()` — number of stack slots type `T` occupies.
* `reflect.stackSizeOfObject(value)` — number of stack slots any object occupies.
* `reflect.serializationPrefixOf()` — serialization prefix or length of a struct.
* `reflect.estimateSerializationOf()` — returns `(minBits, maxBits, minRefs, maxRefs)`.
* `reflect.sourceLocation()` — returns `SourceLocation { lineNo, charNo, fileName }` of the call site. When used as a default parameter value, captures the caller's location.
* `reflect.sourceLocationAsString()` — returns a string `"fileName:lineNo:charNo"` at compile time. Being a parameter's default, it also calculated per call.
Example of using `sourceLocation`:
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun log(msg: string, loc: SourceLocation = reflect.sourceLocation()) {
debug.print(loc.lineNo);
}
fun demo() {
log("a"); // prints K — current line no
log("b"); // prints K+1
}
```
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/gas-payments"
```
Gas- and payment-related primitives. All functions are documented with detailed comments and can be explored in the IDE.
* `getGasConsumedAtTheMoment`
* `acceptExternalMessage`
* `setGasLimitToMaximum`
* `setGasLimit`
* `calculateGasFee`
* `calculateGasFeeWithoutFlatPrice`
* `calculateStorageFee`
* `calculateForwardFee`
* `calculateForwardFeeWithoutLumpPrice`
* `contract.getStorageDuePayment`
* `contract.getStoragePaidPayment`
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/exotic-cells"
```
Functions for loading and parsing [exotic cells](/foundations/serialization/cells), including library references.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/lisp-lists"
```
Lisp-style lists are represented as nested two-element tuples. For example, `[1, [2, [3, null]]]` represents the list `[1, 2, 3]`. They are rarely used in modern code.
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/tvm-dicts"
```
Low-level API for working with TVM dictionaries. Their use is not recommended; prefer [built-in maps](/languages/tolk/types/maps).
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "@stdlib/tvm-lowlevel"
```
Functions for working with TVM registers and the stack.
## Why are some functions `builtin`?
Many functions in `common.tolk` don't provide `asm` instructions:
```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
@pure
fun slice.loadInt(mutate self, len: int): int
builtin
```
This is done for [optimization](/languages/tolk/features/compiler-optimizations) purposes. The compiler generates different assembler code depending on the arguments. For example, if `len` is a constant value such as `32`, `loadUint` is translated to `32 LDU`. If `len` is a variable, it is taken from the stack and the `LDUX` instruction is emitted.
Another example, `builder.storeUint(1, 32).storeUint(2, 64)` is not translated into `32 STU` and `64 STU`. Instead, these calls are merged into a single `STSLICECONST`.
## How does the embedded stdlib work?
The stdlib is bundled with the compiler as the `tolk-stdlib/` directory and is discovered automatically. An import of the form `@stdlib/xxx` loads `{STDLIB_PATH}/xxx.tolk`.
The stdlib directory is discovered as follows:
1. The compiler searches predefined and relative paths. For example, when launched from a system-installed package such as `/usr/bin/tolk`, the stdlib is located at `/usr/share/ton/smartcont`. For custom installations, the `TOLK_STDLIB` environment variable can be set.
2. The WASM wrapper [tolk-js](https://github.com/ton-blockchain/tolk-js) also includes the stdlib, so it is already available 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 stdlib files.