Reference
Cells, Builders and Slices

Cells, Builders and Slices

Cells is a low level primitive that represents data in TON blockchain. Cell consists of a 1023 bits of data with up to 4 references to another Cells. Cells are read-only and immutable. Builders are immutable structures that can be used to construct Cells. Slices are a way to parse cells.

💡

Be very careful when constructing and parsing cells, 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 (opens in a new tab).

beginCell

fun beginCell(): Builder

Creates a new empty Builder.

Usage example:

let fizz: Builder = beginCell();

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≤0 ≤ bits ≤256≤ 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≤0 ≤ bits ≤257≤ 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.storeUint(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 11 as a single bit if value is true, and writes 00 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.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..2120−10 .. 2^{120} − 1 into the copy of the Builder. The serialization of value consists of a 4-bit unsigned big-endian integer ll, which is the smallest integer l≥0l ≥ 0, such that value <28∗l< 2^{8 * l}, followed by an 8∗l8 * l-bit unsigned big-endian representation of value. If value does not belong to the supported range, a range check exception is thrown. 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);

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 44 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.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();

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 a hash of the Cell as an Int.

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

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≤0 ≤ l ≤256≤ 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().storeInt(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≤0 ≤ l ≤256≤ 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().storeInt(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≤0 ≤ l ≤257≤ 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≤0 ≤ l ≤257≤ 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≤0 ≤ l ≤1023≤ 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≤0 ≤ l ≤1023≤ 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≤0 ≤ l ≤1023≤ 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 11, 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.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..2120−10 .. 2^{120} - 1 from the Slice. This values 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();

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 s: Slice = beginCell().storeRef(emptyCell()).asSlice();
let fizz: Cell = s.loadRef();
 
let s: Slice = beginCell()
    .storeRef(emptyCell())
    .storeRef(emptyCell())
    .asSlice();
let ref1: Cell = s.loadRef();
let ref2: Cell = s.loadRef();

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
💡

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 a hash of the Slice as an Int.

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.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, cell: 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.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, cell: 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;
}

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
Strings and StringBuildersAdvanced