Serialization

N bits
TL-B: bitsN
Stored using STSLICE, preceded by a runtime check that the slice contains exactly N bits and zero references; the check can be turned off using skipBitsNValidation = false.
Loaded using LDSLICE / LDSLICEX for N > 256

`RemainingBitsAndRefs`

Represents the remainder of a slice when reading, and a raw slice when writing.
TL-B: Cell
Stored using STSLICE
Loaded by copying the current slice and resetting the reader to an empty slice.

`builder`, `slice`

Can be used for writing, but not for reading.
Not recommended, as they do not reveal internal structure and have unpredictable size.
Auto-generated TypeScript wrappers cannot parse them.

`struct`

If a struct has a prefix, it is written first. The fields are then serialized sequentially.

struct (0x12345678) A {
    a: int8
    b: cell?
}

fun demo() {
    val a: A = {
        a: 123,
        b: createEmptyCell(),
    };
    // 41 bits and 1 ref: opcode + int8 + '1' + empty ref
    a.toCell()
}

32-bit prefixes (opcodes)

By convention, all incoming and outgoing messages use 32-bit prefixes:

struct (0x7362d09c) TransferNotification {
    queryId: uint64
    // ...
}

Not only 32-bit prefixes

Declaring messages with opcodes does not differ from declaring ordinary structs. A prefix can have any bit width:

0x000F — 16-bit prefix
0x0F — 8-bit prefix
0b010 — 3-bit prefix
0b00001111 — 8-bit prefix

Consider the TL-B scheme:

asset_simple$001 workchain:int8 ptr:bits32 = Asset;
asset_booking$1000 order_id:uint64 = Asset;
// ...

In Tolk, use structures and union types:

struct (0b001) AssetSimple {
    workchain: int8
    ptr: bits32
}

struct (0b1000) AssetBooking {
    orderId: uint64
}

type Asset = AssetSimple | AssetBooking // | ...

During deserialization, Asset is matched using the explicitly declared prefixes.

If a struct has a prefix, it is applied consistently in all contexts, both standalone and as part of a union:

AssetBooking.fromSlice(s)   // expecting '1000...' (binary)
AssetBooking{...}.toCell()  // '1000...'

Type aliases

A type alias is identical to its underlying type, unless a custom serializer is defined.

To implement a "variadic string" encoded as len + data:

len: (## 8)        // 8 bits of len
data: (bits len)   // 0..255 bits of data

To express this, define a type and provide a custom serializer:

type ShortString = slice

fun ShortString.packToBuilder(self, mutate b: builder) {
    val nBits = self.remainingBitsCount();
    b.storeUint(nBits, 8);
    b.storeSlice(self);
}

fun ShortString.unpackFromSlice(mutate s: slice) {
    val nBits = s.loadUint(8);
    return s.loadBits(nBits);
}

ShortString can then be used as a regular type everywhere:

tokenName: ShortString
fullDomain: Cell<ShortString>

The method names packToBuilder and unpackFromSlice are reserved for this purpose. Their signatures must match exactly as shown.

`enum`

The serialization type can be specified manually:

// `Role` will be (un)packed as `int8`
enum Role: int8 {
    Admin,
    User,
    Guest,
}

struct ChangeRoleMsg {
    ownerAddress: address
    newRole: Role    // int8: -128 <= V <= 127
}

Otherwise, it is calculated automatically. For Role above, uint2 is sufficient to fit values 0, 1, 2:

// `Role` will (un)packed as `uint2`
enum Role {
	  Admin,
	  User,
	  Guest,
}

Input values are validated during deserialization. For enum Role: int8, any input value outside the range of defined enum variants, e.g., < 0 or > 2, triggers exception 5.

Values not explicitly listed in the enum definition are also rejected:

enum OwnerHashes: uint256 {
    id1 = 0x1234,
    id2 = 0x2345,
    ...
}

// on serialization, just "store uint256"
// on deserialization, "load uint256" + throw 5 if v not in [0x1234, 0x2345, ...]

Nullable types `T?` (except `address?`)

Often called Maybe; 0 or 1+T
TL-B: (Maybe T)
Stored using 1 STI + IF ...
Loaded using 1 LDI + IF ...

Exception: address? is serialized as internal or none (2 or 267 bits):

00 – null;
otherwise – a standard internal address.

Union types `T1 | T2 | ...`

T | null is serialized as TL-B Maybe T.
If all T_i have prefixes struct (0x1234) A, those prefixes are used.
Otherwise, the compiler generates a prefix tree automatically.

Manual serialization prefixes

If all T_i have manual prefixes, they are used:

struct (0b001)  AssetSimple   { /* body1 */ }
struct (0b1000) AssetBooking  { /* body2 */ }
struct (0b01)   AssetNothing  {}

struct Demo {
    // '001'+body1 OR '1000'+body2
    e: AssetSimple | AssetBooking
    // '001'+body1 OR '1000'+body2 OR '01'
    f: AssetSimple | AssetBooking | AssetNothing
}

If a prefix exists for A but not for B, the union A | B cannot be serialized.

Auto-generated prefix tree

If T_i do not have manual prefixes, the compiler generates a prefix tree.

A two-component union T1 | T2 is serialized as TL-B Either using prefixes 0 and 1. Example: int32 | int64 → 0 + int32 or 1 + int64.
For unions with more components, longer prefixes are generated. Example: int32 | int64 | int128 | int256 → 00 / 01 / 10 / 11

General rules:

If null is present, it is assigned prefix 0, and all other variants use 1 + tree:
- A|B|C|D|null → 0 | 100+A | 101+B | 110+C | 111+D.
If null is not present, variants are assigned sequentially:
- A|B|C → 00+A | 01+B | 10+C.

struct WithUnion {
    f: int8 | int16 | int32
}

Field f is serialized as:

00 + int8
01 + int16
10 + int32

On deserialization, the same prefixes are expected; an unmatched prefix (e.g., 11) triggers an exception.

The same applies to structs without manual prefixes:

struct A { ... }    // 0x... prefixes not specified
struct B { ... }
struct C { ... }

struct WithUnion {
    // auto-generated prefix tree: 00/01/10
    f: A | B | C
    // with null, like Maybe<A|B>: 0/10/11
    g: A | B | null
    // even this works; when '11', a ref exists
    h: A | int32 | C | cell
}

`void` as a union variant — empty slice

A union variant of type void has no representation on the wire — it's matched by an empty slice (zero bits, zero refs). The other variants form a normal prefix tree among themselves and are unaffected.

struct (0x01) Some { x: int32 }

// either Some (0x01 + int32) — or empty slice
type SomeOrEnd = Some | void

// either 32 bits — or empty slice
type Int32OrEnd = int32 | void

// 0+int32, 1+int64, or empty slice
type WideOrEnd = int32 | int64 | void

On pack: writing the void variant emits nothing.
On unpack: when the input slice is empty, the deserialized value is the void variant; otherwise, normal prefix-tree dispatch is used.
void must be the last variant of a serializable union (otherwise the prefix dispatch would be ambiguous); the compiler enforces this when generating opcodes.

In match, the void arm is written as void => ...:

match (msg) {
    Some => { /* read Some.x */ }
    void => { /* slice was empty */ }
}

Tensors `(T1, T2, ...)`

Tensor components are serialized sequentially, akin to struct fields.

`string`

Serialized as a reference: a string is a snake-encoded cell
TL-B: ^Cell
Stored using STREF
Loaded using LDREF

`array<T>`

Serializable when T is serializable, e.g., array<int8> or array<bool?>.
Binary format: uint8 length, followed by chained cell references (snake refs), each containing a bool flag for the next reference and serialized elements.

For example, array<uint8> [1, 2, 3, 4, 5] can be packed into a single chunk with all 5 elements in a single reference, resulting in the following bitcode:

uint8 is 5 (length)
bool is true (has ref)
ref cell:
- bool is false (no next ref)
- 0x0102030405 (1, 2, 3, 4, 5)

This is not the only option. The data can be packed as ref 1 ref 2345, or ref 12 + ref 34 + ref 5, and so on. For example, ref 123 + ref 45 produces:

uint8 is 5 (length)
bool is true (has ref)
ref cell:
- bool is true (has next ref)
- 0x010203
- ref cell:
  - bool is false (no next ref)
  - 0x0405

An empty array is uint8 = 0, followed by a bool = false, which equates to nine zero bits.

The compiler precalculates chunk size to fit as many elements into a cell as possible. Client-side libraries can follow a simpler strategy — for example, write into a cell until there is space, then create a nested reference, repeating the process.

Shaped tuples `[T1, T2, ...]`

Shaped components are serialized sequentially: serialization is identical to tensors. But their nature is different: [T1, ...] are stored in a TVM tuple, whereas (T1, ...) act like N variables on a stack.

`map<K, V>`

Maybe reference: 0 for empty or 1+ref for dictionary contents
TL-B: HashmapE n X
Stored using STDICT
Loaded using LDDICT

Callables `(...ArgsT) -> ResultT`

Callables cannot be serialized.
Lambdas can be used within contract logic but cannot be serialized for off‑chain responses.

`unknown`

Cannot be serialized. Prefer using array<T> with serializable T instead of array<unknown> (tuple).

Serialization

On this page