common

Definitions

int

type int = builtin

int is the primitive 257-bit signed integer type.

bool

type bool = builtin

bool is a classic boolean type, which can hold only two values: true and false. At the TVM (TON virtual machine) level, it's an integer -1 or 0. Note: boolVar as int is possible, but remember, that true is -1, not 1!

cell

type cell = builtin

cell is a data structure, which can hold of up to 1023 bits (not bytes!) and up to 4 references (refs) to other cells. Both contract code and contract state are represented by a tree of cells.

slice

type slice = builtin

slice is a "cell opened for reading". When you call cell.beginParse, you get a slice, from which you can load binary data or high-level structures with T.fromSlice.

builder

type builder = builtin

builder is a "cell at the stage of creation". When you call beginCell, you get a builder, populate it with binary data or structures, and after builder.endCell, you get a cell.

continuation

type continuation = builtin

continuation is an "executable cell" representing executable TVM bytecode. They are used to manage execution flow in TVM programs and serve as the basis for function calls, exception handling, and control flow operations.

address

type address = builtin

address represents a standard (internal) address: workchain + hash. Addresses are comparable with == operator, they have methods like address.getWorkchain. In binary, it's 267 bits: '10' (addr_std) + '0' (no anycast) + workchain (int8) + hash (uint256). If you wish to describe "a potentially missing address", use address? (nullable). When set to null, address? will be serialized as '00' ("none address"): '00' (two zero bits) is a standard representation of a "missing" ("none") address. At the TVM level, addresses are slices, so it's possible to someAddress as slice. See docs

any_address

type any_address = builtin

any_address represents an internal/external/none address. You can test it with any_address.isExternal and similar methods. If you wish to describe "internal or none address", use address? (nullable) instead of "any". That's why any_address is used in practice extremely rarely. At the TVM level, addresses are slices, so it's possible to anyAddress as slice. See docs

never

type never = builtin

never is a special type that represents computations that never complete normally. A function that always throws an exception returns never, and the compiler knows that any code after it is unreachable.

intN

type intN = builtin

int8, int32, int222, etc. is "a fixed-width signed integer with N bits", N <= 257. Note: it's still int at runtime, you can assign "100500" to "int8": overflow will happen at serialization to a cell/builder, NOT at assignment.

uintN

type uintN = builtin

uint32, uint64, uint111, etc. is "a fixed-width unsigned integer with N bits", N <= 256. Note: it's still int at runtime, you can assign "100500" to "uint8": overflow will happen at serialization to a cell/builder, NOT at assignment.

coins

type coins = builtin

coins is a special primitive representing "nanotoncoins". One TON = 10^9 nanotoncoins. You can create coins with ton() function: ton("0.05") (actually, int 50000000 at runtime). Arithmetic operations on coins degrade to 257-bit int type.

varint16

type varint16 = builtin

varint16 is int at runtime, but serialized as "variadic signed int", -2^119 <= X < 2^119.

varuint16

type varuint16 = builtin

varuint16 is int at runtime, but serialized as "variadic unsigned int", 0 <= X < 2^120.

varint32

type varint32 = builtin

varint32 is int at runtime, but serialized as "variadic signed int", -2^247 <= X < 2^247.

varuint32

type varuint32 = builtin

varuint32 is int at runtime, but serialized as "variadic unsigned int", 0 <= X < 2^248.

string

type string = builtin

string represents text data stored as a cell in snake format. Snake format: data bytes, if more data exists — ref to next cell. Example of "abcd" in a single chunk: cell(data: "abcd") (32 bits inside) Example of "abcd" in two chunks: cell(data: "ab", ref: cell(data: "cd")) At the TVM level, string is a TVM CELL (1 stack slot).

bitsN

type bitsN = builtin

bits256, bits111, etc. is "a fixed-width slice with N bits and 0 refs", N <= 1023. Note: use as operator to convert slice to bitsN: someSlice as bits256 (manually writing as enforces you to think that this conversion is correct). Note: similar to intN, you can assign an invalid slice to bitsN, an error will be fired at serialization with T.toCell and similar, NOT at assignment.

bytesN

type bytesN = builtin

bytes8, bytes99, etc. is a convenient alias for bits(N*8)

map

struct map<K, V> {
    private tvmDict: dict
}

map<K, V> is "a map from a key K to a value V". Internally, it's an "optional cell": an empty map is null, a non-empty points to a root cell. Restrictions for K and V types:

• a key must be fixed-width; valid: int32, uint64, address, bits256, Point; invalid: int, coins
• a value must be serializable; valid: int32, coins, AnyStruct, Cell<AnyStruct>; invalid: int, builder

array

struct array<T> {
    private tvmTuple: tuple
}

array<T> is a container that stores from 0 to 255 elements of type T. Internally, it's a TVM tuple: the i-th element of a TVM tuple is the i-th element of an array. On a stack, an array occupies one stack slot regardless of its size. T can be any type (complex types are converted to sub-tuples under the hood). Work with array using its methods: arr.push(v), arr.get(i), etc.

unknown

type unknown = builtin

unknown represents one TVM primitive (one stack slot) with a kind unknown at compile-time. Any type T can be cast to unknown and back. If T is a TVM primitive, it's a type-only cast. Otherwise, an object is converted to a tuple, and is still stored as one stack slot.

var u1 = 5 as unknown;         // stack: "5"
u1 as int;                     // stack: "5"
var u2 = (10, 20) as unknown;  // stack: "[ 10 20 ]" (a TVM tuple)
u2 as (int, int);              // stack: "10 20" (two integers)

Be extremely careful using unknown, because the compiler is unable to validate the casts. An invalid cast from your side leads to stack corruption, resulting in undefined behavior.

tuple

type tuple = array<unknown>

tuple represents a TVM tuple. Essentially, it's "an array of unknown elements". Reading an individual element results in unknown, cast it to perform some actions:

// wrong:
var elem = someTuple.get(0);    // unknown
return elem + 123;              // error, can not apply `+`

// correct:
var elem = someTuple.get(0) as int;
return elem + 123;

lisp_list

struct lisp_list<T> {
    private tvmTuple: [T, lisp_list<T>] | null
}

lisp_list<T> is a set of nested 2-element TVM tuples: [1, [2, [3, null]]] represents a list [1, 2, 3]. Unlike array<T>, it can represent a list longer than 255 elements, but it has access only to the frontmost element (head).

To use lisp-style list, import the @stdlib/lisp-lists and call its methods.

var list: lisp_list<int> = [];
list.prependHead(1);
list.prependHead(2);
// list is now "2 1" (on a stack: [ 2 [ 1 null ] ])
list.getHead(); // 2

dict

type dict = cell?

Think of it as "a map with unknown keys and unknown values". Prefer using map<K, V>, not dict.

void

type void = builtin

void is the unit type representing the absence of a meaningful value. It's similar to both void and unit in other languages. Note: a function without return type means "auto infer", NOT "void".

Cell

struct Cell<T> {
    private readonly tvmCell: cell
}

Cell<T> represents a typed cell reference (as opposed to untyped cell).

struct ExtraData { ... }

struct MyStorage {
    ...
    extra:    Cell<ExtraData>    // TL-B `^ExtraData`
    optional: Cell<ExtraData>?   // TL-B `(Maybe ^ExtraData)`
    code:     cell               // TL-B `^Cell`
    data:     cell?              // TL-B `(Maybe ^Cell)`
}

Note, that st = MyStorage.fromSlice(s) does NOT deep-load any refs; st.extra is Cell<T>, not T; you should manually call st.extra.load() to get T (ExtraData in this example). Typed cells are comparable with == and !=, just like raw cell.

createEmptyTuple

@pure
@deprecated("use `[]` instead of `createEmptyTuple`")
fun createEmptyTuple(): array<unknown>

Creates a TVM tuple with zero elements. Deprecated since Tolk v1.3. Use [] to get an empty array instead:

// old way, deprecated:
var t = createEmptyTuple();

// new way, preferred:
var t = [];   // array<unknown>

// create an empty typed array:
var numbers: array<int> = [];

array<T>.push

@pure
fun array<T>.push(mutate self, value: T): void

Appends a value to array. If its size exceeds 255, throws a type check exception.

array<T>.first

@pure
fun array<T>.first(self): T

Returns the first element of a non-empty array.

array<T>.get

@pure
fun array<T>.get(self, index: int): T

Returns the i-th element of an array.

array<T>.set

@pure
fun array<T>.set(mutate self, value: T, index: int): void

Sets the i-th element of an array to a specified value (an element with this index must already exist, a new element is not created).

array<T>.size

@pure
fun array<T>.size(self): int

Returns the size of an array (elements count in it).

array<T>.last

@pure
fun array<T>.last(self): T

Returns the last element of a non-empty array.

array<T>.pop

@pure
fun array<T>.pop(mutate self): T

Pops and returns the last element of a non-empty array.

T.toTuple

@pure
fun T.toTuple(self): array<unknown>

Packs any object from a stack to a tuple. An object occupies N slots on a stack — the tuple will be of size N. It works identically as casting an object to unknown. Example:

struct Point { x: int, y: int }

var p: Point = { x: 1, y: 2 };
var t = p.toTuple();     // [ 1 2 ]
p = Point.fromTuple(t);  // back
t.get(0) as int;         // 1

It can be used for logging or low-level purposes like running a child VM or custom "equals". See T.fromTuple counterpart.

T.fromTuple

@pure
fun T.fromTuple(packedObject: array<unknown>): T

Unpacks a tuple back to an object on a stack. It works identically as casting unknown to an object. See T.toTuple for explanation and examples.

ton

@pure
fun ton(floatString: string): coins

Converts a constant floating-point string to nanotoncoins. Example: ton("0.05") is equal to 50000000. Note, that ton() requires a constant string; ton(some_var) is an error.

min

@pure
fun min(x: int, y: int): int

Computes the minimum of two integers.

max

@pure
fun max(x: int, y: int): int

Computes the maximum of two integers.

minMax

@pure
fun minMax(x: int, y: int): (int, int)

Sorts two integers. Example: minMax(x, y) with (x=20, y=10) and with (x=10, y=20) returns (10, 20)

abs

@pure
fun abs(x: int): int

Computes the absolute value of an integer.

sign

@pure
fun sign(x: int): int

Returns the sign of an integer: -1 if x < 0, 0 if x == 0, 1 if x > 0.

divMod

@pure
fun divMod(x: int, y: int): (int, int)

Computes the quotient and remainder of x / y. Example: divMod(112,3) = (37,1)

modDiv

@pure
fun modDiv(x: int, y: int): (int, int)

Computes the remainder and quotient of x / y. Example: modDiv(112,3) = (1,37)

mulDivFloor

@pure
fun mulDivFloor(x: int, y: int, z: int): int

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

mulDivRound

@pure
fun mulDivRound(x: int, y: int, z: int): int

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

mulDivCeil

@pure
fun mulDivCeil(x: int, y: int, z: int): int

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

mulDivMod

@pure
fun mulDivMod(x: int, y: int, z: int): (int, int)

Computes the quotient and remainder of (x * y / z). Example: mulDivMod(112,3,10) = (33,6)

contract

struct contract

contract is a built-in struct, it has only static methods. Example: contract.getCode() and other methods.

contract.getAddress

@pure
fun contract.getAddress(): address

Returns the internal address of the current smart contract. If necessary, it can be parsed further using address.getWorkchain and others.

contract.getOriginalBalance

@pure
fun contract.getOriginalBalance(): coins

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

contract.getOriginalBalanceWithExtraCurrencies

@pure
fun contract.getOriginalBalanceWithExtraCurrencies(): [coins, ExtraCurrenciesMap]

Same as contract.getOriginalBalance, but also returns the balance in extra currencies.

contract.getData

@pure
fun contract.getData(): cell

Returns the persistent contract storage cell. It can be parsed or modified with slice and builder primitives later.

contract.setData

fun contract.setData(c: cell): void

Sets the persistent contract storage.

contract.getCode

@pure
fun contract.getCode(): cell

Retrieves code of smart-contract from c7.

contract.setCodePostponed

fun contract.setCodePostponed(newCode: cell): void

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

MASTERCHAIN

const MASTERCHAIN = -1

BASECHAIN

const BASECHAIN = 0

blockchain

struct blockchain

blockchain is a built-in struct, it has only static methods. Example: blockchain.configParam(16) and other methods.

blockchain.now

@pure
fun blockchain.now(): int

Returns current Unix timestamp (in seconds).

blockchain.logicalTime

@pure
fun blockchain.logicalTime(): int

Returns the logical time of the current transaction.

blockchain.currentBlockLogicalTime

@pure
fun blockchain.currentBlockLogicalTime(): int

Returns the starting logical time of the current block.

blockchain.configParam

@pure
fun blockchain.configParam(x: int): cell?

Returns the value of the global configuration parameter with integer index i as a cell or null value.

commitContractDataAndActions

fun commitContractDataAndActions(): void

Commits current state of 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.

PackOptions

struct PackOptions {
    /// when a struct has a field of type `bits128` and similar (it's a slice under the hood),
    /// by default, compiler inserts runtime checks (get bits/refs count + compare with 128 + compare with 0);
    /// these checks ensure that serialized binary data will be correct, but they cost gas;
    /// however, if you guarantee that a slice is valid (for example, it comes from trusted sources),
    /// set this option to true to disable runtime checks;
    /// note: `int32` and other are always validated for overflow without any extra gas,
    /// so this flag controls only rarely used `bitsN` type
    skipBitsNValidation: bool = false
}

PackOptions allows you to control behavior of obj.toCell() and similar functions.

UnpackOptions

struct UnpackOptions {
    /// after finished reading all fields from a cell/slice, call [slice.assertEnd] to ensure no remaining data left;
    /// it's the default behavior, it ensures that you've fully described data you're reading with a struct;
    /// example: `struct Point { x: int8; y: int8 }`, input "0102" is ok, "0102FF" will throw excno 9;
    /// note: setting this to false does not decrease gas (DROP from a stack and ENDS cost the same);
    /// note: this option controls [T.fromCell] and [T.fromSlice], but is ignored by [slice.loadAny];
    /// note: `lazy` ignores this option, because it reads fields on demand or even skips them
    assertEndAfterReading: bool = true

    /// this excNo is thrown if a prefix doesn't match, e.g. for `struct (0x01) A` given input "88...";
    /// similarly, for a union type, this is thrown when none of the opcodes match;
    /// note: `lazy` ignores this option if you have `else` in `match` (you write custom logic there)
    throwIfOpcodeDoesNotMatch: int = 63
}

UnpackOptions allows you to control behavior of MyStruct.fromCell(c) and similar functions.

T.toCell

@pure
fun T.toCell(self, options: PackOptions = {}): Cell<T>

Convert anything to a cell (most likely, you'll call it for structures).

var st: MyStorage = { ... };
contract.setData(st.toCell());

Internally, a builder is created, all fields are serialized one by one, and a builder is flushed (beginCell() + serialize fields + endCell()).

T.fromCell

@pure
fun T.fromCell(packedCell: cell, options: UnpackOptions = {}): T

Parse anything from a cell (most likely, you'll call it for structures).

var st = MyStorage.fromCell(contract.getData());

Internally, a cell is unpacked to a slice, and that slice is parsed (packedCell.beginParse() + read from slice).

T.fromSlice

@pure
fun T.fromSlice(rawSlice: slice, options: UnpackOptions = {}): T

Parse anything from a slice (most likely, you'll call it for structures).

var msg = CounterIncrement.fromSlice(cs);

All fields are read from a slice immediately unless lazy. If a slice is corrupted, an exception is thrown (most likely, excode 9 "cell underflow"). Note, that a passed slice is NOT mutated, its internal pointer is NOT shifted. If you need to mutate it, like cs.loadInt(), consider calling cs.loadAny<CounterIncrement>().

slice.loadAny

@pure
fun slice.loadAny<T>(mutate self, options: UnpackOptions = {}): T

Parse anything from a slice, shifting its internal pointer. Similar to slice.loadUint() and others, but allows loading structures.

var st: MyStorage = cs.loadAny();     // or cs.loadAny<MyStorage>()

Similar to MyStorage.fromSlice(cs), but called as a slice method and mutates the slice. Note: options.assertEndAfterReading is ignored by this function, because it's actually intended to read data from the middle.

slice.skipAny

@pure
fun slice.skipAny<T>(mutate self, options: UnpackOptions = {}): self

Skip anything in a slice, shifting its internal pointer. Similar to slice.skipBits() and others, but allows skipping structures.

struct TwoInts { a: int32; b: int32; }
cs.skipAny<TwoInts>();    // skips 64 bits

builder.storeAny

@pure
fun builder.storeAny<T>(mutate self, v: T, options: PackOptions = {}): self

Store anything to a builder. Similar to builder.storeUint() and others, but allows storing structures.

var b = beginCell().storeUint(32).storeAny(msgBody).endCell();

T.forceLoadLazyObject

@pure
fun T.forceLoadLazyObject(self): slice

Forces an object created by lazy to load fully. Returns the remaining slice (having read all fields). Since options.assertEndAfterReading is ignored by lazy (fields are loaded on demand), this method can help you overcome this, if you really need to check input consistency.

val msg = lazy CounterMessage.fromSlice(s);
match (msg) {     // it's a lazy match, without creating a union on the stack
    CounterIncrement => {
        ...
        newCounter = curCounter + msg.incBy;   // `incBy` loaded here, on demand
        msg.forceLoadLazyObject().assertEnd()  // the purpose: get remainder
    }
}

Note: while slice.assertEnd may seem reasonable, these checks are avoided in practice, because the purpose of lazy is to auto-detect and load only necessary fields, not up to the end.

Cell<T>.load

@pure
fun Cell<T>.load(self, options: UnpackOptions = {}): T

Parse data from already loaded cell reference.

struct MyStorage { ... extra: Cell<ExtraData> }

var st = MyStorage.fromCell(contract.getData());
// st.extra is cell; if we need to unpack it, we do
var extra = st.extra.load();   // it's ExtraData, unpacked from loaded ref

Cell<T>.beginParse

@pure
fun Cell<T>.beginParse(self): slice

Converts a typed cell into a slice.

Cell<T>.hash

@pure
fun Cell<T>.hash(self): uint256

Returns hash of a typed cell, same as cell.hash.

RemainingBitsAndRefs

type RemainingBitsAndRefs = slice

RemainingBitsAndRefs is a special built-in type to get "all the rest" slice tail on reading.

struct JettonMessage {
    ... some fields
    forwardPayload: RemainingBitsAndRefs;
}

When you deserialize JettonMessage, forwardPayload contains "everything left after reading fields above".

createEmptyCell

@pure
fun createEmptyCell(): cell

Creates a cell with zero bits and references. Equivalent to beginCell().endCell().

createEmptySlice

@pure
fun createEmptySlice(): slice

Creates a slice with zero remaining bits and references. Equivalent to beginCell().endCell().beginParse().

stringCrc32

@pure
@deprecated("""use `"str".crc32()` instead of `stringCrc32("str")`""")
fun stringCrc32(constString: string): int

Compile-time function that calculates crc32 of a constant string.

const op = stringCrc32("some_str") // = 4013618352 = 0xEF3AF4B0

Note: stringCrc32(slice_var) does NOT work! It accepts a constant string and works at compile-time.

stringCrc16

@pure
@deprecated("""use `"str".crc16()` instead of `stringCrc16("str")`""")
fun stringCrc16(constString: string): int

Compile-time function that calculates crc16 (XMODEM) of a constant string.

const op = stringCrc16("some_str") // = 53407 = 0xD09F

Note: stringCrc16(slice_var) does NOT work! It accepts a constant string and works at compile-time.

stringSha256

@pure
@deprecated("""use `"str".sha256()` instead of `stringSha256("str")`""")
fun stringSha256(constString: string): int

Compile-time function that calculates sha256 of a constant string and returns 256-bit integer.

const hash = stringSha256("some_crypto_key")

Note: it's a compile-time function, stringSha256(slice_var) does NOT work! Use slice.bitsHash or slice.hash (declared below) to hash a slice without/with its refs at runtime.

stringSha256_32

@pure
@deprecated("""use `"str".sha256_32()` instead of `stringSha256_32("str")`""")
fun stringSha256_32(constString: string): int

Compile-time function that calculates sha256 of a constant string and takes the first 32 bits.

const minihash = stringSha256_32("some_crypto_key")

Note: stringSha256_32(slice_var) does NOT work! It accepts a constant string and works at compile-time.

stringToBase256

@pure
@deprecated("""use `"str".toBase256()` instead of `stringToBase256("str")`""")
fun stringToBase256(constString: string): int

Compile-time function that takes N-chars ascii string and interprets it as a number in base 256.

const value = stringToBase256("AB") // = 16706 (65*256 + 66)

Note: stringToBase256(slice_var) does NOT work! It accepts a constant string and works at compile-time.

cell.hash

@pure
fun cell.hash(self): uint256

Computes the representation hash of a cell and returns it as a 256-bit unsigned integer. Useful for signing and checking signatures of arbitrary entities represented by a tree of cells.

slice.hash

@pure
fun slice.hash(self): uint256

Computes the hash of a slice and returns it as a 256-bit unsigned integer. The result is the same as cell.hash for a cell containing data and references from this slice.

builder.hash

@pure
fun builder.hash(self): uint256

Computes the hash of a builder and returns it as a 256-bit unsigned integer. The same as "transform builder to cell + calc hash of that cell", but without cell creation.

slice.bitsHash

@pure
fun slice.bitsHash(self): uint256

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

cell.hashEqual

@pure
fun cell.hashEqual(self, another: cell): bool

Checks whether two cells are equal by comparing their hashes. Used internally by the compiler for operators == and != on cells.

isSignatureValid

@pure
fun isSignatureValid(hash: uint256, signature: slice, publicKey: uint256): bool

Checks the Ed25519-signature of a hash (uint256, usually computed as the hash of some data) using publicKey (also represented by a 256-bit unsigned integer). The signature must contain at least 512 data bits; only the first 512 bits are used. Note that CHKSIGNU creates a 256-bit slice with the hash and calls CHKSIGNS. That is, if parameter hash is computed as the hash of some data, these data are hashed twice, the second hashing occurring inside CHKSIGNS.

isSliceSignatureValid

@pure
fun isSliceSignatureValid(data: slice, signature: slice, publicKey: int): bool

Checks whether signature is a valid Ed25519-signature of the data portion of slice data using publicKey, similarly to isSignatureValid. If the bit length of data is not divisible by eight, throws a cell underflow exception. The verification of Ed25519 signatures is the standard one, with sha256 used to reduce data to the 256-bit number that is actually signed.

random

struct random

random is a built-in struct, it has only static methods. Example: random.uint256() and other methods.

random.uint256

fun random.uint256(): uint256

Generates a new pseudo-random unsigned 256-bit integer x. Ensure you've called random.initialize in advance to make it unpredictable!

random.range

fun random.range(limit: int): int

Generates a new pseudo-random integer z in the range 0..limit−1 (or limit..−1, if limit < 0). More precisely, an unsigned random value x is generated as in random; then z := x * limit / 2^256 is computed. Ensure you've called random.initialize in advance to make it unpredictable!

random.getSeed

@pure
fun random.getSeed(): uint256

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

random.setSeed

fun random.setSeed(seed: uint256): void

Sets the random seed to the provided value.

random.initializeBy

fun random.initializeBy(mixSeedWith: uint256): void

Initializes (mixes) random seed with the provided value.

random.initialize

fun random.initialize(): void

Mixes the random seed with this transaction's logical time (blockchain.logicalTime, asm LTIME). LTIME is the network ordering value for this transaction (not unixtime). Typically, call once before random.uint256 / random.range.

cell.calculateSize

@pure
fun cell.calculateSize(self, maxCells: int): (int, int, int, bool)

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, effectively returning the total storage used by this tree taking into account the identification of equal cells. The values of x, y, and z are computed by a depth-first traversal of this tree, with a hash table of visited cell hashes used to prevent visits of already-visited cells. The total count of visited cells x cannot exceed non-negative maxCells; otherwise the computation is aborted before visiting the (maxCells + 1)-st cell and a zero flag is returned to indicate failure.

slice.calculateSize

@pure
fun slice.calculateSize(self, maxCells: int): (int, int, int, bool)

Similar to cell.calculateSize, but accepting a slice instead of a cell. The returned value of x does not take into account the cell that contains the slice itself; however, its data bits and cell references are accounted for in y and z.

cell.calculateSizeStrict

fun cell.calculateSizeStrict(self, maxCells: int): (int, int, int)

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

slice.calculateSizeStrict

fun slice.calculateSizeStrict(self, maxCells: int): (int, int, int)

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

cell?.depth

@pure
fun cell?.depth(self): int

Returns the depth of a cell: 0 if no references, otherwise 1 + maximum of depths of all references. When called for null, returns 0.

slice.depth

@pure
fun slice.depth(self): int

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

builder.depth

@pure
fun builder.depth(self): int

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

debug

struct debug

debug is a built-in struct, it has only static methods. Example: debug.print(v) and other methods.

debug.print

fun debug.print<T>(x: T): void

Dump a variable to the debug log as a raw TVM stack value.

debug.printString

fun debug.printString(x: string): void

Dump a string to the debug log.

debug.dumpStack

fun debug.dumpStack(): void

Dumps the stack (at most the top 255 values) and shows the total stack depth.

createEmptyMap

@pure
@deprecated("use `[]` instead of `createEmptyMap`")
fun createEmptyMap<K, V>(): map<K, V>

Returns an empty typed map. It's essentially "PUSHNULL", since TVM NULL represents an empty map.

// old way, deprecated:
var m: map<int8, int32> = createEmptyMap();

// new way, preferred:
var m: map<int8, int32> = [];

createMapFromLowLevelDict

@pure
fun createMapFromLowLevelDict<K, V>(d: dict): map<K, V>

Converts a low-level TVM dictionary to a typed map. Actually, does nothing: accepts an "optional cell" and returns the same "optional cell", so if you specify key/value types incorrectly, it will fail later, at map.get and similar.

map<K, V>.toLowLevelDict

@pure
fun map<K, V>.toLowLevelDict(self): dict

Converts a high-level map to a low-level TVM dictionary. Actually, does nothing: returns the same "optional cell".

map<K, V>.isEmpty

@pure
fun map<K, V>.isEmpty(self): bool

Checks whether a map is empty (whether a cell is null).

Note: a check m == null will not work, use m.isEmpty().

map<K, V>.exists

@pure
fun map<K, V>.exists(self, key: K): bool

Checks whether a key exists in a map.

map<K, V>.get

@pure
fun map<K, V>.get(self, key: K): MapLookupResult<V>

Gets an element by key. If not found, does NOT throw, just returns isFound = false.

val r = m.get(123);
if (r.isFound) {
    r.loadValue()
}

map<K, V>.mustGet

@pure
fun map<K, V>.mustGet(self, key: K, throwIfNotFound: int = 9): V

Gets an element by key and throws if it doesn't exist.

map<K, V>.set

@pure
fun map<K, V>.set(mutate self, key: K, value: V): self

Sets an element by key.

m.set(k, 3);

Since it returns self, calls may be chained.

map<K, V>.setAndGetPrevious

@pure
fun map<K, V>.setAndGetPrevious(mutate self, key: K, value: V): MapLookupResult<V>

Sets an element and returns the previous element at that key. If no previous, isFound = false.

val prev = m.setAndGetPrevious(k, 3);
if (prev.isFound) {
    prev.loadValue()
}

map<K, V>.replaceIfExists

@pure
fun map<K, V>.replaceIfExists(mutate self, key: K, value: V): bool

Sets an element only if the key already exists. Returns whether an element was replaced.

map<K, V>.replaceAndGetPrevious

@pure
fun map<K, V>.replaceAndGetPrevious(mutate self, key: K, value: V): MapLookupResult<V>

Sets an element only if the key already exists and returns the previous element at that key.

map<K, V>.addIfNotExists

@pure
fun map<K, V>.addIfNotExists(mutate self, key: K, value: V): bool

Sets an element only if the key does not exist. Returns whether an element was added.

map<K, V>.addOrGetExisting

@pure
fun map<K, V>.addOrGetExisting(mutate self, key: K, value: V): MapLookupResult<V>

Sets an element only if the key does not exist. If exists, returns an old value.

map<K, V>.delete

@pure
fun map<K, V>.delete(mutate self, key: K): bool

Delete an element at the key. Returns whether an element was deleted.

map<K, V>.deleteAndGetDeleted

@pure
fun map<K, V>.deleteAndGetDeleted(mutate self, key: K): MapLookupResult<V>

Delete an element at the key and returns the deleted element. If not exists, isFound = false.

val prev = m.deleteAndGetDeleted(k);
if (prev.isFound) {
    prev.loadValue()
}

map<K, V>.findFirst

@pure
fun map<K, V>.findFirst(self): MapEntry<K, V>

Finds the first (minimal) element in a map. If key are integers, it's the minimal integer. If keys are addresses or complex structures (represented as slices), it's lexicographically smallest. For an empty map, just returns isFound = false. Useful for iterating over a map:

var r = m.findFirst();
while (r.isFound) {
    // ... use r.getKey() and r.loadValue()
    r = m.iterateNext(r)
}

map<K, V>.findLast

@pure
fun map<K, V>.findLast(self): MapEntry<K, V>

Finds the last (maximal) element in a map. If key are integers, it's the maximal integer. If keys are addresses or complex structures (represented as slices), it's lexicographically largest. For an empty map, just returns isFound = false. Useful for iterating over a map:

var r = m.findLast();
while (r.isFound) {
    // ... use r.getKey() and r.loadValue()
    r = m.iteratePrev(r)
}

map<K, V>.findKeyGreater

@pure
fun map<K, V>.findKeyGreater(self, pivotKey: K): MapEntry<K, V>

Finds an element with key > pivotKey. Don't forget to check isFound before using getKey() and loadValue() of the result.

map<K, V>.findKeyGreaterOrEqual

@pure
fun map<K, V>.findKeyGreaterOrEqual(self, pivotKey: K): MapEntry<K, V>

Finds an element with key >= pivotKey. Don't forget to check isFound before using getKey() and loadValue() of the result.

map<K, V>.findKeyLess

@pure
fun map<K, V>.findKeyLess(self, pivotKey: K): MapEntry<K, V>

Finds an element with key < pivotKey. Don't forget to check isFound before using getKey() and loadValue() of the result.

map<K, V>.findKeyLessOrEqual

@pure
fun map<K, V>.findKeyLessOrEqual(self, pivotKey: K): MapEntry<K, V>

Finds an element with key <= pivotKey. Don't forget to check isFound before using getKey() and loadValue() of the result.

map<K, V>.iterateNext

@pure
fun map<K, V>.iterateNext(self, current: MapEntry<K, V>): MapEntry<K, V>

Iterate over a map in ascending order.

// iterate for all keys >= 10 up to the end
var r = m.findKeyGreaterOrEqual(10);
while (r.isFound) {
    // ... use r.getKey() and r.loadValue()
    r = m.iterateNext(r)
}

map<K, V>.iteratePrev

@pure
fun map<K, V>.iteratePrev(self, current: MapEntry<K, V>): MapEntry<K, V>

Iterate over a map in reverse order.

// iterate for all keys < 10 down lo lowest
var r = m.findKeyLess(10);
while (r.isFound) {
    // ... use r.getKey() and r.loadValue()
    r = m.iteratePrev(r)
}

MapLookupResult

struct MapLookupResult<TValue> {
    private readonly rawSlice: slice?        // holds encoded value, present if isFound
    isFound: bool
}

MapLookupResult is a return value of map.get, map.setAndGetPrevious, and similar. Instead of returning a nullable value (that you'd check on null before usage), this struct is returned (and you check isFound before usage).

val r = m.get(key);
if (r.isFound) {
    r.loadValue()    // unpacks a returned slice
}

MapLookupResult<TValue>.loadValue

@pure
fun MapLookupResult<TValue>.loadValue(self): TValue

MapLookupResult<slice>.loadValue

@pure
fun MapLookupResult<slice>.loadValue(self): slice

MapEntry

struct MapEntry<K, V> {
    private readonly rawValue: slice?        // holds encoded value, present if isFound
    private readonly key: K
    isFound: bool
}

MapEntry is a return value of map.findFirst, map.iterateNext, and similar. You should check for isFound before calling getKey() and loadValue().

var r = m.findFirst();
while (r.isFound) {
    // ... use r.getKey() and r.loadValue()
    r = m.iterateNext(r)
}

MapEntry<K, V>.getKey

@pure
fun MapEntry<K, V>.getKey(self): K

MapEntry<K, V>.loadValue

@pure
fun MapEntry<K, V>.loadValue(self): V

MapEntry<K, slice>.loadValue

@pure
fun MapEntry<K, slice>.loadValue(self): slice

string.beginParse

@pure
fun string.beginParse(self): slice

Begins parsing the string content. Use for accessing raw bytes. Remember that a string may be a snake: not just "ab", but "a" + (ref "b").

string.literalSlice

@pure
fun string.literalSlice(self): slice

Compile-time method that returns raw bytes of a short string literal as a slice. Use this when you need a slice constant, not a string.

const s: slice = "hello".literalSlice()

Unlike beginParse(), it works at compile-time and is allowed in constant expressions.

string.crc32

@pure
fun string.crc32(self): int

Compile-time method that calculates crc32 of a constant string.

const op = "some_str".crc32()  // = 4013618352 = 0xEF3AF4B0

Note: this is a compile-time method, it works only with string literals.

string.crc16

@pure
fun string.crc16(self): int

Compile-time method that calculates crc16 (XMODEM) of a constant string.

const op = "some_str".crc16()  // = 53407 = 0xD09F

Note: this is a compile-time method, it works only with string literals.

string.sha256

@pure
fun string.sha256(self): int

Compile-time method that calculates sha256 of a constant string.

const hash = "some_crypto_key".sha256()

Note: this is a compile-time method, it works only with string literals.

string.sha256_32

@pure
fun string.sha256_32(self): int

Compile-time method that calculates sha256 of a constant string and takes the first 32 bits.

const minihash = "some_crypto_key".sha256_32()

Note: this is a compile-time method, it works only with string literals.

string.hexToSlice

@pure
fun string.hexToSlice(self): slice

Compile-time method that converts a constant hex-encoded string to a slice.

const v = "abcdef".hexToSlice()  // = slice with 3 bytes: 0xAB,0xCD,0xEF

Note: this is a compile-time method, it works only with string literals.

string.toBase256

@pure
fun string.toBase256(self): int

Compile-time method that takes N-chars ascii string and interprets it as a number in base 256.

const value = "AB".toBase256() // = 16706 (65*256 + 66)

Note: this is a compile-time method, it works only with string literals.

stringHexToSlice

@pure
@deprecated("""use `"hex".hexToSlice()` instead of `stringHexToSlice("hex")`""")
fun stringHexToSlice(constStringBytesHex: string): slice

Compile-time function that converts a constant hex-encoded string to N/2 bytes.

const v = stringHexToSlice("abcdef") // = slice with 3 bytes: 0xAB,0xCD,0xEF

Note: stringHexToSlice(slice_var) does NOT work! It accepts a constant string and works at compile-time.

cell.beginParse

@pure
fun cell.beginParse(self): slice

Converts a cell into a slice.

slice.assertEnd

fun slice.assertEnd(self): void

Checks if a slice is empty. If not, throws an exception with code 9.

slice.loadRef

@pure
fun slice.loadRef(mutate self): cell

Loads the next reference from a slice.

slice.preloadRef

@pure
fun slice.preloadRef(self): cell

Preloads the next reference from a slice.

slice.loadInt

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

Loads a signed len-bit integer from a slice.

slice.loadUint

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

Loads an unsigned len-bit integer from a slice.

slice.loadBits

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

Loads the first 0 ≤ len ≤ 1023 bits from a slice.

slice.preloadInt

@pure
fun slice.preloadInt(self, len: int): int

Preloads a signed len-bit integer from a slice.

slice.preloadUint

@pure
fun slice.preloadUint(self, len: int): int

Preloads an unsigned len-bit integer from a slice.

slice.preloadBits

@pure
fun slice.preloadBits(self, len: int): slice

Preloads the first 0 ≤ len ≤ 1023 bits from a slice.

slice.loadCoins

@pure
fun slice.loadCoins(mutate self): coins

Loads the serialized amount of nanotoncoins (any unsigned integer up to 2^120 - 1).

slice.loadBool

@pure
fun slice.loadBool(mutate self): bool

Loads a boolean from a slice.

slice.skipBits

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

Shifts a slice pointer to len bits forward.

slice.getFirstBits

@pure
fun slice.getFirstBits(self, len: int): slice

Returns the first 0 ≤ len ≤ 1023 bits of a slice.

slice.removeLastBits

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

Returns all but the last 0 ≤ len ≤ 1023 bits of a slice.

slice.getLastBits

@pure
fun slice.getLastBits(self, len: int): slice

Returns the last 0 ≤ len ≤ 1023 bits of a slice.

slice.getMiddleBits

@pure
fun slice.getMiddleBits(self, offset: int, len: int): slice

Returns 0 ≤ len ≤ 1023 bits of a slice starting from 0 ≤ offset ≤ 1023. (in other words, extracts a bit substring [offset, len) out of the slice)

slice.loadDict

@pure
fun slice.loadDict(mutate self): dict

Loads a dictionary (TL HashMapE structure, represented as TVM cell) from a slice.

slice.preloadDict

@pure
fun slice.preloadDict(self): dict

Preloads a dictionary (cell) from a slice.

slice.skipDict

@pure
fun slice.skipDict(mutate self): self

Skip a dictionary from a slice.

slice.loadMaybeRef

@pure
fun slice.loadMaybeRef(mutate self): cell?

Loads (Maybe ^Cell) from a slice. In other words, loads 1 bit: if it's true, loads the first ref, otherwise returns null.

slice.preloadMaybeRef

@pure
fun slice.preloadMaybeRef(self): cell?

Preloads (Maybe ^Cell) from a slice.

slice.skipMaybeRef

@pure
fun slice.skipMaybeRef(mutate self): self

Skips (Maybe ^Cell) in a slice.

slice.loadString

@pure
fun slice.loadString(mutate self): string

Loads a string from a slice. A string is a nested ref, so just load a ref.

beginCell

@pure
fun beginCell(): builder

Creates a new empty builder.

builder.endCell

@pure
fun builder.endCell(self): cell

Converts a builder into an ordinary cell.

builder.toSlice

@pure
fun builder.toSlice(self): slice

Converts a builder into a slice. The same as b.endCell().beginParse()

builder.storeRef

@pure
fun builder.storeRef(mutate self, c: cell): self

Stores a reference to a cell into a builder.

builder.storeInt

@pure
fun builder.storeInt(mutate self, x: int, len: int): self

Stores a signed len-bit integer into a builder (0 ≤ len ≤ 257).

builder.storeUint

@pure
fun builder.storeUint(mutate self, x: int, len: int): self

Stores an unsigned len-bit integer into a builder (0 ≤ len ≤ 256).

builder.storeSlice

@pure
fun builder.storeSlice(mutate self, s: slice): self

Stores a slice into a builder.

builder.storeString

@pure
fun builder.storeString(mutate self, s: string): self

Stores a string into a builder (it's a TVM cell, stored as a ref).

builder.storeAddress

@pure
fun builder.storeAddress(mutate self, addr: address): self

Stores an internal address into a builder.

builder.storeAddressOpt

@pure
fun builder.storeAddressOpt(mutate self, addrOrNull: address?): self

Stores an internal address or '00' if the parameter is null. '00' (two zero bits) is a standard representation of a "missing" ("none") address.

builder.storeAddressAny

@pure
fun builder.storeAddressAny(mutate self, addrAny: any_address): self

Stores "any address" (internal/external/none) into a builder.

builder.storeAddressNone

@pure
fun builder.storeAddressNone(mutate self): self

Stores a "none address": '00' (two zero bits) is TL addr_none$00.

builder.storeCoins

@pure
fun builder.storeCoins(mutate self, x: coins): self

Stores the amount of nanotoncoins into a builder.

builder.storeBool

@pure
fun builder.storeBool(mutate self, x: bool): self

Stores a boolean into a builder.

builder.storeDict

@pure
fun builder.storeDict(mutate self, c: dict): self

Stores a low-level TVM dictionary (optional cell) into a builder. In other words, if c is null, stores 0; if c is not null, stores 1 and a reference to c.

builder.storeMaybeRef

@pure
fun builder.storeMaybeRef(mutate self, c: cell?): self

Stores (Maybe ^Cell) into a builder. In other words, if c is null, stores 0; if c is not null, stores 1 and a reference to c.

builder.storeBuilder

@pure
fun builder.storeBuilder(mutate self, from: builder): self

Concatenates two builders.

slice.remainingRefsCount

@pure
fun slice.remainingRefsCount(self): int

Returns the number of references in a slice.

slice.remainingBitsCount

@pure
fun slice.remainingBitsCount(self): int

Returns the number of data bits in a slice.

slice.remainingBitsAndRefsCount

@pure
fun slice.remainingBitsAndRefsCount(self): (int, int)

Returns both the number of data bits and the number of references in a slice.

slice.isEmpty

@pure
fun slice.isEmpty(self): bool

Checks whether a slice is empty (i.e., contains no bits of data and no cell references).

slice.isEndOfBits

@pure
fun slice.isEndOfBits(self): bool

Checks whether a slice has no bits of data.

slice.isEndOfRefs

@pure
fun slice.isEndOfRefs(self): bool

Checks whether a slice has no references.

slice.bitsEqual

@pure
fun slice.bitsEqual(self, b: slice): bool

Checks whether data parts of two slices coincide.

builder.refsCount

@pure
fun builder.refsCount(self): int

Returns the number of cell references already stored in a builder.

builder.bitsCount

@pure
fun builder.bitsCount(self): int

Returns the number of data bits already stored in a builder.

address

@pure
fun address(stdAddress: string): address

Compile-time function that parses a valid contract address.

address("EQCRDM9h4k3UJdOePPuyX40mCgA4vxge5Dc5vjBR8djbEKC5")
address("0:527964d55cfa6eb731f4bfc07e9d025098097ef8505519e853986279bd8400d8")

Returns address, which can be stored in a struct, compared with ==, etc.

address.getWorkchainAndHash

@pure
fun address.getWorkchainAndHash(self): (int8, uint256)

Extracts workchain and hash from a standard (internal) address.

address.getWorkchain

@pure
fun address.getWorkchain(self): int8

Extracts workchain from a standard (internal) address.

createAddressNone

@pure
fun createAddressNone(): any_address

Creates a slice representing "none external address" (TL addr_none$00 — two zero bits). Note! Use this in combination with EXTERNAL addresses (e.g. for createExternalLogMessage). To represent "internal or none" address (which you most likely need to), use address? (nullable) and null accordingly.

any_address.isNone

@pure
fun any_address.isNone(self): bool

Returns if "any address" is "none". In TL/B, it's addr_none$00.

any_address.isInternal

@pure
fun any_address.isInternal(self): bool

Returns if "any address" is a standard (internal) address: workchain + hash. Then it can be safely cast to address. In TL/B, it's addr_std$10.

any_address.isExternal

@pure
fun any_address.isExternal(self): bool

Returns if "any address" is an external address, used to communication with the outside world. In TL/B, it's addr_extern$01.

any_address.getWorkchainAndHash

@pure
fun any_address.getWorkchainAndHash(self): (int8, uint256)

Extracts workchain and hash from a standard (internal) address. If the address is not internal, throws a cell deserialization exception.

any_address.getWorkchain

@pure
fun any_address.getWorkchain(self): int8

Extracts workchain from a standard (internal) address. If the address is not internal, throws a cell deserialization exception.

any_address.castToInternal

@pure
fun any_address.castToInternal(self): address

Casts any_address to address checking that "any" is actually "internal". E.g., addr = myAny.castToInternal() does the check and returns address. To skip the runtime check, use unsafe type casting instead: addr = myAny as address.

address.bitsEqual

@pure
@deprecated("use `senderAddress == ownerAddress`, not `senderAddress.bitsEqual(ownerAddress)`")
fun address.bitsEqual(self, b: address): bool

Checks whether two addresses are equal. Equivalent to a == b. Deprecated! Left for smoother transition from FunC, where you used slice everywhere. Use just a == b and a != b to compare addresses, don't use bitsEqual.

slice.loadAddress

@pure
fun slice.loadAddress(mutate self): address

Loads a standard (internal) address (containing workchain + hash). In TL/B, it's MsgAddressInt. If an address is incorrect or is not internal, throws a deserialization exception (code 9).

slice.loadAddressOpt

@pure
fun slice.loadAddressOpt(mutate self): address?

Loads a standard (internal) address or returns null if the input is "none address". If an address is incorrect or is not internal/none, throws a deserialization exception (code 9). '00' (two zero bits) is a standard representation of a "missing" ("none") address. As a result, you get either address (for internal) or null (for none).

slice.loadAddressAny