Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
A consolidated summary of how each Tolk type is serialized into TL-B–compatible binary data.
## `int`
Not serializable; use `intN` or other numeric types instead.
## `intN`
* fixed N-bit signed integer
* TL-B `intN`
* stored via `{N} STI`
* loaded via `{N} LDI`
## `uintN`
* fixed N-bit unsigned integer
* TL-B `uintN`
* stored via `{N} STU`
* loaded via `{N} LDU`
## `coins`
* alias to `varuint16`
* TL-B `VarUInteger 16`
* stored via `STGRAMS`
* loaded via `LDGRAMS`
## `varintN` for N = 16 or N = 32
* variadic signed integer: 4/5 bits for len + 8\*len bit number
* TL-B `VarInteger {N}`
* stored via `STVARINT{N}`
* loaded via `LDVARINT{N}`
## `varuintN` for N = 16 or N = 32
* variadic unsigned integer: 4/5 bits for len + 8\*len bit number
* TL-B `VarUInteger {N}`
* stored via `STVARUINT{N}`
* loaded via `LDVARUINT{N}`
## `bool`
* one bit: '0' or '1'
* TL-B `Bool`
* stored via `1 STI`
* loaded via `1 LDI` resulting in 0 or -1
## `address`
* standard (internal) address; 267 bits: 0b100 + workchain + hash
* TL-B `addr_std`
* stored via `STSTDADDR`
* loaded via `LDSTDADDR`
## `address?` (nullable)
* internal or none address; 2 or 267 bits: null -> '00', otherwise -> address
* TL-B `addr_none` or `addr_std`
* stored via `STOPTSTDADDR`
* loaded via `LDOPTSTDADDR`
## `any_address`
* any valid TL-B address, from 2 to 523 bits
* TL-B `MsgAddress`
* stored via `STSLICE`
* loaded via `LDMSGADDR`
## `cell` and `Cell`
* a reference
* TL-B `^Cell` / `^T`
* stored via `STREF`
* loaded via `LDREF`
## `cell?` and `Cell?` (nullable)
* maybe reference ('0' or '1'+ref)
* TL-B `Maybe ^Cell` / `Maybe ^T`
* stored via `STOPTREF`
* loaded via `LDOPTREF`
## `bitsN`
* just N bits
* TL-B `bitsN`
* stored via `STSLICE`, preceded by a runtime check that the slice contains exactly N bits and zero references; this check can be disabled using `skipBitsNValidation = false`.
* loaded via `LDSLICE` / `LDSLICEX` (for N > 256)
## `RemainingBitsAndRefs`
* the remainder of a slice when reading, and a raw slice when writing
* TL-B `Cell`
* stored via `STSLICE`
* loaded by copying current slice and assigning current to an empty one
## `builder` and `slice`
Can be used for writing, not for reading.
Not recommended, because they do not reveal internal structure and have unpredictable size.
Auto-generated TypeScript wrappers are not able to parse them.
## Structures
If a struct has a prefix, it's written first. Then its fields are serialized sequentially.
```tolk theme={null}
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 messages (incoming and outgoing) use 32-bit prefixes:
```tolk theme={null}
struct (0x7362d09c) TransferNotification {
queryId: uint64
// ...
}
```
### Not only 32-bit prefixes
Declaring messages with opcodes does not differ from declaring any other structs. Prefixes can be of any width:
* `0x000F` — 16-bit prefix
* `0x0F` — 8-bit prefix
* `0b010` — 3-bit prefix
* `0b00001111` — 8-bit prefix
Example. Let's express the following TL-B scheme:
```tl-b theme={null}
asset_simple$001 workchain:int8 ptr:bits32 = Asset;
asset_booking$1000 order_id:uint64 = Asset;
// ...
```
In Tolk, use structures and union types:
```tolk theme={null}
struct (0b001) AssetSimple {
workchain: int8
ptr: bits32
}
struct (0b1000) AssetBooking {
orderId: uint64
}
type Asset = AssetSimple | AssetBooking // | ...
```
When deserializing, `Asset` will follow manually provided prefixes, see "union types" below.
If a structure has a prefix, it is used consistently in all contexts (both standalone and within unions):
```tolk theme={null}
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.
Example. Need 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, create a `type` and **define a custom serializer**:
```tolk theme={null}
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);
}
```
And just use `ShortString` as a regular type — everywhere:
```tolk theme={null}
tokenName: ShortString
fullDomain: Cell
```
Method names `packToBuilder` and `unpackFromSlice` are reserved for this purpose, their signatures must match exactly as shown.
## Enums
The serialization type can be specified manually:
```tolk theme={null}
// `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`:
```tolk theme={null}
// `Role` will (un)packed as `uint2`
enum Role {
Admin,
User,
Guest,
}
```
Input values are validated during deserialization.
For `enum Role: int8` any (input\<0 || input>2) triggers exception 5 (integer out of range).
Non-range values are also validated:
```tolk theme={null}
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)`
* asm `1 STI` + IF ...
* asm `1 LDI` + IF ...
The exception: `address?` is serialized as "internal or none" (2/267 bits): null -> '00', otherwise -> address.
## Union types `T1 | T2 | ...`
Rules for union type serialization:
* `T | null` is TL/B `Maybe T` ('0' or '1'+T)
* if all `T_i` have prefixes `struct (0x1234) A`, they are used
* otherwise, a compiler auto-generates a prefix tree
### Manual serialization prefixes
If all `T_i` have manual prefixes, they are used:
```tolk theme={null}
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: it seems like a bug in code.
### Auto-generated prefix tree
If `T_i` don't have manual prefixes, the compiler generates a prefix tree.
A two-component union `T1 | T2` is TL/B `Either` (prefixes 0/1).
For example, `int32 | int64` becomes ('0'+int32 or '1'+int64).
Multi-component unions have longer prefixes.
For example `int32 | int64 | int128 | int256` forms a tree 00/01/10/11.
General rules:
* if `null` exists, it's 0, all others are 1+tree ("maybe others")
* example: `A|B|C|D|null` => 0 | 100+A | 101+B | 110+C | 111+D
* if no `null`, just distributed sequentially
* example: `A|B|C` => 00+A | 01+B | 10+C
```tolk theme={null}
struct WithUnion {
f: int8 | int16 | int32
}
```
This field will be packed as: '00'+int8 OR '01'+int16 OR '10'+int32.
On deserialization, the same format is expected (prefix '11' will throw an exception).
Same for structs without a manual prefix:
```tolk theme={null}
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: 0/10/11
g: A | B | null
// even this works; when '11', a ref exists
h: A | int32 | C | cell
}
```
## Tensors `(T1, T2, ...)`
Tensor components are serialized sequentially, in the same manner as structure fields.
## `tuple` and typed tuples
Tuples cannot be serialized; serialization is not implemented for tuples.
But tuples can be returned from get methods, since contract getters work via the stack, not serialization.
## `map`
* maybe reference: '0' (empty) or '1'+ref (dict contents)
* TL-B `HashmapE n X` (follow [hashmaps in TL-B](/languages/tl-b/complex-and-non-trivial-examples#hashmap))
* stored via `STDICT`
* loaded via `LDDICT`
## Callables `(...ArgsT) -> ResultT`
Callables cannot be serialized.
Lambdas may be used within contract logic but cannot be serialized for off‑chain responses.
## See also
* [Overall: TVM stack representation](/languages/tolk/types/overall-tvm-stack)
* [Type system overview](/languages/tolk/types/list-of-types)
* [Automatic serialization](/languages/tolk/features/auto-serialization)