Начало работы с Solana может быть довольно трудным без руководства. В этой статье я позабочусь о том, чтобы на нашем локальном компьютере было все готово для начала работы с программами Solana с использованием фреймворка Anchor.

Поскольку предстоит пройти через многое, я позабочусь о том, чтобы быстро добраться до сути, чтобы вы могли перечитать эту статью в качестве контрольного списка действий в будущем. При этом мы потратим немного времени на изучение того, как работает Anchor, чтобы лучше понять цикл «Сборка, развертывание, тестирование», который мы будем использовать в этой серии.

Если вы пользователь Windows, я боюсь, что это руководство больше предназначено для пользователей Linux и Mac. К счастью, Buildspace имеет хорошее [руководство по установке Solana на компьютер с Windows](https://github.com/buildspace/buildspace-projects/blob/main/Solana_And_Web3/ en/Section_2/Resources/windows_setup.md), так что, надеюсь, вы все еще сможете продолжить после этого.

Я также хотел бы добавить, что экосистема Solana развивается относительно быстро, и поэтому некоторые из этих шагов могут в конечном итоге измениться или — скрестить пальцы — упроститься в будущем. Если это так, пожалуйста, свяжитесь со мной, и я обязательно обновлю статью соответствующим образом.

Установка Rust

Почему? Rust — это язык, который Солана использует для создания программ.

Установить Rust так же просто, как запустить это.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

После установки он добавит следующий PATH — или аналогичный — к вашим конфигурациям оболочки, что полезно знать, хотите ли вы переместить это в свои точечные файлы или что-то в этом роде.

export PATH="$HOME/.cargo/bin:$PATH"

Вы можете проверить правильность установки rust, выполнив следующие команды.

rustup --version
rustc --version
cargo --version

Установка Соланы

Точно так же вы можете установить Solana, запустив следующий скрипт установки.

sh -c "$(curl -sSfL https://release.solana.com/v1.9.4/install)"

Обратите внимание, что с тех пор могли быть выпущены более новые версии, поэтому не стесняйтесь проверять наличие последней версии в документации Solana.

Установка Solana также добавит новый PATH в конфигурацию вашей оболочки. В качестве альтернативы, в зависимости от вашей системы, он может попросить вас вручную обновить PATH, предоставив вам строку для копирования/вставки.

export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

Вы можете проверить правильность установки Solana, выполнив следующие команды.

# Check the Solana binary is available.
solana --version

# Check you can run a local validator (Run Ctrl+C to exit).
# We’ll see what this does in this article.
# Note this creates a "test-ledger" folder in your current directory.
solana-test-validator

EDIT 15-01-2022: Начиная с Solana v1.9.4, пользователям Apple M1 больше не нужно компилировать двоичные файлы Solana из исходного кода, и они могут просто следовать приведенным выше инструкциям! 🥳 Если у вас есть компьютер Apple M1 и вы используете более старую версию Solana, вы можете прочитать предыдущие инструкции по этому вопросу.

Использование Соланы локально

Почему? По умолчанию Solana использует сеть «mainnet». На данный момент мы хотим разрабатывать наши программы локально, прежде чем развертывать их по-настоящему.

solana config set --url localhost

После запуска вы должны увидеть, что все ваши конфигурации указывают на URL-адреса локального хоста, а это именно то, что нам нужно.

Создание локальной пары ключей

Почему? Нам нужен открытый и закрытый ключ, чтобы идентифицировать себя при локальном использовании двоичных файлов Solana.

Во-первых, вы можете проверить, есть ли у вас локальная пара ключей, выполнив следующую команду.

solana address

Если вы получаете сообщение об ошибке, это означает, что у вас его еще нет, поэтому давайте создадим новый.

Просто запустите следующую команду и следуйте инструкциям. Лично я не ввожу парафраз, так как сгенерированная пара ключей будет использоваться только локально.

solana-keygen new

В конце процесса вам будет предоставлена длинная фраза восстановления, которую можно использовать для восстановления как открытого, так и закрытого ключа. Несмотря на то, что она используется только локально, я на всякий случай храню эту фразу восстановления в своем менеджере паролей.

Обратите внимание, что вы можете восстановить любую пару ключей, запустив solana-keygen recover и указав в процессе фразу восстановления.

Установка anchor

Почему? Anchor — это фреймворк Solana, который значительно улучшил возможности разработчиков при создании программ.

Вы можете установить Anchor на локальном компьютере, выполнив следующую команду.

cargo install --git https://github.com/project-serum/anchor anchor-cli --locked

Обратите внимание, что вы также можете установить Anchor с помощью npm глобально, но, поскольку я использую несколько версий npm через nvm, я не большой поклонник глобальных зависимостей npm.

Вы можете запустить следующую команду, чтобы проверить, правильно ли установлен Anchor CLI.

anchor --version

Установка yarn

Почему? По умолчанию Anchor использует yarn для управления библиотеками JavaScript.

Если он еще не установлен, вы можете сделать это, выполнив одну из следующих команд:

# Using npm global dependencies.
npm install -g yarn

# Using homebrew on Mac.
brew install yarn

# Using apt on Linux
apt install yarn

Создание anchor проекта

Теперь, когда у нас установлен Anchor, мы можем запустить anchor init, чтобы начать новый проект!

# Go to your dev folder (for me it’s “~/Code”).
cd ~/Code

# Create a new Anchor project.
anchor init solana-twitter

# Cd into the newly created project.
cd solana-twitter

Внутри нашего нового проекта Anchor приготовил для нас кучу вещей:

Папка programs для всех наших программ Solana. Он уже поставляется с очень простой программой, которую мы можем использовать, поэтому нам не нужно делать все строительные леса.
Папка tests для всех наших тестов JavaScript, напрямую взаимодействующих с нашими программами. Опять же, он уже поставляется с тестовым файлом для нашей автоматически сгенерированной программы.
Файл конфигурации Anchor.toml, помогающий нам настроить идентификатор нашей программы, кластеры Solana, тестовую команду и т. д.
Пустая папка app, которая позже будет содержать наш клиент JavaScript.

Теперь, когда у нас есть наш проект, давайте посмотрим, как мы можем построить, развернуть и протестировать программу по умолчанию, сгенерированную Anchor. Таким образом, мы лучше поймем цикл разработки программы для Соланы.

Сборка и развертывание

У Anchor есть две очень полезные команды, которые делегируют компилятору Rust и инструментам Solana CLI сборку и развертывание ваших программ для вас.

# Compiles your program.
anchor build

# Deploys your compiled program.
anchor deploy

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

При этом давайте быстро посмотрим, что происходит, когда мы запускаем эти команды.

Anchor build

Во-первых, наш код компилируется, и нам будут показаны любые предупреждения или ошибки, возникающие во время компиляции. Компилятор Rust довольно мощный, поэтому, если мы сделали что-то не так в своем коде, он, скорее всего, не даст его скомпилировать.

Давайте запустим эту команду в нашем новом проекте.

anchor build

Как видите, наша программа скомпилирована, но вы должны увидеть следующее предупреждение: unused variable: 'ctx'. Это справедливо, потому что автоматически сгенерированная программа настолько проста, что фактически ничего не делает с этой переменной ctx, и поэтому компилятор предупреждает нас, что она не используется. Мы можем спокойно игнорировать это предупреждение на данный момент.

Кроме того, как только наш код был скомпилирован, целевая папка была соответствующим образом обновлена. Вам не нужно полностью понимать, что происходит внутри этой папки, но в основном она отслеживает любые встроенные выпуски и развертывание нашей программы. Обратите внимание, что эта папка относится к вашему локальному компьютеру и не будет зафиксирована в вашем репозитории git.

Наконец, сборка привязки также сгенерировала файл IDL. IDL означает «Язык описания интерфейса» и представляет собой просто файл JSON, содержащий все спецификации нашей программы Solana. Он содержит информацию о своих инструкциях, параметрах, требуемых этими инструкциями, счетах, сгенерированных программой и т. д.

Цель этого файла IDL — передать его нашему клиенту JavaScript позже, чтобы мы могли взаимодействовать с нашей программой Solana структурированным образом.

Anchor deploy

Запуск anchor deploy возьмет нашу последнюю сборку и развернет ее в кластере.

Обратите внимание, что при первой сборке программы она также сгенерирует для нее открытый и закрытый ключи, которые будут храниться в целевом каталоге. Сгенерированный открытый ключ станет уникальным идентификатором вашей программы — он же идентификатор программы.

Поскольку ранее мы настроили наш кластер как localhost, в настоящее время у нас нет сети для развертывания. Это означает, что если вы попытаетесь запустить anchor deploy прямо сейчас, вы получите сообщение об ошибке: ошибка при отправке запроса на URL-адрес (http://localhost:8899/).

Чтобы это исправить, нам нужно запустить локальный реестр.

Запуск локального валидатора

Локальный реестр — это, по сути, имитация кластера Solana внутри вашей локальной машины. При локальной сборке мы на самом деле не хотим ничего отправлять в блокчейн Solana, так что это именно то, что нам нужно.

К счастью для нас, запустить локальный реестр так же просто, как выполнить следующую команду.

solana-test-validator

Эта команда будет держать сеанс открытым в вашем терминале, пока вы не выйдете из него, запустив Ctrl + C. Пока сессия открыта, теперь у вас есть локальная книга для развертывания! 🎉

Это означает, что теперь вы можете запустить anchor deploy, и он успешно развернется в вашем локальном реестре.

anchor deploy

Обратите внимание, что все данные, отправленные в ваш локальный реестр, хранятся в папке «test-ledger», созданной в текущем каталоге.

Итак, давайте удостоверимся, что мы не передаем всю эту папку в наш репозиторий git, обновляя наш файл .gitignore вот так.

  .anchor
  .DS_Store
  target
  **/*.rs.bk
  node_modules
+ test-ledger

Также обратите внимание, что выход из вашей локального валидатора (путем запуска Ctrl+C) не уничтожит данные, которые вы отправили в кластер. Однако удаление этой папки test-ledger приведет к этому. Вы можете добиться того же результата, добавив флаг --reset.

# Runs a new empty local ledger.
solana-test-validator --reset

Обновление идентификатора программы

Теперь, когда мы запустили anchor build и anchor deploy в первый раз, нам нужно обновить идентификатор нашей программы.

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

Идентификатор вашей программы должен отображаться при запуске anchor deploy, но вы также можете получить к нему доступ, используя следующую команду Solana.

solana address -k target/deploy/solana_twitter-keypair.json
# Outputs something like: 2EKFZUwMrNdo8YLRHn3CyZa98zp6WH7Zpg16qYGU7htD

В зависимости от того, как вы назвали свой якорный проект, этот файл может называться по-другому, поэтому вам, возможно, придется заглянуть в папку target/deploy, чтобы найти нужный файл.

Хорошо, теперь, когда мы знаем идентификатор нашей программы, давайте обновим его.

Когда мы создали наш новый проект с помощью anchor init, Anchor использовал случайный заполнитель в двух местах в качестве идентификатора нашей программы, который мы теперь можем заменить.

Во-первых, в нашем конфигурационном файле Anchor.toml.

[programs.localnet]
solana_twitter = "2EKFZUwMrNdo8YLRHn3CyZa98zp6WH7Zpg16qYGU7htD"

Затем в файле lib.rs нашей программы Solana. В моем случае это programs/solana-twitter/src/lib.rs.

use anchor_lang::prelude::*;
use anchor_lang::solana_program::system_program;

declare_id!("2EKFZUwMrNdo8YLRHn3CyZa98zp6WH7Zpg16qYGU7htD");

Наконец, нам нужно собрать и развернуть еще раз, чтобы убедиться, что наша программа скомпилирована с правильным идентификатором.

anchor build
anchor deploy

Скрипты Anchor

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

Если вы заглянете внутрь своего файла Anchor.toml, вы увидите раздел scripts, содержащий test скрипт.

[scripts]
test = "yarn ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

Это уже настроено для нас, так что он будет запускать все тесты внутри нашей папки tests с помощью Mocha.

Чтобы запустить этот сценарий, выполните следующую команду.

anchor run test

Если у вас запущен локальный валидатор — с помощью solana-test-validator — и вы правильно собрали и развернули свой проект — с помощью anchor build и anchor deploy, то вы должны увидеть, что тест пройден!

Обратите внимание, что вы можете добавить любой пользовательский скрипт в конфигурационный файл Anchor.toml и использовать для его выполнения команду anchor run. Вот быстрый пример.

[scripts]
test = "..."
my-custom-script = "echo 'Hello world!'"

anchor run my-custom-script
# Outputs: Hello world!

Anchor test

Хорошо, теперь мы знаем полный цикл разработки. Во-первых, вам нужен локальный реестр, затем вы можете создавать, развертывать и тестировать. Вот краткий обзор:

# Start the local ledger.
solana-test-validator

# Then, on a separate terminal session.
anchor build
anchor deploy
anchor run test

Что ж, оказывается, у anchor есть специальная команда, которая заботится об этом полном цикле для нас. Это называется:

anchor test

⛔️ Не путать с anchor run test, который только запускает тестовый скрипт внутри вашего файла Anchor.toml.

Так что же на самом деле делает anchor test?

Во-первых, он запускает локальный реестр, который будет автоматически закрыт в конце команды. Это означает, что вы не можете запустить anchor test, если у вас уже запущен локальный валидатор. Перед запуском anchor testобязательно завершите любой локальный реестр, это обычная ошибка. Также обратите внимание, что он использует флаг --reset, чтобы убедиться, что наши тесты всегда начинаются с одних и тех же пустых данных.
```
solana-test-validator --reset
```
Теперь Anchor готов к сборке, развертыванию и запуску тестов.
```
anchor build
anchor deploy
anchor run test
```

Команда anchor test очень полезна при локальной разработке программ для Соланы. Он абстрагируется от всего лишнего и позволяет вам сосредоточиться на своей программе.

Однако помните, что запуск anchor test сразу после создания нового проекта – через anchor init – не будет работать, потому что вам сначала нужно будет обновить идентификатор вашей программы после первого развертывания.

Поэтому я предлагаю вам собрать и развернуть вручную в самый первый раз, и как только вы обновите свой идентификатор программы, вы можете начать использовать anchor test.

Anchor localnet

Если вы в конечном итоге будете работать над другими проектами Anchor, вы можете встретить команду anchor localnet. Эта команда очень похожа на anchor test, за исключением того, что она не запускает никакой проверки и не завершает локальный реестр в конце.

Таким образом, это в основном эквивалентно:

solana-test-validator --reset
anchor build
anchor deploy

# The local ledger will stay active after deployment.

Эта команда обычно используется для быстрого запуска вашей программы при работе с внешним клиентом.

Вывод

Фух, наконец-то мы добрались! Поздравляем с настройкой вашей локальной машины с помощью Solana и Anchor. Кроме того, теперь у нас есть полностью созданный проект, который мы можем использовать для создания нашего проекта Twitter в Солане.

Я надеюсь, что вы не столкнулись со слишком многими проблемами на этом пути. Я знаю, что настройка вещей на вашем компьютере может быть настоящим кошмаром, особенно когда технологии развиваются быстро. Если у вас есть какие-либо проблемы, не стесняйтесь добавлять комментарии к этой статье или, что еще лучше, создайте проблему в репозитории GitHub ниже, чтобы любой мог присоединиться и помочь вам во всех эпизодах.

Если вы хотите увидеть код, который мы сгенерировали во время этого эпизода, вот ссылка на ветку episode-2 репозитория этой серии.

Просмотреть эпизод 2 на GitHub

Теперь, когда мы все настроили и понимаем наш цикл разработки, давайте начнем создавать вещи!