Simple examples

Maybe

nothing$0 {X:Type} = Maybe X;
just$1 {X:Type} value:X = Maybe X;

The Maybe combinator is used to represent optional values. In this case, the first bit indicates a value. If the bit is 0, the value is not serialized and skipped. If the bit is 1, the value follows and is serialized.

Either

left$0 {X:Type} {Y:Type} value:X = Either X Y;
right$1 {X:Type} {Y:Type} value:Y = Either X Y;

The Either type is used when one of two possible result types may be present. The choice of type depends on the prefix bit. If the prefix bit is 0, then the left type is serialized. If it is 1, the right type is serialized.

This construct is used, for example, when serializing messages, where the body is either included directly in the main cell or stored in a separate referenced cell.

Both

pair$_ {X:Type} {Y:Type} first:X second:Y = Both X Y;

The Both type variation is used exclusively with regular pairs, where both types are serialized sequentially without any conditions.

VarUInteger n

var_uint$_ {n:#} len:(#< n) value:(uint (len * 8)) = VarUInteger n;

The combinator is parameterized by a natural number n, represented in curly brackets. For a given n, VarUInteger n describes the serialization of a natural number m, which in its binary representation contains no more than (n - 1) * 8 bits.

First, the number of bytes required for writing m, that is called len, is serialized into $\lceil \log_{2}n \rceil$ bits as an unsigned big-endian integer. Then m itself is serialized as a uint on len*8 bits. Thus, the size of the serialization of a particular m through the combinator VarUInteger n depends on m.

For example, VarUInteger 32 is used to represent the amount of a certain extra currency on an account. We can store in that type values up to 2**248 - 1. Let’s serialize the value = 27583 according to that type.

The binary representation of value is 110101110111111. It requires 15 bits to write it as an unsigned integer, so we need len = 2 bytes. The len is serialized as 00010 (into $\lceil \log_{2} 32 \rceil = 5$ bits). Then, the value is serialized as 0110101110111111 into len * 8 = 16 bits. Thus, the complete serialization of 27583 through VarUInteger 32 type description is 00010 0110101110111111.

Another important example is VarUInteger 16, which is used to represent account’s balance. We can store in that type values up to 2**120 - 1. According to that type, the value = 27583 will be serialized as 0010 0110101110111111, because len = 2 is serialized into $\lceil \log_{2} 16 \rceil = 4$ bits.