TON Telegram Open Network - как пользоваться TL-B Scheme

avatar cromlehg 3 months ago

Оглавление

Введение

На момент написания статьи многие аспекты Telegram Open Network для разработчика были слабо документированы или очень сложны для понимания. По некоторым темам документация вовсе отсутствовала. Можно даже сказать что чтение некоторых сркриптов на fift и документации чем-то похоже на reverse engineering. 
Автору пришлось потратить неоправданно много времени на понимание построения сообщений в скриптах fift. Мы считаем что документация должна быть более user-friendly и нацелена на быстрое понимание пользователем. Дабы избавить читателя от траты времени на поиски информации по TL-B мы постарались изложить свой опыт понимания TL-B и структуры некоторых сообщений.

Изложенной в этой статье - это понимание автора, поэтому статья не претендует на истину в последней инстанции и более того может содержать ошибки и неточности.

Где применяется TL-B?

TL-B применяется для описания многих структур данных в TON. Например для описания структуры сообщений, посылаемых в сеть.
Или для описания структуры блоков. 

Зачем уметь читать TL-B?

Чтобы общаться с сетью TON и со смарт-контрактами (даже загрузка контракта в сеть длается сообщением) нужно уметь создавать сообщения.
А чтобы правильно сформировать сообщение нужно знать его структуру. 
Назначение сообщений описано в официальной документации, например тут https://test.ton.org/tblkch.pdf. В документе рассамтривается структура сообщений, которая описана в https://github.com/ton-blockchain/ton/blob/master/crypto/block/block.tlb. Структура эта, как вы уже догадались, описана в виде TL-B схемы. Поэтому если Вы не умеете читать TL-B, то понять как строить произвольное сообщение не сможете.

Как читать TL-B схему?

В TL-B схема определяет типы и их структуру. Правильно называть структуру типа - конструктором. 
Итак, типы определяются следующим образом:

<конструктор> = Тип;

<конструктор> - может состоять из нескольких полей.  Т.е. объявление типа можно представить так:

<поле 1> <поле 2> ... <поле n> = Тип; 

А каждое поле может быть одним из нескольких вариантов:

1. <название поля>$<биты> - в этом случае поле просто содержит указанные биты
2. <название поля>:Тип

Для одного типа может быть обьявлено несколько разных конструкторов. Такие структуры как правило имеют в начале битовое поле, по которому можно определить что это за конструктор. Это своего рода способ определения подтипов одного Типа.

Приведем пример Типа, котрорый имеет два разных конструктора. Оба конструктора имеют одно поле. Это поле содержит один бит и по нему мы можем отличить конструкторы.

bool_false$0 = Bool;
bool_true$1 = Bool;

Можно определять шаблоны типов. Лучше всего посмотреть на примере типа Maybe X:

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

Тип Maybe X работает так - если первым стоит 0 в конструкторе, то это конструктор пустого Maybe X. Если первый бит равен 1, то дальше идет поле содержащее сам X.
{x: Type} - указывает на то, что это может быть любой тип. 

Тип применяется когда нужно описать поле, которое может быть пустым. 

Давайте рассмотрим еще один шаблон типа, применяемый в TON:

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

Тут в шаблон типа уже подставляются два разных типа X и Y. Работет он так - если первый бит 0, то поле дальше содержит X, если первый бит 1 то поле дальше содержит Y. 
Этот тип применяется когда конкретное поле конструктора может содержать один из двух типов.

Называть подтипы в дальнешем будем по имени первого битового поля.  Например left и right - это подтипы Either X Y. Если первый бит 0, то подтип left, если первый бит 1 - то подтип right.
 

Резюме

Мы надеемся, что статья помогла читателю познакомиться с TL-B схемой и поможет в дальнейшем самостоятельно разбирать документацию.

Обсудить, задать вопросы или сообщить о неточностях можно в нашей официальной группе - Blockchain's Witnesses

Оглавление