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 another 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.

And every user is recommended to use Structs and their methods like 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). 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). Alias to emptyCell().asSlice().

Usage example:

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

fizz == buzz; // true

Cell.beginParse

extends fun beginParse(self: Cell): Slice;

Extension function for the Cell.

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

Usage example:

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

Cell.hash

extends fun hash(self: Cell): Int;

Extension function for the Cell.

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.

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

Usage example:

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

Builder.endCell

extends fun endCell(self: Builder): Cell;

Extension function for the Builder.

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.

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.

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.

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.

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.

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.

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. Alias to Builder.storeBool().

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, cell: Builder): Builder;

Extension function for the Builder.

Appends all data from a Builder cell to the copy of the Builder. Returns that copy.

Usage example:

let b: Builder = beginCell().storeCoins(42);
let fizz: Builder = beginCell().storeBuilder(b);
b.endCell() == fizz.endCell(); // true

Builder.storeSlice

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

Extension function for the Builder.

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

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.

Stores (serializes) an unsigned Int value in the range $0 .. 2^{120} − 1$ into the 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.

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.storeAddress

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

Extension function for the Builder.

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

Usage example:

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

Builder.storeRef

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

Extension function for the Builder.

Stores a reference cell 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.storeRef(emptyCell());

Builder.storeMaybeRef

Available since Tact 1.5

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

Extension function for the Builder.

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

If the cell is null, only stores $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.

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.

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.asSlice

extends fun asSlice(self: Builder): Slice;

Extension function for the Builder.

Converts the Builder to a Slice and returns it. 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.

Converts the Builder to a Cell and returns it. Alias to self.endCell().

Usage example:

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

Slice.loadUint

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

Extension mutation function for the Slice.

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 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.

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 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.

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 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.

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 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.

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 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.

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 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);

Slice.skipBits

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

Extension mutation function for the Slice.

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 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.loadBool

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

Extension mutation function for the Slice.

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 such Bool when Slice doesn’t contain it throw an exception with exit code 8: Cell overflow.

Attempts to load more data than 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.loadBit

Available since Tact 1.5

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

Extension mutation function for the Slice. 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.

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

Attempts to load such Int when Slice doesn’t contain it throw an exception with exit code 8: Cell overflow.

Attempts to load more data than 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();

Useful links:

Special coins serialization type

Slice.loadAddress

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

Extension mutation function for the Slice.

Loads and returns an Address from the Slice.

Attempts to load such Address when Slice doesn’t contain it throw an exception with exit code 8: Cell overflow.

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.loadRef

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

Extension mutation function for the Slice.

Loads the next reference from the Slice as a Cell.

Attempts to load such reference Cell when Slice doesn’t contain it throw an exception with exit code 8: Cell overflow.

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.

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

Attempts to preload such reference Cell when Slice doesn’t contain it throw an exception with exit code 8: Cell overflow.

Attempts to preload 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.preloadRef(); // didn'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.refs

extends fun refs(self: Slice): Int;

Extension function for the Slice.

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.

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.empty

extends fun empty(self: Slice): Bool;

Extension function for the Slice.

Checks whether the Slice is empty (i.e., contains no bits of data and no cell references). Returns true if it’s 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 doesn’t throw any exceptions even when the Slice is empty.

Slice.dataEmpty

extends fun dataEmpty(slice: Slice): Bool;

Extension function for the Slice.

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.

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.

Checks whether the Slice is empty (i.e., contains no bits of data and no cell references). If it’s not, 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

extends fun hash(self: Slice): Int;

Extension function for the Slice.

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.asCell

extends fun asCell(self: Slice): Cell;

Extension function for the Slice.

Converts the Slice to a Cell and returns it. 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

Address.asSlice

extends fun asSlice(self: Address): Slice;

Extension function for the Address.

Converts the Address to a Slice and returns it. Alias to beginCell().storeAddress(self).asSlice().

Usage example:

let a: Address = myAddress();
let fizz: Slice = a.asSlice();
let buzz: Slice = beginCell().storeAddress(a).asSlice();

fizz == buzz; // true

Struct.toCell

extends fun toCell(self: Struct): Cell;

Extension function for any structure type Struct.

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 structure type Struct.

Converts the Struct to a Slice and returns it. 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

extends fun fromCell(self: Struct, cell: Cell): Struct;

Extension function for any structure type Struct.

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

Attempts to pass a Cell with layout different from the specified Struct or to load more data than a 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

extends fun fromSlice(self: Struct, slice: Slice): Struct;

Extension function for any structure type Struct.

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

Attempts to pass a Slice with layout different from the specified Struct or to load more data than a 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 Message.

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 Message.

Converts the Message to a Slice and returns it. 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

extends fun fromCell(self: Message, cell: Cell): Message;

Extension function for any message type Message.

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

Attempts to pass a Cell with 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

extends fun fromSlice(self: Message, slice: Slice): Message;

Extension function for any message type Message.

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

Attempts to pass a Slice with 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;
}