Я признаю, что название является спорным, но Clarinet — это инструмент Clarity, поэтому технически мы имеем дело с одним ингредиентом.
Приходя из экосистемы Ethereum и привыкнув к Solidity с точки зрения синтаксиса, выразительности, развертывания и тестирования, я изначально очень скептически относился к тому, может ли быть какой-либо другой язык, который мог бы конкурировать с ним. Увы, после изучения стеков я не мог не написать статью о языке, который действительно оправдывает свое название.
Ясность — это неполный по Тьюрингу разрешимый язык, что означает, что команды будут завершены, несмотря ни на что. Это имеет первостепенное значение в смарт-контрактах, которые должны содержать большие суммы пользовательских средств, поскольку это делает поведение смарт-контракта полностью предсказуемым для программиста.
Начнем с настройки самого необходимого. Ради длины статьи я предполагаю, что вы работаете в среде macOS или Linux. Не каламбур для пользователей Windows, ссылки в конце будут дополнительными.
Установка пакетов
Предлагается пакет Homebrew, поскольку он включает в себя Clarinet, если он не установлен в вашей системе, вы можете перейти здесь для получения инструкций:
$ brew install clarinet
Clarinet — это приложение командной строки для Clarity. Это разнообразный пакет, который позволяет нам разрабатывать, развертывать и тестировать наши смарт-контракты на месте, без необходимости настраивать виртуальные блокчейны (тестовые сети), как в Ganache, когда мы используем пакет Truffle, перенося контракт для каждого теста.
Одна из его самых приятных особенностей заключается в том, что он создает виртуальные кошельки, заполненные токенами сборщиков, поэтому вы можете напрямую протестировать поведение смарт-контракта. Кроме того, вам не нужно ждать, пока блоки подтвердятся в реальном времени, но это была функция и для настройки трюфельного ганаша.
Для редактирования вы также можете использовать редактор Sublime или VsCode, я предпочитаю VsCode с надстройкой Clarity.
После установки Clarinet мы можем создать наш первый проект через консоль. Нет необходимости в командах mkdir и т. д., просто перейдите по пути, по которому вы хотите разместить проект вашего кларнета, и введите:
$ clarinet new clarity-hello-world
Если мы -cd- к /clarity-hello-world и воспользуемся командой -ls-, мы увидим созданные папки и файлы.
Существует 1 файл и 3 папки: файл Clarinet.toml и папки contracts, settings и tests.
Предполагая, что у нас установлен git, мы хотим начать отслеживать наши изменения и прогресс. Если у вас его нет, вы можете установить его здесь.
$ cd clarity-hello-world $ git init
если мы также используем -git status сразу после этого, мы можем увидеть неустановленные изменения в нашем проекте красным цветом. (или любой другой цвет, который есть на вашем терминале):
Чтобы инсценировать наши изменения, а затем зафиксировать:
$ git add .
Если вы хотите напрямую назвать свое изменение через консоль, используйте:
$ git commit -m "your description"
Если вы такой же поклонник VIM, как и я:
$ git commit
Vim запустится, нажмите I, чтобы перейти в режим вставки, введите свое описание сверху, затем нажмите ESC, затем “: wq”, чтобы сохранить изменения. и выйдите из Vim.
Начало нашего контракта с кларнетом:
$ clarinet contract new hello-world
Если мы снова воспользуемся командой $ git status, мы увидим в изменениях, что были созданы 2 новых неотслеживаемых файла: hello-world.clar и hello-world. тесты, НО также изменен Clarinet.toml! На первой картинке показан результат git-status, а на второй — $git diff Clarinet.toml. (игнорируйте .DS_Store, это не важно для Mac).
Лучше всего обновлять наш git для каждого изменения, которое мы вносим в наш проект, поэтому:
$ git add . $ git commit -m "Added new contract"
Затем мы cd переходим в папку с контрактами, чтобы начать изменять наш контракт .clar. Мы можем использовать для этого текстовый редактор, такой как Vim, или нашу внешнюю IDE, например VsCode. В случае Vim мы вводим:
$ vim hello-world.clar
Прежде чем двигаться дальше, я кратко напомню об объеме функций. Область действия — это значение, которое дает возможность вызывать функцию из других функций, других контрактов или нет. Похоже на Солидность:
Общедоступную функцию можно вызывать (использовать) из других контрактов и извне (интерфейс).
Внешнюю функцию можно вызывать из других контрактов, но не извне.
Функция только для чтения не изменяет переменные, карты и т. д. контракта.
Доступ к частным функциям предоставляется только этому смарт-контракту.
Знакомство с синтаксисом Clarity поначалу может показаться немного странным, по крайней мере для меня, но это довольно просто, и то, что вы пишете, именно то, что вы получаете.
Мы начнем с создания нашей первой публичной функции.
Давайте немного разберем синтаксис:
(привет) : это имя функции, прямо перед скобками мы определяем видимость после команды define как public.
(ok hello world) : ok — это конструктор ответа, который вернет значение hello-world только потому, что мы не не задавайте никаких параметров нашей функции.
Затем мы добавим функцию только для чтения, которая будет принимать число в качестве входных данных и немедленно возвращать это число. Довольно просто, но поможет нам освоить новый синтаксис. Помните, что только чтение ничего не изменит внутри нашего смарт-контракта.
После использования $ git status и $ git diff hello-world.clar мы видим, что изменения были обнаружены.
Сначала мы должны проверить синтаксис нашего контракта, поэтому:
$ clarinet check
… и тут же улавливает мою неосторожную ошибку, когда я забыл закрыть входную часть функции. Мой ввод:
(define-read-only (echo-number (val int) (ok val))
И в результате:
После корректируем правильное закрытие или входную часть функции:
(define-read-only (echo-number (val int)) (ok val))
Получаем желаемый результат:
Теперь красота кларнета… Немного тестирования:
Инициализируя консоль кларнета, мы можем немедленно взаимодействовать с нашим смарт-контрактом, не развертывая его в тестовой сети. Подобно консольной команде truffle и без необходимости настраивать наши тестовые файлы RPC для сети:
$ clarinet console
Важно: перед инициализацией консоли кларнета нам нужно вернуться в корневой каталог /clarity-hello-world.
Clarinet — это инструмент цикла чтения-оценки-печати (REPL), который мгновенно выполняет код ясности при вызове функции!
Когда мы выполняем, мы получаем все детали нашего смарт-кошелька, а также кошельков Stacks, Clarinet предоставляет нам STX для проведения нашего тестирования.
Первое, что можно заметить, это то, что в деталях нашего контракта единственная видимая функция — это та, которая имеет входные значения, то есть эхо-номер доступен только для чтения.
Давайте сначала протестируем нашу первую функцию, которая не принимает никаких входных данных:
>> (contract-call? .hello-world say-hi)
Давайте снова разберем нашу команду:
contract-call?: довольно очевидно, что операция, которую мы хотим выполнить с нашим контрактом, вызывает функцию
.hello-world: контракт, на который мы хотим настроить таргетинг, чтобы выполнить вызов функции В этом контракте.
поздоровайтесь: название функции, если вы помните, когда мы писали ее ранее.
Когда мы выполняем, мы сразу наполняем радостью наши сердца, получая:
Затем мы вызываем функцию, которой требуется int(eger) в качестве значения, чтобы вернуть его:
>> (contract-call? .hello-world echo-number 57)
Тот же синтаксис, с той лишь разницей, что у нас есть вход для значения эхо-числа, которое мы устанавливаем на случайное число «57».
Второе изображение — это ошибочный результат, который мы получаем, если вводим недопустимое значение и запускаем тест.
Мы выходим из консоли Clarinet, дважды нажав CTRL+C.
Развертывание смарт-контракта в сети STACKS:
Мы снова переходим в наш корневой каталог, затем cdк папке настроек и открываем Mainnet.toml:
В мнемонике довольно очевидно, что мы вставляем нашу исходную фразу из 24 слов, поскольку мы являемся исполнителями смарт-контракта.
Теперь пришло время развернуть:
- Во-первых, clarinet создаст для нас файл .yaml в папке deployments, который поможет нам выполнить процедуру развертывания.
$ clarity deployment generate --mainnet --low-cost
Параметры после «сгенерировать» определяют, где мы хотим развернуться, devnet, testnet, mainet и т. д., а последний указывает желаемую стоимость транзакции.
2. Вводим последнюю команду развертывания:
$ clarinet deployment apply --mainnet
Вместо параметра apply мы также можем использовать:
- check: чтобы проверить формат развертывания
- generate: для создания нового развертывания
В результате мы получаем обзор нашей процедуры развертывания, отображающий имя контракта, отправителя (нас) и стоимость, а также продолжительность 1 блока.
Но так как в настоящее время у нас нет баланса на нашем кошельке, мы получаем следующую ошибку:
Надеюсь, вам понравилось это вводное руководство, само собой разумеется, что оно может обновляться в случае возникновения ошибок или обновлений.
Источники:
Блог Moodmosaic: https://blog.nikosbaxevanis.com/2022/01/28/clarity-hello-world-deployed-on-stacks/
Hirosystems GitHub: https://github.com/hirosystems/clarinet#clarinet
Не стесняйтесь следить и подписываться на мою бесплатную рассылку для обновлений:
