Короткий посібник по створенню сабграфів
Цей текст є перекладом з англійської короткого посібника від Graph.
У цій статті ви знайдете інформацію щодо того, як створювати сабграфи для контрактів, які ви розгортали на локальному тестнеті (наприклад, за допомогою Ganache), на мейннеті або ж на одному з тестнетів Ethereum (Ropsten, Rinkeby або Kovan).
Розгортання на локальному тестнеті
У цьому посібнику розглядається розгортання на локальному тестнеті за допомогою Truffle і Ganache. Вам необхідно виконати приведені далі кроки.
1. Налаштування Ganache CLI.
2. Запуск локальної ноди Graph.
3. Ініціалізація нового сабграфа.
4. Розгортання зразкового смарт-контракту на Ganache.
5. Розгорнання сабграфа на локальну ноду Graph.
6. Використання сабграфа в децентралізованому застосунку, написаному на React.
1. Налаштування Ganache CLI.
Щоб глобально встановити Truffle і Ganache, запустіть одну із двох приведених далі команд із термінала:
Коли Ganache буде встановлено, ви зможете запустити
у тому ж терміналі. Буде створено 10 тестових акаунтів, на яких буде певна кількість Ефіру. Зверніть увагу: увести -h 0.0.0.0 необхідно, щоб можна було отримати доступ до Ganache із Docker та інших комп’ютерів. За замовчуванням, Ganache прив’язується тільки до 127.0.0.1, до якого можна отримати доступ лише з хоста, на якому запущено Ganache.
ПРИМІТКА. Використання Ganache для тестування сабграфа може призвести до неочікуваних наслідків. Під час запуску тестів Ganache робитиме знімки стану блокчейна й повертатиме його до початкового стану — до чистого розгортання контрактів. Якщо ваше тестування у Truffle налаштоване таким чином, нода Graph зависне, оскільки в її роботі не передбачено повернення блокчейну до початкового стану. Крім того, якщо нові екземпляри контрактів будуть продовжувати розгоратися під час тестування, адреси контрактів не будуть збігатися з адресами контрактів із Deployer. Таким чином, у вас не буде єдиної адреси, яку потрібно додати до маніфесту subgraph.yaml. Користувачам рекомендується повністю розуміти, як Ganache запускає тести, інакше може виявитися, що нода Graph не запускає обробники (handlers).
2. Запуск локальної ноди Graph.
На іншому терміналі виконайте приведені далі дії.
- Клонуйте ноду Graph за допомогою
2. Укажіть каталог Docker ноди Graph:
3. Лише для користувачів Linux. Для налаштування Docker Compose ноди Graph використовується псевдонім для хоста host.docker.internal. На Linux він іще не підтримується. Щоб замінити його IP-адресою хоста, із каталогу Docker запустіть таку команду:
Сценарій запише IP-адресу хоста в docker-compose.yml.
4. Запустіть локальну ноду Graph, яка підключиться до Ganache на хості:
3. Ініціалізація нового сабграфа.
- Установіть Graph CLI глобально за допомогою npm або yarn:
2. Переконайтеся в тому, що ви знаходитеся в папці, у якій потрібно створити сабграф на комп’ютері, і запустіть:
- <GITHUB_USERNAME> — обов’язкове для заповнення поле. Це ваше ім’я користувача на GitHub.
- <SUBGRAPH_NAME> — обов’язкове для заповнення поле. Це назва проекту вашого сабграфа.
- <DIRECTORY> — необов’язкове для заповнення поле. Це назва каталогу, у якому ви створюєте сабграф. Значення за замовчуванням: <SUBGRAPH_NAME>.
У результаті буде створено зразковий сабграф, який можна використовувати як початкову точку для створення власного сабграфа. Додаткову інформацію щодо того, як писати сабграф, можна знайти в розділі з документами Визначення сабграфа.
4. Розгортання зразкового смарт-контракту на Ganache.
Після запуску graph init у кроці 3 можна розгортати зразковий смарт-контракт, який буде індексуватися сабграфом у Ganache.
Для цього просто запустіть
у кореневому каталозі сабграфа із кроку 3. У результаті буде скомпільовано смарт-контракт GravatarRegistry, що розгорнеться в Ganache. Крім того, буде виконано пара транзакцій по контракту, щоб створити дані для індексування.
Примітка. truffle migrate відобразить адресу, на яку розгортається контракт GravatarRegistry. Обов’язково скопіюйте цей контракт, ці дані знадобляться вам пізніше.
5. Розгортання сабграфа на локальну ноду Graph.
- У кореневому каталозі сабграфа додайте адресу контракту з попереднього кроку в сабграф:
2. Установіть залежності сабграфа й запустіть створення коду Graph CLI:
3. Після цього призначте назву сабграфа в ноді Graph за допомогою
4. Урешті, запустіть
щоб розгорнути сабграф на локальну ноду Graph.
Якщо необхідно спостерігати обробку журналів, перевірте вихідні дані терміналу ноди Graph. Зробіть те ж саме для діагностики й виправлення помилок.
6. Використання сабграфа в децентралізованому застосунку, написаному на React.
Для цього відкрийте ще один термінал. Тепер клонуйте зразковий децентралізований застосунок, сумісний із цим сабграфом, за допомогою
Після цього вкажіть каталог застосунку й налаштуйте його конфігурацію для використання кінцевої точки GraphQL зразкового сабграфа:
$ cd ethdenver-dapp
$ echo ‘REACT_APP_GRAPHQL_ENDPOINT=http://localhost:8000/subgraphs/name/<GITHUB_USERNAME>/<SUBGRAPH_NAME>' > .env
Нарешті, установіть залежності децентралізованого застосунку й запустіть його:
Розміщена служба
У цьому розділі приведена інформація щодо розгортання сабграфа на розміщеній службі. Якщо у вас немає акаунта на Graph Explorer, можна зареєструватися через GitHub. Після створення акаунта можна почати створювати сабграфи за допомогою інтерфейсу користувача та розгортати їх із термінала. Крім мейннету, нода Graph підтримує багато тестнетів Ethereum (Rinkeby, Ropsten, Kovan).
По-перше, перейдіть на сторінку Dashboard (Приладна дошка) і натисніть Add Subgraph (Додати сабграф). Виберіть зображення (необов’язково) і визначте назву для сабграфа. Коли завершите, натисніть Save (Зберегти). Новий, нерозгорнутий сабграф відобразиться на приладній дошці.
Щоб розробити і розгорнути цей сабграф, виконайте приведені далі дії.
- Установіть Graph CLI глобально на комп’ютер,використавши Yarn або NPM:
2. Ми приготували зразковий сабграф, який можна використовувати як початкову точку. Налаштуйте його, запустивши:
- <GITHUB_USERNAME> — обов’язкове для заповнення поле. Це ваше ім’я користувача на GitHub.
- <SUBGRAPH_NAME> — обов’язкове для заповнення поле. Це назва проекту вашого сабграфа.
- <DIRECTORY> — необов’язкове для заповнення поле. Це назва каталогу, у якому ви створюєте сабграф. Значення за замовчуванням: <SUBGRAPH_NAME>.
3. У результаті виконання попередньої команди відобразяться інструкції щодо того, як автентифікуватися в розміщеній службі та як підготувати й розгорнути сабграф. Просто слідуйте ним.
ПРИМІТКА. У разі створення сабграфа від імені організації, необхідно бути в ролі адміністратора, щоб отримати маркер доступу. Якщо ви просто учасник, зверніться до адміністратора.
Тепер можна спостерігати індексування сабграфа та взаємодіяти з ним через інтерактивне середовище GraphQL в Graph Explorer за адресою
https://thegraph.com/exporer/subgraph/<GITHUB_USERNAME>/<SUBGRAPH_NAME>/
Використання сабграфа в децентралізованому застосунку, написаному на React.
Для цього відкрийте термінал. Тепер клонуйте зразковий децентралізований застосунок, сумісний із цим сабграфом, за допомогою
Після цього вкажіть каталог застосунку й налаштуйте його конфігурацію для використання кінцевої точки GraphQL зразкового сабграфа:
$ cd ethdenver-dapp
$ echo ‘REACT_APP_GRAPHQL_ENDPOINT=https://api.thegraph.com/subgraphs/name/<GITHUB_USERNAME>/<SUBGRAPH_NAME>' > .env
Нарешті, установіть залежності децентралізованого застосунку й запустіть його:
Запитання й відповіді
1. Чи можна видалити сабграф?
Після створення видалити сабграфи неможливо.
2. Чи можна змінити назву сабграфа?
Ні. Після створення сабграфа змінити його назву неможливо. Ретельно продумайте її перед створенням сабграфа. Назва повинна бути легкою для пошуку й ідентифікації серед інших децентралізованих застосунків.
3. Чи можна змінити акаунт GitHub, прив’язаний до мого сабграфа?
Ні. Після створення сабграфа змінити прив’язаний акаунт GitHub неможливо. Ретельно продумайте, який акаунт будете прив’язувати, перед створенням сабграфа.
4. Чи можна створити сабграф, якщо в моїх смарт-контрактах немає подій (events)?
Настійно рекомендується структурувати смарт-контракти так, щоб у них були події, пов’язані з даними, які будете запитувати. Обробники подій у сабграфі запускаються подіями контракту й, безсумнівно, найшвидше з усіх інших способів отримують корисні дані.
Якщо в контрактах, з якими ви працюєте, не містяться події, для запуску індексації сабграф може використовувати обробники викликів і блоків (call and block handlers). Проте, не рекомендується їх застосовувати через значне зниження продуктивності.
5. Чи можливо розгорнути один сабграф з однією й тією ж назвою для багатьох мереж?
Для використання з кожною мережею буде необхідна окрема назва. Хоча не можна використовувати різні сабграфи під однією назвою, є зручні способи вести єдину базу кодів від багатьох мереж. Додаткову інформацію див. у документації: Повторне розгортання сабграфа
6. Чим шаблони відрізняються від джерел даних?
За допомогою шаблонів можна створювати джерела даних на ходу під час індексування сабграфа. Може статися так, що контракт буде породжувати нові контракти протягом всього часу взаємодії з ним. Заздалегідь знаючи їх форму (ABI, події тощо), можна визначати спосіб індексування в шаблоні. Коли вони будуть множитися, сабграф створюватиме джерело динамічних даних, поставляючи адресу контракту.
Див. розділ «Створення шаблону джерела даних» тут: Шаблони джерела даних.
7. Як переконатися в тому, що для локальних розгортань використовується остання версія ноди Graph?
Запустіть таку команду:
Примітка. docker / docker-compose завжди буде використовувати версію ноди Graph, витягнутої при першому запуску, тому так важливо переконатися в тому, що ви користуєтеся найновішою версією ноди Graph.
8. Як викликати функцію контракту або отримати доступ до публічної перемінної стану із зіставлень (mappings) сабграфа?
Див. Доступ до інформації про стан смарт-контракту у розділі API AssemblyScript .
9. Чи можливо налаштувати сабграф за допомогою graph init із graph-cli з двома контрактами? Або ж варто вручну додати інше джерело даних у subgraph.yaml після запуску graph init?
На жаль, зараз це неможливо. graph init задумано як базова початкова точка, з якої пізніше можна додати більше джерел даних уручну.
10. Я хочу зробити внесок або повідомити про проблему на GitHub, де можна знайти сховища проектів із відкритим кодом?
11. Яким чином рекомендується писати «автоматично створені» ID для сутності при обробці подій?
Якщо створюється тільки одна сутність (entity) під час події та немає кращих можливостей, тоді індекс транзакції hash + log буде унікальним. Можна зробити їх більш заплутаними, конвертувавши у байти та пропустивши через crypto.keccak256, але це не підвищить їх унікальність.
12. Чи можливо під час прослуховування декількох контрактів вибрати порядок контрактів для прослуховування подій?
У сабграфі події завжди обробляються в порядку їх появи у блоках, незалежно від того, у рамках одного контракту чи багатьох.
13. Чи можливо розрізняти мережі (мейннет, Kovan, Ropsten, локальна) з обробників подій?
Так. Для цього імпортуйте graph-ts згідно із прикладом далі:
14. Чи підтримуються обробники викликів і блоків на Rinkeby?
На Rinkeby підтримуються обробники блоків, але без filter: call. Обробники викликів зараз не підтримуються.
15. Чи можна імпортувати ethers.js або інші бібліотеки JS у зіставлення (mappings) мого сабграфа?
Зараз ні, адже зіставлення написані на AssemblyScript. Одне з можливих альтернативних рішень — зберігати необроблені дані в сутностях і виконувати логіку, для якої необхідні бібліотеки JS, на клієнті.
16. Чи можливо вказати, з якого блоку починати індексування?
Так. dataSources.source.startBlock у файлі subgraph.yaml указує на номер блока, з якого джерело даних починає індексування. Найчастіше ми радимо використовувати блок, на якому було створено контракт. Детальніше тут: Початкові блоки
17. Є поради щодо підвищення продуктивності індексування? Мій сабграф дуже довго синхронізується.
Так. Ознайомтеся з додатковою функцією початкових блоків, щоб запустити індексування із блока, з якого було розгорнуто контракт: Початкові блоки
18. Чи є спосіб безпосередньо зробити запит сабграфа, щоб визначити, який останній номер блока він індексував?
Так! Спробуйте приведену далі команду, замінюючи organization/subgraphName на назву організації, від імені якої його опубліковано, і назву сабграфа:
curl -X POST -d ‘{ “query”: “{indexingStatusForCurrentVersion(subgraphName: \”organization/subgraphName\”) { chains { latestBlock { hash number }}}}”}’ https://api.thegraph.com/index-node/graphql
Якщо версія сабграфа досі знаходиться на розгляді, просто замініть indexingStatusForCurrentVersion на indexingStatusForPendingVersion.
19. Які мережі підтримує Graph?
Нода Graph підтримує будь-який ланцюг API JSON RPC, сумісний з Ethereum. У розміщеній службі підтримуються такі мережі:
- мейннет Ethereum;
- Kovan;
- Rinkeby;
- Ropsten;
- Goerli;
- PoA-Core;
- xDAI;
- Sokol.
Ми працюємо над тим, щоб інтегрувати інші блокчейни. Докладнішу інформацію див. у нашому сховищі: RFC-0003: підтримка багатьох блокчейнів.
20. Чи можливо дублювати сабграф на інший акаунт або кінцеву точку без повторного розгортання?
Знадобиться повторно розгорнути сабграф, але, якщо ID сабграфа (хеш IPFS) не зміниться, йому не потрібно буде синхронізуватися з самого початку.
21. Чи можливо використовувати Apollo Federation поверх ноди Graph?
Federation поки що не підтримується, але це планується у майбутньому. Зараз можна скористатися зшиванням схеми як на клієнті, так і через службу проксі.
22. Чи є обмеження кількості об’єктів, які Graph може повернути на запит?
За замовчуванням кількість запитів обмежено до 100 об’єктів на колекцію. Якщо необхідно отримувати більше, можна збільшити цю кількість до 1000 об’єктів на колекцію, а також розбивати їх на сторінки, скориставшись такою командою:
