Пишем Смарт-контракт на FunC для TON (The Open Network)

Введение

В этом уроке мы напишем ваш первый смарт-контракт в тестовой сети The Open Network на языке FUNC, задеплоим его в тестовую сеть с помощью toncli, а также протестируем его с помощью сообщения на языке Fift.

Требования

Для прохождения данного урока вам необходимо установить интерфейс для командной строки toncli

Смарт-контракт

Смарт-контракт, который мы будем делать, должен обладать следующей функциональностью:

• хранить в своих данных целое число total - 64-битное число без знака;

• при получении внутреннего входящего сообщения контракт, должен взять 32-битное целое число без знака из тела сообщения, добавить его к total и сохранить в данных контракта;

• В смарт-контракте должен быть предусмотрен метод get total позволяющий вернуть значение total

• Если тело входящего сообщения меньше 32 бит, то контракт должен выдать исключение

Создадим проект с помощью toncli

В консоли выполните следующие команды:

toncli start wallet
cd wallet

Toncli создал простой проект кошелька, в нем вы можете увидеть 4 папки:

• build;

• func;

• fift;

• test;

На данном этапе нас интересуют папки func и fift, в которых мы будем писать код на FunС и Fift соответственно.

Что такое FunC и Fift

Высокоуровневый язык FunC используется для программирования смарт-контрактов на TON. Программы FunC компилируются в Fift ассемблерный код, который генерирует соответствующий байт-код для виртуальной машины TON(TVM). Далее этот байт-код (на самом деле дерево ячеек, как и любые другие данные в TON Blockchain) может быть использован для создания смарт-контракта в блокчейне или может быть запущен на локальном экземпляре TVM(Ton Virtual Machine).

Подробнее с FunC можно ознакомиться здесь

Подготовим файл для нашего кода

Зайдите в папку func:

cd func

И откройте файл code.func, на своем экране вы уведите смарт-контракт кошелька, удалите весь код и мы готовы начать писать наш первый смарт контракт.

Внешние методы

У смарт-контрактов в сети TON есть два внешних метода к которым можно обращаться.

Первый, recv_external() эта функция выполняется когда запрос к контракту происходит из внешнего мира, то есть не из TON, например когда мы сами формируем сообщение и отправляем его через lite-client.

Второй, recv_internal() эта функция выполняется когда внутри самого TON, например когда какой-либо контракт обращается к нашему.

Под наши условия подходит recv_internal()

В файле code.func пропишем:

() recv_internal(slice in_msg_body) impure {
;; здесь будет код
}

;; две точки с запятой синтаксис однострочного комментария

Мы передаем в функцию слайс in_msg_body и используем ключевое слово impure

impure — ключевое слово, которое указывает на то, что функция изменяет данные смарт-контракта.

А вот чтобы понять, что такое слайс, поговорим про типы в смарт-контрактах сети TON

Типы cell,slice, builder, Integrer в FunC

В нашем просто смарт контракте мы будем использовать всего лишь четыре типа:

• Cell(ячейка) - Ячейка TVM, состоящая из 1023 бит данных и до 4 ссылки на другие ячейки

• Slice - Частичное представление ячейки TVM, используемой для разбора данных из ячейки

• Builder - Частично построенная ячейка, содержащая до 1023 бит данных и до четырех ссылок; может использоваться для создания новых ячеек

• Integrer - знаковое 257-разрядное целое число

Подробнее о типах в FunC:
кратко здесь
развернуто здесь в разделе 2.1

Преобразуем полученный слайс в Integer

Чтобы преобразовать полученный слайс в Integer добавим следующий код:
int n = in_msg_body~load_uint(32);

Функция recv_internal() теперь выглядит так:

() recv_internal(slice in_msg_body) impure {
int n = in_msg_body~load_uint(32);
}

load_uint функция из стандартной библиотеки FunC она загружает целое число n-бит без знака из слайса.

Постоянные данные смарт-контракта

Чтобы добавить полученную переменную к total и сохранить значение в смарт-контракте, рассмотрим как реализован функционал хранения постоянных данных/хранилища в TON.

Примечание: не путайте с TON Storage, хранилище в предыдущем предложении удобная аналогия.

Виртуальная машина TVM является стековой, соответственно хорошей практикой хранения данных в контракте будет использовать определенный регистр, а не хранить данный "сверху" стека.

Для хранения постоянных данных отведен регистр с4, тип данных Ячейка.

Подробнее с регистрами можно ознакомиться с4 в пункте 1.3

Возьмем данные из с4

Для того чтобы "достать" данные из с4 нам понадобятся две функции из стандартной библиотеки FunC .

А именно:
get_data - берет ячейку из c4 регистра.
begin_parse - ячейку преобразует в slice

Передадим это значение в слайс ds

slice ds = get_data().begin_parse();

А также преобразуем этот слайс в Integer 64-бит для суммирования в соответствии с нашей задачей. (С помощью уже знакомой нам функции load_uint)

int total = ds~load_uint(64);

Теперь наша функция будет выглядеть так:

() recv_internal(slice in_msg_body) impure {
	int n = in_msg_body~load_uint(32);

	slice ds = get_data().begin_parse();
	int total = ds~load_uint(64);
}

Cуммируем

Для суммирования будем использовать бинарную операцию суммирования + и присвоение =

() recv_internal(slice in_msg_body) impure {
	int n = in_msg_body~load_uint(32);

	slice ds = get_data().begin_parse();
	int total = ds~load_uint(64);

	total += n;
}

Cохраняем значение

Для того чтобы сохранить постоянное значение, нам необходимо выполнить три действия:

• создать Builder для будущей ячейки

• записать в нее значение

• из Builder создать Cell (ячейку)

• Записать получившуюся ячейку в регистр

Делать это мы будем опять же с помощью функций стандартной библиотеки FunC

set_data(begin_cell().store_uint(total, 64).end_cell());

begin_cell() - создаст Builder для будущей ячейки
store_uint()- запишет значение total
end_cell()- создать Cell (ячейку)
set_data() - запишет ячейку в регистр с4

Итог:

() recv_internal(slice in_msg_body) impure {
	int n = in_msg_body~load_uint(32);

	slice ds = get_data().begin_parse();
	int total = ds~load_uint(64);

	total += n;

	set_data(begin_cell().store_uint(total, 64).end_cell());
}

Генерация исключений

Все что осталось сделать в нашей internal функции это добавить вызов исключения, если получена переменная не 32-битная.

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

Исключения могут быть вызваны условными примитивами throw_if и throw_unless и безусловным throw .

Воспользуемся throw_if и передадим любой код ошибки. Для того, чтобы взять битность используем slice_bits().

throw_if(35,in_msg_body.slice_bits() < 32);

Вставим в начало функции:

() recv_internal(slice in_msg_body) impure {
	throw_if(35,in_msg_body.slice_bits() < 32);

	int n = in_msg_body~load_uint(32);

	slice ds = get_data().begin_parse();
	int total = ds~load_uint(64);

	total += n;

	set_data(begin_cell().store_uint(total, 64).end_cell());
}

Пишем Get функцию

Любая функция в FunC соответствует следующему паттерну:

[<forall declarator>] <return_type><function_name(<comma_separated_function_args>) <specifiers>

Напишем функцию get_total() возвращающую Integer и имеющую спецификацию method_id (об этом чуть позже)

int get_total() method_id {
;; здесь будет код
}

Method_id

Спецификация method_id позволяет вызывать GET функцию по названию из lite-client or ton-explorer.
Грубо говоря все фукнции в том имеют численный идентификатор, get методы нумеруются по crc16 хэшам их названий.

Берем данные из с4

Для того, что функция возвращала total хранящееся в контракте, нам надо взять данные из регистра, что мы уже делали:

int get_total() method_id {
slice ds = get_data().begin_parse();
 int total = ds~load_uint(64);
return total;
}

Весь код нашего смарт-контракта

() recv_internal(slice in_msg_body) impure {
	throw_if(35,in_msg_body.slice_bits() < 32);

	int n = in_msg_body~load_uint(32);

	slice ds = get_data().begin_parse();
	int total = ds~load_uint(64);

	total += n;

	set_data(begin_cell().store_uint(total, 64).end_cell());
}
 
int get_total() method_id {
	slice ds = get_data().begin_parse();
 	int total = ds~load_uint(64);
	
	return total;
}

Деплоим контракт в тестовую сеть

Для деплоя в тестовую сеть будем использовать интерфейса для командной строки toncli

toncli deploy -n testnet

Что делать если пишет, что не хватает TON?

Необходимо получить их с тестового крана, бот для этого @testgiver_ton_bot
Адрес кошелька вы можете увидеть прямо в консоли, после команды деплой, toncli отобразит его справа от строки INFO: Found existing deploy-wallet

Чтобы проверить пришли ли TON на ваш кошелек в тестовой сети, можете использовать вот этот explorer: https://testnet.tonscan.org/

Важно: Речь идет только о тестовой сети

Тестируем контракт

Вызов recv_internal()

Для вызова recv_internal() необходимо послать сообщение внутри сети TON.
С помощью toncli send

Напишем небольшой скрипт на Fift, который будет отправлять 32-битное сообщение в наш контракт.

Скрипт сообщения

Для этого создадим в папке fift файл try.fif и напишем в нем следующий код:

"Asm.fif" include

<b
	11 32 u, // number
b>

"Asm.fif" include - необходим для компиляции сообщения в байт код

Теперь рассмотрим сообщение:

<b b> - создают Builder ячейки, подробнее в пункте 5.2

5 32 u - кладем 32-битное unsigned integer 11

// number - однострочный комментарий

Деплоим получившееся сообщение

В командной строке:

toncli send -n testnet -a 0.03 --address "адрес вашего контракта" --body ./fift/try.fif

Теперь протестируем GET функцию:

toncli get get_total

Должно получиться следующее:

Код и остальные уроки можно найти тут.