Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
Tolk provides many functions for everyday use, available out of the box.
They are called "standard library", or "stdlib".
## 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:
```tolk theme={null}
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.
```tolk theme={null}
// 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.
```tolk theme={null}
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](/languages/tolk/types/tuples)
(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:
```tolk theme={null}
fun demo() {
var t = createEmptyTuple();
t.push(123);
return t.get(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.
```tolk theme={null}
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); // 1
}
```
### Mathematical primitives
These functions accept and return integers unless stated otherwise.
All integers are 257-bit, see [numbers](/languages/tolk/types/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](/languages/tolk/features/contract-storage).
#### contract.setData(cell)
Sets the persistent contract storage. Typically, the argument is `storageObject.toCell()`.
See [contract storage](/languages/tolk/features/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\(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\(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](/languages/tolk/features/auto-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](/languages/tolk/features/auto-serialization) to manual working with builders.
### Address manipulation primitives
Methods for `address` and `any_address` (see [address types](/languages/tolk/types/address)) are suggested after a dot.
#### address.fromWorkchainAndHash(wc, hash)
A static method of `address` — constructs an internal address (267 bits) from arguments.
```tolk theme={null}
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".
```tolk theme={null}
fun demo() {
val none = createAddressNone(); // it's `any_address`
none.isInternal(); // false
none.isNone(); // true
}
```
#### 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](/languages/tolk/types/type-checks-and-casts): `addr = myAny as address`.
### Reserving Toncoins on contract's balance
Stdlib contains several constants `RESERVE_MODE_XXX` for [reserve modes](/foundations/actions/reserve).
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](/foundations/messages/modes).
Composing message cells is encapsulated with a power function `createMessage`, see [message sending](/languages/tolk/features/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.
```tolk theme={null}
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`
```tolk theme={null}
import "@stdlib/exotic-cells"
```
Functions for loading and parsing [exotic cells](/foundations/serialization/cells) and particularly library references.
```tolk theme={null}
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.
```tolk theme={null}
import "@stdlib/tvm-dicts"
```
Low-level API for working with TVM dictionaries. Not recommended to use — enjoy [built-in maps](/languages/tolk/types/maps) instead.
```tolk theme={null}
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:
```tolk theme={null}
@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](/languages/tolk/features/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](https://github.com/ton-blockchain/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.