Первые шаги Гуманитария в Создании собственного Сабграфа
Автор: Leopold #8689
Первым делом при изучении нового вам нужно найти хорошее руководство, которое поможет вам ускорить ваш путь.
На мой взгляд хорошим стартом будет использование этих 3 ресурсов:
Однако если Вы не очень сильны в английском или предпочитаете воспринимать информацию пошагово через текст и картинки, то, возможно, Вам может пригодится моя статья.
Прочитав введение(https://thegraph.com/docs/introduction), Вы получите общее представление о том, что такое Graph и как он работает.
В следующем разделе (https://thegraph.com/docs/quick-start) Вам предоставлятся выбор как именно создавать Сабграф: через самостоятельное создание локальной среды (больше подходит для массивных сабграфов и профессиональных программистов) или же воспользовавшись Хостинговом сервисом от команды The Graph, находящейся в облачном хранилище (этот путь гораздо легче для новичка и David Kajpust в данном видео рекомендует воспользоваться именно им)
В настоящей статье мы разберем именно второй способ.
Для того, чтобы воспользоваться хостингом от команды The Graph Вам необходимо пройти авторизацию на их сайте (авторизация возможна через ваш Github аккаунт, поэтому если у Вас его нет сначала создайте его)
После авторизации у Вас появится возможность добавления новых Сабграфов
При нажатии на выделенную кнопку Вы получите окно добавления Сабграфа с перечнем параметров
После заполнения требуемых полей и нажатия кнопки Создание Сабграфа Вы сможете перейти на страницу вашего созданного, но не развернутого Сабграфа
Под боксами под номерами 1,2,3 скрыты команды, которые нужно будет выполнить в терминале на вашем компьютере, чтобы
1. Установить Graph CLI
2. Создать Сабграф
3. Развернуть Сабграф на узле The Graph
Терминалы для дальнейшей работы могут быть использованы разные.
Представители команды The Graph на MacOS используют iTerm2: https://iterm2.com/
Для обладателей Windows, в принципе, может быть достаточной базовая версии Windows PowerShell (ну или можете выбрать что-нибудь из предлагаемых аналогов iTerm: https://alternativeto.net/software/iterm2/?platform=windows)
Под боксом 1 Вы найдете сообщение, предлагающее установить Graph CLI с помощью npm или yarn прямо с окна вашего терминала:
$ npm install -g @graphprotocol/graph-cli$ yarn global add @graphprotocol/graph-cli
Но предварительно Вам, возможно, будет необходимо установить сам Yarn для дальнейшей работы с ним.
Если Вы используете Mac OS, то можете воспользоваться следующей ссылкой: https://gist.github.com/rcugut/46904124d198a9dbd430abe88ebf849b
Если Вы пользователь Windows, то можете посмотреть тут: https://classic.yarnpkg.com/en/docs/install/#windows-stable
ВАЖНОЕ ПРИМЕЧАНИЕ ДЛЯ ПОЛЬЗОВАТЕЛЕЙ WINDOWS:
Я получил много вопросов от пользователей Windows, т.к. у них терминал выдавал различного рода ошибки. Я рекомендую, прежде чем выполнять дальнейшие команды, попробовать осуществить ВСЕ шаги из данной инструкции. Важные замечания по следованию данной инструкции: не забывайте запускать установочники от имени Администратора, не забудьте поставить галку об установке дополнительных атрибутов к Node.js
Журнал командной строки выполнения этой команды в терминале представлен ниже:
После успешной установки Graph CLI мы переходим к созданию непосредственно Сабграфа. Эту операцию опять же можно выполнить 2 способами: 1) из существующего контракта Ethereum 2) из существующего примера от команды The Graph
В данной статье мы рассмотрим 2-ой способ. Это простой способ создания подграфа Gravatar, но он будет полезен и для создания Вашего собственного Сабграфа за счет получения шаблонного кода, который впоследствии будете просто редактировать
Прим.: Мы рассмотрели 1-ый способ в отдельной статье. Однако я настоятельно рекомендую сначала ознакомиться и постараться пройти все шаги данной статьи, прежде, чем приступать к чтению второй
Нажав на бокс 2 на странице вашего созданного, но не развернутого Сабграфа, Вы увидите следующее окно
Вам нужно скопировать команду
$ graph init --from-example <GITHUB_USERNAME>/<SUBGRAPH_NAME> <DIRECTORY>
и вставить его в окно Вашего терминала с заменой следующих переменных:
<GITHUB_USERNAME> меняете на Ваше имя пользователя
<SUBGRAPH_NAME> меняете на заданное Вами имя Сабграфа
<DIRECTORY>не является обязательным для заполнения. Вообще это имя каталога, в котором создается ваш подграф. По умолчанию, нужно опять же прописать Имя вашего Сабграфа.
Реализация вышеназванной функции в терминале будет выглядеть следующим образом (терминал запросит от Вас повторно подтвердить имя вашего Сабграфа и папку, в которую Вы хотите его установить :
После успешного создания Сабграфа Вам нужно развернуть его на хостинге The Graph. Это можно сделать с помощью команд, которые скрыты в боксе 3 на странице вашего созданного, но не развернутого Сабграфа
Для реализации первой команды
graph auth https://api.thegraph.com/deploy/ <ACCESS_TOKEN>Вам нужно заменить <access-token> на токен доступа вашего Сабграфа, который отражен на той же вышеназванной странице
При реализации вышеназванной функции в терминале Вы получите следующее окно:
Реализованная команда создала папку называющуюся идентично Вашему Сабграфу. Для того, чтобы зайти в папку реализуйте команду “cd <название папки>” и следом используйте команду: “ls”. В результате Вы увидите содержимое вашей папки:
Внутри папки Вы можете видеть разные файлы (License, abis, readme, etc), но для лучшего восприятия кода можно открыть данную папку в Visual Studio. Для этого нужно реализовать команду: “code .”, которая запустит вышеназванную программу с уже открытой в ней папкой Вашего Сабграфа (прим. у Вас должна быть предварительно установлена Visual Studio. Если Вы не установили эту программу при установки Node.js, то можете скачать ее с официального сайта)
Следующим шагом станет реализация команды “yarn codegen” либо “npm run codegen”, которая в АВТОМАТИЧЕСКОМ режиме создаст необходимые для нашего Сабграфа файлы
Что делает данная команда и почему она весьма полезна? Она берет данные из abis смартконтракта в сети Ethereum, выглядящие следующим образом:
и создает куда более читабельный код, устанавливает Setters и Getters (я не придумал русского аналога этим понятиям), создает файлы и вносит изменения в Mappings, Schema и Subgraph.yaml (Манифест), облегчающие работу с Сабграфом
Заключающим шагом развертывания нашего Сабграфа на Хостинге The Graph будет непосредственно операция deploy:
graph deploy \
--debug \
--node https://api.thegraph.com/deploy/ \
--ipfs https://api.thegraph.com/ipfs/ \
<SUBGRAPH_NAME>Не забываем заменить <SUBGRAPH_NAME> на имя нашего Сабграфа
Примечание: В дискорде 1 из кураторов предложил предыдущую команду запускать вместе с токеном доступа и это решило проблему других пользователей
graph deploy — access-token <Ваш Access token>\
— debug \
— node https://api.thegraph.com/deploy/ \
— ipfs https://api.thegraph.com/ipfs/ \
<github/subgraph_name>Так как у многих возникает 1 и та же ошибка при реализации вышеназванных команд, то советую писать предыдузий код в 1 строку. Значок “\” нужно убрать (он просто как раз означал непрерывность кода). Итого Ваш код будет выглядеть так
Как мы видим после завершения реализации команды мы получили ссылку на страницу созданного нами Сабграфа, который развернут на Хостинг сервисе The Graph и в данный момент вероятно индексируется им. Перейдя по ссылке мы увидим уже знакомую нам страницу:
Итак, по завершении синхронизации мы получим PlayGround GraphQL на нашей панели инструментов в Graph Explorer, готовый выполнять запросы с использованием нового только что созданного нами Сабграфа
Дальнейшие шаги
Стоит понимать, что пока мы только научились создавать и размещать простой шаблонный Сабграф. Чтобы в итоге получить Сабграф, выполняющий интересующие конкретно нас функции, мы должны будет видоизменять код данного Сабграфа, продумывать что именно мы хотим получить в SchemaQL нашего Сабграфа и вносить изменения в Mappings, Manifest и т.д. Важным подспорьем здесь станет уже изученная и успешно примененная нами функция “yarn codegen”.
Также вместо исправления созданного тестового Сабграфа Вы можете оставить его как есть и с имеющимся у Вас опытом создать новый Сабграф напрямую с контракта Ethereum. Про создание Сабграфа напрямую с контракта Ethereum можно почитать здесь. Если Вы все же желаете видоизменить уже созданный Сабграф, а не создавать новый, то можете продолжить чтение данной статьи.
Условно представим, что мы хотим использовать данные с Юнисвопа по торгуемым там парам. Мы можем пойти на их страницу на Гитхабе, скачать оттуда их ABI файл или просто скопировать весь код с этой страницы
Затем заменить abi файл Gravity.json на скачанный abi файл (или просто удалить весь код и вставить скопированный код с Гитхаба) в Visual Studia нашего Сабграфа
После этого нам нужно изменить Data sources в нашем сабграфе на новое название ABI
После этого мы запускаем команду “yarn codegen”, которая в автоматическом режиме с учетом новых входных данных перепишет Mappings, Manifest и прочие файлы нашего сабграфа.
После этого я советую запустить команду “yarn build”, которая проверит готов ли Ваш измененный сабграф к реазвертыванию на ноде The Graph и если терминал не выдаст вам никаких ошибок, то можете приступать к обновлению уже развернутого Сабграфа повторным запуском команды Deploy
graph deploy — access-token <Ваш Access token>\
— debug \
— node https://api.thegraph.com/deploy/ \
— ipfs https://api.thegraph.com/ipfs/ \
<github/subgraph_name>Ложкой дегтя выступит тот факт, что хоть “yarn codegen” и полезная функция, но это не волшебная палочка и она не сделает абсолютно всю работу за Вас. Чтобы создать из текущего шаблона по настоящему хороший и нужный пользователям Сабграф Вам придется потратить некоторое время на изучение GraphQL, интересующего Вас контракта Ethereum и более глубокое ознакомление с документацией Графа (https://thegraph.com/docs). Но если Вы успешно справились с созданием и развертыванием этого тестового Сабграфа, то и вышеназванные ”задачи со звездочкой” Вам более чем по зубам — поэтому дерзайте!
С Уважением, Leopold #8689
