Cells, Builders and Slices

Cell is a low-level primitive that represents data in TON Blockchain. Cells consist of $1023$ bits of data with up to $4$ references to other cells. They are read-only and immutable, and cannot have cyclic references.

Builder is an immutable primitive to construct cells, and Slice is a mutable primitive to parse them.

Note

Be very careful when constructing and parsing cells manually, and always make sure to document their desired layout: a strict order of values and types for serialization and deserialization.

To do so, advanced users are recommended to use Type Language - Binary (TL-B) schemas.

Additionally, every user is recommended to use structs and their methods, such as Struct.toCell() and Struct.fromCell(), instead of manually constructing and parsing cells, because structs and Messages are closest to being the living TL-B schemas of your contracts.

beginCell

fun beginCell(): Builder;

Creates a new empty Builder.

Usage example:

let fizz: Builder = beginCell();

emptyCell

fun emptyCell(): Cell;

Creates and returns an empty Cell (without data and references). An alias to beginCell().endCell().

Usage example:

let fizz: Cell = emptyCell();
let buzz: Cell = beginCell().endCell();

fizz == buzz; // true

emptySlice

fun emptySlice(): Slice;

Creates and returns an empty Slice (without data and references). An alias to emptyCell().asSlice().

Usage example:

let fizz: Slice = emptySlice();
let buzz: Slice = emptyCell().asSlice();

fizz == buzz; // true

Cell

A section to group all extension and extension mutation functions for the Cell type.

Cell.beginParse

extends fun beginParse(self: Cell): Slice;

Extension function for the Cell type.

Opens the Cell for parsing and returns it as a Slice.

Usage example:

let c: Cell = emptyCell();
let fizz: Slice = c.beginParse();

Cell.depth

Available since Tact 1.6

extends fun depth(self: Cell?): Int;

Extension function for the Cell type.

Computes and returns the Int depth of the Cell. Produces $0$ if the Cell has no references. Otherwise, it returns $1$ plus the maximum of the depths of the referenced cells. If self is null, returns $0$.

Usage example:

let c: Cell = beginCell().storeInt(42, 7).endCell();
let depth: Int = c.depth(); // 0

Cell.computeDataSize

500+ gas Available since Tact 1.6

extends fun computeDataSize(self: Cell?, maxCells: Int): DataSize;

Extension function for the Cell type.

Computes and returns the number of distinct cells, bits, and refs in the Cell by using a depth-first search (DFS) algorithm, recursively traversing each referenced cell. This function is computationally expensive and can consume a lot of gas. If self is null, returns a DataSize with all fields set to $0$.

The results are packed into a DataSize struct consisting of:

Field	Type	Description
cells	Int	The total number of nested cells, including the starting one
bits	Int	The total number of bits in all nested cells, including the starting one
refs	Int	The total number of refs in all nested cells, including the starting one

If the specified maxCells value is insufficient to traverse all cells including the starting one, an exception with exit code 8 is thrown: Cell overflow.

Attempts to specify a negative value for maxCells throw an exception with exit code 5: Integer out of expected range.

Usage example:

let c: Cell = beginCell().storeInt(42, 7).storeRef(emptyCell()).endCell();
try {
    let dataSize: DataSize = c.computeDataSize(2);
    dataSize.cells; // 2
    dataSize.bits;  // 7
    dataSize.refs;  // 1
} catch (exitCode) {
    // if maxCells was insufficient to traverse the cell
    // and all of its references, the exitCode here would be 8
}

Cell.hash

extends fun hash(self: Cell): Int;

Extension function for the Cell type.

Calculates and returns an Int value of the SHA-256 hash of the standard Cell representation of the given Cell.

Usage example:

let c: Cell = emptyCell();
let fizz: Int = c.hash();

Cell.asSlice

extends fun asSlice(self: Cell): Slice;

Extension function for the Cell type.

Converts the Cell to a Slice and returns it. An alias to self.beginParse().

Usage example:

let c: Cell = emptyCell();
let fizz: Slice = c.asSlice();

Builder

A section to group all extension and extension mutation functions for the Builder type.

Builder.endCell

500+ gas

extends fun endCell(self: Builder): Cell;

Extension function for the Builder type.

Converts a Builder into an ordinary Cell.

Usage example:

let b: Builder = beginCell();
let fizz: Cell = b.endCell();

Builder.storeUint

extends fun storeUint(self: Builder, value: Int, bits: Int): Builder;

Extension function for the Builder type.

Stores an unsigned bits-bit value into the copy of the Builder for 0 ≤ bits ≤ 256. Returns that copy.

Attempts to store a negative value or provide an insufficient or out-of-bounds bits number throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeUint(42, 6);

Builder.storeInt

extends fun storeInt(self: Builder, value: Int, bits: Int): Builder;

Extension function for the Builder type.

Stores a signed bits-bit value into the copy of the Builder for 0 ≤ bits ≤ 257. Returns that copy.

Attempts to provide an insufficient or out-of-bounds bits number throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeInt(42, 7);

Builder.storeBool

extends fun storeBool(self: Builder, value: Bool): Builder;

Extension function for the Builder type.

Stores a Bool value into the copy of the Builder. Writes 1 as a single bit if value is true, and writes 0 otherwise. Returns that copy of the Builder.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeBool(true);  // writes 1
let buzz: Builder = b.storeBool(false); // writes 0

Builder.storeBit

Available since Tact 1.5

extends fun storeBit(self: Builder, value: Bool): Builder;

Extension function for the Builder type.

An alias to Builder.storeBool().

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeBit(true);  // writes 1
let buzz: Builder = b.storeBit(false); // writes 0

Builder.storeBuilder

extends fun storeBuilder(self: Builder, other: Builder): Builder;

Extension function for the Builder type.

Appends all data from the other builder to the copy of the self builder. Returns that copy.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

fun example(op: Int, queryId: Int, payload: Builder) {
   let msgBody = beginCell().storeUint(op, 32).storeUint(queryId, 64);
   if (payload.bits() != 0) {
       msgBody = msgBody.storeBuilder(payload); // assignment is important here
   }
}

Builder.storeSlice

extends fun storeSlice(self: Builder, slice: Slice): Builder;

Extension function for the Builder type.

Stores a slice into a copy of the Builder. Returns that copy.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let s: Slice = emptyCell().asSlice();
let fizz: Builder = b.storeSlice(s);

Builder.storeCoins

extends fun storeCoins(self: Builder, value: Int): Builder;

Extension function for the Builder type.

Stores (serializes) an unsigned Int value in the range from $0$ to $2^{120}-1$ inclusive into a copy of the Builder. The serialization of value consists of a $4$-bit unsigned big-endian integer $l$, which is the smallest integer $l ≥ 0$ such that value $< 2^{8 * l}$, followed by an $8 * l$-bit unsigned big-endian representation of value. Returns that copy of the Builder.

Attempts to store an out-of-bounds value throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

This is the most common way of storing nanoToncoins.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeCoins(42);

Useful links:

Special coins serialization type

Builder.storeVarUint16

Available since Tact 1.6

extends fun storeVarUint16(self: Builder, value: Int): Builder;

Extension function for the Builder type.

An alias to Builder.storeCoins().

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeVarUint16(42);

Useful links:

Types of variable bit-width

Builder.storeVarInt16

Available since Tact 1.6

extends fun storeVarInt16(self: Builder, value: Int): Builder;

Extension function for the Builder type.

Similar to Builder.storeCoins(), but with a different value range: from $-2^{119}$ to $2^{119}-1$ inclusive.

Attempts to store an out-of-bounds value throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeVarInt16(-42);

Useful links:

Types of variable bit-width

Builder.storeVarUint32

Available since Tact 1.6

extends fun storeVarUint32(self: Builder, value: Int): Builder;

Extension function for the Builder type.

Stores (serializes) an unsigned Int value in the range from $0$ to $2^{248}-1$ inclusive into a copy of the Builder. The serialization of value consists of a $5$-bit unsigned big-endian integer $l$, which is the smallest integer $l ≥ 0$ such that value $< 2^{8 * l}$, followed by an $8 * l$-bit unsigned big-endian representation of value. Returns that copy of the Builder.

Attempts to store an out-of-bounds value throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeVarUint32(420000);

Useful links:

Types of variable bit-width

Builder.storeVarInt32

Available since Tact 1.6

extends fun storeVarInt32(self: Builder, value: Int): Builder;

Extension function for the Builder type.

Similar to Builder.storeVarUint32(), but with a different value range: from $-2^{247}$ to $2^{247} - 1$ inclusive.

Attempts to store an out-of-bounds value throw an exception with exit code 5: Integer out of expected range.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeVarInt32(-420000);

Useful links:

Types of variable bit-width

Builder.storeAddress

extends fun storeAddress(self: Builder, address: Address): Builder;

Extension function for the Builder type.

Stores the address in a copy of the Builder. Returns that copy.

Attempts to store an address into the Builder self, if self cannot fit it, throw an exception with exit code 8: Cell overflow.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeAddress(myAddress());

Builder.storeBasechainAddress

Available since Tact 1.6

extends fun storeBasechainAddress(self: Builder, address: BasechainAddress): Builder;

Extension function for the Builder type.

Stores the basechain address in the copy of the Builder and returns that copy.

If the address has a null hash, stores two zero bits 0b00 (addr_none). Otherwise, stores the full address with the three-bit prefix 0b100, followed by the 8-bit workchain ID set to 0 and the 256-bit hash.

Attempts to store more data than the Builder self can fit throw an exception with exit code 8: Cell overflow.

Usage example:

fun example() {
    let addr: BasechainAddress = newBasechainAddress(0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);
    let b: Builder = beginCell();
    let b2: Builder = b.storeBasechainAddress(addr);
}

Builder.storeRef

extends fun storeRef(self: Builder, cell: Cell): Builder;

Extension function for the Builder type.

Stores a reference cell into a copy of the Builder. Returns that copy.

As a single Cell can store up to $4$ references, attempts to store more throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b.storeRef(emptyCell());

Builder.storeMaybeRef

Available since Tact 1.5

extends fun storeMaybeRef(self: Builder, cell: Cell?): Builder;

Extension function for the Builder type.

If the cell is not null, stores $1$ as a single bit and then a reference to cell into a copy of the Builder. Returns that copy.

If the cell is null, stores only $0$ as a single bit into the copy of the Builder. Returns that copy.

As a single Cell can store up to $4$ references, attempts to store more throw an exception with exit code 8: Cell overflow.

Usage example:

let b: Builder = beginCell();
let fizz: Builder = b
    .storeMaybeRef(emptyCell()) // stores a single 1 bit, then an empty cell
    .storeMaybeRef(null);       // stores only a single 0 bit

Builder.refs

extends fun refs(self: Builder): Int;

Extension function for the Builder type.

Returns the number of cell references already stored in the Builder as an Int.

Usage example:

let b: Builder = beginCell();
let fizz: Int = b.refs(); // 0

Builder.bits

extends fun bits(self: Builder): Int;

Extension function for the Builder type.

Returns the number of data bits already stored in the Builder as an Int.

Usage example:

let b: Builder = beginCell();
let fizz: Int = b.bits(); // 0

Builder.depth

Available since Tact 1.6

extends fun depth(self: Builder): Int;

Extension function for the Builder type.

Computes and returns the Int depth of the Builder. Produces $0$ if the Builder has no references stored so far, otherwise $1$ plus the maximum depth of the referenced cells.

Usage example:

let b: Builder = beginCell().storeInt(42, 7);
let depth: Int = b.depth(); // 0

Builder.asSlice

extends fun asSlice(self: Builder): Slice;

Extension function for the Builder type.

Converts the Builder into a Slice and returns it. An alias to self.endCell().beginParse().

Usage example:

let b: Builder = beginCell();
let fizz: Slice = b.asSlice();

Builder.asCell

extends fun asCell(self: Builder): Cell;

Extension function for the Builder type.

Converts the Builder into a Cell and returns it. An alias to self.endCell().

Usage example:

let b: Builder = beginCell();
let fizz: Cell = b.asCell();

Slice

A section to group all extension and extension mutation functions for the Slice type.

Slice.loadUint

extends mutates fun loadUint(self: Slice, l: Int): Int;

Extension mutation function for the Slice type.

Loads and returns an unsigned l-bit Int from the Slice, for $0 ≤ l ≤ 256$.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeUint(42, 7).asSlice();
let fizz: Int = s.loadUint(7);

Slice.preloadUint

extends fun preloadUint(self: Slice, l: Int): Int;

Extension function for the Slice type.

Preloads and returns an unsigned l-bit Int from the Slice, for $0 ≤ l ≤ 256$. Doesn’t modify the Slice.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeUint(42, 7).asSlice();
let fizz: Int = s.preloadUint(7);

Slice.loadInt

extends mutates fun loadInt(self: Slice, l: Int): Int;

Extension mutation function for the Slice type.

Loads and returns a signed l-bit Int from the Slice, for $0 ≤ l ≤ 257$.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let fizz: Int = s.loadInt(7);

Slice.preloadInt

extends fun preloadInt(self: Slice, l: Int): Int;

Extension function for the Slice type.

Preloads and returns a signed l-bit Int from the Slice, for $0 ≤ l ≤ 257$. Doesn’t modify the Slice.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let fizz: Int = s.preloadInt(7);

Slice.loadBits

extends mutates fun loadBits(self: Slice, l: Int): Slice;

Extension mutation function for the Slice type.

Loads $0 ≤$ l $≤ 1023$ bits from the Slice and returns them as a separate Slice.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let fizz: Slice = s.loadBits(7);

Slice.preloadBits

extends fun preloadBits(self: Slice, l: Int): Slice;

Extension function for the Slice type.

Preloads $0 ≤$ l $≤ 1023$ bits from the Slice and returns them as a separate Slice. Doesn’t modify the original Slice.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let fizz: Slice = s.preloadBits(7);

Note

In order to reduce gas usage, prefer using this function over calling Slice.firstBits(), since the latter is less optimized.

Slice.skipBits

extends mutates fun skipBits(self: Slice, l: Int);

Extension mutation function for the Slice type.

Loads all but the first $0 ≤$ l $≤ 1023$ bits from the Slice.

Attempts to specify an out-of-bounds l value throw an exception with exit code 5: Integer out of expected range.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
s.skipBits(5);                   // all but first 5 bits
let fizz: Slice = s.loadBits(1); // load only 1 bit

Slice.skipLastBits

Available since Tact 1.6

extends fun skipLastBits(self: Slice, len: Int);

Extension function for the Slice type.

Preloads all but the last $0 ≤$ len $≤ 1023$ bits from the Slice.

Attempts to specify an out-of-bounds len value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let allButLastFive: Slice = s.skipLastBits(5); // all but last 5 bits,
                                               // i.e. only the first 2

Slice.loadBool

extends mutates fun loadBool(self: Slice): Bool;

Extension mutation function for the Slice type.

Loads a single bit and returns a Bool value from the Slice. Reads true if the loaded bit is equal to $1$, and reads false otherwise.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeBool(true).asSlice();
let fizz: Bool = s.loadBool(); // true

Slice.skipBool

Available since Tact 1.6.2

extends mutates fun skipBool(self: Slice);

Extension mutation function for the Slice type.

Skips a single bit from the Slice. Similar to discarding the return value of Slice.loadBool().

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell()
    .storeBool(true)
    .storeUint(42, 7)
    .asSlice();

s.skipBool();
let fizz: Int = s.loadUint(7); // 42

Slice.loadBit

Available since Tact 1.5

extends mutates fun loadBit(self: Slice): Bool;

Extension mutation function for the Slice type.

An alias to Slice.loadBool().

Usage example:

let s: Slice = beginCell().storeBit(true).asSlice();
let fizz: Bool = s.loadBit(); // true

Slice.loadCoins

extends mutates fun loadCoins(self: Slice): Int;

Extension mutation function for the Slice type.

Loads and returns a serialized unsigned Int value in the range from $0$ to $2^{120} - 1$ inclusive from the Slice. This value usually represents the amount in nanoToncoins.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeCoins(42).asSlice();
let fizz: Int = s.loadCoins(); // 42

Useful links:

Special coins serialization type

Slice.skipCoins

Available since Tact 1.6.2

extends mutates fun skipCoins(self: Slice);

Extension mutation function for the Slice type.

Skips a serialized unsigned Int value in the range from $0$ to $2^{120} - 1$ inclusive from the Slice. Similar to discarding the return value of Slice.loadCoins().

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell()
    .storeCoins(239)
    .storeUint(42, 7)
    .asSlice();

s.skipCoins();
let fizz: Int = s.loadUint(7); // 42

Slice.loadVarUint16

Available since Tact 1.6

extends mutates fun loadVarUint16(self: Slice): Int;

Extension mutation function for the Slice type.

An alias to Slice.loadCoins().

Usage example:

let s: Slice = beginCell().storeVarUint16(42).asSlice();
let fizz: Int = s.loadVarUint16(); // 42

Useful links:

Types of variable bit-width

Slice.skipVarUint16

Available since Tact 1.6.2

extends mutates fun skipVarUint16(self: Slice);

Extension mutation function for the Slice type.

Alias to Slice.skipCoins().

Usage example:

let s: Slice = beginCell()
    .storeVarUint16(239)
    .storeUint(42, 7)
    .asSlice();

s.skipVarUint16();
let fizz: Int = s.loadUint(7); // 42

Slice.loadVarInt16

Available since Tact 1.6

extends mutates fun loadVarInt16(self: Slice): Int;

Extension mutation function for the Slice type.

Similar to Slice.loadCoins(), but with a different value range: from $-2^{119}$ to $2^{119} - 1$ inclusive.

Attempts to load more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeVarInt16(-42).asSlice();
let fizz: Int = s.loadVarInt16(); // -42

Useful links:

Types of variable bit-width

Slice.skipVarInt16

Available since Tact 1.6.2

extends mutates fun skipVarInt16(self: Slice);

Extension mutation function for the Slice type.

Similar to Slice.skipCoins(), but with a different value range: from $-2^{119}$ to $2^{119} - 1$ inclusive.

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell()
    .storeVarInt16(-239)
    .storeUint(42, 7)
    .asSlice();

s.skipVarInt16();
let fizz: Int = s.loadUint(7); // 42

Slice.loadVarUint32

Available since Tact 1.6

extends mutates fun loadVarUint32(self: Slice): Int;

Loads and returns a serialized unsigned Int value in the range from $0$ to $2^{248} - 1$ inclusive from the Slice.

Attempts to load more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeVarUint32(420000).asSlice();
let fizz: Int = s.loadVarUint32(); // 420000

Useful links:

Types of variable bit-width

Slice.skipVarUint32

Available since Tact 1.6.2

extends mutates fun skipVarUint32(self: Slice);

Extension mutation function for the Slice type.

Skips a serialized unsigned Int value in the range from $0$ to $2^{248} - 1$ inclusive from the Slice. Similar to discarding the return value of Slice.loadVarUint32().

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell()
    .storeVarUint32(239)
    .storeUint(42, 7)
    .asSlice();

s.skipVarUint32();
let fizz: Int = s.loadUint(7); // 42

Slice.loadVarInt32

Available since Tact 1.6

extends mutates fun loadVarInt32(self: Slice): Int;

Similar to Slice.loadVarUint32(), but with a different value range: from $-2^{247}$ to $2^{247} - 1$ inclusive.

Attempts to load more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeVarInt32(-420000).asSlice();
let fizz: Int = s.loadVarInt32(); // -420000

Useful links:

Types of variable bit-width

Slice.skipVarInt32

Available since Tact 1.6.2

extends mutates fun skipVarInt32(self: Slice);

Extension mutation function for the Slice type.

Similar to Slice.skipVarUint32(), but with a different value range: from $-2^{247}$ to $2^{247} - 1$ inclusive.

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell()
    .storeVarInt32(-239)
    .storeUint(42, 7)
    .asSlice();

s.skipVarInt32();
let fizz: Int = s.loadUint(7); // 42

Slice.loadAddress

extends mutates fun loadAddress(self: Slice): Address;

Extension mutation function for the Slice type.

Loads and returns an Address from the Slice.

Attempts to load more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeAddress(myAddress()).asSlice();
let fizz: Address = s.loadAddress();

Slice.skipAddress

Available since Tact 1.6.2

extends mutates fun skipAddress(self: Slice);

Extension mutation function for the Slice type.

Skips an Address from the Slice.

Attempts to skip more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s1: Slice = beginCell()
    .storeAddress(myAddress())
    .storeUint(42, 32)
    .asSlice();

s1.skipAddress();
let fizz: Int = s1.loadUint(32); // 42

Slice.loadRef

extends mutates fun loadRef(self: Slice): Cell;

Extension mutation function for the Slice type.

Loads the next reference from the Slice as a Cell.

Attempts to load more data than Slice contains throw an exception with exit code 9: Cell underflow.

Usage examples:

let s1: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Cell = s1.loadRef();

let s2: Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(s1.asCell())
    .asSlice();
let ref1: Cell = s2.loadRef();
let ref2: Cell = s2.loadRef();
ref1 == ref2; // false

Slice.preloadRef

extends fun preloadRef(self: Slice): Cell;

Extension function for the Slice type.

Preloads the next reference from the Slice as a Cell. Doesn’t modify the original Slice.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage examples:

let s1: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Cell = s1.preloadRef(); // doesn't modify s1

let s2: Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(s1.asCell())
    .asSlice();

let ref1: Cell = s2.preloadRef();
let ref2: Cell = s2.preloadRef();
ref1 == ref2; // true

Slice.skipRef

Available since Tact 1.6.2

extends mutates fun skipRef(self: Slice);

Extension mutation function for the Slice type.

Skips the next reference from the Slice. Similar to discarding the return value of Slice.loadRef().

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s1: Slice = beginCell()
    .storeRef(emptyCell())
    .storeUint(42, 32)
    .asSlice();

s1.skipRef();
let fizz: Int = s1.loadUint(32); // 42

Slice.loadMaybeRef

Available since Tact 1.6

extends mutates fun loadMaybeRef(self: Slice): Cell?;

Extension mutation function for the Slice type.

Loads a single bit from the Slice: if it’s $1$, the referenced Cell is loaded and returned. If the loaded bit is $0$, nothing else is loaded and null is returned.

Attempts to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s = msg.asSlice();
let outActions = s.loadMaybeRef();

if (outActions != null) {
    let actions = outActions!!;
    // process actions
}

Slice.preloadMaybeRef

Available since Tact 1.6

extends fun preloadMaybeRef(self: Slice): Cell?;

Extension function for the Slice type.

Preloads a single bit from the Slice: if it’s $1$, the referenced Cell is preloaded and returned. If the preloaded bit is $0$, null is returned. Doesn’t modify the original Slice.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage examples:

let s1: Slice = beginCell().storeMaybeRef(emptyCell()).asSlice();
let fizz: Cell = s1.preloadMaybeRef(); // returns emptyCell() and doesn't modify s1

let s2: Slice = beginCell()
    .storeMaybeRef(null)
    .storeMaybeRef(s1.asCell())
    .asSlice();

let ref1: Cell = s2.preloadMaybeRef(); // returns null and doesn't modify s2
let ref2: Cell = s2.preloadMaybeRef(); // same effect
ref1 == null; // true
ref1 == ref2; // true

Slice.skipMaybeRef

Available since Tact 1.6.2

extends mutates fun skipMaybeRef(self: Slice);

Extension mutation function for the Slice type.

Skips Cell? from the Slice. Similar to discarding the return value of Slice.loadMaybeRef().

Attempts to skip more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s1: Slice = beginCell()
    .storeMaybeRef(emptyCell())
    .storeUint(42, 32)
    .asSlice();

s1.skipMaybeRef();
let fizz: Int = s1.loadUint(32); // 42

Slice.refs

extends fun refs(self: Slice): Int;

Extension function for the Slice type.

Returns the number of references in the Slice as an Int.

Usage example:

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Int = s.refs();

Slice.bits

extends fun bits(self: Slice): Int;

Extension function for the Slice type.

Returns the number of data bits in the Slice as an Int.

Usage example:

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Int = s.bits();

Slice.firstBits

Available since Tact 1.6

extends fun firstBits(self: Slice, len: Int): Slice;

Extension function for the Slice type.

Preloads the first $0 ≤$ len $≤ 1023$ bits from the Slice.

Attempts to specify an out-of-bounds len value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let firstFive: Slice = s.firstBits(5); // first 5 bits

Note

In order to reduce gas usage, prefer calling Slice.preloadBits() over using this function, since the former is more optimized.

Slice.lastBits

Available since Tact 1.6

extends fun lastBits(self: Slice, len: Int): Slice;

Extension function for the Slice type.

Preloads the last $0 ≤$ len $≤ 1023$ bits from the Slice.

Attempts to specify an out-of-bounds len value throw an exception with exit code 5: Integer out of expected range.

Attempts to preload more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let lastFive: Slice = s.lastBits(5); // last 5 bits

Slice.depth

Available since Tact 1.6

extends fun depth(self: Slice): Int;

Extension function for the Slice type.

Computes and returns the Int depth of the Slice. Produces $0$ if the Slice has no references. Otherwise, it returns $1$ plus the maximum of the depths of the referenced cells.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).asSlice();
let depth: Int = s.depth(); // 0

Slice.computeDataSize

500+ gas Available since Tact 1.6

extends fun computeDataSize(self: Slice, maxCells: Int): DataSize;

Extension function for the Slice type.

Similar to Cell.computeDataSize(), but does not take into account the cell that contains the Slice itself. However, it accounts for its bits and refs.

The results are packed into a DataSize struct consisting of:

Field	Type	Description
cells	Int	The total number of nested cells, including the starting one
bits	Int	The total number of bits in all nested cells, including the starting one
refs	Int	The total number of refs in all nested cells, including the starting one

If the specified maxCells value is insufficient to traverse all cells not including the starting one, an exception with exit code 8 is thrown: Cell overflow.

Attempts to specify a negative value for maxCells throw an exception with exit code 5: Integer out of expected range.

Usage example:

let s: Slice = beginCell().storeInt(42, 7).storeRef(emptyCell()).asSlice();
try {
    let dataSize: DataSize = s.computeDataSize(1);
    dataSize.cells; // 1
    dataSize.bits;  // 7
    dataSize.refs;  // 1
} catch (exitCode) {
    // if maxCells was insufficient to traverse the cell
    // and all of its references, the exitCode here would be 8
}

Slice.empty

extends fun empty(self: Slice): Bool;

Extension function for the Slice type.

Checks whether the Slice is empty (i.e., contains no bits of data and no cell references). Returns true if it is empty, false otherwise.

Usage example:

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Bool = s.empty();                     // false
let buzz: Bool = beginCell().asSlice().empty(); // true

Note

Unlike Slice.endParse(), this function does not throw any exceptions, even when the Slice is empty.

Slice.dataEmpty

extends fun dataEmpty(slice: Slice): Bool;

Extension function for the Slice type.

Checks whether the Slice has no bits of data. Returns true if it has no data, false otherwise.

Usage example:

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Bool = s.dataEmpty();  // true

let s2: Slice = beginCell().storeInt(42, 7).asSlice();
let buzz: Bool = s2.dataEmpty(); // false

Slice.refsEmpty

extends fun refsEmpty(slice: Slice): Bool;

Extension function for the Slice type.

Checks whether the Slice has no references. Returns true if it has no references, false otherwise.

Usage example:

let s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Bool = s.refsEmpty();                     // false
let buzz: Bool = beginCell().asSlice().refsEmpty(); // true

Slice.endParse

extends fun endParse(self: Slice);

Extension function for the Slice type.

Checks whether the Slice is empty (i.e., contains no bits of data and no cell references). If it is not, it throws an exception with exit code 9: Cell underflow.

Usage examples:

let emptyOne: Slice = emptySlice();
emptyOne.endParse(); // nothing, as it's empty

let paul: Slice = "Fear is the mind-killer".asSlice();
try {
    paul.endParse(); // throws exit code 9
}

Slice.hash

500+ gas

extends fun hash(self: Slice): Int;

Extension function for the Slice type.

Calculates and returns an Int value of the SHA-256 hash of the standard Cell representation of the given Slice.

Usage example:

let s: Slice = beginCell().asSlice();
let fizz: Int = s.hash();

Slice.hashData

Available since Tact 1.6

extends fun hashData(self: Slice): Int;

Extension function for the Slice type.

Calculates and returns an Int value of the SHA-256 hash of the data bits from the given Slice, which should have a number of bits divisible by 8.

Unlike sha256(), this function is gas-efficient and only hashes the data of the given Slice, i.e. up to 1023 bits, ignoring the refs.

Attempts to specify a Slice with a number of bits not divisible by 8 throw an exception with exit code 9: Cell underflow.

Usage examples:

// Base64-encoded BoC with "Hello, World!"
let short: Slice = slice("te6cckEBAQEADgAAGEhlbGxvIHdvcmxkIXgtxbw=");

// It's enough to only take the hash of the data
sha256(short) == short.hashData(); // true

// But if we construct a slice larger than 1023 bits with all refs combined,
// we must use sha256() or we'll get skewed results or even collisions

let tmp: Builder = beginCell();
repeat (127) { tmp = tmp.storeUint(69, 8) } // storing 127 bytes
let ref: Cell = beginCell().storeUint(33, 8).endCell();
let long: Slice = tmp.storeRef(ref).asSlice(); // plus a ref with a single byte

// Hashing just the data bits in the current slice isn't enough
sha256(long) == long.hashData(); // false!

Slice.asCell

500+ gas

extends fun asCell(self: Slice): Cell;

Extension function for the Slice type.

Converts the Slice to a Cell and returns it. An alias to beginCell().storeSlice(self).endCell().

Usage example:

let s: Slice = beginCell().asSlice();
let fizz: Cell = s.asCell();
let buzz: Cell = beginCell().storeSlice(s).endCell();

fizz == buzz; // true

Slice.asString

extends fun asString(self: Slice): String;

Extension function for the Slice type.

Casts the Slice to a String and returns it. The inverse of String.asSlice().

Usage example:

let s: String = "Keep your Slices close, but your Strings closer.";
let fizz: String = s;
let buzz: String = s.asSlice().asString();

fizz == buzz; // true

Slice.fromBase64

500+ gas

extends fun fromBase64(self: Slice): Slice;

Extension function for the Slice type.

Returns a new Slice from the decoded Base64 Slice.

Note that this function is limited and only takes the first 1023 bits of data from the given Slice, without throwing an exception if the Slice has more data (i.e., when it has any references).

If the given Slice contains characters not from the Base64 set, an exception with exit code 134 will be thrown: Invalid argument.

Usage example:

let s: Slice = "SSBhbSBHcm9vdC4=".asSlice();
let fizz: Slice = s.fromBase64();

Slice.asAddress

Available since Tact 1.6

extends fun asAddress(self: Slice, chain: Int): Address;

Extension function for the Slice type.

Casts the Slice to an Address on a given chain ID and returns it. It is the inverse of Address.asSlice() and a safe but more gas-expensive version of Slice.asAddressUnsafe().

Attempts to specify a Slice with an invalid account ID length throw an error with exit code 136: Invalid standard address.

Attempts to specify a Slice with an invalid tag prefix (not 0b100) or with an invalid account ID length (not 256 bits) throw an error with exit code 136: Invalid standard address.

Usage example:

let a: Address = myAddress(); // let's assume we're in a basechain
let a2: Address = a.asSlice().asAddress(0); // so the chain ID is 0

a == a2; // true

Note

Because of the checks performed, this function is more gas-expensive than its unsafe but cheaper counterpart: Slice.asAddressUnsafe().

Slice.asAddressUnsafe

Available since Tact 1.6

extends fun asAddressUnsafe(self: Slice): Address;

Extension function for the Slice type.

Unsafely casts the Slice to an Address and returns it. The inverse of Address.asSlice().

This function does not perform any checks on the contents of the Slice.

Usage example:

let a: Address = myAddress();
let a2: Address = a.asSlice().asAddressUnsafe();

a == a2; // true

Caution

Use it only if you want to optimize the code for gas and can guarantee in advance that the Slice contains the data of an Address.

Otherwise, use the safer but more gas-expensive Slice.asAddress() function.

Struct.toCell

extends fun toCell(self: Struct): Cell;

Extension function for any struct type.

Converts the struct to a Cell and returns it.

Usage example:

struct GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun coinCell(): Cell {
    let s: GuessCoin = GuessCoin { probably: 42, nothing: 27 };
    let fizz: Cell = s.toCell();

    return fizz; // "x{12A11B}"
}

Struct.toSlice

Available since Tact 1.5

extends fun toSlice(self: Struct): Slice;

Extension function for any struct type.

Converts the struct to a Slice and returns it. An alias to self.toCell().asSlice().

Usage example:

struct GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun coinSlice(): Slice {
    let s: GuessCoin = GuessCoin { probably: 42, nothing: 27 };
    let fizz: Slice = s.toSlice();

    return fizz; // "CS{Cell{000612a11b} bits: 0..24; refs: 0..0}"
}

Struct.fromCell

fun Struct.fromCell(cell: Cell): Struct;

Extension function for any struct type.

Converts a Cell into the specified struct and returns that struct.

Attempts to pass a Cell with a layout different from the specified struct or to load more data than the Cell contains throw an exception with exit code 9: Cell underflow.

Usage examples:

struct GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun directParse(payload: Cell): GuessCoin {
    return GuessCoin.fromCell(payload);
}

fun cautiousParse(payload: Cell): GuessCoin? {
    let coin: GuessCoin? = null;
    try {
        coin = GuessCoin.fromCell(payload);
    } catch (e) {
        dump("Cell payload doesn't match GuessCoin struct!");
    }
    return coin;
}

Struct.fromSlice

fun Struct.fromSlice(slice: Slice): Struct;

Extension function for any Struct type.

Converts a Slice into the specified struct and returns that struct.

Attempts to pass a Slice with a layout different from the specified struct or to load more data than the Slice contains throw an exception with exit code 9: Cell underflow.

Usage examples:

struct GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun directParse(payload: Slice): GuessCoin {
    return GuessCoin.fromSlice(payload);
}

fun cautiousParse(payload: Slice): GuessCoin? {
    let coin: GuessCoin? = null;
    try {
        coin = GuessCoin.fromSlice(payload);
    } catch (e) {
        dump("Slice payload doesn't match GuessCoin struct!");
    }
    return coin;
}

Message.toCell

extends fun toCell(self: Message): Cell;

Extension function for any Message type.

Converts the Message to a Cell and returns it.

Usage example:

message GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun coinCell(): Cell {
    let s: GuessCoin = GuessCoin { probably: 42, nothing: 27 };
    let fizz: Cell = s.toCell();

    return fizz; // "x{AB37107712A11B}"
}

Message.toSlice

Available since Tact 1.5

extends fun toSlice(self: Message): Slice;

Extension function for any Message type.

Converts the Message to a Slice and returns it. An alias to self.toCell().asSlice().

Usage example:

message GuessCoin {
    probably: Int as coins;
    nothing: Int as coins;
}

fun coinSlice(): Slice {
    let s: GuessCoin = GuessCoin { probably: 42, nothing: 27 };
    let fizz: Slice = s.toSlice();

    return fizz; // "CS{Cell{000eab37107712a11b} bits: 0..56; refs: 0..0}"
}

Message.fromCell

fun Message.fromCell(cell: Cell): Message;

Extension function for any Message type.

Converts a Cell into the specified Message and returns that Message.

Attempts to pass a Cell that contains an opcode prefix of a different message throw an exception with exit code 129: Invalid serialization prefix.

Attempts to pass a Cell with a layout different from the specified Message or to load more data than a Cell contains throw an exception with exit code 9: Cell underflow.

Usage examples:

message(0x777) TripleAxe {
    prize: Int as uint32;
}

fun directParse(payload: Cell): TripleAxe {
    return TripleAxe.fromCell(payload);
}

fun cautiousParse(payload: Cell): TripleAxe? {
    let coin: TripleAxe? = null;
    try {
        coin = TripleAxe.fromCell(payload);
    } catch (e) {
        dump("Cell payload doesn't match TripleAxe Message!");
    }
    return coin;
}

Message.fromSlice

fun Message.fromSlice(slice: Slice): Message;

Extension function for any Message type.

Converts a Slice into the specified Message and returns that Message.

Attempts to pass a Slice that contains an opcode prefix of a different message throw an exception with exit code 129: Invalid serialization prefix.

Attempts to pass a Slice with a layout different from the specified Message or to load more data than a Slice contains throw an exception with exit code 9: Cell underflow.

Usage examples:

message(0x777) TripleAxe {
    prize: Int as uint32;
}

fun directParse(payload: Slice): TripleAxe {
    return TripleAxe.fromSlice(payload);
}

fun cautiousParse(payload: Slice): TripleAxe? {
    let coin: TripleAxe? = null;
    try {
        coin = TripleAxe.fromSlice(payload);
    } catch (e) {
        dump("Slice payload doesn't match TripleAxe Message!");
    }
    return coin;
}

Message.opcode

Available since Tact 1.6.7

fun Message.opcode(): Int;

Extension function for any Message type.

Returns the opcode of the Message.

Usage example:

message(0x777) TripleAxe {
    prize: Int as uint32;
}

contract Example {
    receive(msg: TripleAxe) {
        dump(TripleAxe.opcode()); // 0x777
   }
}

Contract.toCell

Available since Tact 1.6.12

extends fun toCell(self: Contract): Cell;

Extension function for any contract type.

Converts the contract state to a Cell and returns it.

Usage example:

contract Example {
    probably: Int as coins = 42;
    nothing: Int as coins = 27;

    get fun asCell(): Cell {
        return self.toCell();
    }
}

Note

If a contract doesn’t use contract parameters, the resulting Cell or Slice will contain a leading one bit representing the lazy initialization bit.

Contract.toSlice

Available since Tact 1.6.12

extends fun toSlice(self: Contract): Slice;

Extension function for any contract type.

Converts the contract state to a Slice and returns it. An alias to self.toCell().asSlice().

Usage example:

contract Example {
    probably: Int as coins = 42;
    nothing: Int as coins = 27;

    get fun asSlice(): Slice {
        return self.toSlice();
    }
}

Note

If a contract doesn’t use contract parameters, the resulting Cell or Slice will contain a leading one bit representing the lazy initialization bit.

Contract.fromCell

Available since Tact 1.6.13

fun fromCell(cell: Cell): Contract;

Extension function for any contract type.

Converts a Cell into the specified contract struct and returns it.

Usage example:

contract GuessCoinContract {
    probably: Int as coins = 42;
    nothing: Int as coins = 27;

    receive() { cashback(sender()) }
}

fun directParse(payload: Cell): GuessCoinContract {
    return GuessCoinContract.fromCell(payload);
}

fun cautiousParse(payload: Cell): GuessCoinContract? {
    let coin: GuessCoinContract? = null;
    try {
        coin = GuessCoinContract.fromCell(payload);
    } catch (e) {
        dump("Cell payload doesn't match GuessCoinContract struct!");
    }
    return coin;
}

Contract.fromSlice

Available since Tact 1.6.13

fun fromSlice(slice: Slice): Contract;

Extension function for any contract type.

Converts a Slice into the specified contract struct and returns it.

Usage example:

contract GuessCoinContract {
    probably: Int as coins = 42;
    nothing: Int as coins = 27;

    receive() { cashback(sender()) }
}

fun directParse(payload: Slice): GuessCoinContract {
    return GuessCoinContract.fromSlice(payload);
}

fun cautiousParse(payload: Slice): GuessCoinContract? {
    let coin: GuessCoinContract? = null;
    try {
        coin = GuessCoinContract.fromSlice(payload);
    } catch (e) {
        dump("Slice payload doesn't match GuessCoinContract struct!");
    }
    return coin;
}