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.

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 (opens in a new tab) 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.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 $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.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);

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

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

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 (opens in a new tab) 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.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;
}